@danielblomma/cortex-mcp 2.2.4 → 2.4.0

package/scaffold/mcp/tests/pattern-evidence.test.mjs

@@ -0,0 +1,321 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  classifyPatternEvidence,
+  contextReferenceTimeMs,
+  runLocalPatternEvidence,
+  runPatternEvidence,
+} from "../dist/patternEvidence.js";
+
+function chunk(id, fileId, startLine, endLine) {
+  return {
+    id,
+    file_id: fileId,
+    name: id,
+    kind: "function",
+    signature: "",
+    body: "",
+    description: "",
+    start_line: startLine,
+    end_line: endLine,
+    language: "typescript",
+    exported: false,
+    updated_at: "2026-07-12T00:00:00.000Z",
+    source_of_truth: false,
+    trust_level: 60,
+    status: "active",
+  };
+}
+
+function document(id, filePath, kind, content = "") {
+  return {
+    id,
+    path: filePath,
+    kind,
+    updated_at: "2026-07-12T00:00:00.000Z",
+    source_of_truth: false,
+    trust_level: kind === "DOC" ? 80 : 60,
+    status: "active",
+    excerpt: content,
+    content,
+  };
+}
+
+function contextData({ documents, chunks = [] }) {
+  return {
+    documents,
+    chunks,
+    rules: [],
+    adrs: [],
+    modules: [],
+    projects: [],
+    relations: [],
+    ranking: { semantic: 0.4, graph: 0.25, trust: 0.2, recency: 0.15 },
+    source: "cache",
+  };
+}
+
+test("classifies helper, error, and config evidence in local-first order with line citations", () => {
+  const target = {
+    input: "src/features/auth/controller.ts",
+    entity_id: "file:src/features/auth/controller.ts",
+    entity_type: "File",
+    path: "src/features/auth/controller.ts",
+  };
+  const results = [
+    {
+      id: target.entity_id,
+      entity_type: "File",
+      kind: "CODE",
+      title: target.path,
+      path: target.path,
+      excerpt: "target must not cite itself",
+      score: 0.99,
+    },
+    {
+      id: "chunk:helper",
+      entity_type: "Chunk",
+      kind: "function",
+      title: "normalizeUser",
+      path: "src\\features\\auth\\controller.ts",
+      excerpt: "file-local helper shape",
+      score: 0.9,
+      matched_rules: ["rule.repo_local_pattern_review", "rule.repo_local_pattern_review"],
+    },
+    {
+      id: "chunk:error",
+      entity_type: "Chunk",
+      kind: "function",
+      title: "toAuthError",
+      path: "src/features/auth/errors.ts",
+      excerpt: "module-local error handling",
+      score: 0.8,
+    },
+    {
+      id: "chunk:config",
+      entity_type: "Chunk",
+      kind: "function",
+      title: "parseFeatureEnv",
+      path: "src/features/config/env.ts",
+      excerpt: "feature-local config parsing",
+      score: 0.7,
+    },
+    {
+      id: "file:docs/conventions.md",
+      entity_type: "File",
+      kind: "DOC",
+      title: "docs/conventions.md",
+      path: "docs/conventions.md",
+      excerpt: "repository fallback",
+      score: 0.6,
+    },
+  ];
+  const chunks = [
+    chunk("chunk:helper", "file:src/features/auth/controller.ts", 10, 18),
+    chunk("chunk:error", "file:src/features/auth/errors.ts", 4, 12),
+    chunk("chunk:config", "file:src/features/config/env.ts", 20, 31),
+  ];
+
+  const classified = classifyPatternEvidence({ target, results, chunks, topK: 3 });
+
+  assert.deepEqual(classified.tiers.map((tier) => tier.name), [
+    "same_file",
+    "same_module",
+    "same_feature_area",
+    "repo_wide",
+  ]);
+  assert.deepEqual(classified.tiers.map((tier) => tier.evidence.map((item) => item.id)), [
+    ["chunk:helper"],
+    ["chunk:error"],
+    ["chunk:config"],
+    ["file:docs/conventions.md"],
+  ]);
+  assert.equal(classified.tiers[0].evidence[0].path, "src/features/auth/controller.ts");
+  assert.equal(classified.tiers[0].evidence[0].start_line, 10);
+  assert.equal(classified.tiers[0].evidence[0].end_line, 18);
+  assert.deepEqual(classified.tiers[0].evidence[0].matched_rules, ["rule.repo_local_pattern_review"]);
+  assert.equal(classified.localPatternFound, true);
+  assert.equal(classified.fallbackUsed, false);
+});
+
+test("reports repository fallback without claiming a local pattern", () => {
+  const classified = classifyPatternEvidence({
+    target: {
+      input: "src/isolated.ts",
+      entity_id: "file:src/isolated.ts",
+      entity_type: "File",
+      path: "src/isolated.ts",
+    },
+    results: [
+      {
+        id: "file:docs/general-practices.md",
+        entity_type: "File",
+        kind: "DOC",
+        title: "docs/general-practices.md",
+        path: "docs/general-practices.md",
+        excerpt: "general fallback only",
+      },
+    ],
+    chunks: [],
+    topK: 3,
+  });
+
+  assert.equal(classified.localPatternFound, false);
+  assert.equal(classified.fallbackUsed, true);
+  assert.deepEqual(classified.tiers.slice(0, 3).flatMap((tier) => tier.evidence), []);
+  assert.equal(classified.tiers[3].evidence.length, 1);
+});
+
+test("filters chunk evidence when indexed line bounds are missing or invalid", () => {
+  const target = {
+    input: "src/a.ts",
+    entity_id: "file:src/a.ts",
+    entity_type: "File",
+    path: "src/a.ts",
+  };
+  const results = [
+    {
+      id: "chunk:missing",
+      entity_type: "Chunk",
+      kind: "function",
+      title: "missing",
+      path: "src/b.ts",
+      excerpt: "missing metadata",
+    },
+    {
+      id: "chunk:invalid",
+      entity_type: "Chunk",
+      kind: "function",
+      title: "invalid",
+      path: "src/c.ts",
+      excerpt: "invalid metadata",
+    },
+  ];
+
+  const classified = classifyPatternEvidence({
+    target,
+    results,
+    chunks: [chunk("chunk:invalid", "file:src/c.ts", 0, 0)],
+    topK: 3,
+  });
+
+  assert.deepEqual(classified.tiers.flatMap((tier) => tier.evidence), []);
+  assert.equal(classified.localPatternFound, false);
+  assert.equal(classified.fallbackUsed, false);
+});
+
+test("retrieves each locality tier before cutoff and stays deterministic", async () => {
+  const target = document("file:src/auth/handler.ts", "src/auth/handler.ts", "CODE");
+  const localFile = document("file:src/auth/config.ts", "src/auth/config.ts", "CODE");
+  const localChunk = {
+    ...chunk("chunk:local-config", localFile.id, 7, 14),
+    name: "parseLocalSetting",
+    body: "environment",
+    description: "module-local environment parsing",
+  };
+  const repoDocuments = Array.from({ length: 60 }, (_, index) =>
+    document(
+      `file:docs/pattern-${index}.md`,
+      `docs/pattern-${index}.md`,
+      "DOC",
+      "environment variable parsing configuration pattern",
+    ));
+  const data = contextData({ documents: [target, localFile, ...repoDocuments], chunks: [localChunk] });
+  const input = {
+    target: target.path,
+    query: "environment variable parsing configuration pattern",
+    top_k: 2,
+    include_deprecated: false,
+  };
+
+  const first = await runPatternEvidence(input, { data });
+  const second = await runPatternEvidence(input, { data });
+  const moduleTier = first.tiers.find((tier) => tier.name === "same_module");
+
+  assert.ok(moduleTier.evidence.some((evidence) => evidence.id === localChunk.id));
+  assert.equal(first.local_pattern_found, true);
+  assert.equal(first.ranking_reference_time, "2026-07-12T00:00:00.000Z");
+  assert.deepEqual(second, first);
+});
+
+test("runtime response exposes repository-only fallback and warning", async () => {
+  const target = document("file:src/isolated.ts", "src/isolated.ts", "CODE");
+  const fallback = document(
+    "file:docs/general-practices.md",
+    "docs/general-practices.md",
+    "DOC",
+    "general retry convention",
+  );
+  const result = await runPatternEvidence({
+    target: target.path,
+    query: "general retry convention",
+    top_k: 2,
+    include_deprecated: false,
+  }, {
+    data: contextData({ documents: [target, fallback] }),
+  });
+
+  assert.equal(result.local_pattern_found, false);
+  assert.equal(result.fallback_used, true);
+  assert.match(result.warning, /No applicable file-local, module-local, or feature-local pattern/);
+  assert.equal(result.tiers[3].evidence[0].id, fallback.id);
+});
+
+test("reference time calculation stays bounded for large indexes", () => {
+  const documents = Array.from({ length: 200_000 }, (_, index) => ({
+    updated_at: index === 199_999 ? "2026-07-13T00:00:00.000Z" : "2026-07-12T00:00:00.000Z",
+  }));
+  const data = contextData({ documents });
+
+  assert.equal(contextReferenceTimeMs(data), Date.parse("2026-07-13T00:00:00.000Z"));
+});
+
+test("equal-score evidence is stable across reversed source order", async () => {
+  const target = document("file:src/isolated.ts", "src/isolated.ts", "CODE");
+  const a = document("file:docs/a.md", "docs/a.md", "DOC", "shared convention");
+  const b = document("file:docs/b.md", "docs/b.md", "DOC", "shared convention");
+  const input = {
+    target: target.path,
+    query: "shared convention",
+    top_k: 1,
+    include_deprecated: false,
+  };
+
+  const forward = await runPatternEvidence(input, {
+    data: contextData({ documents: [target, a, b] }),
+  });
+  const reversed = await runPatternEvidence(input, {
+    data: contextData({ documents: [target, b, a] }),
+  });
+
+  assert.deepEqual(reversed, forward);
+  assert.equal(forward.tiers[3].evidence[0].id, a.id);
+});
+
+test("local-only pattern evidence uses lexical search without network fetch", async () => {
+  const target = document("file:src/a.ts", "src/a.ts", "CODE");
+  const fallback = document("file:docs/pattern.md", "docs/pattern.md", "DOC", "shared retry convention");
+  const originalFetch = globalThis.fetch;
+  let fetchCalls = 0;
+  globalThis.fetch = async () => {
+    fetchCalls += 1;
+    throw new Error("network access is forbidden in local review");
+  };
+
+  try {
+    const result = await runLocalPatternEvidence({
+      target: target.path,
+      query: "shared retry convention",
+      top_k: 1,
+      include_deprecated: false,
+    }, {
+      data: contextData({ documents: [target, fallback] }),
+    });
+
+    assert.equal(fetchCalls, 0);
+    assert.equal(result.semantic_engine, "lexical-only");
+    assert.equal(result.fallback_used, true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

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));