indexer

package
v0.4.1 Latest Latest
Warning

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

 Go to latest Published: Sep 6, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package indexer orchestrates building and maintaining a codegraph index: directory management, file scanning, full indexing (Init), incremental sync, git-hook installation, and git-worktree awareness.

Ported from src/index.ts, src/directory.ts, src/extraction/index.ts and src/sync/ of github.com/colbymchenry/codegraph (MIT). Library-first: no UI, progress is reported through plain callbacks.

Index

Constants

View Source 
const DefaultWorkers = 8

DefaultWorkers is the default extraction pool size.

View Source 
const ExtractionVersion = 14

ExtractionVersion mirrors EXTRACTION_VERSION in src/extraction/extraction-version.ts at the time of the port.

View Source 
const MaxFileSize = 1024 * 1024

MaxFileSize is the largest file (bytes) the indexer will parse. Generated bundles, minified JS, and vendored blobs above this produce no useful symbols (MAX_FILE_SIZE in src/extraction/index.ts).

View Source 
const PackageVersion = "0.1.0"

PackageVersion stamps the index with the engine that built it (indexed_with_version metadata, mirroring CodeGraphPackageVersion).

Variables

View Source 
var DefaultSyncHooks = []GitHookName{HookPostCommit, HookPostMerge, HookPostCheckout}

DefaultSyncHooks are installed by default: commit, merge (git pull), and checkout.

Functions

func CodeGraphDirName 

func CodeGraphDirName() string

CodeGraphDirName resolves the per-project data directory name, honoring the CODEGRAPH_DIR environment override (default ".codegraph"). The override must be a plain directory name; anything containing path separators, "..", or an absolute path is ignored (with a one-time stderr warning), mirroring codeGraphDirName() in src/directory.ts.

func CreateDirectory 

func CreateDirectory(projectRoot string) error

CreateDirectory creates the .codegraph directory structure. It errors only when a per-scope database already exists (the directory alone is fine).

func DatabasePath 

func DatabasePath(projectRoot string) string

DatabasePath returns the legacy single-database path for a project. The index is now partitioned into per-scope databases (see ScopedDatabasePath); this helper remains only for the `import` command pending scoped-import support.

func FindNearestCodeGraphRoot 

func FindNearestCodeGraphRoot(startPath string) string

FindNearestCodeGraphRoot walks up from startPath to find the nearest CodeGraph-initialized project root, like git finding .git/. Returns "" when none is found.

func GetCodeGraphDir 

func GetCodeGraphDir(projectRoot string) string

GetCodeGraphDir returns the .codegraph directory path for a project.

func GitWorktreeRoot 

func GitWorktreeRoot(dir string) string

GitWorktreeRoot returns the absolute, symlink-resolved toplevel of the git working tree dir belongs to, or "" when dir isn't inside a git repo (or git is missing). `git rev-parse --show-toplevel` returns the per-worktree root: the main checkout and each linked worktree report their own distinct directory.

func HashContent 

func HashContent(content []byte) string

HashContent returns the SHA-256 hex digest of file content, matching hashContent in src/extraction/index.ts.

func Init 

func Init(projectRoot string, opts Options) (*Indexer, IndexResult, error)

Init initializes a new CodeGraph project: creates the .codegraph directory and database, then runs a full index (scan → concurrent extraction → batched store writes → resolution → maintenance) and stamps the project metadata. Mirrors CodeGraph.init(root, {index: true}).

func IsCodeGraphDataDir 

func IsCodeGraphDataDir(name string) bool

IsCodeGraphDataDir reports whether name (a single path segment) is a CodeGraph data directory: the default ".codegraph", the active CODEGRAPH_DIR override, or any ".codegraph-*" sibling.

func IsGitRepo 

func IsGitRepo(projectRoot string) bool

IsGitRepo reports whether projectRoot is inside a git working tree. Returns false when git isn't installed or the path isn't a repo.

func IsInitialized 

func IsInitialized(projectRoot string) bool

IsInitialized reports whether a project has been initialized: the .codegraph/ directory exists AND it holds at least one per-scope database.

func IsSourceFile 

func IsSourceFile(relPath string) bool

IsSourceFile reports whether a project-relative path has a supported source extension (Go / TypeScript / TSX / JavaScript / JSX in this port).

func IsSyncHookInstalled 

func IsSyncHookInstalled(projectRoot string, hooks []GitHookName) bool

IsSyncHookInstalled reports whether any CodeGraph sync hook is currently installed.

func RemoveDirectory 

func RemoveDirectory(projectRoot string) error

RemoveDirectory removes the .codegraph directory. A symlinked .codegraph is unlinked, never followed (mirrors removeDirectory in src/directory.ts).

func ScanDirectory 

func ScanDirectory(rootDir string) []string

