@theglitchking/babel-fish 2.3.0 → 2.4.0

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,6 +34,10 @@ 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
@@ -1452,6 +1456,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                                                         ║
 # ╚══════════════════════════════════════════════════════════════════════════╝
@@ -1622,6 +1670,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/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,69 @@ 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"]
+
+
 def main() -> int:
     tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
     failed = []

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.0"
   },
   "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.0",
       "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.0",
   "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,57 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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.0",
   "description": "Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.",
   "type": "module",
   "bin": {