@polycode-projects/the-mechanical-code-talker 1.11.6 → 2.0.1

package/src/{source.mjs → adapters/source.mjs}

@@ -71,7 +71,7 @@ async function readOneGraphFile(file) {
   }
 }
 
-/** The multi-graph path (src/graph-merge.mjs): config.graphFiles names MORE
+/** The multi-graph path (src/adapters/graph-merge.mjs): config.graphFiles names MORE
  *  THAN ONE graph file. Reads each (same per-file ENOENT→bootstrap tolerance
  *  as the single-graph path), merges them via mergeEntityPayloads, and caches
  *  the merge under a composite key (the sorted, joined file list) — so

package/src/{toml-config.mjs → adapters/toml-config.mjs}

@@ -110,7 +110,7 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   if (seed.limit !== undefined) seedCfg.limit = seed.limit;
   if (Object.keys(seedCfg).length) cfg.seed = seedCfg;
 
-  // Extension-pack seam (src/extensions.mjs): sparse PASS-THROUGH only — the
+  // Extension-pack seam (src/services/extensions.mjs): sparse PASS-THROUGH only — the
   // raw `[extensions]`/`[bias]` tables ride through unmodified so a caller can
   // see they're present; validation happens one layer up, in
   // resolveExtensions() (never here — this module stays a plain raw reader).

package/src/{answer-variants.json → domain/answer-variants.json}

@@ -1,6 +1,6 @@
 {
   "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.",
+  "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/domain/answer-variants.mjs for how these are selected at render time.",
   "pools": {
     "defined-in": {
       "base": "defined in",

package/src/domain/answer-variants.mjs

@@ -0,0 +1,23 @@
+// answer-variants.mjs — deterministic, committed answer-phrasing variety for
+// a curated set of answer templates (answer-variants.json).
+//
+// Selection is a pure hash of (poolId, key), never Math.random/Date.now, so
+// output is byte-identical across runs (pinnable in tests). The data rides in
+// as a JSON module (no filesystem read at import or call time); the browser
+// bundle stubs this whole module to the base-phrase identity, so the dock's
+// wording never varies.
+
+import variantData from "./answer-variants.json" with { type: "json" };
+import { sha256Bytes } from "./hash.mjs";
+
+/** Deterministically choose `base` or one of `poolId`'s committed variants,
+ *  keyed on `key`. Any failure (unknown pool, missing data, falsy `key`)
+ *  falls back to `base`. */
+export function pickPhrase(poolId, key, base) {
+  if (!key) return base;
+  const variants = variantData?.pools?.[poolId]?.variants;
+  if (!Array.isArray(variants) || !variants.length) return base;
+  const forms = [base, ...variants];
+  const idx = sha256Bytes(`${poolId}:${String(key)}`)[0] % forms.length;
+  return forms[idx];
+}

package/src/{ask-vocab.mjs → domain/ask-vocab.mjs}

@@ -2,9 +2,15 @@
 // hint, and renderer noun forms derive from. No NLP library or lemmatiser:
 // plain phrase lists feeding the same fixed-precedence regex grammar.
 
-/** relation token -> { comment, verbs[] }. Each `verbs` list spans formal,
+/** relation token -> { bare, comment, verbs[] }. Each `verbs` list spans formal,
  *  neutral, and casual phrasings of the same relation; a misparse costs
- *  nothing beyond an honest object-miss (resolveObject never guesses). */
+ *  nothing beyond an honest object-miss (resolveObject never guesses).
+ *
+ *  `bare` is the relation's base verb form, for frames that need an infinitive
+ *  rather than the inflected relation token ("modules that do not IMPORT x",
+ *  where the token would read "do not imports"). Hand-curated per relation, the
+ *  same closed-vocabulary discipline as `verbs`: deriving it by stripping an
+ *  "s" is a morphology rule that gets "touches" and "co-change with" wrong. */
 // Reverse `inherits` phrasings ("is X a superclass of Y") name the same
 // relation as the forward verbs above but with subject/object swapped, so
 // they're kept in INHERITS_REVERSE_VERB_LIST too: strategies that build "ask"
