@polycode-projects/the-mechanical-code-talker 3.1.2 → 3.1.4

package/corpus/seon/relations.jsonl

@@ -7,3 +7,5 @@
 {"relation":"touches","definition":"A touch is a commit changing a file or a symbol in the codebase.","sense":"software"}
 {"relation":"cochange","definition":"Change-coupling is two files that tend to be changed together in the same commits.","sense":"software"}
 {"relation":"reexports","definition":"A re-export is a module passing another module's definition through as part of its own public API.","sense":"software"}
+{"relation":"serves","definition":"A service edge is one part of the codebase providing or backing another, such as a handler serving a route.","sense":"software"}
+{"relation":"denotes","definition":"A denotation is a vocabulary term naming a code entity, linking the word to the thing it refers to.","sense":"software"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "3.1.2",
+  "version": "3.1.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; indexes a repo on request (tmct index) or reads any producer's graph.",

package/src/adapters/repository-interface.mjs

@@ -46,6 +46,7 @@ export const MISS_REASONS = Object.freeze({
 export const EDGE_KINDS = Object.freeze([
   "imports", "calls", "callsSymbol", "defines", "tests",
   "touches", "touchesSymbol", "contains", "inherits", "cochange", "reexports",
+  "serves", "denotes",
 ]);
 
 /** edge-kind → the `tmct:` object property it realizes (the OWL grounding). */
@@ -61,6 +62,8 @@ export const EDGE_KIND_TO_TMCT = Object.freeze({
   inherits: "tmct:extends",
   cochange: "tmct:dependsOn",
   reexports: "tmct:exports",
+  serves: "tmct:serves",
+  denotes: "tmct:denotes",
 });
 
 /** The named services, grouped as in the plan's six-group inventory. Names are

package/src/adapters/wink-model.mjs

@@ -3,14 +3,23 @@
 //
 // A static `import "wink-nlp"` would drag the ~1 MB model into the base/viewer bundle.
 // Instead, `registerWinkModel` lets a browser/bundler entry hand in an already-imported
-// `{ winkNLP, model }` pair once; Node instead resolves lazily via `createRequire`.
+// `{ winkNLP, model }` pair once; Node instead resolves lazily via `createRequire`,
+// fetched at call time from `process.getBuiltinModule("node:module")` rather than a
+// top-level `import { createRequire } from "node:module"`. A top-level import declares
+// the `createRequire` binding in this module's own output, and a downstream consumer
+// that bundles tmct alongside other CJS dependencies (esbuild, `--format=esm`) can
+// inject its own auto-generated `createRequire` shim into the same bundle scope,
+// producing a duplicate top-level declaration and a `SyntaxError` at Node module-parse
+// time. Resolving it lazily via `process.getBuiltinModule` keeps the bundled output free
+// of any top-level `createRequire` declaration, so there's nothing left to collide with.
+// Don't "simplify" this back to a top-level import. `process.getBuiltinModule` needs
+// Node 22.3.0/20.16.0+; this package's `engines.node` floor (">=24") already clears
+// that, so lowering the floor later needs to keep clearing it too.
 //
 // The loader stays synchronous. Failure is cached as null — a checkout without the
 // optional deps, or a page that never registered a model, runs adapter-less rather
 // than throwing.
 
-import { createRequire } from "node:module";
-
 let injected; // browser/bundler-supplied `() => ({ winkNLP, model })`, or undefined
 let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
 
@@ -40,7 +49,7 @@ function loadWinkModel() {
 /** Node fallback: resolve wink through the module system (never a guessed path).
  *  CJS deps, so `createRequire`. */
 function nodeRequireWink() {
-  const require = createRequire(import.meta.url);
+  const require = process.getBuiltinModule("node:module").createRequire(import.meta.url);
   return {
     winkNLP: require("wink-nlp"),
     model: require("wink-eng-lite-web-model"),

package/src/domain/code-explorer-hints.mjs

@@ -42,6 +42,8 @@ const FORWARD_TEMPLATE = Object.freeze({
   contains: (f) => `what is in ${f}`,
   defines: (f) => `what does ${f} define`,
   inherits: (f) => `what does ${f} inherit from`,
+  serves: (f) => `what does ${f} serve`,
+  denotes: (f) => `what does ${f} denote`,
 });
 
 // Reverse reading (focus is the object): "what <kind> <focus>".
@@ -51,6 +53,8 @@ const REVERSE_TEMPLATE = Object.freeze({
   tests: (f) => `what tests ${f}`,
   inherits: (f) => `what inherits from ${f}`,
   contains: (f) => `what contains ${f}`,
+  serves: (f) => `what serves ${f}`,
+  denotes: (f) => `what denotes ${f}`,
 });
 
 /** Index a payload into the counts and adjacency the hints read: class →

package/src/domain/codeplan/graph-delta.mjs

@@ -30,6 +30,7 @@ export const ENTITY_CLASSES = Object.freeze([
 export const EDGE_PREDICATES = Object.freeze([
   "imports", "calls", "callsSymbol", "defines", "tests",
   "touches", "touchesSymbol", "contains", "inherits", "cochange", "reexports",
+  "serves", "denotes",
 ]);
 
 /** The closed effect vocabulary — every way an operator's declared delta can

package/src/domain/concept.mjs

@@ -219,6 +219,10 @@ export const RELATION_TERM = Object.freeze({
   export: "reexports", exports: "reexports", exporting: "reexports", exported: "reexports",
   reexport: "reexports", reexports: "reexports", reexporting: "reexports",
   "re-export": "reexports", "re-exports": "reexports", "re-exporting": "reexports",
+  // provider-declared kinds: tmct's own indexer emits neither, so a graph it
+  // built degrades to the honest two-band "no edges" answer rather than a miss.
+  serve: "serves", serves: "serves", serving: "serves", served: "serves",
+  denote: "denotes", denotes: "denotes", denoting: "denotes", denoted: "denotes",
 });
 
 /** concept key → the relationKind()s whose edges it enumerates. A concept can span
@@ -234,6 +238,8 @@ const RELATION_KINDS = Object.freeze({
   touches: ["touches", "touchesSymbol"],
   cochange: ["cochange"],
   reexports: ["reexports"],
+  serves: ["serves"],
+  denotes: ["denotes"],
 });
 
 /** concept key → the verb phrase that renders an edge as an English sentence
@@ -248,6 +254,8 @@ const RELATION_RENDER = Object.freeze({
   touches: { verb: "touches", edgeNoun: "touch" },
   cochange: { verb: "changes together with", edgeNoun: "change-coupling" },
   reexports: { verb: "re-exports", edgeNoun: "re-export" },
+  serves: { verb: "serves", edgeNoun: "service" },
+  denotes: { verb: "denotes", edgeNoun: "denotation" },
 });
 
 /** Per concept key, the candidate follow-up shapes in priority order — each
@@ -290,6 +298,14 @@ const RELATION_FOLLOWUP_SHAPES = Object.freeze({
     { side: "subj", make: (x) => `what does ${x} export` },
     { side: "obj", make: (x) => `where is ${x} defined` },
   ],
+  serves: [
+    { side: "subj", make: (x) => `what does ${x} serve` },
+    { side: "obj", make: (x) => `what serves ${x}` },
+  ],
+  denotes: [
+    { side: "subj", make: (x) => `what does ${x} denote` },
+    { side: "obj", make: (x) => `what denotes ${x}` },
+  ],
 });
 
 /** How many example edges the relation force shows before the remainder is held for

package/src/domain/interpret/normalize.mjs

@@ -186,6 +186,12 @@ const EMBEDDED_MEANS_RE = /^what\s+((?:an?\s+|the\s+)?[\w'-]+(?:\s+[\w'-]+){0,2}
  *  untouched, a relation/interrogative remainder unwraps to itself, anything
  *  else bridges to "describe <thing>". */
 const SHOW_GIVE_ME_RE = /^(?:show|give)\s+me\s+(?:the\s+)?(.+?)\??$/i;
+/** An "everything I need [to <verb>|for X]" remainder always bridges to
+ *  "describe <thing>", even when its purpose clause happens to contain a
+ *  relation verb ("everything I need to change X") — RELATION_VERB_RE's
+ *  bag-of-words probe would otherwise misread that verb as making the
+ *  remainder itself an already-relational clause. */
+const EVERYTHING_I_NEED_RE = /^everything\s+i(?:'d|\s+would)?\s+need\b/i;
 
 /** Leading STACCATO connective before an ALREADY well-formed question ("and
  *  what imports it") -> the question alone. Gated on the remainder starting
@@ -254,7 +260,9 @@ export function applyPreambleFrames(text) {
     if (m) {
       const rest = m[1].trim();
       if (!isListingRemainder(rest)) {
-        q = (RELATION_VERB_RE.test(rest) || INTERROGATIVE_LEAD_RE.test(rest)) ? rest : `describe ${rest}`;
+        const isRelationClause = !EVERYTHING_I_NEED_RE.test(rest)
+          && (RELATION_VERB_RE.test(rest) || INTERROGATIVE_LEAD_RE.test(rest));
+        q = isRelationClause ? rest : `describe ${rest}`;
       }
     }
     m = q.match(LEADING_CONNECTIVE_RE);

package/src/domain/module-paths.mjs

@@ -2,8 +2,10 @@
 // the rankers that read what they build.
 
 /** Does this module path (or a lowercased path-shaped label) belong to test code?
- *  Covers `test/` and `tests/` segments, Python's `test_*.py` convention, and
- *  .NET's `*.Tests` assembly suffix. Case-sensitive: callers holding mixed-case
- *  paths lowercase first. */
+ *  Covers `test/` and `tests/` segments, a hyphen/underscore-prefixed test directory
+ *  (`behaviour-tests/`, `unit_test/`), Python's `test_*.py` convention, .NET's
+ *  `*.Tests` assembly suffix, and a `.test`/`.spec` file anywhere in the tree.
+ *  Case-sensitive: callers holding mixed-case paths lowercase first. */
 export const isTestPath = (p) =>
-  /(^|\/)tests?\//.test(p) || /(^|\/)test_[^/]*\.py$/.test(p) || /\.tests(\.|$)/.test(p);
+  /(^|\/)tests?\//.test(p) || /(^|\/)test_[^/]*\.py$/.test(p) || /\.tests(\.|$)/.test(p)
+  || /(^|\/)[^/]*[-_]tests?\//.test(p) || /\.(test|spec)\.[cm]?[jt]sx?$/.test(p);

package/src/services/chat.mjs

@@ -128,6 +128,8 @@ const GOAL_BY_KIND = {
   touchesSymbol: "understand commit/change history",
   cochange: "understand change-coupling between modules",
   reexports: "understand a module's public exports/API surface",
+  serves: "understand which component provides or backs another",
+  denotes: "understand which vocabulary term names a code entity",
 };
 const goalNoun = (entityType) => (entityType ? `${String(entityType).toLowerCase()}(s)` : "entities");
 
@@ -2240,6 +2242,8 @@ const MISS_EXAMPLES = {
   define: ['"where is <name> defined"', '"where is <name> mentioned"'],
   meaning: ['"what is a <ClassName>"', '"what does <term> mean"'],
   count: ['"how many classes are there"', '"how many modules are there"'],
+  serve: ['"what does <name> serve"', '"what serves <name>"'],
+  denote: ['"what does <name> denote"', '"what denotes <name>"'],
 };
 const MISS_DEFAULT = ['"which modules import <name>"', '"what calls <name>"'];
 
@@ -2251,6 +2255,8 @@ function tailoredExamples(q) {
   const has = (re) => re.test(q);
   if (has(/\bimport/)) return MISS_EXAMPLES.import;
   if (has(/\bexport/)) return MISS_EXAMPLES.export;
+  if (has(/\bserv(?:e|es|ed|ing|ice)\b/)) return MISS_EXAMPLES.serve;
+  if (has(/\bdenot(?:e|es|ed|ing|ation)\b/)) return MISS_EXAMPLES.denote;
   if (has(/\b(?:calls?|caller|callee)\b/)) return MISS_EXAMPLES.call;
   if (has(/\b(?:tests?|cover|covering|tested)\b/)) return MISS_EXAMPLES.test;
   if (has(/\b(?:inherit|subclass|extends?|superclass|hierarchy|base class|parent class)\b/)) return MISS_EXAMPLES.inherit;
@@ -11009,9 +11015,18 @@ const DESCRIBE_GRAIN_WORD_RE = new RegExp(
  *  whole tail into the term), and every resolver downstream then reads
  *  "context" as part of the name. Closed list, and the term still has to
  *  resolve afterwards, so a phrase that leaves nothing resolvable simply
- *  declines to the ordinary miss. */
+ *  declines to the ordinary miss.
+ *
+ *  The "everything i need ..." branch is the same shape with a purpose clause
+ *  instead of a bare noun: "give me everything i need to change X"/"...for X"
+ *  both reach here as "describe everything i need to change X"/"describe
+ *  everything i need for X". The "to <verb...>" purpose clause is never split
+ *  word-by-word (a multi-word clause like "to work on X" would mis-split into
+ *  a captured verb plus a dangling remainder) — the greedy `.*\s` instead
+ *  always backtracks to the LAST whitespace run in the match, so the whole
+ *  clause strips as one unit and only the trailing symbol/path survives. */
 const DESCRIBE_LEADING_NOISE_RE =
-  /^(?:the\s+)?(?:context|details|detail|info|information|background)\s+(?:for|on|about|of|around)\s+/i;
+  /^(?:(?:the\s+)?(?:context|details|detail|info|information|background)\s+(?:for|on|about|of|around)\s+|everything\s+i(?:'d|\s+would)?\s+need\s+(?:to\s+.*\s|for\s+))/i;
 function stripDescribeLeadingNoise(term) {
   const stripped = String(term || "").replace(DESCRIBE_LEADING_NOISE_RE, "").trim();
   return stripped || String(term || "").trim();
@@ -13355,6 +13370,15 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
     const described = await describeWrapperAnswer(query, { config, source, focus: newFocus, graph, tel });
     if (described) {
       answer = described.text; via = described.miss ? "miss" : "describe"; recordMiss = !!described.miss;
+      // The composed engine's failed parse above (`via` was still "composed"
+      // to reach this lane at all) can have deduced a goal/canonical for a
+      // DIFFERENT reading it never resolved — e.g. "give me everything i need
+      // to change X" bag-of-words-matches "change" as a touches verb and
+      // deduces subject="describe everything i need". This rescue answers a
+      // different question, so that stale interpretation must not survive
+      // into its answer (same staleness the FUZZY-VERB DECLINE lane guards
+      // against, below).
+      canonical = null; deduced = null;
       note(trace, "lane: (4d) DESCRIBE-WRAPPER RESCUE — a polite wrapper around \"describe/tell me about <symbol>\" resolved via /describe, tried last after every other lane declined");
       note(trace, "goal: get a symbol's definition/kind/relations (phrased conversationally)");
       // Carry the resolved entity forward as the new focus, same class-gated