agentslint 0.1.0__py3-none-any.whl

agentslint/__init__.py

@@ -0,0 +1,7 @@
+"""Static referential-integrity checks for agent instruction files."""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+__version__ = version("agentslint")

agentslint/__main__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from agentslint.cli import main
+
+raise SystemExit(main())

agentslint/cli.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from agentslint import __version__
+from agentslint.config import ConfigError
+from agentslint.diagnostics import render
+from agentslint.discovery import build_workspace
+from agentslint.engine import check_workspace
+from agentslint.models import Severity
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agentslint")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    check = subparsers.add_parser("check", help="validate agent instruction references")
+    check.add_argument("path", nargs="?", default=".", type=Path)
+    check.add_argument("--format", choices=("text", "github", "json"), default="text")
+    check.add_argument("--strict", action="store_true")
+    check.add_argument("--config", type=Path)
+    return parser
+
+
+def main(*, argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        workspace = build_workspace(target=args.path, explicit_config=args.config)
+        diagnostics = check_workspace(workspace=workspace)
+    except ConfigError as exc:
+        print(f"agentslint: configuration error: {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:  # pragma: no cover - final CLI safety boundary
+        print(f"agentslint: internal error: {exc}", file=sys.stderr)
+        return 2
+
+    output = render(
+        diagnostics=diagnostics,
+        output_format=args.format,
+        files_checked=len(workspace.instruction_files),
+    )
+    if output:
+        print(output)
+    if any(item.severity is Severity.ERROR for item in diagnostics):
+        return 1
+    if args.strict and any(item.severity is Severity.WARNING for item in diagnostics):
+        return 1
+    return 0

agentslint/config.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from agentslint.models import Severity
+
+DEFAULT_FILES = ("AGENTS.md", "**/AGENTS.md")
+DEFAULT_EXCLUDES = (".git/**", ".venv/**", "**/.venv/**", "node_modules/**", "**/node_modules/**")
+DEFAULT_MANAGED_TOOLS = frozenset(
+    {
+        "black",
+        "dbt",
+        "eslint",
+        "jest",
+        "playwright",
+        "prettier",
+        "pytest",
+        "ruff",
+        "shellcheck",
+        "sqlfluff",
+        "ty",
+    }
+)
+DEFAULT_TOOL_ALIASES = {
+    "dbt": "dbt-core",
+    "py.test": "pytest",
+}
+ADVISORY_RULES = frozenset(
+    {"command-unsupported", "scope-ambiguous", "shell-syntax", "unsupported-template"}
+)
+KNOWN_KEYS = {
+    "files",
+    "exclude",
+    "additional-managed-tools",
+    "disabled-managed-tools",
+    "tool-aliases",
+    "dbt-manifests",
+    "untracked-roots",
+    "ignore",
+    "severity",
+}
+
+
+class ConfigError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Ignore:
+    file: Path
+    rule: str
+    reference: str
+    reason: str
+    line: int | None = None
+
+
+@dataclass(frozen=True)
+class Config:
+    files: tuple[str, ...] = DEFAULT_FILES
+    excludes: tuple[str, ...] = DEFAULT_EXCLUDES
+    managed_tools: frozenset[str] = DEFAULT_MANAGED_TOOLS
+    tool_aliases: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_TOOL_ALIASES))
+    dbt_manifests: tuple[Path, ...] = ()
+    untracked_roots: tuple[Path, ...] = ()
+    ignores: tuple[Ignore, ...] = ()
+    severity: dict[str, Severity] = field(default_factory=dict)
+    source: Path | None = None
+
+
+def discover_config(*, root: Path, explicit: Path | None = None) -> Config:
+    if explicit is not None:
+        path = explicit if explicit.is_absolute() else (Path.cwd() / explicit)
+        path = path.resolve()
+        if not path.is_file():
+            raise ConfigError(f"configuration file does not exist: {explicit}")
+        return _load_config(path=path, explicit=True)
+
+    standalone = root / "agentslint.toml"
+    pyproject = root / "pyproject.toml"
+    has_standalone = standalone.is_file()
+    pyproject_data = _read_toml(path=pyproject) if pyproject.is_file() else {}
+    has_pyproject = isinstance(_nested(value=pyproject_data, keys=("tool", "agentslint")), dict)
+    if has_standalone and has_pyproject:
+        raise ConfigError("both agentslint.toml and [tool.agentslint] in pyproject.toml were found")
+    if has_standalone:
+        return _load_config(path=standalone, explicit=False)
+    if has_pyproject:
+        return _parse_config(
+            raw=_nested(value=pyproject_data, keys=("tool", "agentslint")),
+            source=pyproject,
+        )
+    return Config()
+
+
+def _load_config(*, path: Path, explicit: bool) -> Config:
+    data = _read_toml(path=path)
+    embedded = _nested(value=data, keys=("tool", "agentslint"))
+    if isinstance(embedded, dict):
+        section = embedded
+    elif path.name == "pyproject.toml":
+        if explicit:
+            raise ConfigError(f"{path} has no [tool.agentslint] table")
+        return Config()
+    else:
+        section = data
+    if not isinstance(section, dict):
+        raise ConfigError(f"agentslint configuration in {path} must be a table")
+    return _parse_config(raw=section, source=path)
+
+
+def _read_toml(*, path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as handle:
+            value = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"cannot read configuration {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ConfigError(f"configuration {path} must contain a TOML table")
+    return value
+
+
+def _nested(*, value: dict[str, Any], keys: tuple[str, ...]) -> Any:
+    current: Any = value
+    for key in keys:
+        if not isinstance(current, dict):
+            return None
+        current = current.get(key)
+    return current
+
+
+def _parse_config(*, raw: dict[str, Any], source: Path) -> Config:
+    unknown = sorted(set(raw) - KNOWN_KEYS)
+    if unknown:
+        raise ConfigError(f"unknown configuration key(s): {', '.join(unknown)}")
+
+    files = _string_tuple(value=raw.get("files", DEFAULT_FILES), key="files")
+    excludes = _string_tuple(value=raw.get("exclude", DEFAULT_EXCLUDES), key="exclude")
+    additional = set(
+        _string_tuple(value=raw.get("additional-managed-tools", ()), key="additional-managed-tools")
+    )
+    disabled = set(
+        _string_tuple(value=raw.get("disabled-managed-tools", ()), key="disabled-managed-tools")
+    )
+    overlap = additional & disabled
+    if overlap:
+        raise ConfigError(
+            "managed tools cannot be both added and disabled: " + ", ".join(sorted(overlap))
+        )
+    managed = (set(DEFAULT_MANAGED_TOOLS) | additional) - disabled
+
+    aliases = dict(DEFAULT_TOOL_ALIASES)
+    aliases.update(_string_mapping(value=raw.get("tool-aliases", {}), key="tool-aliases"))
+
+    manifests = tuple(
+        Path(item)
+        for item in _string_tuple(value=raw.get("dbt-manifests", ()), key="dbt-manifests")
+    )
+    untracked = tuple(
+        Path(item)
+        for item in _string_tuple(value=raw.get("untracked-roots", ()), key="untracked-roots")
+    )
+    ignores = _parse_ignores(value=raw.get("ignore", ()))
+    severity = _parse_severity(value=raw.get("severity", {}))
+    if not files:
+        raise ConfigError("files must contain at least one instruction filename or pattern")
+
+    return Config(
+        files=files,
+        excludes=excludes,
+        managed_tools=frozenset(managed),
+        tool_aliases=aliases,
+        dbt_manifests=manifests,
+        untracked_roots=untracked,
+        ignores=ignores,
+        severity=severity,
+        source=source,
+    )
+
+
+def _string_tuple(*, value: Any, key: str) -> tuple[str, ...]:
+    if not isinstance(value, list | tuple) or not all(
+        isinstance(item, str) and item for item in value
+    ):
+        raise ConfigError(f"{key} must be an array of non-empty strings")
+    return tuple(value)
+
+
+def _string_mapping(*, value: Any, key: str) -> dict[str, str]:
+    if not isinstance(value, dict) or not all(
+        isinstance(name, str) and name and isinstance(target, str) and target
+        for name, target in value.items()
+    ):
+        raise ConfigError(f"{key} must be a table of non-empty string values")
+    return dict(value)
+
+
+def _parse_ignores(*, value: Any) -> tuple[Ignore, ...]:
+    if not isinstance(value, list | tuple):
+        raise ConfigError("ignore must be an array of tables")
+    result: list[Ignore] = []
+    required = {"file", "rule", "reference", "reason"}
+    allowed = required | {"line"}
+    for index, item in enumerate(value):
+        if not isinstance(item, dict):
+            raise ConfigError(f"ignore[{index}] must be a table")
+        if not all(isinstance(key, str) for key in item):
+            raise ConfigError(f"ignore[{index}] keys must be strings")
+        item_keys = {str(key) for key in item}
+        missing = required - item_keys
+        unknown = item_keys - allowed
+        if missing or unknown:
+            details = []
+            if missing:
+                details.append("missing " + ", ".join(sorted(missing)))
+            if unknown:
+                details.append("unknown " + ", ".join(sorted(unknown)))
+            raise ConfigError(f"ignore[{index}] is invalid: {'; '.join(details)}")
+        if not all(isinstance(item[key], str) and item[key] for key in required):
+            raise ConfigError(f"ignore[{index}] fields must be non-empty strings")
+        line = item.get("line")
+        if line is not None and (not isinstance(line, int) or isinstance(line, bool) or line < 1):
+            raise ConfigError(f"ignore[{index}].line must be a positive integer")
+        result.append(
+            Ignore(
+                file=Path(item["file"]),
+                rule=item["rule"],
+                reference=item["reference"],
+                reason=item["reason"],
+                line=line,
+            )
+        )
+    return tuple(result)
+
+
+def _parse_severity(*, value: Any) -> dict[str, Severity]:
+    if not isinstance(value, dict):
+        raise ConfigError("severity must be a table")
+    result: dict[str, Severity] = {}
+    for rule, raw_severity in value.items():
+        if not isinstance(rule, str) or not isinstance(raw_severity, str):
+            raise ConfigError("severity must map rule names to strings")
+        if rule not in ADVISORY_RULES:
+            raise ConfigError(f"severity cannot be overridden for non-advisory rule: {rule}")
+        try:
+            result[rule] = Severity(raw_severity)
+        except ValueError as exc:
+            raise ConfigError(f"invalid severity for {rule}: {raw_severity}") from exc
+    return result

agentslint/diagnostics.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+
+from agentslint.models import Diagnostic, Severity
+
+
+def render_text(*, diagnostics: Iterable[Diagnostic], files_checked: int) -> str:
+    values = tuple(diagnostics)
+    lines = []
+    for diagnostic in sorted(values, key=Diagnostic.sort_key):
+        location = f"{diagnostic.document.as_posix()}:{diagnostic.line}"
+        if diagnostic.column is not None:
+            location += f":{diagnostic.column}"
+        lines.append(
+            f"{location}: {diagnostic.severity.value}[{diagnostic.rule}]: {diagnostic.message}"
+        )
+    if lines:
+        lines.append("")
+    lines.append(_text_summary(diagnostics=values, files_checked=files_checked))
+    return "\n".join(lines)
+
+
+def render_github(*, diagnostics: Iterable[Diagnostic]) -> str:
+    lines = []
+    for diagnostic in sorted(diagnostics, key=Diagnostic.sort_key):
+        properties = [
+            f"file={_escape_property(value=diagnostic.document.as_posix())}",
+            f"line={diagnostic.line}",
+            f"title={_escape_property(value=f'agentslint/{diagnostic.rule}')}",
+        ]
+        if diagnostic.column is not None:
+            properties.append(f"col={diagnostic.column}")
+        lines.append(
+            f"::{diagnostic.severity.value} {','.join(properties)}::"
+            f"{_escape_message(value=diagnostic.message)}"
+        )
+    return "\n".join(lines)
+
+
+def render_json(*, diagnostics: Iterable[Diagnostic], files_checked: int) -> str:
+    diagnostics = tuple(diagnostics)
+    values = []
+    for diagnostic in sorted(diagnostics, key=Diagnostic.sort_key):
+        values.append(
+            {
+                "file": diagnostic.document.as_posix(),
+                "line": diagnostic.line,
+                "column": diagnostic.column,
+                "rule": diagnostic.rule,
+                "severity": diagnostic.severity.value,
+                "message": diagnostic.message,
+                "reference": diagnostic.reference,
+            }
+        )
+    errors, warnings = _severity_counts(diagnostics=diagnostics)
+    return json.dumps(
+        {
+            "schema_version": 1,
+            "summary": {
+                "files_checked": files_checked,
+                "errors": errors,
+                "warnings": warnings,
+            },
+            "diagnostics": values,
+        },
+        indent=2,
+    )
+
+
+def render(*, diagnostics: Iterable[Diagnostic], output_format: str, files_checked: int) -> str:
+    if output_format == "json":
+        return render_json(diagnostics=diagnostics, files_checked=files_checked)
+    if output_format == "github":
+        return render_github(diagnostics=diagnostics)
+    return render_text(diagnostics=diagnostics, files_checked=files_checked)
+
+
+def _text_summary(*, diagnostics: Iterable[Diagnostic], files_checked: int) -> str:
+    errors, warnings = _severity_counts(diagnostics=diagnostics)
+    file_label = "instruction file" if files_checked == 1 else "instruction files"
+    prefix = f"agentslint: checked {files_checked} {file_label}; "
+    if not errors and not warnings:
+        return prefix + "no issues found"
+    counts = []
+    if errors:
+        counts.append(f"{errors} {'error' if errors == 1 else 'errors'}")
+    if warnings:
+        counts.append(f"{warnings} {'warning' if warnings == 1 else 'warnings'}")
+    return prefix + ", ".join(counts)
+
+
+def _severity_counts(*, diagnostics: Iterable[Diagnostic]) -> tuple[int, int]:
+    errors = 0
+    warnings = 0
+    for diagnostic in diagnostics:
+        if diagnostic.severity is Severity.ERROR:
+            errors += 1
+        else:
+            warnings += 1
+    return errors, warnings
+
+
+def _escape_property(*, value: str) -> str:
+    return (
+        value.replace("%", "%25")
+        .replace("\r", "%0D")
+        .replace("\n", "%0A")
+        .replace(":", "%3A")
+        .replace(",", "%2C")
+    )
+
+
+def _escape_message(*, value: str) -> str:
+    return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")

agentslint/discovery.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from fnmatch import fnmatchcase
+from pathlib import Path
+
+from agentslint.config import Config, ConfigError, discover_config
+from agentslint.workspace import Workspace
+
+
+def build_workspace(*, target: Path, explicit_config: Path | None = None) -> Workspace:
+    requested = target.expanduser()
+    if not requested.exists():
+        raise ConfigError(f"check path does not exist: {target}")
+    requested = requested.resolve()
+    start = requested.parent if requested.is_file() else requested
+    git_root = _git_root(start=start)
+    root = git_root or start
+    config = discover_config(root=root, explicit=explicit_config)
+    tracked = _git_paths(root=root) if git_root else None
+    git_backed = tracked is not None
+    if tracked is None:
+        tracked = _walk_paths(root=root, config=config)
+
+    existing = {path for path in tracked if (root / path).exists()}
+    existing.update(
+        parent for path in tuple(existing) for parent in path.parents if parent != Path(".")
+    )
+    for configured_root in config.untracked_roots:
+        absolute = (root / configured_root).resolve()
+        try:
+            absolute.relative_to(root)
+        except ValueError as exc:
+            raise ConfigError(f"untracked root escapes repository: {configured_root}") from exc
+        if absolute.exists():
+            if absolute.is_file():
+                existing.add(absolute.relative_to(root))
+            else:
+                existing.update(
+                    path.relative_to(root)
+                    for path in absolute.rglob("*")
+                    if path.is_file() or path.is_dir()
+                )
+
+    selected = _instruction_files(
+        root=root, requested=requested, tracked=tracked, existing=existing, config=config
+    )
+    return Workspace(
+        root=root,
+        target=requested,
+        config=config,
+        tracked_paths=frozenset(tracked),
+        existing_paths=frozenset(existing),
+        instruction_files=tuple(sorted(selected)),
+        git_backed=git_backed,
+    )
+
+
+def _git_root(*, start: Path) -> Path | None:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=start,
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return Path(result.stdout.strip()).resolve()
+
+
+def _git_paths(*, root: Path) -> set[Path] | None:
+    try:
+        result = subprocess.run(
+            ["git", "ls-files", "-z", "--cached"],
+            cwd=root,
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return {
+        Path(raw.decode("utf-8", errors="surrogateescape"))
+        for raw in result.stdout.split(b"\0")
+        if raw
+    }
+
+
+def _walk_paths(*, root: Path, config: Config) -> set[Path]:
+    result: set[Path] = set()
+    for current, directories, files in os.walk(root, topdown=True, followlinks=False):
+        current_path = Path(current)
+        kept_directories = []
+        for name in directories:
+            relative = (current_path / name).relative_to(root)
+            if _excluded_tree(path=relative, config=config):
+                continue
+            result.add(relative)
+            kept_directories.append(name)
+        directories[:] = kept_directories
+        for name in files:
+            relative = (current_path / name).relative_to(root)
+            if not _excluded(path=relative, config=config):
+                result.add(relative)
+    return result
+
+
+def _instruction_files(
+    *,
+    root: Path,
+    requested: Path,
+    tracked: set[Path],
+    existing: set[Path],
+    config: Config,
+) -> set[Path]:
+    if requested.is_file():
+        relative = requested.relative_to(root)
+        if relative not in tracked:
+            raise ConfigError(f"instruction file is not tracked: {relative}")
+        if not _is_instruction(path=relative, config=config):
+            raise ConfigError(f"file does not match configured instruction names: {relative}")
+        return {relative}
+
+    boundary = requested.relative_to(root)
+    selected = {
+        path
+        for path in tracked & existing
+        if _is_instruction(path=path, config=config)
+        and not _excluded(path=path, config=config)
+        and _beneath(path=path, boundary=boundary)
+    }
+    return selected
+
+
+def _is_instruction(*, path: Path, config: Config) -> bool:
+    value = path.as_posix()
+    return any(
+        value == pattern or path.name == pattern or fnmatchcase(value, pattern)
+        for pattern in config.files
+    )
+
+
+def _excluded(*, path: Path, config: Config) -> bool:
+    value = path.as_posix()
+    return any(fnmatchcase(value, pattern) for pattern in config.excludes)
+
+
+def _excluded_tree(*, path: Path, config: Config) -> bool:
+    return _excluded(path=path, config=config) or _excluded(
+        path=path / "__agentslint_descendant__",
+        config=config,
+    )
+
+
+def _beneath(*, path: Path, boundary: Path) -> bool:
+    if boundary == Path("."):
+        return True
+    try:
+        path.relative_to(boundary)
+    except ValueError:
+        return False
+    return True