specthread 0.1.5 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +171 -66
  2. package/dist/bin/check.js +9 -34
  3. package/dist/bin/cli.js +5 -4
  4. package/dist/bin/generate.js +32 -19
  5. package/dist/bin/open-project.d.ts +5 -0
  6. package/dist/bin/open-project.js +26 -0
  7. package/dist/checks/changelog.js +5 -4
  8. package/dist/checks/headings.d.ts +0 -1
  9. package/dist/checks/headings.js +15 -6
  10. package/dist/checks/links.js +7 -4
  11. package/dist/checks/markers.d.ts +3 -1
  12. package/dist/checks/markers.js +33 -18
  13. package/dist/checks/pending.js +57 -23
  14. package/dist/checks/references.js +2 -2
  15. package/dist/checks/sections.js +3 -6
  16. package/dist/checks/style.d.ts +0 -8
  17. package/dist/checks/style.js +23 -43
  18. package/dist/checks/timestamps.js +5 -5
  19. package/dist/checks/toc.js +4 -6
  20. package/dist/commands/config-template.d.ts +8 -0
  21. package/{scaffold/config.jsonc → dist/commands/config-template.js} +48 -40
  22. package/dist/commands/init.js +121 -47
  23. package/dist/commands/upgrade-prompt.d.ts +12 -0
  24. package/dist/commands/upgrade-prompt.js +147 -0
  25. package/dist/config-loader.d.ts +44 -1
  26. package/dist/config-loader.js +219 -36
  27. package/dist/config.schema.d.ts +16 -35
  28. package/dist/config.schema.js +1 -7
  29. package/dist/constants/docs.d.ts +8 -4
  30. package/dist/constants/docs.js +8 -5
  31. package/dist/constants/exit.d.ts +12 -0
  32. package/dist/constants/exit.js +12 -0
  33. package/dist/constants/paths.d.ts +25 -0
  34. package/dist/constants/paths.js +25 -0
  35. package/dist/constants/patterns.d.ts +13 -6
  36. package/dist/constants/patterns.js +16 -6
  37. package/dist/constants/rules.d.ts +7 -3
  38. package/dist/constants/rules.js +7 -3
  39. package/dist/gen/pending-section.js +20 -16
  40. package/dist/gen/references.js +13 -9
  41. package/dist/gen/summary.d.ts +1 -1
  42. package/dist/gen/summary.js +11 -7
  43. package/dist/gen/toc.js +5 -2
  44. package/dist/run-check.d.ts +5 -0
  45. package/dist/run-check.js +35 -0
  46. package/dist/types.d.ts +6 -4
  47. package/dist/utils/anchor.d.ts +1 -1
  48. package/dist/utils/anchor.js +1 -1
  49. package/dist/utils/ignore.d.ts +2 -8
  50. package/dist/utils/ignore.js +23 -6
  51. package/dist/utils/parse.d.ts +6 -6
  52. package/dist/utils/parse.js +18 -27
  53. package/dist/utils/path-match.d.ts +19 -0
  54. package/dist/utils/path-match.js +27 -0
  55. package/dist/utils/report.d.ts +1 -7
  56. package/dist/utils/report.js +10 -3
  57. package/dist/utils/resolve.d.ts +15 -5
  58. package/dist/utils/resolve.js +63 -25
  59. package/dist/utils/root.d.ts +2 -0
  60. package/dist/utils/root.js +19 -0
  61. package/dist/utils/scan.d.ts +1 -3
  62. package/dist/utils/scan.js +28 -26
  63. package/dist/utils/scope.d.ts +37 -11
  64. package/dist/utils/scope.js +60 -24
  65. package/package.json +3 -3
  66. package/scaffold/AGENTS.md +4 -6
  67. package/scaffold/claude/skills/{check.md → check/SKILL.md} +6 -3
  68. package/scaffold/claude/skills/{gen.md → gen/SKILL.md} +5 -3
  69. package/scaffold/claude/skills/{plan-close.md → plan-close/SKILL.md} +1 -0
  70. package/scaffold/claude/skills/{plan-open.md → plan-open/SKILL.md} +1 -0
  71. package/scaffold/claude/skills/{plan-run.md → plan-run/SKILL.md} +1 -0
  72. package/scaffold/pending.md +1 -1
  73. package/scaffold/project.md +1 -1
  74. package/scaffold/rules.md +28 -27
  75. package/scaffold/templates/plan.md +3 -7
package/README.md CHANGED
@@ -1,76 +1,166 @@
1
1
  # specthread
2
2
 
3
- Spec-Driven Development (SDD) 도구. 문서가 단일 진실 원천이고, 검사/생성 도구가 문서 체계를 유지한다.
3
+ Spec-Driven Development(SDD) 도구입니다. 문서를 단일 정본으로 관리하고, 문서 형식 규칙과 그 규칙을 검사·생성하는 도구를 함께 제공합니다.
4
+
5
+ AI 와 함께 코드를 작성하면 문서와 코드가 쉽게 어긋납니다. specthread 는 문서 형식을 규칙으로 정하고, 규칙 위반과 생성물의 불일치를 `check` 로 검출합니다. 목차·참조 절처럼 다른 내용에서 만들 수 있는 부분은 `gen` 이 생성합니다.
4
6
 
5
7
  ## 시작하기
6
8
 
7
9
  ```bash
8
- npm install -g specthread
9
- specthread init
10
- specthread check
10
+ npm install -D specthread
11
+ npx specthread init
12
+ npx specthread check
11
13
  ```
12
14
 
13
- 프로젝트 로컬로 쓰려면 `npm install -D specthread` 후 `npx specthread`로 실행한다.
15
+ 전역으로 설치하려면 `npm install -g specthread` 후 `specthread` 로 실행합니다.
14
16
 
