claude-dev-env 8.72.2 → 8.73.0

package/scripts/context_budget_check.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Answer "is this context file thin enough?" and keep the over-budget list current.
+
+::
+
+    python context_budget_check.py path/to/SKILL.md     check files, prior = HEAD
+    python context_budget_check.py --hooks              measure the policy's hooks
+    python context_budget_check.py --write-baseline     rebuild the over-budget list
+
+Run it from inside the repository whose ``.claude/context-budget.json`` applies.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path, PurePosixPath
+from typing import TextIO
+
+from dev_env_scripts_constants.context_budget_check_constants import (
+    ALL_GIT_ROOT_ARGUMENTS,
+    ALL_LS_FILES_ARGUMENTS,
+    BASELINE_WRITTEN_MESSAGE,
+    CLEAN_MESSAGE,
+    COMMAND_DESCRIPTION,
+    FAILURE_EXIT_CODE,
+    HEAD_REVISION,
+    HOOK_REPORT_TEMPLATE,
+    HOOKS_FLAG,
+    HOOKS_HELP,
+    MARKDOWN_SUFFIX,
+    NO_BASELINE_TEXT,
+    NO_POLICY_MESSAGE,
+    PATHS_HELP,
+    POLICY_RELATIVE_PATH,
+    SUCCESS_EXIT_CODE,
+    UTF8_ENCODING,
+    WRITE_BASELINE_FLAG,
+    WRITE_BASELINE_HELP,
+)
+from policy_lint import adapters
+from policy_lint.model import ContentOrigin, Diagnostic, Document
+from policy_lint.selection_git import git_bytes_for, read_blob, split_nul_tokens
+
+_hooks_directory = str(Path(__file__).resolve().parents[1] / "hooks")
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from context_budget.baseline import build_baseline, policy_text_with_baseline
+from context_budget.hook_measure import (
+    HookMeasurementError,
+    hook_findings,
+    injected_character_count,
+    run_hook_command,
+)
+from context_budget.model import BudgetPolicy, ContextBudgetPolicyError
+from context_budget.policy_file import read_policy_file
+from context_budget.sections import context_kind_for_path
+from hooks_constants.context_budget_constants import BASELINE_FILES_KEY, BASELINE_HOOKS_KEY
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return the command's argument parser.
+
+    Returns:
+        The parser for paths, ``--hooks``, and ``--write-baseline``.
+    """
+    parser = argparse.ArgumentParser(description=COMMAND_DESCRIPTION)
+    parser.add_argument("paths", nargs="*", help=PATHS_HELP)
+    parser.add_argument(HOOKS_FLAG, action="store_true", help=HOOKS_HELP)
+    parser.add_argument(WRITE_BASELINE_FLAG, action="store_true", help=WRITE_BASELINE_HELP)
+    return parser
+
+
+def _repository_root(starting_directory: Path) -> Path:
+    root_bytes = git_bytes_for(starting_directory, ALL_GIT_ROOT_ARGUMENTS)
+    return Path(root_bytes.decode(UTF8_ENCODING).strip()).resolve()
+
+
+def _document_for(repository_root: Path, file_path: Path) -> Document:
+    relative_path = file_path.resolve().relative_to(repository_root).as_posix()
+    return Document(
+        PurePosixPath(relative_path),
+        file_path.read_text(encoding=UTF8_ENCODING),
+        read_blob(repository_root, HEAD_REVISION, relative_path),
+        None,
+        ContentOrigin.WORKTREE,
+    )
+
+
+def _diagnostics_for(repository_root: Path, file_path: Path) -> tuple[Diagnostic, ...]:
+    document = _document_for(repository_root, file_path)
+    if document.path.as_posix() == POLICY_RELATIVE_PATH:
+        return adapters.context_budget_policy_diagnostics(document, repository_root)
+    if document.path.suffix == MARKDOWN_SUFFIX:
+        return adapters.context_budget_diagnostics(document, repository_root)
+    return ()
+
+
+def _check_paths(repository_root: Path, all_paths: Sequence[str], stdout: TextIO) -> int:
+    """Check explicit files with each file's HEAD version as its prior state.
+
+    Args:
+        repository_root: Repository root holding the policy.
+        all_paths: Paths given on the command line.
+        stdout: Report stream.
+
+    Returns:
+        Zero when every file is within budget, else one.
+    """
+    all_messages = [
+        each_diagnostic.message
+        for each_path in all_paths
+        for each_diagnostic in _diagnostics_for(repository_root, Path(each_path))
+    ]
+    for each_message in all_messages:
+        stdout.write(each_message + "\n")
+    if all_messages:
+        return FAILURE_EXIT_CODE
+    stdout.write(CLEAN_MESSAGE.format(count=len(all_paths)) + "\n")
+    return SUCCESS_EXIT_CODE
+
+
+def _measure_hooks(policy: BudgetPolicy, repository_root: Path) -> dict[str, int]:
+    """Run every hook the policy lists and count the characters each injects.
+
+    Args:
+        policy: Budget policy listing the hooks.
+        repository_root: Directory each hook runs from.
+
+    Returns:
+        Injected characters by hook name.
+    """
+    return {
+        each_hook.name: injected_character_count(run_hook_command(each_hook, repository_root))
+        for each_hook in policy.all_hooks
+    }
+
+
+def _check_hooks(policy: BudgetPolicy, repository_root: Path, stdout: TextIO) -> int:
+    """Report each hook's injected characters and fail on any over budget.
+
+    Args:
+        policy: Budget policy listing the hooks.
+        repository_root: Directory each hook runs from.
+        stdout: Report stream.
+
+    Returns:
+        Zero when every hook is within budget, else one.
+    """
+    count_by_name = _measure_hooks(policy, repository_root)
+    all_messages: list[str] = []
+    for each_hook in policy.all_hooks:
+        count = count_by_name[each_hook.name]
+        baseline = policy.baseline_characters_by_hook_name.get(each_hook.name, NO_BASELINE_TEXT)
+        stdout.write(
+            HOOK_REPORT_TEMPLATE.format(
+                name=each_hook.name, count=count, limit=each_hook.char_limit, baseline=baseline
+            )
+            + "\n"
+        )
+        all_messages.extend(hook_findings(policy, each_hook, count))
+    for each_message in all_messages:
+        stdout.write(each_message + "\n")
+    return FAILURE_EXIT_CODE if all_messages else SUCCESS_EXIT_CODE
+
+
+def current_baseline(policy: BudgetPolicy, repository_root: Path) -> dict[str, dict]:
+    """Build the baseline the tracked tree and the policy's hooks need today.
+
+    Args:
+        policy: Current budget policy.
+        repository_root: Repository root holding the policy.
+
+    Returns:
+        The ``baseline`` object.
+    """
+    all_tracked_paths = split_nul_tokens(git_bytes_for(repository_root, ALL_LS_FILES_ARGUMENTS))
+    text_by_path = {
+        each_path: (repository_root / each_path).read_text(encoding=UTF8_ENCODING)
+        for each_path in all_tracked_paths
+        if context_kind_for_path(policy, each_path) is not None
+        and (repository_root / each_path).is_file()
+    }
+    return build_baseline(policy, text_by_path, _measure_hooks(policy, repository_root))
+
+
+def _write_baseline(policy: BudgetPolicy, repository_root: Path, stdout: TextIO) -> int:
+    """Rebuild the policy file's baseline from the tracked tree and its hooks.
+
+    Args:
+        policy: Current budget policy.
+        repository_root: Repository root holding the policy.
+        stdout: Report stream.
+
+    Returns:
+        Zero after the file is written.
+    """
+    baseline = current_baseline(policy, repository_root)
+    policy_path = repository_root / POLICY_RELATIVE_PATH
+    policy_text = policy_path.read_text(encoding=UTF8_ENCODING)
+    policy_path.write_text(policy_text_with_baseline(policy_text, baseline), encoding=UTF8_ENCODING)
+    file_count = len(baseline[BASELINE_FILES_KEY])
+    hook_count = len(baseline[BASELINE_HOOKS_KEY])
+    stdout.write(BASELINE_WRITTEN_MESSAGE.format(files=file_count, hooks=hook_count) + "\n")
+    return SUCCESS_EXIT_CODE
+
+
+def _run_action(namespace: argparse.Namespace, repository_root: Path, stdout: TextIO) -> int:
+    policy = read_policy_file(repository_root)
+    if policy is None:
+        stdout.write(NO_POLICY_MESSAGE + "\n")
+        return FAILURE_EXIT_CODE
+    if namespace.write_baseline:
+        return _write_baseline(policy, repository_root, stdout)
+    if namespace.hooks:
+        return _check_hooks(policy, repository_root, stdout)
+    return _check_paths(repository_root, namespace.paths, stdout)
+
+
+def main(all_arguments: Sequence[str], starting_directory: Path, stdout: TextIO) -> int:
+    """Run the command.
+
+    Args:
+        all_arguments: Command-line arguments.
+        starting_directory: Directory inside the repository to check.
+        stdout: Report stream.
+
+    Returns:
+        The exit code of the requested action.
+    """
+    namespace = build_parser().parse_args(list(all_arguments))
+    repository_root = _repository_root(starting_directory)
+    try:
+        return _run_action(namespace, repository_root, stdout)
+    except (ContextBudgetPolicyError, HookMeasurementError) as error:
+        stdout.write(str(error) + "\n")
+        return FAILURE_EXIT_CODE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:], Path.cwd(), sys.stdout))

package/scripts/dev_env_scripts_constants/context_budget_check_constants.py

@@ -0,0 +1,26 @@
+"""Constants for the context budget command."""
+
+from __future__ import annotations
+
+COMMAND_DESCRIPTION = (
+    "Check context files against .claude/context-budget.json, measure its hooks, "
+    "or rebuild its over-budget list from the current tree."
+)
+PATHS_HELP = "Context files to check; the prior state is each file's HEAD version."
+HOOKS_FLAG = "--hooks"
+HOOKS_HELP = "Run each hook the policy lists and hold it to its character budget."
+WRITE_BASELINE_FLAG = "--write-baseline"
+WRITE_BASELINE_HELP = "Rebuild the policy's baseline from the tracked tree and its hooks."
+HEAD_REVISION = "HEAD"
+ALL_LS_FILES_ARGUMENTS: tuple[str, ...] = ("ls-files", "-z")
+ALL_GIT_ROOT_ARGUMENTS: tuple[str, ...] = ("rev-parse", "--show-toplevel")
+POLICY_RELATIVE_PATH = ".claude/context-budget.json"
+MARKDOWN_SUFFIX = ".md"
+UTF8_ENCODING = "utf-8"
+NO_POLICY_MESSAGE = "context-budget: no " + POLICY_RELATIVE_PATH + " in this repository."
+CLEAN_MESSAGE = "context-budget: OK ({count} checked)"
+HOOK_REPORT_TEMPLATE = "{name}: {count} characters (limit {limit}, baseline {baseline})"
+BASELINE_WRITTEN_MESSAGE = "context-budget: baseline written ({files} files, {hooks} hooks)"
+NO_BASELINE_TEXT = "none"
+FAILURE_EXIT_CODE = 1
+SUCCESS_EXIT_CODE = 0

package/scripts/policy_lint/adapter_context_budget.py

@@ -0,0 +1,158 @@
+"""Hold changed agent context files and the over-budget list to the context budget.
+
+The budget core lives in ``hooks/context_budget``, shared with the write hook.
+The policy is ``.claude/context-budget.json`` at the repository root; a
+repository without one is not checked.
+
+::
+
+    context-budget         SKILL.md over its limit grew    -> finding
+    context-budget-policy  baseline entry raised           -> finding
+"""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+from types import ModuleType
+
+from .adapter_support import HookModuleLoader
+from .config import constants
+from .model import Diagnostic, Document, DocumentSet, Severity
+
+
+def accepts_context_markdown(document: Document) -> bool:
+    """Return whether the document is Markdown the kind table may select.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for Markdown documents.
+    """
+    return document.path.suffix.lower() in constants.ALL_MARKDOWN_SUFFIXES
+
+
+def accepts_context_budget_policy(document: Document) -> bool:
+    """Return whether the document is the repository's budget policy file.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for ``.claude/context-budget.json``.
+    """
+    return document.path.as_posix() == constants.CONTEXT_BUDGET_POLICY_PATH
+
+
+def _file_diagnostic(rule_id: str, message: str) -> Diagnostic:
+    return Diagnostic(rule_id, Severity.ERROR, message)
+
+
+def context_budget_diagnostics(
+    document: Document, repository_root: Path, load_module: HookModuleLoader
+) -> tuple[Diagnostic, ...]:
+    """Report the budget findings of one changed context file.
+
+    Args:
+        document: Current text and the prior text the ratchet compares.
+        repository_root: Repository root holding the policy file.
+        load_module: Hook module loader.
+
+    Returns:
+        One diagnostic per finding; empty without a readable policy file.
+    """
+    policy_file = load_module(constants.CONTEXT_BUDGET_POLICY_FILE_MODULE)
+    model = load_module(constants.CONTEXT_BUDGET_MODEL_MODULE)
+    try:
+        policy = policy_file.read_policy_file(repository_root)
+    except model.ContextBudgetPolicyError:
+        return ()
+    if policy is None:
+        return ()
+    findings = load_module(constants.CONTEXT_BUDGET_FINDINGS_MODULE)
+    all_findings = findings.file_findings(
+        policy, document.path.as_posix(), document.text, document.prior_text
+    )
+    return tuple(
+        _file_diagnostic(constants.CONTEXT_BUDGET_RULE_ID, each.message)
+        for each in all_findings
+    )
+
+
+def _prior_policy(prior_text: str | None, policy_file: ModuleType, model: ModuleType) -> object:
+    if prior_text is None:
+        return None
+    try:
+        return policy_file.parse_policy(prior_text)
+    except model.ContextBudgetPolicyError:
+        return None
+
+
+def _policy_messages(
+    document: Document, repository_root: Path, load_module: HookModuleLoader
+) -> list[str]:
+    policy_file = load_module(constants.CONTEXT_BUDGET_POLICY_FILE_MODULE)
+    model = load_module(constants.CONTEXT_BUDGET_MODEL_MODULE)
+    policy_path = document.path.as_posix()
+    try:
+        current_policy = policy_file.parse_policy(document.text)
+    except model.ContextBudgetPolicyError as error:
+        all_messages = [
+            constants.CONTEXT_BUDGET_UNREADABLE_MESSAGE.format(path=policy_path, error=error)
+        ]
+    else:
+        prior_policy = _prior_policy(document.prior_text, policy_file, model)
+        policy_changes = load_module(constants.CONTEXT_BUDGET_POLICY_CHANGES_MODULE)
+        all_messages = [
+            each.message
+            for each in policy_changes.policy_shrink_findings(
+                policy_path, prior_policy, current_policy, repository_root
+            )
+        ]
+    return all_messages
+
+
+def context_budget_policy_diagnostics(
+    document: Document, repository_root: Path, load_module: HookModuleLoader
+) -> tuple[Diagnostic, ...]:
+    """Report each change to the policy file that loosens the budget.
+
+    Args:
+        document: Current policy text and its prior text.
+        repository_root: Working tree that holds each hook's command script.
+        load_module: Hook module loader.
+
+    Returns:
+        One diagnostic per loosening change, or one for an unparseable file.
+    """
+    rule_id = constants.CONTEXT_BUDGET_POLICY_RULE_ID
+    all_messages = _policy_messages(document, repository_root, load_module)
+    return tuple(_file_diagnostic(rule_id, each) for each in all_messages)
+
+
+def context_budget_policy_change_set_diagnostics(
+    document_set: DocumentSet,
+) -> tuple[Diagnostic, ...]:
+    """Reject removal or movement of the policy path in a Git selection.
+
+    Args:
+        document_set: Changed documents and removed or renamed paths.
+
+    Returns:
+        One finding when the selection removes the policy path.
+    """
+    policy_path = PurePosixPath(constants.CONTEXT_BUDGET_POLICY_PATH)
+    removed_paths = set(document_set.deleted_paths)
+    removed_paths.update(
+        old_path for old_path, new_path in document_set.renamed_paths if old_path != new_path
+    )
+    if policy_path not in removed_paths:
+        return ()
+    return (
+        Diagnostic(
+            constants.CONTEXT_BUDGET_POLICY_RULE_ID,
+            Severity.ERROR,
+            constants.CONTEXT_BUDGET_POLICY_REMOVED_MESSAGE.format(path=policy_path),
+            check_id=constants.CONTEXT_BUDGET_POLICY_REMOVAL_RULE_ID,
+        ),
+    )

package/scripts/policy_lint/adapters.py

@@ -11,6 +11,7 @@ from shared_tree_paths import resolve_shared_scripts_directory
 from . import (
     adapter_callers,
     adapter_configuration,
+    adapter_context_budget,
     adapter_contrast_framing,
     adapter_detectors,
     adapter_pairing,
@@ -498,3 +499,75 @@ def retired_hook_prose_diagnostics(
     return adapter_retired_hook_prose.retired_hook_prose_diagnostics(
         document, repository_root
     )
+
+
+def accepts_context_markdown(document: Document) -> bool:
+    """Return whether the document is Markdown the context budget may select.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for Markdown documents.
+    """
+    return adapter_context_budget.accepts_context_markdown(document)
+
+
+def accepts_context_budget_policy(document: Document) -> bool:
+    """Return whether the document is the context budget policy file.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for ``.claude/context-budget.json``.
+    """
+    return adapter_context_budget.accepts_context_budget_policy(document)
+
+
+def context_budget_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Hold one changed context file to its kind limits and the over-budget list.
+
+    Args:
+        document: Current Markdown text and its prior text.
+        repository_root: Repository root holding the policy file.
+
+    Returns:
+        Context budget diagnostics.
+    """
+    return adapter_context_budget.context_budget_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def context_budget_policy_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Report a policy file change that loosens the context budget.
+
+    Args:
+        document: Current policy text and its prior text.
+        repository_root: Request repository root.
+
+    Returns:
+        Shrink-only diagnostics.
+    """
+    return adapter_context_budget.context_budget_policy_diagnostics(
+        document, repository_root, _hooks_module
+    )
+
+
+def context_budget_policy_change_set_diagnostics(
+    document_set: DocumentSet,
+) -> tuple[Diagnostic, ...]:
+    """Reject a Git selection that removes the context budget policy path.
+
+    Args:
+        document_set: Changed documents and removed or renamed paths.
+
+    Returns:
+        Policy removal diagnostics.
+    """
+    return adapter_context_budget.context_budget_policy_change_set_diagnostics(document_set)

package/scripts/policy_lint/config/constants.py

@@ -77,7 +77,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)
-ALL_TEST_FILE_SUFFIXES = ("_test.py",)
+ALL_TEST_FILE_SUFFIXES = ("_test.py", "_test_support.py")
 POLICY_LINT_DIRECTORY_NAME = "policy_lint"
 POLICY_LINT_RULES_TEST_PREFIX = "test_policy_lint_rules"
 POLICY_LINT_SELECTION_TEST_PREFIX = "test_policy_lint_selection"
@@ -200,3 +200,19 @@ ALL_INVENTORY_FILE_NAMES = frozenset(
 )
 ALL_UNCALLED_EXEMPT_FILE_NAMES = frozenset({"__init__.py", "conftest.py"})
 CALLER_NAME_PATTERN_TEMPLATE = r"(?<![\w-]){name}(?![\w-])"
+
+CONTEXT_BUDGET_RULE_ID = "context-budget"
+CONTEXT_BUDGET_POLICY_RULE_ID = "context-budget-policy"
+CONTEXT_BUDGET_POLICY_REMOVAL_RULE_ID = "context-budget-policy-removal"
+CONTEXT_BUDGET_POLICY_PATH = ".claude/context-budget.json"
+CONTEXT_BUDGET_POLICY_REMOVED_MESSAGE = (
+    "{path}: context-budget: the policy file is removed. Restore it to preserve the budget."
+)
+CONTEXT_BUDGET_POLICY_FILE_MODULE = "context_budget.policy_file"
+CONTEXT_BUDGET_FINDINGS_MODULE = "context_budget.findings"
+CONTEXT_BUDGET_POLICY_CHANGES_MODULE = "context_budget.policy_changes"
+CONTEXT_BUDGET_MODEL_MODULE = "context_budget.model"
+CONTEXT_BUDGET_UNREADABLE_MESSAGE = (
+    "{path}: context-budget: the policy file does not parse ({error}). Fix it to"
+    " the documented shape."
+)

package/scripts/policy_lint/registry.py

@@ -4,6 +4,7 @@ from collections.abc import Callable
 from pathlib import PurePosixPath
 
 from . import adapters, model
+from .config import constants
 
 
 def build_document_rule(
@@ -114,6 +115,16 @@ def _text_document_rules() -> tuple[model.Rule, ...]:
             adapters.accepts_instruction_markdown,
             adapters.retired_hook_prose_diagnostics,
         ),
+        build_document_rule(
+            "context-budget",
+            adapters.accepts_context_markdown,
+            adapters.context_budget_diagnostics,
+        ),
+        build_document_rule(
+            "context-budget-policy",
+            adapters.accepts_context_budget_policy,
+            adapters.context_budget_policy_diagnostics,
+        ),
     )
 
 
@@ -142,6 +153,12 @@ def default_registry() -> tuple[model.Rule, ...]:
         *_python_document_rules(),
         *_text_document_rules(),
         *_configuration_document_rules(),
+        model.ChangeSetRule(
+            constants.CONTEXT_BUDGET_POLICY_REMOVAL_RULE_ID,
+            frozenset({"changed"}),
+            frozenset({model.SelectionKind.STAGED, model.SelectionKind.BASE}),
+            adapters.context_budget_policy_change_set_diagnostics,
+        ),
         model.ChangeSetRule(
             "test-pairing",
             frozenset({"changed"}),