codeintel

package
v0.36.0 Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package codeintel — native arch-intel diff/gate layer.

This file ports the pure-regex/JSON layers of the TS @donmai/architectural-intelligence package to Go:

  • ReadDiffObservations — file-path zone inference, convention detection, decision inference, acceptance-criteria inference (all pure regex).
  • EvaluateGate — DriftGatePolicy evaluation.
  • BuildNativeDriftReport — assemble a DriftReport from the above outputs.

These functions cover the "cheap" subset of arch-intel that requires NO external binary, NO LLM, and NO database. They run as the primary path of `donmai arch assess` when DONMAI_ARCH_BIN is not set.

The full pipeline (SQLite graph + LLM deviation-detection prompt) is deferred to a followup; see runs/2026-06-05-tui-readiness/research/18-arch-intel-assessment.md.

Package codeintel provides code intelligence for the donmai CLI.

Native implementation (S0–S3)

All six code-intel subcommands are now implemented natively in Go:

  • get-repo-map (S0/S1): TypeScript/JS + Go + Python + Rust regex extractors
  • search-symbols (S1): BM25-style symbol name search
  • search-code (S2): Okapi BM25 full-text search over symbol corpus
  • check-duplicate (S3): xxHash64 exact + SimHash near-dup detection
  • find-type-usages (S3): regex scan for type reference sites
  • validate-cross-deps (S3): cross-package import validator

The native path is the PRIMARY implementation for all subcommands. The exec-shim (DONMAI_CODE_BIN env override) is kept as a FALLBACK for operators who need to force the TypeScript implementation.

Exec-shim fallback

When DONMAI_CODE_BIN is set 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

View Source 
const (
	SeverityCritical = "critical"
	SeverityWarning  = "warning"
	SeverityInfo     = "info"
)

Deviation severities.

View Source 
const (
	// SimHashBits is the fingerprint width.
	SimHashBits = 64
	// SimHashDefaultThreshold is the default Hamming-distance threshold for
	// near-duplicate detection. Matches the TS default.
	SimHashDefaultThreshold = 3
)

Variables

View Source 
var DriftVerdictSchema = json.RawMessage(`{
  "type": "object",
  "properties": {
    "deviations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "observation": {"type": "string"},
          "severity": {"type": "string", "enum": ["critical", "warning", "info"]},
          "rationale": {"type": "string"},
          "citation": {"type": "string"}
        },
        "required": ["observation", "severity", "rationale"]
      }
    }
  },
  "required": ["deviations"]
}`)

DriftVerdictSchema is the JSON Schema the model's deviation output must match. Passed as OneShotRequest.ResponseSchema so native harnesses constrain output server-side and soft harnesses get it as a prompt instruction + post-validation.

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 by resolveArchBin when the donmai-arch binary cannot be found. Note: ArchAssess does NOT surface this sentinel to callers — it falls back to the native diff/gate path instead. IsArchBinAvailable uses it to decide whether to show the informational notice.

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.

func EvaluateGate added in v0.26.0 

func EvaluateGate(observations []DiffObservation, policy string) bool

EvaluateGate evaluates whether a set of observations triggers the drift gate.

In the native path, observations are diff-level signals rather than LLM-derived Deviation nodes with explicit severity. The gate is evaluated on observation confidence:

  • "none" → never gate
  • "no-severity-high" → gate when any observation has confidence >= 0.65 (maps to inferred-high threshold — no LLM severity available)
  • "zero-deviations" → gate when there are any observations
  • "max:N" → gate when observation count > N

The TS `assessChange()` path evaluates against Deviation.severity instead; this is only the no-LLM fallback.

func MerkleIdentical added in v0.26.0 

func MerkleIdentical(oldTree, newTree *MerkleTree) bool

MerkleIdentical returns true when both trees share the same root hash.

func RecomputeRootHash added in v0.26.0 

func RecomputeRootHash(files map[string]FileIndex) string

RecomputeRootHash builds a Merkle tree from the current index and returns the new root hash. This replaces the simpler XOR-fold approach used in S0/S1 with the proper tree-based hash that matches the TS implementation.

After calling this, update idx.RootHash with the returned value before saving.

func SimHashCompute added in v0.26.0 

func SimHashCompute(text string) uint64

SimHashCompute returns the 64-bit SimHash fingerprint for text. Matches the TS SimHash.compute method.

func SimHashHammingDistance added in v0.26.0 

