@polycode-projects/seonix 0.9.1 → 0.10.1

package/src/roslyn_build.mjs

@@ -0,0 +1,59 @@
+// roslyn_build.mjs — shared build logic for the Roslyn C# semantic extractor
+// (roslyn/publish/roslyn-extract.dll). Used by two callers: the lazy-build path
+// in cs_roslyn.mjs (triggered on the first real C# extraction attempt in a
+// process, not on `npm install`) and the explicit `npm run build:roslyn`
+// prewarm command (e.g. baking the dll into a Docker image ahead of time).
+//
+// Best-effort and silent-by-default: no dotnet on PATH -> skip, tree-sitter
+// (src/cs_treesitter.mjs) covers the absent case. A `dotnet publish` failure
+// (e.g. no network for the first NuGet restore) is a warning, never thrown.
+import { access } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const ROOT = join(here, "..");
+export const ROSLYN_DIR = join(ROOT, "roslyn");
+export const DLL = join(ROSLYN_DIR, "publish", "roslyn-extract.dll");
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      env: { ...process.env, DOTNET_CLI_TELEMETRY_OPTOUT: "1", DOTNET_NOLOGO: "1" },
+      ...opts,
+    });
+    let out = "";
+    let err = "";
+    child.stdout?.on("data", (d) => (out += d));
+    child.stderr?.on("data", (d) => (err += d));
+    child.on("close", (code) => resolve({ code: code ?? -1, out, err }));
+    child.on("error", () => resolve({ code: -1, out, err: "" }));
+  });
+}
+
+async function exists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+/** Build the Roslyn dll if it's missing and `dotnet` is on PATH.
+ *  @returns {Promise<boolean>} true if the dll is present after this call
+ *  (already built, or built now); false otherwise (no dotnet, or publish
+ *  failed — caller falls back to tree-sitter). */
+export async function ensureRoslynBuilt({ quiet = false } = {}) {
+  if (await exists(DLL)) return true;
+
+  const dotnetCheck = await run("dotnet", ["--version"]);
+  if (dotnetCheck.code !== 0) return false; // no .NET SDK — tree-sitter fallback covers C#
+
+  const publish = await run("dotnet", ["publish", "-c", "Release", "-o", "publish"], { cwd: ROSLYN_DIR });
+  if (publish.code !== 0) {
+    if (!quiet) {
+      console.warn("[seonix] Roslyn C# extractor build failed — falling back to tree-sitter for C#.");
+      console.warn(`[seonix] dotnet publish exited ${publish.code}: ${publish.err.slice(-300)}`);
+    }
+    return false;
+  }
+  if (!quiet) console.log("[seonix] Roslyn C# extractor built (full semantic call/type resolution enabled).");
+  return true;
+}

package/src/schema-docs.mjs

@@ -71,9 +71,11 @@ export const PREDICATE_DOCS = Object.freeze([
     "Module → Module. An import-backed, module-granular \"this file calls into that " +
     "file\" edge — not resolved to a specific symbol (see callsSymbol for that)." },
   { prop: "mgx:callsSymbol", kind: "callsSymbol", description:
-    "Function/Method → Function/Class. A call site resolved to exactly one same-named " +
-    "definition in the repository — unambiguous names only; an ambiguous or external " +
-    "call is dropped rather than guessed (no wrong edge)." },
+    "Function/Method → Function/Class/Method. A call site resolved to exactly one " +
+    "same-named definition in the repository — unambiguous names only (method targets " +
+    "resolve through a tiered simple-name fallback: same-module wins, interface members " +
+    "are excluded when one implementation remains); an ambiguous or external call is " +
+    "dropped rather than guessed (no wrong edge)." },
   { prop: "seon:declaresMethod", kind: "defines", description:
     "Module → Function/Class/Method/Attribute/GlobalVariable. What a module's top-level " +
     "scope actually declares." },
