claude-dev-env 8.62.1 → 8.63.0

package/.agents/skills/context-audit/scripts/context_sources.py

@@ -0,0 +1,252 @@
+"""Read checkout files and measure them as context rows.
+
+A row records one loaded file: its size, its links out, and its depth mode.
+The helpers here read text, parse frontmatter, and follow links and imports.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from context_audit_constants.config import constants
+from context_audit_constants.config.constants import DepthMode, RowKind, Trigger
+
+
+@dataclass(frozen=True)
+class ContextRow:
+    """One file an agent loads, with its size and how it loads."""
+
+    path: str
+    kind: RowKind
+    loader: str
+    trigger: Trigger
+    bytes: int
+    lines: int
+    est_tokens: int
+    links_out: int
+    depth_mode: DepthMode
+    cap: int | None
+    note: str
+
+
+@dataclass(frozen=True)
+class RowSource:
+    """Where a row's file sits and how the agent reaches it."""
+
+    path: str
+    kind: RowKind
+    loader: str
+    trigger: Trigger
+    note: str
+
+
+def list_tracked_files(root: Path) -> list[Path]:
+    """Return the tracked files under *root*, minus caches and vendored folders.
+
+    Args:
+        root: A git checkout.
+
+    Returns:
+        Absolute paths of tracked files that exist on disk.
+    """
+    listing = subprocess.run(
+        constants.ALL_GIT_LIST_FILES_ARGUMENTS,
+        cwd=root,
+        capture_output=True,
+        check=True,
+    ).stdout
+    all_paths = [
+        root / os.fsdecode(each_entry)
+        for each_entry in listing.split(constants.GIT_LIST_FILES_SEPARATOR)
+        if each_entry
+    ]
+    return [
+        each_path
+        for each_path in all_paths
+        if not constants.ALL_SKIPPED_PATH_PARTS.intersection(each_path.parts)
+        and each_path.is_file()
+    ]
+
+
+def read_text(path: Path) -> str:
+    """Return the file text, or an empty string when it cannot be read.
+
+    Args:
+        path: The file to read.
+
+    Returns:
+        The decoded text.
+    """
+    try:
+        return path.read_text(
+            encoding=constants.TEXT_ENCODING, errors=constants.TEXT_DECODE_ERRORS
+        )
+    except OSError:
+        return ""
+
+
+def parse_frontmatter(text: str) -> dict[str, str]:
+    """Return the frontmatter fields of a markdown file as flat strings.
+
+    ::
+
+        ---
+        name: demo
+        paths:
+          - src/**
+        ---
+        -> {"name": "demo", "paths": "- src/**"}
+
+    Args:
+        text: The file text.
+
+    Returns:
+        Field text by field name; empty when the file has no frontmatter.
+    """
+    fence_length = len(constants.FRONTMATTER_FENCE)
+    closing_index = text.find(constants.FRONTMATTER_CLOSING_FENCE, fence_length)
+    if not text.startswith(constants.FRONTMATTER_FENCE) or closing_index == -1:
+        return {}
+    field_by_name: dict[str, str] = {}
+    current_name = ""
+    for each_line in text[fence_length:closing_index].splitlines():
+        current_name = _merge_frontmatter_line(field_by_name, current_name, each_line)
+    return field_by_name
+
+
+def _merge_frontmatter_line(
+    field_by_name: dict[str, str], current_name: str, line: str
+) -> str:
+    field_match = re.match(constants.FRONTMATTER_FIELD_PATTERN, line)
+    if field_match:
+        field_by_name[field_match.group(1)] = field_match.group(2).strip()
+        return field_match.group(1)
+    if current_name and line.startswith(
+        constants.ALL_FRONTMATTER_CONTINUATION_PREFIXES
+    ):
+        field_by_name[current_name] = (
+            f"{field_by_name[current_name]} {line.strip()}".strip()
+        )
+    return current_name
+
+
+def find_relative_links(source: Path, text: str, root: Path) -> list[Path]:
+    """Return the files inside *root* that markdown links in *text* point to.
+
+    Args:
+        source: The file the text came from.
+        text: Markdown text.
+        root: The checkout root.
+
+    Returns:
+        Resolved link targets that exist inside the checkout.
+    """
+    all_targets = [
+        each_target
+        for each_target in re.findall(constants.LINK_PATTERN, text)
+        if not re.match(constants.URL_SCHEME_PATTERN, each_target)
+    ]
+    return _existing_inside(source, all_targets, root)
+
+
+def find_import_targets(source: Path, text: str, root: Path) -> list[Path]:
+    """Return the files inside *root* that ``@path`` import lines name.
+
+    Args:
+        source: The instruction file the text came from.
+        text: The instruction text.
+        root: The checkout root.
+
+    Returns:
+        Resolved import targets that exist inside the checkout.
+    """
+    return _existing_inside(source, re.findall(constants.IMPORT_PATTERN, text), root)
+
+
+def _existing_inside(source: Path, all_targets: list[str], root: Path) -> list[Path]:
+    all_candidates = [
+        (source.parent / each_target).resolve() for each_target in all_targets
+    ]
+    return [
+        each_candidate
+        for each_candidate in all_candidates
+        if each_candidate.is_file() and root in each_candidate.parents
+    ]
+
+
+def classify_depth(
+    cap: int | None, byte_count: int, line_count: int, link_count: int
+) -> DepthMode:
+    """Return how much depth a file carries against its cap.
+
+    ::
+
+        classify_depth(20, 0, 0, 0)       -> empty
+        classify_depth(None, 900, 30, 0)  -> reference
+        classify_depth(20, 4000, 64, 2)   -> carries
+        classify_depth(20, 600, 12, 3)    -> points
+
+    Args:
+        cap: The line cap, or None for on-link depth.
+        byte_count: File size in bytes.
+        line_count: File length in lines.
+        link_count: Relative links out of the file.
+
+    Returns:
+        The depth mode; a file over cap lines, or over cap times 120 bytes, carries.
+    """
+    if byte_count <= constants.EMPTY_FILE_BYTE_LIMIT:
+        return DepthMode.EMPTY
+    if cap is None:
+        return DepthMode.REFERENCE
+    if line_count > cap or byte_count > cap * constants.CHARACTERS_PER_CAPPED_LINE:
+        return DepthMode.CARRIES
+    return DepthMode.POINTS if link_count else DepthMode.LEAN
+
+
+def count_lines(text: str) -> int:
+    """Return the line count of *text*, counting a final unterminated line.
+
+    Args:
+        text: Any text.
+
+    Returns:
+        The number of lines.
+    """
+    has_unterminated_tail = bool(text) and not text.endswith(constants.LINE_BREAK)
+    return text.count(constants.LINE_BREAK) + int(has_unterminated_tail)
+
+
+def measure_row(
+    source: RowSource, text: str, cap: int | None, link_count: int
+) -> ContextRow:
+    """Return the row for *text* loaded from *source*.
+
+    Args:
+        source: Where the file sits and how it loads.
+        text: The text the agent receives.
+        cap: The line cap, or None for on-link depth.
+        link_count: Relative links out of the text.
+
+    Returns:
+        The measured row.
+    """
+    byte_count = len(text.encode(constants.TEXT_ENCODING))
+    line_count = count_lines(text)
+    return ContextRow(
+        path=source.path,
+        kind=source.kind,
+        loader=source.loader,
+        trigger=source.trigger,
+        bytes=byte_count,
+        lines=line_count,
+        est_tokens=round(byte_count / constants.BYTES_PER_ESTIMATED_TOKEN),
+        links_out=link_count,
+        depth_mode=classify_depth(cap, byte_count, line_count, link_count),
+        cap=cap,
+        note=source.note,
+    )

