specthread 0.1.5 → 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 +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 +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 +9 -5
  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 +1 -3
  56. package/dist/utils/scan.js +22 -24
  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/scaffold/rules.md CHANGED
@@ -13,7 +13,7 @@
13
13
 
14
14
  ## 1. 개요
15
15
 
16
- 이 프로젝트의 모든 문서가 따르는 형식 규칙. **도메인과 무관한 부분만** 담는다. 경로·마커 종류·상용구처럼 이 프로젝트에서만 성립하는 값은 [`project.md`](./project.md) 가 갖는다.
16
+ 이 프로젝트의 모든 문서가 따르는 형식 규칙. **도메인과 무관한 부분만** 담는다. 스캔 경로·마커 종류처럼 이 프로젝트에서만 성립하는 값은 `config.jsonc` 가 갖고, 그 값의 의미와 맥락은 [`project.md`](./project.md) 가 갖는다.
17
17
 
18
18
  | 파일 | 담는 것 | 층 |
19
19
  |-----|-------|---|
@@ -22,7 +22,7 @@
22
22
  | `spec.md` 템플릿 | 시스템 명세 템플릿 | 코어 |
23
23
  | `plan.md` 템플릿 | 작업 계획 템플릿 | 코어 |
24
24
 
25
- **어느 유형이 어느 템플릿을 쓰는지는 `config.docTypes` 가 정의한다.** 위 표는 파일 목록과 층 표시만 담는다.
25
+ 위 표는 파일 목록과 층 표시만 담는다. 어느 문서가 어느 템플릿을 따르는지는 지금은 사람이 정한다.
26
26
 
27
27
  ## 2. 수평 규칙
28
28
 
@@ -111,20 +111,13 @@ ASCII 박스 드로잉은 쓰지 않는다. 폭을 손으로 맞춰야 하고,
111
111
  검사:
112
112
  - `heading/tail-name-reused`
113
113
  - `heading/numbered-tail`
114
+ - `heading/tail-order`
114
115
 
115
- `참조` · `미확정 사항` · `변경 이력` 세 이름을 본문 절 제목으로 쓰지 않는다. 기계가 이름으로 꼬리 절 위치를 찾아 채우므로 (§3-3), 같은 이름의 본문 절이 있으면 엉뚱한 자리를 덮어쓸 수 있다.
116
+ `참조` · `미확정 사항` · `변경 이력` 세 이름을 본문 절 제목으로 쓰지 않는다. 기계가 이름으로 꼬리 절 위치를 찾아 채우므로 (§3-3), 같은 이름의 본문 절이 있으면 엉뚱한 범위를 덮어쓸 수 있다.
116
117
 
117
- 같은 주제를 다루는 본문 절에는 한정어를 붙인다 - `참조 방식` / `참조 규칙` 처럼.
118
-
119
- ### 2-6. 문장 부호
120
-
121
- 검사:
122
- - `style/em-dash`
123
- - `style/rule-undeclared`
124
-
125
- **em dash 를 쓰지 않는다.** 하이픈 `-` 으로 적는다.
118
+ 꼬리 절은 이 순서로 둔다. 없는 절은 건너뛴다. 순서가 어긋난 문서는 생성기가 고치지 않는다.
126
119
 
127
- 강제: `no-em-dash` 훅 (프로젝트에서 설정). `config.features.emDash` 가 `false` 면 비활성화.
120
+ 같은 주제를 다루는 본문 절에는 한정어를 붙인다 - `참조 방식` / `참조 규칙` 처럼.
128
121
 
129
122
  ## 3. 참조 방식
130
123
 
@@ -169,7 +162,7 @@ ASCII 박스 드로잉은 쓰지 않는다. 폭을 손으로 맞춰야 하고,
169
162
  - 아직 데이터가 없는 항목도 본문에 둔다. 구현 여부는 링크 유무로 드러낸다
170
163
  - 아직 정하지 않은 것은 미확정 사항 절로 간다
171
164
  - 수치/제약은 문서가 정본이다. 판정 기준: _이 문서대로 코드가 짜였는지 검증할 수 있는가_
172
- - 역방향 링크가 건강 지표다. 코드가 해당 절을 가리키지 않으면 검사기가 경고한다
165
+ - 역방향 링크가 건강 지표다. 코드가 해당 절을 가리키는지는 리뷰에서 확인한다 (검사기는 보지 않는다)
173
166
  - 한 대상에 소유 절은 하나다. 겹치는 쪽에 소유처를 한 줄 적는다
174
167
 
175
168
  ### 3-3. 참조 절 - 기계 생성
@@ -192,7 +185,7 @@ ASCII 박스 드로잉은 쓰지 않는다. 폭을 손으로 맞춰야 하고,
192
185
 
193
186
  같은 대상을 여러 번 가리키면 한 줄로 합치고 어느 절에서 참조됐는지를 붙인다.
194
187
 
