@polycode-projects/the-mechanical-code-talker 1.5.4 → 1.8.3

package/src/ask-vocab.mjs

@@ -324,17 +324,37 @@ const TRAILING_DISCOURSE_TAG_RE = new RegExp(
   `\\s+(?:${TRAILING_DISCOURSE_TAG.join("|")})\\s*[?.!]*$`, "i",
 );
 
-/** Strip trailing bare discourse tags (TRAILING_DISCOURSE_TAG, above) off the
- *  end of a captured meta-whatis term — "what is a component then" resolves
- *  the same term as "what is a component". Applied up to twice (a stacked
- *  "too then"/"then too" is the only worked case that ever needs a second
- *  pass; no phrasing seen so far stacks a third), mirroring
- *  stripTrailingScopeFiller's own single-clause discipline for the common
- *  single-tag case while still covering the rarer double-tag one. */
+/** Trailing COMMA-delimited discourse clauses ("what is a class, please
+ *  explain") — a distinct shape from TRAILING_DISCOURSE_TAG above (a bare
+ *  space-led tag, no comma): an ESL follow-on clause tacked onto a
+ *  meta-whatis term after a comma, meaning "please explain [it]", not part of
+ *  the term itself (BENCHMARK_CONVERSATION_1.7.0.md routed backlog C1). Closed
+ *  and curated exactly like TRAILING_DISCOURSE_TAG — anchored on a LITERAL
+ *  comma immediately before the tag, so this can never fire mid-phrase and
+ *  can never touch a term that merely contains a comma for some other reason
+ *  (no real code identifier ends in ", please explain" or ", explain"). */
+export const TRAILING_DISCOURSE_CLAUSE = Object.freeze(["please explain", "explain"]);
+
+const TRAILING_DISCOURSE_CLAUSE_RE = new RegExp(
+  `,\\s*(?:${TRAILING_DISCOURSE_CLAUSE.join("|")})\\s*[?.!]*$`, "i",
+);
+
+/** Strip trailing bare discourse tags (TRAILING_DISCOURSE_TAG, above) AND
+ *  trailing comma-delimited discourse clauses (TRAILING_DISCOURSE_CLAUSE,
+ *  above) off the end of a captured meta-whatis term — "what is a component
+ *  then" resolves the same term as "what is a component", and "what is a
+ *  class, please explain" resolves the same term as "what is a class".
+ *  Applied up to twice (a stacked "too then"/"then too" is the only worked
+ *  case that ever needs a second pass; no phrasing seen so far stacks a
+ *  third), mirroring stripTrailingScopeFiller's own single-clause discipline
+ *  for the common single-tag case while still covering the rarer
+ *  double-tag one. The comma-clause strip runs each pass too, so "class,
+ *  please explain then" (an unworked but plausible stack) still resolves. */
 export function stripTrailingDiscourseTag(text) {
   let out = text;
   for (let pass = 0; pass < 2; pass += 1) {
-    const next = out.replace(TRAILING_DISCOURSE_TAG_RE, "").trim();
+    let next = out.replace(TRAILING_DISCOURSE_TAG_RE, "").trim();
+    next = next.replace(TRAILING_DISCOURSE_CLAUSE_RE, "").trim();
     if (next === out) break;
     out = next;
   }
@@ -349,6 +369,48 @@ export const VERB_TO_KIND = Object.freeze(
   ),
 );
 