package/.agents/skills/context-audit/scripts/test_context_audit.py

@@ -0,0 +1,217 @@
+"""Behavior tests for the context audit, run as a command on a temporary git checkout."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPT_PATH = Path(__file__).resolve().parent / "context_audit.py"
+
+
+def write_file(root: Path, relative_path: str, text: str) -> None:
+    target = root / relative_path
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding="utf-8")
+
+
+def numbered_lines(count: int) -> str:
+    return "".join(f"line {each_index}\n" for each_index in range(count))
+
+
+@pytest.fixture
+def checkout(tmp_path: Path) -> Path:
+    root = tmp_path / "sample-repo"
+    write_file(root, "CLAUDE.md", "@AGENTS.md\n@docs/shared.md\n")
+    write_file(root, "AGENTS.md", numbered_lines(30))
+    write_file(root, "docs/shared.md", "Shared steps. See [deep](deep.md).\n")
+    write_file(root, "docs/deep.md", "Deep notes. See [deeper](deeper.md).\n")
+    write_file(root, "docs/deeper.md", "Deeper notes.\n")
+    write_file(root, "nested/CLAUDE.md", "")
+    write_file(
+        root,
+        ".claude/rules/api.md",
+        "---\npaths:\n  - src/api/**\n---\nUse the client.\n",
+    )
+    write_file(root, ".claude/rules/general.md", "Keep diffs small.\n")
+    write_file(
+        root,
+        ".claude/skills/demo/SKILL.md",
+        "---\nname: demo\ndescription: Run the demo. Use when asked to demo.\n---\n"
+        + numbered_lines(250),
+    )
+    write_file(root, ".claude/skills/demo/references/guide.md", "Guide body.\n")
+    write_file(
+        root,
+        ".claude/skills/quiet/SKILL.md",
+        "---\nname: quiet\ndescription: Hidden.\ndisable-model-invocation: true\n---\nBody.\n",
+    )
+    write_file(
+        root, "tests/fixture/.claude/skills/ghost/SKILL.md", "---\nname: ghost\n---\n"
+    )
+    write_file(root, "tool.py", '"""' + numbered_lines(20) + '"""\n')
+    subprocess.run(["git", "init", "-q"], cwd=root, check=True)
+    subprocess.run(["git", "add", "-A"], cwd=root, check=True)
+    return root
+
+
+def run_audit(*all_arguments: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(SCRIPT_PATH), *all_arguments],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def audit_rows(
+    checkout: Path, tmp_path: Path, *all_extra_arguments: str
+) -> dict[tuple[str, str], dict]:
+    rows_path = tmp_path / "rows.jsonl"
+    completed = run_audit(str(checkout), "--rows", str(rows_path), *all_extra_arguments)
+    assert completed.returncode == 0, completed.stderr
+    all_rows = [
+        json.loads(each_line) for each_line in rows_path.read_text().splitlines()
+    ]
+    return {(each_row["path"], each_row["kind"]): each_row for each_row in all_rows}
+
+
+def test_root_instructions_load_at_session_start_and_carry_when_over_cap(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    agents_row = row_by_key[("AGENTS.md", "instructions")]
+    assert agents_row["trigger"] == "session-start"
+    assert agents_row["loader"] == "@import from CLAUDE.md"
+    assert agents_row["lines"] == 30
+    assert agents_row["depth_mode"] == "carries"
+    assert row_by_key[("CLAUDE.md", "instructions")]["depth_mode"] == "lean"
+
+
+def test_nested_empty_instructions_load_on_folder_enter_as_empty(
+    checkout: Path, tmp_path: Path
+) -> None:
+    nested_row = audit_rows(checkout, tmp_path)[("nested/CLAUDE.md", "instructions")]
+    assert nested_row["trigger"] == "folder-enter"
+    assert nested_row["depth_mode"] == "empty"
+
+
+def test_import_loads_with_importer_and_its_links_follow_on_demand(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    assert row_by_key[("docs/shared.md", "import")]["trigger"] == "session-start"
+    assert row_by_key[("docs/shared.md", "import")]["depth_mode"] == "points"
+    deep_row = row_by_key[("docs/deep.md", "linked-doc")]
+    deeper_row = row_by_key[("docs/deeper.md", "linked-doc")]
+    assert (deep_row["trigger"], deep_row["depth_mode"], deep_row["note"]) == (
+        "on-link",
+        "reference",
+        "link depth 1",
+    )
+    assert deeper_row["note"] == "link depth 2"
+
+
+def test_rule_with_paths_loads_on_path_match_and_plain_rule_at_session_start(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    assert row_by_key[(".claude/rules/api.md", "rule")]["trigger"] == "path-match"
+    assert (
+        row_by_key[(".claude/rules/general.md", "rule")]["trigger"] == "session-start"
+    )
+
+
+def test_skill_yields_listing_body_and_reference_rows(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    description_row = row_by_key[(".claude/skills/demo/SKILL.md", "skill-description")]
+    body_row = row_by_key[(".claude/skills/demo/SKILL.md", "skill-body")]
+    reference_row = row_by_key[
+        (".claude/skills/demo/references/guide.md", "skill-reference")
+    ]
+    assert (description_row["trigger"], description_row["depth_mode"]) == (
+        "session-start",
+        "points",
+    )
+    assert (body_row["trigger"], body_row["depth_mode"]) == ("skill-invoke", "carries")
+    assert reference_row["trigger"] == "on-link"
+
+
+def test_disabled_skill_has_no_listing_and_fixture_skill_is_skipped(
+    checkout: Path, tmp_path: Path
+) -> None:
+    row_by_key = audit_rows(checkout, tmp_path)
+    assert (".claude/skills/quiet/SKILL.md", "skill-description") not in row_by_key
+    assert (".claude/skills/quiet/SKILL.md", "skill-body") in row_by_key
+    assert not any(
+        each_path.startswith("tests/") and each_kind.startswith("skill")
+        for each_path, each_kind in row_by_key
+    )
+
+
+def test_module_docstring_loads_on_file_open_and_carries_over_cap(
+    checkout: Path, tmp_path: Path
+) -> None:
+    docstring_row = audit_rows(checkout, tmp_path)[("tool.py", "docstring")]
+    assert (
+        docstring_row["trigger"],
+        docstring_row["depth_mode"],
+        docstring_row["cap"],
+    ) == ("file-open", "carries", 15)
+
+
+def test_saved_hook_text_counts_at_session_start(
+    checkout: Path, tmp_path: Path
+) -> None:
+    hook_text_file = tmp_path / "hook-banner.txt"
+    hook_text_file.write_text(numbered_lines(3), encoding="utf-8")
+    row_by_key = audit_rows(
+        checkout, tmp_path, "--session-start-text", str(hook_text_file)
+    )
+    hook_row = row_by_key[("hook-banner.txt", "hook-text")]
+    assert (hook_row["trigger"], hook_row["lines"], hook_row["depth_mode"]) == (
+        "session-start",
+        3,
+        "lean",
+    )
+
+
+def test_report_lists_each_cleanup_section(checkout: Path) -> None:
+    completed = run_audit(str(checkout))
+    assert completed.returncode == 0, completed.stderr
+    carries_section, _, after_carries = completed.stdout.partition(
+        "## Empty instruction stubs"
+    )
+    stubs_section, _, split_section = after_carries.partition("## Long skills to split")
+    assert "| AGENTS.md | instructions | session-start | 30 | 20 |" in carries_section
+    assert "| tool.py | docstring | file-open | 20 | 15 |" in carries_section
+    assert "SKILL.md" not in carries_section
+    assert stubs_section.strip() == "- nested/CLAUDE.md (instructions)"
+    assert (
+        "| .claude/skills/demo/SKILL.md | 254 | 200 |"
+        in split_section.split("\n", 3)[3]
+    )
+
+
+def test_command_option_is_gone_and_text_file_must_exist(
+    checkout: Path, tmp_path: Path
+) -> None:
+    rejected = run_audit(str(checkout), "--session-start-command", "echo hi")
+    assert rejected.returncode == 2
+    assert "unrecognized arguments" in rejected.stderr
+    missing = run_audit(
+        str(checkout), "--session-start-text", str(tmp_path / "absent.txt")
+    )
+    assert missing.returncode == 2
+    assert "file not found" in missing.stderr
+
+
+def test_folder_outside_git_is_refused(tmp_path: Path) -> None:
+    completed = run_audit(str(tmp_path))
+    assert completed.returncode == 2
+    assert "not a git checkout" in completed.stderr

package/bin/ever-shipped-skills.mjs

@@ -18,6 +18,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'condensing-instructions',
     'codex-review',
     'codex-cleanse',
+    'context-audit',
     'context7-mcp',
     'copilot-finding-triage',
     'copilot-review',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.62.1",
+    "version": "8.63.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {