JavaScript와 네이티브 코드로 된 웹 개발 CLI를 담당 계층에서 고치기

## CLI 동작을 담당하는 계층을 찾고 전역과 로컬 경로를 따로 따라가기 편집하기 전에 요청을 해당 동작을 소유한 구성 요소에 연결한다. - JavaScript 또는 TypeScript 진입점은 상위 local CLI 동작과 package export를 소유한다. - native crate는 독립형 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 경로가 같은 사용자 명령을 모두 구현할 수 있다면 두 경로를 각각 추적한다. 한 경로를 수정했더라도 다른 경로에 불일치가 남아 있으면 수정은 완료되지 않은 것이다. 작업이 저장소 기여자 지침만 다룬다면 생성된 project guidance를 편집하지 않는다. 설명을 복제하지 말고 권위 있는 architecture 및 config document를 우선한다. ## 내장 명령과 태스크 러너의 태스크를 나눠서 다루기 도구 체인의 내장 명령과 task runner를 구분한다. 내장 test, build, lint 또는 format 명령은 함께 제공되는 구현을 호출할 수 있지만, run 명령은 같은 이름의 package script 또는 설정된 task를 실행한다. package script를 정식 run target으로 취급한다. task에 dependency, cache, command config, input tracking 또는 environment tracking이 필요할 때만 명시적인 task config를 사용한다. 하나의 task 이름에는 소유자가 하나만 있어야 한다. 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를 검토한다. - 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에서 똑같이 도는 의사 터미널 스냅샷 테스트 추가하기 새로운 command-line case와 interactive flow case를 저장소의 pseudo-terminal snapshot harness에 추가한다. 각 case를 shell string이 아니라 명시적인 argument array로 정의한다. 플랫폼별 core utility 대신 harness helper command를 사용하여 같은 fixture가 Unix와 Windows에서 동일하게 동작하게 한다. case가 local CLI, global CLI 또는 둘 다를 대상으로 하는지 선언한다. local case에는 최신 local distribution build가 필요하다. snapshot 불일치는 검토 가능한 diff와 함께 실패하고 candidate output file을 생성해야 한다. snapshot은 명시적인 record mode로만 갱신하며, 기록된 결과를 code처럼 검토한 뒤 commit한다. command UX 변경은 대상 동작과 transcript를 모두 테스트한다. install 또는 migration 동작에서는 실제 package manager 동작을 우회하지 말고, pack한 checkout을 저장소의 local registry interface를 통해 제공한다. interactive milestone과 keystroke step을 명시하여 실패가 차이가 발생한 phase를 식별할 수 있게 한다. ## 언어별 lint 규칙을 따르고 생성된 파일은 생성기로만 바꾸기 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에 언어 규칙을 중복해서 쓰지 않는다. 생성된 binding, shim, agent file, distribution, snapshot output을 명확한 소유자가 있는 artifact로 취급한다. 해당 generator 또는 명시적인 snapshot acceptance flow를 통해서만 변경한다. diff를 요청된 소유 계층으로 제한하고, 관련 없는 tracked file과 untracked file은 그대로 둔다. 생성 파일이 예상과 다르게 변하면 파생물에 patch를 적용하지 말고 source 또는 generator를 조사한다. install된 global CLI를 검증할 때는 문서화된 bootstrap 경로를 사용하고 확인된 version을 검증한다. package build가 install된 binary도 갱신했다고 추론해서는 안 된다. ## 전역 네이티브 경로와 로컬 JavaScript 경로를 비교해 디버그하기 먼저 포함된 component version을 기록하고 top-level help와 command-specific 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의 차이에 따라 달라진다면 두 경우를 모두 명시적으로 재현한다. generated output에 따라 달라진다면 source 수정이 효과 없다고 결론 내리기 전에 정확한 파생물을 다시 build한다. navigation guidance를 이용해 권위 있는 file을 찾는다. 간결한 agent guide가 자세한 architecture, migration, task 또는 snapshot documentation을 대신하게 해서는 안 된다.