commitguardian 0.1.0__py3-none-any.whl

commitguard/services/hooks.py

@@ -0,0 +1,254 @@
+"""Git hook runtime: what ``commitguard hook <name>`` does.
+
+Hooks are enforcement points only. Every stage builds commits from Git data
+and runs the same :class:`~commitguard.services.analysis.Analyzer` used by
+``scan``/``check``.
+
+=============  ===========================================  ==================
+Stage          Input                                         What is analysed
+=============  ===========================================  ==================
+pre-commit     pending author/committer (``git var``)        identity rules
+commit-msg     message file after Git's default cleanup      message + identity
+               plus pending author/committer
+pre-push       ref updates on stdin                          every outgoing commit
+=============  ===========================================  ==================
+
+commit-msg sees the message *before* Git creates the commit object; options
+such as ``--cleanup=verbatim`` are invisible to it. pre-push analyses the real
+commit objects and is the authoritative local check.
+"""
+
+from collections.abc import Callable, Sequence
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.config.enforcement import (
+    Enforcement,
+    Remediation,
+    build_enforcement,
+    build_remediation,
+)
+from commitguard.config.loader import LoadedConfig
+from commitguard.core.context import ScanTrigger
+from commitguard.core.decision import Action
+from commitguard.exceptions.git import GitError
+from commitguard.git.push import PushUpdate, parse_pre_push_input
+from commitguard.git.ranges import resolve_commit_range
+from commitguard.git.repository import Repository
+from commitguard.services.analysis import (
+    MAX_MESSAGE_FILE_BYTES,
+    Analyzer,
+    build_report,
+    load_analyzer,
+    pending_commit,
+)
+from commitguard.services.remediation import (
+    RemovedLine,
+    removable_lines,
+    strip_lines,
+    with_actual_text,
+)
+from commitguard.services.reports import ScanReport
+from commitguard.utils.filesystem import read_bytes_limited
+
+
+class HookName(StrEnum):
+    PRE_COMMIT = "pre-commit"
+    COMMIT_MSG = "commit-msg"
+    PRE_PUSH = "pre-push"
+
+
+class UpdateDisposition(StrEnum):
+    SCANNED = "scanned"
+    DELETED = "deleted"  # nothing to analyse
+    NON_COMMIT = "non_commit"  # e.g. tag pointing at a tree or blob
+    UP_TO_DATE = "up_to_date"  # no commits the remote does not already have
+
+
+class UpdatePlan(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    update: PushUpdate
+    disposition: UpdateDisposition
+    commits: tuple[str, ...] = ()
+
+
+class HookRun(BaseModel):
+    """Outcome of one hook invocation."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    hook: HookName
+    enabled: bool
+    report: ScanReport | None = None
+    updates: tuple[UpdatePlan, ...] = ()
+    remote: str | None = None
+    #: Lines deleted from the pending message by ``remediation.auto_remove``.
+    #: Non-empty only when the rewritten message then analysed clean.
+    removed: tuple[RemovedLine, ...] = ()
+
+
+def _setup(
+    repository: Repository, config_path: Path | None
+) -> tuple[Analyzer, LoadedConfig, Enforcement, Remediation]:
+    analyzer, loaded = load_analyzer(repository, config_path=config_path)
+    return (
+        analyzer,
+        loaded,
+        build_enforcement(*loaded.configs),
+        build_remediation(*loaded.configs),
+    )
+
+
+def run_pre_commit(repository: Repository, *, config_path: Path | None = None) -> HookRun:
+    analyzer, loaded, enforcement, _ = _setup(repository, config_path)
+    if not enforcement.pre_commit:
+        return HookRun(hook=HookName.PRE_COMMIT, enabled=False)
+    author, committer = repository.pending_identities()
+    # No message exists yet: only identity-based rules can match.
+    report = analyzer.analyze(pending_commit("", author, committer), ScanTrigger.PRE_COMMIT)
+    return HookRun(
+        hook=HookName.PRE_COMMIT,
+        enabled=True,
+        report=build_report(
+            [report],
+            repository=repository,
+            target="pending commit",
+            trigger=ScanTrigger.PRE_COMMIT,
+            config=loaded,
+        ),
+    )
+
+
+def run_commit_msg(
+    repository: Repository, message_file: Path, *, config_path: Path | None = None
+) -> HookRun:
+    analyzer, loaded, enforcement, remediation = _setup(repository, config_path)
+    if not enforcement.commit_msg:
+        return HookRun(hook=HookName.COMMIT_MSG, enabled=False)
+    raw = read_bytes_limited(message_file, max_bytes=MAX_MESSAGE_FILE_BYTES)
+    message = repository.cleanup_message(raw.decode("utf-8", errors="replace"))
+    author, committer = repository.pending_identities()
+
+    def analyse(text: str) -> ScanReport:
+        commit = analyzer.analyze(pending_commit(text, author, committer), ScanTrigger.COMMIT_MSG)
+        return build_report(
+            [commit],
+            repository=repository,
+            target="pending commit message",
+            trigger=ScanTrigger.COMMIT_MSG,
+            config=loaded,
+        )
+
+    report = analyse(message)
+    removed: tuple[RemovedLine, ...] = ()
+    if remediation.auto_remove and report.action is Action.BLOCK:
+        fixed = _auto_remove(message_file, message, report, analyse)
+        if fixed is not None:
+            report, removed = fixed
+    return HookRun(hook=HookName.COMMIT_MSG, enabled=True, report=report, removed=removed)
+
+
+def _auto_remove(
+    message_file: Path,
+    message: str,
+    report: ScanReport,
+    analyse: Callable[[str], ScanReport],
+) -> tuple[ScanReport, tuple[RemovedLine, ...]] | None:
+    """Delete the offending lines, if that genuinely clears the block.
+
+    Returns the report for the rewritten message and what was removed, or
+    ``None`` to leave the original block in place. Every path that is not
+    provably clean returns ``None``: the caller then blocks as usual.
+    """
+    removals = removable_lines(report.commits[0]) if report.commits else None
+    if removals is None:
+        return None
+    rewritten = strip_lines(message, frozenset(r.line_number for r in removals))
+    if not rewritten.strip():
+        return None  # nothing would be left; refuse rather than empty the message
+    after = analyse(rewritten)
+    if after.action is Action.BLOCK:
+        return None  # the removal did not fix it: never allow on assumption
+    message_file.write_text(rewritten, encoding="utf-8")
+    return after, with_actual_text(message, removals)
+
+
+def plan_push(
+    repository: Repository,
+    updates: Sequence[PushUpdate],
+    remote: str,
+    *,
+    max_commits: int,
+) -> tuple[list[UpdatePlan], list[str]]:
+    """Work out which commits a push would introduce, deduplicated, oldest first.
+
+    For each update the commits reachable from the local object but not from
+    the remote's current object (when present locally) or from any of the
+    remote's tracking refs are selected. That covers new branches (all-zero
+    remote object) without rescanning history the remote already has, and
+    force pushes (only commits the remote lacks). Deletions have no outgoing
+    commits; tags are peeled to the commit they reference.
+    """
+    known_remote = repository.remote_tracking_tips(remote)
+    plans: list[UpdatePlan] = []
+    ordered: dict[str, None] = {}
+    for update in updates:
+        if update.is_delete:
+            plans.append(UpdatePlan(update=update, disposition=UpdateDisposition.DELETED))
+            continue
+        commit = repository.peel_to_commit(update.local_oid)
+        if commit is None:
+            plans.append(UpdatePlan(update=update, disposition=UpdateDisposition.NON_COMMIT))
+            continue
+        exclude = set(known_remote)
+        remote_commit = None if update.is_new_ref else repository.peel_to_commit(update.remote_oid)
+        if remote_commit is not None:
+            exclude.add(remote_commit)
+        commits = resolve_commit_range(
+            repository, commit, exclude, base=remote_commit, max_count=max_commits
+        ).commits
+        for sha in commits:
+            ordered.setdefault(sha, None)
+        if len(ordered) > max_commits:
+            raise GitError(f"push would introduce more than {max_commits} commits")
+        plans.append(
+            UpdatePlan(
+                update=update,
+                disposition=UpdateDisposition.SCANNED if commits else UpdateDisposition.UP_TO_DATE,
+                commits=tuple(commits),
+            )
+        )
+    return plans, list(ordered)
+
+
+def run_pre_push(
+    repository: Repository,
+    remote: str,
+    stdin_text: str,
+    *,
+    config_path: Path | None = None,
+) -> HookRun:
+    analyzer, loaded, enforcement, _ = _setup(repository, config_path)
+    if not enforcement.pre_push:
+        return HookRun(hook=HookName.PRE_PUSH, enabled=False, remote=remote)
+    updates = parse_pre_push_input(stdin_text)
+    plans, shas = plan_push(repository, updates, remote, max_commits=enforcement.max_push_commits)
+    reports = [
+        analyzer.analyze(commit, ScanTrigger.PRE_PUSH) for commit in repository.read_commits(shas)
+    ]
+    return HookRun(
+        hook=HookName.PRE_PUSH,
+        enabled=True,
+        remote=remote,
+        updates=tuple(plans),
+        report=build_report(
+            reports,
+            repository=repository,
+            target=f"push to {remote}",
+            trigger=ScanTrigger.PRE_PUSH,
+            config=loaded,
+        ),
+    )

commitguard/services/remediation.py

@@ -0,0 +1,99 @@
+"""Removing prohibited attribution from a pending commit message.
+
+Only the ``commit-msg`` hook can do this safely. It runs *before* Git creates
+the commit object, so deleting a line rewrites nothing: there is no history to
+rewrite yet. By the time ``pre-push`` runs, the commits exist and correcting
+them means rewriting history, which CommitGuard never does on its own.
+
+The rules are deliberately narrow, because this feature turns a block into a
+commit:
+
+* it applies only when **every** blocking finding points at a message line.
+  Attribution carried by the author or committer identity cannot be fixed by
+  editing text, so it still blocks;
+* a detector failure always blocks - a message that could not be fully analysed
+  is never "fixed";
+* the stripped message is **re-analysed**, and the commit proceeds only if the
+  result is clean. Nothing is ever allowed on the assumption that the removal
+  worked;
+* if nothing but blank lines would be left, the commit blocks instead, rather
+  than producing an empty message.
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.core.decision import Action
+from commitguard.core.result import EvidenceSource
+from commitguard.services.reports import CommitReport
+
+#: Evidence that lives on a line of the message, and so can be deleted.
+REMOVABLE_SOURCES = frozenset(
+    {EvidenceSource.COAUTHOR_TRAILER, EvidenceSource.TRAILER, EvidenceSource.MESSAGE}
+)
+
+
+class RemovedLine(BaseModel):
+    """One line deleted from a pending commit message."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    line_number: int
+    text: str
+    rule_id: str
+
+
+def removable_lines(report: CommitReport) -> tuple[RemovedLine, ...] | None:
+    """The message lines whose deletion would clear every block, or ``None``.
+
+    ``None`` means "editing the message cannot fix this": an identity-based
+    finding, a detector failure, or evidence with no line number.
+    """
+    if any(failure.action is Action.BLOCK for failure in report.failures):
+        return None
+    removals: dict[int, RemovedLine] = {}
+    for evaluated in report.findings:
+        if evaluated.action is not Action.BLOCK:
+            continue  # warnings do not block, so nothing has to be removed for them
+        for evidence in evaluated.finding.evidence:
+            if evidence.source not in REMOVABLE_SOURCES or evidence.line_number is None:
+                return None
+            removals.setdefault(
+                evidence.line_number,
+                RemovedLine(
+                    line_number=evidence.line_number,
+                    text=evidence.value,
+                    rule_id=evaluated.finding.rule_id,
+                ),
+            )
+    return tuple(removals[number] for number in sorted(removals)) or None
+
+
+def with_actual_text(message: str, removals: tuple[RemovedLine, ...]) -> tuple[RemovedLine, ...]:
+    """Replace each removal's evidence value with the message line itself.
+
+    Evidence carries the matched value (``Claude <noreply@anthropic.com>``);
+    the developer needs to see the whole line that disappeared.
+    """
+    lines = message.splitlines()
+    return tuple(
+        removed.model_copy(update={"text": lines[removed.line_number - 1].strip()})
+        if 0 < removed.line_number <= len(lines)
+        else removed
+        for removed in removals
+    )
+
+
+def strip_lines(message: str, line_numbers: frozenset[int]) -> str:
+    """Return ``message`` without the given 1-based lines.
+
+    Blank lines left stranded at the end are trimmed, so deleting a trailing
+    trailer block does not leave the message ending in blank lines.
+    """
+    kept = [
+        line
+        for number, line in enumerate(message.splitlines(), start=1)
+        if number not in line_numbers
+    ]
+    while kept and not kept[-1].strip():
+        kept.pop()
+    return "\n".join(kept) + "\n" if kept else ""

commitguard/services/reports.py

@@ -0,0 +1,146 @@
+"""Structured, serialisable analysis reports.
+
+Reports are the stable output contract for the CLI's JSON format and the
+future audit log. They contain commit IDs, findings, evidence (concise
+metadata only) and decisions - never file contents or full commit messages.
+"""
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field
+
+from commitguard.core.decision import Action, Decision
+from commitguard.core.result import DetectionResult, DetectorFailure, Finding
+
+REPORT_SCHEMA_VERSION: Literal[1] = 1
+MAX_SUBJECT_CHARS = 120
+
+
+class EvaluatedFinding(BaseModel):
+    """A finding together with the policy outcome applied to it."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    finding: Finding
+    action: Action
+    policy_id: str | None
+    reason: str
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def fingerprint(self) -> str:
+        return self.finding.fingerprint
+
+
+class EvaluatedFailure(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    failure: DetectorFailure
+    action: Action
+    reason: str
+
+
+class CommitReport(BaseModel):
+    """Detection + decision for one commit."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    commit_sha: str | None
+    short_sha: str
+    subject: str = Field(default="", description="First line of the message, truncated")
+    action: Action
+    findings: tuple[EvaluatedFinding, ...] = ()
+    failures: tuple[EvaluatedFailure, ...] = ()
+    detectors_run: tuple[str, ...] = ()
+    detectors_skipped: tuple[str, ...] = ()
+
+    @classmethod
+    def build(
+        cls,
+        short_sha: str,
+        detection: DetectionResult,
+        decision: Decision,
+        *,
+        subject: str = "",
+    ) -> "CommitReport":
+        findings: list[EvaluatedFinding] = []
+        failures: list[EvaluatedFailure] = []
+        for explanation in decision.explanations:
+            if explanation.finding is not None:
+                findings.append(
+                    EvaluatedFinding(
+                        finding=explanation.finding,
+                        action=explanation.action,
+                        policy_id=explanation.policy_id,
+                        reason=explanation.reason,
+                    )
+                )
+            elif explanation.failure is not None:
+                failures.append(
+                    EvaluatedFailure(
+                        failure=explanation.failure,
+                        action=explanation.action,
+                        reason=explanation.reason,
+                    )
+                )
+        return cls(
+            commit_sha=detection.commit_sha,
+            short_sha=short_sha,
+            subject=subject[:MAX_SUBJECT_CHARS],
+            action=decision.action,
+            findings=tuple(findings),
+            failures=tuple(failures),
+            detectors_run=detection.detectors_run,
+            detectors_skipped=detection.detectors_skipped,
+        )
+
+
+class CIReport(BaseModel):
+    """CI context attached to reports produced by ``commitguard ci``."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    provider: str
+    event: str
+    repository: str | None = None
+    ref: str | None = None
+    pull_request_number: int | None = None
+    from_fork: bool = False
+    base_sha: str | None = None
+    head_sha: str | None = None
+    policy_source: str
+    config_changes: tuple[str, ...] = Field(
+        default=(), description="Config files changed by the evaluated commits (not applied)"
+    )
+    policy_weakenings: tuple[str, ...] = Field(
+        default=(), description="Policies the evaluated commits' config would weaken (not applied)"
+    )
+    notices: tuple[str, ...] = ()
+
+
+class ScanReport(BaseModel):
+    """Result of analysing one or more commits."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    schema_version: Literal[1] = REPORT_SCHEMA_VERSION
+    tool_version: str
+    generated_at: datetime
+    repository: str | None
+    target: str
+    trigger: str
+    config_sources: tuple[str, ...]
+    action: Action
+    commits: tuple[CommitReport, ...]
+    ci: CIReport | None = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def summary(self) -> dict[str, int]:
+        counts = {action.value: 0 for action in Action}
+        for commit in self.commits:
+            actions = [f.action for f in commit.findings] + [f.action for f in commit.failures]
+            for action in actions:
+                counts[action.value] += 1
+        return {"commits": len(self.commits), **counts}

commitguard/services/scan.py

@@ -0,0 +1,172 @@
+"""ScanService: one entry point for "analyse these commits under this policy".
+
+Every server-side adapter (``commitguard ci github`` in GitHub Actions and the
+GitHub App worker) builds a :class:`ScanRequest` and gets a :class:`ScanResult`
+containing the same :class:`~commitguard.services.reports.ScanReport` that
+``commitguard scan --format json`` produces - there is no platform-specific
+result format and no platform-specific detection.
+
+A scan is deterministic: the same commits, trusted policy, mandatory policy,
+rules and CommitGuard version produce the same result and the same
+:attr:`ScanMetadata.scan_id`, which makes retries, duplicate webhooks and
+Action/App comparisons checkable.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from commitguard import __version__
+from commitguard.ci.context import CIContext
+from commitguard.config.sources import MandatoryPolicy
+from commitguard.core.decision import Action
+from commitguard.git.repository import Repository
+from commitguard.policies.governance import EffectivePolicy, GovernanceInputs
+from commitguard.policies.model import Policy
+from commitguard.rules.loader import builtin_rules_fingerprint
+from commitguard.rules.matcher import CompiledRules
+from commitguard.security.hashing import fingerprint
+from commitguard.security.validation import validate_repository_path
+from commitguard.services.ci import DEFAULT_CI_MAX_COMMITS, CIPlan, execute_ci_plan, plan_ci
+from commitguard.services.enforcement import EnforcementDecision, EnforcementService
+from commitguard.services.reports import ScanReport
+
+SCAN_ID_LENGTH = 32
+
+
+class ScanRequest(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
+
+    repository: Repository
+    context: CIContext
+    config_path: str | None = None
+    max_commits: int = Field(default=DEFAULT_CI_MAX_COMMITS, ge=1)
+    fail_on: Action = Action.BLOCK
+    mandatory_policy: MandatoryPolicy | None = None
+    #: Organization governance (GitHub App); replaces ``mandatory_policy`` when set.
+    governance: GovernanceInputs | None = None
+    rules: CompiledRules | None = None  # None: the bundled, trusted rules
+    #: Version label of ``rules`` when they are not the bundled rules.
+    rules_version: str | None = None
+
+    def model_post_init(self, __context: object) -> None:
+        if self.config_path is not None:
+            validate_repository_path(self.config_path)
+        if self.fail_on is Action.ALLOW:
+            raise ValueError("fail_on must be block or warn")
+
+
+class ScanStatistics(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    commits_scanned: int
+    violations: int  # commits whose result is BLOCK
+    warnings: int  # commits whose result is WARN
+    allowed: int
+    findings: int
+    detector_failures: int
+
+
+class ScanMetadata(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    scan_id: str
+    tool_version: str
+    rules_version: str
+    policy_version: str
+    policy_source: str
+    provider: str
+    event: str
+    base_sha: str | None
+    head_sha: str | None
+
+
+class ScanResult(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    report: ScanReport
+    plan: CIPlan
+    statistics: ScanStatistics
+    metadata: ScanMetadata
+    enforcement: EnforcementDecision
+    policies: tuple[Policy, ...] = ()  # effective policies, for reproducible history
+    #: Fields the repository configuration set per rule (before organization governance).
+    repository_overrides: dict[str, dict[str, str | bool]] = {}
+    effective: EffectivePolicy | None = None
+
+    @property
+    def action(self) -> Action:
+        return self.report.action
+
+
+def statistics_for(report: ScanReport) -> ScanStatistics:
+    commits = report.commits
+    return ScanStatistics(
+        commits_scanned=len(commits),
+        violations=sum(1 for c in commits if c.action is Action.BLOCK),
+        warnings=sum(1 for c in commits if c.action is Action.WARN),
+        allowed=sum(1 for c in commits if c.action is Action.ALLOW),
+        findings=sum(len(c.findings) for c in commits),
+        detector_failures=sum(len(c.failures) for c in commits),
+    )
+
+
+class ScanService:
+    def plan(self, request: ScanRequest) -> CIPlan:
+        return plan_ci(
+            request.repository,
+            request.context,
+            config_path=request.config_path,
+            max_commits=request.max_commits,
+        )
+
+    def execute(self, request: ScanRequest, plan: CIPlan) -> ScanResult:
+        run = execute_ci_plan(
+            request.repository,
+            request.context,
+            plan,
+            rules=request.rules,
+            mandatory=request.mandatory_policy,
+            governance=request.governance,
+        )
+        if request.rules is None:
+            rules_version = builtin_rules_fingerprint()
+        else:
+            rules_version = request.rules_version or "custom"
+        context = request.context
+        scan_id = fingerprint(
+            [
+                __version__,
+                rules_version,
+                run.policy_fingerprint,
+                context.provider.value,
+                context.event.value,
+                context.repository or "",
+                str(context.pull_request_number or ""),
+                plan.range.base or "",
+                plan.range.head or "",
+                ",".join(plan.range.exclude),
+            ]
+        )[:SCAN_ID_LENGTH]
+        metadata = ScanMetadata(
+            scan_id=scan_id,
+            tool_version=__version__,
+            rules_version=rules_version,
+            policy_version=run.policy_fingerprint,
+            policy_source=run.report.ci.policy_source if run.report.ci else "",
+            provider=context.provider.value,
+            event=context.event_name,
+            base_sha=plan.range.base,
+            head_sha=plan.range.head,
+        )
+        return ScanResult(
+            report=run.report,
+            plan=plan,
+            statistics=statistics_for(run.report),
+            metadata=metadata,
+            enforcement=EnforcementService(request.fail_on).decide(run.report),
+            policies=run.policies,
+            repository_overrides=run.repository_overrides,
+            effective=run.effective,
+        )
+
+    def run(self, request: ScanRequest) -> ScanResult:
+        return self.execute(request, self.plan(request))

commitguard/utils/__init__.py

@@ -0,0 +1 @@
+"""Low-level helpers (subprocess, filesystem, platform) with no domain knowledge."""