claude-dev-env 2.36.0 → 4.0.0

package/scripts/tests/test_reporting.py

@@ -0,0 +1,54 @@
+"""Behavior tests for repository-check report rendering."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIRECTORY = Path(__file__).resolve().parents[1]
+_TESTS_DIRECTORY = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIRECTORY))
+if str(_TESTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_TESTS_DIRECTORY))
+
+from repository_checks.models import RepositoryCheckReport, RepositoryFinding
+from repository_checks.reporting import render_report
+from repository_policy_test_support import (
+    commit_tracked_files,
+    initialize_repository,
+    run_policy,
+    write_text,
+)
+
+
+def test_should_render_findings_and_failed_checks_in_report_order() -> None:
+    report = RepositoryCheckReport(
+        (RepositoryFinding("check", "relative/file.py", "message"),),
+        ("failed-check",),
+    )
+    assert render_report(report) == (
+        "check: relative/file.py: message\nerror: rule failed: failed-check\n"
+    )
+
+
+def test_should_render_an_empty_clean_report() -> None:
+    assert render_report(RepositoryCheckReport((), ())) == ""
+
+
+def test_should_print_repository_relative_paths_only(tmp_path: Path) -> None:
+    repository_root = tmp_path / "repo"
+    initialize_repository(repository_root)
+    write_text(
+        repository_root / "notes" / "CLAUDE.md",
+        "# notes\n\n"
+        "| File | Role |\n"
+        "|---|---|\n"
+        "| `absent_helper.py` | Missing helper |\n",
+    )
+    commit_tracked_files(repository_root)
+    _exit_code, stdout_text, stderr_text = run_policy(repository_root)
+    absolute_root_text = str(repository_root.resolve())
+    assert absolute_root_text not in stdout_text
+    assert absolute_root_text not in stderr_text
+    assert "notes/CLAUDE.md" in stdout_text

package/scripts/tests/test_repository_policy.py

@@ -0,0 +1,71 @@
+"""Command behavior for the committed-tree repository checker."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIRECTORY = Path(__file__).resolve().parents[1]
+_TESTS_DIRECTORY = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIRECTORY))
+if str(_TESTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_TESTS_DIRECTORY))
+
+import repository_policy
+from repository_checks.config.constants import (
+    CHECK_ID_CLAUDE_MD_ORPHANS,
+    CHECK_ID_ENV_VAR_DOCUMENTATION,
+    CHECK_ID_PACKAGE_INVENTORY,
+    CHECK_ID_PYTEST_TESTPATHS,
+    CHECK_ID_TRACKED_PERSONAL_DATA,
+)
+from repository_policy_test_support import run_policy, seed_clean_repository
+
+_POLICY_SCRIPT_PATH = _SCRIPTS_DIRECTORY / "repository_policy.py"
+_CHECK_SCRIPT_PATH = _SCRIPTS_DIRECTORY / "check.ps1"
+_UTF8_ENCODING = "utf-8"
+
+
+def test_should_exit_zero_on_a_clean_tracked_tree(tmp_path: Path) -> None:
+    repository_root = seed_clean_repository(tmp_path / "repo")
+    exit_code, stdout_text, stderr_text = run_policy(repository_root)
+    assert exit_code == 0
+    assert stdout_text == ""
+    assert stderr_text == ""
+
+
+def test_should_keep_stable_check_identifiers() -> None:
+    assert repository_policy.ALL_CHECK_IDS == (
+        CHECK_ID_CLAUDE_MD_ORPHANS,
+        CHECK_ID_ENV_VAR_DOCUMENTATION,
+        CHECK_ID_PACKAGE_INVENTORY,
+        CHECK_ID_PYTEST_TESTPATHS,
+        CHECK_ID_TRACKED_PERSONAL_DATA,
+    )
+
+
+def test_should_invoke_the_checker_from_check_script() -> None:
+    script_text = _CHECK_SCRIPT_PATH.read_text(encoding=_UTF8_ENCODING)
+    assert "Invoke-Tool -Label 'repository-policy'" in script_text
+    assert "repository_policy.py" in script_text
+    assert "--repository-root" in script_text
+    assert "SkipRepositoryPolicy" in script_text
+
+
+def test_should_run_the_checker_as_a_subprocess(tmp_path: Path) -> None:
+    repository_root = seed_clean_repository(tmp_path / "repo")
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(_POLICY_SCRIPT_PATH),
+            "--repository-root",
+            str(repository_root),
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert completed.returncode == 0
+    assert completed.stdout == ""

