103 lines
4.1 KiB
Python
103 lines
4.1 KiB
Python
#!/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'(?<!!)\[[^\]]+\]\(([^\s)]+)(?:\s+[^)]*)?\)')
|
|
SHA = re.compile(r'^[0-9a-f]{40}([0-9a-f]{24})?$')
|
|
|
|
|
|
def git(root, *args):
|
|
result = subprocess.run(['git', *args], cwd=root, capture_output=True, text=True, check=False)
|
|
return result.stdout if result.returncode == 0 else ''
|
|
|
|
|
|
def audit_state(root, now):
|
|
path = root / 'docs' / '.audit-state.json'
|
|
try:
|
|
state = json.loads(path.read_text(encoding='utf-8'))
|
|
if state.get('schema_version') != 1 or not SHA.fullmatch(state.get('last_audited_commit', '')):
|
|
raise ValueError
|
|
last = datetime.fromisoformat(state['last_successful_audit'].replace('Z', '+00:00'))
|
|
interval = int(state.get('audit_interval_days', 14))
|
|
if last.tzinfo is None or last > 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())
|