ScanDirectory enumerates the project's source files as project-relative POSIX paths. In git repos it uses `git ls-files` (which respects .gitignore at all levels); otherwise it walks the filesystem applying the built-in default ignores plus .gitignore files. Mirrors scanDirectory in src/extraction/index.ts. The result is sorted for determinism. ScanDirectory returns every non-gitignored file under rootDir. Admission is decoupled from language detection: every file that .gitignore filtering keeps is indexed. Recognized languages get full symbol extraction; unknown-language files (including SpecScore artifacts and binaries) become bare file-level nodes rather than vanishing.

func ScopedDatabasePath 

func ScopedDatabasePath(projectRoot string, sc scope.Scope) string

ScopedDatabasePath returns the database file path for a scope within a project: .codegraph/codegraph-{lang}-{version}.db.

func Uninit 

func Uninit(projectRoot string) error

Uninit removes the .codegraph directory of a project that isn't open.

func WorktreeMismatchNotice 

func WorktreeMismatchNotice(m WorktreeIndexMismatch) string

WorktreeMismatchNotice is the compact, single-line variant for prefixing a tool's result.

func WorktreeMismatchWarning 

func WorktreeMismatchWarning(m WorktreeIndexMismatch) string

WorktreeMismatchWarning is the one-line-per-fact warning describing a detected mismatch.

Types

type ChangedFiles 

type ChangedFiles struct {
	Added    []string
	Modified []string
	Removed  []string
}

ChangedFiles classifies pending filesystem changes against the index.

type GitHookName 

type GitHookName string

GitHookName is a git hook the sync snippet can be installed into. 

const (
	HookPostCommit   GitHookName = "post-commit"
	HookPostMerge    GitHookName = "post-merge"
	HookPostCheckout GitHookName = "post-checkout"
)

The supported sync hooks.

type GitHookResult 

type GitHookResult struct {
	// Installed holds the hook names created, updated, or removed.
	Installed []GitHookName
	// HooksDir is the resolved hooks directory ("" when not a git repo).
	HooksDir string
	// Skipped explains why nothing happened (e.g. not a git repository).
	Skipped string
}

GitHookResult reports what an install/remove call did.

func InstallGitSyncHook 

func InstallGitSyncHook(projectRoot string, hooks []GitHookName) GitHookResult

InstallGitSyncHook installs (or updates) the CodeGraph sync snippet in the given git hooks. Idempotent: re-running replaces the marker block rather than duplicating it, and user-authored hook content is preserved.

func RemoveGitSyncHook 

func RemoveGitSyncHook(projectRoot string, hooks []GitHookName) GitHookResult

RemoveGitSyncHook removes the CodeGraph sync snippet from the given hooks. It strips only the marker block; the hook file is deleted entirely when nothing but a shebang remains, otherwise the user's content is rewritten untouched.

type IndexProgress 

type IndexProgress struct {
	Phase       Phase
	Current     int
	Total       int
	CurrentFile string
}

IndexProgress is reported to the OnProgress callback during indexing.

type IndexResult 

type IndexResult struct {
	Success      bool
	FilesIndexed int
	FilesSkipped int
	FilesErrored int
	NodesCreated int
	EdgesCreated int
	Errors       []model.ExtractionError
	DurationMs   int64
}

IndexResult is the outcome of a full or partial indexing operation.

type Indexer 

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

Indexer is an open codegraph project: the seam embedding consumers use to build and maintain the index. Construct with Init or Open.

func Open 

func Open(projectRoot string, opts Options) (*Indexer, error)

Open opens an existing CodeGraph project.

func (*Indexer) ClearAll 

func (idx *Indexer) ClearAll() error

ClearAll clears every scope store.

func (*Indexer) Close 

func (idx *Indexer) Close() error

Close releases the file lock (if held) and closes every scope store.

func (*Indexer) GetChangedFiles 

func (idx *Indexer) GetChangedFiles() ChangedFiles

GetChangedFiles classifies filesystem changes since the last index without applying them. Uses `git status --porcelain` as a fast path when available, falling back to a full scan + hash compare. Mirrors ExtractionOrchestrator.getChangedFiles.

func (*Indexer) IndexAll 

func (idx *Indexer) IndexAll(opts Options) IndexResult

IndexAll indexes every source file in the project. It holds the in-process mutex and the cross-process file lock for the duration; when the file lock is held elsewhere it returns a failed result (not an error), like the original.

func (*Indexer) ProjectRoot 

func (idx *Indexer) ProjectRoot() string

ProjectRoot returns the project root directory.

func (*Indexer) Registry 

func (idx *Indexer) Registry() *Registry

Registry exposes the per-scope store registry.

func (*Indexer) Store 

func (idx *Indexer) Store() *store.Store

