claude-dev-env 8.72.2 → 8.73.0

package/hooks/context_budget/findings.py

@@ -0,0 +1,251 @@
+"""Compare a context file with its kind limits and its over-budget entry.
+
+::
+
+    unlisted file   lines > limit                         -> file finding
+                    unpointed section > detail limit      -> section finding
+    listed file     lines null, lines > limit             -> file finding
+                    lines N, lines > limit and lines > N  -> grown finding
+                    section heading not recorded          -> section finding
+    CI ratchet      changed file below its record N       -> record the new count, or null
+                    changed file lost a recorded section  -> drop it from the entry
+                    changed file within budget            -> remove the entry
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from collections.abc import Iterable
+
+from context_budget.model import (
+    BaselineEntry,
+    BudgetFinding,
+    BudgetPolicy,
+    FileMeasure,
+    SectionScan,
+)
+from context_budget.sections import baseline_entry_for, measure_file
+from hooks_constants.context_budget_constants import (
+    FILE_FINDING_TEMPLATE,
+    FILE_SCOPE,
+    GROWN_FINDING_TEMPLATE,
+    GROWN_PAST_PRIOR_TEMPLATE,
+    KEBAB_SEPARATOR,
+    LINES_KEY,
+    NON_KEBAB_CHARACTER_PATTERN,
+    RATCHET_LOWER_TEMPLATE,
+    RATCHET_REMOVE_TEMPLATE,
+    SECTION_FINDING_TEMPLATE,
+    SECTIONS_KEY,
+)
+
+
+def _kebab(heading: str) -> str:
+    return NON_KEBAB_CHARACTER_PATTERN.sub(KEBAB_SEPARATOR, heading.lower()).strip(KEBAB_SEPARATOR)
+
+
+def _section_finding(relative_path: str, scan: SectionScan, limit: int) -> BudgetFinding:
+    return BudgetFinding(
+        relative_path,
+        scan.heading,
+        SECTION_FINDING_TEMPLATE.format(
+            path=relative_path,
+            heading=scan.heading,
+            count=scan.detail_line_count,
+            limit=limit,
+            kebab=_kebab(scan.heading),
+        ),
+    )
+
+
+def _unrecorded_sections(
+    all_sections: Iterable[SectionScan], all_recorded_headings: Iterable[str]
+) -> list[SectionScan]:
+    remaining_count_by_heading = Counter(all_recorded_headings)
+    all_unrecorded: list[SectionScan] = []
+    for each_scan in all_sections:
+        if remaining_count_by_heading[each_scan.heading] > 0:
+            remaining_count_by_heading[each_scan.heading] -= 1
+        else:
+            all_unrecorded.append(each_scan)
+    return all_unrecorded
+
+
+def _entry_json(entry: BaselineEntry) -> str:
+    return json.dumps({LINES_KEY: entry.lines, SECTIONS_KEY: list(entry.all_section_headings)})
+
+
+def _ratchet_message(
+    relative_path: str, measure: FileMeasure, current: BaselineEntry, recorded: BaselineEntry
+) -> str:
+    return RATCHET_LOWER_TEMPLATE.format(
+        path=relative_path,
+        recorded_entry_json=_entry_json(recorded),
+        count=measure.line_count,
+        sections=json.dumps(list(current.all_section_headings)),
+        entry_json=_entry_json(current),
+    )
+
+
+def _ratchet_findings(
+    relative_path: str, measure: FileMeasure, recorded: BaselineEntry
+) -> list[BudgetFinding]:
+    current = baseline_entry_for(measure)
+    if current is None:
+        message = RATCHET_REMOVE_TEMPLATE.format(path=relative_path, count=measure.line_count)
+        return [BudgetFinding(relative_path, FILE_SCOPE, message)]
+    has_lost_section = bool(
+        Counter(recorded.all_section_headings) - Counter(current.all_section_headings)
+    )
+    has_dropped_lines = recorded.lines is not None and (
+        current.lines is None or current.lines < recorded.lines
+    )
+    if not has_dropped_lines and not has_lost_section:
+        return []
+    message = _ratchet_message(relative_path, measure, current, recorded)
+    return [BudgetFinding(relative_path, FILE_SCOPE, message)]
+
+
+def _line_limit_findings(relative_path: str, measure: FileMeasure) -> list[BudgetFinding]:
+    limit = measure.kind.line_limit or 0
+    if measure.line_count <= limit:
+        return []
+    message = FILE_FINDING_TEMPLATE.format(
+        path=relative_path, count=measure.line_count, kind=measure.kind.name, limit=limit
+    )
+    return [BudgetFinding(relative_path, FILE_SCOPE, message)]
+
+
+def _grown_findings(
+    relative_path: str, measure: FileMeasure, recorded: BaselineEntry, grown_template: str
+) -> list[BudgetFinding]:
+    if recorded.lines is None:
+        return _line_limit_findings(relative_path, measure)
+    limit = measure.kind.line_limit or 0
+    if measure.line_count <= max(recorded.lines, limit):
+        return []
+    message = grown_template.format(
+        path=relative_path,
+        recorded=recorded.lines,
+        count=measure.line_count,
+        kind=measure.kind.name,
+        limit=limit,
+    )
+    return [BudgetFinding(relative_path, FILE_SCOPE, message)]
+
+
+def _file_scope_findings(
+    relative_path: str,
+    measure: FileMeasure,
+    recorded: BaselineEntry | None,
+    is_ratchet_due: bool,
+    grown_template: str,
+) -> tuple[list[BudgetFinding], list[SectionScan]]:
+    if recorded is None:
+        return _line_limit_findings(relative_path, measure), list(measure.all_over_limit_sections)
+    all_findings = _grown_findings(relative_path, measure, recorded, grown_template)
+    if is_ratchet_due:
+        all_findings.extend(_ratchet_findings(relative_path, measure, recorded))
+    all_new_sections = _unrecorded_sections(
+        measure.all_over_limit_sections, recorded.all_section_headings
+    )
+    return all_findings, all_new_sections
+
+
+def file_findings(
+    policy: BudgetPolicy, relative_path: str, text: str, ratchet_prior_text: str | None
+) -> tuple[BudgetFinding, ...]:
+    """Check one file against its kind and the over-budget list.
+
+    Args:
+        policy: Budget policy.
+        relative_path: Repository-relative POSIX path.
+        text: Current file text.
+        ratchet_prior_text: Prior text when the CI ratchet applies, else None.
+
+    Returns:
+        Findings in file-then-section order.
+    """
+    measure = measure_file(policy, relative_path, text)
+    if measure is None:
+        return ()
+    recorded = policy.baseline_entry_by_path.get(relative_path)
+    is_ratchet_due = ratchet_prior_text is not None and ratchet_prior_text != text
+    grown_template = (
+        GROWN_PAST_PRIOR_TEMPLATE if policy.is_baseline_the_prior_text else GROWN_FINDING_TEMPLATE
+    )
+    all_findings, all_new_sections = _file_scope_findings(
+        relative_path, measure, recorded, is_ratchet_due, grown_template
+    )
+    return (
+        *all_findings,
+        *(_section_finding(relative_path, each, policy.section_detail_line_limit)
+          for each in all_new_sections),
+    )
+
+
+def _with_prior_as_baseline(
+    policy: BudgetPolicy, relative_path: str, prior_text: str
+) -> BudgetPolicy:
+    prior_measure = measure_file(policy, relative_path, prior_text)
+    prior_entry = None if prior_measure is None else baseline_entry_for(prior_measure)
+    if prior_entry is None:
+        return policy
+    return BudgetPolicy(
+        policy.section_detail_line_limit,
+        policy.all_kinds,
+        policy.all_hooks,
+        {**policy.baseline_entry_by_path, relative_path: prior_entry},
+        policy.baseline_characters_by_hook_name,
+        is_baseline_the_prior_text=True,
+    )
+
+
+def _introduced(
+    all_post_findings: Iterable[BudgetFinding],
+    all_prior_findings: Iterable[BudgetFinding],
+    has_grown: bool,
+) -> tuple[BudgetFinding, ...]:
+    remaining_count_by_scope = Counter(each.scope for each in all_prior_findings)
+    all_introduced: list[BudgetFinding] = []
+    for each_finding in all_post_findings:
+        if each_finding.scope == FILE_SCOPE:
+            is_new = has_grown
+        else:
+            is_new = remaining_count_by_scope[each_finding.scope] <= 0
+            remaining_count_by_scope[each_finding.scope] -= 1
+        if is_new:
+            all_introduced.append(each_finding)
+    return tuple(all_introduced)
+
+
+def edit_findings(
+    policy: BudgetPolicy,
+    relative_path: str,
+    prior_text: str | None,
+    post_text: str,
+    is_prior_the_baseline: bool,
+) -> tuple[BudgetFinding, ...]:
+    """Return the findings an edit adds; a file finding needs added lines.
+
+    Args:
+        policy: Budget policy.
+        relative_path: Repository-relative POSIX path.
+        prior_text: On-disk text before the edit, or None for a new file.
+        post_text: Text the edit leaves.
+        is_prior_the_baseline: Whether the prior text is the baseline entry.
+
+    Returns:
+        Findings present after the edit and absent before it.
+    """
+    if prior_text is None:
+        return file_findings(policy, relative_path, post_text, None)
+    effective_policy = policy
+    if is_prior_the_baseline:
+        effective_policy = _with_prior_as_baseline(policy, relative_path, prior_text)
+    return _introduced(
+        file_findings(effective_policy, relative_path, post_text, None),
+        file_findings(effective_policy, relative_path, prior_text, None),
+        len(post_text.splitlines()) > len(prior_text.splitlines()),
+    )

package/hooks/context_budget/hook_measure.py

@@ -0,0 +1,178 @@
+"""Measure the text a context-adding hook injects and hold it to its budget.
+
+::
+
+    command ["env", "A=1", "python3", "hooks/x.py"]
+      runs  <current python> hooks/x.py  with A=1, PATH, and an empty home
+    stdout {"hookSpecificOutput": {"additionalContext": "..."}}  -> its length
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from context_budget.model import BudgetPolicy, HookBudget
+from hooks_constants.context_budget_constants import (
+    ADDITIONAL_CONTEXT_KEY,
+    ALL_HOME_ENVIRONMENT_NAMES,
+    ALL_INHERITED_ENVIRONMENT_NAMES,
+    ALL_PYTHON_COMMAND_NAMES,
+    ENV_ASSIGNMENT_SEPARATOR,
+    ENV_COMMAND_NAME,
+    HOOK_FINDING_TEMPLATE,
+    HOOK_GROWN_TEMPLATE,
+    HOOK_MEASUREMENT_FAILED_TEMPLATE,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    HOOK_TIMEOUT_SECONDS,
+    SYSTEM_MESSAGE_KEY,
+    UTF8_ENCODING,
+)
+
+
+class HookMeasurementError(RuntimeError):
+    """Raised when a hook command cannot provide a successful measurement."""
+
+
+def _text_length(raw_value: object) -> int:
+    return len(raw_value) if isinstance(raw_value, str) else 0
+
+
+def injected_character_count(hook_stdout: str) -> int:
+    """Count the characters a hook injects into the session.
+
+    Args:
+        hook_stdout: The hook's standard output.
+
+    Returns:
+        The length of ``additionalContext`` plus ``systemMessage`` when the
+        output is a JSON object, else the length of the output.
+    """
+    try:
+        parsed_output = json.loads(hook_stdout)
+    except json.JSONDecodeError:
+        return len(hook_stdout)
+    if not isinstance(parsed_output, dict):
+        return len(hook_stdout)
+    hook_specific_output = parsed_output.get(HOOK_SPECIFIC_OUTPUT_KEY)
+    context_length = 0
+    if isinstance(hook_specific_output, dict):
+        context_length = _text_length(hook_specific_output.get(ADDITIONAL_CONTEXT_KEY))
+    return context_length + _text_length(parsed_output.get(SYSTEM_MESSAGE_KEY))
+
+
+def hook_findings(policy: BudgetPolicy, hook: HookBudget, character_count: int) -> tuple[str, ...]:
+    """Check one hook's injected character count against its limit or baseline.
+
+    Args:
+        policy: Budget policy holding the hook baseline.
+        hook: The measured hook.
+        character_count: Characters the hook injected.
+
+    Returns:
+        A one-message tuple when the hook is over budget, else empty.
+    """
+    recorded_count = policy.baseline_characters_by_hook_name.get(hook.name)
+    if recorded_count is not None:
+        if character_count <= recorded_count:
+            return ()
+        return (
+            HOOK_GROWN_TEMPLATE.format(
+                name=hook.name, count=character_count, recorded=recorded_count
+            ),
+        )
+    if character_count <= hook.char_limit:
+        return ()
+    return (
+        HOOK_FINDING_TEMPLATE.format(name=hook.name, count=character_count, limit=hook.char_limit),
+    )
+
+
+def split_command_environment(
+    all_command_parts: Sequence[str],
+) -> tuple[dict[str, str], tuple[str, ...]]:
+    """Lift a leading ``env NAME=value ...`` prefix out of a hook command.
+
+    ::
+
+        ["env", "A=1", "python3", "x.py"] -> ({"A": "1"}, ("python3", "x.py"))
+
+    Args:
+        all_command_parts: The policy's command vector.
+
+    Returns:
+        The environment pairs and the remaining argument vector.
+    """
+    if not all_command_parts or all_command_parts[0] != ENV_COMMAND_NAME:
+        return {}, tuple(all_command_parts)
+    value_by_name: dict[str, str] = {}
+    remaining_index = 1
+    for each_part in all_command_parts[1:]:
+        name, separator, value = each_part.partition(ENV_ASSIGNMENT_SEPARATOR)
+        if not separator or not name:
+            break
+        value_by_name[name] = value
+        remaining_index += 1
+    return value_by_name, tuple(all_command_parts[remaining_index:])
+
+
+def _hook_environment(home_directory: str, value_by_name: dict[str, str]) -> dict[str, str]:
+    environment = {
+        each_name: os.environ[each_name]
+        for each_name in ALL_INHERITED_ENVIRONMENT_NAMES
+        if each_name in os.environ
+    }
+    environment.update(dict.fromkeys(ALL_HOME_ENVIRONMENT_NAMES, home_directory))
+    environment.update(value_by_name)
+    return environment
+
+
+def _run_hook_in_empty_home(
+    hook: HookBudget,
+    repository_root: Path,
+) -> subprocess.CompletedProcess[str]:
+    value_by_name, all_arguments = split_command_environment(hook.all_command_parts)
+    if all_arguments and all_arguments[0] in ALL_PYTHON_COMMAND_NAMES:
+        all_arguments = (sys.executable, *all_arguments[1:])
+    with tempfile.TemporaryDirectory() as home_directory:
+        return subprocess.run(
+            list(all_arguments),
+            input=hook.stdin_text,
+            capture_output=True,
+            text=True,
+            encoding=UTF8_ENCODING,
+            cwd=repository_root,
+            env=_hook_environment(home_directory, value_by_name),
+            timeout=HOOK_TIMEOUT_SECONDS,
+            check=False,
+        )
+
+
+def run_hook_command(hook: HookBudget, repository_root: Path) -> str:
+    """Run a hook with a fresh home; Python commands use this interpreter.
+
+    Args:
+        hook: The hook to run.
+        repository_root: Directory the command runs from.
+
+    Returns:
+        Successful standard output.
+
+    Raises:
+        HookMeasurementError: When the hook exits with a nonzero status.
+    """
+    completed_process = _run_hook_in_empty_home(hook, repository_root)
+    if completed_process.returncode != 0:
+        raise HookMeasurementError(
+            HOOK_MEASUREMENT_FAILED_TEMPLATE.format(
+                name=hook.name,
+                status=completed_process.returncode,
+                stderr=completed_process.stderr.strip(),
+            )
+        )
+    return completed_process.stdout

