agentfile-lint 0.4.0__py3-none-any.whl

agentfile_lint/__init__.py

@@ -0,0 +1,3 @@
+"""agentfile-lint: a linter for agent instruction files (AGENTS.md / CLAUDE.md)."""
+
+__version__ = "0.4.0"

agentfile_lint/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

agentfile_lint/_vendor/entry.py.txt

@@ -0,0 +1,18 @@
+"""agentfile-lint, vendored copy. Run: python3 agentfile-lint.py [options]
+
+Standard library only. Verify the copy first with: python3 verify.py
+"""
+import os
+import sys
+
+if sys.version_info < (3, 11):
+    sys.stderr.write(f"agentfile-lint needs Python >= 3.11, found {sys.version.split()[0]}\n")
+    raise SystemExit(2)
+
+sys.dont_write_bytecode = True
+# `python3 -I` does not put the script directory on sys.path, so add it explicitly.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from agentfile_lint.cli import main  # noqa: E402
+
+sys.exit(main())

agentfile_lint/_vendor/verify.py.txt

@@ -0,0 +1,69 @@
+"""Check that this directory still matches the manifest in README.md.
+
+Detects accidental modification only: a deliberate change can edit the files and the manifest
+together. The real gate is review of the diff that upgrades this copy.
+
+Exit 0: every listed file matches and nothing else is present. Exit 1: mismatch, missing or
+extra file (named on stderr). Exit 2: the manifest cannot be read.
+"""
+import hashlib
+import os
+import sys
+
+BEGIN = "<!-- manifest:begin -->"
+END = "<!-- manifest:end -->"
+README = "README.md"
+
+
+def _manifest(root):
+    try:
+        with open(os.path.join(root, README), encoding="utf-8", newline="") as fh:
+            lines = fh.read().split("\n")
+    except OSError as exc:
+        sys.stderr.write(f"verify: cannot read {README}: {exc}\n")
+        raise SystemExit(2)
+    if BEGIN not in lines or END not in lines:
+        sys.stderr.write(f"verify: {README} has no manifest block\n")
+        raise SystemExit(2)
+    entries = {}
+    for line in lines[lines.index(BEGIN) + 1:lines.index(END)]:
+        if not line or line.startswith("```"):
+            continue
+        digest, sep, name = line.partition("  ")
+        if not sep or len(digest) != 64:
+            sys.stderr.write(f"verify: malformed manifest line: {line}\n")
+            raise SystemExit(2)
+        entries[name] = digest
+    return entries
+
+
+def main():
+    root = os.path.dirname(os.path.abspath(__file__))
+    entries = _manifest(root)
+    bad = []
+    for name, digest in sorted(entries.items()):
+        path = os.path.join(root, *name.split("/"))
+        try:
+            with open(path, "rb") as fh:
+                actual = hashlib.sha256(fh.read()).hexdigest()
+        except OSError:
+            bad.append(f"{name}: missing")
+            continue
+        if actual != digest:
+            bad.append(f"{name}: modified")
+    present = set()
+    for base, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d != "__pycache__"]
+        for f in files:
+            present.add(os.path.relpath(os.path.join(base, f), root).replace(os.sep, "/"))
+    for name in sorted(present - set(entries) - {README}):
+        bad.append(f"{name}: not listed in the manifest")
+    if bad:
+        for line in bad:
+            sys.stderr.write(f"verify: {line}\n")
+        return 1
+    print(f"verify: ok ({len(entries)} files)")
+    return 0
+
+
+sys.exit(main())

agentfile_lint/allowlist.py

