claude-dev-env 8.6.1 → 8.7.0

package/scripts/repository_checks/match_exemptions.py

@@ -0,0 +1,67 @@
+"""Load the scanner matches a repository owns through its policy document."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repository_checks.config.policy_document import (
+    ALL_MATCH_EXEMPTION_FAMILIES,
+    MatchExemptionFamily,
+)
+from repository_checks.policy_document import (
+    PolicyConfigurationRunFatal,
+    entry_path_and_digest,
+    read_policy_entries,
+)
+
+
+def load_match_exemptions(
+    repository_root: Path, family: MatchExemptionFamily
+) -> frozenset[tuple[str, str, str]]:
+    """Read one family of matches the repository owns.
+
+    ::
+
+        the email family over a document owning one address
+        ok:   {("contacts.py", "email", "<digest of the address>")}
+
+    Args:
+        repository_root: Repository containing the optional policy configuration.
+        family: Document field, scanner category, and rejection subject to read.
+    Returns:
+        Exact path, scanner category, and digest identities.
+    Raises:
+        ValueError: Configuration contains invalid JSON or schema fields.
+        OSError: Configuration cannot be read.
+    """
+    exemptions: set[tuple[str, str, str]] = set()
+    for each_entry in read_policy_entries(repository_root, family.field_name):
+        relative_path, digest = entry_path_and_digest(each_entry, family.subject)
+        identity = (relative_path, family.category, digest)
+        if identity in exemptions:
+            raise PolicyConfigurationRunFatal(
+                f"Duplicate repository {family.subject.lower()}"
+            )
+        exemptions.add(identity)
+    return frozenset(exemptions)
+
+
+def load_all_match_exemptions(
+    repository_root: Path,
+) -> frozenset[tuple[str, str, str]]:
+    """Read every family of matches the repository owns.
+
+    Args:
+        repository_root: Repository containing the optional policy configuration.
+    Returns:
+        Exact path, scanner category, and digest identities across all families.
+    Raises:
+        ValueError: Configuration contains invalid JSON or schema fields.
+        OSError: Configuration cannot be read.
+    """
+    return frozenset().union(
+        *(
+            load_match_exemptions(repository_root, each_family)
+            for each_family in ALL_MATCH_EXEMPTION_FAMILIES
+        )
+    )

package/scripts/repository_checks/models.py

@@ -7,10 +7,28 @@ from dataclasses import dataclass
 from repository_checks.config.constants import (
     FAILED_CHECK_EXIT_CODE,
     FINDINGS_EXIT_CODE,
+    SEVERITY_BREAKING,
+    SEVERITY_BY_CHECK_ID,
+    SEVERITY_SMELL,
     SUCCESS_EXIT_CODE,
 )
 
 
+def severity_for_check_id(check_id: str) -> str:
+    """Return the severity a check identifier declares.
+
+    A check identifier absent from the table reads as breaking, so a check
+    added without a severity row fails the tree rather than passing quietly.
+
+    Args:
+        check_id: Stable identifier of the check that raised a finding.
+
+    Returns:
+        Either SEVERITY_BREAKING or SEVERITY_SMELL.
+    """
+    return SEVERITY_BY_CHECK_ID.get(check_id, SEVERITY_BREAKING)
+
+
 @dataclass(frozen=True)
 class RepositoryFinding:
     """One committed-tree finding with a stable check id and relative path."""
@@ -19,19 +37,45 @@ class RepositoryFinding:
     relative_path: str
     message: str
 
+    @property
+    def severity(self) -> str:
+        """Return the severity this finding's check identifier declares."""
+        return severity_for_check_id(self.check_id)
+
 
 @dataclass(frozen=True)
 class RepositoryCheckReport:
-    """Sorted findings and the check ids that failed while they ran."""
+    """Sorted findings and the check ids that failed while they ran.
+
+    Splits its findings into the breaking ones and the advisory ones, and
+    derives the exit code from the breaking ones alone.
+    """
 
     all_findings: tuple[RepositoryFinding, ...]
     all_failed_check_ids: tuple[str, ...]
 
+    @property
+    def all_breaking_findings(self) -> tuple[RepositoryFinding, ...]:
+        """Return the findings that fail the tree."""
+        return self._findings_of_severity(SEVERITY_BREAKING)
+
+    @property
+    def all_smell_findings(self) -> tuple[RepositoryFinding, ...]:
+        """Return the findings that report and leave the tree passing."""
+        return self._findings_of_severity(SEVERITY_SMELL)
+
     @property
     def exit_code(self) -> int:
         """Return the process status for this report."""
         if self.all_failed_check_ids:
             return FAILED_CHECK_EXIT_CODE
