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.
Files changed (69) hide show
  1. package/README.md +88 -13
  2. package/dist/bin/check.js +9 -34
  3. package/dist/bin/cli.js +4 -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 +13 -4
  10. package/dist/checks/links.js +10 -6
  11. package/dist/checks/markers.d.ts +3 -1
  12. package/dist/checks/markers.js +33 -18
  13. package/dist/checks/pending.js +54 -22
  14. package/dist/checks/references.js +2 -2
  15. package/dist/checks/sections.js +3 -5
  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 +92 -42
  23. package/dist/config-loader.d.ts +22 -1
  24. package/dist/config-loader.js +192 -25
  25. package/dist/config.schema.d.ts +16 -35
  26. package/dist/config.schema.js +1 -7
  27. package/dist/constants/docs.d.ts +7 -2
  28. package/dist/constants/docs.js +7 -3
  29. package/dist/constants/exit.d.ts +12 -0
  30. package/dist/constants/exit.js +12 -0
  31. package/dist/constants/paths.d.ts +25 -0
  32. package/dist/constants/paths.js +25 -0
  33. package/dist/constants/patterns.d.ts +12 -3
  34. package/dist/constants/patterns.js +15 -3
  35. package/dist/constants/rules.d.ts +7 -3
  36. package/dist/constants/rules.js +7 -3
  37. package/dist/gen/pending-section.js +18 -14
  38. package/dist/gen/references.js +19 -10
  39. package/dist/gen/summary.d.ts +1 -1
  40. package/dist/gen/summary.js +9 -6
  41. package/dist/gen/toc.js +4 -1
  42. package/dist/run-check.d.ts +5 -0
  43. package/dist/run-check.js +35 -0
  44. package/dist/types.d.ts +4 -2
  45. package/dist/utils/ignore.d.ts +2 -8
  46. package/dist/utils/ignore.js +23 -6
  47. package/dist/utils/parse.js +11 -19
  48. package/dist/utils/path-match.d.ts +19 -0
  49. package/dist/utils/path-match.js +27 -0
  50. package/dist/utils/report.d.ts +1 -7
  51. package/dist/utils/report.js +10 -3
  52. package/dist/utils/resolve.js +15 -1
  53. package/dist/utils/root.d.ts +2 -0
  54. package/dist/utils/root.js +19 -0
  55. package/dist/utils/scan.d.ts +7 -5
  56. package/dist/utils/scan.js +25 -25
  57. package/dist/utils/scope.d.ts +37 -11
  58. package/dist/utils/scope.js +60 -24
  59. package/package.json +2 -2
  60. package/scaffold/AGENTS.md +4 -6
  61. package/scaffold/claude/skills/{check.md → check/SKILL.md} +6 -3
  62. package/scaffold/claude/skills/{gen.md → gen/SKILL.md} +4 -2
  63. package/scaffold/claude/skills/{plan-close.md → plan-close/SKILL.md} +1 -0
  64. package/scaffold/claude/skills/{plan-open.md → plan-open/SKILL.md} +1 -0
  65. package/scaffold/claude/skills/{plan-run.md → plan-run/SKILL.md} +1 -0
  66. package/scaffold/pending.md +1 -1
  67. package/scaffold/project.md +1 -1
  68. package/scaffold/rules.md +28 -27
  69. 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/ ← 문서 골격 (수정 가능, check 대상)
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 # scaffold 파일을 최신으로 덮어쓰기
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
- 28개 규칙으로 문서 형식을 검사한다. 목차, 헤딩, 링크, 참조 절, 변경 이력, 미확정 마커 등.
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
- 설정이 없으면 기본값으로 동작한다. init이 생성하는 `config.jsonc`에 모든 옵션이 주석으로 설명되어 있다.
71
+ 배열과 `path` 는 통째로 교체되고, 나머지 객체는 키 단위로 합쳐진다. 잘못된 값이 있으면 파일과 키를 출력하고 종료 코드 2 로 끝난다. init이 생성하는 `config.jsonc`에 모든 옵션이 주석으로 설명되어 있고, `fileKinds`는 기본 확장자 목록이 실제 값으로 기록되므로 필요한 확장자를 그 자리에서 더하거나 뺄 수 있다.
64
72
 
65
- | 키 | 역할 |
66
- | ----------- | ----------------------------------------------- |
67
- | `path` | 스캔 대상 경로 (자유 KV) |
68
- | `fileKinds` | 확장자 → 종류 매핑 (`doc` / `source`) |
69
- | `features` | 기능 플래그 (`markers`, `emDash`, `references`) |
70
- | `markers` | 마커 종류·시점 라벨 |
71
- | `docTypes` | 경로별 템플릿·프론트매터 스키마 |
72
- | `skipCheck` | 검사 건너뛸 경로 |
73
- | `skipRefs` | 참조 절 생성 건너뛸 경로 |
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
- * 문서 검사기 진입점. `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,8 @@ 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
+ 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 ? 0 : 1);
40
+ process.exit(command === undefined ? EXIT.OK : EXIT.FAILURE);
40
41
  }
41
42
  };
42
43
  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
7
  * 둘 다 생성기가 자리를 잘못 짚게 만드는 원인이다. 꼬리 절은 이름으로 찾으므로
8
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))
@@ -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 { REPO_ROOT } from '../utils/scan.js';
6
- import { inChangeLog, inRefSection, isTargetDoc } from '../utils/scope.js';
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 (!isTargetDoc(file, index.config))
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(REPO_ROOT, rel))) {
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.endsWith('.md'))
54
+ if (!link.anchor || !docExts.has(extname(rel).toLowerCase()))
51
55
  continue;
52
56
  const target = index.files.get(rel);
53
57
  // 색인 범위 밖 문서 (archive 등) 는 앵커를 확인하지 않는다
@@ -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[];
@@ -1,42 +1,55 @@
1
1
  /**
2
- * 마커 ↔ 관리 문서 대조 (`docs/system/rules.md` §4-1).
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
- const ITEM = /^###\s+`\[([a-z]+::[a-z0-9][a-z0-9-]*)\]`/;
9
- /** 관리 문서 항목 slug → 그 헤딩 줄 번호 */
10
- const pendingItemLines = (pending) => {
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
- let inChangeLog = false;
13
- pending.lines.forEach((raw, i) => {
14
- if (/^## 변경 이력/.test(raw))
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 = ITEM.exec(raw);
20
+ const m = ITEM_HEADING.exec(raw);
19
21
  if (m)
20
- out.set(m[1], i + 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(index.config.pending);
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 === index.config.pending)
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 (items.has(id) || file.ignored.has(marker.line))
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 [slug, line] of items) {
50
- if (seen.has(slug) || pending.ignored.has(line))
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: `[${slug}] 를 가리키는 마커가 없다 - 억제하려면 @specthread-ignore`,
71
+ message: `[${id}] 를 가리키는 마커가 없다 - 억제하려면 @specthread-ignore`,
57
72
  });
58
73
  }
59
74
  return findings;