godocgen

godocgen builds a local, searchable map of a source repository. Point it at a project and it opens a browser with modules, documents, symbols, source links, and a best-effort call graph.

The project started as a hand-written lexer and parser exercise. Go, Python, JavaScript, TypeScript, SQL, JSON, and YAML now use that architecture. The implementation uses the Go standard library and does not use regular expressions for source analysis.

Run it

You need Go 1.26 or later.

go install ./cmd/godocgen
godocgen /path/to/project

You can also run it without installing it:

go run ./cmd/godocgen /path/to/project

The command selects an available localhost port, starts the server, and opens your browser. Stop it with Ctrl+C.

Use these options for scripts or a fixed bookmark:

godocgen --no-open --port 8080 /path/to/project

What it indexes

Language	Extensions	Symbols
Go	.go	packages, imports, types, structs, interfaces, functions, methods, variables, constants
Python	.py	modules, imports, classes, methods, functions, type aliases, fields, variables, constants
JavaScript	.js, .jsx, .mjs, .cjs	modules, imports, classes, methods, fields, functions, function expressions, arrow functions, variables, constants
TypeScript	.ts, .tsx	JavaScript symbols plus interfaces, properties, types, enums, and namespaces
SQL	.sql	tables, views, schemas, functions, procedures, and named or numbered queries
Markdown	.md, .mdx	ATX headings and their prose
JSON	.json	object keys and value types; JSONC comments and trailing commas are accepted
YAML	.yaml, .yml	sections and mapping keys

Go files are grouped by package. Other languages keep their natural file-level module or document unit. The walker skips dependencies, caches, build output, virtual environments, and Go testdata fixtures.

What the browser shows

• A project dashboard with file and symbol counts by language.
• Searchable module and document navigation.
• Symbols grouped by kind, with signatures and attached documentation.
• Links from each symbol to its source line.
• Full source pages with stable line anchors.
• Calls and Called by links for named functions, methods, and classes.

The call graph is a navigation aid, not a compiler result. It matches named calls inside indexed symbol bodies. Dynamic dispatch, aliases, callbacks, reflection, generated code, and overloaded names can produce missing or ambiguous links.

Design

The main analysis path is:

filesystem → walker → lexer → tokens → parser → shared symbols → renderer/server

Each parser consumes language tokens and returns plain symbol data. The pipeline groups those symbols, resolves token-derived call candidates, and passes the result to language-neutral HTML templates. An incomplete source file should reduce the detail in the index, not stop the whole project scan.

internal/lexer and internal/parser contain custom implementations. Go uses exact token kinds based on the Go lexical vocabulary. Python adds logical newlines and indentation tokens. JavaScript and TypeScript share an ECMAScript scanner with distinct keywords, punctuators, private identifiers, regular expression literals, templates, and numeric literals. SQL preserves quoted identifiers, dollar-quoted strings, parameters, comments, and statement boundaries. Its parser also records table and view reads and writes for a later data-flow view. JSON uses a recursive-descent value parser and accepts JSONC comments and trailing commas. YAML uses layout and scalar tokens to index block and flow mappings. Markdown stays a line parser because its structure is line-oriented.

Develop

go test ./...
go vet ./...
go build ./cmd/godocgen

See ROADMAP.md for the next product milestones. The original course review and early implementation notes remain in TODO.md as project history.