@polycode-projects/the-mechanical-code-talker 1.5.5 → 1.8.4

package/corpus/tier2/manifest.json

@@ -57,6 +57,48 @@
       "bytes": 5826,
       "sha256": "01284f1350fa2ca9653b1c5f52a39fdcb657727c65e77693eae954cb95a14a2e",
       "license": "MPL-2.0"
+    },
+    {
+      "id": "human",
+      "kind": "domain",
+      "description": "The default human-world persona (PLAN_SEED.md): everyday people, places, objects, nature, time/events, body/food and mind vocabulary, hand-curated from Open English WordNet (CC-BY-4.0) and bridged to Schema.org's (Apache-2.0) top-level classes — replaces the code-domain SEON+ConceptNet default.",
+      "source": {
+        "kind": "curated",
+        "tool": "corpus/tier2/generate.mjs"
+      },
+      "file": "human.jsonl",
+      "facts": 664,
+      "bytes": 81430,
+      "sha256": "040e6d1f6761a29a080f7825ff8aae60caf879125c1f7a1480340ef04129bcd5",
+      "license": "MPL-2.0"
+    },
+    {
+      "id": "human-medium",
+      "kind": "domain",
+      "description": "The Medium tier of the default human-world persona (PLAN_SEED.md): incremental facts beyond Small only — activated alongside \"human\" via --persona-size medium, never active by default.",
+      "source": {
+        "kind": "curated",
+        "tool": "corpus/tier2/generate.mjs"
+      },
+      "file": "human-medium.jsonl",
+      "facts": 944,
+      "bytes": 110796,
+      "sha256": "63270a928f4d304489bd552c1e50704ff2d6f17841cf11a87a292418eaa572c0",
+      "license": "MPL-2.0"
+    },
+    {
+      "id": "human-large",
+      "kind": "domain",
+      "description": "The Large tier of the default human-world persona (PLAN_SEED.md): incremental facts beyond Medium only — activated alongside \"human\" via --persona-size large, never active by default.",
+      "source": {
+        "kind": "curated",
+        "tool": "corpus/tier2/generate.mjs"
+      },
+      "file": "human-large.jsonl",
+      "facts": 12001,
+      "bytes": 1464850,
+      "sha256": "754d9d4c046f92994a5f5fa0abde27af65a47ec546b3051bf972bfa76b642917",
+      "license": "MPL-2.0"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.5.5",
+  "version": "1.8.4",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
@@ -53,7 +53,12 @@
     "./graph-service": "./src/providers/graph-service.mjs",
     "./providers/fixture": "./src/providers/fixture.mjs",
     "./providers/bootstrap": "./src/providers/bootstrap.mjs",
-    "./conformance": "./src/conformance.mjs"
+    "./conformance": "./src/conformance.mjs",
+    "./init": "./src/init.mjs",
+    "./extensions": "./src/extensions.mjs",
+    "./toml-config": "./src/toml-config.mjs",
+    "./generateCompletion": "./src/completions/complete.mjs",
+    "./createCompletionsGraphAdapter": "./src/completions/graph-adapter.mjs"
   },
   "files": [
     "bin/",
@@ -79,13 +84,12 @@
     "chat": "node bin/tmct.mjs",
     "chat:repo": "node bin/tmct.mjs chat --repo",
     "init": "node bin/tmct.mjs init",
-    "init:persona:code": "node bin/tmct.mjs init --with-persona code",
-    "init:corpus:general": "node bin/tmct.mjs init --corpus general",
-    "init:corpus:aws": "node bin/tmct.mjs init --corpus aws",
-    "init:corpus:python": "node bin/tmct.mjs init --corpus python",
-    "init:corpus:java": "node bin/tmct.mjs init --corpus java",
+    "init:persona:human": "node bin/tmct.mjs init --with-persona human",
+    "init:persona:empty": "node bin/tmct.mjs init --with-persona empty",
+    "init:large": "node bin/tmct.mjs init && node bin/tmct.mjs import --corpus seon && node bin/tmct.mjs import --corpus conceptnet && node bin/tmct.mjs import --corpus aws && node bin/tmct.mjs import --corpus python && node bin/tmct.mjs import --corpus java",
     "memory": "node bin/tmct.mjs memory",
     "syllogise": "node bin/tmct.mjs syllogise",
+    "viz": "node bin/tmct.mjs viz",
     "example:mini": "node bin/tmct.mjs chat --repo examples/mini-webapp --ephemeral",
     "example:polyglot": "node bin/tmct.mjs chat --repo examples/polyglot --ephemeral",
     "chatbench:run": "node chatbench/run.mjs",
@@ -95,9 +99,11 @@
     "infbench": "node infbench/generate-cases.mjs && node infbench/run.mjs",
     "audit": "npm audit --audit-level=high",
     "audit:fix": "npm audit fix",
-    "demo:build": "node scripts/build-demo-site.mjs"
+    "demo:build": "node scripts/build-demo-site.mjs",
+    "build:ask-bundle": "node scripts/build-ask-bundle.mjs"
   },
   "devDependencies": {
+    "esbuild": "^0.28.1",
     "ink-testing-library": "^4.0.0"
   }
 }

