crapkit 0.2.0__py3-none-any.whl

crapkit/discover.py

@@ -0,0 +1,365 @@
+"""Discovery helpers for the start-editing packet: who calls a function, which
+tests sit beside a file, and which guide files govern it.
+
+Three standalone questions, answered off the working tree and git's index. Every
+answer is sorted and every lookup is batched: one `git grep` per call whatever
+the length of the identifier list, one directory listing per directory whatever
+the number of glob patterns. Nothing here imports the CLI.
+"""
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+import subprocess
+from collections.abc import Iterable, Mapping
+from pathlib import Path, PurePosixPath
+from typing import NamedTuple
+
+from .errors import GitError
+
+CALLER_CAP = 20
+_GUIDES = ("AGENTS.md", "CLAUDE.md", "CONTRIBUTING.md")
+_SUPPORT_PATTERNS = ("conftest.py", "*.test-support.*")
+_SUPPORT_DIRS = ("fixtures", "factories")
+_EXPORT_STARTS = ("export ", "export{", "import ", "import{", "from ",
+                  "module.exports", "exports.")
+_DEF_MODIFIERS = (r"(?:@|export\s+|default\s+|public\s+|private\s+|protected\s+"
+                  r"|static\s+|async\s+)*")
+
+
+class _Hit(NamedTuple):
+    path: str
+    line: int
+    text: str
+
+
+def _relative(path) -> PurePosixPath:
+    """Repo-relative and posix, whichever slash the caller happened to hold."""
+    return PurePosixPath(str(path).replace("\\", "/"))
+
+
+def _read(root: Path, path: str) -> str:
+    """One file's text, or "" when it is gone.
+
+    utf-8 explicitly: a bare open() reads cp1252 on Windows and utf-8 in a
+    container, which is one repo answering two ways.
+    """
+    try:
+        return (root / path).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def _upward(directory: PurePosixPath) -> list[PurePosixPath]:
+    """The directory and every parent up to the repo root, nearest first."""
+    return list(dict.fromkeys([directory, *directory.parents]))
+
+
+def _guides_in(root: Path, directory: PurePosixPath) -> list[str]:
+    return [str(directory / name) for name in _GUIDES
+            if (root / directory / name).is_file()]
+
+
+def nearest_guides(root, path) -> list[str]:
+    """The AGENTS.md, CLAUDE.md and CONTRIBUTING.md files governing `path`.
+
+    Walks up from the file's own directory to the repo root, nearest first, so
+    the closest instruction an editor has to obey comes first. Within one
+    directory the fixed name order breaks the tie.
+    """
+    root = Path(root)
+    found: list[str] = []
+    for directory in _upward(_relative(path).parent):
+        found += _guides_in(root, directory)
+    return found
+
+
+# --- the tests and support files beside one source ----------------------------
+
+def _entries(directory: Path) -> list[str]:
+    """The file names in one directory, sorted; a directory that is not there is
+    an empty answer, not a failure.
+
+    THE batching seam. Every glob pattern is matched against this one list, so a
+    directory is read once per call however many patterns ask about it.
+    """
+    try:
+        with os.scandir(directory) as scan:
+            return sorted(e.name for e in scan if e.is_file())
+    except OSError:
+        return []
+
+
+def _matching(names: list[str], patterns: Iterable[str]) -> list[str]:
+    return [n for n in names if any(fnmatch.fnmatchcase(n, p) for p in patterns)]
+
+
+def _under(directory: PurePosixPath, names: list[str]) -> list[str]:
+    return [str(directory / n) for n in names]
+
+
+def _test_patterns(stem: str, suffix: str) -> tuple[str, ...]:
+    """The four sibling namings, in the source's own extension: send.ts asks
+    about send*.test.ts and send*.spec.ts, parse.py about test_parse*.py and
+    parse*_test.py. None of them can match the source itself."""
+    return (f"{stem}*.test{suffix}", f"{stem}*.spec{suffix}",
+            f"test_{stem}*{suffix}", f"{stem}*_test{suffix}")
+
+
+def _nested_tests(root: Path, directory: PurePosixPath, stem: str) -> list[str]:
+    """__tests__/send* — the sibling directory JS projects keep tests in."""
+    nested = directory / "__tests__"
+    return _under(nested, _matching(_entries(root / nested), (f"{stem}*",)))
+
+
+def _support(root: Path, directory: PurePosixPath, own: list[str]) -> list[str]:
+    """What a test in this directory leans on: the same-directory support names,
+    plus everything one level down in fixtures/ and factories/."""
+    found = _under(directory, _matching(own, _SUPPORT_PATTERNS))
+    for name in _SUPPORT_DIRS:
+        found += _under(directory / name, _entries(root / directory / name))
+    return sorted(found)
+
+
+def related_tests(root, path) -> dict[str, list[str]]:
+    """The tests that sit beside `path`, and the support files they lean on.
+
+    Sibling globs on the source stem in the source's own extension, plus the
+    __tests__ directory next to it. Both lists are repo-relative and sorted, so
+    two runs of a packet agree.
+    """
+    root = Path(root)
+    rel = _relative(path)
+    directory = rel.parent
+    own = _entries(root / directory)
+    tests = _under(directory, _matching(own, _test_patterns(rel.stem, rel.suffix)))
+    return {"tests": sorted(tests + _nested_tests(root, directory, rel.stem)),
+            "support": _support(root, directory, own)}
+
+
+# --- who calls one identifier -------------------------------------------------
+
+def _grep_output(root: Path, args: list[str]) -> str:
+    """One `git grep`, run for its output.
+
+    Exit 1 is git's way of saying nothing matched, which is an answer rather
+    than a failure; anything above that is a broken command.
+    """
+    try:
+        proc = subprocess.run(["git", "grep", *args], cwd=root, capture_output=True,
+                              text=True, encoding="utf-8", errors="replace")
+    except FileNotFoundError as exc:
+        raise GitError("git executable not found") from exc
+    if proc.returncode > 1:
+        raise GitError(f"git grep failed in {root}: {proc.stderr.strip()}")
+    return proc.stdout
+
+
+def _flat_paths(scope_paths) -> list[str]:
+    """crapkit's config holds scope paths as {scope: (path, ...)}; a caller with
+    a plain list of paths means the same thing."""
+    if isinstance(scope_paths, Mapping):
+        return [p for paths in scope_paths.values() for p in paths]
+    return list(scope_paths or ())
+
+
+def _pathspecs(scope_paths) -> list[str]:
+    return sorted(set(_flat_paths(scope_paths)))
+
+
+def _grep_args(identifiers: list[str], scope_paths) -> list[str]:
+    """-F because an identifier is a literal, and one -e per name because fixed
+    strings have no alternation. However long the list, this is ONE command."""
+    patterns = [arg for name in identifiers for arg in ("-e", name)]
+    scoped = _pathspecs(scope_paths)
+    limit = ["--", *scoped] if scoped else []
+    return ["-n", "-I", "-F", "--full-name", "--no-color", *patterns, *limit]
+
+
+def _is_test_path(path: str) -> bool:
+    """Test file or not, by the rule cli.verifying._is_test_path applies: a
+    test/tests/__tests__ directory segment, a test_ prefix, or a .test./.spec.
+    infix. Written twice on purpose — this module imports nothing from the CLI —
+    and pinned by a test that routes the same paths through both.
+    """
+    parts = path.lower().split("/")
+    return (any(p in ("test", "tests", "__tests__") for p in parts[:-1])
+            or parts[-1].startswith("test_")
+            or ".test." in parts[-1] or ".spec." in parts[-1])
+
+
+def _parse_hit(raw: str) -> _Hit | None:
+    """`path:line:text`, the one shape `git grep -n` emits."""
+    path, _, rest = raw.partition(":")
+    number, _, text = rest.partition(":")
+    return _Hit(path.replace("\\", "/"), int(number), text) if number.isdigit() else None
+
+
+def _hits(root: Path, identifiers: list[str], scope_paths) -> list[_Hit]:
+    """Every match for every name, out of ONE `git grep`.
+
+    git names no pattern in its output, so which name a line answers is settled
+    by the word match below, not by the command. Test files are dropped here: a
+    call from a test is not a caller a change has to answer to.
+    """
+    lines = _grep_output(root, _grep_args(identifiers, scope_paths)).splitlines()
+    parsed = [_parse_hit(line) for line in lines]
+    return [h for h in parsed if h is not None and not _is_test_path(h.path)]
+
+
+def _word(identifier: str) -> re.Pattern[str]:
+    return re.compile(r"(?<![A-Za-z0-9_])" + re.escape(identifier) + r"(?![A-Za-z0-9_])")
+
+
+def _indent(line: str) -> int:
+    return len(line) - len(line.lstrip())
+
+
+def _def_pattern(identifier: str) -> re.Pattern[str]:
+    """A line that DEFINES the name: the keyword forms of both language
+    families, plus the method shorthand a class body uses."""
+    name = re.escape(identifier)
+    return re.compile(r"^\s*" + _DEF_MODIFIERS
+                      + r"(?:(?:def|class|function|const|let|var)\s+" + name + r"\b"
+                      + r"|" + name + r"\s*\([^)]*\)\s*[:{])")
+
+
+def _def_line(lines: list[str], identifier: str) -> int | None:
+    pattern = _def_pattern(identifier)
+    for number, line in enumerate(lines, start=1):
+        if pattern.search(line):
+            return number
+    return None
+
+
+def _span_end(lines: list[str], start: int) -> int:
+    """The last line of the block opened at `start`: everything up to the next
+    non-blank line indented no deeper than the definition.
+
+    Indentation ends a Python body and a braced body alike — the closing brace
+    sits at the definition's own indent, and a closing brace holds no
+    identifier, so stopping just before it costs nothing.
+    """
+    opened = _indent(lines[start - 1])
+    for i in range(start, len(lines)):
+        if lines[i].strip() and _indent(lines[i]) <= opened:
+            return i
+    return len(lines)
+
+
+def _defining_span(lines: list[str], identifier: str) -> tuple[int, int] | None:
+    """The 1-based line range this file defines the name over, or None when it
+    does not define it at all."""
+    start = _def_line(lines, identifier)
+    return None if start is None else (start, _span_end(lines, start))
+
+
+def _is_export_line(stripped: str) -> bool:
+    return stripped.startswith(_EXPORT_STARTS) or "__all__" in stripped
+
+
+def _opens_a_list(stripped: str) -> bool:
+    """A declaration whose names are on the FOLLOWING lines.
+
+    The bracket is the last thing on the line and no argument list closed just
+    before it, which is what separates `export {` and `__all__ = [` from
+    `export function send(x) {`. Counting brackets instead swallowed every
+    function body under an export line, and every local name in one read as
+    exported.
+    """
+    return (stripped.endswith(("[", "(", "{"))
+            and not stripped.rstrip("[({ ").endswith(")"))
+
+
+def _closes_a_list(stripped: str) -> bool:
+    """The closer opens its own line in every formatter that wraps a list."""
+    return stripped.startswith(("]", ")", "}"))
+
+
+def _export_lines(lines: list[str]) -> list[str]:
+    """The file's export surface: the export and import statements, plus the
+    body of a list one of them opens. Computed once per call and reused by every
+    identifier in the batch."""
+    out: list[str] = []
+    inside = False
+    for raw in lines:
+        stripped = raw.strip()
+        if not inside and not _is_export_line(stripped):
+            continue
+        out.append(stripped)
+        inside = _opens_a_list(stripped) if not inside else not _closes_a_list(stripped)
+    return out
+
+
+def _exported(export_lines: list[str], identifier: str) -> bool:
+    word = _word(identifier)
+    return any(word.search(line) for line in export_lines)
+
+
+def _in_span(hit: _Hit, path: str, span: tuple[int, int] | None) -> bool:
+    """A definition and its own body are not calls to itself."""
+    return span is not None and hit.path == path and span[0] <= hit.line <= span[1]
+
+
+def _found(hits: list[_Hit], identifier: str, path: str,
+           span: tuple[int, int] | None) -> list[dict]:
+    word = _word(identifier)
+    kept = [h for h in hits if word.search(h.text) and not _in_span(h, path, span)]
+    kept.sort(key=lambda h: (h.path, h.line))
+    return [{"path": h.path, "line": h.line} for h in kept]
+
+
+def _answer(hits: list[_Hit], identifier: str, path: str, lines: list[str],
+            exports: list[str]) -> dict:
+    found = _found(hits, identifier, path, _defining_span(lines, identifier))
+    return {"count": len(found), "callers": found[:CALLER_CAP],
+            "exported": _exported(exports, identifier)}
+
+
+def _names(identifier) -> list[str]:
+    """The names to ask about, deduplicated in asked-about order.
+
+    A blank one never gets through: `git grep -e ""` matches every line in the
+    repo, and thousands of callers is a wrong answer rather than an error.
+    """
+    raw = [identifier] if isinstance(identifier, str) else list(identifier)
+    return list(dict.fromkeys(n for n in raw if n and n.strip()))
+
+
+def _empty_answer() -> dict:
+    return {"count": 0, "callers": [], "exported": False}
+
+
+def _answers(root: Path, scope_paths, path: str, names: list[str]) -> dict[str, dict]:
+    """One grep and one read of the defining file, however many names.
+
+    Nothing to ask about spawns nothing: `git grep` with no -e is a usage error.
+    """
+    if not names:
+        return {}
+    lines = _read(root, path).splitlines()
+    exports = _export_lines(lines)
+    hits = _hits(root, names, scope_paths)
+    return {n: _answer(hits, n, path, lines, exports) for n in names}
+
+
+def callers(root, scope_paths, path, identifier):
+    """Who calls `identifier`, which `path` defines.
+
+    ONE `git grep` per call whatever `identifier` is: a str asks about one name
+    and returns that name's answer, a list asks about many and returns
+    {name: answer}. The list form IS the cache a packet wants — twelve functions
+    of one file cost one process and one read of that file, not twelve of each,
+    and every name reads the same grep output.
+
+    Neither test files nor the definition's own body count as callers, and each
+    name is measured against its OWN span, so a helper called from the function
+    above it in the same file is a caller. `count` is the whole number found;
+    `callers` stops at 20.
+    """
+    answers = _answers(Path(root), scope_paths, str(_relative(path)),
+                       _names(identifier))
+    if not isinstance(identifier, str):
+        return answers
+    return answers.get(identifier, _empty_answer())

