Node
이 저장소에서 Node의 역할은 좁지만 중요합니다. markdownlint git 훅은
npx --no-install markdownlint-cli2를 실행하며, 이는 package.json / package-lock.json에 고정된
markdownlint-cli2 devDependency를 사용합니다. 만약 잘못된 Node가
PATH에 있으면 해당 훅이 깨지고 커밋이 차단됩니다.
WSL 비대화형 셸 트랩 (가장 자주 발생하는 문제)
로그인 셸은 프로필을 소싱하여 버전 관리자(nvm)를 로드하고 저장소의 Node를 PATH에 추가합니다.
그러나 비대화형 셸 — 스크립트, 백그라운드 작업, 헤드리스 에이전트가 실행한 git 훅 — 은 프로필을
소싱하지 않습니다. 따라서 npx/node가 Linux Node 대신 WSL 상호 운용을 통해 접근한
Windows Node 설치로 해석될 수 있습니다. markdownlint (및 모든 Node 기반 훅)은
터미널에서 수동으로 커밋할 때는 문제없지만, 스크립트나 백그라운드 작업에서만 잘못된 Node에서 실행되거나
완전히 실패합니다.
해결 방법: 스크립트나 백그라운드 작업에서 커밋 또는 푸시하기 전에 저장소의 Node를 PATH에 추가하세요.
정확한 방법은 references/wsl-node-path.md에 있습니다.
npm 위생
package-lock.json에서 재현 가능한 설치를 위해npm install대신npm ci를 사용하세요. 의존성 변경 시 lockfile을 커밋하세요.npx --no-install <tool>은 고정된 로컬 devDependency를 실행하며 네트워크에서 다른 버전을 자동으로 가져오지 않습니다.--no-install플래그를 유지하세요.- Node 사용 공간을 최소화하세요: 이 저장소는 의도적으로 하나의 devDependency만 제공합니다. 의존성 추가는 확인이 필요한 변경이며, 습관적으로 해서는 안 됩니다.