ovecc

---

Ovecc とは

Ovecc はリポジトリを一度読み込み、永続的なモデルを構築します。すべての ファイル、インポート、シンボル、呼び出しを対象にします。その単一のインデックスから、 コードベースについての質問に答えます。

• これを変更すると、何が壊れますか？（impact）
• 依存関係の循環や密結合はどこにありますか？（query、summary）
• 重複、未使用、または複雑すぎる箇所はどこですか？（dupes、deadcode、health）
• セキュリティ上の問題は何ですか。また、既知の CVE がある依存関係はどれですか？（security、audit）
• 変更が頻繁な箇所はどこで、このコードの担当者は誰ですか？（hotspots）

これは、CLI、CI、または MCP 経由でコーディングエージェントから実行できる、 決定論的なコマンドを備えたアーキテクチャデータベースです。

ovecc export graph --htmlで描画された React の依存関係グラフです。サーバーや CDN がなくても、直接開ける単一ファイルに出力されます。

エージェントにかかるコスト

zod で新たなインポートが依存関係の循環を生むかどうかを Claude Sonnet 4.6 で確認した場合：

	トークン数	コスト
ファイルを読むエージェント	528,865	$1.63
MCP 経由で ovecc を使うエージェント	58,906	$0.22

1 回の実行、1 つのモデル、1 つの質問による結果です。エージェントの実行は決定論的ではありません。手法と ovecc が劣るケースについては、 docs/benchmark/BENCHMARKS.mdを参照してください。

アーキテクチャを書き留め、コードにそのルールを守らせる

多くのツールはコードを読み取るだけです。Ovecc はさらに一歩進みます。コードベースのどの部分がどの部分に依存できるかを小さな ファイルに書き留め、ビルドのたびに実際のコードがそのルールに沿っているかを確認します。

小さなアプリ向けの例です。

# .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

チェックを実行すると、違反箇所がすべてファイル名と行番号付きで返されます。

$ 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)

1 回の実行で、4 種類の劣化を検出できます。許可されていない依存先に踏み込むレイヤー、隣の機能と絡み合う機能、純粋であると約束したコード内のネットワーク呼び出し、そして設定した上限を超えつつある関数です。CI に ovecc architecture check を追加すれば、ずれが見つかった時点でプルリクエストが失敗します。3 か月後にレビュー担当者が気づいたり、誰も気づかなかったりする事態を防げます。

まだルールファイルがありませんか？ ovecc architecture suggest は、すでに採用しているアーキテクチャ（Feature-Sliced、bulletproof-react、Clean／Hexagonal、Nx ワークスペース）を認識し、実際のフォルダー構成に対応したファイルを書き出します。または、ovecc architecture init で実際のインポートグラフから下書きを作成できます。初日からチェックに合格した状態で始め、そこからルールを厳しくできます。詳しくは以下のコントラクトリファレンスを参照してください。

インストール

npx ovecc index .

npm はお使いのプラットフォーム用のバイナリのみを取得します。npm i -g ovecc を実行すると、PATH 上に配置されます。

ビルド済みバイナリは最新リリースにもあります。Linux x86_64 および aarch64、Windows x86_64、macOS arm64 に対応しています。ほかにインストールするものはありません。DuckDB は同梱されており、ランタイムは不要で、完全にオフラインで動作します。main へのプッシュごとに、ローリング形式の開発ビルドも公開されます。

macOS バイナリには署名がないため、ブラウザーからダウンロードすると Gatekeeper によって隔離されます。フラグを一度解除すれば実行できます。

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

curl と npm はこのフラグを設定しないため、npx ovecc ではこの問題は発生しません。

ソースからビルドする

安定版 Rust でビルドできます（Windows では windows-gnu ツールチェーンを使用してください。DuckDB は初回ビルド時にソースからコンパイルされます）。Windows の手順を追ったセットアップ方法は、docs/dev/SETUP.md にあります。

