@danielblomma/cortex-mcp 2.2.5 → 2.4.0

package/scaffold/mcp/tests/query-cli.test.mjs

@@ -4,6 +4,7 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const QUERY_MODULE = fileURLToPath(new URL("../dist/cli/query.js", import.meta.url));
+const PROJECT_ROOT = fileURLToPath(new URL("../..", import.meta.url));
 
 function runQuery(args) {
   const script = [
@@ -20,7 +21,11 @@ function runQuery(args) {
       pathToFileURL(QUERY_MODULE).href,
       JSON.stringify(args),
     ],
-    { encoding: "utf8" },
+    {
+      cwd: PROJECT_ROOT,
+      encoding: "utf8",
+      env: { ...process.env, CORTEX_PROJECT_ROOT: PROJECT_ROOT },
+    },
   );
 }
 
@@ -105,6 +110,73 @@ test("explain --json enables scores and matched rules", () => {
   assert.ok(Array.isArray(parsed.data.results));
 });
 
+test("pattern-evidence --json emits ordered cited evidence tiers", () => {
+  const parsed = runJson([
+    "pattern-evidence",
+    "mcp/src/cli/query.ts",
+    "--query",
+    "CLI argument parsing error handling",
+    "--top-k",
+    "2",
+    "--json",
+  ]);
+
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.command, "pattern-evidence");
+  assert.equal(parsed.input.target, "mcp/src/cli/query.ts");
+  assert.equal(parsed.input.top_k, 2);
+  assert.deepEqual(parsed.data.evidence_order, [
+    "same_file",
+    "same_module",
+    "same_feature_area",
+    "repo_wide",
+  ]);
+  assert.equal(typeof parsed.data.local_pattern_found, "boolean");
+  assert.equal(parsed.data.tiers.length, 4);
+  for (const tier of parsed.data.tiers) {
+    assert.ok(Array.isArray(tier.evidence));
+    for (const evidence of tier.evidence) {
+      assert.equal(typeof evidence.path, "string");
+      assert.ok(evidence.path.length > 0);
+      if (evidence.entity_type === "Chunk") {
+        assert.equal(Number.isInteger(evidence.start_line), true);
+        assert.equal(Number.isInteger(evidence.end_line), true);
+      }
+    }
+  }
+});
+
+test("pattern-evidence --json rejects targets that are not file-backed", () => {
+  const parsed = runJson(["pattern-evidence", "rule.source_of_truth", "--json"], 1);
+
+  assert.equal(parsed.ok, false);
+  assert.equal(parsed.command, "pattern-evidence");
+  assert.match(parsed.error.message, /not file-backed/);
+});
+
+test("pattern-evidence derives a query from the target when --query is omitted", () => {
+  const parsed = runJson(["pattern-evidence", "mcp/src/cli/query.ts", "--top-k", "1", "--json"]);
+
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.data.query_source, "derived_from_target");
+  assert.equal(typeof parsed.data.query, "string");
+  assert.ok(parsed.data.query.length > 0);
+});
+
+test("pattern-evidence rejects malformed --top-k values", () => {
+  const parsed = runJson([
+    "pattern-evidence",
+    "mcp/src/cli/query.ts",
+    "--top-k",
+    "2junk",
+    "--json",
+  ], 1);
+
+  assert.equal(parsed.ok, false);
+  assert.equal(parsed.command, "pattern-evidence");
+  assert.match(parsed.error.message, /must be an integer/);
+});
+
 test("json validation errors emit an error envelope", () => {
   const parsed = runJson(["impact", "--json"], 1);
 

package/scaffold/mcp/tests/search-graph-score.test.mjs

@@ -1,6 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { buildSearchResults, buildSearchResultsWithStats } from "../dist/searchResults.js";
+import { expandQueryTokens, semanticScore, structuralSearchBoost, tokenize } from "../dist/searchCore.js";
 
 function makeEntity(id, entityType, overrides = {}) {
   return {
@@ -166,6 +167,172 @@ test("ranking is preserved when score fields are omitted from the response", ()
   assert.equal("score" in results[0], false);
 });
 
+test("tokenization exposes camel-case code identifiers for lexical matching", () => {
+  const tokens = tokenize("buildSearchResults parseRankingFromConfig parseJavaScriptCode parseCSharpParser C# VB.NET");
+
+  assert.ok(tokens.includes("build"));
+  assert.ok(tokens.includes("search"));
+  assert.ok(tokens.includes("results"));
+  assert.ok(tokens.includes("parse"));
+  assert.ok(tokens.includes("ranking"));
+  assert.ok(tokens.includes("config"));
+  assert.ok(tokens.includes("javascript"));
+  assert.ok(tokens.includes("csharp"));
+  assert.ok(tokens.includes("vbnet"));
+  assert.equal(tokens.includes("java"), false);
+});
+
+test("query aliases do not dilute lexical semantic scoring", () => {
+  assert.equal(semanticScore(expandQueryTokens(["dashboard"]), "", "status"), 0.85);
+  assert.equal(semanticScore(expandQueryTokens(["import"]), "", "imports"), 0.85);
+});
+
+test("structural search boost favors matching path and symbol fields", () => {
+  const query = "How does the JavaScript and TypeScript parser collect calls and imports?";
+  const queryTokens = expandQueryTokens(Array.from(new Set(tokenize(query))));
+  const jsImports = makeEntity("js-imports", "Chunk", {
+    label: "collectImports",
+    path: "scaffold/scripts/parsers/javascript/imports.mjs"
+  });
+  const cppParser = makeEntity("cpp-parser", "Chunk", {
+    label: "parseCode",
+    path: "scaffold/scripts/parsers/cpp-treesitter.mjs"
+  });
+  const csharpParser = makeEntity("csharp-parser", "Chunk", {
+    label: "CSharpParser",
+    path: "scaffold/scripts/parsers/dotnet/CSharpParser/Program.cs"
+  });
+
+  assert.ok(
+    structuralSearchBoost(jsImports, queryTokens, query.toLowerCase()) >
+      structuralSearchBoost(cppParser, queryTokens, query.toLowerCase())
+  );
+  assert.ok(
+    structuralSearchBoost(jsImports, queryTokens, query.toLowerCase()) >
+      structuralSearchBoost(csharpParser, queryTokens, query.toLowerCase())
+  );
+});
+
+test("low-semantic graph hubs cannot outrank strong semantic code matches on secondary signals alone", () => {
+  const candidates = [
+    makeEntity("hub", "Chunk", {
+      text: "broad weak query",
+      trust_level: 100
+    }),
+    makeEntity("leaf", "Chunk", {
+      text: "precise strong query",
+      trust_level: 10
+    })
+  ];
+
+  const results = buildSearchResults({
+    candidates,
+    degreeByEntity: new Map([
+      ["hub", 100],
+      ["leaf", 0]
+    ]),
+    queryTokens: ["query"],
+    queryPhrase: "query",
+    ranking: { semantic: 0.4, graph: 0.25, trust: 0.2, recency: 0.15 },
+    includeScores: true,
+    includeMatchedRules: false,
+    includeContent: false,
+    queryVector: null,
+    embeddingVectors: new Map(),
+    topK: 2,
+    minLexicalRelevance: 0,
+    minVectorRelevance: 0,
+    semanticScorer: (_tokens, _phrase, text) => (text.includes("strong") ? 0.7 : 0.2),
+    vectorScorer: () => 0,
+    recencyScorer: () => 1,
+    structuralSearchBooster: () => 0,
+    legacyDataAccessBooster: () => 0
+  });
+
+  assert.equal(results[0].id, "leaf");
+});
+
+test("diverse top-k selection admits a near-tie from another path", () => {
+  const candidates = [
+    makeEntity("a1", "Chunk", { path: "src/a.ts", text: "a1 query" }),
+    makeEntity("a2", "Chunk", { path: "src/a.ts", text: "a2 query" }),
+    makeEntity("a3", "Chunk", { path: "src/a.ts", text: "a3 query" }),
+    makeEntity("b1", "Chunk", { path: "src/b.ts", text: "b1 query" })
+  ];
+  const semanticById = new Map([
+    ["a1", 0.9],
+    ["a2", 0.89],
+    ["a3", 0.88],
+    ["b1", 0.86]
+  ]);
+
+  const results = buildSearchResults({
+    candidates,
+    degreeByEntity: new Map(),
+    queryTokens: ["query"],
+    queryPhrase: "query",
+    ranking: { semantic: 1, graph: 0, trust: 0, recency: 0 },
+    includeScores: true,
+    includeMatchedRules: false,
+    includeContent: false,
+    queryVector: null,
+    embeddingVectors: new Map(),
+    topK: 3,
+    minLexicalRelevance: 0,
+    minVectorRelevance: 0,
+    semanticScorer: (_tokens, _phrase, text) => semanticById.get(text.split(" ")[0]) ?? 0,
+    vectorScorer: () => 0,
+    recencyScorer: () => 0,
+    structuralSearchBooster: () => 0,
+    legacyDataAccessBooster: () => 0
+  });
+
+  assert.deepEqual(results.map((result) => result.id), ["a1", "a2", "b1"]);
+  assert.equal(results.some((result) => result.id === "a3"), false);
+  assert.deepEqual(results.map((result) => result.score), [0.9, 0.89, 0.86]);
+});
+
+test("strong test evidence can outrank a slightly weaker graph hub", () => {
+  const candidates = [
+    makeEntity("hub", "Chunk", {
+      path: "src/hub.ts",
+      text: "implementation query",
+      trust_level: 50
+    }),
+    makeEntity("test-evidence", "File", {
+      path: "tests/context-regressions.test.mjs",
+      text: "regression evidence query",
+      trust_level: 50
+    })
+  ];
+
+  const results = buildSearchResults({
+    candidates,
+    degreeByEntity: new Map([
+      ["hub", 100],
+      ["test-evidence", 0]
+    ]),
+    queryTokens: ["query"],
+    queryPhrase: "query",
+    ranking: { semantic: 0.4, graph: 0.25, trust: 0.2, recency: 0.15 },
+    includeScores: true,
+    includeMatchedRules: false,
+    includeContent: false,
+    queryVector: null,
+    embeddingVectors: new Map(),
+    topK: 2,
+    minLexicalRelevance: 0,
+    minVectorRelevance: 0,
+    semanticScorer: (_tokens, _phrase, text) => (text.includes("regression") ? 0.5 : 0.49),
+    vectorScorer: () => 0,
+    recencyScorer: () => 1,
+    structuralSearchBooster: () => 0,
+    legacyDataAccessBooster: () => 0
+  });
+
+  assert.equal(results[0].id, "test-evidence");
+});
+
 test("search results can consume a repeatable candidate generator with stats", () => {
   let passes = 0;
   const candidateSource = function* () {

package/scaffold/scripts/dashboard.mjs

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -286,12 +286,11 @@ function getLocalCliVersion() {
   }
 
   try {
-    const output = execSync("cortex --version", {
+    const output = execFileSync("cortex", ["--version"], {
       cwd: REPO_ROOT,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8",
       timeout: 1500,
-      shell: true,
     }).trim();
     if (parseVersion(output)) {
       return output;
@@ -331,13 +330,12 @@ function getVersionStatus() {
     } else {
       try {
         const npmCache = path.join(CACHE_DIR, "npm-cache");
-        const latestRaw = execSync("npm view github:DanielBlomma/cortex version --json", {
+        const latestRaw = execFileSync("npm", ["view", "github:DanielBlomma/cortex", "version", "--json"], {
           cwd: REPO_ROOT,
           stdio: ["ignore", "pipe", "pipe"],
           encoding: "utf8",
           timeout: VERSION_LOOKUP_TIMEOUT_MS,
           env: { ...process.env, NPM_CONFIG_CACHE: npmCache },
-          shell: true,
         }).trim();
         const parsedLatest = JSON.parse(latestRaw);
         const latest = Array.isArray(parsedLatest)
@@ -352,20 +350,30 @@ function getVersionStatus() {
             latest,
             message: "unsupported latest version format",
           };
-        } else if (compareVersions(latestParsed, localParsed) > 0) {
-          value = {
-            state: "update-available",
-            local,
-            latest,
-            message: null,
-          };
         } else {
-          value = {
-            state: "current",
-            local,
-            latest,
-            message: null,
-          };
+          const comparison = compareVersions(latestParsed, localParsed);
+          if (comparison > 0) {
+            value = {
+              state: "update-available",
+              local,
+              latest,
+              message: null,
+            };
+          } else if (comparison < 0) {
+            value = {
+              state: "local-newer",
+              local,
+              latest,
+              message: "local build is newer than published version",
+            };
+          } else {
+            value = {
+              state: "current",
+              local,
+              latest,
+              message: null,
+            };
+          }
         }
       } catch (error) {
         value = {
@@ -690,6 +698,9 @@ function render(data, isTTY) {
   if (data.version.state === "update-available") {
     lines.push(sideBorder(
       `Version: ${bold(col("UPDATE AVAILABLE", C.red))} ${col(`${data.version.local} -> ${data.version.latest}`, C.red)}`, w));
+  } else if (data.version.state === "local-newer") {
+    lines.push(sideBorder(
+      `Version: ${col(data.version.local, C.yellow)} ${dim(`Published: ${data.version.latest} local newer`)}`, w));
   } else if (data.version.state === "current") {
     lines.push(sideBorder(
       `Version: ${col(data.version.local, C.green)} ${dim(`Latest: ${data.version.latest}`)}`, w));

package/scaffold/scripts/doctor.sh

@@ -180,15 +180,33 @@ fi
 
 # Quick runtime import check
 if [[ -f "$MCP_DIR/dist/server.js" ]] && [[ -d "$MCP_DIR/node_modules" ]]; then
-  MCP_CHECK=$(cd "$REPO_ROOT" && timeout 10 node -e '
-    const start = Date.now();
-    try {
-      require("./.context/mcp/dist/graph.js");
-      console.log("ok " + (Date.now() - start));
-    } catch(e) {
-      console.log("fail " + e.message);
+  MCP_CHECK=$(cd "$REPO_ROOT" && node -e '
+    const { spawnSync } = require("node:child_process");
+    const timeoutMs = Number(process.env.CORTEX_DOCTOR_GRAPH_TIMEOUT_MS || 30000);
+    const probe = [
+      "const start = Date.now();",
+      "try {",
+      "  require(\"./.context/mcp/dist/graph.js\");",
+      "  console.log(\"ok \" + (Date.now() - start));",
+      "} catch (e) {",
+      "  console.log(\"fail \" + (e && e.message ? e.message : String(e)));",
+      "  process.exitCode = 1;",
+      "}"
+    ].join("\n");
+    const result = spawnSync(process.execPath, ["-e", probe], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: timeoutMs
+    });
+    if (result.error && result.error.code === "ETIMEDOUT") {
+      console.log("fail timeout after " + timeoutMs + "ms");
+    } else if (result.error) {
+      console.log("fail " + result.error.message);
+    } else {
+      const lines = String(result.stdout || "").trim().split(/\r?\n/).filter(Boolean);
+      console.log(lines[lines.length - 1] || ("fail exit " + (result.status ?? "unknown")));
     }
-  ' 2>/dev/null || echo "fail timeout")
+  ' 2>/dev/null || echo "fail graph check crashed")
   if [[ "$MCP_CHECK" == ok* ]]; then
     MS="${MCP_CHECK#ok }"
     pass "Graph module loads (${MS}ms)"

package/scaffold/scripts/ingest.mjs

@@ -457,11 +457,11 @@ function parseRules(rulesText) {
 function walkDirectory(directoryPath, files) {
   const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
   for (const entry of entries) {
-    if (entry.isDirectory() && SKIP_DIRECTORIES.has(entry.name)) {
+    const absolutePath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory() && shouldSkipDirectory(absolutePath, entry.name)) {
       continue;
     }
 
-    const absolutePath = path.join(directoryPath, entry.name);
     if (entry.isDirectory()) {
       walkDirectory(absolutePath, files);
       continue;
@@ -473,10 +473,40 @@ function walkDirectory(directoryPath, files) {
   }
 }
 
+function shouldSkipDirectory(absolutePath, entryName) {
+  if (entryName === "bin" && path.resolve(path.dirname(absolutePath)) === REPO_ROOT) {
+    return false;
+  }
+  return SKIP_DIRECTORIES.has(entryName);
+}
+
+function normalizeSourcePrefix(sourcePath) {
+  const source = toPosixPath(sourcePath).replace(/^\.\/+/, "").replace(/\/+$/, "");
+  return source === "." ? "" : source;
+}
+
+function normalizeRelativePath(relPath) {
+  return toPosixPath(relPath).replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+
+function hasSkippedDirectorySegment(relPath) {
+  const parts = normalizeRelativePath(relPath).split("/").filter(Boolean);
+  return parts.some((part, index) => {
+    if (part === "bin" && index === 0) {
+      return false;
+    }
+    return SKIP_DIRECTORIES.has(part);
+  });
+}
+
 function hasSourcePrefix(relPath, sourcePaths) {
+  const normalizedRelPath = normalizeRelativePath(relPath);
+  if (!normalizedRelPath || hasSkippedDirectorySegment(normalizedRelPath)) {
+    return false;
+  }
   return sourcePaths.some((sourcePath) => {
-    const source = toPosixPath(sourcePath).replace(/\/+$/, "");
-    return relPath === source || relPath.startsWith(`${source}/`);
+    const source = normalizeSourcePrefix(sourcePath);
+    return source === "" || normalizedRelPath === source || normalizedRelPath.startsWith(`${source}/`);
   });
 }
 
@@ -627,6 +657,9 @@ function collectCandidateFiles(sourcePaths, mode) {
   }
 
   for (const sourcePath of sourcePaths) {
+    if (hasSkippedDirectorySegment(sourcePath)) {
+      continue;
+    }
     const absoluteSourcePath = path.resolve(REPO_ROOT, sourcePath);
     if (!fs.existsSync(absoluteSourcePath)) {
       continue;

package/scaffold/scripts/status.sh

@@ -198,11 +198,12 @@ try {
 
 node -e '
 const path = require("node:path");
-const { execSync } = require("node:child_process");
+const { execFileSync, execSync } = require("node:child_process");
 
 const repoRoot = process.argv[1];
 const cacheDir = process.argv[2];
 const localVersionEnv = process.argv[3] || "";
+const VERSION_LOOKUP_TIMEOUT_MS = Number(process.env.CORTEX_VERSION_LOOKUP_TIMEOUT_MS || 8000);
 
 function parseVersion(value) {
   const match = String(value || "").trim().match(/^v?(\d+)\.(\d+)\.(\d+)$/);
@@ -225,7 +226,7 @@ function getLocalVersion() {
   }
 
   try {
-    const output = execSync("cortex --version", {
+    const output = execFileSync("cortex", ["--version"], {
       cwd: repoRoot,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8",
@@ -282,11 +283,11 @@ try {
     const npmCache = path.join(cacheDir, "npm-cache");
     let latestRaw = "";
     try {
-      latestRaw = execSync("npm view github:DanielBlomma/cortex version --json", {
+      latestRaw = execFileSync("npm", ["view", "github:DanielBlomma/cortex", "version", "--json"], {
         cwd: repoRoot,
         stdio: ["ignore", "pipe", "pipe"],
         encoding: "utf8",
-        timeout: 2500,
+        timeout: VERSION_LOOKUP_TIMEOUT_MS,
         env: { ...process.env, NPM_CONFIG_CACHE: npmCache }
       }).trim();
     } catch (error) {
@@ -317,13 +318,19 @@ try {
     process.exit(0);
   }
 
-  const hasUpdate = compareVersions(latestParsed, localParsed) > 0;
+  const comparison = compareVersions(latestParsed, localParsed);
   console.log(`[status] cortex_latest_version=${latestVersion}`);
 
-  if (hasUpdate) {
+  if (comparison > 0) {
+    console.log("[status] cortex_version_state=update-available");
     console.log("[status] cortex_update_available=yes");
     console.log("[status] run: npm i -g github:DanielBlomma/cortex");
+  } else if (comparison < 0) {
+    console.log("[status] cortex_version_state=local-newer");
+    console.log("[status] cortex_update_available=no");
+    console.log("[status] note: local Cortex is newer than the published version");
   } else {
+    console.log("[status] cortex_version_state=current");
     console.log("[status] cortex_update_available=no");
   }
 } catch (error) {