refactor: unify missing-component with 4-stage checks (#17)

docs/REFERENCE.md

@@ -125,10 +125,10 @@ Override score, severity, or enable/disable individual rules:
 |---------|--------------|-----------------|
 | `missing-component` | -7 | risk |
 | `detached-instance` | -5 | risk |
-| `nested-instance-override` | -3 | missing-info |
 | `variant-not-used` | -3 | suggestion |
 | `component-property-unused` | -2 | suggestion |
 | `single-use-component` | -2 | suggestion |
+| `missing-component-description` | -2 | missing-info |
 
 **Naming (5 rules)**
 

src/core/contracts/figma-node.ts

@@ -31,6 +31,7 @@ export const AnalysisNodeTypeSchema = z.enum([
   "LINK_UNFURL",
   "TABLE",
   "TABLE_CELL",
+  "SLOT",
 ]);
 
 export type AnalysisNodeType = z.infer<typeof AnalysisNodeTypeSchema>;

src/core/contracts/rule.ts

@@ -95,15 +95,13 @@ export type RuleId =
   | "raw-shadow"
   | "raw-opacity"
   | "multiple-fill-colors"
-  // Component (8)
+  // Component (6)
   | "missing-component"
   | "detached-instance"
-  | "nested-instance-override"
   | "variant-not-used"
   | "component-property-unused"
   | "single-use-component"
   | "missing-component-description"
-  | "repeated-frame-structure"
   // Naming (5)
   | "default-name"
   | "non-semantic-name"

src/core/engine/design-tree.test.ts

@@ -64,6 +64,67 @@ describe("generateDesignTree", () => {
     });
   });
 
+  describe("INSTANCE component annotation", () => {
+    it("annotates INSTANCE nodes with component name when available", () => {
+      const file = makeFile(
+        makeNode({
+          id: "1:1",
+          name: "Container",
+          type: "FRAME",
+          absoluteBoundingBox: { x: 0, y: 0, width: 200, height: 200 },
+          children: [
+            makeNode({
+              id: "1:2",
+              name: "MyButton",
+              type: "INSTANCE",
+              componentId: "comp:1",
+              absoluteBoundingBox: { x: 0, y: 0, width: 120, height: 40 },
+            }),
+          ],
+        })
+      );
+      file.components = {
+        "comp:1": { key: "abc", name: "Button", description: "" },
+      };
+
+      const output = generateDesignTree(file);
+
+      expect(output).toContain("MyButton (INSTANCE, 120x40) [component: Button]");
+    });
+
+    it("does not annotate INSTANCE when componentId has no match", () => {
+      const file = makeFile(
+        makeNode({
+          id: "1:1",
+          name: "MyButton",
+          type: "INSTANCE",
+          componentId: "comp:999",
+          absoluteBoundingBox: { x: 0, y: 0, width: 120, height: 40 },
+        })
+      );
+
+      const output = generateDesignTree(file);
+
+      expect(output).toContain("MyButton (INSTANCE, 120x40)");
+      expect(output).not.toContain("[component:");
+    });
+
+    it("does not annotate non-INSTANCE nodes", () => {
+      const file = makeFile(
+        makeNode({
+          id: "1:1",
+          name: "Card",
+          type: "FRAME",
+          absoluteBoundingBox: { x: 0, y: 0, width: 200, height: 200 },
+        })
+      );
+
+      const output = generateDesignTree(file);
+
+      expect(output).not.toContain("[component:");
+    });
+  });
+
   describe("TEXT nodes", () => {
     it("TEXT nodes use color: not background: for fill", () => {
       const file = makeFile(

src/core/engine/design-tree.ts

@@ -95,17 +95,29 @@ function mapAlign(figmaAlign: string): string {
 }
 
 /** Render a single node and its children as indented design-tree text. */
-function renderNode(node: AnalysisNode, indent: number, vectorDir?: string): string {
+function renderNode(
+  node: AnalysisNode,
+  indent: number,
+  vectorDir?: string,
+  components?: AnalysisFile["components"],
+): string {
   if (node.visible === false) return "";
 
   const prefix = "  ".repeat(indent);
   const lines: string[] = [];
 
-  // Header
+  // Header — annotate INSTANCE nodes with component name
   const bbox = node.absoluteBoundingBox;
   const w = bbox ? Math.round(bbox.width) : "?";
   const h = bbox ? Math.round(bbox.height) : "?";
-  lines.push(`${prefix}${node.name} (${node.type}, ${w}x${h})`);
+  let header = `${prefix}${node.name} (${node.type}, ${w}x${h})`;
+  if (node.type === "INSTANCE" && node.componentId && components) {
+    const comp = components[node.componentId];
+    if (comp) {
+      header += ` [component: ${comp.name}]`;
+    }
+  }
+  lines.push(header);
 
   // Styles
   const styles: string[] = [];
@@ -206,7 +218,7 @@ function renderNode(node: AnalysisNode, indent: number, vectorDir?: string): str
   // Children
   if (node.children) {
     for (const child of node.children) {
-      const childOutput = renderNode(child, indent + 1, vectorDir);
+      const childOutput = renderNode(child, indent + 1, vectorDir, components);
       if (childOutput) lines.push(childOutput);
     }
   }
@@ -227,7 +239,7 @@ export function generateDesignTree(file: AnalysisFile, options?: DesignTreeOptio
   const w = root.absoluteBoundingBox ? Math.round(root.absoluteBoundingBox.width) : 0;
   const h = root.absoluteBoundingBox ? Math.round(root.absoluteBoundingBox.height) : 0;
 
-  const tree = renderNode(root, 0, options?.vectorDir);
+  const tree = renderNode(root, 0, options?.vectorDir, file.components);
 
   return [
     "# Design Tree",

src/core/engine/rule-engine.ts

@@ -9,6 +9,7 @@ import type {
 import { supportsDepthWeight } from "../contracts/rule.js";
 import { ruleRegistry } from "../rules/rule-registry.js";
 import { RULE_CONFIGS } from "../rules/rule-config.js";
+import { resetMissingComponentState } from "../rules/component/index.js";
 
 /**
  * Analysis issue with calculated score and metadata
@@ -145,6 +146,9 @@ export class RuleEngine {
    * Analyze a Figma file and return issues
    */
   analyze(file: AnalysisFile): AnalysisResult {
+    // Reset module-level dedup state for rules that track seen patterns
+    resetMissingComponentState();
+
     // Find target node if specified
     let rootNode = file.document;
     if (this.targetNodeId) {