package/src/answer-variants.json

@@ -0,0 +1,47 @@
+{
+  "version": 1,
+  "curation": "Hand-curated. scripts/generate-answer-variants.mjs cross-checked each pool against real Open English WordNet synsets (scripts/lib/wordnet-synonyms.mjs) where a sense fit; most of these are domain-specific code-graph connector phrases WordNet's own sense-1 convention resolves to the wrong sense for -- e.g. 'locate' -> 'turn up', 'record' -> 'enter, put down', 'module' -> 'mental faculty' -- so every entry below was accepted or rejected by hand against the exact rendered sentence it replaces, never auto-accepted from a raw synset match. See src/answer-variants.mjs for how these are selected at render time.",
+  "pools": {
+    "defined-in": {
+      "base": "defined in",
+      "variants": ["located in", "found in"],
+      "usedBy": [
+        "ask.mjs renderComposite exists-hit (\"Yes - X is a Y, defined in Z.\")",
+        "ask.mjs metaFallbackEntityAnswer (\"X is a Y in this codebase, defined in Z ...\")"
+      ],
+      "deliberatelyNotUsedBy": [
+        "ask.mjs renderCore whereShape (\"X is defined in Y at line(s) Z\" / \"X is defined in Y (no line span...)\") -- chatbench/graded-pool-max.jsonl pins this exact substring as ground truth for 11 'where is X defined' cases (2 in the always-run promoted subset), and that pool is append-only/never-edited-mid-arc per SKILL_BENCHMARK_CEFR_ENGLISH.md."
+      ]
+    },
+    "is-dated": {
+      "base": "is dated",
+      "variants": ["was made on", "was recorded on"],
+      "usedBy": ["ask.mjs renderCore whenShape, the exact-subject hit (\"commit X is dated Y.\")"]
+    },
+    "full-breakdown": {
+      "base": "for the full breakdown",
+      "variants": ["for the full details", "for more detail"],
+      "usedBy": ["chat.mjs moduleOverviewText's /describe pointer"]
+    },
+    "ask-about-lead": {
+      "base": "Ask about",
+      "variants": ["Try asking about", "You can ask about"],
+      "usedBy": ["chat.mjs orientationText's capability sentence"]
+    },
+    "facts-across": {
+      "base": "across",
+      "variants": ["spanning", "over"],
+      "usedBy": ["chat.mjs memorySummary (\"I remember N facts across M relation types.\")"]
+    },
+    "full-picture": {
+      "base": "the full picture",
+      "variants": ["the whole picture", "the complete picture"],
+      "usedBy": ["chat.mjs whatElseAnswer's exhausted-facts pointer"]
+    },
+    "beyond-that-lead": {
+      "base": "Beyond that,",
+      "variants": ["Also,", "In addition,"],
+      "usedBy": ["chat.mjs whatElseAnswer's follow-on fact listing"]
+    }
+  }
+}

package/src/answer-variants.mjs

