@theglitchking/babel-fish 2.3.0 → 2.4.1

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

@@ -17,7 +17,7 @@ from fnmatch import fnmatch
 import re
 import subprocess
 import sys
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
@@ -34,12 +34,34 @@ MAP_DIR      = SCRIPT_DIR
 SECTIONS_DIR = MAP_DIR / "sections"
 CHECKSUMS    = MAP_DIR / "checksums.json"
 LEARNED_VOC  = MAP_DIR / "learned-vocabulary.json"
+GLOSSARY     = MAP_DIR / "glossary.json"
+# Bump when the glossary.json shape changes. Consumers should refuse a major
+# they do not recognise rather than guess.
+GLOSSARY_SCHEMA_VERSION = "1.0"
 
 # Resolve project root: two levels up from .claude/project-map/
 PROJECT_ROOT = MAP_DIR.parent.parent
 
 SECTIONS_DIR.mkdir(parents=True, exist_ok=True)
 
+
+def configure_paths(project_root: Path) -> None:
+    """Point every output at <project_root>/.claude/project-map/.
+
+    --project-root previously moved only the READ root: the map was written back
+    into whichever directory the script itself lived in, so mapping another
+    project produced nothing for the target and destroyed the script repo's own
+    map. Writes follow the root now.
+    """
+    global PROJECT_ROOT, MAP_DIR, SECTIONS_DIR, CHECKSUMS, LEARNED_VOC, GLOSSARY
+    PROJECT_ROOT = project_root
+    MAP_DIR      = project_root / '.claude' / 'project-map'
+    SECTIONS_DIR = MAP_DIR / 'sections'
+    CHECKSUMS    = MAP_DIR / 'checksums.json'
+    LEARNED_VOC  = MAP_DIR / 'learned-vocabulary.json'
+    GLOSSARY     = MAP_DIR / 'glossary.json'
+    SECTIONS_DIR.mkdir(parents=True, exist_ok=True)
+
 # ── Secrets guard ────────────────────────────────────────────────────────────
 SECRET_PATTERNS = re.compile(
     r'(?i)(password|secret|token|api_key|apikey|private_key|auth_token|'
@@ -1452,6 +1474,50 @@ def build_doc_pointers_section() -> str:
     return '\n'.join(lines) + '\n'
 
 
+# ── Glossary side-channel ─────────────────────────────────────────────────────
+
+def _relative_source() -> str:
+    vocab_md = SECTIONS_DIR / '01-vocabulary.md'
+    try:
+        return str(vocab_md.relative_to(PROJECT_ROOT))
+    except ValueError:
+        return str(vocab_md)
+
+
+def write_glossary(vocab: list[dict], stack: dict) -> Path:
+    """Structured vocabulary for machine consumers.
+
+    01-vocabulary.md stays human-facing. Consumers read this instead of parsing
+    prose: the markdown is a rendered table whose Notes column mixes
+    descriptions with metadata and carries pipe-escaping (`a \\| b`), which is
+    fine to read and hostile to parse.
+    """
+    entries = [
+        {
+            'key': v.get('alias', ''),
+            'canonical_path': v.get('location', ''),
+            'section': v.get('type', ''),
+            'description': v.get('notes', '') or None,
+        }
+        for v in sorted(vocab, key=lambda x: x.get('alias', ''))
+        if v.get('alias')
+    ]
+    payload = {
+        'schema_version': GLOSSARY_SCHEMA_VERSION,
+        'generated_at': datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'),
+        # SECTIONS_DIR is bound to the script's location, which is not under
+        # PROJECT_ROOT when --project-root points elsewhere. Report a relative
+        # path when there is one, the absolute path otherwise.
+        'source': _relative_source(),
+        'project': stack.get('name', PROJECT_ROOT.name),
+        'entry_count': len(entries),
+        'entries': entries,
+    }
+    GLOSSARY.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + '\n',
+                        encoding='utf-8')
+    return GLOSSARY
+
+
 # ╔══════════════════════════════════════════════════════════════════════════╗
 # ║  PROJECT MAP TOC                                                         ║
 # ╚══════════════════════════════════════════════════════════════════════════╝
@@ -1564,9 +1630,8 @@ def main() -> None:
     parser.add_argument('--stack-json', type=Path, default=None, help='Path to stack.json from detect-stack.sh')
     args = parser.parse_args()
 
-    global PROJECT_ROOT
     if args.project_root:
