claude-dev-env 8.4.3 → 8.6.0

package/scripts/test_followup_cli.py

@@ -0,0 +1,270 @@
+"""Behavior tests for the follow-up command."""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+from pathlib import Path
+
+from dev_env_scripts_constants.followup_constants import (
+    BACKLOG_EXCEEDED_EXIT_CODE,
+    FOLLOWUP_BACKLOG_THRESHOLD,
+)
+from followup_cli import main
+
+_hooks_directory = str(Path(__file__).resolve().parents[1] / "hooks")
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from followup_ledger import (
+    FollowupFinding,
+    all_recorded_findings,
+    record_followup_finding,
+)
+
+
+def run_command(all_arguments: list[str]) -> tuple[int, str]:
+    output_stream = io.StringIO()
+    exit_code = main(all_arguments, stdout=output_stream)
+    return exit_code, output_stream.getvalue()
+
+
+def write_lint_report(
+    report_path: Path, all_diagnostics: list[dict[str, object]]
+) -> None:
+    report_path.write_text(
+        json.dumps(
+            {"schema_version": 1, "diagnostics": all_diagnostics, "failed_rules": []}
+        ),
+        encoding="utf-8",
+    )
+
+
+def test_list_reports_nothing_outstanding_for_an_empty_ledger(tmp_path: Path) -> None:
+    exit_code, output_text = run_command(["list", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "no follow-ups recorded" in output_text
+
+
+def test_list_names_each_recorded_finding(tmp_path: Path) -> None:
+    record_followup_finding(
+        tmp_path, FollowupFinding("instruction-git-mode", "CLAUDE.md", "wrong mode")
+    )
+
+    exit_code, output_text = run_command(["list", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "instruction-git-mode" in output_text
+    assert "CLAUDE.md" in output_text
+
+
+def test_ingest_records_every_located_diagnostic(tmp_path: Path) -> None:
+    report_path = tmp_path / "lint.json"
+    write_lint_report(
+        report_path,
+        [
+            {
+                "rule_id": "line-length",
+                "severity": "error",
+                "message": "line runs past the limit",
+                "location": {"path": "src/app.py", "start_line": 4, "start_column": 1},
+            }
+        ],
+    )
+
+    exit_code, _ = run_command(
+        ["ingest", str(report_path), "--repository-root", str(tmp_path)]
+    )
+
+    assert exit_code == 0
+    assert all_recorded_findings(tmp_path) == (
+        FollowupFinding(
+            "line-length", "src/app.py", "line runs past the limit", "line-length"
+        ),
+    )
+
+
+def test_ingest_records_a_diagnostic_without_a_location(tmp_path: Path) -> None:
+    report_path = tmp_path / "lint.json"
+    write_lint_report(
+        report_path,
+        [
+            {
+                "rule_id": "inventory-drift",
+                "severity": "error",
+                "message": "inventory row missing",
+                "location": None,
+            }
+        ],
+    )
+
+    run_command(["ingest", str(report_path), "--repository-root", str(tmp_path)])
+
+    assert all_recorded_findings(tmp_path) == (
+        FollowupFinding(
+            "inventory-drift", "", "inventory row missing", "inventory-drift"
+        ),
+    )
+
+
+def test_ingest_reports_an_unreadable_report(tmp_path: Path) -> None:
+    exit_code, output_text = run_command(
+        ["ingest", str(tmp_path / "absent.json"), "--repository-root", str(tmp_path)]
+    )
+
+    assert exit_code == 2
+    assert "absent.json" in output_text
+
+
+def test_brief_names_every_recorded_finding_and_the_repository(tmp_path: Path) -> None:
+    record_followup_finding(
+        tmp_path, FollowupFinding("instruction-git-mode", "CLAUDE.md", "wrong mode")
+    )
+
+    exit_code, output_text = run_command(["brief", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "instruction-git-mode" in output_text
+    assert "wrong mode" in output_text
+    assert "draft pull request" in output_text
+
+
+def test_brief_asks_for_no_work_on_an_empty_ledger(tmp_path: Path) -> None:
+    exit_code, output_text = run_command(["brief", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "no follow-ups recorded" in output_text
+
+
+def test_clear_empties_the_ledger(tmp_path: Path) -> None:
+    record_followup_finding(
+        tmp_path, FollowupFinding("instruction-git-mode", "CLAUDE.md", "wrong mode")
+    )
+
+    exit_code, _ = run_command(["clear", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert all_recorded_findings(tmp_path) == ()
+
+
+def test_clear_on_an_empty_ledger_succeeds(tmp_path: Path) -> None:
+    exit_code, _ = run_command(["clear", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+
+
+def test_an_unknown_command_reports_usage(tmp_path: Path) -> None:
+    exit_code, output_text = run_command(
+        ["stampede", "--repository-root", str(tmp_path)]
+    )
+
+    assert exit_code == 2
+    assert "Usage" in output_text
+
+
+def test_ingest_carries_the_check_identifier_a_diagnostic_names(
+    tmp_path: Path,
+) -> None:
+    report_path = tmp_path / "lint.json"
+    write_lint_report(
+        report_path,
+        [
+            {
+                "rule_id": "code-rules",
+                "check_id": "code-rules/constant-outside-config",
+                "severity": "error",
+                "message": "Line 3: Constant TIMEOUT - move to config/",
+                "location": {"path": "scripts/run.py", "start_line": 3},
+            }
+        ],
+    )
+
+    run_command(["ingest", str(report_path), "--repository-root", str(tmp_path)])
+
+    recorded_finding = all_recorded_findings(tmp_path)[0]
+    assert recorded_finding.check_id == "code-rules/constant-outside-config"
+    assert recorded_finding.severity == "smell"
+
+
+def test_ingest_records_the_revision_the_repository_has_checked_out(
+    tmp_path: Path,
+) -> None:
+    (tmp_path / ".git").mkdir()
+    (tmp_path / ".git" / "HEAD").write_text("f00dcafe\n", encoding="utf-8")
+    report_path = tmp_path / "lint.json"
+    write_lint_report(
+        report_path,
+        [
+            {
+                "rule_id": "code-rules",
+                "check_id": "code-rules/function-length",
+                "message": "Line 9: Function 'run' is 74 lines",
+                "location": {"path": "scripts/run.py", "start_line": 9},
+            }
+        ],
+    )
+
+    run_command(["ingest", str(report_path), "--repository-root", str(tmp_path)])
+
+    assert all_recorded_findings(tmp_path)[0].origin_commit == "f00dcafe"
+
+
+def test_count_reports_an_empty_backlog(tmp_path: Path) -> None:
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "0" in output_text
+
+
+def test_count_passes_while_the_backlog_sits_under_the_threshold(
+    tmp_path: Path,
+) -> None:
+    record_followup_finding(
+        tmp_path, FollowupFinding("code-rules", "run.py", "one smell", "code-rules/x")
+    )
+
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "1" in output_text
+
+
+def test_count_escalates_once_the_backlog_passes_the_threshold(
+    tmp_path: Path,
+) -> None:
+    for each_index in range(FOLLOWUP_BACKLOG_THRESHOLD + 1):
+        record_followup_finding(
+            tmp_path,
+            FollowupFinding(
+                "code-rules",
+                f"run{each_index}.py",
+                "one smell",
+                f"code-rules/x{each_index}",
+            ),
+        )
+
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == BACKLOG_EXCEEDED_EXIT_CODE
+    assert str(FOLLOWUP_BACKLOG_THRESHOLD) in output_text
+
+
+def test_list_names_the_check_behind_each_finding(tmp_path: Path) -> None:
+    record_followup_finding(
+        tmp_path,
+        FollowupFinding(
+            "code-rules",
+            "run.py",
+            "one smell",
+            "code-rules/constant-outside-config",
+            "smell",
+            "f00dcafe",
+        ),
+    )
+
+    _, output_text = run_command(["list", "--repository-root", str(tmp_path)])
+
+    assert "code-rules/constant-outside-config" in output_text
+    assert "f00dcafe" in output_text

package/scripts/test_validate_instruction_pairs.py

@@ -1,7 +1,22 @@
 import subprocess
 from pathlib import Path
 
-from validate_instruction_pairs import validate_repository
+import sys
+
+from validate_instruction_pairs import (
+    GATE_FAILED_EXIT_CODE,
+    GATE_PASSED_EXIT_CODE,
+    all_instruction_findings,
+    run_gate,
+    validate_repository,
+)
+
+_hooks_directory = str(Path(__file__).resolve().parents[1] / "hooks")
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from followup_ledger import all_recorded_findings, head_commit
+from hooks_constants.followup_ledger_constants import SEVERITY_SMELL
 
 
 def read_workflow(workflow_filename: str) -> str:
@@ -145,3 +160,153 @@ def test_release_please_short_circuit_exists_in_workflow() -> None:
     assert "chore(.*): release " in workflow_text
     assert "autorelease: pending" in workflow_text
     assert "skip-validation:" in workflow_text
+
+
+def write_valid_pair(repository_root: Path) -> None:
+    (repository_root / "AGENTS.md").write_bytes(b"# Canonical guidance\n")
+    (repository_root / "CLAUDE.md").write_bytes(b"@AGENTS.md\n")
+    subprocess.run(
+        ["git", "add", "AGENTS.md", "CLAUDE.md"], cwd=repository_root, check=True
+    )
+
+
+def make_import_text_wrong(repository_root: Path) -> None:
+    (repository_root / "CLAUDE.md").write_bytes(b"@AGENTS.md\n\nExtra guidance.\n")
+
+
+def make_git_mode_executable(repository_root: Path) -> None:
+    subprocess.run(
+        ["git", "update-index", "--chmod=+x", "CLAUDE.md"],
+        cwd=repository_root,
+        check=True,
+    )
+
+
+def test_a_wrong_import_text_is_a_breaking_finding(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    write_valid_pair(tmp_path)
+    make_import_text_wrong(tmp_path)
+
+    all_breaking = [
+        each_finding
+        for each_finding in all_instruction_findings(tmp_path)
+        if each_finding.severity == "breaking"
+    ]
+
+    assert [each_finding.rule_id for each_finding in all_breaking] == [
+        "instruction-import-text"
+    ]
+
+
+def test_a_wrong_git_mode_is_a_smell_finding(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    write_valid_pair(tmp_path)
+    make_git_mode_executable(tmp_path)
+
+    all_smells = [
+        each_finding
+        for each_finding in all_instruction_findings(tmp_path)
+        if each_finding.severity == "smell"
+    ]
+
+    assert [each_finding.rule_id for each_finding in all_smells] == [
+        "instruction-git-mode"
+    ]
+
+
+def test_run_gate_fails_on_a_breaking_finding(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    write_valid_pair(tmp_path)
+    make_import_text_wrong(tmp_path)
+
+    assert run_gate(tmp_path) == GATE_FAILED_EXIT_CODE
+
+
+def test_run_gate_passes_a_smell_and_records_it(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    write_valid_pair(tmp_path)
+    make_git_mode_executable(tmp_path)
+
+    exit_code = run_gate(tmp_path)
+
+    assert exit_code == GATE_PASSED_EXIT_CODE
+    assert [
+        each_finding.rule_id for each_finding in all_recorded_findings(tmp_path)
+    ] == ["instruction-git-mode"]
+
+
+def test_a_recorded_smell_carries_its_severity_and_the_checked_out_revision(
+    tmp_path: Path,
+) -> None:
+    initialize_repository(tmp_path)
+    write_valid_pair(tmp_path)
+    make_git_mode_executable(tmp_path)
+    subprocess.run(
+        ["git", "commit", "--quiet", "-m", "instruction pair"],
+        cwd=tmp_path,
+        check=True,
+    )
+
+    run_gate(tmp_path)
+
+    recorded_finding = all_recorded_findings(tmp_path)[0]
+    assert recorded_finding.severity == SEVERITY_SMELL
+    assert recorded_finding.check_id == "instruction-git-mode"
+    assert recorded_finding.origin_commit == head_commit(tmp_path)
+    assert recorded_finding.origin_commit
+
+
+def test_run_gate_records_a_smell_it_finds_beside_a_breaking_finding(
+    tmp_path: Path,
+) -> None:
+    initialize_repository(tmp_path)
+    write_valid_pair(tmp_path)
+    make_import_text_wrong(tmp_path)
+    make_git_mode_executable(tmp_path)
+
+    exit_code = run_gate(tmp_path)
+
+    assert exit_code == GATE_FAILED_EXIT_CODE
+    assert [
+        each_finding.rule_id for each_finding in all_recorded_findings(tmp_path)
+    ] == ["instruction-git-mode"]
+
+
+def test_run_gate_passes_a_valid_tree_and_records_nothing(tmp_path: Path) -> None:
+    initialize_repository(tmp_path)
+    write_valid_pair(tmp_path)
+
+    exit_code = run_gate(tmp_path)
+
+    assert exit_code == GATE_PASSED_EXIT_CODE
+    assert all_recorded_findings(tmp_path) == ()
+
+
+def read_sparse_checkout_paths() -> list[str]:
+    workflow_text = read_workflow("instruction-pairs-reusable.yml")
+    block_start = workflow_text.index("sparse-checkout: |")
+    block_end = workflow_text.index("sparse-checkout-cone-mode", block_start)
+    return [
+        each_line.strip()
+        for each_line in workflow_text[block_start:block_end].splitlines()
+        if each_line.strip().startswith("packages/")
+    ]
+
+
+def test_sparse_checkout_carries_every_module_the_validator_imports() -> None:
+    package_root = Path(__file__).resolve().parents[1]
+    all_checked_out_paths = set(read_sparse_checkout_paths())
+
+    all_required_paths = {
+        "packages/claude-dev-env/scripts/validate_instruction_pairs.py",
+        "packages/claude-dev-env/scripts/subprocess_window_access.py",
+        "packages/claude-dev-env/scripts/dev_env_scripts_constants/__init__.py",
+        "packages/claude-dev-env/scripts/dev_env_scripts_constants/followup_constants.py",
+        "packages/claude-dev-env/hooks/followup_ledger.py",
+        "packages/claude-dev-env/hooks/hooks_constants/__init__.py",
+        "packages/claude-dev-env/hooks/hooks_constants/followup_ledger_constants.py",
+    }
+
+    assert all_required_paths <= all_checked_out_paths
+    for each_path in all_checked_out_paths:
+        assert (package_root.parents[1] / each_path).is_file()

package/scripts/tests/test_policy_lint_rules_check_catalog.py

@@ -0,0 +1,151 @@
+"""Synchronization tests for the per-check identifier catalog.
+
+Each sample below is a message copied from the check that raises it. A check
+whose wording moves fails its sample here, so the catalog and the checks stay
+in step.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from policy_lint.check_catalog import check_id_for_message
+from policy_lint.config.check_catalog_constants import (
+    ALL_CHECK_CATALOG_ENTRIES,
+    UNCLASSIFIED_CHECK_NAME,
+)
+from policy_lint.model import Diagnostic, Severity
+
+_BUNDLING_RULE_ID = "code-rules"
+_HOOKS_DIRECTORY = Path(__file__).resolve().parents[2] / "hooks"
+_TEST_FILE_PREFIX = "test_"
+_PYTHON_GLOB = "*.py"
+_SOURCE_ENCODING = "utf-8"
+
+ALL_MESSAGE_SAMPLES: tuple[tuple[str, str], ...] = (
+    (
+        "Line 20: Function 'run' is 74 lines - exceeds blocking threshold - "
+        "split into helpers",
+        "function-length",
+    ),
+    (
+        "Line 8: Function-local constant TIMEOUT - consider moving to config/",
+        "function-local-constant",
+    ),
+    ("Line 3: Constant TIMEOUT - move to config/", "constant-outside-config"),
+    (
+        "Line 5: Collection parameter paths - prefix with all_ (CODE_RULES §5)",
+        "collection-name-prefix",
+    ),
+    (
+        "Line 6: loop variable 'path' - prefix with each_ (CODE_RULES §5)",
+        "loop-variable-prefix",
+    ),
+    (
+        "Line 7: Stuttering collection prefix 'all_all_paths'",
+        "stuttering-collection-prefix",
+    ),
+    ("Line 9: string separator '\\n' - name it", "unnamed-string-separator"),
+    ("Line 10: string magic value 'utf-8'", "string-magic-value"),
+    (
+        "Line 11: Block comment found - refactor to self-documenting code",
+        "block-comment-added",
+    ),
+    (
+        "Line 12: Comment found - refactor to self-documenting code",
+        "comment-added",
+    ),
+    ("Line 13: TODO comment added: fix later", "comment-diff"),
+    (
+        "Line 14: module docstring carries a 44-word run-on sentence",
+        "docstring-runon-sentence",
+    ),
+    ("Line 15: module summary runs 9 prose lines", "docstring-prose-wall"),
+    (
+        "Line 16: parameter 'count' on 'run' missing type annotation (CODE_RULES §6)",
+        "missing-type-annotation",
+    ),
+    (
+        "Line 17: function 'run' missing return type annotation (CODE_RULES §6)",
+        "missing-return-annotation",
+    ),
+    ("src/app.py:3: Single-letter variable 'p'", "single-letter-variable"),
+)
+
+
+def _all_hook_source_texts() -> tuple[str, ...]:
+    return tuple(
+        each_path.read_text(encoding=_SOURCE_ENCODING)
+        for each_path in _HOOKS_DIRECTORY.rglob(_PYTHON_GLOB)
+        if not each_path.name.startswith(_TEST_FILE_PREFIX)
+    )
+
+
+@pytest.mark.parametrize(("sample_message", "expected_name"), ALL_MESSAGE_SAMPLES)
+def test_a_message_sample_resolves_to_its_check_name(
+    sample_message: str, expected_name: str
+) -> None:
+    resolved_check_id = check_id_for_message(_BUNDLING_RULE_ID, sample_message)
+
+    assert resolved_check_id == f"{_BUNDLING_RULE_ID}/{expected_name}"
+
+
+def test_every_catalog_entry_carries_a_message_sample() -> None:
+    all_sampled_names = {each_sample[1] for each_sample in ALL_MESSAGE_SAMPLES}
+    all_catalog_names = {
+        each_entry.check_name for each_entry in ALL_CHECK_CATALOG_ENTRIES
+    }
+
+    assert all_catalog_names == all_sampled_names
+
+
+@pytest.mark.parametrize("catalog_entry", ALL_CHECK_CATALOG_ENTRIES)
+def test_each_catalog_marker_is_still_written_by_a_check(catalog_entry) -> None:
+    all_source_texts = _all_hook_source_texts()
+
+    assert any(
+        catalog_entry.message_marker in each_text for each_text in all_source_texts
+    )
+
+
+def test_every_catalog_check_name_is_distinct_from_its_neighbours() -> None:
+    all_names = [each_entry.check_name for each_entry in ALL_CHECK_CATALOG_ENTRIES]
+
+    assert len(set(all_names)) == len(all_names)
+
+
+def test_an_unmatched_message_stays_unclassified() -> None:
+    resolved_check_id = check_id_for_message(
+        _BUNDLING_RULE_ID, "Line 4: a finding no catalog entry names"
+    )
+
+    assert resolved_check_id == f"{_BUNDLING_RULE_ID}/{UNCLASSIFIED_CHECK_NAME}"
+
+
+def test_a_rule_outside_the_bundling_set_keeps_its_own_identifier() -> None:
+    resolved_check_id = check_id_for_message(
+        "rmtree-safety", "Line 9: shutil.rmtree with ignore_errors=True"
+    )
+
+    assert resolved_check_id == "rmtree-safety"
+
+
+def test_a_diagnostic_reports_its_rule_identifier_when_it_carries_no_check_name() -> (
+    None
+):
+    diagnostic = Diagnostic("test-pairing", Severity.ERROR, "no matching test")
+
+    assert diagnostic.as_dict()["check_id"] == "test-pairing"
+
+
+def test_a_diagnostic_reports_the_check_identifier_it_carries() -> None:
+    diagnostic = Diagnostic(
+        "code-rules",
+        Severity.ERROR,
+        "Line 3: Constant TIMEOUT - move to config/",
+        None,
+        "code-rules/constant-outside-config",
+    )
+
+    assert diagnostic.as_dict()["check_id"] == "code-rules/constant-outside-config"