dsh-knit 0.21.0 → 0.22.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.
@@ -0,0 +1,340 @@
1
+ /**
2
+ * Knit · **增量索引的持久层**(v0.22)的测试
3
+ *
4
+ * 这一层只回答一个问题:**「重启之后还能不能凭证据相信盘上那份索引」**。
5
+ * 所以断言分成三组,分别对应模块头注释里的三条硬约束:
6
+ * · 不存正文 —— 记录形状里不许出现 `body`;
7
+ * · 按 canonical root 隔离 —— 同一个 `rel` 在两个工作区之间不许串;
8
+ * · 任何失败都不许抛进检索路径 —— 没有存储、开不起来、介质损坏一律空 Map。
9
+ *
10
+ * 「重启」的测法与 `control.test.mjs` 一致:**同一份介质 + 一个全新的后端**。
11
+ */
12
+ import test from 'node:test'
13
+ import assert from 'node:assert/strict'
14
+ import { mkdtempSync, mkdirSync, realpathSync, rmSync, symlinkSync } from 'node:fs'
15
+ import { tmpdir } from 'node:os'
16
+ import { join } from 'node:path'
17
+
18
+ import {
19
+ INDEX_CLEAN_PER_WRITE, INDEX_TABLES, INDEX_UNIT, INDEX_VERSION,
20
+ canonicalRoot, createIndexStore, headHashOf, keyToRel, recordKey, recordMatches, refsShapeOk, relToKey,
21
+ } from '../src/host/index-store.js'
22
+ import { fakeStorageBackend } from './fixture.mjs'
23
+
24
+ /* ── 工具 ─────────────────────────────────────────────── */
25
+
26
+ /** 假存储后端(与 `control.test.mjs` 同一个形状,放在 `fixture.mjs` 里共用)。 */
27
+ const fakeBackend = fakeStorageBackend
28
+
29
+ /** 造一条合法记录。 */
30
+ const recordOf = (rel, extra = {}) => ({
31
+ root: '/w', rel, mtimeMs: 1000, size: 12, headHash: headHashOf(`# ${rel}`),
32
+ title: rel, summary: '', refs: { md: [], any: [] }, ...extra,
33
+ })
34
+
35
+ /** 建一个临时目录(进程退出时清理)。 */
36
+ const dirs = []
37
+ function tempDir() {
38
+ const dir = mkdtempSync(join(tmpdir(), 'knit-index-store-'))
39
+ dirs.push(dir)
40
+ return dir
41
+ }
42
+ process.on('exit', () => {
43
+ for (const dir of dirs) {
44
+ try { rmSync(dir, { recursive: true, force: true }) } catch { /* 清理失败不影响结论 */ }
45
+ }
46
+ })
47
+
48
+ /* ── 1 · 键与指纹:纯函数,先钉死 ─────────────────────── */
49
+
50
+ test('relToKey:per-record 布局的键必须匹配 `[a-zA-Z0-9_-]+`,中文/斜杠/点都活得下来', () => {
51
+ const rels = [
52
+ 'README.md', 'docs/notes.md', 'a b c/d.e.md',
53
+ '文档/中文 名称.md', 'x/y/z/deep/file-1_2.md', '',
54
+ ]
55
+ for (const rel of rels) {
56
+ const key = relToKey(rel)
57
+ assert.match(key, /^[a-zA-Z0-9_-]*$/, `键 ${key} 不是安全的路径片段`)
58
+ }
59
+ // 同一个 rel 一定映射到同一个键(索引靠它做身份)
60
+ assert.equal(relToKey('a/b.md'), relToKey('a/b.md'))
61
+ assert.notEqual(relToKey('a/b.md'), relToKey('a/b.md/'))
62
+ })
63
+
64
+ test('recordKey:同一个 rel 在不同工作区必须是不同的键(否则互相覆盖)', () => {
65
+ const a = recordKey('/w/one', 'docs/a.md')
66
+ const b = recordKey('/w/two', 'docs/a.md')
67
+ assert.notEqual(a, b, '两个工作区的同名文件不能共用一个键')
68
+ assert.equal(a, recordKey('/w/one', 'docs/a.md'), '同一个输入必须给同一个键')
69
+ assert.match(a, /^[a-zA-Z0-9_-]+$/, 'per-record 布局的键必须是安全路径片段')
70
+ assert.equal(keyToRel(a), 'docs/a.md', '定长 root 指纹 ⇒ 无歧义还原')
71
+ assert.equal(keyToRel(b), 'docs/a.md')
72
+ // 键的长度随 rel 增长,前缀恒为 16 个 hex
73
+ assert.match(a.slice(0, 16), /^[0-9a-f]{16}$/)
74
+ // 还原:各种棘手的 rel 都要能原样取回来
75
+ for (const rel of ['README.md', 'a b c/d.e.md', '文档/中文 名称.md', 'x/y/z/deep/file-1_2.md', '']) {
76
+ assert.equal(keyToRel(recordKey('/w', rel)), rel, `rel=${rel} 必须能还原`)
77
+ }
78
+ })
79
+
80
+ test('headHashOf:16 个 hex、确定、内容不同则不同', () => {
81
+ const a = headHashOf('# 标题\n\n正文')
82
+ assert.match(a, /^[0-9a-f]{16}$/)
83
+ assert.equal(a, headHashOf('# 标题\n\n正文'), '同样的输入必须给同样的指纹')
84
+ assert.notEqual(a, headHashOf('# 标题\n\n正文 '), '差一个字符就必须不同')
85
+ assert.notEqual(headHashOf(''), headHashOf('a'))
86
+ })
87
+
88
+ test('recordMatches:缺指纹 / 元信息不符一律不可复用(不许只靠 mtime+size)', () => {
89
+ const observed = { mtimeMs: 1000, size: 12, headHash: headHashOf('# a.md') }
90
+ assert.equal(recordMatches(recordOf('a.md'), observed), true)
91
+ // 只有 mtime+size 对得上 —— 这正是 v0.21 的全部证据,v0.22 必须拒绝它
92
+ assert.equal(recordMatches({ rel: 'a.md', mtimeMs: 1000, size: 12 }, observed), false)
93
+ assert.equal(recordMatches(recordOf('a.md', { headHash: '' }), observed), false)
94
+ assert.equal(recordMatches(recordOf('a.md', { mtimeMs: 999 }), observed), false)
95
+ assert.equal(recordMatches(recordOf('a.md', { size: 13 }), observed), false)
96
+ assert.equal(recordMatches(recordOf('a.md', { headHash: headHashOf('别的') }), observed), false)
97
+ // 畸形输入不抛
98
+ for (const bad of [null, undefined, 0, 'x', []]) {
99
+ assert.equal(recordMatches(bad, observed), false)
100
+ }
101
+ })
102
+
103
+ test('canonicalRoot:展开符号链接;路径不存在时兜底原值不抛', () => {
104
+ const dir = tempDir()
105
+ const real = join(dir, 'real')
106
+ mkdirSync(real)
107
+ const link = join(dir, 'link')
108
+ symlinkSync(real, link)
109
+ assert.equal(canonicalRoot(link), realpathSync(real))
110
+ assert.equal(canonicalRoot(join(dir, 'nope')), join(dir, 'nope'))
111
+ })
112
+
113
+ /* ── 2 · 元数据与隔离 ─────────────────────────────────── */
114
+
115
+ test('open 的 descriptor 钉死布局与版本:per-record + version 3 + compatibleVersions [1, 2]', async () => {
116
+ const backend = fakeBackend()
117
+ const store = createIndexStore({ backend })
118
+ await store.read('/w')
119
+ assert.equal(backend.descriptors.length, 1, '`openUnit()` 必须记忆化(只开一次)')
120
+ const descriptor = backend.descriptors[0]
121
+ assert.equal(descriptor.name, INDEX_UNIT)
122
+ assert.equal(descriptor.version, INDEX_VERSION)
123
+ assert.equal(descriptor.layout, 'per-record')
124
+ assert.deepEqual(descriptor.tables, INDEX_TABLES)
125
+ // v1(缺 headHash)/ v2(存 head 不存 refs)都必须读得进来,但会被 `refsShapeOk()`
126
+ // 或指纹检查挡在复用之外 ⇒ 下一轮重建 —— 升级不需要迁移代码。
127
+ assert.deepEqual(descriptor.compatibleVersions, [1, 2])
128
+ assert.equal(INDEX_UNIT, 'knit_index')
129
+ assert.equal(INDEX_VERSION, 3)
130
+ })
131
+
132
+ test('持久化:写进去的索引能被「重启后」的新 store 读回来,且记录里不含正文', async () => {
133
+ const medium = { tables: {} }
134
+ const first = createIndexStore({ backend: fakeBackend(medium) })
135
+ assert.equal(first.persisted, false, '证据到之前不许说自己在用存储')
136
+ assert.equal(first.reason, 'unproven')
137
+ await first.write('/w', { put: [recordOf('a.md'), recordOf('b.md')], del: [] })
138
+ await first.flush()
139
+
140
+ const second = createIndexStore({ backend: fakeBackend(medium) })
141
+ const rows = await second.read('/w')
142
+ assert.equal(second.persisted, true, '读成功之后才有资格说在用存储')
143
+ assert.equal(second.reason, 'ok')
144
+ assert.deepEqual([...rows.keys()].sort(), ['a.md', 'b.md'])
145
+ assert.equal(rows.get('a.md').headHash, recordOf('a.md').headHash)
146
+ // 裁决 A + 修法 ①:正文与原文首部都不进索引,只留抽取结果
147
+ for (const value of rows.values()) {
148
+ assert.equal('body' in value, false, '索引记录里不许出现 body')
149
+ assert.equal('head' in value, false, '索引记录里不许出现原文首部 head(修法 ①)')
150
+ assert.equal(refsShapeOk(value.refs), true, '记录里要带可用的抽取结果 refs')
151
+ }
152
+ })
153
+
154
+ test('隔离:同一个 rel 在两个工作区之间不许串(靠值里的 root 过滤)', async () => {
155
+ const medium = { tables: {} }
156
+ const store = createIndexStore({ backend: fakeBackend(medium) })
157
+ const refsOfOne = { md: [{ raw: 'one.md', line: 1 }], any: [{ raw: 'one.md', line: 1 }] }
158
+ const refsOfTwo = { md: [{ raw: 'two.md', line: 2 }], any: [{ raw: 'two.md', line: 2 }] }
159
+ await store.write('/w/one', { put: [recordOf('a.md', { refs: refsOfOne })], del: [] })
160
+ await store.write('/w/two', { put: [recordOf('a.md', { refs: refsOfTwo })], del: [] })
161
+ await store.flush()
162
+
163
+ const restarted = createIndexStore({ backend: fakeBackend(medium) })
164
+ const one = await restarted.read('/w/one')
165
+ const two = await restarted.read('/w/two')
166
+ assert.deepEqual(one.get('a.md').refs, refsOfOne)
167
+ assert.deepEqual(two.get('a.md').refs, refsOfTwo)
168
+ assert.equal((await restarted.read('/w/three')).size, 0, '没索引过的工作区必须是空的')
169
+ })
170
+
171
+ test('隔离:符号链接工作区与真实路径是同一份索引(canonicalRoot 归一)', async () => {
172
+ const dir = tempDir()
173
+ const real = join(dir, 'real')
174
+ mkdirSync(real)
175
+ const link = join(dir, 'link')
176
+ symlinkSync(real, link)
177
+
178
+ const medium = { tables: {} }
179
+ const store = createIndexStore({ backend: fakeBackend(medium) })
180
+ await store.write(link, { put: [recordOf('a.md')], del: [] })
181
+ await store.flush()
182
+
183
+ // 换个字符串形态(真实路径)去读,必须命中同一份记录 —— 否则索引会时灵时不灵
184
+ const restarted = createIndexStore({ backend: fakeBackend(medium) })
185
+ const viaReal = await restarted.read(real)
186
+ assert.deepEqual([...viaReal.keys()], ['a.md'])
187
+ const viaLink = await restarted.read(link)
188
+ assert.deepEqual([...viaLink.keys()], ['a.md'])
189
+ })
190
+
191
+ test('只写差量:一次 `put` 只碰一个键,取消是 `deleteRecord` 而不是重写整张表', async () => {
192
+ const medium = { tables: {} }
193
+ const backend = fakeBackend(medium)
194
+ const store = createIndexStore({ backend })
195
+ await store.write('/w', { put: [recordOf('a.md'), recordOf('b.md'), recordOf('c.md')], del: [] })
196
+ await store.flush()
197
+ assert.equal(backend.writes.length, 3)
198
+
199
+ const before = backend.writes.length
200
+ await store.write('/w', { put: [recordOf('b.md', { refs: { md: [{ raw: 'c.md', line: 3 }], any: [] } })], del: ['c.md'] })
201
+ await store.flush()
202
+ assert.deepEqual(backend.writes.slice(before), [
203
+ ['put', INDEX_TABLES[0], recordKey('/w', 'b.md')],
204
+ ['del', INDEX_TABLES[0], recordKey('/w', 'c.md')],
205
+ ])
206
+ const rows = await store.read('/w')
207
+ assert.deepEqual([...rows.keys()].sort(), ['a.md', 'b.md'])
208
+ assert.deepEqual(rows.get('b.md').refs.md, [{ raw: 'c.md', line: 3 }])
209
+ })
210
+
211
+ /* ── 3 · 降级:任何失败都不许抛进检索路径 ─────────────── */
212
+
213
+ test('降级:没有存储时功能是空转,但必须说清理由,且绝不抛', async () => {
214
+ for (const backend of [null, undefined, {}, { kv: {} }]) {
215
+ const store = createIndexStore({ backend })
216
+ assert.equal(store.persisted, false)
217
+ assert.equal(store.reason, 'no-storage')
218
+ assert.deepEqual(await store.read('/w'), new Map())
219
+ assert.equal(await store.write('/w', { put: [recordOf('a.md')], del: [] }), false)
220
+ assert.equal(await store.flush(), false)
221
+ }
222
+ // 显式传 null 也要走降级(`apply()` 启动那一刻就是 null)
223
+ assert.equal(createIndexStore(null).reason, 'no-storage')
224
+ })
225
+
226
+ test('降级:unit 开不起来 / 介质损坏 ⇒ 空 Map + 明确 reason,检索照常', async () => {
227
+ const failOpen = createIndexStore({ backend: fakeBackend(undefined, { failOpen: true }) })
228
+ assert.deepEqual(await failOpen.read('/w'), new Map())
229
+ assert.equal(failOpen.persisted, false)
230
+ assert.equal(failOpen.reason, 'open-failed')
231
+ assert.equal(await failOpen.write('/w', { put: [recordOf('a.md')], del: [] }), false)
232
+ assert.equal(failOpen.reason, 'open-failed')
233
+
234
+ const broken = createIndexStore({ backend: fakeBackend(undefined, { brokenLoad: true }) })
235
+ assert.deepEqual(await broken.read('/w'), new Map())
236
+ assert.equal(broken.persisted, false)
237
+ assert.equal(broken.reason, 'read-failed')
238
+ })
239
+
240
+ test('降级:表里混着别的工作区与畸形记录时,只挑得出来的那些,不抛', async () => {
241
+ const medium = {
242
+ tables: {
243
+ [INDEX_TABLES[0]]: {
244
+ k1: recordOf('a.md'),
245
+ k2: { root: '/other', rel: 'a.md' },
246
+ k3: null,
247
+ k4: 'not-an-object',
248
+ k5: { root: '/w', rel: '' },
249
+ k6: { root: '/w', rel: 'b.md', mtimeMs: 1, size: 1 },
250
+ },
251
+ },
252
+ }
253
+ const store = createIndexStore({ backend: fakeBackend(medium) })
254
+ const rows = await store.read('/w')
255
+ assert.deepEqual([...rows.keys()], ['a.md', 'b.md'], '缺 headHash 的记录仍要读进来(由复用判定去拒)')
256
+ })
257
+
258
+ /* ── 4 · 清理:遗留键不许永远留在盘上(清理补丁)────────── */
259
+
260
+ test('清理:键与记录不同源的遗留记录只在下一次写盘时顺手删掉,且绝不碰新格式键', async () => {
261
+ const root = '/w'
262
+ const shortLegacy = relToKey('legacy.md')
263
+ const foreignLegacy = relToKey('outside.md')
264
+ // 反例:长度 > 16 且前 16 个字符恰好都是 hex —— **只看前缀**会把它当成新格式、
265
+ // 于是永远不清;加上「解回来必须等于 row.rel」才判得出来。这里它指向另一个 rel。
266
+ const hexPrefixed = `0123456789abcdef${relToKey('other.md')}`
267
+ assert.equal(keyToRel(hexPrefixed), 'other.md', '夹具自证:它确实不是 trap.md 的键')
268
+ const good = recordKey(root, 'a.md')
269
+
270
+ const medium = {
271
+ tables: {
272
+ [INDEX_TABLES[0]]: {
273
+ [shortLegacy]: recordOf('legacy.md'),
274
+ [foreignLegacy]: recordOf('outside.md', { root: '/other' }),
275
+ [hexPrefixed]: recordOf('trap.md'),
276
+ [good]: recordOf('a.md'),
277
+ },
278
+ },
279
+ }
280
+ const backend = fakeBackend(medium)
281
+ const store = createIndexStore({ backend })
282
+
283
+ // 读**不动盘**:老记录仍然读得进来(由复用判定去拒),只是被记进清理队列。
284
+ const rows = await store.read(root)
285
+ assert.deepEqual([...rows.keys()].sort(), ['a.md', 'legacy.md', 'trap.md'])
286
+ assert.equal(backend.writes.length, 0, '读不许写盘')
287
+ assert.equal(store.cleaned, 0)
288
+
289
+ await store.write(root, { put: [recordOf('b.md')], del: [] })
290
+ await store.flush()
291
+ assert.equal(store.cleaned, 3, '两条短旧键 + 一条 hex 前缀旧键都要清,别的工作区的残留也清')
292
+ assert.deepEqual(
293
+ backend.writes.filter((w) => w[0] === 'del').map((w) => w[2]).sort(),
294
+ [shortLegacy, foreignLegacy, hexPrefixed].sort(),
295
+ )
296
+ assert.ok(!backend.writes.some((w) => w[0] === 'del' && w[2] === good), '新格式键不许被删')
297
+ assert.equal(medium.tables[INDEX_TABLES[0]][shortLegacy], undefined)
298
+ assert.equal(medium.tables[INDEX_TABLES[0]][good].rel, 'a.md', '新格式记录原样保留')
299
+
300
+ // 幂等:下一轮读到的是干净的键集合,再写一次不会重复删也不会重复计数。
301
+ await store.read(root)
302
+ await store.write(root, { put: [recordOf('c.md')], del: [] })
303
+ await store.flush()
304
+ assert.equal(store.cleaned, 3)
305
+ })
306
+
307
+ test('清理有上界:一次写盘最多删 INDEX_CLEAN_PER_WRITE 条,剩下的下一轮接着删', async () => {
308
+ const root = '/w'
309
+ const plants = {}
310
+ const planted = 40
311
+ for (let i = 0; i < planted; i += 1) plants[relToKey(`old${i}.md`)] = recordOf(`old${i}.md`)
312
+ const medium = { tables: { [INDEX_TABLES[0]]: plants } }
313
+ const backend = fakeBackend(medium)
314
+ const store = createIndexStore({ backend })
315
+
316
+ await store.read(root)
317
+ await store.write(root, { put: [recordOf('a.md')], del: [] })
318
+ await store.flush()
319
+ assert.equal(store.cleaned, INDEX_CLEAN_PER_WRITE, '一轮最多清 INDEX_CLEAN_PER_WRITE 条')
320
+
321
+ await store.read(root)
322
+ await store.write(root, { put: [recordOf('b.md')], del: [] })
323
+ await store.flush()
324
+ assert.equal(store.cleaned, planted, '两轮把 40 条清完(32 + 8)')
325
+ assert.equal(
326
+ Object.keys(medium.tables[INDEX_TABLES[0]]).length, 2,
327
+ '盘上只剩两条新格式记录(旧格式不让 loadAll() 永远多付钱)',
328
+ )
329
+ })
330
+
331
+ test('sharedIndexStore:同一个后端对象只造一个 store(DSH 同进程反复加载插件)', async () => {
332
+ const { sharedIndexStore } = await import('../src/host/index-store.js')
333
+ const backend = fakeBackend()
334
+ const first = sharedIndexStore(backend)
335
+ const second = sharedIndexStore(backend)
336
+ assert.ok(first)
337
+ assert.equal(first, second, '第二次加载必须复用同一个 store,否则只有第一次开得成 kv unit')
338
+ assert.equal(sharedIndexStore(null), null)
339
+ })
340
+