claude-dev-env 8.72.2 → 8.73.0

package/hooks/context_budget/policy_changes.py

@@ -0,0 +1,214 @@
+"""Report a policy file change that loosens the budget.
+
+The over-budget list may only shrink: a new or larger baseline entry, a raised
+limit, a section rule turned off, a deleted kind, or a deleted hook whose
+command script is still in the tree is a finding. A hook deleted together
+with its script passes.
+Existing kind patterns and precedence stay fixed. A null line count that
+becomes a number is larger. A policy file the change introduces passes.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+
+from context_budget.model import (
+    BaselineEntry,
+    BudgetFinding,
+    BudgetPolicy,
+    ContextKind,
+    HookBudget,
+)
+from hooks_constants.context_budget_constants import (
+    CHANGE_ADDS_FILE,
+    CHANGE_ADDS_HOOK,
+    CHANGE_ADDS_SECTION,
+    CHANGE_CHANGES_KIND_ORDER,
+    CHANGE_CHANGES_PATTERNS,
+    CHANGE_DELETES_HOOK,
+    CHANGE_DELETES_KIND,
+    CHANGE_DISABLES_SECTION_RULE,
+    CHANGE_RAISES_CHAR_LIMIT,
+    CHANGE_RAISES_FILE,
+    CHANGE_RAISES_HOOK,
+    CHANGE_RAISES_LINE_LIMIT,
+    CHANGE_RAISES_SECTION_LIMIT,
+    CHANGE_RECORDS_FILE_LINES,
+    FILE_SCOPE,
+    NO_LINE_LIMIT_TEXT,
+    SHRINK_ONLY_TEMPLATE,
+)
+
+
+def _limit_text(line_limit: int | None) -> str:
+    return NO_LINE_LIMIT_TEXT if line_limit is None else str(line_limit)
+
+
+def _kind_changes(prior_kind: ContextKind, current_kind: ContextKind | None) -> list[str]:
+    if current_kind is None:
+        return [CHANGE_DELETES_KIND.format(subject=prior_kind.name)]
+    all_changes: list[str] = []
+    if current_kind.all_patterns != prior_kind.all_patterns:
+        all_changes.append(CHANGE_CHANGES_PATTERNS.format(subject=prior_kind.name))
+    prior_limit = prior_kind.line_limit
+    current_limit = current_kind.line_limit
+    if prior_limit is not None and (current_limit is None or current_limit > prior_limit):
+        all_changes.append(
+            CHANGE_RAISES_LINE_LIMIT.format(
+                subject=prior_kind.name,
+                prior=_limit_text(prior_limit),
+                current=_limit_text(current_limit),
+            )
+        )
+    if prior_kind.is_section_rule_on and not current_kind.is_section_rule_on:
+        all_changes.append(CHANGE_DISABLES_SECTION_RULE.format(subject=prior_kind.name))
+    return all_changes
+
+
+def _limit_changes(
+    prior_policy: BudgetPolicy, current_policy: BudgetPolicy, repository_root: Path
+) -> list[str]:
+    all_changes: list[str] = []
+    prior_section_limit = prior_policy.section_detail_line_limit
+    current_section_limit = current_policy.section_detail_line_limit
+    if current_section_limit > prior_section_limit:
+        all_changes.append(
+            CHANGE_RAISES_SECTION_LIMIT.format(
+                prior=prior_section_limit, current=current_section_limit
+            )
+        )
+    current_kind_by_name = {each.name: each for each in current_policy.all_kinds}
+    all_prior_kind_names = tuple(
+        each.name for each in prior_policy.all_kinds if each.name in current_kind_by_name
+    )
+    all_current_kind_names = tuple(each.name for each in current_policy.all_kinds)
+    if (
+        all_current_kind_names[:len(all_prior_kind_names)] != all_prior_kind_names
+        or len(set(all_current_kind_names)) != len(all_current_kind_names)
+    ):
+        all_changes.append(CHANGE_CHANGES_KIND_ORDER)
+    for each_prior_kind in prior_policy.all_kinds:
+        all_changes.extend(
+            _kind_changes(each_prior_kind, current_kind_by_name.get(each_prior_kind.name))
+        )
+    return all_changes + _hook_limit_changes(prior_policy, current_policy, repository_root)
+
+
+def _has_script_in_tree(hook: HookBudget, repository_root: Path) -> bool:
+    return any(
+        not Path(each_part).is_absolute() and (repository_root / each_part).is_file()
+        for each_part in hook.all_command_parts
+    )
+
+
+def _deleted_hook_changes(prior_hook: HookBudget, repository_root: Path) -> list[str]:
+    if not _has_script_in_tree(prior_hook, repository_root):
+        return []
+    return [CHANGE_DELETES_HOOK.format(subject=prior_hook.name)]
+
+
+def _hook_limit_changes(
+    prior_policy: BudgetPolicy, current_policy: BudgetPolicy, repository_root: Path
+) -> list[str]:
+    """Preserve each measured hook whose script remains and hold its limit to the prior budget."""
+    all_changes: list[str] = []
+    current_hook_by_name = {each.name: each for each in current_policy.all_hooks}
+    for each_prior_hook in prior_policy.all_hooks:
+        current_hook = current_hook_by_name.get(each_prior_hook.name)
+        if current_hook is None:
+            all_changes.extend(_deleted_hook_changes(each_prior_hook, repository_root))
+            continue
+        current_limit = current_hook.char_limit
+        if current_limit > each_prior_hook.char_limit:
+            all_changes.append(
+                CHANGE_RAISES_CHAR_LIMIT.format(
+                    subject=each_prior_hook.name,
+                    prior=each_prior_hook.char_limit,
+                    current=current_limit,
+                )
+            )
+    return all_changes
+
+
+def _line_entry_change(
+    each_path: str, each_entry: BaselineEntry, prior_entry: BaselineEntry
+) -> str | None:
+    if each_entry.lines is None:
+        return None
+    if prior_entry.lines is None:
+        return CHANGE_RECORDS_FILE_LINES.format(subject=each_path, current=each_entry.lines)
+    if each_entry.lines > prior_entry.lines:
+        return CHANGE_RAISES_FILE.format(
+            subject=each_path, prior=prior_entry.lines, current=each_entry.lines
+        )
+    return None
+
+
+def _file_entry_changes(prior_policy: BudgetPolicy, current_policy: BudgetPolicy) -> list[str]:
+    all_changes: list[str] = []
+    for each_path, each_entry in sorted(current_policy.baseline_entry_by_path.items()):
+        prior_entry = prior_policy.baseline_entry_by_path.get(each_path)
+        if prior_entry is None:
+            all_changes.append(CHANGE_ADDS_FILE.format(subject=each_path))
+            continue
+        line_change = _line_entry_change(each_path, each_entry, prior_entry)
+        if line_change is not None:
+            all_changes.append(line_change)
+        all_added_headings = Counter(each_entry.all_section_headings) - Counter(
+            prior_entry.all_section_headings
+        )
+        all_changes.extend(
+            CHANGE_ADDS_SECTION.format(heading=each_heading, subject=each_path)
+            for each_heading in sorted(all_added_headings.elements())
+        )
+    return all_changes
+
+
+def _hook_entry_change(each_name: str, each_count: int, prior_count: int | None) -> str | None:
+    if prior_count is None:
+        return CHANGE_ADDS_HOOK.format(subject=each_name)
+    if each_count > prior_count:
+        return CHANGE_RAISES_HOOK.format(subject=each_name, prior=prior_count, current=each_count)
+    return None
+
+
+def _hook_entry_changes(prior_policy: BudgetPolicy, current_policy: BudgetPolicy) -> list[str]:
+    prior_count_by_name = prior_policy.baseline_characters_by_hook_name
+    all_candidate_changes = (
+        _hook_entry_change(each_name, each_count, prior_count_by_name.get(each_name))
+        for each_name, each_count in sorted(current_policy.baseline_characters_by_hook_name.items())
+    )
+    return [each for each in all_candidate_changes if each is not None]
+
+
+def policy_shrink_findings(
+    policy_path: str,
+    prior_policy: BudgetPolicy | None,
+    current_policy: BudgetPolicy,
+    repository_root: Path,
+) -> tuple[BudgetFinding, ...]:
+    """Report each change to the policy file that loosens the budget.
+
+    Args:
+        policy_path: Repository-relative path of the policy file.
+        prior_policy: Policy before the change, or None when the change adds it.
+        current_policy: Policy after the change.
+        repository_root: Working tree that holds each hook's command script.
+
+    Returns:
+        One finding per loosening change; empty when the file is new.
+    """
+    if prior_policy is None:
+        return ()
+    all_changes = (
+        _limit_changes(prior_policy, current_policy, repository_root)
+        + _file_entry_changes(prior_policy, current_policy)
+        + _hook_entry_changes(prior_policy, current_policy)
+    )
+    return tuple(
+        BudgetFinding(
+            policy_path, FILE_SCOPE, SHRINK_ONLY_TEMPLATE.format(path=policy_path, change=each)
+        )
+        for each in all_changes
+    )

package/hooks/context_budget/policy_file.py

@@ -0,0 +1,222 @@
+"""Parse ``.claude/context-budget.json`` and locate it from an edited file.
+
+Unknown keys are ignored, so a policy file another tool extends still parses.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from context_budget.model import (
+    BaselineEntry,
+    BudgetPolicy,
+    ContextBudgetPolicyError,
+    ContextKind,
+    HookBudget,
+)
+from hooks_constants.context_budget_constants import (
+    ALL_DEFAULT_KIND_SPECS,
+    ALL_POLICY_PATH_PARTS,
+    BASELINE_FILES_KEY,
+    BASELINE_HOOKS_KEY,
+    BASELINE_KEY,
+    CHAR_LIMIT_KEY,
+    COMMAND_KEY,
+    DEFAULT_SECTION_DETAIL_LINE_LIMIT,
+    GIT_MARKER_NAME,
+    HOOKS_KEY,
+    KINDS_KEY,
+    LINE_LIMIT_KEY,
+    LINES_KEY,
+    NAME_KEY,
+    PATTERNS_KEY,
+    POLICY_ERROR_BAD_FIELD,
+    POLICY_ERROR_DUPLICATE_HOOK_NAME,
+    POLICY_ERROR_NOT_OBJECT,
+    SECTION_DETAIL_LINE_LIMIT_KEY,
+    SECTION_RULE_KEY,
+    SECTIONS_KEY,
+    STDIN_KEY,
+    UTF8_ENCODING,
+)
+
+
+def default_policy() -> BudgetPolicy:
+    """Return the built-in policy for a repository with no policy file.
+
+    Returns:
+        The default kinds with an empty baseline.
+    """
+    return BudgetPolicy(
+        section_detail_line_limit=DEFAULT_SECTION_DETAIL_LINE_LIMIT,
+        all_kinds=tuple(
+            ContextKind(each_name, each_patterns, each_limit, each_rule)
+            for each_name, each_patterns, each_limit, each_rule in ALL_DEFAULT_KIND_SPECS
+        ),
+    )
+
+
+def _bad_field(field_name: str) -> ContextBudgetPolicyError:
+    return ContextBudgetPolicyError(POLICY_ERROR_BAD_FIELD.format(field=field_name))
+
+
+def _integer(raw_value: object, field_name: str) -> int:
+    if isinstance(raw_value, bool) or not isinstance(raw_value, int):
+        raise _bad_field(field_name)
+    return raw_value
+
+
+def _text(raw_value: object, field_name: str) -> str:
+    if not isinstance(raw_value, str):
+        raise _bad_field(field_name)
+    return raw_value
+
+
+def _mapping(raw_value: object, field_name: str) -> dict:
+    if not isinstance(raw_value, dict):
+        raise _bad_field(field_name)
+    return raw_value
+
+
+def _texts(raw_value: object, field_name: str) -> tuple[str, ...]:
+    if not isinstance(raw_value, list):
+        raise _bad_field(field_name)
+    return tuple(_text(each_item, field_name) for each_item in raw_value)
+
+
+def _items(raw_value: object, field_name: str) -> list:
+    if not isinstance(raw_value, list):
+        raise _bad_field(field_name)
+    return raw_value
+
+
+def _parse_kind(raw_kind: object) -> ContextKind:
+    kind_by_key = _mapping(raw_kind, KINDS_KEY)
+    raw_limit = kind_by_key.get(LINE_LIMIT_KEY)
+    return ContextKind(
+        _text(kind_by_key.get(NAME_KEY), NAME_KEY),
+        _texts(kind_by_key.get(PATTERNS_KEY), PATTERNS_KEY),
+        None if raw_limit is None else _integer(raw_limit, LINE_LIMIT_KEY),
+        kind_by_key.get(SECTION_RULE_KEY) is True,
+    )
+
+
+def _parse_hook(raw_hook: object) -> HookBudget:
+    hook_by_key = _mapping(raw_hook, HOOKS_KEY)
+    return HookBudget(
+        _text(hook_by_key.get(NAME_KEY), NAME_KEY),
+        _texts(hook_by_key.get(COMMAND_KEY), COMMAND_KEY),
+        json.dumps(hook_by_key.get(STDIN_KEY, {})),
+        _integer(hook_by_key.get(CHAR_LIMIT_KEY), CHAR_LIMIT_KEY),
+    )
+
+
+def _parse_hooks(raw_hooks: object) -> tuple[HookBudget, ...]:
+    all_hooks = tuple(_parse_hook(each) for each in _items(raw_hooks, HOOKS_KEY))
+    all_names = [each.name for each in all_hooks]
+    if len(set(all_names)) != len(all_names):
+        raise ContextBudgetPolicyError(POLICY_ERROR_DUPLICATE_HOOK_NAME)
+    return all_hooks
+
+
+def _parse_baseline_entry(raw_entry: object) -> BaselineEntry:
+    entry_by_key = _mapping(raw_entry, BASELINE_FILES_KEY)
+    if LINES_KEY not in entry_by_key:
+        raise _bad_field(LINES_KEY)
+    raw_lines = entry_by_key[LINES_KEY]
+    return BaselineEntry(
+        None if raw_lines is None else _integer(raw_lines, LINES_KEY),
+        _texts(entry_by_key.get(SECTIONS_KEY, []), SECTIONS_KEY),
+    )
+
+
+def _parse_baseline(raw_baseline: object) -> tuple[dict[str, BaselineEntry], dict[str, int]]:
+    baseline_by_key = _mapping(raw_baseline, BASELINE_KEY)
+    raw_files = _mapping(baseline_by_key.get(BASELINE_FILES_KEY, {}), BASELINE_FILES_KEY)
+    raw_hooks = _mapping(baseline_by_key.get(BASELINE_HOOKS_KEY, {}), BASELINE_HOOKS_KEY)
+    return (
+        {
+            str(each_path): _parse_baseline_entry(each_entry)
+            for each_path, each_entry in raw_files.items()
+        },
+        {
+            str(each_name): _integer(each_count, BASELINE_HOOKS_KEY)
+            for each_name, each_count in raw_hooks.items()
+        },
+    )
+
+
+def _json_object(policy_text: str) -> dict:
+    try:
+        raw_policy = json.loads(policy_text)
+    except json.JSONDecodeError as error:
+        raise ContextBudgetPolicyError(str(error)) from error
+    if not isinstance(raw_policy, dict):
+        raise ContextBudgetPolicyError(POLICY_ERROR_NOT_OBJECT)
+    return raw_policy
+
+
+def parse_policy(policy_text: str) -> BudgetPolicy:
+    """Parse policy JSON text; unknown keys are ignored.
+
+    Args:
+        policy_text: The text of ``.claude/context-budget.json``.
+
+    Returns:
+        The parsed policy.
+
+    Raises:
+        ContextBudgetPolicyError: When the text is not JSON of the documented shape.
+    """
+    raw_policy = _json_object(policy_text)
+    entry_by_path, characters_by_hook_name = _parse_baseline(raw_policy.get(BASELINE_KEY, {}))
+    return BudgetPolicy(
+        section_detail_line_limit=_integer(
+            raw_policy.get(SECTION_DETAIL_LINE_LIMIT_KEY, DEFAULT_SECTION_DETAIL_LINE_LIMIT),
+            SECTION_DETAIL_LINE_LIMIT_KEY,
+        ),
+        all_kinds=tuple(
+            _parse_kind(each) for each in _items(raw_policy.get(KINDS_KEY, []), KINDS_KEY)
+        ),
+        all_hooks=_parse_hooks(raw_policy.get(HOOKS_KEY, [])),
+        baseline_entry_by_path=entry_by_path,
+        baseline_characters_by_hook_name=characters_by_hook_name,
+    )
+
+
+def find_repository_root(file_path: Path) -> Path | None:
+    """Return the nearest ancestor holding a ``.git`` file or directory.
+
+    Args:
+        file_path: Absolute path of a file that may not exist yet.
+
+    Returns:
+        The repository root, or None outside any repository.
+    """
+    for each_directory in file_path.parents:
+        if (each_directory / GIT_MARKER_NAME).exists():
+            return each_directory
+    return None
+
+
+def read_policy_file(repository_root: Path) -> BudgetPolicy | None:
+    """Read and parse a repository's policy file.
+
+    Args:
+        repository_root: Repository root directory.
+
+    Returns:
+        The parsed policy, or None when the repository has no policy file.
+
+    Raises:
+        ContextBudgetPolicyError: When the file exists and does not parse.
+    """
+    policy_path = repository_root.joinpath(*ALL_POLICY_PATH_PARTS)
+    try:
+        policy_text = policy_path.read_text(encoding=UTF8_ENCODING)
+    except FileNotFoundError:
+        return None
+    except (OSError, UnicodeDecodeError) as error:
+        raise ContextBudgetPolicyError(str(error)) from error
+    return parse_policy(policy_text)