195
- **자동 로드되는 룰 문서는 참조 절을 두지 않는다.** 매 세션 통째로 읽히는 문서는 모든 줄의 비용을 반복해서 내고, 이미 사람이 큐레이션한 라우팅 표를 갖고 있다. 대상은 [`project.md`](./project.md) 가 지정한다.
188
+ **자동 로드되는 룰 문서는 참조 절을 두지 않는다.** 매 세션 통째로 읽히는 문서는 모든 줄의 비용을 반복해서 내고, 이미 사람이 큐레이션한 라우팅 표를 갖고 있다. 대상은 `config.skipRefs` 에 적는다.
196
189
 
197
190
  ### 3-4. 참조와 절 폐기
198
191
 
@@ -271,14 +264,13 @@ ASCII 박스 드로잉은 쓰지 않는다. 폭을 손으로 맞춰야 하고,
271
264
 
272
265
  | 위치 | 표기 | 모양 |
273
266
  |-----|-----|-----|
274
- <!-- @specthread-ignore -->
275
- | 마커 | `PENDING::deps::auth-flow` | 산문·주석 안 |
276
- | 관리 문서 항목 | `` `[deps::auth-flow]` `` | `###` 헤딩 |
277
- | 문서 미확정 사항 절 | `` `[deps::auth-flow]` `` | `li` |
267
+ | 마커 | `PENDING::<종류>::<slug>` | 산문·주석 안 |
268
+ | 관리 문서 항목 | `` `[<종류>::<slug>]` `` | `###` 헤딩 |
269
+ | 문서 미확정 사항 절 | `` `[<종류>::<slug>]` `` | `li` |
278
270
 
279
271
  마커는 산문 안에 박히므로 자기를 식별할 `PENDING` 접두가 필요하다. 관리 문서와 미확정 사항 절은 위치 자체가 맥락이므로 접두 없이 id 만 쓴다. `grep -c "PENDING::design"` 이 실제 발생 지점만 세는 것도 이 구분 덕분이다.
280
272
 
281
- 미확정 사항 절은 관리 문서의 백링크를 뒤집어 자동 생성한다 (검사: `pending/section-stale`). 절이 이미 있는 문서만 채운다.
273
+ 미확정 사항 절은 관리 문서 항목의 `참조:` 줄을 뒤집어 자동 생성한다 (검사: `pending/section-stale`). 절이 이미 있는 문서만 채운다. 작업 문서는 대상이 아니다. 흡수 후 사라져 관리 문서가 가리킬 수 없으므로 생성할 내용이 없다.
282
274
 
283
275
  ### 4-1. 마커
284
276
 
@@ -291,7 +283,7 @@ PENDING::<종류>::<slug>
291
283
  | 요소 | 규칙 |
292
284
  |-----|-----|
293
285
  | `PENDING` | 고정 접두 |
294
- | 종류 | 소문자. `system` 은 코어 예약, 프로젝트 종류는 `config.markers.types` 에서 정의 |
286
+ | 종류 | 소문자. `system` 은 코어 예약, 프로젝트 종류는 `config.markers.types` 에서 정의. 없는 종류는 `marker/unknown-type` |
295
287
  | slug | 전역 유일, kebab-case |
296
288
  | 구분자 | `::` 통일 |
297
289
  | 표기 | 문서에서는 백틱으로 감싼다 |
@@ -317,6 +309,9 @@ JSON "_pending": "style::api-version"
317
309
 
318
310
  - `marker/orphan`: 코드 마커 ID 가 관리 문서에 없음 (추적되지 않는 미확정)
319
311
  - `marker/unmarked`: 관리 문서 항목 ID 가 코드나 문서에 없음 (이미 해결된 것)
312
+ - `marker/unknown-type`: 마커나 관리 문서 항목의 종류가 `config.markers.types` 에 없음
313
+
314
+ 변경 이력 안의 마커는 과거 기록이라 세지 않는다.
320
315
 
321
316
  ### 4-2. 관리 문서
322
317
 
@@ -326,12 +321,13 @@ JSON "_pending": "style::api-version"
326
321
  - `pending/inline-options`
327
322
  - `pending/work-link`
328
323
  - `pending/timepoint`
324
+ - `pending/unknown-timepoint`
329
325
  - `pending/summary-missing`
330
326
  - `pending/summary-stale`
331
327
 
332
328
  미확정 항목을 `pending.md` 한 파일에 모으고 id 순으로 정렬한다.
333
329
 
334
- 관리 문서 안에서 종류마다 `##` 섹션을 하나씩 둔다. 종류 값은 `config.markers.types` 가 정의한다.
330
+ 관리 문서 안에서 종류마다 `##` 섹션을 하나씩 둔다. 섹션은 사람이 만들고, 종류 값은 `config.markers.types` 에 있어야 한다.
335
331
 
