#!/usr/bin/env python3 """Deterministic preflight for the opportunistic Codex documentation audit. This never changes docs or advances audit state. Semantic claims still need review. """ import argparse import json import posixpath import re import subprocess from datetime import datetime, timedelta, timezone from pathlib import Path from urllib.parse import unquote, urlsplit LINK = re.compile(r'(? now + timedelta(minutes=5) or not 1 <= interval <= 365: raise ValueError return state, now >= last + timedelta(days=interval) except (OSError, ValueError, TypeError, AttributeError): return {}, True def active_markdown(root): files = [root / 'README.md', root / 'AGENTS.md', *(root / 'docs').rglob('*.md')] return [path for path in files if path.is_file()] def broken_links(root, files): issues = [] for file in files: try: content = file.read_text(encoding='utf-8') except UnicodeError: issues.append(f'{file.relative_to(root)}: not UTF-8') continue for match in LINK.finditer(content): target = urlsplit(match.group(1)) if target.scheme or target.netloc or not target.path or target.path.startswith('/'): continue relative = unquote(target.path) normalized = posixpath.normpath(posixpath.join(file.parent.relative_to(root).as_posix(), relative)) if normalized.startswith('../') or normalized == '..': issues.append(f'{file.relative_to(root)}: link escapes repository: {relative}') continue destination = root / normalized if destination.is_dir(): destination /= 'README.md' if not destination.resolve().is_relative_to(root): issues.append(f'{file.relative_to(root)}: link resolves outside repository: {relative}') continue if not destination.is_file(): issues.append(f'{file.relative_to(root)}: missing {relative}') return issues def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--force', action='store_true', help='Show the review as due regardless of interval') parser.add_argument('--root', type=Path, default=Path(__file__).resolve().parent.parent) args = parser.parse_args() root = args.root.resolve() now = datetime.now(timezone.utc) state, due = audit_state(root, now) baseline = state.get('last_audited_commit') changed = git(root, 'diff', '--name-only', baseline, '--') if baseline else '' untracked = git(root, 'ls-files', '--others', '--exclude-standard') paths = sorted(set(changed.splitlines() + untracked.splitlines())) issues = broken_links(root, active_markdown(root)) print(f'UTC now: {now.isoformat(timespec="seconds")}') print(f'Audit due: {"yes" if due or args.force else "no"}' + (' (manual override)' if args.force else '')) print(f'Last successful audit: {state.get("last_successful_audit", "unknown")}') print(f'Changed paths since baseline: {len(paths)}') for path in paths[:100]: print(f' {path}') if len(paths) > 100: print(f' ... {len(paths) - 100} more') print(f'Broken relative links: {len(issues)}') for issue in issues: print(f' {issue}') return 1 if issues else 0 if __name__ == '__main__': raise SystemExit(main())