codeintel

package
v0.23.0 Latest Latest
Warning

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

 Go to latest Published: Jun 5, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package codeintel provides code intelligence for the donmai CLI.

Native implementation (S0 + S1)

get-repo-map and search-symbols are now implemented natively in Go via pure-regex extractors (TypeScriptExtractor, GoExtractor) and a JSON-serialised index persisted to .donmai/code-index/index.json.

The native path is the PRIMARY implementation for those two subcommands. The exec-shim (DONMAI_CODE_BIN env override) is kept as a FALLBACK for operators who need to force the TypeScript implementation — e.g., to test against a known-good TS-generated index.

Exec-shim fallback

For subcommands not yet natively ported (search-code, check-duplicate, find-type-usages, validate-cross-deps) the shim path is used:

  1. DONMAI_CODE_BIN env var (legacy: AGENTFACTORY_CODE_BIN) — explicit override
  2. `donmai-code` on PATH (installed via `npm install -g @donmai/cli`)
  3. `pnpm donmai-code` (monorepo dev)

If none resolve, the command returns ErrNotAvailable with clear installation instructions. Operators can set DONMAI_CODE_BIN to any binary/script to override the native implementation as well.

Index format compatibility

The persisted .donmai/code-index/index.json schema is byte-compatible with the TypeScript @donmai/code-intelligence IncrementalIndexer.save() output: 

{ "files": { "<filePath>": FileIndex }, "rootHash": "<hash>" }

where FileIndex matches the TS FileIndexSchema (types.ts). The content hash (gitHash field) uses git-blob SHA1, and the S3-scope xxHash64 dedup field uses github.com/cespare/xxhash/v2 (seed=0) which produces identical output to the TS xxhash-wasm h64ToString() call.

Package codeintel provides native Go code intelligence (S0+S1).

Native implementation

get-repo-map and search-symbols use pure-Go regex extractors (TypeScriptExtractor, GoExtractor) with a JSON-serialised index persisted to .donmai/code-index/index.json. No external binary is required for these subcommands.

index.json schema compatibility

The persisted schema is byte-compatible with the TypeScript @donmai/code-intelligence IncrementalIndexer.save() output: 

{ "files": { "<filePath>": FileIndex }, "rootHash": "<hash>" }

where FileIndex matches the TS FileIndexSchema (types.ts). The gitHash field uses git-blob SHA1 (sha1("blob <size>\0<content>")) — identical to GitHashProvider.hashContent() in the TS package.

Exec-shim fallback

For subcommands not yet natively ported (search-code, check-duplicate, find-type-usages, validate-cross-deps) the Runner falls back to the exec-shim path:

  1. DONMAI_CODE_BIN env var (legacy: AGENTFACTORY_CODE_BIN) — explicit override
  2. `donmai-code` on PATH (installed via `npm install -g @donmai/cli`)
  3. `pnpm donmai-code` (monorepo dev)

If none resolve, the command returns ErrNotAvailable.

Index

Constants

This section is empty.

Variables

View Source 
var ErrArchNotAvailable = errors.New(
	"donmai-arch binary not found — install @donmai/cli globally " +
		"(`npm install -g @donmai/cli`) or set DONMAI_ARCH_BIN",
)

ErrArchNotAvailable is returned when the donmai-arch binary cannot be found.

View Source 
var ErrNotAvailable = errors.New(
	"donmai-code binary not found — install @donmai/cli globally " +
		"(`npm install -g @donmai/cli`) or set DONMAI_CODE_BIN",
)

ErrNotAvailable is returned when the donmai-code binary cannot be found. Callers should surface this with instructions rather than treating it as a fatal error.

Functions

func ContentXXHash64 added in v0.23.0 

func ContentXXHash64(content string) string

ContentXXHash64 computes the xxHash64 (seed=0) of content as a hex string. This matches the TS xxhash64() function which calls h64ToString(content) from the xxhash-wasm package.

The xxhash-wasm h64ToString function uses seed=0 (default) and returns the hash as a lowercase hex string. github.com/cespare/xxhash/v2 uses seed=0 by default and produces identical output.