Store returns the primary (lexicographically-first) scope store. It is a convenience for single-scope projects and tests; multi-scope consumers must use Stores.

func (*Indexer) Stores 

func (idx *Indexer) Stores() []*store.Store

Stores returns every open scope store, ordered deterministically by scope key. Query consumers fan out across these and merge.

func (*Indexer) StoresFiltered 

func (idx *Indexer) StoresFiltered(scopeKeys []string) []*store.Store

StoresFiltered returns the scope stores whose scope key is in scopeKeys, ordered deterministically by key. An empty scopeKeys returns all stores (identical to Stores). Unknown keys are silently ignored.

func (*Indexer) Sync 

func (idx *Indexer) Sync(opts Options) SyncResult

Sync reconciles the index with the current filesystem state. Change detection is filesystem-based, never git: a (size, mtime) stat pre-filter skips unchanged files, then a content-hash compare confirms real changes. Changed files are deleted and re-extracted, references are re-resolved, and maintenance runs when anything changed. When the cross-process file lock is held elsewhere, the zero-value SyncResult is returned (not an error), so callers like the file watcher can detect the lock case by FilesChecked==0 && DurationMs==0. Mirrors ExtractionOrchestrator.sync + CodeGraph.sync.

func (*Indexer) SyncFiles 

func (idx *Indexer) SyncFiles(changed []string, opts Options) SyncResult

SyncFiles incrementally re-indexes a known set of changed files (e.g. from a git hook or watcher event): hash-compares each candidate against the index, deletes + re-extracts real changes, removes entries whose file is gone, and re-resolves references. Paths are project-relative (POSIX or native separators).

func (*Indexer) Uninit 

func (idx *Indexer) Uninit() error

Uninit closes the index and removes the project's .codegraph directory.

type Options 

type Options struct {
	// Workers bounds the extraction goroutine pool (0 = DefaultWorkers).
	Workers int

	// OnProgress, when non-nil, receives progress updates.
	OnProgress func(IndexProgress)

	// Clock returns the current time in Unix milliseconds. Injectable for
	// deterministic tests (0/nil = time.Now).
	Clock func() int64
}

Options configures indexing operations. The zero value is usable.

type Phase 

type Phase string

Phase identifies a stage of an indexing operation. 

const (
	PhaseScanning  Phase = "scanning"
	PhaseParsing   Phase = "parsing"
	PhaseStoring   Phase = "storing"
	PhaseResolving Phase = "resolving"
)

Progress phases, mirroring IndexProgress.phase in src/extraction/index.ts.

type Registry 

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

Registry manages the per-scope SQLite stores of a single project. Stores are opened lazily and cached; existing scope databases on disk are discovered at open time.

func OpenRegistry 

func OpenRegistry(projectRoot string, opts ...store.Option) (*Registry, error)

OpenRegistry creates a registry for projectRoot and discovers (but does not open) the scope databases already present in its .codegraph directory.

func (*Registry) Close 

func (r *Registry) Close() error

Close closes every open store, returning the first error encountered.

func (*Registry) Scopes 

func (r *Registry) Scopes() []scope.Scope

Scopes returns the scopes the registry currently knows about.

func (*Registry) Store 

func (r *Registry) Store(sc scope.Scope) (*store.Store, error)

Store returns the store for a scope, creating (and initializing) its database on first request.

func (*Registry) Stores 

func (r *Registry) Stores() map[scope.Scope]*store.Store

Stores returns every open store keyed by scope.

type SyncResult 

type SyncResult struct {
	FilesChecked     int
	FilesAdded       int
	FilesModified    int
	FilesRemoved     int
	NodesUpdated     int
	DurationMs       int64
	ChangedFilePaths []string
	// FullReindex is true when Sync escalated to a from-scratch reindex
	// because the index was built by a different scanner/extraction version.
	FullReindex bool
}

SyncResult is the outcome of an incremental sync.

type WorktreeIndexMismatch 

type WorktreeIndexMismatch struct {
	// WorktreeRoot is the git working tree the command was run from.
	WorktreeRoot string
	// IndexRoot is the (different) working tree whose .codegraph index is
	// being used.
	IndexRoot string
}

WorktreeIndexMismatch describes a query borrowing another tree's index.

func DetectWorktreeIndexMismatch 

func DetectWorktreeIndexMismatch(startPath, indexRoot string) *WorktreeIndexMismatch

DetectWorktreeIndexMismatch detects when startPath lives in one git working tree but the resolved CodeGraph index (indexRoot) belongs to a *different* working tree.

Returns nil — meaning "nothing to warn about" — when startPath isn't in a git repo (or git is unavailable), the index already lives in startPath's own working tree, or indexRoot isn't itself a working-tree root (an unrelated parent dir that merely happens to contain a .codegraph/), which keeps non-git and monorepo-subdir layouts from producing false warnings.

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.