auditr 0.1.0__py3-none-any.whl

auditor/__init__.py

@@ -0,0 +1,45 @@
+"""auditor — a token-efficient repo auditor for coding agents.
+
+Public API:
+    from auditor import scan_file, scan_path, load_config, render, ScanEngine, IndexStore
+"""
+
+from loguru import logger
+
+from auditor.config import AuditorSettings, ResolvedConfig, load_config
+from auditor.engine import ScanEngine, audit_target
+from auditor.index import IndexStore
+from auditor.models import (
+    Category,
+    FileRole,
+    Finding,
+    IndexEntry,
+    ManifestEntry,
+    ScanResult,
+    Severity,
+    VerdictKind,
+)
+from auditor.reporters import render
+
+__all__ = [
+    "AuditorSettings",
+    "Category",
+    "FileRole",
+    "Finding",
+    "IndexEntry",
+    "IndexStore",
+    "ManifestEntry",
+    "ResolvedConfig",
+    "ScanEngine",
+    "ScanResult",
+    "Severity",
+    "VerdictKind",
+    "audit_target",
+    "load_config",
+    "render",
+]
+
+__version__ = "0.1.0"
+
+# Stay silent when embedded / under MCP; the CLI's logconfig.configure() re-enables it.
+logger.disable("auditor")

auditor/aggregate.py

