@polycode-projects/the-mechanical-code-talker 2.5.4 → 2.6.1

package/README.md

@@ -285,8 +285,8 @@ steps:
        - src/handlers/tasks.mjs (imports it) — tests: test/tasks.test.mjs
        - src/server/router.mjs (imports it) — tests: none recorded
      depth 2 (2):
-       - src/handlers/users.mjs (imports it) — tests: none recorded
-       - src/server/app.mjs (imports it) — tests: none recorded
+       - src/handlers/users.mjs (reaches it through an intermediary) — tests: none recorded
+       - src/server/app.mjs (reaches it through an intermediary) — tests: none recorded
   2. tmct_untested {}
      7 source module(s) with no covering test module:
        src/core/validate.mjs

package/data/templates/responses.jsonl

@@ -54,7 +54,7 @@
 {"id":"nudge-commands","class":"nudge","register":"friendly","template":"If prose fails you, the slash commands always work — try {command}."}
 {"id":"nudge-narrower","class":"nudge","register":"friendly","template":"That matched {count} things — too many to be useful. Narrow it with a module or class name."}
 {"id":"conversational-greeting","class":"conversational","register":"friendly","template":"Hi. Ask me about this codebase — imports, calls, definitions, history — or /help."}
-{"id":"conversational-greeting-hello-there","class":"conversational","register":"friendly","template":"Hello there. (A hollow voice says, \"fool.\") Ask me about this codebase, or /help."}
+{"id":"conversational-greeting-hello-there","class":"conversational","register":"friendly","template":"Hello there. Ask me about this codebase, or /help."}
 {"id":"conversational-greeting-good-morning","class":"conversational","register":"friendly","template":"Good morning. Ask me about this codebase, or /help."}
 {"id":"conversational-greeting-good-afternoon","class":"conversational","register":"friendly","template":"Good afternoon. Ask me about this codebase, or /help."}
 {"id":"conversational-greeting-good-evening","class":"conversational","register":"friendly","template":"Good evening. Ask me about this codebase, or /help."}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.5.4",
+  "version": "2.6.1",
   "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.",

package/src/domain/ask.mjs

