specthread 0.1.5 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +171 -66
  2. package/dist/bin/check.js +9 -34
  3. package/dist/bin/cli.js +5 -4
  4. package/dist/bin/generate.js +32 -19
  5. package/dist/bin/open-project.d.ts +5 -0
  6. package/dist/bin/open-project.js +26 -0
  7. package/dist/checks/changelog.js +5 -4
  8. package/dist/checks/headings.d.ts +0 -1
  9. package/dist/checks/headings.js +15 -6
  10. package/dist/checks/links.js +7 -4
  11. package/dist/checks/markers.d.ts +3 -1
  12. package/dist/checks/markers.js +33 -18
  13. package/dist/checks/pending.js +57 -23
  14. package/dist/checks/references.js +2 -2
  15. package/dist/checks/sections.js +3 -6
  16. package/dist/checks/style.d.ts +0 -8
  17. package/dist/checks/style.js +23 -43
  18. package/dist/checks/timestamps.js +5 -5
  19. package/dist/checks/toc.js +4 -6
  20. package/dist/commands/config-template.d.ts +8 -0
  21. package/{scaffold/config.jsonc → dist/commands/config-template.js} +48 -40
  22. package/dist/commands/init.js +121 -47
  23. package/dist/commands/upgrade-prompt.d.ts +12 -0
  24. package/dist/commands/upgrade-prompt.js +147 -0
  25. package/dist/config-loader.d.ts +44 -1
  26. package/dist/config-loader.js +219 -36
  27. package/dist/config.schema.d.ts +16 -35
  28. package/dist/config.schema.js +1 -7
  29. package/dist/constants/docs.d.ts +8 -4
  30. package/dist/constants/docs.js +8 -5
  31. package/dist/constants/exit.d.ts +12 -0
  32. package/dist/constants/exit.js +12 -0
  33. package/dist/constants/paths.d.ts +25 -0
  34. package/dist/constants/paths.js +25 -0
  35. package/dist/constants/patterns.d.ts +13 -6
  36. package/dist/constants/patterns.js +16 -6
  37. package/dist/constants/rules.d.ts +7 -3
  38. package/dist/constants/rules.js +7 -3
  39. package/dist/gen/pending-section.js +20 -16
  40. package/dist/gen/references.js +13 -9
  41. package/dist/gen/summary.d.ts +1 -1
  42. package/dist/gen/summary.js +11 -7
  43. package/dist/gen/toc.js +5 -2
  44. package/dist/run-check.d.ts +5 -0
  45. package/dist/run-check.js +35 -0
  46. package/dist/types.d.ts +6 -4
  47. package/dist/utils/anchor.d.ts +1 -1
  48. package/dist/utils/anchor.js +1 -1
  49. package/dist/utils/ignore.d.ts +2 -8
  50. package/dist/utils/ignore.js +23 -6
  51. package/dist/utils/parse.d.ts +6 -6
  52. package/dist/utils/parse.js +18 -27
  53. package/dist/utils/path-match.d.ts +19 -0
  54. package/dist/utils/path-match.js +27 -0
  55. package/dist/utils/report.d.ts +1 -7
  56. package/dist/utils/report.js +10 -3
  57. package/dist/utils/resolve.d.ts +15 -5
  58. package/dist/utils/resolve.js +63 -25
  59. package/dist/utils/root.d.ts +2 -0
  60. package/dist/utils/root.js +19 -0
  61. package/dist/utils/scan.d.ts +1 -3
  62. package/dist/utils/scan.js +28 -26
  63. package/dist/utils/scope.d.ts +37 -11
  64. package/dist/utils/scope.js +60 -24
  65. package/package.json +3 -3
  66. package/scaffold/AGENTS.md +4 -6
  67. package/scaffold/claude/skills/{check.md → check/SKILL.md} +6 -3
  68. package/scaffold/claude/skills/{gen.md → gen/SKILL.md} +5 -3
  69. package/scaffold/claude/skills/{plan-close.md → plan-close/SKILL.md} +1 -0
  70. package/scaffold/claude/skills/{plan-open.md → plan-open/SKILL.md} +1 -0
  71. package/scaffold/claude/skills/{plan-run.md → plan-run/SKILL.md} +1 -0
  72. package/scaffold/pending.md +1 -1
  73. package/scaffold/project.md +1 -1
  74. package/scaffold/rules.md +28 -27
  75. package/scaffold/templates/plan.md +3 -7
@@ -1,9 +1,9 @@
1
1
  import { readFileSync, existsSync } from "node:fs";
2
2
  import { join } from "node:path";
3
3
  import { DEFAULT_CONFIG } from "./config.schema.js";
4
+ import { CONFIG_PATH, LOCAL_CONFIG_PATH } from "./constants/paths.js";
4
5
  import { ALL_RULE_GROUPS } from "./constants/rules.js";
5
- const CONFIG_FILE = "specthread/config.jsonc";
6
- const LOCAL_CONFIG_FILE = "specthread/config.local.jsonc";
6
+ import { normalizeConfigPath } from "./utils/path-match.js";
7
7
  // ---------------------------------------------------------------------------