@@ -0,0 +1,93 @@
+"""Roll up the index into a single AUDIT.md (replaces the prior ad-hoc /tmp/aggregate.py).
+
+Reads cached findings from the index — no re-scan — so `auditor aggregate` is cheap and
+reflects the last scan of the registered scope. Persistent ignores are applied here too, so the
+consolidated report matches what `scan` shows.
+"""
+
+from pathlib import Path
+
+from auditor.ignores import IgnoreList
+from auditor.index import IndexStore
+from auditor.models import FileRole, ScanResult, Severity, severity_rank
+
+
+class AuditAggregator:
+    """Builds the consolidated AUDIT.md from the index for a scope."""
+
+    def __init__(self, index: IndexStore) -> None:
+        self.index = index
+
+    async def _results(self) -> list[ScanResult]:
+        """Reconstruct per-file results from the index and drop ignored findings."""
+        entries = await self.index.files()
+        grouped = await self.index.findings_grouped()
+        results = [
+            ScanResult(
+                file=e.path,
+                language=e.language,
+                role=FileRole(e.role),
+                findings=grouped.get(e.path, []),
+            )
+            for e in entries
+        ]
+        IgnoreList.from_rows(await self.index.ignores()).filter(results)
+        return results
+
+    async def markdown(self) -> str:
+        return _render(await self._results())
+
+    async def write(self, out_path: Path) -> Path:
+        out_path.write_text(await self.markdown())
+        return out_path
+
+
+def _render(results: list[ScanResult]) -> str:
+    totals = {s: 0 for s in Severity}
+    for r in results:
+        for sev, n in r.counts.items():
+            totals[sev] += n
+    flagged = sorted(
+        (r for r in results if r.findings),
+        key=lambda r: -len(r.findings),
+    )
+
+    lines = [
+        "# Audit — consolidated report",
+        "",
+        f"Scope: {len(results)} files audited.",
+        "",
+        (
+            f"**Totals — blocking: {totals[Severity.BLOCKING]} · high: {totals[Severity.HIGH]} · "
+            f"medium: {totals[Severity.MEDIUM]} · low: {totals[Severity.LOW]} · "
+            f"suggestion: {totals[Severity.SUGGESTION]}**"
+        ),
+        "",
+        "## Files with findings (most severe first)",
+        "",
+        "| File | Role | Blocking | High | Medium | Low |",
+        "| --- | --- | --- | --- | --- | --- |",
+    ]
+    if flagged:
+        for r in flagged:
+            c = r.counts
+            lines.append(
+                f"| `{r.file}` | {r.role.value} | {c[Severity.BLOCKING]} | "
+                f"{c[Severity.HIGH]} | {c[Severity.MEDIUM]} | {c[Severity.LOW]} |"
+            )
+    else:
+        lines.append("| _(none)_ | | 0 | 0 | 0 | 0 |")
+    lines.append("")
+
+    candidates = [
+        f for r in results for f in r.findings if f.verdict_kind.value == "candidate"
+    ]
+    if candidates:
+        lines += ["## Candidates to judge", ""]
+        for f in sorted(
+            candidates, key=lambda f: (-severity_rank(f.severity), f.rule_id)
+        ):
+            lines.append(f"- **{f.severity.value}** `{f.rule_id}` — {f.message}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"

auditor/ast_util.py

@@ -0,0 +1,85 @@
+"""Low-level Python-AST helpers shared across the auditor (manifest construction,
+detectors). Pure functions over ``ast`` nodes — no project imports, no state."""
+
+import ast
+
+_FuncDef = ast.FunctionDef | ast.AsyncFunctionDef
+_PYDANTIC_BASES = frozenset({"BaseModel", "BaseSettings"})
+_UNTYPED_DICT_RETURNS = ("dict[str, Any]", "dict[str, typing.Any]")
+
+
+def dotted(node: ast.AST) -> str:
+    """Best-effort dotted name for a Name/Attribute/Call func, else an unparse fallback."""
+    if isinstance(node, ast.Call):
+        return dotted(node.func)
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = dotted(node.value)
+        return f"{base}.{node.attr}" if base else node.attr
+    try:
+        return ast.unparse(node)
+    except (ValueError, TypeError):
+        return ""
+
+
+def base_name(node: ast.AST) -> str:
+    """The final segment of a dotted name — a class base, callee, or decorator: ``a.b.c`` -> ``c``,
+    ``f`` -> ``f``. Receiver-blind, for matching a node against a set of bare names."""
+    return dotted(node).rsplit(".", 1)[-1]
+
+
+def decorator_names(node: ast.ClassDef | _FuncDef) -> tuple[str, ...]:
+    return tuple(
+        dotted(d.func if isinstance(d, ast.Call) else d) for d in node.decorator_list
+    )
+
+
+def class_field_count(cls: ast.ClassDef) -> int:
+    """Annotated class-level attributes — a proxy for Pydantic/dataclass field count."""
+    return sum(1 for stmt in cls.body if isinstance(stmt, ast.AnnAssign))
+
+
+def method_line_set(tree: ast.AST) -> set[int]:
+    """Line numbers of every method — a function defined directly in a class body."""
+    return {
+        sub.lineno
+        for node in ast.walk(tree)
+        if isinstance(node, ast.ClassDef)
+        for sub in node.body
+        if isinstance(sub, _FuncDef)
+    }
+
+
+def function_flags(fn: _FuncDef, *, is_method: bool) -> tuple[str, ...]:
+    flags: list[str] = []
+    if isinstance(fn, ast.AsyncFunctionDef):
+        flags.append("ASYNC")
+    if fn.returns is None and fn.name not in ("__init__", "__post_init__"):
+        flags.append("UNTYPED_RETURN")
+    positional = fn.args.posonlyargs + fn.args.args
+    untyped = [
+        p
+        for i, p in enumerate(positional)
+        if p.annotation is None and not (is_method and i == 0)
+    ]
+    if untyped or any(p.annotation is None for p in fn.args.kwonlyargs):
+        flags.append("UNTYPED_ARGS")
+    if fn.returns is not None and dotted(fn.returns) in _UNTYPED_DICT_RETURNS:
+        flags.append("UNTYPED_DICT_RETURN")
+    return tuple(flags)
+
+
+def class_flags(cls: ast.ClassDef) -> tuple[str, ...]:
+    flags: list[str] = []
+    base_names = {base_name(b) for b in cls.bases}
+    if base_names & _PYDANTIC_BASES:
+        flags.append("BASEMODEL")
+    if "dataclass" in {d.split(".")[-1] for d in decorator_names(cls)}:
+        flags.append("DATACLASS")
+    methods = [s for s in cls.body if isinstance(s, _FuncDef)]
+    if methods and all(
+        any(base_name(d) == "staticmethod" for d in m.decorator_list) for m in methods
+    ):
+        flags.append("ALL_STATICMETHODS")
+    return tuple(flags)

auditor/baseline.py

@@ -0,0 +1,69 @@
+"""Baseline support: snapshot today's findings, then on later scans report only the *new* ones.
+
+A baseline stores a line-independent fingerprint per finding — ``(file, rule_id, hash(evidence))``
+— so a finding survives line shifts (edits elsewhere in the file) but a genuinely new issue (new
+offending text) is still surfaced. This is what makes the auditor adoptable on a large existing
+repo: accept the current findings as the baseline, then gate only on what you add.
+
+Fingerprints are stored as a **multiset** (one entry per occurrence), so when several distinct
+findings in a file legitimately share a snippet — e.g. three untyped ``def __init__(`` — all three
+are recorded and a fourth, newly-added one still surfaces. A set would collapse them and silently
+hide the new occurrence. ``filter`` therefore hides up to the recorded count per fingerprint."""
+
+import hashlib
+from collections import Counter
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from auditor.models import Finding, ScanResult
+
+
+def finding_fingerprint(file: str, finding: Finding) -> str:
+    """A stable, line-independent identity: file + rule + a hash of the offending text. Survives
+    line moves; changed/new offending text yields a new fingerprint (reported as new)."""
+    evidence = (finding.evidence or "").strip()
+    return hashlib.sha256(
+        f"{file}\x00{finding.rule_id}\x00{evidence}".encode()
+    ).hexdigest()
+
+
+class Baseline(BaseModel):
+    """A recorded multiset of accepted findings, by fingerprint. Stored as JSON — ``fingerprints``
+    is sorted with one entry per baselined occurrence (repeats are meaningful)."""
+
+    version: int = 1
+    fingerprints: list[str] = Field(default_factory=list)  # sorted; one entry per occurrence
+
+    @classmethod
+    def from_results(cls, results: list[ScanResult]) -> "Baseline":
+        fps = [finding_fingerprint(r.file, f) for r in results for f in r.findings]
+        return cls(fingerprints=sorted(fps))
+
+    @classmethod
+    def load(cls, path: Path) -> "Baseline":
+        return cls.model_validate_json(path.read_text(encoding="utf-8"))
+
+    def write(self, path: Path) -> int:
+        """Persist the baseline; return the number of finding occurrences recorded."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(self.model_dump_json(indent=2) + "\n", encoding="utf-8")
+        return len(self.fingerprints)
+
+    def filter(self, results: list[ScanResult]) -> int:
+        """Drop already-baselined findings from each result in place; return how many were hidden.
+        Hides up to the recorded count per fingerprint, so an occurrence beyond what was baselined
+        (e.g. a newly-added finding sharing a snippet with baselined ones) still surfaces."""
+        budget = Counter(self.fingerprints)
+        hidden = 0
+        for result in results:
+            kept: list[Finding] = []
+            for finding in result.findings:
+                fp = finding_fingerprint(result.file, finding)
+                if budget[fp] > 0:
+                    budget[fp] -= 1
+                    hidden += 1
+                else:
+                    kept.append(finding)
+            result.findings = kept
+        return hidden

auditor/builtins.py

@@ -0,0 +1,20 @@
+"""Importing this module registers all built-in languages and detectors.
+
+Centralizes the one bootstrap import so other modules can depend on registration via a
+plain top-level import (no inline imports, no import cycle: ``PythonAuditor`` references
+``ResolvedConfig`` only under TYPE_CHECKING).
+"""
+
+import auditor.languages.bash.auditor  # noqa: F401  (registers BashAuditor + shell detectors)
+import auditor.languages.manifest.auditor  # noqa: F401  (registers ManifestAuditor + supply-chain detectors)
+import auditor.languages.python.auditor  # noqa: F401  (registers PythonAuditor + every detector)
+import auditor.reporters  # noqa: F401  (registers json/sarif/markdown reporters)
+
+# TypeScript support needs the optional `ts` extra (tree-sitter). Register it when present;
+# without the extra the core Python auditor still works.
+try:
+    import auditor.languages.typescript.auditor  # noqa: F401  (registers TypeScriptAuditor + TS detectors)
+
+    TYPESCRIPT_AVAILABLE = True
+except ImportError:
+    TYPESCRIPT_AVAILABLE = False

auditor/cli/__init__.py

@@ -0,0 +1,33 @@
+"""Command-line interface (typer), split one file per command. ``apps`` holds the root ``app``
+and the status console, ``options`` / ``helpers`` / ``summary`` the shared pieces, and each
+command module owns its handler (and its sub-app, when it has one). This package ``__init__`` is
+the composition root: importing the root commands registers them, and the sub-apps are mounted
+here. The ``auditor.cli:app`` entry point resolves to the ``app`` exported below.
+"""
+
+from auditor.cli import (  # noqa: F401 — imported for their @app.command() side effects
+    aggregate,
+    crossfile,
+    discover,
+    manifest,
+    report,
+    scan,
+)
+from auditor.cli.apps import app
+from auditor.cli.config import config_app
+from auditor.cli.ignore import ignore_app
+from auditor.cli.index import index_app
+from auditor.cli.plugins import plugins_app
+from auditor.cli.rules import rules_app
+from auditor.languages.python.auditor import PythonAuditor
+
+app.add_typer(index_app, name="index")
+app.add_typer(ignore_app, name="ignore")
+app.add_typer(config_app, name="config")
+app.add_typer(rules_app, name="rules")
+app.add_typer(plugins_app, name="plugins")
+
+# ensure all built-in languages register for discovery's suffix list
+_ = PythonAuditor
+
+__all__ = ["app"]

auditor/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Enables ``python -m auditor.cli``."""
+
+from auditor.cli import app
+
+if __name__ == "__main__":
+    app()

auditor/cli/aggregate.py

@@ -0,0 +1,27 @@
+"""``auditor aggregate`` — roll up the index into AUDIT.md."""
+
+from pathlib import Path
+
+import typer
+
+from auditor.aggregate import AuditAggregator
+from auditor.cli.apps import app
+from auditor.cli.helpers import _open_index, _run
+from auditor.cli.options import AggregateOut, DirTarget
+from auditor.discovery import find_root
+
+
+@app.command()
+def aggregate(
+    target: DirTarget = Path("."),
+    out: AggregateOut = Path("AUDIT.md"),
+) -> None:
+    """Roll up the index into AUDIT.md (run `scan --incremental` first)."""
+    root = find_root(target)
+    path = _run(_aggregate(root, out), "aggregating…")
+    typer.echo(f"wrote {path}")
+
+
+async def _aggregate(root: Path, out: Path) -> Path:
+    async with await _open_index(root) as index:
+        return await AuditAggregator(index).write(out)

auditor/cli/apps.py

@@ -0,0 +1,18 @@
+"""The root typer ``app`` and the stderr status console — the two things every command module
+shares. Each command module registers its handler on ``app`` (or defines its own sub-app);
+``cli/__init__`` is the composition root that imports every command module and mounts the
+sub-apps. Kept dependency-free so it stays a safe leaf import for the command modules.
+"""
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="A token-efficient repo auditor."
+)
+
+
+# Goes to STDERR so it never corrupts the JSON/SARIF stdout that agents parse; rich auto-disables
+# the spinner when stderr isn't a TTY (piped/captured output). The human summary uses its own
+# stdout console in `cli.summary`.
+_status = Console(stderr=True)