@@ -0,0 +1,104 @@
+"""Allowlist: time-boxed exceptions. Every entry needs rule, path, reason and expires.
+
+An entry that has expired fails, and so does an entry that is no longer needed (the file no
+longer violates the rule, or the file is gone): exceptions can only shrink.
+"""
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import ConfigError, check_keys, expect_str
+from .finding import Finding
+
+RULE_ID = "allowlist"
+
+
+@dataclass(frozen=True)
+class Settings:
+    max_days: int
+    max_entries: int
+    warn_days: int
+
+
+@dataclass(frozen=True)
+class Entry:
+    rule: str
+    path: str
+    reason: str
+    expires: datetime.date
+
+
+def parse(raw: Any, settings: Settings, known_rules: set[str], today: datetime.date) -> list[Entry]:
+    if not isinstance(raw, list):
+        raise ConfigError("allowlist.entries: expected an array of tables")
+    if len(raw) > settings.max_entries:
+        raise ConfigError(
+            f"allowlist.entries: {len(raw)} entries exceed the limit of {settings.max_entries}; "
+            "fix the files instead of listing more exceptions"
+        )
+    latest = today + datetime.timedelta(days=settings.max_days)
+    entries: list[Entry] = []
+    seen: set[tuple[str, str]] = set()
+    for i, item in enumerate(raw):
+        where = f"allowlist.entries[{i}]"
+        check_keys(item, {"rule", "path", "reason", "expires"}, where)
+        for key in ("rule", "path", "reason", "expires"):
+            if key not in item:
+                raise ConfigError(f"{where}: missing key {key}")
+        rule = expect_str(item["rule"], f"{where}.rule")
+        if rule not in known_rules:
+            raise ConfigError(f"{where}.rule: unknown rule {rule!r}")
+        path = expect_str(item["path"], f"{where}.path")
+        reason = expect_str(item["reason"], f"{where}.reason")
+        expires = item["expires"]
+        # TOML dates arrive as datetime.date; a quoted string is accepted too.
+        if isinstance(expires, str):
+            try:
+                expires = datetime.date.fromisoformat(expires)
+            except ValueError as exc:
+                raise ConfigError(f"{where}.expires: not a YYYY-MM-DD date") from exc
+        if isinstance(expires, datetime.datetime) or not isinstance(expires, datetime.date):
+            raise ConfigError(f"{where}.expires: expected a YYYY-MM-DD date")
+        if expires > latest:
+            raise ConfigError(
+                f"{where}.expires: {expires} is more than {settings.max_days} days from {today} "
+                f"(latest allowed {latest})"
+            )
+        if (rule, path) in seen:
+            raise ConfigError(f"{where}: duplicate entry for {rule} {path}")
+        seen.add((rule, path))
+        entries.append(Entry(rule, path, reason, expires))
+    return entries
+
+
+def apply(
+    findings: list[Finding],
+    entries: list[Entry],
+    settings: Settings,
+    present: set[str],
+    today: datetime.date,
+) -> list[Finding]:
+    """Drop findings covered by a live entry; add findings about the entries themselves.
+
+    `present` is the full set of analyzed paths (decision: always the full set, never argv).
+    """
+    live = {(e.rule, e.path) for e in entries if e.expires >= today}
+    violating = {(f.rule, f.path) for f in findings}
+    out = [f for f in findings if (f.rule, f.path) not in live]
+    for e in entries:
+        days = (e.expires - today).days
+        if days < 0:
+            out.append(Finding(
+                e.path, 0, RULE_ID,
+                f"entry for {e.rule} expired on {e.expires} ({-days} days ago); fix the file or renew with a new reason",
+            ))
+        elif (e.rule, e.path) not in violating:
+            why = "file is not an analyzed instruction file" if e.path not in present else f"file no longer violates {e.rule}"
+            out.append(Finding(e.path, 0, RULE_ID, f"entry for {e.rule} is no longer needed ({why}); remove it"))
+        elif days <= settings.warn_days:
+            out.append(Finding(
+                e.path, 0, RULE_ID, f"entry for {e.rule} expires in {days} days ({e.expires})", level="warn",
+            ))
+    return out

agentfile_lint/check_pins.py