15
- `init`이 프로젝트에 SDD 체계를 세팅한다:
17
+ ## init 이 만드는 파일
16
18
 
17
19
  ```
18
- specthread/ ← 문서 규칙·설정·미확정 사항
19
- config.jsonc
20
- rules.md
21
- project.md
22
- pending.md
23
- templates/ ← 문서 골격 (수정 가능, check 대상)
20
+ specthread/
21
+ config.jsonc 설정
22
+ rules.md 문서 형식 규칙
23
+ project.md 설정값의 맥락과 근거
24
+ pending.md 미확정 사항 정본
25
+ templates/ 문서 골격 (검사 대상 아님)
24
26
  spec.md
25
27
  plan.md
26
- AGENTS.md ← AI 도구 진입점
27
- CLAUDE.md ← Claude Code용 (@AGENTS.md)
28
- .claude/skills/ ← Claude Code 스킬
28
+ AGENTS.md AI 도구 진입점
29
+ CLAUDE.md Claude Code 용 (@AGENTS.md)
30
+ .claude/skills/ Claude Code 스킬
29
31
  ```
30
32
 
31
- 기존 `AGENTS.md`가 있으면 `<!-- specthread:start/end -->` 마커로 섹션만 삽입한다. 기존 `CLAUDE.md`가 있으면 `@AGENTS.md` 줄만 추가한다.
33
+ 기존 `AGENTS.md` 가 있으면 `<!-- specthread:start -->` 와 `<!-- specthread:end -->` 표식 사이에만 specthread 섹션을 넣습니다. 기존 `CLAUDE.md` 에는 `@AGENTS.md` 줄만 추가하고, `.gitignore` 에는 개인 설정 파일 경로를 추가합니다.
34
+
35
+ | 종류 | 파일 | `init` | `init --force` |
36
+ | ---- | ---- | ------ | -------------- |
37
+ | 패키지 파일 | `rules.md`, `templates/`, `.claude/skills/` | 없을 때만 생성 | 새 버전으로 덮어씀 |
38
+ | 사용자 파일 | `config.jsonc`, `project.md`, `pending.md` | 없을 때만 생성 | 유지 |
39
+ | 병합 | `AGENTS.md`(표식 사이), `CLAUDE.md`, `.gitignore` | 병합 | 병합 |
40
+
41
+ 설정을 처음 상태로 되돌리려면 `config.jsonc` 를 지우고 `init` 을 다시 실행합니다.
32
42
 
33
43
  ## 명령어
34
44
 
35
45
  ```bash
36
46
  npx specthread init [--tools claude,cursor] # 프로젝트 초기화
37
- npx specthread init --force # scaffold 파일을 최신으로 덮어쓰기
47
+ npx specthread init --force # 패키지 파일 갱신, 업데이트 프롬프트 출력
38
48
  npx specthread check # 문서 정합성 검사
39
- npx specthread gen # 참조 절·목차·요약 표 미리보기
40
- npx specthread gen --write # 실제 적용
49
+ npx specthread gen # 생성 결과 미리보기
50
+ npx specthread gen --write # 생성 결과 적용
41
51
  ```
42
52
 
43
53
  ### check
44
54
 
45
- 28개 규칙으로 문서 형식을 검사한다. 목차, 헤딩, 링크, 참조 절, 변경 이력, 미확정 마커 등.
55
+ 30개 규칙으로 문서 형식을 검사합니다. 하위 디렉터리에서 실행해도 `specthread/config.jsonc` 가 있는 디렉터리를 루트로 삼아 같은 범위를 검사합니다.
56
+
57
+ | 종료 코드 | 의미 |
58
+ | --------- | ---- |
59
+ | 0 | 지적 없음 |
60
+ | 1 | 지적 있음 |
61
+ | 2 | 실행 실패 (설정 파일 없음, 설정 오류, 모르는 명령) |
46
62
 
47
63
  ### gen
48
64
 
