napi - Better Software Architecture for the AI Age

napi - AI 時代のための、より優れたソフトウェアアーキテクチャ

napi は完全オフラインで動作する CLI です。コードベースのアーキテクチャ（依存関係、複雑さ、構造）を分析し、コードを外部に送信することなく、可視化やリファクタリングを行えます。

ソースコードから依存関係マニフェストを生成してローカルに保存し、CLI からインタラクティブなグラフビジュアライザーを直接提供します。

機能

• 🔍 依存関係の分析：コードベース内のすべてのファイル、シンボル、依存関係を自動的にマッピングします。
• 🚨 監査：複雑さ、サイズ、結合度のしきい値を超えるファイルやシンボルを検出します。
• 📊 インタラクティブなビジュアライザー：ローカルでブラウザーに表示される Cytoscape.js グラフを通じて、アーキテクチャを探索できます。
• 📝 シンボルの抽出：特定の関数、クラス、シンボルをリファクタリング用の独立したファイルに抽出します。
• 🏷️ AI によるラベル付け（任意）：OpenAI、Google、Anthropic のモデルを使って、依存関係に自動でラベルを付けます。
• ⚙️ CI/CD 対応：あらゆるパイプラインに統合でき、プッシュのたびにマニフェストを生成して、アーキテクチャの変化を追跡できます。
• 🔒 完全オフライン：アカウントもサーバーも不要で、データがマシンの外に出ることはありません。

対応言語

言語	状況
Python	✅ 対応済み
C#	✅ 対応済み
C	✅ 対応済み
Java	✅ 対応済み
C++	🚧 開発中
PHP	🚧 開発中
JS/TS	🚧 開発中

インストール

Unix（macOS、Linux）

curl -fsSL https://raw.githubusercontent.com/nanoapi-io/napi/refs/heads/main/install_scripts/install.sh | bash

または、GitHub Releases からバイナリを直接ダウンロードしてください。

Windows

WSL を使って napi を実行してください。 Windows ネイティブへの対応は進行中です。

クイックスタート

# 1. Initialize your project (creates .napirc)
napi init

# 2. Generate a dependency manifest
napi generate

# 3. Open the visualizer in your browser
napi view

これで完了です。マニフェストは .napi/manifests/ にローカル保存され、ビジュアライザーが http://localhost:3000 で開きます。

CLI コマンド

napi init

プロジェクトのルートに .napirc 設定ファイルを作成する、対話式のセットアップです。

次の項目について尋ねられます。

• 言語 -- Python、C#、C、または Java
• 対象／除外パターン -- 分析するファイル
• 出力ディレクトリ -- 抽出したシンボルの保存先
• AI によるラベル付け（任意）-- プロバイダーと同時実行の設定

napi init

napi generate

コードベースを分析し、依存関係マニフェストを生成します。マニフェストには、すべてのファイル、シンボル、依存関係、メトリクス（行数、複雑さ、結合度）が記録されます。

マニフェストは .napi/manifests/ に JSON ファイルとして保存され、ファイル名は {timestamp}-{commitSha}.json という形式になります。

# Interactive (prompts for branch/commit if not in git)
napi generate

# Non-interactive (for CI)
napi generate --branch main --commit-sha abc1234 --commit-sha-date 2026-01-01T00:00:00Z

オプション：

• --branch -- Git ブランチ名（省略時は自動検出）
• --commit-sha -- Git コミットハッシュ（省略時は自動検出）
• --commit-sha-date -- ISO 8601 形式のコミット日時（省略時は自動検出）
• --labelingApiKey -- AI によるラベル付け用の API キー（グローバル設定を上書き）

napi view

ローカルの Web サーバーを起動し、ブラウザーでインタラクティブな依存関係ビジュアライザーを開きます。

napi view
napi view --port 8080

ビューアーでは、次のことができます。

• マニフェスト一覧 -- ブランチ、コミット、日付ごとにローカル保存されたすべてのマニフェストを表示
• プロジェクトグラフ -- Cytoscape.js を使ったファイルレベルの依存関係マップ
• ファイルグラフ -- ファイル内のシンボルレベルの表示（関数、クラス、変数）
• シンボルグラフ -- 特定のシンボルの推移的な依存関係チェーン
• ファイルエクスプローラーのサイドバー -- コードベースの構造を移動
• 監査アラート -- しきい値を超えるファイルやシンボルを示す視覚的なインジケーター

