project-spec 0.0.0-stage → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +375 -2
- package/bin/project-spec.mjs +281 -0
- package/package.json +40 -4
- package/skills/project-knowledge/LICENSE +21 -0
- package/skills/project-knowledge/SKILL.md +139 -0
- package/skills/project-knowledge/agents/openai.yaml +4 -0
- package/skills/project-knowledge/assets/viewer.html +3657 -0
- package/skills/project-knowledge/references/audit.md +52 -0
- package/skills/project-knowledge/references/format.md +217 -0
- package/skills/project-knowledge/references/gaps.md +159 -0
- package/skills/project-knowledge/references/investigate.md +33 -0
- package/skills/project-knowledge/references/merge.md +70 -0
- package/skills/project-knowledge/references/migrate.md +56 -0
- package/skills/project-knowledge/references/sync.md +102 -0
- package/skills/project-knowledge/scripts/knowledge.py +992 -0
- package/skills/project-knowledge/scripts/maintain.py +545 -0
- package/skills/project-knowledge/scripts/merge.py +182 -0
- package/skills/project-knowledge/scripts/test_knowledge.py +1201 -0
- package/skills/project-knowledge/scripts/test_maintain.py +864 -0
- package/skills/project-knowledge/scripts/test_merge.py +165 -0
- package/skills/spec-change/LICENSE +21 -0
- package/skills/spec-change/SKILL.md +63 -0
- package/skills/spec-change/agents/openai.yaml +4 -0
- package/skills/spec-change/references/gaps.md +159 -0
- package/skills/spec-change/references/plan.md +40 -0
|
@@ -0,0 +1,864 @@
|
|
|
1
|
+
import hashlib
|
|
2
|
+
import json
|
|
3
|
+
import os
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
import shutil
|
|
6
|
+
import subprocess
|
|
7
|
+
import tempfile
|
|
8
|
+
import sys
|
|
9
|
+
import unittest
|
|
10
|
+
from unittest import mock
|
|
11
|
+
|
|
12
|
+
sys.dont_write_bytecode = True
|
|
13
|
+
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
14
|
+
import maintain # noqa: E402
|
|
15
|
+
|
|
16
|
+
SCRIPT = Path(__file__).with_name('maintain.py')
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class MaintainTests(unittest.TestCase):
|
|
20
|
+
def setUp(self):
|
|
21
|
+
self.tmp = tempfile.TemporaryDirectory()
|
|
22
|
+
self.addCleanup(self.tmp.cleanup)
|
|
23
|
+
self.repo = Path(self.tmp.name)
|
|
24
|
+
self.git('init', '-b', 'main')
|
|
25
|
+
self.git('config', 'user.email', 'test@example.invalid')
|
|
26
|
+
self.git('config', 'user.name', 'Test')
|
|
27
|
+
self.vault = self.repo / 'vault'
|
|
28
|
+
(self.vault / '.knowledge').mkdir(parents=True)
|
|
29
|
+
(self.vault / 'runs').mkdir()
|
|
30
|
+
self.note('area.md', 'area', 'area', [], [])
|
|
31
|
+
self.note('note.md', 'note', 'note', ['area'], ['source.txt'])
|
|
32
|
+
self.note('runs/review.md', 'review', 'run', [], [])
|
|
33
|
+
(self.repo / 'source.txt').write_text('one')
|
|
34
|
+
(self.vault / '.knowledge/sources.json').write_text(json.dumps({'note': {'source.txt': self.sha(self.repo / 'source.txt')}}))
|
|
35
|
+
self.git('add', '.')
|
|
36
|
+
self.git('commit', '-m', 'initial')
|
|
37
|
+
base = self.git('rev-parse', 'HEAD').strip()
|
|
38
|
+
(self.vault / '.knowledge/review.json').write_text(json.dumps({'schema': 1, 'ref': 'refs/heads/main', 'reviewed_through': base, 'coverage': 'partial'}))
|
|
39
|
+
self.git('add', '.')
|
|
40
|
+
self.git('commit', '-m', 'cursor')
|
|
41
|
+
|
|
42
|
+
def note(self, name, ident, kind, areas, sources):
|
|
43
|
+
data = {'id': ident, 'title': ident, 'type': kind, 'status': 'current', 'areas': areas, 'sources': sources, 'updated': '2026-01-01'}
|
|
44
|
+
(self.vault / name).write_text('---\n' + ''.join(k + ': ' + json.dumps(v) + '\n' for k, v in data.items()) + '---\n')
|
|
45
|
+
|
|
46
|
+
def git(self, *args):
|
|
47
|
+
return subprocess.run(['git', '-C', str(self.repo), *args], check=True, capture_output=True, text=True).stdout
|
|
48
|
+
|
|
49
|
+
def cli(self, *args, ok=True, code=None):
|
|
50
|
+
p = subprocess.run(['python3', str(SCRIPT), *args, '--repo', str(self.repo), '--vault', str(self.vault)], capture_output=True, text=True)
|
|
51
|
+
self.assertEqual(p.returncode, code if code is not None else (0 if ok else 1), p.stderr + p.stdout)
|
|
52
|
+
return p
|
|
53
|
+
|
|
54
|
+
@staticmethod
|
|
55
|
+
def sha(path):
|
|
56
|
+
return hashlib.sha256(path.read_bytes()).hexdigest()
|
|
57
|
+
|
|
58
|
+
def change(self):
|
|
59
|
+
(self.repo / 'source.txt').write_text('two')
|
|
60
|
+
self.git('add', 'source.txt')
|
|
61
|
+
self.git('commit', '-m', 'change')
|
|
62
|
+
|
|
63
|
+
def plan(self):
|
|
64
|
+
initial = json.loads(self.cli('scan', '--json').stdout)
|
|
65
|
+
run = self.vault / 'runs/review.md'
|
|
66
|
+
content = run.read_text()
|
|
67
|
+
content = content.replace('---\n', '---\n' + 'review_base: ' + json.dumps(initial['base']) + '\nreview_target: ' + json.dumps(initial['target']) + '\n', 1)
|
|
68
|
+
lines = content.splitlines()
|
|
69
|
+
seen = set(); filtered = []
|
|
70
|
+
for line in lines:
|
|
71
|
+
key = line.partition(':')[0]
|
|
72
|
+
if key in ('review_base', 'review_target'):
|
|
73
|
+
if key in seen:
|
|
74
|
+
continue
|
|
75
|
+
seen.add(key)
|
|
76
|
+
filtered.append(line)
|
|
77
|
+
run.write_text('\n'.join(filtered) + '\n')
|
|
78
|
+
self.cli('scan', '--write-status')
|
|
79
|
+
path = self.vault / '.knowledge/sync-plan.json'
|
|
80
|
+
return path, json.loads(path.read_text())
|
|
81
|
+
|
|
82
|
+
def receipt(self, planpath, plan):
|
|
83
|
+
result = {'plan_sha256': self.sha(planpath), 'paths': {p: {'status': 'reviewed', 'reason': 'inspected'} for p in plan['paths']}, 'notes': {n: {'status': 'unchanged', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}
|
|
84
|
+
path = self.repo / 'receipt.json'
|
|
85
|
+
path.write_text(json.dumps(result))
|
|
86
|
+
return path
|
|
87
|
+
|
|
88
|
+
def test_scan_read_only_and_old_reverted_changes(self):
|
|
89
|
+
self.change()
|
|
90
|
+
self.git('revert', '--no-edit', 'HEAD')
|
|
91
|
+
before = self.git('status', '--porcelain')
|
|
92
|
+
p = json.loads(self.cli('scan', '--json').stdout)
|
|
93
|
+
self.assertIn('source.txt', p['paths'])
|
|
94
|
+
self.assertEqual(before, self.git('status', '--porcelain'))
|
|
95
|
+
self.assertEqual(p['affected_notes'], ['note'])
|
|
96
|
+
|
|
97
|
+
def test_rename_untracked_and_credential_exclusion(self):
|
|
98
|
+
self.git('mv', 'source.txt', 'new name.txt')
|
|
99
|
+
self.git('commit', '-m', 'rename')
|
|
100
|
+
(self.repo / 'new file.txt').write_text('new')
|
|
101
|
+
(self.repo / '.env').write_text('secret')
|
|
102
|
+
p = json.loads(self.cli('scan', '--json').stdout)
|
|
103
|
+
self.assertEqual(p['paths'], ['new name.txt', 'source.txt'])
|
|
104
|
+
self.assertIn('new file.txt', p['dirty'])
|
|
105
|
+
self.assertNotIn('.env', str(p))
|
|
106
|
+
self.assertTrue(p['errors'])
|
|
107
|
+
|
|
108
|
+
def test_published_knowledge_bundle_does_not_queue_its_own_files(self):
|
|
109
|
+
new_vault = self.repo / 'knowledge' / 'example'
|
|
110
|
+
shutil.copytree(self.vault, new_vault)
|
|
111
|
+
self.vault = new_vault
|
|
112
|
+
cursor = new_vault / '.knowledge/review.json'
|
|
113
|
+
checkpoint = json.loads(cursor.read_text())
|
|
114
|
+
checkpoint['reviewed_through'] = self.git('rev-parse', 'HEAD').strip()
|
|
115
|
+
cursor.write_text(json.dumps(checkpoint))
|
|
116
|
+
(self.repo / 'knowledge/README.md').write_text('How to run the skill')
|
|
117
|
+
(self.repo / 'knowledge/.gitignore').write_text('__pycache__/\n')
|
|
118
|
+
self.git('add', 'knowledge')
|
|
119
|
+
self.git('commit', '-m', 'publish knowledge bundle')
|
|
120
|
+
(self.repo / 'knowledge/README.md').write_text('Updated skill instructions')
|
|
121
|
+
(self.repo / 'knowledge/product-spec.md').write_text('Actual project scope')
|
|
122
|
+
self.change()
|
|
123
|
+
|
|
124
|
+
plan = json.loads(self.cli('scan', '--json').stdout)
|
|
125
|
+
self.assertEqual(plan['paths'], ['source.txt'])
|
|
126
|
+
self.assertEqual(plan['dirty'], ['knowledge/product-spec.md'])
|
|
127
|
+
self.assertEqual(plan['affected_notes'], ['note'])
|
|
128
|
+
|
|
129
|
+
def test_finish_and_noop(self):
|
|
130
|
+
self.change()
|
|
131
|
+
planpath, plan = self.plan()
|
|
132
|
+
receipt = self.receipt(planpath, plan)
|
|
133
|
+
# Receipt is outside reviewed evidence and must exist before scanning.
|
|
134
|
+
receipt.unlink()
|
|
135
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
136
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
137
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(planpath), 'paths': {p: {'status': 'reviewed', 'reason': 'inspected'} for p in plan['paths']}, 'notes': {n: {'status': 'unchanged', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
138
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(receipt))
|
|
139
|
+
cursor = json.loads((self.vault / '.knowledge/review.json').read_text())
|
|
140
|
+
self.assertEqual(cursor['reviewed_through'], self.git('rev-parse', 'HEAD').strip())
|
|
141
|
+
baseline = json.loads((self.vault / '.knowledge/sources.json').read_text())
|
|
142
|
+
self.assertEqual(baseline['note']['source.txt'], self.sha(self.repo / 'source.txt'))
|
|
143
|
+
newpath, newplan = self.plan()
|
|
144
|
+
self.assertEqual(newplan['paths'], [])
|
|
145
|
+
|
|
146
|
+
def test_merge_and_revert_include_side_history(self):
|
|
147
|
+
self.git('checkout', '-b', 'feature')
|
|
148
|
+
self.change()
|
|
149
|
+
self.git('revert', '--no-edit', 'HEAD')
|
|
150
|
+
self.git('checkout', 'main')
|
|
151
|
+
self.git('merge', '--no-ff', '-m', 'merge feature', 'feature')
|
|
152
|
+
plan = json.loads(self.cli('scan', '--json').stdout)
|
|
153
|
+
self.assertIn('source.txt', plan['paths'])
|
|
154
|
+
self.assertGreaterEqual(len(plan['commits']), 3)
|
|
155
|
+
|
|
156
|
+
def test_non_checkout_target_is_blocked(self):
|
|
157
|
+
self.git('checkout', '-b', 'feature')
|
|
158
|
+
self.change()
|
|
159
|
+
target = self.git('rev-parse', 'HEAD').strip()
|
|
160
|
+
self.git('checkout', 'main')
|
|
161
|
+
plan = json.loads(self.cli('scan', '--target', target, '--json').stdout)
|
|
162
|
+
self.assertTrue(any('target is not checked out' in b for b in plan['blockers']))
|
|
163
|
+
|
|
164
|
+
def test_old_commit_and_shared_cursor_fresh_clone(self):
|
|
165
|
+
(self.repo / 'source.txt').write_text('old change')
|
|
166
|
+
self.git('add', 'source.txt')
|
|
167
|
+
env = dict(os.environ, GIT_AUTHOR_DATE='2020-01-01T12:00:00+0000', GIT_COMMITTER_DATE='2020-01-01T12:00:00+0000')
|
|
168
|
+
subprocess.run(['git', '-C', str(self.repo), 'commit', '-m', 'old'], env=env, check=True, capture_output=True)
|
|
169
|
+
clone = self.repo.parent / (self.repo.name + '-clone')
|
|
170
|
+
self.addCleanup(lambda: __import__('shutil').rmtree(clone, ignore_errors=True))
|
|
171
|
+
subprocess.run(['git', 'clone', '-q', str(self.repo), str(clone)], check=True)
|
|
172
|
+
p = subprocess.run(['python3', str(SCRIPT), 'scan', '--repo', str(clone), '--vault', str(clone / 'vault'), '--json'], capture_output=True, text=True, check=True)
|
|
173
|
+
plan = json.loads(p.stdout)
|
|
174
|
+
self.assertIn('source.txt', plan['paths'])
|
|
175
|
+
self.assertEqual(plan['base'], json.loads((clone / 'vault/.knowledge/review.json').read_text())['reviewed_through'])
|
|
176
|
+
self.assertEqual(len(plan['commits']), 2)
|
|
177
|
+
|
|
178
|
+
def test_shallow_history_blocks_and_missing_cursor_errors(self):
|
|
179
|
+
self.change()
|
|
180
|
+
clone = self.repo.parent / (self.repo.name + '-shallow')
|
|
181
|
+
self.addCleanup(lambda: __import__('shutil').rmtree(clone, ignore_errors=True))
|
|
182
|
+
subprocess.run(['git', 'clone', '-q', '--depth=1', self.repo.as_uri(), str(clone)], check=True)
|
|
183
|
+
p = subprocess.run(['python3', str(SCRIPT), 'scan', '--repo', str(clone), '--vault', str(clone / 'vault'), '--json'], capture_output=True, text=True)
|
|
184
|
+
self.assertEqual(p.returncode, 1)
|
|
185
|
+
self.assertIn('ERROR:', p.stderr)
|
|
186
|
+
self.assertNotEqual(json.loads((clone / 'vault/.knowledge/review.json').read_text())['reviewed_through'], subprocess.run(['git', '-C', str(clone), 'rev-parse', 'HEAD'], capture_output=True, text=True, check=True).stdout.strip())
|
|
187
|
+
(self.vault / '.knowledge/review.json').unlink()
|
|
188
|
+
self.cli('scan', ok=False)
|
|
189
|
+
|
|
190
|
+
def test_diverged_cursor_blocked(self):
|
|
191
|
+
self.git('checkout', '-b', 'other')
|
|
192
|
+
self.change()
|
|
193
|
+
other = self.git('rev-parse', 'HEAD').strip()
|
|
194
|
+
self.git('checkout', 'main')
|
|
195
|
+
cursor = self.vault / '.knowledge/review.json'
|
|
196
|
+
data = json.loads(cursor.read_text()); data['reviewed_through'] = other
|
|
197
|
+
cursor.write_text(json.dumps(data))
|
|
198
|
+
plan = json.loads(self.cli('scan', '--json').stdout)
|
|
199
|
+
self.assertTrue(any('not an ancestor' in b for b in plan['blockers']))
|
|
200
|
+
|
|
201
|
+
def test_selective_baseline_and_new_note_after_rescan(self):
|
|
202
|
+
(self.repo / 'other.txt').write_text('other')
|
|
203
|
+
self.note('other.md', 'other', 'note', ['area'], ['other.txt'])
|
|
204
|
+
baseline_file = self.vault / '.knowledge/sources.json'
|
|
205
|
+
baseline = json.loads(baseline_file.read_text()); baseline['other'] = {'other.txt': 'previous-reviewed-hash'}
|
|
206
|
+
baseline_file.write_text(json.dumps(baseline))
|
|
207
|
+
self.git('add', '.')
|
|
208
|
+
self.git('commit', '-m', 'other note')
|
|
209
|
+
cursor = self.vault / '.knowledge/review.json'
|
|
210
|
+
data = json.loads(cursor.read_text()); data['reviewed_through'] = self.git('rev-parse', 'HEAD').strip()
|
|
211
|
+
cursor.write_text(json.dumps(data))
|
|
212
|
+
self.git('add', 'vault/.knowledge/review.json')
|
|
213
|
+
self.git('commit', '-m', 'review other note')
|
|
214
|
+
self.change()
|
|
215
|
+
first, original = self.plan()
|
|
216
|
+
self.note('added.md', 'added', 'note', ['area'], ['source.txt'])
|
|
217
|
+
planpath, plan = self.plan()
|
|
218
|
+
self.assertNotIn('added', original['affected_notes'])
|
|
219
|
+
self.assertIn('added', plan['affected_notes'])
|
|
220
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
221
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
222
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(planpath), 'paths': {p: {'status': 'reviewed', 'reason': 'read'} for p in plan['paths']}, 'notes': {n: {'status': 'unchanged', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
223
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(receipt))
|
|
224
|
+
result = json.loads(baseline_file.read_text())
|
|
225
|
+
self.assertEqual(result['other'], {'other.txt': 'previous-reviewed-hash'})
|
|
226
|
+
self.assertEqual(result['added']['source.txt'], self.sha(self.repo / 'source.txt'))
|
|
227
|
+
|
|
228
|
+
def test_empty_finish_no_canonical_churn(self):
|
|
229
|
+
planpath, plan = self.plan()
|
|
230
|
+
self.assertEqual(plan['paths'], [])
|
|
231
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
232
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
233
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(planpath), 'paths': {}, 'notes': {}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
234
|
+
before = {p: self.sha(self.vault / p) for p in ('.knowledge/review.json', '.knowledge/sources.json')}
|
|
235
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(receipt))
|
|
236
|
+
self.assertEqual(before, {p: self.sha(self.vault / p) for p in before})
|
|
237
|
+
self.assertFalse((self.vault / 'graph.html').exists())
|
|
238
|
+
|
|
239
|
+
def test_dirty_path_and_conflicts_block_finish(self):
|
|
240
|
+
self.change()
|
|
241
|
+
(self.repo / 'source.txt').write_text('uncommitted')
|
|
242
|
+
planpath, plan = self.plan()
|
|
243
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
244
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
245
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(planpath), 'paths': {'source.txt': {'status': 'reviewed', 'reason': 'read'}}, 'notes': {'note': {'status': 'unchanged', 'expected_sha256': plan['notes']['note']['sha256']}}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
246
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(receipt), ok=False)
|
|
247
|
+
self.git('checkout', '--', 'source.txt')
|
|
248
|
+
self.git('checkout', '-b', 'conflict')
|
|
249
|
+
(self.repo / 'source.txt').write_text('branch')
|
|
250
|
+
self.git('commit', '-am', 'branch')
|
|
251
|
+
self.git('checkout', 'main')
|
|
252
|
+
(self.repo / 'source.txt').write_text('main')
|
|
253
|
+
self.git('commit', '-am', 'main')
|
|
254
|
+
subprocess.run(['git', '-C', str(self.repo), 'merge', 'conflict'], capture_output=True)
|
|
255
|
+
plan = json.loads(self.cli('scan', '--json').stdout)
|
|
256
|
+
self.assertTrue(any('conflict' in b for b in plan['blockers']))
|
|
257
|
+
|
|
258
|
+
def test_status_escapes_paths_and_skips_credential_aliases(self):
|
|
259
|
+
name = '<script> & ü.txt'
|
|
260
|
+
(self.repo / name).write_text('content')
|
|
261
|
+
(self.repo / '.env').write_text('secret must not be read')
|
|
262
|
+
(self.repo / 'alias').symlink_to('.env')
|
|
263
|
+
self.cli('scan', '--write-status')
|
|
264
|
+
plan = json.loads((self.vault / '.knowledge/sync-plan.json').read_text())
|
|
265
|
+
self.assertEqual(plan['state'], 'pending')
|
|
266
|
+
self.assertIn(name, plan['dirty'])
|
|
267
|
+
self.assertIn('alias', plan['skipped_sources'])
|
|
268
|
+
self.assertNotIn('alias', plan['source_hashes'])
|
|
269
|
+
page = (self.vault / 'sync.html').read_text()
|
|
270
|
+
self.assertIn('<script> & ü.txt', page)
|
|
271
|
+
self.assertNotIn('<script>', page)
|
|
272
|
+
self.assertIn('knowledge.py serve', page)
|
|
273
|
+
self.assertNotIn('secret must not be read', page)
|
|
274
|
+
|
|
275
|
+
def test_freshness_and_dirty_note_visible(self):
|
|
276
|
+
(self.repo / 'source.txt').write_text('dirty')
|
|
277
|
+
self.cli('scan', '--write-status')
|
|
278
|
+
report = json.loads((self.vault / '.knowledge/sync-plan.json').read_text())
|
|
279
|
+
status = (self.vault / '.knowledge/sync-status.md').read_text()
|
|
280
|
+
self.assertEqual(report['dirty_affected_notes'], ['note'])
|
|
281
|
+
self.assertEqual(report['state'], 'pending')
|
|
282
|
+
self.assertIn('Source freshness warnings', status)
|
|
283
|
+
self.assertIn('source.txt', status)
|
|
284
|
+
self.assertIn(report['scanned_at'], status)
|
|
285
|
+
|
|
286
|
+
def test_deleted_source_repointed_note_remains_affected(self):
|
|
287
|
+
(self.repo / 'alternate.txt').write_text('alternate')
|
|
288
|
+
self.git('add', 'alternate.txt')
|
|
289
|
+
self.git('commit', '-m', 'alternate')
|
|
290
|
+
self.git('rm', 'source.txt')
|
|
291
|
+
self.git('commit', '-m', 'delete original')
|
|
292
|
+
self.note('note.md', 'note', 'note', ['area'], ['alternate.txt'])
|
|
293
|
+
planpath, plan = self.plan()
|
|
294
|
+
self.assertIn('note', plan['affected_notes'])
|
|
295
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
296
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
297
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(planpath), 'paths': {p: {'status': 'reviewed', 'reason': 'read'} for p in plan['paths']}, 'notes': {n: {'status': 'updated', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
298
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(receipt))
|
|
299
|
+
baseline = json.loads((self.vault / '.knowledge/sources.json').read_text())
|
|
300
|
+
self.assertEqual(baseline['note'], {'alternate.txt': self.sha(self.repo / 'alternate.txt')})
|
|
301
|
+
|
|
302
|
+
def test_tampered_impact_cannot_advance_cursor(self):
|
|
303
|
+
self.change()
|
|
304
|
+
path, plan = self.plan()
|
|
305
|
+
before = self.sha(self.vault / '.knowledge/review.json')
|
|
306
|
+
plan['affected_notes'] = []
|
|
307
|
+
path.write_text(json.dumps(plan))
|
|
308
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
309
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
310
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(path), 'paths': {'source.txt': {'status': 'reviewed', 'reason': 'read'}}, 'notes': {}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
311
|
+
self.cli('finish', '--plan', str(path), '--review', str(receipt), ok=False)
|
|
312
|
+
self.assertEqual(before, self.sha(self.vault / '.knowledge/review.json'))
|
|
313
|
+
|
|
314
|
+
def test_symlink_and_dot_path_cannot_accept_dirty_evidence(self):
|
|
315
|
+
(self.repo / 'other.txt').write_text('clean')
|
|
316
|
+
(self.repo / 'alias.txt').symlink_to('other.txt')
|
|
317
|
+
self.note('note.md', 'note', 'note', ['area'], ['source.txt', 'alias.txt'])
|
|
318
|
+
self.git('add', '.')
|
|
319
|
+
self.git('commit', '-m', 'alias')
|
|
320
|
+
cursor = self.vault / '.knowledge/review.json'
|
|
321
|
+
data = json.loads(cursor.read_text()); data['reviewed_through'] = self.git('rev-parse', 'HEAD').strip()
|
|
322
|
+
cursor.write_text(json.dumps(data))
|
|
323
|
+
self.git('add', 'vault/.knowledge/review.json')
|
|
324
|
+
self.git('commit', '-m', 'review alias')
|
|
325
|
+
self.change()
|
|
326
|
+
(self.repo / 'other.txt').write_text('dirty')
|
|
327
|
+
path, plan = self.plan()
|
|
328
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
329
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
330
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(path), 'paths': {p: {'status': 'reviewed', 'reason': 'read'} for p in plan['paths']}, 'notes': {n: {'status': 'unchanged', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
331
|
+
failure = self.cli('finish', '--plan', str(path), '--review', str(receipt), ok=False)
|
|
332
|
+
self.assertIn('cites aliased evidence', failure.stderr)
|
|
333
|
+
self.note('note.md', 'note', 'note', ['area'], ['source.txt', './other.txt'])
|
|
334
|
+
path, plan = self.plan()
|
|
335
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(path), 'paths': {p: {'status': 'reviewed', 'reason': 'read'} for p in plan['paths']}, 'notes': {n: {'status': 'unchanged', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
336
|
+
failure = self.cli('finish', '--plan', str(path), '--review', str(receipt), ok=False)
|
|
337
|
+
self.assertIn('cites dirty evidence', failure.stderr)
|
|
338
|
+
self.assertIn('note', plan['dirty_affected_notes'])
|
|
339
|
+
|
|
340
|
+
def test_run_provenance_rejects_wrong_type_range_and_hash(self):
|
|
341
|
+
self.change()
|
|
342
|
+
planpath, initial = self.plan()
|
|
343
|
+
run = self.vault / 'runs/review.md'
|
|
344
|
+
valid = run.read_text()
|
|
345
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
346
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
347
|
+
for mode in ('type', 'range', 'hash'):
|
|
348
|
+
with self.subTest(mode=mode):
|
|
349
|
+
content = valid
|
|
350
|
+
if mode == 'type':
|
|
351
|
+
content = content.replace('type: "run"', 'type: "index"')
|
|
352
|
+
if mode == 'range':
|
|
353
|
+
content = content.replace(initial['target'], '0' * 40)
|
|
354
|
+
run.write_text(content)
|
|
355
|
+
self.cli('scan', '--write-status')
|
|
356
|
+
plan = json.loads(planpath.read_text())
|
|
357
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(planpath), 'paths': {p: {'status': 'reviewed', 'reason': 'read'} for p in plan['paths']}, 'notes': {n: {'status': 'unchanged', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']}, 'run_path': 'runs/review.md', 'run_sha256': '0' * 64 if mode == 'hash' else self.sha(run)}))
|
|
358
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(receipt), ok=False)
|
|
359
|
+
run.write_text(valid)
|
|
360
|
+
|
|
361
|
+
def test_case_alias_and_hardlink_dirty_evidence(self):
|
|
362
|
+
(self.repo / 'other.txt').write_text('clean')
|
|
363
|
+
os.link(self.repo / 'other.txt', self.repo / 'hardlink.txt')
|
|
364
|
+
self.git('add', 'other.txt', 'hardlink.txt')
|
|
365
|
+
self.git('commit', '-m', 'other evidence')
|
|
366
|
+
cursor = self.vault / '.knowledge/review.json'
|
|
367
|
+
data = json.loads(cursor.read_text()); data['reviewed_through'] = self.git('rev-parse', 'HEAD').strip()
|
|
368
|
+
cursor.write_text(json.dumps(data)); self.git('add', 'vault/.knowledge/review.json'); self.git('commit', '-m', 'review other')
|
|
369
|
+
self.change()
|
|
370
|
+
aliases = ['hardlink.txt']
|
|
371
|
+
if (self.repo / 'OTHER.txt').exists():
|
|
372
|
+
aliases.append('OTHER.txt')
|
|
373
|
+
for alias in aliases:
|
|
374
|
+
with self.subTest(alias=alias):
|
|
375
|
+
(self.repo / 'other.txt').write_text('dirty')
|
|
376
|
+
self.note('note.md', 'note', 'note', ['area'], ['source.txt', alias])
|
|
377
|
+
path, plan = self.plan()
|
|
378
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
379
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
380
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(path), 'paths': {p: {'status': 'reviewed', 'reason': 'read'} for p in plan['paths']}, 'notes': {n: {'status': 'unchanged', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
381
|
+
failure = self.cli('finish', '--plan', str(path), '--review', str(receipt), ok=False)
|
|
382
|
+
self.assertIn('cites dirty evidence', failure.stderr)
|
|
383
|
+
self.assertIn('note', plan['dirty_affected_notes'])
|
|
384
|
+
|
|
385
|
+
def test_case_variant_impacts_changed_source(self):
|
|
386
|
+
self.note('note.md', 'note', 'note', ['area'], ['SOURCE.txt'])
|
|
387
|
+
self.change()
|
|
388
|
+
plan = json.loads(self.cli('scan', '--json').stdout)
|
|
389
|
+
self.assertIn('note', plan['affected_notes'])
|
|
390
|
+
self.assertNotIn('source.txt', plan['unmapped'])
|
|
391
|
+
|
|
392
|
+
def evidence_scenario(self, mode):
|
|
393
|
+
extra = 'build/extra.txt' if mode == 'excluded' else 'extra.txt'
|
|
394
|
+
file = self.repo / extra
|
|
395
|
+
file.parent.mkdir(parents=True, exist_ok=True)
|
|
396
|
+
file.write_text('committed')
|
|
397
|
+
if mode != 'untracked':
|
|
398
|
+
self.git('add', '-f', extra)
|
|
399
|
+
self.git('commit', '-m', 'extra evidence')
|
|
400
|
+
else:
|
|
401
|
+
with (self.repo / '.git/info/exclude').open('a') as ignored:
|
|
402
|
+
ignored.write('extra.txt\n')
|
|
403
|
+
self.note('note.md', 'note', 'note', ['area'], ['source.txt', extra])
|
|
404
|
+
self.change()
|
|
405
|
+
if mode in ('excluded', 'assume', 'skip'):
|
|
406
|
+
if mode == 'assume':
|
|
407
|
+
self.git('update-index', '--assume-unchanged', extra)
|
|
408
|
+
if mode == 'skip':
|
|
409
|
+
self.git('update-index', '--skip-worktree', extra)
|
|
410
|
+
file.write_text('uncommitted')
|
|
411
|
+
path, plan = self.plan()
|
|
412
|
+
self.assertNotIn(extra, plan['dirty'])
|
|
413
|
+
receipt = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
414
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
415
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(path), 'paths': {p: {'status': 'reviewed', 'reason': 'read'} for p in plan['paths']}, 'notes': {n: {'status': 'unchanged', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
416
|
+
cursor = self.vault / '.knowledge/review.json'
|
|
417
|
+
baseline = self.vault / '.knowledge/sources.json'
|
|
418
|
+
before = (cursor.read_bytes(), baseline.read_bytes())
|
|
419
|
+
result = self.cli('finish', '--plan', str(path), '--review', str(receipt), ok=mode == 'clean')
|
|
420
|
+
if mode == 'clean':
|
|
421
|
+
self.assertEqual(json.loads(cursor.read_text())['reviewed_through'], plan['target'])
|
|
422
|
+
self.assertEqual(json.loads(baseline.read_text())['note'][extra], self.sha(file))
|
|
423
|
+
else:
|
|
424
|
+
self.assertEqual((cursor.read_bytes(), baseline.read_bytes()), before)
|
|
425
|
+
self.assertIn('not tracked in target' if mode == 'untracked' else 'dirty evidence', result.stderr)
|
|
426
|
+
|
|
427
|
+
def test_ignored_untracked_selected_evidence_rejected(self):
|
|
428
|
+
self.evidence_scenario('untracked')
|
|
429
|
+
|
|
430
|
+
def test_excluded_dirty_selected_evidence_rejected(self):
|
|
431
|
+
self.evidence_scenario('excluded')
|
|
432
|
+
|
|
433
|
+
def test_assume_unchanged_selected_evidence_rejected(self):
|
|
434
|
+
self.evidence_scenario('assume')
|
|
435
|
+
|
|
436
|
+
def test_skip_worktree_selected_evidence_rejected(self):
|
|
437
|
+
self.evidence_scenario('skip')
|
|
438
|
+
|
|
439
|
+
def test_clean_tracked_extra_selected_evidence_accepted(self):
|
|
440
|
+
self.evidence_scenario('clean')
|
|
441
|
+
|
|
442
|
+
def test_deferred_and_race_rejected(self):
|
|
443
|
+
self.change()
|
|
444
|
+
path, plan = self.plan()
|
|
445
|
+
receipt = Path(self.tmp.name).parent / (Path(self.tmp.name).name + '-receipt.json')
|
|
446
|
+
self.addCleanup(lambda: receipt.unlink(missing_ok=True))
|
|
447
|
+
receipt.write_text(json.dumps({'plan_sha256': self.sha(path), 'paths': {'source.txt': {'status': 'deferred', 'reason': 'later'}}, 'notes': {'note': {'status': 'unchanged', 'expected_sha256': plan['notes']['note']['sha256']}}, 'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}))
|
|
448
|
+
self.cli('finish', '--plan', str(path), '--review', str(receipt), ok=False)
|
|
449
|
+
(self.repo / 'source.txt').write_text('raced')
|
|
450
|
+
self.cli('finish', '--plan', str(path), '--review', str(receipt), ok=False)
|
|
451
|
+
|
|
452
|
+
|
|
453
|
+
# scan performance, robustness and the receipt helper
|
|
454
|
+
def test_scan_resolves_each_path_once(self):
|
|
455
|
+
for i in range(30):
|
|
456
|
+
sources = []
|
|
457
|
+
for j in range(3):
|
|
458
|
+
name = f'src/file{i}_{j}.txt'
|
|
459
|
+
(self.repo / name).parent.mkdir(exist_ok=True)
|
|
460
|
+
(self.repo / name).write_text('x')
|
|
461
|
+
sources.append(name)
|
|
462
|
+
self.note(f'n{i}.md', f'n{i}', 'note', ['area'], sources)
|
|
463
|
+
self.git('add', '.')
|
|
464
|
+
self.git('commit', '-m', 'notes')
|
|
465
|
+
cursor = self.vault / '.knowledge/review.json'
|
|
466
|
+
cursor.write_text(json.dumps({'schema': 1, 'ref': 'refs/heads/main', 'reviewed_through': self.git('rev-parse', 'HEAD').strip(), 'coverage': 'partial'}))
|
|
467
|
+
self.git('add', '.')
|
|
468
|
+
self.git('commit', '-m', 'cursor')
|
|
469
|
+
for i in range(60):
|
|
470
|
+
(self.repo / f'changed{i}.txt').write_text('y')
|
|
471
|
+
(self.repo / 'src/file0_0.txt').write_text('changed')
|
|
472
|
+
self.git('add', '.')
|
|
473
|
+
self.git('commit', '-m', 'many')
|
|
474
|
+
calls = []
|
|
475
|
+
real = maintain.knowledge.safe_path
|
|
476
|
+
with mock.patch.object(maintain.knowledge, 'safe_path', lambda *a: calls.append(a) or real(*a)):
|
|
477
|
+
report = maintain.scan(self.repo.resolve(), self.vault.resolve(), None)
|
|
478
|
+
self.assertEqual(len(report['paths']), 61)
|
|
479
|
+
self.assertEqual([n for n in report['affected_notes'] if n.startswith('n') and n != 'note'], ['n0'])
|
|
480
|
+
sources, paths = 90 + 1, len(report['paths'])
|
|
481
|
+
# Quadratic matching would need sources * paths (several thousand) lookups; linear needs a few per path.
|
|
482
|
+
self.assertLess(len(calls), 12 * (sources + paths), len(calls))
|
|
483
|
+
evidence = maintain.Evidence(self.repo.resolve())
|
|
484
|
+
before = len(calls)
|
|
485
|
+
with mock.patch.object(maintain.knowledge, 'safe_path', lambda *a: calls.append(a) or real(*a)):
|
|
486
|
+
group = evidence.group(['source.txt', 'changed1.txt'])
|
|
487
|
+
for _ in range(50):
|
|
488
|
+
self.assertTrue(evidence.matches(group, 'SOURCE.txt'))
|
|
489
|
+
self.assertFalse(evidence.matches(group, 'other.txt'))
|
|
490
|
+
self.assertEqual(len(calls) - before, 4) # two group paths plus two distinct probes; repeats are cached
|
|
491
|
+
self.assertTrue(maintain.same_evidence(self.repo.resolve(), 'Source.TXT', 'source.txt'))
|
|
492
|
+
self.assertFalse(maintain.same_evidence(self.repo.resolve(), '../x', 'source.txt'))
|
|
493
|
+
|
|
494
|
+
def test_non_utf8_path_in_range_does_not_crash_write_status(self):
|
|
495
|
+
def index_info(line):
|
|
496
|
+
subprocess.run(['git', '-C', str(self.repo), 'update-index', '--index-info'], input=line, check=True)
|
|
497
|
+
blob = subprocess.run(['git', '-C', str(self.repo), 'hash-object', '-w', '--stdin'], input=b'data', capture_output=True, check=True).stdout.strip()
|
|
498
|
+
index_info(b'100644 ' + blob + b'\tbad-\xff.txt\n')
|
|
499
|
+
self.git('commit', '-m', 'add undecodable path')
|
|
500
|
+
index_info(b'0 ' + b'0' * 40 + b'\tbad-\xff.txt\n')
|
|
501
|
+
self.git('commit', '-m', 'remove it')
|
|
502
|
+
planpath, plan = self.plan()
|
|
503
|
+
self.assertTrue(any('bad-' in p for p in plan['paths']))
|
|
504
|
+
self.assertIn('bad-', (self.vault / '.knowledge/sync-status.md').read_text())
|
|
505
|
+
self.assertIn('bad-', (self.vault / 'sync.html').read_text())
|
|
506
|
+
out = self.repo.parent / (self.repo.name + '-bad.json')
|
|
507
|
+
self.addCleanup(lambda: out.unlink(missing_ok=True))
|
|
508
|
+
self.cli('receipt', '--plan', str(planpath), '--out', str(out))
|
|
509
|
+
data = json.loads(out.read_text())
|
|
510
|
+
for entry in data['paths'].values():
|
|
511
|
+
entry.update(status='reviewed', reason='read')
|
|
512
|
+
out.write_text(json.dumps(data))
|
|
513
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(out))
|
|
514
|
+
|
|
515
|
+
def receipt_cli(self, planpath, *extra, ok=True):
|
|
516
|
+
out = self.repo.parent / (self.repo.name + '-receipt.json')
|
|
517
|
+
self.addCleanup(lambda: out.unlink(missing_ok=True))
|
|
518
|
+
p = self.cli('receipt', '--plan', str(planpath), '--out', str(out), *extra, ok=ok)
|
|
519
|
+
return out, p
|
|
520
|
+
|
|
521
|
+
def test_receipt_fills_hashes_and_leaves_review_empty(self):
|
|
522
|
+
self.change()
|
|
523
|
+
planpath, plan = self.plan()
|
|
524
|
+
out, result = self.receipt_cli(planpath)
|
|
525
|
+
data = json.loads(out.read_text())
|
|
526
|
+
self.assertEqual(data['plan_sha256'], self.sha(planpath))
|
|
527
|
+
self.assertEqual(data['paths'], {'source.txt': {'status': '', 'reason': ''}})
|
|
528
|
+
self.assertEqual(data['notes'], {'note': {'status': '', 'expected_sha256': self.sha(self.vault / 'note.md')}})
|
|
529
|
+
self.assertEqual((data['run_path'], data['run_sha256']), ('runs/review.md', self.sha(self.vault / 'runs/review.md')))
|
|
530
|
+
self.assertIn('1 paths', result.stdout)
|
|
531
|
+
# finish still demands a real review
|
|
532
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(out), ok=False)
|
|
533
|
+
data['paths']['source.txt'].update(status='reviewed', reason=' ')
|
|
534
|
+
data['notes']['note']['status'] = 'unchanged'
|
|
535
|
+
out.write_text(json.dumps(data))
|
|
536
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(out), ok=False)
|
|
537
|
+
data['paths']['source.txt']['reason'] = 'read the diff'
|
|
538
|
+
out.write_text(json.dumps(data))
|
|
539
|
+
self.cli('finish', '--plan', str(planpath), '--review', str(out))
|
|
540
|
+
self.assertEqual(json.loads((self.vault / '.knowledge/review.json').read_text())['reviewed_through'], self.git('rev-parse', 'HEAD').strip())
|
|
541
|
+
|
|
542
|
+
def test_receipt_carries_over_only_what_was_reviewed(self):
|
|
543
|
+
self.change()
|
|
544
|
+
planpath, plan = self.plan()
|
|
545
|
+
out, _ = self.receipt_cli(planpath)
|
|
546
|
+
data = json.loads(out.read_text())
|
|
547
|
+
data['paths']['source.txt'].update(status='reviewed', reason='kept')
|
|
548
|
+
data['paths']['gone.txt'] = {'status': 'reviewed', 'reason': 'no longer applies'}
|
|
549
|
+
data['notes']['note']['status'] = 'updated'
|
|
550
|
+
data['notes']['gone'] = {'status': 'updated', 'expected_sha256': 'x'}
|
|
551
|
+
out.write_text(json.dumps(data))
|
|
552
|
+
# Same plan, same note bytes: dispositions stay, stale entries drop.
|
|
553
|
+
self.cli('receipt', '--plan', str(planpath), '--out', str(out))
|
|
554
|
+
fresh = json.loads(out.read_text())
|
|
555
|
+
self.assertEqual(fresh['paths'], {'source.txt': {'status': 'reviewed', 'reason': 'kept'}})
|
|
556
|
+
self.assertEqual(fresh['notes'], {'note': {'status': 'updated', 'expected_sha256': self.sha(self.vault / 'note.md')}})
|
|
557
|
+
# A receipt for another plan must not leave its path dispositions behind.
|
|
558
|
+
data = json.loads(out.read_text())
|
|
559
|
+
data['plan_sha256'] = '0' * 64
|
|
560
|
+
out.write_text(json.dumps(data))
|
|
561
|
+
self.cli('receipt', '--plan', str(planpath), '--out', str(out))
|
|
562
|
+
fresh = json.loads(out.read_text())
|
|
563
|
+
self.assertEqual(fresh['paths'], {'source.txt': {'status': '', 'reason': ''}})
|
|
564
|
+
self.assertEqual(fresh['notes']['note']['status'], 'updated')
|
|
565
|
+
# A note whose bytes changed since the entered disposition loses it; the hash is refreshed.
|
|
566
|
+
data = json.loads(out.read_text())
|
|
567
|
+
data['notes']['note']['expected_sha256'] = '1' * 64
|
|
568
|
+
out.write_text(json.dumps(data))
|
|
569
|
+
self.cli('receipt', '--plan', str(planpath), '--out', str(out))
|
|
570
|
+
fresh = json.loads(out.read_text())
|
|
571
|
+
self.assertEqual(fresh['notes']['note'], {'status': '', 'expected_sha256': self.sha(self.vault / 'note.md')})
|
|
572
|
+
|
|
573
|
+
def test_receipt_run_selection_and_empty_plan(self):
|
|
574
|
+
planpath, plan = self.plan()
|
|
575
|
+
self.assertEqual(plan['paths'], [])
|
|
576
|
+
out, _ = self.receipt_cli(planpath)
|
|
577
|
+
self.assertNotIn('run_path', json.loads(out.read_text()))
|
|
578
|
+
self.change()
|
|
579
|
+
planpath, plan = self.plan()
|
|
580
|
+
out, _ = self.receipt_cli(planpath, '--run', str(self.vault / 'runs/review.md'))
|
|
581
|
+
self.assertEqual(json.loads(out.read_text())['run_path'], 'runs/review.md')
|
|
582
|
+
out, _ = self.receipt_cli(planpath, '--run', 'runs/review.md')
|
|
583
|
+
self.assertEqual(json.loads(out.read_text())['run_path'], 'runs/review.md')
|
|
584
|
+
self.receipt_cli(planpath, '--run', 'runs/missing.md', ok=False)
|
|
585
|
+
self.receipt_cli(planpath, '--run', 'note.md', ok=False)
|
|
586
|
+
self.note('runs/other.md', 'other', 'run', [], [])
|
|
587
|
+
(self.vault / 'runs/other.md').write_text((self.vault / 'runs/review.md').read_text().replace('id: "review"', 'id: "other"'))
|
|
588
|
+
self.cli('scan', '--write-status')
|
|
589
|
+
planpath = self.vault / '.knowledge/sync-plan.json'
|
|
590
|
+
self.receipt_cli(planpath, ok=False) # ambiguous: two run notes carry the range
|
|
591
|
+
|
|
592
|
+
|
|
593
|
+
def closed_gap_fixture(self, decision='done', plan=False):
|
|
594
|
+
sections = ''.join(f'## {n}\n\ntext\n\n' for n in ('Current behavior', 'Gap', 'Evidence', 'Recheck', 'Discussion', 'Decision'))
|
|
595
|
+
(self.vault / 'gaps').mkdir(exist_ok=True)
|
|
596
|
+
(self.repo / 'gone.txt').write_text('soon deleted')
|
|
597
|
+
extra = '' if decision == 'done' else 'decided_by: "Ann"\ndecided_on: "2026-11-15"\n'
|
|
598
|
+
gap = ('---\nid: "g"\ntitle: "g"\ntype: "gap"\nareas: ["area"]\nsources: ["gone.txt"]\nupdated: "2026-01-01"\n'
|
|
599
|
+
f'kind: "product-gap"\nrecheck: "not-checked"\ndecision: "{decision}"\n{extra}---\n{sections}')
|
|
600
|
+
(self.vault / 'gaps/g.md').write_text(gap)
|
|
601
|
+
if plan:
|
|
602
|
+
(self.vault / 'plans').mkdir(exist_ok=True)
|
|
603
|
+
(self.vault / 'plans/p.md').write_text('---\nid: "p"\ntitle: "p"\ntype: "plan"\nstatus: "planned"\nareas: ["area"]\nsources: ["gone.txt"]\nupdated: "2026-01-01"\ngap: "g"\n---\nplan')
|
|
604
|
+
self.git('add', '.')
|
|
605
|
+
self.git('commit', '-m', 'gap')
|
|
606
|
+
cursor = self.vault / '.knowledge/review.json'
|
|
607
|
+
cursor.write_text(json.dumps({'schema': 1, 'ref': 'refs/heads/main', 'reviewed_through': self.git('rev-parse', 'HEAD').strip(), 'coverage': 'partial'}))
|
|
608
|
+
self.git('add', '.')
|
|
609
|
+
self.git('commit', '-m', 'cursor')
|
|
610
|
+
self.git('rm', 'gone.txt')
|
|
611
|
+
self.git('commit', '-m', 'delete')
|
|
612
|
+
|
|
613
|
+
def finish_with_receipt(self, ok=True):
|
|
614
|
+
planpath, plan = self.plan()
|
|
615
|
+
out = self.repo.parent / (self.repo.name + '-closed.json')
|
|
616
|
+
self.addCleanup(lambda: out.unlink(missing_ok=True))
|
|
617
|
+
self.cli('receipt', '--plan', str(planpath), '--out', str(out))
|
|
618
|
+
data = json.loads(out.read_text())
|
|
619
|
+
for entry in data['paths'].values():
|
|
620
|
+
entry.update(status='reviewed', reason='read')
|
|
621
|
+
for entry in data['notes'].values():
|
|
622
|
+
entry['status'] = 'unchanged'
|
|
623
|
+
out.write_text(json.dumps(data))
|
|
624
|
+
return plan, self.cli('finish', '--plan', str(planpath), '--review', str(out), ok=ok)
|
|
625
|
+
|
|
626
|
+
def test_finish_with_closed_gap_whose_source_was_deleted(self):
|
|
627
|
+
self.closed_gap_fixture('done', plan=True)
|
|
628
|
+
plan, _ = self.finish_with_receipt()
|
|
629
|
+
self.assertIn('g', plan['affected_notes'])
|
|
630
|
+
self.assertIn('p', plan['affected_notes'])
|
|
631
|
+
|
|
632
|
+
def test_finish_with_live_gap_and_deleted_source_is_refused(self):
|
|
633
|
+
self.closed_gap_fixture('accepted')
|
|
634
|
+
planpath, plan = self.plan()
|
|
635
|
+
self.assertTrue(any('missing or not a file' in e for e in plan['errors']), plan['errors'])
|
|
636
|
+
_, result = self.finish_with_receipt(ok=False)
|
|
637
|
+
self.assertNotIn('KeyError', result.stderr)
|
|
638
|
+
self.assertIn('structural errors', result.stderr + result.stdout)
|
|
639
|
+
|
|
640
|
+
def test_finish_writes_reviewed_state_and_generates_nothing(self):
|
|
641
|
+
self.closed_gap_fixture('done')
|
|
642
|
+
self.finish_with_receipt()
|
|
643
|
+
for name in ('AS-BUILT.md', 'GAPS.md', 'graph.html', 'Map.canvas', '.knowledge/graph.json'):
|
|
644
|
+
self.assertFalse((self.vault / name).exists(), name)
|
|
645
|
+
self.assertTrue((self.vault / '.knowledge/sources.json').is_file())
|
|
646
|
+
|
|
647
|
+
|
|
648
|
+
def test_relevant_folds_lookalike_credential_and_ignored_names(self):
|
|
649
|
+
for path in ('.\u017f\u017fh/id_r\u017fa', 'a/.GIT/config', 'x/NODE_MODULES/y.js', 'prod.tfvars', 'home/.kube/config'):
|
|
650
|
+
with self.subTest(path=path):
|
|
651
|
+
self.assertFalse(maintain.relevant(path, 'vault'))
|
|
652
|
+
self.assertTrue(maintain.relevant('src/app.py', 'vault'))
|
|
653
|
+
|
|
654
|
+
|
|
655
|
+
# partial finish, retargeting and receipt reporting
|
|
656
|
+
def two_note_range(self):
|
|
657
|
+
"""note cites source.txt, other cites other.txt; both change in the range and other.txt is then left dirty."""
|
|
658
|
+
(self.repo / 'other.txt').write_text('other')
|
|
659
|
+
self.note('other.md', 'other', 'note', ['area'], ['other.txt'])
|
|
660
|
+
baseline_file = self.vault / '.knowledge/sources.json'
|
|
661
|
+
baseline = json.loads(baseline_file.read_text()); baseline['other'] = {'other.txt': self.sha(self.repo / 'other.txt')}
|
|
662
|
+
baseline_file.write_text(json.dumps(baseline))
|
|
663
|
+
self.git('add', '.')
|
|
664
|
+
self.git('commit', '-m', 'other note')
|
|
665
|
+
cursor = self.vault / '.knowledge/review.json'
|
|
666
|
+
data = json.loads(cursor.read_text()); data['reviewed_through'] = self.git('rev-parse', 'HEAD').strip()
|
|
667
|
+
cursor.write_text(json.dumps(data))
|
|
668
|
+
self.git('add', '.')
|
|
669
|
+
self.git('commit', '-m', 'cursor')
|
|
670
|
+
(self.repo / 'source.txt').write_text('two')
|
|
671
|
+
(self.repo / 'other.txt').write_text('other two')
|
|
672
|
+
self.git('add', '.')
|
|
673
|
+
self.git('commit', '-m', 'change both')
|
|
674
|
+
(self.repo / 'other.txt').write_text('someone elses uncommitted edit')
|
|
675
|
+
|
|
676
|
+
def write_receipt(self, planpath, plan, paths=None, notes=None):
|
|
677
|
+
data = {'plan_sha256': self.sha(planpath),
|
|
678
|
+
'paths': {p: {'status': 'reviewed', 'reason': 'read'} for p in plan['paths']},
|
|
679
|
+
'notes': {n: {'status': 'unchanged', 'expected_sha256': plan['notes'][n]['sha256']} for n in plan['affected_notes']},
|
|
680
|
+
'run_path': 'runs/review.md', 'run_sha256': self.sha(self.vault / 'runs/review.md')}
|
|
681
|
+
for path, entry in (paths or {}).items():
|
|
682
|
+
data['paths'][path] = entry
|
|
683
|
+
for ident, entry in (notes or {}).items():
|
|
684
|
+
data['notes'][ident] = {'expected_sha256': plan['notes'][ident]['sha256'], **entry}
|
|
685
|
+
out = self.repo.parent / (self.repo.name + '-partial.json')
|
|
686
|
+
self.addCleanup(lambda: out.unlink(missing_ok=True))
|
|
687
|
+
out.write_text(json.dumps(data))
|
|
688
|
+
return out
|
|
689
|
+
|
|
690
|
+
def state(self):
|
|
691
|
+
return {name: (self.vault / name).read_bytes() if (self.vault / name).exists() else None
|
|
692
|
+
for name in ('.knowledge/review.json', '.knowledge/sources.json')}
|
|
693
|
+
|
|
694
|
+
def test_partial_finish_accepts_clean_notes_and_leaves_checkpoint(self):
|
|
695
|
+
self.two_note_range()
|
|
696
|
+
planpath, plan = self.plan()
|
|
697
|
+
self.assertEqual(plan['dirty_affected_notes'], ['other'])
|
|
698
|
+
receipt = self.write_receipt(planpath, plan,
|
|
699
|
+
paths={'other.txt': {'status': 'deferred', 'reason': 'owner has uncommitted edits'}},
|
|
700
|
+
notes={'other': {'status': 'deferred', 'reason': 'waits for other.txt'}})
|
|
701
|
+
before = self.state()
|
|
702
|
+
checkpoint = json.loads(before['.knowledge/review.json'])['reviewed_through']
|
|
703
|
+
result = self.cli('finish', '--plan', str(planpath), '--review', str(receipt), code=3)
|
|
704
|
+
self.assertIn(f'partial: accepted 1 notes; deferred 1 paths, 1 notes; checkpoint stays at {checkpoint}', result.stdout)
|
|
705
|
+
self.assertIn('deferred path other.txt: owner has uncommitted edits', result.stdout)
|
|
706
|
+
self.assertIn('deferred note other: waits for other.txt', result.stdout)
|
|
707
|
+
after = self.state()
|
|
708
|
+
self.assertEqual(after['.knowledge/review.json'], before['.knowledge/review.json'])
|
|
709
|
+
baseline = json.loads(after['.knowledge/sources.json'])
|
|
710
|
+
self.assertEqual(baseline['note'], {'source.txt': self.sha(self.repo / 'source.txt')})
|
|
711
|
+
self.assertEqual(baseline['other'], json.loads(before['.knowledge/sources.json'])['other']) # deferred note keeps its fingerprint
|
|
712
|
+
# The interval is still pending: the deferred path is listed, the accepted note has no freshness warning.
|
|
713
|
+
again = json.loads(self.cli('scan', '--json').stdout)
|
|
714
|
+
self.assertEqual(again['paths'], ['other.txt', 'source.txt'])
|
|
715
|
+
self.assertTrue(any('other.md' in w for w in again['warnings']))
|
|
716
|
+
self.assertFalse(any('note.md' in w for w in again['warnings']))
|
|
717
|
+
self.assertEqual(again['state'], 'pending')
|
|
718
|
+
# Once the other contributor's edit is committed, a full finish over the same range advances the checkpoint.
|
|
719
|
+
self.git('add', '.')
|
|
720
|
+
self.git('commit', '-m', 'their edit')
|
|
721
|
+
(self.vault / 'runs/review.md').write_text((self.vault / 'runs/review.md').read_text().replace(plan['target'], self.git('rev-parse', 'HEAD').strip()))
|
|
722
|
+
planpath, plan = self.plan()
|
|
723
|
+
self.assertEqual(plan['base'], checkpoint)
|
|
724
|
+
self.assertEqual(plan['dirty'], [])
|
|
725
|
+
receipt = self.write_receipt(planpath, plan)
|
|
726
|
+
result = self.cli('finish', '--plan', str(planpath), '--review', str(receipt))
|
|
727
|
+
self.assertIn('review checkpoint advanced to', result.stdout)
|
|
728
|
+
self.assertEqual(json.loads((self.vault / '.knowledge/review.json').read_text())['reviewed_through'], plan['target'])
|
|
729
|
+
|
|
730
|
+
def test_partial_finish_rejects_accepting_what_is_dirty_or_deferred(self):
|
|
731
|
+
self.two_note_range()
|
|
732
|
+
planpath, plan = self.plan()
|
|
733
|
+
deferred = {'other.txt': {'status': 'deferred', 'reason': 'later'}}
|
|
734
|
+
before = self.state()
|
|
735
|
+
cases = {
|
|
736
|
+
'updated note cites dirty source': (deferred, {'other': {'status': 'updated'}}, 'cites dirty evidence'),
|
|
737
|
+
'unchanged note cites deferred path': (deferred, {'other': {'status': 'unchanged'}}, 'cites dirty evidence'),
|
|
738
|
+
'dirty path marked reviewed': ({}, {'other': {'status': 'deferred', 'reason': 'x'}}, 'dirty integrated path must be deferred'),
|
|
739
|
+
'deferred path without reason': ({'other.txt': {'status': 'deferred', 'reason': ' '}}, {'other': {'status': 'deferred', 'reason': 'x'}}, 'reviewed/excluded/deferred'),
|
|
740
|
+
'deferred note without reason': (deferred, {'other': {'status': 'deferred'}}, 'deferred note needs a reason'),
|
|
741
|
+
'unknown path status': ({'other.txt': {'status': 'later', 'reason': 'x'}}, {}, 'reviewed/excluded/deferred'),
|
|
742
|
+
'empty note status': (deferred, {'other': {'status': ''}}, 'updated/unchanged/deferred'),
|
|
743
|
+
}
|
|
744
|
+
for name, (paths, notes, message) in cases.items():
|
|
745
|
+
with self.subTest(name):
|
|
746
|
+
result = self.cli('finish', '--plan', str(planpath), '--review', str(self.write_receipt(planpath, plan, paths, notes)), ok=False)
|
|
747
|
+
self.assertIn(message, result.stderr)
|
|
748
|
+
self.assertEqual(self.state(), before)
|
|
749
|
+
# A clean path that is deferred makes every note citing it deferred too.
|
|
750
|
+
self.git('checkout', '--', 'other.txt')
|
|
751
|
+
planpath, plan = self.plan()
|
|
752
|
+
receipt = self.write_receipt(planpath, plan, paths={'source.txt': {'status': 'deferred', 'reason': 'unsure'}})
|
|
753
|
+
result = self.cli('finish', '--plan', str(planpath), '--review', str(receipt), ok=False)
|
|
754
|
+
self.assertIn('cites a deferred path (mark the note deferred): note', result.stderr)
|
|
755
|
+
self.assertEqual(self.state(), before)
|
|
756
|
+
|
|
757
|
+
def test_partial_finish_keeps_lock_drift_and_rollback(self):
|
|
758
|
+
self.two_note_range()
|
|
759
|
+
planpath, plan = self.plan()
|
|
760
|
+
receipt = self.write_receipt(planpath, plan, paths={'other.txt': {'status': 'deferred', 'reason': 'later'}},
|
|
761
|
+
notes={'other': {'status': 'deferred', 'reason': 'later'}})
|
|
762
|
+
before = self.state()
|
|
763
|
+
lock = self.vault / '.knowledge/sync.lock'
|
|
764
|
+
lock.write_text('')
|
|
765
|
+
self.assertIn('lock already exists', self.cli('finish', '--plan', str(planpath), '--review', str(receipt), ok=False).stderr)
|
|
766
|
+
lock.unlink()
|
|
767
|
+
(self.repo / 'source.txt').write_text('raced') # drift after the scan
|
|
768
|
+
self.assertIn('plan changed', self.cli('finish', '--plan', str(planpath), '--review', str(receipt), ok=False).stderr)
|
|
769
|
+
(self.repo / 'source.txt').write_text('two')
|
|
770
|
+
self.assertEqual(self.state(), before)
|
|
771
|
+
real, calls = maintain.atomic, []
|
|
772
|
+
|
|
773
|
+
def failing(path, data):
|
|
774
|
+
calls.append(path.name)
|
|
775
|
+
if path.name == 'sources.json' and calls.count('sources.json') == 1:
|
|
776
|
+
raise OSError('disk full')
|
|
777
|
+
return real(path, data)
|
|
778
|
+
with mock.patch.object(maintain, 'atomic', failing), self.assertRaises(OSError):
|
|
779
|
+
maintain.finish(self.repo.resolve(), self.vault.resolve(), planpath, receipt)
|
|
780
|
+
self.assertEqual(self.state(), before) # published files restored, checkpoint never touched
|
|
781
|
+
self.assertFalse(lock.exists())
|
|
782
|
+
|
|
783
|
+
def test_finish_names_the_vault_commit_that_moved_head(self):
|
|
784
|
+
self.change()
|
|
785
|
+
planpath, plan = self.plan()
|
|
786
|
+
out, _ = self.receipt_cli(planpath)
|
|
787
|
+
(self.vault / 'note.md').write_text((self.vault / 'note.md').read_text() + 'prose\n')
|
|
788
|
+
self.git('add', '.')
|
|
789
|
+
self.git('commit', '-m', 'vault only')
|
|
790
|
+
head = self.git('rev-parse', 'HEAD').strip()
|
|
791
|
+
for result in (self.cli('finish', '--plan', str(planpath), '--review', str(out), ok=False),
|
|
792
|
+
self.cli('receipt', '--plan', str(planpath), '--out', str(out), ok=False)):
|
|
793
|
+
self.assertIn('every commit in between touches only excluded paths', result.stderr)
|
|
794
|
+
self.assertIn('scan --write-status', result.stderr)
|
|
795
|
+
self.assertIn('review_target: ' + head, result.stderr)
|
|
796
|
+
self.assertIn('regenerate the receipt', result.stderr)
|
|
797
|
+
# An application commit on top is the ordinary drift error instead.
|
|
798
|
+
(self.repo / 'source.txt').write_text('three')
|
|
799
|
+
self.git('commit', '-am', 'application')
|
|
800
|
+
for result in (self.cli('finish', '--plan', str(planpath), '--review', str(out), ok=False),):
|
|
801
|
+
self.assertIn('plan changed: head', result.stderr)
|
|
802
|
+
self.assertNotIn('excluded paths', result.stderr)
|
|
803
|
+
# The documented recovery works: rescan, retarget the run page, regenerate the receipt, finish.
|
|
804
|
+
self.git('reset', '--hard', head)
|
|
805
|
+
planpath, plan = self.plan()
|
|
806
|
+
self.assertEqual(plan['target'], head)
|
|
807
|
+
|
|
808
|
+
def test_documented_retarget_order_reaches_a_successful_finish(self):
|
|
809
|
+
self.change()
|
|
810
|
+
planpath, plan = self.plan()
|
|
811
|
+
out, _ = self.receipt_cli(planpath)
|
|
812
|
+
(self.vault / 'note.md').write_text((self.vault / 'note.md').read_text() + 'prose\n')
|
|
813
|
+
self.git('add', '.')
|
|
814
|
+
self.git('commit', '-m', 'vault only')
|
|
815
|
+
head = self.git('rev-parse', 'HEAD').strip()
|
|
816
|
+
message = self.cli('finish', '--plan', str(planpath), '--review', str(out), ok=False).stderr
|
|
817
|
+
# Follow the order the message and sync.md give: run page first, then scan, receipt, dispositions, finish.
|
|
818
|
+
self.assertLess(message.index('review_target: ' + head), message.index('scan --write-status'))
|
|
819
|
+
self.assertLess(message.index('scan --write-status'), message.index('"receipt"'))
|
|
820
|
+
run = self.vault / 'runs/review.md'
|
|
821
|
+
run.write_text(run.read_text().replace(plan['target'], head))
|
|
822
|
+
self.cli('scan', '--write-status')
|
|
823
|
+
planpath = self.vault / '.knowledge/sync-plan.json'
|
|
824
|
+
plan = json.loads(planpath.read_text())
|
|
825
|
+
self.assertEqual(plan['target'], head)
|
|
826
|
+
out, _ = self.receipt_cli(planpath)
|
|
827
|
+
data = json.loads(out.read_text())
|
|
828
|
+
data['paths'] = {p: {'status': 'reviewed', 'reason': 'read'} for p in data['paths']}
|
|
829
|
+
data['notes'] = {n: {**v, 'status': 'unchanged'} for n, v in data['notes'].items()}
|
|
830
|
+
out.write_text(json.dumps(data))
|
|
831
|
+
self.assertIn('review checkpoint advanced to ' + head, self.cli('finish', '--plan', str(planpath), '--review', str(out)).stdout)
|
|
832
|
+
|
|
833
|
+
def test_partial_finish_exit_status_is_not_the_usage_error_status(self):
|
|
834
|
+
self.assertEqual(maintain.PARTIAL_EXIT, 3)
|
|
835
|
+
self.assertEqual(subprocess.run(['python3', str(SCRIPT), 'finish'], capture_output=True).returncode, 2)
|
|
836
|
+
|
|
837
|
+
def test_receipt_reports_what_it_kept_and_reset(self):
|
|
838
|
+
self.two_note_range()
|
|
839
|
+
self.git('checkout', '--', 'other.txt')
|
|
840
|
+
planpath, plan = self.plan()
|
|
841
|
+
out, first = self.receipt_cli(planpath)
|
|
842
|
+
self.assertNotIn('dispositions', first.stdout) # nothing entered yet
|
|
843
|
+
data = json.loads(out.read_text())
|
|
844
|
+
for entry in data['paths'].values():
|
|
845
|
+
entry.update(status='reviewed', reason='read')
|
|
846
|
+
for entry in data['notes'].values():
|
|
847
|
+
entry['status'] = 'unchanged'
|
|
848
|
+
data['notes']['other'].update(status='deferred', reason='later')
|
|
849
|
+
out.write_text(json.dumps(data))
|
|
850
|
+
same = self.cli('receipt', '--plan', str(planpath), '--out', str(out)).stdout
|
|
851
|
+
self.assertIn('dispositions kept: 2 paths, 2 notes; reset: 0 paths, 0 notes; dropped (no longer in the plan): 0 paths, 0 notes', same)
|
|
852
|
+
self.assertEqual(json.loads(out.read_text())['notes']['other']['reason'], 'later')
|
|
853
|
+
# Change one note file and the plan: its disposition and every path disposition are reset, with reasons.
|
|
854
|
+
(self.vault / 'other.md').write_text((self.vault / 'other.md').read_text() + 'edited\n')
|
|
855
|
+
(self.repo / 'third.txt').write_text('x')
|
|
856
|
+
self.git('add', '.')
|
|
857
|
+
self.git('commit', '-m', 'third')
|
|
858
|
+
planpath, plan = self.plan()
|
|
859
|
+
result = self.cli('receipt', '--plan', str(planpath), '--out', str(out)).stdout
|
|
860
|
+
self.assertIn('kept: 0 paths, 1 notes', result)
|
|
861
|
+
self.assertIn('reset: 2 paths (plan changed since the receipt was written), 1 notes (note file changed: other)', result)
|
|
862
|
+
|
|
863
|
+
if __name__ == '__main__':
|
|
864
|
+
unittest.main()
|