func SimHashHammingDistance(a, b uint64) int

SimHashHammingDistance returns the number of differing bits between a and b.

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 AssessChangeRequest added in v0.36.0 

type AssessChangeRequest struct {
	Change       string            // e.g. "owner/repo#123" — context only
	Observations []DiffObservation // the signals to assess (from ReadDiffObservations)
	Conventions  []string          // established conventions/decisions (optional context)
}

AssessChangeRequest is the input to a drift assessment: the diff-level observations to judge plus the conventions/decisions context to judge them against, and a human reference for the change (for the prompt).

type Assessment added in v0.36.0 

type Assessment struct {
	Deviations       []Deviation
	HasCriticalDrift bool
	SchemaOK         bool
}

Assessment is the result of a drift assessment. SchemaOK reports whether the model produced output matching DriftVerdictSchema; when false the caller gets an empty (HasCriticalDrift=false) Assessment and decides whether to retry, fall back to the native gate, or drop — the same validate-repair-drop posture the one-shot lane and the KG path use.

type ChangeRefJSON added in v0.26.0 

type ChangeRefJSON struct {
	Repository  string `json:"repository"`
	Kind        string `json:"kind"`
	PrNumber    int    `json:"prNumber,omitempty"`
	Description string `json:"description,omitempty"`
}

ChangeRefJSON mirrors the TS ChangeRef shape for JSON output compatibility.

type ChangeSet added in v0.26.0 

type ChangeSet struct {
	Added    []string
	Modified []string
	Deleted  []string
}

ChangeSet holds the files that differ between two Merkle trees.

func MerkleDiff added in v0.26.0 

func MerkleDiff(oldTree, newTree *MerkleTree) ChangeSet

MerkleDiff compares old and new trees, returning the file-level ChangeSet. Matches the TS ChangeDetector.detect method.

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 CrossDepViolation added in v0.26.0 

type CrossDepViolation struct {
	ImportingFile   string `json:"importingFile"`
	ImportedPackage string `json:"importedPackage"`
	PackageJSONPath string `json:"packageJsonPath"`
	Line            int    `json:"line"`
}

CrossDepViolation is a single missing cross-package dependency declaration.

type CrossDepsResult added in v0.26.0 

type CrossDepsResult struct {
	Valid           bool                `json:"valid"`
	MissingDeps     []CrossDepViolation `json:"missingDeps"`
	PackagesChecked int                 `json:"packagesChecked"`
	FilesChecked    int                 `json:"filesChecked"`
}

CrossDepsResult is the output of ValidateCrossDeps.

func ValidateCrossDeps added in v0.26.0 

func ValidateCrossDeps(cwd, targetPath string) (CrossDepsResult, error)

ValidateCrossDeps checks that cross-package imports in a monorepo have corresponding package.json dependency declarations. targetPath optionally scopes the check to a specific directory prefix.

type Deviation added in v0.36.0 

type Deviation struct {
	Observation string `json:"observation"` // which observation drifted
	Severity    string `json:"severity"`    // critical | warning | info
	Rationale   string `json:"rationale"`   // why it is a deviation
	Citation    string `json:"citation,omitempty"`
}

Deviation is one architectural drift the model flagged: an observation that conflicts with an established convention/decision. JSON field names match the DriftVerdictSchema and are kept compatible with the TS Deviation shape.

type DiffObservation added in v0.26.0 

type DiffObservation struct {
	// Kind is one of "pattern", "convention", "decision".
	Kind string `json:"kind"`

	// Payload carries the structured data for the observation.
	Payload map[string]any `json:"payload"`

	// Confidence is a 0–1 signal strength score.
	Confidence float64 `json:"confidence"`

	// Scope is the architectural scope (always "project" for native path).
	Scope string `json:"scope"`
}

DiffObservation is a single architectural signal extracted from a PR diff. The JSON field names are byte-compatible with the TS ArchObservation shape so downstream tools (platform, smokes) see identical JSON regardless of which implementation produced it.

func ReadDiffObservations added in v0.26.0 

func ReadDiffObservations(diff PrDiff, scope string) []DiffObservation

ReadDiffObservations extracts ArchObservation candidates from a PR diff. All extraction is pure regex — no external binary, LLM, or DB is required.