napi extract

ローカルのマニフェストを使って、コードベース内の特定のシンボルを個別のファイルに抽出します。

# Extract a function from a specific file
napi extract --symbol "src/auth/login.py|authenticate"

# Extract multiple symbols
napi extract --symbol "src/models.py|User" --symbol "src/models.py|Session"

# Use a specific manifest (defaults to latest)
napi extract --symbol "src/main.py|run" --manifestId 1712500000000-a1b2c3d

出力は {outDir}/extracted-{timestamp}/ に書き込まれます。

napi set apiKey

AI による依存関係のラベル付けに使う API キーを設定します。キーはプロジェクトではなく、グローバル設定に保存されます。

napi set apiKey

次の項目について尋ねられます。

• プロバイダー -- Google、OpenAI、または Anthropic
• API キー -- プロバイダーの API キー

ローカルマニフェストの保存

すべてのマニフェストは、プロジェクトのルートディレクトリを基準とする .napi/manifests/ に保存されます。 各マニフェストは、単独で完結する JSON ファイルです。

{
  "id": "1712500000000-a1b2c3d",
  "branch": "main",
  "commitSha": "a1b2c3d4e5f6...",
  "commitShaDate": "2026-04-07T10:00:00Z",
  "createdAt": "2026-04-07T10:01:00Z",
  "manifest": {}
}

.napi/ を .gitignore に追加するか、バージョン管理でアーキテクチャの履歴を追跡できるようコミットしてください。どちらにするかは自由です。

CI/CD との統合

プッシュのたびにマニフェストを自動生成します。

# .github/workflows/napi.yml
name: Generate Manifest
on: [push]
jobs:
  manifest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install napi
        run: curl -fsSL https://raw.githubusercontent.com/nanoapi-io/napi/refs/heads/main/install_scripts/install.sh | bash

      - name: Generate manifest
        run: napi generate --branch ${{ github.ref_name }} --commit-sha ${{ github.sha }} --commit-sha-date "$(git log -1 --format=%cI)"

設定リファレンス

.napirc

napi init によって作成されるプロジェクトレベルの設定です。

{
  "language": "python",
  "python": { "version": "3.10" },
  "project": {
    "include": ["src/**/*.py"],
    "exclude": [".git/**", "**/__pycache__/**", "napi_out/**"]
  },
  "outDir": "napi_out",
  "labeling": {
    "modelProvider": "openai",
    "maxConcurrency": 5
  }
}

グローバル設定

OS の設定ディレクトリ（Linux では ~/.config/napi/config.json、macOS では ~/Library/Application Support/napi/config.json）に保存されます。napi set apiKey で管理します。

{
  "labeling": {
    "apiKeys": {
      "openai": "sk-...",
      "google": "AIza...",
      "anthropic": "sk-ant-..."
    }
  }
}

開発

Deno v2.4 以降が必要です。

# Install dependencies
deno install --allow-scripts

# Run CLI in dev mode
deno task dev

# Run viewer dev server (hot-reload)
deno task dev:viewer

# Build viewer for production
deno task build:viewer

# Compile binary (includes viewer)
deno task compile

# Run tests
deno task test

# Lint
deno lint

# Format
deno fmt

貢献

コミュニティからの貢献を歓迎します。参加方法の詳細は、貢献ガイドをご覧ください。

ライセンス

napi は、Sustainable Use Licenseに基づいてライセンスされています。

さらに詳しく

• マイクロリシックな開発によるストラングラーパターンの自動化
• 「マイクロリス」の台頭：現代の開発者のためにマイクロサービスを再考する

寄付

NanoAPI はフェアソースプロジェクトです。そのため、寄付をすべて自分たちで受け取るのは倫理的ではないと考えています。寄付は以下のように取り扱います。

• 寄付金はプールに集めます
• プールの資金は貢献者に分配します
• 年末に残った資金は、コミュニティが選んだ慈善団体に寄付します

プールの資金額とその分配状況について、定期的に最新情報をお知らせします。