git documentation feature
This commit is contained in:
@@ -0,0 +1,102 @@
|
||||
#!/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())
|
||||
Reference in New Issue
Block a user