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.
@@ -0,0 +1,182 @@
1
+ #!/usr/bin/env python3
2
+ """Inspect two committed vault histories without applying or writing changes."""
3
+ import argparse
4
+ import json
5
+ import os
6
+ from pathlib import Path, PurePosixPath
7
+ import re
8
+ import subprocess
9
+ import sys
10
+
11
+ sys.dont_write_bytecode = True
12
+ import knowledge
13
+
14
+
15
+ def git(repo, *args, allow_failure=False):
16
+ env = dict(os.environ, GIT_OPTIONAL_LOCKS='0', GIT_NO_REPLACE_OBJECTS='1',
17
+ GIT_NO_LAZY_FETCH='1', GIT_ALLOW_PROTOCOL='')
18
+ result = subprocess.run(['git', '-C', str(repo), '--no-optional-locks', *args],
19
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=env)
20
+ if result.returncode and not allow_failure:
21
+ raise ValueError('git ' + args[0] + ' failed: ' + result.stderr.decode('utf-8', 'replace').strip())
22
+ return result
23
+
24
+
25
+ def text(data):
26
+ return os.fsdecode(data)
27
+
28
+
29
+ def classify(path, prefix):
30
+ if not path.startswith(prefix + '/'):
31
+ return None
32
+ rel = path[len(prefix) + 1:]
33
+ parts = PurePosixPath(rel).parts
34
+ if knowledge.credential_path(rel) or any(p in {'.obsidian', '.trash'} for p in parts):
35
+ return None
36
+ if rel in ('.knowledge/review.json', '.knowledge/sources.json'):
37
+ return 'reviewed_state'
38
+ if rel in ('.knowledge/graph.json', 'Map.canvas', 'graph.html'):
39
+ return 'generated_view'
40
+ if rel in ('.knowledge/sync-plan.json', '.knowledge/sync-status.md', '.knowledge/sync.lock', 'sync.html'):
41
+ return 'local_status'
42
+ if rel.endswith('.md') and '.knowledge' not in parts:
43
+ return 'canonical_markdown'
44
+ return None
45
+
46
+
47
+ def changes(repo, base, commit, prefix):
48
+ raw = git(repo, 'diff', '--no-ext-diff', '--no-textconv', '--name-status', '-z', '-M', base, commit, '--').stdout.split(b'\0')
49
+ rows, i = [], 0
50
+ while i < len(raw) and raw[i]:
51
+ status = text(raw[i]); i += 1
52
+ count = 2 if status[0] in 'RC' else 1
53
+ paths = [text(item) for item in raw[i:i + count]]; i += count
54
+ categories = [classify(path, prefix) for path in paths]
55
+ visible = [(path, category) for path, category in zip(paths, categories) if category]
56
+ if visible:
57
+ rows.append({'status': status, 'paths': [item[0] for item in visible],
58
+ 'categories': [item[1] for item in visible]})
59
+ return rows
60
+
61
+
62
+ def tree(repo, commit, prefix):
63
+ # Read tree metadata only; never treat a Git object as a filesystem path.
64
+ raw = git(repo, '--literal-pathspecs', 'ls-tree', '-r', '-z', commit, '--', prefix).stdout
65
+ result = {}
66
+ for entry in raw.split(b'\0'):
67
+ if not entry:
68
+ continue
69
+ header, name = entry.split(b'\t', 1)
70
+ mode, kind, oid = header.split()
71
+ path = text(name)
72
+ category = classify(path, prefix)
73
+ if category:
74
+ result[path] = {'mode': text(mode), 'kind': text(kind), 'oid': text(oid), 'category': category}
75
+ return result
76
+
77
+
78
+ def ids(repo, entries):
79
+ result, skipped = {}, []
80
+ for path, item in entries.items():
81
+ if item['category'] != 'canonical_markdown':
82
+ continue
83
+ if item['kind'] != 'blob' or item['mode'] not in ('100644', '100755'):
84
+ skipped.append({'path': path, 'reason': 'not a regular file blob'})
85
+ continue
86
+ blob = git(repo, 'cat-file', 'blob', item['oid']).stdout
87
+ try:
88
+ content = blob.decode('utf-8')
89
+ front = re.match(r'\A---\s*\n(.*?)\n---\s*(?:\n|$)', content, re.S)
90
+ if not front or knowledge.has_conflict_markers(content):
91
+ raise ValueError('missing or conflicted frontmatter')
92
+ matches = re.findall(r'^id:\s*(.*?)\s*$', front.group(1), re.M)
93
+ if len(matches) != 1:
94
+ raise ValueError('missing or duplicate id')
95
+ ident = json.loads(matches[0])
96
+ if not isinstance(ident, str) or not re.fullmatch(r'[a-z0-9-]+', ident):
97
+ raise ValueError('invalid id')
98
+ result.setdefault(ident, []).append(path)
99
+ except (UnicodeDecodeError, ValueError):
100
+ skipped.append({'path': path, 'reason': 'cannot parse a stable id'})
101
+ return result, skipped
102
+
103
+
104
+ def inspect(repo, vault, ours, theirs):
105
+ if not repo.is_dir() or not vault.is_dir() or not vault.is_relative_to(repo) or repo == vault:
106
+ raise ValueError('repo and vault must be existing directories; vault must be inside repo')
107
+ config = git(repo, 'config', '--get-regexp', r'^(extensions\.partialclone|remote\..*\.promisor)$', allow_failure=True)
108
+ if config.returncode not in (0, 1):
109
+ raise ValueError('cannot inspect Git repository configuration')
110
+ if config.returncode == 0:
111
+ raise ValueError('partial or promisor repository requires full local history')
112
+ top = Path(text(git(repo, 'rev-parse', '--show-toplevel').stdout).strip()).resolve()
113
+ if repo != top:
114
+ raise ValueError('repo must be the worktree root')
115
+ if git(repo, 'rev-parse', '--is-shallow-repository').stdout.strip() == b'true':
116
+ raise ValueError('shallow history cannot establish a reliable merge base')
117
+ # --end-of-options prevents refs from becoming options. Verify explicit commit objects.
118
+ commits = []
119
+ for ref in (ours, theirs):
120
+ if not ref:
121
+ raise ValueError('refs must be nonempty')
122
+ resolved = git(repo, 'rev-parse', '--verify', '--end-of-options', ref + '^{commit}')
123
+ if b'ambiguous' in resolved.stderr.lower():
124
+ raise ValueError('ambiguous ref: ' + ref)
125
+ commits.append(text(resolved.stdout).strip())
126
+ result = git(repo, 'merge-base', '--all', *commits, allow_failure=True)
127
+ bases = text(result.stdout).splitlines()
128
+ if result.returncode or not bases:
129
+ raise ValueError('no common merge base (unrelated histories or invalid history)')
130
+ if len(bases) != 1:
131
+ raise ValueError('multiple merge bases; inspect history manually')
132
+ base, prefix = bases[0], vault.relative_to(repo).as_posix()
133
+ sides = {side: changes(repo, base, commit, prefix) for side, commit in zip(('ours', 'theirs'), commits)}
134
+ trees = {side: tree(repo, commit, prefix) for side, commit in zip(('base', 'ours', 'theirs'), (base, *commits))}
135
+ touched = {side: {path for row in rows for path, category in zip(row['paths'], row['categories']) if category == 'canonical_markdown'} for side, rows in sides.items()}
136
+ our_ids, our_skipped = ids(repo, trees['ours'])
137
+ their_ids, their_skipped = ids(repo, trees['theirs'])
138
+ duplicates = [{'id': ident, 'ours': sorted(our_ids[ident]), 'theirs': sorted(their_ids[ident])}
139
+ for ident in sorted(our_ids.keys() & their_ids.keys())
140
+ if any(a != b for a in our_ids[ident] for b in their_ids[ident])]
141
+ state = {}
142
+ for rel in ('.knowledge/review.json', '.knowledge/sources.json'):
143
+ path = prefix + '/' + rel
144
+ values = {side: trees[side].get(path) for side in ('base', 'ours', 'theirs')}
145
+ state[rel] = {'base': values['base'], 'ours': values['ours'], 'theirs': values['theirs'],
146
+ 'different': values['ours'] != values['theirs']}
147
+ unmerged_raw = git(repo, 'ls-files', '-u', '-z').stdout
148
+ unmerged = sorted({text(entry.split(b'\t', 1)[1]) for entry in unmerged_raw.split(b'\0') if entry and b'\t' in entry})
149
+ report = {'base': base, 'ours': commits[0], 'theirs': commits[1], 'changes': sides,
150
+ 'shared_canonical_paths': sorted(touched['ours'] & touched['theirs']),
151
+ 'duplicate_ids': duplicates, 'reviewed_state': state,
152
+ 'unmerged_index_paths': unmerged,
153
+ 'skipped_id_paths': {'ours': our_skipped, 'theirs': their_skipped}}
154
+ report['needs_review'] = bool(report['shared_canonical_paths'] or duplicates or unmerged or our_skipped or their_skipped or any(x['different'] for x in state.values()))
155
+ return report
156
+
157
+
158
+ def main():
159
+ parser = argparse.ArgumentParser(description=__doc__)
160
+ sub = parser.add_subparsers(dest='command', required=True)
161
+ inspect_parser = sub.add_parser('inspect')
162
+ inspect_parser.add_argument('--repo', required=True, type=Path)
163
+ inspect_parser.add_argument('--vault', required=True, type=Path)
164
+ inspect_parser.add_argument('--ours', required=True)
165
+ inspect_parser.add_argument('--theirs', required=True)
166
+ inspect_parser.add_argument('--json', action='store_true')
167
+ args = parser.parse_args()
168
+ report = inspect(args.repo.resolve(), args.vault.resolve(), args.ours, args.theirs)
169
+ if args.json:
170
+ print(json.dumps(report, ensure_ascii=True, indent=2))
171
+ else:
172
+ print('Needs review:' if report['needs_review'] else 'No overlapping candidates detected:')
173
+ print(json.dumps(report, ensure_ascii=True, indent=2))
174
+ return 0
175
+
176
+
177
+ if __name__ == '__main__':
178
+ try:
179
+ sys.exit(main())
180
+ except (OSError, ValueError, KeyError) as exc:
181
+ print('ERROR:', exc, file=sys.stderr)
182
+ sys.exit(1)