@@ -0,0 +1,130 @@
+"""`agentfile-lint check-pins`: every reference to this tool in a repository pins the same full SHA.
+
+A consumer references the tool from several places (a pre-commit hook, a lefthook command, CI
+workflows). If they pin different commits, the local hook and CI quietly run different rules.
+
+There is no YAML parser here (standard library only); the files are scanned line by line:
+
+- pre-commit: a `repo:` line whose value contains the repo string starts an entry; the next `rev:`
+  line before the following `repo:` line is its pin.
+- anywhere else (lefthook, workflows): a line that contains the repo string and `@<ref>`, as in
+  `uvx --from git+https://host/owner/agentfile-lint@<sha>` or `uses: owner/agentfile-lint@<sha>`.
+  A `uses:`/`git+` line naming the repo with no `@<ref>` is reported as unpinned.
+
+Limits: no anchors/aliases, no multi-line scalars, no expression expansion (`${{ ... }}` is not a SHA
+and is reported), no references built from several variables, and a reference inside a comment is
+still read. Anything the scan does not recognise is simply not seen: it checks consistency of what
+it finds, it does not prove there is nothing else.
+"""
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import config as config_mod
+from . import discover
+from .errors import ConfigError
+
+SHA = re.compile(r"[0-9a-f]{40}")
+_REPO_LINE = re.compile(r"^\s*(?:-\s+)?repo:\s*(\S+)")
+_REV_LINE = re.compile(r"^\s*(?:-\s+)?rev:\s*(?P<q>['\"]?)(?P<ref>[^\s'\"#]*)(?P=q)")
+_PIN_KEYWORDS = ("uses:", "git+", "--from")
+
+
+@dataclass(frozen=True)
+class Ref:
+    path: str
+    line: int
+    ref: str  # "" when the reference carries no @ref / rev
+
+
+def scan(path: str, text: str, repo: str) -> list[Ref]:
+    refs: list[Ref] = []
+    lines = text.splitlines()
+    at_ref = re.compile(re.escape(repo) + r"[^\s'\"@]*@(?P<ref>[^\s'\"#]+)")
+    in_entry = False
+    entry_line = 0
+    for number, line in enumerate(lines, start=1):
+        m = _REPO_LINE.match(line)
+        if m:
+            if in_entry:  # previous entry never had a rev
+                refs.append(Ref(path, entry_line, ""))
+            in_entry = repo in m.group(1) and m.group(1) != "local"
+            entry_line = number
+            continue
+        if in_entry:
+            rev = _REV_LINE.match(line)
+            if rev:
+                refs.append(Ref(path, number, rev.group("ref")))
+                in_entry = False
+            continue
+        if repo in line:
+            found = at_ref.search(line)
+            if found:
+                refs.append(Ref(path, number, found.group("ref")))
+            elif any(k in line for k in _PIN_KEYWORDS) and not line.lstrip().startswith("#"):
+                refs.append(Ref(path, number, ""))
+    if in_entry:
+        refs.append(Ref(path, entry_line, ""))
+    return refs
+
+
+def evaluate(refs: list[Ref]) -> list[tuple[str, int, str]]:
+    """Problems as (path, line, message): not a full SHA, or a SHA that differs from the first one."""
+    problems: list[tuple[str, int, str]] = []
+    first: Ref | None = None
+    for r in refs:
+        if not SHA.fullmatch(r.ref):
+            shown = r.ref or "(none)"
+            problems.append((r.path, r.line, f"reference is pinned to {shown!r}, not a full 40-hex commit SHA"))
+        elif first is None:
+            first = r
+        elif r.ref != first.ref:
+            problems.append((r.path, r.line, f"pinned to {r.ref}, but {first.path}:{first.line} pins {first.ref}"))
+    return problems
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(prog="agentfile-lint check-pins", description="Check that every reference to this tool pins the same full commit SHA.")
+    p.add_argument("--repo", help="string identifying this tool's repository in a reference (default: check_pins.repo from the config, else 'agentfile-lint')")
+    p.add_argument("--config", help=f"config file (default: {config_mod.CONFIG_NAME} at the repo root, if present)")
+    p.add_argument("--files", nargs="+", metavar="GLOB", help="files to scan, as globs relative to the repo root (default: check_pins.files)")
+    p.add_argument("--require-refs", action="store_true", help="fail when no reference is found (default: report and pass)")
+    args = p.parse_args(argv)
+    try:
+        root = discover.repo_root(Path.cwd())
+        cfg_path = Path(args.config) if args.config else None
+        if cfg_path is None:
+            cfg_path = config_mod.default_config_path(root)
+        import datetime
+        cfg = config_mod.load(cfg_path, datetime.date.today())
+    except (ConfigError, discover.DiscoverError) as exc:
+        sys.stderr.write(f"agentfile-lint: {exc}\n")
+        return 2
+    repo = args.repo or cfg.check_pins["repo"]
+    globs = args.files or cfg.check_pins["files"]
+    refs: list[Ref] = []
+    for path in discover.tracked_files(root):
+        if any(fnmatch.fnmatchcase(path, g) for g in globs) and (root / path).is_file():
+            try:
+                text = (root / path).read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                continue
+            refs.extend(scan(path, text, repo))
+    problems = evaluate(refs)
+    for path, line, message in problems:
+        print(f"{path}:{line}: check-pins: {message}", file=sys.stderr)
+    if problems:
+        return 1
+    if not refs:
+        print(f"check-pins: no reference to {repo!r} found in {len(globs)} file pattern(s)")
+        if args.require_refs:
+            print(f":0: check-pins: no reference to {repo!r} found", file=sys.stderr)
+            return 1
+        return 0
+    print(f"check-pins: {len(refs)} reference(s) to {repo!r}, all pinned to {refs[0].ref}")
+    return 0

