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.
- package/README.md +153 -123
- package/dist/bin/cli.js +2 -1
- package/dist/checks/headings.js +2 -2
- package/dist/checks/pending.js +3 -1
- package/dist/checks/sections.js +0 -1
- package/dist/checks/timestamps.js +1 -1
- package/dist/commands/init.js +51 -27
- package/dist/commands/upgrade-prompt.d.ts +12 -0
- package/dist/commands/upgrade-prompt.js +147 -0
- package/dist/config-loader.d.ts +22 -0
- package/dist/config-loader.js +41 -25
- package/dist/constants/docs.d.ts +1 -2
- package/dist/constants/docs.js +1 -2
- package/dist/constants/patterns.d.ts +1 -3
- package/dist/constants/patterns.js +1 -3
- package/dist/gen/pending-section.js +2 -2
- package/dist/gen/references.js +4 -4
- package/dist/gen/summary.js +2 -1
- package/dist/gen/toc.js +1 -1
- package/dist/types.d.ts +2 -2
- package/dist/utils/anchor.d.ts +1 -1
- package/dist/utils/anchor.js +1 -1
- package/dist/utils/ignore.js +1 -1
- package/dist/utils/parse.d.ts +6 -6
- package/dist/utils/parse.js +7 -8
- package/dist/utils/resolve.d.ts +15 -5
- package/dist/utils/resolve.js +49 -25
- package/dist/utils/scan.js +6 -2
- package/package.json +2 -2
- package/scaffold/claude/skills/gen/SKILL.md +2 -2
package/dist/utils/resolve.js
CHANGED
|
@@ -5,18 +5,38 @@
|
|
|
5
5
|
* 확장자를 뺀 것, 마크다운 링크를 동반한 것. 어느 쪽이든 같은 한 규칙으로 다룬다 -
|
|
6
6
|
* **같은 줄에서 왼쪽으로 가장 가까운 문서명** 을 대상으로 삼는다.
|
|
7
7
|
*/
|
|
8
|
-
import { basename, dirname, join, normalize } from "node:path";
|
|
8
|
+
import { basename, dirname, extname, join, normalize } from "node:path";
|
|
9
|
+
import { DEFAULT_FILE_KINDS } from "../config.schema.js";
|
|
9
10
|
import { anchorLinkLabelSpans, codeSpanMask, eachContentLine, } from "./parse.js";
|
|
10
|
-
/** 절 참조. 중간 자리에 문자가 오는 `§1-B-1` 도 받는다
|
|
11
|
+
/** 절 참조. 중간 자리에 문자가 오는 `§1-B-1` 도 받는다 */
|
|
11
12
|
const SECTION_REF = /§(\d+(?:-[0-9A-Za-z]+)*)/g;
|
|
13
|
+
/** 문서 확장자를 뗀 이름. 문서 확장자가 아니면 그대로 둔다 */
|
|
14
|
+
const stemOf = (base, docExts) => {
|
|
15
|
+
const ext = extname(base).toLowerCase();
|
|
16
|
+
return docExts.includes(ext) ? base.slice(0, -ext.length) : base;
|
|
17
|
+
};
|
|
18
|
+
/**
|
|
19
|
+
* 문서 확장자로 끝나는 파일 이름 패턴. 문서 확장자가 없으면 null.
|
|
20
|
+
*
|
|
21
|
+
* 긴 확장자를 먼저 시도하고 뒤에 글자가 이어지지 않는지 본다. `.md` 만 문서일 때
|
|
22
|
+
* `guide.mdx` 의 앞부분을 `guide.md` 로 읽지 않기 위해서다.
|
|
23
|
+
*/
|
|
24
|
+
const docFilePattern = (docExts) => {
|
|
25
|
+
if (docExts.length === 0)
|
|
26
|
+
return null;
|
|
27
|
+
const alts = [...docExts]
|
|
28
|
+
.sort((a, b) => b.length - a.length)
|
|
29
|
+
.map((e) => e.slice(1).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
|
|
30
|
+
return new RegExp(`([A-Za-z0-9_./-]+\\.(?:${alts.join("|")}))(?![A-Za-z0-9])`, "gi");
|
|
31
|
+
};
|
|
12
32
|
/**
|
|
13
33
|
* 문서 이름 → 경로 색인. basename 과 확장자 없는 stem 양쪽으로 넣는다.
|
|
14
34
|
*
|
|
15
|
-
* 코드
|
|
16
|
-
*
|
|
17
|
-
*
|
|
35
|
+
* 코드 주석은 `conventions §2` 처럼 확장자를 빼고 적기도 하므로 stem 도 찾을 수 있어야
|
|
36
|
+
* 한다. 같은 이름의 문서가 여럿이면 (루트와 `docs/` 의 `README.md`) 값이 여러 개
|
|
37
|
+
* 담기고, 그때는 경로가 함께 적혀 있지 않으면 대상을 특정할 수 없다.
|
|
18
38
|
*/
|
|
19
|
-
const buildNameMap = (paths) => {
|
|
39
|
+
const buildNameMap = (paths, docExts) => {
|
|
20
40
|
const map = new Map();
|
|
21
41
|
const push = (key, path) => {
|
|
22
42
|
const list = map.get(key) ?? [];
|
|
@@ -26,7 +46,9 @@ const buildNameMap = (paths) => {
|
|
|
26
46
|
for (const p of paths) {
|
|
27
47
|
const base = basename(p);
|
|
28
48
|
push(base, p);
|
|
29
|
-
|
|
49
|
+
const stem = stemOf(base, docExts);
|
|
50
|
+
if (stem !== base)
|
|
51
|
+
push(stem, p);
|
|
30
52
|
}
|
|
31
53
|
return map;
|
|
32
54
|
};
|
|
@@ -37,18 +59,18 @@ const buildNameMap = (paths) => {
|
|
|
37
59
|
* 이름만 있으면 색인에서 찾는다. 어느 쪽이든 후보가 둘 이상이면 특정하지 않는다 -
|
|
38
60
|
* 추측해서 붙이면 검사가 엉뚱한 문서를 대조하게 된다.
|
|
39
61
|
*/
|
|
40
|
-
const resolveDocName = (raw, fromFile,
|
|
62
|
+
const resolveDocName = (raw, fromFile, docPaths, nameMap) => {
|
|
41
63
|
// 상대 경로는 참조한 문서 위치를 기준으로 푼다. `../` 를 그냥 벗기면
|
|
42
|
-
// `../../
|
|
64
|
+
// `../../README.md` 가 `README.md` 가 되어 어느 디렉터리의 문서인지 알 수 없다.
|
|
43
65
|
if (/^\.{1,2}\//.test(raw)) {
|
|
44
66
|
const resolved = normalize(join(dirname(fromFile), raw));
|
|
45
|
-
return
|
|
67
|
+
return docPaths.includes(resolved)
|
|
46
68
|
? { path: resolved, reason: "resolved" }
|
|
47
69
|
: { path: null, reason: "unknown-doc" };
|
|
48
70
|
}
|
|
49
71
|
// `spec/player.md` 처럼 경로 조각이 붙은 형태는 접미 일치로 찾는다
|
|
50
72
|
if (raw.includes("/")) {
|
|
51
|
-
const hits =
|
|
73
|
+
const hits = docPaths.filter((p) => p === raw || p.endsWith("/" + raw));
|
|
52
74
|
if (hits.length === 1)
|
|
53
75
|
return { path: hits[0], reason: "resolved" };
|
|
54
76
|
return {
|
|
@@ -67,15 +89,15 @@ const resolveDocName = (raw, fromFile, mdPaths, nameMap) => {
|
|
|
67
89
|
/**
|
|
68
90
|
* `§` 왼쪽에서 참조 대상으로 볼 문서명을 고른다. 없으면 null.
|
|
69
91
|
*
|
|
70
|
-
* **끝 위치가 가장 오른쪽인 후보를 고른다.** 시작 위치로 비교하면 `](../../
|
|
71
|
-
* 안의 stem `
|
|
92
|
+
* **끝 위치가 가장 오른쪽인 후보를 고른다.** 시작 위치로 비교하면 `](../../README.md)`
|
|
93
|
+
* 안의 stem `README` 가 전체 경로보다 늦게 시작해서 선택되고, 경로로 구분할 수 없게 된다.
|
|
72
94
|
*
|
|
73
95
|
* 고른 문서명과 `§` 사이에 한글이 끼면 버린다. 그 문서명은 참조 대상이 아니라 화제다 -
|
|
74
96
|
* 실 참조는 사이에 공백·괄호·백틱·구분자만 온다.
|
|
75
97
|
*/
|
|
76
|
-
const nearestDocName = (left, knownStems) => {
|
|
98
|
+
const nearestDocName = (left, { docFile, knownStems }) => {
|
|
77
99
|
const candidates = [];
|
|
78
|
-
for (const named of left.matchAll(
|
|
100
|
+
for (const named of docFile === null ? [] : left.matchAll(docFile)) {
|
|
79
101
|
candidates.push({ text: named[1], end: named.index + named[1].length });
|
|
80
102
|
}
|
|
81
103
|
for (const word of left.matchAll(/([A-Za-z][A-Za-z0-9-]*)/g)) {
|
|
@@ -101,23 +123,25 @@ const asRelativePath = (target) => /^\.{1,2}\//.test(target) ? target : `./${tar
|
|
|
101
123
|
*
|
|
102
124
|
* stem 은 두 글자 이하를 뺀다 - 짧은 낱말은 산문에서 우연히 겹칠 확률이 높다.
|
|
103
125
|
*/
|
|
104
|
-
export const makeRefContext = (
|
|
105
|
-
const
|
|
126
|
+
export const makeRefContext = ({ docPaths, ignoreDocNames = [], docExts = DEFAULT_FILE_KINDS.doc, }) => {
|
|
127
|
+
const exts = docExts.map((e) => e.toLowerCase());
|
|
106
128
|
const deny = new Set(ignoreDocNames);
|
|
129
|
+
const stems = docPaths.map((p) => stemOf(basename(p), exts));
|
|
107
130
|
return {
|
|
108
|
-
|
|
109
|
-
nameMap,
|
|
110
|
-
knownStems: new Set(
|
|
131
|
+
docPaths,
|
|
132
|
+
nameMap: buildNameMap(docPaths, exts),
|
|
133
|
+
knownStems: new Set(stems.filter((k) => k.length > 2 && !deny.has(k))),
|
|
134
|
+
docFile: docFilePattern(exts),
|
|
111
135
|
};
|
|
112
136
|
};
|
|
113
137
|
/**
|
|
114
138
|
* 한 파일의 절 참조를 모두 뽑아 해소한다.
|
|
115
139
|
*
|
|
116
|
-
* `
|
|
117
|
-
* 따로 다룰 필요가 없다. 문서명을 못 찾으면 마크다운은 자기 문서 참조로 보고
|
|
140
|
+
* `auth.md §1·§4·§6` 같은 복수 절도 각 `§` 가 자기 왼쪽에서 가장 가까운 문서명을 대상으로
|
|
141
|
+
* 하므로 따로 다룰 필요가 없다. 문서명을 못 찾으면 마크다운은 자기 문서 참조로 보고
|
|
118
142
|
* (표 안 `§4-1` 같은 것), 코드는 대상 불명으로 남긴다.
|
|
119
143
|
*/
|
|
120
|
-
export const parseSectionRefs = (path, kind, lines, {
|
|
144
|
+
export const parseSectionRefs = (path, kind, lines, { docPaths, nameMap, knownStems, docFile }) => {
|
|
121
145
|
const out = [];
|
|
122
146
|
const scan = (line, i) => {
|
|
123
147
|
const mask = kind === "doc" ? codeSpanMask(line) : null;
|
|
@@ -135,7 +159,7 @@ export const parseSectionRefs = (path, kind, lines, { mdPaths, nameMap, knownSte
|
|
|
135
159
|
continue;
|
|
136
160
|
}
|
|
137
161
|
const docName = span === undefined
|
|
138
|
-
? nearestDocName(line.slice(0, m.index), knownStems)
|
|
162
|
+
? nearestDocName(line.slice(0, m.index), { docFile, knownStems })
|
|
139
163
|
: asRelativePath(span.target);
|
|
140
164
|
// 백틱 안에 문서명 없이 들어앉은 `§N` 은 표기법 인용이라 참조가 아니다
|
|
141
165
|
if (mask?.[m.index] && docName === null) {
|
|
@@ -152,7 +176,7 @@ export const parseSectionRefs = (path, kind, lines, { mdPaths, nameMap, knownSte
|
|
|
152
176
|
});
|
|
153
177
|
continue;
|
|
154
178
|
}
|
|
155
|
-
const { path: target, reason } = resolveDocName(docName, path,
|
|
179
|
+
const { path: target, reason } = resolveDocName(docName, path, docPaths, nameMap);
|
|
156
180
|
out.push({
|
|
157
181
|
num: m[1],
|
|
158
182
|
targetFile: target,
|
package/dist/utils/scan.js
CHANGED
|
@@ -85,8 +85,12 @@ const collectTargets = (root, pathConfig, extMap) => {
|
|
|
85
85
|
export const buildIndex = (root, config) => {
|
|
86
86
|
const extMap = buildExtMap(config.fileKinds);
|
|
87
87
|
const targets = collectTargets(root, config.path, extMap);
|
|
88
|
-
const
|
|
89
|
-
const ctx = makeRefContext(
|
|
88
|
+
const docPaths = targets.filter((t) => t.kind === "doc").map((t) => t.path);
|
|
89
|
+
const ctx = makeRefContext({
|
|
90
|
+
docPaths,
|
|
91
|
+
ignoreDocNames: config.ignoreDocNames,
|
|
92
|
+
docExts: config.fileKinds.doc,
|
|
93
|
+
});
|
|
90
94
|
const files = new Map();
|
|
91
95
|
for (const { path, kind } of targets) {
|
|
92
96
|
const lines = readFileSync(join(root, path), "utf8").split("\n");
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specthread",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Spec-Driven Development (SDD) template. Docs are the single source of truth; code implements docs.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -25,12 +25,12 @@
|
|
|
25
25
|
"release:minor": "npm version minor && npm publish && git push --tags",
|
|
26
26
|
"release:major": "npm version major && npm publish && git push --tags",
|
|
27
27
|
"docs:check": "node --test tools/docs/__tests__/scaffold.test.ts",
|
|
28
|
-
"docs:generate": "node tools/docs/bin/generate.ts",
|
|
29
28
|
"docs:test": "node --test \"tools/docs/__tests__/*.test.ts\"",
|
|
30
29
|
"docs:typecheck": "tsc -p tools/tsconfig.json"
|
|
31
30
|
},
|
|
32
31
|
"devDependencies": {
|
|
33
32
|
"@types/node": "^26.5.1",
|
|
33
|
+
"specthread": "^0.2.0",
|
|
34
34
|
"typescript": "^7.0.2"
|
|
35
35
|
}
|
|
36
36
|
}
|
|
@@ -38,6 +38,6 @@ npx specthread gen --write
|
|
|
38
38
|
4. 변경이 있으면:
|
|
39
39
|
- 어떤 파일의 어떤 절이 갱신되는지 요약한다.
|
|
40
40
|
- 사용자에게 적용 여부를 확인한다.
|
|
41
|
-
5. "꼬리 절 순서가 어긋나 건너뜀" 이 나오면 그 파일의 꼬리 절을 참조 → 미확정 사항 → 변경 이력 순서로 옮긴 뒤 다시 실행한다.
|
|
42
41
|
- 승인하면 `npx specthread gen --write`를 실행한다.
|
|
43
|
-
5.
|
|
42
|
+
5. "꼬리 절 순서가 어긋나 건너뜀" 이 나오면 그 파일의 꼬리 절을 참조 → 미확정 사항 → 변경 이력 순서로 옮긴 뒤 다시 실행한다.
|
|
43
|
+
6. 적용 후 `npx specthread check`를 실행해서 생성 관련 지적(`toc/stale`, `reference/stale`, `pending/section-stale`)이 해소되었는지 확인한다.
|