Core concepts

A short vocabulary lesson. Everything else in these docs builds on the six ideas on this page.

The architecture model

ovecc index turns a repository into a graph of facts:

Fact	What it is	Example
File	An indexed source file	src/core/db.ts
Module	A group of files, inferred from directory structure	core, services, routes
Dependency	A resolved import edge between files/modules	routes → services
Symbol	A top-level function, class, type, …	chargeCustomer
Call	A resolved call-graph edge	invoiceSummary → query
API	An exposed HTTP route or RPC handler	GET /users/:id
Table	A database schema object referenced by code	table:invoices
Finding	A rule violation with evidence	Unused export: formatEuros

All of it is persisted locally in .ovecc/graph.db. Every other command is a read over this model — which is why they are fast and why they answer identically until you re-index.

Snapshots

Each ovecc index run writes a snapshot: the full state of the model at that moment, tagged with the current commit. Snapshots are what make change-scoped analysis possible:

• review / gate / diff compare two snapshots (previous and latest by default; you can pass explicit snapshot ids or Git refs).
• drift and history trend metrics across snapshots.

A typical loop: index the base branch, make a change, index again, then review.

tip

Commands that need a base (review, gate, diff, drift) require at least two snapshots. If you see could not resolve base snapshot 'previous', index once more.

Targets

Commands like impact, explain, advise, and export context take a target, which can be:

Form	Matches	Example
module name	an inferred module	ovecc impact services
file path	one source file	ovecc explain src/core/db.ts
symbol name	a top-level symbol	ovecc impact chargeCustomer
table:NAME	a database table	ovecc query "rdeps table:products"
api: + label or substring	an HTTP route (labels look like GET /users/:id)	ovecc impact "api:/search" or ovecc impact "api:GET /search"

A target that matches nothing is reported explicitly (No matching architecture element), so a typo never masquerades as an empty result.

Findings and rules

A finding is one concrete problem: a rule name (like security/secret or unused-export), a severity, a human title, and one or more pieces of evidence — file:line, plus a detail such as the offending import specifier. Findings are recorded at index time and surfaced by violations (all of them), or by focused views (security, deadcode, health). Many findings carry a machine-readable fix action; the mechanical ones are auto-fixable via ovecc fix.

The full rule catalog with severities is in the rules reference.

Severities

Four levels, used consistently everywhere:

Severity	Meaning
critical	Act now — e.g. a hardcoded live credential, tainted input reaching eval
high	Serious defect — new dependency cycle, boundary violation, vulnerable dependency
medium	Should fix — weak crypto, permissive CORS, phantom dependency
low	Hygiene — unused exports/files, oversized units

--severity <level> filters output; --fail-on medium|high|any turns findings into a CI exit code (see exit codes).

Determinism

ovecc's core promise: the same input produces the same output.

• Output is path-normalized (repo-relative, POSIX separators) and byte-identical across runs for an unchanged database — safe to diff, cache, and snapshot-test.
• Findings are traceable to explicit facts. Nothing is inferred by a model; no network, no LLM. (explain generates prose, but every sentence is backed by a fact from the context slice.)
• Taint findings are honest about being a reachability over-approximation and say so in their description.

The .ovecc/ directory

Path	What it is
.ovecc/config.toml	Your configuration and governance rules — commit this
.ovecc/graph.db	The architecture database (all snapshots) — git-ignored
.ovecc/baseline.json	Accepted findings, written by violations --write-baseline
.ovecc/osv/	Cached vulnerability advisories from audit --fetch

ovecc init git-ignores .ovecc/ for you; the convention is to commit only config.toml. To do that, change the ignore entry to .ovecc/* and add !.ovecc/config.toml below it (Git cannot re-include a file under a fully ignored directory) — see configuration.