@@ -0,0 +1,67 @@
+// answer-variants.mjs — deterministic, committed answer-phrasing variety
+// ("wiring the generated corpus into the live answer path", ROADMAP.md's
+// What's next item / archive/PLAN_TEMPLATE_COVERAGE.md's stated follow-on).
+//
+// A SMALL, curated, committed table (answer-variants.json) of safe cosmetic/
+// locational/connector-word rephrasings for a deliberately narrow set of
+// answer templates in ask.mjs/chat.mjs -- never a relation verb (imports/
+// calls/tests/inherits/touches), never an entity id/label/path, never a miss/
+// rephrase-hint template. Each pool was hand-reviewed for meaning-safety in
+// its SPECIFIC rendered sentence (see answer-variants.json's own "curation"
+// field) -- WordNet was consulted but its sense-1 lookups mostly resolved to
+// the wrong sense for this domain-specific connector vocabulary, so nothing
+// here was auto-accepted from a raw synset match.
+//
+// Selection is a pure hash, never Math.random/Date.now: the SAME (poolId, key)
+// always picks the SAME form, so the same query against the same entity
+// renders byte-identical text every time (pinnable in tests), while different
+// entities/answers spread across the pool's forms. This is the ONE place that
+// hash-and-pick logic lives -- every call site below imports pickPhrase
+// rather than re-deriving its own index arithmetic.
+//
+// Lazy + failure-tolerant load (chat.mjs's own "a turn never crashes" ethos,
+// see chatTemplates()): a missing/corrupt data file, or `node:fs` simply
+// being unavailable, degrades to always returning `base` -- never a throw.
+// That second case is load-bearing, not theoretical: ask.mjs is bundled
+// whole into the browser "Ask the graph" panel (scripts/build-ask-bundle.mjs
+// stubs node:fs's readFileSync as a function that THROWS when called, so the
+// browser bundle still boots; this module's readFileSync call only ever
+// happens lazily inside pickPhrase, wrapped in try/catch, exactly so that
+// throw is caught here and never reaches the caller.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+
+const DATA_FILE = join(dirname(fileURLToPath(import.meta.url)), "answer-variants.json");
+
+let dataCache; // undefined = not yet attempted; null = load failed/unavailable
+function loadData() {
+  if (dataCache !== undefined) return dataCache;
+  try {
+    dataCache = JSON.parse(readFileSync(DATA_FILE, "utf8"));
+  } catch {
+    dataCache = null;
+  }
+  return dataCache;
+}
+
+/** Deterministically choose `base` or one of `poolId`'s committed variants,
+ *  keyed on `key` -- pass something stable that identifies THIS specific
+ *  answer (an entity's own `id` for entity-anchored templates; any other
+ *  stable string, e.g. a graph-summary key, for templates with no single
+ *  entity). Same (poolId, key) always returns the same string; an unknown
+ *  pool, a missing/unreadable data file, or a falsy `key` all fall back to
+ *  `base` unconditionally -- variety is strictly additive, never a way to
+ *  lose the original wording. */
+export function pickPhrase(poolId, key, base) {
+  if (!key) return base;
+  const data = loadData();
+  const variants = data?.pools?.[poolId]?.variants;
+  if (!Array.isArray(variants) || !variants.length) return base;
+  const forms = [base, ...variants];
+  const digest = createHash("sha256").update(`${poolId}:${String(key)}`).digest();
+  const idx = digest[0] % forms.length;
+  return forms[idx];
+}

package/src/ask-browser-entry.mjs

@@ -0,0 +1,34 @@
+// ask-browser-entry.mjs — the esbuild entry for `tmct viz`'s embedded "Ask the
+// graph" chat panel (PLAN_BREADTH_FIRST_NLU.md §5 follow-on, operator directive
+// 2026-07-11: a real NL chat running client-side against the embedded graph,
+// via tmct's OWN JS engine — not reimplemented, not a stub).
+//
+// Precedent: seonix's own `src/ask-browser-entry.mjs` (PLAN_CHAT_EXTRACTION.md
+// Stage 5) proved this exact approach in production — esbuild + a Node-builtin
+// stub plugin bundles tmct's real ask() into a single browser IIFE. This entry
+// mirrors that pattern, adapted for tmct bundling its OWN ask.mjs directly
+// (no external package import needed — we're already inside the source tree)
+// and extended with the graph-traversal exports `tmct viz`'s own client-side
+// re-focus/re-walk needs (spiralExpand etc. — seonix's code-graph viewer
+// recomputes depth with its own hand-rolled client-side BFS; tmct's viewer
+// reuses the real spiralExpand instead, so the browser walk is byte-identical
+// to the CLI's).
+//
+// Bundled by scripts/build-ask-bundle.mjs into src/ask-browser.bundle.js (an
+// IIFE), which viz.mjs inlines verbatim into the viewer page's own <script>.
+// Runs adapter-less (no wink model in the browser — ask()'s lemma/POS tier
+// degrades to its curated + fuzzy tiers, exactly the boundary
+// test/ask-nlp.test.mjs's own "viewer bundle without wink" test proves stays
+// answerable) and grammar-lite (no ACE/construction-grammar strategies, both
+// fs-dependent — the plain grammar/keyword-spot/noise-strip strategies still
+// answer every shape tmct viz's own memory-graph queries need).
+import { ask, parseQuery } from "./ask.mjs";
+import {
+  parseEntities, spiralExpand, mostRecentIndividual, derivedUpdatedAt, MEMORY_SPIRAL_EXPAND_KINDS,
+  buildVizNodesAndEdges,
+} from "./codegraph.mjs";
+
+globalThis.tmctViz = {
+  ask, parseQuery, parseEntities, spiralExpand, mostRecentIndividual, derivedUpdatedAt,
+  MEMORY_SPIRAL_EXPAND_KINDS, buildVizNodesAndEdges,
+};