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 ADDED
@@ -0,0 +1,3 @@
1
+ """docpolicy — portable documentation-drift enforcement."""
2
+
3
+ __version__ = "0.1.0"
docpolicy/__main__.py ADDED
@@ -0,0 +1,4 @@
1
+ from docpolicy.cli import main
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit(main())
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