@danielblomma/cortex-mcp 1.7.2 → 2.0.3

package/scaffold/mcp/src/core/validators/config.ts

@@ -0,0 +1,47 @@
+export type ValidatorsConfig = Record<string, Record<string, unknown>>;
+
+/**
+ * Parse the validators section from the simple YAML fields map.
+ *
+ * Fields arrive as flat "validators.max-file-size.max_bytes" = "500000" entries.
+ * We reconstruct them into nested config: { "max-file-size": { max_bytes: 500000 } }.
+ */
+export function parseValidatorsConfig(fields: Record<string, string>): ValidatorsConfig {
+  const config: ValidatorsConfig = {};
+  const prefix = "validators.";
+
+  for (const [key, value] of Object.entries(fields)) {
+    if (!key.startsWith(prefix)) continue;
+
+    const rest = key.slice(prefix.length);
+    const dotIndex = rest.indexOf(".");
+    if (dotIndex < 0) continue;
+
+    const validatorId = rest.slice(0, dotIndex);
+    const optionKey = rest.slice(dotIndex + 1);
+
+    if (!config[validatorId]) {
+      config[validatorId] = {};
+    }
+
+    config[validatorId][optionKey] = coerceValue(value);
+  }
+
+  return config;
+}
+
+function coerceValue(value: string): unknown {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  const num = Number(value);
+  if (!Number.isNaN(num) && value.trim() !== "") return num;
+  // Handle YAML-style arrays: ["a", "b", "c"]
+  if (value.startsWith("[") && value.endsWith("]")) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      // Fall through to string
+    }
+  }
+  return value;
+}

package/scaffold/mcp/src/core/validators/engine.ts