agentfile_lint/cli.py

@@ -0,0 +1,128 @@
+"""Command line entry point.
+
+Output: one line per finding, `file:line: rule-id: message`. Whole-file findings use line 0 and
+the `:0` is always printed, so the format has exactly one shape. Errors go to stderr, warnings to
+stdout. Exit codes: 0 no errors (warnings allowed), 1 at least one error, 2 usage or config problem.
+"""
+from __future__ import annotations
+
+import sys
+
+if sys.version_info < (3, 11):  # checked before importing anything that needs tomllib
+    sys.stderr.write(f"agentfile-lint needs Python >= 3.11, found {sys.version.split()[0]}\n")
+    raise SystemExit(2)
+
+import argparse
+import datetime
+import json
+import os
+from pathlib import Path
+
+from . import __version__
+from . import config as config_mod
+from . import discover, engine
+from .errors import ConfigError
+from .rules import RULES
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="agentfile-lint", description="Lint agent instruction files.")
+    p.add_argument("files", nargs="*", help="only decides whether to run; the full tracked set is always analyzed")
+    p.add_argument("--config", help=f"config file (default: {config_mod.CONFIG_NAME} at the repo root, if present)")
+    p.add_argument("--today", help="YYYY-MM-DD, replaces the current date (reproducible runs)")
+    p.add_argument("--version", action="version", version=f"agentfile-lint {__version__}")
+    p.add_argument("--list-rules", action="store_true", help="print the rules and their effective levels, then exit")
+    p.add_argument("--warn-as-error", action="store_true", help="treat warnings as errors")
+    return p
+
+
+def _relevant(files: list[str], root: Path, cwd: Path, globs: list[str]) -> bool:
+    """argv names only decide whether to run at all (full-set semantics)."""
+    for name in files:
+        try:
+            rel = Path(os.path.abspath(cwd / name)).relative_to(root).as_posix()
+        except ValueError:
+            continue
+        if rel == config_mod.CONFIG_NAME or discover.matches(rel, globs):
+            return True
+    return False
+
+
+def _config_main(argv: list[str]) -> int:
+    """`agentfile-lint config --format json`: the effective (merged, validated) configuration."""
+    p = argparse.ArgumentParser(prog="agentfile-lint config", description="Print the effective configuration.")
+    p.add_argument("--format", choices=["json"], default="json", help="output format (only json)")
+    p.add_argument("--config", help=f"config file (default: {config_mod.CONFIG_NAME} at the repo root, if present)")
+    p.add_argument("--today", help="YYYY-MM-DD, used to validate allowlist expiry dates")
+    args = p.parse_args(argv)
+    try:
+        today = datetime.date.fromisoformat(args.today) if args.today else datetime.date.today()
+    except ValueError:
+        sys.stderr.write("agentfile-lint: --today must be YYYY-MM-DD\n")
+        return 2
+    try:
+        cfg_path = Path(args.config) if args.config else None
+        if cfg_path is None:
+            try:
+                root = discover.repo_root(Path.cwd())
+            except discover.DiscoverError:
+                root = None
+            cfg_path = config_mod.default_config_path(root)
+        cfg = config_mod.load(cfg_path, today)
+    except ConfigError as exc:
+        sys.stderr.write(f"agentfile-lint: {exc}\n")
+        return 2
+    sys.stdout.write(json.dumps(config_mod.to_jsonable(cfg), sort_keys=True, indent=2, ensure_ascii=False) + "\n")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] == "vendor":  # subcommand; any other first word keeps the check CLI
+        try:
+            from . import vendor
+        except ImportError:
+            sys.stderr.write("agentfile-lint: vendor is only available from a source checkout\n")
+            return 2
+        return vendor.main(argv[1:])
+    if argv and argv[0] == "check-pins":
+        from . import check_pins
+        return check_pins.main(argv[1:])
+    if argv and argv[0] == "config":
+        return _config_main(argv[1:])
+    args = _parser().parse_args(argv)
+    try:
+        today = datetime.date.fromisoformat(args.today) if args.today else datetime.date.today()
+    except ValueError:
+        sys.stderr.write("agentfile-lint: --today must be YYYY-MM-DD\n")
+        return 2
+    cwd = Path.cwd()
+    try:
+        try:
+            root = discover.repo_root(cwd)
+        except discover.DiscoverError:
+            if not args.list_rules:
+                raise
+            root = None
+        cfg_path = Path(args.config) if args.config else None
+        if cfg_path is None:
+            cfg_path = config_mod.default_config_path(root)
+        cfg = config_mod.load(cfg_path, today)
+    except (ConfigError, discover.DiscoverError) as exc:
+        sys.stderr.write(f"agentfile-lint: {exc}\n")
+        return 2
+
+    if args.list_rules:
+        for rule_id, module in RULES.items():
+            print(f"{rule_id}  {cfg.rules[rule_id]['level']:<5}  {module.NAME}: {module.DESCRIPTION}")
+        print("allowlist  error  expired or no-longer-needed allowlist entries; warns before expiry (always on)")
+        return 0
+
+    if args.files and not _relevant(args.files, root, cwd, cfg.globs):
+        return 0
+
+    findings = engine.analyze(root, cfg, today, args.warn_as_error)
+    for f in findings:
+        print(f.format(), file=sys.stderr if f.level == "error" else sys.stdout)
+    sys.stdout.flush()
+    return 1 if any(f.level == "error" for f in findings) else 0