@@ -113,6 +115,23 @@ export const PREDICATE_DOCS = Object.freeze([
     "split) and any doc-comment prose, used by the second-pass prose-to-symbol " +
     "cross-reference index (PLAN_PROSE_INDEX.md) to resolve free-text object terms that " +
     "don't exact-match an identifier." },
+  // GATED (un-typed interfaces, PLAN_UNTYPED_INTERFACES.md; ROADMAP backlog #15): documented
+  // here so "what does serves mean" is answerable, but `gated: true` means ingestSchemaDocs
+  // only materialises the SchemaPredicate individual when the predicate is ACTUALLY present
+  // in this build's vocabulary — i.e. only on an interfaces-ON graph that found at least one
+  // route. A default/OFF graph never has "mgx:serves"/"mgx:callsHttp" in its vocabulary, so
+  // the guard keeps it out, preserving byte-identity (see the extended guard test in
+  // schema-docs.test.mjs).
+  { prop: "mgx:serves", kind: "serves", gated: true, description:
+    "Route → Function/Method. Route-declaration → handler-symbol — the HTTP boundary a " +
+    "syntax-only AST graph misses entirely (a route string is not a node, and a handler " +
+    "passed by reference at registration is not a call/import edge). Un-typed interfaces " +
+    "(PLAN_UNTYPED_INTERFACES.md), opt-in via SEONIX_INTERFACES=1 / [interfaces]." },
+  { prop: "mgx:callsHttp", kind: "callsHttp", gated: true, description:
+    "Function/Method → Route. Client call-site → Route, the fuzzy other half of the same " +
+    "un-typed-interface chain: an HTTP client call's URL literal (fetch/axios/HttpClient) " +
+    "matched to a Route's normalised path template (verb agreement, segment-wildcard " +
+    "matching, match_threshold-gated) — completes client → route → handler." },
 
   // ---- attributes (individual-scoped facts, not edges) ----
   { prop: "seon:startsAt", kind: "attribute", description:
@@ -240,6 +259,16 @@ export function ingestSchemaDocs(entities) {
     }
   }
 
+  // Present-predicate guard (ROADMAP backlog #15): a `gated: true` PREDICATE_DOCS entry (the
+  // un-typed-interfaces mgx:serves/mgx:callsHttp docs) only earns a SchemaPredicate individual
+  // when its prop is ACTUALLY present in this build's vocabulary — vocabulary entries for these
+  // props are themselves only emitted by interfaces.mjs when the gated feature is on AND found
+  // at least one match, so a default/OFF graph's vocabulary never contains them and this guard
+  // keeps their SchemaPredicate individuals out too, preserving byte-identity. Non-gated entries
+  // are unconditional, exactly as before.
+  const vocabProps = new Set((entities.vocabulary || []).map((v) => v?.prop));
+  const predicatePresent = (p) => !p.gated || vocabProps.has(p.prop);
+
   entities.individuals ||= [];
   const existingIds = new Set(entities.individuals.map((i) => i?.id));
   for (const c of CLASS_DOCS) {
@@ -247,6 +276,7 @@ export function ingestSchemaDocs(entities) {
     if (!existingIds.has(ind.id)) { entities.individuals.push(ind); existingIds.add(ind.id); }
   }
   for (const p of PREDICATE_DOCS) {
+    if (!predicatePresent(p)) continue;
     const ind = predicateIndividual(p);
     if (!existingIds.has(ind.id)) { entities.individuals.push(ind); existingIds.add(ind.id); }
   }

package/src/server.mjs

@@ -20,7 +20,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { loadConfig, ToolError } from "./config.mjs";
-import { createTelemetry } from "./telemetry.mjs";
+import { createTelemetry, truncateStr, looksLikeMiss } from "./telemetry.mjs";
 import * as defaultSource from "./source.mjs";
 import {
   parseEntities,
@@ -31,6 +31,7 @@ import {
   siteOf,
   renderMembers,
   renderSubclasses,
+  renderExternalSubclasses,
   renderArchitecture,
   renderTestsFor,
   renderUntested,
@@ -47,6 +48,7 @@ import {
   renderContextMore,
   renderCalls,
   callHint,
+  edgesOfKind,
   renderFileHistory,
   renderMethodHistory,
   renderClassHistory,
@@ -319,10 +321,24 @@ export async function dispatchTool(name, args, { config, source = defaultSource
     const graph = await loadGraph(config, source);
     const { match, candidates } = resolveOrThrow(graph, symbol, "symbol");
     const site = siteOf(match);
-    if (!site) {
+    // Path-vs-symbol UX (WH_ESTATE_AUDIT §2b): a Module match must never fall through to the
+    // span-slicer — some extractors stamp modules with a thin 1-2-line span, which used to
+    // render a near-empty, useless "snippet" for `seonix_snippet <file>`. Whether or not a
+    // span exists, answer with the actionable alternatives: the symbols the module defines
+    // (each snippet-able directly), seonix_describe, or reading the file itself.
+    if (String(match.class || "") === "Module" || !site) {
+      const defined = edgesOfKind(graph, "defines")
+        .filter((e) => e.subject === match.id)
+        .map((e) => e.objectLabel || e.object);
+      const cap = 12;
+      const list = defined.length
+        ? ` It defines: ${defined.slice(0, cap).join(", ")}${defined.length > cap ? `, +${defined.length - cap} more` : ""}.`
+        : "";
       throw new ToolError(
-        `"${match.label}" (${match.class || "Entity"}) has no source span in the graph — ` +
-          "it is likely a module. Use seonix_describe for its contents, then seonix_snippet one of the functions/classes it defines.",
+        `"${match.label}" is a ${match.class || "Module"} — seonix_snippet takes a symbol ` +
+          `(a function/class name or Class.Method), not a file path.${list}` +
+          ` seonix_snippet one of those, seonix_describe "${match.label}" for the module's full contents,` +
+          " or Read the file itself for raw source.",
       );
     }
     // repo root = the dir containing .seonix/ (graphFile = <repo>/.seonix/graph.json)
@@ -389,8 +405,23 @@ export async function dispatchTool(name, args, { config, source = defaultSource
     const symbol = String(args?.class || "").trim();
     if (!symbol) throw new ToolError("class is required");
     const graph = await loadGraph(config, source);
-    const { match } = resolveOrThrow(graph, symbol, "class");
-    return renderSubclasses(graph, match);
+    // Honest resolution (wh dogfood T14): exact match first; a fuzzy hit must never be
+    // presented as if it were the asked-for class.
+    const { match, candidates, exact } = resolveSymbol(graph, symbol);
+    if (exact) return renderSubclasses(graph, match);
+    // No individual with that exact name — an external/framework base may still appear
+    // as a supertype LABEL on inherits edges; if so, that's the real answer.
+    const external = renderExternalSubclasses(graph, symbol);
+    if (external) return external;
+    if (!match) {
+      throw new ToolError(
+        `no entity matching class "${symbol}" in the code-map graph. ` +
+          "Try a repo-relative path (e.g. django/utils/text.py), a basename, or seonix_search for a fuzzy lookup.",
+      );
+    }
+    // Fuzzy-only candidates: answer for the best match but NAME the substitution up front.
+    const others = candidates.length ? ` (other near matches: ${candidates.map((c) => c.label).join(", ")})` : "";
+    return `no exact match for "${symbol}"; nearest is "${match.label}"${others}:\n${renderSubclasses(graph, match)}`;
   }
   if (name === "seonix_architecture") {
     const graph = await loadGraph(config, source);
@@ -425,7 +456,16 @@ export async function dispatchTool(name, args, { config, source = defaultSource
           `${cands ? `: ${cands}` : ""}. Re-ask with a more specific query.`,
       );
     }
-    return `${content}\n\n---seonix_ask---\n${JSON.stringify(tmct_ask, null, 2)}`;
+    // Actionable caller-miss (wh dogfood C10/C11/T9): an empty symbol-level call answer used to
+    // name the traversal but not the cause or the next move. Port seonix_calls' honest wording:
+    // method-level call edges can be sparse for a language, so a miss is weak evidence — point
+    // at the module-level fallback instead of leaving the agent at a dead end.
+    const missNote = (tmct_ask?.miss === true && /callsSymbol/.test(String(tmct_ask?.traversal || "")))
+      ? "\nnote: method-level call edges (callsSymbol) can be sparse for this language — an empty answer " +
+        "is not proof of no callers. Fall back to module level: seonix_impact {\"module\":\"<file>\",\"depth\":1} " +
+        "for direct dependents, or ask \"which modules import <file>\"."
+      : "";
+    return `${content}${missNote}\n\n---seonix_ask---\n${JSON.stringify(tmct_ask, null, 2)}`;
   }
   if (
     name === "seonix_tests_for" || name === "seonix_history" || name === "seonix_callers" ||
@@ -486,8 +526,12 @@ export function buildServer({ config = loadConfig(), source = defaultSource, env
       const text = await dispatchTool(name, args || {}, { config, source });
       tel?.record({
         tool: name,
+        // wh dogfood backlog #6: telemetry recorded only tool+size — add the query/args text
+        // (truncated, correlation only), wall-clock duration, and a best-effort hit/miss flag.
+        query: { raw: truncateStr(JSON.stringify(args || {})) },
         response: { count: text ? text.split("\n").length : 0, truncated: /truncated/i.test(text) },
         perf: { ms_total: Date.now() - t0 },
+        quality: { miss: looksLikeMiss(text) },
         cost: { returned_chars: text.length, returned_tokens_est: Math.ceil(text.length / 4) },
       });
       return { content: [{ type: "text", text }] };

package/src/summary.mjs

@@ -92,6 +92,7 @@ export function hubModules(entities, { prefix = "", top = 5 } = {}) {
 export function buildSummary(entities, stats) {
   const {
     mode = "single", repos = [], skipped = [], languages = {}, graphBytes = 0,
+    store = "json", // "sqlite" ONLY when graph.db was actually built (SEONIX_STORE exported + write ok)
   } = stats || {};
 
   // per-class individual counts (the fix for the "7,345 = total?" misread)
@@ -133,9 +134,15 @@ export function buildSummary(entities, stats) {
   }
 
   // effective history depth for the run = the deepest pass across repos
-  const depths = repos.map((r) => r.historyDepth || { name: 0, symbol: 0 });
-  const nameDepth = depths.length ? Math.max(...depths.map((d) => d.name || 0)) : 0;
-  const symbolDepth = depths.length ? Math.max(...depths.map((d) => d.symbol || 0)) : 0;
+  // (running max, not Math.max(...spread) — one arg per repo, and spread-into-call is banned
+  // over anything repo-scaled; see test/edges-of-kind.test.mjs)
+  let nameDepth = 0;
+  let symbolDepth = 0;
+  for (const r of repos) {
+    const d = r.historyDepth || { name: 0, symbol: 0 };
+    if ((d.name || 0) > nameDepth) nameDepth = d.name || 0;
+    if ((d.symbol || 0) > symbolDepth) symbolDepth = d.symbol || 0;
+  }
 
   const repoRows = repos.map((r) => ({
     name: r.name,
@@ -156,6 +163,7 @@ export function buildSummary(entities, stats) {
       capChars: V8_STRING_CAP,
       capPct: `~${((graphBytes / V8_STRING_CAP) * 100).toFixed(1)}%`,
     },
+    store,
     history: { tier: historyTier(nameDepth), depth: { name: nameDepth, symbol: symbolDepth } },
     classes,
     edges: { total: edgeTotal, byPredicate },
@@ -174,6 +182,9 @@ export function renderSummaryMd(summary) {
   lines.push("# seonix index summary", "");
   lines.push(`- mode: ${summary.mode}`);
   lines.push(`- graph: ${fmt(summary.graph.bytes)} bytes (${summary.graph.capPct} of the V8 string cap)`);
+  // Store visibility: "sqlite" only when graph.db was actually built this run — a SEONIX_STORE
+  // that was set but never exported (invisible to child processes) reads `store: json` here.
+  lines.push(`- store: ${(summary.store || "json") === "sqlite" ? "sqlite (graph.db + graph.json; graph.json authoritative)" : "json (graph.json only)"}`);
   lines.push(`- history: tier=${summary.history.tier} depth name=${summary.history.depth.name} symbol=${summary.history.depth.symbol}`);
   const totalInds = Object.values(summary.classes).reduce((a, b) => a + b, 0);
   lines.push(`- individuals: ${fmt(totalInds)} total`);

package/src/telemetry.mjs

@@ -20,6 +20,37 @@ const DROP_KEYS = new Set(["text", "content", "snippet"]);
  *  question, which is the correlation key and is not file content). */
 const MAX_STR = 500;
 
+/** Truncate a string to ~`max` chars (default 200) for a query/args preview field —
+ *  the wh dogfood's "record the query/args text" ask, kept short deliberately (this is
+ *  a correlation aid, not the file-content-safe `query.raw` exemption in redact() below,
+ *  which some surfaces (locate/digest) still pass a short literal query through). Pure. */
+export function truncateStr(s, max = 200) {
+  const str = String(s ?? "");
+  return str.length > max ? str.slice(0, max) : str;
+}
+
+/** Best-effort, cheap-to-tell hit/miss classifier over a tool's RENDERED text output
+ *  (wh dogfood backlog #6: telemetry too thin to tell a query-mix's hit rate without
+ *  re-reading prose at analysis time). Matches the honest-miss phrasings the
+ *  codegraph.mjs renderers already use ("no entity matching", "none recorded", "cannot
+ *  map", "unknown kind/tool/argument", the tmct_ask envelope's own `"miss": true`) plus
+ *  the generic "no <kind> matches/found" shape. NOT exhaustive — a renderer can grow a
+ *  new miss phrasing this never learns — so `true` is fairly reliable, `false` only
+ *  means "no miss marker seen", not "definitely a hit". Pure. */
+const MISS_PATTERNS = [
+  /no entity matching/i,
+  /no [a-z]+ (matches|found)/i,
+  /:\s*no [a-z][a-z /-]* recorded\b/i,
+  /\bnone recorded\b/i,
+  /\bcannot map\b/i,
+  /^unknown (kind|tool|argument)/i,
+  /"miss"\s*:\s*true/,
+];
+export function looksLikeMiss(text) {
+  if (typeof text !== "string" || !text) return false;
+  return MISS_PATTERNS.some((re) => re.test(text));
+}
+
 /** Enabled iff `SEONIX_TELEMETRY==="1"` OR `[telemetry] enabled=true` in the toml.
  *  The env wins BOTH directions: `SEONIX_TELEMETRY==="0"` force-disables even when the
  *  toml turns it on. Default OFF (anything but "1"/"0" in the env falls through to toml). */