crapkit/doctor.py

@@ -0,0 +1,308 @@
+"""`crapkit doctor` checks: does crapkit.toml still describe THIS repo? Pure."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import NamedTuple
+
+_KNOWN = {
+    "": {"crapkit", "scope", "lane", "exclude"},
+    "crapkit": {"target", "churn_window_months", "worklist_floor", "worklist_top",
+                "ratchet_file", "alert_command", "scoped_tests", "notes",
+                "mutation_command", "mutation_timeout_seconds", "mutation_workers",
+                "diff_uncovered_max", "debt_max_age_months", "repayment_min_per_30d",
+                "max_parallel_lanes", "analysis_workers"},
+    "scope": {"name", "paths", "languages", "target", "coverage_optional", "notes"},
+    "lane": {"name", "command", "artifact", "parser", "scopes", "cwd", "path_prefix", "env",
+             "full_suite", "container_ok", "results_artifact", "timeout_seconds", "retries",
+             "retest_command"},
+    "exclude": {"globs", "max_file_bytes"},
+}
+
+
+_ARRAY_TABLES = frozenset({"scope", "lane"})
+
+
+class UnknownKey(NamedTuple):
+    """One ignored key. The table travels with it: without it the reader cannot
+    be told which spellings would have been accepted."""
+    path: str   # dotted, as printed: "crapkit.churn_windo_months"
+    table: str  # a key of _KNOWN; "" is the top level
+
+
+# Sorted once at import, not once per rejected key: every unknown-key message
+# quotes its whole table, so a config with twenty typos in [crapkit] sorted the
+# same fifteen strings twenty times.
+_VALID_KEYS = {table: tuple(sorted(keys)) for table, keys in _KNOWN.items()}
+
+
+def valid_keys(table: str) -> tuple[str, ...]:
+    """Everything crapkit reads in one table, sorted so a message never moves."""
+    return _VALID_KEYS[table]
+
+
+def table_label(table: str) -> str:
+    """How the table is spelled in crapkit.toml. Arrays of tables double their
+    brackets, so a suggestion can be pasted as written."""
+    if not table:
+        return "crapkit.toml"
+    return f"[[{table}]]" if table in _ARRAY_TABLES else f"[{table}]"
+
+
+def _unknown_in(table: str, mapping: dict, label: str) -> list[UnknownKey]:
+    return [UnknownKey(f"{label}.{key}" if label else key, table)
+            for key in mapping if key not in _KNOWN[table]]
+
+
+def unknown_key_findings(raw: dict) -> list[UnknownKey]:
+    """Keys crapkit silently ignores — usually typos — each with its table. The
+    loader stays lenient (a config must survive version skew); doctor is where
+    typos die."""
+    problems = _unknown_in("", raw, "")
+    for table in ("crapkit", "exclude"):
+        problems += _unknown_in(table, raw.get(table, {}), table)
+    for table in ("scope", "lane"):
+        for row in raw.get(table, ()):
+            problems += _unknown_in(table, row, f"{table} {row.get('name', '?')!r}")
+    return problems
+
+
+class Finding(NamedTuple):
+    """One doctor line. FAIL decides the exit code, WARN never does, and an
+    empty level is a continuation line (the file list under a scope)."""
+    level: str
+    text: str
+
+
+_NO_TEMPLATE = (
+    "scope {name!r} has a lane but no [crapkit.scoped_tests] template — "
+    "`crapkit test-scoped` exits 3 on its files, so whoever edits them is handed "
+    'no command to run their tests; add {name} = "<test command>" under '
+    "[crapkit.scoped_tests]"
+)
+
+
+def scoped_test_gaps(lanes, scoped_tests) -> tuple[Finding, ...]:
+    """Scopes a lane measures that `crapkit test-scoped` cannot run, sorted. WARN.
+
+    Nothing is broken here: the lane runs, coverage lands, the gate holds. What
+    is missing is the one command a start-editing packet can hand over, and the
+    gap otherwise surfaces as an exit 3 in the middle of somebody's edit.
+
+    The lanes are walked once, not once per scope: a config declaring a lane per
+    package has more lanes than scopes, and this is a doctor line, not a survey.
+    """
+    templated = {scope for scope, _template in scoped_tests}
+    laned = {scope for lane in lanes for scope in lane.scopes}
+    return tuple(Finding("WARN", _NO_TEMPLATE.format(name=name))
+                 for name in sorted(laned - templated))
+
+
+class Knobs(NamedTuple):
+    max_parallel_lanes: int
+    analysis_workers: int
+    mutation_workers: int
+
+
+def suggest_knobs(*, cpus: int, lanes: int) -> Knobs:
+    """Advisory parallelism for this machine.
+
+    One core stays for the shell watching the run. A lane and a mutation worker
+    each hold a whole test suite in memory, so they get a quarter of the box
+    rather than a core apiece, and there is never a reason to run more lane
+    slots than there are lanes.
+    """
+    return Knobs(max_parallel_lanes=max(1, min(lanes, cpus // 4)),
+                 analysis_workers=max(1, cpus - 1),
+                 mutation_workers=max(1, cpus // 4))
+
+
+def parallel_seconds(durations: tuple[float, ...], slots: int) -> float:
+    """Makespan of these lanes on `slots` runners, longest first (LPT).
+
+    A bound, never a promise: lanes contend for the same cores and disk. It is
+    exact for the handful of lanes a real config declares.
+    """
+    ends = [0.0] * max(1, slots)
+    for seconds in sorted(durations, reverse=True):
+        ends[ends.index(min(ends))] += seconds
+    return max(ends)
+
+
+def _cost_line(slots: int, durations: tuple[float, ...]) -> str:
+    if not durations:
+        return "# lane cost: no durations recorded yet — suggested from the cpu count alone"
+    return (f"# lane cost: {sum(durations):.1f}s serial -> "
+            f"~{parallel_seconds(durations, slots):.1f}s across {slots} lane slot(s)")
+
+
+def tune_lines(*, cpus: int, knobs: Knobs, durations: tuple[float, ...]) -> list[str]:
+    """Paste-ready [crapkit] knob lines plus what the suggestion was based on."""
+    return [f"# doctor --tune: suggestions for {cpus} cpu(s); nothing was written",
+            "[crapkit]",
+            f"max_parallel_lanes = {knobs.max_parallel_lanes}",
+            f"analysis_workers = {knobs.analysis_workers}",
+            f"mutation_workers = {knobs.mutation_workers}",
+            _cost_line(knobs.max_parallel_lanes, durations)]
+
+
+class ArtifactLitter(NamedTuple):
+    """One lane output written outside .crapkit/. The lane travels with the path
+    because a tree with fifteen coverage directories in it cannot say which lane
+    made which."""
+    lane: str
+    path: str
+
+
+_STORE_DIR = ".crapkit"
+
+
+def _first_part(path: str) -> str:
+    return path.replace("\\", "/").partition("/")[0]
+
+
+def scope_top_dirs(scopes) -> frozenset[str]:
+    """The top-level directory of every declared scope path.
+
+    A lane that writes inside a package it measures (web/coverage/ beside
+    web/src) is that package's business, not root litter.
+    """
+    return frozenset(_first_part(path) for scope in scopes for path in scope.paths)
+
+
+def _artifact_top(path: str) -> str:
+    """The top-level directory this artifact lands in, or "" for a repo-root
+    file — which has no directory to be excused by."""
+    normalized = path.replace("\\", "/")
+    return _first_part(normalized) if "/" in normalized else ""
+
+
+def _lane_outputs(lane) -> tuple[str, ...]:
+    return tuple(path for path in (lane.artifact, lane.results_artifact) if path)
+
+
+def artifact_litter(lanes, scope_tops: frozenset[str]) -> tuple[ArtifactLitter, ...]:
+    """Lane outputs that dirty the consumer's tree: a file at the repo root, or a
+    top-level directory that is neither .crapkit/ nor a scope's own tree.
+
+    Reported per path, in declaration order: a lane arguing about its coverage
+    file usually drops a junit report beside it, and folding the two into one
+    finding leaves the second one unnamed.
+    """
+    clean = {_STORE_DIR, *scope_tops}
+    return tuple(ArtifactLitter(lane.name, path) for lane in lanes
+                 for path in _lane_outputs(lane) if _artifact_top(path) not in clean)
+
+
+_PLAIN_FILE_MODE = "100644"  # git's non-executable file; 100755 is the armed one
+
+
+def non_executable_hooks(modes: dict[str, str]) -> tuple[str, ...]:
+    """Committed hook files git will silently skip, in path order.
+
+    A hook whose index mode is 100644 does not run on Linux or macOS, so
+    `core.hooksPath` installs a gate that never fires. Only plain files are
+    reported: a symlink (120000) or a gitlink (160000) is not a mode
+    `git update-index --chmod=+x` would fix.
+    """
+    return tuple(sorted(path for path, mode in modes.items()
+                        if mode == _PLAIN_FILE_MODE))
+
+
+class UnmeasuredDir(NamedTuple):
+    directory: str
+    functions: int
+    example_test: str
+
+
+@dataclass
+class _DirStats:
+    functions: int = 0
+    flags: set = field(default_factory=set)
+    stems: set = field(default_factory=set)
+
+
+_TEST_DIR_PARTS = frozenset({"test", "tests", "__tests__", "spec", "specs"})
+
+
+def _dir_of(path: str) -> str:
+    return path.rpartition("/")[0]
+
+
+def _stem_of(path: str) -> str:
+    return path.rsplit("/", 1)[-1].split(".")[0]
+
+
+def _subject_stem(path: str) -> str | None:
+    """The source stem a test file names, or None when the name is not a test.
+    Four conventions cover every runner crapkit parses: foo.test.ts, foo.spec.ts,
+    test_foo.py, foo_test.py."""
+    name = path.rsplit("/", 1)[-1]
+    stem = _stem_of(path)
+    if ".test." in name or ".spec." in name:
+        return stem
+    if stem.startswith("test_"):
+        return stem[len("test_"):]
+    if stem.endswith("_test"):
+        return stem[:-len("_test")]
+    return None
+
+
+def _path_parts(path: str) -> tuple[str, ...]:
+    return tuple(p for p in path.split("/") if p)
+
+
+def _mirrored_parts(test_dir: str) -> tuple[str, ...]:
+    return tuple(p for p in _path_parts(test_dir) if p not in _TEST_DIR_PARTS)
+
+
+def _mirrors(test_dir: str, source_dir: str) -> bool:
+    """A tests/ mirror: the test directory, with its test-named components
+    dropped, is a path suffix of the source directory. tests/api mirrors src/api;
+    a flat tests/ mirrors nothing, or it would claim the whole repo."""
+    parts = _mirrored_parts(test_dir)
+    return parts == _path_parts(source_dir)[-len(parts):] if parts else False
+
+
+def _test_files(tracked: list[str]) -> list[str]:
+    return sorted(p for p in tracked if _subject_stem(p))
+
+
+def _matching_test(directory: str, stems: set, test_files: list[str]) -> str | None:
+    """The first tracked test file that names this directory's code: a same-stem
+    test anywhere in the repo (tests/test_parser.py for core/parser.py),
+    a sibling, or a tests/ mirror of the directory."""
+    for path in test_files:
+        if _subject_stem(path) in stems or _mirrors(_dir_of(path), directory):
+            return path
+    return None
+
+
+def _group_dirs(rows, skip_scopes: frozenset[str]) -> dict[str, _DirStats]:
+    stats: dict[str, _DirStats] = {}
+    for row in rows:
+        if row.scope in skip_scopes:
+            continue
+        entry = stats.setdefault(_dir_of(row.path), _DirStats())
+        entry.functions += 1
+        entry.flags.add(row.flag)
+        entry.stems.add(_stem_of(row.path))
+    return stats
+
+
+def unmeasured_directories(rows, tracked: list[str], *,
+                           skip_scopes: frozenset[str] = frozenset()) -> tuple[UnmeasuredDir, ...]:
+    """Directories where EVERY scored function is flag "untested" and a test file
+    for that directory exists anyway.
+
+    That combination is a tooling gap, not a testing gap: the lane runs, the
+    tests pass, and the lane's own include list never looks at this code. One
+    measured function anywhere in the directory clears it.
+    """
+    test_files = _test_files(tracked)
+    found = []
+    for directory, stats in sorted(_group_dirs(rows, skip_scopes).items()):
+        example = _matching_test(directory, stats.stems, test_files) \
+            if stats.flags == {"untested"} else None
+        if example:
+            found.append(UnmeasuredDir(directory, stats.functions, example))
+    return tuple(found)