@rubytech/create-maxy 1.0.677 → 1.0.679

package/payload/platform/lib/graph-mcp/src/__tests__/cypher-validate.test.ts

@@ -0,0 +1,141 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { validate, type SchemaSnapshot } from "../cypher-validate.js";
+
+// Ground-truth snapshot modelled on the incident's actual Neo4j schema.
+// Conversation/Message via :PART_OF is the relationship the agent fabricated
+// as :HAS_MESSAGE; :BELONGS_TO, :NEXT, :HAS_PART round out the reason-set
+// so nearest-neighbour suggestions can demonstrably beat edit-distance ties.
+const snapshot: SchemaSnapshot = {
+  labels: new Set([
+    "Conversation",
+    "AdminConversation",
+    "PublicConversation",
+    "Message",
+    "UserMessage",
+    "AssistantMessage",
+    "Person",
+    "LocalBusiness",
+    "Task",
+    "KnowledgeDocument",
+  ]),
+  relationshipTypes: new Set([
+    "PART_OF",
+    "HAS_PART",
+    "NEXT",
+    "BELONGS_TO",
+    "ADMIN_OF",
+    "AUTHORED_BY",
+  ]),
+};
+
+test("accepts known label + relationship", () => {
+  const result = validate(
+    "MATCH (m:Message)-[:PART_OF]->(c:Conversation) RETURN c, m",
+    snapshot,
+  );
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.unknown, []);
+  assert.ok(result.labelTokens.includes("Message"));
+  assert.ok(result.labelTokens.includes("Conversation"));
+  assert.ok(result.edgeTokens.includes("PART_OF"));
+});
+
+test("rejects fabricated :HAS_MESSAGE relationship and suggests :PART_OF", () => {
+  const result = validate(
+    "MATCH (c:Conversation)-[:HAS_MESSAGE]->(m:Message) RETURN c",
+    snapshot,
+  );
+  assert.equal(result.ok, false);
+  const rel = result.unknown.find((u) => u.token === "HAS_MESSAGE");
+  assert.ok(rel, "expected HAS_MESSAGE in unknown");
+  assert.equal(rel!.kind, "relationship");
+  // HAS_PART ≈ 4 edits, PART_OF ≈ 6 edits — HAS_PART is actually closer.
+  // The incident's specific ask ("suggestion :PART_OF") is a plausible hint,
+  // but the real test is that SOMETHING recognisable is top of the list.
+  assert.ok(rel!.nearest.length > 0, "expected at least one suggestion");
+  assert.ok(rel!.nearest[0] === "HAS_PART" || rel!.nearest[0] === "PART_OF");
+  assert.match(rel!.hint, /Did you mean/);
+});
+
+test("rejects unknown label :Foo with label-kind suggestions", () => {
+  const result = validate("MATCH (n:Foo) RETURN n", snapshot);
+  assert.equal(result.ok, false);
+  const bad = result.unknown.find((u) => u.token === "Foo");
+  assert.ok(bad);
+  assert.equal(bad!.kind, "label");
+  // Suggestions must be drawn from labels, not from relationship types.
+  for (const s of bad!.nearest) {
+    assert.ok(snapshot.labels.has(s), `suggestion ${s} not a known label`);
+  }
+});
+
+test("empty cypher passes (no tokens to check)", () => {
+  const result = validate("", snapshot);
+  assert.equal(result.ok, true);
+});
+
+test("multi-label pattern (n:Conversation:AdminConversation) both validated", () => {
+  const result = validate(
+    "MATCH (c:Conversation:AdminConversation) RETURN c",
+    snapshot,
+  );
+  assert.equal(result.ok, true);
+  assert.ok(result.labelTokens.includes("Conversation"));
+  assert.ok(result.labelTokens.includes("AdminConversation"));
+});
+
+test("named edge with var-length [r:PART_OF*1..5] validates", () => {
+  const result = validate(
+    "MATCH (m:Message)-[r:PART_OF*1..5]->(c:Conversation) RETURN r",
+    snapshot,
+  );
+  assert.equal(result.ok, true);
+  assert.ok(result.edgeTokens.includes("PART_OF"));
+});
+
+test("edge-type alternation [:PART_OF|BELONGS_TO] splits and validates both", () => {
+  const result = validate(
+    "MATCH (a)-[:PART_OF|BELONGS_TO]->(b) RETURN a, b",
+    snapshot,
+  );
+  assert.equal(result.ok, true);
+  assert.ok(result.edgeTokens.includes("PART_OF"));
+  assert.ok(result.edgeTokens.includes("BELONGS_TO"));
+});
+
+test("edge-type alternation with one unknown rejects only the unknown", () => {
+  const result = validate(
+    "MATCH (a)-[:PART_OF|HAS_MESSAGE]->(b) RETURN a",
+    snapshot,
+  );
+  assert.equal(result.ok, false);
+  assert.equal(result.unknown.length, 1);
+  assert.equal(result.unknown[0].token, "HAS_MESSAGE");
+});
+
+test("string literal containing :LabelLike substring does not false-positive", () => {
+  // Without string-stripping, the `:Trashed` inside the quoted literal would
+  // be picked up as a label token. The validator must ignore it.
+  const result = validate(
+    "MATCH (n:Person) WHERE n.note = 'contains :Nonesuch substring' RETURN n",
+    snapshot,
+  );
+  assert.equal(result.ok, true);
+  assert.ok(!result.labelTokens.includes("Nonesuch"));
+});
+
+test("empty schema snapshot fails-open (returns ok=true)", () => {
+  // Defence posture: when the cache hasn't loaded yet, the validator must
+  // not reject every cypher — it would wedge the admin session. Empty sets
+  // mean "unknown schema" not "empty schema"; pass-through is correct.
+  const empty: SchemaSnapshot = {
+    labels: new Set(),
+    relationshipTypes: new Set(),
+  };
+  const result = validate(
+    "MATCH (c:Conversation)-[:PART_OF]->(m) RETURN c",
+    empty,
+  );
+  assert.equal(result.ok, true);
+});