-        PROJECT_ROOT = args.project_root.resolve()
+        configure_paths(args.project_root.resolve())
 
     print(f"[generate] Project root: {PROJECT_ROOT}")
 
@@ -1622,6 +1687,9 @@ def main() -> None:
     print("[generate] Building vocabulary...")
     vocab = VocabularyBuilder().build(routes, models, schemas, features, stack, skills)
 
+    glossary_path = write_glossary(vocab, stack)
+    print(f"[generate] Glossary → {glossary_path.name} ({len(vocab)} entries)")
+
     print("[generate] Tracing import chains...")
     chains = ImportChainTracer().trace(routes)
 

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

@@ -32,6 +32,21 @@ PROJECT_ROOT = MAP_DIR.parent.parent
 
 REPORTS_DIR.mkdir(parents=True, exist_ok=True)
 
+
+def configure_paths(project_root: Path) -> None:
+    """Grade the map belonging to project_root, not the script's own.
+
+    Previously --project-root moved only the path-validation root, so the
+    script's own sections were graded against a different project's filesystem —
+    producing a confident but meaningless score (0% vocabulary accuracy).
+    """
+    global PROJECT_ROOT, MAP_DIR, SECTIONS_DIR, REPORTS_DIR
+    PROJECT_ROOT = project_root
+    MAP_DIR      = project_root / '.claude' / 'project-map'
+    SECTIONS_DIR = MAP_DIR / 'sections'
+    REPORTS_DIR  = MAP_DIR / 'reports'
+    REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+
 PASS_THRESHOLD = 90.0
 
 # ── Secret pattern (mirrors generate.py) ─────────────────────────────────────
@@ -597,9 +612,8 @@ def main() -> None:
                         help='Override report output path')
     args = parser.parse_args()
 
-    global PROJECT_ROOT
     if args.project_root:
-        PROJECT_ROOT = args.project_root.resolve()
+        configure_paths(args.project_root.resolve())
 
     print(f"[grader] Grading iteration {args.iteration}/{args.total}...")
 

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

@@ -36,6 +36,21 @@ LEARNED_VOC  = SCRIPT_DIR / "learned-vocabulary.json"
 MINE_CURSOR  = SCRIPT_DIR / ".mine-cursor.json"
 PROJECT_ROOT = SCRIPT_DIR.parent.parent
 
+
+def configure_paths(project_root: Path) -> None:
+    """Write mined aliases into project_root's map, not the script's own.
+
+    Previously --project-root selected whose TRANSCRIPTS to mine but left the
+    output pointed at the script's directory, so mining another project wrote
+    its aliases into this one's learned vocabulary.
+    """
+    global PROJECT_ROOT, LEARNED_VOC, MINE_CURSOR
+    PROJECT_ROOT = project_root
+    map_dir      = project_root / '.claude' / 'project-map'
+    LEARNED_VOC  = map_dir / 'learned-vocabulary.json'
+    MINE_CURSOR  = map_dir / '.mine-cursor.json'
+    map_dir.mkdir(parents=True, exist_ok=True)
+
 # ── Config ───────────────────────────────────────────────────────────────────
 MIN_SCORE        = 5.0     # Minimum score to include in vocabulary
 RECENCY_WINDOWS  = [       # (days_threshold, weight)
@@ -466,9 +481,8 @@ def main() -> None:
                         help='Ignore the incremental cursor and re-mine every transcript')
     args = parser.parse_args()
 
-    global PROJECT_ROOT
     if args.project_root:
-        PROJECT_ROOT = args.project_root.resolve()
+        configure_paths(args.project_root.resolve())
 
     print(f"[mine-sessions] Project root: {PROJECT_ROOT}")
 

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

@@ -12,6 +12,7 @@ well-formedness; these measure usefulness.
 from __future__ import annotations
 
 import importlib.util
+import pathlib
 import shutil
 import sys
 import tempfile
@@ -173,6 +174,102 @@ def test_plugin_repo_map_is_not_empty(g):
     assert "no vocabulary generated yet" not in section, "section 01 still renders the stub"
 
 