49
- 본문 링크와 헤딩을 기반으로 목차·참조 절·미확정 사항 요약을 생성한다. `--write` 없이 실행하면 변경 대상만 보여준다.
65
+ 본문 링크, 헤딩, `pending.md` 항목에서 아래 내용을 생성합니다. `--write` 없이 실행하면 바뀔 파일 목록만 출력합니다.
66
+
67
+ | 생성 대상 | 내용 | 조건 |
68
+ | --------- | ---- | ---- |
69
+ | 목차 | 제목 아래 `##` 헤딩 목록 | 항상 |
70
+ | 참조 절 | 본문 링크를 대상별로 모은 `## 참조` | `features.references` |
71
+ | 미확정 사항 절 | `pending.md` 항목 중 그 문서를 참조하는 것 | `features.markers`, 절이 이미 있는 문서만 |
72
+ | 요약 표 | `pending.md` 각 절 첫 부분의 항목 표 | `features.markers` |
73
+
74
+ 꼬리 절(참조 → 미확정 사항 → 변경 이력) 순서가 어긋난 문서는 생성하지 않고 건너뜁니다.
75
+
76
+ ### init --force
77
+
78
+ `rules.md`, 템플릿, 스킬을 새 버전으로 바꾸고, 남은 정리를 AI 에게 맡길 업데이트 프롬프트를 출력합니다. 프롬프트에는 실행할 때 감지한 항목만 포함됩니다.
79
+
80
+ | 감지 항목 | 프롬프트 단계 |
81
+ | --------- | ------------- |
82
+ | 내용이 바뀐 패키지 파일 | git diff 로 사용자 수정분 확인 |
83
+ | 표식 없는 이전 형식 `AGENTS.md` | 표식으로 감싼 뒤 `init` 재실행 |
84
+ | 끝 표식이 없는 `AGENTS.md` | 끝 표식 추가 후 `init` 재실행 |
85
+ | 이전 경로의 스킬 파일 (`.claude/skills/<이름>.md`) | 새 스킬과 비교 후 삭제 |
86
+ | 설정 파일의 제거된 키 (주석 포함) | 키 삭제 |
87
+ | 사용자 파일의 옛 문구 | 현재 문구로 교체 |
88
+ | `path` 에서 빠진 기본 경로 | 의도 확인 |
89
+
90
+ 검사(`check`)와 생성(`gen --write`) 단계는 항상 포함됩니다. Claude Code 에서 `! npx specthread init --force` 로 실행하면 출력이 대화에 바로 포함됩니다.
91
+
92
+ ## 검사 규칙
93
+
94
+ 규칙 ID 는 `<군>/<검사>` 형식입니다. 규칙 본문은 `specthread/rules.md` 에 있고, 각 절에 해당 규칙 ID 가 적혀 있습니다.
95
+
96
+ | 군 | 수 | 검사 내용 |
97
+ | -- | -- | --------- |
98
+ | `heading` | 4 | 제목 1개, 꼬리 절 이름·번호·순서 |
99
+ | `toc` | 2 | 목차 누락, 헤딩과 불일치 |
100
+ | `link` | 2 | 링크 대상 파일, 앵커 |
101
+ | `section-ref` | 5 | `§N` 대상 절 존재, 앵커 링크 사용, 문서명 해소 |
102
+ | `reference` | 2 | 참조 절 누락, 본문 링크와 불일치 |
103
+ | `changelog` | 1 | 변경 이력 날짜 순서 |
104
+ | `timestamp` | 1 | 본문의 날짜 |
105
+ | `marker` | 3 | 마커와 `pending.md` 항목 대조, 종류 등록 여부 |
106
+ | `pending` | 9 | 항목 형식, 시점 표기, 요약 표·미확정 사항 절 최신 여부 |
107
+ | `style` | 1 | 코드의 규칙 ID 가 `rules.md` 에 선언됐는지 |
108
+
109
+ 검사를 끄는 방법:
110
+
111
+ - 기능 단위: `features.markers`, `features.references`
112
+ - 경로 단위: `skipCheck`
113
+ - 줄 단위: 같은 줄이나 바로 윗줄의 주석에 `@specthread-ignore`
50
114
 
51
115
  ## 설정
52
116
 
53
- `specthread/config.jsonc`로 프로젝트별 동작을 제어한다. 개인 오버라이드는 `specthread/config.local.jsonc` (gitignore 대상).
117
+ `specthread/config.jsonc` 로 프로젝트별 동작을 정합니다. 개인 설정은 `specthread/config.local.jsonc` 에 두고, 이 파일은 `init` 이 `.gitignore` 에 추가합니다.
54
118
 
55
119
  ```
56
- Core defaults (도구 내부 기본값)
57
- ↓ deep merge
58
- specthread/config.jsonc (프로젝트 공유)
59
- ↓ deep merge
60
- specthread/config.local.jsonc (개인)
120
+ 도구 기본값 → specthread/config.jsonc → specthread/config.local.jsonc
61
121
  ```
62
122
 
63
- 설정이 없으면 기본값으로 동작한다. init이 생성하는 `config.jsonc`에 모든 옵션이 주석으로 설명되어 있다.
123
+ - 배열과 `path`: 통째로 교체
124
+ - 그 밖의 객체: 키 단위 병합
125
+ - 잘못된 값: 파일과 키를 출력하고 종료 코드 2
126
+ - 제거된 키, 모르는 키: 경고만 출력
127
+
128
+ | 키 | 역할 | 기본값 |
129
+ | -- | ---- | ------ |
130
+ | `path` | 스캔 대상 경로 (키는 자유 라벨) | `docs/`, `specthread/` |
131
+ | `fileKinds` | 확장자별 파일 종류 (`doc` / `source`) | `doc` 은 `.md`, `source` 는 코드·데이터 확장자 |
132
+ | `features` | 기능 켜기·끄기 (`markers`, `references`) | 모두 `true` |
133
+ | `markers` | 마커 종류(`types`), 해결 예정 라벨(`timepoints`) | `["system"]`, `[]` |
134
+ | `ignoreDocNames` | 절 참조 해소에서 제외할 문서 이름 | `[]` |
135
+ | `skipCheck` | 검사·생성을 건너뛸 경로 | `[]` |
136
+ | `skipRefs` | 참조 절을 만들지 않을 경로 | `[]` |
137
+ | `work` | 작업 문서 폴더 | `docs/work/` |
64
138
 
