codemap

package
v0.5.6 Latest Latest
Warning

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

 Go to latest Published: Apr 26, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Version = "dev"

Version is the extractor version, set at build time via -ldflags.

Functions

func CtagsAvailable 

func CtagsAvailable() bool

CtagsAvailable returns true if the ctags binary is installed.

func DetectLanguage 

func DetectLanguage(path string) string

DetectLanguage returns the language identifier for a source file.

func DiscoverFiles 

func DiscoverFiles(root string, opts DiscoveryOpts) (map[ModuleKey][]string, error)

DiscoverFiles walks root and returns a map of ModuleKey → []file-path (both relative to root). ModuleKey groups files by (directory, language) so a mixed-language directory produces separate keys per language.

func GenerateMermaid 

func GenerateMermaid(graph *Graph, outputDir string) error

GenerateMermaid writes Mermaid diagram files for the graph into outputDir. Produces:

  • module-dependencies.mmd (flowchart of module imports)
  • {module}--types.mmd (classDiagram per module with types, if any)

func LoadTypeCheckedPackages 

func LoadTypeCheckedPackages(projectRoot string) ([]*packages.Package, error)

LoadTypeCheckedPackages loads all packages under projectRoot with full type information.

func RemoveDeletedFiles 

func RemoveDeletedFiles(extraction *ModuleExtraction, deletedFiles []string)

RemoveDeletedFiles removes file entries that match deletedFiles from extraction. Import graph is not modified (approximation — may retain stale entries).

func ResolveCallGraph 

func ResolveCallGraph(extractions []*ModuleExtraction, allSites []CallSite)

ResolveCallGraph populates Calls and CalledBy on symbols in extractions using allSites.

func ResolveGitCommit 

func ResolveGitCommit(root string) string

ResolveGitCommit returns the current HEAD commit SHA, or empty string.

func ResolveProjectModule 

func ResolveProjectModule(root string) (string, error)

ResolveProjectModule reads the module path from the go.mod in root.

func ResolveProjectName 

func ResolveProjectName(root, language string) (string, error)

ResolveProjectName returns the project name for a given language by reading the language-specific project descriptor file.

func ResolveRepoName 

func ResolveRepoName(root string) string

ResolveRepoName tries git remote, falls back to directory basename.

func WriteEnrichedModule 

func WriteEnrichedModule(outputDir string, enriched *EnrichedModule) error

WriteEnrichedModule writes an enriched module JSON to outputDir atomically.

func WriteGraph 

func WriteGraph(path string, g *Graph) error

WriteGraph writes the graph to path atomically.

func WriteManifest 

func WriteManifest(path string, m *Manifest) error

WriteManifest writes the manifest to path atomically.

func WriteModuleExtraction 

func WriteModuleExtraction(outputDir string, extraction *ModuleExtraction) error

WriteModuleExtraction writes a single module's extraction to JSON in outputDir. Uses atomic write (write to .tmp then rename).

func WriteNarrative 

func WriteNarrative(path, content string) error

WriteNarrative writes the narrative markdown to path atomically.

Types

type CallGraphEdge 

type CallGraphEdge struct {
	From        string `json:"from"`
	To          string `json:"to"`
	CrossModule bool   `json:"cross_module"`
}

CallGraphEdge is a call relationship (populated by CM-007).

type CallGraphLayer 

type CallGraphLayer struct {
	Description string          `json:"description"`
	Nodes       []CallGraphNode `json:"nodes"`
	Edges       []CallGraphEdge `json:"edges"`
}

CallGraphLayer is populated by CM-007; empty for now.

type CallGraphNode 

type CallGraphNode struct {
	ID     string `json:"id"`
	Module string `json:"module"`
}

CallGraphNode is a function node (populated by CM-007).

type CallSite 

type CallSite struct {
	CallerFunc  string // fully qualified: "internal/codemap.ExtractModule"
	CalleeName  string // fully qualified: "internal/codemap.ParseGoFile"
	Line        int
	IsMethod    bool
	CrossModule bool
}

CallSite represents a single project-internal function call relationship.

func ExtractCallSites 

func ExtractCallSites(fset *token.FileSet, pkg *packages.Package, projectModule string) []CallSite

