specthread 0.2.0 → 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.
@@ -0,0 +1,147 @@
1
+ /**
2
+ * `init --force` 가 마지막에 출력하는 업데이트 프롬프트.
3
+ *
4
+ * 사용자가 AI 에 그대로 붙여 넣는 글이다. init 이 감지한 상태에 해당하는 단계만 넣고,
5
+ * 검사와 생성 단계는 항상 넣는다. 버전을 올리며 정리할 것이 생기면 감지 항목을 더한다.
6
+ */
7
+ import { existsSync, readFileSync } from "node:fs";
8
+ import { join } from "node:path";
9
+ import { readConfig, REMOVED_KEYS } from "../config-loader.js";
10
+ import { DEFAULT_CONFIG } from "../config.schema.js";
11
+ import { CONFIG_PATH, LOCAL_CONFIG_PATH, PENDING_PATH, PROJECT_PATH, SPECTHREAD_DIR, } from "../constants/paths.js";
12
+ import { normalizeConfigPath, underPath } from "../utils/path-match.js";
13
+ /**
14
+ * 사용자 파일은 `--force` 로도 덮어쓰지 않는다. scaffold 의 사용자 파일 문구를 바꾸면
15
+ * 옛 문구를 여기에 더해 업데이트 프롬프트가 고치게 한다.
16
+ */
17
+ const STALE_TEXT = [
18
+ {
19
+ file: PROJECT_PATH,
20
+ before: "`config.jsonc` 에서 경로를 override 할 수 있다.",
21
+ after: "경로는 `specthread/pending.md` 고정이다.",
22
+ },
23
+ {
24
+ file: PENDING_PATH,
25
+ before: "**종류마다 `##` 섹션이 하나씩 생긴다.** 종류 값은 `config.markers.types` 가 정의하며,",
26
+ after: "**종류마다 `##` 섹션을 하나씩 둔다.** 섹션은 사람이 만들고, 종류 값은 `config.markers.types` 에 있어야 한다.",
27
+ },
28
+ ];
29
+ /** 규약 파일 경로를 정하던 키. 값을 적어 썼다면 파일을 `specthread/` 아래로 옮겨야 한다 */
30
+ const PATH_KEYS = new Set(["rules", "pending", "project"]);
31
+ /** 주석 줄에 남은 제거된 키. 기본값을 주석으로 적어 둔 설정 파일에서 나온다 */
32
+ const commentedKeys = (text) => Object.keys(REMOVED_KEYS).filter((key) => {
33
+ const name = key.slice(key.lastIndexOf(".") + 1);
34
+ return new RegExp(`^\\s*//.*"${name}"\\s*:`, "m").test(text);
35
+ });
36
+ const removedKeys = (root, live) => {
37
+ const out = live.map((r) => ({ ...r, commented: false }));
38
+ for (const file of [CONFIG_PATH, LOCAL_CONFIG_PATH]) {
39
+ const abs = join(root, file);
40
+ if (!existsSync(abs))
41
+ continue;
42
+ for (const key of commentedKeys(readFileSync(abs, "utf8"))) {
43
+ if (!out.some((r) => r.file === file && r.key === key))
44
+ out.push({ file, key, commented: true });
45
+ }
46
+ }
47
+ return out;
48
+ };
49
+ const staleText = (root) => STALE_TEXT.filter(({ file, before }) => {
50
+ const abs = join(root, file);
51
+ return existsSync(abs) && readFileSync(abs, "utf8").includes(before);
52
+ });
53
+ /**
54
+ * 기본 스캔 경로 중 설정에서 빠진 것. 그 디렉터리가 있을 때만 본다.
55
+ *
56
+ * `path` 는 기본값과 합치지 않고 통째로 교체하므로 일부 키만 적으면 기본 경로가 빠진다.
57
+ * `specthread/` 의 규약 파일은 `path` 와 관계없이 읽으므로 대상에서 뺀다.
58
+ */
59
+ const uncoveredDefaults = (root, path) => {
60
+ const bases = Object.values(path).flat().map(normalizeConfigPath);
61
+ return Object.values(DEFAULT_CONFIG.path)
62
+ .flat()
63
+ .map(normalizeConfigPath)
64
+ .filter((d) => d !== SPECTHREAD_DIR && existsSync(join(root, d)))
65
+ .filter((d) => !bases.some((b) => underPath(b, d) || underPath(d, b)));
66
+ };
67
+ const bullets = (items) => items.map((item) => `- ${item}`);
68
+ const HEADER = [
69
+ "specthread 패키지 파일을 새 버전으로 갱신했다. 아래를 순서대로 처리해줘.",
70
+ "내가 직접 쓴 내용은 지우지 말고, 판단이 필요하면 멈추고 물어봐.",
71
+ ];
72
+ export const renderUpgradePrompt = (input) => {
73
+ const { config, removed: live } = readConfig(input.root);
74
+ const steps = [];
75
+ if (input.agents === "broken") {
76
+ steps.push([
77
+ "`AGENTS.md` 에 `<!-- specthread:start -->` 는 있고 `<!-- specthread:end -->` 가 없다. " +
78
+ "specthread 섹션이 끝나는 줄 다음에 끝 표식을 넣고 `npx specthread init` 을 다시 실행한다.",
79
+ ]);
80
+ }
81
+ if (input.agents === "legacy") {
82
+ steps.push([
83
+ "`AGENTS.md` 의 specthread 섹션을 `<!-- specthread:start -->` 와 `<!-- specthread:end -->` 로 감싼다. " +
84
+ "섹션은 `# specthread` 제목부터 그 섹션 끝까지이고, 그 밖의 내용은 그대로 둔다.",
85
+ ...bullets([
86
+ "specthread 섹션이 두 번 들어 있으면 뒤의 것을 지운다.",
87
+ "감싼 뒤 `npx specthread init` 을 다시 실행해 섹션을 새 버전으로 바꾼다.",
88
+ ]),
89
+ ]);
90
+ }
91
+ if (input.overwritten.length > 0) {
92
+ steps.push([
93
+ "아래 파일을 새 버전으로 덮어썼다. git diff 로 확인하고, 내가 고쳐 둔 내용이 사라졌으면 알려줘.",
94
+ ...bullets(input.overwritten),
95
+ ]);
96
+ }
97
+ if (input.oldSkills.length > 0) {
98
+ steps.push([
99
+ "아래 옛 스킬 파일을 같은 이름의 `<이름>/SKILL.md` 와 비교한다. 내가 고친 부분이 없으면 지우고, 있으면 알려줘.",
100
+ ...bullets(input.oldSkills),
101
+ ]);
102
+ }
103
+ const removed = removedKeys(input.root, live);
104
+ if (removed.length > 0) {
105
+ const pathKeyInUse = removed.some((r) => !r.commented && PATH_KEYS.has(r.key));
106
+ steps.push([
107
+ "설정 파일에서 제거된 키를 지운다. 주석으로만 남은 것은 그 설명 주석까지 지운다.",
108
+ ...bullets(removed.map((r) => `${r.file}: ${r.key}${r.commented ? " (주석)" : ""}`)),
109
+ ...(pathKeyInUse
110
+ ? [
111
+ "`rules`·`pending`·`project` 에 경로를 적어 쓰고 있었다면 지우지 말고 알려줘. " +
112
+ "경로가 `specthread/` 아래로 고정이라 파일을 옮겨야 한다.",
113
+ ]
114
+ : []),
115
+ ]);
116
+ }
117
+ const stale = staleText(input.root);
118
+ if (stale.length > 0) {
119
+ steps.push([
120
+ "사용자 파일의 옛 문구를 지금 문구로 바꾼다.",
121
+ ...bullets(stale.map((s) => `${s.file}: "${s.before}" → "${s.after}"`)),
122
+ ]);
123
+ }
124
+ const uncovered = uncoveredDefaults(input.root, config.path);
125
+ if (uncovered.length > 0) {
126
+ steps.push([
127
+ "`config.path` 가 아래 경로를 스캔하지 않는다. `path` 는 기본값과 합치지 않고 통째로 교체되므로, " +
128
+ "일부 키만 적으면 기본 경로가 빠진다. 의도한 것인지 물어봐.",
129
+ ...bullets(uncovered.map((d) => `${d}/`)),
130
+ ]);
131
+ }
132
+ steps.push([
133
+ "`npx specthread check` 를 실행하고 지적을 고친다.",
134
+ ...bullets([
135
+ "종료 코드 2 로 끝나면 출력된 설정 파일과 키부터 고친다.",
136
+ "`marker/unknown-type` 이 나오면 쓰고 있는 종류를 `config.markers.types` 에 추가할지 물어봐.",
137
+ "`heading/tail-order` 가 나오면 꼬리 절을 참조 → 미확정 사항 → 변경 이력 순서로 옮긴다.",
138
+ ]),
139
+ ]);
140
+ steps.push(["`npx specthread gen --write` 를 실행한 뒤 `npx specthread check` 가 0 건인지 확인한다."]);
141
+ const body = steps.flatMap(([first, ...rest], i) => [
142
+ `${i + 1}. ${first}`,
143
+ ...rest.map((line) => ` ${line}`),
144
+ "",
145
+ ]);
146
+ return [...HEADER, "", ...body].join("\n").trimEnd();
147
+ };
@@ -15,6 +15,28 @@ export declare class ConfigError extends Error {
15
15
  readonly problems: ConfigProblem[];
16
16
  constructor(problems: ConfigProblem[]);
17
17
  }
