kragg 0.3.0__py3-none-any.whl

kragg/__init__.py

@@ -0,0 +1,5 @@
+"""Opinionated guardrails for AI-assisted Python projects."""
+
+__version__ = "0.3.0"
+
+__all__ = ["__version__"]

kragg/__main__.py

@@ -0,0 +1,4 @@
+from kragg.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kragg/brief.py

@@ -0,0 +1,127 @@
+"""Change brief: a human-reviewable digest of the working-tree change set.
+
+A vibe-coded change is sane when a reviewer can grasp it in minutes. The
+brief groups changed files by area, names the critical functions touched,
+and reports the last gate run — markdown ready for a PR description.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kragg import journal
+from kragg.gates.critical_tests import critical_in_files
+from kragg.policy import KraggPolicy
+from kragg.runner import run_command
+
+
+def build_brief(root: Path, policy: KraggPolicy, since: str | None) -> str | None:
+    """Build the markdown brief; None when git is unavailable."""
+    base = _resolve_base(root, since)
+    if base is None:
+        return None
+    changed = _changed_files(root, base)
+    if changed is None:
+        return None
+    lines = ["# Change brief", ""]
+    lines.append(_stats_line(root, base, changed, since))
+    lines.append("")
+    lines.extend(_grouped_sections(changed, policy))
+    lines.extend(_critical_section(root, policy, changed))
+    lines.extend(_gate_section(root))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _resolve_base(root: Path, since: str | None) -> str | None:
+    if since is None:
+        return "HEAD"
+    merge_base = _git_lines(root, "merge-base", since, "HEAD")
+    return merge_base[0].strip() if merge_base else None
+
+
+def _changed_files(root: Path, base: str) -> list[str] | None:
+    if _git_lines(root, "rev-parse", "--is-inside-work-tree") is None:
+        return None
+    changed = _git_lines(root, "diff", "--name-only", "--diff-filter=ACMR", base)
+    untracked = _git_lines(root, "ls-files", "--others", "--exclude-standard")
+    files: list[str] = []
+    for raw in [*(changed or []), *(untracked or [])]:
+        name = raw.strip()
+        if name and not name.startswith(".kragg/") and name not in files:
+            files.append(name)
+    return files
+
+
+def _stats_line(
+    root: Path,
+    base: str,
+    changed: list[str],
+    since: str | None,
+) -> str:
+    added = deleted = 0
+    for line in _git_lines(root, "diff", "--numstat", base) or []:
+        parts = line.split("\t")
+        if len(parts) == 3 and parts[0].isdigit() and parts[1].isdigit():
+            added += int(parts[0])
+            deleted += int(parts[1])
+    against = since or "HEAD"
+    return f"{len(changed)} files changed (+{added} / -{deleted}) vs {against}"
+
+
+def _grouped_sections(changed: list[str], policy: KraggPolicy) -> list[str]:
+    groups: dict[str, list[str]] = {"Source": [], "Tests": [], "Other": []}
+    for name in changed:
+        groups[_area(name, policy)].append(name)
+    lines: list[str] = []
+    for title in ("Source", "Tests", "Other"):
+        if groups[title]:
+            lines.append(f"## {title}")
+            lines.extend(f"- {name}" for name in groups[title])
+            lines.append("")
+    return lines
+
+
+def _area(name: str, policy: KraggPolicy) -> str:
+    path = Path(name)
+    if any(path.is_relative_to(prefix) for prefix in policy.source_paths):
+        return "Source"
+    if any(path.is_relative_to(prefix) for prefix in policy.test_paths):
+        return "Tests"
+    return "Other"
+
+
+def _critical_section(
+    root: Path,
+    policy: KraggPolicy,
+    changed: list[str],
+) -> list[str]:
+    python_files = [name for name in changed if name.endswith(".py")]
+    touched = critical_in_files(root, policy.source_paths, python_files)
+    lines = ["## Critical functions touched"]
+    if touched:
+        lines.extend(
+            f"- `{qualname}` (fan-in {fan_in}) in {file}"
+            for qualname, fan_in, file in touched
+        )
+    else:
+        lines.append("none")
+    lines.append("")
+    return lines
+
+
+def _gate_section(root: Path) -> list[str]:
+    runs = journal.read_runs(root, 10)
+    lines = ["## Last gate run"]
+    if runs:
+        lines.extend(journal.render_status_lines(runs))
+    else:
+        lines.append("no recorded runs (run `uv run kragg check`)")
+    return lines
+
+
+def _git_lines(root: Path, *args: str) -> list[str] | None:
+    try:
+        result = run_command("git", ["git", *args], root)
+    except OSError:
+        return None
+    return result.stdout.splitlines() if result.passed else None

kragg/catalog.py

@@ -0,0 +1,456 @@
+"""Gate catalog: assembles the concrete check and security pipelines."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+from kragg.check import FAST, SLOW, GateSpec, OutputParser
+from kragg.coverage import COVERAGE_JSON_RELATIVE
+from kragg.environment import (
+    ProjectEnvironment,
+    missing_interpreter_message,
+    missing_module,
+    remediation,
+)
+from kragg.gates import (
+    architecture,
+    critical_coverage,
+    critical_tests,
+    halstead,
+    secrets,
+    test_quality,
+    type_complexity,
+)
+from kragg.models import GateResult, Violation
+from kragg.parsers import (
+    parse_bandit_json,
+    parse_mypy_output,
+    parse_pip_audit_json,
+    parse_pytest_output,
+    parse_radon_cc,
+    parse_radon_mi,
+    parse_ruff_json,
+)
+from kragg.policy import KraggPolicy
+from kragg.runner import run_command
+
+
+def build_check_gates(
+    root: Path,
+    policy: KraggPolicy,
+    env: ProjectEnvironment,
+    targets: tuple[str, ...],
+    incremental: bool = False,
+) -> list[GateSpec]:
+    """Assemble the full `kragg check` pipeline."""
+    slow_skip = "incremental mode" if incremental else None
+    (root / ".kragg").mkdir(parents=True, exist_ok=True)
+    pytest_args = (
+        "--cov=src",
+        "--cov-report=term-missing",
+        f"--cov-report=json:{COVERAGE_JSON_RELATIVE}",
+        f"--cov-fail-under={policy.coverage_fail_under}",
+        "-q",
+    )
+    return [
+        GateSpec("ruff", FAST, lambda: _ruff_gate(root, targets)),
+        GateSpec(
+            "mypy",
+            FAST,
+            lambda: _project_tool_gate(
+                "mypy", env, root, "mypy", targets, parse_mypy_output
+            ),
+        ),
+        GateSpec("radon-cc", FAST, lambda: _radon_cc_gate(root, targets)),
+        GateSpec("radon-mi", FAST, lambda: _radon_mi_gate(root, targets)),
+        GateSpec("halstead", FAST, lambda: _halstead_gate(root, targets)),
+        GateSpec(
+            "type-complexity",
+            FAST,
+            lambda: _type_complexity_gate(root, policy, targets),
+        ),
+        GateSpec(
+            "boundaries",
+            FAST,
+            lambda: _boundaries_gate(root, policy),
+            skip_reason=None if len(policy.layers) >= 2 else "no layers configured",
+        ),
+        GateSpec("structure", FAST, lambda: _structure_gate(root, policy)),
+        GateSpec(
+            "critical-tests",
+            FAST,
+            lambda: _critical_tests_gate(root, policy),
+            skip_reason=_no_criticality_reason(root),
+        ),
+        GateSpec("test-quality", FAST, lambda: _test_quality_gate(root, policy)),
+        GateSpec("bandit", FAST, lambda: _bandit_gate(root, targets)),
+        GateSpec("detect-secrets", FAST, lambda: _secrets_gate(root, targets)),
+        GateSpec(
+            "pytest-coverage",
+            SLOW,
+            lambda: _project_tool_gate(
+                "pytest-coverage",
+                env,
+                root,
+                "pytest",
+                pytest_args,
+                parse_pytest_output,
+            ),
+            skip_reason=slow_skip,
+        ),
+        GateSpec(
+            "critical-coverage",
+            SLOW,
+            lambda: _critical_coverage_gate(root, policy),
+            skip_reason=slow_skip or _no_criticality_reason(root),
+        ),
+        GateSpec(
+            "pip-audit",
+            SLOW,
+            lambda: _project_tool_gate(
+                "pip-audit",
+                env,
+                root,
+                "pip_audit",
+                ("-f", "json"),
+                parse_pip_audit_json,
+            ),
+            skip_reason=slow_skip,
+        ),
+    ]
+
+
+def _no_criticality_reason(root: Path) -> str | None:
+    if (root / ".kragg" / "criticality.json").exists():
+        return None
+    return "no criticality data (run `kragg criticality --write`)"
+
+
+def build_security_gates(
+    root: Path,
+    env: ProjectEnvironment,
+    targets: tuple[str, ...],
+    incremental: bool = False,
+) -> list[GateSpec]:
+    """Assemble the `kragg security` pipeline."""
+    slow_skip = "incremental mode" if incremental else None
+    return [
+        GateSpec("bandit", FAST, lambda: _bandit_gate(root, targets)),
+        GateSpec("detect-secrets", FAST, lambda: _secrets_gate(root, targets)),
+        GateSpec(
+            "pip-audit",
+            SLOW,
+            lambda: _project_tool_gate(
+                "pip-audit",
+                env,
+                root,
+                "pip_audit",
+                ("-f", "json"),
+                parse_pip_audit_json,
+            ),
+            skip_reason=slow_skip,
+        ),
+    ]
+
+
+def _project_tool_gate(
+    name: str,
+    env: ProjectEnvironment,
+    root: Path,
+    module: str,
+    args: tuple[str, ...],
+    parser: OutputParser | None,
+) -> GateResult:
+    """Run an environment-dependent tool on the project interpreter."""
+    if not env.found:
+        return GateResult(
+            name=name,
+            passed=False,
+            error=True,
+            output=missing_interpreter_message(root),
+        )
+    command = env.module_command(module, *args)
+    result = run_command(name, command, root)
+    if not result.passed:
+        missing = missing_module(result)
+        if missing is not None and _is_tool_module(module, missing):
+            return GateResult(
+                name=name,
+                passed=False,
+                error=True,
+                command=tuple(command),
+                output=(
+                    f"{module} is not installed in the project environment "
+                    f"({env.describe()}).\n{remediation(missing)}"
+                ),
+            )
+    violations = parser(result.stdout) if parser is not None else ()
+    return GateResult(
+        name=name,
+        passed=result.passed,
+        output="" if result.passed or violations else result.output,
+        command=tuple(command),
+        violations=violations,
+        violation_count=len(violations),
+    )
+
+
+def _is_tool_module(module: str, missing: str) -> bool:
+    """Only the tool itself missing is an environment error.
+
+    A user-code import failing inside pytest also prints "No module named X";
+    that is a test failure, not a broken environment.
+    """
+    return missing == module or (module == "pytest" and missing == "pytest_cov")
+
+
+def _command_gate(
+    name: str,
+    command: list[str],
+    root: Path,
+    parser: OutputParser,
+    error_codes: tuple[int, ...] = (),
+) -> GateResult:
+    result = run_command(name, command, root)
+    violations = parser(result.stdout)
+    return GateResult(
+        name=name,
+        passed=result.passed,
+        output="" if result.passed or violations else result.output,
+        command=tuple(command),
+        violations=violations,
+        violation_count=len(violations),
+        error=result.returncode in error_codes,
+    )
+
+
+def _ruff_gate(root: Path, targets: tuple[str, ...]) -> GateResult:
+    command = _kragg_module("ruff", "check", "--output-format", "json", *targets)
+
+    def parse(stdout: str) -> tuple[Violation, ...]:
+        return tuple(_relative_to_root(v, root) for v in parse_ruff_json(stdout))
+
+    return _command_gate("ruff", command, root, parse, error_codes=(2,))
+
+
+def _relative_to_root(violation: Violation, root: Path) -> Violation:
+    if violation.file is None:
+        return violation
+    path = Path(violation.file)
+    if path.is_absolute() and path.resolve().is_relative_to(root.resolve()):
+        return replace(violation, file=str(path.resolve().relative_to(root.resolve())))
+    return violation
+
+
+def _radon_cc_gate(root: Path, targets: tuple[str, ...]) -> GateResult:
+    command = _kragg_module("radon", "cc", *targets, "-s", "-n", "C")
+    result = run_command("radon-cc", command, root)
+    violations = parse_radon_cc(result.stdout)
+    passed = result.passed and not result.stdout.strip()
+    return GateResult(
+        name="radon-cc",
+        passed=passed,
+        output="" if passed or violations else result.output,
+        command=tuple(command),
+        violations=violations,
+        violation_count=len(violations),
+    )
+
+
+def _radon_mi_gate(root: Path, targets: tuple[str, ...]) -> GateResult:
+    command = _kragg_module("radon", "mi", *targets, "-s")
+    result = run_command("radon-mi", command, root)
+    violations = parse_radon_mi(result.stdout)
+    passed = result.passed and not violations
+    return GateResult(
+        name="radon-mi",
+        passed=passed,
+        output="" if passed or violations else result.output,
+        command=tuple(command),
+        violations=violations,
+        violation_count=len(violations),
+    )
+
+
+def _halstead_gate(root: Path, targets: tuple[str, ...]) -> GateResult:
+    violations: list[Violation] = []
+    for target in targets:
+        for failure in halstead.check_path(_resolve(root, target)):
+            location, _, function = failure.location.partition("::")
+            violations.append(
+                Violation(
+                    message=(
+                        f"{function or location}: {failure.metric} "
+                        f"{failure.actual:.1f} exceeds max {failure.maximum:.1f}"
+                    ),
+                    file=location,
+                    code="halstead",
+                    fix_hint="reduce operators/operands; split the function",
+                )
+            )
+    return GateResult(
+        name="halstead",
+        passed=not violations,
+        violations=tuple(violations),
+        violation_count=len(violations),
+    )
+
+
+def _type_complexity_gate(
+    root: Path,
+    policy: KraggPolicy,
+    targets: tuple[str, ...],
+) -> GateResult:
+    violations: list[Violation] = []
+    for target in targets:
+        found = type_complexity.check_path(
+            _resolve(root, target),
+            policy.type_max_nesting_depth,
+            policy.type_max_length,
+        )
+        for item in found:
+            violations.append(
+                Violation(
+                    message=(
+                        f"{item.context}: annotation `{item.annotation_text}` "
+                        f"(depth={item.depth}, length={item.length})"
+                    ),
+                    file=str(item.file_path),
+                    line=item.line or None,
+                    code="type-complexity",
+                    fix_hint=item.suggestion,
+                )
+            )
+    return GateResult(
+        name="type-complexity",
+        passed=not violations,
+        violations=tuple(violations),
+        violation_count=len(violations),
+    )
+
+
+def _boundaries_gate(root: Path, policy: KraggPolicy) -> GateResult:
+    violations = architecture.check_layers(root, policy.source_paths, policy.layers)
+    return GateResult(
+        name="boundaries",
+        passed=not violations,
+        violations=violations,
+        violation_count=len(violations),
+    )
+
+
+def _structure_gate(root: Path, policy: KraggPolicy) -> GateResult:
+    violations = architecture.check_structure(
+        root,
+        policy.source_paths,
+        policy.max_file_lines,
+        policy.max_public_symbols,
+    )
+    return GateResult(
+        name="structure",
+        passed=not violations,
+        violations=violations,
+        violation_count=len(violations),
+    )
+
+
+def _critical_tests_gate(root: Path, policy: KraggPolicy) -> GateResult:
+    violations = critical_tests.check_critical_tests(
+        root,
+        policy.source_paths,
+        policy.test_paths,
+    )
+    return GateResult(
+        name="critical-tests",
+        passed=not violations,
+        violations=violations,
+        violation_count=len(violations),
+    )
+
+
+def _test_quality_gate(root: Path, policy: KraggPolicy) -> GateResult:
+    violations = test_quality.check_tests(root, policy.test_paths)
+    return GateResult(
+        name="test-quality",
+        passed=not violations,
+        violations=violations,
+        violation_count=len(violations),
+    )
+
+
+def _critical_coverage_gate(root: Path, policy: KraggPolicy) -> GateResult:
+    violations = critical_coverage.check_critical_coverage(root, policy.source_paths)
+    return GateResult(
+        name="critical-coverage",
+        passed=not violations,
+        violations=violations,
+        violation_count=len(violations),
+    )
+
+
+def _bandit_gate(root: Path, targets: tuple[str, ...]) -> GateResult:
+    args = ["-ll", "-r", *targets, "-f", "json"]
+    if (root / "pyproject.toml").exists():
+        args = ["-c", "pyproject.toml", *args]
+    command = _kragg_module("bandit", *args)
+    return _command_gate("bandit", command, root, parse_bandit_json, error_codes=(2,))
+
+
+def _secrets_gate(root: Path, targets: tuple[str, ...]) -> GateResult:
+    try:
+        baseline = secrets.load_baseline(root)
+        violations = _scan_secrets(root, targets, baseline)
+    except RuntimeError as exc:
+        return GateResult(
+            name="detect-secrets",
+            passed=False,
+            error=True,
+            output=str(exc),
+        )
+    return GateResult(
+        name="detect-secrets",
+        passed=not violations,
+        violations=violations,
+        violation_count=len(violations),
+    )
+
+
+def _scan_secrets(
+    root: Path,
+    targets: tuple[str, ...],
+    baseline: dict[str, list[str]],
+) -> tuple[Violation, ...]:
+    violations: list[Violation] = []
+    for target in targets:
+        scan = secrets.scan_target(root, _resolve(root, target))
+        for filepath, findings in scan.items():
+            known = set(baseline.get(filepath, []))
+            for finding in findings:
+                hashed = finding.get("hashed_secret")
+                if not hashed or hashed in known:
+                    continue
+                raw_line = finding.get("line_number")
+                violations.append(
+                    Violation(
+                        message=f"potential secret: {finding.get('type', 'unknown')}",
+                        file=filepath,
+                        line=raw_line if isinstance(raw_line, int) else None,
+                        code="secret",
+                        fix_hint=(
+                            "remove the credential; if reviewed and safe, add it "
+                            "to .secrets.baseline"
+                        ),
+                    )
+                )
+    return tuple(violations)
+
+
+def _kragg_module(module: str, *args: str) -> list[str]:
+    return [sys.executable, "-m", module, *args]
+
+
+def _resolve(root: Path, target: str) -> Path:
+    path = Path(target)
+    return path if path.is_absolute() else root / path

