claude-dev-env 2.18.0 → 2.19.0

package/bin/install.test.mjs

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import {
     mkdtempSync,
     rmSync,
@@ -27,6 +27,7 @@ import {
     pythonCandidatesForPlatform,
     isWindowsStorePythonStub,
     interpreterCommandFromPath,
+    commandArgumentFromPath,
     invokedAsEntryPoint,
     managedHookScriptRelativePaths,
     managedHookScriptRelativePathsFromSourceRoots,
@@ -504,7 +505,9 @@ test('mergeHooksIntoSettings inserts dollar characters in plugin root and interp
     const rewrittenCommand = settings.hooks.SessionStart[0].hooks[0].command;
     assert.equal(
         rewrittenCommand,
-        'C:/Users/$&evil$1/Python/python.exe C:/Users/$&evil$1/.claude/hooks/session/session_env_cleanup.py',
+        process.platform === 'win32'
+            ? 'C:/Users/$&evil$1/Python/python.exe "C:/Users/$&evil$1/.claude/hooks/session/session_env_cleanup.py"'
+            : "C:/Users/$&evil$1/Python/python.exe 'C:/Users/$&evil$1/.claude/hooks/session/session_env_cleanup.py'",
     );
     assert.equal(rewrittenCommand.includes('${CLAUDE_PLUGIN_ROOT}'), false);
 });
@@ -530,6 +533,191 @@ test('mergeHooksIntoSettings substitutes a quoted absolute interpreter path for
 });
 
 
