@polycode-projects/the-mechanical-code-talker 0.3.0 → 0.4.0

package/data/templates/grammar-rules.toml

@@ -0,0 +1,89 @@
+# grammar-rules.toml — the data-driven grammar-rule table (Phase 7, lever 2)
+# (PLAN_RESPONSE_FINISHING.md, "The grammar pass (lever 2)").
+#
+# Each [[rule]] is a corrective grammar rule applied by applyGrammar() in
+# src/finish.mjs over the PROSE spans of a segmented answer — NEVER the flat
+# string, and NEVER a protected span (entity / path / number / code / provenance
+# / receipt). The engine reads STRUCTURE, never guesses from surface: an article
+# rule that would touch the word inside the following protected span refuses to
+# fire, agreement reads the following number's value, and so on.
+#
+# CONTRACT (the plan's law): a rule's NEUTRAL behaviour is BYTE-STABLE. The only
+# byte changes a rule may introduce are GENUINE fixes to defects tmct itself
+# generates ("a artifact"). `kind` selects the built-in handler; `enabled=false`
+# PARKS a rule out of the live answer path; the remaining keys are that handler's
+# applicability conditions + parameters. Rules apply in file order; the set is
+# chosen to commute so finish() is idempotent: finish(finish(x)) === finish(x).
+#
+# SEQUENCING (PLAN_RESPONSE_FINISHING.md, "one grammar rule per tuning cycle"):
+# only ARTICLE-SELECTION is live this cycle — it fixes a genuine defect with a
+# narrow, safe blast radius. AGREEMENT, CAPITALISATION, LIST and TERMINAL are
+# fully implemented and golden-tested IN ISOLATION, but PARKED (enabled=false):
+# each rewrites established product bytes (tmct's lowercase openers and repeated
+# "and" joins are an intentional VOICE, not a grammar defect), so activating them
+# is a per-rule tuning-cycle decision with its own bench + showcase reconcile,
+# not a blanket flip. `enabled=false` keeps them inert in finish(); the goldens
+# force-enable each rule to prove its behaviour independent of the live flag.
+
+# 1. Article selection — a/an by the following word's phonetic onset. The live
+#    defect this fixes: the assert echo "every module is a artifact" -> "an
+#    artifact". Reads the next word (whether in-span or the leading token of the
+#    following protected span); refuses at a boundary it cannot read safely.
+[[rule]]
+id = "article-selection"
+kind = "article"
+enabled = true
+registers = []            # [] = every register
+description = "a/an agreement with the following word's phonetic onset"
+# Spelling-vowel words that begin with a CONSONANT sound (take 'a').
+consonant_sound_vowels = ["uni", "use", "user", "usa", "usu", "ubi", "eu", "ewe", "one", "once"]
+# Spelling-consonant words that begin with a VOWEL sound (take 'an'): silent h.
+vowel_sound_consonants = ["hour", "honest", "honour", "honor", "heir", "herb"]
+
+# 2. Subject–verb agreement — an existential copula agrees with the count that
+#    follows it ("there is 3 classes" -> "there are 3 classes"; "there are 1
+#    class" -> "there is 1 class"). Structure-driven: the plurality is READ from
+#    the following number span's value (or a protected span's explicit `plural`
+#    flag), never guessed. Neutral on already-correct agreement.
+[[rule]]
+id = "subject-verb-agreement"
+kind = "agreement"
+enabled = false   # PARKED — implemented + golden-tested, not live this cycle
+registers = []
+description = "existential copula agrees with the following count/plurality"
+singular = ["is", "was", "has"]
+plural = ["are", "were", "have"]
+
+# 3. Sentence capitalisation — capitalise the first alphabetic character of a
+#    sentence-initial prose span. Never fires when the answer opens on a
+#    protected span (a path/entity opener is left exactly as grounded).
+[[rule]]
+id = "sentence-capitalisation"
+kind = "capitalise"
+enabled = false   # PARKED — implemented + golden-tested, not live this cycle
+registers = []
+description = "capitalise the first alphabetic of a prose-initial span"
+
+# 4. List punctuation — a series joined by repeated " and " connectives becomes
+#    a comma series with a single terminal conjunction ("a and b and c" -> "a, b
+#    and c"). Operates ONLY on the prose connective spans, never the entity spans
+#    they join; a two-item list ("a and b") is already correct and untouched.
+[[rule]]
+id = "list-punctuation"
+kind = "list"
+enabled = false   # PARKED — implemented + golden-tested, not live this cycle
+registers = []
+description = "repeated 'and' joins in a 3+ item series become a comma series"
+connective = " and "
+separator = ", "
+
+# 5. Terminal punctuation — exactly one sentence-final stop: a run of 2+ trailing
+#    stops in the final prose span collapses to one ("done.." -> "done."). Adds
+#    nothing where a fragment/list answer legitimately ends without a stop.
+[[rule]]
+id = "terminal-punctuation"
+kind = "terminal"
+enabled = false   # PARKED — implemented + golden-tested, not live this cycle
+registers = []
+description = "collapse a run of trailing sentence stops to a single stop"
+stops = [".", "!", "?"]

