Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ExtAwareParser ¶ added in v0.5.0
type ExtAwareParser interface {
ParseExt(source, ext string) (FileStructure, error)
}
ExtAwareParser is an optional extension implemented by parsers that need the file extension to do their job — currently the JS/TS parser, which selects a tree-sitter grammar by .js/.ts/.tsx. The generator passes the extension via ParseExt when a parser implements this; parsers that don't are called via the plain Parse method. Keeping it optional avoids churning the Go and Python parsers (whose extension is unambiguous) and all their callers.
type FileStructure ¶
type FileStructure struct {
Imports []string // Import paths (sorted)
Functions []string // Function names, incl. methods/nested as Outer.name (sorted)
Classes []string // Class names, nested qualified as Outer.Inner (sorted)
Exports []string // Exported symbol names (sorted)
// SymbolHashes maps "kind:name" (e.g. "function:Reader.fetch") to a hash of
// that symbol's source body, for parsers that extract per-symbol spans (the
// AST-backed Python parser). It enables modified-symbol diffing: a symbol
// present in both snapshots whose body hash changed is reported "modified"
// rather than invisible. Nil for regex parsers that cannot isolate a body —
// the diff then degrades to add/remove only for their symbols.
SymbolHashes map[string]string
// SymbolLines maps "kind:name" to the symbol's 1-based start line, for
// parsers that know it (the AST-backed Python parser). Powers `runecho-ir
// map` (symbol → file:line). Nil for parsers without span info; consumers
// render an unknown line as "?".
SymbolLines map[string]int
}
FileStructure represents the parsed structure of a source file.
type GoParser ¶
type GoParser struct{}
GoParser implements structural parsing for .go files using the standard library's go/parser + go/ast. This is a real AST (CGO-free, no build tags), so unlike the former regex pass it emits per-symbol start lines and function body hashes — matching the Python parser's FileStructure contract.
Symbol routing (preserved from the regex era):
- Exported funcs and methods → Functions. Methods are qualified by receiver type ("Reader.Fetch"), matching the Python parser's scope-qualified names, so identical method names on different types never collide.
- Exported types → Classes (struct, interface, alias, etc.); located but not hashed (parity with Python classes — changes surface through members).
- Exported interface method signatures → Functions, qualified by the interface type ("Reader.Read"); located and hashed over the signature span so a contract change flips the hash (parity with the JS/TS parser, which records method_signature the same way). Embedded interfaces and type-set constraints carry no method name and are skipped.
- Exported top-level var/const → Exports; located, not hashed (no body).
Only exported (capitalized) names are extracted, as before.
func (*GoParser) Parse ¶
func (p *GoParser) Parse(source string) (FileStructure, error)
Parse extracts top-level exported structure from Go source via go/ast. Best-effort on parse errors: go/parser recovers to a partial *ast.File for most single-error (mid-edit) buffers, and we walk whatever declarations it produced — honoring the Parser interface's partial-structure contract without a separate degraded path.
func (*GoParser) SupportsExtension ¶
SupportsExtension returns true for .go files.
type JSParser ¶
type JSParser struct{}
JSParser parses .js, .ts, .jsx, .tsx, .gs files. Imports and exports are extracted with deterministic regex (line-oriented constructs). Functions and classes use a real tree-sitter AST via a pure-Go (CGO-free) runtime when the matching grammar is embedded in the build, so they carry per-symbol start lines and function body hashes (matching the Python parser's FileStructure contract). When the grammar is absent (a build without the grammar_subset_* tags), it degrades to the former regex extraction — names only, no spans — so symbol coverage never regresses.
Altitude: like the Go parser, it captures top-level functions/classes plus class methods (qualified as Class.method); it does not descend into function bodies, so nested closures/callbacks are intentionally omitted.
Best-effort: the shipped grammars are reduced "subset" grammars covering the common surface (declarations, classes/interfaces/enums, methods, arrow and function consts). Some advanced TypeScript syntax — notably a return-typed arrow const, `const f = (x: T): R => ...` — does not parse cleanly and yields fewer symbols. This matches the prior regex parser's gap (no regression); it is documented rather than silently dropped.
func NewJSParser ¶
func NewJSParser() *JSParser
NewJSParser creates a new JavaScript/TypeScript parser.
func (*JSParser) Parse ¶
func (p *JSParser) Parse(source string) (FileStructure, error)
Parse satisfies the Parser interface. Without the file extension it cannot pick the most specific grammar, so it assumes JavaScript (the JS grammar also parses JSX). The generator calls ParseExt instead (via the ExtAwareParser interface), which selects typescript/tsx for .ts/.tsx.
func (*JSParser) ParseExt ¶ added in v0.5.0
func (p *JSParser) ParseExt(source, ext string) (FileStructure, error)
ParseExt is the extension-aware entry point (see ExtAwareParser). ext selects the tree-sitter grammar: .ts → typescript, .tsx → tsx, everything else → js.
func (*JSParser) SupportsExtension ¶
SupportsExtension returns true for .js, .ts, .jsx, .tsx, .gs files.
type Parser ¶
type Parser interface {
// Parse extracts top-level structure from source code.
// Returns partial structure on parse errors (best-effort).
Parse(source string) (FileStructure, error)
// SupportsExtension returns true if this parser handles the file extension.
SupportsExtension(ext string) bool
}
Parser extracts shallow structural information from source files.
type PythonParser ¶
type PythonParser struct{}
PythonParser parses .py files. Imports and __all__ exports are extracted with deterministic regex (cheap and sufficient — line-oriented constructs). Functions and classes use a real tree-sitter AST via a pure-Go (CGO-free) runtime, so `async def`, methods, nested defs, and private/dunder helpers are all captured as first-class symbols. The previous regex pass matched only plain top-level `def` and dropped everything else into the refs bucket.
func NewPythonParser ¶
func NewPythonParser() *PythonParser
func (*PythonParser) Parse ¶
func (p *PythonParser) Parse(source string) (FileStructure, error)
func (*PythonParser) SupportsExtension ¶
func (p *PythonParser) SupportsExtension(ext string) bool
Source Files