omni-scanner

🔱 Omni — 全てを見通す目

連邦ガバナンスのトライコーダー — 銀河規模でコードベースをスキャンし、マッピングして保護する、モジュール式で拡張可能な観測エンジンです。

「ドキュメントを信じてはいけません。現実を信じましょう。」 — ACE

Omni は、Python を基盤とする受動的な観測プラットフォームで、コードに関する真実を明らかにします。ファイルを変更したり、ビルドを壊したりすることはありません。観察し、マッピングして、レポートを生成します。コードベース向けのトライコーダーと考えてください。任意のディレクトリを指定すると、その構造、依存関係、健全性、乖離、コンプライアンスを数秒で明らかにします。

---

✨ 概要

項目	内容
🔍 スキャナーカテゴリー	12（静的解析から Git の考古学的調査まで）
📦 スキャナー総数	全カテゴリーにわたる55種類の計測器
⚡ CLI コマンド	あらゆる観測ニーズに対応する14種類の動詞
🧠 MCP サーバー	すべてのスキャナーを AI から呼び出し可能なツールとして公開
🏛️ 柱	4つのオーケストレーションサブシステム（Cartography、Intel、Gatekeeper、Registry）
🔌 連邦モード	ガバナンスバックエンドとの任意の高度な統合
🦴 スタンドアロンモード	どこでも動作し、バックエンドは不要

---

🚀 クイックスタート

初めての方へ：ステップごとのセットアップチュートリアルは、**初心者向けガイド：ゼロから一人前まで**をご覧ください。

インストール

# Recommended: Install from PyPI
pip install omni-governance

# Or install from source:
# pip install -e .

最初のスキャン

# Scan the current directory with all static scanners
omni scan .

# Run a specific scanner
omni scan . --scanner surfaces

# See what Omni knows about itself
omni introspect

エコシステムを探索する

# Map your entire project constellation
omni map

# Check governance compliance
omni gate .

# Generate a full report
omni report . --format markdown

---

🏗️ アーキテクチャ — 三位一体

Omni は三位一体アーキテクチャに従っており、関心事を厳密に分離した3つのレイヤーで構成されます。

                    ┌──────────────────────────┐
                    │        CLI (cli.py)       │  ← User interface
                    │     14 verbs, 1 brain     │
                    └────────────┬─────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
    ┌─────────▼──────┐  ┌───────▼────────┐  ┌──────▼───────┐
    │  🧠 CORE       │  │  🏛️ PILLARS    │  │  📚 LIB      │
    │  Identity      │  │  Cartography   │  │  I/O, Render │
    │  Registry      │  │  Intel         │  │  Reporting   │
    │  Gate          │  │  Gatekeeper    │  │  Tree, TAP   │
    │  Paths         │  │  Registry      │  │  Requirements│
    └─────────┬──────┘  └───────┬────────┘  └──────────────┘
              │                 │
    ┌─────────▼─────────────────▼──────────────────────────┐
    │              🔍 SCANNERS (55 Instruments)            │
    │   12 categories • Dynamic plugin loading             │
    │   Each scanner: scan(target: Path) → dict            │
    └──────────────────────────────────────────────────────┘
              │
    ┌─────────▼──────┐
    │  🔧 BUILDERS   │  ← The only layer that writes
    │  Registry Gen  │
    │  Report Gen    │
    └────────────────┘

読み取り専用の保証：スキャナーがソースファイルを変更することはありません。書き込みを行うのは Builder のみで、書き込み先も指定された成果物ディレクトリに限られます。

アーキテクチャの詳細については、**ARCHITECTURE.md**をご覧ください。

---

🔍 スキャナーカテゴリー

Omni の55種類のスキャナーは、12のカテゴリーに分類されています。各スキャナーは共通の scan(target: Path) → dict コントラクトを実装し、SCANNER_MANIFEST.yaml ファイルを通じて自動検出されます。

オープンソーススキャナー（ビルドに含まれます）

