lakeday-org/perch

perch – AI駆動の意味的コードLint

何であるか – perch は、ソースコードをスキャンして 意味的 な欠陥（例：呼び出し順序の誤り、オフセット1エラー、環境変数の誤用）を報告するコマンドラインツールです。分析は TypeSafe の大規模言語モデルサービス（APIキー経由でアクセス）によって駆動されます。構文解析を超えて、モデルに各メソッドの意図を推論させ、信頼度で結果をランク付けします。

動作方法

• perch scan はプロジェクトを走査し、関数/メソッドのグラフを構築し、簡潔な「質問」をLLMに送信します。モデルは特定のパターンが欠陥である確率を返し、perchはそれを深刻度スコア（P1、P2、…）に変換してテーブル形式で出力します。
• 結果は隠しフォルダ .perch/ にキャッシュされるため、繰り返し実行が高速です。
• perch issues で一覧を照会でき、perch issues <id> で個別の発見に詳細を確認し、修正後に perch check <id> で再検査できます。

拡張方法 – カスタムルールはシンプルなYAML形式（perch.yaml または .perch/rules/ 下のファイル）で記述します。ルールは以下の項目を指定します：

• where – ファイルのグロブパターン
• each – 精度の粒度（method、function など）
• min – 問題を表示するための最小信頼度
• ensure – 目的の振る舞いを自然言語で記述

アシスタント統合 – perchは、さまざまなLLMアシスタント（Claude、Codex、Pi、Cursor）向けの「スキル」をインストールできます。perch setup <assistant> コマンドにより、アシスタントが修正提案に使用できるプロンプトを含むMarkdownファイルが生成されます。

導入方法

npm install -g @lakeday/perch
export PERCH_API_KEY=$(cat ~/.perch_key)   # console.typesafe.ai から取得
perch scan

CLIは問題のリスト、信頼度、および発見されたメソッドをテーブル形式で出力します。

一般的なワークフロー

1. perch scan をローカルまたはCIで実行。
2. perch issues で深刻度の高い項目を確認。
3. コードを修正後、perch check <id> を実行して問題が解消されたか確認。
4. 偽陽性を .perch/closed.jsonl にエントリを追加することで無視。

ドキュメントとエコシステム – 完全なドキュメントは https://docs.perchscan.com にホストされており、インストール、ルール言語、CI統合、内部の「グラフ走査」についてカバーしています。プロジェクトはnpm（@lakeday/perch）に公開されており、CIバッジ、型チェック、ユニットテストを含んでいます。

成熟度 – リポジトリには安定したCLI、自動テスト、CIが含まれます。外部APIキーが必要なため、コア分析はTypeSafeサービスに依存しますが、周辺ツール（ルールエンジン、キャッシュ、CI統合）はオープンソースです。

ライセンス – MIT（LICENSE を参照）。

---

Perch は、独自のプロンプトを書かずに、モデル駆動の高レベルなコード品質チェックを実現したい開発者向けの本格的なAI補助Lintプラットフォームです。