canicode 0.3.0

package/dist/cli/index.js

@@ -0,0 +1,4399 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { writeFile, readFile, appendFile } from 'fs/promises';
+import { join, resolve, dirname, basename } from 'path';
+import { config } from 'dotenv';
+import cac from 'cac';
+import { z } from 'zod';
+import { homedir } from 'os';
+
+z.object({
+  fileKey: z.string(),
+  nodeId: z.string().optional(),
+  fileName: z.string().optional()
+});
+var FIGMA_URL_PATTERNS = [
+  // https://www.figma.com/design/FILE_KEY/FILE_NAME?node-id=NODE_ID
+  /figma\.com\/design\/([a-zA-Z0-9]+)(?:\/([^?]+))?(?:\?.*node-id=([^&]+))?/,
+  // https://www.figma.com/file/FILE_KEY/FILE_NAME?node-id=NODE_ID
+  /figma\.com\/file\/([a-zA-Z0-9]+)(?:\/([^?]+))?(?:\?.*node-id=([^&]+))?/,
+  // https://www.figma.com/proto/FILE_KEY/FILE_NAME?node-id=NODE_ID
+  /figma\.com\/proto\/([a-zA-Z0-9]+)(?:\/([^?]+))?(?:\?.*node-id=([^&]+))?/
+];
+function parseFigmaUrl(url) {
+  for (const pattern of FIGMA_URL_PATTERNS) {
+    const match = url.match(pattern);
+    if (match) {
+      const [, fileKey, fileName, nodeId] = match;
+      if (!fileKey) {
+        throw new FigmaUrlParseError(`Invalid Figma URL: missing file key`);
+      }
+      return {
+        fileKey,
+        fileName: fileName ? decodeURIComponent(fileName) : void 0,
+        nodeId: nodeId ? decodeURIComponent(nodeId) : void 0
+      };
+    }
+  }
+  throw new FigmaUrlParseError(
+    `Invalid Figma URL format. Expected: https://www.figma.com/design/FILE_KEY/...`
+  );
+}
+var FigmaUrlParseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FigmaUrlParseError";
+  }
+};
+function buildFigmaDeepLink(fileKey, nodeId) {
+  return `https://www.figma.com/design/${fileKey}?node-id=${encodeURIComponent(nodeId)}`;
+}
+var CategorySchema = z.enum([
+  "layout",
+  "token",
+  "component",
+  "naming",
+  "ai-readability",
+  "handoff-risk"
+]);
+var CATEGORIES = CategorySchema.options;
+var CATEGORY_LABELS = {
+  layout: "Layout",
+  token: "Design Token",
+  component: "Component",
+  naming: "Naming",
+  "ai-readability": "AI Readability",
+  "handoff-risk": "Handoff Risk"
+};
+var SeveritySchema = z.enum([
+  "blocking",
+  "risk",
+  "missing-info",
+  "suggestion"
+]);
+var SEVERITY_LABELS = {
+  blocking: "Blocking",
+  risk: "Risk",
+  "missing-info": "Missing Info",
+  suggestion: "Suggestion"
+};
+
+// src/contracts/rule.ts
+z.object({
+  id: z.string(),
+  name: z.string(),
+  category: CategorySchema,
+  why: z.string(),
+  impact: z.string(),
+  fix: z.string()
+});
+z.object({
+  severity: SeveritySchema,
+  score: z.number().int().max(0),
+  depthWeight: z.number().min(1).max(2).optional(),
+  enabled: z.boolean().default(true),
+  options: z.record(z.string(), z.unknown()).optional()
+});
+var DEPTH_WEIGHT_CATEGORIES = ["layout", "handoff-risk"];
+function supportsDepthWeight(category) {
+  return DEPTH_WEIGHT_CATEGORIES.includes(category);
+}
+
+// src/rules/rule-config.ts
+var RULE_CONFIGS = {
+  // ============================================
+  // Layout (11 rules)
+  // ============================================
+  "no-auto-layout": {
+    severity: "blocking",
+    score: -7,
+    depthWeight: 1.5,
+    enabled: true
+  },
+  "absolute-position-in-auto-layout": {
+    severity: "blocking",
+    score: -10,
+    depthWeight: 1.3,
+    enabled: true
+  },
+  "fixed-width-in-responsive-context": {
+    severity: "risk",
+    score: -4,
+    depthWeight: 1.3,
+    enabled: true
+  },
+  "missing-responsive-behavior": {
+    severity: "risk",
+    score: -4,
+    depthWeight: 1.5,
+    enabled: true
+  },
+  "group-usage": {
+    severity: "risk",
+    score: -5,
+    depthWeight: 1.2,
+    enabled: true
+  },
+  "fixed-size-in-auto-layout": {
+    severity: "risk",
+    score: -5,
+    enabled: true
+  },
+  "missing-min-width": {
+    severity: "risk",
+    score: -5,
+    enabled: true
+  },
+  "missing-max-width": {
+    severity: "risk",
+    score: -4,
+    enabled: true
+  },
+  "deep-nesting": {
+    severity: "risk",
+    score: -4,
+    enabled: true,
+    options: {
+      maxDepth: 5
+    }
+  },
+  "overflow-hidden-abuse": {
+    severity: "missing-info",
+    score: -3,
+    enabled: true
+  },
+  "inconsistent-sibling-layout-direction": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
+  // ============================================
+  // Token (7 rules)
+  // ============================================
+  "raw-color": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
+  "raw-font": {
+    severity: "blocking",
+    score: -8,
+    enabled: true
+  },
+  "inconsistent-spacing": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true,
+    options: {
+      gridBase: 8
+    }
+  },
+  "magic-number-spacing": {
+    severity: "risk",
+    score: -4,
+    enabled: true,
+    options: {
+      gridBase: 8
+    }
+  },
+  "raw-shadow": {
+    severity: "missing-info",
+    score: -3,
+    enabled: true
+  },
+  "raw-opacity": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
+  "multiple-fill-colors": {
+    severity: "missing-info",
+    score: -3,
+    enabled: true,
+    options: {
+      tolerance: 10
+    }
+  },
+  // ============================================
+  // Component (6 rules)
+  // ============================================
+  "missing-component": {
+    severity: "risk",
+    score: -7,
+    enabled: true,
+    options: {
+      minRepetitions: 3
+    }
+  },
+  "detached-instance": {
+    severity: "risk",
+    score: -5,
+    enabled: true
+  },
+  "nested-instance-override": {
+    severity: "risk",
+    score: -5,
+    enabled: true
+  },
+  "variant-not-used": {
+    severity: "missing-info",
+    score: -3,
+    enabled: true
+  },
+  "component-property-unused": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
+  "single-use-component": {
+    severity: "suggestion",
+    score: -1,
+    enabled: true
+  },
+  // ============================================
+  // Naming (5 rules)
+  // ============================================
+  "default-name": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
+  "non-semantic-name": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
+  "inconsistent-naming-convention": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
+  "numeric-suffix-name": {
+    severity: "suggestion",
+    score: -1,
+    enabled: true
+  },
+  "too-long-name": {
+    severity: "suggestion",
+    score: -1,
+    enabled: true,
+    options: {
+      maxLength: 50
+    }
+  },
+  // ============================================
+  // AI Readability (5 rules)
+  // ============================================
+  "ambiguous-structure": {
+    severity: "blocking",
+    score: -10,
+    depthWeight: 1.3,
+    enabled: true
+  },
+  "z-index-dependent-layout": {
+    severity: "risk",
+    score: -5,
+    depthWeight: 1.3,
+    enabled: true
+  },
+  "missing-layout-hint": {
+    severity: "risk",
+    score: -5,
+    enabled: true
+  },
+  "invisible-layer": {
+    severity: "blocking",
+    score: -10,
+    enabled: true
+  },
+  "empty-frame": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
+  // ============================================
+  // Handoff Risk (5 rules)
+  // ============================================
+  "hardcode-risk": {
+    severity: "risk",
+    score: -5,
+    depthWeight: 1.5,
+    enabled: true
+  },
+  "text-truncation-unhandled": {
+    severity: "risk",
+    score: -5,
+    enabled: true
+  },
+  "image-no-placeholder": {
+    severity: "missing-info",
+    score: -3,
+    enabled: true
+  },
+  "prototype-link-in-design": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
+  "no-dev-status": {
+    severity: "missing-info",
+    score: -2,
+    enabled: false
+    // Disabled by default
+  }
+};
+function getConfigsWithPreset(preset) {
+  const configs = { ...RULE_CONFIGS };
+  switch (preset) {
+    case "relaxed":
+      for (const [id, config2] of Object.entries(configs)) {
+        if (config2.severity === "blocking") {
+          configs[id] = {
+            ...config2,
+            severity: "risk",
+            score: Math.round(config2.score * 0.5)
+          };
+        }
+      }
+      break;
+    case "dev-friendly":
+      for (const [id, config2] of Object.entries(configs)) {
+        const ruleId = id;
+        if (!ruleId.includes("layout") && !ruleId.includes("handoff") && !ruleId.includes("responsive")) {
+          configs[ruleId] = { ...config2, enabled: false };
+        }
+      }
+      break;
+    case "ai-ready":
+      for (const [id, config2] of Object.entries(configs)) {
+        const ruleId = id;
+        if (ruleId.includes("ambiguous") || ruleId.includes("structure") || ruleId.includes("name")) {
+          configs[ruleId] = {
+            ...config2,
+            score: Math.round(config2.score * 1.5)
+          };
+        }
+      }
+      break;
+    case "strict":
+      for (const [id, config2] of Object.entries(configs)) {
+        configs[id] = {
+          ...config2,
+          enabled: true,
+          score: Math.round(config2.score * 1.5)
+        };
+      }
+      break;
+  }
+  return configs;
+}
+function getRuleOption(ruleId, optionKey, defaultValue) {
+  const config2 = RULE_CONFIGS[ruleId];
+  if (!config2.options) return defaultValue;
+  const value = config2.options[optionKey];
+  return value ?? defaultValue;
+}
+
+// src/rules/rule-registry.ts
+var RuleRegistry = class {
+  rules = /* @__PURE__ */ new Map();
+  /**
+   * Register a rule
+   */
+  register(rule) {
+    this.rules.set(rule.definition.id, rule);
+  }
+  /**
+   * Get a rule by ID
+   */
+  get(id) {
+    return this.rules.get(id);
+  }
+  /**
+   * Get all registered rules
+   */
+  getAll() {
+    return Array.from(this.rules.values());
+  }
+  /**
+   * Get rules by category
+   */
+  getByCategory(category) {
+    return this.getAll().filter((rule) => rule.definition.category === category);
+  }
+  /**
+   * Get enabled rules with their configs
+   */
+  getEnabled(configs = RULE_CONFIGS) {
+    return this.getAll().filter((rule) => {
+      const config2 = configs[rule.definition.id];
+      return config2?.enabled ?? true;
+    });
+  }
+  /**
+   * Get config for a rule
+   */
+  getConfig(id, configs = RULE_CONFIGS) {
+    return configs[id];
+  }
+  /**
+   * Check if a rule is registered
+   */
+  has(id) {
+    return this.rules.has(id);
+  }
+  /**
+   * Get count of registered rules
+   */
+  get size() {
+    return this.rules.size;
+  }
+};
+var ruleRegistry = new RuleRegistry();
+function defineRule(rule) {
+  ruleRegistry.register(rule);
+  return rule;
+}
+
+// src/core/rule-engine.ts
+function calculateMaxDepth(node, currentDepth = 0) {
+  if (!node.children || node.children.length === 0) {
+    return currentDepth;
+  }
+  let maxChildDepth = currentDepth;
+  for (const child of node.children) {
+    const childDepth = calculateMaxDepth(child, currentDepth + 1);
+    if (childDepth > maxChildDepth) {
+      maxChildDepth = childDepth;
+    }
+  }
+  return maxChildDepth;
+}
+function countNodes(node) {
+  let count = 1;
+  if (node.children) {
+    for (const child of node.children) {
+      count += countNodes(child);
+    }
+  }
+  return count;
+}
+function findNodeById(node, nodeId) {
+  const normalizedId = nodeId.replace(/-/g, ":");
+  if (node.id === normalizedId) {
+    return node;
+  }
+  if (node.children) {
+    for (const child of node.children) {
+      const found = findNodeById(child, nodeId);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+function calcDepthWeight(depth, maxDepth, depthWeight) {
+  if (!depthWeight || depthWeight <= 1) return 1;
+  if (maxDepth === 0) return depthWeight;
+  const ratio = depth / maxDepth;
+  return depthWeight - (depthWeight - 1) * ratio;
+}
+var RuleEngine = class {
+  configs;
+  enabledRuleIds;
+  disabledRuleIds;
+  targetNodeId;
+  constructor(options = {}) {
+    this.configs = options.configs ?? RULE_CONFIGS;
+    this.enabledRuleIds = options.enabledRules ? new Set(options.enabledRules) : null;
+    this.disabledRuleIds = new Set(options.disabledRules ?? []);
+    this.targetNodeId = options.targetNodeId;
+  }
+  /**
+   * Analyze a Figma file and return issues
+   */
+  analyze(file) {
+    let rootNode = file.document;
+    if (this.targetNodeId) {
+      const targetNode = findNodeById(file.document, this.targetNodeId);
+      if (!targetNode) {
+        throw new Error(`Node not found: ${this.targetNodeId}`);
+      }
+      rootNode = targetNode;
+    }
+    const maxDepth = calculateMaxDepth(rootNode);
+    const nodeCount = countNodes(rootNode);
+    const issues = [];
+    const enabledRules = this.getEnabledRules();
+    this.traverseAndCheck(
+      rootNode,
+      file,
+      enabledRules,
+      maxDepth,
+      issues,
+      0,
+      [],
+      void 0,
+      void 0
+    );
+    return {
+      file,
+      issues,
+      maxDepth,
+      nodeCount,
+      analyzedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Get rules that should be run based on configuration
+   */
+  getEnabledRules() {
+    return ruleRegistry.getAll().filter((rule) => {
+      const ruleId = rule.definition.id;
+      if (this.disabledRuleIds.has(ruleId)) return false;
+      if (this.enabledRuleIds && !this.enabledRuleIds.has(ruleId)) return false;
+      const config2 = this.configs[ruleId];
+      return config2?.enabled ?? true;
+    });
+  }
+  /**
+   * Recursively traverse the tree and run rules
+   */
+  traverseAndCheck(node, file, rules, maxDepth, issues, depth, path, parent, siblings) {
+    const nodePath = [...path, node.name];
+    const context = {
+      file,
+      parent,
+      depth,
+      maxDepth,
+      path: nodePath,
+      siblings
+    };
+    for (const rule of rules) {
+      const ruleId = rule.definition.id;
+      const config2 = this.configs[ruleId];
+      const options = config2?.options;
+      try {
+        const violation = rule.check(node, context, options);
+        if (violation) {
+          let calculatedScore = config2.score;
+          if (supportsDepthWeight(rule.definition.category) && config2.depthWeight) {
+            const weight = calcDepthWeight(depth, maxDepth, config2.depthWeight);
+            calculatedScore = Math.round(config2.score * weight);
+          }
+          issues.push({
+            violation,
+            rule,
+            config: config2,
+            depth,
+            maxDepth,
+            calculatedScore
+          });
+        }
+      } catch (error) {
+        console.error(`Rule "${ruleId}" threw error on node "${node.name}":`, error);
+      }
+    }
+    if (node.children && node.children.length > 0) {
+      for (const child of node.children) {
+        this.traverseAndCheck(
+          child,
+          file,
+          rules,
+          maxDepth,
+          issues,
+          depth + 1,
+          nodePath,
+          node,
+          node.children
+        );
+      }
+    }
+  }
+};
+function createRuleEngine(options) {
+  return new RuleEngine(options);
+}
+function analyzeFile(file, options) {
+  const engine = createRuleEngine(options);
+  return engine.analyze(file);
+}
+
+// src/adapters/figma-client.ts
+var FIGMA_API_BASE = "https://api.figma.com/v1";
+var FigmaClient = class _FigmaClient {
+  token;
+  constructor(options) {
+    this.token = options.token;
+  }
+  static fromEnv() {
+    const token = process.env["FIGMA_TOKEN"];
+    if (!token) {
+      throw new FigmaClientError(
+        "FIGMA_TOKEN environment variable is not set"
+      );
+    }
+    return new _FigmaClient({ token });
+  }
+  async getFile(fileKey) {
+    const url = `${FIGMA_API_BASE}/files/${fileKey}`;
+    const response = await fetch(url, {
+      headers: {
+        "X-Figma-Token": this.token
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new FigmaClientError(
+        `Failed to fetch file: ${response.status} ${response.statusText}`,
+        response.status,
+        error
+      );
+    }
+    return response.json();
+  }
+  /**
+   * Get rendered images for specific nodes
+   * Returns a map of nodeId → image URL
+   */
+  async getNodeImages(fileKey, nodeIds, options) {
+    const format = options?.format ?? "png";
+    const scale = options?.scale ?? 2;
+    const BATCH_SIZE = 50;
+    const allImages = {};
+    for (let i = 0; i < nodeIds.length; i += BATCH_SIZE) {
+      const batch = nodeIds.slice(i, i + BATCH_SIZE);
+      const ids = batch.join(",");
+      const url = `${FIGMA_API_BASE}/images/${fileKey}?ids=${encodeURIComponent(ids)}&format=${format}&scale=${scale}`;
+      const response = await fetch(url, {
+        headers: {
+          "X-Figma-Token": this.token
+        }
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw new FigmaClientError(
+          `Failed to fetch images: ${response.status} ${response.statusText}`,
+          response.status,
+          error
+        );
+      }
+      const data = await response.json();
+      for (const [nodeId, imageUrl] of Object.entries(data.images)) {
+        allImages[nodeId] = imageUrl;
+      }
+    }
+    return allImages;
+  }
+  /**
+   * Download an image URL and return as base64
+   */
+  async fetchImageAsBase64(imageUrl) {
+    const response = await fetch(imageUrl);
+    if (!response.ok) {
+      throw new FigmaClientError(
+        `Failed to download image: ${response.status}`,
+        response.status
+      );
+    }
+    const buffer = await response.arrayBuffer();
+    return Buffer.from(buffer).toString("base64");
+  }
+  async getFileNodes(fileKey, nodeIds) {
+    const ids = nodeIds.join(",");
+    const url = `${FIGMA_API_BASE}/files/${fileKey}/nodes?ids=${encodeURIComponent(ids)}`;
+    const response = await fetch(url, {
+      headers: {
+        "X-Figma-Token": this.token
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new FigmaClientError(
+        `Failed to fetch nodes: ${response.status} ${response.statusText}`,
+        response.status,
+        error
+      );
+    }
+    return response.json();
+  }
+};
+var FigmaClientError = class extends Error {
+  constructor(message, statusCode, responseBody) {
+    super(message);
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.name = "FigmaClientError";
+  }
+};
+
+// src/adapters/figma-transformer.ts
+function transformFigmaResponse(fileKey, response) {
+  return {
+    fileKey,
+    name: response.name,
+    lastModified: response.lastModified,
+    version: response.version,
+    document: transformNode(response.document),
+    components: transformComponents(response.components),
+    styles: transformStyles(response.styles)
+  };
+}
+function transformNode(node) {
+  const base = {
+    id: node.id,
+    name: node.name,
+    type: node.type,
+    visible: "visible" in node ? node.visible ?? true : true
+  };
+  if ("layoutMode" in node && node.layoutMode) {
+    base.layoutMode = node.layoutMode;
+  }
+  if ("layoutAlign" in node && node.layoutAlign) {
+    base.layoutAlign = node.layoutAlign;
+  }
+  if ("layoutPositioning" in node && node.layoutPositioning) {
+    base.layoutPositioning = node.layoutPositioning;
+  }
+  if ("primaryAxisAlignItems" in node) {
+    base.primaryAxisAlignItems = node.primaryAxisAlignItems;
+  }
+  if ("counterAxisAlignItems" in node) {
+    base.counterAxisAlignItems = node.counterAxisAlignItems;
+  }
+  if ("itemSpacing" in node) {
+    base.itemSpacing = node.itemSpacing;
+  }
+  if ("paddingLeft" in node) {
+    base.paddingLeft = node.paddingLeft;
+  }
+  if ("paddingRight" in node) {
+    base.paddingRight = node.paddingRight;
+  }
+  if ("paddingTop" in node) {
+    base.paddingTop = node.paddingTop;
+  }
+  if ("paddingBottom" in node) {
+    base.paddingBottom = node.paddingBottom;
+  }
+  if ("absoluteBoundingBox" in node && node.absoluteBoundingBox) {
+    base.absoluteBoundingBox = node.absoluteBoundingBox;
+  }
+  if ("componentId" in node) {
+    base.componentId = node.componentId;
+  }
+  if ("componentPropertyDefinitions" in node) {
+    base.componentPropertyDefinitions = node.componentPropertyDefinitions;
+  }
+  if ("componentProperties" in node) {
+    base.componentProperties = node.componentProperties;
+  }
+  if ("styles" in node) {
+    base.styles = node.styles;
+  }
+  if ("fills" in node) {
+    base.fills = node.fills;
+  }
+  if ("strokes" in node) {
+    base.strokes = node.strokes;
+  }
+  if ("effects" in node) {
+    base.effects = node.effects;
+  }
+  if ("boundVariables" in node && node.boundVariables) {
+    base.boundVariables = node.boundVariables;
+  }
+  if ("characters" in node) {
+    base.characters = node.characters;
+  }
+  if ("style" in node) {
+    base.style = node.style;
+  }
+  if ("devStatus" in node && node.devStatus) {
+    base.devStatus = node.devStatus;
+  }
+  if ("children" in node && Array.isArray(node.children)) {
+    base.children = node.children.map(transformNode);
+  }
+  return base;
+}
+function transformComponents(components) {
+  const result = {};
+  for (const [id, component] of Object.entries(components)) {
+    result[id] = {
+      key: component.key,
+      name: component.name,
+      description: component.description
+    };
+  }
+  return result;
+}
+function transformStyles(styles) {
+  const result = {};
+  for (const [id, style] of Object.entries(styles)) {
+    result[id] = {
+      key: style.key,
+      name: style.name,
+      styleType: style.styleType
+    };
+  }
+  return result;
+}
+
+// src/adapters/figma-file-loader.ts
+async function loadFigmaFileFromJson(filePath) {
+  const content = await readFile(filePath, "utf-8");
+  const data = JSON.parse(content);
+  const fileKey = basename(filePath, ".json");
+  return transformFigmaResponse(fileKey, data);
+}
+
+// src/adapters/figma-mcp-adapter.ts
+var TAG_TYPE_MAP = {
+  canvas: "CANVAS",
+  frame: "FRAME",
+  group: "GROUP",
+  section: "SECTION",
+  component: "COMPONENT",
+  "component-set": "COMPONENT_SET",
+  instance: "INSTANCE",
+  rectangle: "RECTANGLE",
+  "rounded-rectangle": "RECTANGLE",
+  ellipse: "ELLIPSE",
+  vector: "VECTOR",
+  text: "TEXT",
+  line: "LINE",
+  "boolean-operation": "BOOLEAN_OPERATION",
+  star: "STAR",
+  "regular-polygon": "REGULAR_POLYGON",
+  slice: "SLICE",
+  sticky: "STICKY",
+  table: "TABLE",
+  "table-cell": "TABLE_CELL",
+  symbol: "COMPONENT",
+  slot: "FRAME"
+};
+function parseXml(xml) {
+  const nodes = [];
+  const stack = [];
+  const tagRegex = /<(\/?)([\w-]+)([^>]*?)(\/?)>/g;
+  let match;
+  while ((match = tagRegex.exec(xml)) !== null) {
+    const isClosing = match[1] === "/";
+    const tagName = match[2];
+    const attrString = match[3] ?? "";
+    const isSelfClosing = match[4] === "/";
+    if (isClosing) {
+      const finished = stack.pop();
+      if (finished) {
+        const parent = stack[stack.length - 1];
+        if (parent) {
+          parent.children.push(finished);
+        } else {
+          nodes.push(finished);
+        }
+      }
+    } else {
+      const attrs = parseAttributes(attrString);
+      const node = { tag: tagName, attrs, children: [] };
+      if (isSelfClosing) {
+        const parent = stack[stack.length - 1];
+        if (parent) {
+          parent.children.push(node);
+        } else {
+          nodes.push(node);
+        }
+      } else {
+        stack.push(node);
+      }
+    }
+  }
+  while (stack.length > 0) {
+    const finished = stack.pop();
+    const parent = stack[stack.length - 1];
+    if (parent) {
+      parent.children.push(finished);
+    } else {
+      nodes.push(finished);
+    }
+  }
+  return nodes;
+}
+function parseAttributes(attrString) {
+  const attrs = {};
+  const attrRegex = /([\w-]+)="([^"]*)"/g;
+  let match;
+  while ((match = attrRegex.exec(attrString)) !== null) {
+    const key = match[1];
+    const value = match[2];
+    if (key && value !== void 0) {
+      attrs[key] = value;
+    }
+  }
+  return attrs;
+}
+function toAnalysisNode(xmlNode) {
+  const type = TAG_TYPE_MAP[xmlNode.tag] ?? "FRAME";
+  const id = xmlNode.attrs["id"] ?? "0:0";
+  const name = xmlNode.attrs["name"] ?? xmlNode.tag;
+  const hidden = xmlNode.attrs["hidden"] === "true";
+  const x = parseFloat(xmlNode.attrs["x"] ?? "0");
+  const y = parseFloat(xmlNode.attrs["y"] ?? "0");
+  const width = parseFloat(xmlNode.attrs["width"] ?? "0");
+  const height = parseFloat(xmlNode.attrs["height"] ?? "0");
+  const node = {
+    id,
+    name,
+    type,
+    visible: !hidden,
+    absoluteBoundingBox: { x, y, width, height }
+  };
+  if (xmlNode.children.length > 0) {
+    node.children = xmlNode.children.map(toAnalysisNode);
+  }
+  return node;
+}
+function parseMcpMetadataXml(xml, fileKey, fileName) {
+  const parsed = parseXml(xml);
+  const children = parsed.map(toAnalysisNode);
+  let document;
+  if (children.length === 1 && children[0]) {
+    document = children[0];
+  } else {
+    document = {
+      id: "0:0",
+      name: "Document",
+      type: "DOCUMENT",
+      visible: true,
+      children
+    };
+  }
+  return {
+    fileKey,
+    name: fileName ?? fileKey,
+    lastModified: (/* @__PURE__ */ new Date()).toISOString(),
+    version: "mcp",
+    document,
+    components: {},
+    styles: {}
+  };
+}
+var AIREADY_DIR = join(homedir(), ".canicode");
+var CONFIG_PATH = join(AIREADY_DIR, "config.json");
+var REPORTS_DIR = join(AIREADY_DIR, "reports");
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+function readConfig() {
+  if (!existsSync(CONFIG_PATH)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function writeConfig(config2) {
+  ensureDir(AIREADY_DIR);
+  writeFileSync(CONFIG_PATH, JSON.stringify(config2, null, 2) + "\n", "utf-8");
+}
+function getFigmaToken() {
+  return process.env["FIGMA_TOKEN"] ?? readConfig().figmaToken;
+}
+function setFigmaToken(token) {
+  const config2 = readConfig();
+  config2.figmaToken = token;
+  writeConfig(config2);
+}
+function getConfigPath() {
+  return CONFIG_PATH;
+}
+function getReportsDir() {
+  return REPORTS_DIR;
+}
+function ensureReportsDir() {
+  ensureDir(REPORTS_DIR);
+}
+function initAiready(token) {
+  setFigmaToken(token);
+  ensureReportsDir();
+}
+
+// src/core/loader.ts
+function isFigmaUrl(input) {
+  return input.includes("figma.com/");
+}
+function isJsonFile(input) {
+  return input.endsWith(".json");
+}
+async function loadFile(input, token, mode = "auto") {
+  if (isJsonFile(input)) {
+    const filePath = resolve(input);
+    if (!existsSync(filePath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    console.log(`Loading from JSON: ${filePath}`);
+    return { file: await loadFigmaFileFromJson(filePath) };
+  }
+  if (isFigmaUrl(input)) {
+    const { fileKey, nodeId, fileName } = parseFigmaUrl(input);
+    if (mode === "mcp") {
+      return loadFromMcp(fileKey, nodeId, fileName);
+    }
+    if (mode === "api") {
+      return loadFromApi(fileKey, nodeId, token);
+    }
+    try {
+      console.log("Auto-detecting data source... trying MCP first.");
+      return await loadFromMcp(fileKey, nodeId, fileName);
+    } catch (mcpError) {
+      const mcpMsg = mcpError instanceof Error ? mcpError.message : String(mcpError);
+      console.log(`MCP unavailable (${mcpMsg}). Falling back to REST API.`);
+      return loadFromApi(fileKey, nodeId, token);
+    }
+  }
+  throw new Error(
+    `Invalid input: ${input}. Provide a Figma URL or JSON file path.`
+  );
+}
+async function loadFromMcp(fileKey, nodeId, fileName) {
+  console.log(`Loading via MCP: ${fileKey} (node: ${nodeId ?? "root"})`);
+  const file = await loadViaMcp(fileKey, nodeId ?? "0:1", fileName);
+  return { file, nodeId };
+}
+async function loadFromApi(fileKey, nodeId, token) {
+  console.log(`Fetching from Figma REST API: ${fileKey}`);
+  if (nodeId) {
+    console.log(`Target node: ${nodeId}`);
+  }
+  const figmaToken = token ?? getFigmaToken();
+  if (!figmaToken) {
+    throw new Error(
+      "Figma token required. Run 'canicode init --token YOUR_TOKEN' or set FIGMA_TOKEN env var."
+    );
+  }
+  const client = new FigmaClient({ token: figmaToken });
+  const response = await client.getFile(fileKey);
+  return {
+    file: transformFigmaResponse(fileKey, response),
+    nodeId
+  };
+}
+async function loadViaMcp(fileKey, nodeId, fileName) {
+  const { execSync } = await import('child_process');
+  const result = execSync(
+    `claude --print "Use the mcp__figma__get_metadata tool with fileKey=\\"${fileKey}\\" and nodeId=\\"${nodeId.replace(/-/g, ":")}\\" \u2014 return ONLY the raw XML output, nothing else."`,
+    { encoding: "utf-8", timeout: 12e4 }
+  );
+  const xmlStart = result.indexOf("<");
+  const xmlEnd = result.lastIndexOf(">");
+  if (xmlStart === -1 || xmlEnd === -1) {
+    throw new Error("MCP did not return valid XML metadata");
+  }
+  const xml = result.slice(xmlStart, xmlEnd + 1);
+  return parseMcpMetadataXml(xml, fileKey, fileName);
+}
+
+// src/core/scoring.ts
+var SEVERITY_DENSITY_WEIGHT = {
+  blocking: 3,
+  risk: 2,
+  "missing-info": 1,
+  suggestion: 0.5
+};
+var TOTAL_RULES_PER_CATEGORY = {
+  layout: 11,
+  token: 7,
+  component: 6,
+  naming: 5,
+  "ai-readability": 5,
+  "handoff-risk": 5
+};
+var CATEGORY_WEIGHT = {
+  layout: 1,
+  token: 1,
+  component: 1,
+  naming: 1,
+  "ai-readability": 1,
+  "handoff-risk": 1
+};
+var DENSITY_WEIGHT = 0.7;
+var DIVERSITY_WEIGHT = 0.3;
+var SCORE_FLOOR = 5;
+function calculateGrade(percentage) {
+  if (percentage >= 95) return "S";
+  if (percentage >= 90) return "A+";
+  if (percentage >= 85) return "A";
+  if (percentage >= 80) return "B+";
+  if (percentage >= 75) return "B";
+  if (percentage >= 70) return "C+";
+  if (percentage >= 65) return "C";
+  if (percentage >= 50) return "D";
+  return "F";
+}
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+function calculateScores(result) {
+  const categoryScores = initializeCategoryScores();
+  const nodeCount = result.nodeCount;
+  const uniqueRulesPerCategory = /* @__PURE__ */ new Map();
+  for (const category of CATEGORIES) {
+    uniqueRulesPerCategory.set(category, /* @__PURE__ */ new Set());
+  }
+  for (const issue of result.issues) {
+    const category = issue.rule.definition.category;
+    const severity = issue.config.severity;
+    const ruleId = issue.rule.definition.id;
+    categoryScores[category].issueCount++;
+    categoryScores[category].bySeverity[severity]++;
+    categoryScores[category].weightedIssueCount += SEVERITY_DENSITY_WEIGHT[severity];
+    uniqueRulesPerCategory.get(category).add(ruleId);
+  }
+  for (const category of CATEGORIES) {
+    const catScore = categoryScores[category];
+    const uniqueRules = uniqueRulesPerCategory.get(category);
+    const totalRules = TOTAL_RULES_PER_CATEGORY[category];
+    catScore.uniqueRuleCount = uniqueRules.size;
+    let densityScore = 100;
+    if (nodeCount > 0 && catScore.issueCount > 0) {
+      const density = catScore.weightedIssueCount / nodeCount;
+      densityScore = clamp(Math.round(100 - density * 100), 0, 100);
+    }
+    catScore.densityScore = densityScore;
+    let diversityScore = 100;
+    if (catScore.issueCount > 0) {
+      const diversityRatio = uniqueRules.size / totalRules;
+      diversityScore = clamp(Math.round((1 - diversityRatio) * 100), 0, 100);
+    }
+    catScore.diversityScore = diversityScore;
+    const combinedScore = densityScore * DENSITY_WEIGHT + diversityScore * DIVERSITY_WEIGHT;
+    catScore.percentage = catScore.issueCount > 0 ? clamp(Math.round(combinedScore), SCORE_FLOOR, 100) : 100;
+    catScore.score = catScore.percentage;
+    catScore.maxScore = 100;
+  }
+  let totalWeight = 0;
+  let weightedSum = 0;
+  for (const category of CATEGORIES) {
+    const weight = CATEGORY_WEIGHT[category];
+    weightedSum += categoryScores[category].percentage * weight;
+    totalWeight += weight;
+  }
+  const overallPercentage = totalWeight > 0 ? Math.round(weightedSum / totalWeight) : 100;
+  const summary = {
+    totalIssues: result.issues.length,
+    blocking: 0,
+    risk: 0,
+    missingInfo: 0,
+    suggestion: 0,
+    nodeCount
+  };
+  for (const issue of result.issues) {
+    switch (issue.config.severity) {
+      case "blocking":
+        summary.blocking++;
+        break;
+      case "risk":
+        summary.risk++;
+        break;
+      case "missing-info":
+        summary.missingInfo++;
+        break;
+      case "suggestion":
+        summary.suggestion++;
+        break;
+    }
+  }
+  return {
+    overall: {
+      score: overallPercentage,
+      maxScore: 100,
+      percentage: overallPercentage,
+      grade: calculateGrade(overallPercentage)
+    },
+    byCategory: categoryScores,
+    summary
+  };
+}
+function initializeCategoryScores() {
+  const scores = {};
+  for (const category of CATEGORIES) {
+    scores[category] = {
+      category,
+      score: 100,
+      maxScore: 100,
+      percentage: 100,
+      issueCount: 0,
+      uniqueRuleCount: 0,
+      weightedIssueCount: 0,
+      densityScore: 100,
+      diversityScore: 100,
+      bySeverity: {
+        blocking: 0,
+        risk: 0,
+        "missing-info": 0,
+        suggestion: 0
+      }
+    };
+  }
+  return scores;
+}
+function formatScoreSummary(report) {
+  const lines = [];
+  lines.push(`Overall: ${report.overall.grade} (${report.overall.percentage}%)`);
+  lines.push("");
+  lines.push("By Category:");
+  for (const category of CATEGORIES) {
+    const cat = report.byCategory[category];
+    lines.push(`  ${category}: ${cat.percentage}% (${cat.issueCount} issues, ${cat.uniqueRuleCount} rules)`);
+  }
+  lines.push("");
+  lines.push("Issues:");
+  lines.push(`  Blocking: ${report.summary.blocking}`);
+  lines.push(`  Risk: ${report.summary.risk}`);
+  lines.push(`  Missing Info: ${report.summary.missingInfo}`);
+  lines.push(`  Suggestion: ${report.summary.suggestion}`);
+  lines.push(`  Total: ${report.summary.totalIssues}`);
+  return lines.join("\n");
+}
+var CustomRuleSchema = z.object({
+  id: z.string(),
+  category: CategorySchema,
+  severity: SeveritySchema,
+  score: z.number().int().max(0),
+  prompt: z.string(),
+  why: z.string(),
+  impact: z.string(),
+  fix: z.string()
+});
+var CustomRulesFileSchema = z.array(CustomRuleSchema);
+
+// src/rules/custom/custom-rule-loader.ts
+async function loadCustomRules(filePath) {
+  const absPath = resolve(filePath);
+  const raw = await readFile(absPath, "utf-8");
+  const parsed = JSON.parse(raw);
+  const customRules = CustomRulesFileSchema.parse(parsed);
+  const rules = [];
+  const configs = {};
+  for (const cr of customRules) {
+    rules.push(toRule(cr));
+    configs[cr.id] = {
+      severity: cr.severity,
+      score: cr.score,
+      enabled: true
+    };
+  }
+  return { rules, configs };
+}
+function toRule(cr) {
+  return {
+    definition: {
+      id: cr.id,
+      name: cr.id.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+      category: cr.category,
+      why: cr.why,
+      impact: cr.impact,
+      fix: cr.fix
+    },
+    check: createPromptBasedCheck()
+  };
+}
+function createPromptBasedCheck(_cr) {
+  return (node, _context) => {
+    if (node.type === "DOCUMENT" || node.type === "CANVAS") return null;
+    return null;
+  };
+}
+var RuleOverrideSchema = z.object({
+  score: z.number().int().max(0).optional(),
+  severity: SeveritySchema.optional(),
+  enabled: z.boolean().optional()
+});
+var ConfigFileSchema = z.object({
+  excludeNodeTypes: z.array(z.string()).optional(),
+  excludeNodeNames: z.array(z.string()).optional(),
+  gridBase: z.number().int().positive().optional(),
+  colorTolerance: z.number().int().positive().optional(),
+  rules: z.record(z.string(), RuleOverrideSchema).optional()
+});
+async function loadConfigFile(filePath) {
+  const absPath = resolve(filePath);
+  const raw = await readFile(absPath, "utf-8");
+  const parsed = JSON.parse(raw);
+  return ConfigFileSchema.parse(parsed);
+}
+function mergeConfigs(base, overrides) {
+  const merged = { ...base };
+  if (overrides.gridBase !== void 0) {
+    for (const [id, config2] of Object.entries(merged)) {
+      if (config2.options && "gridBase" in config2.options) {
+        merged[id] = {
+          ...config2,
+          options: { ...config2.options, gridBase: overrides.gridBase }
+        };
+      }
+    }
+  }
+  if (overrides.colorTolerance !== void 0) {
+    for (const [id, config2] of Object.entries(merged)) {
+      if (config2.options && "tolerance" in config2.options) {
+        merged[id] = {
+          ...config2,
+          options: { ...config2.options, tolerance: overrides.colorTolerance }
+        };
+      }
+    }
+  }
+  if (overrides.rules) {
+    for (const [ruleId, override] of Object.entries(overrides.rules)) {
+      const existing = merged[ruleId];
+      if (existing) {
+        merged[ruleId] = {
+          ...existing,
+          ...override.score !== void 0 && { score: override.score },
+          ...override.severity !== void 0 && { severity: override.severity },
+          ...override.enabled !== void 0 && { enabled: override.enabled }
+        };
+      }
+    }
+  }
+  return merged;
+}
+
+// src/report-html/index.ts
+var GAUGE_R = 54;
+var GAUGE_C = Math.round(2 * Math.PI * GAUGE_R);
+var CATEGORY_DESCRIPTIONS = {
+  layout: "Auto Layout, responsive constraints, nesting depth, absolute positioning",
+  token: "Design token binding for colors, fonts, shadows, spacing grid",
+  component: "Component reuse, detached instances, variant coverage",
+  naming: "Semantic layer names, naming conventions, default names",
+  "ai-readability": "Structure clarity for AI code generation, z-index, empty frames",
+  "handoff-risk": "Hardcoded values, text truncation, image placeholders, dev status"
+};
+var SEVERITY_ORDER = ["blocking", "risk", "missing-info", "suggestion"];
+function gaugeColor(pct) {
+  if (pct >= 75) return "#22c55e";
+  if (pct >= 50) return "#f59e0b";
+  return "#ef4444";
+}
+function severityBadge(sev) {
+  const map = {
+    blocking: "bg-red-500/10 text-red-600 border-red-500/20",
+    risk: "bg-amber-500/10 text-amber-600 border-amber-500/20",
+    "missing-info": "bg-zinc-500/10 text-zinc-600 border-zinc-500/20",
+    suggestion: "bg-green-500/10 text-green-600 border-green-500/20"
+  };
+  return map[sev];
+}
+function scoreBadgeStyle(pct) {
+  if (pct >= 75) return "bg-green-500/10 text-green-700 border-green-500/20";
+  if (pct >= 50) return "bg-amber-500/10 text-amber-700 border-amber-500/20";
+  return "bg-red-500/10 text-red-700 border-red-500/20";
+}
+function severityDot(sev) {
+  const map = {
+    blocking: "bg-red-500",
+    risk: "bg-amber-500",
+    "missing-info": "bg-zinc-400",
+    suggestion: "bg-green-500"
+  };
+  return map[sev];
+}
+function generateHtmlReport(file, result, scores, options) {
+  const screenshotMap = new Map(
+    (options?.nodeScreenshots ?? []).map((ns) => [ns.nodeId, ns])
+  );
+  const figmaToken = options?.figmaToken;
+  const quickWins = getQuickWins(result.issues, 5);
+  const issuesByCategory = groupIssuesByCategory(result.issues);
+  return `<!DOCTYPE html>
+<html lang="en" class="antialiased">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>CanICode Report \u2014 ${esc(file.name)}</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <script>
+    tailwind.config = {
+      theme: {
+        extend: {
+          fontFamily: { sans: ['Inter', 'ui-sans-serif', 'system-ui', '-apple-system', 'sans-serif'] },
+          colors: {
+            border: 'hsl(240 5.9% 90%)',
+            ring: 'hsl(240 5.9% 10%)',
+            background: 'hsl(0 0% 100%)',
+            foreground: 'hsl(240 10% 3.9%)',
+            muted: { DEFAULT: 'hsl(240 4.8% 95.9%)', foreground: 'hsl(240 3.8% 46.1%)' },
+            card: { DEFAULT: 'hsl(0 0% 100%)', foreground: 'hsl(240 10% 3.9%)' },
+          },
+          borderRadius: { lg: '0.5rem', md: 'calc(0.5rem - 2px)', sm: 'calc(0.5rem - 4px)' },
+        }
+      }
+    }
+  </script>
+  <style>
+    details summary::-webkit-details-marker { display: none; }
+    details summary::marker { content: ""; }
+    details summary { list-style: none; }
+    .gauge-fill { transition: stroke-dashoffset 0.8s cubic-bezier(0.4,0,0.2,1); }
+    @media print {
+      .no-print { display: none !important; }
+      .topbar-print { position: static !important; background: white !important; color: hsl(240 10% 3.9%) !important; }
+    }
+  </style>
+</head>
+<body class="bg-muted font-sans text-foreground min-h-screen">
+
+  <!-- Top Bar -->
+  <header class="topbar-print sticky top-0 z-50 bg-zinc-950 text-white border-b border-zinc-800">
+    <div class="max-w-[960px] mx-auto px-6 py-3 flex items-center gap-4">
+      <span class="font-semibold text-sm tracking-tight">CanICode</span>
+      <span class="text-zinc-400 text-sm truncate">${esc(file.name)}</span>
+      <span class="ml-auto text-zinc-500 text-xs no-print">${(/* @__PURE__ */ new Date()).toLocaleDateString()}</span>
+    </div>
+  </header>
+
+  <main class="max-w-[960px] mx-auto px-6 pb-16">
+
+    <!-- Overall Score -->
+    <section class="flex flex-col items-center pt-12 pb-6">
+      ${renderGaugeSvg(scores.overall.percentage, 200, 10, scores.overall.grade)}
+      <div class="mt-3 text-center">
+        <span class="text-lg font-semibold">${scores.overall.percentage}</span>
+        <span class="text-muted-foreground text-sm ml-1">/ 100</span>
+      </div>
+      <p class="text-muted-foreground text-sm mt-1">Overall Score</p>
+    </section>
+
+    <!-- Category Gauges -->
+    <section class="bg-card border border-border rounded-lg shadow-sm p-6 mb-6">
+      <div class="grid grid-cols-3 sm:grid-cols-6 gap-4">
+${CATEGORIES.map((cat) => {
+    const cs = scores.byCategory[cat];
+    const desc = CATEGORY_DESCRIPTIONS[cat];
+    return `        <div class="flex flex-col items-center group relative">
+          ${renderGaugeSvg(cs.percentage, 100, 7)}
+          <span class="text-xs font-medium mt-2.5 text-center leading-tight">${CATEGORY_LABELS[cat]}</span>
+          <span class="text-[11px] text-muted-foreground">${cs.issueCount} issues</span>
+          <div class="absolute bottom-full mb-2 left-1/2 -translate-x-1/2 hidden group-hover:block bg-zinc-900 text-white text-xs px-3 py-2 rounded-md whitespace-nowrap z-10 shadow-lg pointer-events-none">
+            ${esc(desc)}
+            <div class="absolute top-full left-1/2 -translate-x-1/2 border-4 border-transparent border-t-zinc-900"></div>
+          </div>
+        </div>`;
+  }).join("\n")}
+      </div>
+    </section>
+
+    <!-- Issue Summary -->
+    <section class="bg-card border border-border rounded-lg shadow-sm p-4 mb-6">
+      <div class="flex flex-wrap items-center justify-center gap-6">
+        ${renderSummaryDot("bg-red-500", scores.summary.blocking, "Blocking")}
+        ${renderSummaryDot("bg-amber-500", scores.summary.risk, "Risk")}
+        ${renderSummaryDot("bg-zinc-400", scores.summary.missingInfo, "Missing Info")}
+        ${renderSummaryDot("bg-green-500", scores.summary.suggestion, "Suggestion")}
+        <div class="border-l border-border pl-6 flex items-center gap-2">
+          <span class="text-xl font-bold tracking-tight">${scores.summary.totalIssues}</span>
+          <span class="text-sm text-muted-foreground">Total</span>
+        </div>
+      </div>
+    </section>
+
+${quickWins.length > 0 ? renderOpportunities(quickWins, file.fileKey) : ""}
+
+    <!-- Categories -->
+    <div class="space-y-3">
+${CATEGORIES.map((cat) => renderCategory(cat, scores, issuesByCategory.get(cat) ?? [], file.fileKey, screenshotMap, figmaToken)).join("\n")}
+    </div>
+
+    <!-- Footer -->
+    <footer class="mt-12 pt-6 border-t border-border text-center">
+      <p class="text-sm text-muted-foreground">Generated by <span class="font-semibold text-foreground">CanICode</span></p>
+      <p class="text-xs text-muted-foreground/60 mt-1">${(/* @__PURE__ */ new Date()).toLocaleString()} \xB7 ${result.nodeCount} nodes \xB7 Max depth ${result.maxDepth}</p>
+    </footer>
+
+  </main>
+
+${figmaToken ? `  <script>
+    const FIGMA_TOKEN = '${figmaToken}';
+    async function postComment(btn) {
+      const fileKey = btn.dataset.fileKey;
+      const nodeId = btn.dataset.nodeId.replace(/-/g, ':');
+      const rule = btn.dataset.rule;
+      const message = btn.dataset.message;
+      const path = btn.dataset.path;
+      const fix = btn.dataset.fix;
+      const why = btn.dataset.why;
+      const impact = btn.dataset.impact;
+
+      const commentBody = '[CanICode] ' + rule + '\\n\\nFix: ' + fix + '\\nWhy: ' + why + '\\nImpact: ' + impact + '\\n\\n' + message + '\\nNode: ' + path;
+
+      btn.disabled = true;
+      btn.textContent = 'Sending...';
+
+      try {
+        const res = await fetch('https://api.figma.com/v1/files/' + fileKey + '/comments', {
+          method: 'POST',
+          headers: { 'X-FIGMA-TOKEN': FIGMA_TOKEN, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ message: commentBody, client_meta: { node_id: nodeId } }),
+        });
+        if (!res.ok) throw new Error(await res.text());
+        btn.textContent = 'Sent \\u2713';
+        btn.classList.remove('hover:bg-muted');
+        btn.classList.add('text-green-600', 'border-green-500/30');
+      } catch (e) {
+        btn.textContent = 'Failed \\u2717';
+        btn.classList.remove('hover:bg-muted');
+        btn.classList.add('text-red-600', 'border-red-500/30');
+        btn.disabled = false;
+        console.error('Failed to post Figma comment:', e);
+      }
+    }
+  </script>` : ""}
+</body>
+</html>`;
+}
+function renderGaugeSvg(pct, size, strokeW, grade) {
+  const offset = GAUGE_C * (1 - pct / 100);
+  const color = gaugeColor(pct);
+  if (grade) {
+    return `<svg width="${size}" height="${size}" viewBox="0 0 120 120" class="block">
+            <circle cx="60" cy="60" r="${GAUGE_R}" fill="none" stroke-width="${strokeW}" class="stroke-border" />
+            <circle cx="60" cy="60" r="${GAUGE_R}" fill="none" stroke="${color}" stroke-width="${strokeW}" stroke-linecap="round" stroke-dasharray="${GAUGE_C}" stroke-dashoffset="${offset}" transform="rotate(-90 60 60)" class="gauge-fill" />
+            <text x="60" y="60" text-anchor="middle" dominant-baseline="central" fill="currentColor" font-size="52" font-weight="700" class="font-sans">${esc(grade)}</text>
+          </svg>`;
+  }
+  const fontSize = 32;
+  return `<svg width="${size}" height="${size}" viewBox="0 0 120 120" class="block">
+            <circle cx="60" cy="60" r="${GAUGE_R}" fill="none" stroke-width="${strokeW}" class="stroke-border" />
+            <circle cx="60" cy="60" r="${GAUGE_R}" fill="none" stroke="${color}" stroke-width="${strokeW}" stroke-linecap="round" stroke-dasharray="${GAUGE_C}" stroke-dashoffset="${offset}" transform="rotate(-90 60 60)" class="gauge-fill" />
+            <text x="60" y="62" text-anchor="middle" dominant-baseline="central" fill="currentColor" font-size="${fontSize}" font-weight="700" class="font-sans">${pct}</text>
+          </svg>`;
+}
+function renderSummaryDot(dotClass, count, label) {
+  return `<div class="flex items-center gap-2">
+          <span class="w-2.5 h-2.5 rounded-full ${dotClass}"></span>
+          <span class="text-lg font-bold tracking-tight">${count}</span>
+          <span class="text-sm text-muted-foreground">${label}</span>
+        </div>`;
+}
+function renderOpportunities(issues, fileKey) {
+  const maxAbs = issues.reduce((m, i) => Math.max(m, Math.abs(i.calculatedScore)), 1);
+  return `
+    <!-- Opportunities -->
+    <section class="bg-card border border-border rounded-lg shadow-sm mb-6 overflow-hidden">
+      <div class="px-6 py-4 border-b border-border">
+        <h2 class="text-sm font-semibold flex items-center gap-2">
+          <span class="w-2 h-2 rounded-full bg-red-500"></span>
+          Opportunities
+        </h2>
+        <p class="text-xs text-muted-foreground mt-1">Top blocking issues \u2014 fix these first for the biggest improvement.</p>
+      </div>
+      <div class="divide-y divide-border">
+${issues.map((issue) => {
+    const def = issue.rule.definition;
+    const link = buildFigmaDeepLink(fileKey, issue.violation.nodeId);
+    const barW = Math.round(Math.abs(issue.calculatedScore) / maxAbs * 100);
+    return `        <div class="px-6 py-3 flex items-center gap-4 hover:bg-muted/50 transition-colors">
+          <div class="flex-1 min-w-0">
+            <div class="text-sm font-medium truncate">${esc(def.name)}</div>
+            <div class="text-xs text-muted-foreground truncate mt-0.5">${esc(issue.violation.message)}</div>
+          </div>
+          <div class="w-32 flex items-center gap-2 shrink-0">
+            <div class="flex-1 h-1.5 bg-muted rounded-full overflow-hidden">
+              <div class="h-full bg-red-500 rounded-full" style="width:${barW}%"></div>
+            </div>
+            <span class="text-xs font-medium text-red-600 w-12 text-right">${issue.calculatedScore}</span>
+          </div>
+          <a href="${link}" target="_blank" rel="noopener" class="text-xs text-muted-foreground hover:text-foreground shrink-0 no-print">Figma \u2192</a>
+        </div>`;
+  }).join("\n")}
+      </div>
+    </section>`;
+}
+function renderCategory(cat, scores, issues, fileKey, screenshotMap, figmaToken) {
+  const cs = scores.byCategory[cat];
+  const hasProblems = issues.some((i) => i.config.severity === "blocking" || i.config.severity === "risk");
+  const bySeverity = /* @__PURE__ */ new Map();
+  for (const sev of SEVERITY_ORDER) bySeverity.set(sev, []);
+  for (const issue of issues) bySeverity.get(issue.config.severity)?.push(issue);
+  return `
+      <details class="bg-card border border-border rounded-lg shadow-sm overflow-hidden group"${hasProblems ? " open" : ""}>
+        <summary class="px-5 py-3.5 flex items-center gap-3 cursor-pointer hover:bg-muted/50 transition-colors select-none">
+          <span class="inline-flex items-center justify-center w-10 h-6 rounded-md text-xs font-bold border ${scoreBadgeStyle(cs.percentage)}">${cs.percentage}</span>
+          <div class="flex-1 min-w-0">
+            <div class="text-sm font-semibold">${CATEGORY_LABELS[cat]}</div>
+            <div class="text-xs text-muted-foreground">${esc(CATEGORY_DESCRIPTIONS[cat])}</div>
+          </div>
+          <span class="text-xs text-muted-foreground">${cs.issueCount} issues</span>
+          <svg class="w-4 h-4 text-muted-foreground transition-transform group-open:rotate-180 shrink-0 no-print" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path d="M19 9l-7 7-7-7"/></svg>
+        </summary>
+        <div class="border-t border-border">
+${issues.length === 0 ? '          <div class="px-5 py-4 text-sm text-green-600 font-medium">No issues found</div>' : SEVERITY_ORDER.filter((sev) => (bySeverity.get(sev)?.length ?? 0) > 0).map((sev) => renderSeverityGroup(sev, bySeverity.get(sev) ?? [], fileKey, screenshotMap, figmaToken)).join("\n")}
+        </div>
+      </details>`;
+}
+function renderSeverityGroup(sev, issues, fileKey, screenshotMap, figmaToken) {
+  return `          <div class="px-5 py-3">
+            <div class="flex items-center gap-2 mb-2">
+              <span class="w-2 h-2 rounded-full ${severityDot(sev)}"></span>
+              <span class="text-xs font-semibold uppercase tracking-wider">${SEVERITY_LABELS[sev]}</span>
+              <span class="text-xs text-muted-foreground ml-auto">${issues.length}</span>
+            </div>
+            <div class="space-y-1">
+${issues.map((issue) => renderIssueRow(issue, fileKey, screenshotMap, figmaToken)).join("\n")}
+            </div>
+          </div>`;
+}
+function renderIssueRow(issue, fileKey, screenshotMap, figmaToken) {
+  const sev = issue.config.severity;
+  const def = issue.rule.definition;
+  const link = buildFigmaDeepLink(fileKey, issue.violation.nodeId);
+  const screenshot = screenshotMap.get(issue.violation.nodeId);
+  const screenshotHtml = screenshot ? `<div class="mt-3"><a href="${link}" target="_blank" rel="noopener"><img src="data:image/png;base64,${screenshot.screenshotBase64}" alt="${esc(screenshot.nodePath)}" class="max-w-[240px] border border-border rounded-md"></a></div>` : "";
+  return `              <details class="border border-border rounded-md overflow-hidden">
+                <summary class="flex items-center gap-2.5 px-3 py-2 text-sm cursor-pointer hover:bg-muted/50 transition-colors">
+                  <span class="w-1.5 h-1.5 rounded-full ${severityDot(sev)} shrink-0"></span>
+                  <span class="font-medium shrink-0">${esc(def.name)}</span>
+                  <span class="text-muted-foreground truncate text-xs flex-1">${esc(issue.violation.message)}</span>
+                  <span class="inline-flex items-center px-1.5 py-0.5 text-[10px] font-medium rounded border ${severityBadge(sev)} shrink-0">${issue.calculatedScore}</span>
+                </summary>
+                <div class="px-3 py-3 bg-muted/30 border-t border-border text-sm space-y-2">
+                  <div class="font-mono text-xs text-muted-foreground break-all">${esc(issue.violation.nodePath)}</div>
+                  <div class="text-muted-foreground leading-relaxed space-y-1">
+                    <p><span class="font-medium text-foreground">Why:</span> ${esc(def.why)}</p>
+                    <p><span class="font-medium text-foreground">Impact:</span> ${esc(def.impact)}</p>
+                    <p><span class="font-medium text-foreground">Fix:</span> ${esc(def.fix)}</p>
+                  </div>${screenshotHtml}
+                  <div class="flex items-center gap-2 mt-1 no-print">
+                    <a href="${link}" target="_blank" rel="noopener" class="inline-flex items-center gap-1 px-2.5 py-1 text-xs font-medium border border-border rounded-md hover:bg-muted transition-colors">Open in Figma <span>\u2192</span></a>${figmaToken ? `
+                    <button onclick="postComment(this)" data-file-key="${esc(fileKey)}" data-node-id="${esc(issue.violation.nodeId)}" data-rule="${esc(def.name)}" data-message="${esc(issue.violation.message)}" data-path="${esc(issue.violation.nodePath)}" data-fix="${esc(def.fix)}" data-why="${esc(def.why)}" data-impact="${esc(def.impact)}" class="inline-flex items-center gap-1 px-2.5 py-1 text-xs font-medium border border-border rounded-md hover:bg-muted transition-colors cursor-pointer">Comment on Figma</button>` : ""}
+                  </div>
+                </div>
+              </details>`;
+}
+function getQuickWins(issues, limit) {
+  return issues.filter((issue) => issue.config.severity === "blocking").sort((a, b) => a.calculatedScore - b.calculatedScore).slice(0, limit);
+}
+function groupIssuesByCategory(issues) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const category of CATEGORIES) grouped.set(category, []);
+  for (const issue of issues) grouped.get(issue.rule.definition.category).push(issue);
+  return grouped;
+}
+function esc(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+var SamplingStrategySchema = z.enum(["all", "top-issues", "random"]);
+z.enum([
+  "pending",
+  "analyzing",
+  "converting",
+  "evaluating",
+  "tuning",
+  "completed",
+  "failed"
+]);
+var CalibrationConfigSchema = z.object({
+  input: z.string(),
+  token: z.string().optional(),
+  targetNodeId: z.string().optional(),
+  maxConversionNodes: z.number().int().positive().default(20),
+  samplingStrategy: SamplingStrategySchema.default("top-issues"),
+  outputPath: z.string().default("logs/calibration/calibration-report.md")
+});
+
+// src/agents/analysis-agent.ts
+function buildNodeIssueSummaries(result) {
+  const nodeMap = /* @__PURE__ */ new Map();
+  for (const issue of result.issues) {
+    const nodeId = issue.violation.nodeId;
+    const existing = nodeMap.get(nodeId);
+    if (existing) {
+      existing.totalScore += issue.calculatedScore;
+      existing.issueCount++;
+      existing.ruleIds.add(issue.rule.definition.id);
+      existing.severities.add(issue.config.severity);
+    } else {
+      nodeMap.set(nodeId, {
+        nodePath: issue.violation.nodePath,
+        totalScore: issue.calculatedScore,
+        issueCount: 1,
+        ruleIds: /* @__PURE__ */ new Set([issue.rule.definition.id]),
+        severities: /* @__PURE__ */ new Set([issue.config.severity])
+      });
+    }
+  }
+  const summaries = [];
+  for (const [nodeId, data] of nodeMap) {
+    summaries.push({
+      nodeId,
+      nodePath: data.nodePath,
+      totalScore: data.totalScore,
+      issueCount: data.issueCount,
+      flaggedRuleIds: [...data.ruleIds],
+      severities: [...data.severities]
+    });
+  }
+  summaries.sort((a, b) => a.totalScore - b.totalScore);
+  return summaries;
+}
+function extractRuleScores(result) {
+  const scores = {};
+  for (const issue of result.issues) {
+    const ruleId = issue.rule.definition.id;
+    if (!scores[ruleId]) {
+      scores[ruleId] = {
+        score: issue.config.score,
+        severity: issue.config.severity
+      };
+    }
+  }
+  return scores;
+}
+function runAnalysisAgent(input) {
+  const { analysisResult } = input;
+  const scoreReport = calculateScores(analysisResult);
+  const nodeIssueSummaries = buildNodeIssueSummaries(analysisResult);
+  return {
+    analysisResult,
+    scoreReport,
+    nodeIssueSummaries
+  };
+}
+
+// src/agents/conversion-agent.ts
+async function runConversionAgent(input, executor) {
+  const records = [];
+  const skippedNodeIds = [];
+  for (const node of input.nodes) {
+    const startTime = Date.now();
+    try {
+      const result = await executor(
+        node.nodeId,
+        input.fileKey,
+        node.flaggedRuleIds
+      );
+      const durationMs = Date.now() - startTime;
+      records.push({
+        nodeId: node.nodeId,
+        nodePath: node.nodePath,
+        generatedCode: result.generatedCode,
+        difficulty: result.difficulty,
+        notes: result.notes,
+        ruleRelatedStruggles: result.ruleRelatedStruggles,
+        uncoveredStruggles: result.uncoveredStruggles,
+        durationMs
+      });
+    } catch {
+      skippedNodeIds.push(node.nodeId);
+    }
+  }
+  return { records, skippedNodeIds };
+}
+
+// src/agents/evaluation-agent.ts
+var DIFFICULTY_SCORE_RANGES = {
+  easy: { min: -3, max: 0 },
+  moderate: { min: -7, max: -4 },
+  hard: { min: -12, max: -8 },
+  failed: { min: -12, max: -8 }
+};
+function scoreMatchesDifficulty(score, difficulty) {
+  const range = DIFFICULTY_SCORE_RANGES[difficulty];
+  return score >= range.min && score <= range.max;
+}
+function classifyFlaggedRule(currentScore, actualDifficulty) {
+  if (scoreMatchesDifficulty(currentScore, actualDifficulty)) {
+    return "validated";
+  }
+  if (actualDifficulty === "easy" && currentScore < -3 || actualDifficulty === "moderate" && currentScore < -7) {
+    return "overscored";
+  }
+  return "underscored";
+}
+function buildReasoning(type, ruleId, currentScore, actualDifficulty) {
+  const range = DIFFICULTY_SCORE_RANGES[actualDifficulty];
+  switch (type) {
+    case "validated":
+      return `Rule "${ruleId}" score (${currentScore}) aligns with actual difficulty "${actualDifficulty}" (expected range: ${range.min} to ${range.max}).`;
+    case "overscored":
+      return `Rule "${ruleId}" score (${currentScore}) is too harsh for actual difficulty "${actualDifficulty}" (expected range: ${range.min} to ${range.max}).`;
+    case "underscored":
+      return `Rule "${ruleId}" score (${currentScore}) is too lenient for actual difficulty "${actualDifficulty}" (expected range: ${range.min} to ${range.max}).`;
+    case "missing-rule":
+      return `No rule covers this difficulty "${actualDifficulty}" (expected score range: ${range.min} to ${range.max}).`;
+  }
+}
+function runEvaluationAgent(input) {
+  const mismatches = [];
+  const validatedRuleSet = /* @__PURE__ */ new Set();
+  const nodeSummaryMap = new Map(
+    input.nodeIssueSummaries.map((s) => [s.nodeId, s])
+  );
+  for (const record of input.conversionRecords) {
+    const summary = nodeSummaryMap.get(record.nodeId);
+    const difficulty = record.difficulty;
+    for (const struggle of record.ruleRelatedStruggles) {
+      const ruleInfo = input.ruleScores[struggle.ruleId];
+      if (!ruleInfo) continue;
+      const actualDifficulty = struggle.actualImpact;
+      const type = classifyFlaggedRule(ruleInfo.score, actualDifficulty);
+      if (type === "validated") {
+        validatedRuleSet.add(struggle.ruleId);
+      }
+      mismatches.push({
+        type,
+        nodeId: record.nodeId,
+        nodePath: record.nodePath,
+        ruleId: struggle.ruleId,
+        currentScore: ruleInfo.score,
+        currentSeverity: ruleInfo.severity,
+        actualDifficulty,
+        reasoning: buildReasoning(type, struggle.ruleId, ruleInfo.score, actualDifficulty)
+      });
+    }
+    if (summary) {
+      const struggledRuleIds = new Set(
+        record.ruleRelatedStruggles.map((s) => s.ruleId)
+      );
+      for (const ruleId of summary.flaggedRuleIds) {
+        if (struggledRuleIds.has(ruleId)) continue;
+        const ruleInfo = input.ruleScores[ruleId];
+        if (!ruleInfo) continue;
+        if (difficulty === "easy" || difficulty === "moderate") {
+          mismatches.push({
+            type: "overscored",
+            nodeId: record.nodeId,
+            nodePath: record.nodePath,
+            ruleId,
+            currentScore: ruleInfo.score,
+            currentSeverity: ruleInfo.severity,
+            actualDifficulty: "easy",
+            reasoning: `Rule "${ruleId}" was flagged but caused no struggle during conversion (overall node difficulty: "${difficulty}").`
+          });
+        } else {
+          validatedRuleSet.add(ruleId);
+          mismatches.push({
+            type: "validated",
+            nodeId: record.nodeId,
+            nodePath: record.nodePath,
+            ruleId,
+            currentScore: ruleInfo.score,
+            currentSeverity: ruleInfo.severity,
+            actualDifficulty: difficulty,
+            reasoning: `Rule "${ruleId}" was flagged and overall conversion was "${difficulty}" \u2014 conservatively validated.`
+          });
+        }
+      }
+    }
+    for (const uncovered of record.uncoveredStruggles) {
+      const estimatedDifficulty = uncovered.estimatedImpact;
+      mismatches.push({
+        type: "missing-rule",
+        nodeId: record.nodeId,
+        nodePath: record.nodePath,
+        actualDifficulty: estimatedDifficulty,
+        reasoning: `Uncovered struggle: "${uncovered.description}" (category: ${uncovered.suggestedCategory}, impact: ${estimatedDifficulty}).`
+      });
+    }
+  }
+  return {
+    mismatches,
+    validatedRules: [...validatedRuleSet]
+  };
+}
+
+// src/agents/tuning-agent.ts
+var DIFFICULTY_MIDPOINT = {
+  easy: -2,
+  moderate: -5,
+  hard: -10,
+  failed: -12
+};
+var DIFFICULTY_SEVERITY = {
+  easy: "suggestion",
+  moderate: "risk",
+  hard: "blocking",
+  failed: "blocking"
+};
+function getConfidence(caseCount) {
+  if (caseCount >= 3) return "high";
+  if (caseCount >= 2) return "medium";
+  return "low";
+}
+function proposedScoreFromDifficulties(difficulties) {
+  const counts = {};
+  for (const d of difficulties) {
+    counts[d] = (counts[d] ?? 0) + 1;
+  }
+  let dominant = difficulties[0] ?? "moderate";
+  let maxCount = 0;
+  for (const [difficulty, count] of Object.entries(counts)) {
+    if (count > maxCount) {
+      maxCount = count;
+      dominant = difficulty;
+    }
+  }
+  return DIFFICULTY_MIDPOINT[dominant] ?? -5;
+}
+function proposeSeverity(currentSeverity, proposedScore) {
+  let expectedSeverity;
+  if (proposedScore <= -8) {
+    expectedSeverity = "blocking";
+  } else if (proposedScore <= -4) {
+    expectedSeverity = "risk";
+  } else if (proposedScore <= -2) {
+    expectedSeverity = "missing-info";
+  } else {
+    expectedSeverity = "suggestion";
+  }
+  if (expectedSeverity !== currentSeverity) {
+    return expectedSeverity;
+  }
+  return void 0;
+}
+function runTuningAgent(input) {
+  const adjustments = [];
+  const newRuleProposals = [];
+  const overscoredByRule = /* @__PURE__ */ new Map();
+  const underscoredByRule = /* @__PURE__ */ new Map();
+  const missingRuleCases = [];
+  for (const mismatch of input.mismatches) {
+    switch (mismatch.type) {
+      case "overscored": {
+        if (!mismatch.ruleId) break;
+        const existing = overscoredByRule.get(mismatch.ruleId);
+        if (existing) {
+          existing.push(mismatch);
+        } else {
+          overscoredByRule.set(mismatch.ruleId, [mismatch]);
+        }
+        break;
+      }
+      case "underscored": {
+        if (!mismatch.ruleId) break;
+        const existing = underscoredByRule.get(mismatch.ruleId);
+        if (existing) {
+          existing.push(mismatch);
+        } else {
+          underscoredByRule.set(mismatch.ruleId, [mismatch]);
+        }
+        break;
+      }
+      case "missing-rule":
+        missingRuleCases.push(mismatch);
+        break;
+    }
+  }
+  for (const [ruleId, cases] of overscoredByRule) {
+    const ruleInfo = input.ruleScores[ruleId];
+    if (!ruleInfo) continue;
+    const difficulties = cases.map((c) => c.actualDifficulty);
+    const proposedScore = proposedScoreFromDifficulties(difficulties);
+    const currentSeverity = ruleInfo.severity;
+    const newSeverity = proposeSeverity(currentSeverity, proposedScore);
+    adjustments.push({
+      ruleId,
+      currentScore: ruleInfo.score,
+      proposedScore,
+      currentSeverity,
+      proposedSeverity: newSeverity,
+      reasoning: `Overscored in ${cases.length} case(s). Actual difficulties: [${difficulties.join(", ")}]. Current score ${ruleInfo.score} is too harsh.`,
+      confidence: getConfidence(cases.length),
+      supportingCases: cases.length
+    });
+  }
+  for (const [ruleId, cases] of underscoredByRule) {
+    const ruleInfo = input.ruleScores[ruleId];
+    if (!ruleInfo) continue;
+    const difficulties = cases.map((c) => c.actualDifficulty);
+    const proposedScore = proposedScoreFromDifficulties(difficulties);
+    const currentSeverity = ruleInfo.severity;
+    const newSeverity = proposeSeverity(currentSeverity, proposedScore);
+    adjustments.push({
+      ruleId,
+      currentScore: ruleInfo.score,
+      proposedScore,
+      currentSeverity,
+      proposedSeverity: newSeverity,
+      reasoning: `Underscored in ${cases.length} case(s). Actual difficulties: [${difficulties.join(", ")}]. Current score ${ruleInfo.score} is too lenient.`,
+      confidence: getConfidence(cases.length),
+      supportingCases: cases.length
+    });
+  }
+  const missingGrouped = /* @__PURE__ */ new Map();
+  for (const c of missingRuleCases) {
+    const categoryMatch = c.reasoning.match(/category:\s*([^,)]+)/);
+    const category = categoryMatch?.[1]?.trim() ?? "unknown";
+    const existing = missingGrouped.get(category);
+    if (existing) {
+      existing.push(c);
+    } else {
+      missingGrouped.set(category, [c]);
+    }
+  }
+  for (const [category, cases] of missingGrouped) {
+    const difficulties = cases.map((c) => c.actualDifficulty);
+    const dominantDifficulty = getDominantDifficulty(difficulties);
+    const descriptions = cases.map((c) => {
+      const descMatch = c.reasoning.match(/Uncovered struggle: "([^"]+)"/);
+      return descMatch?.[1] ?? c.reasoning;
+    });
+    newRuleProposals.push({
+      suggestedId: `new-${category}-rule`,
+      category,
+      description: descriptions.join("; "),
+      suggestedSeverity: DIFFICULTY_SEVERITY[dominantDifficulty] ?? "risk",
+      suggestedScore: DIFFICULTY_MIDPOINT[dominantDifficulty] ?? -5,
+      reasoning: `${cases.length} uncovered struggle(s) in category "${category}". Difficulties: [${difficulties.join(", ")}].`,
+      supportingCases: cases.length
+    });
+  }
+  return { adjustments, newRuleProposals };
+}
+function getDominantDifficulty(difficulties) {
+  const counts = {};
+  for (const d of difficulties) {
+    counts[d] = (counts[d] ?? 0) + 1;
+  }
+  let dominant = difficulties[0] ?? "moderate";
+  let maxCount = 0;
+  for (const [difficulty, count] of Object.entries(counts)) {
+    if (count > maxCount) {
+      maxCount = count;
+      dominant = difficulty;
+    }
+  }
+  return dominant;
+}
+
+// src/agents/report-generator.ts
+function generateCalibrationReport(data) {
+  const lines = [];
+  lines.push("# Calibration Report");
+  lines.push("");
+  lines.push(renderOverview(data));
+  lines.push(renderCurrentScores(data));
+  lines.push(renderAdjustmentProposals(data.adjustments));
+  lines.push(renderNewRuleProposals(data.newRuleProposals));
+  lines.push(renderValidatedRules(data.validatedRules));
+  lines.push(renderMismatchDetails(data.mismatches));
+  lines.push(renderApplicationGuide(data.adjustments));
+  return lines.join("\n");
+}
+function renderOverview(data) {
+  return `## Overview
+
+| Metric | Value |
+|--------|-------|
+| File | ${data.fileName} (${data.fileKey}) |
+| Analyzed At | ${data.analyzedAt} |
+| Total Nodes | ${data.nodeCount} |
+| Total Issues | ${data.issueCount} |
+| Converted Nodes | ${data.convertedNodeCount} |
+| Skipped Nodes | ${data.skippedNodeCount} |
+| Overall Grade | ${data.scoreReport.overall.grade} (${data.scoreReport.overall.percentage}%) |
+`;
+}
+function renderCurrentScores(data) {
+  const lines = [];
+  lines.push("## Current Score Summary");
+  lines.push("");
+  lines.push("| Category | Score | Issues | Density | Diversity |");
+  lines.push("|----------|-------|--------|---------|-----------|");
+  for (const [category, catScore] of Object.entries(data.scoreReport.byCategory)) {
+    lines.push(
+      `| ${category} | ${catScore.percentage}% | ${catScore.issueCount} | ${catScore.densityScore} | ${catScore.diversityScore} |`
+    );
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderAdjustmentProposals(adjustments) {
+  if (adjustments.length === 0) {
+    return "## Score Adjustment Proposals\n\nNo adjustments proposed.\n";
+  }
+  const lines = [];
+  lines.push("## Score Adjustment Proposals");
+  lines.push("");
+  lines.push("| Rule | Current Score | Proposed Score | Severity Change | Confidence | Cases | Reasoning |");
+  lines.push("|------|--------------|----------------|-----------------|------------|-------|-----------|");
+  for (const adj of adjustments) {
+    const severityChange = adj.proposedSeverity ? `${adj.currentSeverity} -> ${adj.proposedSeverity}` : adj.currentSeverity;
+    lines.push(
+      `| ${adj.ruleId} | ${adj.currentScore} | ${adj.proposedScore} | ${severityChange} | ${adj.confidence} | ${adj.supportingCases} | ${adj.reasoning} |`
+    );
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderNewRuleProposals(proposals) {
+  if (proposals.length === 0) {
+    return "## New Rule Proposals\n\nNo new rules proposed.\n";
+  }
+  const lines = [];
+  lines.push("## New Rule Proposals");
+  lines.push("");
+  for (const proposal of proposals) {
+    lines.push(`### ${proposal.suggestedId}`);
+    lines.push("");
+    lines.push(`- **Category**: ${proposal.category}`);
+    lines.push(`- **Suggested Severity**: ${proposal.suggestedSeverity}`);
+    lines.push(`- **Suggested Score**: ${proposal.suggestedScore}`);
+    lines.push(`- **Supporting Cases**: ${proposal.supportingCases}`);
+    lines.push(`- **Description**: ${proposal.description}`);
+    lines.push(`- **Reasoning**: ${proposal.reasoning}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderValidatedRules(validatedRules) {
+  if (validatedRules.length === 0) {
+    return "## Validated Rules\n\nNo rules were validated in this run.\n";
+  }
+  const lines = [];
+  lines.push("## Validated Rules");
+  lines.push("");
+  lines.push("The following rules had scores that aligned with actual conversion difficulty:");
+  lines.push("");
+  for (const ruleId of validatedRules) {
+    lines.push(`- \`${ruleId}\``);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderMismatchDetails(mismatches) {
+  if (mismatches.length === 0) {
+    return "## Detailed Mismatch List\n\nNo mismatches found.\n";
+  }
+  const lines = [];
+  lines.push("## Detailed Mismatch List");
+  lines.push("");
+  const grouped = {};
+  for (const m of mismatches) {
+    const list = grouped[m.type];
+    if (list) {
+      list.push(m);
+    } else {
+      grouped[m.type] = [m];
+    }
+  }
+  for (const [type, cases] of Object.entries(grouped)) {
+    lines.push(`### ${type} (${cases.length})`);
+    lines.push("");
+    for (const c of cases) {
+      const ruleInfo = c.ruleId ? ` | Rule: \`${c.ruleId}\`` : "";
+      const scoreInfo = c.currentScore !== void 0 ? ` | Score: ${c.currentScore}` : "";
+      lines.push(`- **${c.nodePath}** (${c.nodeId})${ruleInfo}${scoreInfo} | Difficulty: ${c.actualDifficulty}`);
+      lines.push(`  > ${c.reasoning}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderApplicationGuide(adjustments) {
+  const lines = [];
+  lines.push("## Application Guide");
+  lines.push("");
+  lines.push("To apply these calibration results:");
+  lines.push("");
+  lines.push("1. Review each adjustment proposal above");
+  lines.push("2. Edit `src/rules/rule-config.ts` to update scores and severities");
+  lines.push("3. Run `pnpm test:run` to verify no tests break");
+  lines.push("4. Re-run calibration to confirm improvements");
+  lines.push("");
+  if (adjustments.length > 0) {
+    lines.push("### Suggested Changes to `rule-config.ts`");
+    lines.push("");
+    lines.push("```typescript");
+    for (const adj of adjustments) {
+      lines.push(`// ${adj.ruleId}: ${adj.currentScore} -> ${adj.proposedScore} (${adj.confidence} confidence)`);
+      if (adj.proposedSeverity) {
+        lines.push(`//   severity: "${adj.currentSeverity}" -> "${adj.proposedSeverity}"`);
+      }
+    }
+    lines.push("```");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function getTimestamp() {
+  const now = /* @__PURE__ */ new Date();
+  return now.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit", hour12: false });
+}
+function getDateTimeString() {
+  const now = /* @__PURE__ */ new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  const hours = String(now.getHours()).padStart(2, "0");
+  const minutes = String(now.getMinutes()).padStart(2, "0");
+  return `${year}-${month}-${day}-${hours}-${minutes}`;
+}
+function extractFixtureName(fixturePath) {
+  const fileName = fixturePath.split("/").pop() ?? fixturePath;
+  return fileName.replace(/\.json$/, "");
+}
+var ActivityLogger = class {
+  logPath;
+  initialized = false;
+  constructor(fixturePath, logDir = "logs/activity") {
+    const dateTimeStr = getDateTimeString();
+    const fixtureName = fixturePath ? extractFixtureName(fixturePath) : "unknown";
+    this.logPath = resolve(logDir, `${dateTimeStr}-${fixtureName}.md`);
+  }
+  /**
+   * Ensure the log directory and file header exist
+   */
+  async ensureInitialized() {
+    if (this.initialized) return;
+    const dir = dirname(this.logPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    if (!existsSync(this.logPath)) {
+      const ts = getDateTimeString();
+      await writeFile(this.logPath, `# Calibration Activity Log \u2014 ${ts}
+
+`, "utf-8");
+    }
+    this.initialized = true;
+  }
+  /**
+   * Log a pipeline step
+   */
+  async logStep(activity) {
+    await this.ensureInitialized();
+    const lines = [];
+    lines.push(`## ${getTimestamp()} \u2014 ${activity.step}`);
+    if (activity.nodePath) {
+      lines.push(`- Node: ${activity.nodePath}`);
+    }
+    lines.push(`- Result: ${activity.result}`);
+    lines.push(`- Duration: ${activity.durationMs}ms`);
+    lines.push("");
+    await appendFile(this.logPath, lines.join("\n") + "\n", "utf-8");
+  }
+  /**
+   * Log a summary at pipeline completion
+   */
+  async logSummary(summary) {
+    await this.ensureInitialized();
+    const lines = [];
+    lines.push(`## ${getTimestamp()} \u2014 Pipeline Summary`);
+    lines.push(`- Status: ${summary.status}`);
+    lines.push(`- Total Duration: ${summary.totalDurationMs}ms`);
+    lines.push(`- Nodes Analyzed: ${summary.nodesAnalyzed}`);
+    lines.push(`- Nodes Converted: ${summary.nodesConverted}`);
+    lines.push(`- Mismatches Found: ${summary.mismatches}`);
+    lines.push(`- Adjustments Proposed: ${summary.adjustments}`);
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    await appendFile(this.logPath, lines.join("\n") + "\n", "utf-8");
+  }
+  getLogPath() {
+    return this.logPath;
+  }
+};
+
+// src/agents/orchestrator.ts
+function selectNodes(summaries, strategy, maxNodes) {
+  if (summaries.length === 0) return [];
+  switch (strategy) {
+    case "all":
+      return summaries.slice(0, maxNodes);
+    case "random": {
+      const shuffled = [...summaries];
+      for (let i = shuffled.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        const temp = shuffled[i];
+        shuffled[i] = shuffled[j];
+        shuffled[j] = temp;
+      }
+      return shuffled.slice(0, maxNodes);
+    }
+    case "top-issues":
+    default:
+      return summaries.slice(0, maxNodes);
+  }
+}
+var EXCLUDED_NODE_TYPES = /* @__PURE__ */ new Set([
+  "VECTOR",
+  "BOOLEAN_OPERATION",
+  "STAR",
+  "REGULAR_POLYGON",
+  "ELLIPSE",
+  "LINE"
+]);
+function findNode(root, nodeId) {
+  if (root.id === nodeId) return root;
+  if (root.children) {
+    for (const child of root.children) {
+      const found = findNode(child, nodeId);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+function hasTextDescendant(node) {
+  if (node.type === "TEXT") return true;
+  if (node.children) {
+    for (const child of node.children) {
+      if (hasTextDescendant(child)) return true;
+    }
+  }
+  return false;
+}
+var MIN_WIDTH = 200;
+var MIN_HEIGHT = 200;
+var ELIGIBLE_NODE_TYPES = /* @__PURE__ */ new Set([
+  "FRAME",
+  "COMPONENT",
+  "INSTANCE"
+]);
+var ICON_NAME_PATTERN = /\b(icon|ico|badge|indicator)\b/i;
+function filterConversionCandidates(summaries, documentRoot) {
+  return summaries.filter((summary) => {
+    const node = findNode(documentRoot, summary.nodeId);
+    if (!node) return false;
+    if (EXCLUDED_NODE_TYPES.has(node.type)) return false;
+    if (!ELIGIBLE_NODE_TYPES.has(node.type)) return false;
+    if (ICON_NAME_PATTERN.test(node.name)) return false;
+    const bbox = node.absoluteBoundingBox;
+    if (bbox && (bbox.width < MIN_WIDTH || bbox.height < MIN_HEIGHT)) return false;
+    if (!node.children || node.children.length < 3) return false;
+    if (!hasTextDescendant(node)) return false;
+    return true;
+  });
+}
+function isFigmaUrl2(input) {
+  return input.includes("figma.com/");
+}
+function isJsonFile2(input) {
+  return input.endsWith(".json");
+}
+async function loadFile2(input, token) {
+  if (isJsonFile2(input)) {
+    const filePath = resolve(input);
+    if (!existsSync(filePath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    const file = await loadFigmaFileFromJson(filePath);
+    return { file, fileKey: file.fileKey, nodeId: void 0 };
+  }
+  if (isFigmaUrl2(input)) {
+    const { fileKey, nodeId } = parseFigmaUrl(input);
+    const figmaToken = token ?? process.env["FIGMA_TOKEN"];
+    if (!figmaToken) {
+      throw new Error(
+        "Figma token required. Provide token or set FIGMA_TOKEN environment variable."
+      );
+    }
+    const client = new FigmaClient({ token: figmaToken });
+    const response = await client.getFile(fileKey);
+    const file = transformFigmaResponse(fileKey, response);
+    return { file, fileKey, nodeId };
+  }
+  throw new Error(
+    `Invalid input: ${input}. Provide a Figma URL or JSON file path.`
+  );
+}
+function buildRuleScoresMap() {
+  const scores = {};
+  for (const [id, config2] of Object.entries(RULE_CONFIGS)) {
+    scores[id] = { score: config2.score, severity: config2.severity };
+  }
+  return scores;
+}
+async function runCalibrationAnalyze(config2) {
+  const parsed = CalibrationConfigSchema.parse(config2);
+  const { file, fileKey, nodeId } = await loadFile2(parsed.input, parsed.token);
+  const analyzeOptions = nodeId ? { targetNodeId: nodeId } : {};
+  const analysisResult = analyzeFile(file, analyzeOptions);
+  const analysisOutput = runAnalysisAgent({ analysisResult });
+  const ruleScores = {
+    ...buildRuleScoresMap(),
+    ...extractRuleScores(analysisResult)
+  };
+  return { analysisOutput, ruleScores, fileKey };
+}
+function runCalibrationEvaluate(analysisJson, conversionJson, ruleScores) {
+  const evaluationOutput = runEvaluationAgent({
+    nodeIssueSummaries: analysisJson.nodeIssueSummaries.map((s) => ({
+      nodeId: s.nodeId,
+      nodePath: s.nodePath,
+      flaggedRuleIds: s.flaggedRuleIds
+    })),
+    conversionRecords: conversionJson.records,
+    ruleScores
+  });
+  const tuningOutput = runTuningAgent({
+    mismatches: evaluationOutput.mismatches,
+    ruleScores
+  });
+  const report = generateCalibrationReport({
+    fileKey: analysisJson.fileKey,
+    fileName: analysisJson.fileName,
+    analyzedAt: analysisJson.analyzedAt,
+    nodeCount: analysisJson.nodeCount,
+    issueCount: analysisJson.issueCount,
+    convertedNodeCount: conversionJson.records.length,
+    skippedNodeCount: conversionJson.skippedNodeIds.length,
+    scoreReport: analysisJson.scoreReport,
+    mismatches: evaluationOutput.mismatches,
+    validatedRules: evaluationOutput.validatedRules,
+    adjustments: tuningOutput.adjustments,
+    newRuleProposals: tuningOutput.newRuleProposals
+  });
+  return {
+    evaluationOutput,
+    tuningOutput,
+    report
+  };
+}
+async function runCalibration(config2, executor, options) {
+  const parsed = CalibrationConfigSchema.parse(config2);
+  const pipelineStart = Date.now();
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const logger = new ActivityLogger(parsed.input) ;
+  try {
+    let stepStart = Date.now();
+    const { file, fileKey, nodeId } = await loadFile2(parsed.input, parsed.token);
+    const analyzeOptions = nodeId ? { targetNodeId: nodeId } : {};
+    const analysisResult = analyzeFile(file, analyzeOptions);
+    const analysisOutput = runAnalysisAgent({ analysisResult });
+    const ruleScores = {
+      ...buildRuleScoresMap(),
+      ...extractRuleScores(analysisResult)
+    };
+    await logger?.logStep({
+      step: "Analysis",
+      result: `${analysisResult.nodeCount} nodes, ${analysisResult.issues.length} issues, grade ${analysisOutput.scoreReport.overall.grade}`,
+      durationMs: Date.now() - stepStart
+    });
+    stepStart = Date.now();
+    const candidates = filterConversionCandidates(
+      analysisOutput.nodeIssueSummaries,
+      analysisResult.file.document
+    );
+    const selectedNodes = selectNodes(
+      candidates,
+      parsed.samplingStrategy,
+      parsed.maxConversionNodes
+    );
+    const conversionOutput = await runConversionAgent(
+      {
+        fileKey,
+        nodes: selectedNodes.map((n) => ({
+          nodeId: n.nodeId,
+          nodePath: n.nodePath,
+          flaggedRuleIds: n.flaggedRuleIds
+        }))
+      },
+      executor
+    );
+    await logger?.logStep({
+      step: "Conversion",
+      result: `${conversionOutput.records.length} converted, ${conversionOutput.skippedNodeIds.length} skipped`,
+      durationMs: Date.now() - stepStart
+    });
+    stepStart = Date.now();
+    const evaluationOutput = runEvaluationAgent({
+      nodeIssueSummaries: selectedNodes.map((n) => ({
+        nodeId: n.nodeId,
+        nodePath: n.nodePath,
+        flaggedRuleIds: n.flaggedRuleIds
+      })),
+      conversionRecords: conversionOutput.records,
+      ruleScores
+    });
+    await logger?.logStep({
+      step: "Evaluation",
+      result: `${evaluationOutput.mismatches.length} mismatches, ${evaluationOutput.validatedRules.length} validated`,
+      durationMs: Date.now() - stepStart
+    });
+    stepStart = Date.now();
+    const tuningOutput = runTuningAgent({
+      mismatches: evaluationOutput.mismatches,
+      ruleScores
+    });
+    await logger?.logStep({
+      step: "Tuning",
+      result: `${tuningOutput.adjustments.length} adjustments, ${tuningOutput.newRuleProposals.length} new rule proposals`,
+      durationMs: Date.now() - stepStart
+    });
+    const report = generateCalibrationReport({
+      fileKey,
+      fileName: file.name,
+      analyzedAt: startedAt,
+      nodeCount: analysisResult.nodeCount,
+      issueCount: analysisResult.issues.length,
+      convertedNodeCount: conversionOutput.records.length,
+      skippedNodeCount: conversionOutput.skippedNodeIds.length,
+      scoreReport: analysisOutput.scoreReport,
+      mismatches: evaluationOutput.mismatches,
+      validatedRules: evaluationOutput.validatedRules,
+      adjustments: tuningOutput.adjustments,
+      newRuleProposals: tuningOutput.newRuleProposals
+    });
+    const reportPath = resolve(parsed.outputPath);
+    const reportDir = resolve(parsed.outputPath, "..");
+    if (!existsSync(reportDir)) {
+      mkdirSync(reportDir, { recursive: true });
+    }
+    await writeFile(reportPath, report, "utf-8");
+    await logger?.logSummary({
+      totalDurationMs: Date.now() - pipelineStart,
+      nodesAnalyzed: analysisResult.nodeCount,
+      nodesConverted: conversionOutput.records.length,
+      mismatches: evaluationOutput.mismatches.length,
+      adjustments: tuningOutput.adjustments.length,
+      status: "completed"
+    });
+    return {
+      status: "completed",
+      scoreReport: analysisOutput.scoreReport,
+      nodeIssueSummaries: analysisOutput.nodeIssueSummaries,
+      mismatches: evaluationOutput.mismatches,
+      validatedRules: evaluationOutput.validatedRules,
+      adjustments: tuningOutput.adjustments,
+      newRuleProposals: tuningOutput.newRuleProposals,
+      reportPath,
+      logPath: logger?.getLogPath()
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    await logger?.logSummary({
+      totalDurationMs: Date.now() - pipelineStart,
+      nodesAnalyzed: 0,
+      nodesConverted: 0,
+      mismatches: 0,
+      adjustments: 0,
+      status: `failed: ${errorMessage}`
+    });
+    return {
+      status: "failed",
+      scoreReport: {
+        overall: { score: 0, maxScore: 100, percentage: 0, grade: "F" },
+        byCategory: {},
+        summary: { totalIssues: 0, blocking: 0, risk: 0, missingInfo: 0, suggestion: 0, nodeCount: 0 }
+      },
+      nodeIssueSummaries: [],
+      mismatches: [],
+      validatedRules: [],
+      adjustments: [],
+      newRuleProposals: [],
+      reportPath: parsed.outputPath,
+      error: errorMessage
+    };
+  }
+}
+
+// src/cli/docs.ts
+function printDocsIndex() {
+  console.log(`
+CANICODE DOCUMENTATION
+
+  canicode docs setup    Full setup guide (CLI, MCP, Skills)
+  canicode docs rules    Custom rules guide + example
+  canicode docs config   Config override guide + example
+
+Full documentation: github.com/let-sunny/canicode#readme
+`.trimStart());
+}
+function printDocsSetup() {
+  console.log(`
+CANICODE SETUP GUIDE
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ 1. CLI
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Install:
+    npm install -g canicode
+
+  Setup:
+    canicode init --token figd_xxxxxxxxxxxxx
+    (saved to ~/.canicode/config.json, reports go to ~/.canicode/reports/)
+
+  Use:
+    canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
+    (opens report in browser automatically, use --no-open to disable)
+
+  Data source flags:
+    --api     REST API (uses saved token)
+    --mcp     Figma MCP bridge (Claude Code only, no token needed)
+    (none)    Auto: try MCP first, fallback to API
+
+  Options:
+    --preset strict|relaxed|dev-friendly|ai-ready
+    --config ./my-config.json
+    --custom-rules ./my-rules.json
+    --no-open   Don't open report in browser
+
+  Output:
+    ~/.canicode/reports/report-YYYY-MM-DD-HH-mm-<filekey>.html
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ 2. MCP SERVER (Claude Code integration)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Route A \u2014 Figma MCP relay (no token needed):
+
+    Install (once):
+      claude mcp add figma -- npx -y @anthropic-ai/claude-code-mcp-figma
+      claude mcp add --transport stdio canicode npx canicode-mcp
+
+    Flow:
+      Claude Code
+        -> Figma MCP get_metadata(fileKey, nodeId) -> XML node tree
+        -> canicode MCP analyze(designData: XML) -> analysis result
+
+  Route B \u2014 REST API direct (token needed):
+
+    Install (once):
+      claude mcp add --transport stdio canicode npx canicode-mcp
+      canicode init --token figd_xxxxxxxxxxxxx
+
+    Flow:
+      Claude Code
+        -> canicode MCP analyze(input: URL) -> internal REST API fetch -> result
+
+  Use (both routes \u2014 just ask Claude Code):
+    "Analyze this Figma design: https://www.figma.com/design/..."
+
+  Route A vs B:
+    A: No token, 2 MCP servers, Claude orchestrates 2 calls
+    B: Token needed, 1 MCP server, canicode fetches directly
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ 3. CLAUDE SKILLS (lightweight)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Install:
+    cp -r path/to/canicode/.claude/skills/canicode .claude/skills/
+
+  Setup (for REST API):
+    npx canicode init --token figd_xxxxxxxxxxxxx
+
+  Use (in Claude Code):
+    /canicode analyze "https://www.figma.com/design/..."
+
+  Runs CLI under the hood \u2014 all flags work (--mcp, --api, --preset, etc.)
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ TOKEN PRIORITY (all methods)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  1. --token flag (one-time override)
+  2. FIGMA_TOKEN env var (CI/CD)
+  3. ~/.canicode/config.json (canicode init)
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ WHICH ONE SHOULD I USE?
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  CI/CD, automation        -> CLI + FIGMA_TOKEN env var
+  Claude Code, interactive -> MCP Server (Route A)
+  No token, Claude Code    -> MCP Server (Route A)
+  Quick trial              -> Skills
+`.trimStart());
+}
+function printDocsRules() {
+  console.log(`
+CUSTOM RULES GUIDE
+
+Custom rules let you add project-specific checks beyond canicode's built-in 39 rules.
+
+STRUCTURE
+  - id: unique identifier (kebab-case)
+  - category: layout | token | component | naming | ai-readability | handoff-risk
+  - severity: blocking | risk | missing-info | suggestion
+  - score: negative number (-1 to -15)
+  - prompt: what Claude checks for (used in AI-based evaluation)
+  - why: reason this matters
+  - impact: consequence if ignored
+  - fix: how to resolve
+
+EXAMPLE
+  [
+    {
+      "id": "icon-missing-component",
+      "category": "component",
+      "severity": "blocking",
+      "score": -10,
+      "prompt": "Check if this node is an icon (small size, vector children, no text) and is not a component or instance.",
+      "why": "Icon nodes that are not components cannot be reused consistently.",
+      "impact": "Developers will hardcode icons instead of using a shared component.",
+      "fix": "Convert this icon node to a component and publish it to the library."
+    }
+  ]
+
+USAGE
+  canicode analyze <url> --custom-rules ./my-rules.json
+  See full example: examples/custom-rules.json
+`.trimStart());
+}
+function printDocsConfig() {
+  console.log(`
+CONFIG GUIDE
+
+Override canicode's default rule scores, severity, and filters.
+
+STRUCTURE
+  - excludeNodeTypes: node types to skip (e.g. VECTOR, BOOLEAN_OPERATION)
+  - excludeNodeNames: name patterns to skip (e.g. icon, ico)
+  - gridBase: spacing grid unit, default 8
+  - colorTolerance: color diff tolerance, default 10
+  - rules: per-rule overrides (score, severity, enabled)
+
+EXAMPLE
+  {
+    "excludeNodeTypes": [],
+    "excludeNodeNames": [],
+    "gridBase": 4,
+    "rules": {
+      "no-auto-layout": { "score": -15, "severity": "blocking" },
+      "raw-color": { "score": -12 },
+      "default-name": { "enabled": false }
+    }
+  }
+
+USAGE
+  canicode analyze <url> --config ./my-config.json
+  See full example: examples/config.json
+`.trimStart());
+}
+var DOCS_TOPICS = {
+  setup: printDocsSetup,
+  install: printDocsSetup,
+  // alias
+  rules: printDocsRules,
+  config: printDocsConfig
+};
+function handleDocs(topic) {
+  if (!topic) {
+    printDocsIndex();
+    return;
+  }
+  const handler = DOCS_TOPICS[topic];
+  if (handler) {
+    handler();
+  } else {
+    console.error(`Unknown docs topic: ${topic}`);
+    console.error(`Available topics: setup, rules, config`);
+    process.exit(1);
+  }
+}
+
+// src/rules/layout/index.ts
+function isContainerNode(node) {
+  return node.type === "FRAME" || node.type === "GROUP" || node.type === "COMPONENT";
+}
+function hasAutoLayout(node) {
+  return node.layoutMode !== void 0 && node.layoutMode !== "NONE";
+}
+function hasTextContent(node) {
+  return node.type === "TEXT" || (node.children?.some((c) => c.type === "TEXT") ?? false);
+}
+var noAutoLayoutDef = {
+  id: "no-auto-layout",
+  name: "No Auto Layout",
+  category: "layout",
+  why: "Frames without Auto Layout require manual positioning for every element",
+  impact: "Layout breaks on content changes, harder to maintain and scale",
+  fix: "Apply Auto Layout to the frame with appropriate direction and spacing"
+};
+var noAutoLayoutCheck = (node, context) => {
+  if (node.type !== "FRAME") return null;
+  if (hasAutoLayout(node)) return null;
+  if (!node.children || node.children.length === 0) return null;
+  return {
+    ruleId: noAutoLayoutDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `Frame "${node.name}" has no Auto Layout`
+  };
+};
+defineRule({
+  definition: noAutoLayoutDef,
+  check: noAutoLayoutCheck
+});
+var absolutePositionInAutoLayoutDef = {
+  id: "absolute-position-in-auto-layout",
+  name: "Absolute Position in Auto Layout",
+  category: "layout",
+  why: "Absolute positioning inside Auto Layout breaks the automatic flow",
+  impact: "Element will not respond to sibling changes, may overlap unexpectedly",
+  fix: "Remove absolute positioning or use proper Auto Layout alignment"
+};
+var INTENTIONAL_ABSOLUTE_PATTERNS = /^(badge|close|dismiss|overlay|float|fab|dot|indicator|corner|decoration|tag|status|notification|x|icon[-_ ]?(close|dismiss|x)|btn[-_ ]?(close|dismiss))/i;
+function isSmallRelativeToParent(node, parent) {
+  const nodeBB = node.absoluteBoundingBox;
+  const parentBB = parent.absoluteBoundingBox;
+  if (!nodeBB || !parentBB) return false;
+  if (parentBB.width === 0 || parentBB.height === 0) return false;
+  const widthRatio = nodeBB.width / parentBB.width;
+  const heightRatio = nodeBB.height / parentBB.height;
+  return widthRatio < 0.25 && heightRatio < 0.25;
+}
+var absolutePositionInAutoLayoutCheck = (node, context) => {
+  if (!context.parent) return null;
+  if (!hasAutoLayout(context.parent)) return null;
+  if (node.layoutPositioning !== "ABSOLUTE") return null;
+  if (INTENTIONAL_ABSOLUTE_PATTERNS.test(node.name)) return null;
+  if (isSmallRelativeToParent(node, context.parent)) return null;
+  if (context.parent.type === "COMPONENT") return null;
+  return {
+    ruleId: absolutePositionInAutoLayoutDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" uses absolute positioning inside Auto Layout parent "${context.parent.name}". If intentional (badge, overlay, close button), rename to badge-*, overlay-*, close-* to suppress this warning.`
+  };
+};
+defineRule({
+  definition: absolutePositionInAutoLayoutDef,
+  check: absolutePositionInAutoLayoutCheck
+});
+var fixedWidthInResponsiveContextDef = {
+  id: "fixed-width-in-responsive-context",
+  name: "Fixed Width in Responsive Context",
+  category: "layout",
+  why: "Fixed width inside Auto Layout prevents responsive behavior",
+  impact: "Content will not adapt to container size changes",
+  fix: "Use 'Fill' or 'Hug' instead of fixed width"
+};
+var fixedWidthInResponsiveContextCheck = (node, context) => {
+  if (!context.parent) return null;
+  if (!hasAutoLayout(context.parent)) return null;
+  if (!isContainerNode(node)) return null;
+  if (node.layoutAlign === "STRETCH") return null;
+  const bbox = node.absoluteBoundingBox;
+  if (!bbox) return null;
+  if (node.layoutAlign !== "INHERIT") return null;
+  return {
+    ruleId: fixedWidthInResponsiveContextDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" has fixed width inside Auto Layout`
+  };
+};
+defineRule({
+  definition: fixedWidthInResponsiveContextDef,
+  check: fixedWidthInResponsiveContextCheck
+});
+var missingResponsiveBehaviorDef = {
+  id: "missing-responsive-behavior",
+  name: "Missing Responsive Behavior",
+  category: "layout",
+  why: "Elements without constraints won't adapt to different screen sizes",
+  impact: "Layout will break or look wrong on different devices",
+  fix: "Set appropriate constraints (left/right, top/bottom, scale, etc.)"
+};
+var missingResponsiveBehaviorCheck = (node, context) => {
+  if (!isContainerNode(node)) return null;
+  if (context.parent && hasAutoLayout(context.parent)) return null;
+  if (context.depth < 2) return null;
+  if (!hasAutoLayout(node) && !node.layoutAlign) {
+    return {
+      ruleId: missingResponsiveBehaviorDef.id,
+      nodeId: node.id,
+      nodePath: context.path.join(" > "),
+      message: `"${node.name}" has no responsive behavior configured`
+    };
+  }
+  return null;
+};
+defineRule({
+  definition: missingResponsiveBehaviorDef,
+  check: missingResponsiveBehaviorCheck
+});
+var groupUsageDef = {
+  id: "group-usage",
+  name: "Group Usage",
+  category: "layout",
+  why: "Groups don't support Auto Layout and have limited layout control",
+  impact: "Harder to maintain consistent spacing and alignment",
+  fix: "Convert Group to Frame and apply Auto Layout"
+};
+var groupUsageCheck = (node, context) => {
+  if (node.type !== "GROUP") return null;
+  return {
+    ruleId: groupUsageDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" is a Group - consider converting to Frame with Auto Layout`
+  };
+};
+defineRule({
+  definition: groupUsageDef,
+  check: groupUsageCheck
+});
+var fixedSizeInAutoLayoutDef = {
+  id: "fixed-size-in-auto-layout",
+  name: "Fixed Size in Auto Layout",
+  category: "layout",
+  why: "Fixed sizes inside Auto Layout limit flexibility",
+  impact: "Element won't adapt to content or container changes",
+  fix: "Consider using 'Hug' for content-driven sizing"
+};
+var fixedSizeInAutoLayoutCheck = (node, context) => {
+  if (!context.parent) return null;
+  if (!hasAutoLayout(context.parent)) return null;
+  if (!isContainerNode(node)) return null;
+  if (!node.absoluteBoundingBox) return null;
+  const { width, height } = node.absoluteBoundingBox;
+  if (width <= 48 && height <= 48) return null;
+  return null;
+};
+defineRule({
+  definition: fixedSizeInAutoLayoutDef,
+  check: fixedSizeInAutoLayoutCheck
+});
+var missingMinWidthDef = {
+  id: "missing-min-width",
+  name: "Missing Min Width",
+  category: "layout",
+  why: "Without min-width, containers can collapse to unusable sizes",
+  impact: "Text truncation or layout collapse on narrow screens",
+  fix: "Set a minimum width constraint on the container"
+};
+var missingMinWidthCheck = (node, context) => {
+  if (!isContainerNode(node) && !hasTextContent(node)) return null;
+  if (node.absoluteBoundingBox) {
+    const { width, height } = node.absoluteBoundingBox;
+    if (width <= 48 && height <= 24) return null;
+  }
+  if (!context.parent || !hasAutoLayout(context.parent)) return null;
+  return null;
+};
+defineRule({
+  definition: missingMinWidthDef,
+  check: missingMinWidthCheck
+});
+var missingMaxWidthDef = {
+  id: "missing-max-width",
+  name: "Missing Max Width",
+  category: "layout",
+  why: "Without max-width, content can stretch too wide on large screens",
+  impact: "Poor readability and layout on wide screens",
+  fix: "Set a maximum width constraint, especially for text containers"
+};
+var missingMaxWidthCheck = (node, _context) => {
+  if (!isContainerNode(node) && !hasTextContent(node)) return null;
+  if (node.absoluteBoundingBox) {
+    const { width } = node.absoluteBoundingBox;
+    if (width <= 200) return null;
+  }
+  return null;
+};
+defineRule({
+  definition: missingMaxWidthDef,
+  check: missingMaxWidthCheck
+});
+var deepNestingDef = {
+  id: "deep-nesting",
+  name: "Deep Nesting",
+  category: "layout",
+  why: "Deep nesting makes the structure hard to understand and maintain",
+  impact: "Increases complexity, harder to debug layout issues",
+  fix: "Flatten the structure by removing unnecessary wrapper frames"
+};
+var deepNestingCheck = (node, context, options) => {
+  const maxDepth = options?.["maxDepth"] ?? getRuleOption("deep-nesting", "maxDepth", 5);
+  if (context.depth < maxDepth) return null;
+  if (!isContainerNode(node)) return null;
+  return {
+    ruleId: deepNestingDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" is nested ${context.depth} levels deep (max: ${maxDepth})`
+  };
+};
+defineRule({
+  definition: deepNestingDef,
+  check: deepNestingCheck
+});
+var overflowHiddenAbuseDef = {
+  id: "overflow-hidden-abuse",
+  name: "Overflow Hidden Abuse",
+  category: "layout",
+  why: "Using clip content to hide layout problems masks underlying issues",
+  impact: "Content may be unintentionally cut off, problems harder to diagnose",
+  fix: "Fix the underlying layout issue instead of hiding overflow"
+};
+var overflowHiddenAbuseCheck = (_node, _context) => {
+  return null;
+};
+defineRule({
+  definition: overflowHiddenAbuseDef,
+  check: overflowHiddenAbuseCheck
+});
+var inconsistentSiblingLayoutDirectionDef = {
+  id: "inconsistent-sibling-layout-direction",
+  name: "Inconsistent Sibling Layout Direction",
+  category: "layout",
+  why: "Sibling containers with mixed layout directions without clear reason create confusion",
+  impact: "Harder to understand and maintain the design structure",
+  fix: "Use consistent layout direction for similar sibling elements"
+};
+var inconsistentSiblingLayoutDirectionCheck = (node, context) => {
+  if (!isContainerNode(node)) return null;
+  if (!context.siblings || context.siblings.length < 2) return null;
+  const siblingContainers = context.siblings.filter(
+    (s) => isContainerNode(s) && s.id !== node.id
+  );
+  if (siblingContainers.length === 0) return null;
+  const myDirection = node.layoutMode;
+  if (!myDirection || myDirection === "NONE") return null;
+  const siblingDirections = siblingContainers.map((s) => s.layoutMode).filter((d) => d && d !== "NONE");
+  if (siblingDirections.length === 0) return null;
+  const allSameSiblingDirection = siblingDirections.every(
+    (d) => d === siblingDirections[0]
+  );
+  if (allSameSiblingDirection && siblingDirections[0] !== myDirection) {
+    if (context.parent?.layoutMode === "HORIZONTAL" && myDirection === "VERTICAL") {
+      return null;
+    }
+    return {
+      ruleId: inconsistentSiblingLayoutDirectionDef.id,
+      nodeId: node.id,
+      nodePath: context.path.join(" > "),
+      message: `"${node.name}" has ${myDirection} layout while siblings use ${siblingDirections[0]}`
+    };
+  }
+  return null;
+};
+defineRule({
+  definition: inconsistentSiblingLayoutDirectionDef,
+  check: inconsistentSiblingLayoutDirectionCheck
+});
+
+// src/rules/token/index.ts
+function hasStyleReference(node, styleType) {
+  return node.styles !== void 0 && styleType in node.styles;
+}
+function hasBoundVariable(node, key) {
+  return node.boundVariables !== void 0 && key in node.boundVariables;
+}
+function isOnGrid(value, gridBase) {
+  return value % gridBase === 0;
+}
+var rawColorDef = {
+  id: "raw-color",
+  name: "Raw Color",
+  category: "token",
+  why: "Raw hex colors are not connected to the design system",
+  impact: "Color changes require manual updates across the entire design",
+  fix: "Use a color style or variable instead of raw hex values"
+};
+var rawColorCheck = (node, context) => {
+  if (!node.fills || !Array.isArray(node.fills)) return null;
+  if (node.fills.length === 0) return null;
+  if (hasStyleReference(node, "fill")) return null;
+  if (hasBoundVariable(node, "fills")) return null;
+  for (const fill of node.fills) {
+    const fillObj = fill;
+    if (fillObj["type"] === "SOLID" && fillObj["color"]) {
+      return {
+        ruleId: rawColorDef.id,
+        nodeId: node.id,
+        nodePath: context.path.join(" > "),
+        message: `"${node.name}" uses raw color without style or variable`
+      };
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: rawColorDef,
+  check: rawColorCheck
+});
+var rawFontDef = {
+  id: "raw-font",
+  name: "Raw Font",
+  category: "token",
+  why: "Text without text styles is disconnected from the type system",
+  impact: "Typography changes require manual updates across the design",
+  fix: "Apply a text style to maintain consistency"
+};
+var rawFontCheck = (node, context) => {
+  if (node.type !== "TEXT") return null;
+  if (hasStyleReference(node, "text")) return null;
+  if (hasBoundVariable(node, "fontFamily") || hasBoundVariable(node, "fontSize")) {
+    return null;
+  }
+  return {
+    ruleId: rawFontDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" has no text style applied`
+  };
+};
+defineRule({
+  definition: rawFontDef,
+  check: rawFontCheck
+});
+var inconsistentSpacingDef = {
+  id: "inconsistent-spacing",
+  name: "Inconsistent Spacing",
+  category: "token",
+  why: "Spacing values outside the grid system break visual consistency",
+  impact: "Inconsistent visual rhythm and harder to maintain",
+  fix: "Use spacing values from the design system grid (e.g., 8pt increments)"
+};
+var inconsistentSpacingCheck = (node, context, options) => {
+  const gridBase = options?.["gridBase"] ?? getRuleOption("inconsistent-spacing", "gridBase", 8);
+  const paddings = [
+    node.paddingLeft,
+    node.paddingRight,
+    node.paddingTop,
+    node.paddingBottom
+  ].filter((p) => p !== void 0 && p > 0);
+  for (const padding of paddings) {
+    if (!isOnGrid(padding, gridBase)) {
+      return {
+        ruleId: inconsistentSpacingDef.id,
+        nodeId: node.id,
+        nodePath: context.path.join(" > "),
+        message: `"${node.name}" has padding ${padding}px not on ${gridBase}pt grid`
+      };
+    }
+  }
+  if (node.itemSpacing !== void 0 && node.itemSpacing > 0) {
+    if (!isOnGrid(node.itemSpacing, gridBase)) {
+      return {
+        ruleId: inconsistentSpacingDef.id,
+        nodeId: node.id,
+        nodePath: context.path.join(" > "),
+        message: `"${node.name}" has item spacing ${node.itemSpacing}px not on ${gridBase}pt grid`
+      };
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: inconsistentSpacingDef,
+  check: inconsistentSpacingCheck
+});
+var magicNumberSpacingDef = {
+  id: "magic-number-spacing",
+  name: "Magic Number Spacing",
+  category: "token",
+  why: "Arbitrary spacing values make the system harder to understand",
+  impact: "Unpredictable spacing, harder to create consistent layouts",
+  fix: "Round spacing to the nearest grid value or use spacing tokens"
+};
+var magicNumberSpacingCheck = (node, context, options) => {
+  const gridBase = options?.["gridBase"] ?? getRuleOption("magic-number-spacing", "gridBase", 8);
+  const allSpacings = [
+    node.paddingLeft,
+    node.paddingRight,
+    node.paddingTop,
+    node.paddingBottom,
+    node.itemSpacing
+  ].filter((s) => s !== void 0 && s > 0);
+  for (const spacing of allSpacings) {
+    const commonValues = [1, 2, 4];
+    if (!isOnGrid(spacing, gridBase) && !commonValues.includes(spacing)) {
+      if (spacing % 2 !== 0 && spacing > 4) {
+        return {
+          ruleId: magicNumberSpacingDef.id,
+          nodeId: node.id,
+          nodePath: context.path.join(" > "),
+          message: `"${node.name}" uses magic number spacing: ${spacing}px`
+        };
+      }
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: magicNumberSpacingDef,
+  check: magicNumberSpacingCheck
+});
+var rawShadowDef = {
+  id: "raw-shadow",
+  name: "Raw Shadow",
+  category: "token",
+  why: "Shadow effects without styles are disconnected from the design system",
+  impact: "Shadow changes require manual updates across the design",
+  fix: "Create and apply an effect style for shadows"
+};
+var rawShadowCheck = (node, context) => {
+  if (!node.effects || !Array.isArray(node.effects)) return null;
+  if (node.effects.length === 0) return null;
+  if (hasStyleReference(node, "effect")) return null;
+  for (const effect of node.effects) {
+    const effectObj = effect;
+    if (effectObj["type"] === "DROP_SHADOW" || effectObj["type"] === "INNER_SHADOW") {
+      return {
+        ruleId: rawShadowDef.id,
+        nodeId: node.id,
+        nodePath: context.path.join(" > "),
+        message: `"${node.name}" has shadow effect without effect style`
+      };
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: rawShadowDef,
+  check: rawShadowCheck
+});
+var rawOpacityDef = {
+  id: "raw-opacity",
+  name: "Raw Opacity",
+  category: "token",
+  why: "Hardcoded opacity values are not connected to design tokens",
+  impact: "Opacity changes require manual updates",
+  fix: "Use opacity variables or consider if opacity is truly needed"
+};
+var rawOpacityCheck = (node, _context) => {
+  if (hasBoundVariable(node, "opacity")) return null;
+  return null;
+};
+defineRule({
+  definition: rawOpacityDef,
+  check: rawOpacityCheck
+});
+var multipleFillColorsDef = {
+  id: "multiple-fill-colors",
+  name: "Multiple Fill Colors",
+  category: "token",
+  why: "Similar but slightly different colors indicate inconsistent token usage",
+  impact: "Visual inconsistency and harder to maintain brand colors",
+  fix: "Consolidate to a single color token or style"
+};
+var multipleFillColorsCheck = (_node, _context, _options) => {
+  return null;
+};
+defineRule({
+  definition: multipleFillColorsDef,
+  check: multipleFillColorsCheck
+});
+
+// src/rules/component/index.ts
+function isComponentInstance(node) {
+  return node.type === "INSTANCE";
+}
+function isComponent(node) {
+  return node.type === "COMPONENT" || node.type === "COMPONENT_SET";
+}
+function collectFrameNames(node, names = /* @__PURE__ */ new Map()) {
+  if (node.type === "FRAME" && node.name) {
+    const existing = names.get(node.name) ?? [];
+    existing.push(node.id);
+    names.set(node.name, existing);
+  }
+  if (node.children) {
+    for (const child of node.children) {
+      collectFrameNames(child, names);
+    }
+  }
+  return names;
+}
+var missingComponentDef = {
+  id: "missing-component",
+  name: "Missing Component",
+  category: "component",
+  why: "Repeated identical structures should be componentized",
+  impact: "Changes require manual updates in multiple places",
+  fix: "Create a component from the repeated structure"
+};
+var missingComponentCheck = (node, context, options) => {
+  if (node.type !== "FRAME") return null;
+  const minRepetitions = options?.["minRepetitions"] ?? getRuleOption("missing-component", "minRepetitions", 3);
+  const frameNames = collectFrameNames(context.file.document);
+  const sameNameFrames = frameNames.get(node.name);
+  if (sameNameFrames && sameNameFrames.length >= minRepetitions) {
+    if (sameNameFrames[0] === node.id) {
+      return {
+        ruleId: missingComponentDef.id,
+        nodeId: node.id,
+        nodePath: context.path.join(" > "),
+        message: `"${node.name}" appears ${sameNameFrames.length} times - consider making it a component`
+      };
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: missingComponentDef,
+  check: missingComponentCheck
+});
+var detachedInstanceDef = {
+  id: "detached-instance",
+  name: "Detached Instance",
+  category: "component",
+  why: "Detached instances lose their connection to the source component",
+  impact: "Updates to the component won't propagate to this instance",
+  fix: "Reset the instance or create a new variant if customization is needed"
+};
+var detachedInstanceCheck = (node, context) => {
+  if (node.type !== "FRAME") return null;
+  const components = context.file.components;
+  const nodeName = node.name.toLowerCase();
+  for (const [, component] of Object.entries(components)) {
+    if (nodeName.includes(component.name.toLowerCase())) {
+      return {
+        ruleId: detachedInstanceDef.id,
+        nodeId: node.id,
+        nodePath: context.path.join(" > "),
+        message: `"${node.name}" may be a detached instance of component "${component.name}"`
+      };
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: detachedInstanceDef,
+  check: detachedInstanceCheck
+});
+var nestedInstanceOverrideDef = {
+  id: "nested-instance-override",
+  name: "Nested Instance Override",
+  category: "component",
+  why: "Excessive overrides in instances make components harder to maintain",
+  impact: "Component updates may not work as expected",
+  fix: "Create a variant or new component for significantly different use cases"
+};
+var nestedInstanceOverrideCheck = (node, context) => {
+  if (!isComponentInstance(node)) return null;
+  if (!node.componentProperties) return null;
+  const overrideCount = Object.keys(node.componentProperties).length;
+  if (overrideCount > 5) {
+    return {
+      ruleId: nestedInstanceOverrideDef.id,
+      nodeId: node.id,
+      nodePath: context.path.join(" > "),
+      message: `"${node.name}" has ${overrideCount} property overrides - consider creating a variant`
+    };
+  }
+  return null;
+};
+defineRule({
+  definition: nestedInstanceOverrideDef,
+  check: nestedInstanceOverrideCheck
+});
+var variantNotUsedDef = {
+  id: "variant-not-used",
+  name: "Variant Not Used",
+  category: "component",
+  why: "Using instances but not leveraging variants defeats their purpose",
+  impact: "Manual changes instead of using designed variants",
+  fix: "Use the appropriate variant instead of overriding the default"
+};
+var variantNotUsedCheck = (_node, _context) => {
+  return null;
+};
+defineRule({
+  definition: variantNotUsedDef,
+  check: variantNotUsedCheck
+});
+var componentPropertyUnusedDef = {
+  id: "component-property-unused",
+  name: "Component Property Unused",
+  category: "component",
+  why: "Component properties should be utilized to expose customization",
+  impact: "Hardcoded values that should be configurable",
+  fix: "Connect the value to a component property"
+};
+var componentPropertyUnusedCheck = (node, _context) => {
+  if (!isComponent(node)) return null;
+  if (!node.componentPropertyDefinitions) return null;
+  const definedProps = Object.keys(node.componentPropertyDefinitions);
+  if (definedProps.length === 0) return null;
+  return null;
+};
+defineRule({
+  definition: componentPropertyUnusedDef,
+  check: componentPropertyUnusedCheck
+});
+var singleUseComponentDef = {
+  id: "single-use-component",
+  name: "Single Use Component",
+  category: "component",
+  why: "Components used only once add complexity without reuse benefit",
+  impact: "Unnecessary abstraction increases maintenance overhead",
+  fix: "Consider inlining if this component won't be reused"
+};
+var singleUseComponentCheck = (node, context) => {
+  if (!isComponent(node)) return null;
+  let instanceCount = 0;
+  function countInstances(n) {
+    if (n.type === "INSTANCE" && n.componentId === node.id) {
+      instanceCount++;
+    }
+    if (n.children) {
+      for (const child of n.children) {
+        countInstances(child);
+      }
+    }
+  }
+  countInstances(context.file.document);
+  if (instanceCount === 1) {
+    return {
+      ruleId: singleUseComponentDef.id,
+      nodeId: node.id,
+      nodePath: context.path.join(" > "),
+      message: `Component "${node.name}" is only used once`
+    };
+  }
+  return null;
+};
+defineRule({
+  definition: singleUseComponentDef,
+  check: singleUseComponentCheck
+});
+
+// src/rules/naming/index.ts
+var DEFAULT_NAME_PATTERNS = [
+  /^Frame\s*\d*$/i,
+  /^Group\s*\d*$/i,
+  /^Rectangle\s*\d*$/i,
+  /^Ellipse\s*\d*$/i,
+  /^Vector\s*\d*$/i,
+  /^Line\s*\d*$/i,
+  /^Text\s*\d*$/i,
+  /^Image\s*\d*$/i,
+  /^Component\s*\d*$/i,
+  /^Instance\s*\d*$/i
+];
+var NON_SEMANTIC_NAMES = [
+  "rectangle",
+  "ellipse",
+  "vector",
+  "line",
+  "polygon",
+  "star",
+  "path",
+  "shape",
+  "image",
+  "fill",
+  "stroke"
+];
+function isDefaultName(name) {
+  return DEFAULT_NAME_PATTERNS.some((pattern) => pattern.test(name));
+}
+function isNonSemanticName(name) {
+  const normalized = name.toLowerCase().trim();
+  return NON_SEMANTIC_NAMES.includes(normalized);
+}
+function hasNumericSuffix(name) {
+  return /\s+\d+$/.test(name);
+}
+function detectNamingConvention(name) {
+  if (/^[a-z]+(-[a-z]+)*$/.test(name)) return "kebab-case";
+  if (/^[a-z]+(_[a-z]+)*$/.test(name)) return "snake_case";
+  if (/^[a-z]+([A-Z][a-z]*)*$/.test(name)) return "camelCase";
+  if (/^[A-Z][a-z]+([A-Z][a-z]*)*$/.test(name)) return "PascalCase";
+  if (/^[A-Z]+(_[A-Z]+)*$/.test(name)) return "SCREAMING_SNAKE_CASE";
+  if (/\s/.test(name)) return "Title Case";
+  return null;
+}
+var defaultNameDef = {
+  id: "default-name",
+  name: "Default Name",
+  category: "naming",
+  why: "Default names like 'Frame 123' provide no context about the element's purpose",
+  impact: "Designers and developers cannot understand the structure",
+  fix: "Rename with a descriptive, semantic name (e.g., 'Header', 'ProductCard')"
+};
+var defaultNameCheck = (node, context) => {
+  if (!node.name) return null;
+  if (!isDefaultName(node.name)) return null;
+  return {
+    ruleId: defaultNameDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" is a default name - provide a meaningful name`
+  };
+};
+defineRule({
+  definition: defaultNameDef,
+  check: defaultNameCheck
+});
+var nonSemanticNameDef = {
+  id: "non-semantic-name",
+  name: "Non-Semantic Name",
+  category: "naming",
+  why: "Names like 'Rectangle' describe shape, not purpose",
+  impact: "Structure is hard to understand without context",
+  fix: "Use names that describe what the element represents (e.g., 'Divider', 'Avatar')"
+};
+var nonSemanticNameCheck = (node, context) => {
+  if (!node.name) return null;
+  if (!isNonSemanticName(node.name)) return null;
+  if (!node.children || node.children.length === 0) {
+    const shapeTypes = ["RECTANGLE", "ELLIPSE", "VECTOR", "LINE", "STAR", "REGULAR_POLYGON"];
+    if (shapeTypes.includes(node.type)) return null;
+  }
+  return {
+    ruleId: nonSemanticNameDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" is a non-semantic name - describe its purpose`
+  };
+};
+defineRule({
+  definition: nonSemanticNameDef,
+  check: nonSemanticNameCheck
+});
+var inconsistentNamingConventionDef = {
+  id: "inconsistent-naming-convention",
+  name: "Inconsistent Naming Convention",
+  category: "naming",
+  why: "Mixed naming conventions at the same level create confusion",
+  impact: "Harder to navigate and maintain the design",
+  fix: "Use a consistent naming convention for sibling elements"
+};
+var inconsistentNamingConventionCheck = (node, context) => {
+  if (!context.siblings || context.siblings.length < 2) return null;
+  const conventions = /* @__PURE__ */ new Map();
+  for (const sibling of context.siblings) {
+    if (!sibling.name) continue;
+    const convention = detectNamingConvention(sibling.name);
+    if (convention) {
+      conventions.set(convention, (conventions.get(convention) ?? 0) + 1);
+    }
+  }
+  if (conventions.size < 2) return null;
+  let dominantConvention = "";
+  let maxCount = 0;
+  for (const [convention, count] of conventions) {
+    if (count > maxCount) {
+      maxCount = count;
+      dominantConvention = convention;
+    }
+  }
+  const nodeConvention = detectNamingConvention(node.name);
+  if (nodeConvention && nodeConvention !== dominantConvention && maxCount >= 2) {
+    return {
+      ruleId: inconsistentNamingConventionDef.id,
+      nodeId: node.id,
+      nodePath: context.path.join(" > "),
+      message: `"${node.name}" uses ${nodeConvention} while siblings use ${dominantConvention}`
+    };
+  }
+  return null;
+};
+defineRule({
+  definition: inconsistentNamingConventionDef,
+  check: inconsistentNamingConventionCheck
+});
+var numericSuffixNameDef = {
+  id: "numeric-suffix-name",
+  name: "Numeric Suffix Name",
+  category: "naming",
+  why: "Names with numeric suffixes often indicate copy-paste duplication",
+  impact: "Suggests the element might need componentization",
+  fix: "Remove the suffix or create a component if duplicated"
+};
+var numericSuffixNameCheck = (node, context) => {
+  if (!node.name) return null;
+  if (isDefaultName(node.name)) return null;
+  if (!hasNumericSuffix(node.name)) return null;
+  return {
+    ruleId: numericSuffixNameDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" has a numeric suffix - consider renaming`
+  };
+};
+defineRule({
+  definition: numericSuffixNameDef,
+  check: numericSuffixNameCheck
+});
+var tooLongNameDef = {
+  id: "too-long-name",
+  name: "Too Long Name",
+  category: "naming",
+  why: "Very long names are hard to read and use in code",
+  impact: "Clutters the layer panel and makes selectors unwieldy",
+  fix: "Shorten the name while keeping it descriptive"
+};
+var tooLongNameCheck = (node, context, options) => {
+  if (!node.name) return null;
+  const maxLength = options?.["maxLength"] ?? getRuleOption("too-long-name", "maxLength", 50);
+  if (node.name.length <= maxLength) return null;
+  return {
+    ruleId: tooLongNameDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name.substring(0, 30)}..." is ${node.name.length} chars (max: ${maxLength})`
+  };
+};
+defineRule({
+  definition: tooLongNameDef,
+  check: tooLongNameCheck
+});
+
+// src/rules/ai-readability/index.ts
+function hasAutoLayout2(node) {
+  return node.layoutMode !== void 0 && node.layoutMode !== "NONE";
+}
+function isContainerNode2(node) {
+  return node.type === "FRAME" || node.type === "GROUP" || node.type === "COMPONENT";
+}
+function hasOverlappingBounds(a, b) {
+  const boxA = a.absoluteBoundingBox;
+  const boxB = b.absoluteBoundingBox;
+  if (!boxA || !boxB) return false;
+  return !(boxA.x + boxA.width <= boxB.x || boxB.x + boxB.width <= boxA.x || boxA.y + boxA.height <= boxB.y || boxB.y + boxB.height <= boxA.y);
+}
+var ambiguousStructureDef = {
+  id: "ambiguous-structure",
+  name: "Ambiguous Structure",
+  category: "ai-readability",
+  why: "Overlapping nodes without Auto Layout create ambiguous visual hierarchy",
+  impact: "AI cannot reliably determine the reading order or structure",
+  fix: "Use Auto Layout to create clear, explicit structure"
+};
+var ambiguousStructureCheck = (node, context) => {
+  if (!isContainerNode2(node)) return null;
+  if (hasAutoLayout2(node)) return null;
+  if (!node.children || node.children.length < 2) return null;
+  for (let i = 0; i < node.children.length; i++) {
+    for (let j = i + 1; j < node.children.length; j++) {
+      const childA = node.children[i];
+      const childB = node.children[j];
+      if (childA && childB && hasOverlappingBounds(childA, childB)) {
+        if (childA.visible !== false && childB.visible !== false) {
+          return {
+            ruleId: ambiguousStructureDef.id,
+            nodeId: node.id,
+            nodePath: context.path.join(" > "),
+            message: `"${node.name}" has overlapping children without Auto Layout`
+          };
+        }
+      }
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: ambiguousStructureDef,
+  check: ambiguousStructureCheck
+});
+var zIndexDependentLayoutDef = {
+  id: "z-index-dependent-layout",
+  name: "Z-Index Dependent Layout",
+  category: "ai-readability",
+  why: "Using overlapping layers to create visual layout is hard to interpret",
+  impact: "Code generation may misinterpret the intended layout",
+  fix: "Restructure using Auto Layout to express the visual relationship explicitly"
+};
+var zIndexDependentLayoutCheck = (node, context) => {
+  if (!isContainerNode2(node)) return null;
+  if (!node.children || node.children.length < 2) return null;
+  let significantOverlapCount = 0;
+  for (let i = 0; i < node.children.length; i++) {
+    for (let j = i + 1; j < node.children.length; j++) {
+      const childA = node.children[i];
+      const childB = node.children[j];
+      if (!childA || !childB) continue;
+      if (childA.visible === false || childB.visible === false) continue;
+      const boxA = childA.absoluteBoundingBox;
+      const boxB = childB.absoluteBoundingBox;
+      if (!boxA || !boxB) continue;
+      if (hasOverlappingBounds(childA, childB)) {
+        const overlapX = Math.min(boxA.x + boxA.width, boxB.x + boxB.width) - Math.max(boxA.x, boxB.x);
+        const overlapY = Math.min(boxA.y + boxA.height, boxB.y + boxB.height) - Math.max(boxA.y, boxB.y);
+        if (overlapX > 0 && overlapY > 0) {
+          const overlapArea = overlapX * overlapY;
+          const smallerArea = Math.min(
+            boxA.width * boxA.height,
+            boxB.width * boxB.height
+          );
+          if (overlapArea > smallerArea * 0.2) {
+            significantOverlapCount++;
+          }
+        }
+      }
+    }
+  }
+  if (significantOverlapCount > 0) {
+    return {
+      ruleId: zIndexDependentLayoutDef.id,
+      nodeId: node.id,
+      nodePath: context.path.join(" > "),
+      message: `"${node.name}" uses layer stacking for layout (${significantOverlapCount} overlaps)`
+    };
+  }
+  return null;
+};
+defineRule({
+  definition: zIndexDependentLayoutDef,
+  check: zIndexDependentLayoutCheck
+});
+var missingLayoutHintDef = {
+  id: "missing-layout-hint",
+  name: "Missing Layout Hint",
+  category: "ai-readability",
+  why: "Complex nesting without Auto Layout makes structure unpredictable",
+  impact: "AI may generate incorrect code due to ambiguous relationships",
+  fix: "Add Auto Layout or simplify the nesting structure"
+};
+var missingLayoutHintCheck = (node, context) => {
+  if (!isContainerNode2(node)) return null;
+  if (hasAutoLayout2(node)) return null;
+  if (!node.children || node.children.length === 0) return null;
+  const nestedContainers = node.children.filter((c) => isContainerNode2(c));
+  if (nestedContainers.length >= 2) {
+    const withoutLayout = nestedContainers.filter((c) => !hasAutoLayout2(c));
+    if (withoutLayout.length >= 2) {
+      return {
+        ruleId: missingLayoutHintDef.id,
+        nodeId: node.id,
+        nodePath: context.path.join(" > "),
+        message: `"${node.name}" has ${withoutLayout.length} nested containers without layout hints`
+      };
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: missingLayoutHintDef,
+  check: missingLayoutHintCheck
+});
+var invisibleLayerDef = {
+  id: "invisible-layer",
+  name: "Invisible Layer",
+  category: "ai-readability",
+  why: "Hidden layers add noise and may confuse analysis tools",
+  impact: "Exported code may include unnecessary elements",
+  fix: "Delete hidden layers or move them to a separate 'archive' page"
+};
+var invisibleLayerCheck = (node, context) => {
+  if (node.visible !== false) return null;
+  if (context.parent?.visible === false) return null;
+  return {
+    ruleId: invisibleLayerDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" is hidden - consider removing if not needed`
+  };
+};
+defineRule({
+  definition: invisibleLayerDef,
+  check: invisibleLayerCheck
+});
+var emptyFrameDef = {
+  id: "empty-frame",
+  name: "Empty Frame",
+  category: "ai-readability",
+  why: "Empty frames add noise and may indicate incomplete design",
+  impact: "Generates unnecessary wrapper elements in code",
+  fix: "Remove the frame or add content"
+};
+var emptyFrameCheck = (node, context) => {
+  if (node.type !== "FRAME") return null;
+  if (node.children && node.children.length > 0) return null;
+  if (node.absoluteBoundingBox) {
+    const { width, height } = node.absoluteBoundingBox;
+    if (width <= 48 && height <= 48) return null;
+  }
+  return {
+    ruleId: emptyFrameDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" is an empty frame`
+  };
+};
+defineRule({
+  definition: emptyFrameDef,
+  check: emptyFrameCheck
+});
+
+// src/rules/handoff-risk/index.ts
+function hasAutoLayout3(node) {
+  return node.layoutMode !== void 0 && node.layoutMode !== "NONE";
+}
+function isContainerNode3(node) {
+  return node.type === "FRAME" || node.type === "GROUP" || node.type === "COMPONENT";
+}
+function isTextNode(node) {
+  return node.type === "TEXT";
+}
+function isImageNode(node) {
+  if (node.type === "RECTANGLE" && node.fills) {
+    for (const fill of node.fills) {
+      const fillObj = fill;
+      if (fillObj["type"] === "IMAGE") return true;
+    }
+  }
+  return false;
+}
+var hardcodeRiskDef = {
+  id: "hardcode-risk",
+  name: "Hardcode Risk",
+  category: "handoff-risk",
+  why: "Absolute positioning with fixed values creates inflexible layouts",
+  impact: "Layout will break when content changes or on different screens",
+  fix: "Use Auto Layout with relative positioning"
+};
+var hardcodeRiskCheck = (node, context) => {
+  if (!isContainerNode3(node)) return null;
+  if (node.layoutPositioning !== "ABSOLUTE") return null;
+  if (context.parent && hasAutoLayout3(context.parent)) {
+    return {
+      ruleId: hardcodeRiskDef.id,
+      nodeId: node.id,
+      nodePath: context.path.join(" > "),
+      message: `"${node.name}" uses absolute positioning with fixed values`
+    };
+  }
+  return null;
+};
+defineRule({
+  definition: hardcodeRiskDef,
+  check: hardcodeRiskCheck
+});
+var textTruncationUnhandledDef = {
+  id: "text-truncation-unhandled",
+  name: "Text Truncation Unhandled",
+  category: "handoff-risk",
+  why: "Text nodes without truncation handling may overflow",
+  impact: "Long text will break the layout",
+  fix: "Set text truncation (ellipsis) or ensure container can grow"
+};
+var textTruncationUnhandledCheck = (node, context) => {
+  if (!isTextNode(node)) return null;
+  if (!context.parent) return null;
+  if (!hasAutoLayout3(context.parent)) return null;
+  if (node.absoluteBoundingBox) {
+    const { width } = node.absoluteBoundingBox;
+    if (node.characters && node.characters.length > 50 && width < 300) {
+      return {
+        ruleId: textTruncationUnhandledDef.id,
+        nodeId: node.id,
+        nodePath: context.path.join(" > "),
+        message: `"${node.name}" may need text truncation handling`
+      };
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: textTruncationUnhandledDef,
+  check: textTruncationUnhandledCheck
+});
+var imageNoPlaceholderDef = {
+  id: "image-no-placeholder",
+  name: "Image No Placeholder",
+  category: "handoff-risk",
+  why: "Images without placeholder state may cause layout shifts",
+  impact: "Poor user experience during image loading",
+  fix: "Define a placeholder state or background color"
+};
+var imageNoPlaceholderCheck = (node, context) => {
+  if (!isImageNode(node)) return null;
+  if (node.fills && Array.isArray(node.fills) && node.fills.length === 1) {
+    const fill = node.fills[0];
+    if (fill["type"] === "IMAGE") {
+      return {
+        ruleId: imageNoPlaceholderDef.id,
+        nodeId: node.id,
+        nodePath: context.path.join(" > "),
+        message: `"${node.name}" image has no placeholder fill`
+      };
+    }
+  }
+  return null;
+};
+defineRule({
+  definition: imageNoPlaceholderDef,
+  check: imageNoPlaceholderCheck
+});
+var prototypeLinkInDesignDef = {
+  id: "prototype-link-in-design",
+  name: "Prototype Link in Design",
+  category: "handoff-risk",
+  why: "Prototype connections may affect how the design is interpreted",
+  impact: "Developers may misunderstand which elements should be interactive",
+  fix: "Document interactions separately or use clear naming"
+};
+var prototypeLinkInDesignCheck = (_node, _context) => {
+  return null;
+};
+defineRule({
+  definition: prototypeLinkInDesignDef,
+  check: prototypeLinkInDesignCheck
+});
+var noDevStatusDef = {
+  id: "no-dev-status",
+  name: "No Dev Status",
+  category: "handoff-risk",
+  why: "Without dev status, developers cannot know if a design is ready",
+  impact: "May implement designs that are still in progress",
+  fix: "Mark frames as 'Ready for Dev' or 'Completed' when appropriate"
+};
+var noDevStatusCheck = (node, context) => {
+  if (node.type !== "FRAME") return null;
+  if (context.depth > 1) return null;
+  if (node.devStatus) return null;
+  return {
+    ruleId: noDevStatusDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `"${node.name}" has no dev status set`
+  };
+};
+defineRule({
+  definition: noDevStatusDef,
+  check: noDevStatusCheck
+});
+
+// src/cli/index.ts
+config();
+var cli = cac("canicode");
+var MAX_NODES_WITHOUT_SCOPE = 500;
+function pickRandomScope(root) {
+  const candidates = [];
+  function collect(node) {
+    const isContainer = node.type === "FRAME" || node.type === "COMPONENT" || node.type === "SECTION";
+    if (isContainer) {
+      const size = countNodes2(node);
+      if (size >= 50 && size <= 500) {
+        candidates.push(node);
+      }
+    }
+    if ("children" in node && node.children) {
+      for (const child of node.children) {
+        collect(child);
+      }
+    }
+  }
+  collect(root);
+  if (candidates.length === 0) return null;
+  const idx = Math.floor(Math.random() * candidates.length);
+  return candidates[idx] ?? null;
+}
+function countNodes2(node) {
+  let count = 1;
+  if (node.children) {
+    for (const child of node.children) {
+      count += countNodes2(child);
+    }
+  }
+  return count;
+}
+cli.command("analyze <input>", "Analyze a Figma file or JSON fixture").option("--preset <preset>", "Analysis preset (relaxed | dev-friendly | ai-ready | strict)").option("--output <path>", "HTML report output path").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option("--mcp", "Load via Figma MCP (no FIGMA_TOKEN needed)").option("--api", "Load via Figma REST API (requires FIGMA_TOKEN)").option("--screenshot", "Include screenshot comparison in report (requires ANTHROPIC_API_KEY)").option("--custom-rules <path>", "Path to custom rules JSON file").option("--config <path>", "Path to config JSON file (override rule scores/settings)").option("--no-open", "Don't open report in browser after analysis").example("  canicode analyze https://www.figma.com/design/ABC123/MyDesign").example("  canicode analyze https://www.figma.com/design/ABC123/MyDesign --mcp").example("  canicode analyze https://www.figma.com/design/ABC123/MyDesign --api --token YOUR_TOKEN").example("  canicode analyze ./fixtures/design.json --output report.html").example("  canicode analyze ./fixtures/design.json --custom-rules ./my-rules.json").example("  canicode analyze ./fixtures/design.json --config ./my-config.json").action(async (input, options) => {
+  try {
+    if (options.mcp && options.api) {
+      throw new Error("Cannot use --mcp and --api together. Choose one.");
+    }
+    if (!options.mcp && !options.token && !getFigmaToken() && !isJsonFile(input)) {
+      throw new Error(
+        "canicode is not configured. Run 'canicode init --token YOUR_TOKEN' first.\nOr use --mcp flag for Figma MCP mode (no token needed)."
+      );
+    }
+    if (options.screenshot) {
+      const anthropicKey = process.env["ANTHROPIC_API_KEY"];
+      if (!anthropicKey) {
+        throw new Error(
+          "ANTHROPIC_API_KEY required for --screenshot mode. Set it in .env or environment."
+        );
+      }
+      console.log("Screenshot comparison mode enabled (coming soon).\n");
+    }
+    const mode = options.mcp ? "mcp" : options.api ? "api" : "auto";
+    const { file, nodeId } = await loadFile(input, options.token, mode);
+    const totalNodes = countNodes2(file.document);
+    let effectiveNodeId = nodeId;
+    if (!effectiveNodeId && totalNodes > MAX_NODES_WITHOUT_SCOPE) {
+      if (isJsonFile(input)) {
+        const picked = pickRandomScope(file.document);
+        if (picked) {
+          effectiveNodeId = picked.id;
+          console.log(`
+Auto-scoped to "${picked.name}" (${picked.id}, ${countNodes2(picked)} nodes) \u2014 file too large (${totalNodes} nodes) for unscoped analysis.`);
+        } else {
+          console.warn(`
+Warning: Could not find a suitable scope in fixture. Analyzing all ${totalNodes} nodes.`);
+        }
+      } else {
+        throw new Error(
+          `Too many nodes (${totalNodes}) for unscoped analysis. Max ${MAX_NODES_WITHOUT_SCOPE} nodes without a node-id scope.
+
+Add ?node-id=XXX to the Figma URL to target a specific section.
+Example: canicode analyze "https://www.figma.com/design/.../MyDesign?node-id=1-234"`
+        );
+      }
+    }
+    if (!effectiveNodeId && totalNodes > 100) {
+      console.warn(`
+Warning: Analyzing ${totalNodes} nodes without scope. Results may be noisy.`);
+      console.warn("Tip: Add ?node-id=XXX to analyze a specific section.\n");
+    }
+    console.log(`
+Analyzing: ${file.name}`);
+    console.log(`Nodes: ${totalNodes}`);
+    let configs = options.preset ? { ...getConfigsWithPreset(options.preset) } : { ...RULE_CONFIGS };
+    if (options.config) {
+      const configFile = await loadConfigFile(options.config);
+      configs = mergeConfigs(configs, configFile);
+      console.log(`Config loaded: ${options.config}`);
+    }
+    if (options.customRules) {
+      const { rules, configs: customConfigs } = await loadCustomRules(options.customRules);
+      for (const rule of rules) {
+        ruleRegistry.register(rule);
+      }
+      configs = { ...configs, ...customConfigs };
+      console.log(`Custom rules loaded: ${rules.length} rules from ${options.customRules}`);
+    }
+    const analyzeOptions = {
+      configs,
+      ...effectiveNodeId && { targetNodeId: effectiveNodeId }
+    };
+    const result = analyzeFile(file, analyzeOptions);
+    console.log(`Nodes: ${result.nodeCount} (max depth: ${result.maxDepth})`);
+    const scores = calculateScores(result);
+    console.log("\n" + "=".repeat(50));
+    console.log(formatScoreSummary(scores));
+    console.log("=".repeat(50));
+    const now = /* @__PURE__ */ new Date();
+    const ts = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}-${String(now.getHours()).padStart(2, "0")}-${String(now.getMinutes()).padStart(2, "0")}`;
+    let outputPath;
+    if (options.output) {
+      outputPath = resolve(options.output);
+      const outputDir = dirname(outputPath);
+      if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+      }
+    } else {
+      ensureReportsDir();
+      outputPath = resolve(getReportsDir(), `report-${ts}-${file.fileKey}.html`);
+    }
+    const figmaToken = options.token ?? getFigmaToken();
+    const html = generateHtmlReport(file, result, scores, { figmaToken });
+    await writeFile(outputPath, html, "utf-8");
+    console.log(`
+Report saved: ${outputPath}`);
+    if (!options.noOpen) {
+      const { exec } = await import('child_process');
+      const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+      exec(`${cmd} "${outputPath}"`);
+    }
+    if (scores.overall.grade === "F") {
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(
+      "\nError:",
+      error instanceof Error ? error.message : String(error)
+    );
+    process.exit(1);
+  }
+});
+cli.command(
+  "calibrate-analyze <input>",
+  "Run calibration analysis and output JSON for conversion step"
+).option("--output <path>", "Output JSON path", { default: "logs/calibration/calibration-analysis.json" }).option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option("--target-node-id <nodeId>", "Scope analysis to a specific node").action(async (input, options) => {
+  try {
+    console.log("Running calibration analysis...");
+    const calibConfig = {
+      input,
+      maxConversionNodes: 20,
+      samplingStrategy: "top-issues",
+      outputPath: "logs/calibration/calibration-report.md",
+      ...options.token && { token: options.token },
+      ...options.targetNodeId && { targetNodeId: options.targetNodeId }
+    };
+    const { analysisOutput, ruleScores, fileKey } = await runCalibrationAnalyze(calibConfig);
+    const filteredSummaries = filterConversionCandidates(
+      analysisOutput.nodeIssueSummaries,
+      analysisOutput.analysisResult.file.document
+    );
+    const outputData = {
+      fileKey,
+      fileName: analysisOutput.analysisResult.file.name,
+      analyzedAt: analysisOutput.analysisResult.analyzedAt,
+      nodeCount: analysisOutput.analysisResult.nodeCount,
+      issueCount: analysisOutput.analysisResult.issues.length,
+      scoreReport: analysisOutput.scoreReport,
+      nodeIssueSummaries: filteredSummaries,
+      ruleScores
+    };
+    const outputPath = resolve(options.output ?? "logs/calibration/calibration-analysis.json");
+    const outputDir = dirname(outputPath);
+    if (!existsSync(outputDir)) {
+      mkdirSync(outputDir, { recursive: true });
+    }
+    await writeFile(outputPath, JSON.stringify(outputData, null, 2), "utf-8");
+    console.log(`
+Analysis complete.`);
+    console.log(`  Nodes: ${outputData.nodeCount}`);
+    console.log(`  Issues: ${outputData.issueCount}`);
+    console.log(`  Nodes with issues: ${outputData.nodeIssueSummaries.length}`);
+    console.log(`  Grade: ${outputData.scoreReport.overall.grade} (${outputData.scoreReport.overall.percentage}%)`);
+    console.log(`
+Output saved: ${outputPath}`);
+  } catch (error) {
+    console.error(
+      "\nError:",
+      error instanceof Error ? error.message : String(error)
+    );
+    process.exit(1);
+  }
+});
+cli.command(
+  "calibrate-evaluate <analysisJson> <conversionJson>",
+  "Evaluate conversion results and generate calibration report"
+).option("--output <path>", "Report output path").action(async (analysisJsonPath, conversionJsonPath, options) => {
+  try {
+    console.log("Running calibration evaluation...");
+    const analysisPath = resolve(analysisJsonPath);
+    const conversionPath = resolve(conversionJsonPath);
+    if (!existsSync(analysisPath)) {
+      throw new Error(`Analysis file not found: ${analysisPath}`);
+    }
+    if (!existsSync(conversionPath)) {
+      throw new Error(`Conversion file not found: ${conversionPath}`);
+    }
+    const { readFile: readFile4 } = await import('fs/promises');
+    const analysisData = JSON.parse(await readFile4(analysisPath, "utf-8"));
+    const conversionData = JSON.parse(await readFile4(conversionPath, "utf-8"));
+    const { evaluationOutput, tuningOutput, report } = runCalibrationEvaluate(
+      analysisData,
+      conversionData,
+      analysisData.ruleScores
+    );
+    const calNow = /* @__PURE__ */ new Date();
+    const calTs = `${calNow.getFullYear()}-${String(calNow.getMonth() + 1).padStart(2, "0")}-${String(calNow.getDate()).padStart(2, "0")}-${String(calNow.getHours()).padStart(2, "0")}-${String(calNow.getMinutes()).padStart(2, "0")}`;
+    const defaultCalOutput = `logs/calibration/calibration-${calTs}.md`;
+    const outputPath = resolve(options.output ?? defaultCalOutput);
+    const calOutputDir = dirname(outputPath);
+    if (!existsSync(calOutputDir)) {
+      mkdirSync(calOutputDir, { recursive: true });
+    }
+    await writeFile(outputPath, report, "utf-8");
+    const mismatchCounts = {
+      overscored: 0,
+      underscored: 0,
+      "missing-rule": 0,
+      validated: 0
+    };
+    for (const m of evaluationOutput.mismatches) {
+      const key = m.type;
+      mismatchCounts[key]++;
+    }
+    console.log(`
+Evaluation complete.`);
+    console.log(`  Validated: ${mismatchCounts.validated}`);
+    console.log(`  Overscored: ${mismatchCounts.overscored}`);
+    console.log(`  Underscored: ${mismatchCounts.underscored}`);
+    console.log(`  Missing rules: ${mismatchCounts["missing-rule"]}`);
+    console.log(`  Score adjustments proposed: ${tuningOutput.adjustments.length}`);
+    console.log(`  New rule proposals: ${tuningOutput.newRuleProposals.length}`);
+    console.log(`
+Report saved: ${outputPath}`);
+  } catch (error) {
+    console.error(
+      "\nError:",
+      error instanceof Error ? error.message : String(error)
+    );
+    process.exit(1);
+  }
+});
+cli.command(
+  "calibrate-run <input>",
+  "Run full calibration pipeline (analysis-only, conversion via /calibrate-loop)"
+).option("--output <path>", "Markdown report output path").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option("--max-nodes <count>", "Max nodes to convert", { default: 5 }).option("--sampling <strategy>", "Sampling strategy (all | top-issues | random)", { default: "top-issues" }).action(async (input, options) => {
+  try {
+    const figmaToken = options.token ?? getFigmaToken();
+    if (isFigmaUrl(input) && !parseFigmaUrl(input).nodeId) {
+      console.warn("\nWarning: No node-id specified. Calibrating entire file may produce noisy results.");
+      console.warn("Tip: Add ?node-id=XXX to target a specific section.\n");
+    }
+    console.log("Running calibration pipeline (analysis-only)...");
+    console.log(`  Input: ${input}`);
+    console.log(`  Max nodes: ${options.maxNodes ?? 5}`);
+    console.log(`  Sampling: ${options.sampling ?? "top-issues"}`);
+    console.log("");
+    const calNow = /* @__PURE__ */ new Date();
+    const calTs = `${calNow.getFullYear()}-${String(calNow.getMonth() + 1).padStart(2, "0")}-${String(calNow.getDate()).padStart(2, "0")}-${String(calNow.getHours()).padStart(2, "0")}-${String(calNow.getMinutes()).padStart(2, "0")}`;
+    const defaultOutput = `logs/calibration/calibration-${calTs}.md`;
+    const executor = async (_nodeId, _fileKey, flaggedRuleIds) => ({
+      generatedCode: `<!-- conversion skipped \u2014 use /calibrate-loop for full pipeline -->`,
+      difficulty: "moderate",
+      notes: "Skipped \u2014 CLI runs analysis only. Use /calibrate-loop in Claude Code for full pipeline with code conversion.",
+      ruleRelatedStruggles: flaggedRuleIds.map((r) => ({
+        ruleId: r,
+        description: "Unable to assess \u2014 conversion skipped",
+        actualImpact: "moderate"
+      })),
+      uncoveredStruggles: []
+    });
+    const result = await runCalibration(
+      {
+        input,
+        maxConversionNodes: options.maxNodes ?? 5,
+        samplingStrategy: options.sampling ?? "top-issues",
+        outputPath: options.output ?? defaultOutput,
+        ...figmaToken && { token: figmaToken }
+      },
+      executor,
+      { enableActivityLog: true }
+    );
+    if (result.status === "failed") {
+      throw new Error(result.error ?? "Calibration pipeline failed");
+    }
+    console.log("\nCalibration complete (analysis-only).");
+    console.log(`  Grade: ${result.scoreReport.overall.grade} (${result.scoreReport.overall.percentage}%)`);
+    console.log(`  Nodes with issues: ${result.nodeIssueSummaries.length}`);
+    console.log(`  Report: ${result.reportPath}`);
+    if (result.logPath) {
+      console.log(`  Activity log: ${result.logPath}`);
+    }
+  } catch (error) {
+    console.error(
+      "\nError:",
+      error instanceof Error ? error.message : String(error)
+    );
+    process.exit(1);
+  }
+});
+cli.command(
+  "save-fixture <input>",
+  "Save Figma file data as a JSON fixture for offline analysis"
+).option("--output <path>", "Output JSON path (default: fixtures/<filekey>.json)").option("--mcp", "Load via Figma MCP (no FIGMA_TOKEN needed)").option("--api", "Load via Figma REST API (requires FIGMA_TOKEN)").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").example("  canicode save-fixture https://www.figma.com/design/ABC123/MyDesign --mcp").example("  canicode save-fixture https://www.figma.com/design/ABC123/MyDesign --api --token YOUR_TOKEN").action(async (input, options) => {
+  try {
+    if (options.mcp && options.api) {
+      throw new Error("Cannot use --mcp and --api together. Choose one.");
+    }
+    if (isFigmaUrl(input) && !parseFigmaUrl(input).nodeId) {
+      console.warn("\nWarning: No node-id specified. Saving entire file as fixture.");
+      console.warn("Tip: Add ?node-id=XXX to save a specific section.\n");
+    }
+    const mode = options.mcp ? "mcp" : options.api ? "api" : "auto";
+    const { file } = await loadFile(input, options.token, mode);
+    const outputPath = resolve(
+      options.output ?? `fixtures/${file.fileKey}.json`
+    );
+    const outputDir = dirname(outputPath);
+    if (!existsSync(outputDir)) {
+      mkdirSync(outputDir, { recursive: true });
+    }
+    await writeFile(outputPath, JSON.stringify(file, null, 2), "utf-8");
+    console.log(`Fixture saved: ${outputPath}`);
+    console.log(`  File: ${file.name}`);
+    console.log(`  Nodes: ${countNodes2(file.document)}`);
+  } catch (error) {
+    console.error(
+      "\nError:",
+      error instanceof Error ? error.message : String(error)
+    );
+    process.exit(1);
+  }
+});
+cli.command("init", "Set up canicode (Figma token or MCP)").option("--token <token>", "Save Figma API token to ~/.canicode/").option("--mcp", "Show Figma MCP setup instructions").action((options) => {
+  try {
+    if (options.token) {
+      initAiready(options.token);
+      console.log(`  Config saved: ${getConfigPath()}`);
+      console.log(`  Reports will be saved to: ${getReportsDir()}/`);
+      console.log(`
+  Next: canicode analyze "https://www.figma.com/design/..."`);
+      return;
+    }
+    if (options.mcp) {
+      console.log(`MCP SETUP
+`);
+      console.log(`1. Install Figma MCP in Claude Code:`);
+      console.log(`   claude mcp add figma -- npx -y @anthropic-ai/claude-code-mcp-figma
+`);
+      console.log(`2. Add canicode MCP server:`);
+      console.log(`   claude mcp add --transport stdio canicode npx canicode-mcp
+`);
+      console.log(`3. Set Figma token (for MCP server's REST API fallback):`);
+      console.log(`   canicode init --token YOUR_TOKEN
+`);
+      console.log(`4. Use in Claude Code:`);
+      console.log(`   "Analyze this Figma design: https://www.figma.com/design/..."`);
+      return;
+    }
+    console.log(`CANICODE SETUP
+`);
+    console.log(`Choose your Figma data source:
+`);
+    console.log(`Option 1: REST API (recommended for CI/automation)`);
+    console.log(`  canicode init --token YOUR_FIGMA_TOKEN`);
+    console.log(`  Get token: figma.com > Settings > Personal access tokens
+`);
+    console.log(`Option 2: Figma MCP (recommended for Claude Code)`);
+    console.log(`  canicode init --mcp`);
+    console.log(`  No token needed for CLI \u2014 uses Claude Code's Figma MCP bridge
+`);
+    console.log(`After setup:`);
+    console.log(`  canicode analyze "https://www.figma.com/design/..."`);
+  } catch (error) {
+    console.error(
+      "\nError:",
+      error instanceof Error ? error.message : String(error)
+    );
+    process.exit(1);
+  }
+});
+cli.command("docs [topic]", "Show documentation (topics: setup, rules, config)").action((topic) => {
+  handleDocs(topic);
+});
+cli.help((sections) => {
+  sections.push(
+    {
+      title: "\nSetup",
+      body: [
+        `  canicode init --token <token>   Save Figma token to ~/.canicode/`,
+        `  canicode init --mcp             Show MCP setup instructions`
+      ].join("\n")
+    },
+    {
+      title: "\nData source",
+      body: [
+        `  --mcp                   Load via Figma MCP (no token needed)`,
+        `  --api                   Load via Figma REST API (needs FIGMA_TOKEN)`,
+        `  (default)               Auto-detect: try MCP first, then API`
+      ].join("\n")
+    },
+    {
+      title: "\nCustomization",
+      body: [
+        `  --custom-rules <path>   Add custom rules (see: canicode docs rules)`,
+        `  --config <path>         Override rule settings (see: canicode docs config)`
+      ].join("\n")
+    },
+    {
+      title: "\nExamples",
+      body: [
+        `  $ canicode analyze "https://www.figma.com/design/..." --mcp`,
+        `  $ canicode analyze "https://www.figma.com/design/..." --api`,
+        `  $ canicode analyze "https://www.figma.com/design/..." --preset strict`,
+        `  $ canicode analyze "https://www.figma.com/design/..." --config ./my-config.json`,
+        `  $ canicode analyze "https://www.figma.com/design/..." --custom-rules ./my-rules.json`
+      ].join("\n")
+    },
+    {
+      title: "\nInstallation",
+      body: [
+        `  CLI:     npm install -g canicode`,
+        `  MCP:     claude mcp add --transport stdio canicode npx canicode-mcp`,
+        `  Skills:  github.com/let-sunny/canicode`
+      ].join("\n")
+    }
+  );
+});
+cli.version("0.1.0");
+cli.parse();
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map