package/data/templates/responses.jsonl

@@ -53,3 +53,16 @@
 {"id":"nudge-precision","class":"nudge","register":"friendly","template":"The closer you get to a shape like \"{example}\", the sharper my answer gets."}
 {"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-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."}
+{"id":"conversational-thanks","class":"conversational","register":"friendly","template":"Any time. Ask another, or /help for what I can do."}
+{"id":"conversational-farewell","class":"conversational","register":"friendly","template":"Bye — flushing the session log. Come back with a question any time."}
+{"id":"orientation-friendly","class":"orientation","register":"friendly","template":"I answer questions about THIS codebase's structure — imports, calls, definitions,\nhistory and counts. For example:\n  which modules import walk.mjs\n  what calls buildContextBundle\n  how many classes are there\n/help for commands, /stats for an overview of the graph."}
+{"id":"miss-no-previous-answer","class":"miss","register":"friendly","template":"No previous answer to expand yet — ask me a question first, then say \"why\" or \"say more\"."}
+{"id":"technical-density","class":"count","register":"technical","template":"{subject} carries {count} {noun} across {scope} — a concentration well above what a codebase of this size typically sustains ({provenance})."}
+{"id":"technical-comparison","class":"count","register":"technical","template":"At {count} {noun}, {subject} sits {comparison} the comparable-project baseline, a divergence that reflects deliberate structure rather than measurement noise ({provenance})."}
+{"id":"technical-superlative","class":"count","register":"technical","template":"No {noun} in {scope} is more {metric} than {subject}; it leads the next candidate by a clear margin of {count} ({provenance})."}
+{"id":"technical-ratio","class":"count","register":"technical","template":"{subject} sustains a ratio of {count} {noun} per {unit}, placing it in the upper band for projects of comparable {scope} ({provenance})."}

package/package.json

@@ -1,12 +1,38 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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.",
+  "keywords": [
+    "chatbot",
+    "no-llm",
+    "offline",
+    "deterministic",
+    "eliza",
+    "parry",
+    "nlp",
+    "wink-nlp",
+    "owl",
+    "rdf",
+    "ontology",
+    "controlled-natural-language",
+    "ace",
+    "knowledge-graph",
+    "provenance",
+    "code-navigation",
+    "cli"
+  ],
   "license": "MPL-2.0",
   "author": "Polycode Limited",
   "homepage": "https://polycode-projects.gitlab.io/the-mechanical-code-talker/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/polycode-projects/the-mechanical-code-talker.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/polycode-projects/the-mechanical-code-talker/-/issues"
+  },
   "engines": {
     "node": ">=24"
   },
@@ -47,7 +73,9 @@
     "test": "node --test \"test/**/*.test.mjs\"",
     "chat": "node bin/tmct.mjs",
     "chatbench:run": "node chatbench/run.mjs",