65
- | 키 | 역할 |
66
- | ----------- | ----------------------------------------------- |
67
- | `path` | 스캔 대상 경로 (자유 KV) |
68
- | `fileKinds` | 확장자 → 종류 매핑 (`doc` / `source`) |
69
- | `features` | 기능 플래그 (`markers`, `emDash`, `references`) |
70
- | `markers` | 마커 종류·시점 라벨 |
71
- | `docTypes` | 경로별 템플릿·프론트매터 스키마 |
72
- | `skipCheck` | 검사 건너뛸 경로 |
73
- | `skipRefs` | 참조 절 생성 건너뛸 경로 |
139
+ `init` 이 만드는 `config.jsonc` 에 모든 옵션의 설명이 주석으로 적혀 있습니다. `fileKinds.doc` 에 확장자(예: `.mdx`)를 추가하면 그 파일도 문서로 검사하고 절 참조 대상으로 해소합니다.
140
+
141
+ `specthread/` 아래 규칙·미확정 사항·프로젝트 문서의 경로는 고정입니다. 템플릿과 설정 파일은 항상 검사에서 제외됩니다.
142
+
143
+ ## 문서 체계
144
+
145
+ `specthread/rules.md` 가 문서 형식 규칙의 정본입니다. 주요 규칙은 아래와 같습니다.
146
+
147
+ - 제목 바로 아래 목차
148
+ - 본문 절은 `§N-M` 번호 체계, 다른 문서의 절은 앵커 링크로 참조
149
+ - 문서 끝 꼬리 절은 참조 → 미확정 사항 → 변경 이력 순서
150
+ - 날짜·버전 정보는 본문이 아닌 변경 이력에 기록
151
+ - 빈 섹션은 `해당 없음 - <이유>`
152
+
153
+ ### 미확정 사항
154
+
155
+ 작업 중 정하지 못한 것은 작업을 멈추지 않고 마커로 표시합니다. 같은 ID 를 세 곳에서 관리하고, 정본은 `pending.md` 하나입니다.
156
+
157
+ | 위치 | 표기 | 작성 |
158
+ | ---- | ---- | ---- |
159
+ | 코드·문서의 발생 지점 | `PENDING::<종류>::<slug>` | 사람 |
160
+ | `specthread/pending.md` | `` ### `[<종류>::<slug>]` 제목 `` | 사람 |
161
+ | 각 문서의 `## 미확정 사항` | 그 문서를 참조하는 항목 목록 | `gen` |
162
+
163
+ JSON 처럼 주석을 쓸 수 없는 파일에서는 `"_pending": "<종류>::<slug>"` 필드로 표기합니다. `check` 는 마커와 항목을 양방향으로 대조해서, 항목 없는 마커(`marker/orphan`)와 마커 없는 항목(`marker/unmarked`)을 지적합니다.
74
164
 
75
165
  ## SDD 작업 흐름
76
166
 
@@ -78,65 +168,80 @@ specthread/config.local.jsonc (개인)
78
168
  스펙 확인 → 현황 점검(check) → 계획 수립 → 구현 → 검증(check) → 문서 갱신
79
169
  ```
80
170
 
81
- 구현 전에 spec을 읽고, 구현 후에 spec을 갱신한다. 진행 중 모호함을 발견하면 `PENDING` 마커를 남기고 작업을 계속한다.
171
+ 구현 전에 spec 을 읽고, 구현 후에 spec 을 갱신합니다. 작업 계획은 `docs/work/` 에 plan 문서로 작성하고, 작업이 끝나면 내용을 spec 에 반영한 뒤 plan 문서를 삭제합니다.
82
172
 
83
- ### 예시: 기존 인증 spec에 소셜 로그인 추가
173
+ ### 예시: 기존 인증 spec 에 소셜 로그인 추가
84
174
 
85
- `docs/spec/auth.md`가 이미 있는 프로젝트에서 소셜 로그인을 추가한다:
175
+ `docs/spec/auth.md` 가 있는 프로젝트에서 소셜 로그인을 추가하는 경우입니다.
86
176
 
87
177
  ```
88
178
  You: 소셜 로그인 기능 계획 세워줘
89
- AI: docs/spec/auth.md 를 읽고, plan 템플릿 기반으로
90
- docs/work/social-login.md 생성.
91
- 목표, 작업 단계, 영향 파일을 함께 채운다.
179
+ AI: docs/spec/auth.md 확인 후 plan 템플릿으로 docs/work/social-login.md 작성.
180
+ 목표, 작업 단계, 영향 파일 포함.
92
181
  문서 정합성 검사 통과.
93
182
  ```
94
183
 
95
184
  ```
96
185
  You: 진행해줘
97
186
  AI: 작업 단계 1 "OAuth 프로바이더 연동" 구현.
98
- 세션 관리 방식이 미확정이라
99
- PENDING::design::oauth-session 마커를 남긴다.
187
+ 세션 관리 방식이 미정이라 PENDING::design::oauth-session 마커 추가.
100
188
  단계 상태를 "완료"로 갱신.
101
189
  ```
102
190
 
103
191
  ```
104
192
  You: 전부 끝났어, 정리해줘
105
- AI: 종료 게이트 점검 후,
106
- 작업 내용을 docs/spec/auth.md §3 에 흡수.
193
+ AI: 종료 게이트 점검 후 작업 내용을 docs/spec/auth.md §3 에 반영.
107
194
  docs/work/social-login.md 삭제.
108
195
  문서 정합성 검사 통과.
