{
  "markdown": "<div align=\"center\">\n\n  <img src=\"docs/img/ovecc_white_logo.png\" alt=\"Ovecc\" width=\"180\" />\n\n  <p>\n    <b>CLI-first architecture intelligence: understand your codebase, then hold it to the rules you set.</b>\n  </p>\n\n  <p>\n    Rust, one binary, no runtime. Runs offline, with no LLM in the loop.\n  </p>\n\n  <p>\n    <a href=\"https://github.com/Ovecc-labs/ovecc/actions/workflows/ci.yml\"><img src=\"https://github.com/Ovecc-labs/ovecc/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /></a>\n    <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-MPL--2.0-blue?style=flat-square\" alt=\"License\" /></a>\n    <a href=\"../../releases/latest\"><img src=\"https://img.shields.io/badge/Release-latest-00d2b4?style=flat-square\" alt=\"Latest release\" /></a>\n    <img src=\"https://img.shields.io/badge/Built%20with-Rust-dea584?style=flat-square&logo=rust\" alt=\"Rust\" />\n  </p>\n\n</div>\n\n---\n\n## What is Ovecc\n\nOvecc reads your repository once and builds a persistent model of it: every\nfile, import, symbol, and call. From that single index it answers the questions\nyou ask about a codebase:\n\n- What breaks if I change this? (`impact`)\n- Where are the dependency cycles and the tight coupling? (`query`, `summary`)\n- What is duplicated, dead, or over-complex? (`dupes`, `deadcode`, `health`)\n- What is insecure, and which dependencies have known CVEs? (`security`, `audit`)\n- Where is the churn, and who owns this code? (`hotspots`)\n\nIt is an architecture database with deterministic commands, driven from the CLI,\nfrom CI, or by a coding agent over MCP.\n\n<img src=\"docs/img/graph-hero.png\" alt=\"React's dependency graph in ovecc's offline viewer\" width=\"100%\" />\n<p align=\"center\"><i>React's dependency graph, rendered by <code>ovecc export graph --html</code> into a single file you can open directly, no server or CDN needed.</i></p>\n\n### What it costs an agent\n\nAsking whether a new import closes a dependency cycle, on zod, with Claude\nSonnet 4.6:\n\n| | Tokens | Cost |\n| --- | --- | --- |\n| Agent reading files | 528,865 | $1.63 |\n| Agent + ovecc over MCP | 58,906 | $0.22 |\n\nOne run, one model, one question, and agent runs are not deterministic. Method\nand the cases where ovecc loses are in\n[docs/benchmark/BENCHMARKS.md](docs/benchmark/BENCHMARKS.md).\n\n## Write your architecture down, and hold the code to it\n\nMost tools stop at reading the code. Ovecc goes one step further: you write\ndown which parts of your codebase are allowed to depend on which, in one small\nfile, and every build checks the real code against it.\n\nHere's one for a small app:\n\n```toml\n# .ovecc/architecture.toml\n[[component]]\nname = \"api\"\npaths = [\"src/api/**\"]\ndepends_on = [\"core\"]              # the api may use core, nothing else\n\n[[component]]\nname = \"features\"\npaths = [\"src/features/**\"]\ndepends_on = [\"core\"]\nslices = true                      # and features may not import each other\n\n[[component]]\nname = \"core\"\npaths = [\"src/core/**\"]\ndeny_capabilities = [\"network\"]    # pure domain: no fetch, no I/O\nmax_cyclomatic = 8                 # keep core functions simple\n```\n\nRun the check and every breach comes back with a file and a line:\n\n```console\n$ ovecc architecture check\n\nDivergences (1):\n  [High] api -> features is not in the contract\n    src/api/routes.ts:2 (../features/billing/service)\n\nSlice isolation breaches (1):\n  [High] features/billing -> features/users breaks slice isolation\n    src/features/billing/service.ts:1 (../users/repo)\n\nDenied capabilities used (1):\n  [Medium] core uses denied capability 'network'\n    src/core/pricing.ts:3 (fetch)\n\nComplexity budgets exceeded (1):\n  [Medium] core: 1 function over the cyclomatic budget\n    src/core/pricing.ts:8 (cyclomatic 11 > 8)\n```\n\nFour kinds of decay caught in one run: a layer reaching where it shouldn't, a\nfeature tangling into its neighbor, a network call inside code you promised was\npure, and a function creeping past the budget you set. Put `ovecc architecture\ncheck` in CI and the pull request fails on the drift, instead of a reviewer\nnoticing three months later, or nobody noticing at all.\n\n**Don't have one yet?** `ovecc architecture suggest` recognizes the architecture\nyou already follow (Feature-Sliced, bulletproof-react, Clean/Hexagonal, an Nx\nworkspace) and writes the file bound to your real folders. Or `ovecc\narchitecture init` drafts it from your actual import graph, so day one starts\ngreen and you tighten from there. The details are in [the contract reference\nbelow](#the-architecture-contract-in-depth).\n\n## Install\n\n```sh\nnpx ovecc index .\n```\n\nnpm pulls only the binary for your platform. `npm i -g ovecc` keeps it on your\n`PATH`.\n\nPrebuilt binaries are also on the [latest release](../../releases/latest): Linux\nx86_64 and aarch64, Windows x86_64, macOS arm64. There is nothing else to\ninstall: DuckDB is bundled, there is no runtime, and it works fully offline. A\nrolling [dev build](../../releases/tag/latest) ships on every push to `main`.\n\nThe macOS binary is unsigned, so Gatekeeper quarantines it when a browser\ndownloads it. Clear the flag once and it runs:\n\n```sh\nxattr -d com.apple.quarantine ./ovecc-macos-aarch64\n```\n\ncurl and npm don't set that flag, so `npx ovecc` never runs into it.\n\n### Build from source\n\nBuilds with stable Rust (on Windows use the `windows-gnu` toolchain; DuckDB is\ncompiled from source on the first build). The step-by-step Windows setup is in\n[docs/dev/SETUP.md](docs/dev/SETUP.md).\n\n```sh\ncargo build --release\ncargo test --workspace\n```\n\nThe binary is `ovecc` (`crates/ovecc-cli`).\n\n## Quick start\n\n```sh\novecc index .                 # parse, resolve, and persist the model into .ovecc/\novecc summary                 # coupling, density, cycles, risk score\novecc advise src/server.ts    # the agent-facing surface: findings for one file, each with a fix\novecc diagnose                # named architectural smells, evidence + curated remediation\novecc history max_cyclomatic  # trend one metric across every index run — is it getting better?\novecc violations              # architecture + security findings, with file:line\novecc violations --write-baseline   # accept today's backlog; later runs surface only what is new\novecc metrics                 # per-component fan-in/out, instability, abstractness, distance\novecc components              # the components the graph recovers, and what they hold\novecc coupling                # files that change together but do not import each other\novecc security                # secrets, insecure patterns, weak crypto, tainted flows\novecc audit                   # offline OSV dependency vulnerabilities\novecc impact Billing          # blast radius of a change\novecc hotspots                # churn x coupling x ownership debt ranking\novecc dupes                   # duplicated code (clone families), with file:line\novecc health                  # functions over the complexity thresholds (oxc)\novecc deadcode                # unused exports + unreachable files (oxc + reachability)\novecc fix                     # apply the mechanical fixes for those findings (dry-run by default)\novecc query \"cycles\"          # real elementary dependency cycles (A -> B -> A)\novecc report                  # one-shot architecture report (markdown or json)\novecc gate                    # CI gate: fail a PR on new cycles / violations\novecc review                  # the named new defects a change introduced (file:line + cycle witnesses)\novecc architecture init       # draft .ovecc/architecture.toml from the graph, or a --template\novecc architecture check      # gate the code against the contract, with file:line\novecc architecture suggest    # recognize which architecture the repo already follows\novecc export graph --html     # interactive dependency-graph viewer, one self-contained offline file\novecc capabilities            # machine-readable contract: commands, metrics, rules, exit codes\novecc mcp                     # MCP server over stdio: expose every command as an agent tool\n```\n\nIf you only ever run three of these, run `advise` before editing a file,\n`diagnose` instead of `violations` (same findings, plus the fix and when *not*\nto act), and `history` to see whether the codebase is improving. `summary`\nprints these as a footer, because a list read once loses to output read every\nrun.\n\nEvery command renders as `text`, `json`, `ndjson`, or `markdown` via `--format`\n(plus `sarif` for GitHub code scanning and `codeclimate` for GitLab Code Quality)\nand returns stable exit codes for CI. The full per-command reference, with real\noutput, is in [docs/COMMANDS.md](docs/COMMANDS.md). For pull requests, the repo\nships a drop-in [GitHub Action](action.yml) that indexes base and head, comments\nthe `review` findings on the PR, and gates on severity.\n\n## The architecture contract in depth\n\n`.ovecc/architecture.toml` is your intended architecture as code. Each component\nclaims files by path glob; `depends_on` is the allow-list of what it may import.\n`ovecc architecture init` writes the first draft from the graph you already have,\nso every entry mirrors a real import and day one has zero violations. Prefer a\nknown shape? `init --template fsd` (or `bulletproof-react`, `nx-workspace`,\n`clean-architecture`) drops in a reference architecture, and the diff against your\ncode becomes your migration plan.\n\nFrom then on, each run compares code to contract and names what it finds:\n\n- a **divergence** is an import the contract does not allow,\n- a **bypass** is an import that skips a component's declared public interface,\n- an **absence** is a dependency you declared but never actually use.\n\nThree more checks read past the import graph (JS/TS):\n\n- `slices = true` isolates a component's sub-folders from each other, the rule\n  behind Feature-Sliced Design and bulletproof-react, with FSD's `@x` public-API\n  escape hatch honored.\n- `deny_capabilities` forbids a component the ambient powers that break purity:\n  `network`, `filesystem`, `storage`, `dom`, `process`, `time`, `random`. A\n  `Date.now()` in a pure domain comes back with its file and line.\n- `max_cyclomatic` / `max_cognitive` put a per-function complexity budget in the\n  contract, so \"keep the core simple\" becomes a rule the build can check.\n\nInterfaces are virtual: you list a component's public entry files and ovecc\nenforces them on the real imports, so you get encapsulation without barrel files\nor an extra re-export layer.\n\nAdoption is meant to be gradual. `check --freeze` records today's violations in a\nper-component baseline (one line each, so branches merge cleanly), gates only new\nones from then on, and drops entries as you fix them so the count never climbs.\nAgents can read the contract before editing, through `ovecc architecture show\n<path>` or the `ovecc_architecture` MCP tool.\n\n### Rules\n\nSimpler, language-neutral policy lives in `.ovecc/config.toml`, is enforced at\nindex time, and shows up in `violations` (and the `gate` CI check):\n\n```toml\n# Forbid a module-to-module dependency.\n[[rules.boundaries]]\nname = \"billing must not depend on user\"\nsource = \"billing\"\ntarget = \"user\"\nallowed = false\nseverity = \"high\"\n\n# Ban imports by specifier pattern (exact, prefix*, *suffix, or *infix*).\n[[rules.banned_imports]]\nname = \"no-deprecated-lodash\"\npattern = \"lodash\"\nmessage = \"use es-toolkit instead\"\nseverity = \"medium\"\n```\n\nSilence a single finding inline with `// ovecc-ignore` (or\n`// ovecc-ignore-next-line`, and `# ovecc-ignore` in Python) on the offending\nline; it is dropped at index time.\n\n## For CI and coding agents\n\nEvery command is built to run in a pipeline: pick a format with `--format`, rely\non stable exit codes (`0` clean, `1` a `--fail-on` threshold crossed, `2` and up\na real error), and emit `sarif` or `codeclimate` for GitHub and GitLab. The\ndrop-in [GitHub Action](action.yml) wires `review` into pull requests.\n\nThe same analysis is available to coding agents over the Model Context Protocol.\n`ovecc mcp` runs an MCP server over stdio that exposes each command as a tool\n(`ovecc_summary`, `ovecc_impact`, `ovecc_architecture`, ...), so an agent can ask\n\"is this export used?\", \"what is the blast radius of `BillingService`?\", or \"does\nthis PR break the architecture contract?\" and get the same deterministic answer.\nRegister it with any MCP client:\n\n```json\n{ \"mcpServers\": { \"ovecc\": { \"command\": \"npx\", \"args\": [\"-y\", \"ovecc\", \"mcp\"] } } }\n```\n\nWith the binary already on `PATH`, `\"command\": \"ovecc\"` and `\"args\": [\"mcp\"]` start it\nwithout the npm lookup.\n\nStart with `ovecc capabilities --format json`: it returns every command, the\nmetrics and rules they emit (each with a definition), the severity vocabulary,\nand the exit-code contract, enough to drive an audit without reading these docs.\nEvery command's JSON is a stable, self-describing envelope, normalized to\nrepo-relative POSIX paths and byte-identical across runs. The full walkthrough is\nin [docs/dev/MCP.md](docs/dev/MCP.md).\n\n## Languages\n\nThe JavaScript and TypeScript family is parsed with tree-sitter and enriched by\nthe pure-Rust **oxc** stack: real `tsconfig` path and `exports` resolution\n(`oxc_resolver`), plus per-function complexity and exports\n(`oxc_parser`/`oxc_semantic`). One tree-sitter adapter covers Python, Go, Rust,\nand C++. They all feed the same language-agnostic model, so resolution, the call\ngraph, taint, and the rules work across every supported language. Adding a\nlanguage is a new extractor behind the parser boundary, not a core change.\n\n## Workspace layout\n\nTen library crates and one binary, each documented in its own `README.md` (plus\n`xtask`, the std-only task runner behind `cargo xtask`):\n\n| Crate | Responsibility |\n| --- | --- |\n| [`ovecc-core`](crates/ovecc-core) | Data model, typed ids, config, error type, trait contracts |\n| [`ovecc-parser`](crates/ovecc-parser) | Tree-sitter adapters and security pattern detection |\n| [`ovecc-indexer`](crates/ovecc-indexer) | Indexing pipeline: discover, parse, resolve, analyze, persist |\n| [`ovecc-db`](crates/ovecc-db) | DuckDB persistence, migrations, differential sync |\n| [`ovecc-git`](crates/ovecc-git) | Native Git history, churn, ownership (via gix) |\n| [`ovecc-graph`](crates/ovecc-graph) | Blast radius, hotspots, cycles, conventions |\n| [`ovecc-rules`](crates/ovecc-rules) | Rule evaluation and security classification |\n| [`ovecc-dataflow`](crates/ovecc-dataflow) | Source-to-sink taint reachability |\n| [`ovecc-audit`](crates/ovecc-audit) | Offline OSV dependency audit |\n| [`ovecc-ai`](crates/ovecc-ai) | Optional deterministic, offline explanation |\n| [`ovecc-cli`](crates/ovecc-cli) | Command-line interface |\n\n## Design guarantees\n\n- **Deterministic before generative.** Every finding traces back to explicit\n  facts; the same input produces the same output.\n- **Local and private.** Indexing, analysis, and explanation run on the machine;\n  nothing leaves it.\n- **Incremental.** Re-indexing an unchanged repository re-parses nothing and\n  writes only a new snapshot.\n\n## License\n\nMPL-2.0; see [LICENSE](LICENSE). Every file in this repository is covered by it\nunless the file itself carries a different `SPDX-License-Identifier` header. Files\nwith a different header are adapted from\n[fallow](https://github.com/fallow-rs/fallow) and remain MIT; third-party\nattributions are in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).\n\nReleases up to and including v0.2.5 were published under Apache-2.0 and remain\navailable under it.\n",
  "bytes": 15374,
  "sha": "db0ba93acc2d83b59bcff47bcc383e7e87f07ead75859a44b095f091785ab43f",
  "repo_slug": "ovecc-labs/ovecc",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ovecc_labs_ovecc_fdb22606/readme"
}