コンテンツにスキップ

出力モード

codeknitは、出力先(出力モード)とエンコード方法(出力フォーマット)の2つの決定を分けています。このページでは、各オプションが存在する理由、そのコスト、および適した場面について説明します。.skt文法については、出力フォーマットリファレンスを参照してください。コマンドについては、parseコマンドガイドを参照してください。

--output-modeフラグは、directory-flat、directory-tree、inlineの3つのモードのうち1つを選択します。--formatフラグは、skt(デフォルト)またはjsonを選択します。どのモードもいずれかのフォーマットと組み合わせることができます。

この2つの選択が分かれているのは、異なる質問に答えるためです。モードは、出力がどのように分割され、ディスク上のどこに配置されるかを決定し、これは人間やLLMが読む際に重要です。フォーマットは、それを消費するのがLLMや人間の読者か、スクリプトかを決定します。

directory-flatはデフォルトのモードです。map_001.skt、map_002.sktなどの番号付きチャンクファイルを、./skeleton/(または別の出力ディレクトリを指定した場合)に書き込みます。

存在理由。 大規模なコードベースでは、1つのコンテキストウィンドウに収まるよりも多くの構造が生成されます。チャンク化により、読者は必要なファイルだけを開くことができ、すべてを読み込む必要がありません。

分割の仕組み。 codeknitは各ソースファイルのブロックをそのまま保持し、チャンクがおよそ--max-lines(デフォルト500)に達すると、ブロック間で新しいチャンクを開始します。この制限は目安であり、厳密な上限ではありません。非常に大きなブロックを持つ1つのソースファイルは、500行を超えるチャンクを生成する可能性があります。ブロックをそのまま保持することで、シンボルが同じファイル内の兄弟から分離されることはありません。

トレードオフ。 チャンクはソースパスで整理されていません。あるファイルの構造を見つけるには、チャンク内の## source-pathヘッダーを検索する必要があります。特定のファイルを頻繁に参照する場合は、directory-treeの方が適しています。

ミニファイ。 --minifyを指定すると、辞書はチャンクの隣にdict.sktとして書き込まれます。詳細はミニファイを参照してください。

directory-treeは、ソースツリーを出力ディレクトリの下にミラーリングします。各ソースファイルは、対応するパスに.sktファイルとして出力されます。

命名規則。 codeknitは、ソースファイル名の拡張子を置き換えるのではなく、完全なソースファイル名に.sktを追加します。src/foo.cはsrc/foo.c.sktになり、src/foo.hはsrc/foo.h.sktになります。このルールがないと、両方がfoo.sktにマッピングされ、衝突します。ファイルの出力が分割される場合、その部分はfoo.c_part1.skt、foo.c_part2.sktなどと命名されます。大文字小文字のみの衝突を含む、競合する出力パスは、上書きするのではなく、明確に失敗します。

flatモードとの分割の違い。 ツリーモードでは、--max-linesは各ソースチャンクの厳密な上限であり、最小値は3です。各シンボルチャンクは[symbols]と## source-pathヘッダーを繰り返すため、単独で読むことができます。エッジのみのチャンクは[edges]を持ちます。この制限は、ソースチャンクに適用され、dict.sktやwarnings.sktなどの補助ファイルには適用されません。

トレードオフ。 ツリー出力はソースと並行して簡単にナビゲートできますが、多数の小さなファイルを生成します。大規模なプロジェクトでは数千ものファイルが生成され、広範な概要を得たい読者は多くのファイルを開く必要があります。

inlineはすべてをstdoutに出力します。出力ディレクトリやステージングエリアは作成されません。

存在理由。 これは2つのケースに適しています。1つのファイルを素早く検査する場合と、出力を別のツールにパイプする場合です。ディスクに何も書き込まれない唯一のモードです。

トレードオフ。 何も分割されません。結果全体が一度にターミナルまたは消費者のコンテキストに出力されるため、数ファイルを超えるものでは読者を圧倒します。単一のファイルまたは非常に小規模なプロジェクト(およそ5ファイル未満)に適していると考えるべきです。stdoutはロールバックできないため、失敗した消費者は部分的な出力を見る可能性があります。ディレクトリモードにはこの問題はありません。

フォーマット 最適な用途 出力
skt LLMコンテキストと人間による検査 .sktファイルまたはstdout
json スクリプトおよび構造化統合 ディレクトリモードではcodeknit.json、inlineモードではstdout

