canicode 0.8.4 → 0.8.5

package/README.md

@@ -11,23 +11,26 @@
   <a href="https://let-sunny.github.io/canicode/"><img src="https://img.shields.io/badge/Try_it-GitHub_Pages-blue" alt="GitHub Pages"></a>
   <a href="https://www.figma.com/community/plugin/1617144221046795292/canicode"><img src="https://img.shields.io/badge/Figma_Plugin-under_review-orange" alt="Figma Plugin"></a>
   <a href="https://github.com/let-sunny/canicode#mcp-server-claude-code--cursor--claude-desktop"><img src="https://img.shields.io/badge/MCP_Registry-published-green" alt="MCP Registry"></a>
+  <a href="https://github.com/marketplace/actions/canicode-action"><img src="https://img.shields.io/badge/GitHub_Action-Marketplace-2088FF" alt="GitHub Action"></a>
 </p>
 
-<p align="center">Analyze Figma designs. Score how dev-friendly and AI-friendly they are. Get actionable issues before writing code.</p>
+<p align="center">The design linter that scores how easily your Figma design can be implemented by AI or developers — before a single line of code is written.</p>
+
+<p align="center">No AI tokens consumed per analysis. Rules run deterministically — AI only validated the scores during development.</p>
 
 <p align="center"><strong><a href="https://github.com/let-sunny/canicode/discussions/new?category=share-your-figma">Share your Figma design</a></strong> to help improve scoring accuracy.</p>
 
 <p align="center"><strong><a href="https://let-sunny.github.io/canicode/">Try it in your browser</a></strong> — no install needed.</p>
 
 <p align="center">
-  <img src="docs/images/screenshot.png" alt="CanICode Report" width="720">
+  <img src="docs/images/screenshot.gif" alt="CanICode Report" width="720">
 </p>
 
 ---
 
 ## How It Works
 
-39 rules across 6 categories check every node in the Figma tree:
+39 rules. 6 categories. Every node in the Figma tree.
 
 | Category | Rules | What it checks |
 |----------|-------|----------------|
@@ -40,53 +43,110 @@
 
 Each issue is classified: **Blocking** > **Risk** > **Missing Info** > **Suggestion**.
 
-Scores use density + diversity weighting per category, combined into an overall grade (S/A+/A/B+/B/C+/C/D/F). Rule scores are calibrated against actual code conversion difficulty — see [`docs/CALIBRATION.md`](docs/CALIBRATION.md).
+### Rule Scores Validated by AI
+
+Rule scores aren't guesswork. They're validated through a 4-agent debate pipeline that converts real Figma nodes to code and measures actual implementation difficulty.
+
+1. **Runner** analyzes the design and flags issues
+2. **Converter** converts the flagged nodes to actual code
+3. **Critic** challenges whether the scores match the real difficulty
+4. **Arbitrator** makes the final call — adjust or keep
+
+- A node that's hard to implement → rule score goes up
+- A node that's easy to implement despite the flag → rule score goes down
+
+The rules themselves run deterministically on every analysis — no tokens consumed. The AI debate validates scores when new fixtures are added, not on every run. See [`docs/CALIBRATION.md`](docs/CALIBRATION.md).
 
 ---
 
 ## Getting Started
 
