specthread 0.1.4 → 0.2.0
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 +88 -13
- package/dist/bin/check.js +9 -34
- package/dist/bin/cli.js +4 -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 +13 -4
- package/dist/checks/links.js +10 -6
- package/dist/checks/markers.d.ts +3 -1
- package/dist/checks/markers.js +33 -18
- package/dist/checks/pending.js +54 -22
- package/dist/checks/references.js +2 -2
- package/dist/checks/sections.js +3 -5
- 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 +92 -42
- package/dist/config-loader.d.ts +22 -1
- package/dist/config-loader.js +192 -25
- package/dist/config.schema.d.ts +16 -35
- package/dist/config.schema.js +1 -7
- package/dist/constants/docs.d.ts +7 -2
- package/dist/constants/docs.js +7 -3
- 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 +12 -3
- package/dist/constants/patterns.js +15 -3
- package/dist/constants/rules.d.ts +7 -3
- package/dist/constants/rules.js +7 -3
- package/dist/gen/pending-section.js +18 -14
- package/dist/gen/references.js +19 -10
- package/dist/gen/summary.d.ts +1 -1
- package/dist/gen/summary.js +9 -6
- package/dist/gen/toc.js +4 -1
- package/dist/run-check.d.ts +5 -0
- package/dist/run-check.js +35 -0
- package/dist/types.d.ts +4 -2
- package/dist/utils/ignore.d.ts +2 -8
- package/dist/utils/ignore.js +23 -6
- package/dist/utils/parse.js +11 -19
- 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.js +15 -1
- package/dist/utils/root.d.ts +2 -0
- package/dist/utils/root.js +19 -0
- package/dist/utils/scan.d.ts +7 -5
- package/dist/utils/scan.js +25 -25
- package/dist/utils/scope.d.ts +37 -11
- package/dist/utils/scope.js +60 -24
- package/package.json +2 -2
- 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} +4 -2
- 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
|
@@ -20,7 +20,7 @@ specthread/ ← 문서 규칙·설정·미확정 사항
|
|
|
20
20
|
rules.md
|
|
21
21
|
project.md
|
|
22
22
|
pending.md
|
|
23
|
-
templates/ ← 문서 골격 (
|
|
23
|
+
templates/ ← 문서 골격 (check 대상 아님)
|
|
24
24
|
spec.md
|
|
25
25
|
plan.md
|
|
26
26
|
AGENTS.md ← AI 도구 진입점
|
|
@@ -30,11 +30,19 @@ CLAUDE.md ← Claude Code용 (@AGENTS.md)
|
|
|
30
30
|
|
|
31
31
|
기존 `AGENTS.md`가 있으면 `<!-- specthread:start/end -->` 마커로 섹션만 삽입한다. 기존 `CLAUDE.md`가 있으면 `@AGENTS.md` 줄만 추가한다.
|
|
32
32
|
|
|
33
|
+
| 종류 | 파일 | `init` | `init --force` |
|
|
34
|
+
| ---- | ---- | ------ | -------------- |
|
|
35
|
+
| 패키지 파일 | `rules.md`, `templates/`, `.claude/skills/` | 없을 때만 생성 | 새 버전으로 덮어씀 |
|
|
36
|
+
| 사용자 파일 | `config.jsonc`, `project.md`, `pending.md` | 없을 때만 생성 | 없을 때만 생성 |
|
|
37
|
+
| 병합 | `AGENTS.md` (마커 사이), `CLAUDE.md`, `.gitignore` | 병합 | 병합 |
|
|
38
|
+
|
|
39
|
+
설정을 처음 상태로 되돌리려면 `config.jsonc`를 지우고 `init`을 다시 실행한다.
|
|
40
|
+
|
|
33
41
|
## 명령어
|
|
34
42
|
|
|
35
43
|
```bash
|
|
36
44
|
npx specthread init [--tools claude,cursor] # 프로젝트 초기화
|
|
37
|
-
npx specthread init --force #
|
|
45
|
+
npx specthread init --force # 패키지 파일을 새 버전으로 갱신 (사용자 파일은 유지)
|
|
38
46
|
npx specthread check # 문서 정합성 검사
|
|
39
47
|
npx specthread gen # 참조 절·목차·요약 표 미리보기
|
|
40
48
|
npx specthread gen --write # 실제 적용
|
|
@@ -42,7 +50,7 @@ npx specthread gen --write # 실제 적용
|
|
|
42
50
|
|
|
43
51
|
### check
|
|
44
52
|
|
|
45
|
-
|
|
53
|
+
30개 규칙으로 문서 형식을 검사한다. 목차, 헤딩, 링크, 참조 절, 변경 이력, 미확정 마커 등.
|
|
46
54
|
|
|
47
55
|
### gen
|
|
48
56
|
|
|
@@ -60,17 +68,19 @@ specthread/config.jsonc (프로젝트 공유)
|
|
|
60
68
|
specthread/config.local.jsonc (개인)
|
|
61
69
|
```
|
|
62
70
|
|
|
63
|
-
|
|
71
|
+
배열과 `path` 는 통째로 교체되고, 나머지 객체는 키 단위로 합쳐진다. 잘못된 값이 있으면 파일과 키를 출력하고 종료 코드 2 로 끝난다. init이 생성하는 `config.jsonc`에 모든 옵션이 주석으로 설명되어 있고, `fileKinds`는 기본 확장자 목록이 실제 값으로 기록되므로 필요한 확장자를 그 자리에서 더하거나 뺄 수 있다.
|
|
64
72
|
|
|
65
|
-
| 키 | 역할
|
|
66
|
-
| ----------- |
|
|
67
|
-
| `path` | 스캔 대상 경로 (자유 KV)
|
|
68
|
-
| `fileKinds` | 확장자 → 종류 매핑 (`doc` / `source`)
|
|
69
|
-
| `features` | 기능 플래그 (`markers`, `
|
|
70
|
-
| `markers` | 마커 종류·시점 라벨
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
73
|
+
| 키 | 역할 |
|
|
74
|
+
| ----------- | ------------------------------------------ |
|
|
75
|
+
| `path` | 스캔 대상 경로 (자유 KV) |
|
|
76
|
+
| `fileKinds` | 확장자 → 종류 매핑 (`doc` / `source`) |
|
|
77
|
+
| `features` | 기능 플래그 (`markers`, `references`) |
|
|
78
|
+
| `markers` | 마커 종류·시점 라벨 |
|
|
79
|
+
| `skipCheck` | 검사·생성을 건너뛸 경로 |
|
|
80
|
+
| `skipRefs` | 참조 절 생성을 건너뛸 경로 |
|
|
81
|
+
| `work` | 작업 문서 폴더 (기본 `docs/work/`) |
|
|
82
|
+
|
|
83
|
+
`specthread/` 아래 규칙·미확정·프로젝트 문서의 위치는 고정이다. 템플릿과 설정 파일은 항상 검사에서 제외된다.
|
|
74
84
|
|
|
75
85
|
## SDD 작업 흐름
|
|
76
86
|
|
|
@@ -133,6 +143,71 @@ AI는 작업 중에 `check`와 `gen`을 자동으로 호출한다. `AGENTS.md`
|
|
|
133
143
|
|
|
134
144
|
스킬 없이 자연어로 같은 작업을 요청해도 된다. `AGENTS.md`가 AI에게 워크플로우를 알려주기 때문이다. 스킬은 자주 쓰는 흐름의 단축키다.
|
|
135
145
|
|
|
146
|
+
## 0.1.x 에서 올리기
|
|
147
|
+
|
|
148
|
+
0.2.0 은 설정 키 일부를 정리하고 규칙 3개를 더했다. 패키지를 올린 뒤 아래를 실행한다.
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
npm install -D specthread@latest
|
|
152
|
+
npx specthread init --force
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`init --force` 는 `rules.md`·템플릿·스킬만 새 버전으로 바꾼다. 사용자 파일과, 0.1.x 가 마커 없이 만든 `AGENTS.md` 는 건드리지 않는다. 남은 정리는 AI 에게 아래 프롬프트로 맡긴다.
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
specthread 를 0.2.0 으로 올렸다. 아래를 순서대로 처리해줘.
|
|
159
|
+
내가 직접 쓴 내용은 지우지 말고, 판단이 필요하면 멈추고 물어봐.
|
|
160
|
+
|
|
161
|
+
0. specthread/rules.md 와 specthread/templates/ 를 고쳐 쓴 적이 있으면,
|
|
162
|
+
다음 단계에서 덮어써지므로 먼저 커밋되어 있는지 확인한다.
|
|
163
|
+
|
|
164
|
+
1. AGENTS.md
|
|
165
|
+
- `<!-- specthread:start -->` 표식이 없으면, specthread 가 만든 부분
|
|
166
|
+
(`# specthread` 제목부터 그 섹션 끝까지)을 `<!-- specthread:start -->` 와
|
|
167
|
+
`<!-- specthread:end -->` 로 감싼다. 그 밖의 내용은 그대로 둔다.
|
|
168
|
+
- specthread 섹션이 두 번 들어가 있으면 뒤의 것을 지운다.
|
|
169
|
+
|
|
170
|
+
2. `npx specthread init --force` 를 실행한다.
|
|
171
|
+
rules.md, 템플릿, 스킬, AGENTS.md 의 specthread 섹션이 새 버전으로 바뀐다.
|
|
172
|
+
|
|
173
|
+
3. specthread/config.jsonc
|
|
174
|
+
- `"emDash"` 키와 그 주석을 지운다.
|
|
175
|
+
- 주석으로만 남은 `locale`, `rules`, `pending`, `project` 블록을 지운다.
|
|
176
|
+
- `rules`·`pending`·`project` 에 실제 값을 적어 쓰고 있었다면 지우지 말고 알려줘.
|
|
177
|
+
이제 경로가 specthread/ 아래로 고정이라 파일을 옮겨야 한다.
|
|
178
|
+
- `path` 에 일부 키만 적어 두었다면 알려줘. 이제 path 는 기본값과 합치지 않고
|
|
179
|
+
통째로 교체되므로, docs/ 와 specthread/ 스캔이 빠질 수 있다.
|
|
180
|
+
|
|
181
|
+
4. specthread/project.md 의 "`config.jsonc` 에서 경로를 override 할 수 있다" 를
|
|
182
|
+
"경로는 `specthread/pending.md` 고정이다" 로 바꾼다.
|
|
183
|
+
|
|
184
|
+
5. specthread/pending.md 의 "종류마다 `##` 섹션이 하나씩 생긴다. 종류 값은
|
|
185
|
+
`config.markers.types` 가 정의하며" 를 "종류마다 `##` 섹션을 하나씩 둔다.
|
|
186
|
+
섹션은 사람이 만들고, 종류 값은 `config.markers.types` 에 있어야 한다." 로 바꾼다.
|
|
187
|
+
|
|
188
|
+
6. `.claude/skills/` 바로 아래에 check.md, gen.md, plan-open.md, plan-run.md,
|
|
189
|
+
plan-close.md 가 남아 있으면 같은 이름의 `<이름>/SKILL.md` 와 비교한다.
|
|
190
|
+
내가 고친 부분이 없으면 지우고, 있으면 알려줘.
|
|
191
|
+
|
|
192
|
+
7. `npx specthread check` 를 실행한다.
|
|
193
|
+
- `marker/unknown-type` 이 나오면 쓰고 있는 종류를 `config.markers.types` 에
|
|
194
|
+
추가할지 물어봐.
|
|
195
|
+
- `heading/tail-order` 가 나오면 꼬리 절을 참조 → 미확정 사항 → 변경 이력 순서로 옮긴다.
|
|
196
|
+
|
|
197
|
+
8. `npx specthread gen --write` 후 `npx specthread check` 가 0 건인지 확인한다.
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
바뀐 동작:
|
|
201
|
+
|
|
202
|
+
| 변경 | 영향 |
|
|
203
|
+
| ---- | ---- |
|
|
204
|
+
| `locale`, `rules`, `pending`, `project`, `features.emDash` 키 제거 | 남아 있으면 경고만 내고 동작한다 |
|
|
205
|
+
| `path` 통째 교체 | 일부 키만 적었다면 기본 `docs/`, `specthread/` 스캔이 빠진다 |
|
|
206
|
+
| 종료 코드 2 | 설정 파일이 없거나 설정을 읽지 못하면, 또는 모르는 명령이면 2 로 끝난다 |
|
|
207
|
+
| 규칙 추가 | `heading/tail-order`, `marker/unknown-type`, `pending/unknown-timepoint` |
|
|
208
|
+
| em dash 검사 제거 | `style/em-dash` 가 없어졌다 |
|
|
209
|
+
| 스킬 경로 | `.claude/skills/<이름>/SKILL.md` 로 바뀌었다. 옛 파일은 지우지 않고 알린다 |
|
|
210
|
+
|
|
136
211
|
## 요구 사항
|
|
137
212
|
|
|
138
213
|
- Node.js >= 18.0.0
|
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,8 @@ const usage = `specthread - Spec-Driven Development (SDD) 도구
|
|
|
6
7
|
|
|
7
8
|
commands:
|
|
8
9
|
init [--tools claude,cursor] 프로젝트에 SDD 체계 초기화
|
|
9
|
-
init --force
|
|
10
|
-
check 문서 정합성 검사 (
|
|
10
|
+
init --force 패키지 파일(rules·템플릿·스킬)을 새 버전으로 갱신
|
|
11
|
+
check 문서 정합성 검사 (30개 규칙)
|
|
11
12
|
gen [--write] 참조 절·목차·미확정 사항 요약 생성
|
|
12
13
|
help 이 도움말 표시
|
|
13
14
|
|
|
@@ -36,8 +37,7 @@ const run = async () => {
|
|
|
36
37
|
break;
|
|
37
38
|
default:
|
|
38
39
|
console.log(usage);
|
|
39
|
-
process.exit(command === undefined ?
|
|
40
|
+
process.exit(command === undefined ? EXIT.OK : EXIT.FAILURE);
|
|
40
41
|
}
|
|
41
42
|
};
|
|
42
43
|
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
7
|
* 둘 다 생성기가 자리를 잘못 짚게 만드는 원인이다. 꼬리 절은 이름으로 찾으므로
|
|
8
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
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { RULE } from '../constants/rules.js';
|
|
2
2
|
/** 링크 유효성 - 대상 파일이 있는가, 앵커가 실제 헤딩을 가리키는가. */
|
|
3
3
|
import { existsSync } from 'node:fs';
|
|
4
|
-
import { join, dirname, normalize } from 'node:path';
|
|
5
|
-
import {
|
|
6
|
-
import { inChangeLog, inRefSection,
|
|
4
|
+
import { join, dirname, extname, normalize } from 'node:path';
|
|
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
|
/**
|
|
@@ -14,8 +14,9 @@ const isExternal = (target) => /^(https?:|mailto:)/.test(target);
|
|
|
14
14
|
*/
|
|
15
15
|
export const checkLinks = (index) => {
|
|
16
16
|
const findings = [];
|
|
17
|
+
const docExts = docExtSet(index.config.fileKinds);
|
|
17
18
|
for (const file of index.files.values()) {
|
|
18
|
-
if (!
|
|
19
|
+
if (!isDoc(file))
|
|
19
20
|
continue;
|
|
20
21
|
const anchors = new Set(file.headings.map((h) => h.anchor));
|
|
21
22
|
for (const link of file.links) {
|
|
@@ -25,6 +26,9 @@ export const checkLinks = (index) => {
|
|
|
25
26
|
// 깨져 있다. 고칠 자리는 본문이고, 참조 절은 다시 생성하면 따라온다
|
|
26
27
|
if (inRefSection(file, link.line))
|
|
27
28
|
continue;
|
|
29
|
+
// 미확정 사항 절은 관리 문서 항목을 옮긴 생성 뷰다. 원문은 관리 문서에서 검사한다
|
|
30
|
+
if (inPendingSection(file, link.line))
|
|
31
|
+
continue;
|
|
28
32
|
if (link.target === null) {
|
|
29
33
|
if (link.anchor && !anchors.has(link.anchor))
|
|
30
34
|
findings.push({
|
|
@@ -38,7 +42,7 @@ export const checkLinks = (index) => {
|
|
|
38
42
|
if (isExternal(link.target))
|
|
39
43
|
continue;
|
|
40
44
|
const rel = normalize(join(dirname(file.path), link.target));
|
|
41
|
-
if (!existsSync(join(
|
|
45
|
+
if (!existsSync(join(index.root, rel))) {
|
|
42
46
|
findings.push({
|
|
43
47
|
file: file.path,
|
|
44
48
|
line: link.line,
|
|
@@ -47,7 +51,7 @@ export const checkLinks = (index) => {
|
|
|
47
51
|
});
|
|
48
52
|
continue;
|
|
49
53
|
}
|
|
50
|
-
if (!link.anchor || !rel.
|
|
54
|
+
if (!link.anchor || !docExts.has(extname(rel).toLowerCase()))
|
|
51
55
|
continue;
|
|
52
56
|
const target = index.files.get(rel);
|
|
53
57
|
// 색인 범위 밖 문서 (archive 등) 는 앵커를 확인하지 않는다
|
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[];
|
package/dist/checks/markers.js
CHANGED
|
@@ -1,42 +1,55 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* 마커 ↔ 관리 문서 대조 (`
|
|
2
|
+
* 마커 ↔ 관리 문서 대조 (`specthread/rules.md` §4-1).
|
|
3
3
|
*
|
|
4
4
|
* 양방향으로 본다 - 코드·문서에 박힌 새 형식 마커가 관리 문서 항목을 실제로
|
|
5
5
|
* 가리키는가, 그리고 관리 문서 항목이 최소 하나의 마커에서라도 걸리는가.
|
|
6
|
+
* 종류가 `markers.types` 에 있는지도 함께 본다.
|
|
6
7
|
*/
|
|
8
|
+
import { PENDING_PATH } from "../constants/paths.js";
|
|
9
|
+
import { ITEM_HEADING } from "../constants/patterns.js";
|
|
7
10
|
import { RULE } from "../constants/rules.js";
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
+
import { eachContentLine } from "../utils/parse.js";
|
|
12
|
+
import { inChangeLog } from "../utils/scope.js";
|
|
13
|
+
/** 관리 문서 항목 id → 그 헤딩 줄 번호. 변경 이력 안의 것은 과거 기록이라 뺀다 */
|
|
14
|
+
export const pendingItemLines = (pending) => {
|
|
11
15
|
const out = new Map();
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
if (
|
|
15
|
-
inChangeLog = true;
|
|
16
|
-
if (inChangeLog)
|
|
16
|
+
const collect = (raw, i) => {
|
|
17
|
+
const line = i + 1;
|
|
18
|
+
if (inChangeLog(pending, line))
|
|
17
19
|
return;
|
|
18
|
-
const m =
|
|
20
|
+
const m = ITEM_HEADING.exec(raw);
|
|
19
21
|
if (m)
|
|
20
|
-
out.set(m[1],
|
|
21
|
-
}
|
|
22
|
+
out.set(m[1], line);
|
|
23
|
+
};
|
|
24
|
+
eachContentLine(pending.lines, collect);
|
|
22
25
|
return out;
|
|
23
26
|
};
|
|
27
|
+
const kindOf = (id) => id.split("::")[0];
|
|
24
28
|
export const checkMarkers = (index) => {
|
|
25
|
-
const pending = index.files.get(
|
|
29
|
+
const pending = index.files.get(PENDING_PATH);
|
|
26
30
|
if (pending === undefined)
|
|
27
31
|
return [];
|
|
28
32
|
const items = pendingItemLines(pending);
|
|
33
|
+
const types = new Set(index.config.markers.types);
|
|
29
34
|
const findings = [];
|
|
30
35
|
const seen = new Set();
|
|
36
|
+
const unknownType = (file, line, id) => ({
|
|
37
|
+
file,
|
|
38
|
+
line,
|
|
39
|
+
rule: RULE.MARKER.UNKNOWN_TYPE,
|
|
40
|
+
message: `종류 ${kindOf(id)} 가 config.markers.types 에 없다 - ${id}`,
|
|
41
|
+
});
|
|
31
42
|
for (const file of index.files.values()) {
|
|
32
|
-
if (file.path ===
|
|
43
|
+
if (file.path === PENDING_PATH)
|
|
33
44
|
continue;
|
|
34
45
|
for (const marker of file.markers) {
|
|
35
46
|
if (marker.slug === "")
|
|
36
47
|
continue;
|
|
37
48
|
const id = `${marker.kind}::${marker.slug}`;
|
|
38
49
|
seen.add(id);
|
|
39
|
-
if (
|
|
50
|
+
if (!types.has(marker.kind))
|
|
51
|
+
findings.push(unknownType(file.path, marker.line, id));
|
|
52
|
+
if (items.has(id))
|
|
40
53
|
continue;
|
|
41
54
|
findings.push({
|
|
42
55
|
file: file.path,
|
|
@@ -46,14 +59,16 @@ export const checkMarkers = (index) => {
|
|
|
46
59
|
});
|
|
47
60
|
}
|
|
48
61
|
}
|
|
49
|
-
for (const [
|
|
50
|
-
if (
|
|
62
|
+
for (const [id, line] of items) {
|
|
63
|
+
if (!types.has(kindOf(id)))
|
|
64
|
+
findings.push(unknownType(pending.path, line, id));
|
|
65
|
+
if (seen.has(id))
|
|
51
66
|
continue;
|
|
52
67
|
findings.push({
|
|
53
68
|
file: pending.path,
|
|
54
69
|
line,
|
|
55
70
|
rule: RULE.MARKER.UNMARKED,
|
|
56
|
-
message: `[${
|
|
71
|
+
message: `[${id}] 를 가리키는 마커가 없다 - 억제하려면 @specthread-ignore`,
|
|
57
72
|
});
|
|
58
73
|
}
|
|
59
74
|
return findings;
|