@danielblomma/cortex-mcp 2.2.5 → 2.4.0

package/scaffold/mcp/src/enterprise/tools/enterprise.ts

@@ -4,6 +4,7 @@ import { readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { walkProjectFiles } from "./walk.js";
+import { resolveChangedReviewFiles } from "../reviews/changed-files.js";
 import type { EnterpriseConfig } from "../../core/config.js";
 import type { TelemetryCollector } from "../../core/telemetry/collector.js";
 import type { AuditWriter } from "../../core/audit/writer.js";
@@ -16,6 +17,7 @@ import { queueViolation } from "../violations/push.js";
 import { getReviewPushContext, queueReviewResult } from "../reviews/push.js";
 import { partitionReviewPolicies } from "../reviews/policy-selection.js";
 import { recordQueuedReviewTrustState } from "../reviews/trust-state.js";
+import { buildPatternReviewContext } from "../reviews/pattern-context.js";
 import { pushWorkflowSnapshot } from "../workflow/push.js";
 import { OUTBOUND_DATA_BOUNDARY } from "../privacy/boundary.js";
 import {
@@ -41,6 +43,25 @@ type ToolPayload = Record<string, unknown>;
 
 const VALID_ROLES = new Set<Role>(["admin", "developer", "readonly"]);
 
+export function buildContextReviewAuditInput(input: {
+  scope: "all" | "changed";
+  include_passed: boolean;
+  include_pattern_evidence: boolean;
+  pattern_query?: string;
+  pattern_top_k: number;
+  pattern_limit: number;
+}): Record<string, unknown> {
+  return {
+    scope: input.scope,
+    include_passed: input.include_passed,
+    include_pattern_evidence: input.include_pattern_evidence,
+    pattern_query_present: Boolean(input.pattern_query),
+    pattern_query_length: input.pattern_query?.length ?? 0,
+    pattern_top_k: input.pattern_top_k,
+    pattern_limit: input.pattern_limit,
+  };
+}
+
 function snapshotReviewedFiles(
   projectRoot: string,
   changedFiles: string[] | undefined,
@@ -828,12 +849,20 @@ export function registerEnterpriseTools(
       description:
         "Run enterprise policy validators against the current project. " +
         "Checks enforced policies (test coverage, file size, external API calls, code review) " +
-        "and returns pass/fail results with actionable details.",
+        "and returns pass/fail results plus non-blocking repo-local pattern evidence.",
       inputSchema: z.object({
         scope: z.enum(["all", "changed"]).default("changed")
           .describe("'changed' validates only git-modified files; 'all' validates everything"),
         include_passed: z.boolean().default(true)
           .describe("Include passing validators in results"),
+        include_pattern_evidence: z.boolean().default(true)
+          .describe("Include bounded, local-only repo pattern context without changing pass/fail"),
+        pattern_query: z.string().trim().min(1).max(1000).optional()
+          .describe("Optional shared pattern query; omitted queries are derived per target"),
+        pattern_top_k: z.number().int().min(1).max(5).default(2)
+          .describe("Maximum evidence items returned per locality tier and target"),
+        pattern_limit: z.number().int().min(1).max(25).default(10)
+          .describe("Maximum review targets analyzed for pattern evidence"),
       }),
     },
     async (input) => {
@@ -844,6 +873,10 @@ export function registerEnterpriseTools(
       const parsed = z.object({
         scope: z.enum(["all", "changed"]).default("changed"),
         include_passed: z.boolean().default(true),
+        include_pattern_evidence: z.boolean().default(true),
+        pattern_query: z.string().trim().min(1).max(1000).optional(),
+        pattern_top_k: z.number().int().min(1).max(5).default(2),
+        pattern_limit: z.number().int().min(1).max(25).default(10),
       }).parse(input ?? {});
 
       const projectRoot = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
@@ -859,40 +892,7 @@ export function registerEnterpriseTools(
       //   project review; no git dependency.
       let changedFiles: string[] | undefined;
       if (parsed.scope === "changed") {
-        // Use `git rev-parse --is-inside-work-tree` to distinguish
-        // "valid repo, nothing changed" (→ empty list, reviewer sees
-        // nothing to scan) from "not a repo / git broken" (→ walk the
-        // project so scope=changed still returns meaningful results
-        // when run outside a git checkout).
-        let inGitRepo = false;
-        try {
-          const { execSync } = await import("node:child_process");
-          execSync("git rev-parse --is-inside-work-tree", {
-            cwd: projectRoot,
-            encoding: "utf8",
-            timeout: 3000,
-            stdio: ["ignore", "pipe", "ignore"],
-          });
-          inGitRepo = true;
-        } catch {
-          inGitRepo = false;
-        }
-
-        if (inGitRepo) {
-          try {
-            const { execSync } = await import("node:child_process");
-            const output = execSync("git diff --name-only HEAD 2>/dev/null || git diff --name-only", {
-              cwd: projectRoot,
-              encoding: "utf8",
-              timeout: 5000,
-            });
-            changedFiles = output.split("\n").map((f) => f.trim()).filter(Boolean);
-          } catch {
-            changedFiles = [];
-          }
-        } else {
-          changedFiles = walkProjectFiles(projectRoot);
-        }
+        changedFiles = resolveChangedReviewFiles(projectRoot) ?? walkProjectFiles(projectRoot);
       } else {
         changedFiles = walkProjectFiles(projectRoot);
       }
@@ -914,6 +914,14 @@ export function registerEnterpriseTools(
         projectRoot,
         changedFiles,
       }, config.validators);
+      const patternReview = await buildPatternReviewContext({
+        files: changedFiles ?? [],
+        enabled: parsed.include_pattern_evidence,
+        query: parsed.pattern_query,
+        topK: parsed.pattern_top_k,
+        limit: parsed.pattern_limit,
+      });
+      const patternSummary = patternReview.summary as Record<string, unknown>;
 
       // Filter out passed if requested
       const results = parsed.include_passed
@@ -944,7 +952,7 @@ export function registerEnterpriseTools(
       recordToolActivity({
         timestamp: now,
         tool: "context.review",
-        input: parsed as Record<string, unknown>,
+        input: buildContextReviewAuditInput(parsed),
         result_count: output.results.length,
         entities_returned: output.results.map((r) => r.policy_id),
         rules_applied: output.results.filter((r) => !r.pass).map((r) => r.policy_id),
@@ -958,6 +966,10 @@ export function registerEnterpriseTools(
           failed: output.summary.failed,
           warnings: output.results.filter((r) => !r.pass && r.severity === "warning").length,
           skipped: skippedPolicies.length,
+          pattern_analyzed: patternSummary.analyzed ?? 0,
+          pattern_local_evidence: patternSummary.local_evidence ?? 0,
+          pattern_repo_fallback: patternSummary.repo_fallback ?? 0,
+          pattern_omitted: patternSummary.omitted ?? 0,
         },
       });
 
@@ -1018,6 +1030,7 @@ export function registerEnterpriseTools(
         workflow_source: trustState.workflow.source,
         delivery: trustState.delivery,
         trust_warnings: trustState.trust_warnings,
+        pattern_review: patternReview,
       });
     },
   );

package/scaffold/mcp/src/paths.ts

@@ -98,12 +98,10 @@ export const PATHS = {
   transformsConfigRelations: path.join(CACHE_DIR, "relations.transforms_config.jsonl")
 };
 
-// Graph degree mostly measures how many rules constrain an entity (docs are
-// hubs, leaf code is not), so it gets low weight. Tuned together with the
-// midrank-percentile graph_score in searchResults.ts.
+// Tuned together with the midrank-percentile graph_score in searchResults.ts.
 export const DEFAULT_RANKING: RankingWeights = {
-  semantic: 0.55,
-  graph: 0.1,
+  semantic: 0.4,
+  graph: 0.25,
   trust: 0.2,
   recency: 0.15
 };

package/scaffold/mcp/src/patternEvidence.ts

@@ -0,0 +1,347 @@
+import { loadContextData } from "./graph.js";
+import { iterateSearchEntities } from "./contextEntities.js";
+import { embedQuery, loadEmbeddingIndex } from "./embeddings.js";
+import { runContextSearch } from "./search.js";
+import type { ChunkRecord, ContextData, PatternEvidenceParams, ToolPayload } from "./types.js";
+
+type SearchResult = Record<string, unknown>;
+
+type PatternTarget = {
+  input: string;
+  entity_id: string;
+  entity_type: "File" | "Chunk" | "ADR";
+  path: string;
+};
+
+type PatternEvidence = {
+  id: string;
+  entity_type: string;
+  kind: string;
+  title: string;
+  path: string;
+  start_line?: number;
+  end_line?: number;
+  excerpt: string;
+  score?: number;
+  matched_rules?: unknown[];
+};
+
+export type PatternEvidenceTierName =
+  | "same_file"
+  | "same_module"
+  | "same_feature_area"
+  | "repo_wide";
+
+type PatternEvidenceTier = {
+  name: PatternEvidenceTierName;
+  scope: string;
+  evidence: PatternEvidence[];
+};
+
+const EVIDENCE_TIERS: Array<{ name: PatternEvidenceTierName; scope: string }> = [
+  { name: "same_file", scope: "Same file as the review target." },
+  { name: "same_module", scope: "Same directory or module as the review target." },
+  { name: "same_feature_area", scope: "Same parent feature area as the review target." },
+  { name: "repo_wide", scope: "Repository-wide fallback evidence." },
+];
+
+export function normalizeRepoPath(value: string): string {
+  const normalized = value.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+  return normalized.replace(/\/{2,}/g, "/").replace(/\/$/, "");
+}
+
+function dirnameRepoPath(value: string): string {
+  const normalized = normalizeRepoPath(value);
+  const separator = normalized.lastIndexOf("/");
+  return separator === -1 ? "." : normalized.slice(0, separator) || ".";
+}
+
+function parentRepoPath(value: string): string | null {
+  const normalized = normalizeRepoPath(value);
+  if (!normalized || normalized === ".") {
+    return null;
+  }
+  const separator = normalized.lastIndexOf("/");
+  return separator === -1 ? "." : normalized.slice(0, separator) || ".";
+}
+
+function isWithinPath(candidate: string, directory: string | null): boolean {
+  if (!directory || directory === ".") {
+    return false;
+  }
+  return candidate === directory || candidate.startsWith(`${directory}/`);
+}
+
+function resolvePatternTarget(data: ContextData, input: string): PatternTarget {
+  const normalizedInput = normalizeRepoPath(input);
+  const document = data.documents.find(
+    (entry) => entry.id === input || normalizeRepoPath(entry.path) === normalizedInput,
+  );
+  if (document) {
+    return {
+      input,
+      entity_id: document.id,
+      entity_type: document.kind === "ADR" ? "ADR" : "File",
+      path: normalizeRepoPath(document.path),
+    };
+  }
+
+  const chunk = data.chunks.find((entry) => entry.id === input);
+  if (chunk) {
+    const owner = data.documents.find((entry) => entry.id === chunk.file_id);
+    if (!owner) {
+      throw new Error(`Pattern target chunk has no indexed owner file: ${input}`);
+    }
+    return {
+      input,
+      entity_id: chunk.id,
+      entity_type: "Chunk",
+      path: normalizeRepoPath(owner.path),
+    };
+  }
+
+  const adr = data.adrs.find((entry) => entry.id === input);
+  if (adr?.path) {
+    return {
+      input,
+      entity_id: adr.id,
+      entity_type: "ADR",
+      path: normalizeRepoPath(adr.path),
+    };
+  }
+
+  const knownEntity = [
+    ...data.rules.map((entry) => entry.id),
+    ...data.modules.map((entry) => entry.id),
+    ...data.projects.map((entry) => entry.id),
+  ].includes(input);
+  if (knownEntity) {
+    throw new Error(`Pattern target is not file-backed: ${input}`);
+  }
+  throw new Error(`Pattern target was not found in indexed context: ${input}`);
+}
+
+function derivePatternQuery(data: ContextData, target: PatternTarget): string {
+  if (target.entity_type === "Chunk") {
+    const chunk = data.chunks.find((entry) => entry.id === target.entity_id);
+    if (chunk) {
+      return [chunk.name, chunk.kind, chunk.signature].filter(Boolean).join(" ");
+    }
+  }
+
+  const document = data.documents.find((entry) => entry.id === target.entity_id);
+  const chunkSignals = data.chunks
+    .filter((entry) => entry.file_id === target.entity_id && !entry.id.includes(":window:"))
+    .slice(0, 12)
+    .flatMap((entry) => [entry.name, entry.kind])
+    .filter(Boolean);
+  const basename = target.path.split("/").at(-1)?.replace(/\.[^.]+$/, "") ?? target.path;
+  return [basename, ...chunkSignals, document?.excerpt ?? ""].filter(Boolean).join(" ").slice(0, 1000);
+}
+
+function tierForPath(targetPath: string, candidatePath: string): PatternEvidenceTierName {
+  const normalizedTarget = normalizeRepoPath(targetPath);
+  const normalizedCandidate = normalizeRepoPath(candidatePath);
+  if (normalizedCandidate === normalizedTarget) {
+    return "same_file";
+  }
+
+  const targetModule = dirnameRepoPath(normalizedTarget);
+  if (dirnameRepoPath(normalizedCandidate) === targetModule) {
+    return "same_module";
+  }
+
+  const featureArea = parentRepoPath(targetModule);
+  if (isWithinPath(normalizedCandidate, featureArea)) {
+    return "same_feature_area";
+  }
+  return "repo_wide";
+}
+
+function toPatternEvidence(result: SearchResult, chunksById: Map<string, ChunkRecord>): PatternEvidence | null {
+  const id = typeof result.id === "string" ? result.id : "";
+  const candidatePath = typeof result.path === "string" ? normalizeRepoPath(result.path) : "";
+  if (!id || !candidatePath) {
+    return null;
+  }
+
+  const chunk = chunksById.get(id);
+  const entityType = typeof result.entity_type === "string" ? result.entity_type : "";
+  if (entityType === "Chunk" && (!chunk || chunk.start_line <= 0 || chunk.end_line < chunk.start_line)) {
+    return null;
+  }
+  const evidence: PatternEvidence = {
+    id,
+    entity_type: entityType,
+    kind: typeof result.kind === "string" ? result.kind : "",
+    title: typeof result.title === "string" ? result.title : id,
+    path: candidatePath,
+    excerpt: typeof result.excerpt === "string" ? result.excerpt : "",
+  };
+  if (chunk) {
+    evidence.start_line = chunk.start_line;
+    evidence.end_line = chunk.end_line;
+  }
+  if (typeof result.score === "number") {
+    evidence.score = result.score;
+  }
+  if (Array.isArray(result.matched_rules)) {
+    evidence.matched_rules = [...new Set(result.matched_rules)];
+  }
+  return evidence;
+}
+
+const referenceTimeCache = new WeakMap<ContextData, number>();
+
+export function contextReferenceTimeMs(data: ContextData): number {
+  const cached = referenceTimeCache.get(data);
+  if (cached !== undefined) {
+    return cached;
+  }
+  let latest = 0;
+  const consider = (value: string): void => {
+    const timestamp = Date.parse(value);
+    if (Number.isFinite(timestamp) && timestamp > latest) {
+      latest = timestamp;
+    }
+  };
+  for (const entry of data.documents) consider(entry.updated_at);
+  for (const entry of data.rules) consider(entry.updated_at);
+  for (const entry of data.adrs) consider(entry.decision_date);
+  for (const entry of data.chunks) consider(entry.updated_at);
+  for (const entry of data.modules) consider(entry.updated_at);
+  for (const entry of data.projects) consider(entry.updated_at);
+  referenceTimeCache.set(data, latest);
+  return latest;
+}
+
+export function classifyPatternEvidence(input: {
+  target: PatternTarget;
+  results: SearchResult[];
+  chunks: ChunkRecord[];
+  topK: number;
+}): { tiers: PatternEvidenceTier[]; localPatternFound: boolean; fallbackUsed: boolean } {
+  const chunksById = new Map(input.chunks.map((chunk) => [chunk.id, chunk]));
+  const evidenceByTier = new Map<PatternEvidenceTierName, PatternEvidence[]>(
+    EVIDENCE_TIERS.map((tier) => [tier.name, []]),
+  );
+  const seen = new Set<string>();
+
+  for (const result of input.results) {
+    if (result.id === input.target.entity_id) {
+      continue;
+    }
+    const evidence = toPatternEvidence(result, chunksById);
+    if (!evidence || seen.has(evidence.id)) {
+      continue;
+    }
+    seen.add(evidence.id);
+    const tierName = tierForPath(input.target.path, evidence.path);
+    const tierEvidence = evidenceByTier.get(tierName);
+    if (tierEvidence && tierEvidence.length < input.topK) {
+      tierEvidence.push(evidence);
+    }
+  }
+
+  const tiers = EVIDENCE_TIERS.map((tier) => ({
+    ...tier,
+    evidence: evidenceByTier.get(tier.name) ?? [],
+  }));
+  const localPatternFound = tiers.slice(0, 3).some((tier) => tier.evidence.length > 0);
+  const fallbackUsed = !localPatternFound && tiers[3].evidence.length > 0;
+  return { tiers, localPatternFound, fallbackUsed };
+}
+
+export async function runPatternEvidence(
+  parsed: PatternEvidenceParams,
+  options: { data?: ContextData; use_embeddings?: boolean } = {}
+): Promise<ToolPayload> {
+  const data = options.data ?? await loadContextData();
+  const target = resolvePatternTarget(data, parsed.target);
+  const explicitQuery = parsed.query?.trim();
+  const query = explicitQuery || derivePatternQuery(data, target);
+  if (!query) {
+    throw new Error(`Could not derive a pattern query for target: ${parsed.target}`);
+  }
+
+  const referenceTimeMs = contextReferenceTimeMs(data);
+  const embeddingIndex = options.use_embeddings === false
+    ? { model: null, vectors: new Map<string, Float32Array>() }
+    : loadEmbeddingIndex();
+  const queryVector = embeddingIndex.model && embeddingIndex.vectors.size > 0
+    ? await embedQuery(query, embeddingIndex.model)
+    : null;
+  const tierByEntityId = new Map<string, PatternEvidenceTierName>();
+  for (const entity of iterateSearchEntities(data, false)) {
+    if (
+      entity.id !== target.entity_id &&
+      entity.path &&
+      (entity.entity_type === "File" || entity.entity_type === "Chunk" || entity.entity_type === "ADR")
+    ) {
+      tierByEntityId.set(entity.id, tierForPath(target.path, entity.path));
+    }
+  }
+
+  const searchResults: SearchResult[] = [];
+  const warningParts: string[] = [];
+  let contextSource: unknown = data.source;
+  let semanticEngine: unknown;
+  for (const tier of EVIDENCE_TIERS) {
+    const search = await runContextSearch(
+      {
+        query,
+        top_k: parsed.top_k,
+        include_deprecated: parsed.include_deprecated ?? false,
+        response_preset: "full",
+        include_scores: true,
+        include_matched_rules: true,
+      },
+      {
+        data,
+        reference_time_ms: referenceTimeMs,
+        embedding_index: embeddingIndex,
+        query_vector: queryVector,
+        candidate_filter: (entity) => tierByEntityId.get(entity.id) === tier.name,
+      },
+    );
+    if (Array.isArray(search.results)) {
+      searchResults.push(...search.results as SearchResult[]);
+    }
+    if (typeof search.warning === "string" && !warningParts.includes(search.warning)) {
+      warningParts.push(search.warning);
+    }
+    contextSource = search.context_source ?? contextSource;
+    semanticEngine = search.semantic_engine ?? semanticEngine;
+  }
+  const classified = classifyPatternEvidence({
+    target,
+    results: searchResults,
+    chunks: data.chunks,
+    topK: parsed.top_k,
+  });
+  if (!classified.localPatternFound) {
+    warningParts.push("No applicable file-local, module-local, or feature-local pattern evidence was found.");
+  }
+
+  return {
+    target,
+    query,
+    query_source: explicitQuery ? "explicit" : "derived_from_target",
+    evidence_order: EVIDENCE_TIERS.map((tier) => tier.name),
+    top_k_per_tier: parsed.top_k,
+    ranking_reference_time: referenceTimeMs > 0 ? new Date(referenceTimeMs).toISOString() : null,
+    local_pattern_found: classified.localPatternFound,
+    fallback_used: classified.fallbackUsed,
+    tiers: classified.tiers,
+    context_source: contextSource,
+    semantic_engine: semanticEngine,
+    warning: warningParts.length > 0 ? warningParts.join(" | ") : undefined,
+  };
+}
+
+export async function runLocalPatternEvidence(
+  parsed: PatternEvidenceParams,
+  options: { data?: ContextData } = {}
+): Promise<ToolPayload> {
+  return runPatternEvidence(parsed, { ...options, use_embeddings: false });
+}

package/scaffold/mcp/src/search.ts

@@ -17,6 +17,7 @@ import {
   normalizeText,
   recencyScore,
   semanticScore,
+  structuralSearchBoost,
   tokenize
 } from "./searchCore.js";
 import { buildSearchResultsWithStats } from "./searchResults.js";
@@ -36,6 +37,8 @@ import {
   resolveSearchResponsePreset
 } from "./presets.js";
 import type {
+  ContextData,
+  EmbeddingIndex,
   ImpactParams,
   RelatedParams,
   RelationType,
@@ -58,33 +61,53 @@ const IMPACT_RELATION_TYPES = new Set([
   "PART_OF"
 ]);
 
+export type ContextSearchOptions = {
+  data?: ContextData;
+  candidate_filter?: (entity: SearchEntity) => boolean;
+  reference_time_ms?: number;
+  embedding_index?: EmbeddingIndex;
+  query_vector?: Float32Array | null;
+};
+
 function* filterSearchCandidates(
   candidates: Iterable<SearchEntity>,
-  includeDeprecated: boolean
+  includeDeprecated: boolean,
+  candidateFilter?: (entity: SearchEntity) => boolean
 ): Generator<SearchEntity> {
   for (const entity of candidates) {
-    if (includeDeprecated || entity.status.toLowerCase() !== "deprecated") {
+    if (
+      (includeDeprecated || entity.status.toLowerCase() !== "deprecated") &&
+      (!candidateFilter || candidateFilter(entity))
+    ) {
       yield entity;
     }
   }
 }
 
-export async function runContextSearch(parsed: SearchParams): Promise<ToolPayload> {
+export async function runContextSearch(
+  parsed: SearchParams,
+  options: ContextSearchOptions = {}
+): Promise<ToolPayload> {
   const searchPresetConfig = resolveSearchResponsePreset(parsed);
   const responsePreset = searchPresetConfig.responsePreset;
   const includeScores = searchPresetConfig.includeScores;
   const includeMatchedRules = searchPresetConfig.includeMatchedRules;
   const includeContent = searchPresetConfig.includeContent;
-  const data = await loadContextData();
+  const data = options.data ?? await loadContextData();
   const allRelations = [...data.relations, ...buildChunkPartOfRelations(data)];
   const degreeByEntity = relationDegree(allRelations);
   const queryTokens = expandQueryTokens(Array.from(new Set(tokenize(parsed.query))));
   const queryPhrase = normalizeText(parsed.query).trim();
   const candidates = () =>
-    filterSearchCandidates(iterateSearchEntities(data, includeContent), parsed.include_deprecated);
-  const embeddings = loadEmbeddingIndex();
-  const queryVector =
-    embeddings.model && embeddings.vectors.size > 0
+    filterSearchCandidates(
+      iterateSearchEntities(data, includeContent),
+      parsed.include_deprecated,
+      options.candidate_filter
+    );
+  const embeddings = options.embedding_index ?? loadEmbeddingIndex();
+  const queryVector = Object.prototype.hasOwnProperty.call(options, "query_vector")
+    ? options.query_vector ?? null
+    : embeddings.model && embeddings.vectors.size > 0
       ? await embedQuery(parsed.query, embeddings.model)
       : null;
 
@@ -104,7 +127,10 @@ export async function runContextSearch(parsed: SearchParams): Promise<ToolPayloa
     minVectorRelevance: MIN_VECTOR_RELEVANCE,
     semanticScorer: semanticScore,
     vectorScorer: cosineSimilarity,
-    recencyScorer: recencyScore,
+    recencyScorer: options.reference_time_ms === undefined
+      ? recencyScore
+      : (isoDate) => recencyScore(isoDate, options.reference_time_ms),
+    structuralSearchBooster: structuralSearchBoost,
     legacyDataAccessBooster: legacyDataAccessBoost
   });