parser

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 26, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package parser defines the common data model and interface shared by all language-specific AST parsers (Python, TypeScript, Go). It corresponds to ast_digger/parsers/base.py in the Python implementation.

Package parser: fuzzy.go implements the "fuzzy match" logic shared by PythonParser, TypeScriptParser, and GolangParser's ExtractSymbol, used to populate apperr.SymbolNotFoundError.Suggestions with up-to-5 candidate symbol names when a requested symbol_path cannot be found (F-10, task 14).

It corresponds to Python's BaseParser.suggest_symbols (ast_digger/parsers/base.py), which delegates to the standard library's difflib.get_close_matches (cutoff=0.6, n=5). difflib.get_close_matches ranks candidates by difflib.SequenceMatcher.ratio(), which implements the Ratcliff/Obershelp algorithm: 2*M/T, where T is the combined length of the two strings and M is the total length of a recursively-found sequence of matching (non-overlapping, longest-first) contiguous blocks.

fuzzyRatio below reimplements that same ratio (not merely an "equivalent" similarity measure): findLongestMatch is a direct, from-scratch port of the core loop in CPython's difflib.SequenceMatcher.find_longest_match (the "j2len" dynamic-programming sweep), and sumMatchingBlockSizes mirrors difflib's recursive decomposition around the longest match to accumulate the same total M. difflib's "autojunk" heuristic (which only engages for sequences of 200+ elements, e.g. very long lines, and treats elements appearing in >1% of a long sequence as noise) is not implemented here, since the only inputs this file ever compares are short symbol names/paths (e.g. "MyClass.my_method"), for which autojunk categorically never activates in CPython either.

Package parser: golang.go implements the Parser interface for Go source files using the tree-sitter-go grammar. It corresponds to ast_digger/parsers/go.py in the Python implementation.

The concrete type is named GolangParser (rather than "GoParser") and this file is named golang.go (rather than "go.go") to avoid clashing, in name only, with Go's own standard-library go/parser package and the "go" build tool/keyword; there is no functional reason for the naming beyond reducing confusion when this package is imported alongside go/parser or similar.

Package parser: java.go implements the Parser interface for Java source files using the tree-sitter-java grammar. It follows the same structure and conventions as golang.go (GolangParser), adapted for Java's class- based symbol model.

Package parser: javascript.go implements the Parser interface for JavaScript source files using the tree-sitter-javascript grammar. It follows the same structure and conventions as typescript.go (TypeScriptParser), adapted for JavaScript's simpler (untyped) symbol model: there is no interface_declaration/type_alias_declaration/ method_signature (none of those node kinds exist in JavaScript's grammar).

Unlike TypeScript (which needs a dedicated TSX grammar to parse JSX syntax), a single tree-sitter-javascript grammar parses ".js"/".jsx" (and ".mjs"/".cjs") source uniformly, JSX elements included -- so JavaScriptParser needs only one *tree_sitter.Language, not two.

Package parser: python.go implements the Parser interface for Python source files using the tree-sitter-python grammar. It corresponds to ast_digger/parsers/python.py in the Python implementation.

Package parser: rust.go implements the Parser interface for Rust source files using the tree-sitter-rust grammar.

Package parser: typescript.go implements the Parser interface for TypeScript and TSX source files using the tree-sitter-typescript grammar. It corresponds to ast_digger/parsers/typescript.py in the Python implementation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type GolangParser 

type GolangParser struct {
	// contains filtered or unexported fields
}

GolangParser implements the Parser interface for Go (.go) source files.

It corresponds to the Python `GoParser` class defined in ast_digger/parsers/go.py.

func NewGolangParser 

func NewGolangParser() *GolangParser

NewGolangParser constructs a GolangParser with the tree-sitter-go grammar loaded.

func (*GolangParser) ExtractSymbol 

func (p *GolangParser) ExtractSymbol(filePath, symbolPath string) (SymbolData, error)

ExtractSymbol resolves symbolPath (e.g. "MyStruct.MyMethod") within filePath and returns the corresponding SymbolData, including its source code. It corresponds to Python's `GoParser.extract_symbol`.

func (*GolangParser) FindReferencesInFile 

func (p *GolangParser) FindReferencesInFile(filePath, symbolName string) ([]ReferenceData, error)