@@ -225,7 +225,7 @@ function parseComposite(text, nlp) {
     || parseQualifierCheck(w, lc)
     || parseUniversal(w, lc, nlp)
     || parseNegation(text, nlp, 0)
-    || parseNegatedAsk(w, lc)
+    || parseNegatedAsk(w, lc, nlp)
     || parseForwardNegation(w, lc, nlp)
     || parseTemporal(w, lc, nlp, 0)
     || parseCommitFilter(w, lc)
@@ -718,11 +718,18 @@ function parseQualifierCheck(w, lc) {
  *  the same sentence at positive polarity ("not" is no stopword) and the merge
  *  would call the two readings an ambiguity. Declining to a composite production
  *  is what keeps the sentence out of that merge. */
-function parseNegatedAsk(w, lc) {
-  if (lc[0] !== "do" && lc[0] !== "does" && lc[0] !== "did") return null;
+function parseNegatedAsk(w, lc, nlp) {
+  // The copular leads carry the PASSIVE twin ("is X not imported by Y") —
+  // without them the strategies read the sentence at positive polarity (the
+  // "not" drops as noise) and the bare "Yes" answers the un-negated question.
+  // parseQualifierCheck ran first, so "is X not deprecated" keeps its lane.
+  // The positive re-parse runs the SAME simple-clause pair the composer's
+  // fragments use — the passive lives in the keyword strategy, which the
+  // anchored grammar alone never reaches.
+  if (!["do", "does", "did", "is", "are", "was", "were"].includes(lc[0])) return null;
   const notIdx = lc.indexOf("not", 1);
   if (notIdx < 0) return null;
-  const positive = parseAnchored(w.filter((_, i) => i !== notIdx).join(" "));
+  const positive = parseSimpleClause(w.filter((_, i) => i !== notIdx).join(" "), nlp);
   if (!positive || positive.shape !== "ask") return null;
   return { ...positive, negated: true };
 }
@@ -1784,7 +1791,15 @@ function evalTemporal(graph, ast, opts) {
 }
 
 function evalSuperlative(graph, ast) {
-  const pool = graph.individuals.filter((i) => i.class === ast.entityType);
+  let pool = graph.individuals.filter((i) => i.class === ast.entityType);
+  // A tests-metric ranking over Modules surveys COVERAGE, and a test module
+  // is never a coverage target — the same exclusion renderUntested (the
+  // /untested surface) applies, so the two surveys can't disagree about the
+  // same set ("what most needs a test" used to name b.test.mjs).
+  if (ast.metric?.kind === "tests" && ast.entityType === "Module") {
+    const testSubjects = new Set(edgesOfKind(graph, "tests").map((e) => e.subject));
+    pool = pool.filter((i) => !testSubjects.has(i.id) && !isTestPath(String(i.label).toLowerCase()));
+  }
   const scored = pool.map((ind) => ({ ind, score: degreeMetric(graph, ind, ast.metric) }))
     .sort((a, z) => (ast.extreme === "most" ? z.score - a.score : a.score - z.score));
   if (!scored.length) return { compositeKind: "superlative", entityType: ast.entityType, matches: [] };
@@ -2608,7 +2623,10 @@ export function resolveObject(graph, term, opts = {}) {
     }
     return declineOnUnplacedWords(resolveObjectCore(graph, term, opts), term);
   }
-  return resolveObjectCore(graph, term, opts);
+  // The pinned-class branch honors the same contract — a term carrying words
+  // the index has no reading for declines instead of resolving past them
+  // ("the old Task" pinned to Class must not silently swallow "old").
+  return declineOnUnplacedWords(resolveObjectCore(graph, term, opts), term);
 }
 
 /** Resolve a term that may be a context pronoun ("this"/"it"/"that"/"here") —
@@ -2979,7 +2997,10 @@ export function traverse(graph, parsed, { contextId = null, prev = null, pinnedO
     if (entityType && entityType !== "Change") {
       const wantClasses = classesForKinds(graph, fwdKinds);
       const siblingClass = FINE_CLASS_SIBLING[entityType];
-      if (!wantClasses.has(entityType) && !(siblingClass && wantClasses.has(siblingClass))) {
+      // An edge-less kind (wantClasses empty) is not a grain mismatch — there
+      // is nothing to name after "only …", and the render leaked a literal
+      // "undefined" there. Fall through to the plain empty-edges answer.
+      if (wantClasses.size && !wantClasses.has(entityType) && !(siblingClass && wantClasses.has(siblingClass))) {
         return {
           matches: [], objMatch, candidates, ambiguous, matchedVia,
           forwardGrainMiss: true, wantClasses: [...wantClasses],
@@ -3451,13 +3472,48 @@ function renderCore(parsed, result, graph) {
   if (result.ambiguous) {
     // Name the actual candidates in the prose, not just the structured field
     // — "narrow the term" isn't actionable if the reader can't see the options.
-    const pool = [result.objMatch, ...(result.candidates || [])].filter(Boolean);
+    let pool = [result.objMatch, ...(result.candidates || [])].filter(Boolean);
+    let branches = result.branches;
+    // A relation question's object slot is a code entity, so a Commit/Session
+    // candidate (a prose-tier hit on a commit MESSAGE) is grain noise in the
+    // did-you-mean — dropped, along with its branch, unless the question is
+    // itself about touches/history where a commit genuinely fits.
+    if (parsed.kind && parsed.kind !== "touches" && !pool.every((i) => i.class === "Commit")) {
+      const grainOk = (i) => !["Commit", "Session", "Source", "Utterance"].includes(i?.class);
+      const kept = pool.filter(grainOk);
+      if (kept.length) {
+        pool = kept;
+        if (branches?.length) branches = branches.filter((b) => grainOk(b.candidate));
+      }
+    }
+    // The nearest REAL neighbour joins the list: a misremembered symbol
+    // ("saveTask") shares an identifier word with the real one ("saveStore"),
+    // which no containment/prose tier ever surfaces. Ranked by shared
+    // camelCase-split words (≥3 chars), edit distance breaking ties.
+    if (graph && !/[/.]/.test(String(parsed.object || ""))) {
+      const tLc = String(parsed.object || "").toLowerCase();
+      const termWords = new Set(splitIdentifierWords(String(parsed.object || "")).filter((w) => w.length >= 3));
+      const already = new Set(pool.map((i) => i.id));
+      let nearest = null;
+      let bestShared = 0;
+      let bestD = Infinity;
+      if (termWords.size) {
+        for (const i of graph.individuals) {
+          if (!["Function", "Method", "Class", "GlobalVariable", "Attribute"].includes(i.class) || already.has(i.id)) continue;
+          const shared = splitIdentifierWords(String(i.label)).filter((w) => termWords.has(w)).length;
+          if (!shared || shared < bestShared) continue;
+          const d = editDistance(String(i.label).toLowerCase(), tLc, 8);
+          if (shared > bestShared || d < bestD) { nearest = i; bestShared = shared; bestD = d; }
+        }
+      }
+      if (nearest) pool = [...pool, nearest];
+    }
     const noun = pool.length && pool.every((i) => i.class === "Commit") ? "commit" : "module";
     const shown = pool.slice(0, OVERFLOW_CAP).map((i) => i.label);
     const extra = pool.length > OVERFLOW_CAP ? `, …and ${pool.length - OVERFLOW_CAP} more` : "";
     const lead = `"${parsed.object}" matches more than one ${noun} ambiguously — did you mean ${listJoin(shown)}${extra}? Try one of those. If you're not sure, narrow it to one name.`;
-    const content = (result.branches && result.branches.length)
-      ? `${lead}\n${result.branches.map((b, i) => `${i + 1}) ${b.candidate.label}: ${b.rendered.content}`).join("\n")}`
+    const content = (branches && branches.length)
+      ? `${lead}\n${branches.map((b, i) => `${i + 1}) ${b.candidate.label}: ${b.rendered.content}`).join("\n")}`
       : lead;
     return {
       content, miss: false, ambiguous: true, candidates: pool.map((i) => i.label),

package/src/domain/codegraph.mjs

@@ -413,7 +413,11 @@ export function renderImpact(graph, ind, { maxDepth = 8 } = {}) {
       const tests = dep.tests.length
         ? `tests: ${capJoin(dep.tests, IMPACT_TESTS_PER_DEP)}`
         : "tests: none recorded";
-      lines.push(`  - ${dep.label} (${dep.via} it) — ${tests}`);
+      // Past depth 1 the via verb describes the hop to the dependent's own
+      // parent, not an edge to the changed module — saying "imports it" there
+      // would claim a direct edge that does not exist.
+      const receipt = i === 0 ? `${dep.via} it` : "reaches it through an intermediary";
+      lines.push(`  - ${dep.label} (${receipt}) — ${tests}`);
     }
     if (level.length > IMPACT_PER_DEPTH) lines.push(`  …+${level.length - IMPACT_PER_DEPTH} more at depth ${i + 1}`);
   });
@@ -425,7 +429,7 @@ export function renderImpact(graph, ind, { maxDepth = 8 } = {}) {
     lines.push(
       "warning: partial edge lists (" +
         truncatedStructural.map((t) => `${t.predicate}: ${t.shown}/${t.count}`).join(", ") +
-        ") — this closure may be missing edges. Cross-check critical results with tmct_search.",
+        ") — this closure may be missing edges. Cross-check critical results with a lexical search (/find <term>).",
     );
   }
   return lines.join("\n");

package/src/domain/interpret/normalize.mjs

@@ -132,7 +132,7 @@ const THANKS_PREAMBLE_RE = /^(?:thanks|thank\s+you|many\s+thanks|thx|ty|cheers)(
 const ACK_PREAMBLE_RE = /^(?:(?:ok(?:ay)?|aight|cool|alright|sure|right|fine|great|nice|got it|gotcha|sounds good|no worries|no problem)[\s,]+)+(.+)$/i;
 /** Self-orientation lead-in with a delimiter — "just poking around, <Q>",
  *  "first time using this, <Q>". */
-const BROWSING_PREAMBLE_RE = /^(?:just\s+(?:poking\s+around|looking\s+around|browsing|exploring|checking\s+(?:this|it)\s+out)|first\s+time\s+(?:trying\s+this\s+out|using\s+this|here))\s*[,.—–-]\s*(.+)$/i;
+const BROWSING_PREAMBLE_RE = /^(?:just\s+(?:poking\s+around|looking\s+around|browsing|exploring|checking\s+(?:this|it)\s+out)|first\s+time\s+(?:trying\s+this\s+out|using\s+this|here)|i'?m\s+new\s+(?:here|around\s+here|to\s+(?:this|all\s+this)(?:\s+(?:repo|codebase|project|app|tool|thing))?))\s*[,.—–-]\s*(.+)$/i;
 /** Repeated leading hedge adverb before a polite request verb ("maybe
  *  possibly tell me <Q>"). No delimiter required, unlike ACK_PREAMBLE_RE. */
 const HEDGE_ADVERB_PREAMBLE_RE = /^(?:(?:maybe|possibly|perhaps)\s+)+(.+)$/i;

package/src/domain/router/registry.mjs

@@ -41,6 +41,7 @@ export const PRECOND = Object.freeze({
   graphLoaded: "cap:graph-loaded", // a graph artifact is present + parseable
   resolves: "cap:resolves", // { param, as } — the slot binds to an entity of kind `as`
   anyPresent: "cap:any-present", // { params } — at least one of these slots is provided
+  memoryFacts: "cap:memory-facts", // the conversational-memory store holds relation facts for the term
 });
 
 // ---- capability builder (returns PLAIN FROZEN data) -------------------------
@@ -57,6 +58,11 @@ const resolves = (paramName, as) =>
 /** any-present(params) — search-style disjunction (query OR kind must be given). */
 const anyPresent = (params) =>
   Object.freeze({ type: VOCAB.Precondition, pred: PRECOND.anyPresent, params: Object.freeze([...params]) });
+/** memory-facts — the memory graph holds mgx:synonym / mgx:relatedTo / mgx:similarTo
+ *  facts for the term. The memory-graph sibling of graph-loaded: the SKOS view
+ *  answers from the conversational-memory store and misses honestly without it,
+ *  with or without a code-map graph. */
+const memoryFacts = () => Object.freeze({ type: VOCAB.Precondition, pred: PRECOND.memoryFacts });
 
 /** Add-effect: after the call the agent knows `topic` about `?of`. */
 const knows = (topic, ofParam = null) =>
@@ -80,7 +86,8 @@ function capability({ name, label, question, params = [], preconditions = [], ad
 // Arg keys verified against src/tools/server.mjs `dispatchTool`'s switch: describe/callers/
 // callees/tests/history/… take `symbol`; impact/exports take `module`; members/
 // subclasses take `class`; search takes `query` (+ optional kind/name/decorator);
-// architecture takes an optional `package`; untested takes nothing.
+// architecture takes an optional `package`; untested takes nothing; related
+// takes `term` (a memory-graph concept term).
 
 const CAPABILITIES = Object.freeze([
   capability({
@@ -107,9 +114,9 @@ const CAPABILITIES = Object.freeze([
     add: [knows("signature", "symbol")],
   }),
   capability({
-    name: "tmct_impact", label: "impact", question: "what a change to this module reaches (impact closure)",
-    params: [param("module", KINDS.Module)],
-    preconditions: [graphLoaded(), resolves("module", KINDS.Module)],
+    name: "tmct_impact", label: "impact", question: "what a change to this module or symbol reaches (impact closure)",
+    params: [param("module", KINDS.Symbol, { note: "a Module, or any sited symbol — a fine-grained seed walks callsSymbol dependents and coarsens them to module grain" })],
+    preconditions: [graphLoaded(), resolves("module", KINDS.Symbol)],
     add: [knows("impact", "module")],
   }),
   capability({
@@ -178,6 +185,12 @@ const CAPABILITIES = Object.freeze([
     preconditions: [graphLoaded()],
     add: [knows("architecture", "package")],
   }),
+  capability({
+    name: "tmct_related", label: "related", question: "a term's synonyms and related concepts (the SKOS view over the conversational-memory graph)",
+    params: [param("term", KINDS.Query, { note: "a concept term, matched against memory relation facts rather than resolved in the code graph" })],
+    preconditions: [memoryFacts()],
+    add: [knows("related", "term")],
+  }),
 ]);
 
 // The live capability set: the built-in frozen array is the seed; registration

package/src/domain/router/resolver.mjs

@@ -56,8 +56,10 @@ export const UNMAPPED_KINDS = Object.freeze({
 
 // ---- capabilities the NL surface cannot reach today (named, not accidental) ---
 // A declared capability with no NL/command/frame path is a routing gap and must be tagged
-// here with the reason. Every capability is currently reachable, so this is empty.
-export const NOT_NL_REACHABLE = Object.freeze({});
+// here with the reason.
+export const NOT_NL_REACHABLE = Object.freeze({
+  tmct_related: "the SKOS synonym/related surface is served by the chat lane's own recogniser over the memory graph; a router frame for it needs memory-term binding, which resolveObject (code-graph-only) does not prove yet",
+});
 
 // ---- imperative intent FRAMES (fills what the relational grammar and command register
 // both miss). regex -> { topic, arg | noArg }. Ordered: first match wins.