+# ── Glossary side-channel (#10) ──────────────────────────────────────────────
+
+def test_glossary_json_written_and_shaped(g):
+    """Consumers read this instead of parsing the markdown table."""
+    import json
+    skills = g.SkillParser().parse()
+    vocab = g.VocabularyBuilder().build([], [], [], [], g.load_stack(), skills)
+    path = g.write_glossary(vocab, g.load_stack())
+    assert path.exists(), "glossary.json not written"
+    data = json.loads(path.read_text())
+
+    for field in ("schema_version", "generated_at", "source", "project",
+                  "entry_count", "entries"):
+        assert field in data, f"missing {field}: {sorted(data)}"
+    assert data["entry_count"] == len(data["entries"])
+    assert data["schema_version"].count(".") == 1, data["schema_version"]
+
+    for e in data["entries"]:
+        assert set(e) == {"key", "canonical_path", "section", "description"}, e
+        assert e["key"], e
+    keys = [e["key"] for e in data["entries"]]
+    assert keys == sorted(keys), "entries must be sorted by key"
+    assert len(keys) == len(set(keys)), "keys must be unique"
+
+
+def test_glossary_source_path_is_real(g):
+    """v1.0 of the contract named `.babel-fish/`, which was never written."""
+    import json
+    data = json.loads(g.write_glossary([], g.load_stack()).read_text())
+    assert ".babel-fish" not in data["source"], data["source"]
+    assert data["source"].endswith("01-vocabulary.md"), data["source"]
+    assert pathlib.PurePath(data["source"]).parent.name == "sections", data["source"]
+
+
+def test_glossary_values_are_unescaped(g):
+    """The markdown table escapes pipes into values (`auto \\| nudge`). JSON
+    must carry the real string — that escaping is the clearest reason not to
+    parse the rendered table."""
+    import json
+    vocab = [{"alias": "policy", "type": "command", "location": "commands/policy.md",
+              "notes": "Get or set the policy (auto | nudge | off)"}]
+    data = json.loads(g.write_glossary(vocab, g.load_stack()).read_text())
+    assert data["entries"][0]["description"] == "Get or set the policy (auto | nudge | off)"
+    assert "\\|" not in data["entries"][0]["description"]
+
+
+def test_empty_glossary_is_valid(g):
+    """An empty vocabulary is a valid glossary, not an error."""
+    import json
+    data = json.loads(g.write_glossary([], g.load_stack()).read_text())
+    assert data["entries"] == [] and data["entry_count"] == 0
+
+
+def test_glossary_survives_foreign_project_root(g):
+    """SECTIONS_DIR is bound to the script location, which is NOT under
+    PROJECT_ROOT when --project-root points elsewhere. That combination raised
+    ValueError from relative_to()."""
+    import json
+    g.write_glossary([], g.load_stack())  # PROJECT_ROOT is the temp fixture here
+    data = json.loads(g.GLOSSARY.read_text())
+    assert data["source"].endswith("01-vocabulary.md"), data["source"]
+
+
+# ── --project-root write path (#15) ──────────────────────────────────────────
+
+def test_project_root_relocates_every_output(g):
+    """--project-root used to move only the READ root: the map was written back
+    into the script's own directory, so the target got nothing and the script
+    repo's map was destroyed."""
+    target = g.PROJECT_ROOT / "elsewhere"
+    (target / "src").mkdir(parents=True)
+    (target / "src" / "app.py").write_text("# app\n")
+
+    script_owned = g.MAP_DIR
+    g.configure_paths(target)
+
+    assert g.PROJECT_ROOT == target
+    for name in ("MAP_DIR", "SECTIONS_DIR", "CHECKSUMS", "LEARNED_VOC", "GLOSSARY"):
+        p = getattr(g, name)
+        assert str(p).startswith(str(target)), f"{name} still outside the target: {p}"
+        assert not str(p).startswith(str(script_owned)), f"{name} still in the script dir: {p}"
+    assert g.SECTIONS_DIR.is_dir(), "sections dir not created under the target"
+
+
+def test_project_root_writes_land_in_the_target(g):
+    import json
+    target = g.PROJECT_ROOT / "elsewhere"
+    target.mkdir(parents=True)
+    g.configure_paths(target)
+    g.write_glossary([{"alias": "x", "type": "feature",
+                       "location": "src/x.py", "notes": "n"}], g.load_stack())
+    written = target / ".claude" / "project-map" / "glossary.json"
+    assert written.exists(), "glossary.json was not written under the target"
+    assert json.loads(written.read_text())["entry_count"] == 1
+
+
 def main() -> int:
     tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
     failed = []

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

@@ -136,6 +136,22 @@ def test_generate_emits_prose_not_a_row_for_empty_vocab():
     assert "No vocabulary generated yet" in out
 
 
