repotemplates 0.13.0__py3-none-any.whl

repotemplates/__init__.py

@@ -0,0 +1 @@
+"""Scaffold repos from repotemplates and check them against it."""

repotemplates/__main__.py

@@ -0,0 +1,3 @@
+from repotemplates.cli import main
+
+main()

repotemplates/check.py

@@ -0,0 +1,330 @@
+"""Compare a repo's template-owned files with the template. Read-only."""
+
+from __future__ import annotations
+
+import subprocess
+import tomllib
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from repotemplates.classes import (
+    CONFIG,
+    GITIGNORE,
+    IGNORE,
+    PINNED,
+    attribute_gaps,
+    compare_pins,
+    ignore_gaps,
+)
+from repotemplates.manifest import (
+    SETTINGS,
+    SETTINGS_HOOKS,
+    DirSource,
+    Manifest,
+    file_digest,
+    file_path,
+    fingerprint,
+)
+from repotemplates.versions import is_prerelease, sort_key
+
+__all__ = [
+    "CLAUDE_SETTINGS",
+    "KINDS",
+    "RAISABLE_PINS",
+    "FileReport",
+    "RepoReport",
+    "StampReport",
+    "check_fleet",
+    "check_repo",
+    "latest_release",
+]
+
+# The stamp table, and the name it had before the rename in 0.12.0.
+STAMP_TABLES = ("repotemplates", "proj-template")
+CLAUDE_SETTINGS = (SETTINGS, ".claude/settings.local.json")
+# The file classes, in report order
+KINDS = ("hook-script", "hook-entries", "pinned", "config", "ignore")
+# Pin verdicts that leave a pinned file behind the template. upgrade raises
+# the raisable ones; ``differs`` (a pin that is not a version) needs a person.
+RAISABLE_PINS = ("behind", "mixed")
+STALE_PINS = (*RAISABLE_PINS, "differs")
+DEPENDABOT = ".github/dependabot.yml"
+RENOVATE = (".github/renovate.json", ".github/workflows/renovate.yml")
+
+
+@dataclass(frozen=True)
+class StampReport:
+    """``status``: latest, behind, ahead, alpha, unknown, unreadable, or missing.
+
+    ``omit`` is the stamp table's list of template files the repo leaves out on
+    purpose.
+    """
+
+    version: str | None
+    table: str | None
+    status: str
+    latest: str | None
+    omit: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class FileReport:
+    """``status``: current, matches, retired, one-off, partial, missing, omitted,
+    or unreadable.
+
+    ``matches`` and ``retired`` name a release: the newest one the file equals.
+    ``retired`` is a path the template no longer ships. ``partial`` is an ignore
+    file missing some of the template's rules, listed in ``detail``. ``omitted``
+    is a file the repo leaves out by design: declared in the stamp's ``omit``, or
+    the Dependabot or Renovate file of a repo that uses the other.
+    ``pins`` is set for a pinned file: same, ahead, behind, mixed, or differs.
+    ``waived`` lists an ignore file's template rules the repo leaves out because
+    it tracks paths they would ignore.
+    """
+
+    path: str
+    kind: str
+    status: str
+    release: str | None = None
+    git: str | None = None
+    pins: str | None = None
+    detail: tuple[str, ...] = ()
+    waived: tuple[str, ...] = ()
+
+    @property
+    def current(self) -> bool:
+        return self.status in ("current", "omitted") and self.pins not in STALE_PINS
+
+
+@dataclass(frozen=True)
+class RepoReport:
+    name: str
+    path: str
+    stamp: StampReport
+    files: list[FileReport] = field(default_factory=list)
+    settings: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def current(self) -> bool:
+        return self.stamp.status == "latest" and all(f.current for f in self.files)
+
+    def to_dict(self) -> dict[str, object]:
+        out = asdict(self)
+        out["current"] = self.current
+        return out
+
+
+def latest_release(manifest: Manifest, installed: str) -> str | None:
+    """The newest stable release this install knows: its own, or a tagged one."""
+    candidates = list(manifest.releases)
+    if not is_prerelease(installed):
+        candidates.append(installed)
+    keyed = [
+        (key, v) for v in candidates if (key := sort_key(v)) and not is_prerelease(v)
+    ]
+    return max(keyed)[1] if keyed else None
+
+
+def read_stamp(repo: Path, latest: str | None) -> StampReport:
+    pyproject = repo / "pyproject.toml"
+    if not pyproject.is_file():
+        return StampReport(None, None, "missing", latest)
+    try:
+        data = tomllib.loads(pyproject.read_text())
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError):
+        return StampReport(None, None, "unreadable", latest)
+    tool = data.get("tool", {})
+    if not isinstance(tool, dict):
+        return StampReport(None, None, "unreadable", latest)
+    for table in STAMP_TABLES:
+        if table not in tool:
+            continue
+        # A stamp table with no string version is malformed, not missing
+        section = tool[table]
+        value = section.get("version") if isinstance(section, dict) else None
+        if not isinstance(value, str):
+            return StampReport(None, f"tool.{table}", "unreadable", latest)
+        omit = section.get("omit", [])
+        if not isinstance(omit, list) or not all(isinstance(o, str) for o in omit):
+            return StampReport(value, f"tool.{table}", "unreadable", latest)
+        status = _stamp_status(value, latest)
+        return StampReport(value, f"tool.{table}", status, latest, tuple(omit))
+    return StampReport(None, None, "missing", latest)
+
+
+def _stamp_status(value: str, latest: str | None) -> str:
+    key = sort_key(value)
+    if key is None:
+        return "unknown"
+    if is_prerelease(value):
+        return "alpha"
+    latest_key = sort_key(latest) if latest else None
+    if latest_key is None or key == latest_key:
+        return "latest"
+    return "behind" if key < latest_key else "ahead"
+
+
+def _git(repo: Path, *args: str) -> int:
+    try:
+        return subprocess.run(["git", *args], cwd=repo, capture_output=True).returncode
+    except FileNotFoundError:
+        # No git on PATH: every query fails, so git_state reports "no git"
+        return 127
+
+
+def git_state(repo: Path, path: str) -> str:
+    """tracked, ignored, untracked, absent, or no git."""
+    if not (repo / path).exists():
+        return "absent"
+    if _git(repo, "rev-parse", "--git-dir") != 0:
+        return "no git"
+    if _git(repo, "ls-files", "--error-unmatch", "--", path) == 0:
+        return "tracked"
+    if _git(repo, "check-ignore", "-q", "--", path) == 0:
+        return "ignored"
+    return "untracked"
+
+
+def _kind(key: str) -> str:
+    if key == SETTINGS_HOOKS:
+        return "hook-entries"
+    if key in PINNED:
+        return "pinned"
+    if key in CONFIG:
+        return "config"
+    if key in IGNORE:
+        return "ignore"
+    return "hook-script"
+
+
+def _repo_digest(repo: Path, key: str) -> tuple[str | None, bool]:
+    """The repo's digest for ``key``, and whether the file could be read."""
+    try:
+        raw = DirSource(repo).read(file_path(key))
+    except OSError:
+        return None, False
+    if raw is None:
+        return None, True
+    try:
+        return file_digest(key, raw), True
+    except ValueError:
+        return None, False
+
+
+def _ordered(keys: set[str]) -> list[str]:
+    return sorted(keys, key=lambda k: (KINDS.index(_kind(k)), k))
+
+
+def omitted(repo: Path, declared: tuple[str, ...]) -> set[str]:
+    """Paths the repo leaves out by design: declared, or the other updater's files.
+
+    A repo on Renovate has no use for the Dependabot file, and one on Dependabot
+    none for the Renovate pair, so the file present names the choice.
+    """
+    out = set(declared)
+    if (repo / DEPENDABOT).is_file():
+        out.update(RENOVATE)
+    elif any((repo / path).is_file() for path in RENOVATE):
+        out.add(DEPENDABOT)
+    return out
+
+
+def _pins(repo: Path, template: Path, key: str) -> str | None:
+    if key not in PINNED:
+        return None
+    try:
+        ours = (repo / key).read_text()
+        theirs = (template / key).read_text()
+    except (OSError, UnicodeDecodeError):
+        return None
+    return compare_pins(ours, theirs)
+
+
+def _ignore_report(repo: Path, template: Path, path: str, skip: set[str]) -> FileReport:
+    git = git_state(repo, path)
+    present = (repo / path).is_file()
+    if not present and path in skip:
+        return FileReport(path, "ignore", "omitted", git=git)
+    # git_state asked already when the file is there
+    if git == "no git" or (not present and _git(repo, "rev-parse", "--git-dir")):
+        # The rules are checked by asking git, so a directory that is not a repo
+        # cannot answer
+        return FileReport(path, "ignore", "unreadable", git="no git")
+    text = (template / path).read_text()
+    waived: list[str] = []
+    try:
+        if path == GITIGNORE:
+            gaps, waived = ignore_gaps(repo, text)
+        else:
+            gaps = attribute_gaps(repo, text)
+    except OSError:
+        return FileReport(path, "ignore", "unreadable", git=git)
+    status = "current" if not gaps else "partial" if present else "missing"
+    return FileReport(
+        path, "ignore", status, git=git, detail=tuple(gaps), waived=tuple(waived)
+    )
+
+
+def check_repo(
+    repo: Path, template: Path, manifest: Manifest, installed: str
+) -> RepoReport:
+    repo = repo.resolve()
+    shipped = fingerprint(DirSource(template))
+    latest = latest_release(manifest, installed)
+    stamp = read_stamp(repo, latest)
+    skip = omitted(repo, stamp.omit)
+    files: list[FileReport] = []
+    for key in _ordered(set(shipped) | set(manifest.files)):
+        value, readable = _repo_digest(repo, key)
+        path, kind = file_path(key), _kind(key)
+        git = git_state(repo, path)
+        if not readable:
+            files.append(FileReport(key, kind, "unreadable", git=git))
+        elif value is None:
+            if key in shipped:
+                status = "omitted" if path in skip or key in skip else "missing"
+                files.append(FileReport(key, kind, status, git=git))
+        elif value == shipped.get(key):
+            pins = _pins(repo, template, key)
+            files.append(FileReport(key, kind, "current", git=git, pins=pins))
+        elif (release := manifest.match(key, value)) is not None:
+            status = "matches" if key in shipped else "retired"
+            pins = _pins(repo, template, key) if key in shipped else None
+            files.append(FileReport(key, kind, status, release, git, pins))
+        else:
+            files.append(FileReport(key, kind, "one-off", git=git))
+    for path in IGNORE:
+        if (template / path).is_file():
+            files.append(_ignore_report(repo, template, path, skip))
+    settings = {path: git_state(repo, path) for path in CLAUDE_SETTINGS}
+    return RepoReport(repo.name, str(repo), stamp, files, settings)
+
+
+def is_repo(path: Path) -> bool:
+    return path.is_dir() and (path / ".git").exists()
+
+
+def check_fleet(
+    repos_dir: Path,
+    template: Path,
+    manifest: Manifest,
+    installed: str,
+    *,
+    include_unstamped: bool = False,
+    include_archived: bool = False,
+) -> list[RepoReport]:
+    """Check every clone directly under ``repos_dir``.
+
+    Skips ``*-archive`` repos and repos with no stamp unless asked for them.
+    """
+    reports: list[RepoReport] = []
+    for child in sorted(repos_dir.iterdir()):
+        if not is_repo(child):
+            continue
+        if child.name.endswith("-archive") and not include_archived:
+            continue
+        report = check_repo(child, template, manifest, installed)
+        if report.stamp.status == "missing" and not include_unstamped:
+            continue
+        reports.append(report)
+    return reports

