codeintel

Documentation

Overview

Package codeintel provides a shell-out bridge to the TypeScript @donmai/cli (donmai-code).

Architectural choice: shell-out bridge (Phase D parity)

The tree-sitter Go bindings (go-tree-sitter) were evaluated but rejected for this phase because:

1. CGo + native deps make CI slower and cross-compilation fragile.
2. The AC requires byte-identical index format with TS readers — easiest to guarantee when TS owns the indexing entirely.
3. Phase D goal is parity, not re-implementation.

This package shells out to `pnpm donmai-code` (resolving via PATH or DONMAI_CODE_BIN env var) and returns the parsed JSON output.

A future issue (post-Wave 4) can replace the shell-out with native Go tree-sitter after parity is verified end-to-end.

Binary resolution (PATH portability)

The binary is resolved in this order:

1. DONMAI_CODE_BIN env var (legacy: AGENTFACTORY_CODE_BIN) — explicit override for non-monorepo users
2. `donmai-code` on PATH (installed via `npm install -g @donmai/cli`)
3. `pnpm donmai-code` via pnpm run in the current working directory (monorepo dev)

If none of those resolve, every command returns an ErrNotAvailable error with clear installation instructions. The caller surfaces this gracefully rather than crashing.

Index

• Variables
• type ArchAssessOptions
• type CheckDuplicateOptions
• type FindTypeUsagesOptions
• type GetRepoMapOptions
• type Runner
  • func New(cwd string) *Runner
  • func (r *Runner) ArchAssess(opts ArchAssessOptions) (any, error)
  • func (r *Runner) CheckDuplicate(opts CheckDuplicateOptions) (any, error)
  • func (r *Runner) FindTypeUsages(opts FindTypeUsagesOptions) (any, error)
  • func (r *Runner) GetRepoMap(opts GetRepoMapOptions) (any, error)
  • func (r *Runner) IsArchAvailable() bool
  • func (r *Runner) IsCodeAvailable() bool
  • func (r *Runner) SearchCode(opts SearchCodeOptions) (any, error)
  • func (r *Runner) SearchSymbols(opts SearchSymbolsOptions) (any, error)
  • func (r *Runner) ValidateCrossDeps(opts ValidateCrossDepsOptions) (any, error)
• type SearchCodeOptions
• type SearchSymbolsOptions
• type ValidateCrossDepsOptions

Variables

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.

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.

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 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 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 runs `donmai-code get-repo-map`.

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 if the donmai-code binary can be found.

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 runs `donmai-code search-symbols <query>`.

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 ValidateCrossDepsOptions

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

ValidateCrossDepsOptions holds the flags for validate-cross-deps.