109
196
  ```
110
197
 
111
- 결과: `docs/spec/auth.md`에 소셜 로그인 절이 추가되고, work 문서는 사라진다. spec이 항상 현재 시스템의 정본으로 남는다.
112
-
113
- AI는 작업 중에 `check`와 `gen`을 자동으로 호출한다. `AGENTS.md`가 이 워크플로우를 AI에게 전달하고, `check`가 문서와 코드의 어긋남을 잡는다.
198
+ 작업이 끝나면 `docs/spec/auth.md` 에 소셜 로그인 절이 추가되고 plan 문서는 삭제됩니다. spec 은 항상 현재 시스템을 설명하는 정본으로 유지됩니다.
114
199
 
115
200
  ## AI 도구 지원
116
201
 
117
- `AGENTS.md`가 본체. 대부분의 AI 코딩 도구가 이 파일을 읽는다.
202
+ `AGENTS.md` 가 AI 도구의 진입점입니다. 대부분의 AI 코딩 도구가 이 파일을 읽습니다.
203
+
204
+ | 도구 | 동작 |
205
+ | ---- | ---- |
206
+ | Claude Code | `CLAUDE.md` 의 `@AGENTS.md` 로 읽음 |
207
+ | Cursor / Copilot / Codex / Gemini | `AGENTS.md` 를 직접 읽음 |
208
+
209
+ `--tools claude`(기본값)로 init 하면 Claude Code 스킬이 함께 설치됩니다.
210
+
211
+ | 스킬 | 역할 |
212
+ | ---- | ---- |
213
+ | `/check` | 문서 검사 실행, 결과 해석 |
214
+ | `/gen` | 생성 결과 미리보기, 승인 후 적용 |
215
+ | `/plan-open` | 작업 계획 문서 작성·검수·확정 |
216
+ | `/plan-run` | 계획에 따른 실행과 기록 |
217
+ | `/plan-close` | 완료된 작업을 spec 에 반영, plan 문서 삭제 |
118
218
 
119
- | 도구 | 동작 |
120
- | --------------------------------- | -------------------------------------- |
121
- | Claude Code | `CLAUDE.md`의 `@AGENTS.md`가 자동 확장 |
122
- | Cursor / Copilot / Codex / Gemini | `AGENTS.md`를 네이티브로 읽음 |
219
+ 스킬 없이 자연어로 요청해도 됩니다. `AGENTS.md` 에 작업 흐름이 적혀 있어서 AI 가 같은 순서로 진행합니다.
220
+
221
+ ## 버전 올리기
222
+
223
+ ```bash
224
+ npm install -D specthread@latest
225
+ npx specthread init --force
226
+ ```
123
227
 
124
- `--tools claude` (기본값)로 init하면 Claude Code 스킬이 함께 설치된다:
228
+ 출력된 업데이트 프롬프트를 AI 에게 전달하면 AI 가 남은 정리를 진행합니다. `init --force` 는 패키지 파일만 바꾸고 사용자 파일은 그대로 둡니다. `rules.md` 나 템플릿을 직접 고쳐 썼다면, 실행 전에 커밋해 두어야 바뀐 내용을 diff 로 확인할 수 있습니다.
125
229
 
126
- | 스킬 | 역할 |
127
- | ------------- | ----------------------------- |
128
- | `/check` | 문서 검사 실행 + 결과 해석 |
129
- | `/gen` | 참조 절·목차 생성 + 적용 안내 |
130
- | `/plan-open` | 작업 계획 문서 작성·검수·확정 |
131
- | `/plan-run` | 계획에 따라 실행·기록 |
132
- | `/plan-close` | 완료된 작업을 spec에 흡수 |
230
+ ### 0.2.0 에서 바뀐 동작
133
231
 
134
- 스킬 없이 자연어로 같은 작업을 요청해도 된다. `AGENTS.md`가 AI에게 워크플로우를 알려주기 때문이다. 스킬은 자주 쓰는 흐름의 단축키다.
232
+ | 변경 | 영향 |
233
+ | ---- | ---- |
234
+ | `locale`, `rules`, `pending`, `project`, `features.emDash` 키 제거 | 남아 있으면 경고만 출력 |
235
+ | `path` 통째 교체 | 일부 키만 적으면 기본 `docs/`, `specthread/` 스캔이 빠짐 |
236
+ | 종료 코드 2 | 설정 파일이 없거나 읽지 못할 때, 모르는 명령일 때 |
237
+ | 규칙 추가 | `heading/tail-order`, `marker/unknown-type`, `pending/unknown-timepoint` |
238
+ | em dash 검사 제거 | `style/em-dash` 없음 |
239
+ | 스킬 경로 | `.claude/skills/<이름>/SKILL.md`. 옛 파일은 지우지 않고 안내 |
135
240
 
136
241
  ## 요구 사항
137
242
 
138
- - Node.js >= 18.0.0
139
- - 외부 의존성 없음 (zero-dependency)
243
+ - Node.js 18 이상
244
+ - 외부 의존성 없음
140
245
 
141
246
  ## 라이선스
142
247
 
package/dist/bin/check.js CHANGED
@@ -1,26 +1,12 @@
1
1
  /**
2
- * 문서 검사기 진입점. `pnpm docs:check`
3
- *
4
- * `pnpm test` 와 분리해 둔다 - 실 문서 재편이 끝나기 전에는 목차·참조 절 지적이
5
- * 대량으로 남으므로, 4 smoke 에 넣으면 게이트가 상시 red 가 되어 신호 기능을 잃는다.
2
+ * 문서 검사기 진입점. `specthread check`
6
3
  */
7
- import { loadConfig } from '../config-loader.js';
4
+ import { runCheck } from '../run-check.js';
8
5
  import { buildIndex } from '../utils/scan.js';
9
- import { checkLinks } from '../checks/links.js';
10
- import { checkSectionRefs } from '../checks/sections.js';
11
- import { checkChangeLog } from '../checks/changelog.js';
12
- import { checkHeadings } from '../checks/headings.js';
13
- import { checkToc } from '../checks/toc.js';
14
- import { checkReferences } from '../checks/references.js';
15
- import { checkTimestamps } from '../checks/timestamps.js';
16
- import { checkPending } from '../checks/pending.js';
17
- import { checkMarkers } from '../checks/markers.js';
18
- import { checkRuleDeclared, checkStyle } from '../checks/style.js';
19
- import { isIgnored } from '../utils/ignore.js';
20
6
  import { report } from '../utils/report.js';
21
- import { isWorkExempt } from '../utils/scope.js';
22
- const config = loadConfig();
23
- const index = buildIndex(config);
7
+ import { openProject } from './open-project.js';
8
+ const { root, config } = openProject();
9
+ const index = buildIndex(root, config);
24
10
  // 색인 규모를 먼저 찍는다. 지적 수만 보면 검사가 실제로 대상을 훑었는지 알 수 없다
25
11
  const counts = { doc: 0, source: 0 };
26
12
  let headings = 0;
@@ -39,6 +25,9 @@ for (const f of index.files.values()) {
39
25
  let ignoredLines = 0;
40
26
  for (const f of index.files.values())
41
27
  ignoredLines += f.ignored.size;
28
+ if (counts.doc === 0) {
29
+ console.warn('[specthread] 색인한 문서가 0 건이다. config.path 를 확인한다');
30
+ }
42
31
  const summary = {
43
32
  title: '색인',
44
33
  lines: [
@@ -48,18 +37,4 @@ const summary = {
48
37
  `인라인 억제 ${ignoredLines}`,
49
38
  ],
50
39
  };
51
- const { features } = config;
52
- const findings = [
53
- ...checkHeadings(index),
54
- ...checkToc(index),
55
- ...(features.references ? checkReferences(index) : []),
56
- ...checkLinks(index),
57
- ...checkSectionRefs(index),
58
- ...checkChangeLog(index),
59
- ...checkTimestamps(index),
60
- ...(features.markers ? checkPending(index) : []),
61
- ...(features.markers ? checkMarkers(index) : []),
62
- ...(features.emDash ? checkStyle(index) : []),
63
- ...checkRuleDeclared(index),
64
- ].filter((f) => !isWorkExempt(f, index.config) && !isIgnored(index, f));
65
- process.exit(report(findings, summary));
40
+ process.exit(report(runCheck(index), summary));
package/dist/bin/cli.js CHANGED
@@ -1,4 +1,5 @@
1
1
  #!/usr/bin/env node
2
+ import { EXIT } from "../constants/exit.js";
2
3
  const [command, ...rest] = process.argv.slice(2);
3
4
  const usage = `specthread - Spec-Driven Development (SDD) 도구
