canicode 0.3.1 → 0.3.3

package/README.md

@@ -1,6 +1,19 @@
-# CanICode
+<p align="center">
+  <img src="docs/logo.png" alt="CanICode" width="80">
+</p>
 
-Analyze Figma designs. Score how dev-friendly and AI-friendly they are. Get actionable issues before writing code.
+<h1 align="center">CanICode</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/canicode"><img src="https://img.shields.io/npm/v/canicode.svg" alt="npm version"></a>
+  <a href="https://github.com/let-sunny/canicode/actions/workflows/ci.yml"><img src="https://github.com/let-sunny/canicode/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/let-sunny/canicode/actions/workflows/release.yml"><img src="https://github.com/let-sunny/canicode/actions/workflows/release.yml/badge.svg" alt="Release"></a>
+  <a href="https://let-sunny.github.io/canicode/"><img src="https://img.shields.io/badge/Try_it-GitHub_Pages-blue" alt="GitHub Pages"></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"><strong><a href="https://let-sunny.github.io/canicode/">Try it in your browser</a></strong> — no install needed.</p>
 
 ```bash
 npm install -g canicode
@@ -27,13 +40,17 @@ canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"
 
 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).
+Scores use density + diversity weighting per category, combined into an overall grade (S/A+/A/B+/B/C+/C/D/F).
 
 ---
 
 ## Getting Started
 
-Three ways to use CanICode. Pick one.
+Four ways to use CanICode. Pick one.
+
+### Web (no install)
+
+Go to **[let-sunny.github.io/canicode](https://let-sunny.github.io/canicode/)**, paste a Figma URL, and get results instantly in your browser.
 
 ### CLI (standalone)
 
@@ -50,6 +67,8 @@ To enable "Comment on Figma" buttons in reports, set your Figma token:
 canicode init --token figd_xxxxxxxxxxxxx
 ```
 
+> **Get your token:** Figma → Settings → Security → Personal access tokens → Generate new token
+
 ### MCP Server (Claude Code / Cursor / Claude Desktop)
 
 **Claude Code:**
@@ -156,7 +175,7 @@ See [`examples/custom-rules.json`](examples/custom-rules.json) | Run `canicode d
 <details>
 <summary><strong>Config Overrides</strong></summary>
 
-Override built-in rule scores, severity, and global settings:
+Override rule scores, severity, node exclusions, and global settings:
 
 ```bash
 canicode analyze <url> --config ./my-config.json
@@ -164,8 +183,8 @@ canicode analyze <url> --config ./my-config.json
 
 ```json
 {
+  "excludeNodeNames": ["chatbot", "ad-banner", "wip"],
   "gridBase": 4,
-  "colorTolerance": 5,
   "rules": {
     "no-auto-layout": { "score": -15, "severity": "blocking" },
     "default-name": { "enabled": false }
@@ -175,7 +194,7 @@ canicode analyze <url> --config ./my-config.json
 
 | Option | Description |
 |--------|-------------|
-| `gridBase` | Spacing grid unit (default: 8) |
+| `gridBase` | Spacing grid unit (default: 4) |
 | `colorTolerance` | Color difference tolerance (default: 10) |
 | `excludeNodeTypes` | Node types to skip |
 | `excludeNodeNames` | Node name patterns to skip |
@@ -183,7 +202,7 @@ canicode analyze <url> --config ./my-config.json
 | `rules.<id>.severity` | Override rule severity |
 | `rules.<id>.enabled` | Enable/disable a rule |
 
-See [`examples/config.json`](examples/config.json) | Run `canicode docs config`
+See [`examples/config.json`](examples/config.json) | [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md) | Run `canicode docs config`
 
 </details>
 
@@ -197,7 +216,7 @@ 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).
+Severity weights issues — a single blocking issue counts 3x more than a suggestion. Scores are calculated per category and combined into an overall grade (S/A+/A/B+/B/C+/C/D/F).
 
 </details>
 

package/dist/cli/index.js

@@ -185,7 +185,7 @@ var RULE_CONFIGS = {
     score: -2,
     enabled: true,
     options: {
-      gridBase: 8
+      gridBase: 4
     }
   },
   "magic-number-spacing": {
@@ -193,7 +193,7 @@ var RULE_CONFIGS = {
     score: -4,
     enabled: true,
     options: {
-      gridBase: 8
+      gridBase: 4
     }
   },
   "raw-shadow": {
@@ -502,11 +502,15 @@ var RuleEngine = class {
   enabledRuleIds;
   disabledRuleIds;
   targetNodeId;
+  excludeNamePattern;
+  excludeNodeTypes;
   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;
+    this.excludeNamePattern = options.excludeNodeNames && options.excludeNodeNames.length > 0 ? new RegExp(`\\b(${options.excludeNodeNames.join("|")})\\b`, "i") : null;
+    this.excludeNodeTypes = options.excludeNodeTypes && options.excludeNodeTypes.length > 0 ? new Set(options.excludeNodeTypes) : null;
   }
   /**
    * Analyze a Figma file and return issues
@@ -560,6 +564,12 @@ var RuleEngine = class {
    */
   traverseAndCheck(node, file, rules, maxDepth, issues, depth, path, parent, siblings) {
     const nodePath = [...path, node.name];
+    if (this.excludeNodeTypes && this.excludeNodeTypes.has(node.type)) {
+      return;
+    }
+    if (this.excludeNamePattern && this.excludeNamePattern.test(node.name)) {
+      return;
+    }
     const context = {
       file,
       parent,
@@ -754,6 +764,12 @@ function transformNode(node) {
   if ("layoutPositioning" in node && node.layoutPositioning) {
     base.layoutPositioning = node.layoutPositioning;
   }
+  if ("layoutSizingHorizontal" in node && node.layoutSizingHorizontal) {
+    base.layoutSizingHorizontal = node.layoutSizingHorizontal;
+  }
+  if ("layoutSizingVertical" in node && node.layoutSizingVertical) {
+    base.layoutSizingVertical = node.layoutSizingVertical;
+  }
   if ("primaryAxisAlignItems" in node) {
     base.primaryAxisAlignItems = node.primaryAxisAlignItems;
   }
@@ -1479,7 +1495,7 @@ function generateHtmlReport(file, result, scores, options) {
 ${CATEGORIES.map((cat) => {
     const cs = scores.byCategory[cat];
     const desc = CATEGORY_DESCRIPTIONS[cat];
-    return `        <div class="flex flex-col items-center group relative">
+    return `        <a href="#cat-${cat}" class="flex flex-col items-center group relative cursor-pointer no-underline text-foreground hover:opacity-80 transition-opacity">
           ${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>
@@ -1487,7 +1503,7 @@ ${CATEGORIES.map((cat) => {
             ${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>`;
