Genotoxic

ミューテーション テストと necessist (テストステートメント削除) をコードグラフ分析と組み合わせて、 検出結果を実行可能なカテゴリに分類します: 偽陽性、欠落していたユニットテスト、ファジングターゲット。

使用する場合

• ミューテーション テストが生き残ったミューテントを明らかにした後に分類が必要な場合
• ユニット テストが最も大きな影響を持つ場所を特定する場合
• ユニット テストの代わりにファズ ハーネスが必要な関数を見つける場合
• データ フロー コンテキストを使ってテスト改善に優先順位をつける場合
• 無害なミューテントを実行可能なものから除外する場合
• 弱いアサーションを示す不要なテスト ステートメントを見つける場合 (necessist)

使用しない場合

• コードベースに既存のテスト スイートがない場合 (先にテストを書く)
• 純粋なドキュメントまたは構成の変更
• 自明なロジックを持つ単一ファイル スクリプト

前提条件

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

  uv pip install trailmark
  

  trailmark の実行の代わりに「手動検証」または「手動分析」に フォールバックしないでください。先にインストールしてください。インストールが失敗した場合は、 手動分析に切り替える代わりにエラーを報告してください。
• ターゲット言語向けのミューテーション テスト フレームワーク — フレームワーク コマンドが失敗した場合 (見つからない、インストールされていない)、 references/mutation-frameworks.md の手順を使ってインストールしてください。 手動ミューテーション分析に フォールバックしないでください。フレームワークを先にインストールしてください。 インストールが失敗した場合は、手動ミューテーション分析に切り替える代わりにエラーを報告してください。
• necessist (オプション、推奨) — ターゲット言語が サポートされている場合 (Go、Rust、Solidity/Foundry、 TypeScript/Hardhat、TypeScript/Vitest、Rust/Anchor)、cargo install necessist でインストールしてください。 詳細は references/mutation-frameworks.md を参照してください。
• 合格するテスト スイート
• macOS 環境: mull-runner を実行する前に ulimit -n 1024 を実行してください。 macOS Tahoe (26+) はデフォルトで無制限のファイル ディスクリプタを設定していて、 Mull のサブプロセス生成をクラッシュさせます。詳細は references/mutation-frameworks.md を参照してください。

---

却下すべき正当化

正当化	何が間違っているか	必要なアクション
「すべての生き残ったミューテントにテストが必要」	多くは無害または同等	テストを書く前に分類する
「ミューテーション テストはノイズが多すぎる」	ノイズは分類していないことを意味する	グラフ データを使ってフィルタリングする
「ユニット テストがすべてをカバーしている」	複雑なデータ フローにはファジングが必要	エントリポイントの到達可能性を確認する
「デッド コード ミューテントは関係ない」	デッド コードは削除すべき	クリーンアップのためにフラグを立てる
「低い複雑性 = 低リスク」	境界バグは単純なコードに隠れている	ミューテント位置を確認する
「ツールがインストールされていない、手動でやる」	手動分析はツールが見つけるものを見落とす	先にツールをインストールする
「Necessist はミューテーション テストではない、スキップする」	Necessist は ミューテーション テストが見落とすものを見つける: 弱いテスト	言語がサポートしている場合は両方実行する

---

クイック スタート

# 1. コード グラフをビルドする
uv run trailmark analyze --language auto --summary {targetDir}

# 2. ミューテーション テストを実行する (言語に依存)
# Python:
uv run mutmut run --paths-to-mutate {targetDir}/src
uv run mutmut results

# 2b. Necessist を実行する (言語がサポートしている場合)
necessist

# 3. このスキルのワークフロー (フェーズ 3) で結果を分析する

---

ワークフロー概要

フェーズ 1: グラフ ビルド      → trailmark でコードベースをパースする
      ↓
フェーズ 2: ミューテーション実行     → ミューテーション テスト フレームワークを実行する
フェーズ 2b: Necessist 実行   → テスト ステートメントを削除する (オプション、並行実行)
      ↓
フェーズ 3: 分類           → グラフ データを使用して検出結果を分類する
      ↓
出力: 分類されたレポート
  ├── 相互検証済み         (両方のツールが同じ関数にフラグ — 最高値)
  ├── 偽陽性      (無害、スキップ)
  ├── テスト カバレッジの欠落        (ユニット テストを書く)
  └── ファジング ターゲット      (ファズ ハーネスを設定する)

---

デシジョン ツリー

├─ 言語のためにミューテーション テストを設定する必要がありますか?
│  └─ 参照: references/mutation-frameworks.md
│
├─ Necessist を設定する必要がありますか、または弱いテスト ステートメントを見つけますか?
│  └─ 参照: references/mutation-frameworks.md (Necessist セクション)
│
├─ 詳細で分類基準を理解する必要がありますか?
│  └─ 参照: references/triage-methodology.md
│
├─ グラフ データがどのように分類に情報を提供するかを理解する必要がありますか?
│  └─ 参照: references/graph-analysis.md
│
└─ すでに結果とグラフがありますか? 以下のフェーズ 3 を使用してください。

---

フェーズ 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 を参照してください: ノード マッピング、到達可能性クエリ、影響範囲、事前分析サブグラフ ルックアップ。