cargo build --release
cargo test --workspace

バイナリは ovecc です（crates/ovecc-cli）。

クイックスタート

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

この中から実行するコマンドが3つだけなら、ファイルを編集する前に advise を、violations の代わりに diagnose を（検出結果は同じですが、修正方法と、対応すべきでない場合も示します）、コードベースが改善しているか確認するために history を実行してください。summary はこれらをフッターとして出力します。一度だけ読むリストより、実行のたびに読む出力のほうが役立つためです。

各コマンドは --format を使って text、json、ndjson、または markdown 形式で出力できます（GitHub のコードスキャン用の sarif と GitLab Code Quality 用の codeclimate も利用できます）。また、CI 向けに安定した終了コードを返します。実際の出力例を含むコマンドごとの完全なリファレンスは、docs/COMMANDS.md にあります。プルリクエスト向けに、リポジトリにはすぐに導入できる GitHub Action が用意されています。ベースとヘッドをインデックス化し、review の検出結果を PR にコメントし、重大度に基づいてゲートします。

アーキテクチャ契約の詳細

.ovecc/architecture.toml は、コードとして記述する意図したアーキテクチャです。各コンポーネントはパスの glob でファイルを指定し、depends_on はインポートを許可する対象のリストです。ovecc architecture init は、既存のグラフから最初の案を生成するため、各項目が実際のインポートと一致し、初日から違反はゼロです。既知の構成を使いたい場合は、init --template fsd（または bulletproof-react、nx-workspace、clean-architecture）で参照アーキテクチャを導入できます。コードとの差分が移行計画になります。

それ以降は、実行のたびにコードと契約を比較し、見つかった内容を分類します。

• 逸脱は、契約で許可されていないインポートです。
• 迂回は、コンポーネントが宣言した公開インターフェースを経由しないインポートです。
• 不在は、宣言したものの実際には使用されていない依存関係です。

さらに、JS/TS のインポートグラフの先を調べるチェックが3つあります。

• slices = true は、コンポーネントのサブフォルダー同士を分離します。Feature-Sliced Design と bulletproof-react の基盤となるルールであり、FSD の @x による公開 API の例外も適用されます。
• deny_capabilities は、純粋性を損なう、コンポーネントに暗黙に与えられた権限を禁止します。対象は network、filesystem、storage、dom、process、time、random です。純粋なドメイン内の Date.now() は、ファイルと行番号とともに検出されます。
• max_cyclomatic / max_cognitive は、関数ごとの複雑度の上限を契約に設定します。「コアをシンプルに保つ」という方針を、ビルドで検証できるルールにできます。

インターフェースは仮想的なものです。コンポーネントの公開エントリーファイルを列挙すると、ovecc が実際のインポートに対して適用するため、バレルファイルや追加の再エクスポート層なしでカプセル化を実現できます。

段階的な導入を想定しています。check --freeze は、現在の違反をコンポーネントごとのベースラインに記録します（ブランチをきれいにマージできるよう、1行につき1件です）。それ以降は新たな違反のみをゲートし、修正した項目は削除されるため、件数が増えることはありません。エージェントは、編集前に ovecc architecture show <path> または ovecc_architecture MCP ツールを使って契約を確認できます。

ルール

言語に依存しないよりシンプルなポリシーは .ovecc/config.toml に記述し、インデックス作成時に適用され、violations（および gate CI チェック）に表示されます。

# 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"

問題のある行に // ovecc-ignore（または // ovecc-ignore-next-line、Python では # ovecc-ignore）を記述すると、該当する検出結果を個別に無視できます。無視された検出結果はインデックス作成時に除外されます。

CI とコーディングエージェント向け

すべてのコマンドはパイプラインで実行できるように設計されています。--format で形式を選択し、安定した終了コード（問題がなければ 0、--fail-on のしきい値を超えた場合は 1、実際のエラーは 2 以上）を利用し、GitHub と GitLab 向けに sarif または codeclimate を出力できます。すぐに使える GitHub Action により、プルリクエストで review を実行できます。

