Ovecc README

CLI-first architecture intelligence: understand your codebase, then hold it to the rules you set.

Rust, one binary, no runtime. Runs offline, with no LLM in the loop.

What is Ovecc

Ovecc reads your repository once and builds a persistent model of it: every file, import, symbol, and call. From that single index it answers the questions you ask about a codebase:

• What breaks if I change this? (impact)
• Where are the dependency cycles and the tight coupling? (query, summary)
• What is duplicated, dead, or over-complex? (dupes, deadcode, health)
• What is insecure, and which dependencies have known CVEs? (security, audit)
• Where is the churn, and who owns this code? (hotspots)

It is an architecture database with deterministic commands, driven from the CLI, from CI, or by a coding agent over MCP.

React's dependency graph, rendered by ovecc export graph --html into a single file you can open directly, no server or CDN needed.

What it costs an agent

Asking whether a new import closes a dependency cycle, on zod, with Claude Sonnet 4.6:

One run, one model, one question, and agent runs are not deterministic. Method and the cases where ovecc loses are in docs/benchmark/BENCHMARKS.md.

Write your architecture down, and hold the code to it

Most tools stop at reading the code. Ovecc goes one step further: you write down which parts of your codebase are allowed to depend on which, in one small file, and every build checks the real code against it.

Here's one for a small app:

# .ovecc/architecture.toml
[[component]]
name = "api"
paths = ["src/api/**"]
depends_on = ["core"]              # the api may use core, nothing else

[[component]]
name = "features"
paths = ["src/features/**"]
depends_on = ["core"]
slices = true                      # and features may not import each other

[[component]]
name = "core"
paths = ["src/core/**"]
deny_capabilities = ["network"]    # pure domain: no fetch, no I/O
max_cyclomatic = 8                 # keep core functions simple

Run the check and every breach comes back with a file and a line:

$ ovecc architecture check

Divergences (1):
  [High] api -> features is not in the contract
    src/api/routes.ts:2 (../features/billing/service)

Slice isolation breaches (1):
  [High] features/billing -> features/users breaks slice isolation
    src/features/billing/service.ts:1 (../users/repo)

Denied capabilities used (1):
  [Medium] core uses denied capability 'network'
    src/core/pricing.ts:3 (fetch)

Complexity budgets exceeded (1):
  [Medium] core: 1 function over the cyclomatic budget
    src/core/pricing.ts:8 (cyclomatic 11 > 8)

Four kinds of decay caught in one run: a layer reaching where it shouldn't, a feature tangling into its neighbor, a network call inside code you promised was pure, and a function creeping past the budget you set. Put ovecc architecture check in CI and the pull request fails on the drift, instead of a reviewer noticing three months later, or nobody noticing at all.

Don't have one yet? ovecc architecture suggest recognizes the architecture you already follow (Feature-Sliced, bulletproof-react, Clean/Hexagonal, an Nx workspace) and writes the file bound to your real folders. Or ovecc architecture init drafts it from your actual import graph, so day one starts green and you tighten from there. The details are in the contract reference below.

Install

npx ovecc index .

npm pulls only the binary for your platform. npm i -g ovecc keeps it on your PATH.

Prebuilt binaries are also on the latest release: Linux x86_64 and aarch64, Windows x86_64, macOS arm64. There is nothing else to install: DuckDB is bundled, there is no runtime, and it works fully offline. A rolling dev build ships on every push to main.

The macOS binary is unsigned, so Gatekeeper quarantines it when a browser downloads it. Clear the flag once and it runs:

xattr -d com.apple.quarantine ./ovecc-macos-aarch64

curl and npm don't set that flag, so npx ovecc never runs into it.

Build from source

Builds with stable Rust (on Windows use the windows-gnu toolchain; DuckDB is compiled from source on the first build). The step-by-step Windows setup is in docs/dev/SETUP.md.

cargo build --release
cargo test --workspace

The binary is ovecc (crates/ovecc-cli).

Quick start

ovecc index .                 # parse, resolve, and persist the model into .ovecc/
ovecc summary                 # coupling, density, cycles, risk score
ovecc advise src/server.ts    # the agent-facing surface: findings for one file, each with a fix
ovecc diagnose                # named architectural smells, evidence + curated remediation
ovecc history max_cyclomatic  # trend one metric across every index run — is it getting better?
ovecc violations              # architecture + security findings, with file:line
ovecc violations --write-baseline   # accept today's backlog; later runs surface only what is new
ovecc metrics                 # per-component fan-in/out, instability, abstractness, distance
ovecc components              # the components the graph recovers, and what they hold
ovecc coupling                # files that change together but do not import each other
ovecc security                # secrets, insecure patterns, weak crypto, tainted flows
ovecc audit                   # offline OSV dependency vulnerabilities
ovecc impact Billing          # blast radius of a change
ovecc hotspots                # churn x coupling x ownership debt ranking
ovecc dupes                   # duplicated code (clone families), with file:line
ovecc health                  # functions over the complexity thresholds (oxc)
ovecc deadcode                # unused exports + unreachable files (oxc + reachability)
ovecc fix                     # apply the mechanical fixes for those findings (dry-run by default)
ovecc query "cycles"          # real elementary dependency cycles (A -> B -> A)
ovecc report                  # one-shot architecture report (markdown or json)
ovecc gate                    # CI gate: fail a PR on new cycles / violations
ovecc review                  # the named new defects a change introduced (file:line + cycle witnesses)
ovecc architecture init       # draft .ovecc/architecture.toml from the graph, or a --template
ovecc architecture check      # gate the code against the contract, with file:line
ovecc architecture suggest    # recognize which architecture the repo already follows
ovecc export graph --html     # interactive dependency-graph viewer, one self-contained offline file
ovecc capabilities            # machine-readable contract: commands, metrics, rules, exit codes
ovecc mcp                     # MCP server over stdio: expose every command as an agent tool