---

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

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

生き残ったミューテントをキャプチャしてください。 各フレームワークは異なる方法で報告しますが、 ミューテントごとにこれらのフィールドを抽出してください:

フィールド	説明
ファイル パス	ミューテーションを含むソース ファイル
行番号	ミューテーションが適用された行
ミューテーション タイプ	何が変更されたか (演算子、値など)
ステータス	survived、killed、timeout、error

フェーズ 3 では生き残ったミューテントのみにフィルタリングします。

---

フェーズ 2b: Necessist を実行する (オプション)

ターゲット言語がサポートされている場合 (Go、Rust、Solidity/Foundry、 TypeScript/Hardhat、TypeScript/Vitest、Rust/Anchor)、necessist を実行して 不要なテスト ステートメントを見つけます。これはフェーズ 2 とは独立して実行され、 並行実行できます。

# フレームワークを自動検出する
necessist

# または特定のテスト ファイルをターゲットにする
necessist tests/test_parser.rs

# 結果をエクスポートする
necessist --dump

テストが削除後に合格した検出結果にフィルタリングします。フレームワーク固有の構成と 正規化されたレコード形式については references/mutation-frameworks.md を参照してください。

references/graph-analysis.md のアルゴリズムを使って 各削除を本番関数にマップします。

---

フェーズ 3: 検出結果を分類する

生き残ったミューテントごと、および necessist 削除ごとに、グラフ データを使って その分類バケットを決定します。Necessist 削除は最初に本番関数にマップする必要があります (references/graph-analysis.md を参照)。

クイック分類 (ミューテーション テスト)

シグナル	バケット	理由
グラフに呼び出し元がない	偽陽性	デッド コード、ミューテントは到達不可能
テスト呼び出し元のみ	偽陽性	テスト インフラストラクチャ、本番環境ではない
ログ/表示文字列	偽陽性	装飾的、動作への影響なし
同等ミューテント	偽陽性	ミューテーションがあっても動作は変わらない
シンプルな関数、CC が低い、エントリポイント パスなし	テスト カバレッジの欠落	ユニット テストは単純明快
エラー処理パス	テスト カバレッジの欠落	負のテスト ケースが必要
境界条件 (off-by-one)	テスト カバレッジの欠落	プロパティベース テストの候補
純粋関数、決定論的	テスト カバレッジの欠落	テストは簡単で高価値
高 CC (>10)、エントリポイント到達可能	ファジング ターゲット	複雑 + 公開 = ファズする
パーサー/検証機能/デシリアライザー	ファジング ターゲット	構造化入力処理
多くの呼び出し元 (>10) + 中程度の CC	ファジング ターゲット	高い影響範囲
バイナリ/ワイヤ プロトコル処理	ファジング ターゲット	ファザーは形式テストに優れている

クイック分類 (Necessist)

シグナル	バケット	理由
冗長なセットアップまたはデバッグ呼び出し	偽陽性	ステートメントは本当に不要
本番関数にマップできない	偽陽性	分類のためのグラフ コンテキストなし
呼び出しが削除されたが、アサーションがその効果をチェックしていない	テスト カバレッジの欠落	テストはアサーションが弱い
アサーションが削除されたが、テストは依然として合格	テスト カバレッジの欠落	冗長またはカバレッジが不十分
高 CC のエントリポイント到達可能関数にマップ	ファジング ターゲット	複雑 + 公開 + 弱いテスト

ミューテーション テストと necessist の両方が同じ本番関数にフラグを立てた場合、 相互検証済みとしてマークします — 最高信頼度の検出結果。

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

分類のためのグラフ クエリ

ミューテントごとに、それを含むグラフ ノードにマップして、フェーズ 1 の事前分析 サブグラフ (tainted、high_blast_radius、privilege_boundary) を使って分類します。 分類ロジックは呼び出し元がない → 偽陽性、特権境界 → ファジング、 高 CC + tainted → ファジング、高影響範囲 → ファジング、それ以外 → テスト カバレッジの欠落をチェックします。

references/graph-analysis.md の batch_triage 実装と ノード マッピング関数を参照してください。

---

出力形式

マークダウン レポートを生成します:

# Genotoxic 分類レポート

## 概要
- 生き残ったミューテント総数: N
- Necessist 削除総数: N
- 相互検証済み検出結果: N
- 偽陽性: N (N%)
- テスト カバレッジの欠落: N (N%)
- ファジング ターゲット: N (N%)

## 相互検証済み検出結果
| ファイル | 行 | 関数 | ミューテーション シグナル | Necessist シグナル | アクション |
|--------|-------|--------|----------------------|---------------------|---------|

## 偽陽性
| ファイル | 行 | ミューテーション | 理由 | ソース |
|--------|-------|----------|--------|--------|

## テスト カバレッジの欠落
| ファイル | 行 | 関数 | CC | 呼び出し元 | 提案されるテスト | ソース |
|--------|-------|----------|----|---------|-----------------|--------|

## ファジング ターゲット
| ファイル | 行 | 関数 | CC | エントリポイント パス | 影響範囲 | ソース |
|--------|-------|----------|----|---------------------|--------|--------|

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 にジャンプしてデシジョン ツリーを使用して 特定の参照資料を読み込みます。