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.
TypeScript antigravity-skillsbusiness-knowledgeclaude-codeclaude-skillscodebase-analysiscodexcodex-skillsdeveloper-tools-ai-agentgemini-cli-skillskarpathy-llm-wikiknowledge-baseknowledge-graphmemoryopencode-skillspi-agentunderstandcodevibe-coding
feat(core): merge Figma manifest + analysis into kind:design graph with layers/tour
gruminge1fd0c9ae74c
diff --git a/understand-anything-plugin/packages/core/src/figma/__tests__/merge.test.ts b/understand-anything-plugin/packages/core/src/figma/__tests__/merge.test.tsnew file mode 100644index 00000000..bbed2581--- /dev/null+++ b/understand-anything-plugin/packages/core/src/figma/__tests__/merge.test.ts@@ -0,0 +1,42 @@+import { describe, it, expect } from "vitest";+import { mergeDesignGraph } from "../merge";+import type { GraphNode, GraphEdge, ProjectMeta } from "../../types";++const project: ProjectMeta = { name: "MyApp", languages: ["figma"], frameworks: [], description: "d", analyzedAt: "t", gitCommitHash: "" };+const manifest = {+ nodes: [+ { id: "page:1:0", type: "page", name: "Onboarding", summary: "Onboarding", tags: ["page"], complexity: "simple" },+ { id: "screen:1:1", type: "screen", name: "Login", summary: "Login", tags: ["screen"], complexity: "simple" },+ { id: "component:2:1", type: "component", name: "Primary", summary: "Primary", tags: ["component"], complexity: "simple" },+ { id: "token:color:brand", type: "token", name: "brand", summary: "brand", tags: ["token"], complexity: "simple" },+ ] as GraphNode[],+ edges: [+ { source: "page:1:0", target: "screen:1:1", type: "contains", direction: "forward", weight: 1 },+ { source: "component:2:1", target: "token:color:brand", type: "uses_token", direction: "forward", weight: 0.5 },+ ] as GraphEdge[],+};++describe("mergeDesignGraph", () => {+ it("produces a valid kind:design graph", () => {+ const res = mergeDesignGraph(manifest, [], project);+ expect(res.success).toBe(true);+ expect(res.data!.kind).toBe("design");+ });+ it("groups screens under their page layer and DS nodes under Design System", () => {+ const { data } = mergeDesignGraph(manifest, [], project);+ const ds = data!.layers.find((l) => l.id === "layer:design-system")!;+ expect(ds.nodeIds).toEqual(expect.arrayContaining(["component:2:1", "token:color:brand"]));+ const page = data!.layers.find((l) => l.name === "Onboarding")!;+ expect(page.nodeIds).toEqual(expect.arrayContaining(["page:1:0", "screen:1:1"]));+ });+ it("applies design-analyzer enrichment by id", () => {+ const { data } = mergeDesignGraph(manifest, [{ nodes: [{ id: "screen:1:1", summary: "The sign-in screen", tags: ["auth", "entry"] }] }], project);+ const screen = data!.nodes.find((n) => n.id === "screen:1:1")!;+ expect(screen.summary).toBe("The sign-in screen");+ expect(screen.tags).toEqual(["auth", "entry"]);+ });+ it("builds a tour that starts with the Design System", () => {+ const { data } = mergeDesignGraph(manifest, [], project);+ expect(data!.tour[0].title).toBe("Design System");+ });+});diff --git a/understand-anything-plugin/packages/core/src/figma/merge.ts b/understand-anything-plugin/packages/core/src/figma/merge.tsnew file mode 100644index 00000000..756a5b97--- /dev/null+++ b/understand-anything-plugin/packages/core/src/figma/merge.ts@@ -0,0 +1,84 @@+import type { KnowledgeGraph, GraphNode, GraphEdge, Layer, TourStep, ProjectMeta } from "../types.js";+import { validateGraph, type ValidationResult } from "../schema.js";++export interface DesignAnalysis {+ nodes?: Array<Pick<GraphNode, "id"> & Partial<Pick<GraphNode, "summary" | "tags">>>;+ edges?: GraphEdge[];+}++const DS_TYPES = new Set<GraphNode["type"]>(["component", "componentSet", "token"]);++export function mergeDesignGraph(+ manifest: { nodes: GraphNode[]; edges: GraphEdge[] },+ analyses: DesignAnalysis[],+ project: ProjectMeta,+): ValidationResult {+ // 1. index manifest nodes (clone so we can enrich)+ const byId = new Map<string, GraphNode>();+ for (const n of manifest.nodes) byId.set(n.id, { ...n });+ const edges: GraphEdge[] = [...manifest.edges];++ // 2. apply LLM enrichment; design-analyzer must not invent structural nodes+ for (const a of analyses) {+ for (const patch of a.nodes ?? []) {+ const base = byId.get(patch.id);+ if (!base) continue;+ if (patch.summary) base.summary = patch.summary;+ if (patch.tags && patch.tags.length) base.tags = patch.tags;+ }+ for (const e of a.edges ?? []) edges.push(e);+ }+ const nodes = [...byId.values()];++ // 3. layers: one per page (+ descendants), plus a Design System layer+ const parent = new Map<string, string>();+ for (const e of manifest.edges) if (e.type === "contains") parent.set(e.target, e.source);+ const pageOf = (id: string): string | undefined => {+ let cur: string | undefined = id;+ const guard = new Set<string>();+ while (cur && !guard.has(cur)) {+ guard.add(cur);+ if (byId.get(cur)?.type === "page") return cur;+ cur = parent.get(cur);+ }+ return undefined;+ };+ const layerMap = new Map<string, string[]>();+ const ds: string[] = [];+ for (const n of nodes) {+ if (DS_TYPES.has(n.type)) { ds.push(n.id); continue; }+ const key = n.type === "page" ? n.id : (pageOf(n.id) ?? "layer:unscoped");+ if (!layerMap.has(key)) layerMap.set(key, []);+ layerMap.get(key)!.push(n.id);+ }+ const layers: Layer[] = [];+ for (const [pageId, ids] of layerMap) {+ const pageNode = byId.get(pageId);+ layers.push({+ id: `layer:${pageId}`,+ name: pageNode?.name ?? "Unscoped",+ description: pageNode ? `Figma page: ${pageNode.name}` : "Nodes not under a page",+ nodeIds: ids,+ });+ }+ if (ds.length) {+ layers.push({ id: "layer:design-system", name: "Design System", description: "Components, variants, and design tokens", nodeIds: ds });+ }++ // 4. tour: Design System first, then each page+ const tour: TourStep[] = [];+ let order = 1;+ if (ds.length) tour.push({ order: order++, title: "Design System", description: "Shared components, variants, and tokens the screens are built from.", nodeIds: ds.slice(0, 8) });+ for (const l of layers) {+ if (l.id === "layer:design-system") continue;+ tour.push({ order: order++, title: l.name, description: `Screens on the "${l.name}" page.`, nodeIds: l.nodeIds.slice(0, 8) });+ }++ // 5. assemble + validate, then re-attach kind (validateGraph drops it)+ const graph: KnowledgeGraph = { version: "1.0.0", kind: "design", project, nodes, edges, layers, tour };+ const result = validateGraph(graph);+ if (result.success && result.data) {+ (result.data as KnowledgeGraph).kind = "design";+ }+ return result;+}