JavaScriptとネイティブコードでできたWeb開発CLIを、担当する層を見つけて直す

## 直す前に、CLIの動きを担当する層と、globalとlocalの通り道を見つける 編集する前に、依頼をその動作を所有するコンポーネントへ対応付ける。 - JavaScriptまたはTypeScriptのentry pointは、上位のlocal CLI動作とpackage exportを所有する - native crateは、standalone global binary、runtime bootstrap、package manager連携、installer、migration、共有process utilityを所有する - native bindingは、local JavaScript CLIとnative command実装の間のbridgeを所有する - core packageは、組み込まれたbuild、test、documentation、packagingの機能面を提供する - リポジトリtoolingは、local registry、build helper、fixture、release supportを所有する - documentationと生成されるproject guidanceは、正本が異なる別製品として扱う global経路とlocal経路の両方が同じ利用者向けcommandを実装できる場合は、それぞれを独立して追跡する。一方の経路を直しても他方に不整合が残るなら、修正は完了していない。 依頼がリポジトリへの貢献者向けinstructionsだけを対象とする場合、生成されるproject guidanceを編集してはならない。説明を複製せず、正本のarchitecture documentとconfig documentを優先する。 ## 組み込みのコマンドとtask runnerのtaskを分けて扱う toolchainの組み込みcommandとtask runnerを区別する。組み込みのtest、build、lint、format commandは同梱された実装を呼び出す場合がある。一方、run commandは同名のpackage scriptまたは設定済みtaskを実行する。 package scriptを正式なrun targetとして扱う。dependency、cache、command config、input tracking、environment trackingが必要なtaskだけを明示的なtask configで定義する。 1つのtask名には所有元を1つだけ持たせる。package scriptとtool configの両方で同名を定義してはならない。task configは現在の正本config fileに置き、廃止済みのstandalone config formatを再導入しない。 公開test importは対応中のpackage surfaceに維持し、compatibility shimは所有元のbuild scriptから生成する。廃止済みpackageを作り直してはならず、external dependencyをlocal workspace memberだと仮定してもならない。 routingを変更する前に、command help、同梱tool version、package export、最も近いtask documentationを確認する。 ## 変更の種類に合わせて、必要なだけのテストを選ぶ 変更した動作を覆う最小の検証セットを使う。 - documentationまたはagent guidance: 参照path、command、link、whitespaceを確認する - JavaScript CLI動作: リポジトリcheck、unit test、対象packageのtestを実行する - native CLIまたはcrate動作: native check、test、lintを実行する - command outputまたはinteraction design: 対象を絞ったpseudo-terminal snapshot testを実行し、diffをreviewする - global CLI動作: local global binaryをbuildしてinstallし直し、versionと対象commandを検証する - releaseまたはpackaging動作: release buildを実行する - merge前のintegration: CLIをbootstrapし、全testを実行してrepository statusを確認する formatまたはlintによる書き換えを意図的に作業範囲へ含める場合だけ、fix modeを使う。動作を変更する場合は、編集前に最も近い既存testを探し、同じ領域へcoverageを追加する。 documentationだけの変更に無関係な広いsuiteを実行してはならない。同梱toolのdispatchが関係する場合、unit testだけを根拠にCLI routingが正しいと判断してはならない。 ## UnixとWindowsで同じに動く、疑似ターミナルのsnapshot testを足す 新しいcommand-line caseとinteractive flow caseは、リポジトリのpseudo-terminal snapshot harnessへ追加する。各caseはshell stringではなく、明示的なargument arrayで定義する。 platform固有のcore utilityではなくharnessのhelper commandを使い、同じfixtureがUnixとWindowsで同じように動作するようにする。caseがlocal CLI、global CLI、または両方のどれを対象とするか宣言する。local caseには最新のlocal distribution buildが必要である。 snapshotの不一致はreview可能なdiffとcandidate output fileを伴って失敗しなければならない。snapshotは明示的なrecord modeだけで更新し、記録した結果をcodeと同じようにreviewしてからcommitする。 command UXを変更する場合は、対象動作とそのtranscriptの両方をテストする。installまたはmigration動作では、実際のpackage managerの挙動を迂回せず、pack済みcheckoutをリポジトリのlocal registry interfaceから配信する。 interactive milestoneとkeystroke stepを明示し、失敗時にどのphaseで差異が生じたか特定できるようにする。 ## 言語ごとのlintの決まりに従い、生成ファイルはgeneratorからだけ変える native codeでは、リポジトリのlint制約、共有output helper、environment config、path handling、近接するcommand styleに従う。TypeScriptでは、正本compiler、terminal output helper、repository task configを使う。 linter、compiler config、またはsource referenceが正本である場合、貢献者向けguidanceへ言語ruleを重複して書かない。 生成されたbinding、shim、agent file、distribution、snapshot outputは、所有元があるartifactとして扱う。generatorまたは明示的なsnapshot acceptance flowだけを通じて変更する。 diffは依頼された所有層に限定し、無関係なtracked fileとuntracked fileには触れない。生成fileが予期せず変わった場合、派生物へpatchを当てるのではなくsourceまたはgeneratorを調査する。 install済みglobal CLIを検証する時は、文書化されたbootstrap経路を使い、解決されたversionを確認する。package buildによってinstall済みbinaryも更新されたと推測してはならない。 ## globalのネイティブ経路とlocalのJavaScript経路を比べて、不具合を調べる まず同梱componentのversionを記録し、top-level helpとcommand固有helpを確認する。 routingの不具合では、global native経路とlocal JavaScript＋binding経路を比較する。configの不具合では、static extractionとJavaScript resolver fallbackを比較する。package managerの不具合では、command surfaceとinstall layerの両方、および関連するterminal snapshotを確認する。 check、lint、format、type-check、testの不具合では、end-to-end commandを検証する。同梱toolのroutingにより、個別package testが通っても利用者configが気付かれないまま無視される場合がある。 失敗がlocalとglobalの違いに依存する場合は、両方を明示的に再現する。生成outputに依存する場合は、source修正が無効だと結論づける前に、対象となる派生物を正確に再buildする。 navigation guidanceを使って正本fileを見つける。簡潔なagent guideで、詳細なarchitecture、migration、task、snapshot documentationを置き換えてはならない。