カテゴリ	スキャナー	目的
📁 static	9	ファイルシステム分析 — コントラクト、依存関係、ドキュメント、イベント、フック、インポート、サーフェス、ツール、UUID
🏗️ architecture	4	構造の適用 — インポート境界、結合の検出、ドリフト分析、コンプライアンス
🔎 discovery	8	コンポーネントのカタログ化 — プロジェクト、CLI コマンド、コア、MCP サーバー、アーカイブ、全数調査
🌐 polyglot	4	言語エコシステム — Python パッケージ、Node.js、Rust クレート、汎用（Go／Java／.NET／Docker）
📚 library	6	ドキュメントインテリジェンス — 凝集性分析、コンテンツの深度、ナレッジグラフ、儀式
🔀 git	5	リポジトリインテリジェンス — ステータス、活発度、コミット履歴、PR テレメトリ、ユーティリティ
🔍 search	3	パターンマッチング — ファイル検索、テキスト検索、コンテキスト付き正規表現パターン検索
🗄️ db	1	汎用の設定駆動型データベーススキャン

Federation 専用スキャナー（オープンソースビルドには含まれません）

これらのスキャナーには Federation Heart バックエンドが必要で、独自のガバナンス層の一部です。Heart が利用可能な場合は omni introspect に表示されますが、オープンソース版には含まれません。

カテゴリ	スキャナー	目的
🛡️ health	6	ランタイムの健全性 — Federation、CMP、ピラー、ステーション、トンネル、システムのステータス
🗃️ database	5	CMP エンティティのスキャン — エージェント、アーティファクト、会話、エンティティ、プロジェクト
⚓ fleet	1	フリートレジストリの生成と検証
🔥 phoenix	3	Git 履歴の復元 — アーカイブスキャン、孤立データの検出、時間的なギャップ分析

各カテゴリには、スキャナーの詳細なドキュメントを記載した README があります。すべての情報については、スキャナーアーキテクチャガイドをご覧ください。

---

🏛️ 4 つのピラー

ピラーは、複数のスキャナーを連携させ、より高度なインテリジェンスを生成するオーケストレーションサブシステムです。

ピラー	役割	主な機能
🗺️ Cartography	エコシステムマッパー	プロジェクトの連なりと依存関係の網をマッピングします
🕵️ Intel	インテリジェンス収集者	複数のスキャナーのデータを、実行可能なインサイトに集約します
⚖️ Gatekeeper	ポリシー適用者	コンプライアンスを検証し、ドリフトを検出して、違反を警告します
📋 Registry	レジストリ運用者	PROJECT_REGISTRY_V1.yaml を解析、検証、管理します

詳しくは、ピラーアーキテクチャをご覧ください。

---

⚡ CLI コマンドリファレンス

コマンド	目的
omni scan	対象ディレクトリに対してスキャナーを実行します
omni inspect	単一プロジェクトを詳細に検査します
omni gate	ポリシーの適用とコンプライアンスチェックを行います
omni map	エコシステムの地図作成と依存関係のマッピングを行います
omni tree	ディレクトリツリーを可視化します
omni audit	出所、依存関係、ロックの監査を行います
omni registry	レジストリ操作とイベントスキャンを行います
omni library	Grand Librarian のドキュメントインテリジェンスを提供します
omni canon	Canon の検証と検出を行います
omni report	構造化レポートを生成します
omni init	Federation 準拠の新しいプロジェクトのひな形を作成します
omni introspect	自己検査 — すべてのスキャナー、ドリフト、機能を表示します
omni interpret	スキャン結果を解釈し、説明します
omni inspect-tree	ツリー表示と検査をまとめて実行します

---

🔌 Federation モードとスタンドアロンモード

Omni は透過的に 2 つのモードで動作します。

スタンドアロンモード（デフォルト）

外部依存関係はありません。設定は omni.yml と環境変数から読み込まれます。すべてのオープンソーススキャナーが問題なく動作します。個人開発者やオープンソースプロジェクトに最適です。

Federation モード（オプション）

federation_heart がインストールされている場合、Omni では次の機能が利用できます。

