claude-dev-env 2.35.0 → 4.0.0

package/_shared/pr-loop/scripts/terminology_sweep.py

@@ -1,7 +1,7 @@
 """Flag a prose term that names a code identifier a hair differently.
 
 A change adds the field ``premium_request_interactions`` while the same
-branch's docs call it the ``premium-request-budget`` field: one thing, two
+branch's docs call it the ``premium-request-budget`` field. One thing, two
 names, and a reader who searches one never finds the other.
 
 ::
@@ -14,38 +14,29 @@ names, and a reader who searches one never finds the other.
 
 The sweep reads a unified diff, collects the multi-word identifiers added on
 code lines, and scans each added prose line for a hyphen or space variant that
-renames only the final word of an identifier: it agrees on every earlier word
-and differs on the last. A term that diverges in any earlier word, or shares
-only one leading word, is ordinary prose. It also spares English compound
-tails, singular/plural forms, stopword windows, and words that are themselves
-tokens of another introduced identifier.
+renames only the final word of an identifier. The variant agrees on every
+earlier word and differs on the last. A term that diverges in any earlier
+word, or shares only one leading word, is ordinary prose. It also spares
+English compound tails, singular/plural forms, stopword windows, and words
+that are themselves tokens of another introduced identifier.
 """
 
 import argparse
 import os
 import subprocess
 import sys
+from collections.abc import Sequence
 from pathlib import Path
 
