xylem は何をしますか?
リポジトリをソースコードに基づいたマップに変換します。4つのビューを持ち、静的な2ファイルサイト(index.html と deep-view.json)として出力されます。
| ビュー | 表示内容 |
|---|---|
| Explore | システムの構成要素(コンポーネント)とその間の接続を、レイヤーごとにグループ化して表示 |
| Customer journeys | ユーザーが取れる各ジャーニーを、アーキテクチャ上でアニメーション表示:リクエスト、応答、ラベル付きハンドオフ |
| State map | マッピング範囲内のすべての宣言された状態次元、その状態、およびジャーニーが実際に取る遷移を表示 |
| Code | マッピングされた各関数をリージョン内のタイルとして表示。その関数の設計判断、呼び出しと呼び出し元、関数レベルでトレースされたジャーニーパスを表示 |
ページよりも手法が重要です。すべての主張は file:line に結び付けられます。すべての接続は実際のものです。コードで解決できない点については、推測せずにその旨をマップに明記します。
基本ルール(すべてのフェーズに適用)
- 証拠か無か。 すべてのコンポーネント、ユニット、設計判断、エッジ、状態、アクションは
file:lineを引用する必要があります。引用できない場合は、UNVERIFIEDとマークするか、省略します。これは作成者/レビューアの責務です:自動化ゲートはアーキテクチャの証拠と深いソース位置を強制しますが、すべての状態/アクションの引用や説明の意味を強制するわけではありません。 - IDを割り当て、エンティティや接続を発明しないこと。 スキャフォールドのファイル位置IDを使用します。手動で作成されたIDも一意で安定している必要があります。リージョンをまたぐエッジは、宣言されたアーキテクチャ接続を介する必要があります。接続がない場合は
diagram_gapを記録し、コードで検証してから証拠を添えて追加します。 - 正直なギャップは不可能なパスに勝る。 ジャーニーの結果がソースから明確にトレースできない場合は、
{"unavailable": "<具体的な理由>"}と記述します。成功パスを失敗結果にコピーしてはいけません。両方とも真になり得ないブランチを決して連鎖させてはいけません。 - それが何であるかを明記する。 トレースは静的なソースパスであり、実際の実行の記録ではありません。ページ内でそのようにラベル付けします。
- 読み取り専用。 ターゲットリポジトリを決して編集しないでください。すべてを
.xylem/(またはユーザーが指定したフォルダ)に書き込みます。 - プライバシー。 ユーザーが要求しない限り、リポジトリのコンテンツを外部サービスに送信しないでください。サイトはデータとオプションの動画に対して同一オリジンのリクエストのみを行います。外部リクエストは行いません。オフラインで使用するためにループバックで提供します。
出力レイアウト
.xylem/
census.json # コード内で見つかったすべての定義(scripts/census.py)
architecture.json # フェーズ 1
journeys.json # フェーズ 2
deep.json # フェーズ 3(関数レベルマップ)
validation.json # scripts/validate.py の出力
reviews/ # 相互レビューレポート(フェーズ 6)
site/ # index.html + deep-view.json (+ videos/) (scripts/build_site.py)
すべてのファイルのフォーマットは references/schemas.md にあります。JSON を書き始める前に読んでください。
フェーズとゲート
フェーズは順番に実行します。各フェーズはゲートで終了します。ゲートが合格するか、ユーザーが文書化されたギャップを受け入れるまで続行しないでください。明示的に許可されたトライアルでは、失敗したアーティファクトとログを変更せずに保持し、そのトライアルスコープ内でのみ続行します。後続の出力には暫定ラベルを付けます。構造的な合格は、完全なセマンティックカバレッジを確立するものではありません。
フェーズ 0: センサス(決定論的)
python scripts/census.py <repo> --out .xylem/census.json [--exclude dir ...]
これは、Python AST、標準ライブラリの JS/TS トークンウォーカー、およびその他のサポート言語のおおよその正規表現を使用して、名前付き定義をインベントリします。scannedFiles には定義のないソースファイルが含まれます。JS/TS は、ジェネリックなアロー、具象的な複数行/計算メソッド、オーバーロードシグネチャ、字句的な関数/クラスの所有者、正規表現リテラル、テンプレート補間をカバーします。匿名コールバックはセンサスユニットではありません。これは実際のインベントリであり、すべての言語構文の証明ではありません。完全性を主張する前に、独立したパーサーまたはソースサンプルで検証してください。後のパーセンテージはこのインベントリのみを説明します。
ゲート: センサスのカウントがリポジトリサイズに対して妥当に見えること。除外されたパスは、生成コードや node_modules など、正当化されていること。
フェーズ 1: アーキテクチャ
エントリポイント、ビルドファイル、メインモジュール、プロセス境界を読み取ります。次に architecture.json を書き込みます。
- layers: 例:shell、UI、server、domain、storage、workers、external;
- components: それぞれ
id、layer、files[]、平易な責務、およびprocessTypeを持ちます。 - connections: それぞれ
{from, to, label, kind}、kindは spawn、ipc、http、file、data、uses のいずれか。 - flows: 主要なエンドツーエンドのフローを、順序付けられたコンポーネントステップとして。
ゲート: python scripts/validate.py .xylem --only architecture が合格すること。すべての scannedFiles エントリがコンポーネントに属しているか、理由が記された architecture.meta.fileExclusions エントリがあること。証拠パスと行は証拠ルートの下に存在する必要があります。
フェーズ 2: ジャーニーと状態
journeys.json を書き込みます。UI、ルート、CLI コマンド、ジョブ、エラーパスからこれらを解決します。
- stateDimensions: すべての独立したステートマシン。
- screens: すべての画面。
- actions: 各ユーザーアクションとシステム遷移。その結果、ユーザーが表示する正確なテキスト、およびアンドゥを含みます。
- journeys: 開始状態とステップ。
すべてのアクションは、順序付けられたアーキテクチャトレース(コンポーネントと接続を交互に)を持ちます。復路には {"connection": [a, b], "direction": "reply"} を使用します。次のステップが前のステップの終了場所から始まらない場合、そのステップは transition.handoff を持ち、タイプとラベル(user、timer、queue、continuation、lifecycle、download)を伴います。ハッピーパス、アンハッピーパス、リカバリパス、エッジケースのジャーニーをカバーします。
ゲート: validate.py --only journeys が合格すること。
- すべてのジャーニーが有効な結果を経由して再生されること。
- サイレントジャンプゼロ(各ライトアップは、ワイヤー、応答、またはラベル付きハンドオフによって到達されること)。
- 孤立状態がないこと。
フェーズ 3: 関数レベルマップ(最終解決)
- センサスからドラフトマップを生成します。
python scripts/scaffold_deep.py .xylem
これは deep.json を書き込みます。ドラフトには、割り当てられたセンサスユニット、AST からの Python 設計判断、およびヒューリスティックな JS/TS の if、while、for、switch、括弧で囲まれた catch ポイントが含まれます。JS/TS は、三項演算子、計算、またはショートサーキット判断の完全なインベントリを主張しません。コメント、リテラルコンテンツ、子宣言は各ボディから除外されます。ジェネリック呼び出しは、個別の呼び出しサイト位置を保持します。呼び出しエッジは source: heuristic と confidence: name-resolved を使用します。未解決の名前はリンクとして発明されません。ソースに対して洗練します。名前解決は型解決ではありません。
2. コードを読んでドラフトを洗練します。
- ユニットごとに、名前ではなくボディから書かれた、ビジネス可読な
summary。 - すべての設計判断について、
plainな質問(「このファイルは 16 MiB より大きいですか?」)と正確なコードtest、kind(branch、calculation、loop、unconditional)、および正しい後続。returnまたはraiseはパスを終了します。try ブロックの通常の継続とエラー継続は別々であり、保留中の例外はfinallyを実行してから伝播します。確信が持てない場合は、後続をunresolvedとマークします。決してverifiedとマークしないでください。 riskタグは、既知の欠陥を直接実装する設計判断にのみ付与します。
actionTracesを書き込みます。各ジャーニーアクションと結果について、順序付けられた実行イベント{component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}。eventは、call、return、branch、async、spawn、ipc、http、file、render、unknown、throw、finally、resume のいずれかです。アクティベーションフレーム、終端イベント、サポートされる再生制限についてはスキーマを参照してください。- UI ハンドラ、ルート、ジョブなど、実際の開始点から開始します。
- 呼び出し、戻り、プロセス境界を追跡します。拒否は、実際のエラーパスをユーザーに戻るまで追跡する必要があります。「保存」や「成功」に続けてはいけません。
- パスが不明な場合は、
{"event": "unknown", "note": "..."}を出力するか、結果全体を利用不可とマークします。
大規模リポジトリ:フェーズ 3 をコード領域ごとに複数のエージェントに分割し、それぞれが同じ形式で deep-<part>.json を書き込み、scripts/merge_deep.py でマージします。ID はファイルと定義行によって調整し、名前の類似性では調整しません。
ゲート: validate.py が完全なセットで合格すること。
- すべてのセンサス定義が出力されるか、理由とともに明示的に除外されていること。出力されたカバレッジと除外の計上は別々のカウンターです。
- すべてのエッジエンドポイントが解決すること。
- すべてのリージョン間エッジが接続を介していること。
- 設計判断の後続が解決すること。
- トレース参照が有効であること。
- セレクターの一貫性: 変更されていない値に対して、アクティベーションが相互に排他的な選択を行わないこと。ソースの書き込みは値を変更できます。反復ラベルだけでは制約をリセットできません。サポートされる文法と制限はスキーマにあります。例えば、
x==='a'が yes で、その後x==='b'が yes、または値が除外されてからincludes()で必須になるなど。トレースを修正するか、unavailableに引き下げて、競合に名前を付けます。
フェーズ 4: ページの構築
python scripts/build_site.py .xylem
これにより site/index.html と site/deep-view.json が書き込まれます。動画はオプションです。videos/<journeyId>.mp4 と videos/manifest.json を .xylem/ に事前に配置します(スキーマを参照)。site/ を HTTP で提供して表示します。例:python -m http.server -d .xylem/site。file:// ページでは Code ビューのデータを読み込めません。
ゲート: ページを開き、各モードを一度確認します。
- コンソールエラーがないこと。
- 電話幅(420 px)で水平スクロールがないこと。
- キーボードとダークモードが動作すること。
フェーズ 5: オプションの実画面録画
アプリにローカルで実行できる UI がある場合は、Playwright でジャーニーを録画します。スターターは scripts/record_journey.example.mjs です。録画のルール:
- モックレスポンスなしで実際の UI を駆動します。
- ステップごとにキャプションを追加します。
- アイドル待機を高速化し、高速化をキャプションに記載します。
manifest.jsonにステップごとのatSecを記録します。- 部分的な録画は部分的なものとしてマークします。
ビューアは動画をマップに同期するため、動画が時計の役割を果たします。
フェーズ 6: 相互レビュー委員会
可能であれば、2 人の独立したレビューアを使用します。2 つの異なるモデルまたはエージェント、または少なくとも作成者の推論にアクセスできない新しいコンテキストを使用します。references/protocol.md に従います。
- 作成者は自分の作業を決して評価しません。
- レビューアはファイルとコードを受け取り、作成者の結論は受け取りません。
- レビューアは独立したチェッカーを実行し、ソースに対する主張をサンプリングします。protocol.md の単一サンプリングルール(最小値未満のすべての利用可能なアイテム)に従います。
- 所見は
reviews/<reviewer>-<round>.mdに、重大度、証拠、具体的な修正とともに記録されます。 - 受理ゲート: アーキテクチャ、ジャーニー、ディープ、ページ/データ、フリーズされたバンドルに対する明示的な ACCEPT、REJECT、または BLOCKED。重大な欠陥のみが REJECT を正当化します:誤った結論、不可能なパス、またはコアタスクのブロック。宣言された制限、正直な
unavailableマーカー、トレースの静的な性質は拒否の理由にはなりません。 - 制限付きのレビューバジェットを使用します。未解決の場合は REJECT/BLOCKED で停止し、証拠を保持します。説明ではなく、正確なビルドアーティファクトを再レビューします。
ゲート: フリーズされたバンドルのすべてのアーティファクトが独立したレビューによって受理されること。サンプリングクォータを満たすためにパスを捏造しないでください。
フェーズ 7: 公開とレポート
ユーザーにページの内容を実際の数値で伝えます。
- 関数、設計判断、ジャーニー、トレースされた結果。
- 利用できない結果の数とその理由。
- 相互レビューされた内容。
制限を率直に報告します。
スクリプト
| スクリプト | 目的 |
|---|---|
census.py | 多言語定義センサス(カバレッジの分母) |
scaffold_deep.py | センサスとアーキテクチャから関数レベルマップのドラフトを作成 |
merge_deep.py | 部分マップをマージ。ファイルと行で ID を調整 |
validate.py | すべてのゲート:スキーマ、参照、カバレッジ、サイレントジャンプ、後続、セレクターの一貫性 |
build_site.py | コンパクトな Code ビューデータをエクスポートし、シングルページサイトを構築 |
record_journey.example.mjs | 実画面ジャーニー動画のための Playwright スターター |
Python スクリプトには Python 3.9+ と標準ライブラリのみが必要です。オプションの .mjs ブラウザ/録画ヘルパーには、別途入手可能な Playwright が必要です。ページはフレームワークや外部リクエストを使用しません。