sktはコンパクトで行指向です。各シンボルは1つの物理行に配置され、署名内の改行はエスケープされるため、読者は出力の一部をロードしてもその構造を壊すことがありません。これが.sktでチャンク化が機能する理由です。

jsonは、テキストではなく型付きフィールドを必要とする消費者のために存在します。これはfiles、symbols、およびエッジが含まれる場合はedgesを含む単一のドキュメントです。単一のドキュメントであるため、行数で分割されません。ディレクトリモードでは、--max-linesはJSONに影響を与えず、大規模なプロジェクトでは1つの大きなcodeknit.jsonが生成されます。

コンパクトなサンプル:

{
"files": ["app.go"],
"symbols": [
{"id": "app.go::User", "short_id": "S1", "name": "User", "file": "app.go",
"category": "type", "kind": "struct", "signature": "type User struct", "span": [3, 3]},
{"id": "app.go::Save", "short_id": "S2", "name": "Save", "file": "app.go",
"category": "callable", "kind": "function", "signature": "Save(u: S1)", "span": [5, 5]}
],
"edges": [
{"from": "app.go::Save", "from_short": "S2", "to": "app.go::User",
"to_short": "S1", "kind": "references"}
]
}
モード 最適な用途 出力
directory-flat ほとんどのプロジェクト(デフォルト) ./skeleton/map_001.skt、map_002.skt、…
directory-tree ソースと並行してナビゲート ./skeleton/<ミラーリングされたパス>.skt
inline 単一ファイル、パイプ stdout

経験則:

  • 迷ったときは、デフォルトのdirectory-flatを使用してください。
  • 単一ファイルの場合:inlineで問題ありません。
  • 数ファイルを超える場合:directory-flatまたはdirectory-treeを使用してください。
  • 大規模なコードベース:--minifyを追加してください。
  • 同じディレクトリに再実行する場合:--cleanを追加してください。

ステージング、再実行、および--clean

Section titled “ステージング、再実行、および--clean”

ディレクトリモードでは、出力ディレクトリに直接書き込むことはありません。codeknitは出力ディレクトリの隣にあるステージングディレクトリで出力を生成し、生成が成功した後にのみ公開します。失敗した実行では、以前の出力がそのまま残ります。

デフォルトでは、codeknitは選択されたフォーマットの生成済み出力が既に存在する場合、書き込みを拒否します。その理由は、シンボルID(S1、S2、…)が抽出が変更されるたびに変更される可能性があるためです。異なる実行からのチャンクを混合すると、エッジが間違ったシンボルを指すことになります。--cleanは置き換えを許可します。生成が成功した後、古い.sktファイル(SKTモード)またはcodeknit.json(JSONモード)が置き換えられます。ディレクトリ内の無関係なエントリは保持されます。そのうちの1つが生成されたパスと衝突する場合、実行は上書きするのではなく失敗します。

公開はディレクトリ固有のロックを取得し、以前の出力をバックアップし、置き換えが失敗した場合はそれを復元します。プロセスが2つのディレクトリ名変更の間で中断された場合、次の実行は何も生成する前にバックアップを復元します。これによりプロセスの失敗から回復します。ただし、ディレクトリの更新を瞬時に行うわけではありません。2つの名前変更の間には短い間隔があるため、中断のないアクセスを必要とする読者は生成と調整する必要があります。また、ストレージの障害や電源喪失からは保護されません。

出力ディレクトリとしてソースディレクトリやその祖先を選択しないでください。完全な公開保証については、解析信頼性リファレンスを参照してください。

--minifyは辞書ベースの圧縮を適用します。codeknitは、callable/methodやexportedなどの繰り返しトークンを短いコード(d0、d1、…)に置き換えます。マッピングは[dict]セクションに保存され、ディレクトリモードではdict.sktファイルになります。

節約は繰り返しから生まれます。ほとんどのシンボル行は同じカテゴリ、種類、およびプロパティを共有するため、大規模なコードベースではこれらの文字列が数千回繰り返されます。コストは間接参照です。読者は辞書を使用してコードを展開する必要があり、単一のチャンクはもはや自己完結しません。辞書は別の補助出力であるため、--max-linesにはカウントされません。

ミニファイされた出力は関係の種類をエンコードし、解決マーカーを読み取り可能な状態に保つため、unresolvedおよびambiguousエッジは区別可能なままです。小規模なプロジェクトでは節約はわずかであり、この追加ステップが価値を持つことはほとんどありません。大規模なプロジェクトでは、トークンの節約が大きくなる可能性があります。