claude-dev-env 8.6.1 → 8.8.0

package/scripts/policy_lint/adapter_contrast_framing.py

@@ -0,0 +1,59 @@
+"""Report authored prose that defines its subject against a rejected reading.
+
+A contrast leaves the reader holding two readings where one would do. The
+detector lives in ``scripts/contrast_framing.py`` and reads its pattern list
+from ``scripts/dev_env_scripts_constants/contrast_framing_constants.py``, the
+same list the durable post linter reads.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from contrast_framing import describe_contrast_framing, find_contrast_framing
+
+from .config import constants
+from .model import Diagnostic, Document, Location, Severity
+
+
+def accepts_authored_markdown(document: Document) -> bool:
+    """Return whether the document is Markdown an author wrote.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for Markdown outside the generated documents.
+    """
+    if document.path.suffix.lower() not in constants.ALL_MARKDOWN_SUFFIXES:
+        return False
+    return document.path.name.lower() not in constants.ALL_GENERATED_DOCUMENT_NAMES
+
+
+def contrast_framing_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Report each contrast-framing occurrence in one document.
+
+    Args:
+        document: Current document text and path.
+        repository_root: Request repository root, unused by this detector.
+
+    Returns:
+        Contrast-framing diagnostics in document order.
+    """
+    del repository_root
+    all_lines = document.text.splitlines()
+    return tuple(
+        Diagnostic(
+            constants.CONTRAST_FRAMING_RULE_ID,
+            Severity.ERROR,
+            describe_contrast_framing(
+                all_lines[each_line_number - 1], each_form_name
+            ),
+            Location(document.path, each_line_number, each_column),
+        )
+        for each_line_number, each_column, each_form_name in find_contrast_framing(
+            document.text
+        )
+    )

package/scripts/policy_lint/adapters.py