package/scripts/tests/test_runner.py

@@ -0,0 +1,59 @@
+"""Behavior tests for repository-check orchestration."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_TESTS_DIRECTORY = Path(__file__).resolve().parent
+if str(_TESTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_TESTS_DIRECTORY))
+
+from repository_checks.config.constants import (
+    FAILED_CHECK_EXIT_CODE,
+    FINDINGS_EXIT_CODE,
+)
+from repository_policy_test_support import (
+    commit_tracked_files,
+    initialize_repository,
+    run_policy,
+    seed_clean_repository,
+    write_text,
+)
+
+
+def test_should_fail_closed_when_tracked_paths_cannot_be_read(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    repository_root = seed_clean_repository(tmp_path / "repo")
+
+    def fail_tracked_paths(_repository_root: Path) -> tuple[str, ...]:
+        raise OSError("git ls-files failed")
+
+    monkeypatch.setattr(
+        "repository_checks.tracked_tree.tracked_relative_paths", fail_tracked_paths
+    )
+    exit_code, stdout_text, _stderr_text = run_policy(repository_root)
+    assert exit_code == FAILED_CHECK_EXIT_CODE
+    assert "error: rule failed:" in stdout_text
+
+
+def test_should_emit_stable_sorted_findings(tmp_path: Path) -> None:
+    repository_root = tmp_path / "repo"
+    initialize_repository(repository_root)
+    write_text(
+        repository_root / "zeta" / "CLAUDE.md",
+        "# zeta\n\n| File | Role |\n|---|---|\n| `missing_zeta.py` | Missing |\n",
+    )
+    write_text(
+        repository_root / "alpha" / "CLAUDE.md",
+        "# alpha\n\n| File | Role |\n|---|---|\n| `missing_alpha.py` | Missing |\n",
+    )
+    commit_tracked_files(repository_root)
+    first_exit_code, first_stdout, _first_stderr = run_policy(repository_root)
+    _second_exit_code, second_stdout, _second_stderr = run_policy(repository_root)
+    assert first_exit_code == FINDINGS_EXIT_CODE
+    assert first_stdout == second_stdout
+    assert first_stdout.index("alpha/CLAUDE.md") < first_stdout.index("zeta/CLAUDE.md")

package/scripts/tests/test_tracked_secrets.py

@@ -0,0 +1,175 @@
+"""Behavior tests for tracked-secret checks."""
+
+from __future__ import annotations
+
+import hashlib
+import sys
+from pathlib import Path
+
+import pytest
+from repository_checks.config.constants import (
+    ALL_TRACKED_SECRET_EXACT_EXEMPTIONS,
+    CHECK_ID_TRACKED_PERSONAL_DATA,
+    FINDINGS_EXIT_CODE,
+)
+from repository_checks.hook_modules import load_hooks_module
+from repository_checks.tracked_secrets import collect_tracked_secret_findings
+
+_TESTS_DIRECTORY = Path(__file__).resolve().parent
+if str(_TESTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_TESTS_DIRECTORY))
+
+from repository_policy_test_support import (
+    commit_tracked_files,
+    initialize_repository,
+    run_policy,
+    write_text,
+)
+
+_SYNTHETIC_GITHUB_TOKEN = "ghp_" + ("A" * 36)
+_UTF8_ENCODING = "utf-8"
+_REPOSITORY_ROOT = Path(__file__).resolve().parents[4]
+_EXEMPT_FIXTURE_EMAIL = "fixture-owner@company.io"
+_OTHER_FIXTURE_EMAIL = "other-owner@company.io"
+_OTHER_FIXTURE_HOME_PATH = "C:/Users/realname/notes.txt"
+_FIXTURE_NOTES_RELATIVE_PATH = "src/notes.py"
+_OTHER_NOTES_RELATIVE_PATH = "src/other_notes.py"
+_PII_PREVENTION_CONSTANTS = load_hooks_module(
+    "hooks_constants.pii_prevention_constants"
+)
+_PII_CATEGORY_EMAIL = _PII_PREVENTION_CONSTANTS.CATEGORY_EMAIL
+_PII_CATEGORY_HOME_PATH = _PII_PREVENTION_CONSTANTS.CATEGORY_HOME_PATH
+
+
+def test_should_flag_a_tracked_secret(tmp_path: Path) -> None:
+    repository_root = tmp_path / "repo"
+    initialize_repository(repository_root)
+    write_text(
+        repository_root / "src" / "app.py", f"token = '{_SYNTHETIC_GITHUB_TOKEN}'\n"
+    )
+    commit_tracked_files(repository_root)
+    exit_code, stdout_text, _stderr_text = run_policy(repository_root)
+    assert exit_code == FINDINGS_EXIT_CODE
+    assert CHECK_ID_TRACKED_PERSONAL_DATA in stdout_text
+    assert "src/app.py" in stdout_text
+    assert _SYNTHETIC_GITHUB_TOKEN not in stdout_text
+
+
+def test_should_fail_closed_before_reading_a_tracked_symlink_outside_repository(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    repository_root = tmp_path / "repo"
+    repository_root.mkdir()
+    outside_path = tmp_path / "outside.py"
+    write_text(outside_path, f"token = '{_SYNTHETIC_GITHUB_TOKEN}'\n")
+    tracked_symlink = repository_root / "linked.py"
+    tracked_symlink.symlink_to(outside_path)
+    original_read_text = Path.read_text
+    all_read_paths: list[Path] = []
+
+    def record_read_path(
+        file_path: Path,
+        encoding: str | None = None,
+        errors: str | None = None,
+    ) -> str:
+        all_read_paths.append(file_path)
+        return original_read_text(file_path, encoding=encoding, errors=errors)
+
+    monkeypatch.setattr(Path, "read_text", record_read_path)
+    with pytest.raises(OSError):
+        collect_tracked_secret_findings(repository_root, ["linked.py"])
+    assert tracked_symlink not in all_read_paths
+
+
+def test_should_flag_a_different_email_in_the_same_exact_exempted_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    repository_root = tmp_path / "repo"
+    initialize_repository(repository_root)
+    _write_exact_exemption_fixture(repository_root)
+    commit_tracked_files(repository_root)
+    _install_exact_email_exemption(monkeypatch)
+    exit_code, stdout_text, _stderr_text = run_policy(repository_root)
+    assert exit_code == FINDINGS_EXIT_CODE
+    assert _pii_categories_for_path(stdout_text, _FIXTURE_NOTES_RELATIVE_PATH) == [
+        _PII_CATEGORY_EMAIL,
+        _PII_CATEGORY_HOME_PATH,
+        _PII_PREVENTION_CONSTANTS.CATEGORY_SECRET,
+    ]
+    assert _EXEMPT_FIXTURE_EMAIL not in stdout_text
+    assert _SYNTHETIC_GITHUB_TOKEN not in stdout_text
+
+
+def test_should_flag_an_exact_exempt_value_at_a_different_path(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    repository_root = tmp_path / "repo"
+    initialize_repository(repository_root)
+    _write_exact_exemption_fixture(repository_root)
+    commit_tracked_files(repository_root)
+    _install_exact_email_exemption(monkeypatch)
+    _exit_code, stdout_text, _stderr_text = run_policy(repository_root)
+    assert _PII_CATEGORY_EMAIL in _pii_categories_for_path(
+        stdout_text, _OTHER_NOTES_RELATIVE_PATH
+    )
+
+
+def test_should_store_tracked_secret_exemptions_as_digests() -> None:
+    sha256_hex_digest_length = hashlib.sha256(b"").digest_size * 2
+    assert ALL_TRACKED_SECRET_EXACT_EXEMPTIONS
+    for _relative_path, _category, each_digest in ALL_TRACKED_SECRET_EXACT_EXEMPTIONS:
+        assert len(each_digest) == sha256_hex_digest_length
+        bytes.fromhex(each_digest)
+
+
+def test_should_keep_owned_checker_modules_free_of_tracked_secret_findings() -> None:
+    checker_directory = (
+        _REPOSITORY_ROOT
+        / "packages"
+        / "claude-dev-env"
+        / "scripts"
+        / "repository_checks"
+    )
+    all_relative_paths = [
+        each_path.relative_to(_REPOSITORY_ROOT).as_posix()
+        for each_path in checker_directory.rglob("*.py")
+        if each_path.is_file()
+    ]
+    assert collect_tracked_secret_findings(_REPOSITORY_ROOT, all_relative_paths) == []
+
+
+def _write_exact_exemption_fixture(repository_root: Path) -> None:
+    write_text(
+        repository_root / _FIXTURE_NOTES_RELATIVE_PATH,
+        f"contact = '{_EXEMPT_FIXTURE_EMAIL}'\nalt = '{_OTHER_FIXTURE_EMAIL}'\nhome = '{_OTHER_FIXTURE_HOME_PATH}'\ntoken = '{_SYNTHETIC_GITHUB_TOKEN}'\n",
+    )
+    write_text(
+        repository_root / _OTHER_NOTES_RELATIVE_PATH,
+        f"contact = '{_EXEMPT_FIXTURE_EMAIL}'\n",
+    )
+
+
+def _pii_categories_for_path(stdout_text: str, relative_path: str) -> list[str]:
+    finding_prefix = f"{CHECK_ID_TRACKED_PERSONAL_DATA}: {relative_path}:"
+    return sorted(
+        each_line.split("[", 1)[1].split("]", 1)[0]
+        for each_line in stdout_text.splitlines()
+        if each_line.startswith(finding_prefix)
+    )
+
+
+def _install_exact_email_exemption(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(
+        "repository_checks.tracked_secrets.repository_constants.ALL_TRACKED_SECRET_EXACT_EXEMPTIONS",
+        frozenset(
+            {
+                (
+                    _FIXTURE_NOTES_RELATIVE_PATH,
+                    _PII_CATEGORY_EMAIL,
+                    hashlib.sha256(
+                        _EXEMPT_FIXTURE_EMAIL.encode(_UTF8_ENCODING)
+                    ).hexdigest(),
+                )
+            }
+        ),
+    )

package/scripts/tests/test_tracked_tree.py

@@ -0,0 +1,28 @@
+"""Behavior tests for tracked repository path discovery."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_TESTS_DIRECTORY = Path(__file__).resolve().parent
+if str(_TESTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_TESTS_DIRECTORY))
+
+from repository_checks.tracked_tree import tracked_relative_paths
+from repository_policy_test_support import run_policy, seed_clean_repository, write_text
+
+
+def test_should_list_only_committed_relative_paths(tmp_path: Path) -> None:
+    repository_root = seed_clean_repository(tmp_path / "repo")
+    write_text(repository_root / "untracked.txt", "not committed\n")
+    assert tracked_relative_paths(repository_root) == ("README.md",)
+
+
+def test_should_skip_a_tracked_path_absent_from_the_worktree(tmp_path: Path) -> None:
+    repository_root = seed_clean_repository(tmp_path / "repo")
+    (repository_root / "README.md").unlink()
+    exit_code, stdout_text, stderr_text = run_policy(repository_root)
+    assert exit_code == 0
+    assert stdout_text == ""
+    assert stderr_text == ""

