db

package
v1.0.3 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package db manages the SQLite index database lifecycle.

Index

Constants

View Source 
const IndexDir = ".contextception"

IndexDir is the directory name where the index is stored.

View Source 
const IndexFile = "index.sqlite"

IndexFile is the filename of the SQLite database.

Variables

This section is empty.

Functions

func ClearAllDataTx 

func ClearAllDataTx(tx *sql.Tx) error

ClearAllDataTx removes all data from files, edges, unresolved, signals, and git signal tables within a transaction.

func ClearGitDataTx 

func ClearGitDataTx(tx *sql.Tx) error

ClearGitDataTx clears git_signals and co_change_pairs within a transaction.

func DeleteFileEdgesTx 

func DeleteFileEdgesTx(tx *sql.Tx, path string) error

DeleteFileEdgesTx removes all edges originating from a file within a transaction.

func DeleteFileSignalsTx 

func DeleteFileSignalsTx(tx *sql.Tx, path string) error

DeleteFileSignalsTx removes signals for a file within a transaction.

func DeleteFileTx 

func DeleteFileTx(tx *sql.Tx, path string) error

DeleteFileTx removes a file and its associated edges/signals/unresolved (via CASCADE) within a transaction.

func DeleteFileUnresolvedTx 

func DeleteFileUnresolvedTx(tx *sql.Tx, path string) error

DeleteFileUnresolvedTx removes all unresolved imports for a file within a transaction.

func FileExistsTx 

func FileExistsTx(tx *sql.Tx, path string) (bool, error)

FileExistsTx checks if a file path exists in the index.

func IndexPath 

func IndexPath(repoRoot string) string

IndexPath returns the full path to the index file for a given repo root.

func InsertCoChangePairTx 

func InsertCoChangePairTx(tx *sql.Tx, r CoChangePairRecord) error

InsertCoChangePairTx inserts a co-change pair record within an existing transaction.

func InsertEdgeTx 

func InsertEdgeTx(tx *sql.Tx, src, dst, edgeType, spec, method string, line int, importedNames []string) error

InsertEdgeTx inserts a dependency edge within an existing transaction. Ignores duplicate edges silently. importedNames may be nil for bare imports.

func InsertFileTx 

func InsertFileTx(tx *sql.Tx, path, hash string, mtime int64, lang string, size int64) error

InsertFileTx inserts a file record within an existing transaction.

func InsertGitSignalTx 

func InsertGitSignalTx(tx *sql.Tx, r GitSignalRecord) error

InsertGitSignalTx inserts a git signal record within an existing transaction.

func InsertUnresolvedTx 

func InsertUnresolvedTx(tx *sql.Tx, src, spec, reason string, line int) error

InsertUnresolvedTx inserts an unresolved import within an existing transaction. Ignores duplicates silently.

func SetMetaTx 

func SetMetaTx(tx *sql.Tx, key, value string) error

SetMetaTx sets a metadata key within an existing transaction.

func UpsertFileTx 

func UpsertFileTx(tx *sql.Tx, path, hash string, mtime int64, lang string, size int64) error

UpsertFileTx inserts or updates a file record within an existing transaction.

Types

type CoChangePairRecord 

type CoChangePairRecord struct {
	FileA      string
	FileB      string
	Frequency  int
	WindowDays int
	ComputedAt string
}

CoChangePairRecord represents a row in the co_change_pairs table.

type CoChangePartner 

type CoChangePartner struct {
	Path      string
	Frequency int
}

CoChangePartner represents a file that co-changes with a given file.

type DirLanguageCount 

type DirLanguageCount struct {
	Dir       string
	Language  string
	FileCount int
}

DirLanguageCount represents a directory's file count for a specific language.

type DirectedEdge 

type DirectedEdge struct {
	Src string
	Dst string
}

DirectedEdge represents a directed dependency edge between two files.

type EntrypointFile 

type EntrypointFile struct {
	Path      string
	Language  string
	Indegree  int
	Outdegree int
}

EntrypointFile represents a file with structural graph signals.

type GitSignalRecord 

type GitSignalRecord struct {
	FilePath   string
	SignalType string
	Value      float64
	WindowDays int
	ComputedAt string
}

GitSignalRecord represents a row in the git_signals table.

type Index 

type Index struct {
	DB   *sql.DB
	Path string
}

Index wraps the SQLite database connection for the contextception index.

func OpenIndex 

func OpenIndex(path string) (*Index, error)

OpenIndex opens or creates the SQLite index database at the given path. It configures pragmas for WAL mode, foreign keys, and busy timeout. On first creation, it ensures .contextception/ is in .gitignore.

func (*Index) Close 

func (idx *Index) Close() error

Close closes the database connection.

func (*Index) CoChangePairCount 

func (idx *Index) CoChangePairCount(windowDays int) (int, error)

CoChangePairCount returns the number of co-change pairs for the given window.

func (*Index) EdgeCount 

func (idx *Index) EdgeCount() (int, error)

