genotoxic

Genotoxic

突然変異テストとnecessist（テスト文の削除）をコードグラフ解析と組み合わせ、検出結果を実行可能なカテゴリ（誤検出、不足しているユニットテスト、ファジング対象）に分類します。

使用する場面

• 突然変異テストで生き残ったミュータントが見つかり、トリアージが必要なとき
• ユニットテストによる効果が最も高い箇所を特定するとき
• ユニットテストではなく、ファズハーネスが必要な関数を見つけるとき
• データフローのコンテキストを使って、テストの改善に優先順位を付けるとき
• 無害なミュータントと対処が必要なミュータントを選別するとき
• 弱いアサーションを示す不要なテスト文を見つけるとき（necessist）

使用しない場面

• コードベースに既存のテストスイートがない場合（まずテストを作成してください）
• ドキュメントまたは設定のみの変更
• ロジックが単純な単一ファイルのスクリプト

前提条件

• trailmark がインストールされていること — uv run trailmark が失敗する場合は、次を実行してください。

  uv tool install trailmark
  

Python snippets: uv run --with trailmark python - (a tool env is not importable)

trailmark の実行の代わりに「手動検証」や「手動分析」を**絶対に**行わないでください。まずインストールしてください。インストールに失敗した場合は、手動分析に切り替えるのではなく、エラーを報告してください。
- 対象言語用の**突然変異テストフレームワーク** — フレームワークのコマンドが見つからない、またはインストールされておらず失敗する場合は、[references/mutation-frameworks.md](references/mutation-frameworks.md) の手順に従ってインストールしてください。「手動の突然変異分析」に切り替えたり、突然変異テストを省略したりすることは**絶対にしないでください**。まずフレームワークをインストールしてください。インストールに失敗した場合は、手動の突然変異分析に切り替えるのではなく、エラーを報告してください。
- **necessist**（任意、推奨）— 対象言語がサポートされている場合（Go、Rust、Solidity/Foundry、TypeScript/Hardhat、TypeScript/Vitest、Rust/Anchor）は、`cargo install necessist` でインストールしてください。詳細は [references/mutation-frameworks.md](references/mutation-frameworks.md) を参照してください。
- テストが成功する既存のテストスイート
- **macOS 環境**：`mull-runner` を実行する前に `ulimit -n 1024` を実行してください。macOS Tahoe（26 以降）では、デフォルトでファイルディスクリプターが無制限に設定されているため、Mull のサブプロセスの起動時にクラッシュします。詳細は [references/mutation-frameworks.md](references/mutation-frameworks.md) を参照してください。

---

## 却下すべき合理化

| 合理化 | 誤りである理由 | 必要な対応 |
|-----------------|-----------------|-----------------|
| 「生き残ったミュータントにはすべてテストが必要だ」 | 多くは無害、または同等です | テストを作成する前にトリアージしてください |
| 「突然変異テストはノイズが多すぎる」 | ノイズが多いのは、トリアージしていないということです | グラフのデータを使って絞り込んでください |
| 「ユニットテストですべてをカバーできる」 | 複雑なデータフローにはファジングが必要です | エントリーポイントから到達可能か確認してください |
| 「デッドコードのミュータントは問題ない」 | デッドコードは削除すべきです | クリーンアップ対象として報告してください |
| 「複雑度が低ければリスクも低い」 | 境界値のバグは単純なコードにも潜んでいます | ミュータントの位置を確認してください |
| 「ツールがインストールされていないので、手動で行う」 | 手動分析ではツールが検出する問題を見逃します | まずツールをインストールしてください |
| 「Necessist は突然変異テストではないので、省略する」 | Necessist は突然変異テストでは見つからない、弱いテストを検出します | 言語がサポートされている場合は両方実行してください |

---

## クイックスタート