repotemplates/classes.py

@@ -0,0 +1,291 @@
+"""Comparison rules for the template-owned files beyond the Claude hooks.
+
+Each class has its own idea of "the same file":
+
+- **Pinned** files (the pre-commit config and the workflows) compare with their
+  pins masked: ``rev:`` values, action refs and their version comments, and a
+  ``python-version`` matrix list, which follows each repo's ``requires-python``.
+  The pins are compared on their own, by name, and a repo whose pin is newer
+  than the template's is ahead, not drifted: Dependabot moves consumers first.
+- **Config** files (Dependabot, Renovate) compare by exact content.
+- **Ignore** files (``.gitignore``, ``.gitattributes``) compare by behaviour,
+  with local additions allowed: each template rule must hold in the repo, which
+  git itself answers for a probe path built from the rule. The fleet spells one
+  rule several ways (``.claude``, ``.claude/``, ``.claude/*``), so line text is
+  the wrong test.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = [
+    "CONFIG",
+    "GITATTRIBUTES",
+    "GITIGNORE",
+    "IGNORE",
+    "PINNED",
+    "Pin",
+    "attribute_gaps",
+    "compare_pins",
+    "ignore_gaps",
+    "mask",
+    "merge_pinned",
+    "pins",
+]
+
+PINNED = (
+    ".pre-commit-config.yaml",
+    ".github/workflows/test.yml",
+    ".github/workflows/publish.yml",
+    ".github/workflows/renovate.yml",
+)
+CONFIG = (".github/dependabot.yml", ".github/renovate.json")
+GITIGNORE = ".gitignore"
+GITATTRIBUTES = ".gitattributes"
+IGNORE = (GITIGNORE, GITATTRIBUTES)
+
+_REPO = re.compile(r"^\s*-?\s*repo:\s*['\"]?(?P<name>[^'\"\s#]+)")
+_REV = re.compile(
+    r"^(?P<head>\s*rev:\s*)(?P<q>['\"]?)(?P<ref>[^'\"\s#]+)(?P=q)(?P<tail>\s*#.*)?$"
+)
+_USES = re.compile(
+    r"^(?P<head>\s*(?:-\s*)?uses:\s*)(?P<q>['\"]?)(?P<name>[^@'\"\s]+)@"
+    r"(?P<ref>[^'\"\s#]+)(?P=q)(?P<tail>\s*#\s*(?P<comment>\S+).*)?$"
+)
+_MATRIX = re.compile(r"^(?P<head>\s*python-version:\s*)\[.*\]\s*$")
+_VERSION = re.compile(r"^v?(\d+(?:\.\d+)*)$")
+
+
+@dataclass(frozen=True)
+class Pin:
+    """One pinned dependency: a hook repo or an action, and the release it names.
+
+    ``version`` is the action's version comment when it has one (the ref is then
+    a commit SHA), else the ref itself.
+    """
+
+    name: str
+    version: str
+    line: int
+
+
+def _lines(text: str) -> list[str]:
+    return text.split("\n")
+
+
+def mask(text: str) -> str:
+    """The file with every pin and the Python matrix list replaced by a marker."""
+    out: list[str] = []
+    for line in _lines(text):
+        if m := _REV.match(line):
+            line = f"{m['head']}<pin>"
+        elif m := _USES.match(line):
+            line = f"{m['head']}{m['name']}@<pin>"
+        elif m := _MATRIX.match(line):
+            line = f"{m['head']}<matrix>"
+        out.append(line)
+    return "\n".join(out)
+
+
+def pins(text: str) -> list[Pin]:
+    found: list[Pin] = []
+    repo: str | None = None
+    for number, line in enumerate(_lines(text)):
+        if m := _REPO.match(line):
+            repo = m["name"]
+        if (m := _REV.match(line)) and repo is not None:
+            found.append(Pin(repo, m["ref"], number))
+        elif m := _USES.match(line):
+            # A SHA ref names its release in the comment; any other comment
+            # ("# keep") says nothing about the version
+            comment = m["comment"]
+            version = comment if comment and _key(comment) else m["ref"]
+            found.append(Pin(m["name"], version, number))
+    return found
+
+
+def _key(version: str) -> tuple[int, ...] | None:
+    m = _VERSION.match(version)
+    return tuple(int(p) for p in m.group(1).split(".")) if m else None
+
+
+def _cmp(ours: str, theirs: str) -> int | None:
+    """-1, 0, or 1 for ours against theirs; None when either is not a version."""
+    if ours == theirs:
+        return 0
+    a, b = _key(ours), _key(theirs)
+    if a is None or b is None:
+        return None
+    width = max(len(a), len(b))
+    a, b = a + (0,) * (width - len(a)), b + (0,) * (width - len(b))
+    return (a > b) - (a < b)
+
+
+def compare_pins(repo_text: str, template_text: str) -> str:
+    """same, ahead, behind, mixed, or differs: the repo's pins against the template's.
+
+    Only names both files pin are compared. ``differs`` is a pin that is not a
+    version on one side (a bare SHA) and is not equal.
+    """
+    template = {p.name: p.version for p in pins(template_text)}
+    seen: set[int] = set()
+    for pin in pins(repo_text):
+        if pin.name not in template:
+            continue
+        result = _cmp(pin.version, template[pin.name])
+        if result is None:
+            return "differs"
+        seen.add(result)
+    if seen <= {0}:
+        return "same"
+    if seen <= {0, 1}:
+        return "ahead"
+    if seen <= {0, -1}:
+        return "behind"
+    return "mixed"
+
+
+def merge_pinned(template_text: str, repo_text: str) -> str:
+    """The template's file, keeping what the repo legitimately holds of its own.
+
+    A pin the repo has newer than the template's stays, and so does the repo's
+    Python matrix list when both files have exactly one. Everything else is the
+    template's.
+    """
+    repo_pins: dict[str, tuple[str, str]] = {}
+    repo_lines = _lines(repo_text)
+    for pin in pins(repo_text):
+        repo_pins.setdefault(pin.name, (pin.version, repo_lines[pin.line]))
+    repo_matrix = [line for line in repo_lines if _MATRIX.match(line)]
+    template_lines = _lines(template_text)
+    template_matrix = [line for line in template_lines if _MATRIX.match(line)]
+    by_line = {p.line: p for p in pins(template_text)}
+    out: list[str] = []
+    for number, line in enumerate(template_lines):
+        pin = by_line.get(number)
+        if pin is not None and pin.name in repo_pins:
+            version, repo_line = repo_pins[pin.name]
+            if _cmp(version, pin.version) == 1:
+                line = _same_indent(line, repo_line)
+        elif _MATRIX.match(line) and len(repo_matrix) == len(template_matrix) == 1:
+            line = _same_indent(line, repo_matrix[0])
+        out.append(line)
+    return "\n".join(out)
+
+
+def _same_indent(template_line: str, repo_line: str) -> str:
+    """The repo's line, re-indented to sit where the template's does."""
+    indent = template_line[: len(template_line) - len(template_line.lstrip())]
+    return indent + repo_line.lstrip()
+
+
+# --- ignore files -----------------------------------------------------------
+
+_PROBE = "rtprobe"
+
+
+def _rules(text: str) -> list[str]:
+    return [
+        line.strip()
+        for line in text.splitlines()
+        if line.strip() and not line.lstrip().startswith("#")
+    ]
+
+
+def _probe(pattern: str) -> str:
+    """A path the pattern matches: globs filled in, a directory given a child."""
+    path = pattern.lstrip("/").replace("**", "a").replace("*", _PROBE)
+    path = path.replace("?", "x")
+    return f"{path}{_PROBE}" if path.endswith("/") else path
+
+
+def _git(
+    repo: Path, *args: str, stdin: str | None = None
+) -> subprocess.CompletedProcess[str]:
+    # The user's own excludes and attributes files would answer for the repo
+    config = [
+        "-c",
+        "core.excludesFile=/dev/null",
+        "-c",
+        "core.attributesFile=/dev/null",
+    ]
+    return subprocess.run(
+        ["git", *config, *args], cwd=repo, input=stdin, capture_output=True, text=True
+    )
+
+
+def ignore_gaps(repo: Path, template_text: str) -> tuple[list[str], list[str]]:
+    """The template's ignore rules that do not hold in the repo, and those waived.
+
+    A rule holds when git ignores its probe path (or, for a ``!`` rule, does not).
+    ``--no-index`` asks about the rules alone, so a tracked file does not answer.
+    A rule that does not hold is waived when the repo tracks a path it would
+    ignore: tracking ``.claude/settings.json`` is a choice not to ignore
+    ``.claude/``, which is a per-repo decision, not drift.
+    """
+    rules = _rules(template_text)
+    probes = [_probe(r.removeprefix("!")) for r in rules]
+    ignored = _ignored(repo, probes)
+    gaps: list[str] = []
+    waived: list[str] = []
+    for i, (rule, probe) in enumerate(zip(rules, probes, strict=True)):
+        if (probe in ignored) != rule.startswith("!"):
+            continue
+        (waived if _tracks(repo, rules, i) else gaps).append(rule)
+    return gaps, waived
+
+
+def _tracks(repo: Path, rules: Sequence[str], i: int) -> bool:
+    """Whether the repo tracks a path the template's rule ``rules[i]`` ignores.
+
+    git matches the rule as a gitignore pattern, together with the template's
+    later negations: ``.env.*`` does not claim a tracked ``.env.example`` while
+    the template's own ``!.env.example`` un-ignores it.
+    """
+    if rules[i].startswith("!"):
+        return False
+    later = [r for r in rules[i + 1 :] if r.startswith("!")]
+    excludes = [f"--exclude={r}" for r in (rules[i], *later)]
+    result = _git(repo, "ls-files", "--cached", "--ignored", *excludes)
+    return result.returncode == 0 and bool(result.stdout.strip())
+
+
+def _ignored(repo: Path, probes: Sequence[str]) -> set[str]:
+    stdin = "\n".join(probes) + "\n"
+    result = _git(repo, "check-ignore", "--no-index", "--stdin", stdin=stdin)
+    # 1 is "nothing ignored", not a failure
+    if result.returncode not in (0, 1):
+        raise OSError(result.stderr.strip() or "git check-ignore failed")
+    return set(result.stdout.splitlines())
+
+
+def _expected(attr: str) -> tuple[str, str]:
+    """An attribute spec as git check-attr reports it: (name, value)."""
+    if attr.startswith("-"):
+        return attr[1:], "unset"
+    if attr.startswith("!"):
+        return attr[1:], "unspecified"
+    name, sep, value = attr.partition("=")
+    return name, value if sep else "set"
+
+
+def attribute_gaps(repo: Path, template_text: str) -> list[str]:
+    """The template's attribute lines that do not hold in the repo."""
+    gaps: list[str] = []
+    for line in _rules(template_text):
+        pattern, *attrs = line.split()
+        probe = _probe(pattern)
+        for name, value in (_expected(a) for a in attrs):
+            result = _git(repo, "check-attr", name, "--", probe)
+            if result.returncode != 0:
+                raise OSError(result.stderr.strip() or "git check-attr failed")
+            got = result.stdout.strip().rsplit(": ", 1)[-1]
+            if got != value:
+                gaps.append(line)
+                break
+    return gaps