auditor/cli/config.py

@@ -0,0 +1,28 @@
+"""``auditor config show`` — print the resolved configuration."""
+
+from pathlib import Path
+
+import typer
+from pydantic import ValidationError
+
+from auditor.cli.helpers import (
+    _echo_json,
+    _fail,
+    _format_config_error,
+    _parse_config_json,
+)
+from auditor.cli.options import ConfigJson, RootArg
+from auditor.config import load_config
+from auditor.discovery import find_root
+
+config_app = typer.Typer(no_args_is_help=True, help="Inspect resolved configuration.")
+
+
+@config_app.command("show")
+def config_show(target: RootArg = Path("."), config_json: ConfigJson = None) -> None:
+    """Print the resolved configuration."""
+    try:
+        settings = load_config(find_root(target), overrides=_parse_config_json(config_json))
+    except ValidationError as exc:
+        _fail(f"invalid config — {_format_config_error(exc)}")
+    _echo_json(settings.model_dump(mode="json"))

auditor/cli/crossfile.py

@@ -0,0 +1,29 @@
+"""``auditor crossfile`` — recompute cross-file duplicate findings from the index."""
+
+from pathlib import Path
+
+from auditor import crossfile as crossfile_pass
+from auditor.cli.apps import app
+from auditor.cli.helpers import _echo_json, _open_index, _run
+from auditor.cli.options import DirTarget
+from auditor.config import load_config
+from auditor.discovery import find_root
+
+
+@app.command()
+def crossfile(target: DirTarget = Path(".")) -> None:
+    """Recompute cross-file duplicate findings from the index."""
+    root = find_root(target)
+    count = _run(_crossfile(root), "cross-file pass…")
+    _echo_json({"cross_file_findings": count})
+
+
+async def _crossfile(root: Path) -> int:
+    settings = load_config(root)
+    async with await _open_index(root) as index:
+        per_file = await crossfile_pass.run(
+            index,
+            settings_modules=settings.settings_modules,
+            settings_cohesion_on=settings.settings_cohesion,
+        )
+        return sum(len(v) for v in per_file.values())

