docpolicy 0.1.0__py3-none-any.whl
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.
Potentially problematic release.
This version of docpolicy might be problematic. Click here for more details.
- docpolicy/__init__.py +3 -0
- docpolicy/__main__.py +4 -0
- docpolicy/checks.py +505 -0
- docpolicy/classify.py +37 -0
- docpolicy/cli.py +401 -0
- docpolicy/frontmatter.py +38 -0
- docpolicy/miniyaml.py +195 -0
- docpolicy/policy.py +172 -0
- docpolicy/triage.py +587 -0
- docpolicy-0.1.0.dist-info/METADATA +276 -0
- docpolicy-0.1.0.dist-info/RECORD +15 -0
- docpolicy-0.1.0.dist-info/WHEEL +5 -0
- docpolicy-0.1.0.dist-info/entry_points.txt +2 -0
- docpolicy-0.1.0.dist-info/licenses/LICENSE +21 -0
- docpolicy-0.1.0.dist-info/top_level.txt +1 -0
docpolicy/__init__.py
ADDED
docpolicy/__main__.py
ADDED
docpolicy/checks.py
ADDED
|
@@ -0,0 +1,505 @@
|
|
|
1
|
+
"""Checks C1-C12. check() = fast subset (per-call safe), audit() = full pass."""
|
|
2
|
+
|
|
3
|
+
import hashlib
|
|
4
|
+
import json
|
|
5
|
+
import os
|
|
6
|
+
import re
|
|
7
|
+
import shlex
|
|
8
|
+
import sqlite3
|
|
9
|
+
import subprocess
|
|
10
|
+
import time
|
|
11
|
+
from dataclasses import dataclass, field
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
|
|
14
|
+
from docpolicy import frontmatter as fm
|
|
15
|
+
from docpolicy.policy import SKIP_DIRS, Policy, PolicyError
|
|
16
|
+
|
|
17
|
+
MD_GLOB = "**/*.md"
|
|
18
|
+
ISSUE_REF_FALLBACK = re.compile(r"\b(?:[A-Z]{2,4})-(?P<num>\d+)\b")
|
|
19
|
+
MD_LINK = re.compile(r"\]\(([^)#\s]+?)(#[^)\s]*)?\)")
|
|
20
|
+
H1 = re.compile(r"^#\s+(.+)$", re.MULTILINE)
|
|
21
|
+
|
|
22
|
+
CODE_TITLES = {
|
|
23
|
+
"C1": "classification", "C2": "subject-uniqueness", "C3": "supersession",
|
|
24
|
+
"C4": "generated-freshness", "C5": "links", "C6": "issue-refs",
|
|
25
|
+
"C7": "ephemeral", "C8": "title-collision", "C9": "archive-hygiene",
|
|
26
|
+
"C10": "tag-collision", "C11": "inbox-age", "C12": "assertion-drift",
|
|
27
|
+
"FM": "frontmatter",
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@dataclass
|
|
32
|
+
class Finding:
|
|
33
|
+
code: str
|
|
34
|
+
severity: str
|
|
35
|
+
path: str # repo-relative posix, "" for repo-level findings
|
|
36
|
+
message: str
|
|
37
|
+
|
|
38
|
+
def as_dict(self):
|
|
39
|
+
return {"code": self.code, "severity": self.severity,
|
|
40
|
+
"path": self.path, "message": self.message}
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
@dataclass
|
|
44
|
+
class DocInfo:
|
|
45
|
+
rel: str
|
|
46
|
+
classes: list
|
|
47
|
+
fm: dict
|
|
48
|
+
body: str
|
|
49
|
+
mtime: float
|
|
50
|
+
had_fm: bool
|
|
51
|
+
fm_ok: bool
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def iter_markdown(repo: Path):
|
|
55
|
+
for p in sorted(repo.rglob("*.md")):
|
|
56
|
+
if any(part in SKIP_DIRS for part in p.relative_to(repo).parts):
|
|
57
|
+
continue
|
|
58
|
+
yield p
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def collect(repo: Path, policy: Policy, only: set | None = None) -> list[DocInfo]:
|
|
62
|
+
docs = []
|
|
63
|
+
for p in iter_markdown(repo):
|
|
64
|
+
rel = p.relative_to(repo).as_posix()
|
|
65
|
+
if only is not None and rel not in only:
|
|
66
|
+
continue
|
|
67
|
+
classes = policy.class_for(rel)
|
|
68
|
+
# Exempt docs (secrets, legal, generated-adjacent): classify the PATH only,
|
|
69
|
+
# never read content — covers .env files, key material, licence texts.
|
|
70
|
+
if classes and policy.class_mode(classes[0]) == "exempt":
|
|
71
|
+
docs.append(DocInfo(rel, classes, {}, "", 0.0, False, False))
|
|
72
|
+
continue
|
|
73
|
+
try:
|
|
74
|
+
text = p.read_text(encoding="utf-8", errors="replace")
|
|
75
|
+
except OSError as e:
|
|
76
|
+
docs.append(DocInfo(rel, classes, {}, "", 0.0, False, False))
|
|
77
|
+
continue
|
|
78
|
+
fmd, body, had = fm.parse(text)
|
|
79
|
+
ok = fmd is not None
|
|
80
|
+
docs.append(DocInfo(rel, classes, fmd if ok else {}, body,
|
|
81
|
+
p.stat().st_mtime, had, ok))
|
|
82
|
+
return docs
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _sev(policy: Policy, code: str, advisory: bool) -> str:
|
|
86
|
+
if advisory:
|
|
87
|
+
return "warn"
|
|
88
|
+
return policy.severity.get(code, "warn")
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _add(out: list, policy: Policy, code: str, path: str, msg: str, advisory: bool):
|
|
92
|
+
sev = _sev(policy, code, advisory)
|
|
93
|
+
if sev == "off":
|
|
94
|
+
return
|
|
95
|
+
out.append(Finding(code, sev, path, msg))
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def check_frontmatter(d: DocInfo, policy: Policy, out: list, advisory: bool):
|
|
99
|
+
"""Frontmatter requirements for canonical-mode docs (FM + C9 helpers)."""
|
|
100
|
+
modes = {policy.class_mode(c) for c in d.classes}
|
|
101
|
+
if "canonical" not in modes:
|
|
102
|
+
return
|
|
103
|
+
if (d.classes and not d.had_fm) or (d.had_fm and not d.fm_ok):
|
|
104
|
+
_add(out, policy, "FM", d.rel,
|
|
105
|
+
"malformed or missing frontmatter (need '---' block with subject + status)",
|
|
106
|
+
advisory)
|
|
107
|
+
return
|
|
108
|
+
subject = (d.fm.get("subject") or "").strip()
|
|
109
|
+
status = (d.fm.get("status") or "").strip()
|
|
110
|
+
if not subject:
|
|
111
|
+
_add(out, policy, "FM", d.rel, "missing frontmatter field: subject", advisory)
|
|
112
|
+
if not status:
|
|
113
|
+
_add(out, policy, "FM", d.rel, "missing frontmatter field: status", advisory)
|
|
114
|
+
elif status not in fm.KNOWN_STATUSES:
|
|
115
|
+
_add(out, policy, "FM", d.rel,
|
|
116
|
+
f"bad status {status!r} (allowed: {sorted(fm.KNOWN_STATUSES)})", advisory)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def check_supersession(docs: list[DocInfo], policy: Policy, out: list, advisory: bool,
|
|
120
|
+
restrict: set | None = None):
|
|
121
|
+
"""C2 (one active per subject) + C3 (superseded_by integrity).
|
|
122
|
+
|
|
123
|
+
restrict: when set (per-file / pre-write mode), only emit findings whose
|
|
124
|
+
path is in the target set — a pre-existing collision elsewhere in the repo
|
|
125
|
+
must not block an unrelated write."""
|
|
126
|
+
by_subject: dict[str, list[DocInfo]] = {}
|
|
127
|
+
by_rel = {d.rel: d for d in docs}
|
|
128
|
+
for d in docs:
|
|
129
|
+
if "canonical" not in {policy.class_mode(c) for c in d.classes}:
|
|
130
|
+
continue
|
|
131
|
+
status = (d.fm.get("status") or "").strip()
|
|
132
|
+
subject = (d.fm.get("subject") or "").strip()
|
|
133
|
+
if not subject or status not in fm.KNOWN_STATUSES:
|
|
134
|
+
continue # FM findings already cover this
|
|
135
|
+
if status == fm.STATUS_ACTIVE:
|
|
136
|
+
by_subject.setdefault(subject, []).append(d)
|
|
137
|
+
if status == fm.STATUS_SUPERSEDED:
|
|
138
|
+
if restrict is not None and d.rel not in restrict:
|
|
139
|
+
continue
|
|
140
|
+
target = (d.fm.get("superseded_by") or "").strip()
|
|
141
|
+
if not target:
|
|
142
|
+
_add(out, policy, "C3", d.rel,
|
|
143
|
+
f"status superseded but no superseded_by (subject {subject!r})",
|
|
144
|
+
advisory)
|
|
145
|
+
elif target not in by_rel:
|
|
146
|
+
_add(out, policy, "C3", d.rel,
|
|
147
|
+
f"superseded_by target not found: {target}", advisory)
|
|
148
|
+
else:
|
|
149
|
+
tstatus = (by_rel[target].fm.get("status") or "").strip()
|
|
150
|
+
tclasses = by_rel[target].classes
|
|
151
|
+
tmodes = {policy.class_mode(c) for c in tclasses}
|
|
152
|
+
if tstatus != fm.STATUS_ACTIVE and not (tmodes & {"ephemeral", "exempt", "append-only"}):
|
|
153
|
+
_add(out, policy, "C3", d.rel,
|
|
154
|
+
f"superseded_by target {target} is not active (status {tstatus!r})",
|
|
155
|
+
advisory)
|
|
156
|
+
for subject, actives in sorted(by_subject.items()):
|
|
157
|
+
if len(actives) > 1:
|
|
158
|
+
if restrict is not None and not any(d.rel in restrict for d in actives):
|
|
159
|
+
continue
|
|
160
|
+
_add(out, policy, "C2", actives[0].rel,
|
|
161
|
+
f"subject {subject!r} has {len(actives)} active docs: "
|
|
162
|
+
+ ", ".join(d.rel for d in actives)
|
|
163
|
+
+ " — exactly one must be active; set the rest superseded+superseded_by",
|
|
164
|
+
advisory)
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def check_generated(repo: Path, policy: Policy, out: list, advisory: bool):
|
|
168
|
+
"""C4: re-run each declared generator; restore original bytes afterwards."""
|
|
169
|
+
for c in policy.classes:
|
|
170
|
+
if c["mode"] != "generated" or not c["paths"] or not c.get("generator"):
|
|
171
|
+
continue
|
|
172
|
+
for pat in c["paths"]:
|
|
173
|
+
for p in sorted(repo.glob(pat)):
|
|
174
|
+
# `dir/**` matches the directory itself and its subdirectories, not just the
|
|
175
|
+
# files inside; only files have bytes to diff (a directory raised IsADirectoryError).
|
|
176
|
+
if not p.is_file():
|
|
177
|
+
continue
|
|
178
|
+
rel = p.relative_to(repo).as_posix()
|
|
179
|
+
before = p.read_bytes()
|
|
180
|
+
h_before = hashlib.sha256(before).hexdigest()
|
|
181
|
+
# No shell: the generator line is repo-owner config (same trust as a
|
|
182
|
+
# Makefile entry), but we still shlex-split it and expand ~/$VARS per
|
|
183
|
+
# token instead of handing it to a shell. Complex pipelines belong in
|
|
184
|
+
# a script; the policy points at the script.
|
|
185
|
+
try:
|
|
186
|
+
argv = [
|
|
187
|
+
os.path.expandvars(os.path.expanduser(tok))
|
|
188
|
+
for tok in shlex.split(c["generator"])
|
|
189
|
+
]
|
|
190
|
+
except ValueError as e:
|
|
191
|
+
_add(out, policy, "C4", rel,
|
|
192
|
+
f"cannot parse generator {c['generator']!r}: {e}", advisory)
|
|
193
|
+
continue
|
|
194
|
+
try:
|
|
195
|
+
subprocess.run(argv, cwd=repo, timeout=120, check=False,
|
|
196
|
+
capture_output=True)
|
|
197
|
+
except subprocess.TimeoutExpired:
|
|
198
|
+
_add(out, policy, "C4", rel, f"generator timed out: {c['generator']!r}",
|
|
199
|
+
advisory)
|
|
200
|
+
p.write_bytes(before)
|
|
201
|
+
continue
|
|
202
|
+
after = p.read_bytes() if p.exists() else b""
|
|
203
|
+
if hashlib.sha256(after).hexdigest() != h_before:
|
|
204
|
+
_add(out, policy, "C4", rel,
|
|
205
|
+
"generated file is stale — re-run: " + c["generator"], advisory)
|
|
206
|
+
p.write_bytes(before) # audit is side-effect free
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def check_links(d: DocInfo, repo: Path, policy: Policy, out: list, advisory: bool):
|
|
210
|
+
"""C5: relative markdown links must resolve."""
|
|
211
|
+
for m in MD_LINK.finditer(d.body):
|
|
212
|
+
target = m.group(1).strip()
|
|
213
|
+
if target.startswith(("http://", "https://", "mailto:", "#", "/")):
|
|
214
|
+
continue
|
|
215
|
+
resolved = (repo / d.rel).parent / target
|
|
216
|
+
if not resolved.exists():
|
|
217
|
+
_add(out, policy, "C5", d.rel, f"broken relative link: {target}", advisory)
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def check_issue_refs(docs: list[DocInfo], repo: Path, policy: Policy,
|
|
221
|
+
out: list, advisory: bool):
|
|
222
|
+
"""C6: <PROJECT>-NN references must exist in the configured task store.
|
|
223
|
+
Project codes come FROM the store (tasks.project), so 'SHA-256' or 'AVX-512'
|
|
224
|
+
cannot false-positive unless a project is literally named SHA or AVX."""
|
|
225
|
+
db = policy.sources.get("issues")
|
|
226
|
+
if db is None or not Path(db).is_file():
|
|
227
|
+
return
|
|
228
|
+
known: set[int] = set()
|
|
229
|
+
codes: set[str] = set()
|
|
230
|
+
try:
|
|
231
|
+
con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
|
|
232
|
+
known = {r[0] for r in con.execute("SELECT id FROM tasks")}
|
|
233
|
+
cols = {r[1] for r in con.execute("PRAGMA table_info(tasks)")}
|
|
234
|
+
if "project" in cols:
|
|
235
|
+
codes = {str(r[0]).upper() for r in con.execute("SELECT DISTINCT project FROM tasks")
|
|
236
|
+
if r[0]}
|
|
237
|
+
con.close()
|
|
238
|
+
except sqlite3.Error as e:
|
|
239
|
+
_add(out, policy, "C6", "", f"cannot read issue store {db}: {e}", advisory)
|
|
240
|
+
return
|
|
241
|
+
if codes:
|
|
242
|
+
ref = re.compile(r"\b(?:" + "|".join(sorted(codes, key=len, reverse=True)) + r")-(?P<num>\d+)\b")
|
|
243
|
+
else:
|
|
244
|
+
ref = ISSUE_REF_FALLBACK
|
|
245
|
+
for d in docs:
|
|
246
|
+
for m in ref.finditer(d.body):
|
|
247
|
+
n = int(m.group("num"))
|
|
248
|
+
if n not in known:
|
|
249
|
+
_add(out, policy, "C6", d.rel,
|
|
250
|
+
f"issue reference {m.group(0)} not found in task store", advisory)
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
def check_ephemeral(d: DocInfo, repo: Path, policy: Policy, out: list, advisory: bool):
|
|
254
|
+
"""C7: ephemeral docs must be fresh and point at a canonical doc."""
|
|
255
|
+
for cid in d.classes:
|
|
256
|
+
c = policy.classes_by_id.get(cid, {})
|
|
257
|
+
if c.get("mode") != "ephemeral":
|
|
258
|
+
continue
|
|
259
|
+
max_age = c.get("max_age_days")
|
|
260
|
+
if max_age and d.mtime:
|
|
261
|
+
age_days = (time.time() - d.mtime) / 86400
|
|
262
|
+
if age_days > max_age:
|
|
263
|
+
_add(out, policy, "C7", d.rel,
|
|
264
|
+
f"ephemeral doc is {age_days:.0f}d old (max {max_age}) — promote to the "
|
|
265
|
+
"canonical doc or tombstone it to a pointer", advisory)
|
|
266
|
+
if c.get("require_pointer"):
|
|
267
|
+
has_pointer = any(
|
|
268
|
+
not t.startswith(("http", "mailto:")) for t in MD_LINK.findall(d.body)
|
|
269
|
+
if isinstance(t, str)
|
|
270
|
+
) or bool(re.search(r"\]\([^)#\s]+\.md", d.body))
|
|
271
|
+
if not has_pointer:
|
|
272
|
+
_add(out, policy, "C7", d.rel,
|
|
273
|
+
"ephemeral doc lacks a pointer to a canonical doc", advisory)
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def check_titles(docs: list[DocInfo], policy: Policy, out: list, advisory: bool):
|
|
277
|
+
"""C8: duplicate H1 across canonical docs (advisory)."""
|
|
278
|
+
seen: dict[str, list[str]] = {}
|
|
279
|
+
for d in docs:
|
|
280
|
+
if "canonical" not in {policy.class_mode(c) for c in d.classes}:
|
|
281
|
+
continue
|
|
282
|
+
m = H1.search(d.body)
|
|
283
|
+
if m:
|
|
284
|
+
seen.setdefault(m.group(1).strip().lower(), []).append(d.rel)
|
|
285
|
+
for title, rels in sorted(seen.items()):
|
|
286
|
+
if len(rels) > 1:
|
|
287
|
+
_add(out, policy, "C8", rels[0],
|
|
288
|
+
f"duplicate H1 {title!r} in: {', '.join(rels)} — one subject, one doc?",
|
|
289
|
+
advisory)
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def check_archive(d: DocInfo, policy: Policy, out: list, advisory: bool):
|
|
293
|
+
"""C9: archive-class docs must not be active."""
|
|
294
|
+
for cid in d.classes:
|
|
295
|
+
if policy.class_mode(cid) == "archive":
|
|
296
|
+
status = (d.fm.get("status") or "").strip()
|
|
297
|
+
if status and status not in (fm.STATUS_SUPERSEDED, fm.STATUS_ARCHIVED, fm.STATUS_DRAFT):
|
|
298
|
+
_add(out, policy, "C9", d.rel,
|
|
299
|
+
f"archive doc has status {status!r} — must be superseded or archived",
|
|
300
|
+
advisory)
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
def check_inbox(d: DocInfo, policy: Policy, out: list, advisory: bool):
|
|
304
|
+
"""C11: captures must not sit in the inbox forever (triaged or not, they age).
|
|
305
|
+
|
|
306
|
+
Inbox docs are deliberately exempt from FM/C2/C9 — zero friction at capture
|
|
307
|
+
time is the point. The cost is surfaced here instead: an old capture is a
|
|
308
|
+
finding, and the fix is `docpolicy triage --apply` (or delete it)."""
|
|
309
|
+
for cid in d.classes:
|
|
310
|
+
c = policy.classes_by_id.get(cid, {})
|
|
311
|
+
if c.get("mode") != "inbox":
|
|
312
|
+
continue
|
|
313
|
+
max_age = c.get("max_age_days")
|
|
314
|
+
if max_age and d.mtime:
|
|
315
|
+
age_days = (time.time() - d.mtime) / 86400
|
|
316
|
+
if age_days > max_age:
|
|
317
|
+
_add(out, policy, "C11", d.rel,
|
|
318
|
+
f"inbox capture is {age_days:.0f}d old (max {max_age}) — "
|
|
319
|
+
"run: docpolicy triage --repo . (or delete it)", advisory)
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
def check_tag_collisions(docs: list[DocInfo], policy: Policy, out: list, advisory: bool):
|
|
323
|
+
"""C10: two ACTIVE canonical docs sharing 2+ tags claim one topic (advisory).
|
|
324
|
+
|
|
325
|
+
Subject is document identity (one active per subject, C2), so topic overlap
|
|
326
|
+
is invisible to C2 — tags are where it shows. One shared tag is adjacency
|
|
327
|
+
(promotion deliberately links related docs); two or more is the merge
|
|
328
|
+
signal, and merging needs judgement, so it warns rather than errors.
|
|
329
|
+
"""
|
|
330
|
+
actives = []
|
|
331
|
+
for d in docs:
|
|
332
|
+
if "canonical" not in {policy.class_mode(c) for c in d.classes}:
|
|
333
|
+
continue
|
|
334
|
+
if (d.fm.get("status") or "").strip() != fm.STATUS_ACTIVE:
|
|
335
|
+
continue
|
|
336
|
+
tags = d.fm.get("tags")
|
|
337
|
+
if isinstance(tags, str):
|
|
338
|
+
t = tags.strip()
|
|
339
|
+
tags = [x.strip().strip("'\"") for x in t[1:-1].split(",")] if t.startswith("[") else [t]
|
|
340
|
+
if not isinstance(tags, list):
|
|
341
|
+
continue
|
|
342
|
+
tagset = {str(t).strip().lower() for t in tags if str(t).strip()}
|
|
343
|
+
if tagset:
|
|
344
|
+
actives.append((d.rel, tagset))
|
|
345
|
+
for i, (rel_a, tags_a) in enumerate(actives):
|
|
346
|
+
for rel_b, tags_b in actives[i + 1:]:
|
|
347
|
+
shared = sorted(tags_a & tags_b)
|
|
348
|
+
if len(shared) >= 2:
|
|
349
|
+
_add(out, policy, "C10", rel_a,
|
|
350
|
+
f"shares {len(shared)} tags with {rel_b} ({', '.join(shared)}) — "
|
|
351
|
+
"same topic? merge into one doc, or drop the shared tags",
|
|
352
|
+
advisory)
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
def check(repo: Path, policy: Policy, only: set | None = None,
|
|
356
|
+
advisory: bool = False, stdin_file: str | None = None,
|
|
357
|
+
stdin_text: str | None = None) -> list[Finding]:
|
|
358
|
+
"""Fast pass: C1/FM/C9/C7 on the target set, C2/C3 across the whole repo.
|
|
359
|
+
|
|
360
|
+
stdin_file + stdin_text evaluate a VIRTUAL doc (the about-to-be-written
|
|
361
|
+
content) instead of the on-disk state — the pre-write hook path. C2/C3
|
|
362
|
+
still scan every doc so cross-doc collisions are caught.
|
|
363
|
+
"""
|
|
364
|
+
out: list[Finding] = []
|
|
365
|
+
all_docs = collect(repo, policy)
|
|
366
|
+
if stdin_file is not None and stdin_text is not None:
|
|
367
|
+
fmd, body, had = fm.parse(stdin_text)
|
|
368
|
+
virtual = DocInfo(rel=stdin_file, classes=policy.class_for(stdin_file),
|
|
369
|
+
fm=fmd if fmd is not None else {}, body=body, mtime=0.0,
|
|
370
|
+
had_fm=had, fm_ok=fmd is not None)
|
|
371
|
+
by_rel = {d.rel: d for d in all_docs}
|
|
372
|
+
by_rel[stdin_file] = virtual
|
|
373
|
+
docs = list(by_rel.values())
|
|
374
|
+
targets = [virtual]
|
|
375
|
+
restrict = {stdin_file}
|
|
376
|
+
else:
|
|
377
|
+
docs = all_docs
|
|
378
|
+
targets = all_docs if only is None else [d for d in docs if d.rel in only]
|
|
379
|
+
restrict = None if only is None else set(only)
|
|
380
|
+
for d in targets:
|
|
381
|
+
if not d.classes and not policy.severity.get("C1") == "off":
|
|
382
|
+
_add(out, policy, "C1", d.rel, "unclassified: no class pattern matches",
|
|
383
|
+
advisory)
|
|
384
|
+
check_frontmatter(d, policy, out, advisory)
|
|
385
|
+
check_archive(d, policy, out, advisory)
|
|
386
|
+
check_ephemeral(d, repo, policy, out, advisory)
|
|
387
|
+
check_inbox(d, policy, out, advisory)
|
|
388
|
+
check_supersession(docs, policy, out, advisory, restrict=restrict)
|
|
389
|
+
return out
|
|
390
|
+
|
|
391
|
+
|
|
392
|
+
def _norm_assert(v) -> str:
|
|
393
|
+
"""Normalize an assertion value for comparison (numbers cross-type equal)."""
|
|
394
|
+
if isinstance(v, bool):
|
|
395
|
+
return "true" if v else "false"
|
|
396
|
+
if isinstance(v, (int, float)):
|
|
397
|
+
f = float(v)
|
|
398
|
+
return str(int(f)) if f == int(f) and abs(f) < 1e15 else repr(f)
|
|
399
|
+
return str(v).strip()
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
def _assert_match(reality, expected) -> bool:
|
|
403
|
+
"""Scalar: numeric-then-string equality. List expected: subset semantics —
|
|
404
|
+
every asserted item must exist in reality (reality may know more)."""
|
|
405
|
+
if isinstance(expected, list):
|
|
406
|
+
if not isinstance(reality, list):
|
|
407
|
+
return False
|
|
408
|
+
real = {_norm_assert(x) for x in reality}
|
|
409
|
+
return all(_norm_assert(x) in real for x in expected)
|
|
410
|
+
if isinstance(reality, list):
|
|
411
|
+
return _norm_assert(reality[0]) == _norm_assert(expected) if reality else False
|
|
412
|
+
ea, ra = _norm_assert(expected), _norm_assert(reality)
|
|
413
|
+
if ea == ra:
|
|
414
|
+
return True
|
|
415
|
+
try:
|
|
416
|
+
return float(ea) == float(ra)
|
|
417
|
+
except ValueError:
|
|
418
|
+
return False
|
|
419
|
+
|
|
420
|
+
|
|
421
|
+
def check_assertions(docs: list[DocInfo], repo: Path, policy: Policy, out: list,
|
|
422
|
+
advisory: bool):
|
|
423
|
+
"""C12: `assert:` frontmatter on canonical docs must match machine facts.
|
|
424
|
+
|
|
425
|
+
The generated class declares `facts:` (a JSON file its generator writes).
|
|
426
|
+
Every canonical doc may carry an `assert:` mapping; each key must either be
|
|
427
|
+
absent from facts (never asserted about) or equal reality. This is the
|
|
428
|
+
loop-closer: a spec that contradicts what the repo actually is becomes a
|
|
429
|
+
finding, not a silent prose drift."""
|
|
430
|
+
facts_rel = None
|
|
431
|
+
for c in policy.classes:
|
|
432
|
+
if c["mode"] == "generated" and c.get("facts"):
|
|
433
|
+
facts_rel = str(c["facts"])
|
|
434
|
+
break
|
|
435
|
+
if facts_rel is None:
|
|
436
|
+
return
|
|
437
|
+
facts_path = Path(os.path.expanduser(facts_rel))
|
|
438
|
+
if not facts_path.is_absolute():
|
|
439
|
+
facts_path = repo / facts_path
|
|
440
|
+
facts: dict = {}
|
|
441
|
+
if not facts_path.is_file():
|
|
442
|
+
_add(out, policy, "C12", facts_rel,
|
|
443
|
+
"facts file missing — run the generator (see the generated class)", advisory)
|
|
444
|
+
return
|
|
445
|
+
try:
|
|
446
|
+
loaded = json.loads(facts_path.read_text(encoding="utf-8"))
|
|
447
|
+
if isinstance(loaded, dict):
|
|
448
|
+
facts = loaded
|
|
449
|
+
else:
|
|
450
|
+
raise ValueError("facts root must be a JSON object")
|
|
451
|
+
except (OSError, ValueError) as e:
|
|
452
|
+
_add(out, policy, "C12", facts_rel, f"facts file unreadable: {e}", advisory)
|
|
453
|
+
return
|
|
454
|
+
for d in docs:
|
|
455
|
+
if "canonical" not in {policy.class_mode(c) for c in d.classes}:
|
|
456
|
+
continue
|
|
457
|
+
assert_map = d.fm.get("assert") if isinstance(d.fm, dict) else None
|
|
458
|
+
if not isinstance(assert_map, dict):
|
|
459
|
+
continue
|
|
460
|
+
for key in sorted(assert_map):
|
|
461
|
+
expected = assert_map[key]
|
|
462
|
+
if key not in facts:
|
|
463
|
+
_add(out, policy, "C12", d.rel,
|
|
464
|
+
f"assertion {key!r}: not present in {facts_rel} — the generator "
|
|
465
|
+
"does not extract this fact yet", advisory)
|
|
466
|
+
continue
|
|
467
|
+
if not _assert_match(facts[key], expected):
|
|
468
|
+
_add(out, policy, "C12", d.rel,
|
|
469
|
+
f"assertion {key!r}: doc expects {expected!r}, repo reality is "
|
|
470
|
+
f"{facts[key]!r}", advisory)
|
|
471
|
+
|
|
472
|
+
|
|
473
|
+
def _dedupe(out: list[Finding]) -> list[Finding]:
|
|
474
|
+
seen = set()
|
|
475
|
+
unique = []
|
|
476
|
+
for f in out:
|
|
477
|
+
key = (f.code, f.path, f.message)
|
|
478
|
+
if key not in seen:
|
|
479
|
+
seen.add(key)
|
|
480
|
+
unique.append(f)
|
|
481
|
+
return unique
|
|
482
|
+
|
|
483
|
+
|
|
484
|
+
def audit(repo: Path, policy: Policy, advisory: bool = False) -> list[Finding]:
|
|
485
|
+
"""Full pass: everything in check() plus C4-C8, C10, C12. Side-effect free."""
|
|
486
|
+
out = check(repo, policy, advisory=advisory)
|
|
487
|
+
docs = collect(repo, policy)
|
|
488
|
+
check_generated(repo, policy, out, advisory)
|
|
489
|
+
for d in docs:
|
|
490
|
+
check_links(d, repo, policy, out, advisory)
|
|
491
|
+
check_issue_refs(docs, repo, policy, out, advisory)
|
|
492
|
+
check_titles(docs, policy, out, advisory)
|
|
493
|
+
check_tag_collisions(docs, policy, out, advisory)
|
|
494
|
+
check_assertions(docs, repo, policy, out, advisory)
|
|
495
|
+
return _dedupe(out)
|
|
496
|
+
|
|
497
|
+
|
|
498
|
+
def summarize(findings: list[Finding]) -> dict:
|
|
499
|
+
by_sev = {"error": 0, "warn": 0}
|
|
500
|
+
by_code: dict[str, int] = {}
|
|
501
|
+
for f in findings:
|
|
502
|
+
by_sev[f.severity] = by_sev.get(f.severity, 0) + 1
|
|
503
|
+
by_code[f.code] = by_code.get(f.code, 0) + 1
|
|
504
|
+
return {"total": len(findings), "errors": by_sev["error"],
|
|
505
|
+
"warnings": by_sev["warn"], "by_code": by_code}
|
docpolicy/classify.py
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""Path classification: gitignore-style ** globs -> regex, matched on posix relpaths."""
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def glob_to_regex(pattern: str) -> re.Pattern:
|
|
7
|
+
"""Convert a glob with ** support into a compiled regex.
|
|
8
|
+
|
|
9
|
+
'docs/specs/*.md' matches one level under docs/specs/
|
|
10
|
+
'docs/**/*.md' matches any depth
|
|
11
|
+
'**/archive/**' matches any path containing an archive segment
|
|
12
|
+
"""
|
|
13
|
+
out = []
|
|
14
|
+
i = 0
|
|
15
|
+
pat = pattern.strip().lstrip("/")
|
|
16
|
+
while i < len(pat):
|
|
17
|
+
c = pat[i]
|
|
18
|
+
if pat[i : i + 3] == "**/":
|
|
19
|
+
out.append("(?:.*/)?")
|
|
20
|
+
i += 3
|
|
21
|
+
elif pat[i : i + 2] == "**":
|
|
22
|
+
out.append(".*")
|
|
23
|
+
i += 2
|
|
24
|
+
elif c == "*":
|
|
25
|
+
out.append("[^/]*")
|
|
26
|
+
i += 1
|
|
27
|
+
elif c == "?":
|
|
28
|
+
out.append("[^/]")
|
|
29
|
+
i += 1
|
|
30
|
+
else:
|
|
31
|
+
out.append(re.escape(c))
|
|
32
|
+
i += 1
|
|
33
|
+
return re.compile("^" + "".join(out) + "$")
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def match(pattern: str, rel_posix: str) -> bool:
|
|
37
|
+
return glob_to_regex(pattern).match(rel_posix) is not None
|