EdgeCount returns the number of dependency edges.

func (*Index) EntrypointCount 

func (idx *Index) EntrypointCount() (int, error)

EntrypointCount returns the number of files flagged as entrypoints.

func (*Index) FileCount 

func (idx *Index) FileCount() (int, error)

FileCount returns the number of indexed files.

func (*Index) FileExists 

func (idx *Index) FileExists(path string) (bool, error)

FileExists checks if a file path exists in the index (non-transaction version).

func (*Index) GetAllFileHashes 

func (idx *Index) GetAllFileHashes() (map[string]string, error)

GetAllFileHashes returns a map of path→content_hash for all indexed files.

func (*Index) GetChurnForFiles 

func (idx *Index) GetChurnForFiles(paths []string, windowDays int) (map[string]float64, error)

GetChurnForFiles returns churn values for the given paths and window.

func (*Index) GetCoChangePartners 

func (idx *Index) GetCoChangePartners(path string, windowDays int, limit int) ([]CoChangePartner, error)

GetCoChangePartners returns files that co-change with the given path, sorted by frequency desc. Pass limit=0 to return all partners (no limit).

func (*Index) GetDirectImporters 

func (idx *Index) GetDirectImporters(path string) ([]string, error)

GetDirectImporters returns all files that import the given file.

func (*Index) GetDirectImports 

func (idx *Index) GetDirectImports(path string) ([]string, error)

GetDirectImports returns all files imported by the given file.

func (*Index) GetDirectoryStructure 

func (idx *Index) GetDirectoryStructure() ([]DirLanguageCount, error)

GetDirectoryStructure returns file counts grouped by top-level directory and language.

func (*Index) GetEdgesAmong 

func (idx *Index) GetEdgesAmong(paths []string) ([]DirectedEdge, error)

GetEdgesAmong returns directed edges where both src and dst are in the given path set.

func (*Index) GetEntrypoints 

func (idx *Index) GetEntrypoints() ([]EntrypointFile, error)

GetEntrypoints returns files flagged as entrypoints (is_entrypoint=1 in signals).

func (*Index) GetForwardEdgesBatch 

func (idx *Index) GetForwardEdgesBatch(paths []string) (map[string][]string, error)

GetForwardEdgesBatch returns forward edges (imports) for multiple files in a single query. Returns a map of source file → list of destination files.

func (*Index) GetFoundations 

func (idx *Index) GetFoundations(limit int) ([]EntrypointFile, error)

GetFoundations returns the top-N files by indegree, excluding entrypoints and utilities. These are the most depended-upon source files in the project.

func (*Index) GetGoSiblingsInDir 

func (idx *Index) GetGoSiblingsInDir(dir, exclude string) ([]string, error)

GetGoSiblingsInDir returns non-test .go files in the given directory, excluding the specified file and subdirectories.

func (*Index) GetHighestChurnFile 

func (idx *Index) GetHighestChurnFile(windowDays int, exclude map[string]bool) (string, float64, error)

GetHighestChurnFile returns the file with the highest churn value for the given window, excluding files in the exclude set. Returns empty string if no churn data exists.

func (*Index) GetImportedNamesForSubject 

func (idx *Index) GetImportedNamesForSubject(subject string) (map[string][]string, error)

GetImportedNamesForSubject returns dst_file → symbol names for all edges from subject.

func (*Index) GetImporterSymbols 

func (idx *Index) GetImporterSymbols(subject string) (map[string][]string, error)

GetImporterSymbols returns src_file → symbol names for all edges into subject.

func (*Index) GetImportersOf 

func (idx *Index) GetImportersOf(paths []string, exclude map[string]bool) ([]string, error)

GetImportersOf returns reverse edges from multiple files, excluding a set.

func (*Index) GetImportsOf 

func (idx *Index) GetImportsOf(paths []string, exclude map[string]bool) ([]string, error)

GetImportsOf returns forward edges from multiple files, excluding a set.

func (*Index) GetJavaSiblingsInDir 

func (idx *Index) GetJavaSiblingsInDir(dir, exclude string) ([]string, error)

GetJavaSiblingsInDir returns non-test .java files in the given directory, excluding the specified file and subdirectories.

func (*Index) GetMaxChurn 

func (idx *Index) GetMaxChurn(windowDays int) (float64, error)

GetMaxChurn returns the maximum churn value across all files for the given window.

func (*Index) GetMaxIndegree 

func (idx *Index) GetMaxIndegree() (int, error)

GetMaxIndegree returns the maximum indegree across all signals.

func (*Index) GetMeta 

func (idx *Index) GetMeta(key string) (string, error)

GetMeta reads a metadata value by key.

func (*Index) GetOrchestrators 

func (idx *Index) GetOrchestrators(minIn, minOut, limit int, exclude map[string]bool) ([]EntrypointFile, error)

GetOrchestrators returns files with high connectivity in both directions (indegree >= minIn AND outdegree >= minOut), ordered by total degree descending. Files in the exclude set are skipped.