-        if self.all_findings:
+        if self.all_breaking_findings:
             return FINDINGS_EXIT_CODE
         return SUCCESS_EXIT_CODE
+
+    def _findings_of_severity(self, severity: str) -> tuple[RepositoryFinding, ...]:
+        return tuple(
+            each_finding
+            for each_finding in self.all_findings
+            if each_finding.severity == severity
+        )

package/scripts/repository_checks/reporting.py

@@ -3,12 +3,21 @@
 from __future__ import annotations
 
 from repository_checks.config import constants as repository_constants
-from repository_checks.models import RepositoryCheckReport
+from repository_checks.models import RepositoryCheckReport, RepositoryFinding
 
 
 def render_report(report: RepositoryCheckReport) -> str:
     """Render findings and failed checks as newline-terminated text.
 
+    An advisory finding carries an ``advisory:`` prefix, so a reader of a
+    passing run can tell the reported line from one that failed the tree.
+
+    ::
+
+        claude-md-orphans: notes/CLAUDE.md: references missing file x.py
+        advisory: package-inventory: pipeline/seam.py: production file is
+        absent from package inventory
+
     Args:
         report: Findings and failed check identifiers.
 
@@ -16,12 +25,7 @@ def render_report(report: RepositoryCheckReport) -> str:
         The report body, or an empty string when the tree is clean.
     """
     all_lines = [
-        repository_constants.FINDING_LINE_TEMPLATE.format(
-            check_id=each_finding.check_id,
-            relative_path=each_finding.relative_path,
-            message=each_finding.message,
-        )
-        for each_finding in report.all_findings
+        _finding_line(each_finding) for each_finding in report.all_findings
     ]
     all_lines.extend(_failed_check_lines(report))
     if not all_lines:
@@ -32,6 +36,18 @@ def render_report(report: RepositoryCheckReport) -> str:
     )
 
 
