commitguardian 0.1.0__py3-none-any.whl

commitguard/cli/commands/init.py

@@ -0,0 +1,137 @@
+"""``commitguard init``: set a repository up for enforcement.
+
+Writes ``.commitguard.yaml``, and can install the Git hooks and write a GitHub
+workflow. Existing files are never overwritten.
+
+Interactive by default when the terminal can answer (a TTY), and fully
+non-interactive otherwise, so scripts and CI behave the same as ``--non-interactive``:
+nothing is prompted, and only what the options ask for is done.
+"""
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from commitguard.cli.output import fail, handled_errors, info
+from commitguard.config.defaults import DEFAULT_CONFIG_FILENAME, DEFAULT_CONFIG_TEMPLATE
+from commitguard.config.loader import find_config
+from commitguard.git.repository import Repository
+from commitguard.github.workflow import CHECK_NAME, WORKFLOW_FILE, render_workflow
+from commitguard.utils.filesystem import atomic_write_text
+
+
+def _write_new(path: Path, content: str) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(path, content)
+    except FileExistsError:
+        fail(f"{path} already exists; not overwriting it")
+    except OSError as exc:
+        fail(f"could not write {path}: {exc.strerror}")
+
+
+def _ask(question: str, *, default: bool) -> bool:
+    return bool(typer.confirm(question, default=default))
+
+
+def init_command(
+    github: Annotated[
+        bool,
+        typer.Option("--github", help=f"Also create {WORKFLOW_FILE.as_posix()}."),
+    ] = False,
+    install: Annotated[
+        bool,
+        typer.Option(
+            "--install-hooks", help="Also install the Git hooks (as `commitguard install`)."
+        ),
+    ] = False,
+    non_interactive: Annotated[
+        bool,
+        typer.Option(
+            "--non-interactive",
+            help="Never prompt; do exactly what the options say (the default when not a terminal).",
+        ),
+    ] = False,
+    action_repository: Annotated[
+        str | None,
+        typer.Option(
+            "--action-repository",
+            help="Repository hosting the CommitGuard Action (OWNER/REPO), used with --github.",
+        ),
+    ] = None,
+    action_ref: Annotated[
+        str | None,
+        typer.Option(
+            "--action-ref",
+            help="Full commit SHA of the CommitGuard Action to pin, used with --github.",
+        ),
+    ] = None,
+) -> None:
+    """Create .commitguard.yaml, and optionally install hooks and a GitHub workflow."""
+    interactive = not non_interactive and sys.stdin.isatty() and sys.stdout.isatty()
+    with handled_errors():
+        repository = Repository.discover()
+        if interactive:
+            info(f"Setting up CommitGuard in {repository.root}")
+            if not github and not (action_repository or action_ref):
+                github = _ask(
+                    "Add a GitHub Actions check (recommended: it cannot be bypassed)?",
+                    default=False,
+                )
+                if github:
+                    action_repository = action_repository or typer.prompt(
+                        "Repository hosting the CommitGuard Action (OWNER/REPO)"
+                    )
+                    action_ref = action_ref or typer.prompt(
+                        "Commit SHA of the Action to pin (40 characters)"
+                    )
+            if not install:
+                install = _ask("Install the Git hooks in this repository now?", default=True)
+        workflow_path = repository.root / WORKFLOW_FILE
+        workflow_text = None
+        if github:
+            if not action_repository or not action_ref:
+                fail(
+                    "--github requires --action-repository OWNER/REPO and --action-ref "
+                    "<40-character commit SHA> (the Action is pinned to an exact commit)"
+                )
+            if workflow_path.exists() or workflow_path.is_symlink():
+                fail(f"{workflow_path} already exists; not overwriting it")
+            workflow_text = render_workflow(action_repository, action_ref)
+        elif action_repository or action_ref:
+            fail("--action-repository and --action-ref are only used with --github")
+
+        existing = find_config(repository.root)
+        if existing is not None and not github:
+            fail(f"configuration already exists: {existing}")
+
+        created = []
+        if existing is None:
+            target = repository.root / DEFAULT_CONFIG_FILENAME
+            _write_new(target, DEFAULT_CONFIG_TEMPLATE)
+            created.append(target)
+        if workflow_text is not None:
+            _write_new(workflow_path, workflow_text)
+            created.append(workflow_path)
+
+    for path in created:
+        info(f"Created {path}")
+    if install:
+        from commitguard.cli.commands.install import install_command
+
+        info("")
+        install_command()
+        info("")
+    if existing is not None:
+        info(f"Kept existing configuration: {existing}")
+    info("Next: review and commit the files.")
+    if github:
+        info(
+            f'Then require the "{CHECK_NAME}" status check on protected branches '
+            "(see `commitguard github setup`); the workflow alone does not block merges."
+        )
+    else:
+        if not install:
+            info("Run `commitguard install` to enforce policies in local Git hooks.")