func (*Index) GetPackageImporterCount 

func (idx *Index) GetPackageImporterCount(dir string) (int, error)

GetPackageImporterCount returns the count of distinct files from OTHER directories that have edges pointing to any file in the given directory. Approximates "how many files outside this Go package depend on this package".

func (*Index) GetRustSiblingsInDir 

func (idx *Index) GetRustSiblingsInDir(dir, exclude string) ([]string, error)

GetRustSiblingsInDir returns non-test .rs files in the given directory, excluding the specified file and subdirectories.

func (*Index) GetSignals 

func (idx *Index) GetSignals(paths []string) (map[string]SignalRow, error)

GetSignals returns signals for the given file paths.

func (*Index) GetSubjectResolutionRate 

func (idx *Index) GetSubjectResolutionRate(subject string) (int, int, error)

GetSubjectResolutionRate returns (resolvedCount, notFoundCount) for a subject file. resolvedCount = edges from subject (internal resolved imports). notFoundCount = unresolved from subject with reason 'not_found' (internal misses), plus unresolved crate::, super::, and self:: specifiers (always internal in Rust). External and stdlib unresolved are excluded (expected, not failures).

func (*Index) GetTestFilesByName 

func (idx *Index) GetTestFilesByName(dir string, basenames []string) ([]string, error)

GetTestFilesByName searches recursively under a directory prefix for files matching any of the given basenames. Used for Python tests/ directory discovery where test files (e.g., test_pipelines.py) live in a separate tests/ tree.

func (*Index) GetTestFilesInDir 

func (idx *Index) GetTestFilesInDir(dir, suffix string) ([]string, error)

GetTestFilesInDir returns files in the given directory (not subdirectories) matching a suffix. Used for Go (_test.go) and Rust test discovery.

func (*Index) GetUnresolvedByFile 

func (idx *Index) GetUnresolvedByFile(path string) ([]UnresolvedRecord, error)

GetUnresolvedByFile returns all unresolved imports for a given file.

func (*Index) GetUnresolvedSummary 

func (idx *Index) GetUnresolvedSummary() (UnresolvedSummary, error)

GetUnresolvedSummary returns aggregate unresolved import counts grouped by reason.

func (*Index) GitSignalCount 

func (idx *Index) GitSignalCount(windowDays int) (int, error)

GitSignalCount returns the number of files with git signals for the given window.

func (*Index) MigrateToLatest 

func (idx *Index) MigrateToLatest() (bool, error)

MigrateToLatest applies all pending migrations to bring the schema up to date. Each migration runs in its own transaction. Returns true when any migration was applied, false when already up to date.

func (*Index) PackageRootCount 

func (idx *Index) PackageRootCount() (int, error)

PackageRootCount returns the number of detected package roots.

func (*Index) SchemaVersion 

func (idx *Index) SchemaVersion() (int, error)

SchemaVersion reads the current schema version from the meta table. Returns 0 if the meta table does not exist (fresh database).

func (*Index) SearchByPath 

func (idx *Index) SearchByPath(query string, limit int) ([]SearchResult, error)

SearchByPath returns files whose path contains the query substring (case-insensitive).

func (*Index) SearchBySymbol 

func (idx *Index) SearchBySymbol(symbol string, limit int) ([]SearchResult, error)

SearchBySymbol returns files that export the given symbol name (exact match). Searches the imported_names JSON column on edges — finds dst_file where any importer references the given symbol name.

func (*Index) SetMeta 

func (idx *Index) SetMeta(key, value string) error

SetMeta sets a metadata key-value pair.

func (*Index) UnresolvedCount 

func (idx *Index) UnresolvedCount() (int, error)

UnresolvedCount returns the number of unresolved imports.

func (*Index) UpsertPackageRoots 

func (idx *Index) UpsertPackageRoots(roots []PackageRootRecord) error

UpsertPackageRoots replaces all package roots for a given language.

func (*Index) UtilityCount 

func (idx *Index) UtilityCount() (int, error)

UtilityCount returns the number of files flagged as utilities.

type PackageRootRecord 

type PackageRootRecord struct {
	Path            string
	DetectionMethod string
	Language        string
}

PackageRootRecord represents a package root for bulk upsert.

type SearchResult 

type SearchResult struct {
	Path      string
	Language  string
	SizeBytes int64
}

SearchResult represents a file found by a search query.

type SignalRow 

type SignalRow struct {
	Indegree     int
	Outdegree    int
	IsEntrypoint bool
	IsUtility    bool
}

SignalRow holds precomputed structural signals for a file.

type UnresolvedRecord 

type UnresolvedRecord struct {
	SrcFile    string
	Specifier  string
	Reason     string
	LineNumber int
}

UnresolvedRecord represents a single unresolved import row.

type UnresolvedSummary 

type UnresolvedSummary struct {
	Total    int
	ByReason map[string]int
}

UnresolvedSummary holds aggregate unresolved import statistics.

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.