Four signal classes are emitted (matching the TS diff-reader.ts behaviour):

  1. File-path zone patterns → "pattern" observations
  2. Convention signals from diff patches → "convention" observations
  3. Decision inference from PR title/body → "decision" observations
  4. Acceptance-criteria items → "pattern" / "convention" observations

type DupEntry added in v0.26.0 

type DupEntry struct {
	ID      string
	XXHash  string // hex, 16 chars
	SimHash uint64
}

DupEntry stores the hashes for a single indexed content item.

type DupResult added in v0.26.0 

type DupResult struct {
	IsDuplicate     bool   `json:"isDuplicate"`
	MatchType       string `json:"matchType"`       // "exact", "near", "none"
	ExistingID      string `json:"existingId"`      // set when IsDuplicate=true
	HammingDistance int    `json:"hammingDistance"` // set when MatchType=="near"
}

DupResult is the result of a CheckDuplicate call.

func CheckDuplicateContent added in v0.26.0 

func CheckDuplicateContent(content string, index []FileIndex, threshold int) DupResult

CheckDuplicateContent performs a stateless duplicate check against an existing index using xxHash64 + SimHash. It operates on individual file content items without a persistent store.

Parameters:

  • content is the content to check.
  • index is the list of FileIndex entries (from the persisted index.json) representing the corpus to search.
  • threshold is the SimHash Hamming-distance threshold.

type DupStore added in v0.26.0 

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

DupStore is an in-memory content deduplication store. Not safe for concurrent use; callers must synchronize externally if needed.

func (*DupStore) CheckDuplicate added in v0.26.0 

func (d *DupStore) CheckDuplicate(content string, threshold int) DupResult

CheckDuplicate checks content against the store for exact and near duplicates. Returns a DupResult. Does NOT store the content — call Store to add it.

func (*DupStore) Store added in v0.26.0 

func (d *DupStore) Store(id, content string)

Store adds content to the store.

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 LaneAdapter added in v0.36.0 

type LaneAdapter struct {
	// Harness is the resolved agent harness the assessment runs on.
	Harness agent.HarnessProvider
	// Model is the optional model id; empty falls back to the harness default.
	Model string
}

LaneAdapter is the production ModelAdapter: it runs the deviation-detection prompt through the OSS one-shot lane (agent.Complete) with DriftVerdictSchema. Under a host-session/subscription cell this is a ≈$0 soft-JSON SpawnComplete; under a keyed native cell it is strict structured — the cell, not this adapter, decides (the whole point of routing through the lane).

func (LaneAdapter) AssessChange added in v0.36.0 

func (a LaneAdapter) AssessChange(ctx context.Context, req AssessChangeRequest) (Assessment, error)

AssessChange runs the deviation-detection prompt through the one-shot lane and returns the structured Assessment. A nil Harness is a programming error. A transport/provider error is returned; a successful-but-unparseable model response is NOT an error — it yields SchemaOK=false with no deviations (the caller decides how to handle the soft miss).

type MerkleTree added in v0.26.0 

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

MerkleTree builds and diffs a content-addressed tree over a file set.

func MerkleTreeFromHashes added in v0.26.0 

func MerkleTreeFromHashes(fileHashes map[string]string) *MerkleTree

MerkleTreeFromHashes builds a MerkleTree from a path → gitHash map.

func MerkleTreeFromIndex added in v0.26.0 

func MerkleTreeFromIndex(idx IndexFile) *MerkleTree

MerkleTreeFromIndex builds a MerkleTree from an IndexFile's gitHash entries.

func NewMerkleTree added in v0.26.0 

func NewMerkleTree() *MerkleTree

NewMerkleTree returns an empty MerkleTree.

func (*MerkleTree) Files added in v0.26.0 

func (t *MerkleTree) Files() map[string]string

Files returns a map of file path → file hash for all leaf nodes.

func (*MerkleTree) RootHash added in v0.26.0 

func (t *MerkleTree) RootHash() string

RootHash returns the root hash of the tree.

type ModelAdapter added in v0.36.0 

type ModelAdapter interface {
	AssessChange(ctx context.Context, req AssessChangeRequest) (Assessment, error)
}

ModelAdapter is the arch-intel drift LLM seam. The full pipeline port consumes THIS — never a direct provider SDK (see THE MANDATE above).

type NativeDriftReport added in v0.26.0 