Types

type ArchAssessOptions 

type ArchAssessOptions struct {
	// PrURL is the full GitHub PR URL (e.g. https://github.com/org/repo/pull/123).
	// Takes precedence over Repository+PrNumber when both are provided.
	PrURL string

	// Repository is the repo identifier (e.g. github.com/org/repo).
	Repository string

	// PrNumber is the PR number within the repository.
	PrNumber int

	// GatePolicy overrides DONMAI_DRIFT_GATE: none | no-severity-high | zero-deviations | max:N
	GatePolicy string

	// ScopeLevel is the scope level for the baseline query.
	// Valid values: project | org | tenant | global
	ScopeLevel string

	// ProjectID is the project ID for scope.
	ProjectID string

	// DB is the SQLite DB path (overrides DONMAI_ARCH_DB).
	DB string

	// Summary outputs human-readable text instead of JSON.
	Summary bool
}

ArchAssessOptions holds the flags for donmai-arch assess.

type CheckDuplicateOptions 

type CheckDuplicateOptions struct {
	Content     string
	ContentFile string
}

CheckDuplicateOptions holds the flags for check-duplicate.

type CodeSymbol added in v0.23.0 

type CodeSymbol struct {
	Name          string     `json:"name"`
	Kind          SymbolKind `json:"kind"`
	FilePath      string     `json:"filePath"`
	Line          int        `json:"line"`
	EndLine       *int       `json:"endLine,omitempty"`
	Signature     string     `json:"signature,omitempty"`
	Documentation string     `json:"documentation,omitempty"`
	Exported      bool       `json:"exported"`
	ParentName    string     `json:"parentName,omitempty"`
	Language      string     `json:"language,omitempty"`
}

CodeSymbol mirrors the TS CodeSymbol type from types.ts. JSON field names must match the TS serialisation exactly for index.json round-trip compatibility.

type FileAST added in v0.23.0 

type FileAST struct {
	FilePath string
	Language string
	Symbols  []CodeSymbol
	Imports  []string
	Exports  []string
}

FileAST holds the extraction result for a single file. It is an in-memory intermediate and is NOT persisted directly; see FileIndex for what goes to disk.

type FileIndex added in v0.23.0 

type FileIndex struct {
	FilePath    string       `json:"filePath"`
	GitHash     string       `json:"gitHash"`
	Symbols     []CodeSymbol `json:"symbols"`
	LastIndexed int64        `json:"lastIndexed"` // Unix ms
}

FileIndex is the per-file node persisted to index.json. Schema matches the TS FileIndexSchema in types.ts.

type FindTypeUsagesOptions 

type FindTypeUsagesOptions struct {
	TypeName   string
	MaxResults int
}

FindTypeUsagesOptions holds the flags for find-type-usages.

type GetRepoMapOptions 

type GetRepoMapOptions struct {
	MaxFiles     int
	FilePatterns []string
}

GetRepoMapOptions holds the flags for get-repo-map.

type GoExtractor added in v0.23.0 

type GoExtractor struct{}

GoExtractor is a pure-regex symbol extractor for Go source files. It is a faithful port of the TS GoExtractor class from donmai-libraries/packages/code-intelligence/src/parser/go-extractor.ts.

func (*GoExtractor) Extract added in v0.23.0 

func (e *GoExtractor) Extract(source, filePath string) FileAST

Extract parses Go source and returns a FileAST.

type IndexFile added in v0.23.0 

type IndexFile struct {
	Files    map[string]FileIndex `json:"files"`
	RootHash string               `json:"rootHash"`
}

IndexFile is the top-level structure of .donmai/code-index/index.json. The TS IncrementalIndexer.save() writes: 

{ "files": { "<filePath>": FileIndex, ... }, "rootHash": "<hash>" }

type IndexMetadata added in v0.23.0 

type IndexMetadata struct {
	Version      int      `json:"version"`
	RootHash     string   `json:"rootHash"`
	TotalFiles   int      `json:"totalFiles"`
	TotalSymbols int      `json:"totalSymbols"`
	LastUpdated  int64    `json:"lastUpdated"` // Unix ms
	Languages    []string `json:"languages"`
}