8
8
  // JSONC 파싱
9
9
  // ---------------------------------------------------------------------------
@@ -34,10 +34,14 @@ const stripJsonComments = (text) => {
34
34
  i++;
35
35
  continue;
36
36
  }
37
+ // 블록 주석 안의 줄바꿈은 남긴다. 지우면 문법 오류의 줄 번호가 실제 파일과 어긋난다
37
38
  if (ch === "/" && text[i + 1] === "*") {
38
39
  i += 2;
39
- while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
40
+ while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) {
41
+ if (text[i] === "\n")
42
+ result += "\n";
40
43
  i++;
44
+ }
41
45
  i += 2;
42
46
  continue;
43
47
  }
@@ -48,18 +52,168 @@ const stripJsonComments = (text) => {
48
52
  }
49
53
  return result;
50
54
  };
51
- const parseJsonc = (text) => JSON.parse(stripJsonComments(text));
55
+ /**
56
+ * 닫는 괄호 앞 쉼표를 지운다. 주석을 지운 뒤에 돌린다.
57
+ *
58
+ * JSONC 는 trailing comma 를 허용하고, Prettier 도 .jsonc 를 저장할 때 기본으로 넣는다.
59
+ * 이걸 막으면 포맷만 해도 설정 파일을 읽지 못한다.
60
+ */
61
+ const stripTrailingCommas = (text) => {
62
+ let result = "";
63
+ let inString = false;
64
+ let escapeNext = false;
65
+ for (let i = 0; i < text.length; i++) {
66
+ const ch = text[i];
67
+ if (escapeNext) {
68
+ escapeNext = false;
69
+ }
70
+ else if (inString) {
71
+ if (ch === "\\")
72
+ escapeNext = true;
73
+ if (ch === '"')
74
+ inString = false;
75
+ }
76
+ else if (ch === '"') {
77
+ inString = true;
78
+ }
79
+ else if (ch === ",") {
80
+ let j = i + 1;
81
+ while (j < text.length && /\s/.test(text[j]))
82
+ j++;
83
+ if (text[j] === "}" || text[j] === "]")
84
+ continue;
85
+ }
86
+ result += ch;
87
+ }
88
+ return result;
89
+ };
90
+ /**
91
+ * 설정을 쓸 수 없을 때 던진다.
92
+ *
93
+ * 문제를 하나씩 던지면 사용자가 고치고 다시 돌리기를 반복해야 한다. 한 번에 모아 낸다.
94
+ */
95
+ export class ConfigError extends Error {
96
+ problems;
97
+ constructor(problems) {
98
+ super(problems.map((p) => `${p.file}${p.key === "" ? "" : ` ${p.key}`}: ${p.message}`).join("\n"));
99
+ this.problems = problems;
100
+ }
101
+ }
102
+ const parseJsonc = (text, file) => {
103
+ try {
104
+ return JSON.parse(stripTrailingCommas(stripJsonComments(text)));
105
+ }
106
+ catch (e) {
107
+ throw new ConfigError([{ file, key: "", message: `JSONC 문법 오류 - ${e.message}` }]);
108
+ }
109
+ };
52
110
  // ---------------------------------------------------------------------------
53
- // Deep merge — 중첩 객체만 재귀, 배열은 덮어쓰기
111
+ // 검증
54
112
  // ---------------------------------------------------------------------------
55
113
  const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