-Five ways to use CanICode. Pick one.
+| If you want to... | Use |
+|---|---|
+| Just try it | **[Web App](https://let-sunny.github.io/canicode/)** — paste a URL, no install |
+| Analyze inside Figma | **[Figma Plugin](https://www.figma.com/community/plugin/1617144221046795292/canicode)** (under review) |
+| Use with Claude Code / Cursor | **MCP Server** or **Skill** — see below |
+| Add to CI/CD | **[GitHub Action](https://github.com/marketplace/actions/canicode-action)** |
+| Full control | **CLI** |
 
-### 1. CLI
+<details>
+<summary><strong>CLI</strong></summary>
 
 ```bash
 npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
 ```
 
-Setup:
-```bash
-canicode init --token figd_xxxxxxxxxxxxx
-```
+Setup: `canicode init --token figd_xxxxxxxxxxxxx`
 
 > **Get your token:** Figma → Settings → Security → Personal access tokens → Generate new token
 
-### 2. MCP Server (Claude Code / Cursor / Claude Desktop)
+**Figma API Rate Limits** — Rate limits depend on **where the file lives**, not just your plan.
+
+| Seat | File in Starter plan | File in Pro/Org/Enterprise |
+|------|---------------------|---------------------------|
+| View, Collab | 6 req/month | 6 req/month |
+| Dev, Full | 6 req/month | 10–20 req/min |
+
+Hitting 429 errors? Make sure the file is in a paid workspace. Or use MCP (no token, separate rate limit pool). Or `save-fixture` once and analyze locally. [Full details](https://developers.figma.com/docs/rest-api/rate-limits/)
+
+</details>
+
+<details>
+<summary><strong>MCP Server</strong> (Claude Code / Cursor / Claude Desktop)</summary>
 
-**Claude Code (recommended — with official Figma MCP, no token needed):**
 ```bash
 claude mcp add canicode -- npx -y -p canicode canicode-mcp
 claude mcp add -s project -t http figma https://mcp.figma.com/mcp
 ```
 
-**Claude Code (with Figma API token):**
+Then ask: *"Analyze this Figma design: https://www.figma.com/design/..."*
+
+canicode's rule engine analyzes the design data — the AI assistant just orchestrates the calls.
+
+Or with a Figma API token (no Figma MCP needed):
 ```bash
 claude mcp add canicode -e FIGMA_TOKEN=figd_xxxxxxxxxxxxx -- npx -y -p canicode canicode-mcp
 ```
 
 For Cursor / Claude Desktop config, see [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md).
 
-Then ask: *"Analyze this Figma design: https://www.figma.com/design/..."*
+**Figma MCP Rate Limits**
+
+| Plan | Limit |
+|------|-------|
+| Starter | 6 tool calls/month |
+| Pro / Org — Full or Dev seat | 200 tool calls/day |
+| Enterprise — Full or Dev seat | 600 tool calls/day |
+
+MCP and CLI use separate rate limit pools — switching to MCP won't affect your CLI quota. [Full details](https://developers.figma.com/docs/figma-mcp-server/plans-access-and-permissions/)
+
+</details>
 
-> **Note:** MCP/Skill path extracts style data from Figma MCP's generated code (React + Tailwind), not raw Figma node properties. Results may differ slightly from CLI — see [`docs/MCP-VS-CLI.md`](docs/MCP-VS-CLI.md) for a detailed comparison. For the most accurate analysis, use the CLI with a Figma API token.
+<details>
+<summary><strong>Claude Code Skill</strong> (lightweight, no MCP install)</summary>
 
-### 3. Web (no install)
+```bash
+cp -r .claude/skills/canicode /your-project/.claude/skills/
+```
+
+Requires the official Figma MCP. Then use `/canicode` with a Figma URL.
 
-Go to **[let-sunny.github.io/canicode](https://let-sunny.github.io/canicode/)**, paste a Figma URL, and get results instantly in your browser.
+</details>
+
+<details>
+<summary><strong>GitHub Action</strong></summary>
+
+```yaml
+- uses: let-sunny/canicode-action@v0.1.0
+  with:
+    figma_url: 'https://www.figma.com/design/ABC123/MyDesign?node-id=1-234'
+    figma_token: ${{ secrets.FIGMA_TOKEN }}
+    min_score: 70
+```
 
-### 4. Figma Plugin (under review)
+Posts analysis as a PR comment. Fails if score is below threshold. See [**canicode-action**](https://github.com/marketplace/actions/canicode-action) on Marketplace.
 
-Install from **[Figma Community](https://www.figma.com/community/plugin/1617144221046795292/canicode)** — analyze directly inside Figma. No tokens needed.
+</details>
 
 ---
 
@@ -126,12 +186,14 @@ For architecture details, see [`CLAUDE.md`](CLAUDE.md). For calibration pipeline
 - [x] **Phase 3** — Config overrides, MCP server, Claude Skills
 - [x] **Phase 4** — Figma comment from report (per-issue "Comment" button in HTML report, posts to Figma node via API)
 - [x] **Phase 5** — Custom rules with pattern matching (node name/type/attribute conditions)
-- [ ] **Phase 6** — Screenshot comparison (Figma vs AI-generated code, visual diff)
+- [x] **Phase 6** — Screenshot comparison (`visual-compare` CLI: Figma vs AI-generated code, pixel-level diff)
+- [x] **Phase 7** — Calibration pipeline upgrade (visual-compare + Gap Analyzer for objective score validation)
+- [x] **Phase 8** — Rule discovery pipeline (6-agent debate: researcher → designer → implementer → A/B visual validation → evaluator → critic)
+- [ ] **Ongoing** — Rule refinement via calibration + gap analysis on community fixtures
 
 ## Support
 
-- **Bug reports:** [GitHub Issues](https://github.com/let-sunny/canicode/issues)
-- **Questions and discussions:** [GitHub Issues](https://github.com/let-sunny/canicode/issues)
+- **Bugs and questions:** [GitHub Issues](https://github.com/let-sunny/canicode/issues)
 - **Privacy:** See [PRIVACY.md](PRIVACY.md) for details on data collection and how to opt out
 
 ## License

package/dist/cli/index.js

@@ -1,7 +1,9 @@
 #!/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 pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import { writeFile, readFile, appendFile } from 'fs/promises';
 import { createRequire } from 'module';
 import { config } from 'dotenv';
 import cac from 'cac';
@@ -9,6 +11,108 @@ import { z } from 'zod';
 import { randomUUID } from 'crypto';
 import { homedir } from 'os';
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/core/engine/visual-compare.ts
+var visual_compare_exports = {};
+__export(visual_compare_exports, {
+  visualCompare: () => visualCompare
+});
+async function fetchFigmaScreenshot(fileKey, nodeId, token, outputPath) {
+  const res = await fetch(
+    `https://api.figma.com/v1/images/${fileKey}?ids=${nodeId}&format=png&scale=2`,
+    { headers: { "X-Figma-Token": token } }
+  );
+  if (!res.ok) throw new Error(`Figma Images API: ${res.status} ${res.statusText}`);
+  const data = await res.json();
+  const imgUrl = data.images[nodeId];
+  if (!imgUrl) throw new Error(`No image returned for node ${nodeId}`);
+  const imgRes = await fetch(imgUrl);
+  if (!imgRes.ok) throw new Error(`Failed to download Figma screenshot: ${imgRes.status}`);
+  const buffer = Buffer.from(await imgRes.arrayBuffer());
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, buffer);
+}
+async function renderCodeScreenshot(codePath, outputPath, viewport) {
+  const { chromium } = await import('playwright');
+  const browser = await chromium.launch();
+  const page = await browser.newPage({ viewport });
+  await page.goto(`file://${resolve(codePath)}`, {
+    waitUntil: "networkidle",
+    timeout: 3e4
+  });
+  await page.waitForTimeout(1e3);
+  await page.screenshot({ path: outputPath, fullPage: true });
+  await browser.close();
+}
+function resizePng(png, targetWidth, targetHeight) {
+  const resized = new PNG({ width: targetWidth, height: targetHeight });
+  for (let y = 0; y < targetHeight; y++) {
+    for (let x = 0; x < targetWidth; x++) {
+      const srcX = Math.floor(x / targetWidth * png.width);
+      const srcY = Math.floor(y / targetHeight * png.height);
+      const srcIdx = (srcY * png.width + srcX) * 4;
+      const dstIdx = (y * targetWidth + x) * 4;
+      resized.data[dstIdx] = png.data[srcIdx];
+      resized.data[dstIdx + 1] = png.data[srcIdx + 1];
+      resized.data[dstIdx + 2] = png.data[srcIdx + 2];
+      resized.data[dstIdx + 3] = png.data[srcIdx + 3];
+    }
+  }
+  return resized;
+}
+function compareScreenshots(path1, path2, diffOutputPath) {
+  const raw1 = PNG.sync.read(readFileSync(path1));
+  const raw2 = PNG.sync.read(readFileSync(path2));
+  const width = Math.max(raw1.width, raw2.width);
+  const height = Math.max(raw1.height, raw2.height);
+  const img1 = raw1.width !== width || raw1.height !== height ? resizePng(raw1, width, height) : raw1;
+  const img2 = raw2.width !== width || raw2.height !== height ? resizePng(raw2, width, height) : raw2;
+  const diff = new PNG({ width, height });
+  const diffPixels = pixelmatch(img1.data, img2.data, diff.data, width, height, {
+    threshold: 0.1
+  });
+  mkdirSync(dirname(diffOutputPath), { recursive: true });
+  writeFileSync(diffOutputPath, PNG.sync.write(diff));
+  const totalPixels = width * height;
+  const similarity = Math.round((1 - diffPixels / totalPixels) * 100);
+  return { similarity, diffPixels, totalPixels, width, height };
+}
+async function visualCompare(options) {
+  const outputDir = options.outputDir ?? "/tmp/canicode-visual-compare";
+  const figmaScreenshotPath = resolve(outputDir, "figma.png");
+  const codeScreenshotPath = resolve(outputDir, "code.png");
+  const diffPath = resolve(outputDir, "diff.png");
+  const urlMatch = options.figmaUrl.match(/\/design\/([^/]+)\//);
+  const fileKey = urlMatch?.[1];
+  if (!fileKey) throw new Error("Invalid Figma URL \u2014 could not extract file key");
+  const nodeIdMatch = options.figmaUrl.match(/node-id=([^&\s]+)/);
+  const nodeId = nodeIdMatch?.[1]?.replace(/-/g, ":");
+  if (!nodeId) throw new Error("Invalid Figma URL \u2014 missing node-id");
+  await fetchFigmaScreenshot(fileKey, nodeId, options.figmaToken, figmaScreenshotPath);
+  const figmaPng = PNG.sync.read(readFileSync(figmaScreenshotPath));
+  const viewport = options.viewport ?? { width: figmaPng.width, height: figmaPng.height };
+  await renderCodeScreenshot(options.codePath, codeScreenshotPath, viewport);
+  const result = compareScreenshots(figmaScreenshotPath, codeScreenshotPath, diffPath);
+  return {
+    ...result,
+    figmaScreenshotPath,
+    codeScreenshotPath,
+    diffPath
+  };
+}
+var init_visual_compare = __esm({
+  "src/core/engine/visual-compare.ts"() {
+  }
+});
 z.object({
   fileKey: z.string(),
   nodeId: z.string().optional(),
@@ -217,7 +321,7 @@ var RULE_CONFIGS = {
     }
   },
   // ============================================
-  // Component (6 rules)
+  // Component (7 rules)
   // ============================================
   "missing-component": {
     severity: "risk",
@@ -252,6 +356,11 @@ var RULE_CONFIGS = {
     score: -1,
     enabled: true
   },
+  "missing-component-description": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
   // ============================================
   // Naming (5 rules)
   // ============================================
@@ -834,6 +943,20 @@ function transformNode(node) {
   }
   return base;
 }
+function transformFileNodesResponse(fileKey, response) {
+  const entries = Object.values(response.nodes);
+  const first = entries[0];
+  if (!first) throw new Error("No nodes returned from Figma API");
+  return {
+    fileKey,
+    name: response.name,
+    lastModified: response.lastModified,
+    version: response.version,
+    document: transformNode(first.document),
+    components: transformComponents(first.components),
+    styles: transformStyles(first.styles)
+  };
+}
 function transformComponents(components) {
   const result = {};
   for (const [id, component] of Object.entries(components)) {
@@ -967,6 +1090,13 @@ async function loadFromApi(fileKey, nodeId, token) {
     );
   }
   const client = new FigmaClient({ token: figmaToken });
+  if (nodeId) {
+    const response2 = await client.getFileNodes(fileKey, [nodeId.replace(/-/g, ":")]);
+    return {
+      file: transformFileNodesResponse(fileKey, response2),
+      nodeId
+    };
+  }
   const response = await client.getFile(fileKey);
   return {
     file: transformFigmaResponse(fileKey, response),
@@ -975,7 +1105,7 @@ async function loadFromApi(fileKey, nodeId, token) {
 }
 
 // package.json
-var version = "0.8.4";
+var version = "0.8.5";
 var AnalysisNodeTypeSchema = z.enum([
   "DOCUMENT",
   "CANVAS",
@@ -1788,6 +1918,35 @@ defineRule({
   definition: singleUseComponentDef,
   check: singleUseComponentCheck
 });
+var seenMissingDescriptionComponentIds = /* @__PURE__ */ new Set();
+var missingComponentDescriptionDef = {
+  id: "missing-component-description",
+  name: "Missing Component Description",
+  category: "component",
+  why: "Component descriptions in Figma are the primary channel for communicating intent, usage guidelines, and prop expectations to developers. Without them, developers must reverse-engineer purpose from visual appearance alone.",
+  impact: "Increases implementation ambiguity, especially for icon-only components, compound components with multiple variants, and components whose names are variant key strings that give no prose context.",
+  fix: "Open the component in Figma, select it, and add a description in the right-hand panel under the component's properties. Include: what the component is, when to use it, any accessibility or interaction notes, and the owning team or design token set if applicable."
+};
+var missingComponentDescriptionCheck = (node, context) => {
+  if (node.type !== "INSTANCE") return null;
+  const componentId = node.componentId;
+  if (!componentId) return null;
+  const componentMeta = context.file.components[componentId];
+  if (!componentMeta) return null;
+  if (componentMeta.description.trim() !== "") return null;
+  if (seenMissingDescriptionComponentIds.has(componentId)) return null;
+  seenMissingDescriptionComponentIds.add(componentId);
+  return {
+    ruleId: missingComponentDescriptionDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `Component "${componentMeta.name}" has no description. Descriptions help developers understand purpose and usage.`
+  };
+};
+defineRule({
+  definition: missingComponentDescriptionDef,
+  check: missingComponentDescriptionCheck
+});
 
 // src/core/rules/naming/index.ts
 var DEFAULT_NAME_PATTERNS = [
@@ -3018,13 +3177,19 @@ function hasTextDescendant(node) {
 }
 var MIN_WIDTH = 200;
 var MIN_HEIGHT = 200;
+var FILTER_THRESHOLD = 500;
 var ELIGIBLE_NODE_TYPES = /* @__PURE__ */ new Set([
   "FRAME",
   "COMPONENT",
   "INSTANCE"
 ]);
 function filterConversionCandidates(summaries, documentRoot) {
-  return summaries.filter((summary) => {
+  const visibleSummaries = summaries.filter((summary) => {
+    const node = findNode(documentRoot, summary.nodeId);
+    return node ? node.visible !== false : false;
+  });
+  if (visibleSummaries.length <= FILTER_THRESHOLD) return visibleSummaries;
+  return visibleSummaries.filter((summary) => {
     const node = findNode(documentRoot, summary.nodeId);
     if (!node) return false;
     if (EXCLUDED_NODE_TYPES.has(node.type)) return false;
@@ -4695,6 +4860,50 @@ cli.command(
     process.exit(1);
   }
 });
+cli.command(
+  "visual-compare <codePath>",
+  "Compare rendered code against Figma screenshot (pixel-level similarity)"
+).option("--figma-url <url>", "Figma URL with node-id (required)").option("--token <token>", "Figma API token (or use FIGMA_TOKEN env var)").option("--output <dir>", "Output directory for screenshots and diff (default: /tmp/canicode-visual-compare)").option("--width <px>", "Viewport width (default: 1440)").option("--height <px>", "Viewport height (default: 900)").example("  canicode visual-compare ./generated/index.html --figma-url 'https://www.figma.com/design/ABC/File?node-id=1-234'").action(async (codePath, options) => {
+  try {
+    if (!options.figmaUrl) {
+      console.error("Error: --figma-url is required");
+      process.exit(1);
+    }
+    const token = options.token ?? getFigmaToken();
+    if (!token) {
+      console.error("Error: Figma token required. Use --token or set FIGMA_TOKEN env var.");
+      process.exit(1);
+    }
+    const { visualCompare: visualCompare2 } = await Promise.resolve().then(() => (init_visual_compare(), visual_compare_exports));
+    console.log("Comparing...");
+    const result = await visualCompare2({
+      figmaUrl: options.figmaUrl,
+      figmaToken: token,
+      codePath: resolve(codePath),
+      outputDir: options.output,
+      viewport: {
+        width: options.width ?? 1440,
+        height: options.height ?? 900
+      }
+    });
+    console.log(JSON.stringify({
+      similarity: result.similarity,
+      diffPixels: result.diffPixels,
+      totalPixels: result.totalPixels,
+      width: result.width,
+      height: result.height,
+      figmaScreenshot: result.figmaScreenshotPath,
+      codeScreenshot: result.codeScreenshotPath,
+      diff: result.diffPath
+    }, null, 2));
+  } 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) {