maat16-agentlint 0.1.1.dev3__py3-none-any.whl

agentlint/__init__.py

@@ -0,0 +1,13 @@
+"""agentlint: design-rule governance for agent projects.
+
+Rules are ``DR-nnn`` ids in packs (built-in: spec, claudemd, mcp; per project: rules.py).
+A project's policy sets levels and exemptions; reports come as text, json, GitHub
+annotations or html. See README.md.
+"""
+from .core import Context, Finding, Policy, PolicyError, Skill, rule  # noqa: F401
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _version
+    __version__ = _version("maat16-agentlint")          # set by setuptools-scm from git at build time
+except PackageNotFoundError:                       # a bare checkout on PYTHONPATH, not installed
+    __version__ = "0+unknown"

agentlint/__main__.py

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

agentlint/cli.py

@@ -0,0 +1,111 @@
+"""agentlint command line.
+
+    agentlint <policy.toml | project-name> [--strict] [--format text|json|github|html] [--out FILE] [--open]
+    agentlint <policy> --list-rules [--format text|json|md] [--out FILE]
+    agentlint --list-rules --format md --split --out docs      # the built-in families, one file each
+
+Exit codes: 0 pass · 1 findings at a failing level (errors, or warnings with --strict) ·
+2 the policy or a rule pack is broken (nothing was validated).
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import webbrowser
+from pathlib import Path
+
+from .core import RANGES, REGISTRY, PolicyError, builtin_policy, family_of, load_packs, load_policy, run
+from .report import (render_github, render_json, render_rules_index, render_rules_json,
+                     render_rules_md, render_rules_text, render_text, summary)
+from .report_html import render_html
+
+PROJECTS = Path(__file__).resolve().parent.parent / "projects"
+RENDER = {"text": render_text, "json": render_json, "github": render_github, "html": render_html}
+RULES = {"text": render_rules_text, "json": render_rules_json, "md": render_rules_md}
+
+
+def resolve_policy(arg: str) -> Path:
+    p = Path(arg)
+    if p.is_file():
+        return p.resolve()
+    if p.is_dir() and (p / "policy.toml").is_file():
+        return (p / "policy.toml").resolve()
+    cand = PROJECTS / arg / "policy.toml"
+    if cand.is_file():
+        return cand
+    raise PolicyError(f"no policy at {arg!r} and no project {arg!r} under {PROJECTS}")
+
+
+def emit(text: str, out: Path | None) -> None:
+    if out is None:
+        print(text)
+        return
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(text, encoding="utf-8", newline="\n")   # LF on every OS: generated files are committed
+    print(f"agentlint: wrote {out}")
+
+
+def write_split(policy, out: Path) -> None:
+    """One Markdown document per family plus an index, into a directory."""
+    out.mkdir(parents=True, exist_ok=True)
+    families = sorted({family_of(r.number) for r in REGISTRY.values()},
+                      key=lambda f: next(i for i, (_r, n, _d) in enumerate(RANGES) if n == f))
+    for fam in families:
+        (out / f"{fam}.md").write_text(render_rules_md(policy, fam), encoding="utf-8", newline="\n")
+    (out / "README.md").write_text(render_rules_index(policy), encoding="utf-8", newline="\n")
+    print(f"agentlint: wrote {out}/README.md and {', '.join(f + '.md' for f in families)}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    ap = argparse.ArgumentParser(prog="agentlint", description=(
+        "Design-rule governance for agent projects: skills, subagents, CLAUDE.md, MCP and settings, "
+        "plus each project's own rules, with levels, exemptions and reports for CI."))
+    ap.add_argument("policy", nargs="?", help="a policy.toml (or its directory), or a project name under "
+                    "projects/; omit it with --list-rules to see the built-in packs")
+    ap.add_argument("--root", type=Path, help="override the project root the policy names")
+    ap.add_argument("--strict", action="store_true", help="warnings fail too (the CI setting)")
+    ap.add_argument("--format", choices=(*RENDER, "md"), default="text",
+                    help="report format (default text); md is for --list-rules only")
+    ap.add_argument("--out", type=Path, help="write the report to this file; the text report still prints")
+    ap.add_argument("--open", action="store_true", help="open the file written with --out in the default browser")
+    ap.add_argument("--list-rules", action="store_true", help="print the rules register and exit")
+    ap.add_argument("--split", action="store_true",
+                    help="with --list-rules --format md --out DIR: one document per family plus README.md")
+    args = ap.parse_args(argv)
+
+    try:
+        if args.policy is None:
+            if not args.list_rules:
+                raise PolicyError("name a policy or a project, or use --list-rules for the built-in register")
+            policy = builtin_policy(Path.cwd())
+        else:
+            policy = load_policy(resolve_policy(args.policy), args.root)
+        load_packs(policy)
+        if args.list_rules:
+            if args.split:
+                if args.format != "md" or args.out is None:
+                    raise PolicyError("--split needs --format md and --out DIR")
+                write_split(policy, args.out)
+                return 0
+            emit(RULES.get(args.format, render_rules_text)(policy), args.out)
+            return 0
+        if args.format == "md":
+            raise PolicyError("--format md is for --list-rules; reports come as text, json, github or html")
+        findings, ctx = run(policy)
+    except PolicyError as e:
+        print(f"agentlint: {e}", file=sys.stderr)
+        return 2
+
+    emit(RENDER[args.format](policy, ctx, findings, args.strict), args.out)
+    if args.out is not None:
+        print(render_text(policy, ctx, findings, args.strict))
+        if args.open:
+            webbrowser.open(args.out.resolve().as_uri())
+    return 1 if summary(findings, args.strict)["failed"] else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

agentlint/core.py

@@ -0,0 +1,373 @@
+"""agentlint core: the rule registry, discovery, the policy, exemptions and the run.
+
+A rule is a generator decorated with ``@rule("DR-012", "error", "summary", source=...)``.
+It receives a ``Context`` and yields ``(path, message)`` pairs - ``path`` relative to the
+project root - or ``ctx.skip(reason)`` when it cannot run (a table it needs will not
+import). A skip is reported, never counted as a pass.
+
+Rules live in packs: built-in ones under ``agentlint/packs/`` (``spec``, ``claudemd``,
+``mcp``) and a project's own ``rules.py`` beside its policy. Ids are ``DR-nnn`` and unique
+across every pack a run loads; each family owns a number range (``RANGES``).
+
+The policy (TOML) sets the project root, the skill globs, the packs, the effective level of
+any rule (``error`` / ``warn`` / ``info`` / ``off``) and the exemptions. An exemption names
+a rule, a path glob, a reason, an owner and an expiry date; findings it covers are reported
+as exempt (still visible), an expired one stops applying and is itself reported (DR-001),
+an unused one is reported (DR-002).
+"""
+from __future__ import annotations
+
+import datetime as dt
+import fnmatch
+import importlib
+import importlib.util
+import re
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    sys.exit("agentlint: pyyaml is required (pip install pyyaml)")
+
+LEVELS = ("error", "warn", "info", "off")
+RUN_LEVELS = LEVELS[:3]
+RULE_ID = re.compile(r"^DR-\d{3}$")
+
+#: Number ranges by family. A pack keeps to its range; project packs use 900 upward and
+#: only one project pack loads per run, so their numbers never meet.
+RANGES = (
+    ((0, 9), "governance", "the policy itself, raised by the engine"),
+    ((10, 99), "skills", "SKILL.md: the Agent Skills specification and Claude Code's extensions"),
+    ((100, 199), "claudemd", "CLAUDE.md, AGENTS.md, CLAUDE.local.md and .claude/rules"),
+    ((200, 299), "mcp", ".mcp.json servers and the settings that approve them"),
+    ((300, 399), "agents", "subagent definitions under .claude/agents"),
+    ((400, 499), "settings", ".claude/settings.json: permissions, hooks, keys"),
+    ((500, 899), "reserved", "future families"),
+    ((900, 999), "project", "the project's own pack"),
+)
+#: The packs every policy gets unless it names its own list.
+BUILTIN_PACKS = ("skills", "claudemd", "mcp", "agents", "settings")
+
+
+class PolicyError(Exception):
+    """A problem in the policy or a rule pack: exit 2, nothing validated."""
+
+
+# ------------------------------------------------------------------ rules
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    level: str
+    summary: str
+    category: str
+    source: str
+    pack: str
+    doc: str
+    fn: object
+
+    @property
+    def number(self) -> int:
+        return int(self.id[3:])
+
+
+REGISTRY: dict[str, Rule] = {}
+_PACK: list[str] = ["engine"]
+
+
+def family_of(number: int) -> str:
+    for (lo, hi), name, _ in RANGES:
+        if lo <= number <= hi:
+            return name
+    return "?"
+
+
+def rule(id: str, level: str, summary: str, *, source: str = "", category: str | None = None):
+    """Register a rule under a ``DR-nnn`` id with its default level, a one-line summary
+    and the source it enforces (a spec section, a project file). The docstring is the
+    rule's explanation in the register."""
+    if not RULE_ID.match(id):
+        raise PolicyError(f"rule id {id!r} must look like DR-012")
+    if level not in RUN_LEVELS:
+        raise PolicyError(f"rule {id}: level must be one of {RUN_LEVELS}, not {level!r}")
+
+    def deco(fn):
+        if id in REGISTRY:
+            raise PolicyError(f"rule {id} is defined twice ({REGISTRY[id].pack} and {_PACK[-1]})")
+        REGISTRY[id] = Rule(id, level, summary, category or family_of(int(id[3:])), source,
+                            _PACK[-1], " ".join((fn.__doc__ or "").split()), fn)
+        return fn
+    return deco
+
+
+class Skip:
+    """Yielded by a rule that cannot run; reported, never a pass."""
+
+    def __init__(self, reason: str):
+        self.reason = reason
+
+
+# ------------------------------------------------------------------ skills
+
+FRONT = re.compile(r"\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)(.*)\Z", re.S)
+
+
+def split_frontmatter(text: str) -> tuple[dict, str]:
+    m = FRONT.match(text)
+    if not m:
+        raise ValueError("no YAML frontmatter opened and closed by ---")
+    try:
+        meta = yaml.safe_load(m.group(1))
+    except yaml.YAMLError as e:
+        raise ValueError(f"frontmatter is not valid YAML: {e}") from None
+    if not isinstance(meta, dict):
+        raise ValueError("frontmatter is not a mapping")
+    return meta, m.group(2)
+
+
+@dataclass
+class Skill:
+    dir: Path
+    rel: str                    # SKILL.md relative to the root (posix); the dir when missing
+    text: str = ""
+    meta: dict | None = None    # None when the file is missing or does not parse
+    body: str = ""
+    error: str | None = None
+
+    @property
+    def name(self) -> str:
+        return self.dir.name
+
+
+PRUNE = {".git", "node_modules", ".venv", "venv", "__pycache__", "build", "dist", ".tox"}
+
+
+def _pruned(p: Path) -> bool:
+    return any(part in PRUNE or part.endswith(".egg-info") for part in p.parts)
+
+
+def discover(root: Path, globs: list[str]) -> list[Skill]:
+    seen: set[Path] = set()
+    out: list[Skill] = []
+    for g in globs:
+        for d in sorted(root.glob(g)):
+            if not d.is_dir() or d in seen or _pruned(d.relative_to(root)):
+                continue
+            seen.add(d)
+            md = next((d / n for n in ("SKILL.md", "skill.md") if (d / n).exists()), None)
+            s = Skill(d, (md or d).relative_to(root).as_posix())
+            if md is None:
+                s.error = "SKILL.md missing"
+            else:
+                try:
+                    s.text = md.read_text(encoding="utf-8")
+                    s.meta, s.body = split_frontmatter(s.text)
+                except (OSError, UnicodeDecodeError, ValueError) as e:
+                    s.error = str(e)
+            out.append(s)
+    return out
+
+
+@dataclass
+class Context:
+    root: Path
+    policy: "Policy"
+    skills: list[Skill]
+    cache: dict = field(default_factory=dict)       # for a pack to share what it parsed
+    inventory: dict = field(default_factory=dict)   # what was discovered, by kind, for the report
+
+    def rel(self, p: Path) -> str:
+        try:
+            return Path(p).resolve().relative_to(self.root).as_posix()
+        except ValueError:
+            return Path(p).as_posix()
+
+    def files(self, *globs: str) -> list[Path]:
+        """Files under the root matching any glob, pruned of vendored and build trees."""
+        found: set[Path] = set()
+        for g in globs:
+            for p in self.root.glob(g):
+                if p.is_file() and not _pruned(p.relative_to(self.root)):
+                    found.add(p)
+        return sorted(found)
+
+    def skip(self, reason: str) -> Skip:
+        return Skip(reason)
+
+
+# ------------------------------------------------------------------ policy
+
+@dataclass
+class Exemption:
+    index: int
+    rule: str
+    path: str
+    reason: str
+    by: str
+    until: dt.date | None
+    matched: int = 0
+
+    def covers(self, rule_id: str, path: str) -> bool:
+        return rule_id == self.rule and fnmatch.fnmatchcase(path, self.path)
+
+
+@dataclass
+class Policy:
+    file: Path
+    name: str
+    root: Path
+    skills: list[str]
+    packs: list[str]
+    levels: dict[str, str]
+    exemptions: list[Exemption]
+
+    def level(self, rule_id: str) -> str:
+        return self.levels.get(rule_id, REGISTRY[rule_id].level)
+
+
+DEFAULT_SKILLS = ["**/.claude/skills/*", "**/.agents/skills/*", "skills/*"]
+
+
+def load_policy(path: Path, root_override: Path | None = None) -> Policy:
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as e:
+        raise PolicyError(f"{path}: {e}") from None
+    proj = data.get("project") or {}
+    root = (root_override or (path.parent / proj.get("root", "."))).resolve()
+    if not root.is_dir():
+        raise PolicyError(f"{path}: project root {root} is not a directory")
+    rules = data.get("rules") or {}
+    levels = dict(rules.get("levels") or {})
+    for k, v in levels.items():
+        if v not in LEVELS:
+            raise PolicyError(f"{path}: [rules.levels] {k} = {v!r}; use one of {LEVELS}")
+    exemptions = []
+    for i, e in enumerate(data.get("exemptions") or [], 1):
+        if not isinstance(e, dict) or not e.get("rule") or not e.get("reason"):
+            raise PolicyError(f"{path}: exemption #{i} needs at least 'rule' and 'reason'")
+        until = e.get("until")
+        if until is not None and not isinstance(until, dt.date):
+            raise PolicyError(f"{path}: exemption #{i} 'until' must be a bare date, e.g. until = 2026-10-09")
+        exemptions.append(Exemption(i, str(e["rule"]), str(e.get("path", "*")), str(e["reason"]),
+                                    str(e.get("by", "")), until))
+    return Policy(path, str(proj.get("name") or path.parent.name), root,
+                  list(proj.get("skills") or DEFAULT_SKILLS), list(rules.get("packs") or BUILTIN_PACKS),
+                  levels, exemptions)
+
+
+def builtin_policy(root: Path) -> Policy:
+    """A policy with every built-in pack and no overrides: what ``--list-rules`` uses when
+    no project is named, and a sensible first run on any directory."""
+    return Policy(root / "policy.toml", root.name, root, list(DEFAULT_SKILLS), list(BUILTIN_PACKS), {}, [])
+
+
+def load_packs(policy: Policy) -> None:
+    """Import every pack the policy names: a bare name is built in (``agentlint.packs.<name>``),
+    anything with a slash or ``.py`` is a file relative to the policy."""
+    for p in policy.packs:
+        _PACK.append(p)
+        try:
+            if "/" in p or p.endswith(".py"):
+                f = (policy.file.parent / p).resolve()
+                if not f.is_file():
+                    raise PolicyError(f"{policy.file}: rule pack not found: {f}")
+                spec = importlib.util.spec_from_file_location(f"agentlint_pack_{f.stem}_{abs(hash(str(f)))}", f)
+                mod = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(mod)          # type: ignore[union-attr]
+            else:
+                try:
+                    importlib.import_module(f"agentlint.packs.{p}")
+                except ModuleNotFoundError as e:
+                    if e.name == f"agentlint.packs.{p}":
+                        raise PolicyError(f"{policy.file}: no built-in pack named {p!r}") from None
+                    raise
+        finally:
+            _PACK.pop()
+    unknown = sorted({k for k in policy.levels if k not in REGISTRY}
+                     | {e.rule for e in policy.exemptions if e.rule not in REGISTRY})
+    if unknown:
+        raise PolicyError(f"{policy.file}: names rules no loaded pack defines: {', '.join(unknown)}")
+
+
+# ------------------------------------------------------------------ the run
+
+@dataclass
+class Finding:
+    rule: str
+    level: str                  # effective level, or "skip"
+    path: str
+    message: str
+    status: str = "open"        # open | exempt | skip
+    exemption: Exemption | None = None
+
+
+# governance rules the engine raises itself
+
+@rule("DR-001", "warn", "an exemption has passed its 'until' date", source="policy [[exemptions]]")
+def _expired(ctx):
+    """An expired exemption no longer applies: the findings it covered reopen at their own
+    level, and the stale entry is reported until it is renewed or removed."""
+    return ()
+
+
+@rule("DR-002", "info", "an exemption matched no finding", source="policy [[exemptions]]")
+def _unused(ctx):
+    """An exemption that covers nothing is dead policy; remove it so the file stays a true
+    record of what is tolerated."""
+    return ()
+
+
+@rule("DR-003", "error", "a rule crashed while running", source="the rule pack")
+def _crashed(ctx):
+    """A rule that raises is a bug in the pack, reported as an error so it is fixed rather
+    than silently skipped."""
+    return ()
+
+
+def run(policy: Policy, today: dt.date | None = None) -> tuple[list[Finding], Context]:
+    today = today or dt.date.today()
+    ctx = Context(policy.root, policy, discover(policy.root, policy.skills))
+    ctx.inventory["skills"] = len(ctx.skills)
+    findings: list[Finding] = []
+    active = [e for e in policy.exemptions if e.until is None or e.until >= today]
+    for r in sorted(REGISTRY.values(), key=lambda r: r.number):
+        level = policy.level(r.id)
+        if level == "off" or r.id in ("DR-001", "DR-002", "DR-003"):
+            continue
+        try:
+            items = list(r.fn(ctx) or ())
+        except Exception as e:  # noqa: BLE001 - a crashing rule must not stop the run
+            if policy.level("DR-003") != "off":
+                findings.append(Finding("DR-003", policy.level("DR-003"), "",
+                                        f"{r.id} crashed: {type(e).__name__}: {e}"))
+            continue
+        for it in items:
+            if isinstance(it, Skip):
+                findings.append(Finding(r.id, "skip", "", it.reason, "skip"))
+                continue
+            path, msg = it
+            f = Finding(r.id, level, str(path), str(msg))
+            for e in active:
+                if e.covers(r.id, f.path):
+                    f.status, f.exemption = "exempt", e
+                    e.matched += 1
+                    break
+            findings.append(f)
+    for e in policy.exemptions:
+        if e.until is not None and e.until < today:
+            if policy.level("DR-001") != "off":
+                findings.append(Finding("DR-001", policy.level("DR-001"), e.path,
+                                        f"exemption #{e.index} for {e.rule} expired on {e.until}: {e.reason}"))
+        elif e.matched == 0 and policy.level("DR-002") != "off":
+            findings.append(Finding("DR-002", policy.level("DR-002"), e.path,
+                                    f"exemption #{e.index} for {e.rule} matched nothing: {e.reason}"))
+    return findings, ctx
+
+
+def failed(findings: list[Finding], strict: bool) -> bool:
+    open_ = [f for f in findings if f.status == "open"]
+    return any(f.level == "error" for f in open_) or (strict and any(f.level == "warn" for f in open_))

agentlint/packs/__init__.py

@@ -0,0 +1,4 @@
+"""Built-in rule packs, one per family, each in its DR number range (``core.RANGES``):
+``skills`` (DR-010..099), ``claudemd`` (DR-100..199), ``mcp`` (DR-200..299), ``agents``
+(DR-300..399), ``settings`` (DR-400..499). ``_shared`` holds helpers and registers nothing;
+``data/`` holds the bundled Claude Code settings schema."""