4
5
 
@@ -6,8 +7,9 @@ const usage = `specthread - Spec-Driven Development (SDD) 도구
6
7
 
7
8
  commands:
8
9
  init [--tools claude,cursor] 프로젝트에 SDD 체계 초기화
9
- init --force scaffold 파일을 최신으로 덮어쓰기
10
- check 문서 정합성 검사 (28개 규칙)
10
+ init --force 패키지 파일(rules·템플릿·스킬)을 새 버전으로 갱신하고
11
+ 남은 정리를 위한 업데이트 프롬프트 출력
12
+ check 문서 정합성 검사 (30개 규칙)
11
13
  gen [--write] 참조 절·목차·미확정 사항 요약 생성
12
14
  help 이 도움말 표시
13
15
 
@@ -36,8 +38,7 @@ const run = async () => {
36
38
  break;
37
39
  default:
38
40
  console.log(usage);
39
- process.exit(command === undefined ? 0 : 1);
41
+ process.exit(command === undefined ? EXIT.OK : EXIT.FAILURE);
40
42
  }
41
43
  };
42
44
  run();
43
- export {};
@@ -1,40 +1,48 @@
1
1
  /**
2
- * 생성기 진입점. `pnpm docs:generate` (미리보기) / `--write` (적용)
2
+ * 생성기 진입점. `specthread gen` (미리보기) / `--write` (적용)
3
3
  *
4
4
  * 기본이 미리보기다. 문서를 고치는 도구가 확인 없이 쓰면 되돌리기가 어렵다.
5
5
  */
6
6
  import { writeFileSync } from "node:fs";
7
7
  import { join } from "node:path";
8
- import { loadConfig } from "../config-loader.js";
9
- import { buildIndex, REPO_ROOT } from "../utils/scan.js";
10
- import { isTargetDoc } from "../utils/scope.js";
8
+ import { buildIndex } from "../utils/scan.js";
9
+ import { groupAllowed, isDoc, tailOrderOk } from "../utils/scope.js";
11
10
  import { applyToc } from "../gen/toc.js";
12
11
  import { applyReferences } from "../gen/references.js";
13
12
  import { applySummary } from "../gen/summary.js";
14
13
  import { applyPendingSection } from "../gen/pending-section.js";
14
+ import { openProject } from "./open-project.js";
15
+ const write = process.argv.includes("--write");
16
+ const { root, config } = openProject();
17
+ const { features } = config;
15
18
  /**
16
19
  * 한 문서에 걸 생성기 목록. **문서 아래쪽을 고치는 것부터** 둔다.
17
20
  *
18
- * 색인의 줄 번호는 원본 기준이라, 위쪽을 먼저 고치면 아래쪽 생성기가 밀린 자리를
21
+ * 색인의 줄 번호는 원본 기준이라, 위쪽을 먼저 고치면 아래쪽 생성기가 밀린 줄을
19
22
  * 가리킨다. 반대 순서면 앞 생성기가 건드린 범위가 뒤 생성기의 범위 밖이라 안전하다.
20
23
  */
21
- const write = process.argv.includes("--write");
22
- const config = loadConfig();
23
- const { features } = config;
24
- const GENERATORS = [
25
- ...(features.markers ? [applyPendingSection] : []),
26
- ...(features.references ? [applyReferences] : []),
27
- ...(features.markers ? [applySummary] : []),
28
- applyToc,
24
+ const STEPS = [
25
+ ...(features.markers ? [{ apply: applyPendingSection, group: "pending" }] : []),
26
+ ...(features.references ? [{ apply: applyReferences, group: "reference" }] : []),
27
+ ...(features.markers ? [{ apply: applySummary, group: "pending" }] : []),
28
+ { apply: applyToc, group: "toc" },
29
29
  ];
30
- const index = buildIndex(config);
31
- const files = index.files.values();
30
+ const index = buildIndex(root, config);
32
31
  const changed = [];
33
- for (const file of files) {
34
- if (!isTargetDoc(file, index.config))
32
+ const skipped = [];
33
+ for (const file of index.files.values()) {
34
+ if (!isDoc(file))
35
35
  continue;
36
+ const steps = STEPS.filter((s) => groupAllowed(file.path, s.group, config));
37
+ if (steps.length === 0)
38
+ continue;
39
+ // 아래쪽부터 고치는 순서가 꼬리 절 순서를 전제한다. 어긋나면 엉뚱한 범위를 덮어쓴다
40
+ if (!tailOrderOk(file.headings)) {
41
+ skipped.push(file.path);
42
+ continue;
43
+ }
36
44
  let next = file.lines;
37
- for (const apply of GENERATORS) {
45
+ for (const { apply } of steps) {
38
46
  next = apply(file, next, index) ?? next;
39
47
  }
40
48
  // 바꿀 것이 없는 문서는 목록에 올리지 않는다
@@ -42,7 +50,7 @@ for (const file of files) {
42
50
  continue;
43
51
  changed.push(file.path);
44
52
  if (write) {
45
- writeFileSync(join(REPO_ROOT, file.path), next.join("\n"), "utf8");
53
+ writeFileSync(join(root, file.path), next.join("\n"), "utf8");
46
54
  }
47
55
  }
48
56
  const mode = write ? "적용" : "미리보기";
@@ -50,6 +58,11 @@ console.log(`문서 생성 ${mode} - ${changed.length} 건`);
50
58
  for (const path of changed) {
51
59
  console.log(` ${path}`);
52
60
  }
61
+ if (skipped.length > 0) {
62
+ console.log(`\n꼬리 절 순서가 어긋나 건너뜀 - ${skipped.length} 건 (heading/tail-order)`);
63
+ for (const path of skipped)
64
+ console.log(` ${path}`);
65
+ }
53
66
  if (!write && changed.length > 0) {
54
67
  console.log("\n실제로 쓰려면 --write");
55
68
  }
@@ -0,0 +1,5 @@
1
+ import type { SpecthreadConfig } from "../config.schema.ts";
2
+ export declare const openProject: () => {
3
+ root: string;
4
+ config: SpecthreadConfig;
5
+ };
@@ -0,0 +1,26 @@
1
+ /**
2
+ * check·gen 공통 시작 - 루트를 찾고 설정을 읽는다. 실패하면 `EXIT.FAILURE` 로 끝낸다.
3
+ */
4
+ import { ConfigError, loadConfig } from "../config-loader.js";
5
+ import { EXIT } from "../constants/exit.js";
6
+ import { CONFIG_PATH } from "../constants/paths.js";
7
+ import { findRoot } from "../utils/root.js";
8
+ export const openProject = () => {
9
+ const root = findRoot();
10
+ if (root === null) {
11
+ console.error(`[specthread] ${CONFIG_PATH} 를 찾지 못했다. 프로젝트 루트에서 \`specthread init\` 을 먼저 실행한다`);
12
+ process.exit(EXIT.FAILURE);
13
+ }
14
+ try {
15
+ return { root, config: loadConfig(root) };
16
+ }
17
+ catch (e) {
18
+ if (!(e instanceof ConfigError))
19
+ throw e;
20
+ console.error("[specthread] 설정을 읽지 못했다");
21
+ for (const p of e.problems) {
22
+ console.error(` ${p.file}${p.key === "" ? "" : ` ${p.key}`}: ${p.message}`);
23
+ }
24
+ process.exit(EXIT.FAILURE);
25
+ }
26
+ };
@@ -1,6 +1,7 @@
1
1
  import { RULE } from '../constants/rules.js';