agentfile_lint/config.py

@@ -0,0 +1,169 @@
+"""Configuration: shipped preset + optional repo config with `extends`; unknown keys fail.
+
+Merge rule: tables merge key by key (the child wins); every other value, lists included,
+is replaced as a whole.
+"""
+from __future__ import annotations
+
+import datetime
+import tomllib
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from . import allowlist
+from .errors import LEVELS, ConfigError, check_keys, expect_int, expect_str, expect_str_list
+from .rules import RULES
+
+CONFIG_NAME = ".agentfile-lint.toml"
+# Migration aid for the 0.4.0 rename; remove at 1.0.
+LEGACY_CONFIG_NAME = ".instruction-lint.toml"
+PRESET_PREFIX = "preset:"
+DEFAULT_PRESET = "preset:default"
+_TOP_KEYS = {"extends", "discover", "allowlist", "rules", "check_pins"}
+PIN_DEFAULTS = {
+    "repo": "agentfile-lint",
+    "files": [
+        ".pre-commit-config.yaml", ".pre-commit-config.yml", "lefthook.yml", "lefthook.yaml",
+        ".lefthook.yml", ".lefthook.yaml", ".github/workflows/*.yml", ".github/workflows/*.yaml",
+    ],
+}
+
+
+def default_config_path(root: Path | None) -> Path | None:
+    """The repo-root config file, or None. Fails when only the pre-0.4.0 file name exists."""
+    if root is None:
+        return None
+    path = root / CONFIG_NAME
+    if path.is_file():
+        return path
+    if (root / LEGACY_CONFIG_NAME).is_file():
+        raise ConfigError(
+            f"found {LEGACY_CONFIG_NAME}, which agentfile-lint no longer reads; "
+            f"rename it to {CONFIG_NAME} (git mv {LEGACY_CONFIG_NAME} {CONFIG_NAME})"
+        )
+    return None
+
+
+@dataclass
+class Config:
+    globs: list[str]
+    allowlist: allowlist.Settings
+    entries: list[allowlist.Entry]
+    rules: dict[str, dict[str, Any]]  # rule id -> validated params, including "level"
+    check_pins: dict[str, Any] = field(default_factory=lambda: dict(PIN_DEFAULTS))  # repo, files
+
+
+def to_jsonable(cfg: "Config") -> dict[str, Any]:
+    """The effective configuration as plain JSON data (dates as ISO strings)."""
+    return {
+        "discover": {"globs": cfg.globs},
+        "allowlist": {
+            "max_days": cfg.allowlist.max_days,
+            "max_entries": cfg.allowlist.max_entries,
+            "warn_days": cfg.allowlist.warn_days,
+            "entries": [
+                {"rule": e.rule, "path": e.path, "reason": e.reason, "expires": e.expires.isoformat()}
+                for e in cfg.entries
+            ],
+        },
+        "rules": cfg.rules,
+        "check_pins": cfg.check_pins,
+    }
+
+
+def _merge(base: dict[str, Any], over: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for key, value in over.items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _merge(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def _read(source: str, text: str) -> dict[str, Any]:
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{source}: invalid TOML: {exc}") from exc
+
+
+def _load_raw(ref: str, base_dir: Path | None, seen: tuple[str, ...]) -> dict[str, Any]:
+    if ref.startswith(PRESET_PREFIX):
+        name = ref[len(PRESET_PREFIX):]
+        key = ref
+        try:
+            text = (resources.files("agentfile_lint") / "presets" / f"{name}.toml").read_text(encoding="utf-8")
+        except (FileNotFoundError, OSError) as exc:
+            raise ConfigError(f"unknown preset {name!r}") from exc
+        data = _read(ref, text)
+    else:
+        path = Path(ref)
+        if not path.is_absolute() and base_dir is not None:
+            path = base_dir / path
+        key = str(path.resolve())
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ConfigError(f"cannot read config {path}: {exc.strerror}") from exc
+        data = _read(str(path), text)
+        base_dir = path.parent
+    if key in seen:
+        raise ConfigError(f"extends cycle at {ref}")
+    extends = data.get("extends", [DEFAULT_PRESET] if ref != DEFAULT_PRESET else [])
+    if isinstance(extends, str):
+        extends = [extends]
+    if not isinstance(extends, list) or not all(isinstance(e, str) for e in extends):
+        raise ConfigError(f"{ref}: extends must be a list of strings")
+    merged: dict[str, Any] = {}
+    for parent in extends:
+        merged = _merge(merged, _load_raw(parent, base_dir, seen + (key,)))
+    own = {k: v for k, v in data.items() if k != "extends"}
+    return _merge(merged, own)
+
+
+def load(config_path: Path | None, today: datetime.date) -> Config:
+    """Load the preset plus `config_path` (when given). Raises ConfigError on any problem."""
+    if config_path is None:
+        raw = _load_raw(DEFAULT_PRESET, None, ())
+    else:
+        raw = _load_raw(str(config_path), None, ())
+    return _validate(raw, today)
+
+
+def _validate(raw: dict[str, Any], today: datetime.date) -> Config:
+    check_keys(raw, _TOP_KEYS, "config")
+    discover = raw.get("discover", {})
+    check_keys(discover, {"globs"}, "discover")
+    globs = expect_str_list(discover.get("globs"), "discover.globs")
+
+    al = raw.get("allowlist", {})
+    check_keys(al, {"max_days", "max_entries", "warn_days", "entries"}, "allowlist")
+    settings = allowlist.Settings(
+        max_days=expect_int(al.get("max_days"), "allowlist.max_days", 0),
+        max_entries=expect_int(al.get("max_entries"), "allowlist.max_entries", 0),
+        warn_days=expect_int(al.get("warn_days"), "allowlist.warn_days", 0),
+    )
+
+    rules_raw = raw.get("rules", {})
+    check_keys(rules_raw, set(RULES), "rules")
+    rules: dict[str, dict[str, Any]] = {}
+    for rule_id, module in RULES.items():
+        params = rules_raw.get(rule_id)
+        if params is None:
+            raise ConfigError(f"rules.{rule_id}: missing")
+        level = params.get("level")
+        if level not in LEVELS:
+            raise ConfigError(f"rules.{rule_id}.level: expected one of {', '.join(LEVELS)}")
+        rules[rule_id] = module.validate(params)
+
+    entries = allowlist.parse(al.get("entries", []), settings, set(RULES), today)
+    pins = raw.get("check_pins", {})
+    check_keys(pins, set(PIN_DEFAULTS), "check_pins")
+    pins = {
+        "repo": expect_str(pins.get("repo", PIN_DEFAULTS["repo"]), "check_pins.repo"),
+        "files": expect_str_list(pins.get("files", PIN_DEFAULTS["files"]), "check_pins.files"),
+    }
+    return Config(globs=globs, allowlist=settings, entries=entries, rules=rules, check_pins=pins)

agentfile_lint/context.py

@@ -0,0 +1,26 @@
+"""What cross-file rules may look at: the full tracked file set, never just the command-line files."""
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+
+
+class Context:
+    def __init__(self, root: Path, tracked: list[str], files: dict[str, str]):
+        self.root = root
+        self.tracked = tracked          # every `git ls-files` entry
+        self.files = files              # analyzed instruction files (valid UTF-8): path -> text
+        self.tracked_set = set(tracked)
+        self.dirs = {""}                # every directory that holds a tracked file ("" is the root)
+        for path in tracked:
+            for parent in PurePosixPath(path).parents:
+                self.dirs.add("" if str(parent) == "." else str(parent))
+        self._cache: dict[str, str | None] = {}
+
+    def read(self, path: str) -> str | None:
+        """Text of a tracked file, or None when it is missing or not valid UTF-8."""
+        if path not in self._cache:
+            try:
+                self._cache[path] = (self.root / path).read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                self._cache[path] = None
+        return self._cache[path]