ExtractCallSites finds all project-internal call sites in a type-checked package. Only includes calls to functions within the same project module.

type ChangeSet 

type ChangeSet struct {
	FullRemap    bool
	ChangedFiles []string
	NewFiles     []string
	DeletedFiles []string
	Method       string // "git" or "mtime"
}

ChangeSet describes what changed since the last extraction.

func DetectChanges 

func DetectChanges(manifest *Manifest, projectRoot string, discoveredFiles map[ModuleKey][]string) (*ChangeSet, error)

DetectChanges compares manifest state against current filesystem/git state. Returns FullRemap=true when the manifest is unusable or missing.

type CtagsTag 

type CtagsTag struct {
	Name      string `json:"name"`
	Path      string `json:"path"`
	Language  string `json:"language"`
	Kind      string `json:"kind"`
	Line      int    `json:"line"`
	End       int    `json:"end"`
	Signature string `json:"signature"`
	Access    string `json:"access"`
	Scope     string `json:"scope"`
	ScopeKind string `json:"scopeKind"`
}

CtagsTag represents one tag from ctags --output-format=json.

func RunCtags 

func RunCtags(files []string, projectRoot string) ([]CtagsTag, error)

RunCtags invokes universal-ctags on the given files and returns parsed tags. files should be paths relative to projectRoot.

type DegreeInfo 

type DegreeInfo struct {
	Module string `json:"module"`
	Degree int    `json:"degree"`
}

DegreeInfo identifies the module with the highest degree and its edge count.

type DiscoveryOpts 

type DiscoveryOpts struct {
	ExcludePatterns  []string
	IncludeGenerated bool
	SpecificFiles    []string
	Lang             string // "auto", "go", etc.
}

DiscoveryOpts controls file discovery behaviour.

type EnrichOpts 

type EnrichOpts struct {
	Model   string
	Budget  float64
	Verbose bool
}

EnrichOpts controls LLM enrichment behaviour.

type EnrichedFileExtract 

type EnrichedFileExtract struct {
	Path        string         `json:"path"`
	LineCount   int            `json:"line_count"`
	Symbols     []MergedSymbol `json:"symbols"`
	ErrorCount  int            `json:"error_count"`
	ParseErrors []ParseError   `json:"parse_errors"`
}

EnrichedFileExtract is a FileExtract with merged (base + enrichment) symbols.

type EnrichedModule 

type EnrichedModule struct {
	Module           string                `json:"module"`
	Language         string                `json:"language"`
	Files            []EnrichedFileExtract `json:"files"`
	Imports          ImportGraph           `json:"imports"`
	ExtractedAt      string                `json:"extracted_at"`
	ExtractorVersion string                `json:"extractor_version"`
	// LLM enrichment fields
	ModuleDescription string   `json:"module_description,omitempty"`
	ModuleCategory    string   `json:"module_category,omitempty"`
	KeyTypes          []string `json:"key_types,omitempty"`
	KeyFunctions      []string `json:"key_functions,omitempty"`
	EnrichedAt        string   `json:"enriched_at,omitempty"`
	EnricherModel     string   `json:"enricher_model,omitempty"`
}

EnrichedModule is the full enriched extraction output. It mirrors ModuleExtraction but with EnrichedFileExtract and module-level LLM fields.

type EnrichedSymbol 

type EnrichedSymbol struct {
	Name              string   `json:"name"`
	Description       string   `json:"description,omitempty"`
	ModuleIdentity    string   `json:"module_identity,omitempty"`
	Complexity        string   `json:"complexity,omitempty"`
	IsEntrypoint      bool     `json:"is_entrypoint"`
	ArchitecturalRole string   `json:"architectural_role,omitempty"`
	Tags              []string `json:"tags,omitempty"`
}

EnrichedSymbol is the LLM enrichment delta for a single symbol, matched by Name.

type Enricher 

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

Enricher calls the Anthropic API to add semantic enrichment to module extractions.

func NewEnricher 

func NewEnricher(apiKey string, opts EnrichOpts) *Enricher

NewEnricher creates an Enricher with the given API key and options.

func (*Enricher) EnrichGraph 

func (e *Enricher) EnrichGraph(graph *Graph, enrichedModules map[string]*EnrichedModule)