336
332
  ```markdown
337
333
  ## 2. design
@@ -372,7 +368,7 @@ JSON "_pending": "style::api-version"
372
368
  `작성일`(항상 과거)과 `해결 예정`(항상 미래) 두 라벨로 구분한다. 해결 예정이 없으면 생략한다.
373
369
 
374
370
  - 해결 예정에 달력 날짜를 쓰지 않는다. 작성일과 같은 모양이 되면 구분이 안 된다
375
- - 라벨 값은 검사하지 않는다. 새 프로젝트는 마일스톤 목록이 비어 있으므로, 집합 검사를 걸면 첫 항목부터 위반이 된다. `config.markers.timepoints` 는 참고 목록이지 검사 관문이 아니다
371
+ - 라벨 값은 `config.markers.timepoints` 가 비어 있으면 검사하지 않는다. 새 프로젝트는 마일스톤 목록이 비어 있으므로 첫 항목부터 위반이 되지 않게 한다. 목록을 채우면 그 밖의 라벨은 `pending/unknown-timepoint` 로 지적한다
376
372
 
377
373
  **등록 기준**
378
374
 
@@ -384,12 +380,17 @@ _정하지 않으면 무엇이 막히는지_ 말할 수 있어야 한다. 이것
384
380
 
385
381
  **자동 생성**
386
382
 
387
- - 백링크: slug 로 `grep` 해서 코드·문서 위치를 자동 수집한다
388
- - 요약 표: 각 절 머리에 `| id | 항목 | 해결 예정 | 걸린 곳 |` 표를 자동 생성한다. 세 열 모두 손으로 셀 수 없는 값이라 `stale` 검사로 어긋남을 잡는다
389
- - 마커가 없는 미확정(문서 전체에 걸리는 것)도 담는다. 백링크에 해당 문서만 적는다
383
+ - 문서 미확정 사항 절: 항목의 `참조:` 줄이 가리키는 문서마다 그 문서의 절에 항목이 실린다
384
+ - 요약 표: 각 절 머리에 `| id | 항목 | 해결 예정 | 걸린 곳 |` 표를 자동 생성한다. `걸린 곳` 은 그 id 의 마커 수다. 손으로 셀 수 없는 값이라 `stale` 검사로 어긋남을 잡는다
385
+ - 마커가 없는 미확정(문서 전체에 걸리는 것)도 담을 수 있다. `참조:` 줄에 해당 문서를 적고, 항목 헤딩 바로 위에 `<!-- @specthread-ignore -->` 를 둬 `marker/unmarked` 를 막는다
390
386
 
391
387
  ## 5. 규칙 변경 절차
392
388
 
389
+ 검사:
390
+ - `style/rule-undeclared`
391
+
392
+ 검사기가 강제하는 규칙은 이 문서의 해당 절에 검사 id 를 적는다. 적지 않으면 문서화되지 않은 규칙을 강제하는 것이므로 검사기가 지적한다. 반대로 id 가 없는 절은 사람이 검사하는 규칙이다.
393
+
393
394
  문서를 고치다 보면 규칙이 안 맞는 곳이 나온다. 그때 바로 규칙을 바꾸지 않는다.
394
395
 
395
396
  | 단계 | 처리 |
@@ -409,7 +410,7 @@ _정하지 않으면 무엇이 막히는지_ 말할 수 있어야 한다. 이것
409
410
 
410
411
  ### 문서
411
412
 
412
- - [`project.md`](./project.md) - §1, §3-3
413
+ - [`project.md`](./project.md) - §1
413
414
 
414
415
  ## 미확정 사항
415
416
 
@@ -25,7 +25,6 @@
25
25
  - [6. 검증 기준](#6-검증-기준)
26
26
  - [7. 예상 산출물](#7-예상-산출물)
27
27
  - [참조](#참조)
28
- - [미확정 사항](#미확정-사항)
29
28
  - [변경 이력](#변경-이력)
30
29
 
31
30
  ## 1. 목표
@@ -81,10 +80,6 @@
81
80
  ### 문서
82
81
  ### 코드·데이터
83
82
 
84
- ## 미확정 사항
85
-
86
- - `[<종류>::<slug>]` <한 줄 설명>
87
-
88
83
  ## 변경 이력
89
84
 
90
85
  | 날짜 | 내용 |
@@ -136,9 +131,10 @@
136
131
  | 절 | 규칙 |
137
132
  |---|-----|
138
133
  | 참조 | 본문 링크를 모아 기계가 채운다 |
139
- | 미확정 사항 | 마커 기반 생성 뷰 |
140
134
  | 변경 이력 | 한 커밋이 한 줄 |
141
135
 
136
+ 작업 문서에는 미확정 사항 절을 두지 않는다. 작업 문서는 흡수 후 사라지므로 관리 문서가 가리킬 수 없고, 따라서 생성할 내용이 없다.
137
+
142
138
  ## 참조
143
139
 
144
140
  ### 문서
@@ -151,7 +147,7 @@
151
147
 
152
148
  ## 미확정 사항
153
149
 
154
- 해당 없음 - 이 문서를 가리키는 미확정 항목이 없다 ([`pending.md`](../../specthread/pending.md)).
150
+ 해당 없음 - 이 문서를 가리키는 미확정 항목이 없다 ([`pending.md`](../pending.md)).
155
151
 
156
152
  ## 변경 이력
157
153