FindReferencesInFile searches filePath for occurrences where symbolName is referenced or invoked, excluding matches inside comments and string literals. It corresponds to Python's `GoParser.find_references_in_file`.

Unlike PythonParser.FindReferencesInFile/TypeScriptParser. FindReferencesInFile (which additionally exclude definition-site identifiers via an is_definition check), this method does not exclude definition sites: it mirrors Python's `GoParser.find_references_in_file` verbatim, which performs only the comment/string-literal exclusion below. Do not "fix" this asymmetry without also updating ast_digger/parsers/go.py.

func (*GolangParser) GenerateSkeleton 

func (p *GolangParser) GenerateSkeleton(filePath string) (string, error)

GenerateSkeleton reconstructs filePath's source with every function/method/func-literal body replaced by "{ /* ... */ }", leaving signatures and doc comments untouched. It corresponds to Python's `GoParser.generate_skeleton`.

func (*GolangParser) ParseFile 

func (p *GolangParser) ParseFile(filePath string) ([]SymbolData, error)

ParseFile parses filePath and returns the list of symbols (functions, methods, structs, interfaces, types) found in it. It corresponds to Python's `GoParser.parse_file`.

func (*GolangParser) ResolveImports 

func (p *GolangParser) ResolveImports(filePath, symbolName string) (string, int, error)

ResolveImports resolves the definition location of symbolName as imported by filePath, returning the defining file's path and the 1-indexed line its definition starts on. It corresponds to Python's `GoParser.resolve_imports`.

Unlike PythonParser/TypeScriptParser's ResolveImports (which return a path relative to the working directory via relFilePath), the returned path here is whatever path resolveGoPackageDir/filepath.Join produced when locating the defining file (an absolute path in practice, since both projectRoot and fileDir are resolved to absolute paths below) -- this intentionally mirrors Python's `return str(go_file), line` in ast_digger/parsers/go.py, which likewise does not normalize the result to a project-root-relative path.

type JavaParser 

type JavaParser struct {
	// contains filtered or unexported fields
}

JavaParser implements the Parser interface for Java (.java) source files.

func NewJavaParser 

func NewJavaParser() *JavaParser

NewJavaParser constructs a JavaParser with the tree-sitter-java grammar loaded.

func (*JavaParser) ExtractSymbol 

func (p *JavaParser) ExtractSymbol(filePath, symbolPath string) (SymbolData, error)

ExtractSymbol resolves symbolPath within filePath and returns the corresponding SymbolData, including its source code. symbolPath is either a bare top-level type name ("SampleClass", referring to a top-level class/interface/enum declaration itself) or a dotted "ClassName.methodName" path (referring to a method or constructor declared directly inside a class/interface/enum named ClassName, searched recursively through the whole file so ClassName may itself be a nested type). When methodName is overloaded, the first matching declaration (in source order) is returned.

func (*JavaParser) FindReferencesInFile 

func (p *JavaParser) FindReferencesInFile(filePath, symbolName string) ([]ReferenceData, error)

FindReferencesInFile searches filePath for occurrences where symbolName is referenced or invoked, excluding matches inside comments (line_comment/block_comment) and string literals (string_literal). It mirrors GolangParser.FindReferencesInFile: definition-site identifiers are not excluded, only comment and string-literal occurrences are.

func (*JavaParser) GenerateSkeleton 

func (p *JavaParser) GenerateSkeleton(filePath string) (string, error)

GenerateSkeleton reconstructs filePath's source with every method/ constructor body replaced by "{ /* ... */ }", leaving signatures, modifiers, and Javadoc comments untouched.

func (*JavaParser) ParseFile 

func (p *JavaParser) ParseFile(filePath string) ([]SymbolData, error)

ParseFile parses filePath and returns the list of symbols (classes, interfaces, enums, methods, constructors) found in it.

Field declarations (field_declaration) are intentionally not extracted as symbols, matching the same "properties are not individually extracted" design decision already applied by PythonParser/TypeScriptParser/ GolangParser. Constructors are reported with Kind "method" (there is no dedicated "constructor" kind), per design.md's F-1 policy.

func (*JavaParser) ResolveImports 

func (p *JavaParser) ResolveImports(filePath, symbolName string) (string, int, error)