+def test_project_root_relocates_grader_paths(tmp):
+    """The grader used to read its OWN sections while validating paths against
+    a different project — a confident but meaningless score."""
+    g = load_grader(tmp)
+    target = tmp / "elsewhere"
+    target.mkdir(parents=True)
+    script_owned = g.SECTIONS_DIR
+    g.configure_paths(target)
+    assert g.PROJECT_ROOT == target
+    for name in ("MAP_DIR", "SECTIONS_DIR", "REPORTS_DIR"):
+        p = getattr(g, name)
+        assert str(p).startswith(str(target)), f"{name} outside target: {p}"
+        assert p != script_owned, f"{name} still the script's: {p}"
+    assert g.REPORTS_DIR.is_dir()
+
+
 def main() -> int:
     import inspect
     tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]

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

@@ -172,6 +172,19 @@ def test_junk_phrases_filtered(m, root):
     assert not any("," in g or ":" in g for g in got), got
 
 
+def test_project_root_relocates_miner_output(m, root):
+    """Mining another project used to write its aliases into THIS project's
+    learned vocabulary."""
+    target = root / "elsewhere"
+    target.mkdir(parents=True)
+    m.configure_paths(target)
+    assert m.PROJECT_ROOT == target
+    for name in ("LEARNED_VOC", "MINE_CURSOR"):
+        p = getattr(m, name)
+        assert str(p).startswith(str(target)), f"{name} outside target: {p}"
+    assert m.LEARNED_VOC.parent.is_dir()
+
+
 def main() -> int:
     import inspect
     tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for babel-fish - Codebase introspection and vocabulary translation for AI coding assistants",