@@ -10,6 +10,7 @@ from shared_tree_paths import resolve_shared_scripts_directory
 
 from . import (
     adapter_configuration,
+    adapter_contrast_framing,
     adapter_detectors,
     adapter_pairing,
     adapter_retired_hook_prose,
@@ -438,6 +439,35 @@ def accepts_instruction_markdown(document: Document) -> bool:
     return adapter_retired_hook_prose.accepts_instruction_markdown(document)
 
 
+def accepts_authored_markdown(document: Document) -> bool:
+    """Return whether the document is Markdown an author wrote.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for Markdown outside the generated documents.
+    """
+    return adapter_contrast_framing.accepts_authored_markdown(document)
+
+
+def contrast_framing_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Report prose that defines its subject against a rejected reading.
+
+    Args:
+        document: Current Markdown text and path.
+        repository_root: Request repository root.
+
+    Returns:
+        Contrast-framing diagnostics.
+    """
+    return adapter_contrast_framing.contrast_framing_diagnostics(
+        document, repository_root
+    )
+
+
 def retired_hook_prose_diagnostics(
     document: Document, repository_root: Path
 ) -> tuple[Diagnostic, ...]:

package/scripts/policy_lint/config/constants.py

@@ -168,3 +168,5 @@ RETIRED_HOOK_PROSE_MESSAGE = (
     "reaches no tool call. Say what the reader faces now, or drop the "
     "present-tense action."
 )
+
+CONTRAST_FRAMING_RULE_ID = "contrast-framing"

package/scripts/policy_lint/registry.py

@@ -104,6 +104,11 @@ def _text_document_rules() -> tuple[model.Rule, ...]:
             adapters.accepts_workflow,
             adapters.workflow_substitution_diagnostics,
         ),
+        build_document_rule(
+            "contrast-framing",
+            adapters.accepts_authored_markdown,
+            adapters.contrast_framing_diagnostics,
+        ),
         build_document_rule(
             "retired-hook-prose",
             adapters.accepts_instruction_markdown,

package/scripts/repository_checks/config/constants.py

@@ -21,6 +21,16 @@ ALL_CHECK_IDS = (
     CHECK_ID_TRACKED_PERSONAL_DATA,
 )
 
+SEVERITY_BREAKING = "breaking"
+SEVERITY_SMELL = "smell"
+SEVERITY_BY_CHECK_ID: dict[str, str] = {
+    CHECK_ID_CLAUDE_MD_ORPHANS: SEVERITY_BREAKING,
+    CHECK_ID_ENV_VAR_DOCUMENTATION: SEVERITY_BREAKING,
+    CHECK_ID_PACKAGE_INVENTORY: SEVERITY_SMELL,
+    CHECK_ID_PYTEST_TESTPATHS: SEVERITY_BREAKING,
+    CHECK_ID_TRACKED_PERSONAL_DATA: SEVERITY_BREAKING,
+}
+
 SUCCESS_EXIT_CODE = 0
 FINDINGS_EXIT_CODE = 1
 FAILED_CHECK_EXIT_CODE = INCOMPLETE_EXIT_CODE
@@ -28,6 +38,7 @@ USAGE_EXIT_CODE = INVALID_INPUT_EXIT_CODE
 
 REPOSITORY_ROOT_FLAG = "--repository-root"
 FINDING_LINE_TEMPLATE = "{check_id}: {relative_path}: {message}"
+ADVISORY_FINDING_LINE_TEMPLATE = "advisory: {check_id}: {relative_path}: {message}"
 RULE_FAILED_LINE_TEMPLATE = "error: rule failed: {check_id}"
 REPORT_LINE_SEPARATOR = "\n"
 EMPTY_REPORT_TEXT = ""
@@ -57,6 +68,7 @@ PACKAGE_INVENTORY_CONSTANTS_MODULE_NAME = (
 )
 PYTEST_TESTPATHS_MODULE_NAME = "blocking.pytest_testpaths_orphan_blocker"
 PII_SCANNER_MODULE_NAME = "blocking.pii_scanner"
+FOLLOWUP_LEDGER_MODULE_NAME = "followup_ledger"
 REPOSITORY_EXEMPTION_MODULE_NAME = (
     "blocking.pii_prevention_blocker_parts.repository_exemption"
 )

package/scripts/repository_checks/config/policy_document.py

@@ -1,6 +1,7 @@
 """Repository policy document and exception-entry schema."""
 
 import re
+from typing import NamedTuple
 
 CONFIG_RELATIVE_PATH = "config/repository-policy.json"
 DIGEST_PATTERN = re.compile(r"[0-9a-f]{64}")
@@ -11,9 +12,34 @@ FIRST_PRINTABLE_CODEPOINT = 32
 VERSION_FIELD = "version"
 SUPPORTED_DOCUMENT_VERSION = 1
 EMAIL_EXEMPTIONS_FIELD = "email_exemptions"
+PRIVATE_IP_EXEMPTIONS_FIELD = "private_ip_exemptions"
 PATH_EXEMPTIONS_FIELD = "path_exemptions"
-ALL_EXEMPTION_FIELDS = frozenset({EMAIL_EXEMPTIONS_FIELD, PATH_EXEMPTIONS_FIELD})
-ALL_DOCUMENT_FIELDS = ALL_EXEMPTION_FIELDS | {VERSION_FIELD}
 EMAIL_EXEMPTION_SUBJECT = "Email exemption"
+PRIVATE_IP_EXEMPTION_SUBJECT = "Private IP exemption"
 PATH_EXEMPTION_SUBJECT = "Path exemption"
 EMAIL_CATEGORY = "email"
+PRIVATE_IP_CATEGORY = "private-ip"
+
+
+class MatchExemptionFamily(NamedTuple):
+    """One scanner category cleared by a committed path and match digest."""
+
+    field_name: str
+    category: str
+    subject: str
+
+
+EMAIL_EXEMPTION_FAMILY = MatchExemptionFamily(
+    EMAIL_EXEMPTIONS_FIELD, EMAIL_CATEGORY, EMAIL_EXEMPTION_SUBJECT
+)
+PRIVATE_IP_EXEMPTION_FAMILY = MatchExemptionFamily(
+    PRIVATE_IP_EXEMPTIONS_FIELD, PRIVATE_IP_CATEGORY, PRIVATE_IP_EXEMPTION_SUBJECT
+)
+ALL_MATCH_EXEMPTION_FAMILIES = (
+    EMAIL_EXEMPTION_FAMILY,
+    PRIVATE_IP_EXEMPTION_FAMILY,
+)
+ALL_EXEMPTION_FIELDS = frozenset(
+    each_family.field_name for each_family in ALL_MATCH_EXEMPTION_FAMILIES
+) | {PATH_EXEMPTIONS_FIELD}
+ALL_DOCUMENT_FIELDS = ALL_EXEMPTION_FIELDS | {VERSION_FIELD}

package/scripts/repository_checks/followups.py

@@ -0,0 +1,54 @@
+"""Record advisory committed-tree findings in the follow-up ledger."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import ModuleType
+
+from repository_checks.config.constants import (
+    ALL_FAIL_CLOSED_EXCEPTION_TYPES,
+    FOLLOWUP_LEDGER_MODULE_NAME,
+    SEVERITY_SMELL,
+)
+from repository_checks.hook_modules import load_hooks_module
+from repository_checks.models import RepositoryCheckReport, RepositoryFinding
+
+
+def record_smell_findings(repository_root: Path, report: RepositoryCheckReport) -> None:
+    """Append every advisory finding to the repository's follow-up ledger.
+
+    The ledger keeps the gate's decision unchanged, so a ledger that cannot be
+    loaded or written leaves the report's exit code as it stands.
+
+    Args:
+        repository_root: The repository whose ledger receives the findings.
+        report: The findings this run produced.
+    """
+    if not report.all_smell_findings:
+        return
+    try:
+        ledger = load_hooks_module(FOLLOWUP_LEDGER_MODULE_NAME)
+        origin_commit = ledger.head_commit(repository_root)
+        for each_finding in report.all_smell_findings:
+            _append_finding(ledger, repository_root, each_finding, origin_commit)
+    except ALL_FAIL_CLOSED_EXCEPTION_TYPES:
+        return
+
+
+def _append_finding(
+    ledger: ModuleType,
+    repository_root: Path,
+    finding: RepositoryFinding,
+    origin_commit: str,
+) -> None:
+    ledger.record_followup_finding(
+        repository_root,
+        ledger.FollowupFinding(
+            finding.check_id,
+            finding.relative_path,
+            finding.message,
+            finding.check_id,
+            SEVERITY_SMELL,
+            origin_commit,
+        ),
+    )

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:]))