commitguard/cli/commands/install.py

@@ -0,0 +1,152 @@
+"""``commitguard install`` / ``commitguard uninstall``: manage Git hooks.
+
+Existing hooks are never overwritten: they are preserved as
+``<hook>.pre-commitguard`` and run after CommitGuard. ``uninstall`` removes
+only CommitGuard's managed block and restores preserved hooks.
+"""
+
+from typing import Annotated
+
+import typer
+
+from commitguard.cli.output import handled_errors, info, supports_unicode
+from commitguard.config.enforcement import build_enforcement
+from commitguard.config.loader import load_effective_config
+from commitguard.exceptions.base import CommitGuardError
+from commitguard.git.hooks import (
+    HookType,
+    InstallAction,
+    InstallResult,
+    UninstallAction,
+    UninstallResult,
+    default_python,
+    install_global,
+    install_hooks,
+    uninstall_global,
+    uninstall_hooks,
+)
+from commitguard.git.repository import Repository
+from commitguard.security.sanitization import sanitize_for_terminal
+
+HookOption = Annotated[
+    list[HookType] | None,
+    typer.Option("--hook", help="Limit to this hook (repeatable). Default: all three."),
+]
+GlobalOption = Annotated[
+    bool,
+    typer.Option(
+        "--global",
+        help="Use a Git template directory so NEW repositories (git init/clone) get the hooks.",
+    ),
+]
+SharedOption = Annotated[
+    bool,
+    typer.Option(
+        "--allow-shared-hooks-path",
+        help="Allow a core.hooksPath outside this repository's Git directory.",
+    ),
+]
+
+BYPASS_NOTE = (
+    "Note: local hooks can be bypassed (git commit/push --no-verify) by anyone who controls "
+    "this clone. Authoritative protection needs the GitHub check required by branch "
+    "protection (see: commitguard github setup)."
+)
+
+
+def _mark() -> str:
+    return "✓" if supports_unicode() else "OK"
+
+
+def _describe_install(result: InstallResult) -> str:
+    name = result.hook.value
+    text = {
+        InstallAction.INSTALLED: f"Installed {name} hook",
+        InstallAction.CHAINED: f"Installed {name} hook",
+        InstallAction.UPDATED: f"Updated {name} hook",
+        InstallAction.UNCHANGED: f"{name} hook already installed and up to date",
+    }[result.action]
+    if result.chained is not None:
+        text += f" (existing hook preserved as {result.chained.name}; it runs after CommitGuard)"
+    return f"{_mark()} {text}"
+
+
+def _describe_uninstall(result: UninstallResult) -> str:
+    name = result.hook.value
+    text = {
+        UninstallAction.REMOVED: f"{_mark()} Removed CommitGuard {name} hook",
+        UninstallAction.RESTORED: f"{_mark()} Removed CommitGuard {name} hook and restored the "
+        "hook that existed before installation",
+        UninstallAction.BLOCK_REMOVED: f"{_mark()} Removed CommitGuard block from {name} hook "
+        "(other content kept)",
+        UninstallAction.NOT_INSTALLED: f"- {name}: CommitGuard hook not installed",
+        UninstallAction.FOREIGN: f"- {name}: not a CommitGuard hook; left untouched",
+    }[result.action]
+    return text + (f" ({result.note})" if result.note else "")
+
+
+def install_command(
+    hooks: HookOption = None,
+    global_: GlobalOption = False,
+    allow_shared_hooks_path: SharedOption = False,
+) -> None:
+    """Install CommitGuard Git hooks (pre-commit, commit-msg, pre-push)."""
+    selected = tuple(hooks) if hooks else None
+    with handled_errors():
+        info("CommitGuard")
+        if global_:
+            template, results, configured = install_global(selected)
+            info(f"Template directory: {sanitize_for_terminal(str(template))}")
+            for result in results:
+                info(_describe_install(result))
+            if configured:
+                info(f"{_mark()} Set global git config init.templateDir")
+            info("New repositories created with git init / git clone will include the hooks.")
+            info("Existing repositories are unchanged: run `commitguard install` inside them.")
+            info(BYPASS_NOTE)
+            return
+
+        repository = Repository.discover()
+        results = install_hooks(
+            repository, selected, allow_shared_hooks_path=allow_shared_hooks_path
+        )
+        info(f"Hooks directory: {sanitize_for_terminal(str(results[0].path.parent))}")
+        for result in results:
+            info(_describe_install(result))
+        info(f"Hooks run: {sanitize_for_terminal(default_python())} -P -m commitguard hook <name>")
+        info("  (falls back to `commitguard` on PATH if that interpreter is removed)")
+        try:
+            enforcement = build_enforcement(*load_effective_config(repository.root).configs)
+        except CommitGuardError as exc:
+            info(f"! Configuration is invalid; hooks will block until it is fixed: {exc}")
+        else:
+            for name in ("pre_commit", "commit_msg", "pre_push"):
+                if not enforcement.enabled(name):
+                    info(f"! {name.replace('_', '-')} enforcement is disabled in configuration")
+        info(BYPASS_NOTE)
+
+
+def uninstall_command(
+    hooks: HookOption = None,
+    global_: GlobalOption = False,
+    allow_shared_hooks_path: SharedOption = False,
+) -> None:
+    """Remove CommitGuard hooks, preserving and restoring any other hooks."""
+    selected = tuple(hooks) if hooks else None
+    with handled_errors():
+        info("CommitGuard")
+        if global_:
+            _, uninstall_results, unset = uninstall_global(selected)
+            for result in uninstall_results:
+                info(_describe_uninstall(result))
+            if unset:
+                info(f"{_mark()} Unset global git config init.templateDir")
+            info("Repositories created earlier keep their copied hooks; uninstall there too.")
+            return
+        repository = Repository.discover()
+        uninstall_results = uninstall_hooks(
+            repository, selected, allow_shared_hooks_path=allow_shared_hooks_path
+        )
+        for result in uninstall_results:
+            info(_describe_uninstall(result))
+        info("Existing Git hooks were preserved.")