56
- const deepMerge = (base, override) => {
114
+ const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
115
+ const stringArray = (v) => (isStringArray(v) ? null : "문자열 배열이어야 한다");
116
+ const string = (v) => (typeof v === "string" ? null : "문자열이어야 한다");
117
+ // 문자열 "false" 는 참으로 읽히므로 받지 않는다
118
+ const bool = (v) => (typeof v === "boolean" ? null : "true 또는 false 여야 한다 (따옴표 없이)");
119
+ const skipCheckList = (v) => {
120
+ if (!Array.isArray(v))
121
+ return "배열이어야 한다";
122
+ const ok = v.every((e) => typeof e === "string" || (isPlainObject(e) && typeof e.path === "string" && isStringArray(e.only)));
123
+ return ok ? null : '항목은 경로 문자열이거나 { "path": 문자열, "only": 문자열 배열 } 이어야 한다';
124
+ };
125
+ const SCHEMA = {
126
+ path: { anyKey: stringArray },
127
+ fileKinds: { fields: { doc: { check: stringArray }, source: { check: stringArray } } },
128
+ features: { fields: { markers: { check: bool }, references: { check: bool } } },
129
+ markers: { fields: { types: { check: stringArray }, timepoints: { check: stringArray } } },
130
+ ignoreDocNames: { check: stringArray },
131
+ skipCheck: { check: skipCheckList },
132
+ skipRefs: { check: stringArray },
133
+ work: { check: string },
134
+ };
135
+ /** 제거한 키와 그 이유. 기존 config 가 깨지지 않게 오류 대신 경고로 알린다 */
136
+ export const REMOVED_KEYS = {
137
+ locale: "읽는 곳이 없었다",
138
+ docTypes: "읽는 곳이 없었다",
139
+ rules: `규칙 문서는 specthread/rules.md 고정이다`,
140
+ pending: `관리 문서는 specthread/pending.md 고정이다`,
141
+ project: `프로젝트 문서는 specthread/project.md 고정이다`,
142
+ "features.emDash": "em dash 검사를 제거했다",
143
+ };
144
+ /**
145
+ * 한 계층을 검증하고, 제거한 키와 모르는 키를 뺀 사본을 돌려준다.
146
+ *
147
+ * 병합 전에 계층마다 본다. 병합 뒤에 보면 틀린 값이 어느 파일에서 왔는지 알 수 없다.
148
+ */
149
+ const validateLayer = (raw, file) => {
150
+ const problems = [];
151
+ const warnings = [];
152
+ const removed = [];
153
+ if (!isPlainObject(raw)) {
154
+ return { value: {}, problems: [{ file, key: "", message: "최상위가 객체여야 한다" }], warnings, removed };
155
+ }
156
+ const walk = (obj, schema, prefix) => {
157
+ const out = {};
158
+ for (const [key, v] of Object.entries(obj)) {
159
+ const full = prefix === "" ? key : `${prefix}.${key}`;
160
+ if (full in REMOVED_KEYS) {
161
+ removed.push({ file, key: full });
162
+ warnings.push(`${file}: ${full} 는 제거된 키다. 지워도 된다 - ${REMOVED_KEYS[full]}`);
163
+ continue;
164
+ }
165
+ const field = schema[key];
166
+ if (field === undefined) {
167
+ warnings.push(`${file}: 알 수 없는 키 ${full} - 무시한다`);
168
+ continue;
169
+ }
170
+ if (field.check !== undefined) {
171
+ const message = field.check(v);
172
+ if (message === null)
173
+ out[key] = v;
174
+ else
175
+ problems.push({ file, key: full, message });
176
+ continue;
177
+ }
178
+ if (!isPlainObject(v)) {
179
+ problems.push({ file, key: full, message: "객체여야 한다" });
180
+ continue;
181
+ }
182
+ if (field.anyKey !== undefined) {
183
+ const check = field.anyKey;
184
+ const bad = Object.entries(v).filter(([, x]) => check(x) !== null);
185
+ for (const [k, x] of bad)
186
+ problems.push({ file, key: `${full}.${k}`, message: check(x) ?? "" });
187
+ if (bad.length === 0)
188
+ out[key] = v;
189
+ continue;
190
+ }
191
+ out[key] = walk(v, field.fields ?? {}, full);
192
+ }
193
+ return out;
194
+ };
195
+ return { value: walk(raw, SCHEMA, ""), problems, warnings, removed };
196
+ };
197
+ // ---------------------------------------------------------------------------
198
+ // Deep merge - 중첩 객체만 재귀, 배열은 덮어쓰기
199
+ // ---------------------------------------------------------------------------
200
+ /**
201
+ * 객체지만 통째로 교체하는 키.
202
+ *
203
+ * `path` 는 키가 자유 라벨이라, 키 단위로 병합하면 기본 키 (`docs`, `specthread`) 를
204
+ * 생략으로는 지울 수 없다. "이 경로들을 스캔한다" 는 뜻이 되려면 배열처럼 교체해야 한다.
205
+ */
206
+ const REPLACE_KEYS = new Set(["path"]);
207
+ const deepMerge = (base, override, depth = 0) => {
57
208
  const result = { ...base };
58
209
  for (const key of Object.keys(override)) {
59
210
  const baseVal = result[key];
60
211
  const overVal = override[key];
61
- if (isPlainObject(baseVal) && isPlainObject(overVal)) {
62
- result[key] = deepMerge(baseVal, overVal);
212
+ if (depth === 0 && REPLACE_KEYS.has(key)) {
213
+ result[key] = overVal;
214
+ }
215
+ else if (isPlainObject(baseVal) && isPlainObject(overVal)) {
216
+ result[key] = deepMerge(baseVal, overVal, depth + 1);
63
217
  }
64
218
  else if (overVal !== undefined) {
65
219
  result[key] = overVal;
@@ -68,39 +222,68 @@ const deepMerge = (base, override) => {
68
222
  return result;
69
223
  };
70
224
  // ---------------------------------------------------------------------------
71
- // skipCheck 검증
225
+ // 병합 후 처리
72
226
  // ---------------------------------------------------------------------------
73
227
  const ruleGroupSet = new Set(ALL_RULE_GROUPS);
74
- const validateSkipCheck = (items) => {
75
- for (const item of items) {
76
- if (typeof item === "string")
228
+ /** 모르는 군은 경고만 한다. 그 군의 지적은 어차피 없으므로 걸러도 결과가 같다 */
229
+ const skipCheckWarnings = (items) => items.flatMap((item) => typeof item === "string"
230
+ ? []
231
+ : item.only
232
+ .filter((group) => !ruleGroupSet.has(group))
233
+ .map((group) => `skipCheck: unknown rule group "${group}" in path "${item.path}". ` +
234
+ `Valid groups: ${ALL_RULE_GROUPS.join(", ")}`));
235
+ /** 경로 값을 색인 경로와 같은 형태로 맞춘다. 소비처는 정규화된 값만 본다 */
236
+ const normalizePaths = (config) => ({
237
+ ...config,
238
+ skipCheck: config.skipCheck.map((e) => typeof e === "string" ? normalizeConfigPath(e) : { ...e, path: normalizeConfigPath(e.path) }),
239
+ skipRefs: config.skipRefs.map(normalizeConfigPath),
240
+ work: normalizeConfigPath(config.work),
241
+ });
242
+ /**
243
+ * 기본값 → config.jsonc → config.local.jsonc 순으로 병합한다. 출력도 예외도 없다.
244
+ *
245
+ * 쓸 수 없는 값은 병합에서 빼고 `problems` 에 담는다. 업데이트 프롬프트처럼 설정이 틀려도
246
+ * 중단하지 않아야 하는 기능이 이 결과를 사용한다.
247
+ */
248
+ export const readConfig = (root = process.cwd()) => {
249
+ let merged = { ...DEFAULT_CONFIG };
250
+ const problems = [];
251
+ const warnings = [];
252
+ const removed = [];
253
+ for (const file of [CONFIG_PATH, LOCAL_CONFIG_PATH]) {
254
+ const abs = join(root, file);
255
+ if (!existsSync(abs))
77
256
  continue;
78
- for (const group of item.only) {
79
- if (!ruleGroupSet.has(group)) {
80
- console.warn(`[specthread] skipCheck: unknown rule group "${group}" in path "${item.path}". ` +
81
- `Valid groups: ${ALL_RULE_GROUPS.join(", ")}`);
82
- }
257
+ let raw;
258
+ try {
259
+ raw = parseJsonc(readFileSync(abs, "utf-8"), file);
83
260
  }
261
+ catch (e) {
262
+ if (!(e instanceof ConfigError))
263
+ throw e;
264
+ problems.push(...e.problems);
265
+ continue;
266
+ }
267
+ const layer = validateLayer(raw, file);
268
+ problems.push(...layer.problems);
269
+ warnings.push(...layer.warnings);
270
+ removed.push(...layer.removed);
271
+ merged = deepMerge(merged, layer.value);
84
272
  }
85
- return items;
273
+ const config = normalizePaths(merged);
274
+ warnings.push(...skipCheckWarnings(config.skipCheck));
275
+ return { config, problems, warnings, removed };
86
276
  };
87
- // ---------------------------------------------------------------------------
88
- // Public API
89
- // ---------------------------------------------------------------------------
90
- export const loadConfig = (cwd = process.cwd()) => {
91
- let config = { ...DEFAULT_CONFIG };
92
- const configPath = join(cwd, CONFIG_FILE);
93
- if (existsSync(configPath)) {
94
- const raw = readFileSync(configPath, "utf-8");
95
- const parsed = parseJsonc(raw);
96
- config = deepMerge(config, parsed);
97
- }
98
- const localPath = join(cwd, LOCAL_CONFIG_FILE);
99
- if (existsSync(localPath)) {
100
- const raw = readFileSync(localPath, "utf-8");
101
- const parsed = parseJsonc(raw);
102
- config = deepMerge(config, parsed);
103
- }
104
- config.skipCheck = validateSkipCheck(config.skipCheck);
277
+ /**
278
+ * 기본값 → config.jsonc → config.local.jsonc 순으로 병합한 설정.
279
+ *
280
+ * 쓸 수 없는 값이 하나라도 있으면 `ConfigError` 를 던진다. 경고는 출력만 하고 진행한다.
281
+ */
282
+ export const loadConfig = (root = process.cwd()) => {
283
+ const { config, problems, warnings } = readConfig(root);
284
+ for (const w of warnings)
285
+ console.warn(`[specthread] ${w}`);
286
+ if (problems.length > 0)
287
+ throw new ConfigError(problems);
105
288
  return config;
106
289
  };
@@ -1,7 +1,8 @@
1
1
  /**
2
- * specthread.config.jsonc 스키마.
2
+ * specthread/config.jsonc 스키마.
3
3
  *
4
- * 파싱: strip-json-comments 로 주석 제거 후 JSON.parse().
4
+ * 파싱과 검증은 `config-loader.ts` 가 한다. 규약 파일의 위치는 설정이 아니라
5
+ * `constants/paths.ts` 가 갖는다.
5
6
  */
6
7
  import type { RuleGroup } from "./constants/rules.ts";
7
8
  /**
@@ -20,6 +21,9 @@ export interface FileKindsConfig {
20
21
  * 프로젝트 경로. 자유 KV - 키는 용도 라벨, 값은 경로 배열.
21
22
  * 디렉터리면 재귀 스캔, 파일이면 직접 로드. 파싱 전략은 확장자로 결정.
22
23
  *
24
+ * 병합 시 객체 전체를 교체한다. 키 단위로 병합하면 기본 키를 생략으로 지울 수 없다.
25
+ * 규약 파일 (`constants/paths.ts`) 은 여기 적지 않아도 항상 색인한다.
26
+ *
23
27
  * 예:
24
28
  * "docs": ["docs/"] - docs-only 프로젝트
25
29
  * "source": ["client/src/"], "data": ["data/"] - 소스+데이터
@@ -29,38 +33,30 @@ export type PathConfig = Record<string, string[]>;
29
33
  /**
30
34
  * 기능 단위 on/off. tsconfig 의 strict/noImplicitAny 모델.
31
35
  *
32
- * 28 개 규칙은 독립적이지 않다 (heading 이 깨지면 section-ref 가 깨짐).
36
+ * 규칙은 독립적이지 않다 (heading 이 깨지면 section-ref 가 깨짐).
33
37
  * 개별 레벨이 아닌 기능 플래그로 묶는다.
34
38
  */
35
39
  export interface FeaturesConfig {
36
40
  /** 마커 체계 전체. false → marker/*, pending/* 검사 + pending 추적 비활성화 */
37
41
  markers: boolean;
38
- /** em dash 검사 + 치환 훅. false → style/em-dash 검사 + hook 비활성화 */
39
- emDash: boolean;
40
42
  /** 참조 절 자동 생성. false → reference/* 검사 + gen references 스킵 */
41
43
  references: boolean;
42
44
  }
43
45
  export interface MarkersConfig {
44
46
  /**
45
47
  * 마커 종류. "system" 은 코어 예약, 나머지는 프로젝트 정의.
48
+ * 마커와 관리 문서 항목의 종류가 여기 없으면 `marker/unknown-type`.
46
49
  * 예: ["system", "design", "balance", "deps", "style"]
47
50
  */
48
51
  types: string[];
49
52
  /**
50
53
  * 처리 시점 라벨. 마일스톤 등.
54
+ * 비어 있지 않으면 `해결 예정` 라벨이 여기 없을 때 `pending/unknown-timepoint`.
55
+ * 비어 있으면 라벨을 검사하지 않는다.
51
56
  * 예: ["M1", "M2", "M3"]
52
57
  */
53
58
  timepoints: string[];
54
59
  }
55
- export interface FrontmatterSchema {
56
- required: string[];
57
- optional: string[];
58
- }
59
- export interface DocTypeConfig {
60
- path: string;
61
- template: string;
62
- frontmatter?: FrontmatterSchema;
63
- }
64
60
  /**
65
61
  * skipCheck 항목의 객체 형태.
66
62
  * path 에 매칭되는 파일에 대해 only 에 지정한 군만 검사한다.
@@ -69,13 +65,6 @@ export interface SkipCheckEntry {
69
65
  path: string;
70
66
  only: RuleGroup[];
71
67
  }
72
- /**
73
- * 현재 한국어 고정. 다국어 필요 시 locale 별 문자열 맵으로 확장.
74
- *
75
- * 한국어 의존: TAIL_NAMES, TIMEPOINT 정규식, SENTENCE_END,
76
- * 출력 메시지, 참조 절 제목, 요약 표 헤더.
77
- */
78
- export type Locale = "ko";
79
68
  export interface SpecthreadConfig {
80
69
  /** 스캔 대상 경로. 자유 KV */
81
70
  path: PathConfig;
@@ -83,28 +72,20 @@ export interface SpecthreadConfig {
83
72
  fileKinds: FileKindsConfig;
84
73
  features: FeaturesConfig;
85
74
  markers: MarkersConfig;
86
- docTypes: Record<string, DocTypeConfig>;
87
75
  /**
88
76
  * 문서명 해소 시 무시할 단어.
89
- * 예: ["spec"] - "spec §4" 가 template/spec.md 로 잘못 매칭되는 것 방지.
77
+ * 예: ["spec"] - "spec §4" 가 templates/spec.md 로 잘못 매칭되는 것 방지.
90
78
  */
91
79
  ignoreDocNames: string[];
92
80
  /**
93
- * 규칙 검사를 건너뛸 경로.
94
- * - string: 해당 경로 prefix 의 전체 검사를 건너뛴다
95
- * - { path, only }: 해당 경로에서 지정한 군만 검사한다
81
+ * 규칙 검사를 건너뛸 경로. 경로 아래 (디렉터리 경계) 의 파일에 적용한다.
82
+ * - string: 해당 경로의 검사·생성을 전부 건너뛴다
83
+ * - { path, only }: 해당 경로에서 지정한 군만 검사·생성한다
96
84
  */
97
85
  skipCheck: (string | SkipCheckEntry)[];
98
- /** 참조 절 생성을 건너뛸 경로 */
86
+ /** 참조 절을 만들지 않을 경로. 경로 아래 (디렉터리 경계) 의 문서에 적용한다 */
99
87
  skipRefs: string[];
100
- locale: Locale;
101
- /** 규칙 문서 */
102
- rules: string;
103
- /** 미확정 사항 정본 */
104
- pending: string;
105
- /** 프로젝트 맥락 문서 */
106
- project: string;
107
- /** 초안 문서 폴더 */
88
+ /** 작업 문서 폴더. 흡수 후 사라지므로 미확정 사항 절 생성·검사에서 뺀다 */
108
89
  work: string;
109
90
  }
110
91
  export declare const DEFAULT_FILE_KINDS: FileKindsConfig;
@@ -46,20 +46,14 @@ export const DEFAULT_CONFIG = {
46
46
  fileKinds: DEFAULT_FILE_KINDS,
47
47
  features: {
48
48
  markers: true,
49
- emDash: true,
50
49
  references: true,
51
50
  },
52
51
  markers: {
53
52
  types: ["system"],
54
53
  timepoints: [],
55
54
  },
56
- docTypes: {},
57
55
  ignoreDocNames: [],
58
56
  skipCheck: [],
59
57
  skipRefs: [],
60
- locale: "ko",
61
- rules: "specthread/rules.md",
62
- pending: "specthread/pending.md",
63
- project: "specthread/project.md",
64
- work: "docs/work/",
58
+ work: "docs/work",
65
59
  };
@@ -1,10 +1,9 @@
1
1
  /**
2
2
  * 문서 체계 값 - 여러 곳이 같은 값을 봐야 하는 것들.
3
3
  *
4
- * 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다. `TAIL_NAMES` 가
5
- * `utils/parse.ts` 와 `checks/headings.ts` 에 각각 있어 실제로 그 상태였다.
4
+ * 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다.
6
5
  *
7
- * 규칙 본문은 `docs/system/rules.md` 가 갖는다. 여기는 그 규칙이 쓰는 값만 담는다.
6
+ * 규칙 본문은 `specthread/rules.md` 가 갖는다. 여기는 그 규칙이 쓰는 값만 담는다.
8
7
  */
9
8
  /**
10
9
  * 꼬리 절 예약어 (`rules.md` §2-5).
@@ -12,4 +11,9 @@
12
11
  * 파서가 꼬리 절 경계를 잡는 데 쓰고, 검사기가 본문 절이 이 이름을 쓰는지 본다.
13
12
  * 순서가 곧 문서 안 등장 순서다.
14
13
  */
15
- export declare const TAIL_NAMES: readonly ['참조', '미확정 사항', '변경 이력'];
14
+ export declare const TAIL: {
15
+ readonly REFS: '참조';
16
+ readonly PENDING: '미확정 사항';
17
+ readonly CHANGELOG: '변경 이력';
18
+ };
19
+ export declare const TAIL_NAMES: readonly ["참조", "미확정 사항", "변경 이력"];
@@ -1,10 +1,9 @@
1
1
  /**
2
2
  * 문서 체계 값 - 여러 곳이 같은 값을 봐야 하는 것들.
3
3
  *
4
- * 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다. `TAIL_NAMES` 가
5
- * `utils/parse.ts` 와 `checks/headings.ts` 에 각각 있어 실제로 그 상태였다.
4
+ * 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다.
6
5
  *
7
- * 규칙 본문은 `docs/system/rules.md` 가 갖는다. 여기는 그 규칙이 쓰는 값만 담는다.
6
+ * 규칙 본문은 `specthread/rules.md` 가 갖는다. 여기는 그 규칙이 쓰는 값만 담는다.
8
7
  */
9
8
  /**
10
9
  * 꼬리 절 예약어 (`rules.md` §2-5).
@@ -12,5 +11,9 @@
12
11
  * 파서가 꼬리 절 경계를 잡는 데 쓰고, 검사기가 본문 절이 이 이름을 쓰는지 본다.
13
12
  * 순서가 곧 문서 안 등장 순서다.
14
13
  */
15
- // locale: ko
16
- export const TAIL_NAMES = ['참조', '미확정 사항', '변경 이력'];
14
+ export const TAIL = {
15
+ REFS: '참조',
16
+ PENDING: '미확정 사항',
17
+ CHANGELOG: '변경 이력',
18
+ };
19
+ export const TAIL_NAMES = [TAIL.REFS, TAIL.PENDING, TAIL.CHANGELOG];
@@ -0,0 +1,12 @@
1
+ /**
2
+ * 종료 코드. 지적이 있는 것과 실행 자체가 실패한 것을 나눠, CI 가 설정 오류를
3
+ * 문서 문제로 오인하지 않게 한다.
4
+ */
5
+ export declare const EXIT: {
6
+ /** 지적 없음 */
7
+ readonly OK: 0;
8
+ /** 지적이 있다 */
9
+ readonly FINDINGS: 1;
10
+ /** 실행 실패. 설정 파일이 없거나 읽지 못했거나, 명령을 모른다 */
11
+ readonly FAILURE: 2;
12
+ };
@@ -0,0 +1,12 @@
1
+ /**
2
+ * 종료 코드. 지적이 있는 것과 실행 자체가 실패한 것을 나눠, CI 가 설정 오류를
3
+ * 문서 문제로 오인하지 않게 한다.
4
+ */
5
+ export const EXIT = {
6
+ /** 지적 없음 */
7
+ OK: 0,
8
+ /** 지적이 있다 */
9
+ FINDINGS: 1,
10
+ /** 실행 실패. 설정 파일이 없거나 읽지 못했거나, 명령을 모른다 */
11
+ FAILURE: 2,
12
+ };
@@ -0,0 +1,25 @@
1
+ /**
2
+ * 규약 경로 - 도구가 직접 읽고 쓰는 파일의 위치.
3
+ *
4
+ * 설정으로 열어 두지 않는다. init·스킬·AGENTS.md 가 모두 이 위치를 전제한다.
5
+ */
6
+ export declare const SPECTHREAD_DIR = "specthread";
7
+ export declare const CONFIG_PATH = "specthread/config.jsonc";
8
+ export declare const LOCAL_CONFIG_PATH = "specthread/config.local.jsonc";
9
+ /** 규칙 문서 */
10
+ export declare const RULES_PATH = "specthread/rules.md";
11
+ /** 미확정 사항 정본 */
12
+ export declare const PENDING_PATH = "specthread/pending.md";
13
+ /** 프로젝트 맥락 문서 */
14
+ export declare const PROJECT_PATH = "specthread/project.md";
15
+ /** 문서 템플릿 폴더 */
16
+ export declare const TEMPLATES_DIR = "specthread/templates";
17
+ /** `path` 와 관계없이 항상 색인한다. 이 파일들을 읽는 검사가 스캔 범위에 좌우되지 않게 한다 */
18
+ export declare const CONVENTION_FILES: readonly ["specthread/rules.md", "specthread/pending.md", "specthread/project.md"];
19
+ /**
20
+ * 항상 검사·생성에서 뺀다. 색인에는 남는다.
21
+ *
22
+ * 템플릿과 설정 파일은 예시를 담는다. `skipCheck` 배열은 덮어쓰기라 사용자가 하나만 적어도
23
+ * 기본값이 사라지므로, 그 배열에 넣지 않고 코드가 항상 더한다.
24
+ */
25
+ export declare const DEFAULT_EXCLUDES: readonly ["specthread/templates", "specthread/config.jsonc", "specthread/config.local.jsonc"];
@@ -0,0 +1,25 @@
1
+ /**
2
+ * 규약 경로 - 도구가 직접 읽고 쓰는 파일의 위치.
3
+ *
4
+ * 설정으로 열어 두지 않는다. init·스킬·AGENTS.md 가 모두 이 위치를 전제한다.
5
+ */
6
+ export const SPECTHREAD_DIR = "specthread";
7
+ export const CONFIG_PATH = `${SPECTHREAD_DIR}/config.jsonc`;
8
+ export const LOCAL_CONFIG_PATH = `${SPECTHREAD_DIR}/config.local.jsonc`;
9
+ /** 규칙 문서 */
10
+ export const RULES_PATH = `${SPECTHREAD_DIR}/rules.md`;
11
+ /** 미확정 사항 정본 */
12
+ export const PENDING_PATH = `${SPECTHREAD_DIR}/pending.md`;
13
+ /** 프로젝트 맥락 문서 */
14
+ export const PROJECT_PATH = `${SPECTHREAD_DIR}/project.md`;
15
+ /** 문서 템플릿 폴더 */
16
+ export const TEMPLATES_DIR = `${SPECTHREAD_DIR}/templates`;
17
+ /** `path` 와 관계없이 항상 색인한다. 이 파일들을 읽는 검사가 스캔 범위에 좌우되지 않게 한다 */
18
+ export const CONVENTION_FILES = [RULES_PATH, PENDING_PATH, PROJECT_PATH];
19
+ /**
20
+ * 항상 검사·생성에서 뺀다. 색인에는 남는다.
21
+ *
22
+ * 템플릿과 설정 파일은 예시를 담는다. `skipCheck` 배열은 덮어쓰기라 사용자가 하나만 적어도
23
+ * 기본값이 사라지므로, 그 배열에 넣지 않고 코드가 항상 더한다.
24
+ */
25
+ export const DEFAULT_EXCLUDES = [TEMPLATES_DIR, CONFIG_PATH, LOCAL_CONFIG_PATH];
@@ -1,18 +1,25 @@
1
1
  /**
2
2
  * 여러 검사가 같은 형식을 봐야 할 때 쓰는 정규식과 문자.
3
3
  *
4
- * 한 형식을 두 검사가 각자 표현하면 하나를 고칠 때 다른 하나가 남는다. 시점 표기가
5
- * 실제로 그 상태였다 - `checks/timestamps.ts` 는 날짜를 예외로 빼려고, `checks/pending.ts`
6
- * 는 형식을 검사하려고 같은 것을 따로 적고 있었다.
4
+ * 한 형식을 두 검사가 각자 표현하면 하나를 고칠 때 다른 하나가 남는다.
7
5
  *
8
6
  * 한 검사만 쓰는 정규식은 그 파일에 둔다. 여기 모으면 어디서 쓰는지 알 수 없어진다.
9
7
  */
8
+ /** 코드·문서 마커. 종류와 slug 를 캡처한다 */
9
+ export declare const MARKER: RegExp;
10
+ /** JSON 안 마커. 데이터에는 주석을 못 달아서 필드로 표기한다 */
11
+ export declare const PENDING_JSON: RegExp;
12
+ /** 관리 문서 항목 헤딩. id (`종류::slug`) 와 제목을 캡처한다 */
13
+ export declare const ITEM_HEADING: RegExp;
14
+ /** `li` 로 적힌 항목. 정본에서는 헤딩이어야 한다 */
15
+ export declare const ITEM_AS_LI: RegExp;
10
16
  /**
11
- * em dash. 리터럴로 적으면 치환 훅이 그 파일을 고쳐 검사를 무력화한다.
17
+ * 미확정 항목 세 모양. 종류와 slug 를 캡처한다.
12
18
  *
13
- * 훅 설정에 기대지 않고 손상을 막으려고 이스케이프로 둔다.
19
+ * 관리 문서 항목은 `###` 헤딩 (`` `[slug]` ``), 문서 미확정 사항 절은 생성된 백링크
20
+ * (`` [`slug`](...) ``), 둘 다 아닌 `li` (`` - `[slug]` ``) 는 낡은 형식이다.
14
21
  */
15
- export declare const EM_DASH = "\u2014";
22
+ export declare const PENDING_ITEM: RegExp;
16
23
  /**
17
24
  * 관리 문서 항목의 시점 표기 (`rules.md` §4-2).
18
25
  *
@@ -1,18 +1,28 @@
1
1
  /**
2
2
  * 여러 검사가 같은 형식을 봐야 할 때 쓰는 정규식과 문자.
3
3
  *
4
- * 한 형식을 두 검사가 각자 표현하면 하나를 고칠 때 다른 하나가 남는다. 시점 표기가
5
- * 실제로 그 상태였다 - `checks/timestamps.ts` 는 날짜를 예외로 빼려고, `checks/pending.ts`
6
- * 는 형식을 검사하려고 같은 것을 따로 적고 있었다.
4
+ * 한 형식을 두 검사가 각자 표현하면 하나를 고칠 때 다른 하나가 남는다.
7
5
  *
8
6
  * 한 검사만 쓰는 정규식은 그 파일에 둔다. 여기 모으면 어디서 쓰는지 알 수 없어진다.
9
7
  */
8
+ /** 마커·항목 id 의 두 부분. 종류는 영소문자, slug 는 영소문자·숫자·하이픈 */
9
+ const KIND = '[a-z]+';
10
+ const SLUG = '[a-z0-9][a-z0-9-]*';
11
+ /** 코드·문서 마커. 종류와 slug 를 캡처한다 */
12
+ export const MARKER = new RegExp(`PENDING::(${KIND})::(${SLUG})`, 'g');
13
+ /** JSON 안 마커. 데이터에는 주석을 못 달아서 필드로 표기한다 */
14
+ export const PENDING_JSON = new RegExp(`"_pending"\\s*:\\s*"(${KIND})::(${SLUG})"`, 'g');
15
+ /** 관리 문서 항목 헤딩. id (`종류::slug`) 와 제목을 캡처한다 */
16
+ export const ITEM_HEADING = new RegExp(`^###\\s+\`\\[(${KIND}::${SLUG})\\]\`\\s*(.*)$`);
17
+ /** `li` 로 적힌 항목. 정본에서는 헤딩이어야 한다 */
18
+ export const ITEM_AS_LI = new RegExp(`^\\s*-\\s+\`\\[${KIND}::${SLUG}\\]\``);
10
19
  /**
11
- * em dash. 리터럴로 적으면 치환 훅이 그 파일을 고쳐 검사를 무력화한다.
20
+ * 미확정 항목 세 모양. 종류와 slug 를 캡처한다.
12
21
  *
13
- * 훅 설정에 기대지 않고 손상을 막으려고 이스케이프로 둔다.
22
+ * 관리 문서 항목은 `###` 헤딩 (`` `[slug]` ``), 문서 미확정 사항 절은 생성된 백링크
23
+ * (`` [`slug`](...) ``), 둘 다 아닌 `li` (`` - `[slug]` ``) 는 낡은 형식이다.
14
24
  */
15
- export const EM_DASH = '\u2014';
25
+ export const PENDING_ITEM = new RegExp(`^(?:\\s*-|###)\\s+[\`\\[]+(${KIND})::(${SLUG})[\`\\]]+`);
16
26
  /**
17
27
  * 관리 문서 항목의 시점 표기 (`rules.md` §4-2).
18
28
  *