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

package/data/phrasebook/software-phrases.txt

@@ -0,0 +1,231 @@
+# software-phrases.txt — the SE phrase book (ROADMAP items 4+7).
+#
+# One phrase pattern per line; {x}/{y} are entity slots the matcher binds to
+# names in the graph. Lines starting with `~` declare a SYNONYM FAMILY: words
+# and short phrases the matcher may treat as interchangeable when normalizing
+# input. `#` starts a comment; blank lines are ignored.
+# Parsed by src/corpus/templates.mjs loadPhrasebook().
+
+# --- synonym families: the interchangeable vocabulary of asking about code ---
+~ call, invoke, use, execute, run, trigger, talk to
+~ import, include, require, pull in, depend on, load
+~ module, file, source file, unit
+~ function, fn, func, routine, procedure, method
+~ class, type, struct, record, interface
+~ test, spec, unit test, test case, check
+~ bug, defect, fault, issue, problem, glitch
+~ fix, repair, patch, resolve, correct
+~ change, modify, edit, touch, update, alter, rework
+~ delete, remove, drop, kill, strip out, get rid of
+~ create, add, make, introduce, write, define
+~ rename, relabel, move, relocate
+~ commit, change set, checkin, revision
+~ author, committer, contributor, developer, dev, engineer, programmer
+~ big, large, huge, long, giant
+~ small, tiny, short, little, lean
+~ recent, latest, newest, last, fresh
+~ old, oldest, ancient, stale, legacy
+~ broken, failing, red, busted, dead
+~ working, passing, green, healthy, fine
+~ central, core, important, key, load-bearing, critical
+~ unused, dead, orphaned, abandoned, unreferenced
+~ caller, call site, consumer, client
+~ callee, target, dependency
+~ parent, superclass, base class, ancestor
+~ child, subclass, derived class, descendant
+~ member, field, attribute, property
+~ argument, parameter, param, arg, input
+~ return, result, output, yield
+~ error, exception, failure, crash, panic
+~ codebase, repo, repository, project, source tree, code
+
+# --- call graph: what calls what ---
+what calls {x}
+what does {x} call
+who calls {x}
+who is calling {x}
+which functions call {x}
+which modules call {x}
+what invokes {x}
+callers of {x}
+call sites of {x}
+where is {x} called
+where is {x} called from
+is {x} called anywhere
+is {x} ever called
+does anything call {x}
+does {x} call {y}
+what talks to {x}
+what does {x} talk to
+what depends on {x}
+what does {x} depend on
+show me the call graph around {x}
+
+# --- imports and dependencies ---
+who imports {x}
+what imports {x}
+which modules import {x}
+what does {x} import
+where is {x} imported
+is {x} imported anywhere
+does {x} import {y}
+what requires {x}
+what uses {x}
+what does {x} use
+what pulls in {x}
+dependencies of {x}
+dependents of {x}
+what breaks if {x} changes
+what would be affected by changing {x}
+impact of changing {x}
+blast radius of {x}
+
+# --- definition and location: where things live ---
+where is {x}
+where is {x} defined
+where does {x} live
+which file defines {x}
+which module defines {x}
+what is defined in {x}
+what does {x} define
+what lives in {x}
+find {x}
+show me {x}
+is there a {x}
+do we have a {x}
+does {x} exist
+where is {x} importable from
+what does {x} export
+what is the public api of {x}
+what is in the {x} package
+
+# --- description: what things are ---
+what is {x}
+what is {x} for
+what does {x} do
+describe {x}
+tell me about {x}
+explain {x}
+what kind of thing is {x}
+is {x} a module or a function
+what type is {x}
+what does {x} return
+what arguments does {x} take
+what parameters does {x} take
+what is the signature of {x}
+what exceptions does {x} throw
+what does {x} raise
+what does {x} catch
+is {x} public or private
+is {x} deprecated
+
+# --- structure: classes, members, inheritance ---
+what does {x} contain
+what members does {x} have
+what methods does {x} have
+what fields does {x} have
+what is inside {x}
+what does {x} inherit from
+what extends {x}
+what subclasses {x}
+subclasses of {x}
+superclass of {x}
+parents of {x}
+children of {x}
+is {x} a subclass of {y}
+what implements {x}
+implementations of {x}
+
+# --- tests ---
+is {x} tested
+does {x} have tests
+what tests {x}
+what tests cover {x}
+which tests exercise {x}
+where are the tests for {x}
+test coverage of {x}
+what does {x} test
+is there a test for {x}
+how well tested is {x}
+what has no tests
+which modules are untested
+do the tests pass
+are the tests green
+
+# --- history: commits, authors, change ---
+who wrote {x}
+who authored {x}
+who last touched {x}
+who changed {x}
+when was {x} last changed
+when was {x} added
+what changed recently
+what changed in the last commit
+what did {x} change
+what commits touched {x}
+history of {x}
+how often does {x} change
+what changes together with {x}
+what usually changes with {x}
+is {x} new
+is {x} stale
+who knows about {x}
+who owns {x}
+
+# --- size, count, shape ---
+how many modules are there
+how many functions are there
+how many classes are there
+how many tests are there
+how big is {x}
+how big is the codebase
+how many lines is {x}
+what is the biggest module
+what is the biggest function
+what is the most complex module
+what is the most central module
+what is the most imported module
+what is the most called function
+what has the most dependencies
+what has no dependencies
+what is unused
+what is dead code
+list the modules
+list the classes
+list everything you know about {x}
+
+# --- bugs, quality, health ---
+is {x} broken
+why is {x} failing
+what is wrong with {x}
+does {x} have known bugs
+is {x} safe to change
+is {x} safe to delete
+what is risky about {x}
+what smells in {x}
+is {x} too big
+does {x} do too much
+
+# --- memory: what tmct itself was told ---
+what did i tell you about {x}
+what do you know about {x}
+what do you remember about {x}
+what have i told you
+what did i ask you before
+did i mention {x}
+remember that {x}
+forget about {x}
+what did you just say
+what was your last answer
+what did we talk about
+summarise this session
+
+# --- meta: about the graph and tmct ---
+what can you answer
+what do you know
+how much do you know
+what is in your graph
+when was your graph built
+where does your graph come from
+what can i ask you
+help me ask a better question

