pyscn

English | 日本語 | 简体中文 | Français

AI コーディング時代の Python コード品質分析。

Cursor、Claude、または ChatGPT で開発していますか？pyscn は構造分析によって、AI が生成したコードの保守性を保ちます。

クイックスタート

# Run analysis without installation
uvx pyscn@latest analyze .
# or
pipx run pyscn analyze .

デモ

機能

1つのコマンドでコードベース全体をスコア化（0〜100、A〜Fの評価）し、優先して修正すべき箇所を示すHTMLレポートを生成します。

pyscnは、コードを5つの観点から分析します。

• 🧹 デッドコード - 安全に削除できる到達不能なコード
• 📋 重複コード - 統合する価値のあるコピー＆ペーストされたコードや構造的に類似したコード（タイプ1〜4のクローン検出）
• 🌀 複雑さ - 読みづらくテストしにくい関数や実行可能なクラススイート（循環的複雑度と認知的複雑度）
• 🔥 モジュールとディレクトリのホットスポット - リファクタリングの優先順位付けに役立つ、ファイルごとの品質とディレクトリごとの複雑度の集計
• 🏗️ アーキテクチャ - 循環インポート、レイヤールール違反（クリーン／レイヤード／ヘキサゴナル／MVCのプリセット）、およびコードの実際の構造を明らかにする、自動検出されたモジュールコミュニティ
• 🧩 クラス設計 - 責務が多すぎる、または依存関係が多すぎるクラス（CBO結合度、LCOM4凝集度）

毎秒100,000行以上 • Go + tree-sitterで構築

その他の言語

pyscnはpolyscanのPythonアナライザーです。JavaScript、TypeScript、Go、Rust、C++を分析するには、次を実行します。

npx polyscan analyze .

同じ5つの観点、同じ0〜100のスコア、1つのHTMLレポート。

GitHub向けPolyscan

Polyscan Appは、毎週の監査レポートをGitHub Issueとして作成します。パブリックリポジトリでは無料です。

AIエージェントとの連携

pyscnには、各分析をいつ、どのように実行するかをAIコーディングエージェントに教えるAgent Skillsが付属しています。ヘルスチェック、リファクタリング、アーキテクチャレビュー、CIに適したレポートに対応します。

Agent Skills（推奨）

uvx add-skills ludo-technologies/pyscn

これにより、Skillsがプロジェクトにインストールされます。Claude Code、Cursor、Codex、Gemini CLI、およびその他多数のエージェントで使用できます（1つのエージェントを対象にするには--agent cursorなどを追加し、すべてのプロジェクトで使うには--globalを指定します）。

あとはエージェントに次のように頼むだけです。

1. 「app/ディレクトリのコード品質を分析してください」

2. 「重複コードを見つけて、リファクタリングを手伝ってください」

3. 「複雑なコードを示して、簡潔にするのを手伝ってください」

MCP サーバー（任意）

より緊密に統合するため、同梱の pyscn-mcp サーバーは、Claude Code、Cursor、ChatGPT、その他の MCP クライアント向けに、同じ分析機能を MCP ツールとして公開します。

Claude Code プラグイン（MCP サーバーとスキルをまとめてセットアップします）：

claude plugin marketplace add ludo-technologies/pyscn
claude plugin install pyscn-mcp@pyscn-marketplace

Claude Code の手動セットアップ：

claude mcp add pyscn-mcp uvx -- pyscn-mcp

Cursor／Claude Desktop： MCP 設定（~/.config/claude-desktop/config.json または Cursor の設定）に追加します：

{
  "mcpServers": {
    "pyscn-mcp": {
      "command": "uvx",
      "args": ["pyscn-mcp"],
      "env": {
        "PYSCN_CONFIG": "/path/to/.pyscn.toml"
      }
    }
  }
}

セットアップ手順は mcp/README.md、アーキテクチャの詳細は docs/MCP_INTEGRATION.md をご覧ください。

インストール

# Install with pipx (recommended)
pipx install pyscn

# Or with uv
uv tool install pyscn

macOS Intel（x86_64）： PyPI のホイールは Apple Silicon 向けのみビルドされます（Intel 向けホイールは v1.5.1 で廃止されました）。そのため、uvx、pipx、uv、pip では Intel Mac に pyscn をインストールできません。代わりに brew install pyscn または go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest を使用してください。

git clone https://github.com/ludo-technologies/pyscn.git
cd pyscn
make build

go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest

よく使うコマンド

pyscn analyze

HTML レポートを含む包括的な分析を実行します

pyscn analyze .                              # All analyses with HTML report
pyscn analyze --json .                       # Generate JSON report
pyscn analyze --json --output - . | jq       # JSON report on stdout
pyscn analyze --json --html --no-open .      # JSON and HTML reports from one run
pyscn analyze --select complexity .          # Only complexity analysis
pyscn analyze --select deps .                # Only dependency analysis
pyscn analyze --select complexity,deps,deadcode . # Multiple analyses
pyscn analyze --skip-communities .           # Skip module community detection

pyscn check

CI に適した高速な品質ゲート

pyscn check .                         # Quick pass/fail check
pyscn check --max-complexity 15 .     # Custom thresholds
pyscn check --max-cycles 0 .          # Only allow 0 cycle dependency
pyscn check --select deps .           # Check only for circular dependencies
pyscn check --select di .             # Detect DI anti-patterns (opt-in)
pyscn check --allow-circular-deps .   # Allow circular dependencies (warning only)

pyscn init

設定ファイルを作成します

pyscn init                         # Generate .pyscn.toml

💡 すべてのオプションについては、pyscn --help または pyscn <command> --help を実行してください

設定

.pyscn.toml ファイルを作成するか、pyproject.toml に [tool.pyscn] を追加します：

# .pyscn.toml
[complexity]
max_complexity = 15

[dead_code]
min_severity = "warning"

[output]
directory = "reports"

⚙️ pyscn init を実行すると、利用可能なすべてのオプションを含む完全な設定ファイルを生成できます

ドキュメント

📖 pyscn ドキュメントサイト — インストール、ルールカタログ、CLI リファレンス、設定、出力仕様

コントリビューター向け：開発ガイド • アーキテクチャ • テスト

エンタープライズサポート

商用サポート、カスタム統合、またはコンサルティングサービスについては、[email protected] までお問い合わせください

ライセンス

MIT License — LICENSE をご覧ください

Go と tree-sitter を使用して ❤️ を込めて開発