trailmark-summary

Trailmark の概要

対象ディレクトリに対して trailmark analyze --language auto --summary を実行します。 これは v0.2 で安全に使えるワークフローです。概要を生成するためだけに Trailmark 0.4.0 を必須にしないでください。

使用する場面

• Vivisect Phase 0 で、分解の前に手早く構造の概要を把握する必要がある
• Galvanize Phase 1 で、検出された言語とエントリーポイントの数を確認する必要がある
• 詳細な分析に進む前に、初めて見るコードベースの概要を素早く把握する

使用しない場面

• すべてのパスを実行する完全な構造分析が必要な場合（trailmark-structural を使用）
• 詳細なコードグラフのクエリが必要な場合（メインの trailmark スキルを直接使用）
• ホットスポットスコアやテイントデータが必要な場合（trailmark-structural を使用）

却下すべき誤った合理化

誤った合理化	それが誤りである理由	必要な対応
「代わりに自分でコードを読めばよい」	手作業で読むだけでは、パーサーベースの言語検出、依存関係データ、エントリーポイントの列挙を見落とします	trailmark をインストールして実行する
「言語検出は重要ではない」	言語の選択を誤ると、分析結果が空または不完全になります	Trailmark のパーサーベースの検出、または --language auto を使用する
「一部だけの出力でも十分だ」	必須の出力 3 項目（検出された言語、エントリーポイント、依存関係）のいずれかが欠けていれば、分析は不完全です	3 項目がすべて含まれていることを確認する
「ツールがインストールされていないので、スキップする」	このスキルは trailmark を実行するために用意されています	スキップせず、インストールされていないことを報告する

使用方法

対象ディレクトリは args パラメーターで渡します。

実行手順

ステップ 1：trailmark が利用可能か確認します。

trailmark analyze --help 2>/dev/null || \
  uv run trailmark analyze --help 2>/dev/null

どちらのコマンドも動作しない場合は、「trailmark is not installed」と報告して終了します。pip install、uv pip install、git clone、その他のインストールコマンドは実行しないでください。trailmark はユーザー自身がインストールする必要があります。

インストール済みのビルドが対応している場合は、任意でバージョンを記録します。

trailmark --version 2>/dev/null || uv run trailmark --version 2>/dev/null || true

バージョンコマンドが見つからなくても失敗として扱わないでください。古い v0.2.x ビルドでも、概要を生成するワークフローには対応している場合があります。

ステップ 2：Trailmark の parse API で言語を検出します。

python3 - "{args}" <<'PY'
import json
import sys

try:
    from trailmark.parse import detect_languages  # canonical location since 0.3.x
except ModuleNotFoundError:
    # v0.2.x predates trailmark.parse; the same function lives in query.api
    from trailmark.query.api import detect_languages

print(json.dumps(detect_languages(sys.argv[1])))
PY

インポートに失敗した場合は、同じスニペットを uv run --with trailmark python - "{args}" で再実行します。結果が [] の場合は、「Trailmark found no supported languages under target」と報告して終了します。

ステップ 3：自動検出を使って概要を生成します。

trailmark analyze --language auto --summary {args} 2>&1 || \
  uv run trailmark analyze --language auto --summary {args} 2>&1

ステップ 4：出力を確認します。

出力には、次の 3 項目がすべて含まれている必要があります。

1. ステップ 2 で検出された言語
2. 概要出力の Entrypoints: 行
3. 概要出力の Dependencies: 行

いずれかが欠けている場合は、不足している項目を報告してください。出力を捏造しないでください。

検出された言語のリストと、Trailmark の概要出力全体を返します。 バージョン文字列を取得できた場合は、返すメタデータに含めてください。