IndexMetadata is the top-level metadata block persisted to index.json. Schema matches the TS IndexMetadataSchema in types.ts.

type NativeRunner added in v0.23.0 

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

NativeRunner provides the S0+S1 subset of code intelligence using pure Go implementations (no external binary required). It covers:

  • GetRepoMap — builds / loads index.json, produces a ranked file map
  • SearchSymbols — BM25-style symbol search over the native index

For operations not yet natively ported (search-code, check-duplicate, find-type-usages, validate-cross-deps) the Runner falls back to the exec-shim path (DONMAI_CODE_BIN / donmai-code / pnpm donmai-code).

The native path is the PRIMARY implementation. The exec-shim is ONLY consulted when DONMAI_CODE_BIN is set, which operators can use for testing or to force the TypeScript path.

func NewNativeRunner added in v0.23.0 

func NewNativeRunner(cwd string) *NativeRunner

NewNativeRunner creates a NativeRunner that operates relative to cwd.

func (*NativeRunner) BuildIndex added in v0.23.0 

func (n *NativeRunner) BuildIndex(opts GetRepoMapOptions) (IndexFile, error)

BuildIndex walks the repository, extracts symbols from all indexable files, and persists the result to index.json. Returns the updated IndexFile.

func (*NativeRunner) GetRepoMapNative added in v0.23.0 

func (n *NativeRunner) GetRepoMapNative(opts GetRepoMapOptions) (any, error)

GetRepoMapNative builds (or loads) the code index and returns a PageRank-ranked repository map as a slice of RepoMapEntry values serialised to JSON-compatible any.

The ranking heuristic assigns each file a score based on the number of exported symbols and penalises test files. This intentionally mirrors the spirit of the TS implementation (BM25 + PageRank) without the full graph computation, which is deferred to S3.

func (*NativeRunner) SearchSymbolsNative added in v0.23.0 

func (n *NativeRunner) SearchSymbolsNative(opts SearchSymbolsOptions) (any, error)

SearchSymbolsNative searches the code index for symbols matching the query. It uses a simple BM25-inspired scoring: exact-name match > prefix match > contains match, filtered optionally by kind and file pattern.

type RepoMapEntry added in v0.23.0 

type RepoMapEntry struct {
	FilePath string          `json:"filePath"`
	Rank     float64         `json:"rank"`
	Symbols  []RepoMapSymbol `json:"symbols"`
}

RepoMapEntry mirrors the TS RepoMapEntrySchema.

type RepoMapSymbol added in v0.23.0 

type RepoMapSymbol struct {
	Name string     `json:"name"`
	Kind SymbolKind `json:"kind"`
	Line int        `json:"line"`
}

RepoMapSymbol is the trimmed symbol shape inside a RepoMapEntry.

type Runner 

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

Runner wraps the donmai-code / donmai-arch CLI binaries and exposes each command as a typed Go function. All public methods return raw JSON-decoded output as map[string]any or []any, matching the TS CLI's JSON-to-stdout contract.

func New 

func New(cwd string) *Runner

New creates a Runner that invokes commands relative to cwd. cwd should be the repository root (the directory where .donmai/ resides or will reside).

func (*Runner) ArchAssess 

func (r *Runner) ArchAssess(opts ArchAssessOptions) (any, error)

ArchAssess runs `donmai-arch assess`. Exit code 1 from the subprocess means the gate was triggered — this is mapped to an ErrGateTriggered sentinel rather than a generic error so callers can handle it without parsing stderr.

func (*Runner) CheckDuplicate 

func (r *Runner) CheckDuplicate(opts CheckDuplicateOptions) (any, error)

CheckDuplicate runs `donmai-code check-duplicate`.

func (*Runner) FindTypeUsages 

func (r *Runner) FindTypeUsages(opts FindTypeUsagesOptions) (any, error)

FindTypeUsages runs `donmai-code find-type-usages <TypeName>`.

func (*Runner) GetRepoMap 