+/** "what is a kind of X" / "what is a subclass of X" collision fix (2026-07-11,
+ *  live-repro: "boney is a dog" -> "what is a dog" -> "what is a kind of
+ *  animal" hit a forced disambiguation wall instead of answering). grammar.mjs's
+ *  T5 "meta-whatis" template reads "what is a/an <object>" as a literal
+ *  glossary/term-definition question ("what is a Commit"). But some registered
+ *  inherits verbs are THEMSELVES phrased "is a <continuation>" ("is a kind
+ *  of", "is a subclass of" — RELATIONS.inherits.verbs above) — when the object
+ *  T5 captures IS one of these continuations plus a real term ("kind of
+ *  animal"), the sentence isn't asking to define the noun phrase "kind of
+ *  animal"; it's the exact same question as "what inherits from animal", just
+ *  phrased with the verb's own "is a" lead instead of "inherits". keyword-spot
+ *  (keywords.mjs) already reads it that way, unambiguously — the meta reading
+ *  is the spurious one, and it collides with keyword-spot's correct reading to
+ *  manufacture a needless {ambiguousParse} tie (interpret/merge.mjs) over a
+ *  phrasing the engine itself just used a turn earlier. Derived from
+ *  VERB_TO_KIND (not hand-duplicated) so any future plain "is a/are a X of"
+ *  verb phrase added to RELATIONS is covered automatically, without touching
+ *  this file again.
+ *
+ *  Deliberately EXCLUDES every INHERITS_REVERSE_VERBS entry ("is a superclass
+ *  of", "is a parent class of") even though they match the same "is a
+ *  <continuation>" shape: those verbs' subject/object are semantically
+ *  SWAPPED relative to storage direction (see INHERITS_REVERSE_VERB_LIST's own
+ *  comment above) — "what is a superclass of X" asks a FORWARD question
+ *  (X's own supertype), not this reverse-by-object listing, and keyword-spot's
+ *  decomposition only applies that swap in the two-sided "ask" shape (verb
+ *  between a subject AND an object), not this "reverse"-only afterText-only
+ *  shape. Suppressing the meta reading for these too would trade one honest
+ *  {ambiguousParse} wall for a confusing WRONG answer (a reverse-by-object
+ *  lookup with the direction backwards) — a separate, pre-existing gap in
+ *  keywords.mjs, out of this fix's scope. */
+const NON_REVERSE_VERB = (v) => !INHERITS_REVERSE_VERBS.includes(v);
+export const ARTICLE_RELATION_CONTINUATIONS = Object.freeze([
+  ...new Set(
+    Object.keys(VERB_TO_KIND)
+      .filter(NON_REVERSE_VERB)
+      .map((v) => v.match(/^(?:is|are)\s+an?\s+(.+)$/i))
+      .filter(Boolean)
+      .map((m) => m[1].toLowerCase()),
+  ),
+]);
+
 export const ENTITY_TO_TYPE = Object.freeze({
   function: "Function", functions: "Function",
   method: "Method", methods: "Method",
@@ -470,6 +532,10 @@ export const MISSPELLINGS = Object.freeze({
   "extands": "extends", "extneds": "extends",
   "depnds": "depends",
   "touchs": "touches", "tuoches": "touches", "touhced": "touched",
+  // "touchd" (BENCHMARK_CONVERSATION_1.7.0.md routed backlog C3): the
+  // dropped-vowel slip of "touched" — distinct from "touhced" above
+  // (transposed letters), same curated-typo discipline.
+  "touchd": "touched",
   // WHERE_MARKERS typo (0.9.13 Tier-1 playtest): "defined" itself had no typo
   // entry, so "where is it defned" fell through to the bare-object search path
   // instead of the where-shape ("no module matching 'it defned' found").
@@ -498,6 +564,12 @@ export const MISSPELLINGS = Object.freeze({
   // anchor; the correction regex's dotted-extension guard keeps a module
   // literally named "wat.mjs" untouched, same residual trade as every entry.
   "waht": "what", "wat": "what",
+  // "dat" (BENCHMARK_CONVERSATION_1.7.0.md routed backlog C3): the internet-
+  // casual spelling of "that" — same register as "wat"/"waht" just above,
+  // curated rather than left to the generic fuzzy tier since "that" is a
+  // load-bearing anchor word throughout this grammar (TEACH_RE's own
+  // "remember that X", relative-clause objects, etc).
+  "dat": "that",
   "dose": "does", "doess": "does",
   "teh": "the",
   // aggregate/list TRIGGER words (2026-07-02, trigger-typo work) — a typo of a count
@@ -788,6 +860,7 @@ export const EDGE_NOUN_TO_METRIC = Object.freeze({
   methods: { kind: "contains", dir: "out", filter: "Method" },
   members: { kind: "contains", dir: "out" },
   tests: { kind: "tests", dir: "in" },
+  test: { kind: "tests", dir: "in" }, // singular ("needs a test") — same edge as plural "tests"
   subclasses: { kind: "inherits", dir: "in" },
   connections: { kind: "*", dir: "both" },
   edges: { kind: "*", dir: "both" },
@@ -805,6 +878,18 @@ export const EDGE_NOUN_TO_METRIC = Object.freeze({
   called: { kind: "calls", dir: "in", sibling: "callsSymbol" },
 });
 
+/** Metric nouns whose edge kind targets exactly ONE entity class in this graph's
+ *  ontology (only a Module is ever the object of a `tests` edge) — read by
+ *  ask.mjs's parseSuperlative to default `entityType` when a superlative names a
+ *  metric but no explicit entity noun ("what most needs a test", vs. the fully
+ *  explicit "which MODULE has the most tests"). Deliberately small: a metric like
+ *  "calls"/"connections" targets more than one class, so it is NOT listed here —
+ *  those keep requiring an explicit entity noun, same as before this table existed. */
+export const METRIC_IMPLIES_ENTITY = Object.freeze({
+  tests: "Module",
+  test: "Module",
+});
+
 /** Anaphora triggers over the PREVIOUS result set (ask()'s `prev` id array):
  *  "which of those/them/these …", "how many of those …". The pronoun refers to the
  *  last answer's ids, not a graph term — with no prev supplied it is an honest miss