@@ -24,6 +30,7 @@ const INHERITS_REVERSE_VERB_LIST = [
 
 export const RELATIONS = {
   imports: {
+    bare: "import",
     comment: "Module -> Module: subject's import graph references object (usesComplexType).",
     verbs: [
       // formal/neutral ("uses code from" stays here: its phrasing is
@@ -41,14 +48,16 @@ export const RELATIONS = {
   // query-side union, not a stored predicate: ask.mjs traverses "uses" as
   // imports + calls + callsSymbol together (KIND_UNIONS).
   uses: {
+    bare: "use",
     comment: "query-side union: imports (Module->Module) + calls (Module->Module) + callsSymbol (fn->fn).",
     verbs: [
-      "uses", "use", "used by", "makes use of", "make use of",
+      "uses", "use", "makes use of", "make use of",
       // gerund (g-drop normalization)
       "using",
     ],
   },
   calls: {
+    bare: "call",
     comment: "Function/Method -> Function/Class (symbol-grain) or Module -> Module (coarse): subject invokes object.",
     verbs: [
       // formal
@@ -62,6 +71,7 @@ export const RELATIONS = {
     ],
   },
   defines: {
+    bare: "define",
     comment: "Module -> top-level Function/Class/Method/Attribute: subject declares object.",
     verbs: [
       "defines", "define", "declares", "declare",
@@ -71,6 +81,7 @@ export const RELATIONS = {
     ],
   },
   contains: {
+    bare: "contain",
     comment: "Class -> Method/Attribute: subject's membership includes object.",
     verbs: [
       "contains", "contain", "lives in", "live in", "is defined in", "are defined in",
@@ -80,6 +91,7 @@ export const RELATIONS = {
     ],
   },
   tests: {
+    bare: "test",
     comment: "Module -> Module: subject is a test module importing/covering object.",
     verbs: [
       "tests", "test", "covers", "cover", "verifies", "verify", "exercises", "exercise",
@@ -89,6 +101,7 @@ export const RELATIONS = {
     ],
   },
   inherits: {
+    bare: "inherit from",
     comment: "Class -> Class: subject's declared base resolves to object (subclassOf).",
     verbs: [
       "inherits from", "inherit from",
@@ -104,6 +117,7 @@ export const RELATIONS = {
     ],
   },
   touches: {
+    bare: "touch",
     comment: "Commit -> Module (coarse) or Commit -> symbol (fine, touchesSymbol): a commit's changed-line-range intersects object.",
     verbs: [
       "touched", "touches", "changed", "change", "modified", "modifies",
@@ -111,8 +125,10 @@ export const RELATIONS = {
       "was modified by", "were modified by", "was tweaked in", "were tweaked in",
       "got changed in", "got edited in",
       // the same touch relation asked from the commit's side ("what did
-      // commit <sha> touch")
-      "touch", "touched by", "modified by", "changed by", "changed in",
+      // commit <sha> touch"). "touched by"/"modified by"/"changed by" are absent
+      // on purpose: they mark a passive AGENT, so swallowing the "by" here would
+      // hide the passive from the strategy that reads it and invert the operands.
+      "touch", "changed in",
       "landed in", "land in",
       // "was in"/"went into" only read as touch questions against a
       // sha-shaped object
@@ -123,6 +139,7 @@ export const RELATIONS = {
     ],
   },
   cochange: {
+    bare: "co-change with",
     comment: "Module -> Module: subject and object are frequently committed together (changeCoupledWith).",
     verbs: [
       "changed with", "co-changes with", "co-change with", "changes alongside",
@@ -135,6 +152,7 @@ export const RELATIONS = {
     ],
   },
   reexports: {
+    bare: "re-export",
     comment: "Module -> exported symbol: subject's public API surface (__all__/export list).",
     verbs: [
       "exports", "export", "re-exports", "re-export", "passes through", "pass through",
@@ -159,6 +177,12 @@ export const INHERITS_REVERSE_VERBS = Object.freeze([
 /** Definition-location markers: "where is X <marker>" (or bare "where is X"). */
 export const WHERE_MARKERS = Object.freeze(["defined", "declared", "located", "implemented"]);
 
+/** Temporal adverbs a locative question may trail ("where is disk-1 now"). They
+ *  carry no meaning the graph can read — the answer is the same with or without
+ *  one — so they are stripped rather than bound as part of the term. A closed set:
+ *  the term itself is free text, and only a listed word may be taken off it. */
+export const TRAILING_TEMPORAL_ADVERBS = Object.freeze(["now", "currently", "right now", "at the moment", "these days", "today"]);
+
 /** Prose-mention markers: "where is X <marker>" -> the prose/mentions surface. */
 export const MENTION_MARKERS = Object.freeze(["mentioned", "referenced"]);
 
@@ -467,6 +491,14 @@ export const QUALIFIERS = Object.freeze({
   uncovered: { via: "tested", value: false },
 });
 
+/** Agent words naming no particular thing, for the "is X <qualifier> by <agent>"
+ *  tail. "is X covered by tests" and "is X tested by anything" are asking the
+ *  plain coverage property, so they stay on the qualifier-check path; a NAMED
+ *  agent ("…by logger.mjs") is asking about that agent's own edges instead. */
+export const GENERIC_AGENT_WORDS = Object.freeze(new Set([
+  "tests", "test", "anything", "something", "anyone", "someone", "any",
+]));
+
 /** Aggregate/count triggers: "how many <kind> …", "count <kind>s", "number of
  *  <kind>". Bare "tally"/"sum"/"total" are deliberately excluded — they're
  *  identifier-fragment risks ("total price") and stay CASCADE_SYNONYMS-mapped