canicode 0.4.0 → 0.5.0

package/README.md

@@ -144,33 +144,6 @@ 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>
@@ -206,6 +179,43 @@ See [`examples/config.json`](examples/config.json) | [`docs/CUSTOMIZATION.md`](d
 
 </details>
 
+<details>
+<summary><strong>Custom Rules</strong></summary>
+
+Add project-specific checks with declarative pattern matching:
+
+```bash
+canicode analyze <url> --custom-rules ./my-rules.json
+```
+
+```json
+[
+  {
+    "id": "icon-not-component",
+    "category": "component",
+    "severity": "blocking",
+    "score": -10,
+    "match": {
+      "type": ["FRAME", "GROUP"],
+      "maxWidth": 48,
+      "maxHeight": 48,
+      "hasChildren": true,
+      "nameContains": "icon"
+    },
+    "message": "\"{name}\" is an icon but not a component",
+    "why": "Icons that are not components cannot be reused consistently.",
+    "impact": "Developers will hardcode icon SVGs instead of using a shared component.",
+    "fix": "Convert this icon to a component and publish it to the design system library."
+  }
+]
+```
+
+Conditions use AND logic — all must match for the rule to fire. Available conditions: `type`, `notType`, `nameContains`, `nameNotContains`, `namePattern`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `hasAutoLayout`, `hasChildren`, `minChildren`, `maxChildren`, `isComponent`, `isInstance`, `hasComponentId`, `isVisible`, `hasFills`, `hasStrokes`, `hasEffects`, `minDepth`, `maxDepth`.
+
+See [`examples/custom-rules.json`](examples/custom-rules.json) | [`docs/CUSTOMIZATION.md`](docs/CUSTOMIZATION.md)
+
+</details>
+
 <details>
 <summary><strong>Scoring Algorithm</strong></summary>
 
@@ -308,9 +318,10 @@ pnpm lint       # type check
 
 - [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 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)
-- [ ] **Phase 5** — Screenshot comparison (Figma vs AI-generated code, visual diff)
+- [x] **Phase 5** — Custom rules with pattern matching (node name/type/attribute conditions)
+- [ ] **Phase 6** — Screenshot comparison (Figma vs AI-generated code, visual diff)
 
 ## License
 

package/dist/cli/index.js

@@ -1487,15 +1487,50 @@ function formatScoreSummary(report) {
   lines.push(`  Total: ${report.summary.totalIssues}`);
   return lines.join("\n");
 }
+var MatchConditionSchema = z.object({
+  // Node type conditions
+  type: z.array(z.string()).optional(),
+  notType: z.array(z.string()).optional(),
+  // Name conditions (case-insensitive, substring match)
+  nameContains: z.string().optional(),
+  nameNotContains: z.string().optional(),
+  namePattern: z.string().optional(),
+  // Size conditions
+  minWidth: z.number().optional(),
+  maxWidth: z.number().optional(),
+  minHeight: z.number().optional(),
+  maxHeight: z.number().optional(),
+  // Layout conditions
+  hasAutoLayout: z.boolean().optional(),
+  hasChildren: z.boolean().optional(),
+  minChildren: z.number().optional(),
+  maxChildren: z.number().optional(),
+  // Component conditions
+  isComponent: z.boolean().optional(),
+  isInstance: z.boolean().optional(),
+  hasComponentId: z.boolean().optional(),
+  // Visibility
+  isVisible: z.boolean().optional(),
+  // Fill/style conditions
+  hasFills: z.boolean().optional(),
+  hasStrokes: z.boolean().optional(),
+  hasEffects: z.boolean().optional(),
+  // Depth condition
+  minDepth: z.number().optional(),
+  maxDepth: z.number().optional()
+});
 var CustomRuleSchema = z.object({
   id: z.string(),
   category: CategorySchema,
   severity: SeveritySchema,
   score: z.number().int().max(0),
-  prompt: z.string(),
+  match: MatchConditionSchema,
+  message: z.string().optional(),
   why: z.string(),
   impact: z.string(),
-  fix: z.string()
+  fix: z.string(),
+  // Backward compat: silently ignore the old prompt field
+  prompt: z.string().optional()
 });
 var CustomRulesFileSchema = z.array(CustomRuleSchema);
 
@@ -1508,6 +1543,7 @@ async function loadCustomRules(filePath) {
   const rules = [];
   const configs = {};
   for (const cr of customRules) {
+    if (!cr.match) continue;
     rules.push(toRule(cr));
     configs[cr.id] = {
       severity: cr.severity,
@@ -1527,13 +1563,52 @@ function toRule(cr) {
       impact: cr.impact,
       fix: cr.fix
     },
-    check: createPromptBasedCheck()
+    check: createPatternCheck(cr)
   };
 }
-function createPromptBasedCheck(_cr) {
-  return (node, _context) => {
+function createPatternCheck(cr) {
+  return (node, context) => {
     if (node.type === "DOCUMENT" || node.type === "CANVAS") return null;
-    return null;
+    const match = cr.match;
+    if (match.type && !match.type.includes(node.type)) return null;
+    if (match.notType && match.notType.includes(node.type)) return null;
+    if (match.nameContains !== void 0 && !node.name.toLowerCase().includes(match.nameContains.toLowerCase())) return null;
+    if (match.nameNotContains !== void 0 && node.name.toLowerCase().includes(match.nameNotContains.toLowerCase())) return null;
+    if (match.namePattern !== void 0 && !new RegExp(match.namePattern, "i").test(node.name)) return null;
+    const bbox = node.absoluteBoundingBox;
+    if (match.minWidth !== void 0 && (!bbox || bbox.width < match.minWidth)) return null;
+    if (match.maxWidth !== void 0 && (!bbox || bbox.width > match.maxWidth)) return null;
+    if (match.minHeight !== void 0 && (!bbox || bbox.height < match.minHeight)) return null;
+    if (match.maxHeight !== void 0 && (!bbox || bbox.height > match.maxHeight)) return null;
+    if (match.hasAutoLayout === true && !node.layoutMode) return null;
+    if (match.hasAutoLayout === false && node.layoutMode) return null;
+    if (match.hasChildren === true && (!node.children || node.children.length === 0)) return null;
+    if (match.hasChildren === false && node.children && node.children.length > 0) return null;
+    if (match.minChildren !== void 0 && (!node.children || node.children.length < match.minChildren)) return null;
+    if (match.maxChildren !== void 0 && node.children && node.children.length > match.maxChildren) return null;
+    if (match.isComponent === true && node.type !== "COMPONENT" && node.type !== "COMPONENT_SET") return null;
+    if (match.isComponent === false && (node.type === "COMPONENT" || node.type === "COMPONENT_SET")) return null;
+    if (match.isInstance === true && node.type !== "INSTANCE") return null;
+    if (match.isInstance === false && node.type === "INSTANCE") return null;
+    if (match.hasComponentId === true && !node.componentId) return null;
+    if (match.hasComponentId === false && node.componentId) return null;
+    if (match.isVisible === true && !node.visible) return null;
+    if (match.isVisible === false && node.visible) return null;
+    if (match.hasFills === true && (!node.fills || node.fills.length === 0)) return null;
+    if (match.hasFills === false && node.fills && node.fills.length > 0) return null;
+    if (match.hasStrokes === true && (!node.strokes || node.strokes.length === 0)) return null;
+    if (match.hasStrokes === false && node.strokes && node.strokes.length > 0) return null;
+    if (match.hasEffects === true && (!node.effects || node.effects.length === 0)) return null;
+    if (match.hasEffects === false && node.effects && node.effects.length > 0) return null;
+    if (match.minDepth !== void 0 && context.depth < match.minDepth) return null;
+    if (match.maxDepth !== void 0 && context.depth > match.maxDepth) return null;
+    const msg = (cr.message ?? `"${node.name}" matched custom rule "${cr.id}"`).replace(/\{name\}/g, node.name).replace(/\{type\}/g, node.type);
+    return {
+      ruleId: cr.id,
+      nodeId: node.id,
+      nodePath: context.path.join(" > "),
+      message: msg
+    };
   };
 }
 var RuleOverrideSchema = z.object({
@@ -2945,35 +3020,56 @@ function printDocsRules() {
   console.log(`
 CUSTOM RULES GUIDE
 
-Custom rules let you add project-specific checks beyond canicode's built-in 39 rules.
+Add project-specific checks with declarative pattern matching.
+All conditions in "match" use AND logic \u2014 every condition must be true to flag a node.
 
-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
+MATCH CONDITIONS
+  type: ["FRAME","GROUP"]     Node type must be one of these
+  notType: ["INSTANCE"]       Node type must NOT be one of these
+  nameContains: "icon"        Name contains (case-insensitive)
+  nameNotContains: "badge"    Name does NOT contain
+  namePattern: "^btn-"        Regex pattern on name
+  minWidth / maxWidth         Size constraints (px)
+  minHeight / maxHeight       Size constraints (px)
+  hasAutoLayout: true/false   Has layoutMode set
+  hasChildren: true/false     Has child nodes
+  minChildren / maxChildren   Child count range
+  isComponent: true/false     Is COMPONENT or COMPONENT_SET
+  isInstance: true/false       Is INSTANCE
+  hasComponentId: true/false  Has componentId
+  isVisible: true/false       Visibility
+  hasFills / hasStrokes       Has fills or strokes
+  hasEffects: true/false      Has effects
+  minDepth / maxDepth         Tree depth range
 
 EXAMPLE
   [
     {
-      "id": "icon-missing-component",
+      "id": "icon-not-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."
+      "match": {
+        "type": ["FRAME", "GROUP"],
+        "maxWidth": 48,
+        "maxHeight": 48,
+        "nameContains": "icon"
+      },
+      "message": ""{name}" is an icon but not a component",
+      "why": "Icons should be reusable components.",
+      "impact": "Developers hardcode icons.",
+      "fix": "Convert to component and publish to library."
     }
   ]
 
 USAGE
   canicode analyze <url> --custom-rules ./my-rules.json
-  See full example: examples/custom-rules.json
+
+  Full guide: docs/CUSTOMIZATION.md
+  Examples:   examples/custom-rules.json
+
+TIP: Ask any LLM "Write a canicode custom rule that checks X" with the
+  match conditions above. It can generate the JSON for you.
 `.trimStart());
 }
 function printDocsConfig() {
@@ -4807,8 +4903,8 @@ cli.help((sections) => {
     {
       title: "\nCustomization",
       body: [
-        `  --custom-rules <path>   Add custom rules (see: canicode docs rules)`,
-        `  --config <path>         Override rule settings (see: canicode docs config)`
+        `  --config <path>         Override rule settings (see: canicode docs config)`,
+        `  --custom-rules <path>   Add custom rules (see: canicode docs rules)`
       ].join("\n")
     },
     {
@@ -4817,8 +4913,7 @@ cli.help((sections) => {
         `  $ 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`
+        `  $ canicode analyze "https://www.figma.com/design/..." --config ./my-config.json`
       ].join("\n")
     },
     {