2
- /** 변경 이력 순서 - 오래된 순이어야 한다 (`docs/system/rules.md` §2-4). */
3
- import { isTargetDoc } from '../utils/scope.js';
2
+ /** 변경 이력 순서 - 오래된 순이어야 한다 (`specthread/rules.md` §2-4). */
3
+ import { TAIL } from '../constants/docs.js';
4
+ import { isDoc } from '../utils/scope.js';
4
5
  /**
5
6
  * 날짜가 거꾸로 놓인 첫 자리를 찾아 한 건만 지적한다.
6
7
  *
@@ -10,7 +11,7 @@ import { isTargetDoc } from '../utils/scope.js';
10
11
  export const checkChangeLog = (index) => {
11
12
  const findings = [];
12
13
  for (const file of index.files.values()) {
13
- if (!isTargetDoc(file, index.config))
14
+ if (!isDoc(file))
14
15
  continue;
15
16
  if (file.changeLogDates.length < 2)
16
17
  continue;
@@ -18,7 +19,7 @@ export const checkChangeLog = (index) => {
18
19
  const bad = dates.findIndex((d, i) => i > 0 && d < dates[i - 1]);
19
20
  if (bad < 0)
20
21
  continue;
21
- const heading = file.headings.find((h) => h.title === '변경 이력');
22
+ const heading = file.headings.find((h) => h.title === TAIL.CHANGELOG);
22
23
  findings.push({
23
24
  file: file.path,
24
25
  line: heading?.line ?? 1,
@@ -1,3 +1,2 @@
1
1
  import type { DocIndex, Finding } from "../types.ts";
2
- /** 꼬리 절 이름. `parse.ts` 의 판정과 같은 목록이어야 한다 */
3
2
  export declare const checkHeadings: (index: DocIndex) => Finding[];
@@ -2,17 +2,16 @@ import { TAIL_NAMES } from '../constants/docs.js';
2
2
  import { RULE } from '../constants/rules.js';