type NativeDriftReport struct {
	// Change is the assessed VCS change.
	Change ChangeRefJSON `json:"change"`

	// Observations are the raw diff-level signals (no LLM required).
	// This field is a donmai-native extension; the TS DriftReport omits it.
	Observations []DiffObservation `json:"observations"`

	// Deviations is always empty in the native path (LLM not run).
	Deviations []any `json:"deviations"`

	// Reinforced is always empty in the native path.
	Reinforced []any `json:"reinforced"`

	// HasCriticalDrift is always false in the native path.
	HasCriticalDrift bool `json:"hasCriticalDrift"`

	// Gated reflects the gate policy evaluation against the observation list.
	// In the native path, gate evaluation uses observation confidence thresholds
	// rather than LLM-produced severity levels.
	Gated bool `json:"gated"`

	// Summary is a human-readable description of the result.
	Summary string `json:"summary"`

	// AssessedAt is the RFC3339 assessment timestamp.
	AssessedAt string `json:"assessedAt"`

	// Mode is "native-diff-only" for this implementation path, distinguishing
	// it from a full LLM-backed assessment.
	Mode string `json:"mode"`
}

NativeDriftReport is the JSON-serialisable result of BuildNativeDriftReport. The top-level fields are byte-compatible with the TS DriftReport shape.

func BuildNativeDriftReport added in v0.26.0 

func BuildNativeDriftReport(
	diff PrDiff,
	observations []DiffObservation,
	gatePolicy string,
) NativeDriftReport

BuildNativeDriftReport assembles a NativeDriftReport from diff observations and a gate policy. This is the primary output of `donmai arch assess` when DONMAI_ARCH_BIN is not set and ANTHROPIC_API_KEY is absent.

type NativeRunner added in v0.23.0 

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

NativeRunner provides the S0–S3 code intelligence suite 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
  • SearchCode — BM25 full-text search over the symbol corpus (S2)
  • CheckDuplicate — xxHash64 exact + SimHash near-dup detection (S3)
  • FindTypeUsages — regex scan for type reference sites (S3)
  • ValidateCrossDeps — cross-package import validator (S3)

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) CheckDuplicateNative added in v0.26.0 

func (n *NativeRunner) CheckDuplicateNative(opts CheckDuplicateOptions) (any, error)

CheckDuplicateNative checks content for exact or near-duplicate matches in the current index using xxHash64 (Tier 1) and SimHash (Tier 2).

The threshold defaults to SimHashDefaultThreshold (3), matching the TS DedupPipeline default.

func (*NativeRunner) FindTypeUsagesNative added in v0.26.0 

func (n *NativeRunner) FindTypeUsagesNative(opts FindTypeUsagesOptions) (any, error)

FindTypeUsagesNative finds all usage sites for a named type in the repository. Delegates to the FindTypeUsages function (type_usages.go).

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) SearchCodeNative added in v0.26.0 

func (n *NativeRunner) SearchCodeNative(opts SearchCodeOptions) (any, error)

SearchCodeNative performs full-text BM25 search over the code symbol corpus.

The implementation builds (or loads) the code index, collects all symbols into a BM25 inverted index, scores them against the query, and applies an optional language filter and max-results cap.

This matches the TS SearchEngine.search + BM25 pipeline:

  • Tokenizer: code-aware camelCase / snake_case expansion (bm25.go:tokenize)
  • Scoring: Okapi BM25 (k1=1.5, b=0.75)
  • Post-processing: exact-name match × 3.0, partial-name match × 1.5
  • Returns: []map[string]any with "symbol", "score", "matchType" keys

Intentional deviation from TS: the TS SearchEngine holds an in-process symbol set that is rebuilt on indexer flush; the Go implementation rebuilds on every call from the persisted index.json. This is acceptable because the index is persisted to disk and re-read only on content change (incremental).

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.

func (*NativeRunner) ValidateCrossDepsNative added in v0.26.0 

func (n *NativeRunner) ValidateCrossDepsNative(opts ValidateCrossDepsOptions) (any, error)

ValidateCrossDepsNative validates cross-package imports in the monorepo. Delegates to ValidateCrossDeps (crossdeps.go).

type PrDiff added in v0.26.0 

type PrDiff struct {
	// Repository identifier, e.g. "github.com/org/repo"
	Repository string

	// PrNumber is the pull request number in the source VCS.
	PrNumber int

	// Title is the PR title.
	Title string

	// Body is the PR description / body text.
	Body string

	// Files is the list of changed files.
	Files []PrFileDiff

	// AcceptanceCriteria is an optional pre-parsed list of AC items.
	AcceptanceCriteria []string
}