+        </a>`;
   }).join("\n")}
       </div>
     </section>
@@ -1542,7 +1558,7 @@ ${figmaToken ? `  <script>
         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 } }),
+          body: JSON.stringify({ message: commentBody, client_meta: { node_id: nodeId, node_offset: { x: 0, y: 0 } } }),
         });
         if (!res.ok) throw new Error(await res.text());
         btn.textContent = 'Sent \\u2713';
@@ -1625,7 +1641,7 @@ function renderCategory(cat, scores, issues, fileKey, screenshotMap, figmaToken)
   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" : ""}>
+      <details id="cat-${cat}" 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">
@@ -2305,6 +2321,12 @@ var ActivityLogger = class {
   }
 };
 
+// src/rules/excluded-names.ts
+var EXCLUDED_NAME_PATTERN = /(badge|close|dismiss|overlay|float|fab|dot|indicator|corner|decoration|tag|status|notification|icon|ico|image|asset|filter|dim|dimmed|bg|background|logo|avatar|divider|separator|nav|navigation|gnb|header|footer|sidebar|toolbar|modal|dialog|popup|toast|tooltip|dropdown|menu|sticky|spinner|loader|cursor|cta|chatbot|thumb|thumbnail|tabbar|tab-bar|statusbar|status-bar)/i;
+function isExcludedName(name) {
+  return EXCLUDED_NAME_PATTERN.test(name);
+}
+
 // src/agents/orchestrator.ts
 function selectNodes(summaries, strategy, maxNodes) {
   if (summaries.length === 0) return [];
@@ -2360,14 +2382,13 @@ var ELIGIBLE_NODE_TYPES = /* @__PURE__ */ new Set([
   "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;
+    if (isExcludedName(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;
@@ -2752,7 +2773,7 @@ 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
+  - gridBase: spacing grid unit, default 4
   - colorTolerance: color diff tolerance, default 10
   - rules: per-rule overrides (score, severity, enabled)
 
@@ -2770,7 +2791,9 @@ EXAMPLE
 
 USAGE
   canicode analyze <url> --config ./my-config.json
-  See full example: examples/config.json
+
+  Full guide: docs/CUSTOMIZATION.md
+  Examples:   examples/config.json
 `.trimStart());
 }
 var DOCS_TOPICS = {
@@ -2836,7 +2859,6 @@ var absolutePositionInAutoLayoutDef = {
   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;
@@ -2850,7 +2872,8 @@ 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 (node.type === "VECTOR" || node.type === "BOOLEAN_OPERATION" || node.type === "LINE" || node.type === "ELLIPSE" || node.type === "STAR" || node.type === "REGULAR_POLYGON") return null;
+  if (isExcludedName(node.name)) return null;
   if (isSmallRelativeToParent(node, context.parent)) return null;
   if (context.parent.type === "COMPONENT") return null;
   return {
@@ -2876,10 +2899,14 @@ 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;
+  if (node.layoutSizingHorizontal) {
+    if (node.layoutSizingHorizontal !== "FIXED") return null;
+  } else {
+    if (node.layoutAlign === "STRETCH") return null;
+    if (!node.absoluteBoundingBox) return null;
+    if (node.layoutAlign !== "INHERIT") return null;
+  }
+  if (isExcludedName(node.name)) return null;
   return {
     ruleId: fixedWidthInResponsiveContextDef.id,
     nodeId: node.id,
@@ -3152,7 +3179,7 @@ var inconsistentSpacingDef = {
   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 gridBase = options?.["gridBase"] ?? getRuleOption("inconsistent-spacing", "gridBase", 4);
   const paddings = [
     node.paddingLeft,
     node.paddingRight,
@@ -3194,7 +3221,7 @@ var magicNumberSpacingDef = {
   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 gridBase = options?.["gridBase"] ?? getRuleOption("magic-number-spacing", "gridBase", 4);
   const allSpacings = [
     node.paddingLeft,
     node.paddingRight,
@@ -3511,6 +3538,7 @@ var defaultNameDef = {
 };
 var defaultNameCheck = (node, context) => {
   if (!node.name) return null;
+  if (isExcludedName(node.name)) return null;
   if (!isDefaultName(node.name)) return null;
   return {
     ruleId: defaultNameDef.id,
@@ -3533,6 +3561,7 @@ var nonSemanticNameDef = {
 };
 var nonSemanticNameCheck = (node, context) => {
   if (!node.name) return null;
+  if (isExcludedName(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"];
@@ -3601,6 +3630,7 @@ var numericSuffixNameDef = {
 };
 var numericSuffixNameCheck = (node, context) => {
   if (!node.name) return null;
+  if (isExcludedName(node.name)) return null;
   if (isDefaultName(node.name)) return null;
   if (!hasNumericSuffix(node.name)) return null;
   return {
@@ -4040,9 +4070,13 @@ Warning: Analyzing ${totalNodes} nodes without scope. Results may be noisy.`);
 Analyzing: ${file.name}`);
     console.log(`Nodes: ${totalNodes}`);
     let configs = options.preset ? { ...getConfigsWithPreset(options.preset) } : { ...RULE_CONFIGS };
+    let excludeNodeNames;
+    let excludeNodeTypes;
     if (options.config) {
       const configFile = await loadConfigFile(options.config);
       configs = mergeConfigs(configs, configFile);
+      excludeNodeNames = configFile.excludeNodeNames;
+      excludeNodeTypes = configFile.excludeNodeTypes;
       console.log(`Config loaded: ${options.config}`);
     }
     if (options.customRules) {
@@ -4055,7 +4089,9 @@ Analyzing: ${file.name}`);
     }
     const analyzeOptions = {
       configs,
-      ...effectiveNodeId && { targetNodeId: effectiveNodeId }
+      ...effectiveNodeId && { targetNodeId: effectiveNodeId },
+      ...excludeNodeNames && { excludeNodeNames },
+      ...excludeNodeTypes && { excludeNodeTypes }
     };
     const result = analyzeFile(file, analyzeOptions);
     console.log(`Nodes: ${result.nodeCount} (max depth: ${result.maxDepth})`);
@@ -4346,6 +4382,61 @@ cli.command("init", "Set up canicode (Figma token or MCP)").option("--token <tok
     process.exit(1);
   }
 });