package/hooks/context_budget/model.py

@@ -0,0 +1,134 @@
+"""Frozen data shapes of the context budget check.
+
+::
+
+    BudgetPolicy
+      kinds     ContextKind("skill entry", ("**/SKILL.md",), 200, True)
+      hooks     HookBudget("startup print", ("python3", "x.py"), "{}", 1500)
+      baseline  {"a/SKILL.md": BaselineEntry(743, ("Plan",)),
+                 "b/SKILL.md": BaselineEntry(None, ("Steps",))}, {"startup print": 5200}
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+
+class ContextBudgetPolicyError(ValueError):
+    """Raised when a policy file does not match the documented shape."""
+
+
+@dataclass(frozen=True)
+class ContextKind:
+    """One row of the kind table.
+
+    Attributes:
+        name: Kind name used in messages.
+        all_patterns: Globs over repository-relative POSIX paths.
+        line_limit: Physical line limit, or None for a skipped kind.
+        is_section_rule_on: Whether the section rule applies.
+    """
+
+    name: str
+    all_patterns: tuple[str, ...]
+    line_limit: int | None
+    is_section_rule_on: bool
+
+
+@dataclass(frozen=True)
+class HookBudget:
+    """One context-adding hook and its character limit.
+
+    Attributes:
+        name: Hook name, the key of its baseline number.
+        all_command_parts: Argument vector run from the repository root.
+        stdin_text: JSON text written to the hook's standard input.
+        char_limit: Injected character limit.
+    """
+
+    name: str
+    all_command_parts: tuple[str, ...]
+    stdin_text: str
+    char_limit: int
+
+
+@dataclass(frozen=True)
+class BaselineEntry:
+    """The recorded over-budget state of one file.
+
+    Attributes:
+        lines: Recorded physical line count when the file is over its kind's
+            line limit, or None when the file is listed only for its sections.
+        all_section_headings: Over-limit unpointed section headings, a multiset.
+    """
+
+    lines: int | None
+    all_section_headings: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class BudgetPolicy:
+    """A parsed ``.claude/context-budget.json``.
+
+    Attributes:
+        section_detail_line_limit: Detail lines a section may hold without a pointer.
+        all_kinds: Ordered kind table; the first matching kind wins.
+        all_hooks: Context-adding hooks to measure.
+        baseline_entry_by_path: Over-budget files by repository-relative path.
+        baseline_characters_by_hook_name: Over-budget hooks by name.
+        is_baseline_the_prior_text: Whether the baseline entry was measured from
+            the file's prior text because the repository has no policy file.
+    """
+
+    section_detail_line_limit: int
+    all_kinds: tuple[ContextKind, ...]
+    all_hooks: tuple[HookBudget, ...] = ()
+    baseline_entry_by_path: Mapping[str, BaselineEntry] = field(default_factory=dict)
+    baseline_characters_by_hook_name: Mapping[str, int] = field(default_factory=dict)
+    is_baseline_the_prior_text: bool = False
+
+
+@dataclass(frozen=True)
+class SectionScan:
+    """One Markdown section's measurements.
+
+    Attributes:
+        heading: Heading text, or ``(top)`` for lines before the first heading.
+        detail_line_count: Detail lines in the section body.
+        has_pointer: Whether the body links to a relative target.
+    """
+
+    heading: str
+    detail_line_count: int
+    has_pointer: bool
+
+
+@dataclass(frozen=True)
+class FileMeasure:
+    """One context file measured against its kind.
+
+    Attributes:
+        kind: The kind the path matched.
+        line_count: Physical lines, frontmatter included.
+        all_over_limit_sections: Unpointed sections over the detail limit.
+    """
+
+    kind: ContextKind
+    line_count: int
+    all_over_limit_sections: tuple[SectionScan, ...]
+
+
+@dataclass(frozen=True)
+class BudgetFinding:
+    """One budget violation.
+
+    Attributes:
+        path: Repository-relative path the finding names.
+        scope: A section heading, or ``file`` for a whole-file finding.
+        message: The full message with its fix.
+    """
+
+    path: str
+    scope: str
+    message: str