-parent_directory = str(Path(__file__).resolve().parent)
-if parent_directory not in sys.path:
-    sys.path.insert(0, parent_directory)
-
-from pr_loop_shared_constants.terminology_sweep_constants import (  # noqa: E402
+from pr_loop_shared_constants.terminology_sweep_constants import (
     ALL_COMMON_ENGLISH_COMPOUND_TAIL_WORDS,
+    ALL_DIFF_FILE_PATH_STRIP_PREFIXES,
+    ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND,
     ALL_GIT_GREP_BASE_TREE_COMMAND_PREFIX,
     ALL_PROSE_STOPWORD_TOKENS,
     ALL_STRING_ESCAPE_SEQUENCES,
-    ALL_TEST_FILE_NAME_INFIX_MARKERS,
-    GIT_BASE_TREE_REVISION,
-    IDENTIFIER_TOKEN_SEPARATOR,
-    PROSE_WINDOW_WORD_SEPARATOR,
-    TEST_DIRECTORY_PATH_SEGMENT,
-    TEST_FILE_PREFIX,
-    TEST_FILE_SUFFIX,
-    ALL_DIFF_FILE_PATH_STRIP_PREFIXES,
-    ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND,
     ALL_SWEEP_CODE_FILE_EXTENSIONS,
+    ALL_TEST_FILE_NAME_INFIX_MARKERS,
     CAMEL_CASE_IDENTIFIER_PATTERN,
     CAMEL_CASE_WORD_PATTERN,
     DIFF_ADDED_LINE_PREFIX,
@@ -55,19 +46,32 @@ from pr_loop_shared_constants.terminology_sweep_constants import (  # noqa: E402
     DIFF_NEW_FILE_HEADER_PREFIX,
     DIFF_OLD_FILE_HEADER_PREFIX,
     DIFF_REMOVED_LINE_PREFIX,
+    GIT_BASE_TREE_REVISION,
+    GIT_DECODE_ERRORS,
+    GIT_DIFF_OPERATION,
     GIT_DIFF_SUBPROCESS_TIMEOUT_SECONDS,
+    GIT_FAILURE_WITHOUT_DETAILS,
+    GIT_GREP_OPERATION_TEMPLATE,
+    GIT_NO_MATCH_EXIT_CODE,
+    GIT_OPERATION_FAILURE_TEMPLATE,
+    GIT_TEXT_ENCODING,
     HYPHENATED_PROSE_TOKEN_PATTERN,
+    IDENTIFIER_TOKEN_SEPARATOR,
     INLINE_CODE_SPAN_PATTERN,
     JAVASCRIPT_LINE_COMMENT_MARKER,
     JSDOC_CONTINUATION_MARKER,
     MARKDOWN_FILE_EXTENSION,
     MINIMUM_IDENTIFIER_TOKEN_COUNT,
+    PROSE_WINDOW_WORD_SEPARATOR,
     PROSE_WORD_PATTERN,
     PYTHON_COMMENT_MARKER,
     SNAKE_CASE_IDENTIFIER_PATTERN,
     STRING_LITERAL_CONTENT_PATTERN,
     TERMINOLOGY_FINDING_TEMPLATE,
     TERMINOLOGY_SWEEP_DESCRIPTION,
+    TEST_DIRECTORY_PATH_SEGMENT,
+    TEST_FILE_PREFIX,
+    TEST_FILE_SUFFIX,
 )
 
 IdentifierTuple = tuple[str, ...]
@@ -173,8 +177,8 @@ def _prose_fragments(file_path: str, line_text: str) -> list[str]:
     A Markdown line is prose with its inline-code spans removed, since a
     backticked span names code verbatim. A code line contributes its comment
     tail, its JSDoc continuation text, and the contents of its string
-    literals. A test module contributes its comment tail and JSDoc text only
-    — its string literals hold fixture data, not prose.
+    literals. A test module contributes its comment tail and JSDoc text only.
+    Its string literals hold fixture data, not prose.
 
     Args:
         file_path: The path the added line belongs to.
@@ -201,9 +205,9 @@ def _prose_fragments(file_path: str, line_text: str) -> list[str]:
 def _is_test_file(file_path: str) -> bool:
     """Return whether a diff path names a test code module.
 
-    A test module's string literals hold fixture data — embedded diffs,
-    generated source, file trees — not documentation prose, so the sweep
-    reads only its comments and JSDoc lines. A ``quota.test.mjs``, a
+    A test module's string literals hold fixture data: embedded diffs,
+    generated source, and file trees. That is not documentation prose, so the
+    sweep reads only its comments and JSDoc lines. A ``quota.test.mjs``, a
     ``layout.spec.ts``, and a ``fixtures.py`` under a tests directory are all
     test modules, so every one of these paths counts::
 
@@ -260,8 +264,8 @@ def _string_literal_fragments(line_text: str) -> list[str]:
     Escape sequences inside a literal (``\\n``, ``\\t``) are replaced with
     spaces before the words are read, so an escape letter never glues onto a
     neighbouring word as a phantom prose term. A literal left with no
-    whitespace after that replacement is an identifier-shaped value — a UID,
-    a key, a path — not prose, and contributes nothing.
+    whitespace after that replacement is an identifier-shaped value: a UID,
+    a key, or a path. It is not prose, and contributes nothing.
     """
     all_fragments: list[str] = []
     for each_match in STRING_LITERAL_CONTENT_PATTERN.finditer(line_text):
@@ -413,9 +417,7 @@ def _word_is_identifier_vocabulary(
         return True
     if prose_word.endswith("es") and prose_word[:-2] in all_identifier_tokens:
         return True
-    if prose_word.endswith("ies") and prose_word[:-3] + "y" in all_identifier_tokens:
-        return True
-    return False
+    return prose_word.endswith("ies") and prose_word[:-3] + "y" in all_identifier_tokens
 
 
 def _near_miss_identifier(
@@ -525,22 +527,8 @@ def _findings_for_line(
     return all_findings
 
 
-def sweep_diff(
-    diff_text: str,
-    all_preexisting_identifier_tuples: frozenset[IdentifierTuple] = frozenset(),
-) -> list[str]:
-    """Return every terminology near-miss finding for a unified diff.
-
-    Args:
-        diff_text: The unified-diff text to sweep.
-        all_preexisting_identifier_tuples: Token tuples of added-line identifiers
-            the base tree already names. A pre-existing identifier is not one
-            the diff introduces, so no prose is flagged against it. Its
-            tokens still count as code vocabulary.
-
-    Returns:
-        One finding string per near-miss term on an added prose line.
-    """
+def _find_terminology_near_misses(
+    diff_text: str, all_preexisting_identifier_tuples: frozenset[IdentifierTuple]) -> list[str]:
     all_added_lines = _parse_added_lines(diff_text)
     all_identifier_tuples = _collect_introduced_identifiers(all_added_lines)
     all_identifier_tokens = frozenset(
@@ -571,6 +559,27 @@ def sweep_diff(
     return all_findings
 
 
+def sweep_diff(
+    diff_text: str,
+    all_preexisting_identifier_tuples: frozenset[IdentifierTuple] = frozenset(),
+) -> list[str]:
+    """Return every terminology near-miss finding for a unified diff.
+
+    Args:
+        diff_text: The unified-diff text to sweep.
+        all_preexisting_identifier_tuples: Token tuples of added-line identifiers
+            the base tree already names. A pre-existing identifier is not one
+            the diff introduces, so no prose is flagged against it. Its
+            tokens still count as code vocabulary.
+
+    Returns:
+        One finding string per near-miss term on an added prose line.
+    """
+    return _find_terminology_near_misses(
+        diff_text, all_preexisting_identifier_tuples
+    )
+
+
 def repository_environment() -> dict[str, str]:
     """Return the process environment with every GIT_ variable removed.
 
@@ -619,8 +628,8 @@ def _base_tree_names(
 
     Each name is looked up as a whole word in the base revision's tree. A
     repository with no commits yet, or a lookup that git cannot run, reports
-    the name as absent, so the sweep then treats it as newly introduced —
-    the behaviour the sweep has with no base-tree check at all.
+    the name as absent, so the sweep then treats it as newly introduced.
+    That is the behaviour the sweep has with no base-tree check at all.
 
     Args:
         repository_root: The repository root the lookups run in.
@@ -652,11 +661,90 @@ def _base_tree_names(
     return frozenset(all_present_names)
 
 
+def _run_strict_git(
+    repository_root: Path, all_arguments: Sequence[str]
+) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(
+            list(all_arguments),
+            cwd=str(repository_root),
+            capture_output=True,
+            text=True,
+            encoding=GIT_TEXT_ENCODING,
+            errors=GIT_DECODE_ERRORS,
+            timeout=GIT_DIFF_SUBPROCESS_TIMEOUT_SECONDS,
+            check=False,
+            env=repository_environment(),
+        )
+    except (subprocess.TimeoutExpired, OSError) as e:
+        raise RuntimeError(str(e)) from e
+
+
+def _raise_for_git_failure(
+    git_process: subprocess.CompletedProcess[str], operation: str
+) -> None:
+    if git_process.returncode == 0:
+        return
+    details = git_process.stderr.strip() or git_process.stdout.strip()
+    raise RuntimeError(
+        GIT_OPERATION_FAILURE_TEMPLATE.format(
+            operation=operation,
+            details=details or GIT_FAILURE_WITHOUT_DETAILS,
+        )
+    )
+
+
+def _strict_base_tree_names(
+    repository_root: Path, all_names: frozenset[str]
+) -> frozenset[str]:
+    all_present_names: set[str] = set()
+    for each_name in sorted(all_names):
+        all_arguments = (
+            *ALL_GIT_GREP_BASE_TREE_COMMAND_PREFIX,
+            each_name,
+            GIT_BASE_TREE_REVISION,
+        )
+        grep_process = _run_strict_git(repository_root, all_arguments)
+        if grep_process.returncode == 0:
+            all_present_names.add(each_name)
+            continue
+        if grep_process.returncode == GIT_NO_MATCH_EXIT_CODE:
+            continue
+        operation = GIT_GREP_OPERATION_TEMPLATE.format(identifier=each_name)
+        _raise_for_git_failure(grep_process, operation)
+    return frozenset(all_present_names)
+
+
+def strict_staged_terminology_findings(repository_root: Path) -> list[str]:
+    """Return near-miss findings for the staged diff.
+
+    Args:
+        repository_root: The repository root the staged diff is read from.
+
+    Returns:
+        One finding string per near-miss term on a staged prose line.
+
+    Raises:
+        RuntimeError: Git could not read the staged diff or look up an
+            identifier in HEAD.
+    """
+    diff_process = _run_strict_git(
+        repository_root, ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND
+    )
+    _raise_for_git_failure(diff_process, GIT_DIFF_OPERATION)
+    all_added_names = _identifier_names_on_added_code_lines(diff_process.stdout)
+    preexisting_tuples = frozenset(
+        _identifier_token_tuple(each_name)
+        for each_name in _strict_base_tree_names(repository_root, all_added_names)
+    )
+    return _find_terminology_near_misses(diff_process.stdout, preexisting_tuples)
+
+
 def staged_terminology_findings(repository_root: Path) -> list[str]:
     """Return terminology near-miss findings for a repository's staged diff.
 
     An identifier the base tree already names is not one the staged diff
-    introduces, so no prose is flagged against it — only genuinely new
+    introduces, so no prose is flagged against it. Only genuinely new
     identifiers are swept.
 
     Args:
@@ -684,7 +772,7 @@ def staged_terminology_findings(repository_root: Path) -> list[str]:
         _identifier_token_tuple(each_name)
         for each_name in _base_tree_names(repository_root, all_added_names)
     )
-    return sweep_diff(diff_process.stdout, preexisting_tuples)
+    return _find_terminology_near_misses(diff_process.stdout, preexisting_tuples)
 
 
 def _read_diff_text(diff_file_path: str | None) -> str:

package/_shared/pr-loop/scripts/tests/test_terminology_sweep.py

@@ -2,6 +2,7 @@
 
 import importlib.util
 import subprocess
+import sys
 from pathlib import Path
 from types import ModuleType
 
@@ -10,17 +11,26 @@ import pytest
 
 def _load_sweep_module() -> ModuleType:
     module_path = Path(__file__).parent.parent / "terminology_sweep.py"
+    module_directory = str(module_path.parent)
+    should_remove_module_directory = module_directory not in sys.path
+    if should_remove_module_directory:
+        sys.path.insert(0, module_directory)
     spec = importlib.util.spec_from_file_location("terminology_sweep", module_path)
     assert spec is not None
     assert spec.loader is not None
     module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
+    try:
+        spec.loader.exec_module(module)
+    finally:
+        if should_remove_module_directory:
+            sys.path.remove(module_directory)
     return module
 
 
 sweep_module = _load_sweep_module()
 sweep_diff = sweep_module.sweep_diff
 staged_terminology_findings = sweep_module.staged_terminology_findings
+strict_staged_terminology_findings = sweep_module.strict_staged_terminology_findings
 main = sweep_module.main
 parse_added_lines = sweep_module._parse_added_lines
 
@@ -282,6 +292,8 @@ def test_staged_terminology_findings_flags_staged_prose(tmp_path: Path) -> None:
         env=_hermetic_git_environment(),
     )
     findings = staged_terminology_findings(tmp_path)
+    with pytest.raises(RuntimeError, match="git grep"):
+        strict_staged_terminology_findings(tmp_path)
     assert any("premium-request" in each_finding for each_finding in findings)
 
 

package/bin/cde.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const lintScriptPath = path.join(packageRoot, "scripts", "cde_lint.py");
+const posixSignalStatusOffset = 128;
+const lintCommandName = "lint";
+const pythonOptionName = "--python";
+const pythonEnvironmentName = "CDE_PYTHON";
+
+
+export function createHelpText() {
+    return [
+        "Usage: cde lint [options]",
+        "",
+        "Run the policy linter. Source modes are mutually exclusive:",
+        "  --files PATH [PATH ...]  Current worktree files",
+        "  --staged                 Staged index content",
+        "  --base REVISION          Changes from a base revision",
+        "  --repository             Tracked worktree files",
+        "  --text-as PATH           One editor buffer from standard input",
+        "",
+        "Report formats: --format text|json|editor",
+        "",
+        "Launcher options:",
+        "  --python <command>       Python interpreter override",
+        "  Exit 0 clean, 1 diagnostics, 2 invalid input or start failure, 3 failed rule",
+        "",
+        "Python may also be selected with CDE_PYTHON.",
+    ].join("\n");
+}
+
+
+export function pythonInterpreterNames(platformName = process.platform) {
+    if (platformName === "win32") return ["py", "python"];
+    return ["python3", "python"];
+}
+
+
+export function findPython(
+    commandNames = pythonInterpreterNames(),
+    canRun = (commandName) => spawnSync(commandName, ["--version"], { stdio: "ignore", shell: false }).status === 0,
+) {
+    for (const eachCommand of commandNames) {
+        if (canRun(eachCommand)) return eachCommand;
+    }
+    return undefined;
+}
+
+
+export function buildLintCommand(interpreter, forwardedArguments) {
+    return {
+        executable: interpreter,
+        arguments: [lintScriptPath, ...forwardedArguments],
+    };
+}
+
+
+function takePythonOverride(allArguments) {
+    const remainingArguments = [];
+    let interpreterOverride;
+    for (let index = 0; index < allArguments.length; index += 1) {
+        if (allArguments[index] === pythonOptionName) {
+            const nextArgument = allArguments[index + 1];
+            if (nextArgument === undefined || nextArgument.startsWith("--")) {
+                return { error: "--python requires an interpreter command" };
+            }
+            interpreterOverride = nextArgument;
+            index += 1;
+            continue;
+        }
+        remainingArguments.push(allArguments[index]);
+    }
+    return { interpreterOverride, remainingArguments, error: undefined };
+}
+
+
+function attachSignalForwarding(childProcess, processEmitter) {
+    const allSignals = ["SIGINT", "SIGTERM"];
+    if (process.platform !== "win32") {
+        allSignals.push("SIGHUP");
+    }
+    const listenerBySignal = [];
+    for (const eachSignal of allSignals) {
+        const listener = () => {
+            try {
+                childProcess.kill(eachSignal);
+            } catch {
+                return;
+            }
+        };
+        processEmitter.on(eachSignal, listener);
+        listenerBySignal.push([eachSignal, listener]);
+    }
+    return () => {
+        for (const [eachSignal, listener] of listenerBySignal) {
+            processEmitter.off(eachSignal, listener);
+        }
+    };
+}
+
+
+function statusCodeForSignal(signalName) {
+    const signalNumber = osConstants.signals?.[signalName];
+    if (signalNumber === undefined) return 1;
+    return posixSignalStatusOffset + signalNumber;
+}
+
+
+export function runLintCommand(command, dependencies = {}) {
+    const runChild = dependencies.runChild ?? spawn;
+    const processEmitter = dependencies.processEmitter ?? process;
+    return new Promise((resolve) => {
+        let childProcess;
+        try {
+            childProcess = runChild(command.executable, command.arguments, {
+                stdio: "inherit",
+                shell: false,
+                windowsHide: true,
+            });
+        } catch {
+            processEmitter.stderr.write("Unable to start the policy linter.\n");
+            resolve(2);
+            return;
+        }
+        const detachSignals = attachSignalForwarding(childProcess, processEmitter);
+        childProcess.on("error", () => {
+            detachSignals();
+            processEmitter.stderr.write("Unable to start the policy linter.\n");
+            resolve(2);
+        });
+        childProcess.on("close", (exitCode, signalName) => {
+            detachSignals();
+            if (exitCode !== null) {
+                resolve(exitCode);
+                return;
+            }
+            resolve(statusCodeForSignal(signalName));
+        });
+    });
+}
+
+
+export async function main(argumentsList = process.argv.slice(2), dependencies = {}) {
+    if (argumentsList.length === 0 || argumentsList.includes("--help") || argumentsList.includes("-h")) {
+        process.stdout.write(`${createHelpText()}\n`);
+        return 0;
+    }
+    if (argumentsList[0] !== lintCommandName) {
+        process.stderr.write(`${createHelpText()}\n`);
+        return 2;
+    }
+    const { interpreterOverride, remainingArguments, error } = takePythonOverride(argumentsList.slice(1));
+    if (error) {
+        process.stderr.write(`${error}\n`);
+        return 2;
+    }
+    const resolvePython = dependencies.findPython ?? findPython;
+    const interpreter = interpreterOverride ?? process.env[pythonEnvironmentName] ?? await resolvePython();
+    if (!interpreter) {
+        process.stderr.write("No usable Python interpreter found. Use --python or CDE_PYTHON.\n");
+        return 2;
+    }
+    const command = buildLintCommand(interpreter, remainingArguments);
+    const runCommand = dependencies.runCommand ?? runLintCommand;
+    return await runCommand(command, dependencies);
+}
+
+
+const isLaunchedDirectly = process.argv[1] !== undefined
+    && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isLaunchedDirectly) process.exitCode = await main();