@theglitchking/babel-fish 2.0.2 → 2.3.0

package/.claude/project-map/mine-sessions.py

@@ -31,6 +31,9 @@ from pathlib import Path
 # ── Paths ────────────────────────────────────────────────────────────────────
 SCRIPT_DIR   = Path(__file__).parent
 LEARNED_VOC  = SCRIPT_DIR / "learned-vocabulary.json"
+# Incremental cursor. Not merely a cost guard: merge_learned() ADDS scores, so
+# re-mining an already-counted transcript inflates it without bound.
+MINE_CURSOR  = SCRIPT_DIR / ".mine-cursor.json"
 PROJECT_ROOT = SCRIPT_DIR.parent.parent
 
 # ── Config ───────────────────────────────────────────────────────────────────
@@ -41,6 +44,7 @@ RECENCY_WINDOWS  = [       # (days_threshold, weight)
     (90,  0.25),
 ]
 MAX_ALIAS_WORDS  = 6       # Ignore user phrases longer than this
+MAX_LOOKAHEAD    = 120     # Messages scanned after a user turn for file activity
 MIN_ALIAS_WORDS  = 1
 STOP_WORDS = {
     'the', 'a', 'an', 'this', 'that', 'these', 'those', 'it', 'its',
@@ -61,6 +65,9 @@ FILE_TOOL_NAMES = {
     'read_file', 'edit_file', 'write_file',
 }
 
+# Tools whose arguments are a shell command rather than a file path.
+BASH_TOOL_NAMES = {'Bash', 'bash', 'run_command'}
+
 # ── Recency weight ────────────────────────────────────────────────────────────
 
 def recency_weight(session_date: datetime) -> float:
@@ -80,23 +87,27 @@ def find_session_files(project_root: Path) -> list[Path]:
     """Find Claude Code JSONL session files for this project."""
     candidates: list[Path] = []
 
-    # ~/.claude/projects/ uses a path-encoded slug
-    # e.g. /mnt/e/the-glitch-kingdom/babel-fish → -mnt-e-the-glitch-kingdom-babel-fish
-    encoded = str(project_root).replace('/', '-').lstrip('-')
+    # ~/.claude/projects/ uses a path-encoded slug that KEEPS the leading
+    # separator: /home/u/proj → -home-u-proj. Stripping it (the old
+    # .lstrip('-')) meant the exact match never once hit, and every lookup
+    # silently fell through to the fuzzy branch below.
+    encoded = str(project_root).replace('/', '-')
     claude_projects = Path.home() / '.claude' / 'projects'
 
     if not claude_projects.exists():
         return []
 
-    # Try exact match first
     exact = claude_projects / encoded
     if exact.is_dir():
-        candidates.extend(sorted(exact.glob('*.jsonl')))
+        return sorted(exact.glob('*.jsonl'))
 
-    # Also try fuzzy match on project name
+    # Fallback only when the exact directory is absent. Substring matching on
+    # the bare project name is not safe as an addition: "kentro" matches four
+    # unrelated project directories, whose aliases would then be attributed to
+    # this repo.
     project_name = project_root.name.lower()
-    for d in claude_projects.iterdir():
-        if d.is_dir() and project_name in d.name.lower() and d != exact:
+    for d in sorted(claude_projects.iterdir()):
+        if d.is_dir() and project_name in d.name.lower():
             candidates.extend(sorted(d.glob('*.jsonl')))
 
     return candidates
@@ -134,14 +145,81 @@ def extract_session_date(messages: list[dict]) -> datetime | None:
     return None
 
 
+# ── JSONL shape helpers ───────────────────────────────────────────────────────
+# Claude Code nests the API message under a "message" key: the role and content
+# live at msg["message"]["role"] / ["content"], not at the top level. Reading the
+# top level yielded 0 tool_use blocks and 0 user messages from a real 1.8 MB
+# transcript (see issue #7). Both shapes are accepted so older or third-party
+# transcripts still parse.
+
+def msg_content(msg: dict):
+    inner = msg.get('message')
+    if isinstance(inner, dict) and inner.get('content') is not None:
+        return inner['content']
+    return msg.get('content')
+
+
+def msg_role(msg: dict) -> str:
+    inner = msg.get('message')
+    if isinstance(inner, dict) and inner.get('role'):
+        return str(inner['role'])
+    return str(msg.get('role') or msg.get('type') or '')
+
+
+def is_user_turn(msg: dict) -> bool:
+    """A real user message, not a tool_result carrier.
+
+    Tool results are delivered with role="user": in a real transcript 167 of 181
+    role=user messages were tool_result blocks. Treating those as user turns
+    made the pairing window close on the assistant's own tool output.
+    """
+    if msg_role(msg) not in ('user', 'human'):
+        return False
+    # isMeta marks machine-injected text delivered in the user slot: skill
+    # bodies, slash-command definitions, hook output. Mining it learned aliases
+    # from the injected docs themselves ("block_index_edits", "superseded by v2
+    # guide", "refactor authentication system" — the last from a skill's own
+    # example). isSidechain marks subagent transcripts, which are not the user
+    # speaking either.
+    if msg.get('isMeta') or msg.get('isSidechain'):
+        return False
+    content = msg_content(msg)
+    if isinstance(content, str):
+        return bool(content.strip())
+    if isinstance(content, list):
+        return any(isinstance(b, dict) and b.get('type') == 'text' for b in content)
+    return False
+
+
+# Bash-mediated file access. A real session ran 148 Bash calls against 2 Read
+# and 2 Edit, so a miner that only understands the file tools sees almost
+# nothing. Candidate tokens are only accepted when they resolve to a file that
+# actually exists in the repo — a wrong alias asserted confidently is worse than
+# a missing one, so no cleverer shell parsing than this.
+BASH_TOKEN_RE = re.compile(r'[\w./-]*[\w-]\.[A-Za-z0-9]{1,6}\b')
+
+
+def extract_paths_from_bash(command: str, project_root: Path) -> list[str]:
+    out = []
+    for tok in BASH_TOKEN_RE.findall(command or ''):
+        tok = tok.strip("'\"()[]{},;:").lstrip('./')
+        if not tok or tok.startswith('-'):
+            continue
+        try:
+            if (project_root / tok).is_file():
+                out.append(tok)
+        except OSError:
+            pass
+    return out
+
+
 # ── Alias extraction ──────────────────────────────────────────────────────────
 
 def extract_file_paths_from_tool_calls(messages: list[dict]) -> list[str]:
     """Extract file paths from tool use calls in a message sequence."""
     paths = []
     for msg in messages:
-        # Handle various JSONL formats
-        content = msg.get('content') or []
+        content = msg_content(msg) or []
         if isinstance(content, str):
             continue
         for block in content:
@@ -150,6 +228,10 @@ def extract_file_paths_from_tool_calls(messages: list[dict]) -> list[str]:
             if block.get('type') not in ('tool_use', 'tool_result'):
                 continue
             tool_name = block.get('name', '')
+            inp_early = block.get('input') or {}
+            if tool_name in BASH_TOOL_NAMES and isinstance(inp_early, dict):
+                paths.extend(extract_paths_from_bash(inp_early.get('command', ''), PROJECT_ROOT))
+                continue
             if tool_name not in FILE_TOOL_NAMES:
                 continue
             # Extract file_path from input
@@ -181,14 +263,14 @@ def extract_user_phrases(text: str) -> list[str]:
 
     # "the X" / "the X page/screen/section/tab/view/panel/modal/form/button"
     for m in re.finditer(
-        r'\bthe\s+([\w\s-]{2,40?}?)\s*(?:page|screen|section|tab|view|panel|modal|form|button|component|widget|dashboard|list|table|chart|graph|map|sidebar|header|footer|nav|menu)\b',
+        r'\bthe\s+([\w\s-]{2,40}?)\s*(?:page|screen|section|tab|view|panel|modal|form|button|component|widget|dashboard|list|table|chart|graph|map|sidebar|header|footer|nav|menu)\b',
         text, re.IGNORECASE
     ):
         phrases.append(m.group(1).lower().strip())
 
     # "X feature" / "X functionality" / "X system" / "X module"
     for m in re.finditer(
-        r'\b([\w\s-]{2,30?}?)\s+(?:feature|functionality|system|module|service|flow|workflow|pipeline|process)\b',
+        r'\b([\w\s-]{2,30}?)\s+(?:feature|functionality|system|module|service|flow|workflow|pipeline|process)\b',
         text, re.IGNORECASE
     ):
         candidate = m.group(1).lower().strip()
@@ -199,7 +281,17 @@ def extract_user_phrases(text: str) -> list[str]:
     # Filter: remove stop-word-only phrases, too short/long
     result = []
     for phrase in phrases:
-        words = [w for w in phrase.split() if w not in STOP_WORDS and len(w) > 1]
+        # Sentence punctuation means this is a clause, not a name for something
+        # ("that, if not", "total documents:"). Aliases don't contain it.
+        if any(ch in phrase for ch in ',:;?!'):
+            continue
+        # Strip punctuation BEFORE the stop-word test — otherwise "that," fails
+        # to match the stop word "that" and survives as an alias.
+        words = [w.strip('.\'"`()[]{}<>*_-') for w in phrase.split()]
+        words = [w for w in words if w and w not in STOP_WORDS and len(w) > 1]
+        # At least one substantial word, so "up to" and "as is" don't qualify.
+        if not any(len(w) >= 3 for w in words):
+            continue
         if MIN_ALIAS_WORDS <= len(words) <= MAX_ALIAS_WORDS:
             clean = ' '.join(words)
             if clean and clean not in result:
@@ -241,12 +333,11 @@ class SessionMiner:
 
         # Walk messages in pairs: look for user message followed by tool calls
         for i, msg in enumerate(messages):
-            role = msg.get('role') or msg.get('type') or ''
-            if role not in ('user', 'human'):
+            if not is_user_turn(msg):
                 continue
 
             # Extract text from this user message
-            content = msg.get('content') or ''
+            content = msg_content(msg) or ''
             if isinstance(content, list):
                 text_parts = []
                 for block in content:
@@ -261,14 +352,13 @@ class SessionMiner:
             if len(text) < 5:
                 continue
 
-            # Find tool calls in subsequent assistant messages (within next 3 messages)
+            # Everything the assistant touched before the next real user turn.
+            # Bounded by MAX_LOOKAHEAD so one runaway turn can't scan the file.
             file_paths: list[str] = []
-            for j in range(i + 1, min(i + 4, len(messages))):
-                next_msg = messages[j]
-                next_role = next_msg.get('role') or next_msg.get('type') or ''
-                if next_role in ('user', 'human') and j > i + 1:
-                    break  # New user turn — stop looking
-                file_paths.extend(extract_file_paths_from_tool_calls([next_msg]))
+            for j in range(i + 1, min(i + 1 + MAX_LOOKAHEAD, len(messages))):
+                if is_user_turn(messages[j]):
+                    break
+                file_paths.extend(extract_file_paths_from_tool_calls([messages[j]]))
 
             if not file_paths:
                 continue
@@ -353,11 +443,27 @@ def decay_old_entries(vocab: dict) -> dict:
 
 # ── Main ──────────────────────────────────────────────────────────────────────
 
+def load_cursor() -> float:
+    try:
+        return float(json.loads(MINE_CURSOR.read_text()).get('last_mined_mtime', 0.0))
+    except Exception:
+        return 0.0
+
+
+def save_cursor(mtime: float) -> None:
+    try:
+        MINE_CURSOR.write_text(json.dumps({'last_mined_mtime': mtime}, indent=2))
+    except OSError:
+        pass
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(description='Mine Claude Code sessions for vocabulary aliases')
     parser.add_argument('--project-root', type=Path, default=None)
     parser.add_argument('--dry-run', action='store_true', help='Print results without saving')
     parser.add_argument('--verbose', '-v', action='store_true', help='Show per-file details')
+    parser.add_argument('--all', action='store_true',
+                        help='Ignore the incremental cursor and re-mine every transcript')
     args = parser.parse_args()
 
     global PROJECT_ROOT
@@ -381,6 +487,17 @@ def main() -> None:
 
     print(f"[mine-sessions] Found {len(session_files)} session file(s)")
 
+    # Only transcripts touched since the last run. Without this, every session
+    # start re-reads the whole history AND re-adds its scores.
+    cursor = 0.0 if args.all else load_cursor()
+    newest = max((f.stat().st_mtime for f in session_files), default=0.0)
+    if cursor:
+        session_files = [f for f in session_files if f.stat().st_mtime > cursor]
+        if not session_files:
+            print("[mine-sessions] No transcripts changed since last run — nothing to do")
+            sys.exit(0)
+        print(f"[mine-sessions] {len(session_files)} changed since last run")
+
     # Mine
     miner = SessionMiner(PROJECT_ROOT, verbose=args.verbose)
     miner.mine(session_files)
@@ -411,6 +528,7 @@ def main() -> None:
     merged = decay_old_entries(merged)
 
     LEARNED_VOC.write_text(json.dumps(merged, indent=2, ensure_ascii=False), encoding='utf-8')
+    save_cursor(newest)
     print(f"[mine-sessions] ✓ Saved {len(merged)} total aliases to {LEARNED_VOC}")
     print(f"  (run 'python generate.py --force' to rebuild sections with updated vocabulary)")
 

package/.claude/project-map/test_generate.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Regression tests for generate.py — run: python3 .claude/project-map/test_generate.py
+
+Stdlib assert + __main__, no pytest, no fixtures (ponytail: the repo has no test
+framework and this doesn't justify adding one).
+
+These exist because grader.py cannot catch what they catch: it scored the
+completely empty pre-#6 map at 97.0% PASS, identical to the populated map, since
+"Vocabulary Accuracy" reads 100% on zero entries. The grader measures
+well-formedness; these measure usefulness.
+"""
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).parent
+
+
+def load_generate(project_root: Path):
+    """Fresh module instance bound to project_root."""
+    spec = importlib.util.spec_from_file_location("gen_under_test", HERE / "generate.py")
+    mod = importlib.util.module_from_spec(spec)
+    argv, sys.argv = sys.argv, ["generate.py"]
+    try:
+        spec.loader.exec_module(mod)
+    finally:
+        sys.argv = argv
+    mod.PROJECT_ROOT = project_root
+    return mod
+
+
+def make_plugin_repo(root: Path) -> None:
+    """The repo shape from #6: markdown skills, slash commands, bash, node shim."""
+    (root / "skills/demo-skill").mkdir(parents=True)
+    (root / "skills/demo-skill/SKILL.md").write_text(
+        "---\nname: demo-skill\ndescription: |\n"
+        "  Does the demo thing.\n  Second line of the block scalar.\n---\n\n# Demo\n"
+    )
+    (root / "commands").mkdir()
+    (root / "commands/deploy.md").write_text(
+        "---\ndescription: Ship it to production\nallowed-tools: Bash(npx:*)\n---\n\nRun the deploy.\n"
+    )
+    (root / "install.sh").write_text("#!/usr/bin/env bash\necho hi\n")
+    (root / "package.json").write_text('{"name":"demo","scripts":{"build":"tsc"}}\n')
+    # A docs tree whose paths must NOT be mistaken for command manifests.
+    (root / ".documentation/reference/commands").mkdir(parents=True)
+    (root / ".documentation/reference/commands/cli.md").write_text("---\ntitle: CLI\n---\n\nprose\n")
+    (root / ".documentation/api").mkdir(parents=True)
+    (root / ".documentation/api/contract.md").write_text("---\ntitle: Contract\n---\n\nprose\n")
+    (root / ".documentation/api/INDEX.md").write_text("---\ntitle: Index\n---\n\nnav\n")
+    (root / ".documentation/reports").mkdir(parents=True)
+    (root / ".documentation/reports/maintenance-2026-09-04T18-32-22.md").write_text(
+        "---\ntitle: Maintenance Report\n---\n\ngenerated\n"
+    )
+    (root / ".documentation/archive").mkdir(parents=True)
+    (root / ".documentation/archive/old.md").write_text("---\ntitle: Old\n---\n\nretired\n")
+    (root / "README.md").write_text("# demo\n")
+
+
+def checksum(g):
+    return g.compute_checksum(g.collect_watched_files(), g.collect_doc_files())
+
+
+def rel(g, paths):
+    return {str(p.relative_to(g.PROJECT_ROOT)) for p in paths}
+
+
+# ── Watch set ────────────────────────────────────────────────────────────────
+
+def test_manifests_are_watched(g):
+    watched = rel(g, g.collect_watched_files())
+    assert "skills/demo-skill/SKILL.md" in watched, watched
+    assert "commands/deploy.md" in watched, watched
+    assert "install.sh" in watched, "issue #6: .sh was unwatched, so section 10 never refreshed"
+
+
+def test_globs_anchor_at_repo_root(g):
+    """The whole reason for fnmatch-on-relative-path instead of adding '.md'."""
+    watched = rel(g, g.collect_watched_files())
+    assert ".documentation/reference/commands/cli.md" not in watched, (
+        "a docs tree named commands/ leaked into the watch set — glob is not anchored"
+    )
+    assert not any(w.startswith(".documentation/") for w in watched), watched
+
+
+def test_editing_a_skill_moves_the_checksum(g):
+    """The #6 blocker: this was bit-identical before the fix."""
+    before = checksum(g)
+    p = g.PROJECT_ROOT / "skills/demo-skill/SKILL.md"
+    p.write_text(p.read_text() + "\nmore\n")
+    assert checksum(g) != before, "editing SKILL.md left the checksum unchanged"
+
+
+# ── Doc pointers ─────────────────────────────────────────────────────────────
+
+def test_adding_a_doc_moves_checksum_editing_one_does_not(g):
+    before = checksum(g)
+    newdoc = g.PROJECT_ROOT / ".documentation/api/added.md"
+    newdoc.write_text("---\ntitle: Added\n---\n\nbody\n")
+    after_add = checksum(g)
+    assert after_add != before, "adding a doc must refresh section 19"
+
+    newdoc.write_text("---\ntitle: Added\n---\n\nbody, substantially rewritten\n")
+    assert checksum(g) == after_add, "editing a doc body must NOT churn the whole map"
+
+    newdoc.unlink()
+    assert checksum(g) == before, "deleting a doc must refresh section 19"
+
+
+def test_doc_pointers_exclude_nav_and_archive(g):
+    docs = rel(g, g.collect_doc_files())
+    assert ".documentation/api/contract.md" in docs, docs
+    assert "README.md" in docs, "section 19's root *.md glob must be covered"
+    assert ".documentation/api/INDEX.md" not in docs, "hewtd nav crowds out real docs"
+    assert ".documentation/archive/old.md" not in docs, "archived docs are not pointers"
+    assert not any("/reports/" in d for d in docs), (
+        "generated reports must not be listed: each run writes a new timestamped "
+        "filename, which would move the checksum and force a full regeneration"
+    )
+
+
+# ── SkillParser ──────────────────────────────────────────────────────────────
+
+def _parsed(g):
+    return {m["name"]: m for m in g.SkillParser().parse()}
+
+
+def test_skill_and_command_parsed(g):
+    got = _parsed(g)
+    assert "demo-skill" in got, got
+    assert "deploy" in got, "commands/*.md carry no 'name:' — it comes from the filename"
+    assert got["demo-skill"]["kind"] == "skill"
+    assert got["deploy"]["kind"] == "command"
+    assert "Second line" in got["demo-skill"]["description"], "block scalar not joined"
+    assert got["deploy"]["description"] == "Ship it to production"
+
+
+def test_regex_fallback_matches_yaml(g):
+    """babel-fish only suggests pyyaml, so the fallback is the common path."""
+    if not g.HAS_YAML:
+        return  # nothing to compare against
+    with_yaml = _parsed(g)
+    g.HAS_YAML = False
+    try:
+        without = _parsed(g)
+    finally:
+        g.HAS_YAML = True
+    assert set(with_yaml) == set(without), (set(with_yaml), set(without))
+    for k in with_yaml:
+        assert with_yaml[k]["description"] == without[k]["description"], k
+
+
+# ── End to end ───────────────────────────────────────────────────────────────
+
+def test_plugin_repo_map_is_not_empty(g):
+    """The test that fails if #6 regresses."""
+    skills = g.SkillParser().parse()
+    vocab = g.VocabularyBuilder().build([], [], [], [], g.load_stack(), skills)
+    aliases = {v["alias"] for v in vocab}
+    assert aliases, "a plugin repo produced an empty vocabulary — issue #6"
+    assert "demo skill" in aliases or "demo-skill" in aliases, aliases
+    assert "/deploy" in aliases, "commands should be reachable as /name"
+    assert "deploy" in aliases, "...and as a bare word"
+
+    tools = {t["name"] for t in g.ToolsScanner().scan()}
+    assert "/deploy" in tools, tools
+
+    section = g.build_vocabulary_section(vocab)
+    assert "no vocabulary generated yet" not in section, "section 01 still renders the stub"
+
+
+def main() -> int:
+    tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    failed = []
+    tmp = Path(tempfile.mkdtemp(prefix="babelfish-test-"))
+    try:
+        for fn in tests:
+            root = tmp / fn.__name__
+            root.mkdir()
+            make_plugin_repo(root)
+            g = load_generate(root)
+            try:
+                fn(g)
+                print(f"  ok   {fn.__name__}")
+            except Exception as e:
+                # Exception, not just AssertionError: against an older
+                # generate.py the new helpers are simply absent, and that
+                # should read as a failing test, not abort the whole run.
+                failed.append((fn.__name__, e))
+                print(f"  FAIL {fn.__name__}: {type(e).__name__}: {e}")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    print(f"\n{len(tests) - len(failed)}/{len(tests)} passed")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/project-map/test_grader.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Regression tests for grader.py — run: python3 .claude/project-map/test_grader.py
+
+Guards the fixes from issue #9. The headline defect there was that the grader
+scored a completely empty map and a populated one identically (97.0% both), so
+these assert the SIGNAL that separates them, not the score — deliberately, since
+folding usefulness into the weighted score would fail legitimately sparse repos.
+"""
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).parent
+
+
+def load_grader(map_dir: Path):
+    spec = importlib.util.spec_from_file_location("grader_under_test", HERE / "grader.py")
+    g = importlib.util.module_from_spec(spec)
+    argv, sys.argv = sys.argv, ["grader.py"]
+    try:
+        spec.loader.exec_module(g)
+    finally:
+        sys.argv = argv
+    g.MAP_DIR = map_dir
+    g.SECTIONS_DIR = map_dir / "sections"
+    g.PROJECT_ROOT = map_dir
+    return g
+
+
+def write_map(map_dir: Path, *, vocab: int, scanned: int, extracted: int = 0) -> None:
+    (map_dir / "sections").mkdir(parents=True, exist_ok=True)
+    (map_dir / "PROJECT_MAP.md").write_text(f"""## Stats
+
+| Metric | Count |
+|--------|-------|
+| API Routes | {extracted} |
+| Data Models | 0 |
+| Schemas/DTOs | 0 |
+| Frontend Features | 0 |
+| Vocabulary Entries | {vocab} |
+
+### Source files scanned
+
+| Language | Files |
+|----------|-------|
+| python | {scanned} |
+
+## Section Index
+""")
+
+
+def test_empty_vocabulary_warns(tmp):
+    write_map(tmp, vocab=0, scanned=0)
+    w = load_grader(tmp).usefulness_warnings()
+    assert any("Vocabulary is empty" in x for x in w), w
+
+
+def test_populated_vocabulary_does_not_warn(tmp):
+    write_map(tmp, vocab=10, scanned=3)
+    w = load_grader(tmp).usefulness_warnings()
+    assert not any("Vocabulary is empty" in x for x in w), w
+
+
+def test_many_files_no_extraction_warns(tmp):
+    write_map(tmp, vocab=7, scanned=47, extracted=0)
+    w = load_grader(tmp).usefulness_warnings()
+    assert any("Scanned 47" in x for x in w), w
+
+
+def test_few_files_no_extraction_is_quiet(tmp):
+    """This repo: 3 CLI shims yielding no routes is correct, not a defect."""
+    write_map(tmp, vocab=10, scanned=3, extracted=0)
+    w = load_grader(tmp).usefulness_warnings()
+    assert not any("Scanned" in x for x in w), w
+
+
+def test_warnings_do_not_touch_the_score(tmp):
+    """Usefulness is reported, never scored — scoring it would fail sparse repos."""
+    g = load_grader(tmp)
+    write_map(tmp, vocab=0, scanned=99)
+    for name in dir(g):
+        if name.startswith("grade_"):
+            r = getattr(g, name)()
+            assert 0.0 <= r.raw_score <= 100.0
+    assert g.usefulness_warnings(), "expected warnings for an empty map"
+
+
+def test_populated_chains_not_misread_as_empty(tmp):
+    """`or '_No' in content` matched _Note / _Nothing anywhere in the file and
+    scored a populated section as an acceptable empty one at a flat 80%."""
+    (tmp / "sections").mkdir(parents=True, exist_ok=True)
+    (tmp / "sections" / "12-import-chains.md").write_text(
+        "# Section 12\n\n_Note: partial._\n\n```\nsrc/a.py -> src/b.py\n```\n")
+    g = load_grader(tmp)
+    r = g.grade_import_chains()
+    assert "No chains traced" not in r.details, (
+        f"a populated section was scored as empty: {r.details}")
+
+
+def test_stub_chains_still_recognised(tmp):
+    (tmp / "sections").mkdir(parents=True, exist_ok=True)
+    (tmp / "sections" / "12-import-chains.md").write_text(
+        "# Section 12\n\n_No import chains traced._\n")
+    r = load_grader(tmp).grade_import_chains()
+    assert "No chains traced" in r.details, r.details
+
+
+def test_empty_vocab_section_reaches_greenfield_branch(tmp):
+    """generate.py used to emit a placeholder TABLE ROW, which parsed as a valid
+    entry with a neutral location — scoring an empty vocabulary 100% and leaving
+    this branch permanently unreachable."""
+    (tmp / "sections").mkdir(parents=True, exist_ok=True)
+    (tmp / "sections" / "01-vocabulary.md").write_text(
+        "# Section 01\n\n| Alias | Type | Location | Notes |\n|---|---|---|---|\n\n"
+        "_No vocabulary generated yet — add source code to populate._\n")
+    r = load_grader(tmp).grade_vocabulary_accuracy()
+    assert r.raw_score == 85.0, f"greenfield branch not reached: {r.raw_score} {r.details}"
+
+
+def test_generate_emits_prose_not_a_row_for_empty_vocab():
+    spec = importlib.util.spec_from_file_location("gen", HERE / "generate.py")
+    gen = importlib.util.module_from_spec(spec)
+    argv, sys.argv = sys.argv, ["generate.py"]
+    try:
+        spec.loader.exec_module(gen)
+    finally:
+        sys.argv = argv
+    out = gen.build_vocabulary_section([])
+    rows = [l for l in out.splitlines()
+            if l.strip().startswith("|") and "Alias" not in l and set(l.strip()) - set("|-: ")]
+    assert not rows, f"empty vocabulary must not emit a table row, got {rows}"
+    assert "No vocabulary generated yet" in out
+
+
+def main() -> int:
+    import inspect
+    tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    failed = []
+    base = Path(tempfile.mkdtemp(prefix="grader-test-"))
+    try:
+        for fn in tests:
+            d = base / fn.__name__
+            d.mkdir(parents=True)
+            try:
+                if "tmp" in inspect.signature(fn).parameters:
+                    fn(d)
+                else:
+                    fn()
+                print(f"  ok   {fn.__name__}")
+            except Exception as e:
+                failed.append(fn.__name__)
+                print(f"  FAIL {fn.__name__}: {type(e).__name__}: {e}")
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+    print(f"\n{len(tests) - len(failed)}/{len(tests)} passed")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())