Help us shape the future of Go! Take the 2026 Go Developer Survey

graph

package
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Sep 18, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultCoarsenClusterSize = 200

DefaultCoarsenClusterSize caps a single subsystem's module count before coarsening splits it.

View Source 
const MetaVersion = 2

MetaVersion is bumped whenever the on-disk index layout changes in a way an incremental update can't reconcile; older indexes need a full build.

Variables

This section is empty.

Functions

func AppendSymbols 

func AppendSymbols(wikiDir string, g ModuleGraph) error

func AppendTypes 

func AppendTypes(wikiDir string, g ModuleGraph) error

func BuildClusterPrompt added in v0.0.4 

func BuildClusterPrompt(subsystem string, cluster []ModuleGraph) string

BuildClusterPrompt returns the plain-text data body for an LLM cluster narrative call. The role prompt is expected to describe the requested output shape (JSON with {subsystem, narrative}).

func ClusterBySubsystem added in v0.0.4 

func ClusterBySubsystem(graphs []ModuleGraph) map[string][]ModuleGraph

ClusterBySubsystem groups modules by their Subsystem tag; the returned map's values are sorted by module path for a deterministic order.

func ClusterHash added in v0.0.4 

func ClusterHash(subsystem string, cluster []ModuleGraph) string

ClusterHash returns a stable hash for a subsystem cluster covering the subsystem name, module paths (sorted), and each module's PackageDoc. Any content change invalidates the cached narrative.

func DeleteModuleGraph 

func DeleteModuleGraph(indexDir, wikiDir, modulePath string) error

DeleteModuleGraph removes the stored JSON and wiki markdown for a module. No-op if files do not exist.

func ExtractNarrativeJSON added in v0.0.4 

func ExtractNarrativeJSON(output string) string

ExtractNarrativeJSON parses an LLM output as a JSON object with a "narrative" field. Falls back to returning the raw output when parsing fails (models sometimes emit extra prose around the JSON).

func FileHash 

func FileHash(path string) (string, error)

func LangForExt 

func LangForExt(ext string) string

LangForExt returns the language name for a file extension, or "" if unknown.

func ModuleHashes 

func ModuleHashes(repoRoot string, files []string) (map[string]string, error)

func ResetAggregates 

func ResetAggregates(wikiDir string) error

func ResetModuleGraphs added in v0.0.4 

func ResetModuleGraphs(indexDir, wikiDir string) error

ResetModuleGraphs removes every stored module JSON and module page so a full build doesn't leave records for directories that no longer exist.

func SaveEdges 

func SaveEdges(indexDir string, graphs []ModuleGraph) error

func SaveMeta 

func SaveMeta(indexDir string, m *Meta) error

func SaveModuleGraph 

func SaveModuleGraph(indexDir string, g ModuleGraph) error

func Slug 

func Slug(path string) string

Slug returns the file-name stem for a module's page and stored JSON: the path flattened for readability plus a short hash of the exact path, so paths that flatten alike (a/b_c, a_b/c) never share a file.

func StubNarrative added in v0.0.4 

func StubNarrative(subsystem string) string

StubNarrative is the visible fallback rendered when a cluster narrative cannot be produced. It is deliberately shaped to be noticeable in review, not hidden as silent noise.

func SubsystemForPath added in v0.0.4 

func SubsystemForPath(modulePath string) string

SubsystemForPath returns the first meaningful segment of a module path, or "misc" if none. Example: "pkg/orchestrator/api" → "orchestrator".

func ValidateNarrative added in v0.0.4 

func ValidateNarrative(narrative string, cluster []ModuleGraph) error

ValidateNarrative applies the narrative quality gates: non-empty, >= 100 chars, references at least 2 module names from the cluster, and does not contain forbidden template phrases. Returns nil on success, error describing the failure otherwise.

func WriteIndex 

func WriteIndex(wikiDir string, graphs []ModuleGraph, narratives SubsystemNarratives) error

WriteIndex writes the top-level codebase index, grouping modules by subsystem. narratives may be nil; a subsystem without a narrative is emitted with its module list only.

func WriteModule 

func WriteModule(wikiDir string, g ModuleGraph) error

WriteModule renders a single module wiki page from tree-sitter data. The page format is deterministic — inputs of the same content produce byte-identical output, no LLM in the loop. Sections are omitted when empty. The "Part of subsystem" line links to the shared index page.

Types

type Edges 

type Edges struct {
	Imports map[string][]string `json:"imports"`
}

type ExportedFunc added in v0.0.4 

type ExportedFunc struct {
	Name      string `json:"name"`
	Signature string `json:"signature,omitempty"`
	Doc       string `json:"doc,omitempty"`
}

ExportedFunc is a single exported/public function extracted from source. Signature is language-appropriate (Go: "func Foo(x int) error"; Python: "def foo(x: int) -> None:"; etc.). Doc is the verbatim leading doc comment with delimiters stripped, or "" if none.

type ExportedType added in v0.0.4 