同じ分析機能を Model Context Protocol 経由でコーディングエージェントから利用できます。ovecc mcp は stdio 経由で MCP サーバーを起動し、各コマンドをツール（ovecc_summary、ovecc_impact、ovecc_architecture など）として公開します。これにより、エージェントは「このエクスポートは使われているか？」「BillingService の影響範囲は？」「この PR はアーキテクチャ契約に違反するか？」と質問し、同じ決定論的な回答を得られます。任意の MCP クライアントに登録できます。

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

バイナリがすでに PATH にある場合は、"command": "ovecc" と "args": ["mcp"] を指定すれば、npm の検索なしで起動できます。

まず ovecc capabilities --format json を実行してください。各コマンド、そのコマンドが出力するメトリクスとルール（それぞれに定義付き）、重大度の語彙、終了コードの仕様がすべて返されます。ドキュメントを読まずに監査を進めるには十分な情報です。各コマンドの JSON は、リポジトリ相対の POSIX パスに正規化され、実行ごとにバイト単位で同一となる、安定した自己記述型のエンベロープです。詳しい手順は docs/dev/MCP.md を参照してください。

言語

JavaScript と TypeScript のファミリーは tree-sitter で解析され、純粋な Rust 製の oxc スタックで補強されます。これにより、実際の tsconfig のパスと exports の解決（oxc_resolver）、関数ごとの複雑度とエクスポート（oxc_parser／oxc_semantic）に対応します。Python、Go、Rust、C++ は、単一の tree-sitter アダプターで処理します。これらはすべて同じ言語非依存モデルに取り込まれるため、解決、呼び出しグラフ、汚染追跡、ルールはサポート対象のすべての言語で機能します。言語を追加する場合は、コアを変更せず、パーサー境界の背後に新しい抽出器を追加します。

ワークスペースの構成

10 個のライブラリクレートと 1 個のバイナリがあり、それぞれに独自の README.md があります（さらに、cargo xtask の背後で動作する std のみのタスクランナーである xtask もあります）。

クレート	役割
ovecc-core	データモデル、型付き ID、設定、エラー型、トレイト契約
ovecc-parser	Tree-sitter アダプターとセキュリティパターンの検出
ovecc-indexer	インデックス作成パイプライン：検出、解析、解決、分析、永続化
ovecc-db	DuckDB による永続化、マイグレーション、差分同期
ovecc-git	ネイティブ Git の履歴、変更量、所有権（gix 経由）
ovecc-graph	影響範囲、ホットスポット、循環依存、規約
ovecc-rules	ルール評価とセキュリティ分類
ovecc-dataflow	ソースからシンクへの汚染到達可能性
ovecc-audit	オフライン OSV 依存関係監査
ovecc-ai	オプションの決定論的なオフライン説明
ovecc-cli	コマンドラインインターフェイス

設計上の保証

• 生成的な処理より決定論性を優先します。 すべての検出結果は明示的な事実に基づき、同じ入力からは同じ出力が得られます。
• ローカルでプライベートです。 インデックス作成、分析、説明はマシン上で実行され、データが外部に送信されることはありません。
• 増分処理に対応します。 変更のないリポジトリを再インデックスする場合、再解析は行われず、新しいスナップショットのみが書き込まれます。

ライセンス

MPL-2.0です。詳細はLICENSEをご覧ください。このリポジトリ内のすべてのファイルは、ファイル自体に異なるSPDX-License-Identifierヘッダーが記載されていない限り、このライセンスの適用対象です。 異なるヘッダーが記載されたファイルは、fallowを改変したもので、引き続きMITライセンスが適用されます。サードパーティの著作権表示についてはTHIRD-PARTY-NOTICES.mdをご覧ください。

v0.2.5までのリリースはApache-2.0の下で公開されており、引き続き同ライセンスの下で利用できます。