```bash
# 1. Build the code graph
uv run trailmark analyze --language auto --summary {targetDir}

# 2. Run mutation testing (language-dependent)
# Python:
uv run mutmut run --paths-to-mutate {targetDir}/src
uv run mutmut results

# 2b. Run necessist (if language supported)
necessist

# 3. Analyze results with this skill's workflow (Phase 3)

---

ワークフローの概要

Phase 1: Graph Build      → Parse codebase with trailmark
      ↓
Phase 2: Mutation Run     → Execute mutation testing framework
Phase 2b: Necessist Run   → Remove test statements (optional, parallel)
      ↓
Phase 3: Triage           → Classify findings using graph data
      ↓
Output: Categorized Report
  ├── Corroborated         (both tools flag same function — highest value)
  ├── False Positives      (harmless, skip)
  ├── Missing Tests        (write unit tests)
  └── Fuzzing Targets      (set up fuzz harnesses)

---

判断ツリー

├─ Need to set up mutation testing for a language?
│  └─ Read: references/mutation-frameworks.md
│
├─ Need to set up necessist or find weak test statements?
│  └─ Read: references/mutation-frameworks.md (Necessist section)
│
├─ Need to understand the triage criteria in depth?
│  └─ Read: references/triage-methodology.md
│
├─ Need to understand how graph data informs triage?
│  └─ Read: references/graph-analysis.md
│
└─ Already have results + graph? Use Phase 3 below.

---

フェーズ 1：コードグラフの構築と事前分析の実行

trailmark で対象のコードベースを解析し、突然変異テストの前に事前分析を実行します。事前分析では、影響範囲、エントリーポイント、権限境界、汚染の伝播を計算します。これらはフェーズ 3 のトリアージで使用します。

uv run trailmark analyze --language auto --summary {targetDir}

QueryEngine API を使ってグラフを構築し、事前分析を実行します。

1. QueryEngine.from_directory("{targetDir}", language="auto")
2. engine.preanalysis() を呼び出します — トリアージの前に必ず実行してください
3. engine.to_json() でエクスポートし、突然変異テストの結果と照合します

対象の自動検出が正しくない場合は、明示的な言語、または python,rust のようにカンマ区切りの言語リストを指定して再実行してください。

ノードのマッピング、到達可能性のクエリ、影響範囲、事前分析のサブグラフ検索など、API の詳細については references/graph-analysis.md を参照してください。

---

Phase 2: ミューテーションテストを実行する

適切なフレームワークを選択して実行します。言語ごとのセットアップについては、 references/mutation-frameworks.mdを参照してください。

生き残ったミュータントを記録します。 フレームワークによって報告形式は異なりますが、 各ミュータントについて次のフィールドを抽出してください。

フィールド	説明
ファイルパス	ミュータントを含むソースファイル
行番号	ミューテーションを適用した行
ミューテーションの種類	変更した内容（演算子、値など）
ステータス	生存、キル、タイムアウト、エラー

Phase 3では、生き残ったミュータントのみを対象にします。

---

Phase 2b: Necessistを実行する（任意）

対象言語がサポートされている場合（Go、Rust、Solidity/Foundry、 TypeScript/Hardhat、TypeScript/Vitest、Rust/Anchor）、necessistを実行して 不要なテスト文を見つけます。これはPhase 2とは独立して実行され、 並列実行できます。

# Auto-detect framework
necessist

# Or target specific test files
necessist tests/test_parser.rs

# Export results
necessist --dump

削除後にテストが成功した検出結果のみを対象にします。フレームワーク固有の設定と 正規化されたレコード形式については、 references/mutation-frameworks.md を参照してください。

references/graph-analysis.mdのアルゴリズムを使って、 各削除を本番関数に対応付けます。

---

Phase 3: 検出結果をトリアージする

生き残った各ミュータントとnecessistによる各削除について、グラフデータを使って トリアージの分類先を判断します。necessistによる削除は、まず本番関数に対応付ける必要があります （references/graph-analysis.mdを参照）。

クイック分類（ミューテーションテスト）

シグナル	分類先	判断理由
グラフ上に呼び出し元がない	誤検出	デッドコードで、ミュータントに到達できません
テストからの呼び出しのみ	誤検出	テスト用の基盤であり、本番環境では使われません
ログ／表示文字列	誤検出	表示上の変更であり、動作に影響しません
等価ミュータント	誤検出	ミューテーション後も動作は変わりません
単純な関数、低CC、エントリーポイントからの経路なし	テスト不足	ユニットテストを簡単に作成できます
エラー処理経路	テスト不足	異常系のテストケースが必要です
境界条件（1つずれ）	テスト不足	プロパティベーステストの候補です
純粋関数、決定論的	テスト不足	テストしやすく、価値が高いです
高CC（>10）、エントリーポイントから到達可能	ファジング対象	複雑で外部に公開されているため、ファジングします
パーサー／バリデーター／デシリアライザー	ファジング対象	構造化された入力を処理します
呼び出し元が多数（>10）＋中程度のCC	ファジング対象	影響範囲が広いです
バイナリ／ワイヤープロトコルの処理	ファジング対象	ファザーは形式のテストに優れています

クイック分類（Necessist）

シグナル	分類先	判断理由
冗長なセットアップまたはデバッグ呼び出し	誤検出	その文は実際に不要です
本番関数に対応付けられない	誤検出	トリアージに使えるグラフのコンテキストがありません
呼び出しを削除しても、その効果を確認するアサーションがない	テスト不足	テストのアサーションが弱いです
アサーションを削除してもテストが成功する	テスト不足	カバレッジが冗長、または不十分です
高CCでエントリーポイントから到達可能な関数に対応する	ファジング対象	複雑で外部に公開されているうえ、テストが弱いです

ミューテーションテストとnecessistの両方が同じ本番関数を指摘した場合は、裏付けありとマークします。これは最も確度の高い検出結果です。

詳しい基準については、 references/triage-methodology.mdを参照してください。

トリアージ用のグラフクエリ

各ミュータントを、それを含むグラフノードに対応付け、Phase 1で作成した事前解析サブグラフ （tainted、high_blast_radius、privilege_boundary）を使って分類します。分類ロジックでは、 呼び出し元なし → 誤検出、権限境界 → ファジング、高CC＋tainted → ファジング、 影響範囲が広い → ファジング、それ以外 → テスト不足の順に確認します。

batch_triageの実装とノードの対応付け関数については、 references/graph-analysis.mdを参照してください。

---

出力形式

Markdown レポートを生成します:

# Genotoxic Triage Report

## Summary
- Total survived mutants: N
- Total necessist removals: N
- Corroborated findings: N
- False positives: N (N%)
- Missing test coverage: N (N%)
- Fuzzing targets: N (N%)

## Corroborated Findings
| File | Line | Function | Mutation Signal | Necessist Signal | Action |
|------|------|----------|----------------|------------------|--------|

## False Positives
| File | Line | Mutation | Reason | Source |
|------|------|----------|--------|--------|

## Missing Test Coverage
| File | Line | Function | CC | Callers | Suggested Test | Source |
|------|------|----------|----|---------|----------------|--------|

## Fuzzing Targets
| File | Line | Function | CC | Entrypoint Path | Blast Radius | Source |
|------|------|----------|----|-----------------|--------------|--------|

Source 列は mutation、necessist、または corroborated です。

レポートを作業ディレクトリの GENOTOXIC_REPORT.md に書き込みます。

---

品質チェックリスト

納品前に:

• 対象言語向けの Trailmark グラフが構築されている
• ミューテーションフレームワークが最後まで実行されている
• Necessist が実行されている(言語がサポートしている場合)、または該当なしとして記録されている
• 生存したミュータントがすべてトリアージされている(未分類のものがない)
• necessist による削除がすべてトリアージされている(該当する場合)
• 裏付けられた所見が特定されている(両方のツールが実行された場合)
• 誤検知に明確な根拠がある
• 不足しているテスト項目に推奨テスト種別が含まれている
• ファジング対象にエントリポイントのパスとブラスト半径が含まれている
• レポートファイルが GENOTOXIC_REPORT.md に書き込まれている
• ユーザーに集計統計が通知されている

---

連携

trailmark スキル:

• フェーズ 1: コードグラフを構築し、複雑度とエントリポイントをクエリする
• フェーズ 3: 呼び出し元分析、到達可能性、ブラスト半径

property-based-testing スキル:

• 境界条件を含むテストカバレッジの不足項目
• シリアライゼーションのミュータントに対するラウンドトリップ/冪等性プロパティ

testing-handbook-skills (ファジング):

• ファジング対象項目: harness-writing、cargo-fuzz、atheris を使用する

---

補足ドキュメント

• references/mutation-frameworks.md - 言語別のフレームワーク設定、出力解析、necessist の構成
• references/triage-methodology.md - ミューテーションテストと necessist の両方に関する詳細なトリアージ基準、エッジケース、実例
• references/graph-analysis.md - グラフクエリのパターン、テストから本番へのマッピング、結果のマージ

---

初めて使用する方: フェーズ 1(グラフ構築)から始め、次にミューテーションを実行し、その後フェーズ 3 のクイック分類表を使用してください。

経験豊富な方: フェーズ 3 に進み、デシジョンツリーを使用して特定のリファレンス資料を読み込んでください。