Documentation
¶
Overview ¶
Package code mounts the Hanzo Cloud /v1/code/* surface: a native, per-org code-intelligence engine for AI coding agents and the hanzo.app UI. Retrieval is HYBRID — three orthogonal tiers fused with reciprocal-rank fusion, the SOTA lesson that embeddings alone under-serve code search:
- lexical (store.go/tokenize.go) — FTS5 trigram over code-tokenized text (camelCase/snake_case split, operators kept); substring + regex (Zoekt model).
- symbolic (parse.go) — go/parser for Go (real def/ref edges) and compact lexical extractors for TS/JS/Python/Rust/Solidity: go-to-symbol + a def→ref edge table.
- semantic (embed.go/search.go) — AST-boundary chunks embedded via the SAME gateway /embeddings clients/knowledge uses, ranked by cosine over a float32 vector table (the sqlite-vec `vec0` drop-in seam).
Storage is ONE SQLite file per org at {DataDir}/orgs/{slug}/code.db (HIP-0302): the org boundary is PHYSICAL — a query in one org's file can never reach another org's rows. Every request resolves its org through principal.Org (the ONE gate): no validated principal ⇒ 403, and a client X-Org-Id is never trusted.
Surface (all org-scoped; /v1 only):
GET /v1/code/search ?q=&type=text|regex|symbol|semantic|hybrid&repo=&limit=
POST /v1/code/context {query,budgetTokens,repo} → budget-packed context bundle
GET /v1/code/ask ?q=&repo= (or POST {query,repo}) → cited RAG answer
POST /v1/code/index {repo,files:[{path,content}],prune} → (re)index, incremental
Order 134: binds /v1/code/* before the AI subsystem's /v1/* catch-all (150).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type AskAnswer ¶
type AskAnswer struct {
Question string `json:"question"`
Answer string `json:"answer"`
Citations []Citation `json:"citations"`
Degraded bool `json:"degraded,omitempty"`
}
AskAnswer is the /ask result: the synthesized answer plus the exact spans it was grounded on. Degraded=true means retrieval succeeded but synthesis was unavailable — the caller still gets cited spans to reason over.
type Chunk ¶
type Chunk struct {
Path string
StartLine int
EndLine int
Symbol string
Kind string
Lang string
Text string
}
Chunk is an AST-boundary span (a function/class/type + its doc), the unit the semantic tier embeds — never a fixed window for parsed code.
type Citation ¶
type Citation struct {
Repo string `json:"repo,omitempty"`
File string `json:"file"`
Line int `json:"line"`
EndLine int `json:"endLine"`
Symbol string `json:"symbol,omitempty"`
}
Citation points an /ask answer back at exact code.
type ContextBundle ¶
type ContextBundle struct {
Query string `json:"query"`
Repo string `json:"repo,omitempty"`
BudgetTokens int `json:"budgetTokens"`
UsedTokens int `json:"usedTokens"`
Spans []Span `json:"spans"`
}
ContextBundle is the token-budgeted context for a coding agent's window: the most relevant spans plus the definitions they call and their key callers, packed greedily until the budget is spent. It is deliberately NOT whole files.
type Edge ¶
Edge is one reference: symbol Name is used at file:line inside From (the enclosing symbol / caller). It is the raw def→ref material; callersOf resolves a name to the enclosing symbols that reference it.
type Embedder ¶
type Embedder interface {
// Embed returns one vector per input, aligned by index, metered against the
// (org, project) billing scope. A disabled embedder returns (nil, nil) so
// indexing proceeds lexically + symbolically.
Embed(ctx context.Context, org, billingOrg, project string, texts []string) ([][]float32, error)
Enabled() bool
}
Embedder turns text into vectors for the semantic tier. It is an interface so the subsystem wires the real AI client while tests inject a deterministic offline embedder — the semantic tier is fully testable without a live model.
type File ¶
File is one file to index: its repo-relative path and content. The exported shape the git plane's push→index reactor hands in (it avoids importing the unexported fileInput).
type IndexResult ¶
type IndexResult struct {
Repo string
Indexed int
Skipped int
Pruned int
Symbols int
Chunks int
Vectors int
Semantic bool
}
IndexResult reports what an index pass wrote, for the reactor's log line.
func IndexFiles ¶
func IndexFiles(ctx context.Context, org, billingOrg, project, repo string, files []File) (IndexResult, error)
IndexFiles indexes a repo's files into the org's code index — the package-level seam the git plane's lifecycle reactor calls on push (clients/git owns the repo bytes; clients/code owns the index; neither imports the other, so the reactor reads the tree and hands it here). It reuses the exact per-file pipeline the POST /v1/code/index handler runs, with prune=true so a push is a full-tree reconcile (deleted files leave the index). A nil/unmounted service is a no-op — the reactor is best-effort and must never block the push/deploy path. Over-limit inputs are bounded, not rejected: indexing is a background enrichment, so a huge push indexes what fits rather than failing the whole repo.
type Parsed ¶
Parsed is the extracted index material for one file.
type Span ¶
type Span struct {
Repo string `json:"repo"`
File string `json:"file"`
Line int `json:"line"`
EndLine int `json:"endLine"`
Kind string `json:"kind,omitempty"`
Symbol string `json:"symbol,omitempty"`
Snippet string `json:"snippet"`
Score float64 `json:"score"`
Tier string `json:"tier,omitempty"`
Role string `json:"role,omitempty"` // context: match | definition | caller
}
Span is one ranked result — the unit both /search and /context return. For search, Snippet is a bounded excerpt; for context, it is the full AST chunk the agent pastes into its window.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is one org's code index over a single SQLite file ({DataDir}/orgs/{slug}/code.db). Because every org gets its OWN file, the org boundary is PHYSICAL — a query in one org's store can never reach another org's rows. Within the file rows are scoped by repo. MaxOpenConns(1) serializes writes against the file lock (the prompts/eval/projects discipline).
type Symbol ¶
type Symbol struct {
Repo string `json:"repo,omitempty"`
Path string `json:"file"`
Name string `json:"name"`
Kind string `json:"kind"`
Line int `json:"line"`
EndLine int `json:"endLine"`
Signature string `json:"signature,omitempty"`
Scope string `json:"scope,omitempty"`
Lang string `json:"lang,omitempty"`
}
Symbol is one definition: a name of a given kind at file:line, with its verbatim signature and enclosing scope (a method's receiver/class). On a read it also carries Repo/Path from the store; the parser leaves those empty and the store stamps them on write.
type Synthesizer ¶
type Synthesizer interface {
Synthesize(ctx context.Context, org, billingOrg, project, prompt string) (string, error)
Enabled() bool
}
Synthesizer turns a retrieval-grounded prompt into a cited answer. It wraps the existing in-process chat path (deps.AI) behind an interface so /ask is testable without a live model.
Source Files