type ExportedType struct {
	Name   string   `json:"name"`
	Doc    string   `json:"doc,omitempty"`
	Fields []string `json:"fields,omitempty"`
}

ExportedType is a single exported/public type (Go: struct/interface; Python: class; TS: class/interface; etc.). Fields lists the type's fields/members verbatim as declared, or nil if the language/grammar does not expose them.

type Meta 

type Meta struct {
	Version    int                   `json:"version"`
	BaseCommit string                `json:"base_commit"`
	Modules    map[string]ModuleMeta `json:"modules"`
}

func LoadMeta 

func LoadMeta(indexDir string) (*Meta, error)

type Module 

type Module struct {
	Path  string
	Files []string
}

func Discover 

func Discover(repoRoot string, maxFileSizeKB int, extraExts, ignorePatterns []string) ([]Module, error)

type ModuleGraph 

type ModuleGraph struct {
	Module     string   `json:"module"`
	Summary    string   `json:"summary,omitempty"`
	PackageDoc string   `json:"package_doc,omitempty"`
	Subsystem  string   `json:"subsystem,omitempty"`
	Imports    []string `json:"imports,omitempty"`
	Consts     []string `json:"consts,omitempty"`

	ExportedFuncs []ExportedFunc `json:"exported_funcs,omitempty"`
	ExportedTypes []ExportedType `json:"exported_types,omitempty"`

	ExportFns   []string `json:"export_fns,omitempty"`
	ExportTypes []string `json:"export_types,omitempty"`
}

ModuleGraph is the per-module record persisted to `.golem/index/graph-modules/<slug>.json` and rendered to wiki pages. Every field except Subsystem comes from tree-sitter extraction; no LLM runs per module.

Summary is only read from indexes written before extraction replaced per-module LLM prose; new records leave it empty and use PackageDoc. ExportFns/ExportTypes mirror the names in ExportedFuncs/ExportedTypes for readers that only need names (graphdeps, whoimports, symbols.md).

func CoarsenSubsystems added in v0.0.4 

func CoarsenSubsystems(graphs []ModuleGraph, maxClusterSize int) []ModuleGraph

CoarsenSubsystems splits any cluster above maxClusterSize by descending one path level at a time. Modules whose path can't descend further keep their tag.

func LoadAllModuleGraphs 

func LoadAllModuleGraphs(indexDir string) ([]ModuleGraph, error)

type ModuleMeta 

type ModuleMeta struct {
	Commit     string            `json:"commit"`
	FileHashes map[string]string `json:"file_hashes"`
}

type StructuralData 

type StructuralData struct {
	PackageDoc    string
	Imports       []string
	Consts        []string
	ExportFns     []string
	ExportTypes   []string
	ExportedFuncs []ExportedFunc
	ExportedTypes []ExportedType
}

StructuralData holds the tree-sitter-extracted structural information for a source file. `ExportFns` / `ExportTypes` remain as name-only slices for backward compatibility with callers that only need names; richer records are in `ExportedFuncs` / `ExportedTypes`.

func Extract 

func Extract(source []byte, langName string) (*StructuralData, error)

Extract parses source with the tree-sitter grammar for langName and returns its package doc, imports, consts, and exported functions/types (with signatures, docs, and fields). Returns empty StructuralData (not an error) for unknown languages.

type SubsystemNarrativeCache added in v0.0.4 

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

SubsystemNarrativeCache persists cluster narratives on disk keyed by ClusterHash, so unchanged clusters never reach the LLM. Rejected outputs are cached too (Failed) so incremental updates don't re-bill them on every run. Safe for concurrent use.

func LoadNarrativeCache added in v0.0.4 

func LoadNarrativeCache(path string) (*SubsystemNarrativeCache, error)

LoadNarrativeCache reads the cache file at path. A missing file yields an empty cache; an unreadable one yields an empty cache and the error.

func (*SubsystemNarrativeCache) Lookup added in v0.0.4 

func (c *SubsystemNarrativeCache) Lookup(hash string) (narrative string, failed, ok bool)

Lookup returns the cached narrative for hash. failed reports a cached quality-gate rejection; ok is false when hash is not cached at all.

func (*SubsystemNarrativeCache) Prune added in v0.0.4 

func (c *SubsystemNarrativeCache) Prune(keep map[string]bool)

Prune drops every entry whose hash is not in keep, so superseded cluster versions don't accumulate.

func (*SubsystemNarrativeCache) Save added in v0.0.4 

func (c *SubsystemNarrativeCache) Save() error

func (*SubsystemNarrativeCache) Set added in v0.0.4 

func (c *SubsystemNarrativeCache) Set(subsystem, hash, narrative string)

func (*SubsystemNarrativeCache) SetFailed added in v0.0.4 

func (c *SubsystemNarrativeCache) SetFailed(subsystem, hash string)

SetFailed records that the cluster at hash produced a rejected narrative.

type SubsystemNarratives added in v0.0.4 

type SubsystemNarratives map[string]string

SubsystemNarratives maps a subsystem name to its cluster narrative. Passed into WriteIndex so the writer itself never calls an LLM.

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.