notex-companion 0.3.3 → 0.4.1

package/dist/cli.js

@@ -6727,11 +6727,13 @@ function shatter(text) {
 function terms(question) {
   return [...new Set(shatter(question).filter((t) => t.length >= 3 && !STOPWORDS.has(t)))];
 }
+var FUZZY_MATCH_EXACT_MIN_COUNT = 2;
 function scoreNodes(index, queryTerms) {
   const scored = [];
   for (const entry of index) {
     let score = 0;
     let exact = false;
+    let fuzzyMatchesByToken;
     for (const term of queryTerms) {
       let best = 0;
       if (entry.labelLower === term) {
@@ -6744,6 +6746,16 @@ function scoreNodes(index, queryTerms) {
         for (const tok of entry.labelTokens) {
           if (tok.length >= 4 && (tok.startsWith(term) || term.startsWith(tok))) {
             best = Math.max(best, 1.5);
+            if (term.length >= 4) {
+              if (!fuzzyMatchesByToken)
+                fuzzyMatchesByToken = new Map;
+              let matchedTerms = fuzzyMatchesByToken.get(tok);
+              if (!matchedTerms) {
+                matchedTerms = new Set;
+                fuzzyMatchesByToken.set(tok, matchedTerms);
+              }
+              matchedTerms.add(term);
+            }
           } else if (term.length >= 4 && tok.includes(term)) {
             best = Math.max(best, 1);
           }
@@ -6761,6 +6773,14 @@ function scoreNodes(index, queryTerms) {
       }
       score += best;
     }
+    if (fuzzyMatchesByToken) {
+      for (const matchedTerms of fuzzyMatchesByToken.values()) {
+        if (matchedTerms.size >= FUZZY_MATCH_EXACT_MIN_COUNT) {
+          exact = true;
+          break;
+        }
+      }
+    }
     if (score > 0)
       scored.push({ id: entry.id, score: Math.round(score * 100) / 100, exact });
   }
@@ -6790,6 +6810,36 @@ function readHeadSha(checkoutPath) {
     return null;
   }
 }
+var SUGGESTED_QUESTIONS_HEADING = /^## Suggested Questions\s*$/;
+var SECTION_HEADING = /^## /;
+var QUESTION_BULLET = /^- \*\*(.+)\*\*$/;
+var RATIONALE_LINE = /^\s*_(.+)_\s*$/;
+function parseSuggestedQuestions(markdown) {
+  const lines = markdown.split(`
+`);
+  const headingIndex = lines.findIndex((line) => SUGGESTED_QUESTIONS_HEADING.test(line));
+  if (headingIndex === -1)
+    return [];
+  const sectionEnd = lines.findIndex((line, i) => i > headingIndex && SECTION_HEADING.test(line));
+  const section = lines.slice(headingIndex + 1, sectionEnd === -1 ? undefined : sectionEnd);
+  const result = [];
+  for (let i = 0;i < section.length; i++) {
+    const questionMatch = section[i].match(QUESTION_BULLET);
+    if (!questionMatch)
+      continue;
+    const rationaleMatch = section[i + 1]?.match(RATIONALE_LINE);
+    result.push({ question: questionMatch[1], rationale: rationaleMatch?.[1] ?? "" });
+  }
+  return result;
+}
+function loadSuggestedQuestions(checkoutPath) {
+  try {
+    const raw = readFileSync2(resolve(checkoutPath, "graphify-out/GRAPH_REPORT.md"), "utf8");
+    return parseSuggestedQuestions(raw);
+  } catch {
+    return [];
+  }
+}
 function loadGraph(checkoutPath) {
   const graphPath = resolve(checkoutPath, "graphify-out/graph.json");
   let raw;
@@ -6851,7 +6901,16 @@ function loadGraph(checkoutPath) {
     sourceFile: checkoutRelative(e.source_file),
     sourceLocation: e.source_location
   });
-  return { stamp, nodesById, edges: doc.links, adjacency, scoreIndex, project, projectEdge };
+  return {
+    stamp,
+    nodesById,
+    edges: doc.links,
+    adjacency,
+    scoreIndex,
+    suggestedQuestions: loadSuggestedQuestions(checkoutPath),
+    project,
+    projectEdge
+  };
 }
 
 // src/http.ts
@@ -7014,7 +7073,7 @@ function traverse(adjacency, allEdges, seedIds, depth, maxNodes) {
 
 // src/ops.ts
 var API_VERSION = "0.2.1";
-var CAPABILITIES = ["search", "query", "path", "node", "browse"];
+var CAPABILITIES = ["search", "query", "path", "node", "browse", "suggestedQuestions"];
 var MAX_NODES_CEILING = 1000;
 var MAX_DEPTH_CEILING = 3;
 var DEFAULT_DEPTH = 1;
@@ -7032,6 +7091,9 @@ function status(index) {
     limits: { maxNodes: MAX_NODES_CEILING, maxDepth: MAX_DEPTH_CEILING }
   };
 }
+function suggestedQuestions(index) {
+  return { graph: index.stamp, questions: index.suggestedQuestions };
+}
 function search(index, req) {
   const limit = Math.max(0, Math.min(req.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT));
   const scored = scoreNodes(index.scoreIndex, terms(req.q)).slice(0, limit);
@@ -7227,6 +7289,8 @@ async function dispatch(req, url, opts) {
   }
   if (method === "GET" && pathname === "/v1/browse")
     return browse(index, parseBrowseRequest(url.searchParams));
+  if (method === "GET" && pathname === "/v1/suggested-questions")
+    return suggestedQuestions(index);
   throw new OpError("not_found", `No such route: ${method} ${pathname}`);
 }
 function decodeNodeId(raw) {
@@ -33888,6 +33952,18 @@ function createGraphTools(ctx) {
         return toResult(outcome, text);
       }
     },
+    graph_suggested_questions: {
+      description: "Questions graphify's own analysis (GRAPH_REPORT.md) flagged as ones this graph is uniquely positioned to answer, each with a one-line rationale (e.g. high betweenness centrality, a weakly-connected community). Empty when the checkout has no GRAPH_REPORT.md.",
+      inputSchema: {},
+      handler: () => {
+        const outcome = runOp(ctx, (index) => suggestedQuestions(index));
+        if (!outcome.ok)
+          return outcome.error;
+        const { result } = outcome;
+        const text = `${result.questions.length} suggested question(s)`;
+        return toResult(outcome, text);
+      }
+    },
     graph_search: {
       description: "Literal label/path search over the loaded graph. Returns scored nodes.",
       inputSchema: { q: exports_external.string().min(1), limit: exports_external.number().int().min(0).optional() },

package/dist/client.js

@@ -98,11 +98,13 @@ function shatter(text) {
 function terms(question) {
   return [...new Set(shatter(question).filter((t) => t.length >= 3 && !STOPWORDS.has(t)))];
 }
+var FUZZY_MATCH_EXACT_MIN_COUNT = 2;
 function scoreNodes(index, queryTerms) {
   const scored = [];
   for (const entry of index) {
     let score = 0;
     let exact = false;
+    let fuzzyMatchesByToken;
     for (const term of queryTerms) {
       let best = 0;
       if (entry.labelLower === term) {
@@ -115,6 +117,16 @@ function scoreNodes(index, queryTerms) {
         for (const tok of entry.labelTokens) {
           if (tok.length >= 4 && (tok.startsWith(term) || term.startsWith(tok))) {
             best = Math.max(best, 1.5);
+            if (term.length >= 4) {
+              if (!fuzzyMatchesByToken)
+                fuzzyMatchesByToken = new Map;
+              let matchedTerms = fuzzyMatchesByToken.get(tok);
+              if (!matchedTerms) {
+                matchedTerms = new Set;
+                fuzzyMatchesByToken.set(tok, matchedTerms);
+              }
+              matchedTerms.add(term);
+            }
           } else if (term.length >= 4 && tok.includes(term)) {
             best = Math.max(best, 1);
           }
@@ -132,6 +144,14 @@ function scoreNodes(index, queryTerms) {
       }
       score += best;
     }
+    if (fuzzyMatchesByToken) {
+      for (const matchedTerms of fuzzyMatchesByToken.values()) {
+        if (matchedTerms.size >= FUZZY_MATCH_EXACT_MIN_COUNT) {
+          exact = true;
+          break;
+        }
+      }
+    }
     if (score > 0)
       scored.push({ id: entry.id, score: Math.round(score * 100) / 100, exact });
   }
@@ -196,7 +216,7 @@ function traverse(adjacency, allEdges, seedIds, depth, maxNodes) {
 
 // src/ops.ts
 var API_VERSION = "0.2.1";
-var CAPABILITIES = ["search", "query", "path", "node", "browse"];
+var CAPABILITIES = ["search", "query", "path", "node", "browse", "suggestedQuestions"];
 var MAX_NODES_CEILING = 1000;
 var MAX_DEPTH_CEILING = 3;
 var DEFAULT_DEPTH = 1;
@@ -214,6 +234,9 @@ function status(index) {
     limits: { maxNodes: MAX_NODES_CEILING, maxDepth: MAX_DEPTH_CEILING }
   };
 }
+function suggestedQuestions(index) {
+  return { graph: index.stamp, questions: index.suggestedQuestions };
+}
 function search(index, req) {
   const limit = Math.max(0, Math.min(req.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT));
   const scored = scoreNodes(index.scoreIndex, terms(req.q)).slice(0, limit);
@@ -361,6 +384,7 @@ function node(index, req) {
   return { graph: index.stamp, node: index.project(raw), neighbours };
 }
 export {
+  suggestedQuestions,
   status,
   search,
   query,

package/dist/graph.d.ts

@@ -1,5 +1,5 @@
 import type { ScoreIndexEntry } from "./scoring.js";
-import type { GraphEdge, GraphNode, GraphStamp } from "./types.js";
+import type { GraphEdge, GraphNode, GraphStamp, SuggestedQuestion } from "./types.js";
 type RawNode = {
     id: string;
     label: string;
@@ -30,6 +30,7 @@ export type GraphIndex = {
     /** Undirected — the graph is `"directed": false` (companion-api.md §2.2). */
     adjacency: Map<string, Array<AdjacencyEntry>>;
     scoreIndex: Array<ScoreIndexEntry>;
+    suggestedQuestions: Array<SuggestedQuestion>;
     project: (n: RawNode) => GraphNode;
     projectEdge: (e: RawEdge) => GraphEdge;
 };
@@ -38,5 +39,16 @@ export declare function rootPrefixFor(checkoutPath: string, graphRoot: string):
 /** Also used by the MCP binding (mcpTools.ts) to detect staleness at call time — re-reads HEAD,
  * doesn't cache it, so a commit made mid-session is picked up on the next tool call. */
 export declare function readHeadSha(checkoutPath: string): string | null;
+/**
+ * Parses graphify's own `GRAPH_REPORT.md` "## Suggested Questions" section (a bullet list of
+ * bold question / italic one-line rationale pairs) into structured pairs. Pure and best-effort:
+ * an absent heading yields `[]`, a bullet that isn't a bold question line is skipped, and a
+ * question with no following italic line still gets a `""` rationale rather than being dropped.
+ */
+export declare function parseSuggestedQuestions(markdown: string): Array<SuggestedQuestion>;
+/** Best-effort: a missing/unreadable `GRAPH_REPORT.md` (e.g. graphify was never run for
+ * suggestions, or only `graph.json` is present) degrades to `[]` rather than failing the
+ * whole graph load — suggested questions are a nice-to-have, never load-bearing. */
+export declare function loadSuggestedQuestions(checkoutPath: string): Array<SuggestedQuestion>;
 export declare function loadGraph(checkoutPath: string): GraphIndex;
 export {};

package/dist/index.js

@@ -98,11 +98,13 @@ function shatter(text) {
 function terms(question) {
   return [...new Set(shatter(question).filter((t) => t.length >= 3 && !STOPWORDS.has(t)))];
 }
+var FUZZY_MATCH_EXACT_MIN_COUNT = 2;
 function scoreNodes(index, queryTerms) {
   const scored = [];
   for (const entry of index) {
     let score = 0;
     let exact = false;
+    let fuzzyMatchesByToken;
     for (const term of queryTerms) {
       let best = 0;
       if (entry.labelLower === term) {
@@ -115,6 +117,16 @@ function scoreNodes(index, queryTerms) {
         for (const tok of entry.labelTokens) {
           if (tok.length >= 4 && (tok.startsWith(term) || term.startsWith(tok))) {
             best = Math.max(best, 1.5);
+            if (term.length >= 4) {
+              if (!fuzzyMatchesByToken)
+                fuzzyMatchesByToken = new Map;
+              let matchedTerms = fuzzyMatchesByToken.get(tok);
+              if (!matchedTerms) {
+                matchedTerms = new Set;
+                fuzzyMatchesByToken.set(tok, matchedTerms);
+              }
+              matchedTerms.add(term);
+            }
           } else if (term.length >= 4 && tok.includes(term)) {
             best = Math.max(best, 1);
           }
@@ -132,6 +144,14 @@ function scoreNodes(index, queryTerms) {
       }
       score += best;
     }
+    if (fuzzyMatchesByToken) {
+      for (const matchedTerms of fuzzyMatchesByToken.values()) {
+        if (matchedTerms.size >= FUZZY_MATCH_EXACT_MIN_COUNT) {
+          exact = true;
+          break;
+        }
+      }
+    }
     if (score > 0)
       scored.push({ id: entry.id, score: Math.round(score * 100) / 100, exact });
   }
@@ -196,7 +216,7 @@ function traverse(adjacency, allEdges, seedIds, depth, maxNodes) {
 
 // src/ops.ts
 var API_VERSION = "0.2.1";
-var CAPABILITIES = ["search", "query", "path", "node", "browse"];
+var CAPABILITIES = ["search", "query", "path", "node", "browse", "suggestedQuestions"];
 var MAX_NODES_CEILING = 1000;
 var MAX_DEPTH_CEILING = 3;
 var DEFAULT_DEPTH = 1;
@@ -214,6 +234,9 @@ function status(index) {
     limits: { maxNodes: MAX_NODES_CEILING, maxDepth: MAX_DEPTH_CEILING }
   };
 }
+function suggestedQuestions(index) {
+  return { graph: index.stamp, questions: index.suggestedQuestions };
+}
 function search(index, req) {
   const limit = Math.max(0, Math.min(req.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT));
   const scored = scoreNodes(index.scoreIndex, terms(req.q)).slice(0, limit);
@@ -387,6 +410,36 @@ function readHeadSha(checkoutPath) {
     return null;
   }
 }
+var SUGGESTED_QUESTIONS_HEADING = /^## Suggested Questions\s*$/;
+var SECTION_HEADING = /^## /;
+var QUESTION_BULLET = /^- \*\*(.+)\*\*$/;
+var RATIONALE_LINE = /^\s*_(.+)_\s*$/;
+function parseSuggestedQuestions(markdown) {
+  const lines = markdown.split(`
+`);
+  const headingIndex = lines.findIndex((line) => SUGGESTED_QUESTIONS_HEADING.test(line));
+  if (headingIndex === -1)
+    return [];
+  const sectionEnd = lines.findIndex((line, i) => i > headingIndex && SECTION_HEADING.test(line));
+  const section = lines.slice(headingIndex + 1, sectionEnd === -1 ? undefined : sectionEnd);
+  const result = [];
+  for (let i = 0;i < section.length; i++) {
+    const questionMatch = section[i].match(QUESTION_BULLET);
+    if (!questionMatch)
+      continue;
+    const rationaleMatch = section[i + 1]?.match(RATIONALE_LINE);
+    result.push({ question: questionMatch[1], rationale: rationaleMatch?.[1] ?? "" });
+  }
+  return result;
+}
+function loadSuggestedQuestions(checkoutPath) {
+  try {
+    const raw = readFileSync(resolve(checkoutPath, "graphify-out/GRAPH_REPORT.md"), "utf8");
+    return parseSuggestedQuestions(raw);
+  } catch {
+    return [];
+  }
+}
 function loadGraph(checkoutPath) {
   const graphPath = resolve(checkoutPath, "graphify-out/graph.json");
   let raw;
@@ -448,7 +501,16 @@ function loadGraph(checkoutPath) {
     sourceFile: checkoutRelative(e.source_file),
     sourceLocation: e.source_location
   });
-  return { stamp, nodesById, edges: doc.links, adjacency, scoreIndex, project, projectEdge };
+  return {
+    stamp,
+    nodesById,
+    edges: doc.links,
+    adjacency,
+    scoreIndex,
+    suggestedQuestions: loadSuggestedQuestions(checkoutPath),
+    project,
+    projectEdge
+  };
 }
 // src/http.ts
 import { timingSafeEqual } from "node:crypto";
@@ -529,6 +591,8 @@ async function dispatch(req, url, opts) {
   }
   if (method === "GET" && pathname === "/v1/browse")
     return browse(index, parseBrowseRequest(url.searchParams));
+  if (method === "GET" && pathname === "/v1/suggested-questions")
+    return suggestedQuestions(index);
   throw new OpError("not_found", `No such route: ${method} ${pathname}`);
 }
 function decodeNodeId(raw) {
@@ -795,6 +859,7 @@ function serve(opts) {
   return { server, token, baseUrl, pairingLine: pairingLine(baseUrl, token) };
 }
 export {
+  suggestedQuestions,
   status,
   serve,
   search,

package/dist/ops.d.ts

@@ -1,4 +1,4 @@
-import type { GraphEdge, GraphNode, OpResponse } from "./types.js";
+import type { GraphEdge, GraphNode, OpResponse, SuggestedQuestion } from "./types.js";
 import type { GraphIndex } from "./graph.js";
 /** Also the version /v1/ping reports (companion-api.md §4.1) — the two must never drift apart. */
 export declare const API_VERSION = "0.2.1";
@@ -14,6 +14,13 @@ export type StatusResult = {
     };
 };
 export declare function status(index: GraphIndex): OpResponse<StatusResult>;
+export type SuggestedQuestionsResult = {
+    questions: Array<SuggestedQuestion>;
+};
+/** graphify's own `GRAPH_REPORT.md`-derived suggestions (graph.ts's loadSuggestedQuestions),
+ * already loaded onto the index at graph-load time — this op just echoes them alongside the
+ * stamp, same shape as every other op. */
+export declare function suggestedQuestions(index: GraphIndex): OpResponse<SuggestedQuestionsResult>;
 export type SearchRequest = {
     q: string;
     limit?: number;
@@ -66,7 +73,7 @@ export type QueryResult = {
     };
     /** See companion-api.md §4.8 / notex-mcp-server.md §5 — same buildFooter as the write paths. */
     footer?: string;
-    /** Set when no seed cleared the seed-score floor — an exact label or label-token match. */
+    /** Set when no seed cleared the seed-score floor — see ScoredNode's `exact` (scoring.ts). */
     lowConfidence?: {
         topScore: number;
     };

package/dist/scoring.d.ts

@@ -10,7 +10,8 @@ export type ScoreIndexEntry = {
 export type ScoredNode = {
     id: string;
     score: number;
-    /** Cleared the seed-score floor: at least one term matched a whole label or a whole label token. */
+    /** Cleared the seed-score floor: at least one term matched a whole label or a whole label
+     * token, or (TBR-130) at least two independent terms each fuzzy-prefix the same label token. */
     exact: boolean;
 };
 /** label tokens weigh full; path tokens weigh less — a path match is weaker evidence. */

package/dist/types.d.ts

@@ -21,6 +21,12 @@ export type GraphNode = {
         name: string;
     } | null;
 };
+/** Parsed from `graphify-out/GRAPH_REPORT.md`'s "## Suggested Questions" section — free-text,
+ * not derived from graph.json, so there is no stable id to key it by. */
+export type SuggestedQuestion = {
+    question: string;
+    rationale: string;
+};
 export type GraphEdge = {
     source: string;
     target: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notex-companion",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Local retrieval companion for Notex — reads a checkout's graphify-out/graph.json and serves deterministic search/query/path/node lookups over loopback HTTP and MCP stdio. No LLM, no graph building, no network beyond 127.0.0.1.",
   "keywords": ["notex", "graphify", "mcp", "code-graph"],
   "license": "MIT",