commitguard/cli/commands/policy.py

@@ -0,0 +1,36 @@
+"""``commitguard policy``: inspect policies."""
+
+import typer
+
+from commitguard.cli.common import ConfigOption
+from commitguard.cli.output import handled_errors, info, table
+from commitguard.config.loader import load_effective_config
+from commitguard.exceptions.git import NotAGitRepositoryError
+from commitguard.git.repository import Repository
+from commitguard.policies.loader import build_policy_set
+
+policy_app = typer.Typer(help="Inspect policies.", no_args_is_help=True)
+
+
+@policy_app.command("list")
+def list_command(config: ConfigOption = None) -> None:
+    """Show the effective policies and the configuration layers they came from."""
+    with handled_errors():
+        try:
+            root = Repository.discover().root
+        except NotAGitRepositoryError:
+            root = None
+        loaded = load_effective_config(root, explicit_path=config)
+        policies = build_policy_set(*loaded.configs)
+
+    info("Configuration layers (lowest precedence first):")
+    for source in loaded.sources:
+        info(f"  - {source}")
+    if root is None:
+        info("  (not inside a Git repository: no repository layer)")
+    info("")
+    rows = [
+        [p.id, "yes" if p.enabled else "no", p.action.value, p.description]
+        for p in policies.values()
+    ]
+    info(table(["policy", "enabled", "action", "description"], rows))