-    "version": "2.3.0"
+    "version": "2.4.1"
   },
   "plugins": [
     {
       "name": "babel-fish",
       "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-      "version": "2.3.0",
+      "version": "2.4.1",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "babel-fish",
   "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/.githooks/pre-commit

@@ -14,7 +14,8 @@ if echo "$STAGED_FILES" | grep -qE "$EXTENSIONS_PATTERN" 2>/dev/null; then
             echo "[codebase-mapper] Regenerating project map..."
             if $PYTHON "$MAP_SCRIPT" 2>/dev/null; then
                 git add .claude/project-map/PROJECT_MAP.md .claude/project-map/checksums.json \
-                        .claude/project-map/sections/*.md .claude/project-map/learned-vocabulary.json 2>/dev/null || true
+                        .claude/project-map/sections/*.md .claude/project-map/learned-vocabulary.json \
+                        .claude/project-map/glossary.json 2>/dev/null || true
             fi
         fi
     fi

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.4.1] - 2026-09-04
+
+### Fixed
+
+- **`--project-root` changed only the read root**
+  ([#15](https://github.com/TheGlitchKing/babel-fish/issues/15)). All three
+  scripts kept writing to the directory the script itself lives in, so pointing
+  the flag at another project silently corrupted the script's own map instead of
+  mapping the target:
+
+  - `generate.py` wrote the map into its own directory — the target got nothing,
+    and the script repo's `sections/`, `glossary.json` and `checksums.json` were
+    overwritten, while the run reported success.
+  - `grader.py` graded its **own** sections while validating vocabulary paths
+    against the **target's** filesystem, producing a confident but meaningless
+    score (0% vocabulary accuracy, 77% FAIL). The nastiest of the three: it
+    neither crashed nor produced nothing.
+  - `mine-sessions.py` mined the target's transcripts and wrote the aliases into
+    its own `learned-vocabulary.json` and `.mine-cursor.json`.
+
+  Each script gained `configure_paths()`, called from `main()` after argument
+  parsing, which relocates every output under `<project-root>/.claude/project-map/`.
+  Module-level defaults are unchanged, so the common case and the test suites
+  are unaffected.
+
+  Not reachable during install: `.claude/install.sh` runs the copied scripts
+  inside the target, where `SCRIPT_DIR` and `--project-root` coincide. The
+  pre-commit hook and `babel-fish regen` / `grade` pass no `--project-root`.
+  Verified by a full install after the change.
+
+## [2.4.0] - 2026-09-04
+
+### Added
+
+- **`glossary.json` — a structured vocabulary artifact for machine consumers**
+  ([#10](https://github.com/TheGlitchKing/babel-fish/issues/10)). Written to
+  `.claude/project-map/glossary.json` on every map build and staged by the
+  pre-commit hook. Consumers read this instead of parsing `01-vocabulary.md`.
+
+  The markdown was never a good parsing target: its `Notes` column mixes
+  descriptions with metadata, and pipe-escaping leaks into values — this repo's
+  own output contained `(auto \| nudge \| off)`. The JSON carries the real
+  string.
+
+### Fixed
+
+- **The glossary contract described a format babel-fish has never emitted.**
+  `glossary-contract.md` v1.0 specified bullet entries
+  (`- **key** → \`path\` — desc`) and stated that non-conforming bullets are
+  ignored; the generator has always written a markdown table. A consumer built
+  strictly to that spec would extract **zero entries**. Rewritten (v2.0) around
+  `glossary.json`, with the markdown documented as human-facing output that is
+  not parsed.
+
+- **Both sides of that contract documented a directory neither produces.** The
+  contract, the integration guide and the README referred to `.babel-fish/`;
+  babel-fish writes `.claude/project-map/`. The same error is mirrored in
+  semantic-memory's `smart-middle-activation.md` and `corpora-json.md`, where it
+  would have made Phase 3.1.0 find nothing — silently. Corrected here and filed
+  there as
+  [semantic-memory#28](https://github.com/the-glitch-kingdom/semantic-memory/issues/28).
+
+- **`--project-root` crashed the generator.** `write_glossary()` computed the
+  source path with `SECTIONS_DIR.relative_to(PROJECT_ROOT)`, but `SECTIONS_DIR`
+  is bound to the script's own location, so pointing `--project-root` elsewhere
+  raised `ValueError`. Found by a test written for the new artifact.
+
+- `integration-with-semantic-memory.md` no longer describes a setup that does
+  not exist. semantic-memory 1.5.1 ships no `translate` verbs, no `project-map`
+  corpus and no glossary reader; the guide now says so at the top instead of
+  giving instructions for it.
+
+### Note
+
+The consumer is unbuilt, so nothing was pinned to the old format. Issue #10
+originally advised caution about "a breaking change to a format a downstream
+consumer pins to" — checking semantic-memory's source showed zero
+`translate`/`reverse_translate`/`list_vocabulary` verbs in its 164-entry tool
+surface and no `glossary` string in `src/`. That freed the format choice
+entirely.
+
 ## [2.3.0] - 2026-09-04
 
 ### Fixed

package/README.md

@@ -9,7 +9,7 @@
 [![GitHub: TheGlitchKing/babel-fish](https://img.shields.io/badge/GitHub-TheGlitchKing%2Fbabel--fish-blue)](https://github.com/TheGlitchKing/babel-fish)
 
 > [!NOTE]
-> **Pairs with [`semantic-memory`](https://github.com/TheGlitchKing/semantic-sidekick) (formerly `semantic-sidekick`).** When both are installed, semantic-memory consumes babel-fish's auto-generated `.babel-fish/` output as a `project-map` corpus AND extracts `01-vocabulary.md` into a structured `glossary.json` side-channel. That gives your AI a deterministic `translate("deals page") → "features/deal-pipeline/DealPipeline.tsx"` MCP verb instead of relying on semantic-search-luck. See [`.documentation/api/glossary-contract.md`](./.documentation/api/glossary-contract.md) for the producer/consumer data contract and [`.documentation/quickstart/integration-with-semantic-memory.md`](./.documentation/quickstart/integration-with-semantic-memory.md) for the setup walkthrough. babel-fish standalone behavior is unchanged — semantic-memory is purely additive.
+> **Pairs with [`semantic-memory`](https://github.com/TheGlitchKing/semantic-sidekick) (formerly `semantic-sidekick`).** When both are installed, semantic-memory consumes babel-fish's auto-generated `.claude/project-map/` output as a `project-map` corpus AND reads the structured `glossary.json` babel-fish emits alongside it. That gives your AI a deterministic `translate("deals page") → "features/deal-pipeline/DealPipeline.tsx"` MCP verb instead of relying on semantic-search-luck. See [`.documentation/api/glossary-contract.md`](./.documentation/api/glossary-contract.md) for the producer/consumer data contract and [`.documentation/quickstart/integration-with-semantic-memory.md`](./.documentation/quickstart/integration-with-semantic-memory.md) for the setup walkthrough. babel-fish standalone behavior is unchanged — semantic-memory is purely additive.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/babel-fish",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.",
   "type": "module",
   "bin": {