package/hooks/context_budget/sections.py

@@ -0,0 +1,213 @@
+"""Classify a path by the kind table and measure its Markdown sections.
+
+::
+
+    ## Plan                    heading starts a section
+    Step one.                  detail line
+    | a | b |                  table row, not detail
+    - [ref](reference/x.md)    pure link item, not detail; relative link is a pointer
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from fnmatch import fnmatchcase
+
+from context_budget.model import (
+    BaselineEntry,
+    BudgetPolicy,
+    ContextKind,
+    FileMeasure,
+    SectionScan,
+)
+from hooks_constants.context_budget_constants import (
+    ALL_NON_RELATIVE_TARGET_PREFIXES,
+    ATX_HEADING_PATTERN,
+    FENCE_OPEN_PATTERN,
+    FRONTMATTER_DELIMITER,
+    LINK_TARGET_PATTERN,
+    PATH_SEPARATOR,
+    PURE_LINK_LIST_ITEM_PATTERN,
+    RECURSIVE_GLOB_SEGMENT,
+    TABLE_ROW_PREFIX,
+    TOP_SECTION_HEADING,
+)
+
+
+def _segments_match(all_pattern_parts: Sequence[str], all_path_parts: Sequence[str]) -> bool:
+    if not all_pattern_parts:
+        return not all_path_parts
+    if all_pattern_parts[0] == RECURSIVE_GLOB_SEGMENT:
+        return any(
+            _segments_match(all_pattern_parts[1:], all_path_parts[each_start:])
+            for each_start in range(len(all_path_parts) + 1)
+        )
+    if not all_path_parts or not fnmatchcase(all_path_parts[0], all_pattern_parts[0]):
+        return False
+    return _segments_match(all_pattern_parts[1:], all_path_parts[1:])
+
+
+def path_matches_pattern(pattern: str, relative_path: str) -> bool:
+    """Return whether a repository-relative POSIX path matches one glob.
+
+    ::
+
+        "**/SKILL.md"       "SKILL.md"            -> True
+        "rules/*.md"        "rules/deep/a.md"     -> False
+        "**/archived/**"    "x/archived/a/b.md"   -> True
+
+    Args:
+        pattern: Glob where ``**`` spans zero or more directories.
+        relative_path: Repository-relative POSIX path.
+
+    Returns:
+        True when the whole path matches.
+    """
+    return _segments_match(pattern.split(PATH_SEPARATOR), relative_path.split(PATH_SEPARATOR))
+
+
+def context_kind_for_path(policy: BudgetPolicy, relative_path: str) -> ContextKind | None:
+    """Return the measured kind of a path; the first matching kind wins.
+
+    Args:
+        policy: Budget policy holding the ordered kind table.
+        relative_path: Repository-relative POSIX path.
+
+    Returns:
+        The matching kind, or None when no kind matches or the match is skipped.
+    """
+    for each_kind in policy.all_kinds:
+        if any(path_matches_pattern(each, relative_path) for each in each_kind.all_patterns):
+            return each_kind if each_kind.line_limit is not None else None
+    return None
+
+
+def _body_lines(text: str) -> list[str]:
+    all_lines = text.splitlines()
+    if not all_lines or all_lines[0].strip() != FRONTMATTER_DELIMITER:
+        return all_lines
+    for each_index in range(1, len(all_lines)):
+        if all_lines[each_index].strip() == FRONTMATTER_DELIMITER:
+            return all_lines[each_index + 1 :]
+    return all_lines
+
+
+def _line_has_pointer(line: str) -> bool:
+    return any(
+        not each_match.group("target").lower().startswith(ALL_NON_RELATIVE_TARGET_PREFIXES)
+        for each_match in LINK_TARGET_PATTERN.finditer(line)
+    )
+
+
+def _is_detail_line(line: str) -> bool:
+    if not line.strip() or line.lstrip().startswith(TABLE_ROW_PREFIX):
+        return False
+    return PURE_LINK_LIST_ITEM_PATTERN.match(line) is None
+
+
+def _closes_fence(line: str, opening_marker: str) -> bool:
+    match = FENCE_OPEN_PATTERN.match(line)
+    if match is None or line[match.end() :].strip():
+        return False
+    marker = match.group("marker")
+    return marker[0] == opening_marker[0] and len(marker) >= len(opening_marker)
+
+
+@dataclass
+class _SectionWalk:
+    """Mutable state of one pass over a Markdown body."""
+
+    all_scans: list[SectionScan]
+    heading: str = TOP_SECTION_HEADING
+    detail_line_count: int = 0
+    has_pointer: bool = False
+    opening_marker: str | None = None
+
+    def close_section(self) -> None:
+        self.all_scans.append(SectionScan(self.heading, self.detail_line_count, self.has_pointer))
+
+    def read_fenced(self, line: str) -> None:
+        if line.strip():
+            self.detail_line_count += 1
+        if self.opening_marker is not None and _closes_fence(line, self.opening_marker):
+            self.opening_marker = None
+
+    def read_open(self, line: str) -> None:
+        fence_match = FENCE_OPEN_PATTERN.match(line)
+        heading_match = ATX_HEADING_PATTERN.match(line)
+        if fence_match is not None:
+            self.opening_marker = fence_match.group("marker")
+            self.detail_line_count += 1
+        elif heading_match is not None:
+            self.close_section()
+            self.heading = (heading_match.group("text") or "").strip()
+            self.detail_line_count = 0
+            self.has_pointer = False
+        else:
+            self.detail_line_count += int(_is_detail_line(line))
+            self.has_pointer = self.has_pointer or _line_has_pointer(line)
+
+
+def scan_sections(text: str) -> tuple[SectionScan, ...]:
+    """Split Markdown into sections and measure each one.
+
+    A heading inside a fenced block is not a heading. Fenced lines count as
+    detail and never supply a pointer.
+
+    Args:
+        text: Full file text; leading frontmatter is removed.
+
+    Returns:
+        One scan per section in document order, starting with ``(top)``.
+    """
+    walk = _SectionWalk([])
+    for each_line in _body_lines(text):
+        if walk.opening_marker is not None:
+            walk.read_fenced(each_line)
+        else:
+            walk.read_open(each_line)
+    walk.close_section()
+    return tuple(walk.all_scans)
+
+
+def measure_file(policy: BudgetPolicy, relative_path: str, text: str) -> FileMeasure | None:
+    """Measure one file against the kind its path selects.
+
+    Args:
+        policy: Budget policy.
+        relative_path: Repository-relative POSIX path.
+        text: File text.
+
+    Returns:
+        The measurement, or None when the path is not measured context.
+    """
+    kind = context_kind_for_path(policy, relative_path)
+    if kind is None:
+        return None
+    all_over_limit_sections: tuple[SectionScan, ...] = ()
+    if kind.is_section_rule_on:
+        all_over_limit_sections = tuple(
+            each_scan
+            for each_scan in scan_sections(text)
+            if each_scan.detail_line_count > policy.section_detail_line_limit
+            and not each_scan.has_pointer
+        )
+    return FileMeasure(kind, len(text.splitlines()), all_over_limit_sections)
+
+
+def baseline_entry_for(measure: FileMeasure) -> BaselineEntry | None:
+    """Return the baseline entry a measurement needs, or None when within budget.
+
+    Args:
+        measure: One file measurement.
+
+    Returns:
+        The entry recording the over-limit headings, and the line count only
+        when it exceeds the kind's line limit.
+    """
+    all_headings = tuple(each_scan.heading for each_scan in measure.all_over_limit_sections)
+    is_over_line_limit = measure.line_count > (measure.kind.line_limit or 0)
+    if not is_over_line_limit and not all_headings:
+        return None
+    return BaselineEntry(measure.line_count if is_over_line_limit else None, all_headings)