func (r *Runner) GetRepoMap(opts GetRepoMapOptions) (any, error)

GetRepoMap builds a PageRank-ranked repository map.

When DONMAI_CODE_BIN is set the exec-shim is used (operator override for testing or forcing the TypeScript path). Otherwise the native Go implementation is used — no external binary required.

func (*Runner) IsArchAvailable 

func (r *Runner) IsArchAvailable() bool

IsArchAvailable returns true if the donmai-arch binary can be found.

func (*Runner) IsCodeAvailable 

func (r *Runner) IsCodeAvailable() bool

IsCodeAvailable returns true. The native implementation for get-repo-map and search-symbols is always available (no external binary required). For the remaining exec-shim commands (search-code, check-duplicate, find-type-usages, validate-cross-deps) callers should handle ErrNotAvailable gracefully.

func (*Runner) SearchCode 

func (r *Runner) SearchCode(opts SearchCodeOptions) (any, error)

SearchCode runs `donmai-code search-code <query>`.

func (*Runner) SearchSymbols 

func (r *Runner) SearchSymbols(opts SearchSymbolsOptions) (any, error)

SearchSymbols searches the code index for symbols matching the query.

When DONMAI_CODE_BIN is set the exec-shim is used. Otherwise the native Go implementation is used.

func (*Runner) ValidateCrossDeps 

func (r *Runner) ValidateCrossDeps(opts ValidateCrossDepsOptions) (any, error)

ValidateCrossDeps runs `donmai-code validate-cross-deps [path]`.

type SearchCodeOptions 

type SearchCodeOptions struct {
	Query      string
	MaxResults int
	Language   string
}

SearchCodeOptions holds the flags for search-code.

type SearchSymbolsOptions 

type SearchSymbolsOptions struct {
	Query       string
	MaxResults  int
	Kinds       []string
	FilePattern string
}

SearchSymbolsOptions holds the flags for search-symbols.

type SymbolKind added in v0.23.0 

type SymbolKind string

SymbolKind enumerates the kinds of code symbols the extractors recognise. Values are the string literals used in the TS @donmai/code-intelligence package (types.ts — SymbolKindSchema) and serialised into index.json verbatim. Do NOT change these strings without also updating the TS side. 

const (
	KindFunction  SymbolKind = "function"
	KindClass     SymbolKind = "class"
	KindInterface SymbolKind = "interface"
	KindType      SymbolKind = "type"
	KindVariable  SymbolKind = "variable"
	KindMethod    SymbolKind = "method"
	KindProperty  SymbolKind = "property"
	KindImport    SymbolKind = "import"
	KindExport    SymbolKind = "export"
	KindEnum      SymbolKind = "enum"
	KindStruct    SymbolKind = "struct"
	KindTrait     SymbolKind = "trait"
	KindImpl      SymbolKind = "impl"
	KindMacro     SymbolKind = "macro"
	KindDecorator SymbolKind = "decorator"
	KindModule    SymbolKind = "module"
)

Symbol kind constants — string values must match the TS SymbolKindSchema in donmai-libraries/packages/code-intelligence/src/types.ts exactly.

type TypeScriptExtractor added in v0.23.0 

type TypeScriptExtractor struct{}

TypeScriptExtractor is a pure-regex symbol extractor for TypeScript and JavaScript source files. It is a faithful port of the TS TypeScriptExtractor class from donmai-libraries/packages/code-intelligence/src/parser/typescript-extractor.ts.

The extractor intentionally avoids tree-sitter or any CGo dependency; the same regex patterns are used on both sides to ensure byte-identical symbol output for a given source file.

func (*TypeScriptExtractor) Extract added in v0.23.0 

func (e *TypeScriptExtractor) Extract(source, filePath string) FileAST

Extract parses source (TypeScript or JavaScript) and returns a FileAST. filePath is used only to derive the language tag and to populate symbol.filePath — no file I/O is performed.

type ValidateCrossDepsOptions 

type ValidateCrossDepsOptions struct {
	Path string // Optional scoping path
}

ValidateCrossDepsOptions holds the flags for validate-cross-deps.

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.