commitguard/cli/commands/report.py

@@ -0,0 +1,39 @@
+"""``commitguard report``: assemble reports from recorded results and evidence.
+
+The report only restates recorded evidence; it never measures anything itself,
+and anything without evidence is reported as "Not tested".
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from commitguard.cli.output import handled_errors, info
+
+report_app = typer.Typer(
+    help="Generate reports from recorded benchmark results.", no_args_is_help=True
+)
+
+
+@report_app.command("security")
+def security_report_command(
+    results: Annotated[
+        Path, typer.Option("--results", help="Results directory (e.g. benchmarks/results).")
+    ] = Path("benchmarks/results"),
+    evidence: Annotated[
+        Path | None,
+        typer.Option("--evidence", help="Evidence directory written by the security test suites."),
+    ] = None,
+    output: Annotated[
+        Path, typer.Option("--output", help="Directory to write the reports to.")
+    ] = Path("reports"),
+) -> None:
+    """Write reports/security-report.{json,md} and reports/benchmark-report.md."""
+    from commitguard.research.report import collect, write_reports
+
+    with handled_errors():
+        data = collect(results, evidence)
+        written = write_reports(data, output)
+    for path in written:
+        info(f"Wrote {path}")

commitguard/cli/commands/reproduce.py

@@ -0,0 +1,123 @@
+"""``commitguard reproduce``: re-run the published evidence on this machine.
+
+Exit codes: 0 when nothing failed (steps may be SKIPPED), 1 when a step failed,
+2 on errors. A skipped step is never reported as a success.
+"""
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from commitguard.cli.output import ExitCode, handled_errors, info
+
+reproduce_app = typer.Typer(
+    help="Reproduce the published security, benchmark and integration evidence.",
+    no_args_is_help=True,
+)
+
+JsonOption = Annotated[bool, typer.Option("--json", help="Print the result document as JSON.")]
+OutputOption = Annotated[
+    Path | None, typer.Option("--output", help="Also write the JSON document to this file.")
+]
+EvidenceOption = Annotated[
+    Path | None,
+    typer.Option("--evidence-dir", help="Directory for evidence written by the test suites."),
+]
+ResultsOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--results", help="Results directory to compare against (e.g. benchmarks/results)."
+    ),
+]
+
+
+def _emit(
+    areas: list[str],
+    as_json: bool,
+    output: Path | None,
+    evidence_dir: Path | None,
+    results: Path | None,
+) -> None:
+    from commitguard.research.environment import collect_manifest
+    from commitguard.research.reproduction import reproduce
+    from commitguard.research.results import result_document
+
+    with handled_errors():
+        result = reproduce(areas, evidence_dir=evidence_dir, results_dir=results)
+        manifest = collect_manifest(argv=["commitguard", "reproduce", *areas])
+    document = result_document("reproduce", manifest, result)
+    rendered = json.dumps(document, indent=2, sort_keys=True, ensure_ascii=False)
+    if output is not None:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(rendered + "\n", encoding="utf-8")
+    if as_json:
+        info(rendered)
+    else:
+        info("CommitGuard reproduction")
+        info("")
+        for step in result.steps:
+            if step.status == "NOT RUN":
+                continue
+            info(f"  {step.status:<8} {step.area:<12} {step.name}")
+            info(f"           {step.detail}")
+            if step.command:
+                info(f"           $ {step.command}")
+        info("")
+        info(
+            f"PASS {result.passed} · FAIL {result.failed} · SKIPPED {result.skipped} "
+            f"· NOT RUN {result.not_run}"
+        )
+        info(
+            f"CommitGuard {manifest.commitguard_version} · {manifest.operating_system} "
+            f"{manifest.os_release} · Python {manifest.python_version} · "
+            f"Git {manifest.git_version or 'unknown'}"
+        )
+        if result.skipped:
+            info("Skipped steps were not run; they are not passes.")
+    if not result.ok:
+        raise typer.Exit(ExitCode.BLOCKED)
+
+
+@reproduce_app.command("all")
+def all_command(
+    as_json: JsonOption = False,
+    output: OutputOption = None,
+    evidence_dir: EvidenceOption = None,
+    results: ResultsOption = None,
+) -> None:
+    """Run every reproduction step (GitHub steps are skipped without credentials)."""
+    _emit(
+        ["security", "benchmark", "integration", "github"], as_json, output, evidence_dir, results
+    )
+
+
+@reproduce_app.command("security")
+def security_command(
+    as_json: JsonOption = False, output: OutputOption = None, evidence_dir: EvidenceOption = None
+) -> None:
+    """Run the security regression suite (pytest -m security)."""
+    _emit(["security"], as_json, output, evidence_dir, None)
+
+
+@reproduce_app.command("benchmark")
+def benchmark_command(
+    as_json: JsonOption = False, output: OutputOption = None, results: ResultsOption = None
+) -> None:
+    """Rebuild the detection dataset and re-measure detection against its labels."""
+    _emit(["benchmark"], as_json, output, None, results)
+
+
+@reproduce_app.command("integration")
+def integration_command(
+    as_json: JsonOption = False, output: OutputOption = None, evidence_dir: EvidenceOption = None
+) -> None:
+    """Run the integration suite (Git repositories, hooks, CI and the App service)."""
+    _emit(["integration"], as_json, output, evidence_dir, None)
+
+
+@reproduce_app.command("github")
+def github_command(as_json: JsonOption = False, output: OutputOption = None) -> None:
+    """Validate a real GitHub App installation (SKIPPED without credentials)."""
+    _emit(["github"], as_json, output, None, None)

commitguard/cli/commands/scan.py

@@ -0,0 +1,47 @@
+"""``commitguard scan``: analyse commits and explain every finding.
+
+Exit codes: 0 allowed (including warnings), 1 blocked, 2 error.
+"""
+
+import typer
+
+from commitguard.cli.common import (
+    DEFAULT_MAX_COMMITS,
+    ConfigOption,
+    FormatOption,
+    MaxCommitsOption,
+    RevisionArgument,
+)
+from commitguard.cli.output import ExitCode, OutputFormat, handled_errors, info
+from commitguard.cli.render import render_json, render_scan_text
+from commitguard.core.context import ScanTrigger
+from commitguard.core.decision import Action
+from commitguard.git.repository import Repository
+from commitguard.services.analysis import analyze_revisions, build_report, load_analyzer
+
+
+def scan_command(
+    revision_range: RevisionArgument = "HEAD",
+    config: ConfigOption = None,
+    output_format: FormatOption = OutputFormat.TEXT,
+    max_commits: MaxCommitsOption = DEFAULT_MAX_COMMITS,
+) -> None:
+    """Scan commits for AI attribution and other policy violations."""
+    with handled_errors():
+        repository = Repository.discover()
+        analyzer, loaded = load_analyzer(repository, config_path=config)
+        reports = analyze_revisions(repository, analyzer, revision_range, max_commits=max_commits)
+        report = build_report(
+            reports,
+            repository=repository,
+            target=revision_range,
+            trigger=ScanTrigger.MANUAL,
+            config=loaded,
+        )
+        rendered = (
+            render_json(report) if output_format is OutputFormat.JSON else render_scan_text(report)
+        )
+
+    info(rendered)
+    if report.action is Action.BLOCK:
+        raise typer.Exit(code=int(ExitCode.BLOCKED))

commitguard/cli/common.py

@@ -0,0 +1,44 @@
+"""Option definitions shared by several commands."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from commitguard.cli.output import OutputFormat
+from commitguard.services.analysis import DEFAULT_MAX_COMMITS
+
+ConfigOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--config",
+        "-c",
+        help="Extra configuration file, applied after global and repository configuration.",
+        dir_okay=False,
+    ),
+]
+
+FormatOption = Annotated[
+    OutputFormat,
+    typer.Option("--format", "-f", help="Output format.", case_sensitive=False),
+]
+
+RevisionArgument = Annotated[
+    str,
+    typer.Argument(
+        help="Commit (HEAD, SHA, branch) or range containing '..' (e.g. origin/main..HEAD).",
+    ),
+]
+
+MaxCommitsOption = Annotated[
+    int,
+    typer.Option("--max-commits", min=1, help="Refuse ranges selecting more commits than this."),
+]
+
+__all__ = [
+    "DEFAULT_MAX_COMMITS",
+    "ConfigOption",
+    "FormatOption",
+    "MaxCommitsOption",
+    "RevisionArgument",
+]