3
3
  /**
4
4
  * 헤딩 구조 - 제목이 하나인가, 꼬리 절 이름을 본문에서 재사용하지 않는가,
5
- * 꼬리 절에 번호가 붙지 않았는가.
5
+ * 꼬리 절에 번호가 붙지 않았는가, 꼬리 절이 정해진 순서인가.
6
6
  *
7
- * 둘 다 생성기가 자리를 잘못 짚게 만드는 원인이다. 꼬리 절은 이름으로 찾으므로
8
- * 이름이 겹치면 어느 쪽이 꼬리인지 가릴 수 없고, 번호가 붙으면 규칙 8 과 어긋난다.
7
+ * 하나라도 어긋나면 생성기가 목차와 꼬리 절을 넣을 위치를 정할 수 없다. 꼬리 절은 이름으로 찾으므로
8
+ * 이름이 겹치면 어느 쪽이 꼬리 절인지 구분할 수 없고, 번호가 붙으면 규칙 8 과 어긋난다.
9
9
  */
10
- import { isTargetDoc, titleHeadings } from "../utils/scope.js";
11
- /** 꼬리 절 이름. `parse.ts` 의 판정과 같은 목록이어야 한다 */
10
+ import { isDoc, tailOrderOk, titleHeadings } from "../utils/scope.js";
12
11
  export const checkHeadings = (index) => {
13
12
  const findings = [];
14
13
  for (const file of index.files.values()) {
15
- if (!isTargetDoc(file, index.config))
14
+ if (!isDoc(file))
16
15
  continue;
17
16
  // 제목이 둘이면 목차를 어디에 둘지 정할 근거가 없다. 생성기도 이 문서를 건너뛴다
18
17
  const titles = titleHeadings(file);
@@ -24,6 +23,16 @@ export const checkHeadings = (index) => {
24
23
  message: `문서 제목이 ${titles.length} 개다 - 하나여야 한다`,
25
24
  });
26
25
  }
26
+ // 순서가 어긋난 문서는 생성기가 건너뛴다. 범위를 원본 줄 번호로 교체하기 때문이다
27
+ if (!tailOrderOk(file.headings)) {
28
+ const first = file.headings.find((h) => h.level === 2 && h.tail);
29
+ findings.push({
30
+ file: file.path,
31
+ line: first?.line ?? 1,
32
+ rule: RULE.HEADING.TAIL_ORDER,
33
+ message: `꼬리 절은 ${TAIL_NAMES.join(' → ')} 순서로 둔다`,
34
+ });
35
+ }
27
36
  for (const heading of file.headings) {
28
37
  // 꼬리 이름과 겹치는 제목만 본다. 나머지는 이 검사의 관심 밖이다
29
38
  if (!TAIL_NAMES.includes(heading.title))
@@ -2,8 +2,8 @@ import { RULE } from '../constants/rules.js';
2
2
  /** 링크 유효성 - 대상 파일이 있는가, 앵커가 실제 헤딩을 가리키는가. */
3
3
  import { existsSync } from 'node:fs';
4
4
  import { join, dirname, extname, normalize } from 'node:path';
5
- import { REPO_ROOT, docExtSet } from '../utils/scan.js';
6
- import { inChangeLog, inRefSection, isTargetDoc } from '../utils/scope.js';
5
+ import { docExtSet } from '../utils/scan.js';
6
+ import { inChangeLog, inPendingSection, inRefSection, isDoc } from '../utils/scope.js';
7
7
  /** 외부 링크는 파일 시스템에 없으니 확인하지 않는다 */
8
8
  const isExternal = (target) => /^(https?:|mailto:)/.test(target);
9
9
  /**
@@ -16,7 +16,7 @@ export const checkLinks = (index) => {
16
16
  const findings = [];
17
17
  const docExts = docExtSet(index.config.fileKinds);
18
18
  for (const file of index.files.values()) {
19
- if (!isTargetDoc(file, index.config))
19
+ if (!isDoc(file))
20
20
  continue;
21
21
  const anchors = new Set(file.headings.map((h) => h.anchor));
22
22
  for (const link of file.links) {
@@ -26,6 +26,9 @@ export const checkLinks = (index) => {
26
26
  // 깨져 있다. 고칠 자리는 본문이고, 참조 절은 다시 생성하면 따라온다
27
27
  if (inRefSection(file, link.line))
28
28
  continue;
29
+ // 미확정 사항 절은 관리 문서 항목을 옮긴 생성 뷰다. 원문은 관리 문서에서 검사한다
30
+ if (inPendingSection(file, link.line))
31
+ continue;
29
32
  if (link.target === null) {
30
33
  if (link.anchor && !anchors.has(link.anchor))
31
34
  findings.push({
@@ -39,7 +42,7 @@ export const checkLinks = (index) => {
39
42
  if (isExternal(link.target))
40
43
  continue;
41
44
  const rel = normalize(join(dirname(file.path), link.target));
42
- if (!existsSync(join(REPO_ROOT, rel))) {
45
+ if (!existsSync(join(index.root, rel))) {
43
46
  findings.push({
44
47
  file: file.path,
45
48
  line: link.line,
@@ -1,2 +1,4 @@
1
- import type { DocIndex, Finding } from "../types.ts";
1
+ import type { DocIndex, Finding, IndexedFile } from "../types.ts";
2
+ /** 관리 문서 항목 id → 그 헤딩 줄 번호. 변경 이력 안의 것은 과거 기록이라 뺀다 */
3
+ export declare const pendingItemLines: (pending: IndexedFile) => Map<string, number>;
2
4
  export declare const checkMarkers: (index: DocIndex) => Finding[];