• CartographyPillar — Federation 全体での正規パス解決
• Constitution — 中央機関によるガバナンスルールの適用
• CMP Integration — Canonical Master Project データベースとの照合によるプロジェクト ID の解決
• Runtime Health — Federation のサービス、ステーション、トンネルのライブステータス

統合は単一のシム（omni/config/settings.py）によって処理されます。Heart が利用可能な場合は接続し、利用できない場合は適切にフォールバックします。

---

🧠 MCP サーバー

Omni には、55 個すべてのスキャナーを AI から呼び出し可能なツールとして公開する Model Context Protocol（MCP）サーバーが含まれています。MCP 対応の AI アシスタントであれば、Omni のスキャナーをプログラムから呼び出せます。

クイックスタート（npx）

MCP サーバーを利用する最も手軽な方法は、npx を使用することです（Node.js が必要です）。

npx -y @modelcontextprotocol/inspector mcp-server-omni-governance

ソースから実行

# The MCP server auto-discovers all registered scanners
python -m mcp_server.omni_mcp_server

セットアップと設定については、MCP サーバーのドキュメントを参照してください。

---

📁 プロジェクト構成

omni/
├── README.md              ← You are here
├── ARCHITECTURE.md        ← Full architectural deep-dive
├── CONTRIBUTING.md        ← How to add scanners and contribute
├── CHANGELOG.md           ← Version history
├── ROADMAP.md             ← Future plans
├── pyproject.toml         ← Package definition
├── omni/
│   ├── cli.py             ← CLI entry point (14 commands)
│   ├── core/              ← Brain — identity, registry, gate, paths
│   ├── config/            ← Configuration & Federation Heart bridge
│   ├── scanners/          ← 55 scanners across 12 categories
│   ├── pillars/           ← 4 orchestration subsystems
│   ├── lib/               ← Shared utilities (I/O, rendering, reporting)
│   ├── builders/          ← Registry and report generators
│   ├── scaffold/          ← Project templates
│   └── templates/         ← Jinja2 report templates
├── mcp_server/            ← MCP server exposing scanners as AI tools
├── scripts/               ← Operational scripts
├── tests/                 ← Test suite (pytest)
├── docs/                  ← Historical docs and plans
└── contracts/             ← Crown Contracts (C-TOOLS-OMNI-*)

---

🔧 設定

Omni では厳格な設定の優先順位が適用されます（優先度の高い順）。

1. CLI フラグ（例：--scanner surfaces）
2. 環境変数（例：OMNI_ROOT）
3. omni.yml（プロジェクトレベルの設定）
4. 組み込みのデフォルト値（適切なフォールバック）

主な環境変数：

変数	目的
OMNI_ROOT	スキャン対象のルートパスを上書きします
OMNI_REPO_INVENTORY	リポジトリインベントリ JSON のパス
OMNI_WORKSPACES	ワークスペースのルートパス
OMNI_DB_CONFIG_PATH	データベース設定ディレクトリ

詳細については、設定ガイドを参照してください。

---

🧪 テスト

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=omni --cov-report=html

フィクスチャ、標準、CI のセットアップについては、テストスイートのドキュメントを参照してください。

---

🤝 コントリビューション

新しいスキャナー、ピラー、改善を歓迎します。スキャナープラグインシステムにより、新しい観測機能を簡単に追加できます。

1. scan(target: Path) → dict 関数を含むスキャナーファイルを作成します
2. カテゴリの SCANNER_MANIFEST.yaml に登録します
3. テストとドキュメントを追加します

詳しい手順については、CONTRIBUTING.md を参照してください。

---

📜 要件

• Python：3.8+
• 依存関係：pyyaml、pydantic（コア）；federation_heart（任意、Federation モード用）
• OS：Windows、macOS、Linux

---

📋 ライセンス

オープンソースです。詳細は LICENSE をご覧ください。

---

全てを見通す目が見守る。コードがコードを書く。
Omni v0.7.0 — Pantheon LadderWorks