ResolveImports resolves the definition location of symbolName as imported by filePath, returning the defining file's path and the 1-indexed line its top-level class/interface/enum declaration starts on.

The search root ("project root") is the process's current working directory, matching GolangParser.ResolveImports/PythonParser. ResolveImports (Python's `project_root = pathlib.Path.cwd().resolve()`). Within it, javaSourceRoot prefers a "src/main/java" directory if present, falling back to the project root itself.

Both plain imports ("import com.example.Foo;", resolved only when its last dotted component equals symbolName) and wildcard imports ("import com.example.*;", resolved by scanning every ".java" file directly in the resolved package directory, in sorted filename order, for a top-level declaration named symbolName) are supported.

As in GolangParser.ResolveImports, two distinct failure modes are distinguished: if no import's package directory could be located on disk at all, an *apperr.FileAccessError is returned; if at least one import's package directory was found but none of it (or the specific imported file) declares symbolName, an *apperr.SymbolNotFoundError is returned instead.

type JavaScriptParser 

type JavaScriptParser struct {
	// contains filtered or unexported fields
}

JavaScriptParser implements the Parser interface for JavaScript source files (".js", ".jsx", ".mjs", ".cjs").

func NewJavaScriptParser 

func NewJavaScriptParser() *JavaScriptParser

NewJavaScriptParser constructs a JavaScriptParser with the tree-sitter-javascript grammar loaded.

func (*JavaScriptParser) ExtractSymbol 

func (p *JavaScriptParser) ExtractSymbol(filePath, symbolPath string) (SymbolData, error)

ExtractSymbol resolves symbolPath (e.g. "MyClass.myMethod") within filePath and returns the corresponding SymbolData, including its source code.

func (*JavaScriptParser) FindReferencesInFile 

func (p *JavaScriptParser) FindReferencesInFile(filePath, symbolName string) ([]ReferenceData, error)

FindReferencesInFile searches filePath for occurrences where symbolName is referenced or invoked, excluding definition sites (see isJSDefinitionIdentifier). Occurrences inside comments and plain string literals are excluded implicitly: tree-sitter-javascript's grammar represents "comment" and "string" nodes as opaque leaves with no "identifier" descendants, so the traversal below never visits any text inside them. Template-literal ("template_string") text is excluded the same way, except for genuine "${...}" substitution expressions, which do parse into real identifier/expression nodes and are correctly counted as references.

func (*JavaScriptParser) GenerateSkeleton 

func (p *JavaScriptParser) GenerateSkeleton(filePath string) (string, error)

GenerateSkeleton reconstructs filePath's source with every function/method/arrow-function body replaced by "{ /* ... */ }", leaving signatures and JSDoc comments untouched.

func (*JavaScriptParser) ParseFile 

func (p *JavaScriptParser) ParseFile(filePath string) ([]SymbolData, error)

ParseFile parses filePath and returns the list of symbols (classes, functions, methods) found in it.

func (*JavaScriptParser) ResolveImports 

func (p *JavaScriptParser) ResolveImports(filePath, symbolName string) (string, int, error)

ResolveImports resolves the definition location of symbolName as imported by filePath, returning the defining file's path (relative to the current working directory / project root) and the 1-indexed line its definition starts on. It mirrors TypeScriptParser.ResolveImports, except candidate module file extensions are tried in ".js"/".jsx" priority order (rather than TypeScript's ".ts"/".tsx" order), with ".mjs"/".cjs" tried afterward as further fallbacks.

type Parser 

type Parser interface {
	// ParseFile parses filePath and returns the list of symbols found in it.
	ParseFile(filePath string) ([]SymbolData, error)

	// ExtractSymbol resolves symbolPath (e.g. "MyClass.my_method") within
	// filePath and returns the corresponding SymbolData, including its
	// source code.
	ExtractSymbol(filePath, symbolPath string) (SymbolData, error)

	// ResolveImports resolves the definition location of symbolName as
	// imported by filePath, returning the defining file path and the
	// 1-indexed line the definition starts on.
	ResolveImports(filePath, symbolName string) (defFilePath string, startLine int, err error)

	// FindReferencesInFile searches filePath for occurrences where
	// symbolName is referenced or invoked.
	FindReferencesInFile(filePath, symbolName string) ([]ReferenceData, error)

	// GenerateSkeleton reconstructs filePath's source with every
	// function/method body replaced by "..." (or a language-appropriate
	// equivalent), while preserving signatures, decorators, and
	// docstrings/doc comments verbatim.
	GenerateSkeleton(filePath string) (string, error)
}