auditor/cli/discover.py

@@ -0,0 +1,43 @@
+"""``auditor discover`` — list auditable files with their classified role."""
+
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from auditor.cli.apps import app
+from auditor.cli.helpers import (
+    _echo_json,
+    _fail,
+    _format_config_error,
+    _parse_config_json,
+    _require_exists,
+)
+from auditor.cli.options import ConfigJson, DirTarget
+from auditor.config import load_config
+from auditor.discovery import FileDiscovery, find_root
+from auditor.roles import RoleClassifier
+
+
+@app.command()
+def discover(target: DirTarget = Path("."), config_json: ConfigJson = None) -> None:
+    """List auditable files with their classified role."""
+    _require_exists(target)
+    root = find_root(target)
+    try:
+        settings = load_config(root, overrides=_parse_config_json(config_json))
+    except ValidationError as exc:
+        _fail(f"invalid config — {_format_config_error(exc)}")
+    classifier = RoleClassifier(settings.role_globs)
+    out = []
+    discovery = FileDiscovery(
+        root,
+        exclude_globs=tuple(settings.exclude),
+        respect_gitignore=settings.respect_gitignore,
+    )
+    for path in discovery.files(target):
+        rel = str(path.relative_to(root)) if path.is_relative_to(root) else str(path)
+        role = classifier.classify(
+            rel, path.read_text(encoding="utf-8", errors="replace")
+        )
+        out.append({"file": rel, "role": role.value})
+    _echo_json(out)

