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.
- package/README.md +171 -66
- package/dist/bin/check.js +9 -34
- package/dist/bin/cli.js +5 -4
- package/dist/bin/generate.js +32 -19
- package/dist/bin/open-project.d.ts +5 -0
- package/dist/bin/open-project.js +26 -0
- package/dist/checks/changelog.js +5 -4
- package/dist/checks/headings.d.ts +0 -1
- package/dist/checks/headings.js +15 -6
- package/dist/checks/links.js +7 -4
- package/dist/checks/markers.d.ts +3 -1
- package/dist/checks/markers.js +33 -18
- package/dist/checks/pending.js +57 -23
- package/dist/checks/references.js +2 -2
- package/dist/checks/sections.js +3 -6
- package/dist/checks/style.d.ts +0 -8
- package/dist/checks/style.js +23 -43
- package/dist/checks/timestamps.js +5 -5
- package/dist/checks/toc.js +4 -6
- package/dist/commands/config-template.d.ts +8 -0
- package/{scaffold/config.jsonc → dist/commands/config-template.js} +48 -40
- package/dist/commands/init.js +121 -47
- package/dist/commands/upgrade-prompt.d.ts +12 -0
- package/dist/commands/upgrade-prompt.js +147 -0
- package/dist/config-loader.d.ts +44 -1
- package/dist/config-loader.js +219 -36
- package/dist/config.schema.d.ts +16 -35
- package/dist/config.schema.js +1 -7
- package/dist/constants/docs.d.ts +8 -4
- package/dist/constants/docs.js +8 -5
- package/dist/constants/exit.d.ts +12 -0
- package/dist/constants/exit.js +12 -0
- package/dist/constants/paths.d.ts +25 -0
- package/dist/constants/paths.js +25 -0
- package/dist/constants/patterns.d.ts +13 -6
- package/dist/constants/patterns.js +16 -6
- package/dist/constants/rules.d.ts +7 -3
- package/dist/constants/rules.js +7 -3
- package/dist/gen/pending-section.js +20 -16
- package/dist/gen/references.js +13 -9
- package/dist/gen/summary.d.ts +1 -1
- package/dist/gen/summary.js +11 -7
- package/dist/gen/toc.js +5 -2
- package/dist/run-check.d.ts +5 -0
- package/dist/run-check.js +35 -0
- package/dist/types.d.ts +6 -4
- package/dist/utils/anchor.d.ts +1 -1
- package/dist/utils/anchor.js +1 -1
- package/dist/utils/ignore.d.ts +2 -8
- package/dist/utils/ignore.js +23 -6
- package/dist/utils/parse.d.ts +6 -6
- package/dist/utils/parse.js +18 -27
- package/dist/utils/path-match.d.ts +19 -0
- package/dist/utils/path-match.js +27 -0
- package/dist/utils/report.d.ts +1 -7
- package/dist/utils/report.js +10 -3
- package/dist/utils/resolve.d.ts +15 -5
- package/dist/utils/resolve.js +63 -25
- package/dist/utils/root.d.ts +2 -0
- package/dist/utils/root.js +19 -0
- package/dist/utils/scan.d.ts +1 -3
- package/dist/utils/scan.js +28 -26
- package/dist/utils/scope.d.ts +37 -11
- package/dist/utils/scope.js +60 -24
- package/package.json +3 -3
- package/scaffold/AGENTS.md +4 -6
- package/scaffold/claude/skills/{check.md → check/SKILL.md} +6 -3
- package/scaffold/claude/skills/{gen.md → gen/SKILL.md} +5 -3
- package/scaffold/claude/skills/{plan-close.md → plan-close/SKILL.md} +1 -0
- package/scaffold/claude/skills/{plan-open.md → plan-open/SKILL.md} +1 -0
- package/scaffold/claude/skills/{plan-run.md → plan-run/SKILL.md} +1 -0
- package/scaffold/pending.md +1 -1
- package/scaffold/project.md +1 -1
- package/scaffold/rules.md +28 -27
- package/scaffold/templates/plan.md +3 -7
package/README.md
CHANGED
|
@@ -1,76 +1,166 @@
|
|
|
1
1
|
# specthread
|
|
2
2
|
|
|
3
|
-
Spec-Driven Development
|
|
3
|
+
Spec-Driven Development(SDD) 도구입니다. 문서를 단일 정본으로 관리하고, 문서 형식 규칙과 그 규칙을 검사·생성하는 도구를 함께 제공합니다.
|
|
4
|
+
|
|
5
|
+
AI 와 함께 코드를 작성하면 문서와 코드가 쉽게 어긋납니다. specthread 는 문서 형식을 규칙으로 정하고, 규칙 위반과 생성물의 불일치를 `check` 로 검출합니다. 목차·참조 절처럼 다른 내용에서 만들 수 있는 부분은 `gen` 이 생성합니다.
|
|
4
6
|
|
|
5
7
|
## 시작하기
|
|
6
8
|
|
|
7
9
|
```bash
|
|
8
|
-
npm install -
|
|
9
|
-
specthread init
|
|
10
|
-
specthread check
|
|
10
|
+
npm install -D specthread
|
|
11
|
+
npx specthread init
|
|
12
|
+
npx specthread check
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
전역으로 설치하려면 `npm install -g specthread` 후 `specthread` 로 실행합니다.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
## init 이 만드는 파일
|
|
16
18
|
|
|
17
19
|
```
|
|
18
|
-
specthread/
|
|
19
|
-
config.jsonc
|
|
20
|
-
rules.md
|
|
21
|
-
project.md
|
|
22
|
-
pending.md
|
|
23
|
-
templates/
|
|
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
|
|
27
|
-
CLAUDE.md
|
|
28
|
-
.claude/skills/
|
|
28
|
+
AGENTS.md AI 도구 진입점
|
|
29
|
+
CLAUDE.md Claude Code 용 (@AGENTS.md)
|
|
30
|
+
.claude/skills/ Claude Code 스킬
|
|
29
31
|
```
|
|
30
32
|
|
|
31
|
-
기존 `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 #
|
|
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
|
-
|
|
55
|
+
30개 규칙으로 문서 형식을 검사합니다. 하위 디렉터리에서 실행해도 `specthread/config.jsonc` 가 있는 디렉터리를 루트로 삼아 같은 범위를 검사합니다.
|
|
56
|
+
|
|
57
|
+
| 종료 코드 | 의미 |
|
|
58
|
+
| --------- | ---- |
|
|
59
|
+
| 0 | 지적 없음 |
|
|
60
|
+
| 1 | 지적 있음 |
|
|
61
|
+
| 2 | 실행 실패 (설정 파일 없음, 설정 오류, 모르는 명령) |
|
|
46
62
|
|
|
47
63
|
### gen
|
|
48
64
|
|
|
49
|
-
본문
|
|
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
|
|
117
|
+
`specthread/config.jsonc` 로 프로젝트별 동작을 정합니다. 개인 설정은 `specthread/config.local.jsonc` 에 두고, 이 파일은 `init` 이 `.gitignore` 에 추가합니다.
|
|
54
118
|
|
|
55
119
|
```
|
|
56
|
-
|
|
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
|
-
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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을
|
|
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
|
|
90
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
122
|
-
|
|
219
|
+
스킬 없이 자연어로 요청해도 됩니다. `AGENTS.md` 에 작업 흐름이 적혀 있어서 AI 가 같은 순서로 진행합니다.
|
|
220
|
+
|
|
221
|
+
## 버전 올리기
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
npm install -D specthread@latest
|
|
225
|
+
npx specthread init --force
|
|
226
|
+
```
|
|
123
227
|
|
|
124
|
-
|
|
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
|
-
|
|
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
|
|
139
|
-
- 외부 의존성 없음
|
|
243
|
+
- Node.js 18 이상
|
|
244
|
+
- 외부 의존성 없음
|
|
140
245
|
|
|
141
246
|
## 라이선스
|
|
142
247
|
|
package/dist/bin/check.js
CHANGED
|
@@ -1,26 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* 문서 검사기 진입점. `
|
|
3
|
-
*
|
|
4
|
-
* `pnpm test` 와 분리해 둔다 - 실 문서 재편이 끝나기 전에는 목차·참조 절 지적이
|
|
5
|
-
* 대량으로 남으므로, 4 smoke 에 넣으면 게이트가 상시 red 가 되어 신호 기능을 잃는다.
|
|
2
|
+
* 문서 검사기 진입점. `specthread check`
|
|
6
3
|
*/
|
|
7
|
-
import {
|
|
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 {
|
|
22
|
-
const config =
|
|
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
|
-
|
|
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
|
|
10
|
-
|
|
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 ?
|
|
41
|
+
process.exit(command === undefined ? EXIT.OK : EXIT.FAILURE);
|
|
40
42
|
}
|
|
41
43
|
};
|
|
42
44
|
run();
|
|
43
|
-
export {};
|
package/dist/bin/generate.js
CHANGED
|
@@ -1,40 +1,48 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* 생성기 진입점. `
|
|
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 {
|
|
9
|
-
import {
|
|
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
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
|
|
34
|
-
|
|
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
|
|
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(
|
|
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,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
|
+
};
|
package/dist/checks/changelog.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { RULE } from '../constants/rules.js';
|
|
2
|
-
/** 변경 이력 순서 - 오래된 순이어야 한다 (`
|
|
3
|
-
import {
|
|
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 (!
|
|
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,
|
package/dist/checks/headings.js
CHANGED
|
@@ -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
|
-
* 이름이 겹치면 어느 쪽이
|
|
7
|
+
* 하나라도 어긋나면 생성기가 목차와 꼬리 절을 넣을 위치를 정할 수 없다. 꼬리 절은 이름으로 찾으므로
|
|
8
|
+
* 이름이 겹치면 어느 쪽이 꼬리 절인지 구분할 수 없고, 번호가 붙으면 규칙 8 과 어긋난다.
|
|
9
9
|
*/
|
|
10
|
-
import {
|
|
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 (!
|
|
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))
|
package/dist/checks/links.js
CHANGED
|
@@ -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 {
|
|
6
|
-
import { inChangeLog, inRefSection,
|
|
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 (!
|
|
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(
|
|
45
|
+
if (!existsSync(join(index.root, rel))) {
|
|
43
46
|
findings.push({
|
|
44
47
|
file: file.path,
|
|
45
48
|
line: link.line,
|
package/dist/checks/markers.d.ts
CHANGED
|
@@ -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[];
|