Skip to content

Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.

fix(schema): scope design aliases by graph kind to keep knowledge normalization

Lum1104d09e0b525973
diff --git a/understand-anything-plugin/packages/core/src/__tests__/schema.test.ts b/understand-anything-plugin/packages/core/src/__tests__/schema.test.ts
index bb19279c..b57a6e5d 100644
--- a/understand-anything-plugin/packages/core/src/__tests__/schema.test.ts
+++ b/understand-anything-plugin/packages/core/src/__tests__/schema.test.ts
@@ -781,3 +781,56 @@ describe("design graph schema", () => {
expect(res.data!.edges.some((e) => e.target === "componentSet:7:8" && e.type === "variant_of")).toBe(true);
});
});
+
+// `page` and `instance_of` are canonical design types, but every other kind
+// relied on them normalizing to knowledge types (page → article, instance_of
+// → exemplifies) before the design kind existed. The alias tables are
+// kind-scoped so promoting them for design graphs doesn't regress the rest.
+describe("kind-aware alias normalization", () => {
+ function knowledgeGraph(kind?: string) {
+ return {
+ version: "1.0.0",
+ ...(kind ? { kind } : {}),
+ project: { name: "K", languages: ["markdown"], frameworks: [], description: "d", analyzedAt: "t", gitCommitHash: "" },
+ nodes: [
+ { id: "article:home", type: "page", name: "Home", summary: "s", tags: ["wiki"], complexity: "simple" },
+ { id: "entity:gpt", type: "entity", name: "GPT", summary: "s", tags: ["model"], complexity: "simple" },
+ { id: "topic:llm", type: "topic", name: "LLMs", summary: "s", tags: ["topic"], complexity: "simple" },
+ ],
+ edges: [
+ { source: "entity:gpt", target: "topic:llm", type: "instance_of", direction: "forward", weight: 0.7 },
+ ],
+ layers: [],
+ tour: [],
+ };
+ }
+
+ it('rewrites page → article and instance_of → exemplifies for kind:"knowledge"', () => {
+ const res = validateGraph(knowledgeGraph("knowledge"));
+ expect(res.success).toBe(true);
+ expect(res.data!.nodes.find((n) => n.id === "article:home")!.type).toBe("article");
+ expect(res.data!.edges[0].type).toBe("exemplifies");
+ });
+
+ it("rewrites page → article for graphs without a kind (pre-design behavior)", () => {
+ const res = validateGraph(knowledgeGraph());
+ expect(res.success).toBe(true);
+ expect(res.data!.nodes.find((n) => n.id === "article:home")!.type).toBe("article");
+ expect(res.data!.edges[0].type).toBe("exemplifies");
+ });
+
+ it('keeps page and instance_of first-class for kind:"design"', () => {
+ const g = designGraph();
+ g.nodes.push({ id: "page:1:0", type: "page", name: "Onboarding", summary: "s", tags: ["page"], complexity: "simple" });
+ const res = validateGraph(g);
+ expect(res.data!.nodes.find((n) => n.id === "page:1:0")!.type).toBe("page");
+ expect(res.data!.edges.find((x) => x.source === "instance:5:6")!.type).toBe("instance_of");
+ });
+
+ it('applies design aliases (styled_by → uses_token) only to design graphs', () => {
+ const g = designGraph();
+ g.edges.push({ source: "screen:1:2", target: "token:color:brand", type: "styled_by", direction: "forward", weight: 0.5 });
+ const res = validateGraph(g);
+ expect(res.data!.edges.some((e) => e.source === "screen:1:2" && e.type === "uses_token")).toBe(true);
+ });
+});
diff --git a/understand-anything-plugin/packages/core/src/schema.ts b/understand-anything-plugin/packages/core/src/schema.ts
index 90c2f48d..a4c308ae 100644
--- a/understand-anything-plugin/packages/core/src/schema.ts
+++ b/understand-anything-plugin/packages/core/src/schema.ts
@@ -1,6 +1,6 @@
import { z } from "zod";
-// Edge types (35 values across 8 categories)
+// Edge types (38 values across 9 categories)
export const EdgeTypeSchema = z.enum([
"imports", "exports", "contains", "inherits", "implements", // Structural
"calls", "subscribes", "publishes", "middleware", // Behavioral
@@ -72,9 +72,12 @@ export const NODE_TYPE_ALIASES: Record<string, string> = {
reference: "source",
raw: "source",
paper: "source",
- // Design aliases (Figma node types). NOTE: the former `page: "article"`
- // entry was removed — `page` is now a first-class design node type, so it
- // must not be rewritten (and `canvas: "page"` would otherwise chain).
+};
+
+// Design aliases (Figma node types) — applied only when the graph's kind is
+// "design". Terms like "page" and "style" mean something else in other
+// kinds, so these must not leak into them (see NON_DESIGN_NODE_TYPE_ALIASES).
+export const DESIGN_NODE_TYPE_ALIASES: Record<string, string> = {
frame: "screen",
artboard: "screen",
canvas: "page",
@@ -89,6 +92,14 @@ export const NODE_TYPE_ALIASES: Record<string, string> = {
style: "token",
};
+// Applied to every non-design kind: `page` is a first-class *design* node
+// type, but knowledge/codebase graphs relied on it normalizing to "article"
+// (see 2fc85e6) — the sanitizer can't tell a wiki page from a Figma page,
+// so the graph's `kind` decides which table wins.
+export const NON_DESIGN_NODE_TYPE_ALIASES: Record<string, string> = {
+ page: "article",
+};
+
// Aliases that LLMs commonly generate instead of canonical edge types
export const EDGE_TYPE_ALIASES: Record<string, string> = {
extends: "inherits",
@@ -133,16 +144,24 @@ export const EDGE_TYPE_ALIASES: Record<string, string> = {
tagged_with: "categorized_under",
written_by: "authored_by",
created_by: "authored_by",
- // Design aliases
+ // Note: "implemented_by" is intentionally NOT aliased to "implements" —
+ // it inverts edge direction (see commit fd0df15). The LLM should use
+ // "implements" with correct source/target instead.
+};
+
+// Design edge aliases — applied only when the graph's kind is "design".
+export const DESIGN_EDGE_TYPE_ALIASES: Record<string, string> = {
instantiates: "instance_of",
variant: "variant_of",
styled_by: "uses_token",
applies_token: "uses_token",
- // NOTE: the former `instance_of: "exemplifies"` entry is removed —
- // instance_of is now a first-class design edge.
- // Note: "implemented_by" is intentionally NOT aliased to "implements" —
- // it inverts edge direction (see commit fd0df15). The LLM should use
- // "implements" with correct source/target instead.
+};
+
+// Applied to every non-design kind: `instance_of` is a first-class design
+// edge, but knowledge graphs relied on it normalizing to "exemplifies"
+// ("X is an instance of Y" — see 2fc85e6).
+export const NON_DESIGN_EDGE_TYPE_ALIASES: Record<string, string> = {
+ instance_of: "exemplifies",
};
// Aliases for complexity values LLMs commonly generate
@@ -500,15 +519,25 @@ export function normalizeGraph(data: unknown): unknown {
const d = data as Record<string, unknown>;
const result = { ...d };
+ // "page" and "instance_of" are canonical design types but alias *sources*
+ // in every other kind, so the active alias tables depend on the graph's kind.
+ const isDesign = typeof d.kind === "string" && d.kind.toLowerCase() === "design";
+ const nodeAliases: Record<string, string> = isDesign
+ ? { ...NODE_TYPE_ALIASES, ...DESIGN_NODE_TYPE_ALIASES }
+ : { ...NODE_TYPE_ALIASES, ...NON_DESIGN_NODE_TYPE_ALIASES };
+ const edgeAliases: Record<string, string> = isDesign
+ ? { ...EDGE_TYPE_ALIASES, ...DESIGN_EDGE_TYPE_ALIASES }
+ : { ...EDGE_TYPE_ALIASES, ...NON_DESIGN_EDGE_TYPE_ALIASES };
+
if (Array.isArray(d.nodes)) {
result.nodes = (d.nodes as Array<Record<string, unknown>>).map((node) => {
if (
typeof node === "object" &&
node !== null &&
typeof node.type === "string" &&
- node.type in NODE_TYPE_ALIASES
+ node.type in nodeAliases
) {
- return { ...node, type: NODE_TYPE_ALIASES[node.type] };
+ return { ...node, type: nodeAliases[node.type] };
}
return node;
});
@@ -520,9 +549,9 @@ export function normalizeGraph(data: unknown): unknown {
typeof edge === "object" &&
edge !== null &&
typeof edge.type === "string" &&
- edge.type in EDGE_TYPE_ALIASES
+ edge.type in edgeAliases
) {
- return { ...edge, type: EDGE_TYPE_ALIASES[edge.type] };
+ return { ...edge, type: edgeAliases[edge.type] };
}
return edge;
});
diff --git a/understand-anything-plugin/packages/core/src/types.ts b/understand-anything-plugin/packages/core/src/types.ts
index 3e0ea731..53da7652 100644
--- a/understand-anything-plugin/packages/core/src/types.ts
+++ b/understand-anything-plugin/packages/core/src/types.ts
@@ -7,7 +7,7 @@ export type NodeType =
| "article" | "entity" | "topic" | "claim" | "source"
| "page" | "screen" | "component" | "componentSet" | "instance" | "token";
-// Edge types (35 total in 8 categories: Structural, Behavioral, Data flow, Dependencies, Semantic, Infrastructure/Schema, Domain, Knowledge)
+// Edge types (38 total in 9 categories: Structural, Behavioral, Data flow, Dependencies, Semantic, Infrastructure/Schema, Domain, Knowledge, Design)
export type EdgeType =
| "imports" | "exports" | "contains" | "inherits" | "implements" // Structural
| "calls" | "subscribes" | "publishes" | "middleware" // Behavioral
@@ -18,8 +18,7 @@ export type EdgeType =
| "migrates" | "documents" | "routes" | "defines_schema" // Schema/Data
| "contains_flow" | "flow_step" | "cross_domain" // Domain
| "cites" | "contradicts" | "builds_on" | "exemplifies" | "categorized_under" | "authored_by" // Knowledge
- // Design (3 new → 38 total)
- | "instance_of" | "variant_of" | "uses_token";
+ | "instance_of" | "variant_of" | "uses_token"; // Design
// Optional knowledge metadata for article/entity/topic/claim/source nodes
export interface KnowledgeMeta {