+test('mergeHooksIntoSettings quotes standalone plugin-root hook paths and preserves existing quotes', () => {
+    const hooksConfig = {
+        hooks: {
+            PreToolUse: [{
+                matcher: 'Write|Edit|MultiEdit',
+                hooks: [
+                    { type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py' },
+                    { type: 'command', command: 'python3 "${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pre_tool_use_dispatcher.py"' },
+                    { type: 'command', command: 'python3 -c "import sys; sys.path.insert(0, r\'${CLAUDE_PLUGIN_ROOT}/hooks\')"' },
+                    { type: 'command', command: 'python3 -c "import sys; sys.path.insert(0, r\"${CLAUDE_PLUGIN_ROOT}/hooks\")"' },
+                    { type: 'command', command: "python3 -c \"print('${CLAUDE_PLUGIN_ROOT}/hooks/foo.py')\"" },
+                ],
+            }],
+        },
+    };
+    const settings = {};
+
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Program Files/Claude/.claude', 'python3');
+
+    assert.deepEqual(
+        settings.hooks.PreToolUse[0].hooks.map(eachHook => eachHook.command),
+        [
+            process.platform === 'win32'
+                ? 'python3 "C:/Program Files/Claude/.claude/hooks/blocking/pre_tool_use_dispatcher.py"'
+                : "python3 'C:/Program Files/Claude/.claude/hooks/blocking/pre_tool_use_dispatcher.py'",
+            process.platform === 'win32'
+                ? 'python3 "C:/Program Files/Claude/.claude/hooks/blocking/pre_tool_use_dispatcher.py"'
+                : "python3 'C:/Program Files/Claude/.claude/hooks/blocking/pre_tool_use_dispatcher.py'",
+            "python3 -c \"import sys; sys.path.insert(0, (__import__('base64').b64decode('QzovUHJvZ3JhbSBGaWxlcy9DbGF1ZGUvLmNsYXVkZS9ob29rcw==').decode(), '__claude_dev_env_managed_hooks__')[0])\"",
+            "python3 -c \"import sys; sys.path.insert(0, (__import__('base64').b64decode('QzovUHJvZ3JhbSBGaWxlcy9DbGF1ZGUvLmNsYXVkZS9ob29rcw==').decode(), '__claude_dev_env_managed_hooks__')[0])\"",
+            "python3 -c \"print('C:/Program Files/Claude/.claude/hooks/foo.py')\"",
+        ],
+    );
+});
+
+
+test('mergeHooksIntoSettings embeds a decodable inline plugin-root path', () => {
+    const hooksConfig = {
+        hooks: {
+            SessionStart: [{
+                matcher: '',
+                hooks: [{
+                    type: 'command',
+                    command: 'python3 -c "import sys; sys.path.insert(0, r\'${CLAUDE_PLUGIN_ROOT}/hooks\'); print(sys.path[0])"',
+                }],
+            }],
+        },
+    };
+    const settings = {};
+    const pluginRootDirectory = 'C:/Program Files/Claude/.claude';
+
+    mergeHooksIntoSettings(settings, hooksConfig, pluginRootDirectory, 'python3');
+
+    const rewrittenCommand = settings.hooks.SessionStart[0].hooks[0].command;
+    const pythonCommand = process.platform === 'win32' ? 'python' : 'python3';
+    const inlineRun = spawnSync(rewrittenCommand.replace(/^python3\b/, pythonCommand), {
+        encoding: 'utf8',
+        shell: process.platform === 'win32' ? true : '/bin/sh',
+        timeout: 30000,
+    });
+    assert.equal(inlineRun.status, 0, inlineRun.stderr);
+    assert.equal(inlineRun.stdout.trim(), `${pluginRootDirectory}/hooks`);
+    assert.equal(rewrittenCommand.includes("r'${CLAUDE_PLUGIN_ROOT}/hooks'"), false);
+});
+
+
+test('commandArgumentFromPath returns raw shell-safe paths', () => {
+    assert.equal(
+        commandArgumentFromPath('/opt/claude/hooks/pre_tool_use_dispatcher.py', 'linux'),
+        '/opt/claude/hooks/pre_tool_use_dispatcher.py',
+    );
+    assert.equal(
+        commandArgumentFromPath('C:\\Python313\\python.exe', 'win32'),
+        'C:/Python313/python.exe',
+    );
+});
+
+
+test('commandArgumentFromPath quotes POSIX shell metacharacters', () => {
+    assert.equal(
+        commandArgumentFromPath("/opt/Claude's $hooks `pre_tool_use_dispatcher`.py", 'linux'),
+        "'/opt/Claude'\\''s $hooks `pre_tool_use_dispatcher`.py'",
+    );
+});
+
+
+test('commandArgumentFromPath quotes Windows percent and shell metacharacters', () => {
+    assert.equal(
+        commandArgumentFromPath('C:\\Program Files\\%PATH% & (x) ! ^.py', 'win32'),
+        '"C:/Program Files/"^%"PATH"^%" & (x) ! ^.py"',
+    );
+    assert.equal(
+        commandArgumentFromPath('C:\\safe\\%PATH%.py', 'win32'),
+        '"C:/safe/"^%"PATH"^%".py"',
+    );
+});
+
+
+test('commandArgumentFromPath launches a script from a metacharacter path', () => {
+    const temporaryDirectory = mkdtempSync(join(tmpdir(), 'cdev command & (path)!-'));
+    const isWindows = process.platform === 'win32';
+    const scriptPath = join(
+        temporaryDirectory,
+        isWindows ? 'launcher script %PATH% & (x) !.py' : "launcher script & (x) '$'.py",
+    );
+    try {
+        writeFileSync(scriptPath, 'print("launched")\n');
+        const pythonCommand = isWindows ? 'python' : 'python3';
+        const shellCommand = `${pythonCommand} ${commandArgumentFromPath(scriptPath, process.platform)}`;
+        const launcherRun = spawnSync(shellCommand, {
+            encoding: 'utf8',
+            shell: isWindows ? true : '/bin/sh',
+            timeout: 30000,
+        });
+        assert.equal(launcherRun.error, undefined);
+        assert.equal(launcherRun.signal, null);
+        assert.equal(launcherRun.status, 0, launcherRun.stderr);
+        assert.equal(launcherRun.stdout.trim(), 'launched');
+    } finally {
+        rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+});
+
+
+test('commandArgumentFromPath launches a no-space percent path', () => {
+    const temporaryDirectory = mkdtempSync(join(tmpdir(), 'cdev-command-launch-'));
+    const isWindows = process.platform === 'win32';
+    const scriptName = isWindows ? 'launcher%PATH%.py' : 'launcher.py';
+    const scriptPath = join(temporaryDirectory, scriptName);
+    try {
+        writeFileSync(scriptPath, 'print("launched")\n');
+        const pythonCommand = isWindows ? 'python' : 'python3';
+        const shellCommand = `${pythonCommand} ${commandArgumentFromPath(scriptPath, process.platform)}`;
+        const launcherRun = spawnSync(shellCommand, {
+            encoding: 'utf8',
+            shell: isWindows ? true : '/bin/sh',
+            timeout: 30000,
+        });
+        assert.equal(launcherRun.error, undefined);
+        assert.equal(launcherRun.signal, null);
+        assert.equal(launcherRun.status, 0, launcherRun.stderr);
+        assert.equal(launcherRun.stdout.trim(), 'launched');
+    } finally {
+        rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+});
+
+
+test('mergeHooksIntoSettings matches full standalone arguments at boundaries', () => {
+    const hooksConfig = {
+        hooks: {
+            PreToolUse: [{
+                matcher: 'Write',
+                hooks: [
+                    { type: 'command', command: 'python3 prefix${CLAUDE_PLUGIN_ROOT}/hooks/a.py' },
+                    { type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/a.py.bak' },
+                    { type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/a.py' },
+                    { type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/a.py; next' },
+                    { type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/a.py& next' },
+                    { type: 'command', command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/a.py| next' },
+                ],
+            }],
+        },
+    };
+    const settings = {};
+
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Program Files/Claude/.claude', 'python3');
+
+    const expectedQuotedHookPath = process.platform === 'win32'
+        ? '"C:/Program Files/Claude/.claude/hooks/a.py"'
+        : "'C:/Program Files/Claude/.claude/hooks/a.py'";
+    assert.deepEqual(
+        settings.hooks.PreToolUse[0].hooks.map(eachHook => eachHook.command),
+        [
+            'python3 prefixC:/Program Files/Claude/.claude/hooks/a.py',
+            'python3 C:/Program Files/Claude/.claude/hooks/a.py.bak',
+            `python3 ${expectedQuotedHookPath}`,
+            `python3 ${expectedQuotedHookPath}; next`,
+            `python3 ${expectedQuotedHookPath}& next`,
+            `python3 ${expectedQuotedHookPath}| next`,
+        ],
+    );
+});
+
+
 test('mergeHooksIntoSettings prunes a prior py -3 managed hook when reinstalling with an absolute interpreter path', () => {
     const hooksConfig = {
         hooks: {
@@ -687,6 +875,12 @@ test('commandReferencesManagedHook matches the rewritten inline validators-runne
     const rewrittenInlineCommand =
         "py -3 -c \"import sys; sys.path.insert(0, r'C:/Users/example/.claude/hooks'); from validators.run_all_validators import main; sys.exit(main())\"";
     assert.ok(commandReferencesManagedHook(rewrittenInlineCommand, managedPaths));
+    const base64InlineCommand =
+        "py -3 -c \"import sys; sys.path.insert(0, (__import__('base64').b64decode('QzovVXNlcnMvZXhhbXBsZS8uY2xhdWRlL2hvb2tz').decode(), '__claude_dev_env_managed_hooks__')[0]); from validators.run_all_validators import main; sys.exit(main())\"";
+    assert.ok(commandReferencesManagedHook(base64InlineCommand, managedPaths));
+    const unmarkedBase64InlineCommand =
+        "py -3 -c \"import sys; sys.path.insert(0, __import__('base64').b64decode('QzovVXNlcnMvZXhhbXBsZS8uY2xhdWRlL2hvb2tz').decode()); from validators.run_all_validators import main; sys.exit(main())\"";
+    assert.equal(commandReferencesManagedHook(unmarkedBase64InlineCommand, managedPaths), false);
 });
 
 
@@ -695,6 +889,12 @@ test('commandReferencesManagedHook leaves an unmanaged inline -c command that im
     const userInlineCommand =
         "python -c \"import sys; sys.path.insert(0, r'/home/me/tools'); from my_tools.runner import main; sys.exit(main())\"";
     assert.equal(commandReferencesManagedHook(userInlineCommand, managedPaths), false);
+    const similarlyNamedUserInlineCommand =
+        "python -c \"import sys; sys.path.insert(0, r'/home/me/tools'); from mypkg.run_all_validators import main; sys.exit(main())\"";
+    assert.equal(commandReferencesManagedHook(similarlyNamedUserInlineCommand, managedPaths), false);
+    const userPathWithManagedImport =
+        "python -c \"import sys; sys.path.insert(0, r'/home/me/tools'); from validators.run_all_validators import main; sys.exit(main())\"";
+    assert.equal(commandReferencesManagedHook(userPathWithManagedImport, managedPaths), false);
 });
 
 

package/docs/CODE_RULES.md

@@ -44,6 +44,10 @@ Before writing ANY constant: search `config/` for the exact value → semantic m
 
 Full words only (`context`, not `ctx`). Exceptions: `i`/`j`/`k` in loops, `e` for exception. Naming patterns: loop vars `each_*`; booleans `is_/has_/should_/can_/was_/did_`; collections `all_*`; maps `X_by_Y`; preposition params (`from_path=`, `to=`, `into=`). Banned names: `result`, `data`, `output`, `response`, `value`, `item`, `temp`. Banned prefixes: `handle`, `process`, `manage`, `do`. Name a component for what it IS — `Overlay`, `Validator`, `InvoicePreview`.
 
+### Public compatibility definitions
+
+A public function may use the exact inline marker `# pragma: no-banned-noun` on its `def` line. The banned-noun check permits the function name and parameters on that definition. Body local bindings, other definitions, and similar names remain checked.
+
 ---
 
 ## 6. COMPLETE TYPE HINTS

package/hooks/advisory/migration_safety_advisor.py

@@ -26,21 +26,21 @@ def main() -> None:
 
     if found_unsafe:
         operations = ", ".join(found_unsafe)
-        print(
-            json.dumps(
-                {
-                    "hookSpecificOutput": {
-                        "hookEventName": "PreToolUse",
-                        "permissionDecision": "ask",
-                        "permissionDecisionReason": (
-                            f"MIGRATION SAFETY: Contains {operations}. "
-                            "Post-launch, model changes MUST be backwards-compatible. "
-                            "Verify this won't break running instances during deployment."
-                        ),
-                    }
-                }
-            )
+        advisory_message = (
+            f"MIGRATION SAFETY: Contains {operations}. "
+            "Post-launch, model changes MUST be backwards-compatible. "
+            "Verify this won't break running instances during deployment."
         )
+        advisory_payload = {
+            "systemMessage": advisory_message,
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+                "permissionDecisionReason": advisory_message,
+                "additionalContext": advisory_message,
+            },
+        }
+        print(json.dumps(advisory_payload))
 
     sys.exit(0)
 

package/hooks/advisory/test_migration_safety_advisor.py

@@ -0,0 +1,120 @@
+"""Behavior tests for migration_safety_advisor through its production entry paths."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+
+_ADVISORY_DIRECTORY = Path(__file__).resolve().parent
+_HOOKS_DIRECTORY = _ADVISORY_DIRECTORY.parent
+_ADVISOR_SCRIPT = _ADVISORY_DIRECTORY / "migration_safety_advisor.py"
+_DISPATCHER_SCRIPT = _HOOKS_DIRECTORY / "blocking" / "pre_tool_use_dispatcher.py"
+
+
+def _run_hook(script_path: Path, payload: dict[str, object]) -> dict[str, object] | None:
+    completed_process = subprocess.run(
+        [sys.executable, str(script_path)],
+        check=False,
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+    )
+    assert completed_process.returncode == 0
+    if not completed_process.stdout.strip():
+        return None
+    parsed_payload = json.loads(completed_process.stdout)
+    assert isinstance(parsed_payload, dict)
+    return parsed_payload
+
+
+def _build_edit_payload(file_path: Path, new_string: str) -> dict[str, object]:
+    return {
+        "tool_name": "Edit",
+        "tool_input": {
+            "file_path": str(file_path),
+            "old_string": "operations = []",
+            "new_string": new_string,
+        },
+    }
+
+
+def _build_control_payload(tool_name: str, file_path: Path, content: str) -> dict[str, object]:
+    if tool_name == "Write":
+        tool_input: dict[str, object] = {
+            "file_path": str(file_path),
+            "content": content,
+        }
+    else:
+        tool_input = {
+            "file_path": str(file_path),
+            "edits": [{"old_string": "operations = []", "new_string": content}],
+        }
+    return {"tool_name": tool_name, "tool_input": tool_input}
+
+
+def _prepare_fresh_test_pair(migration_path: Path) -> None:
+    migration_path.parent.mkdir(parents=True)
+    migration_path.write_text("operations = []\n", encoding="utf-8")
+    test_path = migration_path.with_name(f"test_{migration_path.stem}.py")
+    test_path.write_text("def test_migration_contract():\n    assert True\n", encoding="utf-8")
+
+
+def _permission_fields(parsed_payload: dict[str, object]) -> dict[str, object]:
+    hook_specific = parsed_payload.get("hookSpecificOutput", {})
+    assert isinstance(hook_specific, dict)
+    return hook_specific
+
+
+def _text_field(field_by_key: dict[str, object], field_name: str) -> str:
+    field_value = field_by_key.get(field_name)
+    assert isinstance(field_value, str)
+    return field_value
+
+
+def test_standalone_advisor_warns_for_unsafe_migration_edit(tmp_path: Path) -> None:
+    migration_path = tmp_path / "billing" / "migrations" / "0002_remove_name.py"
+    payload = _build_edit_payload(migration_path, 'operations = [migrations.RemoveField("name")]')
+
+    advisory_payload = _run_hook(_ADVISOR_SCRIPT, payload)
+    assert advisory_payload is not None
+    permission_fields = _permission_fields(advisory_payload)
+
+    assert permission_fields["permissionDecision"] == "allow"
+    assert "RemoveField" in _text_field(permission_fields, "additionalContext")
+    assert "MIGRATION SAFETY" in _text_field(advisory_payload, "systemMessage")
+
+
+def test_dispatcher_surfaces_migration_warning_for_edit(tmp_path: Path) -> None:
+    migration_path = tmp_path / "billing" / "migrations" / "0002_remove_name.py"
+    _prepare_fresh_test_pair(migration_path)
+    payload = _build_edit_payload(migration_path, 'operations = [migrations.RemoveField("name")]')
+
+    dispatched_payload = _run_hook(_DISPATCHER_SCRIPT, payload)
+    assert dispatched_payload is not None
+    permission_fields = _permission_fields(dispatched_payload)
+
+    assert permission_fields["permissionDecision"] == "allow"
+    assert "RemoveField" in _text_field(permission_fields, "additionalContext")
+    assert "MIGRATION SAFETY" in _text_field(dispatched_payload, "systemMessage")
+
+
+@pytest.mark.parametrize("tool_name", ("Write", "MultiEdit"))
+def test_dispatcher_keeps_migration_advisor_edit_only(tmp_path: Path, tool_name: str) -> None:
+    migration_path = tmp_path / "billing" / "migrations" / "0002_remove_name.py"
+    _prepare_fresh_test_pair(migration_path)
+    payload = _build_control_payload(
+        tool_name,
+        migration_path,
+        'operations = [migrations.RemoveField("name")]',
+    )
+
+    dispatched_payload = _run_hook(_DISPATCHER_SCRIPT, payload)
+    serialized_payload = json.dumps(dispatched_payload or {})
+
+    assert "MIGRATION SAFETY" not in serialized_payload

package/hooks/atomic_file_writer.py

@@ -0,0 +1,81 @@
+"""Atomic text replacement for hook-state files."""
+
+import os
+import tempfile
+from pathlib import Path
+
+from hooks_constants.atomic_file_writer_constants import TEXT_WRITE_MODE
+
+
+def _remove_orphaned_temporary_files(
+    parent_directory: Path, temporary_prefix: str, temporary_suffix: str
+) -> None:
+    for each_temporary_path in parent_directory.glob(f"{temporary_prefix}*{temporary_suffix}"):
+        try:
+            each_temporary_path.unlink(missing_ok=True)
+        except OSError:
+            continue
+
+
+def _write_temporary_text(
+    parent_directory: Path,
+    serialized_text: str,
+    encoding: str,
+    temporary_prefix: str,
+    temporary_suffix: str,
+) -> Path:
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode=TEXT_WRITE_MODE,
+            encoding=encoding,
+            dir=parent_directory,
+            prefix=temporary_prefix,
+            suffix=temporary_suffix,
+            delete=False,
+        ) as writable_handle:
+            temporary_path = Path(writable_handle.name)
+            writable_handle.write(serialized_text)
+        return temporary_path
+    except (OSError, UnicodeError):
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+        raise
+
+
+def write_text_atomically(
+    target_path: Path,
+    serialized_text: str,
+    encoding: str,
+    temporary_prefix: str,
+    temporary_suffix: str,
+    should_reap_orphans: bool,
+) -> None:
+    """Replace one text file through a unique sibling temporary file.
+
+    Args:
+        target_path: The destination file path.
+        serialized_text: The complete replacement text.
+        encoding: The text encoding.
+        temporary_prefix: Prefix for sibling temporary files.
+        temporary_suffix: Suffix for sibling temporary files.
+        should_reap_orphans: Whether to remove same-pattern temporary files first.
+    """
+    parent_directory = target_path.parent
+    parent_directory.mkdir(parents=True, exist_ok=True)
+    if should_reap_orphans:
+        _remove_orphaned_temporary_files(parent_directory, temporary_prefix, temporary_suffix)
+    temporary_path = _write_temporary_text(
+        parent_directory,
+        serialized_text,
+        encoding,
+        temporary_prefix,
+        temporary_suffix,
+    )
+    try:
+        os.replace(temporary_path, target_path)
+    finally:
+        try:
+            temporary_path.unlink(missing_ok=True)
+        except OSError:
+            pass

package/hooks/blocking/AGENTS.md

@@ -95,7 +95,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
 | `send_user_file_open_locally_blocker.py` | PreToolUse (SendUserFile) | A desk-side file attach (`SendUserFile` with `status` not `proactive`); points to opening the file with its native Windows app |
-| `sensitive_file_protector.py` | PreToolUse (Write/Edit) | Writes to sensitive credential or config files |
+| `sensitive_file_protector.py` | PreToolUse (Write/Edit/MultiEdit) | Writes to sensitive credential or config files |
 | `session_edit_stage_gate.py` | PreToolUse (Bash) | A `git commit` that would drop files edited this session because they are tracked but left unstaged |
 | `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
 | `shell_substitution_blocker.py` | PreToolUse (Bash) | A command carrying `$(...)`, a live backtick, or `<(...)`/`>(...)` process substitution, which the allowlist matcher cannot descend into |
@@ -114,6 +114,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | File | Role |
 |---|---|
 | `_gh_body_arg_utils.py` | Parsing helpers for `gh_body_arg_blocker.py` |
+| `test_hook_subprocess_support.py` | Shared subprocess runner for blocking-hook behavior tests |
 
 ## Conventions
 

package/hooks/blocking/code_rules_banned_identifiers.py

@@ -1,7 +1,9 @@
 """Banned identifier, banned noun-word, and banned function-prefix naming checks."""
 
 import ast
+import io
 import sys
+import tokenize
 from pathlib import Path
 
 _blocking_directory = str(Path(__file__).resolve().parent)
@@ -30,6 +32,7 @@ from hooks_constants.banned_identifiers_constants import (  # noqa: E402
     ALL_BANNED_NOUN_WORDS,
     BANNED_IDENTIFIER_MESSAGE_SUFFIX,
     BANNED_IDENTIFIER_SKIP_ADVISORY,
+    BANNED_NOUN_COMPATIBILITY_COMMENT,
     BANNED_NOUN_WORD_MESSAGE_SUFFIX,
     CAMEL_CASE_WORD_PATTERN,
     MAX_BANNED_IDENTIFIER_ISSUES,
@@ -235,8 +238,31 @@ def _is_dunder_name(identifier: str) -> bool:
     return identifier.startswith("__") and identifier.endswith("__")
 
 
+def _collect_annotated_public_definition_lines(
+    content: str, parsed_tree: ast.AST
+) -> frozenset[int]:
+    all_annotation_lines: set[int] = set()
+    try:
+        for each_token in tokenize.generate_tokens(io.StringIO(content).readline):
+            if each_token.type != tokenize.COMMENT:
+                continue
+            if each_token.string.strip() == BANNED_NOUN_COMPATIBILITY_COMMENT:
+                all_annotation_lines.add(each_token.start[0])
+    except (IndentationError, SyntaxError, tokenize.TokenError):
+        return frozenset()
+
+    return frozenset(
+        each_node.lineno
+        for each_node in ast.walk(parsed_tree)
+        if isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and not each_node.name.startswith("_")
+        and each_node.lineno in all_annotation_lines
+    )
+
+
 def _collect_banned_noun_word_bindings(
     parsed_tree: ast.AST,
+    all_annotated_public_definition_lines: frozenset[int],
 ) -> list[tuple[str, int, int, str]]:
     """Yield ``(identifier, lineno, col_offset, banned_word)`` for each binding.
 
@@ -248,7 +274,14 @@ def _collect_banned_noun_word_bindings(
     flagged_bindings: list[tuple[str, int, int, str]] = []
     seen_keys: set[tuple[str, int, int]] = set()
 
-    def record(name: str, lineno: int, col_offset: int) -> None:
+    def record(
+        name: str,
+        lineno: int,
+        col_offset: int,
+        is_annotated_public_definition: bool = False,
+    ) -> None:
+        if is_annotated_public_definition:
+            return
         if name in ALL_BANNED_IDENTIFIERS:
             return
         if _is_dunder_name(name):
@@ -282,11 +315,24 @@ def _collect_banned_noun_word_bindings(
             for each_name_node in _collect_target_names(each_node.optional_vars):
                 record(each_name_node.id, each_name_node.lineno, each_name_node.col_offset)
         elif isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            record(each_node.name, each_node.lineno, each_node.col_offset)
+            is_annotated_public_definition = (
+                each_node.lineno in all_annotated_public_definition_lines
+            )
+            record(
+                each_node.name,
+                each_node.lineno,
+                each_node.col_offset,
+                is_annotated_public_definition,
+            )
             for each_arg in _collect_annotated_arguments(each_node):
                 if each_arg.arg in ALL_SELF_AND_CLS_PARAMETER_NAMES:
                     continue
-                record(each_arg.arg, each_arg.lineno, each_arg.col_offset)
+                record(
+                    each_arg.arg,
+                    each_arg.lineno,
+                    each_arg.col_offset,
+                    is_annotated_public_definition,
+                )
         elif isinstance(each_node, ast.ClassDef):
             record(each_node.name, each_node.lineno, each_node.col_offset)
         elif isinstance(each_node, (ast.Import, ast.ImportFrom)):
@@ -368,9 +414,14 @@ def check_banned_noun_word_boundary(
     except SyntaxError:
         return []
 
+    all_annotated_public_definition_lines = _collect_annotated_public_definition_lines(
+        content, parsed_tree
+    )
     single_line_span = 1
     all_violations_in_walk_order: list[tuple[range, str]] = []
-    for each_name, each_lineno, _, each_word in _collect_banned_noun_word_bindings(parsed_tree):
+    for each_name, each_lineno, _, each_word in _collect_banned_noun_word_bindings(
+        parsed_tree, all_annotated_public_definition_lines
+    ):
         span_range = range(each_lineno, each_lineno + single_line_span)
         span_fragment = BANNED_NOUN_SPAN_FRAGMENT_TEMPLATE.format(
             definition_line=each_lineno, line_span=single_line_span