EnrichGraph merges enrichment data into graph module nodes in place.

func (*Enricher) EnrichModule 

func (e *Enricher) EnrichModule(extraction *ModuleExtraction) (*EnrichedModule, error)

EnrichModule calls the LLM to enrich a single module extraction. API errors are returned as-is; callers should handle them per-module.

func (*Enricher) GenerateNarrative 

func (e *Enricher) GenerateNarrative(graph *Graph, enrichedModules map[string]*EnrichedModule) (string, error)

GenerateNarrative calls the LLM to produce an ARCHITECTURE.md narrative.

func (*Enricher) Spent 

func (e *Enricher) Spent() float64

Spent returns the total USD spent so far.

type FileExtract 

type FileExtract struct {
	Path        string       `json:"path"`
	LineCount   int          `json:"line_count"`
	Symbols     []Symbol     `json:"symbols"`
	ErrorCount  int          `json:"error_count"`
	ParseErrors []ParseError `json:"parse_errors"`
}

FileExtract holds per-file extraction output.

type GoExtractor 

type GoExtractor struct{}

GoExtractor implements LanguageExtractor for Go source files using go/ast.

func (*GoExtractor) ClassifyImport 

func (g *GoExtractor) ClassifyImport(importPath, projectModule string) string

ClassifyImport returns "internal", "external", or "stdlib". Internal: path starts with projectModule. Stdlib: first path segment contains no dot (e.g. "fmt", "encoding/json"). External: everything else.

func (*GoExtractor) Extensions 

func (g *GoExtractor) Extensions() []string

func (*GoExtractor) ExtractFile 

func (g *GoExtractor) ExtractFile(fset *token.FileSet, file *ast.File, source []byte, projectModule string) ([]Symbol, ImportGraph)

ExtractFile walks a parsed AST and extracts symbols and the import graph.

func (*GoExtractor) IsExported 

func (g *GoExtractor) IsExported(name string) bool

func (*GoExtractor) Language 

func (g *GoExtractor) Language() string

type Graph 

type Graph struct {
	Version     string      `json:"version"`
	Repo        string      `json:"repo"`
	GeneratedAt string      `json:"generated_at"`
	GitCommit   string      `json:"git_commit"`
	Layers      GraphLayers `json:"layers"`
	Stats       GraphStats  `json:"stats"`
}

Graph is the multi-layer topology graph matching graph.schema.json.

func AggregateGraph 

func AggregateGraph(extractions []*ModuleExtraction, repoName, gitCommit string) *Graph

AggregateGraph builds the multi-layer graph from all module extractions.

type GraphLayers 

type GraphLayers struct {
	ModuleDependencies ModuleDepLayer `json:"module_dependencies"`
	TypeRelationships  TypeRelLayer   `json:"type_relationships"`
	CallGraph          CallGraphLayer `json:"call_graph"`
}

GraphLayers holds the three topology layers.

type GraphStats 

type GraphStats struct {
	TotalModules         int         `json:"total_modules"`
	TotalSymbols         int         `json:"total_symbols"`
	TotalDependencyEdges int         `json:"total_dependency_edges"`
	TotalTypeEdges       int         `json:"total_type_edges"`
	TotalCallEdges       int         `json:"total_call_edges"`
	AvgInDegree          float64     `json:"avg_in_degree"`
	MaxInDegree          *DegreeInfo `json:"max_in_degree"`
	MaxOutDegree         *DegreeInfo `json:"max_out_degree"`
}

GraphStats holds topology metrics for the whole graph.

type ImportGraph 

type ImportGraph struct {
	Internal []string `json:"internal"`
	External []string `json:"external"`
	Stdlib   []string `json:"stdlib"`
}

ImportGraph aggregates imports for a module split by origin.

func ExtractImports 

func ExtractImports(source []byte, lang string, projectName string) ImportGraph

ExtractImports extracts import classifications for a non-Go source file using regex.

type LanguageExtractor 

type LanguageExtractor interface {
	Language() string
	Extensions() []string
	IsExported(name string) bool
	// ClassifyImport returns "internal", "external", or "stdlib".
	ClassifyImport(importPath string, projectModule string) string
}