+cli.command("list-rules", "List all analysis rules with scores and severity").option("--custom-rules <path>", "Include custom rules from JSON file").option("--config <path>", "Apply config overrides to show effective scores").option("--json", "Output as JSON").action(async (options) => {
+  try {
+    let configs = { ...RULE_CONFIGS };
+    if (options.config) {
+      const configFile = await loadConfigFile(options.config);
+      configs = mergeConfigs(configs, configFile);
+    }
+    if (options.customRules) {
+      const { rules: rules2, configs: customConfigs } = await loadCustomRules(options.customRules);
+      for (const rule of rules2) {
+        ruleRegistry.register(rule);
+      }
+      configs = { ...configs, ...customConfigs };
+    }
+    const rules = ruleRegistry.getAll().map((rule) => {
+      const config2 = configs[rule.definition.id];
+      return {
+        id: rule.definition.id,
+        name: rule.definition.name,
+        category: rule.definition.category,
+        severity: config2?.severity ?? "risk",
+        score: config2?.score ?? 0,
+        enabled: config2?.enabled ?? true
+      };
+    });
+    if (options.json) {
+      console.log(JSON.stringify(rules, null, 2));
+      return;
+    }
+    const byCategory = /* @__PURE__ */ new Map();
+    for (const rule of rules) {
+      const list = byCategory.get(rule.category) ?? [];
+      list.push(rule);
+      byCategory.set(rule.category, list);
+    }
+    for (const [category, catRules] of byCategory) {
+      console.log(`
+  ${category.toUpperCase()}`);
+      for (const r of catRules) {
+        const status = r.enabled ? "" : " (disabled)";
+        const pad = " ".repeat(Math.max(0, 40 - r.id.length));
+        console.log(`    ${r.id}${pad} ${String(r.score).padStart(4)}  ${r.severity}${status}`);
+      }
+    }
+    console.log(`
+  Total: ${rules.length} rules
+`);
+  } 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);
 });