project-spec 0.9.1 → 0.10.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.
@@ -1,1276 +0,0 @@
1
- import importlib.util
2
- import json
3
- import re
4
- import subprocess
5
- import tempfile
6
- import unittest
7
- from contextlib import redirect_stderr, redirect_stdout
8
- from io import StringIO
9
- from pathlib import Path
10
-
11
- SPEC = importlib.util.spec_from_file_location('knowledge', Path(__file__).with_name('knowledge.py'))
12
- k = importlib.util.module_from_spec(SPEC)
13
- SPEC.loader.exec_module(k)
14
-
15
-
16
- class Fixture(unittest.TestCase):
17
- def setUp(self):
18
- self.temp = tempfile.TemporaryDirectory()
19
- self.root = Path(self.temp.name)
20
- self.repo = self.root / 'repo'
21
- self.vault = self.root / 'vault'
22
- self.repo.mkdir()
23
- self.vault.mkdir()
24
- (self.repo / 'source.txt').write_text('evidence', encoding='utf-8')
25
- self.note('areas/a.md', 'a', 'area', areas=[])
26
- self.note('00-index.md', 'index', 'index', areas=[], body='[[areas/a]]')
27
- self.note('notes/n.md', 'n', 'note', sources=['source.txt'], body='Привет [[areas/a|область]] `[[missing]]`\n```\n[[missing]]\n```')
28
-
29
- def tearDown(self):
30
- self.temp.cleanup()
31
-
32
- def note(self, path, ident, ptype='note', areas=None, sources=None, body='', status='current', **extra):
33
- meta = {'id': ident, 'title': 'Тест ' + ident, 'type': ptype, 'status': status,
34
- 'areas': ['a'] if areas is None else areas, 'sources': sources or [], 'updated': '2026-11-14'}
35
- if status is None:
36
- del meta['status']
37
- meta.update(extra)
38
- file = self.vault / path
39
- file.parent.mkdir(parents=True, exist_ok=True)
40
- file.write_text('---\n' + ''.join(f'{key}: {json.dumps(value, ensure_ascii=False)}\n' for key, value in meta.items()) + '---\n' + body, encoding='utf-8')
41
-
42
- def run_cli(self, *args):
43
- out, err = StringIO(), StringIO()
44
- with redirect_stdout(out), redirect_stderr(err):
45
- status = k.main([*args, '--repo', str(self.repo), '--vault', str(self.vault)])
46
- return status, out.getvalue(), err.getvalue()
47
-
48
-
49
- class KnowledgeTests(Fixture):
50
- def test_links_and_duplicates(self):
51
- self.assertEqual(self.run_cli('check')[0], 0)
52
- self.note('other/a.md', 'other', 'area', areas=[])
53
- self.note('notes/n.md', 'n', sources=['source.txt'], body='[[a]] [[absent]]')
54
- self.note('notes/duplicate.md', 'n', sources=['source.txt'])
55
- status, _, err = self.run_cli('check')
56
- self.assertEqual(status, 1)
57
- self.assertIn('ambiguous wikilink a', err)
58
- self.assertIn('missing wikilink absent', err)
59
- self.assertIn('duplicate id n', err)
60
-
61
- def test_missing_and_escaping_source(self):
62
- self.note('notes/n.md', 'n', sources=['missing', '../outside', '.env'])
63
- status, _, err = self.run_cli('check')
64
- self.assertEqual(status, 1)
65
- self.assertIn('missing or not a file', err)
66
- self.assertIn('stay inside', err)
67
- self.assertIn('credential', err)
68
- (self.repo / 'escape').symlink_to(self.root, target_is_directory=True)
69
- self.note('notes/n.md', 'n', sources=['escape/secret'])
70
- self.assertIn('outside', self.run_cli('check')[2])
71
-
72
- def test_obsidian_internal_and_trash_notes_are_ignored(self):
73
- self.note('.trash/deleted.md', 'n', sources=['source.txt'])
74
- for name in ('.obsidian/plugins/example/README.md', '.knowledge/internal.md'):
75
- file = self.vault / name
76
- file.parent.mkdir(parents=True, exist_ok=True)
77
- file.write_text('not a vault note', encoding='utf-8')
78
- status, output, errors = self.run_cli('check')
79
- self.assertEqual(status, 0, errors)
80
- self.assertIn('3 notes', output)
81
-
82
- def test_credential_symlink_alias_is_rejected(self):
83
- (self.repo / '.env').write_text('secret', encoding='utf-8')
84
- (self.repo / 'innocent.txt').symlink_to(self.repo / '.env')
85
- self.note('notes/n.md', 'n', sources=['innocent.txt'])
86
- self.assertIn('credential source is forbidden', self.run_cli('check')[2])
87
-
88
- def test_output_symlinks_do_not_overwrite_canonical_note(self):
89
- original_script = k.__file__
90
- fake_script = self.root / 'skill/scripts/knowledge.py'
91
- fake_script.parent.mkdir(parents=True)
92
- (self.root / 'skill/assets').mkdir()
93
- (self.root / 'skill/assets/viewer.html').write_text('__KNOWLEDGE_DATA__', encoding='utf-8')
94
- k.__file__ = str(fake_script)
95
- note = self.vault / 'notes/n.md'
96
- original = note.read_bytes()
97
- try:
98
- (self.vault / '.knowledge').mkdir()
99
- snapshot = self.vault / '.knowledge/sources.json'
100
- snapshot.symlink_to(note)
101
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 1)
102
- self.assertEqual(original, note.read_bytes())
103
- snapshot.unlink()
104
- (self.vault / '.knowledge').rmdir()
105
- (self.vault / '.knowledge').symlink_to(self.vault / 'notes', target_is_directory=True)
106
- with self.assertRaisesRegex(ValueError, 'output path contains symlink'):
107
- self.run_cli('snapshot', '--all')
108
- self.assertEqual(original, note.read_bytes())
109
- finally:
110
- k.__file__ = original_script
111
-
112
- def test_strict_check_and_command_boundaries(self):
113
- status, _, err = self.run_cli('check', '--strict')
114
- self.assertEqual(status, 1)
115
- self.assertIn('unbaselined source', err)
116
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 0)
117
- self.assertEqual(self.run_cli('check', '--strict')[0], 0)
118
- (self.repo / 'source.txt').write_text('changed', encoding='utf-8')
119
- status, _, err = self.run_cli('check')
120
- self.assertEqual(status, 0)
121
- self.assertIn('changed source', err)
122
- status, _, err = self.run_cli('check', '--strict')
123
- self.assertEqual(status, 1)
124
- self.assertIn('changed source', err)
125
- for args in (('serve', '--strict'), ('snapshot', '--all', '--strict'),
126
- ('serve', '--all'), ('serve', '--notes', 'n'), ('build',), ('clean',)):
127
- with self.subTest(args=args), self.assertRaises(SystemExit) as exc:
128
- self.run_cli(*args)
129
- self.assertEqual(exc.exception.code, 2)
130
-
131
- def test_conflict_groups_block_all_commands_but_prose_is_valid(self):
132
- self.note('notes/n.md', 'n', sources=['source.txt'], body='> quoted\n=======\n> still quoted')
133
- self.assertEqual(self.run_cli('check')[0], 0)
134
- path = self.vault / 'notes/n.md'
135
- path.write_text(path.read_text().replace('status: "current"', 'status: "partial"'))
136
- self.assertEqual(self.run_cli('check')[0], 0)
137
- for group in ('<<<<<<< ours\nleft\n=======\nright\n>>>>>>> theirs',
138
- '```\n<<<<<<< ours\nleft\n||||||| base\nbase\n=======\nright\n>>>>>>> theirs\n```'):
139
- self.note('notes/n.md', 'n', sources=['source.txt'], body=group)
140
- for args in (('check',), ('snapshot', '--all')):
141
- with self.subTest(group=group, args=args):
142
- status, _, err = self.run_cli(*args)
143
- self.assertEqual(status, 1)
144
- self.assertIn('unresolved Git conflict markers', err)
145
- self.assertFalse((self.vault / '.knowledge/sources.json').exists())
146
- self.assertFalse((self.vault / 'graph.html').exists())
147
-
148
- def test_real_git_conflict_with_custom_width(self):
149
- def git(*args, check=True):
150
- return subprocess.run(['git', '-C', str(self.root), *args], capture_output=True, text=True, check=check)
151
- # The vault is inside a disposable repository for a real Git merge.
152
- git('init', '-b', 'main')
153
- git('config', 'user.email', 'test@example.invalid')
154
- git('config', 'user.name', 'Test')
155
- (self.root / '.gitattributes').write_text('vault/notes/n.md conflict-marker-size=5\n')
156
- git('add', '.')
157
- git('commit', '-m', 'base')
158
- git('checkout', '-b', 'other')
159
- self.note('notes/n.md', 'n', sources=['source.txt'], body='other change')
160
- git('commit', '-am', 'other')
161
- git('checkout', 'main')
162
- self.note('notes/n.md', 'n', sources=['source.txt'], body='main change')
163
- git('commit', '-am', 'main')
164
- self.assertNotEqual(git('merge', 'other', check=False).returncode, 0)
165
- content = (self.vault / 'notes/n.md').read_text()
166
- self.assertIn('<<<<< HEAD', content)
167
- self.assertIn('=====\n', content)
168
- self.assertIn('>>>>> other', content)
169
- for args in (('check',), ('snapshot', '--all')):
170
- with self.subTest(args=args):
171
- status, _, err = self.run_cli(*args)
172
- self.assertEqual(status, 1)
173
- self.assertIn('unresolved Git conflict markers', err)
174
- self.assertFalse((self.vault / '.knowledge/sources.json').exists())
175
- self.assertFalse((self.vault / 'graph.html').exists())
176
- self.assertFalse(k.has_conflict_markers('> quoted\n=====\n> another quote'))
177
- self.assertFalse(k.has_conflict_markers('<<<<< ours\n=====\n>>>>>> theirs'))
178
-
179
- def test_real_default_conflict_with_operator_content(self):
180
- def git(*args, check=True):
181
- return subprocess.run(['git', '-C', str(self.root), *args], capture_output=True, text=True, check=check)
182
- git('init', '-b', 'main')
183
- git('config', 'user.email', 'test@example.invalid')
184
- git('config', 'user.name', 'Test')
185
- self.note('notes/n.md', 'n', sources=['source.txt'], body='base side')
186
- git('add', '.')
187
- git('commit', '-m', 'base')
188
- git('checkout', '-b', 'other')
189
- self.note('notes/n.md', 'n', sources=['source.txt'], body='<\nright side')
190
- git('commit', '-am', 'other')
191
- git('checkout', 'main')
192
- self.note('notes/n.md', 'n', sources=['source.txt'], body='left side')
193
- git('commit', '-am', 'main')
194
- git('checkout', 'other')
195
- self.assertNotEqual(git('merge', 'main', check=False).returncode, 0)
196
- content = (self.vault / 'notes/n.md').read_text()
197
- self.assertIn('<<<<<<< HEAD\n<\nright side', content)
198
- self.assertTrue(k.has_conflict_markers(content))
199
- for args in (('check',), ('snapshot', '--all')):
200
- status, _, err = self.run_cli(*args)
201
- self.assertEqual(status, 1, args)
202
- self.assertIn('unresolved Git conflict markers', err)
203
- self.assertFalse(k.has_conflict_markers('```\n<\n=\n>\n```'))
204
- self.assertTrue(k.has_conflict_markers('<<<<<<< HEAD\n< nested\n=======\nx\n>>>>>>> main'))
205
-
206
- def test_snapshot_freshness_and_build(self):
207
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 0)
208
- baseline = (self.vault / '.knowledge/sources.json').read_bytes()
209
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 0)
210
- self.assertEqual(baseline, (self.vault / '.knowledge/sources.json').read_bytes())
211
- (self.repo / 'source.txt').write_text('changed', encoding='utf-8')
212
- self.assertIn('changed source', self.run_cli('check')[2])
213
- self.note('notes/n.md', 'n', sources=['source.txt'], body='Привет </script>')
214
- template = Path(k.__file__).parent.parent / 'assets/viewer.html'
215
- # Build is tested with an isolated temporary template, never the shared asset.
216
- original = k.__file__
217
- fake_script = self.root / 'skill/scripts/knowledge.py'
218
- fake_script.parent.mkdir(parents=True)
219
- (self.root / 'skill/assets').mkdir()
220
- (self.root / 'skill/assets/viewer.html').write_text('<script>const x=__KNOWLEDGE_DATA__</script>', encoding='utf-8')
221
- k.__file__ = str(fake_script)
222
- try:
223
- html = k.live_page(self.repo.resolve(), self.vault.resolve())
224
- finally:
225
- k.__file__ = original
226
- self.assertEqual(baseline, (self.vault / '.knowledge/sources.json').read_bytes())
227
- self.assertFalse((self.vault / 'graph.html').exists())
228
- self.assertIn('Привет', html)
229
- self.assertIn('\\u003c/script\\u003e', html)
230
- notes, edges, _, warnings, _ = k.load_vault(self.repo.resolve(), self.vault.resolve())
231
- self.assertTrue(next(n for n in k.graph_of(notes, edges, warnings)['nodes'] if n['id'] == 'n')['stale'])
232
- self.assertFalse((self.vault / '.knowledge/graph.json').exists(), 'nothing is generated into the vault')
233
-
234
-
235
- GAP_BODY = ''.join(f'## {name}\n\ntext\n\n' for name in k.GAP_SECTIONS)
236
-
237
-
238
- def section_body(**texts):
239
- return ''.join(f'## {name}\n\n{texts.get(name, "text")}\n\n' for name in k.GAP_SECTIONS)
240
-
241
-
242
- class GapLayerTests(Fixture):
243
- GAP = {'kind': 'product-gap', 'recheck': 'not-checked', 'decision': 'open'}
244
-
245
- def gap(self, ident='g', body=GAP_BODY, **props):
246
- merged = {**self.GAP, **props}
247
- status = merged.pop('status', None)
248
- self.note(f'gaps/{ident}.md', ident, 'gap', body=body, status=status, **merged)
249
-
250
- def errors(self):
251
- status, _, err = self.run_cli('check')
252
- return status, err
253
-
254
- def assertInvalid(self, fragment):
255
- status, err = self.errors()
256
- self.assertEqual(status, 1, err)
257
- self.assertIn(fragment, err)
258
-
259
- def build(self):
260
- """What the viewer is given for this vault, saved as .knowledge/graph.json so a test can read it. (status, out, err)"""
261
- repo, vault = self.repo.resolve(), self.vault.resolve()
262
- notes, edges, errors, warnings, _ = k.load_vault(repo, vault)
263
- if errors:
264
- return 1, '', '\n'.join(errors)
265
- target = vault / '.knowledge/graph.json'
266
- target.parent.mkdir(exist_ok=True)
267
- target.write_text(json.dumps(k.graph_of(notes, edges, warnings), ensure_ascii=False), encoding='utf-8')
268
- return 0, '', ''
269
-
270
- def test_status_rules_per_type(self):
271
- for kind, status, ok in [('note', 'current', True), ('note', 'planned', False), ('area', 'planned', False),
272
- ('note', 'unverified', False), ('note', 'conflict', False),
273
- ('run', 'planned', True), ('index', 'planned', True), ('run', 'unverified', False)]:
274
- with self.subTest(kind=kind, status=status):
275
- path = self.vault / 'notes/x.md'
276
- path.unlink(missing_ok=True)
277
- self.note('notes/x.md', 'x', kind, sources=['source.txt'], status=status,
278
- areas=[] if kind in {'run', 'index'} else None)
279
- self.assertEqual(self.errors()[0], 0 if ok else 1, self.errors()[1])
280
- self.note('notes/x.md', 'x', sources=['source.txt'], status='unverified')
281
- self.assertInvalid('record it as a gap')
282
-
283
- def test_non_gap_requires_status_and_gap_forbids_it(self):
284
- self.note('notes/x.md', 'x', status=None)
285
- self.assertInvalid('missing properties: status')
286
- (self.vault / 'notes/x.md').unlink()
287
- self.gap(status='current')
288
- self.assertInvalid('gaps use recheck and decision')
289
-
290
- def test_valid_gap_and_plan_pass_strict_check(self):
291
- self.gap()
292
- self.gap('g2', recheck='confirmed', rechecked_by='agent', rechecked_on='2026-11-15', decision='accepted',
293
- decided_by='Ann', decided_on='2026-11-15', priority='high', confidence='medium',
294
- body=section_body(Recheck='ran it', Decision='Ann said yes'))
295
- self.note('plans/p.md', 'p', 'plan', status='planned', gap='g2')
296
- self.run_cli('snapshot', '--all')
297
- status, err = self.errors()
298
- self.assertEqual(status, 0, err)
299
- self.assertEqual(self.run_cli('check', '--strict')[0], 0)
300
-
301
- # gap properties
302
- def test_gap_property_rules(self):
303
- cases = [
304
- ({'kind': 'wish'}, 'kind must be one of'),
305
- ({'recheck': 'maybe'}, 'recheck must be one of'),
306
- ({'decision': 'later'}, 'decision must be one of'),
307
- ({'recheck': 'confirmed'}, 'rechecked_by is required'),
308
- ({'recheck': 'confirmed', 'rechecked_by': 'agent'}, 'rechecked_on is required'),
309
- ({'recheck': 'confirmed', 'rechecked_by': ' ', 'rechecked_on': '2026-11-15'}, 'rechecked_by must name'),
310
- ({'recheck': 'confirmed', 'rechecked_by': 'agent', 'rechecked_on': '2026-13-45'}, 'rechecked_on'),
311
- ({'rechecked_by': 'Ann'}, "absent while recheck is 'not-checked'"),
312
- ({'rechecked_on': '2026-11-15'}, "absent while recheck is 'not-checked'"),
313
- ({'decision': 'accepted'}, 'decided_by is required'),
314
- ({'decision': 'rejected', 'decided_by': 'Ann'}, 'decided_on is required'),
315
- ({'decision': 'deferred', 'decided_by': 'agent', 'decided_on': '2026-11-15'}, 'agent may not decide'),
316
- ({'decision': 'accepted', 'decided_by': 'Ann', 'decided_on': 'yesterday'}, 'decided_on must be'),
317
- ({'decided_by': 'Ann'}, "absent while decision is 'open'"),
318
- ({'decided_on': '2026-11-15'}, "absent while decision is 'open'"),
319
- ({'decision': 'duplicate'}, 'duplicate_of is required'),
320
- ({'decision': 'duplicate', 'duplicate_of': 'g'}, 'different gap'),
321
- ({'decision': 'duplicate', 'duplicate_of': 'nope'}, 'not the id of an existing gap'),
322
- ({'decision': 'duplicate', 'duplicate_of': 'n'}, 'not the id of an existing gap'),
323
- ({'duplicate_of': 'other'}, "only valid when decision is 'duplicate'"),
324
- ({'priority': 3}, 'priority must be a string'),
325
- ]
326
- self.gap('other')
327
- for props, fragment in cases:
328
- with self.subTest(props=props):
329
- self.gap(**props)
330
- self.assertInvalid(fragment)
331
- (self.vault / 'gaps/g.md').unlink()
332
- self.assertEqual(self.errors()[0], 0)
333
-
334
- def test_duplicate_done_and_agent_bookkeeping_are_valid(self):
335
- self.gap('other')
336
- self.gap('g', decision='duplicate', duplicate_of='other')
337
- self.gap('h', decision='done', body=section_body(Decision='Closed: src/x implements it'))
338
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
339
-
340
- def test_gap_only_properties_rejected_on_other_pages(self):
341
- self.note('notes/x.md', 'x', sources=['source.txt'], kind='conflict')
342
- self.assertInvalid('kind is only valid on gap pages')
343
- self.note('notes/x.md', 'x', sources=['source.txt'], gap='g')
344
- self.assertInvalid('gap is only valid on plan pages')
345
-
346
- # plans
347
- def test_plan_rules(self):
348
- self.gap('open-gap')
349
- self.gap('ok-gap', decision='done', body=section_body(Decision='seen in code'))
350
- for props, fragment in [({'gap': 'open-gap'}, "has decision 'open'"), ({'gap': 'missing'}, 'not the id of an existing gap'),
351
- ({'gap': 'n'}, 'not the id of an existing gap'), ({'gap': ' '}, 'plan requires gap')]:
352
- with self.subTest(props=props):
353
- self.note('plans/p.md', 'p', 'plan', status='planned', **props)
354
- self.assertInvalid(fragment)
355
- self.note('plans/p.md', 'p', 'plan', status='planned', gap='ok-gap', areas=[])
356
- self.assertInvalid('plan requires an area')
357
- self.note('plans/p.md', 'p', 'plan', status='unverified', gap='ok-gap')
358
- self.assertInvalid('status must be one of')
359
- self.note('plans/p.md', 'p', 'plan', status='current', gap='ok-gap')
360
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
361
-
362
- # body rules
363
- def test_spec_pages_cannot_link_to_gap_layer(self):
364
- self.gap()
365
- self.note('notes/n.md', 'n', sources=['source.txt'], body='see [[gaps/g]]')
366
- self.assertInvalid('link from the gap to this page instead')
367
- self.note('notes/n.md', 'n', sources=['source.txt'])
368
- self.note('areas/a.md', 'a', 'area', areas=[], body='[[g]]')
369
- self.assertInvalid('spec pages must not link to the gap layer')
370
- self.note('areas/a.md', 'a', 'area', areas=[])
371
- self.gap(body=GAP_BODY + 'link to [[notes/n]]')
372
- self.note('00-index.md', 'index', 'index', areas=[], body='[[areas/a]] [[gaps/g]]')
373
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
374
-
375
- def test_plan_link_from_note_is_rejected(self):
376
- self.gap(decision='accepted', decided_by='Ann', decided_on='2026-11-15', body=section_body())
377
- self.note('plans/p.md', 'p', 'plan', status='planned', gap='g')
378
- self.note('notes/n.md', 'n', sources=['source.txt'], body='[[plans/p]]')
379
- self.assertInvalid('spec pages must not link')
380
-
381
- def test_gap_sections(self):
382
- names = k.GAP_SECTIONS
383
- self.gap(body=''.join(f'## {n}\ntext\n' for n in names[:-1]))
384
- self.assertInvalid("exactly one '## Decision' section (found 0)")
385
- self.gap(body=GAP_BODY + '## Gap\nagain\n')
386
- self.assertInvalid("exactly one '## Gap' section (found 2)")
387
- self.gap(body=GAP_BODY.replace('## Evidence', '### Evidence'))
388
- self.assertInvalid("'## Evidence' section (found 0)")
389
- # headings in code fences do not count, and order is free
390
- shuffled = ''.join(f'## {n}\ntext\n' for n in reversed(names))
391
- self.gap(body=shuffled + '```\n## Decision\n```\n')
392
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
393
- self.gap(body=''.join(f'## {n}\ntext\n' for n in names[:-1]) + '```\n## Decision\n```\n')
394
- self.assertInvalid("(found 0)")
395
-
396
- def test_decision_and_recheck_sections_must_not_be_empty(self):
397
- self.gap(decision='rejected', decided_by='Ann', decided_on='2026-11-15', body=section_body(Decision=' '))
398
- self.assertInvalid('Decision section must say who decided')
399
- self.gap(recheck='not-reproduced', rechecked_by='Ann', rechecked_on='2026-11-15', body=section_body(Recheck=''))
400
- self.assertInvalid('Recheck section must say what was checked')
401
- self.gap(body=section_body(Decision='', Recheck=''))
402
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
403
- self.gap(recheck='confirmed', rechecked_by='agent', rechecked_on='2026-11-15', body=section_body(Recheck='```\ncmd\n```'))
404
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
405
-
406
- def test_sources_optional_on_gap_and_plan_but_required_on_current_note(self):
407
- self.gap()
408
- self.assertEqual(self.errors()[0], 0)
409
- self.note('notes/x.md', 'x', sources=[])
410
- self.assertInvalid('current note requires sources')
411
-
412
- # derived state and generated files
413
- def test_gap_state_table(self):
414
- base = {'kind': 'product-gap'}
415
- checked = {'recheck': 'confirmed', 'rechecked_by': 'agent', 'rechecked_on': '2026-11-15'}
416
- self.assertEqual(k.gap_state({**base, 'recheck': 'not-checked', 'decision': 'open'}), 'needs-recheck')
417
- for recheck in ('confirmed', 'not-reproduced'):
418
- self.assertEqual(k.gap_state({**base, 'recheck': recheck, 'decision': 'open'}), 'needs-decision')
419
- for decision in ('accepted', 'rejected', 'deferred', 'done', 'duplicate'):
420
- for recheck in k.RECHECKS:
421
- self.assertEqual(k.gap_state({'recheck': recheck, 'decision': decision}), decision)
422
-
423
- def test_viewer_data_carries_the_gap_fields(self):
424
- self.gap('open')
425
- self.gap('acc', recheck='confirmed', rechecked_by='Bob', rechecked_on='2026-11-15', decision='accepted',
426
- decided_by='Ann', decided_on='2026-11-16', body=section_body())
427
- self.note('plans/p.md', 'p', 'plan', status='planned', gap='acc')
428
- self.assertEqual(self.build()[0], 0)
429
- nodes = {n['id']: n for n in json.loads((self.vault / '.knowledge/graph.json').read_text())['nodes']}
430
- fields = {'kind', 'recheck', 'recheckedBy', 'recheckedOn', 'decision', 'decidedBy', 'decidedOn', 'state', 'gap', 'layer'}
431
- self.assertTrue(all(fields <= n.keys() for n in nodes.values()))
432
- self.assertEqual((nodes['open']['state'], nodes['open']['status'], nodes['open']['layer']), ('needs-recheck', '', 'gap'))
433
- self.assertEqual((nodes['acc']['state'], nodes['acc']['recheckedBy'], nodes['acc']['decidedOn']), ('accepted', 'Bob', '2026-11-16'))
434
- self.assertEqual((nodes['p']['gap'], nodes['p']['layer'], nodes['p']['status']), ('acc', 'gap', 'planned'))
435
- self.assertEqual((nodes['n']['layer'], nodes['n']['state'], nodes['n']['kind']), ('spec', '', ''))
436
- self.assertEqual(nodes['index']['layer'], 'nav')
437
-
438
- def test_cited_files_are_repository_text_files_only(self):
439
- (self.repo / 'docs').mkdir()
440
- (self.repo / 'docs/plan.md').write_text('# План\n\n| a | b |\n', encoding='utf-8')
441
- (self.repo / 'logo.bin').write_bytes(b'\x00\x01')
442
- (self.repo / 'latin.txt').write_bytes(b'caf\xe9')
443
- (self.repo / '.env').write_text('SECRET=1', encoding='utf-8')
444
- (self.root / 'outside.txt').write_text('outside', encoding='utf-8')
445
- (self.repo / 'escape.txt').symlink_to(self.root / 'outside.txt')
446
- (self.repo / 'big.txt').write_text('line\n' * 100_000, encoding='utf-8')
447
- self.vault.rename(self.repo / 'vault')
448
- self.vault = self.repo / 'vault'
449
- self.note('notes/n.md', 'n', sources=['source.txt'], body=(
450
- '[plan](../../docs/plan.md#L3) [logo](../../logo.bin) [latin](../../latin.txt) [env](../../.env) '
451
- '[out](../../../outside.txt) [esc](../../escape.txt) [big](../../big.txt) [area](../areas/a.md) '
452
- '[web](https://example.com/x.md) [gone](../../missing.md) `[code](../../docs/hidden.md)`'))
453
- repo, vault = self.repo.resolve(), self.vault.resolve()
454
- notes, _, errors, _, _ = k.load_vault(repo, vault)
455
- self.assertEqual(errors, [])
456
- files, skipped = k.cited_files(repo, vault, notes)
457
- self.assertEqual(sorted(files), ['big.txt', 'docs/plan.md', 'source.txt'])
458
- self.assertEqual(files['docs/plan.md'], {'text': '# План\n\n| a | b |\n', 'truncated': False})
459
- self.assertEqual(files['source.txt']['text'], 'evidence')
460
- self.assertTrue(files['big.txt']['truncated'])
461
- self.assertLessEqual(len(files['big.txt']['text']), k.FILE_LIMIT)
462
- self.assertEqual(skipped, [])
463
- original = k.FILES_LIMIT
464
- k.FILES_LIMIT = 100
465
- try:
466
- files, skipped = k.cited_files(repo, vault, notes)
467
- finally:
468
- k.FILES_LIMIT = original
469
- self.assertEqual((sorted(files), skipped), (['docs/plan.md', 'source.txt'], ['big.txt']))
470
-
471
- def serve(self):
472
- import threading
473
- server = k.make_server(self.repo.resolve(), self.vault.resolve(), 0)
474
- thread = threading.Thread(target=server.serve_forever, daemon=True)
475
- thread.start()
476
- self.addCleanup(lambda: (server.shutdown(), server.server_close(), thread.join(5)))
477
- return server.server_address[1]
478
-
479
- def fetch(self, port, path='/', host=None):
480
- import http.client
481
- connection = http.client.HTTPConnection('127.0.0.1', port, timeout=10)
482
- self.addCleanup(connection.close)
483
- connection.request('GET', path, headers={'Host': host} if host else {})
484
- response = connection.getresponse()
485
- return response.status, response.read().decode('utf-8'), dict(response.getheaders())
486
-
487
- def test_serve_shows_the_vault_as_it_is_on_disk(self):
488
- port = self.serve()
489
- status, page, headers = self.fetch(port)
490
- self.assertEqual(status, 200)
491
- self.assertEqual(headers['Content-Type'], 'text/html; charset=utf-8')
492
- self.assertEqual(headers['Cache-Control'], 'no-store')
493
- data = json.loads(re.search(r'<script id="knowledge-data" type="application/json">\s*(.*?)\s*</script>', page, re.S).group(1))
494
- self.assertTrue(data['live'])
495
- self.assertEqual(data['files']['source.txt']['text'], 'evidence')
496
- self.assertEqual(data['vaultPath'], '../vault')
497
- self.assertEqual((data['history'], data['pending']), ([], []))
498
- self.assertEqual({n['id'] for n in data['nodes']}, {'a', 'index', 'n'})
499
- # nothing was written, and a change on disk shows on the next load without a build
500
- self.assertFalse((self.vault / 'graph.html').exists() or (self.vault / '.knowledge').exists())
501
- (self.repo / 'source.txt').write_text('changed </script>', encoding='utf-8')
502
- self.note('notes/new.md', 'new', sources=['source.txt'])
503
- page = self.fetch(port, '/index.html?x=1')[1]
504
- self.assertIn('"id": "new"', page)
505
- self.assertIn('changed \\u003c/script\\u003e', page)
506
- # only the page itself, and only when addressed as this machine
507
- self.assertEqual(self.fetch(port, '/notes/n.md')[0], 404)
508
- self.assertEqual(self.fetch(port, '/../repo/source.txt')[0], 404)
509
- self.assertEqual(self.fetch(port, '/', host='evil.example')[0], 403)
510
- self.assertEqual(self.fetch(port, '/', host='localhost:1')[0], 200)
511
- # a broken vault is explained instead of failing
512
- self.note('notes/bad.md', 'bad', sources=['source.txt'], body='[[<absent>]]')
513
- status, page, _ = self.fetch(port)
514
- self.assertEqual(status, 200)
515
- self.assertIn('The spec has 1 error', page)
516
- self.assertIn('missing wikilink &lt;absent&gt;', page)
517
- self.assertNotIn('knowledge-data', page)
518
-
519
- def git(self, *args):
520
- return subprocess.run(['git', '-C', str(self.repo), '-c', 'user.name=T', '-c', 'user.email=t@example.com', '-c', 'commit.gpgsign=false', *args],
521
- check=True, capture_output=True, text=True).stdout
522
-
523
- def test_history_and_pending_pages_come_from_git(self):
524
- k._history_cache.clear()
525
- repo, vault = self.repo.resolve(), self.vault.resolve()
526
- self.assertEqual((k.vault_history(repo, vault), k.vault_pending(repo, vault)), ([], []), 'a vault outside the repository has no history')
527
- self.vault.rename(self.repo / 'vault')
528
- self.vault = self.repo / 'vault'
529
- vault = self.vault.resolve()
530
- self.assertEqual((k.vault_history(repo, vault), k.vault_pending(repo, vault)), ([], []), 'nor has a folder that is not a Git work tree')
531
- self.git('init', '-q')
532
- self.note('notes/n.md', 'n', sources=['source.txt'], summary='Old "line".')
533
- (self.vault / 'AS-BUILT.md').write_text('generated', encoding='utf-8')
534
- (self.vault / '.knowledge').mkdir()
535
- (self.vault / '.knowledge/x.md').write_text('internal', encoding='utf-8')
536
- self.git('add', '-A')
537
- self.git('commit', '-q', '-m', 'First pass')
538
- self.note('notes/n.md', 'n', sources=['source.txt'], summary='New line.', body='changed text')
539
- self.note('areas/a.md', 'a', 'area', areas=[], body='only the text changed')
540
- self.note('notes/extra.md', 'extra', sources=['source.txt'], summary='Brand new.')
541
- (self.vault / '00-index.md').unlink()
542
- (self.repo / 'source.txt').write_text('code changed too', encoding='utf-8')
543
- self.git('add', '-A')
544
- self.git('commit', '-q', '-m', 'Second \x01 pass')
545
- history = k.vault_history(repo, vault)
546
- self.assertEqual([(c['subject'], c['more'], len(c['sha'])) for c in history], [('Second pass', 0, 40), ('First pass', 0, 40)])
547
- self.assertRegex(history[0]['date'], r'^\d{4}-\d{2}-\d{2}$')
548
- self.assertEqual(history[0]['pages'], [
549
- {'path': '00-index.md', 'status': 'removed'},
550
- {'path': 'areas/a.md', 'status': 'changed'},
551
- {'path': 'notes/extra.md', 'status': 'added'},
552
- {'path': 'notes/n.md', 'status': 'changed', 'was': 'Old "line".', 'now': 'New line.'},
553
- ])
554
- # generated files, internal files and application files are not history of the spec
555
- self.assertEqual(sorted(p['path'] for p in history[1]['pages']), ['00-index.md', 'areas/a.md', 'notes/n.md'])
556
- self.assertIs(k.vault_history(repo, vault), history, 'one Git call per HEAD')
557
- self.assertEqual(k.vault_pending(repo, vault), [])
558
- self.note('notes/n.md', 'n', sources=['source.txt'], summary='Edited again.')
559
- self.note('gaps/fresh.md', 'fresh', 'gap', sources=[], kind='product-gap', recheck='not-checked', decision='open', status=None)
560
- (self.vault / 'notes/extra.md').unlink()
561
- (self.vault / 'GAPS.md').write_text('generated', encoding='utf-8')
562
- self.assertEqual(k.vault_pending(repo, vault), [
563
- {'path': 'gaps/fresh.md', 'status': 'added'}, {'path': 'notes/extra.md', 'status': 'removed'}, {'path': 'notes/n.md', 'status': 'changed'}])
564
- # long commits are cut, and the cut is counted
565
- original = k.HISTORY_PAGES
566
- k.HISTORY_PAGES = 2
567
- k._history_cache.clear()
568
- try:
569
- cut = k.vault_history(repo, vault)[0]
570
- finally:
571
- k.HISTORY_PAGES = original
572
- k._history_cache.clear()
573
- self.assertEqual((len(cut['pages']), cut['more']), (2, 2))
574
- # the same from a repository folder below the top of the work tree
575
- inner = self.repo / 'app'
576
- inner.mkdir()
577
- (self.repo / 'vault').rename(inner / 'vault')
578
- self.git('add', '-A')
579
- self.git('commit', '-q', '-m', 'Moved')
580
- moved = k.vault_history(inner.resolve(), (inner / 'vault').resolve())
581
- self.assertEqual(moved[0]['subject'], 'Moved')
582
- self.assertIn({'path': 'areas/a.md', 'status': 'added'}, moved[0]['pages'])
583
- self.assertEqual(k.vault_pending(inner.resolve(), (inner / 'vault').resolve()), [])
584
- k._history_cache.clear()
585
-
586
- def built(self, *args):
587
- out = self.root / 'site/spec.html'
588
- status, printed, err = self.run_cli('build', '--out', str(out), *args)
589
- data = json.loads(re.search(r'<script id="knowledge-data" type="application/json">\s*(.*?)\s*</script>', out.read_text(encoding='utf-8'), re.S).group(1)) if out.is_file() else None
590
- return status, printed, err, data
591
-
592
- def refused(self, *args):
593
- """What a command that stops with a usage error says."""
594
- err = StringIO()
595
- with self.assertRaises(SystemExit), redirect_stdout(StringIO()), redirect_stderr(err):
596
- k.main([*args, '--repo', str(self.repo), '--vault', str(self.vault)])
597
- return err.getvalue()
598
-
599
- def test_build_writes_one_page_for_a_server_without_source_text(self):
600
- status, printed, err, data = self.built()
601
- self.assertEqual((status, err), (0, 'WARNING: notes/n.md: unbaselined source source.txt\n'))
602
- self.assertIn('build: wrote ' + str(self.root / 'site/spec.html'), printed)
603
- self.assertIn('their text is not included', printed)
604
- self.assertEqual((data['built'], data.get('live'), data['files'], data['sourceUrl'], data['commit']), (True, None, {}, '', ''))
605
- self.assertEqual({n['id'] for n in data['nodes']}, {'a', 'index', 'n'})
606
- self.assertNotIn('evidence', (self.root / 'site/spec.html').read_text(encoding='utf-8'))
607
- # nothing appeared in the vault, and no temporary file was left beside the page
608
- self.assertFalse((self.vault / '.knowledge').exists())
609
- self.assertEqual([f.name for f in (self.root / 'site').iterdir()], ['spec.html'])
610
- # the text of cited files only when asked for, with a warning about who may see it
611
- status, printed, _, data = self.built('--with-sources')
612
- self.assertEqual((status, data['files']['source.txt']['text']), (0, 'evidence'))
613
- self.assertIn('the text of 1 cited source files is inside the file', printed)
614
-
615
- def test_build_can_run_where_part_of_the_repository_is_missing(self):
616
- self.note('notes/m.md', 'm', sources=['source.txt', 'Dockerfile'])
617
- status, _, err, data = self.built()
618
- self.assertEqual((status, data), (1, None))
619
- self.assertIn('source is missing or not a file', err)
620
- status, printed, err, data = self.built('--allow-missing-sources')
621
- self.assertEqual(status, 0)
622
- self.assertIn('build: 1 cited files are not in this folder, so nobody compared them with the pages: Dockerfile', printed)
623
- self.assertNotIn('Dockerfile', err)
624
- self.note('notes/o.md', 'o', sources=['Dockerfile'])
625
- data = self.built('--allow-missing-sources')[3]
626
- pages = {n['id']: (n['sources'], n['stale']) for n in data['nodes']}
627
- self.assertEqual(pages['o'], (['Dockerfile'], False), 'a file nobody could read does not mark its page as changed')
628
- self.assertEqual(pages['m'], (['source.txt', 'Dockerfile'], True), 'source.txt has no accepted fingerprint')
629
- (self.vault / 'notes/o.md').unlink()
630
- # a folder where a file should be is still an error, and so is the same vault for check
631
- (self.repo / 'Dockerfile').mkdir()
632
- self.assertEqual(self.built('--allow-missing-sources')[0], 1)
633
- (self.repo / 'Dockerfile').rmdir()
634
- self.assertEqual(self.run_cli('check')[0], 1)
635
- self.assertIn('only for build', self.refused('check', '--allow-missing-sources'))
636
-
637
- def test_build_and_serve_work_where_git_is_not_installed(self):
638
- import os
639
- from unittest import mock
640
- k._history_cache.clear()
641
- self.vault.rename(self.repo / 'vault')
642
- self.vault = self.repo / 'vault'
643
- self.git('init', '-q')
644
- self.git('add', '-A')
645
- self.git('commit', '-q', '-m', 'First')
646
- empty = self.root / 'no-tools'
647
- empty.mkdir()
648
- with mock.patch.dict(os.environ, {'PATH': str(empty)}):
649
- status, printed, err, data = self.built()
650
- self.assertEqual((status, data['commit'], data['history'], data['pending']), (0, '', [], []), err)
651
- self.assertNotIn('commit ', printed)
652
- self.assertIn('knowledge-data', k.live_page(self.repo.resolve(), self.vault.resolve()))
653
- self.assertIn('--ignore-dirty needs --repo to be a Git work tree', self.refused('check', '--ignore-dirty'))
654
- k._history_cache.clear()
655
- self.assertEqual([c['subject'] for c in self.built()[3]['history']], ['First'], 'with Git back, the history is too')
656
-
657
- def test_build_links_cited_files_to_the_commit_it_was_built_from(self):
658
- k._history_cache.clear()
659
- self.vault.rename(self.repo / 'vault')
660
- self.vault = self.repo / 'vault'
661
- out = str(self.root / 'site/spec.html')
662
- self.assertIn('--repo is not a Git work tree with a commit', self.refused('build', '--out', out, '--source-url', 'https://github.com/o/r/blob/{commit}'))
663
- self.git('init', '-q')
664
- self.git('add', '-A')
665
- self.git('commit', '-q', '-m', 'First')
666
- head = self.git('rev-parse', 'HEAD').strip()
667
- status, printed, _, data = self.built('--source-url', 'https://github.com/o/r/blob/{commit}/')
668
- self.assertEqual((status, data['commit'], data['sourceUrl']), (0, head, 'https://github.com/o/r/blob/' + head))
669
- self.assertIn('commit ' + head[:7], printed)
670
- self.assertEqual([c['subject'] for c in data['history']], ['First'])
671
- self.assertNotIn('shallow clone', printed)
672
- for bad in ('javascript:alert(1)', 'github.com/o/r', 'https://', 'https://x.example/a b'):
673
- with self.subTest(url=bad):
674
- self.assertIn('--source-url must be an http(s) address', self.refused('build', '--out', out, '--source-url', bad))
675
-
676
- def test_build_refuses_a_broken_vault_and_a_file_inside_the_vault(self):
677
- for out in (self.vault / 'spec.html', self.vault / 'notes/deep/spec.html', self.root):
678
- with self.subTest(out=out):
679
- self.assertIn('--out must be a file outside the vault', self.refused('build', '--out', str(out)))
680
- self.assertFalse((self.vault / 'spec.html').exists() or (self.vault / 'notes/deep').exists())
681
- for args in (['build'], ['check', '--out', 'x.html'], ['serve', '--with-sources'], ['check', '--source-url', 'https://x.example']):
682
- with self.subTest(args=args):
683
- self.assertIn('build', self.refused(*args))
684
- self.note('notes/bad.md', 'bad', sources=['source.txt'], body='[[<absent>]]')
685
- status, _, err, data = self.built()
686
- self.assertEqual((status, data), (1, None))
687
- self.assertIn('missing wikilink <absent>', err)
688
-
689
- def test_history_of_a_shallow_clone_leaves_out_the_commit_without_parents(self):
690
- k._history_cache.clear()
691
- self.vault.rename(self.repo / 'vault')
692
- self.vault = self.repo / 'vault'
693
- self.git('init', '-q')
694
- self.git('add', '-A')
695
- self.git('commit', '-q', '-m', 'First')
696
- self.note('notes/n.md', 'n', sources=['source.txt'], summary='Second line.')
697
- self.git('commit', '-q', '-am', 'Second')
698
- self.note('notes/n.md', 'n', sources=['source.txt'], summary='Third line.')
699
- self.git('commit', '-q', '-am', 'Third')
700
- clone = self.root / 'clone'
701
- subprocess.run(['git', 'clone', '-q', '--depth', '2', self.repo.resolve().as_uri(), str(clone)], check=True, capture_output=True)
702
- history = k.vault_history(clone.resolve(), (clone / 'vault').resolve())
703
- self.assertEqual([(c['subject'], [p['status'] for p in c['pages']]) for c in history], [('Third', ['changed'])],
704
- 'Second is where the clone stops: Git would show every page as added there')
705
- self.repo, self.vault = clone, clone / 'vault'
706
- self.assertIn('build: this is a shallow clone', self.built()[1])
707
-
708
- def test_serve_finds_the_single_vault_and_asks_when_unsure(self):
709
- with self.assertRaisesRegex(ValueError, 'no vault found under knowledge/; pass --vault'):
710
- k.find_vault(self.repo)
711
- (self.repo / 'knowledge/one').mkdir(parents=True)
712
- (self.repo / 'knowledge/one/00-index.md').write_text('x', encoding='utf-8')
713
- self.assertEqual(k.find_vault(self.repo), self.repo / 'knowledge/one')
714
- (self.repo / 'knowledge/two').mkdir()
715
- (self.repo / 'knowledge/two/00-index.md').write_text('x', encoding='utf-8')
716
- with self.assertRaisesRegex(ValueError, r'several vaults found \(knowledge/one, knowledge/two\); pass --vault'):
717
- k.find_vault(self.repo)
718
- # every command finds the vault the same way
719
- with self.assertRaisesRegex(ValueError, 'several vaults found'):
720
- k.main(['check', '--repo', str(self.repo)])
721
- (self.repo / 'knowledge/two/00-index.md').unlink()
722
- (self.repo / 'knowledge/one/00-index.md').write_text('---\nid: "index"\ntitle: "T"\ntype: "index"\nstatus: "current"\nareas: []\nsources: []\nupdated: "2026-11-14"\n---\n', encoding='utf-8')
723
- out = StringIO()
724
- with redirect_stdout(out), redirect_stderr(StringIO()):
725
- self.assertEqual(k.main(['check', '--repo', str(self.repo)]), 0)
726
- self.assertIn('check: 1 notes', out.getvalue())
727
-
728
- def test_a_feature_too_big_for_one_page_has_parts(self):
729
- self.note('notes/chats.md', 'chats', sources=['source.txt'], body='Parts: [[notes/group-chats|group chats]].')
730
- self.note('notes/group-chats.md', 'group-chats', sources=['source.txt'], parent='chats')
731
- status, out, err = self.run_cli('check')
732
- self.assertEqual(status, 0, err)
733
- notes, edges, errors, _, _ = k.load_vault(self.repo.resolve(), self.vault.resolve())
734
- self.assertIn(('chats', 'group-chats'), edges)
735
- self.assertEqual(k.node_of(next(n for n in notes if n['meta']['id'] == 'group-chats'))['parent'], 'chats')
736
- cases = (
737
- (dict(parent='chats'), 'Parts: none listed.', 'notes/group-chats.md: its feature notes/chats.md does not link to it'),
738
- (dict(parent='nobody'), None, 'parent nobody is not the id of an existing note'),
739
- (dict(parent='a'), None, 'parent a is not the id of an existing note'),
740
- (dict(parent='group-chats'), None, 'parent must name a different note'),
741
- (dict(parent=''), None, 'parent is only valid on note pages and names the feature note'),
742
- )
743
- for extra, parent_body, message in cases:
744
- with self.subTest(message=message):
745
- self.note('notes/chats.md', 'chats', sources=['source.txt'], body=parent_body or 'Parts: [[notes/group-chats|group chats]].')
746
- self.note('notes/group-chats.md', 'group-chats', sources=['source.txt'], **extra)
747
- status, _, err = self.run_cli('check')
748
- self.assertEqual(status, 1)
749
- self.assertIn(message, err)
750
- # three levels and no more, and a part stays in its feature's area
751
- self.note('notes/chats.md', 'chats', sources=['source.txt'], body='[[notes/group-chats|group chats]] [[notes/renaming|renaming]]')
752
- self.note('notes/group-chats.md', 'group-chats', sources=['source.txt'], parent='chats', body='[[notes/renaming|renaming]]')
753
- self.note('notes/renaming.md', 'renaming', sources=['source.txt'], parent='group-chats')
754
- self.assertIn('parent group-chats is itself a part of chats; a part belongs to a feature, not to another part', self.run_cli('check')[2])
755
- self.note('areas/b.md', 'b', 'area', areas=[])
756
- self.note('notes/renaming.md', 'renaming', sources=['source.txt'], parent='chats', areas=['b'])
757
- self.assertIn('parent chats is in another area', self.run_cli('check')[2])
758
- self.note('areas/a.md', 'a', 'area', areas=[], parent='chats')
759
- self.assertIn('parent is only valid on note pages', self.run_cli('check')[2])
760
-
761
- def test_area_pages_are_maps_without_tables_or_links_into_notes(self):
762
- table = '| Screen | What it does |\n| --- | --- |\n| Profile | Edits the name. [[notes/n|Profile]] |\n'
763
- for body in (table, '| a | b |\n|:-|-:|\n| 1 | 2 |', 'a | b\n--- | ---\n1 | 2', '| one column |\n| --- |\n| x |'):
764
- with self.subTest(body=body):
765
- self.note('areas/a.md', 'a', 'area', areas=[], body=body)
766
- self.assertInvalid('an area page is a map and holds no table (1 found)')
767
- for link in ('[[notes/n#Profile]]', '[[n#Profile|the profile part]]', '[[notes/n#^block]]', '| [[notes/n#Profile\\|alias]] |'):
768
- with self.subTest(link=link):
769
- self.note('areas/a.md', 'a', 'area', areas=[], body=f'See {link}.')
770
- self.assertInvalid('an area page links whole notes, not a part of one')
771
- self.note('areas/a.md', 'a', 'area', areas=[], body='See [[notes/n#Profile|it]].')
772
- self.assertIn('not a part of one (notes/n#Profile);', self.errors()[1])
773
- # what stays allowed: whole notes, tables in code, lists, and tables or heading links on other pages
774
- self.note('areas/a.md', 'a', 'area', areas=[], body='- [[notes/n|The rule]]: one line about it.\n\n```\n| a | b |\n| - | - |\n```\n\nA line with a | pipe.')
775
- self.note('notes/n.md', 'n', sources=['source.txt'], body=table + '\nSee [[areas/a#Coverage]].')
776
- self.note('notes/m.md', 'm', sources=['source.txt'], body='Part of [[notes/n#Profile]].')
777
- self.gap(body=section_body() + '\nSee [[notes/n#Profile]].')
778
- status, err = self.errors()
779
- self.assertEqual(status, 0, err)
780
-
781
- def test_a_rule_number_is_used_once(self):
782
- rules = '## Business rules\n\n| ID | Rule |\n| --- | --- |\n| BR-PROFILE-01 | A name has 1 to 120 characters. |\n| BR-PROFILE-02 | The email cannot be changed here. |\n'
783
- self.note('notes/n.md', 'n', sources=['source.txt'], body=rules)
784
- self.note('notes/m.md', 'm', sources=['source.txt'], body='| ID | Rule |\n| --- | --- |\n| BR-TEAM-01 | Only owners rename a team. |\n\nSee BR-PROFILE-01.\n\n```\n| BR-PROFILE-01 | an example |\n```')
785
- status, err = self.errors()
786
- self.assertEqual(status, 0, err)
787
- # the same number on another page, and twice on one page
788
- self.note('notes/m.md', 'm', sources=['source.txt'], body='| ID | Rule |\n| --- | --- |\n| BR-PROFILE-02 | Something else. |')
789
- self.assertInvalid('notes/n.md: rule BR-PROFILE-02 is numbered twice (also on notes/m.md)')
790
- self.note('notes/m.md', 'm', sources=['source.txt'], body='')
791
- self.note('notes/n.md', 'n', sources=['source.txt'], body=rules + '| BR-PROFILE-01 | A second rule with the first number. |')
792
- self.assertInvalid('notes/n.md: rule BR-PROFILE-01 is numbered twice (on this page)')
793
-
794
- def test_run_pages_cannot_link_to_vault_pages(self):
795
- for body in ('[[notes/n]]', 'see [[n|the note]] and [[areas/a]]', '![[notes/n]]', '[n](../notes/n.md)', '[n]: ../00-index.md'):
796
- with self.subTest(body=body):
797
- self.note('runs/r.md', 'r', 'run', areas=[], body=body)
798
- self.assertInvalid('run pages are history, not part of the map')
799
- self.note('runs/r.md', 'r', 'run', areas=[], body='see [[n]] and [[areas/a]]')
800
- self.assertIn('(2 links)', self.errors()[1])
801
- self.note('runs/r.md', 'r', 'run', areas=[], body='Updated `notes/n` and `[[areas/a]]`; read [source](../../repo/source.txt) and https://example.com.')
802
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
803
- self.note('00-index.md', 'index', 'index', areas=[], body='[[areas/a]] [[runs/r]]')
804
- self.assertEqual(self.build()[0], 0)
805
- graph = json.loads((self.vault / '.knowledge/graph.json').read_text())
806
- self.assertEqual([e for e in graph['edges'] if e['source'] == 'r'], [])
807
-
808
- # defects
809
- def test_fence_detection_follows_commonmark(self):
810
- bad = '[[missing]]'
811
- for body in (f'```npm test``` passed.\n{bad}', f'```\ncode\n```js\n{bad}\n```\n{bad}', f'~~~\n~~~ x\n{bad}\n~~~\n{bad}'):
812
- with self.subTest(body=body):
813
- self.note('notes/n.md', 'n', sources=['source.txt'], body=body)
814
- self.assertInvalid('missing wikilink missing')
815
- for body in (f'```js\n{bad}\n```', f'~~~ weird `x`\n{bad}\n~~~', f'````\n```\n{bad}\n````', f'```\n{bad}'):
816
- with self.subTest(body=body):
817
- self.note('notes/n.md', 'n', sources=['source.txt'], body=body)
818
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
819
- self.assertEqual(k.prose('```npm test``` passed. [[a]]'), ' passed. [[a]]')
820
-
821
- def test_escaped_pipe_wikilink_in_table(self):
822
- self.note('notes/n.md', 'n', sources=['source.txt'], body='| a |\n| - |\n| [[areas/a\\|Alias]] |\n| [[a\\|Alias]] [[a|B]] [[a\\|x]] |')
823
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
824
- self.note('notes/n.md', 'n', sources=['source.txt'], body='| [[nope\\|Alias]] |')
825
- self.assertInvalid('missing wikilink nope')
826
-
827
- def test_utf8_bom_is_accepted(self):
828
- file = self.vault / 'notes/n.md'
829
- file.write_bytes(b'\xef\xbb\xbf' + file.read_bytes())
830
- status, err = self.errors()
831
- self.assertEqual(status, 0, err)
832
-
833
- def test_credential_denylist(self):
834
- for name in ('.npmrc', '.netrc', '.htpasswd', 'id_rsa', 'id_ed25519', 'id_ecdsa', 'x/terraform.tfstate',
835
- 'terraform.tfstate.backup', 'service-account.json', 'service-account-prod.json', 'deep/dir/.NPMRC'):
836
- with self.subTest(name=name):
837
- self.assertTrue(k.credential_path(name))
838
- for name in ('id_rsa.pub', 'id_ed25519.pub', 'service-accounts.md', 'service_account.py', 'npmrc.md', 'src/service-account.ts'):
839
- with self.subTest(name=name):
840
- self.assertFalse(k.credential_path(name))
841
- (self.repo / '.npmrc').write_text('//registry:_authToken=x')
842
- self.note('notes/n.md', 'n', sources=['.npmrc'])
843
- self.assertInvalid('credential source is forbidden')
844
-
845
- def test_crlf_only_difference_is_reported_as_line_endings(self):
846
- source = self.repo / 'source.txt'
847
- source.write_bytes(b'one\ntwo\n')
848
- self.run_cli('snapshot', '--all')
849
- source.write_bytes(b'one\r\ntwo\r\n')
850
- status, _, err = self.run_cli('check')
851
- self.assertEqual(status, 0)
852
- self.assertIn('line endings differ in source source.txt', err)
853
- self.assertNotIn('changed source', err)
854
- self.assertEqual(self.run_cli('check', '--strict')[0], 1)
855
- source.write_bytes(b'one\r\nthree\r\n')
856
- self.assertIn('changed source', self.run_cli('check')[2])
857
- # and the reverse direction
858
- source.write_bytes(b'one\r\ntwo\r\n')
859
- self.run_cli('snapshot', '--all')
860
- source.write_bytes(b'one\ntwo\n')
861
- self.assertIn('line endings differ', self.run_cli('check')[2])
862
-
863
- def test_generated_writes_are_atomic(self):
864
- self.run_cli('snapshot', '--all')
865
- snapshot = self.vault / '.knowledge/sources.json'
866
- before = snapshot.read_bytes()
867
- real = k.os.replace
868
- calls = []
869
-
870
- def failing(src, dst):
871
- calls.append(dst)
872
- raise OSError('disk full')
873
- k.os.replace = failing
874
- try:
875
- (self.repo / 'source2.txt').write_text('x')
876
- self.note('notes/m.md', 'm', sources=['source2.txt'])
877
- with self.assertRaises(OSError):
878
- self.run_cli('snapshot', '--all')
879
- finally:
880
- k.os.replace = real
881
- self.assertTrue(calls)
882
- self.assertEqual(before, snapshot.read_bytes())
883
- self.assertEqual([p.name for p in snapshot.parent.iterdir()], ['sources.json'])
884
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 0)
885
- self.assertEqual([p.name for p in snapshot.parent.iterdir()], ['sources.json'])
886
- self.assertEqual(oct(snapshot.stat().st_mode & 0o777), oct(0o666 & ~self.umask()))
887
-
888
- def test_missing_source_severity_follows_gap_decision(self):
889
- live = [{}, {'decision': 'accepted', 'decided_by': 'Ann', 'decided_on': '2026-11-15'},
890
- {'decision': 'deferred', 'decided_by': 'Ann', 'decided_on': '2026-11-15'}]
891
- closed = [{'decision': 'done'}, {'decision': 'rejected', 'decided_by': 'Ann', 'decided_on': '2026-11-15'},
892
- {'decision': 'duplicate', 'duplicate_of': 'other'}]
893
- self.gap('other')
894
- for props in live + closed:
895
- with self.subTest(props=props):
896
- self.gap('g', sources=['gone.txt'], body=section_body(), **props)
897
- status, err = self.errors()
898
- if props in live:
899
- self.assertEqual(status, 1)
900
- self.assertIn('missing or not a file', err)
901
- else:
902
- self.assertEqual(status, 0, err)
903
- self.assertIn('WARNING: gaps/g.md: missing source gone.txt', err)
904
- (self.vault / 'gaps/g.md').unlink()
905
- self.gap('done', decision='done', body=section_body())
906
- self.gap('acc', decision='accepted', decided_by='Ann', decided_on='2026-11-15', body=section_body())
907
- self.note('plans/p1.md', 'p1', 'plan', status='planned', gap='done', sources=['gone.txt'])
908
- status, err = self.errors()
909
- self.assertEqual(status, 0, err)
910
- self.assertIn('plans/p1.md: missing source gone.txt', err)
911
- self.note('plans/p2.md', 'p2', 'plan', status='planned', gap='acc', sources=['gone.txt'])
912
- self.assertInvalid('p2.md: gone.txt: source is missing')
913
-
914
- def test_edges_include_gap_and_plan_links_and_plan_gap(self):
915
- self.gap('g', decision='accepted', decided_by='Ann', decided_on='2026-11-15', body=section_body() + '[[notes/n]]')
916
- self.note('plans/p.md', 'p', 'plan', status='planned', gap='g', body='nothing linked')
917
- self.build()
918
- graph = json.loads((self.vault / '.knowledge/graph.json').read_text())
919
- edges = {(e['source'], e['target']) for e in graph['edges']}
920
- self.assertIn(('g', 'n'), edges)
921
- self.assertIn(('p', 'g'), edges)
922
-
923
- def test_priority_confidence_duplicate_of_nodes_and_recheck_staleness(self):
924
- self.gap('other')
925
- self.gap('dup', decision='duplicate', duplicate_of='other')
926
- self.gap('c', recheck='confirmed', rechecked_by='Bob', rechecked_on='2026-11-15', priority='high',
927
- confidence='low', sources=['source.txt'], body=section_body())
928
- self.gap('nc', sources=['source.txt'])
929
- self.run_cli('snapshot', '--all')
930
- self.build()
931
- nodes = {n['id']: n for n in json.loads((self.vault / '.knowledge/graph.json').read_text())['nodes']}
932
- self.assertEqual((nodes['c']['priority'], nodes['c']['confidence'], nodes['c']['duplicateOf']), ('high', 'low', ''))
933
- self.assertEqual((nodes['dup']['duplicateOf'], nodes['n']['priority'], nodes['n']['duplicateOf']), ('other', '', ''))
934
- self.assertFalse(nodes['c']['recheckOutdated'])
935
- (self.repo / 'source.txt').write_text('different')
936
- self.build()
937
- nodes = {n['id']: n for n in json.loads((self.vault / '.knowledge/graph.json').read_text())['nodes']}
938
- self.assertTrue(nodes['c']['recheckOutdated']) # rechecked, and its source changed since
939
- self.assertFalse(nodes['nc']['recheckOutdated']) # never rechecked: nothing to flag
940
- # stored fields are never rewritten
941
- self.assertIn('recheck: "confirmed"', (self.vault / 'gaps/c.md').read_text())
942
-
943
- # review round 1
944
- def test_embeds_are_resolved_and_cannot_reach_the_gap_layer(self):
945
- self.gap(decision='done', body=section_body())
946
- self.note('notes/n.md', 'n', sources=['source.txt'], body='![[gaps/g]]')
947
- self.assertInvalid('spec pages must not link to the gap layer (embed gaps/g)')
948
- self.note('notes/n.md', 'n', sources=['source.txt'], body='![[nowhere]]')
949
- self.assertInvalid('missing embed nowhere')
950
- self.note('notes/n.md', 'n', sources=['source.txt'], body='![[pic.png]]')
951
- self.assertInvalid('missing embed pic.png')
952
- (self.vault / 'attachments').mkdir()
953
- (self.vault / 'attachments/pic.png').write_bytes(b'png')
954
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
955
- self.note('notes/n.md', 'n', sources=['source.txt'], body='![[areas/a]] ![[a#x|alias]]')
956
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
957
-
958
- def test_markdown_links_to_the_gap_layer_are_rejected_from_spec_pages(self):
959
- self.gap(decision='done', body=section_body())
960
- for body in ('[x](../gaps/g.md)', '[x](<../gaps/g.md#top>)', '[x](../gaps/%67.md)', '[queue](../GAPS.md)',
961
- '[queue](../gaps.md)', '[x]: ../gaps/g.md'):
962
- with self.subTest(body=body):
963
- self.note('notes/n.md', 'n', sources=['source.txt'], body=body)
964
- self.assertInvalid('spec pages must not link to the gap layer')
965
- self.note('areas/a.md', 'a', 'area', areas=[], body='[x](../gaps/g.md)')
966
- self.assertInvalid('spec pages must not link to the gap layer')
967
- self.note('areas/a.md', 'a', 'area', areas=[])
968
- for body in ('[ok](../source.txt) [web](https://example.invalid/gaps/g.md) `[c](../gaps/g.md)`', '```\n[c](../gaps/g.md)\n```'):
969
- self.note('notes/n.md', 'n', sources=['source.txt'], body=body)
970
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
971
- self.gap(body=section_body() + '[n](../notes/n.md)', decision='done')
972
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
973
-
974
- def test_links_in_title_or_summary_of_spec_pages_are_rejected(self):
975
- for key, value in (('title', 'See [[gaps/g]]'), ('summary', 'See [q](GAPS.md)'), ('summary', '![[gaps/g]]')):
976
- with self.subTest(key=key):
977
- self.note('notes/n.md', 'n', sources=['source.txt'], **{key: value})
978
- self.assertInvalid(f'{key} of a spec page must not contain links')
979
- self.note('areas/a.md', 'a', 'area', areas=[], summary='[[g]]')
980
- self.assertInvalid('summary of a spec page must not contain links')
981
- self.note('areas/a.md', 'a', 'area', areas=[], summary='Plain [brackets] and (parens).')
982
- self.note('notes/n.md', 'n', sources=['source.txt'])
983
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
984
-
985
- def test_control_characters_in_properties_are_rejected(self):
986
- for char in ('\r', '\n', '\t', '\x00', '\x7f', '\x85', '
', '
'):
987
- for key, value in (('title', 'a' + char + 'b'), ('summary', 'a' + char + 'b'), ('tags', ['x' + char]), ('sources', ['source.txt' + char])):
988
- with self.subTest(char=repr(char), key=key):
989
- self.note('notes/n.md', 'n', **{key: value, **({} if key == 'sources' else {'sources': ['source.txt']})})
990
- # Raw U+0085/U+2028/U+2029 break the one-property-per-line frontmatter before validation.
991
- self.assertInvalid('ERROR: notes/n.md')
992
- for char in ('\\u0085', '\\u2028', '\\u2029'): # JSON escapes survive line splitting, so validation must catch them
993
- self.note('notes/n.md', 'n', sources=['source.txt'])
994
- path = self.vault / 'notes/n.md'
995
- path.write_text(path.read_text().replace('title: "Тест n"', 'title: "a' + char + 'b"'))
996
- self.assertInvalid('title must not contain control characters')
997
- self.gap(rechecked_by='agent, 2026-11-15)\r\r## accepted', recheck='confirmed', rechecked_on='2026-11-15', body=section_body())
998
- self.assertInvalid('rechecked_by must not contain control characters')
999
-
1000
- def test_outdated_recheck(self):
1001
- for props, fragment in (({'recheck': 'outdated'}, 'rechecked_by is required'),
1002
- ({'recheck': 'outdated', 'rechecked_by': 'agent', 'rechecked_on': '2026-11-15'}, None)):
1003
- with self.subTest(props=props):
1004
- self.gap(body=section_body(), **props)
1005
- if fragment:
1006
- self.assertInvalid(fragment)
1007
- else:
1008
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
1009
- self.gap(recheck='outdated', rechecked_by='agent', rechecked_on='2026-11-15', body=section_body(Recheck=' '))
1010
- self.assertInvalid('Recheck section must say what was checked')
1011
- self.assertEqual(k.gap_state({'decision': 'open', 'recheck': 'outdated'}), 'needs-recheck')
1012
- self.assertEqual(k.gap_state({'decision': 'accepted', 'recheck': 'outdated'}), 'accepted')
1013
- self.gap(recheck='outdated', rechecked_by='Bob', rechecked_on='2026-11-15', body=section_body(), sources=['source.txt'])
1014
- self.build()
1015
- node = next(n for n in json.loads((self.vault / '.knowledge/graph.json').read_text())['nodes'] if n['id'] == 'g')
1016
- self.assertEqual((node['state'], node['recheckOutdated']), ('needs-recheck', True))
1017
-
1018
- def test_recheck_outdated_flag_ignores_line_endings_and_non_gaps(self):
1019
- source = self.repo / 'source.txt'
1020
- source.write_bytes(b'a\nb\n')
1021
- self.gap(recheck='confirmed', rechecked_by='Bob', rechecked_on='2026-11-15', body=section_body(), sources=['source.txt'])
1022
- self.run_cli('snapshot', '--all')
1023
- flags = lambda: {n['id']: n['recheckOutdated'] for n in json.loads((self.vault / '.knowledge/graph.json').read_text())['nodes']}
1024
- self.build()
1025
- self.assertEqual(set(flags().values()), {False})
1026
- source.write_bytes(b'a\r\nb\r\n')
1027
- self.build()
1028
- self.assertFalse(flags()['g'])
1029
- source.write_bytes(b'different')
1030
- self.build()
1031
- self.assertTrue(flags()['g'])
1032
- self.assertFalse(flags()['n'])
1033
-
1034
- def test_priority_and_confidence_only_on_gaps_and_plans(self):
1035
- for key in ('priority', 'confidence'):
1036
- with self.subTest(key=key):
1037
- self.note('notes/n.md', 'n', sources=['source.txt'], **{key: 'high'})
1038
- self.assertInvalid(f'{key} is only valid on gap and plan pages')
1039
- self.note('areas/a.md', 'a', 'area', areas=[], **{key: 'high'})
1040
- self.assertInvalid(f'{key} is only valid on gap and plan pages')
1041
- self.note('areas/a.md', 'a', 'area', areas=[])
1042
- self.note('notes/n.md', 'n', sources=['source.txt'])
1043
- self.gap('done-gap', decision='done', body=section_body())
1044
- self.note('plans/p.md', 'p', 'plan', status='planned', gap='done-gap', priority='high', confidence='low')
1045
- self.gap('g2', priority='high', confidence='low')
1046
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
1047
-
1048
- def test_credential_denylist_folds_lookalikes_and_covers_more_names(self):
1049
- for name in ('.ſſh/id_rſa', '.SSH/id_rsa', 'a/.git/config', '.git', '.git-credentials', 'credentials.json',
1050
- 'client_secret_123.json', 'secrets.yaml', 'secrets.json', '.envrc', '.pgpass', '.pypirc', '_netrc',
1051
- '.vault-token', '.terraformrc', '.kube/config', 'home/.docker/config.json',
1052
- 'application_default_credentials.json', 'id_dsa', 'x.jks', 'x.ppk', 'x.p8', 'prod.tfvars', 'a.auto.tfvars', 'x.gpg'):
1053
- with self.subTest(name=name):
1054
- self.assertTrue(k.credential_path(name))
1055
- for name in ('config', '.kube/other', 'docker/config.json', 'secret.md', 'credentials.md', 'src/.github/x.yml', 'client.json'):
1056
- with self.subTest(name=name):
1057
- self.assertFalse(k.credential_path(name))
1058
- (self.repo / '.ssh').mkdir()
1059
- (self.repo / '.ssh/id_rsa').write_text('private')
1060
- self.note('notes/n.md', 'n', sources=['.ſſh/id_rſa'])
1061
- self.assertInvalid('credential source is forbidden')
1062
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 1)
1063
- self.assertFalse((self.vault / '.knowledge/sources.json').exists())
1064
-
1065
- # review round 2
1066
- def test_embed_of_a_dotted_note_name_resolves_as_a_note(self):
1067
- self.note('notes/v1.2-rule.md', 'dotted', sources=['source.txt'])
1068
- self.note('notes/n.md', 'n', sources=['source.txt'], body='![[notes/v1.2-rule]] ![[v1.2-rule]] [[notes/v1.2-rule]]')
1069
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
1070
- self.note('notes/n.md', 'n', sources=['source.txt'], body='![[notes/v9.9-missing]]')
1071
- self.assertInvalid('missing embed notes/v9.9-missing')
1072
- (self.vault / 'pic.v2.png').write_bytes(b'x')
1073
- self.note('notes/n.md', 'n', sources=['source.txt'], body='![[pic.v2.png]]')
1074
- self.assertEqual(self.errors()[0], 0, self.errors()[1])
1075
-
1076
- def test_wikilink_pattern_is_linear_on_unbalanced_brackets(self):
1077
- import time
1078
- started = time.perf_counter()
1079
- self.assertEqual(k.LINK.findall('[[' * 20000), [])
1080
- self.assertEqual(k.LINK.findall('![[x]] [[y|z]] [[a]]'), [('!', 'x'), ('', 'y|z'), ('', 'a')])
1081
- self.assertLess(time.perf_counter() - started, 1.0)
1082
-
1083
- # first real sync: recheck wording, cascading errors, dirty sources, partial snapshots
1084
- def test_failed_page_is_a_link_target_and_causes_no_follow_on_errors(self):
1085
- # One broken page of each kind: a note, an area (by id), a gap (by id).
1086
- self.note('notes/broken.md', 'broken', status=None)
1087
- self.note('areas/ba.md', 'ba', 'area', areas=[], updated='2026-13-45')
1088
- self.gap('fg', recheck='bogus')
1089
- self.gap('dup', decision='duplicate', duplicate_of='fg')
1090
- self.note('plans/p.md', 'p', 'plan', status='planned', gap='fg')
1091
- self.note('notes/m.md', 'm', areas=['a', 'ba'], sources=['source.txt'],
1092
- body='[[broken]] [[notes/broken]] ![[broken]] [[nowhere]]')
1093
- status, err = self.errors()
1094
- self.assertEqual(status, 1, err)
1095
- errors = [line for line in err.splitlines() if line.startswith('ERROR:')]
1096
- self.assertEqual(len(errors), 4, err) # three broken pages plus the one genuinely missing link
1097
- self.assertIn('notes/m.md: missing wikilink nowhere', err)
1098
- for noise in ('missing wikilink broken', 'missing embed broken', 'unknown area', 'is not the id of an existing gap', 'has decision'):
1099
- self.assertNotIn(noise, err)
1100
- self.assertIn('check: failed, 4 errors on 4 pages', err)
1101
-
1102
- def test_snapshot_notes_needs_only_the_selected_pages_valid(self):
1103
- self.note('notes/broken.md', 'broken', status=None)
1104
- self.note('notes/m.md', 'm', sources=['source.txt'], body='[[broken]]')
1105
- self.assertEqual(self.run_cli('check')[0], 1)
1106
- status, out, err = self.run_cli('snapshot', '--notes', 'n')
1107
- self.assertEqual(status, 0, err)
1108
- self.assertIn('1 errors on 1 other pages do not block this snapshot', err)
1109
- baseline = json.loads((self.vault / '.knowledge/sources.json').read_text())
1110
- self.assertEqual(sorted(baseline), ['n'])
1111
- # A selected page that links to the broken page is refused; the link only looks fine because the error is not repeated.
1112
- status, _, err = self.run_cli('snapshot', '--notes', 'n', 'm')
1113
- self.assertEqual(status, 1)
1114
- self.assertIn('notes/m.md: link broken names a page that failed validation', err)
1115
- self.assertEqual(sorted(json.loads((self.vault / '.knowledge/sources.json').read_text())), ['n'])
1116
- # The selected page itself must be valid, including one whose own frontmatter fails.
1117
- before = (self.vault / '.knowledge/sources.json').read_bytes()
1118
- self.note('notes/m.md', 'm', sources=['source.txt'], body='[[nowhere]]')
1119
- self.assertEqual(self.run_cli('snapshot', '--notes', 'm')[0], 1)
1120
- self.assertEqual(self.run_cli('snapshot', '--notes', 'broken')[0], 1)
1121
- self.assertEqual(self.run_cli('snapshot', '--notes', 'absent')[0], 1)
1122
- self.assertEqual(before, (self.vault / '.knowledge/sources.json').read_bytes())
1123
- # Whole-vault commands still demand a fully valid vault.
1124
- self.note('notes/m.md', 'm', sources=['source.txt'])
1125
- for args in (('snapshot', '--all'), ('check',)):
1126
- self.assertEqual(self.run_cli(*args)[0], 1, args)
1127
- # A damaged baseline is vault-wide, so it blocks even a partial snapshot.
1128
- (self.vault / 'notes/broken.md').unlink()
1129
- (self.vault / '.knowledge/sources.json').write_text('[]')
1130
- self.assertEqual(self.run_cli('snapshot', '--notes', 'n')[0], 1)
1131
-
1132
- def git_in(self, top, *args):
1133
- return subprocess.run(['git', '-C', str(top), *args], capture_output=True, text=True, check=True).stdout
1134
-
1135
- def init_git(self, top):
1136
- self.git_in(top, 'init', '-b', 'main')
1137
- self.git_in(top, 'config', 'user.email', 'test@example.invalid')
1138
- self.git_in(top, 'config', 'user.name', 'Test')
1139
- self.git_in(top, 'add', '.')
1140
- self.git_in(top, 'commit', '-m', 'base')
1141
-
1142
- def test_ignore_dirty_forgives_only_uncommitted_changes(self):
1143
- self.init_git(self.repo)
1144
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 0)
1145
- (self.repo / 'source.txt').write_text('edited', encoding='utf-8')
1146
- status, _, err = self.run_cli('check', '--strict')
1147
- self.assertEqual(status, 1)
1148
- self.assertNotIn('not counted', err)
1149
- status, out, err = self.run_cli('check', '--strict', '--ignore-dirty')
1150
- self.assertEqual(status, 0, err)
1151
- self.assertIn('WARNING: notes/n.md: changed source source.txt (uncommitted change, not counted)', err)
1152
- self.assertIn('(1 uncommitted, not counted)', out)
1153
- self.git_in(self.repo, 'add', 'source.txt') # staged still counts as uncommitted
1154
- self.assertEqual(self.run_cli('check', '--strict', '--ignore-dirty')[0], 0)
1155
- self.git_in(self.repo, 'commit', '-m', 'edit') # committed changes are real
1156
- status, _, err = self.run_cli('check', '--strict', '--ignore-dirty')
1157
- self.assertEqual(status, 1)
1158
- self.assertIn('changed source source.txt\n', err + '\n')
1159
- self.assertNotIn('not counted', err)
1160
- # Untracked sources and a repo that is a subdirectory of the work tree.
1161
- (self.repo / 'new.txt').write_text('one', encoding='utf-8')
1162
- self.note('notes/u.md', 'u', sources=['new.txt'])
1163
- self.assertEqual(self.run_cli('snapshot', '--notes', 'u')[0], 0)
1164
- (self.repo / 'new.txt').write_text('two', encoding='utf-8')
1165
- self.assertEqual(self.run_cli('check', '--strict', '--ignore-dirty')[0], 1) # n is still committed-changed
1166
- # An untracked file has no HEAD blob to equal the accepted bytes, so it is never forgiven.
1167
- self.assertIn('changed source new.txt\n', self.run_cli('check', '--ignore-dirty')[2])
1168
-
1169
- def test_markdown_links_to_failed_pages_keep_their_type(self):
1170
- self.note('gaps/g/broken.md', 'gb', 'gap', status=None) # fails, but declares itself a gap
1171
- self.note('notes/broken.md', 'broken', status=None)
1172
- self.note('notes/u.md', 'u', sources=['source.txt'], body='[x](../gaps/g/broken.md)')
1173
- self.note('notes/m.md', 'm', sources=['source.txt'], body='[x](broken.md)')
1174
- self.note('runs/r.md', 'r', 'run', areas=[], body='[x](../notes/broken.md)')
1175
- status, err = self.errors()
1176
- self.assertIn('notes/u.md: spec pages must not link to the gap layer (../gaps/g/broken.md)', err)
1177
- self.assertIn('runs/r.md: run pages are history', err)
1178
- self.assertNotIn('ERROR: notes/m.md', err) # a failed note is a fine target
1179
- self.assertEqual(self.run_cli('snapshot', '--notes', 'u')[0], 1)
1180
- # An unknown type cannot be judged: no error of its own, but it blocks the snapshot of the linking page.
1181
- self.note('notes/unk.md', 'unk', status=None)
1182
- (self.vault / 'notes/unk.md').write_text('---\nid: "unk"\n---\n')
1183
- self.note('notes/m.md', 'm', sources=['source.txt'], body='[x](unk.md)')
1184
- self.assertNotIn('ERROR: notes/m.md', self.errors()[1])
1185
- status, _, err = self.run_cli('snapshot', '--notes', 'm')
1186
- self.assertEqual(status, 1)
1187
- self.assertIn('notes/m.md: link unk.md names a page that failed validation', err)
1188
-
1189
- def test_plan_gap_and_duplicate_of_cascade_only_for_failed_gaps(self):
1190
- self.gap('fg', recheck='bogus') # fails, still a gap
1191
- self.note('plans/p.md', 'p', 'plan', status='planned', gap='fg', sources=['source.txt'])
1192
- self.gap('dup', decision='duplicate', duplicate_of='fg')
1193
- self.note('notes/broken.md', 'broken', status=None)
1194
- self.note('plans/q.md', 'q', 'plan', status='planned', gap='broken', sources=['source.txt'])
1195
- self.gap('dup2', decision='duplicate', duplicate_of='broken')
1196
- status, err = self.errors()
1197
- self.assertIn('plans/q.md: gap broken is not the id of an existing gap', err)
1198
- self.assertIn('duplicate_of broken is not the id of an existing gap', err)
1199
- self.assertNotIn('ERROR: plans/p.md', err)
1200
- self.assertNotIn('ERROR: gaps/dup.md', err)
1201
- for ident in ('p', 'dup'):
1202
- with self.subTest(ident=ident):
1203
- status, _, err = self.run_cli('snapshot', '--notes', ident)
1204
- self.assertEqual(status, 1)
1205
- self.assertIn('names a page that failed validation', err)
1206
-
1207
- def test_ignore_dirty_does_not_hide_a_committed_unreviewed_change(self):
1208
- self.init_git(self.repo)
1209
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 0)
1210
- (self.repo / 'source.txt').write_text('committed change', encoding='utf-8')
1211
- self.git_in(self.repo, 'commit', '-am', 'edit')
1212
- self.assertEqual(self.run_cli('check', '--strict', '--ignore-dirty')[0], 1)
1213
- (self.repo / 'source.txt').write_text('committed change\n', encoding='utf-8') # whitespace edit on top
1214
- status, _, err = self.run_cli('check', '--strict', '--ignore-dirty')
1215
- self.assertEqual(status, 1, err)
1216
- self.assertNotIn('not counted', err)
1217
- # Line-ending variants of the accepted bytes still count as uncommitted-only drift.
1218
- self.git_in(self.repo, 'checkout', 'source.txt')
1219
- (self.repo / 'source.txt').write_bytes(b'one\ntwo\n')
1220
- self.git_in(self.repo, 'commit', '-am', 'back')
1221
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 0)
1222
- (self.repo / 'source.txt').write_bytes(b'one\r\ntwo\r\n')
1223
- status, _, err = self.run_cli('check', '--strict', '--ignore-dirty')
1224
- self.assertEqual(status, 0, err)
1225
- self.assertIn('line endings differ in source source.txt (uncommitted change, not counted)', err)
1226
-
1227
- def test_cascade_suppression_hides_only_the_missing_error(self):
1228
- self.note('notes/broken.md', 'broken', status=None)
1229
- self.note('gaps/g/broken.md', 'gb', 'gap', status=None) # a failed page that still says it is a gap
1230
- self.note('notes/other/broken.md', 'broken2', status=None)
1231
- self.note('notes/w.md', 'w', sources=['source.txt'], body='[[broken]]') # two failed pages share the name
1232
- self.note('notes/v.md', 'v', sources=['source.txt'], body='[[gaps/g/broken]]')
1233
- self.note('notes/x.md', 'x', areas=['n'], sources=['source.txt']) # n is a note, not an area
1234
- status, err = self.errors()
1235
- self.assertEqual(status, 1, err)
1236
- self.assertIn('notes/w.md: ambiguous wikilink broken', err)
1237
- self.assertIn('notes/v.md: spec pages must not link to the gap layer', err)
1238
- self.assertIn('notes/x.md: unknown area n', err)
1239
-
1240
- def test_snapshot_notes_refuses_a_page_with_a_bad_area_or_wrong_type_target(self):
1241
- self.note('areas/ba.md', 'ba', 'area', areas=[], updated='2026-13-45')
1242
- self.note('notes/m.md', 'm', areas=['a', 'ba'], sources=['source.txt'])
1243
- before = (self.vault / '.knowledge/sources.json').read_bytes() if (self.vault / '.knowledge/sources.json').exists() else None
1244
- status, _, err = self.run_cli('snapshot', '--notes', 'm')
1245
- self.assertEqual(status, 1)
1246
- self.assertIn('notes/m.md: area ba names a page that failed validation', err)
1247
- self.assertEqual(before, (self.vault / '.knowledge/sources.json').read_bytes() if (self.vault / '.knowledge/sources.json').exists() else None)
1248
- self.note('notes/m.md', 'm', areas=['n'], sources=['source.txt'])
1249
- status, _, err = self.run_cli('snapshot', '--notes', 'm')
1250
- self.assertEqual(status, 1)
1251
- self.assertIn('notes/m.md: unknown area n', err)
1252
-
1253
- def test_ignore_dirty_in_a_subdirectory_of_the_work_tree_and_outside_git(self):
1254
- with self.assertRaises(SystemExit) as exc, redirect_stderr(StringIO()):
1255
- self.run_cli('check', '--ignore-dirty')
1256
- self.assertEqual(exc.exception.code, 2)
1257
- self.assertEqual(self.run_cli('snapshot', '--all')[0], 0)
1258
- self.init_git(self.root)
1259
- (self.repo / 'source.txt').write_text('edited', encoding='utf-8')
1260
- status, _, err = self.run_cli('check', '--strict', '--ignore-dirty')
1261
- self.assertEqual(status, 0, err)
1262
- self.assertIn('(uncommitted change, not counted)', err)
1263
- for args in (('serve', '--ignore-dirty'), ('snapshot', '--all', '--ignore-dirty')):
1264
- with self.subTest(args=args), self.assertRaises(SystemExit) as exc, redirect_stderr(StringIO()):
1265
- self.run_cli(*args)
1266
- self.assertEqual(exc.exception.code, 2)
1267
-
1268
- @staticmethod
1269
- def umask():
1270
- mask = k.os.umask(0)
1271
- k.os.umask(mask)
1272
- return mask
1273
-
1274
-
1275
- if __name__ == '__main__':
1276
- unittest.main()