package/_shared/advisor/reference/sol-rung.md

@@ -1,39 +0,0 @@
-# Sol rung
-
-Detail behind the **Host profiles → Sol rung** section of [`advisor-protocol.md`](../advisor-protocol.md).
-Open this when Fable is out of usage on a Claude or ThirdParty host and a Sol fallback bind is starting.
-On a Codex host, Sol is the in-session default; see [`identity.md`](identity.md).
-
-## Flag
-
-`ADVISOR_SOL=1` (or `true` / `yes` / `on`) opens the Sol fallback after Fable is out of usage. Two channels exist: set the variable in the helper's process environment, or pass `--enable-sol` on the helper invocation — the CLI flag opens the rung for that run without touching the environment.
-Flag off both ways: fail closed when Fable did not bind.
-A Windows `setx` write only updates the persisted user environment; only a process started after that write inherits the new value, so an already-running session either sets the flag in its own invoking process environment or passes `--enable-sol`.
-
-## Effort
-
-`ADVISOR_EFFORT` selects Codex `model_reasoning_effort` for Sol and `--effort` for Fable: `low`, `medium`, `high`, `xhigh`, or `max`. The default is `low`, which sends `model_reasoning_effort="low"`. Pass `--effort <level>` on the helper to set effort for that Sol run without changing the environment. An unset or unrecognized value uses `low`.
-
-Every fallback reply carries a `fallback_kind` field: `declined` when policy closed the rung (flag off, usage meter at or below the gate) and `broken` when the Sol path itself failed (missing executable, spawn error, timeout, malformed reply). A `broken` fallback is a defect to report, not a routing outcome.
-
-## Preflight
-
-Flag on: run the Codex preflight first —
-
-```
-python ~/.claude/_shared/pr-loop/scripts/codex_usage_probe.py
-```
-
-**GOTCHA — probe path:** that installed path is the only one. `codex_sol_advisor.resolve_usage_probe_path` builds `~/.claude/_shared/pr-loop/scripts/codex_usage_probe.py` and stops. Do not hunt `skills/codex-review/`, Codex worktrees under `C:\dev\.codex\worktrees\`, or other copies. Repo home: `packages/claude-dev-env/_shared/pr-loop/scripts/`.
-
-The shared entry point is `~/.claude/_shared/advisor/scripts/codex_sol_advisor.py`; it calls the installed probe and owns Sol bind or resume parsing. Bind with `python ~/.claude/_shared/advisor/scripts/codex_sol_advisor.py --bind --enable-sol --cwd <repo-root>` and pipe the charter on stdin. Resume with `--resume <session_id>` and pipe the delta consult on stdin.
-
-The gate passes only when the probe exits 0, `percent_left` is finite numeric data, and `percent_left` is strictly greater than `WEEKLY_USAGE_GATE_THRESHOLD_PERCENT` from the existing probe. The exact-threshold case fails closed when Fable did not bind.
-
-## Branches
-
-**Preflight pass** — bind one Codex CLI session at `gpt-5.6-sol` with `model_reasoning_effort` set from `ADVISOR_EFFORT` (default `low`), `--sandbox read-only`, and JSON output. The helper receives the standing-reviewer charter on stdin and returns only parsed ENDORSE / CORRECTION / PLAN / STOP guidance with a session ID.
-
-**Preflight fail** — probe failure, non-zero exit, timeout, missing or malformed usage, `null`, non-finite usage, or usage at or below the threshold fails closed when Fable did not bind.
-
-The helper owns the Sol attempt and returns an explicit fallback result. The consuming advisor path owns the Fable bind. Apply the same gate to every Sol attempt, including resume.