spb/modelmap Public License

1#!/usr/bin/env python32# =============================================================================3#  Project   : modelmap4#  File      : tools/check_headers.py5#  Purpose   : Fail if any tracked source file lacks the mandatory author header6#  Author    : Simon-Pierre Boucher7#  Contact   : contact@spboucher.ai8#  Website   : https://modelmap.io9#  Created   : 2026-08-1210#  Modified  : 2026-08-1211#  Platform  : macOS / Apple Silicon (arm64)12#  License   : All rights reserved (research code)13# =============================================================================14"""Header compliance checker (charter §0.1).1516Scans git-tracked source files and verifies each begins (after an optional17shebang) with the standardized author header, or — for markdown — with YAML18front matter carrying the author fields. Exits non-zero on any violation,19so it can gate commits.20"""2122from __future__ import annotations2324import subprocess25import sys26from pathlib import Path2728ROOT = Path(__file__).resolve().parent.parent2930HASH_COMMENT_EXT = {".py", ".sh", ".zsh", ".yaml", ".yml", ".toml", ".cff"}31SLASH_COMMENT_EXT = {".c", ".cpp", ".h", ".hpp", ".metal", ".swift", ".m", ".js", ".ts", ".css"}32MARKDOWN_EXT = {".md"}33HASH_COMMENT_NAMES = {"Makefile"}3435REQUIRED_TOKENS = (36    "Project   : modelmap",37    "Author    : Simon-Pierre Boucher",38    "Contact   : contact@spboucher.ai",39)40MD_REQUIRED_TOKENS = (41    "project: modelmap",42    "author: Simon-Pierre Boucher",43    "contact: contact@spboucher.ai",44)4546# Files that carry no comments / are data or licenses. CLAUDE.md is the47# authoritative charter (its content is the spec itself, not a research doc).48# README.md is the forge-rendered public summary — front matter would display49# as raw text; author attribution lives in its visible body instead.50EXEMPT = {"LICENSE", ".gitignore", "package.json", "package-lock.json", "CLAUDE.md", "README.md"}515253def tracked_files() -> list[Path]:54    out = subprocess.run(55        ["git", "ls-files"], cwd=ROOT, capture_output=True, text=True, check=True56    ).stdout57    return [ROOT / line for line in out.splitlines() if line.strip()]585960def head_of(path: Path, n_bytes: int = 4096) -> str:61    try:62        return path.read_text(errors="replace")[:n_bytes]63    except OSError:64        return ""656667def check(path: Path) -> str | None:68    """Return an error string, or None if compliant / not applicable."""69    name = path.name70    if name in EXEMPT:71        return None72    ext = path.suffix.lower()73    text = head_of(path)74    if text.startswith("#!"):75        text = text.split("\n", 1)[1] if "\n" in text else ""7677    if ext in MARKDOWN_EXT:78        if not text.lstrip().startswith("---"):79            return "missing YAML front matter"80        missing = [t for t in MD_REQUIRED_TOKENS if t not in text]81        return f"front matter missing: {', '.join(missing)}" if missing else None8283    if ext in HASH_COMMENT_EXT or ext in SLASH_COMMENT_EXT or name in HASH_COMMENT_NAMES:84        missing = [t for t in REQUIRED_TOKENS if t not in text]85        return f"header missing: {', '.join(missing)}" if missing else None8687    return None  # extension not governed by the header rule888990def main() -> int:91    errors: list[tuple[Path, str]] = []92    for f in tracked_files():93        if not f.is_file():94            continue95        err = check(f)96        if err:97            errors.append((f, err))98    if errors:99        print(f"check_headers: {len(errors)} non-compliant file(s):")100        for f, err in errors:101            print(f"  {f.relative_to(ROOT)}: {err}")102        return 1103    print("check_headers: all tracked source files carry the mandatory header.")104    return 0105106107if __name__ == "__main__":108    sys.exit(main())109