If you only ever run three of these, run advise before editing a file, diagnose instead of violations (same findings, plus the fix and when not to act), and history to see whether the codebase is improving. summary prints these as a footer, because a list read once loses to output read every run.

Every command renders as text, json, ndjson, or markdown via --format (plus sarif for GitHub code scanning and codeclimate for GitLab Code Quality) and returns stable exit codes for CI. The full per-command reference, with real output, is in docs/COMMANDS.md. For pull requests, the repo ships a drop-in GitHub Action that indexes base and head, comments the review findings on the PR, and gates on severity.

The architecture contract in depth

.ovecc/architecture.toml is your intended architecture as code. Each component claims files by path glob; depends_on is the allow-list of what it may import. ovecc architecture init writes the first draft from the graph you already have, so every entry mirrors a real import and day one has zero violations. Prefer a known shape? init --template fsd (or bulletproof-react, nx-workspace, clean-architecture) drops in a reference architecture, and the diff against your code becomes your migration plan.

From then on, each run compares code to contract and names what it finds:

• a divergence is an import the contract does not allow,
• a bypass is an import that skips a component's declared public interface,
• an absence is a dependency you declared but never actually use.

Three more checks read past the import graph (JS/TS):

• slices = true isolates a component's sub-folders from each other, the rule behind Feature-Sliced Design and bulletproof-react, with FSD's @x public-API escape hatch honored.
• deny_capabilities forbids a component the ambient powers that break purity: network, filesystem, storage, dom, process, time, random. A Date.now() in a pure domain comes back with its file and line.
• max_cyclomatic / max_cognitive put a per-function complexity budget in the contract, so "keep the core simple" becomes a rule the build can check.

Interfaces are virtual: you list a component's public entry files and ovecc enforces them on the real imports, so you get encapsulation without barrel files or an extra re-export layer.

Adoption is meant to be gradual. check --freeze records today's violations in a per-component baseline (one line each, so branches merge cleanly), gates only new ones from then on, and drops entries as you fix them so the count never climbs. Agents can read the contract before editing, through ovecc architecture show <path> or the ovecc_architecture MCP tool.

Rules

Simpler, language-neutral policy lives in .ovecc/config.toml, is enforced at index time, and shows up in violations (and the gate CI check):

# Forbid a module-to-module dependency.
[[rules.boundaries]]
name = "billing must not depend on user"
source = "billing"
target = "user"
allowed = false
severity = "high"

# Ban imports by specifier pattern (exact, prefix*, *suffix, or *infix*).
[[rules.banned_imports]]
name = "no-deprecated-lodash"
pattern = "lodash"
message = "use es-toolkit instead"
severity = "medium"

Silence a single finding inline with // ovecc-ignore (or // ovecc-ignore-next-line, and # ovecc-ignore in Python) on the offending line; it is dropped at index time.

For CI and coding agents

Every command is built to run in a pipeline: pick a format with --format, rely on stable exit codes (0 clean, 1 a --fail-on threshold crossed, 2 and up a real error), and emit sarif or codeclimate for GitHub and GitLab. The drop-in GitHub Action wires review into pull requests.

The same analysis is available to coding agents over the Model Context Protocol. ovecc mcp runs an MCP server over stdio that exposes each command as a tool (ovecc_summary, ovecc_impact, ovecc_architecture, ...), so an agent can ask "is this export used?", "what is the blast radius of BillingService?", or "does this PR break the architecture contract?" and get the same deterministic answer. Register it with any MCP client:

{ "mcpServers": { "ovecc": { "command": "npx", "args": ["-y", "ovecc", "mcp"] } } }

With the binary already on PATH, "command": "ovecc" and "args": ["mcp"] start it without the npm lookup.

Start with ovecc capabilities --format json: it returns every command, the metrics and rules they emit (each with a definition), the severity vocabulary, and the exit-code contract, enough to drive an audit without reading these docs. Every command's JSON is a stable, self-describing envelope, normalized to repo-relative POSIX paths and byte-identical across runs. The full walkthrough is in docs/dev/MCP.md.

Languages

The JavaScript and TypeScript family is parsed with tree-sitter and enriched by the pure-Rust oxc stack: real tsconfig path and exports resolution (oxc_resolver), plus per-function complexity and exports (oxc_parser/oxc_semantic). One tree-sitter adapter covers Python, Go, Rust, and C++. They all feed the same language-agnostic model, so resolution, the call graph, taint, and the rules work across every supported language. Adding a language is a new extractor behind the parser boundary, not a core change.

Workspace layout

Ten library crates and one binary, each documented in its own README.md (plus xtask, the std-only task runner behind cargo xtask):

Design guarantees

• Deterministic before generative. Every finding traces back to explicit facts; the same input produces the same output.
• Local and private. Indexing, analysis, and explanation run on the machine; nothing leaves it.
• Incremental. Re-indexing an unchanged repository re-parses nothing and writes only a new snapshot.

License

MPL-2.0; see LICENSE. Every file in this repository is covered by it unless the file itself carries a different SPDX-License-Identifier header. Files with a different header are adapted from fallow and remain MIT; third-party attributions are in THIRD-PARTY-NOTICES.md.

Releases up to and including v0.2.5 were published under Apache-2.0 and remain available under it.