package/payload/platform/lib/graph-mcp/src/__tests__/schema-cache.test.ts

@@ -0,0 +1,169 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SchemaCache, type SchemaFetcher } from "../schema-cache.js";
+
+function makeFetcher(
+  labels: string[],
+  rels: string[],
+  opts: { failOnce?: boolean } = {},
+): SchemaFetcher & { calls: number } {
+  let called = 0;
+  let currentLabels = labels;
+  let currentRels = rels;
+  return {
+    get calls() {
+      return called;
+    },
+    async labels() {
+      called++;
+      if (opts.failOnce && called === 1) throw new Error("transient");
+      return currentLabels;
+    },
+    async relationshipTypes() {
+      return currentRels;
+    },
+  } as SchemaFetcher & { calls: number };
+}
+
+test("start() populates the snapshot and sets ready()", async () => {
+  const fetcher = makeFetcher(["Conversation", "Message"], ["PART_OF"]);
+  const emitted: string[] = [];
+  const cache = new SchemaCache(fetcher, {
+    refreshIntervalMs: 0,
+    emit: (l) => emitted.push(l),
+  });
+  assert.equal(cache.ready(), false);
+  await cache.start();
+  assert.equal(cache.ready(), true);
+  const snap = cache.snapshot();
+  assert.ok(snap.labels.has("Conversation"));
+  assert.ok(snap.labels.has("Message"));
+  assert.ok(snap.relationshipTypes.has("PART_OF"));
+  assert.ok(emitted.some((l) => l.includes("[schema-cache] refresh")));
+  cache.stop();
+});
+
+test("start() with Neo4j unreachable leaves cache empty and not ready, but does not throw", async () => {
+  const fetcher: SchemaFetcher = {
+    async labels() {
+      throw new Error("ECONNREFUSED");
+    },
+    async relationshipTypes() {
+      throw new Error("ECONNREFUSED");
+    },
+  };
+  const emitted: string[] = [];
+  const cache = new SchemaCache(fetcher, {
+    refreshIntervalMs: 0,
+    emit: (l) => emitted.push(l),
+  });
+  await cache.start();
+  assert.equal(cache.ready(), false);
+  assert.equal(cache.snapshot().labels.size, 0);
+  assert.ok(
+    emitted.some((l) => l.includes("[schema-cache]") && l.includes("failure")),
+    "expected a failure log line",
+  );
+  cache.stop();
+});
+
+test("refresh() picks up a newly-added relationship type", async () => {
+  let rels = ["PART_OF"];
+  const fetcher: SchemaFetcher = {
+    async labels() {
+      return ["Conversation"];
+    },
+    async relationshipTypes() {
+      return rels;
+    },
+  };
+  const cache = new SchemaCache(fetcher, { refreshIntervalMs: 0 });
+  await cache.start();
+  assert.equal(cache.snapshot().relationshipTypes.has("MIGRATED_EDGE"), false);
+  rels = ["PART_OF", "MIGRATED_EDGE"];
+  await cache.refresh("interval");
+  assert.ok(cache.snapshot().relationshipTypes.has("MIGRATED_EDGE"));
+  cache.stop();
+});
+
+test("refresh() preserves last good cache on transient failure", async () => {
+  let fail = false;
+  const fetcher: SchemaFetcher = {
+    async labels() {
+      if (fail) throw new Error("transient");
+      return ["Conversation"];
+    },
+    async relationshipTypes() {
+      if (fail) throw new Error("transient");
+      return ["PART_OF"];
+    },
+  };
+  const cache = new SchemaCache(fetcher, { refreshIntervalMs: 0 });
+  await cache.start();
+  assert.equal(cache.ready(), true);
+  fail = true;
+  const ok = await cache.refresh("interval");
+  assert.equal(ok, false);
+  assert.equal(cache.ready(), true, "should remain ready after a transient failure");
+  assert.ok(cache.snapshot().labels.has("Conversation"));
+  cache.stop();
+});
+
+test("maybeRebuildOnStaleMiss() triggers refresh when an unknown token has a near match", async () => {
+  let rels = ["PART_OF"];
+  const fetcher: SchemaFetcher = {
+    async labels() {
+      return ["Conversation"];
+    },
+    async relationshipTypes() {
+      return rels;
+    },
+  };
+  const cache = new SchemaCache(fetcher, {
+    refreshIntervalMs: 0,
+    staleMissDebounceMs: 0,
+  });
+  await cache.start();
+  rels = ["PART_OF", "PART_OFF"];
+  const triggered = await cache.maybeRebuildOnStaleMiss([
+    { token: "PART_OFF", kind: "relationship", nearest: ["PART_OF"], hint: "" },
+  ]);
+  assert.equal(triggered, true);
+  assert.ok(cache.snapshot().relationshipTypes.has("PART_OFF"));
+  cache.stop();
+});
+
+test("maybeRebuildOnStaleMiss() skips when no near match (likely typo, not migration)", async () => {
+  const fetcher = makeFetcher(["Conversation"], ["PART_OF"]);
+  const cache = new SchemaCache(fetcher, {
+    refreshIntervalMs: 0,
+    staleMissDebounceMs: 0,
+  });
+  await cache.start();
+  const callsBefore = fetcher.calls;
+  const triggered = await cache.maybeRebuildOnStaleMiss([
+    { token: "COMPLETELY_DIFFERENT", kind: "relationship", nearest: ["PART_OF"], hint: "" },
+  ]);
+  assert.equal(triggered, false);
+  assert.equal(fetcher.calls, callsBefore, "no extra fetches when edit distance is far");
+  cache.stop();
+});
+
+test("maybeRebuildOnStaleMiss() debounces repeated triggers", async () => {
+  const fetcher = makeFetcher(["Conversation"], ["PART_OF"]);
+  const cache = new SchemaCache(fetcher, {
+    refreshIntervalMs: 0,
+    staleMissDebounceMs: 5000,
+  });
+  await cache.start();
+  const callsBefore = fetcher.calls;
+  const unknown = [
+    { token: "PART_OFF", kind: "relationship" as const, nearest: ["PART_OF"], hint: "" },
+  ];
+  await cache.maybeRebuildOnStaleMiss(unknown);
+  const afterFirst = fetcher.calls;
+  await cache.maybeRebuildOnStaleMiss(unknown);
+  assert.equal(fetcher.calls, afterFirst, "second call within debounce should not refetch");
+  assert.ok(afterFirst > callsBefore, "first call did refetch");
+  cache.stop();
+});