@@ -0,0 +1,199 @@
+export type ValidatorContext = {
+  contextDir: string;
+  projectRoot: string;
+  changedFiles?: string[];
+};
+
+export type ValidatorResult = {
+  pass: boolean;
+  severity: "error" | "warning" | "info";
+  message: string;
+  detail?: string;
+};
+
+export type ValidatorDef = {
+  policyId: string;
+  check: (ctx: ValidatorContext, options: Record<string, unknown>) => Promise<ValidatorResult>;
+};
+
+// Generic evaluators are keyed by `type`, not by policyId. One evaluator
+// can execute many policies (e.g. a single RegexEvaluator runs every
+// custom regex rule the user defines in cortex-web). Used when a policy
+// declares `type` + `config`; name-based validators are the fallback for
+// predefined rules that ship with the plugin.
+export type GenericEvaluatorDef = {
+  type: string;
+  check: (ctx: ValidatorContext, config: Record<string, unknown>) => Promise<ValidatorResult>;
+};
+
+// An enforced policy as passed to runValidators. `type` + `config` are
+// optional — predefined rules leave them null and fall back to the
+// name-based validator registry.
+export type EnforcedPolicy = {
+  id: string;
+  type?: string | null;
+  config?: Record<string, unknown> | null;
+  severity?: "info" | "warning" | "error" | "block" | null;
+};
+
+const registry = new Map<string, ValidatorDef>();
+const genericRegistry = new Map<string, GenericEvaluatorDef>();
+
+export function registerValidator(def: ValidatorDef): void {
+  registry.set(def.policyId, def);
+}
+
+export function getValidator(policyId: string): ValidatorDef | undefined {
+  return registry.get(policyId);
+}
+
+export function getRegisteredPolicyIds(): string[] {
+  return [...registry.keys()];
+}
+
+export function registerGenericEvaluator(def: GenericEvaluatorDef): void {
+  genericRegistry.set(def.type, def);
+}
+
+export function getGenericEvaluator(type: string): GenericEvaluatorDef | undefined {
+  return genericRegistry.get(type);
+}
+
+export function getRegisteredEvaluatorTypes(): string[] {
+  return [...genericRegistry.keys()];
+}
+
+export type ReviewResult = {
+  policy_id: string;
+  pass: boolean;
+  severity: "error" | "warning" | "info";
+  message: string;
+  detail?: string;
+};
+
+export type ReviewSummary = {
+  total: number;
+  passed: number;
+  failed: number;
+  warnings: number;
+};
+
+export type ReviewOutput = {
+  results: ReviewResult[];
+  summary: ReviewSummary;
+};
+
+function resolvePolicySeverity(
+  policy: EnforcedPolicy,
+  fallback: ReviewResult["severity"],
+): ReviewResult["severity"] {
+  if (!policy.severity) return fallback;
+  return policy.severity === "block" ? "error" : policy.severity;
+}
+
+/**
+ * Run validators for every enforced policy. Dispatch order per policy:
+ *   1. If the policy has a `type`, look it up in the generic evaluator
+ *      registry (cortex-web custom rules use this path).
+ *   2. Otherwise, look up a name-based validator by policy id
+ *      (predefined rules shipped with the plugin use this path).
+ *   3. If neither path yields an implementation, emit a warning so the
+ *      gap is visible instead of silent.
+ *
+ * Accepts either `Set<string>` (legacy id-only callers) or an array of
+ * `EnforcedPolicy` objects carrying `type` + `config` from the
+ * cortex-web policy sync. Set inputs are normalized to entries with
+ * null type/config, so they always route to the name-based registry.
+ */
+export async function runValidators(
+  enforced: Set<string> | EnforcedPolicy[],
+  ctx: ValidatorContext,
+  validatorConfigs: Record<string, Record<string, unknown>>,
+): Promise<ReviewOutput> {
+  const policies: EnforcedPolicy[] =
+    enforced instanceof Set
+      ? [...enforced].map((id) => ({ id }))
+      : enforced;
+
+  const results: ReviewResult[] = [];
+
+  for (const policy of policies) {
+    if (policy.type) {
+      const evaluator = genericRegistry.get(policy.type);
+      if (!evaluator) {
+        results.push({
+          policy_id: policy.id,
+          pass: false,
+          severity: "warning",
+          message: `No evaluator registered for type "${policy.type}"`,
+          detail:
+            "This policy declares a generic evaluator type that is not " +
+            "implemented in this version of the enterprise plugin. " +
+            "Upgrade the plugin or change the rule type.",
+        });
+        continue;
+      }
+      try {
+        const result = await evaluator.check(ctx, policy.config ?? {});
+        results.push({
+          policy_id: policy.id,
+          pass: result.pass,
+          severity: resolvePolicySeverity(policy, result.severity),
+          message: result.message,
+          detail: result.detail,
+        });
+      } catch (err) {
+        results.push({
+          policy_id: policy.id,
+          pass: false,
+          severity: "error",
+          message: `Evaluator error: ${err instanceof Error ? err.message : String(err)}`,
+        });
+      }
+      continue;
+    }
+
+    const def = registry.get(policy.id);
+    if (!def) {
+      results.push({
+        policy_id: policy.id,
+        pass: false,
+        severity: "warning",
+        message: "No validator implementation registered for this policy",
+        detail:
+          "This policy is enforced but the server-side check is missing. " +
+          "Either install an enterprise plugin that provides it, or disable " +
+          "enforcement in the policy dashboard.",
+      });
+      continue;
+    }
+
+    const options = validatorConfigs[policy.id] ?? {};
+    try {
+      const result = await def.check(ctx, options);
+      results.push({
+        policy_id: policy.id,
+        pass: result.pass,
+        severity: resolvePolicySeverity(policy, result.severity),
+        message: result.message,
+        detail: result.detail,
+      });
+    } catch (err) {
+      results.push({
+        policy_id: policy.id,
+        pass: false,
+        severity: "error",
+        message: `Validator error: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+
+  const summary: ReviewSummary = {
+    total: results.length,
+    passed: results.filter((r) => r.pass).length,
+    failed: results.filter((r) => !r.pass && r.severity === "error").length,
+    warnings: results.filter((r) => !r.pass && r.severity === "warning").length,
+  };
+
+  return { results, summary };
+}

package/scaffold/mcp/src/core/validators/evaluators/code_comments.ts

@@ -0,0 +1,294 @@
+import { statSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  registerGenericEvaluator,
+  type ValidatorContext,
+  type ValidatorResult,
+} from "../engine.js";
+
+// Per "parser parity" — every supported language is a first-class citizen.
+// Adding a new language means adding an entry to LANGUAGES plus a positive
+// and a negative test. Extensions listed here are the only files scanned.
+
+type EndStyle = "braces" | "indent";
+
+type LanguageSpec = {
+  name: string;
+  extensions: string[];
+  functionPatterns: RegExp[];
+  lineCommentPrefix: string;
+  // Block comment support is optional; leave empty to disable.
+  blockCommentStart: string;
+  blockCommentEnd: string;
+  endStyle: EndStyle;
+  // Python-style: a docstring as the first statement in the body counts as
+  // a comment. Only relevant for indent-style languages right now.
+  allowsDocstring?: boolean;
+};
+
+const LANGUAGES: LanguageSpec[] = [
+  {
+    name: "TypeScript/JavaScript",
+    extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+    functionPatterns: [
+      /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*(\w+)\s*(?:<[^>]*>)?\s*\(/,
+      /^\s*(?:export\s+)?(?:const|let|var)\s+(\w+)\s*(?::\s*[\w<>,\s[\]|&]+)?\s*=\s*(?:async\s*)?(?:<[^>]*>)?\s*\([^)]*\)\s*(?::\s*[\w<>,\s[\]|&]+\s*)?=>/,
+      /^\s*(?:public|private|protected)?\s*(?:static\s+)?(?:readonly\s+)?(?:async\s+)?(?:\*\s*)?(\w+)\s*(?:<[^>]*>)?\s*\([^)]*\)\s*(?::\s*[\w<>,\s[\]|&]+\s*)?\{/,
+    ],
+    lineCommentPrefix: "//",
+    blockCommentStart: "/*",
+    blockCommentEnd: "*/",
+    endStyle: "braces",
+  },
+  {
+    name: "Python",
+    extensions: [".py"],
+    functionPatterns: [
+      /^(\s*)(?:async\s+)?def\s+(\w+)\s*\(/,
+    ],
+    lineCommentPrefix: "#",
+    blockCommentStart: "",
+    blockCommentEnd: "",
+    endStyle: "indent",
+    allowsDocstring: true,
+  },
+  {
+    name: "Go",
+    extensions: [".go"],
+    functionPatterns: [
+      /^func\s+(?:\([^)]+\)\s+)?(\w+)\s*\(/,
+    ],
+    lineCommentPrefix: "//",
+    blockCommentStart: "/*",
+    blockCommentEnd: "*/",
+    endStyle: "braces",
+  },
+  {
+    name: "Rust",
+    extensions: [".rs"],
+    functionPatterns: [
+      /^\s*(?:pub(?:\s*\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(?:extern\s+(?:"[^"]*"\s+)?)?fn\s+(\w+)/,
+    ],
+    lineCommentPrefix: "//",
+    blockCommentStart: "/*",
+    blockCommentEnd: "*/",
+    endStyle: "braces",
+  },
+  {
+    name: "C#",
+    extensions: [".cs"],
+    functionPatterns: [
+      // Require at least one access/modifier keyword so we don't match
+      // arbitrary `name(args)` calls. Return type is optional to also
+      // match constructors.
+      /^\s*(?:(?:public|private|protected|internal|static|async|override|virtual|sealed|abstract|new|partial)\s+)+(?:[\w<>\[\],?\s]+?\s+)?(\w+)\s*\([^)]*\)\s*(?:\{|where|:|=>|$)/,
+    ],
+    lineCommentPrefix: "//",
+    blockCommentStart: "/*",
+    blockCommentEnd: "*/",
+    endStyle: "braces",
+  },
+  {
+    name: "Java",
+    extensions: [".java"],
+    functionPatterns: [
+      /^\s*(?:(?:public|private|protected|static|final|abstract|synchronized|native)\s+)+(?:[\w<>\[\],?\s]+?\s+)?(\w+)\s*\([^)]*\)\s*(?:\{|throws|$)/,
+    ],
+    lineCommentPrefix: "//",
+    blockCommentStart: "/*",
+    blockCommentEnd: "*/",
+    endStyle: "braces",
+  },
+];
+
+function pickLanguage(file: string): LanguageSpec | null {
+  const lower = file.toLowerCase();
+  for (const lang of LANGUAGES) {
+    if (lang.extensions.some((ext) => lower.endsWith(ext))) {
+      return lang;
+    }
+  }
+  return null;
+}
+
+// Scan for a preceding comment within `lookback` non-blank lines above
+// `startLine` (exclusive). Returns true if a comment is found.
+function hasPrecedingComment(
+  lines: string[],
+  startLine: number,
+  lang: LanguageSpec,
+  lookback: number,
+): boolean {
+  let checked = 0;
+  for (let i = startLine - 1; i >= 0 && checked < lookback; i -= 1) {
+    const trimmed = lines[i].trim();
+    if (trimmed === "") continue;
+    checked += 1;
+
+    if (trimmed.startsWith(lang.lineCommentPrefix)) return true;
+    if (lang.blockCommentStart) {
+      if (trimmed.endsWith(lang.blockCommentEnd)) return true;
+      if (trimmed.startsWith(lang.blockCommentStart)) return true;
+    }
+    // First non-blank non-comment line above → no leading comment.
+    return false;
+  }
+  return false;
+}
+
+function isDocstringLine(line: string): boolean {
+  const t = line.trim();
+  return t.startsWith('"""') || t.startsWith("'''") || t.startsWith('"') || t.startsWith("'");
+}
+
+// Walk forward from `startLine` (the function declaration line) and return
+// the (exclusive) end-of-function line. Handles both brace and indent
+// styles. Naive — comments/strings may contain braces and skew the
+// counter; acceptable tradeoff without per-language AST parsing.
+function findFunctionEnd(
+  lines: string[],
+  startLine: number,
+  lang: LanguageSpec,
+  indentMatch?: string,
+): number {
+  if (lang.endStyle === "indent") {
+    const baseIndent = (indentMatch ?? "").length;
+    for (let i = startLine + 1; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (line.trim() === "") continue;
+      const indent = line.length - line.trimStart().length;
+      if (indent <= baseIndent) return i;
+    }
+    return lines.length;
+  }
+
+  // Braces
+  let depth = 0;
+  let seenOpen = false;
+  for (let i = startLine; i < lines.length; i += 1) {
+    const line = lines[i];
+    for (let j = 0; j < line.length; j += 1) {
+      const c = line[j];
+      if (c === "{") {
+        depth += 1;
+        seenOpen = true;
+      } else if (c === "}") {
+        depth -= 1;
+        if (seenOpen && depth === 0) return i + 1;
+      }
+    }
+  }
+  return lines.length;
+}
+
+type Violation = {
+  file: string;
+  line: number;
+  name: string;
+  lineCount: number;
+};
+
+function scanFile(
+  content: string,
+  file: string,
+  lang: LanguageSpec,
+  minLines: number,
+): Violation[] {
+  const lines = content.split("\n");
+  const hits: Violation[] = [];
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    for (const pattern of lang.functionPatterns) {
+      const m = line.match(pattern);
+      if (!m) continue;
+
+      // For Python, capture group 1 is indent, 2 is name; for others, 1 is name.
+      const name = lang.endStyle === "indent" ? m[2] ?? "<anonymous>" : m[1] ?? "<anonymous>";
+      const indent = lang.endStyle === "indent" ? m[1] ?? "" : undefined;
+
+      const endLine = findFunctionEnd(lines, i, lang, indent);
+      const funcLineCount = endLine - i;
+
+      if (funcLineCount < minLines) break;
+
+      if (hasPrecedingComment(lines, i, lang, 3)) break;
+
+      if (lang.allowsDocstring && lines[i + 1] && isDocstringLine(lines[i + 1])) break;
+
+      hits.push({ file, line: i + 1, name, lineCount: funcLineCount });
+      break; // one match per line is enough
+    }
+  }
+
+  return hits;
+}
+
+registerGenericEvaluator({
+  type: "code_comments",
+  async check(ctx: ValidatorContext, config: Record<string, unknown>): Promise<ValidatorResult> {
+    const files = ctx.changedFiles ?? [];
+    if (files.length === 0) {
+      return { pass: true, severity: "info", message: "No changed files to scan" };
+    }
+
+    const minLines = typeof config.min_lines === "number" && config.min_lines > 0 ? config.min_lines : 15;
+    const severity =
+      config.severity === "error" || config.severity === "warning" || config.severity === "info"
+        ? config.severity
+        : "warning";
+    const allowlist = Array.isArray(config.allowlist_paths)
+      ? config.allowlist_paths.filter((p): p is string => typeof p === "string")
+      : ["tests/", "test/", "__tests__/", "fixtures/", "docs/"];
+    const maxBytes = typeof config.max_scan_bytes === "number" ? config.max_scan_bytes : 2_000_000;
+
+    // Optional language filter (by name, case-insensitive). Absent = all.
+    const wantedLanguages = Array.isArray(config.languages)
+      ? new Set(
+          config.languages.filter((l): l is string => typeof l === "string").map((l) => l.toLowerCase()),
+        )
+      : null;
+
+    const allHits: Violation[] = [];
+    let scanned = 0;
+
+    for (const file of files) {
+      if (allowlist.some((p) => file.includes(p))) continue;
+      const lang = pickLanguage(file);
+      if (!lang) continue;
+      if (wantedLanguages && !wantedLanguages.has(lang.name.toLowerCase())) continue;
+
+      const abs = join(ctx.projectRoot, file);
+      try {
+        const stat = statSync(abs);
+        if (stat.size > maxBytes) continue;
+        const content = readFileSync(abs, "utf8");
+        scanned += 1;
+        allHits.push(...scanFile(content, file, lang, minLines));
+      } catch {
+        // unreadable — skip
+      }
+    }
+
+    if (allHits.length === 0) {
+      return {
+        pass: true,
+        severity: "info",
+        message: `No undocumented functions (${minLines}+ lines) in ${scanned} changed file${scanned === 1 ? "" : "s"}`,
+      };
+    }
+
+    const detail =
+      allHits
+        .slice(0, 30)
+        .map((h) => `${h.file}:${h.line} — ${h.name} (${h.lineCount} lines)`)
+        .join("\n") + (allHits.length > 30 ? `\n... and ${allHits.length - 30} more` : "");
+
+    return {
+      pass: false,
+      severity,
+      message: `${allHits.length} function${allHits.length === 1 ? "" : "s"} of ${minLines}+ lines without preceding comment`,
+      detail,
+    };
+  },
+});

package/scaffold/mcp/src/core/validators/evaluators/regex.ts

@@ -0,0 +1,144 @@
+import { statSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  registerGenericEvaluator,
+  type ValidatorContext,
+  type ValidatorResult,
+} from "../engine.js";
+
+const BINARY_SNIFF_BYTES = 512;
+const DEFAULT_MAX_BYTES = 2_000_000;
+
+const SEVERITIES = new Set(["error", "warning", "info"]);
+
+type RegexConfig = {
+  pattern: string;
+  flags?: string;
+  file_pattern?: string;
+  severity?: "error" | "warning" | "info";
+  message?: string;
+  max_matches_per_file?: number;
+  max_scan_bytes?: number;
+  allowlist_paths?: string[];
+};
+
+function parseConfig(raw: Record<string, unknown>): RegexConfig | { error: string } {
+  const pattern = raw.pattern;
+  if (typeof pattern !== "string" || pattern.length === 0) {
+    return { error: "config.pattern must be a non-empty string" };
+  }
+  try {
+    new RegExp(pattern, typeof raw.flags === "string" ? raw.flags : undefined);
+  } catch (err) {
+    return { error: `config.pattern is not a valid regex: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  const severity = raw.severity;
+  if (severity !== undefined && (typeof severity !== "string" || !SEVERITIES.has(severity))) {
+    return { error: 'config.severity must be one of "error", "warning", "info"' };
+  }
+
+  if (raw.file_pattern !== undefined && typeof raw.file_pattern !== "string") {
+    return { error: "config.file_pattern must be a string" };
+  }
+  if (raw.file_pattern) {
+    try {
+      new RegExp(raw.file_pattern);
+    } catch (err) {
+      return { error: `config.file_pattern is not a valid regex: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+
+  return {
+    pattern,
+    flags: typeof raw.flags === "string" ? raw.flags : undefined,
+    file_pattern: typeof raw.file_pattern === "string" ? raw.file_pattern : undefined,
+    severity: severity as "error" | "warning" | "info" | undefined,
+    message: typeof raw.message === "string" ? raw.message : undefined,
+    max_matches_per_file:
+      typeof raw.max_matches_per_file === "number" ? raw.max_matches_per_file : undefined,
+    max_scan_bytes:
+      typeof raw.max_scan_bytes === "number" ? raw.max_scan_bytes : undefined,
+    allowlist_paths: Array.isArray(raw.allowlist_paths)
+      ? raw.allowlist_paths.filter((p): p is string => typeof p === "string")
+      : undefined,
+  };
+}
+
+registerGenericEvaluator({
+  type: "regex",
+  async check(ctx: ValidatorContext, rawConfig: Record<string, unknown>): Promise<ValidatorResult> {
+    const parsed = parseConfig(rawConfig);
+    if ("error" in parsed) {
+      return { pass: false, severity: "error", message: `Invalid regex config: ${parsed.error}` };
+    }
+
+    const files = ctx.changedFiles ?? [];
+    if (files.length === 0) {
+      return { pass: true, severity: "info", message: "No changed files to scan" };
+    }
+
+    const severity = parsed.severity ?? "warning";
+    const allowlist = parsed.allowlist_paths ?? ["tests/", "test/", "__tests__/", "fixtures/", "docs/"];
+    const maxBytes = parsed.max_scan_bytes ?? DEFAULT_MAX_BYTES;
+    const maxMatches = parsed.max_matches_per_file ?? 20;
+
+    // A regex used purely to filter file paths should be anchored by the
+    // caller if needed; we compile as-is to give them full control.
+    const fileRe = parsed.file_pattern ? new RegExp(parsed.file_pattern) : null;
+    const contentRe = new RegExp(parsed.pattern, parsed.flags);
+
+    const hits: string[] = [];
+    let scanned = 0;
+
+    for (const file of files) {
+      if (allowlist.some((p) => file.includes(p))) continue;
+      if (fileRe && !fileRe.test(file)) continue;
+
+      const abs = join(ctx.projectRoot, file);
+      try {
+        const stat = statSync(abs);
+        if (stat.size > maxBytes) continue;
+
+        const buf = readFileSync(abs);
+        const sniff = buf.subarray(0, Math.min(buf.length, BINARY_SNIFF_BYTES));
+        if (sniff.includes(0)) continue;
+
+        const content = buf.toString("utf8");
+        scanned += 1;
+
+        const lines = content.split("\n");
+        let fileMatches = 0;
+        for (let i = 0; i < lines.length; i += 1) {
+          // Compile a per-line test with the `g` flag stripped so we don't
+          // hop across repeated state; callers supply single-line patterns.
+          const lineRe = new RegExp(contentRe.source, (contentRe.flags || "").replace(/g/g, ""));
+          if (lineRe.test(lines[i])) {
+            hits.push(`${file}:${i + 1}`);
+            fileMatches += 1;
+            if (fileMatches >= maxMatches) break;
+          }
+        }
+      } catch {
+        // Unreadable file — skip
+      }
+    }
+
+    if (hits.length === 0) {
+      return {
+        pass: true,
+        severity: "info",
+        message: `No regex matches in ${scanned} changed file${scanned === 1 ? "" : "s"}`,
+      };
+    }
+
+    const messageStem = parsed.message ?? "Pattern match";
+    return {
+      pass: false,
+      severity,
+      message: `${messageStem}: ${hits.length} match${hits.length === 1 ? "" : "es"} in ${scanned} file${scanned === 1 ? "" : "s"}`,
+      detail:
+        hits.slice(0, 30).join("\n") + (hits.length > 30 ? `\n... and ${hits.length - 30} more` : ""),
+    };
+  },
+});