canicode 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 minseon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,298 @@
+# CanICode
+
+Analyze Figma designs. Score how dev-friendly and AI-friendly they are. Get actionable issues before writing code.
+
+```bash
+npm install -g canicode
+canicode init --token YOUR_FIGMA_TOKEN
+canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
+```
+
+> Run `canicode docs setup` for the full setup guide — CLI, MCP Server, Claude Skills, and all options.
+
+---
+
+## How It Works
+
+39 rules across 6 categories check every node in the Figma tree:
+
+| Category | Rules | What it checks |
+|----------|-------|----------------|
+| Layout | 11 | Auto-layout usage, responsive behavior, nesting depth |
+| Design Token | 7 | Color/font/shadow tokenization, spacing consistency |
+| Component | 6 | Component reuse, detached instances, variant coverage |
+| Naming | 5 | Semantic names, default names, naming conventions |
+| AI Readability | 5 | Structure clarity, z-index reliance, empty frames |
+| Handoff Risk | 5 | Hardcoded values, truncation handling, placeholder images |
+
+Each issue is classified: **Blocking** > **Risk** > **Missing Info** > **Suggestion**.
+
+Scores use density + diversity weighting per category, combined into an overall grade (A/B/C/D/F).
+
+---
+
+## Getting Started
+
+Three ways to use CanICode. Pick one.
+
+### CLI (standalone)
+
+```bash
+npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
+
+# Or install globally
+npm install -g canicode
+canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
+```
+
+To enable "Comment on Figma" buttons in reports, set your Figma token:
+```bash
+canicode init --token figd_xxxxxxxxxxxxx
+```
+
+### MCP Server (Claude Code / Cursor / Claude Desktop)
+
+**Claude Code:**
+```bash
+claude mcp add canicode -e FIGMA_TOKEN=figd_xxxxxxxxxxxxx -- npx -y canicode canicode-mcp
+```
+
+**Cursor** (`~/.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "canicode": {
+      "command": "npx",
+      "args": ["-y", "canicode", "canicode-mcp"],
+      "env": {
+        "FIGMA_TOKEN": "figd_xxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "canicode": {
+      "command": "npx",
+      "args": ["-y", "canicode", "canicode-mcp"],
+      "env": {
+        "FIGMA_TOKEN": "figd_xxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+Then ask: *"Analyze this Figma design: https://www.figma.com/design/..."*
+
+> With `FIGMA_TOKEN` set, the HTML report includes "Comment on Figma" buttons that post analysis findings directly to Figma nodes.
+
+---
+
+<details>
+<summary><strong>Data Sources</strong></summary>
+
+| Flag | Source | Token required |
+|------|--------|----------------|
+| (none) | Auto-detect: MCP first, then REST API | For API fallback |
+| `--mcp` | Figma MCP via Claude Code | None |
+| `--api` | Figma REST API | Yes |
+
+Token priority:
+1. `--token` flag (one-time override)
+2. `FIGMA_TOKEN` env var (CI/CD)
+3. `~/.canicode/config.json` (`canicode init`)
+
+</details>
+
+<details>
+<summary><strong>Presets</strong></summary>
+
+| Preset | Behavior |
+|--------|----------|
+| `relaxed` | Downgrades blocking to risk, reduces scores by 50% |
+| `dev-friendly` | Focuses on layout and handoff rules only |
+| `ai-ready` | Boosts structure and naming rule weights by 150% |
+| `strict` | Enables all rules, increases all scores by 150% |
+
+```bash
+canicode analyze <url> --preset strict
+```
+
+</details>
+
+<details>
+<summary><strong>Custom Rules</strong></summary>
+
+Add project-specific checks via a JSON file:
+
+```bash
+canicode analyze <url> --custom-rules ./my-rules.json
+```
+
+```json
+[
+  {
+    "id": "icon-missing-component",
+    "category": "component",
+    "severity": "blocking",
+    "score": -10,
+    "prompt": "Check if this node is an icon and is not a component.",
+    "why": "Icons that are not components cannot be reused.",
+    "impact": "Developers will hardcode icons.",
+    "fix": "Convert to a component and publish to the library."
+  }
+]
+```
+
+See [`examples/custom-rules.json`](examples/custom-rules.json) | Run `canicode docs rules`
+
+</details>
+
+<details>
+<summary><strong>Config Overrides</strong></summary>
+
+Override built-in rule scores, severity, and global settings:
+
+```bash
+canicode analyze <url> --config ./my-config.json
+```
+
+```json
+{
+  "gridBase": 4,
+  "colorTolerance": 5,
+  "rules": {
+    "no-auto-layout": { "score": -15, "severity": "blocking" },
+    "default-name": { "enabled": false }
+  }
+}
+```
+
+| Option | Description |
+|--------|-------------|
+| `gridBase` | Spacing grid unit (default: 8) |
+| `colorTolerance` | Color difference tolerance (default: 10) |
+| `excludeNodeTypes` | Node types to skip |
+| `excludeNodeNames` | Node name patterns to skip |
+| `rules.<id>.score` | Override rule score |
+| `rules.<id>.severity` | Override rule severity |
+| `rules.<id>.enabled` | Enable/disable a rule |
+
+See [`examples/config.json`](examples/config.json) | Run `canicode docs config`
+
+</details>
+
+<details>
+<summary><strong>Scoring Algorithm</strong></summary>
+
+```
+Final Score = (Density Score × 0.7) + (Diversity Score × 0.3)
+
+Density Score  = 100 - (weighted issue count / node count) × 100
+Diversity Score = (1 - unique violated rules / total rules in category) × 100
+```
+
+Severity weights issues — a single blocking issue counts 3x more than a suggestion. Scores are calculated per category and combined into an overall grade (A/B/C/D/F).
+
+</details>
+
+<details>
+<summary><strong>MCP Server Details</strong></summary>
+
+The `canicode-mcp` server exposes two tools: `analyze` and `list-rules`.
+
+**Route A — Figma MCP relay (no token):**
+
+```
+Claude Code → Figma MCP get_metadata → XML node tree
+Claude Code → canicode MCP analyze(designData: XML) → result
+```
+
+**Route B — REST API direct (token):**
+
+```
+Claude Code → canicode MCP analyze(input: URL) → internal fetch → result
+```
+
+Route A requires two MCP servers (figma + canicode). Route B requires one + a saved token.
+
+The `analyze` tool accepts `designData` (XML/JSON from Figma MCP) or `input` (Figma URL / fixture path). When both are provided, `designData` takes priority.
+
+</details>
+
+<details>
+<summary><strong>Save Fixture</strong></summary>
+
+Save Figma file data as JSON for offline analysis:
+
+```bash
+canicode save-fixture https://www.figma.com/design/ABC123/MyDesign
+canicode save-fixture https://www.figma.com/design/ABC123/MyDesign --mcp
+```
+
+</details>
+
+---
+
+<details>
+<summary><strong>Tech Stack</strong></summary>
+
+| Layer | Tool |
+|-------|------|
+| Runtime | Node.js (>= 18) |
+| Language | TypeScript (strict mode) |
+| Package Manager | pnpm |
+| Validation | Zod |
+| Testing | Vitest |
+| CLI | cac |
+| Build | tsup |
+
+</details>
+
+<details>
+<summary><strong>Calibration (Internal)</strong></summary>
+
+Rule scores are validated against actual code conversion difficulty via a calibration pipeline. This runs inside Claude Code using `/calibrate-loop` — not exposed as a CLI command.
+
+The pipeline uses 4 subagents:
+1. **Runner** — Analyzes a fixture and extracts issue data
+2. **Converter** — Converts flagged Figma nodes to code via Figma MCP
+3. **Critic** — Reviews proposed score adjustments
+4. **Arbitrator** — Makes final decisions and commits changes
+
+</details>
+
+<details>
+<summary><strong>Development</strong></summary>
+
+```bash
+git clone https://github.com/let-sunny/canicode.git
+cd canicode
+pnpm install
+pnpm build
+```
+
+```bash
+pnpm dev        # watch mode
+pnpm test       # run tests
+pnpm lint       # type check
+```
+
+</details>
+
+## Roadmap
+
+- [x] **Phase 1** — 39 rules, density-based scoring, HTML reports, presets, scoped analysis
+- [x] **Phase 2** — 4-agent calibration pipeline, `/calibrate-loop` debate loop
+- [x] **Phase 3** — Custom rules, 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)
+- [ ] **Phase 5** — Screenshot comparison (Figma vs AI-generated code, visual diff)
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node