LanguageExtractor abstracts language-specific extraction logic.

type Manifest 

type Manifest struct {
	Version          string                     `json:"version"`
	RepoName         string                     `json:"repo_name"`
	ProjectRoot      string                     `json:"project_root"`
	Languages        []string                   `json:"languages"`
	Modules          map[string]*ManifestModule `json:"modules"`
	LastFullMap      *string                    `json:"last_full_map"`
	LastIncremental  *string                    `json:"last_incremental"`
	Stats            ManifestStats              `json:"stats"`
	ExtractorVersion string                     `json:"extractor_version"`
	GitCommit        string                     `json:"git_commit"`
}

Manifest tracks extraction state and per-file timestamps. Matches manifest.schema.json.

func BuildManifest 

func BuildManifest(projectRoot string, extractions []*ModuleExtraction, version string) (*Manifest, error)

BuildManifest constructs a fresh manifest from extraction results.

func LoadManifest 

func LoadManifest(path string) (*Manifest, error)

LoadManifest loads a manifest from disk. Returns an empty manifest if path does not exist.

type ManifestFile 

type ManifestFile struct {
	Mtime       string  `json:"mtime"`
	ExtractedAt string  `json:"extracted_at"`
	EnrichedAt  *string `json:"enriched_at"`
	LineCount   int     `json:"line_count"`
	SymbolCount int     `json:"symbol_count"`
}

ManifestFile holds per-file timestamps and metrics.

type ManifestModule 

type ManifestModule struct {
	Files         map[string]*ManifestFile `json:"files"`
	LastExtracted string                   `json:"last_extracted"`
	LastEnriched  *string                  `json:"last_enriched"`
	Status        string                   `json:"status"` // extracted, enriched, stale, error
}

ManifestModule holds per-module tracking state.

type ManifestStats 

type ManifestStats struct {
	TotalFiles     int            `json:"total_files"`
	TotalModules   int            `json:"total_modules"`
	TotalSymbols   int            `json:"total_symbols"`
	TotalFunctions int            `json:"total_functions"`
	TotalTypes     int            `json:"total_types"`
	Languages      map[string]int `json:"languages"`
}

ManifestStats aggregates extraction metrics.

type MergedSymbol 

type MergedSymbol struct {
	Name       string      `json:"name"`
	Kind       string      `json:"kind"`
	Signature  string      `json:"signature"`
	Params     []Param     `json:"params"`
	Returns    []ReturnVal `json:"returns"`
	Receiver   *string     `json:"receiver"`
	LineStart  int         `json:"line_start"`
	LineEnd    int         `json:"line_end"`
	Exported   bool        `json:"exported"`
	Decorators []string    `json:"decorators"`
	Calls      []string    `json:"calls"`
	CalledBy   []string    `json:"called_by"`
	// LLM enrichment (omitempty keeps unenriched symbols clean)
	Description       string   `json:"description,omitempty"`
	ModuleIdentity    string   `json:"module_identity,omitempty"`
	Complexity        string   `json:"complexity,omitempty"`
	IsEntrypoint      bool     `json:"is_entrypoint,omitempty"`
	ArchitecturalRole string   `json:"architectural_role,omitempty"`
	Tags              []string `json:"tags,omitempty"`
}

MergedSymbol combines base Symbol fields with LLM enrichment fields for the final JSON output.

type ModuleDepLayer 

type ModuleDepLayer struct {
	Description string                 `json:"description"`
	Nodes       []ModuleNode           `json:"nodes"`
	Edges       []ModuleDependencyEdge `json:"edges"`
}

ModuleDepLayer is the module-level import dependency layer.

type ModuleDependencyEdge 

type ModuleDependencyEdge struct {
	From              string `json:"from"`
	To                string `json:"to"`
	Type              string `json:"type"`
	SymbolsReferenced int    `json:"symbols_referenced"`
}

ModuleDependencyEdge represents an import relationship between modules.

type ModuleExtraction 

type ModuleExtraction struct {
	Module           string        `json:"module"`
	Language         string        `json:"language"`
	Files            []FileExtract `json:"files"`
	Imports          ImportGraph   `json:"imports"`
	ExtractedAt      string        `json:"extracted_at"`
	ExtractorVersion string        `json:"extractor_version"`
}

