maat16-agentlint 0.1.1.dev3__tar.gz

maat16_agentlint-0.1.1.dev3/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+# Publish maat16-agentlint to PyPI.
+#
+# Every push to main publishes a DEV pre-release (0.1.1.devN from setuptools-scm) so
+# consumers that install with `pip install --pre maat16-agentlint` always run main; a tag
+# `vX.Y.Z` publishes that final version. No API token anywhere: PyPI trusts this
+# workflow's OIDC identity (Trusted Publishing — the project on pypi.org lists
+# owner maat16 / repository agentlint / workflow publish.yml / environment pypi).
+#
+# The publish job needs `id-token: write`, and NOTHING else in the job may run
+# untrusted code, which is why build and publish are separate jobs.
+name: publish
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0          # setuptools-scm needs the tags and the commit count
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --quiet build
+      - run: python -m build
+      - run: |
+          python -m pip install --quiet dist/*.whl
+          agentlint --list-rules | head -3
+          python -c 'import agentlint; print("maat16-agentlint", agentlint.__version__)'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

maat16_agentlint-0.1.1.dev3/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+reports/

maat16_agentlint-0.1.1.dev3/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: maat16-agentlint
+Version: 0.1.1.dev3
+Summary: Design-rule governance for agent projects: skills, CLAUDE.md, MCP configuration and each project's own rules, with levels, exemptions and reports for CI.
+Project-URL: Source, https://github.com/maat16/agentlint
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6
+
+# agentlint
+
+Design-rule governance for agent projects. One tool, many projects: it discovers a
+project's skills, subagents, CLAUDE.md and AGENTS.md files, MCP configuration and Claude
+Code settings, checks each against its family of rules, adds the project's own rules, and
+reports under a policy that says which rules apply, at what level, and what is exempt for
+how long and why.
+
+```
+python -m agentlint friday                         # text report, exit 1 on errors
+python -m agentlint friday --strict                # warnings fail too (CI)
+python -m agentlint friday --format html --out reports/friday.html --open
+python -m agentlint friday --format github         # GitHub Actions annotations
+python -m agentlint friday --format json           # for other tools
+python -m agentlint friday --list-rules            # the register for that project
+python -m agentlint --list-rules                   # the built-in register, no project needed
+```
+
+Needs Python 3.11+ and pyyaml. `pip install maat16-agentlint` (PyPI; the bare name is taken and `agent-lint` too similar —
+the import name and command are still `agentlint`) or `pip install -e .` from a checkout adds
+the `agentlint` command. `pip install --pre maat16-agentlint` tracks `main`: every push there is
+published as a dev pre-release by `.github/workflows/publish.yml`, and a `vX.Y.Z` tag
+publishes a final version.
+
+## The rules, documented
+
+Every rule is declared in code with its id, default level, summary, explanation and source,
+and the documents are generated from that register so they cannot drift:
+
+- **[docs/](docs/README.md)**: the common rules, one document per family.
+- **`projects/<name>/RULES.md`**: everything that runs for one project, including its own
+  rules, with the levels its policy makes effective.
+
+Regenerate after any rule or policy change:
+
+```
+python -m agentlint --list-rules --format md --split --out docs
+python -m agentlint friday --list-rules --format md --out projects/friday/RULES.md
+```
+
+## Families
+
+Rules are `DR-nnn` design rules in packs, one per family, each with its number range:
+
+| range | pack | what it covers | source |
+|---|---|---|---|
+| DR-000–009 | engine | the policy itself: expired and unused exemptions, crashed rules | agentlint |
+| DR-010–099 | `skills` | SKILL.md: the Agent Skills specification (hard rules, then recommendations) and Claude Code's extensions | agentskills.io, code.claude.com/docs/en/skills |
+| DR-100–199 | `claudemd` | CLAUDE.md, AGENTS.md, CLAUDE.local.md, `.claude/rules`: imports, depth, size, scope, credentials | code.claude.com/docs/en/memory |
+| DR-200–299 | `mcp` | `.mcp.json` servers by transport type, expansions, approvals in settings, tool naming, credentials | code.claude.com/docs/en/mcp |
+| DR-300–399 | `agents` | `.claude/agents/*.md` subagents: loading, names, tools, values, preloaded skills, hooks, budget | code.claude.com/docs/en/sub-agents |
+| DR-400–499 | `settings` | `.claude/settings*.json`: strict JSON, permission rule syntax, modes that cannot apply, hooks, unknown keys | code.claude.com/docs/en/settings, permissions, hooks; the published schema |
+| DR-500–899 | | reserved | |
+| DR-900–999 | `projects/<name>/rules.py` | the project's own rules; one project pack per run | the project |
+
+**Discovery is automatic.** A pack finds its own files anywhere under the project root,
+skipping `.git`, `node_modules`, virtual environments and build trees. The report header
+lists what was found. A policy may add or narrow the skill globs; it never has to list
+files.
+
+## The model
+
+**Levels** are `error` (fails the run), `warn` (prints; fails with `--strict`), `info`
+(prints) and `off` (not run). A rule has a default; a policy may change it.
+
+**Exemptions** name a rule, a path glob, a reason, an owner and an expiry date. A covered
+finding is still reported, marked EXEMPT with its reason, so nothing disappears. An expired
+exemption stops applying and is reported itself (DR-001). One that matches nothing is
+reported (DR-002). A rule that crashes is reported (DR-003), never skipped in silence.
+
+**Skips** are rules that could not run, for example a project table that would not import.
+A skip is visible in every report and never counts as a pass.
+
+**Exit codes**: 0 pass · 1 findings at a failing level · 2 the policy or a pack is broken
+(nothing was validated).
+
+## A project
+
+```
+projects/<name>/
+  policy.toml       root, packs, level overrides, exemptions (skill globs only to add or narrow)
+  rules.py          the project's DR-9xx rules (optional)
+  RULES.md          the generated register for this project
+  ...               data the rules need (friday keeps its connector catalogue here)
+```
+
+```toml
+[project]
+name = "friday"
+root = "../../../friday"                      # relative to this file
+
+[rules]
+packs = ["skills", "claudemd", "mcp", "agents", "settings", "rules.py"]
+
+[rules.levels]
+DR-024 = "off"                                # error | warn | info | off
+
+[[exemptions]]
+rule = "DR-013"
+path = "friday/assets/*/.claude/skills/*/SKILL.md"
+reason = "frontmatter moves under metadata in the next asset pass"
+by = "suhail"
+until = 2026-10-09                            # a bare date
+```
+
+A policy is found by project name under `projects/`, or given as a path. A project with no
+special rules needs only the `[project]` table; every built-in pack then runs.
+
+## Writing a rule
+
+A rule is a generator that yields `(path, message)` pairs, paths relative to the project
+root, or `ctx.skip(reason)` when it cannot run.
+
+```python
+from agentlint.core import rule
+
+@rule("DR-905", "error", "one-line summary", source="where the rule comes from")
+def contracts(ctx):
+    """Why the rule exists, in a sentence or two. This is the register's explanation."""
+    for s in ctx.skills:            # discovered skills: dir, rel, text, meta, body, error
+        if ...:
+            yield s.rel, "what is wrong"
+```
+
+`ctx` carries `root`, `policy`, `skills`, `files(*globs)` for other project files, `rel(path)`,
+`inventory` for the report header, and a `cache` dict a pack can use to parse something once.
+`agentlint/packs/_shared.py` has the helpers the built-in packs share: frontmatter and JSON
+file loaders, the secret detector, hook and MCP server shape checks, tool and permission
+rule syntax, the bundled settings schema. A new family is a new module under
+`agentlint/packs/` with its own range, named in a policy's `packs`.
+
+## Reports
+
+- `text`: what was found, one line per open finding, skips, exemptions grouped by entry, a summary line.
+- `json`: inventory, findings, exemptions with state and match counts, the full register.
+- `github`: `::error` / `::warning` / `::notice` annotations for Actions, plus the summary.
+- `html`: a self-contained page with the verdict, a filterable findings table, the
+  exemptions table and the rules register. Write it with `--out`, open it with `--open`;
+  the text report still prints so CI logs show the result.
+
+## CI
+
+```yaml
+- run: pip install pyyaml -e ./agentlint -e ./friday
+- run: python -m agentlint friday --strict --format github
+- run: python -m agentlint friday --format html --out reports/friday.html
+  if: always()
+- uses: actions/upload-artifact@v4
+  if: always()
+  with: { name: agentlint-friday, path: reports/friday.html }
+```
+
+## Projects
+
+- `friday`: the desk. Its pack covers the desk layout, the connector scope, the code
+  tables that mirror the assets, identical copies of shared skills and packaging.

maat16_agentlint-0.1.1.dev3/README.md

@@ -0,0 +1,156 @@
+# agentlint
+
+Design-rule governance for agent projects. One tool, many projects: it discovers a
+project's skills, subagents, CLAUDE.md and AGENTS.md files, MCP configuration and Claude
+Code settings, checks each against its family of rules, adds the project's own rules, and
+reports under a policy that says which rules apply, at what level, and what is exempt for
+how long and why.
+
+```
+python -m agentlint friday                         # text report, exit 1 on errors
+python -m agentlint friday --strict                # warnings fail too (CI)
+python -m agentlint friday --format html --out reports/friday.html --open
+python -m agentlint friday --format github         # GitHub Actions annotations
+python -m agentlint friday --format json           # for other tools
+python -m agentlint friday --list-rules            # the register for that project
+python -m agentlint --list-rules                   # the built-in register, no project needed
+```
+
+Needs Python 3.11+ and pyyaml. `pip install maat16-agentlint` (PyPI; the bare name is taken and `agent-lint` too similar —
+the import name and command are still `agentlint`) or `pip install -e .` from a checkout adds
+the `agentlint` command. `pip install --pre maat16-agentlint` tracks `main`: every push there is
+published as a dev pre-release by `.github/workflows/publish.yml`, and a `vX.Y.Z` tag
+publishes a final version.
+
+## The rules, documented
+
+Every rule is declared in code with its id, default level, summary, explanation and source,
+and the documents are generated from that register so they cannot drift:
+
+- **[docs/](docs/README.md)**: the common rules, one document per family.
+- **`projects/<name>/RULES.md`**: everything that runs for one project, including its own
+  rules, with the levels its policy makes effective.
+
+Regenerate after any rule or policy change:
+
+```
+python -m agentlint --list-rules --format md --split --out docs
+python -m agentlint friday --list-rules --format md --out projects/friday/RULES.md
+```
+
+## Families
+
+Rules are `DR-nnn` design rules in packs, one per family, each with its number range:
+
+| range | pack | what it covers | source |
+|---|---|---|---|
+| DR-000–009 | engine | the policy itself: expired and unused exemptions, crashed rules | agentlint |
+| DR-010–099 | `skills` | SKILL.md: the Agent Skills specification (hard rules, then recommendations) and Claude Code's extensions | agentskills.io, code.claude.com/docs/en/skills |
+| DR-100–199 | `claudemd` | CLAUDE.md, AGENTS.md, CLAUDE.local.md, `.claude/rules`: imports, depth, size, scope, credentials | code.claude.com/docs/en/memory |
+| DR-200–299 | `mcp` | `.mcp.json` servers by transport type, expansions, approvals in settings, tool naming, credentials | code.claude.com/docs/en/mcp |
+| DR-300–399 | `agents` | `.claude/agents/*.md` subagents: loading, names, tools, values, preloaded skills, hooks, budget | code.claude.com/docs/en/sub-agents |
+| DR-400–499 | `settings` | `.claude/settings*.json`: strict JSON, permission rule syntax, modes that cannot apply, hooks, unknown keys | code.claude.com/docs/en/settings, permissions, hooks; the published schema |
+| DR-500–899 | | reserved | |
+| DR-900–999 | `projects/<name>/rules.py` | the project's own rules; one project pack per run | the project |
+
+**Discovery is automatic.** A pack finds its own files anywhere under the project root,
+skipping `.git`, `node_modules`, virtual environments and build trees. The report header
+lists what was found. A policy may add or narrow the skill globs; it never has to list
+files.
+
+## The model
+
+**Levels** are `error` (fails the run), `warn` (prints; fails with `--strict`), `info`
+(prints) and `off` (not run). A rule has a default; a policy may change it.
+
+**Exemptions** name a rule, a path glob, a reason, an owner and an expiry date. A covered
+finding is still reported, marked EXEMPT with its reason, so nothing disappears. An expired
+exemption stops applying and is reported itself (DR-001). One that matches nothing is
+reported (DR-002). A rule that crashes is reported (DR-003), never skipped in silence.
+
+**Skips** are rules that could not run, for example a project table that would not import.
+A skip is visible in every report and never counts as a pass.
+
+**Exit codes**: 0 pass · 1 findings at a failing level · 2 the policy or a pack is broken
+(nothing was validated).
+
+## A project
+
+```
+projects/<name>/
+  policy.toml       root, packs, level overrides, exemptions (skill globs only to add or narrow)
+  rules.py          the project's DR-9xx rules (optional)
+  RULES.md          the generated register for this project
+  ...               data the rules need (friday keeps its connector catalogue here)
+```
+
+```toml
+[project]
+name = "friday"
+root = "../../../friday"                      # relative to this file
+
+[rules]
+packs = ["skills", "claudemd", "mcp", "agents", "settings", "rules.py"]
+
+[rules.levels]
+DR-024 = "off"                                # error | warn | info | off
+
+[[exemptions]]
+rule = "DR-013"
+path = "friday/assets/*/.claude/skills/*/SKILL.md"
+reason = "frontmatter moves under metadata in the next asset pass"
+by = "suhail"
+until = 2026-10-09                            # a bare date
+```
+
+A policy is found by project name under `projects/`, or given as a path. A project with no
+special rules needs only the `[project]` table; every built-in pack then runs.
+
+## Writing a rule
+
+A rule is a generator that yields `(path, message)` pairs, paths relative to the project
+root, or `ctx.skip(reason)` when it cannot run.
+
+```python
+from agentlint.core import rule
+
+@rule("DR-905", "error", "one-line summary", source="where the rule comes from")
+def contracts(ctx):
+    """Why the rule exists, in a sentence or two. This is the register's explanation."""
+    for s in ctx.skills:            # discovered skills: dir, rel, text, meta, body, error
+        if ...:
+            yield s.rel, "what is wrong"
+```
+
+`ctx` carries `root`, `policy`, `skills`, `files(*globs)` for other project files, `rel(path)`,
+`inventory` for the report header, and a `cache` dict a pack can use to parse something once.
+`agentlint/packs/_shared.py` has the helpers the built-in packs share: frontmatter and JSON
+file loaders, the secret detector, hook and MCP server shape checks, tool and permission
+rule syntax, the bundled settings schema. A new family is a new module under
+`agentlint/packs/` with its own range, named in a policy's `packs`.
+
+## Reports
+
+- `text`: what was found, one line per open finding, skips, exemptions grouped by entry, a summary line.
+- `json`: inventory, findings, exemptions with state and match counts, the full register.
+- `github`: `::error` / `::warning` / `::notice` annotations for Actions, plus the summary.
+- `html`: a self-contained page with the verdict, a filterable findings table, the
+  exemptions table and the rules register. Write it with `--out`, open it with `--open`;
+  the text report still prints so CI logs show the result.
+
+## CI
+
+```yaml
+- run: pip install pyyaml -e ./agentlint -e ./friday
+- run: python -m agentlint friday --strict --format github
+- run: python -m agentlint friday --format html --out reports/friday.html
+  if: always()
+- uses: actions/upload-artifact@v4
+  if: always()
+  with: { name: agentlint-friday, path: reports/friday.html }
+```
+
+## Projects
+
+- `friday`: the desk. Its pack covers the desk layout, the connector scope, the code
+  tables that mirror the assets, identical copies of shared skills and packaging.

maat16_agentlint-0.1.1.dev3/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"

maat16_agentlint-0.1.1.dev3/agentlint/__main__.py

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

maat16_agentlint-0.1.1.dev3/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())