@polycode-projects/seonix 0.2.1 → 0.3.0

package/src/ask-vocab.mjs

@@ -35,8 +35,9 @@ export const RELATIONS = {
   imports: {
     comment: "Module -> Module: subject's import graph references object (usesComplexType).",
     verbs: [
-      // formal/neutral
-      "couples to", "couple to", "uses", "use", "depends on", "imports", "import",
+      // formal/neutral ("uses"/"use" moved to the `uses` union family, 2026-07-02 —
+      // "uses code from" stays here: its phrasing is specifically import-flavored)
+      "couples to", "couple to", "depends on", "imports", "import",
       "relies on", "rely on", "requires", "require", "references", "reference",
       "pulls in", "pull in", "built on", "builds on", "build on", "uses code from",
       // casual/colloquial
@@ -46,6 +47,21 @@ export const RELATIONS = {
       "importing",
     ],
   },
+  // "uses" is a QUERY-side union family, not a stored predicate (2026-07-02 query
+  // families): "what uses X" honestly means BOTH the import graph and the call
+  // graph, so ask.mjs traverses it as imports + calls + callsSymbol together
+  // (KIND_UNIONS there). The verbs moved here FROM imports — "which modules use X"
+  // still answers with the importing modules (the asked Module grain filters the
+  // union down to module-grain subjects), and "what uses <function>" now also
+  // reaches the symbol-grain callers instead of silently ignoring them.
+  uses: {
+    comment: "query-side union: imports (Module->Module) + calls (Module->Module) + callsSymbol (fn->fn).",
+    verbs: [
+      "uses", "use", "used by", "makes use of", "make use of",
+      // gerund (g-drop normalization — §3.5)
+      "using",
+    ],
+  },
   calls: {
     comment: "Function/Method -> Function/Class (symbol-grain) or Module -> Module (coarse): subject invokes object.",
     verbs: [
@@ -104,6 +120,27 @@ export const RELATIONS = {
       "was changed in", "were changed in", "was edited in", "were edited in",
       "was modified by", "were modified by", "was tweaked in", "were tweaked in",
       "got changed in", "got edited in",
+      // commit-question forms (2026-07-02, viewer commit-chat fix): the same touch
+      // relation asked from the commit's side — "which changes touch commit <sha>",
+      // "what did commit <sha> touch", "which functions changed in <sha>", "which
+      // changes landed in commit <sha>", "what was touched by commit <sha>". Bare
+      // "touch" completes the touched/touches pair for the "did … touch" auxiliary
+      // form; the "by"/"in" phrases are the passive/locative counterparts of forms
+      // already above (curated per register spread, not a thesaurus dump).
+      "touch", "touched by", "modified by", "changed by", "changed in",
+      "landed in", "land in",
+      // contents-of-a-commit forms (2026-07-02, operator screenshot: "what was in
+      // commit <sha>" missed on the live site). "was in"/"went into" only read as
+      // touch questions when the object is a commit — the sha-shaped object keeps
+      // them from firing on structural questions ("is X in the graph" has no verb
+      // match anyway). Judgment call: "is in" omitted — too generic without the
+      // past-tense anchor and risks matching containment phrasings.
+      "was in", "were in", "went into", "included in",
+      // when-question forms (2026-07-02 query families): "when was X last
+      // updated/edited" — bare past participles that only read naturally in the
+      // temporal shape; the when template routes them, but they are ordinary
+      // touches verbs so "which modules were updated ..." keeps working too.
+      "updated", "edited",
       // gerund (g-drop normalization — §3.5)
       "touching",
     ],
@@ -118,15 +155,31 @@ export const RELATIONS = {
     ],
   },
   reexports: {
-    comment: "Module -> Module: subject re-exports a name it imported from object.",
+    comment: "Module -> exported symbol: subject's public API surface (__all__/export list).",
     verbs: [
       "exports", "export", "re-exports", "re-export", "passes through", "pass through",
+      // API-surface phrasing (2026-07-02 query families): "what does <module>
+      // expose". Bare "exposed" is NOT listed — the lemma tier maps it here when
+      // an adapter is present, and "how does the API get exposed" has no
+      // traversal either way (pinned as an honest miss in the tests).
+      "exposes", "expose",
       // gerund (g-drop normalization — §3.5)
       "exporting",
     ],
   },
 };
 
+// ---- where/when/mentions markers (2026-07-02 query families) — the location and
+// prose-mention questions carry NO relation verb ("where is X defined", "where is
+// X mentioned"), so ask.mjs routes them by these marker words instead of
+// VERB_TO_KIND. Closed lists, same curation discipline as everything above. ----
+
+/** Definition-location markers: "where is X <marker>" (or bare "where is X"). */
+export const WHERE_MARKERS = Object.freeze(["defined", "declared", "located", "implemented"]);
+
+/** Prose-mention markers: "where is X <marker>" -> the prose/mentions surface. */
+export const MENTION_MARKERS = Object.freeze(["mentioned", "referenced"]);
+
 /** relation token -> flat verb-phrase list, the shape ask.mjs's VERB_TO_KIND
  *  table needs (phrase -> kind), derived once from RELATIONS. */
 export const VERB_TO_KIND = Object.freeze(
@@ -142,6 +195,18 @@ export const ENTITY_TO_TYPE = Object.freeze({
   module: "Module", modules: "Module", file: "Module", files: "Module",
   attribute: "Attribute", attributes: "Attribute", field: "Attribute", fields: "Attribute",
   variable: "GlobalVariable", variables: "GlobalVariable", global: "GlobalVariable", globals: "GlobalVariable",
+  // "changes" in a touch question ("which changes touch commit <sha>") means the
+  // code entities on the other end of the touch edges, at WHATEVER grain the graph
+  // recorded — module (touches) and symbol (touchesSymbol) together when the commit
+  // is the given side, and the touching commits themselves when a module/symbol is
+  // the given side. Mapped to the pseudo-type "Change" (not a node class): ask.mjs's
+  // traverse() reads it as a wildcard over the touch traversal's results rather than
+  // aliasing it to ONE real class and silently dropping the other grain of the
+  // answer. Listed BEFORE commit/commits: findPhrase (ask.mjs) takes the first
+  // same-length phrase in table order, so in "which changes touch commit <sha>" the
+  // entity slot must consume "changes" and leave "commit <sha>" intact as the
+  // object term.
+  change: "Change", changes: "Change",
   commit: "Commit", commits: "Commit",
 });
 
@@ -173,6 +238,83 @@ export const CONTRACTIONS = Object.freeze({
   "gimme": "give me",
 });
 
+// ---- misspellings and wrong words (2026-07-02, two-level fuzzy work) — these are
+// CORRECTIONS, not synonyms: the asker typed a broken or incorrect surface form of
+// a word this grammar already owns, and we restore the canonical form BEFORE
+// parsing (normalizeQuery applies both tables like CONTRACTIONS: word-boundary,
+// longest key first, case-insensitive). Synonyms belong in RELATIONS/ENTITY_TO_TYPE;
+// these tables exist so a typo'd or misused word maps to canonical language
+// deterministically, ahead of (and more precisely than) ask.mjs's bounded
+// edit-distance fallback. ask.mjs's correction regex refuses to rewrite a word
+// glued to a dotted extension ("revision.mjs" stays a module name), since
+// WRONG_WORDS entries are real English words that plausibly name modules; a
+// bare standalone token that happens to be a real identifier remains the
+// accepted residual exposure, same as CONTRACTIONS. ----
+
+/** Curated common typos of THIS vocabulary's own keywords — entity nouns, relation
+ *  verbs, and the grammar's anchor words (which/what/does/the): a typo'd anchor
+ *  kills the anchored templates outright, so anchors earn entries too. Values are
+ *  always the canonical word. Judgment calls logged: "calss" maps to "class" (the
+ *  doubled-s slip of "class"), NOT "calls", though both are edit-distance 1 — the
+ *  exact tie the generic fuzzy tier must refuse to break; a curated table is where
+ *  that call is made deliberately. "dose" is a real English word, but at a word
+ *  boundary in this closed question grammar ("dose X import Y") the intent is
+ *  unambiguous. */
+export const MISSPELLINGS = Object.freeze({
+  // entity nouns
+  "funtion": "function", "funtions": "functions",
+  "fucntion": "function", "fucntions": "functions",
+  "functoin": "function", "functoins": "functions",
+  "calss": "class", "calsses": "classes", "classs": "class", "clases": "classes",
+  "modul": "module", "moduls": "modules",
+  "moduel": "module", "moduels": "modules",
+  "moudle": "module", "moudles": "modules",
+  "methdo": "method", "methdos": "methods",
+  "mehtod": "method", "mehtods": "methods",
+  "comit": "commit", "comits": "commits",
+  "commmit": "commit", "commmits": "commits",
+  "varaible": "variable", "varaibles": "variables",
+  "varibale": "variable", "varibales": "variables",
+  "atribute": "attribute", "atributes": "attributes",
+  // relation verbs
+  "improt": "import", "improts": "imports",
+  "imoprt": "import", "imoprts": "imports",
+  "inherts": "inherits", "inheirts": "inherits",
+  "extands": "extends", "extneds": "extends",
+  "depnds": "depends",
+  "touchs": "touches", "tuoches": "touches", "touhced": "touched",
+  "chagned": "changed", "chnaged": "changed",
+  "chagnes": "changes", "chnages": "changes",
+  "calles": "calls",
+  "exprot": "export", "exprots": "exports",
+  "tets": "tests",
+  // grammar anchor words
+  "whcih": "which", "wich": "which", "whihc": "which",
+  "waht": "what",
+  "dose": "does", "doess": "does",
+  "teh": "the",
+});
+
+/** Words used INCORRECTLY but with clear intent, mapped to the canonical schema
+ *  term — used like synonyms by the asker, but they are corrections of usage, not
+ *  alternative names (which is why they live here and not in ENTITY_TO_TYPE).
+ *  Only mapped where intent is unambiguous in a code-graph question; words
+ *  deliberately NOT mapped are logged in the omitted-on-purpose block at the end
+ *  of this file. */
+export const WRONG_WORDS = Object.freeze({
+  // neither a folder nor a directory grain exists in this graph — in "which
+  // folders import X" the only honest referent is the module/file grain.
+  "folder": "module", "folders": "modules",
+  "directory": "module", "directories": "modules",
+  // unambiguous abbreviation of an entity noun this grammar owns
+  "func": "function", "funcs": "functions",
+  // VCS terms whose canonical schema class here is Commit
+  "changeset": "commit", "changesets": "commits",
+  "revision": "commit", "revisions": "commits",
+  // code-graph "property" is the Attribute grain in this schema
+  "property": "attribute", "properties": "attributes",
+});
+
 /** Trailing g-drop ("callin'", "hittin'") — a plain suffix restore, not a
  *  lemmatiser: -in' -> -ing, applied per-word during normalization. The
  *  apostrophe is REQUIRED (not optional): bare "-in" endings with no
@@ -223,6 +365,27 @@ export const NEGATION_FRAMES = Object.freeze([
   { re: /\b(?:nobody|nothing|no one)\s+(\S.*?)(?:,?\s+does\s+it\??|,?\s+do\s+they\??)?$/i, to: (m) => `what ${m[1]}` },
 ]);
 
+// ---- commit-content frames (2026-07-02, operator screenshot: "what was in commit
+// ef74e44e25c8" missed on the live site) — "what was/is in commit <sha>", "what's
+// in <sha>" (the contraction table has already expanded "what's" by the time
+// frames run), "what went into <sha>", "what made it into commit <sha>" all mean
+// the canonical commit-subject question "what did <sha> touch", so they are
+// REWRITTEN to it before either parse strategy runs: the same mechanism and scope
+// discipline as NEGATION_FRAMES (a small closed pattern set, first match wins),
+// which also makes both strategies parse the family for free. The sha-shaped tail
+// is REQUIRED so these frames only ever fire on an actual commit reference: over a
+// non-sha object ("what was in walk.mjs") the frame does not match and the text is
+// left for the ordinary grammar to handle as it already does, rather than being
+// bent into a commit-subject touches query that would then blank. ----
+export const COMMIT_CONTENT_FRAMES = Object.freeze([
+  // "what was in commit ef74e44e25c8" / "what is in ef74e44e" / "what's in commit <sha>"
+  { re: /^what\s+(?:is|was|were|are)\s+in\s+((?:commit\s+)?[0-9a-f]{7,40})\??$/i, to: (m) => `what did ${m[1]} touch` },
+  // "what went into commit ef74e44e25c8" / casual "what got into <sha>"
+  { re: /^what\s+(?:went|got)\s+into\s+((?:commit\s+)?[0-9a-f]{7,40})\??$/i, to: (m) => `what did ${m[1]} touch` },
+  // "what made it into commit ef74e44e25c8"
+  { re: /^what\s+made\s+it\s+into\s+((?:commit\s+)?[0-9a-f]{7,40})\??$/i, to: (m) => `what did ${m[1]} touch` },
+]);
+
 // ---- §7 meta-vocabulary — trigger phrases for the "meta" query shape (asking what a
 // graph vocabulary term itself means: "what does cochange mean", "what does mgx:
 // callsSymbol mean"). Deliberately NOT folded into RELATIONS/VERB_TO_KIND: these
@@ -256,3 +419,9 @@ export const META_MEANING_VERBS = Object.freeze([
 // alongside"), so g-drop normalization has no bare stem to dialectally
 // contract in the first place; only relations with a genuinely bare-verb
 // casual form ("call", "touch") needed one.
+// WRONG_WORDS not mapped (judgment calls): "script(s)" (routinely names a real
+// module/identifier — rewriting it could corrupt an object term, and file/files
+// already covers the honest synonym); "package(s)" (a genuinely coarser grain
+// this graph doesn't model — mapping it to module would silently answer a
+// different question than the one asked); "fn" (too short and too often a real
+// identifier fragment to rewrite at a word boundary).