+def _finding_line(finding: RepositoryFinding) -> str:
+    if finding.severity == repository_constants.SEVERITY_SMELL:
+        line_template = repository_constants.ADVISORY_FINDING_LINE_TEMPLATE
+    else:
+        line_template = repository_constants.FINDING_LINE_TEMPLATE
+    return line_template.format(
+        check_id=finding.check_id,
+        relative_path=finding.relative_path,
+        message=finding.message,
+    )
+
+
 def _failed_check_lines(report: RepositoryCheckReport) -> list[str]:
     return [
         repository_constants.RULE_FAILED_LINE_TEMPLATE.format(check_id=each_check_id)

package/scripts/repository_checks/tracked_secrets.py

@@ -10,8 +10,8 @@ from types import ModuleType
 from policy_lint.config import constants as policy_constants
 
 from repository_checks.config import constants as repository_constants
-from repository_checks.email_exemptions import load_email_exemptions
 from repository_checks.hook_modules import load_hooks_module
+from repository_checks.match_exemptions import load_all_match_exemptions
 from repository_checks.models import RepositoryFinding
 from repository_checks.path_exemptions import load_path_exemptions
 
@@ -31,7 +31,7 @@ def collect_tracked_secret_findings(
     scanner = load_hooks_module(repository_constants.PII_SCANNER_MODULE_NAME)
     exemption = load_hooks_module(repository_constants.REPOSITORY_EXEMPTION_MODULE_NAME)
     all_allowlisted_literals = exemption.repository_allowlisted_values(repository_root)
-    all_exact_exemptions = load_email_exemptions(repository_root)
+    all_exact_exemptions = load_all_match_exemptions(repository_root)
     all_exact_exemptions |= repository_constants.ALL_TRACKED_SECRET_EXACT_EXEMPTIONS
     all_path_exemptions = load_path_exemptions(repository_root)
     all_findings: list[RepositoryFinding] = []

package/scripts/repository_policy.py

@@ -16,6 +16,7 @@ from repository_checks.config.constants import (
     REPOSITORY_ROOT_FLAG,
     USAGE_EXIT_CODE,
 )
+from repository_checks.followups import record_smell_findings
 from repository_checks.reporting import render_report
 from repository_checks.runner import run_repository_checks
 
@@ -90,8 +91,8 @@ def main(
         stderr: Error stream.
 
     Returns:
-        Zero when the tree is clean, one for findings, two for usage errors,
-        and three when a check fails closed.
+        Zero when the tree carries no breaking finding, one for a breaking
+        finding, two for usage errors, and three when a check fails closed.
     """
     try:
         namespace = _build_parser().parse_args(list(all_arguments))
@@ -102,6 +103,7 @@ def main(
     if namespace.repository_root is not None:
         selected_root = Path(namespace.repository_root).resolve()
     report = run_repository_checks(selected_root)
+    record_smell_findings(selected_root, report)
     stdout.write(render_report(report))
     return report.exit_code
 

package/scripts/review_closure.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Report whether every review finding on a pull request head is answered.
+
+::
+
+    python3 review_closure.py jl-cmd/claude-dev-env 1442
+    CLOSED jl-cmd/claude-dev-env#1442 ab845eb :: every review finding on this
+    commit is answered
+
+A finding waits until the agent driving the pull request replies to it or
+pushes the fix. Exit status is 0 for CLOSED, 1 for OPEN, and 2 when the pull
+request state could not be read.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from dev_env_scripts_constants.review_closure_constants import (
+    CLOSED_EXIT_CODE,
+    COMMAND_DESCRIPTION,
+    DRIVER_LOGIN_ARGUMENT_HELP,
+    ERROR_EXIT_CODE,
+    FINDING_LINE_TEMPLATE,
+    NUMBER_ARGUMENT_HELP,
+    OPEN_EXIT_CODE,
+    SLUG_ARGUMENT_HELP,
+)
+from pr_verification.github_parsing import GitHubError
+from review_closure_github import (
+    github_token,
+    read_approvals_conclusion,
+    read_pull_request,
+    read_review_threads,
+)
+from review_closure_model import (
+    OpenFinding,
+    all_open_findings,
+    driver_logins,
+    head_sha,
+    verdict_line,
+)
+
+
+@dataclass(frozen=True)
+class ClosureReport:
+    """What one run of this command found on a pull request."""
+
+    verdict: str
+    all_findings: tuple[OpenFinding, ...]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command line this script accepts.
+
+    Returns:
+        A parser taking a repository slug, a pull request number, and any
+        number of extra driver logins.
+    """
+    parser = argparse.ArgumentParser(description=COMMAND_DESCRIPTION)
+    parser.add_argument("slug", help=SLUG_ARGUMENT_HELP)
+    parser.add_argument("number", type=int, help=NUMBER_ARGUMENT_HELP)
+    parser.add_argument(
+        "--driver-login",
+        action="append",
+        default=[],
+        help=DRIVER_LOGIN_ARGUMENT_HELP,
+    )
+    return parser
+
+
+def closure_report(
+    slug: str, number: int, all_extra_logins: Sequence[str], token: str
+) -> ClosureReport:
+    """Read one pull request and judge the findings on its head.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        number: The pull request number.
+        all_extra_logins: Logins that count as the driving agent beside the
+            account that opened the pull request.
+        token: The GitHub token the reads authenticate with.
+
+    Returns:
+        The verdict line and each finding that waits.
+
+    Raises:
+        GitHubError: The pull request state could not be read.
+    """
+    all_pull_request_fields = read_pull_request(slug, number, token)
+    all_findings = all_open_findings(
+        read_review_threads(slug, number, token),
+        driver_logins(all_pull_request_fields, all_extra_logins),
+        read_approvals_conclusion(slug, head_sha(all_pull_request_fields), token),
+    )
+    return ClosureReport(
+        verdict=verdict_line(slug, all_pull_request_fields, all_findings),
+        all_findings=all_findings,
+    )
+
+
+def main(all_arguments: Sequence[str]) -> int:
+    """Print the review closure verdict for one pull request.
+
+    Args:
+        all_arguments: The command line, without the program name.
+
+    Returns:
+        Zero when every finding is answered, one when a finding waits, and
+        two when the pull request state could not be read.
+    """
+    parsed = build_parser().parse_args(all_arguments)
+    try:
+        report = closure_report(
+            parsed.slug, parsed.number, parsed.driver_login, github_token()
+        )
+    except GitHubError as failure:
+        print(failure, file=sys.stderr)
+        return ERROR_EXIT_CODE
+    print(report.verdict)
+    for each_finding in report.all_findings:
+        print(
+            FINDING_LINE_TEMPLATE.format(
+                subject=each_finding.subject, reason=each_finding.reason
+            )
+        )
+    return OPEN_EXIT_CODE if report.all_findings else CLOSED_EXIT_CODE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))