18
+ /** 제거한 키와 그 이유. 기존 config 가 깨지지 않게 오류 대신 경고로 알린다 */
19
+ export declare const REMOVED_KEYS: Record<string, string>;
20
+ /** 설정 파일에 남아 있는 제거된 키 하나 */
21
+ export interface RemovedKey {
22
+ file: string;
23
+ /** 점으로 이은 키 경로 */
24
+ key: string;
25
+ }
26
+ /** 설정을 읽은 결과. 문제가 있어도 쓸 수 있는 값만 병합해 함께 돌려준다 */
27
+ export interface ConfigReport {
28
+ config: SpecthreadConfig;
29
+ problems: ConfigProblem[];
30
+ warnings: string[];
31
+ removed: RemovedKey[];
32
+ }
33
+ /**
34
+ * 기본값 → config.jsonc → config.local.jsonc 순으로 병합한다. 출력도 예외도 없다.
35
+ *
36
+ * 쓸 수 없는 값은 병합에서 빼고 `problems` 에 담는다. 업데이트 프롬프트처럼 설정이 틀려도
37
+ * 중단하지 않아야 하는 기능이 이 결과를 사용한다.
38
+ */
39
+ export declare const readConfig: (root?: string) => ConfigReport;
18
40
  /**
19
41
  * 기본값 → config.jsonc → config.local.jsonc 순으로 병합한 설정.
20
42
  *
@@ -132,9 +132,10 @@ const SCHEMA = {
132
132
  skipRefs: { check: stringArray },
133
133
  work: { check: string },
134
134
  };
135
- /** 제거한 키. 기존 config 가 깨지지 않게 오류 대신 경고로 알린다 */
136
- const REMOVED_KEYS = {
135
+ /** 제거한 키와 그 이유. 기존 config 가 깨지지 않게 오류 대신 경고로 알린다 */
136
+ export const REMOVED_KEYS = {
137
137
  locale: "읽는 곳이 없었다",
138
+ docTypes: "읽는 곳이 없었다",
138
139
  rules: `규칙 문서는 specthread/rules.md 고정이다`,
139
140
  pending: `관리 문서는 specthread/pending.md 고정이다`,
140
141
  project: `프로젝트 문서는 specthread/project.md 고정이다`,
@@ -148,14 +149,16 @@ const REMOVED_KEYS = {
148
149
  const validateLayer = (raw, file) => {
149
150
  const problems = [];
150
151
  const warnings = [];
152
+ const removed = [];
151
153
  if (!isPlainObject(raw)) {
152
- return { value: {}, problems: [{ file, key: "", message: "최상위가 객체여야 한다" }], warnings };
154
+ return { value: {}, problems: [{ file, key: "", message: "최상위가 객체여야 한다" }], warnings, removed };
153
155
  }
154
156
  const walk = (obj, schema, prefix) => {
155
157
  const out = {};
156
158
  for (const [key, v] of Object.entries(obj)) {
157
159
  const full = prefix === "" ? key : `${prefix}.${key}`;
158
160
  if (full in REMOVED_KEYS) {
161
+ removed.push({ file, key: full });
159
162
  warnings.push(`${file}: ${full} 는 제거된 키다. 지워도 된다 - ${REMOVED_KEYS[full]}`);
160
163
  continue;
161
164
  }
@@ -189,7 +192,7 @@ const validateLayer = (raw, file) => {
189
192
  }
190
193
  return out;
191
194
  };
192
- return { value: walk(raw, SCHEMA, ""), problems, warnings };
195
+ return { value: walk(raw, SCHEMA, ""), problems, warnings, removed };
193
196
  };
194
197
  // ---------------------------------------------------------------------------
195
198
  // Deep merge - 중첩 객체만 재귀, 배열은 덮어쓰기
@@ -223,18 +226,12 @@ const deepMerge = (base, override, depth = 0) => {
223
226
  // ---------------------------------------------------------------------------
224
227
  const ruleGroupSet = new Set(ALL_RULE_GROUPS);
225
228
  /** 모르는 군은 경고만 한다. 그 군의 지적은 어차피 없으므로 걸러도 결과가 같다 */
226
- const warnSkipCheckGroups = (items) => {
227
- for (const item of items) {
228
- if (typeof item === "string")
229
- continue;
230
- for (const group of item.only) {
231
- if (!ruleGroupSet.has(group)) {
232
- console.warn(`[specthread] skipCheck: unknown rule group "${group}" in path "${item.path}". ` +
233
- `Valid groups: ${ALL_RULE_GROUPS.join(", ")}`);
234
- }
235
- }
236
- }
237
- };
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(", ")}`));
238
235
  /** 경로 값을 색인 경로와 같은 형태로 맞춘다. 소비처는 정규화된 값만 본다 */
239
236
  const normalizePaths = (config) => ({
240
237
  ...config,
@@ -242,32 +239,51 @@ const normalizePaths = (config) => ({
242
239
  skipRefs: config.skipRefs.map(normalizeConfigPath),
243
240
  work: normalizeConfigPath(config.work),
244
241
  });
245
- // ---------------------------------------------------------------------------
246
- // Public API
247
- // ---------------------------------------------------------------------------
248
242
  /**
249
- * 기본값 → config.jsonc → config.local.jsonc 순으로 병합한 설정.
243
+ * 기본값 → config.jsonc → config.local.jsonc 순으로 병합한다. 출력도 예외도 없다.
250
244
  *
251
- * 쓸 수 없는 값이 하나라도 있으면 `ConfigError` 를 던진다. 경고는 출력만 하고 진행한다.
245
+ * 쓸 수 없는 값은 병합에서 빼고 `problems` 에 담는다. 업데이트 프롬프트처럼 설정이 틀려도
246
+ * 중단하지 않아야 하는 기능이 이 결과를 사용한다.
252
247
  */
253
- export const loadConfig = (root = process.cwd()) => {
248
+ export const readConfig = (root = process.cwd()) => {
254
249
  let merged = { ...DEFAULT_CONFIG };
255
250
  const problems = [];
256
251
  const warnings = [];
252
+ const removed = [];
257
253
  for (const file of [CONFIG_PATH, LOCAL_CONFIG_PATH]) {
258
254
  const abs = join(root, file);
259
255
  if (!existsSync(abs))
260
256
  continue;
261
- const layer = validateLayer(parseJsonc(readFileSync(abs, "utf-8"), file), file);
257
+ let raw;
258
+ try {
259
+ raw = parseJsonc(readFileSync(abs, "utf-8"), file);
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);
262
268
  problems.push(...layer.problems);
263
269
  warnings.push(...layer.warnings);
270
+ removed.push(...layer.removed);
264
271
  merged = deepMerge(merged, layer.value);
265
272
  }
273
+ const config = normalizePaths(merged);
274
+ warnings.push(...skipCheckWarnings(config.skipCheck));
275
+ return { config, problems, warnings, removed };
276
+ };
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);
266
284
  for (const w of warnings)
267
285
  console.warn(`[specthread] ${w}`);
268
286
  if (problems.length > 0)
269
287
  throw new ConfigError(problems);
270
- const config = normalizePaths(merged);
271
- warnSkipCheckGroups(config.skipCheck);
272
288
  return config;
273
289
  };
@@ -1,8 +1,7 @@
1
1
  /**
2
2
  * 문서 체계 값 - 여러 곳이 같은 값을 봐야 하는 것들.
3
3
  *
4
- * 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다. `TAIL_NAMES` 가
5
- * `utils/parse.ts` 와 `checks/headings.ts` 에 각각 있어 실제로 그 상태였다.
4
+ * 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다.
6
5
  *
7
6
  * 규칙 본문은 `specthread/rules.md` 가 갖는다. 여기는 그 규칙이 쓰는 값만 담는다.
8
7
  */
@@ -1,8 +1,7 @@
1
1
  /**
2
2
  * 문서 체계 값 - 여러 곳이 같은 값을 봐야 하는 것들.
3
3
  *
4
- * 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다. `TAIL_NAMES` 가
5
- * `utils/parse.ts` 와 `checks/headings.ts` 에 각각 있어 실제로 그 상태였다.
4
+ * 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다.
6
5
  *
7
6
  * 규칙 본문은 `specthread/rules.md` 가 갖는다. 여기는 그 규칙이 쓰는 값만 담는다.
8
7
  */
@@ -1,9 +1,7 @@
1
1
  /**
2
2
  * 여러 검사가 같은 형식을 봐야 할 때 쓰는 정규식과 문자.
3
3
  *
4
- * 한 형식을 두 검사가 각자 표현하면 하나를 고칠 때 다른 하나가 남는다. 시점 표기가
5
- * 실제로 그 상태였다 - `checks/timestamps.ts` 는 날짜를 예외로 빼려고, `checks/pending.ts`
6
- * 는 형식을 검사하려고 같은 것을 따로 적고 있었다.
4
+ * 한 형식을 두 검사가 각자 표현하면 하나를 고칠 때 다른 하나가 남는다.
7
5
  *
8
6
  * 한 검사만 쓰는 정규식은 그 파일에 둔다. 여기 모으면 어디서 쓰는지 알 수 없어진다.
9
7
  */
@@ -1,9 +1,7 @@
1
1
  /**
2
2
  * 여러 검사가 같은 형식을 봐야 할 때 쓰는 정규식과 문자.
3
3
  *
4
- * 한 형식을 두 검사가 각자 표현하면 하나를 고칠 때 다른 하나가 남는다. 시점 표기가
5
- * 실제로 그 상태였다 - `checks/timestamps.ts` 는 날짜를 예외로 빼려고, `checks/pending.ts`
6
- * 는 형식을 검사하려고 같은 것을 따로 적고 있었다.
4
+ * 한 형식을 두 검사가 각자 표현하면 하나를 고칠 때 다른 하나가 남는다.
7
5
  *
8
6
  * 한 검사만 쓰는 정규식은 그 파일에 둔다. 여기 모으면 어디서 쓰는지 알 수 없어진다.
9
7
  */
@@ -6,8 +6,8 @@
6
6
  * 목차·참조 절과 같은 방식이다 - 정본은 관리 문서이고 여기는 생성 뷰다.
7
7
  *
8
8
  * **이미 절을 가진 문서만 채운다.** 참조는 _이 항목이 이 문서와 관련 있다_ 는
9
- * 인용이지 _이 문서가 이 미확정을 소유한다_ 는 선언이 아니다. `STATUS.md` 처럼
10
- * 배경으로 인용될 뿐인 문서에 절을 새로 만들면 소유하지 않는 것을 소유한 듯 보인다.
9
+ * 인용이지 _이 문서가 이 미확정을 소유한다_ 는 선언이 아니다. 배경으로 인용될 뿐인
10
+ * 문서에 절을 새로 만들면 소유하지 않는 것을 소유한 것으로 보인다.
11
11
  *
12
12
  * **소비자가 둘이다.** `bin/generate.ts` 가 파일에 쓰고, `checks/pending.ts` 가 같은
13
13
  * 함수를 불러 지금 내용과 비교한다.
@@ -25,8 +25,8 @@ const isCode = (path, docExts) => {
25
25
  /**
26
26
  * 링크 대상의 리포 루트 기준 위치. 같은 파일 이름이 겹칠 때 라벨로 쓴다.
27
27
  *
28
- * 앞머리만 떼면 구분이 사라진다 - `client/README.md` 안에서 `../CLAUDE.md` 와
29
- * `./CLAUDE.md` 는 서로 다른 파일인데 둘 다 `CLAUDE.md` 가 된다.
28
+ * 앞머리만 떼면 구분이 사라진다 - `docs/guide.md` 안에서 `../README.md` 와
29
+ * `./README.md` 는 서로 다른 파일인데 둘 다 `README.md` 가 된다.
30
30
  */
31
31
  const repoPath = (from, target) => normalize(join(dirname(from), target));
32
32
  /**
@@ -66,8 +66,8 @@ const collect = (file) => {
66
66
  /**
67
67
  * 대상별 표시 이름.
68
68
  *
69
- * 기본은 파일 이름이고, 한 문서 안에서 같은 이름이 둘 이상 나오면 리포 안 위치를
70
- * 알 만큼 앞을 붙인다 - `CLAUDE.md` 는 루트와 client 두 곳에 있다.
69
+ * 기본은 파일 이름이고, 한 문서 안에서 같은 이름이 둘 이상 나오면 리포 루트 기준
70
+ * 경로로 표시한다. 루트와 `docs/` 의 `README.md` 처럼 이름이 같은 파일을 구분하기 위해서다.
71
71
  */
72
72
  const labels = (from, targets) => {
73
73
  const seen = new Map();
@@ -15,6 +15,7 @@
15
15
  import { PENDING_PATH } from '../constants/paths.js';
16
16
  import { ITEM_HEADING, TIMEPOINT } from '../constants/patterns.js';
17
17
  import { slugify } from '../utils/anchor.js';
18
+ import { eachContentLine } from '../utils/parse.js';
18
19
  import { isWorkDoc } from '../utils/scope.js';
19
20
  /** 관리 문서인지. 표는 그 한 파일에만 붙는다 */
20
21
  export const isPendingDoc = (file) => file.path === PENDING_PATH;
@@ -23,7 +24,7 @@ const TIMEPOINT_LINE = new RegExp(`^${TIMEPOINT.source}$`);
23
24
  const sections = (lines) => {
24
25
  const out = [];
25
26
  let cur = null;
26
- lines.forEach((line, i) => {
27
+ eachContentLine(lines, (line, i) => {
27
28
  if (/^##\s+\d/.test(line)) {
28
29
  cur = { heading: i + 1, blockStart: i + 2, blockEnd: i + 1, items: [] };
29
30
  out.push(cur);
package/dist/gen/toc.js CHANGED
@@ -59,7 +59,7 @@ export const applyToc = (file, lines) => {
59
59
  }
60
60
  return [...lines.slice(0, start - 1), ...block, ...lines.slice(end)];
61
61
  }
62
- // 제목 줄은 색인에서 꺼낸다. 본문을 다시 훑으면 펜스 안 `# ` 를 제목으로 볼 수 있다
62
+ // 제목 줄은 색인에서 꺼낸다. 본문을 다시 훑으면 코드블록 안 `# ` 를 제목으로 볼 수 있다
63
63
  return [
64
64
  ...lines.slice(0, title.line),
65
65
  "",
package/dist/types.d.ts CHANGED
@@ -5,8 +5,8 @@ import type { SpecthreadConfig } from './config.schema.ts';
5
5
  * 앵커가 붙은 링크의 라벨 구간과 그 링크 대상.
6
6
  *
7
7
  * 라벨 안에 놓인 `§N` 은 라벨 글자가 아니라 **링크 대상 경로** 로 풀어야 한다.
8
- * `` [`CLAUDE.md` §1](../../CLAUDE.md#1-절대-원칙) `` 에서 라벨만 보면 루트와 client
9
- * 중 어느 `CLAUDE.md` 인지 알 수 없지만 대상 경로는 알려준다.
8
+ * `` [`README.md` §1](../README.md#1-개요) `` 에서 라벨만 보면 어느 디렉터리의
9
+ * `README.md` 인지 알 수 없지만 대상 경로는 알려준다.
10
10
  */
11
11
  export interface AnchorLabelSpan {
12
12
  start: number;
@@ -12,7 +12,7 @@ export declare const slugify: (text: string) => string;
12
12
  /**
13
13
  * 헤딩 원문에서 앞머리 번호를 떼어낸다. `6-1. 기본 데미지` → `6-1` + `기본 데미지`
14
14
  *
15
- * 중간 자리에 문자가 오는 `1-B-1` 도 받는다 - `CLAUDE.md` §7 이 정한 형태다.
15
+ * 중간 자리에 문자가 오는 `1-B-1` 도 받는다.
16
16
  */
17
17
  export declare const splitHeadingNum: (raw: string) => {
18
18
  num: string | null;
@@ -16,7 +16,7 @@ export const slugify = (text) => text
16
16
  /**
17
17
  * 헤딩 원문에서 앞머리 번호를 떼어낸다. `6-1. 기본 데미지` → `6-1` + `기본 데미지`
18
18
  *
19
- * 중간 자리에 문자가 오는 `1-B-1` 도 받는다 - `CLAUDE.md` §7 이 정한 형태다.
19
+ * 중간 자리에 문자가 오는 `1-B-1` 도 받는다.
20
20
  */
21
21
  export const splitHeadingNum = (raw) => {
22
22
  const m = /^(\d+(?:-[0-9A-Za-z]+)*)\.\s+(.*)$/.exec(raw);
@@ -4,7 +4,7 @@
4
4
  * 같은 줄이나 바로 윗줄에 `@specthread-ignore` 가 있으면 그 줄의 지적을 건너뛴다.
5
5
  * eslint-disable-next-line 과 같은 모델이다.
6
6
  *
7
- * 주석 안에 적은 것만 억제로 본다. 코드 스팬·펜스 안은 표기를 설명하는 글이다.
7
+ * 주석 안에 적은 것만 억제로 본다. 코드 스팬·코드블록 안은 표기를 설명하는 글이다.
8
8
  */
9
9
  import { codeSpanMask, eachContentLine } from "./parse.js";
10
10
  /** 주석 여는 표기 뒤의 억제 토큰. `<!--`, `//`, `/*`, `#` */
@@ -1,8 +1,8 @@
1
1
  import type { AnchorLabelSpan, FileKind, Heading, IndexedFile, Marker, Range } from "../types.ts";
2
2
  /**
3
- * 펜스 코드블록 바깥의 줄만 넘겨준다.
3
+ * 코드블록 바깥의 줄만 넘겨준다.
4
4
  *
5
- * 펜스 여는 줄과 닫는 줄 자체도 넘기지 않는다. 여닫이를 구분하지 않고 토글만
5
+ * 코드블록을 여는 줄과 닫는 줄 자체도 넘기지 않는다. 여닫이를 구분하지 않고 토글만
6
6
  * 하므로 언어 표기가 붙은 ` ```markdown ` 도 그대로 잡힌다.
7
7
  */
8
8
  export declare const eachContentLine: (lines: string[], fn: (line: string, index: number) => void) => void;
@@ -10,14 +10,14 @@ export declare const eachContentLine: (lines: string[], fn: (line: string, index
10
10
  * 인라인 백틱 코드 스팬 위치. 각 문자가 코드 안인지 표시한다.
11
11
  *
12
12
  * 백틱 안 `§1-A-3` 은 표기법을 인용한 것이지 참조가 아니다. 반대로
13
- * `` `skill-tree.md §4` `` 처럼 문서명을 함께 담은 것은 실 참조라서, 스팬 안에
14
- * 문서명이 있는지로 갈라야 한다. 위치만 계산해 두고 판정은 참조 파서가 한다.
13
+ * `` `auth.md §4` `` 처럼 문서명을 함께 담은 것은 실제 참조라서, 스팬 안에
14
+ * 문서명이 있는지로 구분해야 한다. 위치만 계산해 두고 판정은 참조 파서가 한다.
15
15
  */
16
16
  export declare const codeSpanMask: (line: string) => boolean[];
17
17
  /**
18
18
  * 앵커가 붙은 마크다운 링크의 라벨 구간.
19
19
  *
20
- * `[`battle.md` §7](./battle.md#7-승리---패배-조건)` 처럼 라벨 안에 놓인 `§` 는 이미
20
+ * `[`auth.md` §3](./auth.md#3-인증-흐름)` 처럼 라벨 안에 놓인 `§` 는 이미
21
21
  * 앵커로 걸린 참조라 정상이다. 반대로 라벨 밖 `§` 는 링크 없이 적은 것이다.
22
22
  * 절 참조 파서가 이 구간으로 둘을 가른다.
23
23
  */
@@ -27,7 +27,7 @@ export declare const linkTargetSpans: (line: string) => Range[];
27
27
  /**
28
28
  * 마커를 모은다.
29
29
  *
30
- * doc 은 펜스 안을 건너뛰고 (템플릿이 마커 예시를 코드블록에 담는다),
30
+ * doc 은 코드블록 안을 건너뛰고 (템플릿이 마커 예시를 코드블록에 담는다),
31
31
  * source 는 전부 훑는다. JSON 계열 파일은 `"_pending"` 키 패턴을 추가로 잡는다.
32
32
  */
33
33
  export declare const parseMarkers: (lines: string[], kind: FileKind, path?: string) => Marker[];
@@ -2,8 +2,7 @@
2
2
  * 마크다운 한 파일에서 색인 재료를 뽑는다 - 헤딩·링크·마커·미확정 항목과
3
3
  * 생성기가 덮어쓸 블록의 위치.
4
4
  *
5
- * 펜스 코드블록 안은 전부 무시한다. 템플릿이 골격을 코드블록으로 담고 있어서
6
- * 추적하지 않으면 헤딩 88 개와 링크 90 개가 오탐으로 잡힌다.
5
+ * 코드블록 안은 전부 무시한다. 템플릿과 규칙 문서는 골격과 예시를 코드블록에 담는다.
7
6
  */
8
7
  import { TAIL, TAIL_NAMES } from "../constants/docs.js";
9
8
  import { MARKER, PENDING_ITEM, PENDING_JSON } from "../constants/patterns.js";
@@ -16,9 +15,9 @@ import { slugify, splitHeadingNum } from "./anchor.js";
16
15
  */
17
16
  const TAIL_SET = new Set(TAIL_NAMES);
18
17
  /**
19
- * 펜스 코드블록 바깥의 줄만 넘겨준다.
18
+ * 코드블록 바깥의 줄만 넘겨준다.
20
19
  *
21
- * 펜스 여는 줄과 닫는 줄 자체도 넘기지 않는다. 여닫이를 구분하지 않고 토글만
20
+ * 코드블록을 여는 줄과 닫는 줄 자체도 넘기지 않는다. 여닫이를 구분하지 않고 토글만
22
21
  * 하므로 언어 표기가 붙은 ` ```markdown ` 도 그대로 잡힌다.
23
22
  */
24
23
  export const eachContentLine = (lines, fn) => {
@@ -36,8 +35,8 @@ export const eachContentLine = (lines, fn) => {
36
35
  * 인라인 백틱 코드 스팬 위치. 각 문자가 코드 안인지 표시한다.
37
36
  *
38
37
  * 백틱 안 `§1-A-3` 은 표기법을 인용한 것이지 참조가 아니다. 반대로
39
- * `` `skill-tree.md §4` `` 처럼 문서명을 함께 담은 것은 실 참조라서, 스팬 안에
40
- * 문서명이 있는지로 갈라야 한다. 위치만 계산해 두고 판정은 참조 파서가 한다.
38
+ * `` `auth.md §4` `` 처럼 문서명을 함께 담은 것은 실제 참조라서, 스팬 안에
39
+ * 문서명이 있는지로 구분해야 한다. 위치만 계산해 두고 판정은 참조 파서가 한다.
41
40
  */
42
41
  export const codeSpanMask = (line) => {
43
42
  const mask = new Array(line.length).fill(false);
@@ -58,7 +57,7 @@ export const codeSpanMask = (line) => {
58
57
  /**
59
58
  * 앵커가 붙은 마크다운 링크의 라벨 구간.
60
59
  *
61
- * `[`battle.md` §7](./battle.md#7-승리---패배-조건)` 처럼 라벨 안에 놓인 `§` 는 이미
60
+ * `[`auth.md` §3](./auth.md#3-인증-흐름)` 처럼 라벨 안에 놓인 `§` 는 이미
62
61
  * 앵커로 걸린 참조라 정상이다. 반대로 라벨 밖 `§` 는 링크 없이 적은 것이다.
63
62
  * 절 참조 파서가 이 구간으로 둘을 가른다.
64
63
  */
@@ -94,7 +93,7 @@ const UNCOMMENTABLE_EXTS = new Set([".json"]);
94
93
  /**
95
94
  * 마커를 모은다.
96
95
  *
97
- * doc 은 펜스 안을 건너뛰고 (템플릿이 마커 예시를 코드블록에 담는다),
96
+ * doc 은 코드블록 안을 건너뛰고 (템플릿이 마커 예시를 코드블록에 담는다),
98
97
  * source 는 전부 훑는다. JSON 계열 파일은 `"_pending"` 키 패턴을 추가로 잡는다.
99
98
  */
100
99
  export const parseMarkers = (lines, kind, path) => {
@@ -1,21 +1,31 @@
1
1
  import type { FileKind, SectionRef } from "../types.ts";
2
2
  /** 참조 해소에 필요한 문맥. 색인 대상 문서 목록에서 한 번 만들어 돌려 쓴다 */
3
3
  export interface RefContext {
4
- mdPaths: string[];
4
+ docPaths: string[];
5
5
  nameMap: Map<string, string[]>;
6
6
  knownStems: Set<string>;
7
+ /** 문서 확장자로 끝나는 파일 이름 패턴. 문서 확장자가 없으면 null */
8
+ docFile: RegExp | null;
9
+ }
10
+ export interface RefContextInput {
11
+ /** 색인 대상 문서의 리포 상대 경로 */
12
+ docPaths: string[];
13
+ /** 문서명 해소에서 제외할 이름. `config.ignoreDocNames` */
14
+ ignoreDocNames?: string[];
15
+ /** 문서 확장자. `config.fileKinds.doc` */
16
+ docExts?: string[];
7
17
  }
8
18
  /**
9
19
  * 색인 대상 문서 목록만으로 참조 해소 문맥을 만든다. 테스트에서도 이걸 쓴다.
10
20
  *
11
21
  * stem 은 두 글자 이하를 뺀다 - 짧은 낱말은 산문에서 우연히 겹칠 확률이 높다.
12
22
  */
13
- export declare const makeRefContext: (mdPaths: string[], ignoreDocNames?: string[]) => RefContext;
23
+ export declare const makeRefContext: ({ docPaths, ignoreDocNames, docExts, }: RefContextInput) => RefContext;
14
24
  /**
15
25
  * 한 파일의 절 참조를 모두 뽑아 해소한다.
16
26
  *
17
- * `battle.md §1·§4·§6` 같은 복수 절도 각 `§` 가 자기 왼쪽의 가까운 문서명에 붙으므로
18
- * 따로 다룰 필요가 없다. 문서명을 못 찾으면 마크다운은 자기 문서 참조로 보고
27
+ * `auth.md §1·§4·§6` 같은 복수 절도 각 `§` 가 자기 왼쪽에서 가장 가까운 문서명을 대상으로
28
+ * 하므로 따로 다룰 필요가 없다. 문서명을 못 찾으면 마크다운은 자기 문서 참조로 보고
19
29
  * (표 안 `§4-1` 같은 것), 코드는 대상 불명으로 남긴다.
20
30
  */
21
- export declare const parseSectionRefs: (path: string, kind: FileKind, lines: string[], { mdPaths, nameMap, knownStems }: RefContext) => SectionRef[];
31
+ export declare const parseSectionRefs: (path: string, kind: FileKind, lines: string[], { docPaths, nameMap, knownStems, docFile }: RefContext) => SectionRef[];