Parser is the common AST-analysis interface implemented by every language-specific parser (PythonParser, TypeScriptParser, GolangParser).

It corresponds to the abstract `BaseParser` class defined in ast_digger/parsers/base.py.

type PythonParser 

type PythonParser struct {
	// contains filtered or unexported fields
}

PythonParser implements the Parser interface for Python source files.

It corresponds to the Python `PythonParser` class defined in ast_digger/parsers/python.py.

func NewPythonParser 

func NewPythonParser() *PythonParser

NewPythonParser constructs a PythonParser with the tree-sitter-python grammar loaded.

func (*PythonParser) ExtractSymbol 

func (p *PythonParser) ExtractSymbol(filePath, symbolPath string) (SymbolData, error)

ExtractSymbol resolves symbolPath (e.g. "MyClass.my_method") within filePath and returns the corresponding SymbolData, including its source code. It corresponds to Python's `PythonParser.extract_symbol`.

func (*PythonParser) FindReferencesInFile 

func (p *PythonParser) FindReferencesInFile(filePath, symbolName string) ([]ReferenceData, error)

FindReferencesInFile searches filePath for occurrences where symbolName is referenced or invoked, excluding definition sites (see isPythonDefinitionIdentifier). It corresponds to Python's `PythonParser.find_references_in_file`.

func (*PythonParser) GenerateSkeleton 

func (p *PythonParser) GenerateSkeleton(filePath string) (string, error)

GenerateSkeleton reconstructs filePath's source with every function/method body replaced by "..." (preceded by a preserved docstring, if the body starts with one), leaving signatures, decorators, and docstrings untouched. It corresponds to Python's `PythonParser.generate_skeleton`.

func (*PythonParser) ParseFile 

func (p *PythonParser) ParseFile(filePath string) ([]SymbolData, error)

ParseFile parses filePath and returns the list of symbols (classes, functions, methods) found in it. It corresponds to Python's `PythonParser.parse_file`.

func (*PythonParser) ResolveImports 

func (p *PythonParser) ResolveImports(filePath, symbolName string) (string, int, error)

ResolveImports resolves the definition location of symbolName as imported by filePath, returning the defining file's path (relative to the current working directory / project root) and the 1-indexed line its definition starts on. It corresponds to Python's `PythonParser.resolve_imports`.

type ReferenceData 

type ReferenceData struct {
	// FilePath is the path of the file the reference was found in.
	FilePath string `json:"file_path"`
	// LineNumber is the 1-indexed line the reference occurs on.
	LineNumber int `json:"line_number"`
	// LineContent is the source line (or snippet) containing the reference.
	// It is serialized under the "snippet" key to match Python's
	// ReferenceData dataclass field name.
	LineContent string `json:"snippet"`
}

ReferenceData describes a single place in the source tree where a symbol is referenced (e.g. called or otherwise used).

It mirrors the Python `ReferenceData` dataclass defined in ast_digger/parsers/base.py.

type RustParser 

type RustParser struct {
	// contains filtered or unexported fields
}

RustParser implements the Parser interface for Rust (.rs) source files.

func NewRustParser 

func NewRustParser() *RustParser

NewRustParser constructs a RustParser with the tree-sitter-rust grammar loaded.

func (*RustParser) ExtractSymbol 

func (p *RustParser) ExtractSymbol(filePath, symbolPath string) (SymbolData, error)

ExtractSymbol resolves symbolPath (e.g. "Greeter.greet" or "main") within filePath and returns SymbolData.

func (*RustParser) FindReferencesInFile 

func (p *RustParser) FindReferencesInFile(filePath, symbolName string) ([]ReferenceData, error)

FindReferencesInFile searches filePath for identifier nodes matching symbolName, excluding comments, string literals, and definition site identifiers.

func (*RustParser) GenerateSkeleton 

func (p *RustParser) GenerateSkeleton(filePath string) (string, error)

