dsh-knit 0.11.0 → 0.12.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,304 @@
1
+ /**
2
+ * Knit · **引用关系**(v0.12)
3
+ *
4
+ * 从工作区的 Markdown 里解析出「谁引用了谁」,供反向链接面板使用。
5
+ *
6
+ * ## 为什么是「宁可少,不可错」
7
+ *
8
+ * 设计依据是拿真实语料量出来的(`01_ Knit PRD/Knit_SDD-v0.12-链接解析与反向链接面板.md` §一):
9
+ *
10
+ * - `[[wikilink]]` 在真实语料里出现 **0 次** —— 所以**不解析 Obsidian 语法**,
11
+ * 真正要认的是 `` `path/x.md` ``(出现 946 次)
12
+ * - **歧义 basename 是最大误报源**:`SKILL.md` 有 20 个、`01_公众号正文.md` 有 12 个。
13
+ * 一条只写了 basename 的提及**无法确定是哪一篇** —— 而那些提及多半在讲
14
+ * 「文件名约定」而不是某一篇具体文档(实测 13% 的边是这么来的)
15
+ *
16
+ * 所以本模块**猜的一律不算**:解析不出来就是没有链接。
17
+ * 少显示一条真链接,比显示一条假链接轻。
18
+ *
19
+ * ## 这是纯解析,不碰排序
20
+ *
21
+ * 链接图当排序信号**实测补不上**词面错配那个缺口(目标文档 BM25 第 45 名 →
22
+ * 融合后 16~24 名,RRF 最好第 8,从未进 top-5)。所以这里只产出「关系」,不参与打分。
23
+ *
24
+ * ## 依赖是注入的,不 import `index.js`
25
+ *
26
+ * `index.js` 要 import 本模块来挂路由;如果本模块反过来 import 它的
27
+ * `collectDocs` / `readDocument`,就成环了。所以照 `tool.js` 的先例
28
+ * (`knitDocsDefinition(scan, read)`)**由调用方把两个函数传进来**。
29
+ * 好处不止是避环:纯函数可以拿假数据直接测,不用起文件系统。
30
+ *
31
+ * ⚠️ **已知边界**(都写在 SDD §八):不做模糊匹配、不处理 `../` 上跳、
32
+ * 不区分代码块内的「示例路径」、正文按 `readDocument` 的 512KB 上限截断。
33
+ */
34
+
35
+ /** 解析一篇正文时最多认多少条候选,防御性上限(正常文档远低于此)。 */
36
+ const MAX_REFS_PER_DOC = 500
37
+
38
+ /**
39
+ * 从正文里抽出**候选**引用(还没解析成 rel)。
40
+ *
41
+ * 三种真实写法,按语料出现频次排:
42
+ * 1. 反引号包裹的路径 —— `` `docs/A.md` ``(946 次,主力)
43
+ * 2. 标准 Markdown 链接 —— `[文字](docs/A.md)`(15 次)
44
+ * 3. 裸路径提及 —— `见 docs/A.md`(前面必须是空白或括号,避免咬到 `a.md.bak` 这类)
45
+ *
46
+ * **不含 `[[wikilink]]`** —— 真实语料 0 次,不做。
47
+ *
48
+ * @param {string} text - 正文(原文,**不是**小写化的 haystack)
49
+ * @returns {string[]} 去重后的候选项,保持出现顺序
50
+ */
51
+ export function extractRefs(text) {
52
+ if (typeof text !== 'string' || text === '') return []
53
+ const out = []
54
+ const seen = new Set()
55
+ const push = (raw) => {
56
+ const v = String(raw || '').trim()
57
+ if (!v || seen.has(v)) return
58
+ if (out.length >= MAX_REFS_PER_DOC) return
59
+ // 外链不是本工作区的文档
60
+ if (/^[a-z][a-z0-9+.-]*:/i.test(v)) return
61
+ if (!/\.md$/i.test(v)) return
62
+ seen.add(v)
63
+ out.push(v)
64
+ }
65
+
66
+ // ① 反引号:允许空格(`00_ Knit PRD/x.md` 这种目录名真实存在),不允许换行/反引号
67
+ for (const m of text.matchAll(/`([^`\n]+?)`/g)) push(m[1])
68
+ // ② Markdown 链接:取 () 里的路径,忽略其后的 #锚点
69
+ for (const m of text.matchAll(/\]\(\s*([^)\s]+?)(?:#[^)\s]*)?\s*\)/g)) push(m[1])
70
+ // ③ 裸路径:前面是行首/空白/中文括号,路径本身不含空格(有空格就得用反引号),
71
+ // 末尾用 `(?![\w.])` 挡住 `a.md.bak` 这类「更长但不是 .md」的字符串
72
+ //
73
+ // ⚠️ 必须在**挖掉反引号与链接目标之后的副本**上跑。否则
74
+ // `` `00_ Knit PRD/x.md` `` 里的 `PRD/x.md`(前面正好是空格)会被当成
75
+ // 一条独立候选 —— 这是测试抓出来的真实缺陷,不是假想。
76
+ const masked = text
77
+ .replace(/`[^`\n]*`/g, (s) => ' '.repeat(s.length))
78
+ .replace(/\]\([^)\n]*\)/g, (s) => ' '.repeat(s.length))
79
+ const BARE = /(?:^|[\s((])((?:[\w\u4e00-\u9fa5.@+-]+\/)*[\w\u4e00-\u9fa5.@+-]+\.md)(?![\w.])/gm
80
+ for (const m of masked.matchAll(BARE)) push(m[1])
81
+
82
+ return out
83
+ }
84
+
85
+ /** rel 用 `/` 连接(`index.js` 保证),所以这里也按 `/` 取目录,不碰 `node:path`。 */
86
+ const dirOf = (rel) => {
87
+ const i = String(rel).lastIndexOf('/')
88
+ return i === -1 ? '' : String(rel).slice(0, i)
89
+ }
90
+ const baseOf = (rel) => {
91
+ const s = String(rel)
92
+ const i = s.lastIndexOf('/')
93
+ return i === -1 ? s : s.slice(i + 1)
94
+ }
95
+
96
+ /**
97
+ * 为一批 rel 建解析上下文。**纯数据,可缓存**。
98
+ *
99
+ * @param {string[]} rels - 工作区里全部文档的 rel
100
+ * @returns {{relSet:Set<string>, rels:string[], byBase:Map<string,string[]>}}
101
+ */
102
+ export function createIndex(rels) {
103
+ const relSet = new Set(rels)
104
+ const byBase = new Map()
105
+ for (const rel of rels) {
106
+ const b = baseOf(rel)
107
+ if (!byBase.has(b)) byBase.set(b, [])
108
+ byBase.get(b).push(rel)
109
+ }
110
+ return { relSet, rels, byBase }
111
+ }
112
+
113
+ /**
114
+ * 把一条候选解析成工作区内的 rel,**解析不出来就返回 null**。
115
+ *
116
+ * 优先级(SDD §3.3,顺序本身就是设计):
117
+ * 1. **引用方所在目录优先** —— 这才是相对路径的语义。
118
+ * 所以 `docs/B.md` 里写 `README.md` 会先找 `docs/README.md`
119
+ * 2. 工作区根
120
+ * 3. **缩写后缀**:`-SDD-v0.6.md` 这种省略了公共前缀的写法(真实语料里存在),
121
+ * 必须**唯一命中**才算
122
+ * 4. **basename**:仅当全库该名字**唯一**时才算
123
+ * 5. 否则 → `null`(§一 的 13% 误报就是这里挡掉的)
124
+ *
125
+ * @param {string} raw - 候选项
126
+ * @param {object} index - `createIndex()` 的产物
127
+ * @param {string} [referrerRel] - 引用方的 rel;不传则跳过第 1 步
128
+ * @returns {string|null}
129
+ */
130
+ export function resolveRef(raw, index, referrerRel) {
131
+ const v = String(raw || '').trim()
132
+ if (!v || !index || !(index.relSet instanceof Set)) return null
133
+ if (/^[a-z][a-z0-9+.-]*:/i.test(v)) return null
134
+ if (!/\.md$/i.test(v)) return null
135
+
136
+ // 去掉 ./ 前缀(`./docs/A.md` 是常见写法,但不是本工作区的 rel)
137
+ const clean = v.replace(/^\.\//, '')
138
+
139
+ // ① 引用方所在目录
140
+ if (referrerRel) {
141
+ const dir = dirOf(referrerRel)
142
+ if (dir) {
143
+ const sibling = `${dir}/${clean}`
144
+ if (index.relSet.has(sibling)) return sibling
145
+ }
146
+ }
147
+
148
+ // ② 工作区根
149
+ if (index.relSet.has(clean)) return clean
150
+
151
+ // ③ 缩写后缀:只在以 `-` 开头时试,且必须唯一
152
+ if (clean.startsWith('-')) {
153
+ const tail = clean.slice(1)
154
+ const hits = index.rels.filter((r) => r.endsWith(tail))
155
+ if (hits.length === 1) return hits[0]
156
+ return null
157
+ }
158
+
159
+ // ④ basename,仅当唯一
160
+ const same = index.byBase.get(baseOf(clean))
161
+ if (same && same.length === 1) return same[0]
162
+
163
+ // ⑤ 猜不了就不算
164
+ return null
165
+ }
166
+
167
+ /** 模块内的图缓存:一个工作区一张图。key 是 `root`,值是 `{signature, graph}`。 */
168
+ const CACHE = new Map()
169
+ /** 进行中的构建,避免并发请求解析两遍。key 是 `root`。 */
170
+ const INFLIGHT = new Map()
171
+
172
+ /**
173
+ * 图签名:变了才重建。用「篇数 + 最大 mtime + 是否被扫描上限截断」——
174
+ * 三个都便宜(`list()` 本身已经按 mtime 缓存了元信息),且足以发现增删改。
175
+ */
176
+ function signatureOf(listed) {
177
+ const docs = (listed && listed.docs) || []
178
+ let max = 0
179
+ for (const d of docs) if (d.mtimeMs > max) max = d.mtimeMs
180
+ return `${docs.length}:${max}:${listed && listed.truncated ? 1 : 0}`
181
+ }
182
+
183
+ /**
184
+ * 建(或复用缓存的)引用图。
185
+ *
186
+ * @param {string} root - 工作区根
187
+ * @param {{list:Function, read:Function}} io - `list(root)` → `{docs, truncated}`;`read(root, rel)` → `{ok, text}`
188
+ * @returns {Promise<object>} `{ signature, docs:Map<rel,title>, out:Map<rel,Set>, in:Map<rel,Set>, limited, parsed, skipped }`
189
+ */
190
+ export async function buildLinkGraph(root, io) {
191
+ const listed = await io.list(root)
192
+ const signature = signatureOf(listed)
193
+ const hit = CACHE.get(root)
194
+ if (hit && hit.signature === signature) return hit.graph
195
+
196
+ const pending = INFLIGHT.get(root)
197
+ if (pending) return pending
198
+
199
+ const work = (async () => {
200
+ const docs = (listed && listed.docs) || []
201
+ const titles = new Map(docs.map((d) => [d.rel, d.title || baseOf(d.rel)]))
202
+ const index = createIndex(docs.map((d) => d.rel))
203
+ const out = new Map()
204
+ let parsed = 0
205
+ let skipped = 0
206
+
207
+ for (const doc of docs) {
208
+ let text = ''
209
+ try {
210
+ const r = await io.read(root, doc.rel)
211
+ if (!r || r.ok !== true) {
212
+ skipped += 1
213
+ continue
214
+ }
215
+ text = r.text || ''
216
+ } catch {
217
+ skipped += 1
218
+ continue
219
+ }
220
+ parsed += 1
221
+ const targets = new Set()
222
+ for (const raw of extractRefs(text)) {
223
+ const rel = resolveRef(raw, index, doc.rel)
224
+ if (rel && rel !== doc.rel) targets.add(rel)
225
+ }
226
+ out.set(doc.rel, targets)
227
+ }
228
+
229
+ // 反向边由正向边推出来,避免两处逻辑不一致
230
+ const incoming = new Map(docs.map((d) => [d.rel, new Set()]))
231
+ for (const [from, targets] of out) {
232
+ for (const to of targets) {
233
+ if (incoming.has(to)) incoming.get(to).add(from)
234
+ }
235
+ }
236
+
237
+ const graph = {
238
+ signature,
239
+ titles,
240
+ out,
241
+ in: incoming,
242
+ limited: !!(listed && listed.truncated),
243
+ parsed,
244
+ skipped,
245
+ }
246
+ CACHE.set(root, { signature, graph })
247
+ INFLIGHT.delete(root)
248
+ return graph
249
+ })()
250
+
251
+ INFLIGHT.set(root, work)
252
+ try {
253
+ return await work
254
+ } catch (err) {
255
+ INFLIGHT.delete(root)
256
+ throw err
257
+ }
258
+ }
259
+
260
+ /** 仅供测试:清掉缓存,避免用例之间互相污染。 */
261
+ export function resetLinkCache() {
262
+ CACHE.clear()
263
+ INFLIGHT.clear()
264
+ }
265
+
266
+ /** 按「对方入度降序 + rel 字典序」排 —— 引用多的文档往往是主脉络,且顺序必须稳定。 */
267
+ function orderBy(rels, graph) {
268
+ return [...rels].sort((a, b) => {
269
+ const da = (graph.in.get(a) || new Set()).size
270
+ const db = (graph.in.get(b) || new Set()).size
271
+ if (da !== db) return db - da
272
+ return a < b ? -1 : a > b ? 1 : 0
273
+ })
274
+ }
275
+
276
+ /**
277
+ * 取某一篇的引用关系。**只返回 `rel` + `title`** —— 与 `knit_docs` 同一条纪律,
278
+ * 不把图、haystack 之类的内部结构泄漏给客户端。
279
+ *
280
+ * @param {object} graph - `buildLinkGraph()` 的产物
281
+ * @param {string} rel - 目标文档
282
+ * @param {number} [limit] - 每侧最多返回多少条(计数仍给全量)
283
+ * @returns {object} 成功 `{ok:true, …}`;未知 rel 返回 `{ok:false, code:'knit/not-found'}`
284
+ */
285
+ export function linksOf(graph, rel, limit = 50) {
286
+ if (!graph || !graph.titles || !graph.titles.has(rel)) {
287
+ return { ok: false, code: 'knit/not-found' }
288
+ }
289
+ const cap = Number.isFinite(limit) && limit > 0 ? Math.trunc(limit) : 50
290
+ const map = (set) => orderBy(set || new Set(), graph)
291
+ .map((r) => ({ rel: r, title: graph.titles.get(r) || baseOf(r) }))
292
+
293
+ const incoming = map(graph.in.get(rel))
294
+ const outgoing = map(graph.out.get(rel))
295
+ return {
296
+ ok: true,
297
+ rel,
298
+ incoming: incoming.slice(0, cap),
299
+ outgoing: outgoing.slice(0, cap),
300
+ incomingTotal: incoming.length,
301
+ outgoingTotal: outgoing.length,
302
+ limited: !!graph.limited,
303
+ }
304
+ }
@@ -1177,3 +1177,183 @@ test('媒体:媒体视图一个媒体都没有时给出专属空态', async ()
1177
1177
  nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1178
1178
  assert.match(byClass(nodes, 'knit-msg').map(textOf).join(''), /还没有图片或视频/)
1179
1179
  })
1180
+
1181
+ /* ── v0.12 引用条 ───────────────────────────────────── */
1182
+
1183
+ /** 列表 / 正文 / 引用 三路分流。 */
1184
+ function linksResponder(linksPayload) {
1185
+ return (url) => {
1186
+ if (url.includes('/api/links')) return linksPayload
1187
+ if (url.includes('/api/doc')) {
1188
+ return { ok: true, rel: '技术方案.md', title: '技术方案', text: '# 技术方案\n\n正文。', truncated: false }
1189
+ }
1190
+ return listPayload()
1191
+ }
1192
+ }
1193
+
1194
+ const LINKS_PAYLOAD = {
1195
+ ok: true,
1196
+ rel: '技术方案.md',
1197
+ incoming: [{ rel: 'sub/需求 文档.md', title: '需求' }],
1198
+ outgoing: [{ rel: 'CHANGELOG.md', title: '变更' }],
1199
+ incomingTotal: 3,
1200
+ outgoingTotal: 1,
1201
+ limited: false,
1202
+ }
1203
+
1204
+ /** 打开第一篇文档,把预览与引用条都跑完。 */
1205
+ async function openFirstDoc(nodes) {
1206
+ let ns = nodes
1207
+ ns = harness.render(h(KnitBodyForLinks(), { sessionId: 's1' }))
1208
+ await harness.flush()
1209
+ ns = harness.render(h(KnitBodyForLinks(), { sessionId: 's1' }))
1210
+ byClass(ns, 'knit-doc')[0].props.onClick()
1211
+ ns = harness.render(h(KnitBodyForLinks(), { sessionId: 's1' }))
1212
+ await harness.flush()
1213
+ return harness.render(h(KnitBodyForLinks(), { sessionId: 's1' }))
1214
+ }
1215
+
1216
+ /** `harness.seed` 的槽位与既有用例保持一致(notice / sort)。 */
1217
+ function KnitBodyForLinks() {
1218
+ harness.reset()
1219
+ harness.seed(['', 'time'])
1220
+ return loadClientModule().exports.__test.KnitBody
1221
+ }
1222
+
1223
+ test('引用条:打开一篇会请求 /api/links,默认折叠只给计数', async () => {
1224
+ const { calls } = installFetch(linksResponder(LINKS_PAYLOAD))
1225
+ const { KnitBody } = loadClientModule().exports.__test
1226
+ harness.reset()
1227
+ harness.seed(['', 'time'])
1228
+ let nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1229
+ await harness.flush()
1230
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1231
+
1232
+ byClass(nodes, 'knit-doc')[0].props.onClick()
1233
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1234
+ await harness.flush()
1235
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1236
+
1237
+ const linksCall = calls.find((u) => u.includes('/api/links'))
1238
+ assert.ok(linksCall, '应请求引用关系')
1239
+ assert.ok(linksCall.includes(encodeURIComponent('技术方案.md')), `rel 应被编码:${linksCall}`)
1240
+ assert.equal(byClass(nodes, 'knit-link-row').length, 0, '默认折叠,不该有列表项')
1241
+ const summary = byClass(nodes, 'knit-links-summary').map(textOf).join('')
1242
+ assert.match(summary, /被引用 3/)
1243
+ assert.match(summary, /引用了 1/)
1244
+ })
1245
+
1246
+ test('引用条:展开后列出两侧,超出的给「还有 N 篇」', async () => {
1247
+ installFetch(linksResponder(LINKS_PAYLOAD))
1248
+ const { KnitBody } = loadClientModule().exports.__test
1249
+ harness.reset()
1250
+ harness.seed(['', 'time'])
1251
+ let nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1252
+ await harness.flush()
1253
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1254
+ byClass(nodes, 'knit-doc')[0].props.onClick()
1255
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1256
+ await harness.flush()
1257
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1258
+
1259
+ byClass(nodes, 'knit-links-head')[0].props.onClick()
1260
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1261
+
1262
+ assert.equal(byClass(nodes, 'knit-link-row').length, 2, '被引用 1 条 + 引用 1 条')
1263
+ assert.deepEqual(byClass(nodes, 'knit-link-name').map(textOf), ['需求', '变更'])
1264
+ assert.deepEqual(byClass(nodes, 'knit-link-path').map(textOf),
1265
+ ['sub/需求 文档.md', 'CHANGELOG.md'], '副行给相对路径,方便认人')
1266
+ // incomingTotal 3 而只列了 1 条 → 提示还有 2 篇
1267
+ assert.match(byClass(nodes, 'knit-links-note').map(textOf).join(''), /还有 2 篇/)
1268
+ })
1269
+
1270
+ test('引用条:点一项就切到那一篇,且**不重新拉列表**(订阅制,不走轮询)', async () => {
1271
+ const { calls } = installFetch(linksResponder(LINKS_PAYLOAD))
1272
+ const { KnitBody } = loadClientModule().exports.__test
1273
+ harness.reset()
1274
+ harness.seed(['', 'time'])
1275
+ let nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1276
+ await harness.flush()
1277
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1278
+ byClass(nodes, 'knit-doc')[0].props.onClick()
1279
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1280
+ await harness.flush()
1281
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1282
+
1283
+ byClass(nodes, 'knit-links-head')[0].props.onClick()
1284
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1285
+
1286
+ byClass(nodes, 'knit-link-row')[0].props.onClick()
1287
+ // ⚠️ **刻意不 flush**:订阅制是**同步**送达的,点完立刻就该是新那篇。
1288
+ // 如果这一跳要经过列表接口,就必须等一次 fetch + flush,这条断言会红。
1289
+ // (不数 `/api/recent` 次数 —— 这个 harness 的 useEffect 不跟踪依赖,
1290
+ // 每次 flush 都会重跑所有 effect,数次数测不出「有没有走轮询」。)
1291
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1292
+ assert.match(
1293
+ byClass(nodes, 'knit-preview-name').map(textOf).join(''),
1294
+ /需求 文档\.md/,
1295
+ '点完立刻切到那一篇,中间不该有 fetch(AGENTS.md §6.4:即时信号别藏在轮询里)',
1296
+ )
1297
+
1298
+ await harness.flush()
1299
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1300
+ assert.ok(
1301
+ calls.some((u) => u.includes('/api/doc') && u.includes(encodeURIComponent('sub/需求 文档.md'))),
1302
+ '随后应真的去取那一篇的正文',
1303
+ )
1304
+ })
1305
+
1306
+ test('引用条:「没有被引用」与「读取失败」是两句不同的话(不都显示成空白)', async () => {
1307
+ installFetch(linksResponder({
1308
+ ok: true, rel: '技术方案.md', incoming: [], outgoing: [],
1309
+ incomingTotal: 0, outgoingTotal: 0, limited: false,
1310
+ }))
1311
+ let { KnitBody } = loadClientModule().exports.__test
1312
+ harness.reset()
1313
+ harness.seed(['', 'time'])
1314
+ let nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1315
+ await harness.flush()
1316
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1317
+ byClass(nodes, 'knit-doc')[0].props.onClick()
1318
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1319
+ await harness.flush()
1320
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1321
+ byClass(nodes, 'knit-links-head')[0].props.onClick()
1322
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1323
+ const emptyText = byClass(nodes, 'knit-links-empty').map(textOf).join('')
1324
+ assert.match(emptyText, /没有被引用/)
1325
+ assert.match(emptyText, /没有引用别的文档/)
1326
+
1327
+ // 失败态:服务端返回错误码 → 走另一句文案,且**不给展开按钮**
1328
+ installFetch(linksResponder({ ok: false, code: 'knit/not-found' }))
1329
+ ;({ KnitBody } = loadClientModule().exports.__test)
1330
+ harness.reset()
1331
+ harness.seed(['', 'time'])
1332
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1333
+ await harness.flush()
1334
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1335
+ byClass(nodes, 'knit-doc')[0].props.onClick()
1336
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1337
+ await harness.flush()
1338
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1339
+ assert.equal(byClass(nodes, 'knit-links-head').length, 0, '失败态没有可展开的头')
1340
+ assert.match(byClass(nodes, 'knit-links').map(textOf).join(''), /引用关系读取失败/)
1341
+ })
1342
+
1343
+ test('引用条:图片/视频不请求 /api/links(图里只有 .md,请求必然 404)', async () => {
1344
+ const { calls } = installFetch(kindResponder({ media: mediaPayload() }))
1345
+ const { KnitBody } = loadClientModule().exports.__test
1346
+ harness.reset()
1347
+ harness.seed(['', 'time', 'media'])
1348
+ let nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1349
+ await harness.flush()
1350
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1351
+
1352
+ byClass(nodes, 'knit-media-card')[0].props.onClick()
1353
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1354
+ await harness.flush()
1355
+ nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1356
+
1357
+ assert.ok(!calls.some((u) => u.includes('/api/links')), '媒体不该请求引用关系')
1358
+ assert.equal(byClass(nodes, 'knit-links').length, 0, '媒体不显示引用条')
1359
+ })
package/test/fixture.mjs CHANGED
@@ -23,9 +23,13 @@ const FAKE_MP4 = Buffer.alloc(4096, 0x21)
23
23
  /**
24
24
  * 建样本工作区。文件名刻意与旧断言一致(README.md / package.json / docs/screenshot.png),
25
25
  * 断言语义不用改;mtime 用 utimes 定死,排序断言不再看运气。
26
+ *
27
+ * @param {Array<[string, string|Buffer]>} [extra] - 追加的 `[rel, 内容]`。
28
+ * v0.12 的引用关系用例需要能自己造带链接的文件 —— **样本一律从这里要**,
29
+ * 不许去借仓库里的真实文件(AGENTS.md §6.8)。
26
30
  * @returns {string} 工作区绝对路径;进程退出时自动清理
27
31
  */
28
- export function makeWorkspace() {
32
+ export function makeWorkspace(extra = []) {
29
33
  const dir = mkdtempSync(join(tmpdir(), 'knit-fixture-'))
30
34
  const base = Date.now() - 120_000
31
35
  const files = [
@@ -35,6 +39,7 @@ export function makeWorkspace() {
35
39
  ['package.json', '{\n "name": "sample"\n}\n'],
36
40
  ['docs/screenshot.png', PADDED_PNG],
37
41
  ['docs/clip.mp4', FAKE_MP4],
42
+ ...extra,
38
43
  ]
39
44
  files.forEach(([rel, content], i) => {
40
45
  const abs = join(dir, rel)
@@ -15,8 +15,20 @@ import { stat } from 'node:fs/promises'
15
15
  import { apply } from '../src/host/index.js'
16
16
  import { makeWorkspace } from './fixture.mjs'
17
17
 
18
- /** 测试自带样本工作区(临时目录),里面有 docs/screenshot.png 当媒体样本。 */
19
- const PROJECT_ROOT = makeWorkspace()
18
+ /**
19
+ * 测试自带样本工作区(临时目录),里面有 docs/screenshot.png 当媒体样本。
20
+ *
21
+ * v0.12 追加了几个**带引用**的文件给 `/api/links` 用。刻意包含一组
22
+ * **同名但不同目录**的 `SKILL.md` —— 那是真实语料里最大的误报源
23
+ * (`SKILL.md` 有 20 个、`01_公众号正文.md` 有 12 个)。
24
+ */
25
+ const PROJECT_ROOT = makeWorkspace([
26
+ ['docs/hub.md', '# hub\n\n见 `docs/notes.md` 与 README.md\n'],
27
+ ['docs/leaf.md', '# leaf\n\n见 [笔记](docs/notes.md)\n'],
28
+ ['x/SKILL.md', '# x 的 skill\n'],
29
+ ['y/SKILL.md', '# y 的 skill\n'],
30
+ ['amb.md', '# amb\n\n见 `SKILL.md`(同名两处,不该产生边)\n'],
31
+ ])
20
32
 
21
33
  /**
22
34
  * 起一个挂着 Knit 路由的回环 server(伪造 cordis 的 webServer / sessions / effect)。
@@ -130,3 +142,69 @@ test('HTTP 端到端:媒体列表、/raw 整文件、Range 206、安全拒绝'
130
142
  await close()
131
143
  }
132
144
  })
145
+
146
+ test('HTTP 端到端:/api/links 的引用关系、缺参与越界、不泄漏内部结构', async () => {
147
+ const { base, close } = await startKnitServer()
148
+ try {
149
+ // 正常:hub 与 leaf 都引用了 docs/notes.md,所以它被引用 2 次、自己不引用别人
150
+ let r = await fetch(`${base}/api/links?sessionId=s&rel=${encodeURIComponent('docs/notes.md')}`)
151
+ let body = await r.json()
152
+ assert.equal(r.status, 200)
153
+ assert.equal(body.ok, true)
154
+ assert.equal(body.rel, 'docs/notes.md')
155
+ assert.equal(body.incomingTotal, 2, 'hub 与 leaf 各一条')
156
+ assert.deepEqual(body.incoming.map((d) => d.rel).sort(), ['docs/hub.md', 'docs/leaf.md'])
157
+ assert.equal(body.outgoingTotal, 0)
158
+ assert.deepEqual(body.outgoing, [])
159
+ assert.ok(body.incoming.every((d) => d.rel && d.title), '每项要有 rel 与 title')
160
+
161
+ // 不泄漏内部结构(与 knit_docs 同一条纪律)
162
+ for (const k of ['out', 'in', 'titles', 'signature', 'parsed', 'skipped', 'haystack']) {
163
+ assert.ok(!(k in body), `不该泄漏 ${k}`)
164
+ }
165
+
166
+ // 反向:hub 自己引用了 notes 与 README
167
+ r = await fetch(`${base}/api/links?sessionId=s&rel=${encodeURIComponent('docs/hub.md')}`)
168
+ body = await r.json()
169
+ assert.equal(r.status, 200)
170
+ assert.equal(body.outgoingTotal, 2)
171
+ assert.deepEqual(body.outgoing.map((d) => d.rel).sort(), ['README.md', 'docs/notes.md'])
172
+ assert.deepEqual(body.incoming, [])
173
+
174
+ // 🔴 误报回归:同名两处 SKILL.md 时,只写 basename 必须不产生边
175
+ r = await fetch(`${base}/api/links?sessionId=s&rel=${encodeURIComponent('x/SKILL.md')}`)
176
+ body = await r.json()
177
+ assert.equal(r.status, 200)
178
+ assert.equal(body.incomingTotal, 0, '歧义 basename 不许产生边')
179
+
180
+ // 缺 rel → 400,且是既有错误码
181
+ r = await fetch(`${base}/api/links?sessionId=s`)
182
+ body = await r.json()
183
+ assert.equal(r.status, 400)
184
+ assert.deepEqual(body, { ok: false, code: 'knit/missing-rel' })
185
+
186
+ // 未知 rel → 404。**越界路径也走这里** —— 图里只有工作区内的 rel,
187
+ // 所以这个路由**没有**按路径读文件的口子,套不出工作区外的内容。
188
+ for (const bad of ['nope.md', '../outside.md', '/etc/passwd.md']) {
189
+ r = await fetch(`${base}/api/links?sessionId=s&rel=${encodeURIComponent(bad)}`)
190
+ body = await r.json()
191
+ assert.equal(r.status, 404, `${bad} 应 404`)
192
+ assert.deepEqual(body, { ok: false, code: 'knit/not-found' })
193
+ }
194
+
195
+ // 安全响应头:JSON 路由与 /api/recent、/api/doc 一致 —— 都走 sendJson,设 `nosniff`。
196
+ // ⚠️ **CSP(含 `sandbox`)只有媒体路由 `/api/raw` 才设** —— 那是给浏览器渲染
197
+ // 图片/视频/SVG 用的,JSON 不吃这一套。我第一版按「所有路由都该有 CSP」写,
198
+ // 是**断言错了**,不是代码缺了防护。
199
+ r = await fetch(`${base}/api/links?sessionId=s&rel=${encodeURIComponent('docs/notes.md')}`)
200
+ assert.equal(r.headers.get('x-content-type-options'), 'nosniff')
201
+ assert.equal(r.headers.get('cache-control'), 'no-store')
202
+ assert.match(r.headers.get('content-type') || '', /application\/json/)
203
+
204
+ // 非 GET → 405(前置守卫覆盖新路由)
205
+ r = await fetch(`${base}/api/links?sessionId=s&rel=x.md`, { method: 'POST' })
206
+ assert.equal(r.status, 405)
207
+ } finally {
208
+ await close()
209
+ }
210
+ })