auditor/cli/helpers.py

@@ -0,0 +1,106 @@
+"""Shared CLI helpers: clean one-line error exits, the async-run spinner bridge, JSON echo,
+format validation, report emission, and index-path resolution. Command modules import what
+they need; anything used by a single command lives in that command's module instead.
+"""
+
+import asyncio
+import difflib
+import json
+from collections.abc import Coroutine, Iterable
+from pathlib import Path
+from typing import Any, NoReturn, TypeVar
+
+import typer
+from pydantic import ValidationError
+
+from auditor.cli.apps import _status
+from auditor.index import IndexStore
+from auditor.paths import index_db_path, repo_key
+from auditor.registry import REGISTRY
+
+_T = TypeVar("_T")
+
+
+def _echo_json(payload: object) -> None:
+    typer.echo(json.dumps(payload, indent=2))
+
+
+def _fail(message: str) -> NoReturn:
+    """Emit a clean one-line error to stderr and exit non-zero (no traceback)."""
+    _status.print(f"[red]error:[/red] {message}")
+    raise typer.Exit(1)
+
+
+def _suggest(value: str, candidates: Iterable[str]) -> str:
+    """`" Did you mean 'X'?"` when a candidate closely matches ``value``, else ``""`` — for
+    friendlier 'unknown rule/category/…' errors."""
+    match = difflib.get_close_matches(value, list(candidates), n=1, cutoff=0.6)
+    return f" Did you mean '{match[0]}'?" if match else ""
+
+
+def _parse_config_json(raw: str | None) -> dict | None:
+    """Parse a ``--config-json`` blob to a dict, or exit cleanly on bad JSON / non-object."""
+    if raw is None:
+        return None
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        _fail(f"invalid --config-json: {exc}")
+    if not isinstance(value, dict):
+        _fail("--config-json must be a JSON object")
+    return value
+
+
+def _format_config_error(exc: ValidationError) -> str:
+    """First validation error as ``'<dotted loc>: <msg>'`` for a clean one-line failure."""
+    err = exc.errors()[0]
+    loc = ".".join(str(p) for p in err["loc"])
+    return f"{loc}: {err['msg']}" if loc else err["msg"]
+
+
+def _require_exists(path: Path) -> None:
+    if not path.exists():
+        _fail(f"no such file or directory: {path}")
+
+
+def _require_file(path: Path) -> None:
+    if not path.is_file():
+        _fail(f"no such file: {path}")
+
+
+def _check_format(fmt: str) -> str:
+    if REGISTRY.reporter(fmt) is None:
+        _fail(f"unknown format {fmt!r}; choose from {sorted(REGISTRY.formats())}")
+    return fmt
+
+
+def _run(
+    coro: Coroutine[Any, Any, _T], message: str = "auditing…", *, spinner: bool = True
+) -> _T:
+    """Run an async core call. Shows a stderr spinner unless ``spinner`` is off (e.g. when
+    ``-v`` logging is driving the progress output instead)."""
+    if not spinner:
+        return asyncio.run(coro)
+    with _status.status(message, spinner="dots"):
+        return asyncio.run(coro)
+
+
+def _open_index(root: Path) -> Coroutine[Any, Any, IndexStore]:
+    """Connect to the shared global index, scoped to ``root``'s partition. Returns the
+    awaitable from ``IndexStore.connect`` (use as ``async with await _open_index(root)``)."""
+    return IndexStore.connect(index_db_path(), repo_key(root))
+
+
+def _open_shared_index() -> Coroutine[Any, Any, IndexStore]:
+    """Connect to the shared global index for cross-repo operations (listing/forgetting repos),
+    not bound to any one repo's partition."""
+    return IndexStore.connect(index_db_path())
+
+
+def _emit(rendered: str, output: Path | None) -> None:
+    """Write a rendered report to ``output`` (with a stderr note) or echo it to stdout."""
+    if output is None:
+        typer.echo(rendered)
+        return
+    output.write_text(rendered, encoding="utf-8")
+    typer.echo(f"wrote {output}", err=True)