kragg/changes.py

@@ -0,0 +1,81 @@
+"""Changed-file detection for incremental checks (`kragg check --changed`)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from kragg.runner import run_command
+
+
+def changed_python_files(
+    root: Path,
+    since: str | None,
+    allowed: Sequence[str],
+) -> list[str] | None:
+    """Return changed + untracked Python files under the allowed paths.
+
+    Returns None when git is unavailable or the root is not a repository.
+    """
+    if not _is_git_repository(root):
+        return None
+    base = _resolve_base(root, since)
+    if base is None:
+        return None
+    changed = _git(root, "diff", "--name-only", "--diff-filter=ACMR", base) or ""
+    untracked = _git(root, "ls-files", "--others", "--exclude-standard") or ""
+    names = [*changed.splitlines(), *untracked.splitlines()]
+    return _filter_python_files(root, names, allowed)
+
+
+def git_sha(root: Path) -> str | None:
+    """Short HEAD sha, or None outside a git repository."""
+    output = _git(root, "rev-parse", "--short", "HEAD")
+    return output.strip() if output is not None else None
+
+
+def git_dirty(root: Path) -> bool:
+    """Whether the working tree has uncommitted changes (False off a repo)."""
+    output = _git(root, "status", "--porcelain")
+    return bool(output.strip()) if output is not None else False
+
+
+def _resolve_base(root: Path, since: str | None) -> str | None:
+    if since is None:
+        return "HEAD"
+    merge_base = _git(root, "merge-base", since, "HEAD")
+    return merge_base.strip() if merge_base is not None else None
+
+
+def _filter_python_files(
+    root: Path,
+    names: list[str],
+    allowed: Sequence[str],
+) -> list[str]:
+    files: list[str] = []
+    for raw in names:
+        name = raw.strip()
+        if not name.endswith(".py") or name in files:
+            continue
+        if _is_allowed(name, allowed) and (root / name).exists():
+            files.append(name)
+    return files
+
+
+def _is_git_repository(root: Path) -> bool:
+    return _git(root, "rev-parse", "--is-inside-work-tree") is not None
+
+
+def _git(root: Path, *args: str) -> str | None:
+    try:
+        result = run_command("git", ["git", *args], root)
+    except OSError:
+        return None
+    return result.stdout if result.passed else None
+
+
+def _is_allowed(name: str, allowed: Sequence[str]) -> bool:
+    path = Path(name)
+    return any(
+        path == Path(prefix) or path.is_relative_to(prefix) for prefix in allowed
+    )