-    "chatbench:judge": "node chatbench/judge.mjs"
+    "chatbench:judge": "node chatbench/judge.mjs",
+    "audit": "npm audit --audit-level=high",
+    "audit:fix": "npm audit fix"
   },
   "devDependencies": {
     "ink-testing-library": "^4.0.0"

package/src/ask-nlp.mjs

@@ -9,13 +9,13 @@
 // the bounded edit-distance tier still work, browser and Node alike). Keeping the
 // ~1MB CJS model out of the page is the point of the split.
 //
-// wink-nlp and wink-eng-lite-web-model are CJS — loaded via createRequire, the
-// same Node-module-resolution approach viz.mjs uses to locate cytoscape (resolve
-// through the module system, never a guessed path). The require happens lazily on
-// first use and failure is cached as null: a checkout without the optional deps
-// installed answers exactly like the browser bundle, it never throws.
+// wink-nlp and wink-eng-lite-web-model are loaded through the shared leaf loader
+// src/wink-model.mjs (Node `createRequire` fallback + a browser registration seam),
+// so this file no longer carries its own Node-only load block. The load happens
+// lazily on first use and failure is cached as null: a checkout without the optional
+// deps installed answers exactly like the browser bundle, it never throws.
 
-import { createRequire } from "node:module";
+import { winkInstance } from "./wink-model.mjs";
 
 let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
 
@@ -25,10 +25,8 @@ let cached; // undefined = not tried yet; null = unavailable (tried once, honest
 export function nlpAdapter() {
   if (cached !== undefined) return cached;
   try {
-    const require = createRequire(import.meta.url);
-    const winkNLP = require("wink-nlp");
-    const model = require("wink-eng-lite-web-model");
-    const nlp = winkNLP(model);
+    const nlp = winkInstance();
+    if (!nlp) { cached = null; return cached; }
     const its = nlp.its;
     cached = {
       /** Lowercase lemma of a single token ("imported" -> "import"); the word

package/src/ask-vocab.mjs

@@ -220,6 +220,28 @@ export const MODIFIER_TO_KIND = Object.freeze({
   transitively: "transitive", indirectly: "transitive",
 });
 
+// ---- reversible-passive participles (Cycle 6, PLAN_CYCLE_4.md) — past participles ->
+// relation kind, for the agent-marked passive "X is <participle> by Y". Kept SEPARATE
+// from VERB_TO_KIND on purpose: these forms are NOT standalone active verbs in this
+// grammar ("defined" belongs to the multi-word "is defined in" and to the WHERE_MARKERS
+// location routing; bare "inherited" has no active key), so folding them into
+// VERB_TO_KIND would silently re-route "where is X defined" and other queries. This
+// table is consulted ONLY by the keyword strategy's passive path, which has already
+// confirmed a passive auxiliary AND an agent-marking "by" — so an active query is never
+// affected. Most common participles ("imported"/"tested"/"called"/"covered") already
+// reach VERB_TO_KIND via the lemma tier; this table backfills the two families the lemma
+// tier can't (defines/inherits) plus the obvious siblings, so the passive works
+// adapter-free too. ----
+export const PASSIVE_PARTICIPLE_TO_KIND = Object.freeze({
+  imported: "imports", called: "calls", used: "uses",
+  tested: "tests", covered: "tests", verified: "tests", exercised: "tests", checked: "tests",
+  defined: "defines", declared: "defines",
+  inherited: "inherits", extended: "inherits", subclassed: "inherits",
+  contained: "contains",
+  exported: "reexports", "re-exported": "reexports", exposed: "reexports",
+  touched: "touches", changed: "touches", modified: "touches", edited: "touches", updated: "touches",
+});
+
 // ---- §3.5 normalization — contractions/informal spellings that would otherwise
 // block a match, expanded BEFORE parsing (BOTH the anchored-template strategy
 // and the independent keyword-spotting strategy see the same normalized text —

package/src/ask.mjs

@@ -51,7 +51,7 @@ import {
 // grammar, split out of this file: normalization pre-pass, the two parsing
 // strategies, and the bounded-fuzzy service. Re-exported below where existing
 // callers/tests import them from here.
-import { normalizeQuery, applyNegationFrames, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
+import { normalizeQuery, applyNegationFrames, matchNegationSet, STOPWORDS, splitWords, wordsOf } from "./interpret/normalize.mjs";
 import { editDistance, fuzzyBound } from "./interpret/fuzzy.mjs";
 import { parseAnchored } from "./interpret/strategies/grammar.mjs";
 import { parseKeywordSpot, findPhrase } from "./interpret/strategies/keywords.mjs";
@@ -244,7 +244,8 @@ function parseSimpleClause(text, nlp) {
 function parseComposite(text, nlp) {
   const w = splitWords(text);
   const lc = w.map((x) => x.toLowerCase());
-  return parseAnaphora(w, lc, nlp)
+  return parseNegation(text, nlp, 0)
+    || parseAnaphora(w, lc, nlp)
     || parseAggregate(w, lc, nlp)
     || parseSuperlative(w, lc, nlp)
     || parseList(w, lc, nlp, 0)
@@ -252,11 +253,81 @@ function parseComposite(text, nlp) {
     || parseRelationalOrQualified(w, lc, nlp, 0);
 }
 
+// B1 NEGATION (Cycle 5, PLAN_CYCLE_4.md) — the SET COMPLEMENT. "which X do not <verb>
+// Y" / "X that don't <verb> Y" / "modules not importing Y" / "which X are not
+// <qualifier>" compiles to allOfClass(kind) DIFFERENCE (the positive result set),
+// reusing the EXISTING machinery: evalBoolean already folds a "difference" atom, and
+// the allOfClass node is a ready-made bounded universe of a kind. The only new work is
+// recognizing the negation marker (matchNegationSet, normalize.mjs) and assembling the
+// boolean-difference AST — no new traversal primitive. Regression guards, all tested:
+//   (1) honest-empty stays honest — an EMPTY complement ("which functions are not
+//       exported", where the only function is exported) renders the standard honest
+//       "nothing matches" miss, never invents a member and never re-trips the literal-
+//       'not' trap (the "not" is consumed here, so it can't leak into an object term);
+//   (2) BOUNDED UNIVERSE only — the universe is the queried kind within the loaded
+//       graph; the "Change" pseudo-type (ask-vocab.mjs) is a wildcard, not a stored
+//       enumerable class, so a complement over "changes" is REFUSED honestly rather
+//       than answered over an empty universe;
+//   (3) active-voice/positive queries are untouched — parseNegation returns null unless
+//       matchNegationSet finds an explicit set-negation marker.
+function complementAst(entityType, diffAtom) {
+  return {
+    node: "boolean",
+    entityType,
+    atoms: [
+      { op: "seed", kind: "set", ast: { node: "allOfClass", entityType } },
+      diffAtom,
+    ],
+  };
+}
+
+function parseNegation(text, nlp, depth = 0) {
+  const neg = matchNegationSet(text);
+  if (!neg) return null;                             // no set-negation marker → not this shape
+  const noun = entityNoun(neg.entWord);
+  // a set complement needs a CONCRETE, enumerable kind. A placeholder ("things") has no
+  // bounded universe; the "Change" pseudo-type is a wildcard over the touch traversal,
+  // never a stored class, so its complement is ill-defined and must be refused honestly.
+  if (!noun || noun.placeholder || !noun.entityType) return null;
+  const entityType = noun.entityType;
+  if (entityType === "Change") {
+    return { node: "miss", reason: `"${neg.entWord}" isn't an enumerable kind — a set complement needs a concrete kind (functions, classes, modules, …)` };
+  }
+  const predWords = splitWords(neg.predicate);
+  const predLc = predWords.map((x) => x.toLowerCase());
+  // (a) qualifier negation ("not tested" / "not exported"): difference the qualifier
+  // set off the class — equivalent to the negated qualifier, an honest empty when none.
+  if (predLc.length && predLc.every((x) => QUALIFIERS[x])) {
+    return complementAst(entityType, { op: "difference", kind: "qual", filters: predLc });
+  }
+  const vh = findPhrase(predLc, VERB_TO_KIND);
+  if (!vh) return { node: "miss", reason: "a negated set query needs a known relation verb (import, call, inherit from, test, …)" };
+  const objWords = predWords.filter((_, i) => (i < vh.start || i >= vh.end) && !STOPWORDS.has(predLc[i]) && predLc[i] !== "from");
+  // (b) existential object ("do not import anything" / "define nothing"): the complement
+  // is the class MINUS the subjects that have ANY edge of this kind.
+  if (!objWords.length) {
+    return complementAst(entityType, { op: "difference", kind: "set", ast: { node: "existsEdge", entityType, kind: vh.kind } });
+  }
+  // (c) concrete object ("do not import a.mjs"): the class MINUS the POSITIVE result
+  // set, parsed through the existing clause/relational machinery (never re-negating —
+  // the reconstructed positive text carries no "not").
+  const positive = parseSetPhrase(`which ${neg.entWord} ${neg.predicate}`, nlp, depth + 1);
+  if (!positive || positive.node === "miss") {
+    return { node: "miss", reason: (positive && positive.reason) || "the negated clause didn't parse" };
+  }
+  return complementAst(entityType, { op: "difference", kind: "set", ast: positive });
+}
+
 /** A set-producing sub-expression (used for nested inner clauses, boolean branches,
  *  and count restrictors): nested first, then the relational/qualifier/boolean
  *  parser, then a bare simple clause. Carries `depth` for the nesting cap. */
 function parseSetPhrase(text, nlp, depth) {
   if (depth > MAX_COMPOSE_DEPTH) return { node: "miss", reason: "too deep to resolve" };
+  // a set-negation clause can appear as a count restrictor ("how many classes are not
+  // tested"), a list filter, or a boolean branch — try the complement frame first so
+  // those compositions get the bounded-complement for free.
+  const negated = parseNegation(text, nlp, depth);
+  if (negated) return negated;
   const w = splitWords(text);
   const lc = w.map((x) => x.toLowerCase());
   const nested = parseNested(w, lc, nlp, depth);
@@ -694,6 +765,13 @@ function evalSet(graph, ast, opts) {
   switch (ast.node) {
     case "clause": return traverse(graph, ast.clause, opts).matches || [];
     case "allOfClass": return graph.individuals.filter((i) => i.class === ast.entityType);
+    // the SUBJECTS that have ANY edge of a kind (the existential "modules that import
+    // anything") — the positive set an existential negation ("do not import anything")
+    // differences off allOfClass to yield "modules that import nothing".
+    case "existsEdge": {
+      const subs = new Set(kindsFor(ast.kind).flatMap((k) => edgesOfKind(graph, k)).map((e) => e.subject));
+      return graph.individuals.filter((i) => subs.has(i.id) && (!ast.entityType || i.class === ast.entityType));
+    }
     case "reverseSet": {
       const ids = new Set(evalSet(graph, ast.inner, opts).map((i) => i.id));
       return reverseOverSet(graph, ast.kind, ast.entityType, ids);