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/dist/commands/init.js
CHANGED
|
@@ -1,13 +1,18 @@
|
|
|
1
1
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
2
|
-
import { join, dirname } from "node:path";
|
|
2
|
+
import { basename, join, dirname } from "node:path";
|
|
3
3
|
import { fileURLToPath } from "node:url";
|
|
4
|
+
import { DEFAULT_CONFIG } from "../config.schema.js";
|
|
5
|
+
import { CONFIG_PATH, LOCAL_CONFIG_PATH, PENDING_PATH, PROJECT_PATH, RULES_PATH, SPECTHREAD_DIR, TEMPLATES_DIR, } from "../constants/paths.js";
|
|
6
|
+
import { renderConfig } from "./config-template.js";
|
|
4
7
|
const SPECTHREAD_START = "<!-- specthread:start -->";
|
|
5
8
|
const SPECTHREAD_END = "<!-- specthread:end -->";
|
|
6
9
|
const scaffoldDir = () => {
|
|
7
10
|
const thisFile = dirname(fileURLToPath(import.meta.url));
|
|
11
|
+
// dist/commands, dist, tools/docs/commands (소스에서 실행) 순
|
|
8
12
|
const candidates = [
|
|
9
13
|
join(thisFile, "..", "..", "scaffold"),
|
|
10
14
|
join(thisFile, "..", "scaffold"),
|
|
15
|
+
join(thisFile, "..", "..", "..", "scaffold"),
|
|
11
16
|
];
|
|
12
17
|
for (const dir of candidates) {
|
|
13
18
|
if (existsSync(dir))
|
|
@@ -15,36 +20,52 @@ const scaffoldDir = () => {
|
|
|
15
20
|
}
|
|
16
21
|
throw new Error("scaffold 디렉터리를 찾을 수 없다");
|
|
17
22
|
};
|
|
18
|
-
const
|
|
19
|
-
if (existsSync(dest) && !force)
|
|
20
|
-
return "skipped";
|
|
23
|
+
const putFile = (dest, content, force, owner) => {
|
|
21
24
|
const existed = existsSync(dest);
|
|
25
|
+
if (existed && owner === "user")
|
|
26
|
+
return force ? "kept" : "skipped";
|
|
27
|
+
if (existed && !force)
|
|
28
|
+
return "skipped";
|
|
22
29
|
const dir = dirname(dest);
|
|
23
30
|
if (!existsSync(dir))
|
|
24
31
|
mkdirSync(dir, { recursive: true });
|
|
25
|
-
writeFileSync(dest,
|
|
32
|
+
writeFileSync(dest, content, "utf8");
|
|
26
33
|
return existed ? "overwritten" : "created";
|
|
27
34
|
};
|
|
35
|
+
const copyFile = (src, dest, force, owner) => putFile(dest, readFileSync(src, "utf8"), force, owner);
|
|
36
|
+
/** 표식으로 감싼 specthread 섹션. 표식 사이만 패키지가 갱신한다 */
|
|
37
|
+
const wrapSection = (section) => `${SPECTHREAD_START}\n${section}\n${SPECTHREAD_END}`;
|
|
38
|
+
/**
|
|
39
|
+
* 표식 없이 만들어진 이전 버전의 AGENTS.md 인지. scaffold 의 제목과 절 이름으로 본다.
|
|
40
|
+
*
|
|
41
|
+
* 섹션을 덧붙이면 같은 내용이 두 번 들어가고, 파일 전체를 바꾸면 사용자가 덧붙인 내용이
|
|
42
|
+
* 사라질 수 있다. 그래서 건드리지 않고 알린다.
|
|
43
|
+
*/
|
|
44
|
+
const isLegacyAgents = (content) => /^# specthread\s*$/m.test(content) && /^## 2\. SDD 작업 흐름\s*$/m.test(content);
|
|
45
|
+
/** AGENTS.md 의 specthread 섹션을 맞춘다. 이전 버전 파일이라 손대지 않았으면 false */
|
|
28
46
|
const ensureAgentsMd = (cwd, scaffold) => {
|
|
29
47
|
const dest = join(cwd, "AGENTS.md");
|
|
30
|
-
const
|
|
48
|
+
const section = readFileSync(join(scaffold, "AGENTS.md"), "utf8");
|
|
31
49
|
if (!existsSync(dest)) {
|
|
32
|
-
writeFileSync(dest,
|
|
50
|
+
writeFileSync(dest, `${wrapSection(section)}\n`, "utf8");
|
|
33
51
|
console.log(" AGENTS.md 생성");
|
|
34
|
-
return;
|
|
52
|
+
return true;
|
|
35
53
|
}
|
|
36
54
|
const content = readFileSync(dest, "utf8");
|
|
37
55
|
if (content.includes(SPECTHREAD_START)) {
|
|
38
56
|
const before = content.slice(0, content.indexOf(SPECTHREAD_START));
|
|
39
57
|
const after = content.slice(content.indexOf(SPECTHREAD_END) + SPECTHREAD_END.length);
|
|
40
|
-
|
|
41
|
-
writeFileSync(dest, `${before}${SPECTHREAD_START}\n${section}\n${SPECTHREAD_END}${after}`, "utf8");
|
|
58
|
+
writeFileSync(dest, `${before}${wrapSection(section)}${after}`, "utf8");
|
|
42
59
|
console.log(" AGENTS.md specthread 섹션 갱신");
|
|
43
|
-
return;
|
|
60
|
+
return true;
|
|
44
61
|
}
|
|
45
|
-
|
|
46
|
-
|
|
62
|
+
if (isLegacyAgents(content)) {
|
|
63
|
+
console.log(" AGENTS.md 이전 버전 형식 (구분 표식 없음). 건드리지 않음");
|
|
64
|
+
return false;
|
|
65
|
+
}
|
|
66
|
+
writeFileSync(dest, `${content.trimEnd()}\n\n${wrapSection(section)}\n`, "utf8");
|
|
47
67
|
console.log(" AGENTS.md specthread 섹션 삽입");
|
|
68
|
+
return true;
|
|
48
69
|
};
|
|
49
70
|
const ensureClaudeMd = (cwd) => {
|
|
50
71
|
const dest = join(cwd, "CLAUDE.md");
|
|
@@ -61,6 +82,23 @@ const ensureClaudeMd = (cwd) => {
|
|
|
61
82
|
writeFileSync(dest, `${content.trimEnd()}\n\n@AGENTS.md\n`, "utf8");
|
|
62
83
|
console.log(" CLAUDE.md @AGENTS.md 추가");
|
|
63
84
|
};
|
|
85
|
+
/** 개인 설정이 커밋되지 않게 한다. 이미 적혀 있으면 건드리지 않는다 */
|
|
86
|
+
const ensureGitignore = (cwd) => {
|
|
87
|
+
const dest = join(cwd, ".gitignore");
|
|
88
|
+
if (!existsSync(dest)) {
|
|
89
|
+
writeFileSync(dest, `${LOCAL_CONFIG_PATH}\n`, "utf8");
|
|
90
|
+
console.log(" .gitignore 생성");
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
const content = readFileSync(dest, "utf8");
|
|
94
|
+
if (content.split(/\r?\n/).some((l) => l.trim() === LOCAL_CONFIG_PATH)) {
|
|
95
|
+
console.log(` .gitignore 이미 ${LOCAL_CONFIG_PATH} 포함`);
|
|
96
|
+
return;
|
|
97
|
+
}
|
|
98
|
+
writeFileSync(dest, `${content.trimEnd()}\n\n# specthread 개인 설정\n${LOCAL_CONFIG_PATH}\n`, "utf8");
|
|
99
|
+
console.log(` .gitignore ${LOCAL_CONFIG_PATH} 추가`);
|
|
100
|
+
};
|
|
101
|
+
const SKILLS = ["check", "gen", "plan-open", "plan-run", "plan-close"];
|
|
64
102
|
const parseTools = (args) => {
|
|
65
103
|
const idx = args.indexOf("--tools");
|
|
66
104
|
if (idx === -1 || idx + 1 >= args.length)
|
|
@@ -71,7 +109,9 @@ const STATUS_LABEL = {
|
|
|
71
109
|
created: "생성",
|
|
72
110
|
overwritten: "덮어씀",
|
|
73
111
|
skipped: "이미 존재. 건너뜀",
|
|
112
|
+
kept: "사용자 파일. 건너뜀",
|
|
74
113
|
};
|
|
114
|
+
const UPGRADE_GUIDE = "README 의 '0.1.x 에서 올리기'";
|
|
75
115
|
export const init = (args) => {
|
|
76
116
|
const cwd = process.cwd();
|
|
77
117
|
const scaffold = scaffoldDir();
|
|
@@ -81,47 +121,57 @@ export const init = (args) => {
|
|
|
81
121
|
console.log("specthread init --force\n");
|
|
82
122
|
else
|
|
83
123
|
console.log("specthread init\n");
|
|
84
|
-
const stDir = join(cwd,
|
|
124
|
+
const stDir = join(cwd, SPECTHREAD_DIR);
|
|
85
125
|
if (existsSync(stDir)) {
|
|
86
|
-
console.log(
|
|
126
|
+
console.log(` ${SPECTHREAD_DIR}/ 이미 존재 - 기존 설정 유지`);
|
|
87
127
|
}
|
|
88
128
|
else {
|
|
89
129
|
mkdirSync(stDir, { recursive: true });
|
|
90
|
-
console.log(
|
|
130
|
+
console.log(` ${SPECTHREAD_DIR}/ 생성`);
|
|
91
131
|
}
|
|
92
|
-
const
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
"
|
|
132
|
+
const configStatus = putFile(join(cwd, CONFIG_PATH), renderConfig(DEFAULT_CONFIG), force, "user");
|
|
133
|
+
console.log(` ${CONFIG_PATH} ${STATUS_LABEL[configStatus]}`);
|
|
134
|
+
// scaffold 원본은 고정 경로와 같은 파일 이름을 쓴다
|
|
135
|
+
const docs = [
|
|
136
|
+
[RULES_PATH, "package"],
|
|
137
|
+
[PROJECT_PATH, "user"],
|
|
138
|
+
[PENDING_PATH, "user"],
|
|
97
139
|
];
|
|
98
|
-
for (const
|
|
99
|
-
const status = copyFile(join(scaffold,
|
|
100
|
-
console.log(`
|
|
140
|
+
for (const [dest, owner] of docs) {
|
|
141
|
+
const status = copyFile(join(scaffold, basename(dest)), join(cwd, dest), force, owner);
|
|
142
|
+
console.log(` ${dest} ${STATUS_LABEL[status]}`);
|
|
101
143
|
}
|
|
102
|
-
const
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
console.log(` specthread/templates/${file} ${STATUS_LABEL[status]}`);
|
|
144
|
+
for (const file of ["spec.md", "plan.md"]) {
|
|
145
|
+
const dest = `${TEMPLATES_DIR}/${file}`;
|
|
146
|
+
const status = copyFile(join(scaffold, "templates", file), join(cwd, dest), force, "package");
|
|
147
|
+
console.log(` ${dest} ${STATUS_LABEL[status]}`);
|
|
107
148
|
}
|
|
108
|
-
ensureAgentsMd(cwd, scaffold);
|
|
149
|
+
let legacy = !ensureAgentsMd(cwd, scaffold);
|
|
150
|
+
ensureGitignore(cwd);
|
|
109
151
|
if (tools.has("claude")) {
|
|
110
152
|
ensureClaudeMd(cwd);
|
|
153
|
+
// Claude Code 는 `<이름>/SKILL.md` 만 스킬로 읽는다. 0.1.x 는 `<이름>.md` 로 깔았다
|
|
111
154
|
const skillsDir = join(cwd, ".claude", "skills");
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
"plan-run.md",
|
|
119
|
-
"plan-close.md",
|
|
120
|
-
];
|
|
121
|
-
for (const file of skillFiles) {
|
|
122
|
-
const status = copyFile(join(scaffold, "claude", "skills", file), join(skillsDir, file), force);
|
|
123
|
-
console.log(` .claude/skills/${file} ${STATUS_LABEL[status]}`);
|
|
155
|
+
const oldSkills = [];
|
|
156
|
+
for (const name of SKILLS) {
|
|
157
|
+
const status = copyFile(join(scaffold, "claude", "skills", name, "SKILL.md"), join(skillsDir, name, "SKILL.md"), force, "package");
|
|
158
|
+
console.log(` .claude/skills/${name}/SKILL.md ${STATUS_LABEL[status]}`);
|
|
159
|
+
if (existsSync(join(skillsDir, `${name}.md`)))
|
|
160
|
+
oldSkills.push(`.claude/skills/${name}.md`);
|
|
124
161
|
}
|
|
162
|
+
// 사용자가 고쳤을 수 있으므로 지우지 않고 알리기만 한다
|
|
163
|
+
if (oldSkills.length > 0) {
|
|
164
|
+
legacy = true;
|
|
165
|
+
console.log("\n 이전 형식의 스킬 파일이 남아 있다. Claude Code 가 읽지 않으므로 지워도 된다:");
|
|
166
|
+
for (const path of oldSkills)
|
|
167
|
+
console.log(` ${path}`);
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
if (force) {
|
|
171
|
+
console.log(`\n--force 는 패키지 파일만 갱신한다. ${CONFIG_PATH}, ${PROJECT_PATH}, ${PENDING_PATH} 는 그대로 둔다.`);
|
|
172
|
+
}
|
|
173
|
+
if (legacy) {
|
|
174
|
+
console.log(`\n이전 버전에서 올린 프로젝트로 보인다. 남은 정리는 ${UPGRADE_GUIDE} 를 따른다.`);
|
|
125
175
|
}
|
|
126
176
|
console.log("\n완료. npx specthread check 로 문서 정합성을 확인할 수 있다.");
|
|
127
177
|
};
|
package/dist/config-loader.d.ts
CHANGED
|
@@ -1,2 +1,23 @@
|
|
|
1
1
|
import type { SpecthreadConfig } from "./config.schema.ts";
|
|
2
|
-
|
|
2
|
+
/** 설정을 읽지 못한 이유 하나. 어느 파일 어느 키인지 함께 낸다 */
|
|
3
|
+
export interface ConfigProblem {
|
|
4
|
+
file: string;
|
|
5
|
+
/** 점으로 이은 키 경로. 파일 전체의 문제면 빈 문자열 */
|
|
6
|
+
key: string;
|
|
7
|
+
message: string;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* 설정을 쓸 수 없을 때 던진다.
|
|
11
|
+
*
|
|
12
|
+
* 문제를 하나씩 던지면 사용자가 고치고 다시 돌리기를 반복해야 한다. 한 번에 모아 낸다.
|
|
13
|
+
*/
|
|
14
|
+
export declare class ConfigError extends Error {
|
|
15
|
+
readonly problems: ConfigProblem[];
|
|
16
|
+
constructor(problems: ConfigProblem[]);
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* 기본값 → config.jsonc → config.local.jsonc 순으로 병합한 설정.
|
|
20
|
+
*
|
|
21
|
+
* 쓸 수 없는 값이 하나라도 있으면 `ConfigError` 를 던진다. 경고는 출력만 하고 진행한다.
|
|
22
|
+
*/
|
|
23
|
+
export declare const loadConfig: (root?: string) => SpecthreadConfig;
|
package/dist/config-loader.js
CHANGED
|
@@ -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
|
-
|
|
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,165 @@ const stripJsonComments = (text) => {
|
|
|
48
52
|
}
|
|
49
53
|
return result;
|
|
50
54
|
};
|
|
51
|
-
|
|
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
|
-
//
|
|
111
|
+
// 검증
|
|
54
112
|
// ---------------------------------------------------------------------------
|
|
55
113
|
const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
56
|
-
const
|
|
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
|
+
const REMOVED_KEYS = {
|
|
137
|
+
locale: "읽는 곳이 없었다",
|
|
138
|
+
rules: `규칙 문서는 specthread/rules.md 고정이다`,
|
|
139
|
+
pending: `관리 문서는 specthread/pending.md 고정이다`,
|
|
140
|
+
project: `프로젝트 문서는 specthread/project.md 고정이다`,
|
|
141
|
+
"features.emDash": "em dash 검사를 제거했다",
|
|
142
|
+
};
|
|
143
|
+
/**
|
|
144
|
+
* 한 계층을 검증하고, 제거한 키와 모르는 키를 뺀 사본을 돌려준다.
|
|
145
|
+
*
|
|
146
|
+
* 병합 전에 계층마다 본다. 병합 뒤에 보면 틀린 값이 어느 파일에서 왔는지 알 수 없다.
|
|
147
|
+
*/
|
|
148
|
+
const validateLayer = (raw, file) => {
|
|
149
|
+
const problems = [];
|
|
150
|
+
const warnings = [];
|
|
151
|
+
if (!isPlainObject(raw)) {
|
|
152
|
+
return { value: {}, problems: [{ file, key: "", message: "최상위가 객체여야 한다" }], warnings };
|
|
153
|
+
}
|
|
154
|
+
const walk = (obj, schema, prefix) => {
|
|
155
|
+
const out = {};
|
|
156
|
+
for (const [key, v] of Object.entries(obj)) {
|
|
157
|
+
const full = prefix === "" ? key : `${prefix}.${key}`;
|
|
158
|
+
if (full in REMOVED_KEYS) {
|
|
159
|
+
warnings.push(`${file}: ${full} 는 제거된 키다. 지워도 된다 - ${REMOVED_KEYS[full]}`);
|
|
160
|
+
continue;
|
|
161
|
+
}
|
|
162
|
+
const field = schema[key];
|
|
163
|
+
if (field === undefined) {
|
|
164
|
+
warnings.push(`${file}: 알 수 없는 키 ${full} - 무시한다`);
|
|
165
|
+
continue;
|
|
166
|
+
}
|
|
167
|
+
if (field.check !== undefined) {
|
|
168
|
+
const message = field.check(v);
|
|
169
|
+
if (message === null)
|
|
170
|
+
out[key] = v;
|
|
171
|
+
else
|
|
172
|
+
problems.push({ file, key: full, message });
|
|
173
|
+
continue;
|
|
174
|
+
}
|
|
175
|
+
if (!isPlainObject(v)) {
|
|
176
|
+
problems.push({ file, key: full, message: "객체여야 한다" });
|
|
177
|
+
continue;
|
|
178
|
+
}
|
|
179
|
+
if (field.anyKey !== undefined) {
|
|
180
|
+
const check = field.anyKey;
|
|
181
|
+
const bad = Object.entries(v).filter(([, x]) => check(x) !== null);
|
|
182
|
+
for (const [k, x] of bad)
|
|
183
|
+
problems.push({ file, key: `${full}.${k}`, message: check(x) ?? "" });
|
|
184
|
+
if (bad.length === 0)
|
|
185
|
+
out[key] = v;
|
|
186
|
+
continue;
|
|
187
|
+
}
|
|
188
|
+
out[key] = walk(v, field.fields ?? {}, full);
|
|
189
|
+
}
|
|
190
|
+
return out;
|
|
191
|
+
};
|
|
192
|
+
return { value: walk(raw, SCHEMA, ""), problems, warnings };
|
|
193
|
+
};
|
|
194
|
+
// ---------------------------------------------------------------------------
|
|
195
|
+
// Deep merge - 중첩 객체만 재귀, 배열은 덮어쓰기
|
|
196
|
+
// ---------------------------------------------------------------------------
|
|
197
|
+
/**
|
|
198
|
+
* 객체지만 통째로 교체하는 키.
|
|
199
|
+
*
|
|
200
|
+
* `path` 는 키가 자유 라벨이라, 키 단위로 병합하면 기본 키 (`docs`, `specthread`) 를
|
|
201
|
+
* 생략으로는 지울 수 없다. "이 경로들을 스캔한다" 는 뜻이 되려면 배열처럼 교체해야 한다.
|
|
202
|
+
*/
|
|
203
|
+
const REPLACE_KEYS = new Set(["path"]);
|
|
204
|
+
const deepMerge = (base, override, depth = 0) => {
|
|
57
205
|
const result = { ...base };
|
|
58
206
|
for (const key of Object.keys(override)) {
|
|
59
207
|
const baseVal = result[key];
|
|
60
208
|
const overVal = override[key];
|
|
61
|
-
if (
|
|
62
|
-
result[key] =
|
|
209
|
+
if (depth === 0 && REPLACE_KEYS.has(key)) {
|
|
210
|
+
result[key] = overVal;
|
|
211
|
+
}
|
|
212
|
+
else if (isPlainObject(baseVal) && isPlainObject(overVal)) {
|
|
213
|
+
result[key] = deepMerge(baseVal, overVal, depth + 1);
|
|
63
214
|
}
|
|
64
215
|
else if (overVal !== undefined) {
|
|
65
216
|
result[key] = overVal;
|
|
@@ -68,10 +219,11 @@ const deepMerge = (base, override) => {
|
|
|
68
219
|
return result;
|
|
69
220
|
};
|
|
70
221
|
// ---------------------------------------------------------------------------
|
|
71
|
-
//
|
|
222
|
+
// 병합 후 처리
|
|
72
223
|
// ---------------------------------------------------------------------------
|
|
73
224
|
const ruleGroupSet = new Set(ALL_RULE_GROUPS);
|
|
74
|
-
|
|
225
|
+
/** 모르는 군은 경고만 한다. 그 군의 지적은 어차피 없으므로 걸러도 결과가 같다 */
|
|
226
|
+
const warnSkipCheckGroups = (items) => {
|
|
75
227
|
for (const item of items) {
|
|
76
228
|
if (typeof item === "string")
|
|
77
229
|
continue;
|
|
@@ -82,25 +234,40 @@ const validateSkipCheck = (items) => {
|
|
|
82
234
|
}
|
|
83
235
|
}
|
|
84
236
|
}
|
|
85
|
-
return items;
|
|
86
237
|
};
|
|
238
|
+
/** 경로 값을 색인 경로와 같은 형태로 맞춘다. 소비처는 정규화된 값만 본다 */
|
|
239
|
+
const normalizePaths = (config) => ({
|
|
240
|
+
...config,
|
|
241
|
+
skipCheck: config.skipCheck.map((e) => typeof e === "string" ? normalizeConfigPath(e) : { ...e, path: normalizeConfigPath(e.path) }),
|
|
242
|
+
skipRefs: config.skipRefs.map(normalizeConfigPath),
|
|
243
|
+
work: normalizeConfigPath(config.work),
|
|
244
|
+
});
|
|
87
245
|
// ---------------------------------------------------------------------------
|
|
88
246
|
// Public API
|
|
89
247
|
// ---------------------------------------------------------------------------
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
const
|
|
99
|
-
|
|
100
|
-
const
|
|
101
|
-
|
|
102
|
-
|
|
248
|
+
/**
|
|
249
|
+
* 기본값 → config.jsonc → config.local.jsonc 순으로 병합한 설정.
|
|
250
|
+
*
|
|
251
|
+
* 쓸 수 없는 값이 하나라도 있으면 `ConfigError` 를 던진다. 경고는 출력만 하고 진행한다.
|
|
252
|
+
*/
|
|
253
|
+
export const loadConfig = (root = process.cwd()) => {
|
|
254
|
+
let merged = { ...DEFAULT_CONFIG };
|
|
255
|
+
const problems = [];
|
|
256
|
+
const warnings = [];
|
|
257
|
+
for (const file of [CONFIG_PATH, LOCAL_CONFIG_PATH]) {
|
|
258
|
+
const abs = join(root, file);
|
|
259
|
+
if (!existsSync(abs))
|
|
260
|
+
continue;
|
|
261
|
+
const layer = validateLayer(parseJsonc(readFileSync(abs, "utf-8"), file), file);
|
|
262
|
+
problems.push(...layer.problems);
|
|
263
|
+
warnings.push(...layer.warnings);
|
|
264
|
+
merged = deepMerge(merged, layer.value);
|
|
103
265
|
}
|
|
104
|
-
|
|
266
|
+
for (const w of warnings)
|
|
267
|
+
console.warn(`[specthread] ${w}`);
|
|
268
|
+
if (problems.length > 0)
|
|
269
|
+
throw new ConfigError(problems);
|
|
270
|
+
const config = normalizePaths(merged);
|
|
271
|
+
warnSkipCheckGroups(config.skipCheck);
|
|
105
272
|
return config;
|
|
106
273
|
};
|
package/dist/config.schema.d.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* specthread
|
|
2
|
+
* specthread/config.jsonc 스키마.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
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
|
-
*
|
|
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" 가
|
|
77
|
+
* 예: ["spec"] - "spec §4" 가 templates/spec.md 로 잘못 매칭되는 것 방지.
|
|
90
78
|
*/
|
|
91
79
|
ignoreDocNames: string[];
|
|
92
80
|
/**
|
|
93
|
-
* 규칙 검사를 건너뛸 경로.
|
|
94
|
-
* - string: 해당
|
|
95
|
-
* - { path, only }: 해당 경로에서 지정한 군만
|
|
81
|
+
* 규칙 검사를 건너뛸 경로. 경로 아래 (디렉터리 경계) 의 파일에 적용한다.
|
|
82
|
+
* - string: 해당 경로의 검사·생성을 전부 건너뛴다
|
|
83
|
+
* - { path, only }: 해당 경로에서 지정한 군만 검사·생성한다
|
|
96
84
|
*/
|
|
97
85
|
skipCheck: (string | SkipCheckEntry)[];
|
|
98
|
-
/** 참조
|
|
86
|
+
/** 참조 절을 만들지 않을 경로. 경로 아래 (디렉터리 경계) 의 문서에 적용한다 */
|
|
99
87
|
skipRefs: string[];
|
|
100
|
-
|
|
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;
|
package/dist/config.schema.js
CHANGED
|
@@ -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
|
-
|
|
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
|
};
|
package/dist/constants/docs.d.ts
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* 두 곳에 같은 값을 두면 한쪽만 고쳤을 때 생성기와 검사기가 어긋난다. `TAIL_NAMES` 가
|
|
5
5
|
* `utils/parse.ts` 와 `checks/headings.ts` 에 각각 있어 실제로 그 상태였다.
|
|
6
6
|
*
|
|
7
|
-
* 규칙 본문은 `
|
|
7
|
+
* 규칙 본문은 `specthread/rules.md` 가 갖는다. 여기는 그 규칙이 쓰는 값만 담는다.
|
|
8
8
|
*/
|
|
9
9
|
/**
|
|
10
10
|
* 꼬리 절 예약어 (`rules.md` §2-5).
|
|
@@ -12,4 +12,9 @@
|
|
|
12
12
|
* 파서가 꼬리 절 경계를 잡는 데 쓰고, 검사기가 본문 절이 이 이름을 쓰는지 본다.
|
|
13
13
|
* 순서가 곧 문서 안 등장 순서다.
|
|
14
14
|
*/
|
|
15
|
-
export declare const
|
|
15
|
+
export declare const TAIL: {
|
|
16
|
+
readonly REFS: '참조';
|
|
17
|
+
readonly PENDING: '미확정 사항';
|
|
18
|
+
readonly CHANGELOG: '변경 이력';
|
|
19
|
+
};
|
|
20
|
+
export declare const TAIL_NAMES: readonly ["참조", "미확정 사항", "변경 이력"];
|