ModuleExtraction is the top-level output per module, matching extraction.schema.json.

func ExtractModule 

func ExtractModule(modulePath string, filePaths []string, projectRoot string, projectModule string, verbose bool) (*ModuleExtraction, error)

ExtractModule runs Go symbol extraction across all files in a module.

func ExtractModuleCtags 

func ExtractModuleCtags(modulePath string, filePaths []string, lang string, projectRoot string, projectName string, verbose bool) (*ModuleExtraction, error)

ExtractModuleCtags extracts symbols and imports for a non-Go module using ctags + regex.

func LoadExistingExtraction 

func LoadExistingExtraction(outputDir, modulePath string) (*ModuleExtraction, error)

LoadExistingExtraction reads a previously written extraction JSON file from outputDir.

func MergeExtraction 

func MergeExtraction(existing, partial *ModuleExtraction) *ModuleExtraction

MergeExtraction updates an existing module extraction with new file data from partial. Files present in partial replace their counterparts in existing; other files are kept. Import graphs are unioned (approximation — may retain stale entries for deleted imports).

type ModuleKey 

type ModuleKey struct {
	Path     string // directory relative to project root (empty = repo root)
	Language string // "go", "rust", "typescript", "python", "r"
}

ModuleKey identifies a logical module by directory and language. A single directory can contain files of multiple languages, each forming its own ModuleKey group.

type ModuleNode 

type ModuleNode struct {
	ID           string   `json:"id"`
	Category     string   `json:"category"`
	Language     string   `json:"language"`
	SymbolCount  int      `json:"symbol_count"`
	FileCount    int      `json:"file_count"`
	Description  *string  `json:"description"`
	KeyTypes     []string `json:"key_types"`
	KeyFunctions []string `json:"key_functions"`
}

ModuleNode represents a module in the dependency graph.

type Param 

type Param struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

Param is a function parameter with name and type.

type ParseError 

type ParseError struct {
	Line    int    `json:"line"`
	Column  int    `json:"column"`
	Message string `json:"message"`
}

ParseError describes a parse error found during extraction.

func ParseGoFile 

func ParseGoFile(fset *token.FileSet, path string, source []byte) (*ast.File, []ParseError, error)

ParseGoFile parses a Go source file and returns the AST plus any parse errors. It always returns a (possibly partial) AST — parse errors are non-fatal. Only returns a non-nil error for truly fatal failures (unreadable file when source is nil).

type ReturnVal 

type ReturnVal struct {
	Type string `json:"type"`
}

ReturnVal is a return value type.

type Symbol 

type Symbol struct {
	Name       string      `json:"name"`
	Kind       string      `json:"kind"` // "function", "method", "type", "interface", "const", "var"
	Signature  string      `json:"signature"`
	Params     []Param     `json:"params"`
	Returns    []ReturnVal `json:"returns"`
	Receiver   *string     `json:"receiver"`
	LineStart  int         `json:"line_start"`
	LineEnd    int         `json:"line_end"`
	Exported   bool        `json:"exported"`
	Decorators []string    `json:"decorators"`
	Calls      []string    `json:"calls"`
	CalledBy   []string    `json:"called_by"`
}

Symbol represents a top-level declaration extracted from a source file.

func CtagsToSymbol 

func CtagsToSymbol(tag CtagsTag, lang string) Symbol

CtagsToSymbol converts a CtagsTag to a Symbol.

type TypeNode 

type TypeNode struct {
	ID     string `json:"id"`
	Kind   string `json:"kind"`
	Module string `json:"module"`
}

TypeNode represents a type or interface in the type relationship layer.

type TypeRelLayer 

type TypeRelLayer struct {
	Description string                 `json:"description"`
	Nodes       []TypeNode             `json:"nodes"`
	Edges       []TypeRelationshipEdge `json:"edges"`
}

TypeRelLayer holds type-level relationships.

type TypeRelationshipEdge 

type TypeRelationshipEdge struct {
	From  string `json:"from"`
	To    string `json:"to"`
	Type  string `json:"type"`
	Field string `json:"field,omitempty"`
}

TypeRelationshipEdge represents a structural relationship between types.

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.