GenerateSkeleton reconstructs filePath's source with every function/method body block replaced by { /* ... */ }.

func (*RustParser) ParseFile 

func (p *RustParser) ParseFile(filePath string) ([]SymbolData, error)

ParseFile parses filePath and returns the list of symbols found in it.

func (*RustParser) ResolveImports 

func (p *RustParser) ResolveImports(filePath, symbolName string) (string, int, error)

ResolveImports resolves relative/crate/super/self imports in filePath for symbolName.

type SymbolData 

type SymbolData struct {
	// Name is the symbol name (e.g. "UserManager", "register_user").
	Name string `json:"name"`
	// Kind classifies the symbol, e.g. "class", "function", "method",
	// "interface", "struct", "type".
	Kind string `json:"kind"`
	// Parent is the enclosing symbol name (e.g. the class name for a
	// method), or nil for top-level symbols.
	Parent *string `json:"parent"`
	// FilePath is the path of the file the symbol was defined in.
	FilePath *string `json:"file_path"`
	// StartLine is the 1-indexed line the symbol definition starts on.
	StartLine int `json:"start_line"`
	// EndLine is the 1-indexed line the symbol definition ends on.
	EndLine int `json:"end_line"`
	// Signature holds parameter/type annotation information, if available.
	Signature *string `json:"signature"`
	// Docstring holds the symbol's docstring/doc comment text, if any.
	Docstring *string `json:"docstring"`
	// Code holds the extracted source code for the symbol. It is not
	// persisted to the cache database and is populated on demand by
	// extracting the relevant lines from the source file.
	Code *string `json:"code"`
}

SymbolData describes a single symbol (class, function, method, struct, interface, type, ...) discovered while parsing a source file.

It mirrors the Python `SymbolData` dataclass defined in ast_digger/parsers/base.py. Optional fields that may be absent for a given symbol/language combination are represented as pointers so that "not set" can be distinguished from the zero value.

type TypeScriptParser 

type TypeScriptParser struct {
	// contains filtered or unexported fields
}

TypeScriptParser implements the Parser interface for TypeScript (.ts) and TSX (.tsx) source files.

It corresponds to the Python `TypeScriptParser` class defined in ast_digger/parsers/typescript.py.

func NewTypeScriptParser 

func NewTypeScriptParser() *TypeScriptParser

NewTypeScriptParser constructs a TypeScriptParser with both the tree-sitter-typescript and tree-sitter-tsx grammars loaded.

func (*TypeScriptParser) ExtractSymbol 

func (p *TypeScriptParser) ExtractSymbol(filePath, symbolPath string) (SymbolData, error)

ExtractSymbol resolves symbolPath (e.g. "MyClass.myMethod") within filePath and returns the corresponding SymbolData, including its source code. It corresponds to Python's `TypeScriptParser.extract_symbol`.

func (*TypeScriptParser) FindReferencesInFile 

func (p *TypeScriptParser) FindReferencesInFile(filePath, symbolName string) ([]ReferenceData, error)

FindReferencesInFile searches filePath for occurrences where symbolName is referenced or invoked, excluding definition sites (see isTSDefinitionIdentifier). It corresponds to Python's `TypeScriptParser.find_references_in_file`.

func (*TypeScriptParser) GenerateSkeleton 

func (p *TypeScriptParser) GenerateSkeleton(filePath string) (string, error)

GenerateSkeleton reconstructs filePath's source with every function/method/arrow-function body replaced by "{ /* ... */ }", leaving signatures, decorators, and JSDoc comments untouched. It corresponds to Python's `TypeScriptParser.generate_skeleton`.

func (*TypeScriptParser) ParseFile 

func (p *TypeScriptParser) ParseFile(filePath string) ([]SymbolData, error)

ParseFile parses filePath and returns the list of symbols (classes, interfaces, type aliases, functions, methods) found in it. It corresponds to Python's `TypeScriptParser.parse_file`.

func (*TypeScriptParser) ResolveImports 

func (p *TypeScriptParser) ResolveImports(filePath, symbolName string) (string, int, error)

ResolveImports resolves the definition location of symbolName as imported by filePath, returning the defining file's path (relative to the current working directory / project root) and the 1-indexed line its definition starts on. It corresponds to Python's `TypeScriptParser.resolve_imports`.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.