commitguard/cli/output.py

@@ -0,0 +1,89 @@
+"""Terminal output helpers and exit codes.
+
+All text derived from commits, configuration files or Git error output passes
+through :mod:`commitguard.security.sanitization` here or in
+:mod:`commitguard.cli.render`: :func:`sanitize_block` for multi-line reason
+blocks (newlines kept, continuation lines indented so none can impersonate a
+CommitGuard status line) and :func:`sanitize_for_terminal` elsewhere.
+"""
+
+import sys
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from enum import IntEnum, StrEnum
+from typing import NoReturn
+
+import typer
+
+from commitguard.exceptions.base import CommitGuardError
+from commitguard.security.sanitization import sanitize_block, sanitize_for_terminal
+
+
+class ExitCode(IntEnum):
+    """Process exit codes (stable contract for hooks and CI).
+
+    0  allowed - no findings, or only findings whose policy is allow/warn
+    1  blocked - at least one finding or detector failure evaluated to BLOCK
+    2  error   - invalid configuration or rules, Git failure, bad arguments,
+               unimplemented command, or any unexpected runtime error
+    """
+
+    OK = 0
+    BLOCKED = 1
+    ERROR = 2
+
+
+class OutputFormat(StrEnum):
+    TEXT = "text"
+    JSON = "json"
+
+
+def info(message: str) -> None:
+    typer.echo(message)
+
+
+def error(message: str) -> None:
+    typer.echo(
+        "commitguard: error: " + sanitize_block(message, max_length=4000),
+        err=True,
+    )
+
+
+def fail(message: str, code: ExitCode = ExitCode.ERROR) -> NoReturn:
+    error(message)
+    raise typer.Exit(code=int(code))
+
+
+def supports_unicode() -> bool:
+    encoding = (getattr(sys.stdout, "encoding", None) or "").lower()
+    return encoding.startswith("utf")
+
+
+def table(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> str:
+    """Render a plain-text table. Cell values are sanitised."""
+    clean_rows = [[sanitize_for_terminal(cell, max_length=200) for cell in row] for row in rows]
+    widths = [len(h) for h in headers]
+    for row in clean_rows:
+        for index, cell in enumerate(row):
+            widths[index] = max(widths[index], len(cell))
+    lines = ["  ".join(h.upper().ljust(widths[i]) for i, h in enumerate(headers)).rstrip()]
+    for row in clean_rows:
+        lines.append("  ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)).rstrip())
+    return "\n".join(lines)
+
+
+@contextmanager
+def handled_errors() -> Iterator[None]:
+    """Map every failure to a clean message and exit code 2.
+
+    Unexpected exceptions must not surface as exit code 1 (which means
+    "blocked by policy") or print tracebacks that could include local data.
+    """
+    try:
+        yield
+    except typer.Exit:
+        raise
+    except CommitGuardError as exc:
+        fail(str(exc))
+    except Exception as exc:  # noqa: BLE001 - last-resort mapping to the error exit code
+        fail(f"internal error ({type(exc).__name__}): {exc}")