package/data/templates/responses.jsonl

@@ -0,0 +1,55 @@
+{"id":"describe-entity-terse","class":"describe","register":"terse","template":"{subject}: {kind} in {location}."}
+{"id":"describe-entity-friendly","class":"describe","register":"friendly","template":"{subject} is a {kind} living in {location}."}
+{"id":"describe-entity-with-doc","class":"describe","register":"friendly","template":"{subject} is a {kind} in {location} — \"{doc}\"."}
+{"id":"describe-module-imports","class":"describe","register":"friendly","template":"{subject} imports {objects}."}
+{"id":"describe-module-imported-by","class":"describe","register":"friendly","template":"{subject} is imported by {objects}."}
+{"id":"describe-callers","class":"describe","register":"friendly","template":"{subject} is called by {objects}."}
+{"id":"describe-callers-terse","class":"describe","register":"terse","template":"{subject} <- {objects}."}
+{"id":"describe-callees","class":"describe","register":"friendly","template":"{subject} calls {objects}."}
+{"id":"describe-members","class":"describe","register":"friendly","template":"{subject} contains {objects}."}
+{"id":"describe-superclass","class":"describe","register":"friendly","template":"{subject} inherits from {object}."}
+{"id":"describe-tested-by","class":"describe","register":"friendly","template":"{subject} is exercised by {objects}."}
+{"id":"describe-untested","class":"describe","register":"friendly","template":"I can't see any test that imports {subject} — that may just mean the coverage is indirect."}
+{"id":"describe-history","class":"describe","register":"friendly","template":"{subject} was last touched by {commit} ({when}): \"{message}\"."}
+{"id":"describe-relation-fact","class":"describe","register":"terse","template":"{subject} {predicate} {object}."}
+{"id":"describe-isa-fact","class":"describe","register":"friendly","template":"As I understand it, a {subject} is a kind of {object}."}
+{"id":"count-plain","class":"count","register":"terse","template":"{count} {noun}."}
+{"id":"count-sentence","class":"count","register":"friendly","template":"There are {count} {noun} in {scope}."}
+{"id":"count-one","class":"count","register":"friendly","template":"There is exactly one {noun} in {scope}: {subject}."}
+{"id":"count-zero","class":"count","register":"friendly","template":"I can't find any {noun} in {scope}."}
+{"id":"count-with-sample","class":"count","register":"friendly","template":"{count} {noun} in {scope} — for example {examples}."}
+{"id":"count-compared","class":"count","register":"friendly","template":"{count} {noun} — {comparison} for a codebase of this size."}
+{"id":"miss-plain","class":"miss","register":"terse","template":"No match for \"{query}\"."}
+{"id":"miss-honest","class":"miss","register":"friendly","template":"I couldn't ground \"{query}\" in anything I know. I'd rather say so than guess."}
+{"id":"miss-rephrase-name","class":"miss","register":"friendly","template":"I don't recognise \"{query}\". If you name a module, function, or class I know about, I can work from there."}
+{"id":"miss-rephrase-pattern","class":"miss","register":"friendly","template":"\"{query}\" didn't match anything. Try a shape like \"{example}\" — that's a question I can answer precisely."}
+{"id":"miss-nearest","class":"miss","register":"friendly","template":"Nothing matches \"{query}\" exactly. The nearest name I know is {nearest} — is that what you meant?"}
+{"id":"miss-nearest-terse","class":"miss","register":"terse","template":"No \"{query}\". Nearest: {nearest}."}
+{"id":"miss-empty-graph","class":"miss","register":"friendly","template":"My graph is empty right now, so I can't answer \"{query}\" yet. Tell me things and I'll remember them."}
+{"id":"miss-out-of-domain","class":"miss","register":"friendly","template":"That sounds like it's outside my patch — I only really know about {scope}. Ask me about the code and I'm much more useful."}
+{"id":"ambiguity-two","class":"ambiguity","register":"friendly","template":"That could go two ways. If you mean {a} then {aAnswer}; if you mean {b} then {bAnswer}."}
+{"id":"ambiguity-two-terse","class":"ambiguity","register":"terse","template":"{a}: {aAnswer} / {b}: {bAnswer}."}
+{"id":"ambiguity-three","class":"ambiguity","register":"friendly","template":"I see three readings. If you mean {a} then {aAnswer}; if you mean {b} then {bAnswer}; if you mean {c} then {cAnswer}."}
+{"id":"ambiguity-name-clash","class":"ambiguity","register":"friendly","template":"\"{query}\" names more than one thing here: {candidates}. Which one do you mean?"}
+{"id":"ambiguity-name-clash-terse","class":"ambiguity","register":"terse","template":"\"{query}\" is ambiguous: {candidates}."}
+{"id":"ambiguity-class-split","class":"ambiguity","register":"friendly","template":"Reading \"{query}\" as a {a} gives one answer, reading it as a {b} gives another. Say which and I'll commit."}
+{"id":"assume-scope","class":"assumption","register":"friendly","template":"I'll assume you're asking about {assumed} — say otherwise and I'll drop that."}
+{"id":"assume-scope-terse","class":"assumption","register":"terse","template":"Assuming {assumed}."}
+{"id":"assume-spelling","class":"assumption","register":"friendly","template":"I read \"{query}\" as {assumed} (closest name I know). {answer}"}
+{"id":"assume-this-repo","class":"assumption","register":"friendly","template":"I'm assuming \"{query}\" is about this repository. {answer}"}
+{"id":"assume-latest","class":"assumption","register":"friendly","template":"You didn't say which {noun}, so I took the most recent one: {assumed}."}
+{"id":"assume-singular","class":"assumption","register":"friendly","template":"Several things match; I picked the strongest, {assumed}. The runners-up were {others}."}
+{"id":"recall-plain","class":"recall","register":"friendly","template":"You told me earlier that {fact}."}
+{"id":"recall-plain-terse","class":"recall","register":"terse","template":"Earlier: {fact}."}
+{"id":"recall-with-when","class":"recall","register":"friendly","template":"Earlier in this session ({when}) you said \"{utterance}\"."}
+{"id":"recall-prior-session","class":"recall","register":"friendly","template":"In a previous session you told me that {fact} — I'm going on that."}
+{"id":"recall-corpus","class":"recall","register":"friendly","template":"My corpus says {fact} — that's background knowledge, not something you told me."}
+{"id":"recall-conflict","class":"recall","register":"friendly","template":"Careful — you told me earlier that {fact}, which doesn't sit well with \"{query}\". Which should I keep?"}
+{"id":"recall-similar-question","class":"recall","register":"friendly","template":"You asked something similar before (\"{utterance}\") and the answer was: {answer}"}
+{"id":"recall-nothing","class":"recall","register":"friendly","template":"You haven't told me anything about {subject} yet."}
+{"id":"stored-fact","class":"stored","register":"friendly","template":"Noted: {subject} {predicate} {object}. I'll remember that."}
+{"id":"stored-fact-terse","class":"stored","register":"terse","template":"Stored: {subject} {predicate} {object}."}
+{"id":"stored-duplicate","class":"stored","register":"friendly","template":"I already knew that {subject} {predicate} {object} — nothing new to store."}
+{"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."}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "0.2.0",
+  "version": "0.3.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.",
@@ -29,18 +29,27 @@
     "src/",
     "README.md",
     "ROADMAP.md",