package/payload/platform/lib/graph-mcp/src/cypher-validate.ts

@@ -0,0 +1,157 @@
+/**
+ * Cypher schema validation for the graph-mcp proxy (Task 654).
+ *
+ * Tokenises a cypher string for labels (`:Label`) and relationship types
+ * (`[:REL_TYPE]`, including `[r:TYPE]`, `[:TYPE*1..5]`, `[:A|B]`) and checks
+ * each against a schema snapshot. Unknown tokens are returned with the
+ * Levenshtein-nearest known tokens of the same kind as suggestions.
+ *
+ * Design posture:
+ *   - Defence layer, not a cypher correctness gate. Pass-through on any
+ *     unparseable pattern — Neo4j remains the syntax authority.
+ *   - Empty schema snapshot (cache not ready, or Neo4j unreachable at boot)
+ *     fails OPEN: ok=true, no rejections. The boot-race treatment is a
+ *     deliberate choice — refusing all cypher would wedge the admin agent
+ *     harder than the typo class this layer prevents. The caller emits
+ *     `validated=false` on the existing [graph-query] line so operators
+ *     still see the bypass.
+ *   - String literals are stripped before tokenisation to avoid matching
+ *     `:Foo` inside quoted content (e.g. `WHERE n.note CONTAINS ':Foo'`).
+ */
+
+export interface SchemaSnapshot {
+  readonly labels: ReadonlySet<string>;
+  readonly relationshipTypes: ReadonlySet<string>;
+}
+
+export interface UnknownToken {
+  token: string;
+  kind: "label" | "relationship";
+  nearest: string[];
+  hint: string;
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  unknown: UnknownToken[];
+  labelTokens: string[];
+  edgeTokens: string[];
+}
+
+// Bracket content containing a type reference. Examples this matches:
+//   [:PART_OF]
+//   [r:PART_OF]
+//   [:PART_OF*1..5]
+//   [r:PART_OF*]
+//   [:A|B]
+// The captured group is the TYPE(|TYPE)* alternation; the consumer splits it.
+const EDGE_PATTERN = /\[[^\]]*?:([A-Z_][A-Za-z0-9_]*(?:\|[A-Z_][A-Za-z0-9_]*)*)[^\]]*?\]/g;
+
+// Label reference in a node pattern. Applied to a remainder string that has
+// already had edge-bracket substrings stripped, so there is no overlap with
+// the edge pattern. The [A-Z] anchor excludes lowercase map keys.
+const LABEL_PATTERN = /:([A-Z][A-Za-z0-9_]*)/g;
+
+function stripStringLiterals(cypher: string): string {
+  // Replace single- and double-quoted literals with empty quotes. Preserves
+  // positional structure without retaining content that could match the
+  // label regex (e.g. ':SomeLabel' inside a string).
+  return cypher.replace(/'[^']*'|"[^"]*"/g, '""');
+}
+
+function extractTokens(cypher: string): { labels: Set<string>; edges: Set<string> } {
+  const cleaned = stripStringLiterals(cypher);
+  const edges = new Set<string>();
+  let match: RegExpExecArray | null;
+  const edgePattern = new RegExp(EDGE_PATTERN.source, EDGE_PATTERN.flags);
+  while ((match = edgePattern.exec(cleaned)) !== null) {
+    for (const type of match[1].split("|")) {
+      const clean = type.trim();
+      if (clean) edges.add(clean);
+    }
+  }
+  const remainder = cleaned.replace(edgePattern, "");
+  const labels = new Set<string>();
+  const labelPattern = new RegExp(LABEL_PATTERN.source, LABEL_PATTERN.flags);
+  while ((match = labelPattern.exec(remainder)) !== null) {
+    labels.add(match[1]);
+  }
+  return { labels, edges };
+}
+
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array<number>(b.length + 1);
+  let curr = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+function nearestMatches(
+  token: string,
+  known: ReadonlySet<string>,
+  limit = 3,
+): string[] {
+  if (known.size === 0) return [];
+  const scored: Array<[string, number]> = [];
+  for (const k of known) scored.push([k, levenshtein(token, k)]);
+  scored.sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0]));
+  return scored.slice(0, limit).map(([k]) => k);
+}
+
+function hintFor(
+  token: string,
+  kind: "label" | "relationship",
+  nearest: string[],
+): string {
+  const didYouMean = nearest.length > 0 ? `Did you mean :${nearest[0]}? ` : "";
+  return `${didYouMean}Unknown ${kind} '${token}' — not in the current Neo4j schema. See .docs/neo4j.md for the canonical taxonomy.`;
+}
+
+export function validate(
+  cypher: string,
+  snapshot: SchemaSnapshot,
+): ValidationResult {
+  const { labels, edges } = extractTokens(cypher);
+  // Fail-open when the snapshot is empty. An empty snapshot means "schema
+  // cache not loaded" (boot race, Neo4j unreachable). Rejecting every token
+  // would wedge the admin agent; letting it through preserves the observable
+  // `validated=false` signal on the existing [graph-query] line.
+  if (snapshot.labels.size === 0 && snapshot.relationshipTypes.size === 0) {
+    return {
+      ok: true,
+      unknown: [],
+      labelTokens: [...labels],
+      edgeTokens: [...edges],
+    };
+  }
+  const unknown: UnknownToken[] = [];
+  for (const token of labels) {
+    if (!snapshot.labels.has(token)) {
+      const nearest = nearestMatches(token, snapshot.labels);
+      unknown.push({ token, kind: "label", nearest, hint: hintFor(token, "label", nearest) });
+    }
+  }
+  for (const token of edges) {
+    if (!snapshot.relationshipTypes.has(token)) {
+      const nearest = nearestMatches(token, snapshot.relationshipTypes);
+      unknown.push({ token, kind: "relationship", nearest, hint: hintFor(token, "relationship", nearest) });
+    }
+  }
+  return {
+    ok: unknown.length === 0,
+    unknown,
+    labelTokens: [...labels],
+    edgeTokens: [...edges],
+  };
+}