Files
Dashboard_Projects_Management/scripts/docs_audit.py
T

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())