-    "LICENSE"
+    "LICENSE",
+    "corpus/",
+    "data/"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
+    "ink": "^7.1.0",
+    "react": "^19.2.7",
     "smol-toml": "^1.7.0",
     "wink-eng-lite-web-model": "^1.8.1",
     "wink-nlp": "^2.4.0"
   },
   "scripts": {
     "test": "node --test \"test/**/*.test.mjs\"",
-    "chat": "node bin/tmct.mjs"
+    "chat": "node bin/tmct.mjs",
+    "chatbench:run": "node chatbench/run.mjs",
+    "chatbench:judge": "node chatbench/judge.mjs"
+  },
+  "devDependencies": {
+    "ink-testing-library": "^4.0.0"
   }
 }

package/src/ask-nlp.mjs

@@ -42,6 +42,20 @@ export function nlpAdapter() {
           return w.toLowerCase();
         }
       },
+      /** True when wink's lexicon flags the word as an English stop word
+       *  ("anyway", "well", "also", …). Consulted by the noise-strip strategy
+       *  (interpret/strategies/noise-strip.mjs) as its wink tier — the strategy's
+       *  own KEEP set screens out the grammar's load-bearing words (which/what/
+       *  does/…) BEFORE this is asked, so wink flagging a question word is
+       *  harmless by construction. False on any surprise, never a throw. */
+      isStopWord(word) {
+        try {
+          const out = nlp.readDoc(String(word || "")).tokens().out(its.stopWordFlag);
+          return out[0] === true;
+        } catch {
+          return false;
+        }
+      },
       /** UPOS tags aligned to the CALLER's word array. wink re-tokenizes (it
        *  splits "walk.mjs" into three tokens), so each input word is greedily
        *  matched to the run of wink tokens that spell it and takes its FIRST

package/src/ask-vocab.mjs

@@ -295,7 +295,13 @@ export const MISSPELLINGS = Object.freeze({
   "tets": "tests",
   // grammar anchor words
   "whcih": "which", "wich": "which", "whihc": "which",
-  "waht": "what",
+  // "wat" (chatbench cycle 2, tf-wat-calls): the internet-casual spelling of
+  // "what" — neither curated noise nor a restorable trigger typo, so "wat calls
+  // fnAlpha" used to die as "couldn't resolve one of the terms". Restored here
+  // so BOTH parse strategies and the relaxation cascade see the canonical
+  // 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",
   "dose": "does", "doess": "does",
   "teh": "the",
   // aggregate/list TRIGGER words (2026-07-02, trigger-typo work) — a typo of a count
@@ -626,6 +632,12 @@ export const CASCADE_NOISE = Object.freeze([
   // vocatives / terms of address (the "matey" of the worked example, and its kin)
   "matey", "mate", "buddy", "pal", "dude", "man", "bro", "bru", "fam",
   "friend", "sir", "maam", "folks", "guys", "everyone", "dear",
+  // the product's OWN name used as an address (chatbench cycle 2, ns-hey-tmct:
+  // "hey tmct, what calls fnAlpha thanks") — a vocative like "matey", stripped
+  // by the same rules: relaxParse's resolvesExact guard still protects a module
+  // literally named "tmct", and noise-strip's template/keyword-spot acceptance
+  // bounds the cost of a mid-question strip to an honest object-miss.
+  "tmct",
   // presentation frames — the keyword-spotting strategy's blind spot: the
   // compositional grammar skips these as FRAME_WORDS, but "show me what imports X"
   // otherwise decomposes (via keyword-spot) to ask{subject:"show me"}. Stripping