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
- Variables
- func CodeGraphDirName() string
- func CreateDirectory(projectRoot string) error
- func DatabasePath(projectRoot string) string
- func FindNearestCodeGraphRoot(startPath string) string
- func GetCodeGraphDir(projectRoot string) string
- func GitWorktreeRoot(dir string) string
- func HashContent(content []byte) string
- func Init(projectRoot string, opts Options) (*Indexer, IndexResult, error)
- func IsCodeGraphDataDir(name string) bool
- func IsGitRepo(projectRoot string) bool
- func IsInitialized(projectRoot string) bool
- func IsSourceFile(relPath string) bool
- func IsSyncHookInstalled(projectRoot string, hooks []GitHookName) bool
- func RemoveDirectory(projectRoot string) error
- func ScanDirectory(rootDir string) []string
- func ScopedDatabasePath(projectRoot string, sc scope.Scope) string
- func Uninit(projectRoot string) error
- func WorktreeMismatchNotice(m WorktreeIndexMismatch) string
- func WorktreeMismatchWarning(m WorktreeIndexMismatch) string
- type ChangedFiles
- type GitHookName
- type GitHookResult
- type IndexProgress
- type IndexResult
- type Indexer
- func (idx *Indexer) ClearAll() error
- func (idx *Indexer) Close() error
- func (idx *Indexer) GetChangedFiles() ChangedFiles
- func (idx *Indexer) IndexAll(opts Options) IndexResult
- func (idx *Indexer) MarkCurrentGitHead() error
- func (idx *Indexer) ProjectRoot() string
- func (idx *Indexer) Rebuild(opts Options) SyncResult
- func (idx *Indexer) RefreshForRead(opts Options) (SyncResult, error)
- func (idx *Indexer) Registry() *Registry
- func (idx *Indexer) Root() string
- func (idx *Indexer) Store() *store.Store
- func (idx *Indexer) Stores() []*store.Store
- func (idx *Indexer) StoresFiltered(scopeKeys []string) []*store.Store
- func (idx *Indexer) Sync(opts Options) SyncResult
- func (idx *Indexer) SyncFiles(changed []string, opts Options) SyncResult
- func (idx *Indexer) Uninit() error
- type Options
- type PathFilter
- type Phase
- type Registry
- type SyncResult
- type WorktreeIndexMismatch
Constants ¶
const DefaultWorkers = 8
DefaultWorkers is the default extraction pool size.
const ExtractionVersion = 14
ExtractionVersion mirrors EXTRACTION_VERSION in src/extraction/extraction-version.ts at the time of the port.
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).
const PackageVersion = "0.1.0"
PackageVersion stamps the index with the engine that built it (indexed_with_version metadata, mirroring CodeGraphPackageVersion).
Variables ¶
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 ¶
CreateDirectory creates the .codegraph directory structure. It errors only when a per-scope database already exists (the directory alone is fine).
func DatabasePath ¶
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 ¶
FindNearestCodeGraphRoot walks up from startPath to find the nearest CodeGraph-initialized project root, like git finding .git/. Returns "" when none is found.
func GetCodeGraphDir ¶
GetCodeGraphDir returns the .codegraph directory path for a project.
func GitWorktreeRoot ¶
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 ¶
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 ¶
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 ¶
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 ¶
IsInitialized reports whether a project has been initialized: the .codegraph/ directory exists AND it holds at least one per-scope database.
func IsSourceFile ¶
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 ¶
RemoveDirectory removes the .codegraph directory. A symlinked .codegraph is unlinked, never followed (mirrors removeDirectory in src/directory.ts).
func ScanDirectory ¶
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 ¶
ScopedDatabasePath returns the database file path for a scope within a project: .codegraph/codegraph-{lang}-{version}.db.
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 ¶
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 ¶
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 (*Indexer) GetChangedFiles ¶
func (idx *Indexer) GetChangedFiles() ChangedFiles
GetChangedFiles prefers a persisted git revision plus git's own change lists. That avoids a whole-tree walk for each symbol read while still catching clean commits made after indexing. Non-git projects, and old indexes without a revision stamp, retain the filesystem/hash fallback.
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) MarkCurrentGitHead ¶ added in v0.5.0
MarkCurrentGitHead records the repository revision only after a caller has successfully refreshed every candidate it chose. It is public so the CLI's freshness path can make that completion explicit without making SyncFiles (which deliberately accepts arbitrary subsets) claim whole-tree freshness.
func (*Indexer) ProjectRoot ¶
ProjectRoot returns the project root directory.
func (*Indexer) Rebuild ¶ added in v0.5.0
func (idx *Indexer) Rebuild(opts Options) SyncResult
Rebuild performs a strict from-scratch reconstruction. It is used when a manifest can move many files between versioned scopes.
func (*Indexer) RefreshForRead ¶ added in v0.5.0
func (idx *Indexer) RefreshForRead(opts Options) (SyncResult, error)
RefreshForRead is the strict freshness boundary for symbol consumers. It honors the extraction-version gate, refreshes only the Git/metadata candidates, and stamps the observed revision only when HEAD did not move during the operation.
func (*Indexer) Root ¶ added in v0.5.0
Root returns the absolute project root for source retrieval clients.
func (*Indexer) 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 ¶
Stores returns every open scope store, ordered deterministically by scope key. Query consumers fan out across these and merge.
func (*Indexer) StoresFiltered ¶
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, SyncResult.LockUnavailable is returned so callers can retry without confusing an empty, fast repository with contention. 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).
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 PathFilter ¶ added in v0.6.0
type PathFilter struct {
// contains filtered or unexported fields
}
PathFilter applies the same built-in and layered .gitignore admission rules as the filesystem scanner. It is safe for concurrent watcher callbacks.
func NewPathFilter ¶ added in v0.6.0
func NewPathFilter(rootDir string) *PathFilter
NewPathFilter creates a watcher-friendly path filter for rootDir.
func (*PathFilter) IsIgnored ¶ added in v0.6.0
func (f *PathFilter) IsIgnored(relPath string) bool
IsIgnored reports whether a project-relative path is excluded. A trailing slash marks a directory. Seeing a .gitignore event invalidates the relevant cached matcher before the event is admitted for reconciliation.
func (*PathFilter) Refresh ¶ added in v0.6.0
func (f *PathFilter) Refresh()
Refresh reloads Git and ignore admission state after an ignore file or repository revision changes.
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 ¶
OpenRegistry creates a registry for projectRoot and discovers (but does not open) the scope databases already present in its .codegraph directory.
type SyncResult ¶
type SyncResult struct {
// LockUnavailable is true when another process owns the cross-process
// writer lock and no reconciliation was attempted.
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
// Errors records non-recoverable incremental-update failures. Callers that
// need fresh graph data must not treat these as a successful refresh.
Errors []model.ExtractionError
}
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 is not inside a known Git working tree.