PrDiff is the provider-orthogonal input to ReadDiffObservations. Callers populate this from their VCS provider (or test fixtures).

type PrFileDiff added in v0.26.0 

type PrFileDiff struct {
	// Path is the relative file path.
	Path string

	// Patch is the unified diff text (the +/− lines).
	Patch string

	// Added is true when the file was newly created.
	Added bool
}

PrFileDiff describes one file in a PR.

type PythonExtractor added in v0.26.0 

type PythonExtractor struct{}

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

func (*PythonExtractor) Extract added in v0.26.0 

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

Extract parses Python source and returns a FileAST.

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`.

Resolution order:

  1. DONMAI_ARCH_BIN (or legacy AGENTFACTORY_ARCH_BIN) — exec-shim override. Gives byte-identical output to the TS pipeline including LLM drift detection and the SQLite observation graph.
  2. donmai-arch on PATH (installed via `npm install -g @donmai/cli`).
  3. pnpm donmai-arch (monorepo dev).
  4. Native Go fallback — pure-regex diff/gate analysis via ReadDiffObservations + BuildNativeDriftReport. No external binary required. Output is tagged with "mode": "native-diff-only"; set DONMAI_ARCH_BIN for full LLM assessment.

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 detects exact and near-duplicate content against the index.

When DONMAI_CODE_BIN is set the exec-shim is used. Otherwise the native xxHash64 + SimHash implementation (S3) is used.

func (*Runner) FindTypeUsages 

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

FindTypeUsages finds all switch/case, mapping objects, and usage sites for a type.

When DONMAI_CODE_BIN is set the exec-shim is used. Otherwise the native regex-scan implementation (S3) is used.

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. The native diff/gate implementation is always available (no external binary required). When DONMAI_ARCH_BIN or donmai-arch on PATH is present, the full LLM-backed pipeline is used instead; the native path is the fallback. Callers should no longer gate on this method.

func (*Runner) IsArchBinAvailable added in v0.26.0 

func (r *Runner) IsArchBinAvailable() bool

IsArchBinAvailable returns true if a donmai-arch binary can be found on PATH or via DONMAI_ARCH_BIN. Used by arch.go to decide whether to show an informational notice about native-diff-only mode.

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 performs BM25 full-text code search.

When DONMAI_CODE_BIN is set the exec-shim is used. Otherwise the native Go BM25 implementation (S2) is used — no external binary required.

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 checks cross-package imports have package.json declarations.

When DONMAI_CODE_BIN is set the exec-shim is used. Otherwise the native implementation (S3) is used.

type RustExtractor added in v0.26.0 

type RustExtractor struct{}

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

func (*RustExtractor) Extract added in v0.26.0 

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

Extract parses Rust source and returns a FileAST.

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 TypeUsage added in v0.26.0 

type TypeUsage struct {
	FilePath string        `json:"filePath"`
	Line     int           `json:"line"`
	Context  string        `json:"context"`
	Kind     TypeUsageKind `json:"kind"`
}

TypeUsage represents a single usage site of a type.

type TypeUsageKind added in v0.26.0 

type TypeUsageKind string

TypeUsageKind classifies how a type is used in a file. 

const (
	UsageKindSwitchCase      TypeUsageKind = "switch_case"
	UsageKindMappingObject   TypeUsageKind = "mapping_object"
	UsageKindImport          TypeUsageKind = "import"
	UsageKindTypeReference   TypeUsageKind = "type_reference"
	UsageKindExhaustiveCheck TypeUsageKind = "exhaustive_check"
)

Usage-kind constants ordered by reporting priority (lowest = highest priority).

type TypeUsagesResult added in v0.26.0 

type TypeUsagesResult struct {
	TypeName         string      `json:"typeName"`
	TotalUsages      int         `json:"totalUsages"`
	Usages           []TypeUsage `json:"usages"`
	SwitchStatements int         `json:"switchStatements"`
	MappingObjects   int         `json:"mappingObjects"`
}

TypeUsagesResult is the output of FindTypeUsages.

func FindTypeUsages added in v0.26.0 

func FindTypeUsages(cwd, typeName string, maxResults int) (TypeUsagesResult, error)

FindTypeUsages searches the file tree under cwd for usages of typeName. Matches the TS findTypeUsagesInProcess function.

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.