canicode 0.11.1 → 0.11.3

package/dist/mcp/server.js

@@ -1863,9 +1863,11 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version = "0.11.1";
+var version = "0.11.3";
 
 // src/core/engine/scoring.ts
+var GRADE_ORDER = ["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"];
+var DEFAULT_CODEGEN_READY_MIN_GRADE = "A";
 function computeTotalScorePerCategory(configs) {
   const totals = Object.fromEntries(
     CATEGORIES.map((c) => [c, 0])
@@ -1892,8 +1894,9 @@ function calculateGrade(percentage) {
   if (percentage >= 50) return "D";
   return "F";
 }
-function isReadyForCodeGen(grade) {
-  return grade === "S" || grade === "A+" || grade === "A";
+function isReadyForCodeGen(grade, minGrade) {
+  const threshold = minGrade ?? DEFAULT_CODEGEN_READY_MIN_GRADE;
+  return GRADE_ORDER.indexOf(grade) <= GRADE_ORDER.indexOf(threshold);
 }
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -2086,7 +2089,7 @@ function buildResultJson(fileName, result, scores, options) {
     scope: result.scope,
     issueCount: result.issues.length,
     acknowledgedCount: scores.summary.acknowledgedCount,
-    isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade),
+    isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade, options?.codegenReadyMinGrade),
     blockingIssueCount: scores.summary.blocking,
     scores: {
       overall: scores.overall,
@@ -2233,7 +2236,13 @@ var BATCHABLE_RULE_IDS = [
   "no-auto-layout",
   "fixed-size-in-auto-layout"
 ];
+var OPT_IN_BATCHABLE_RULE_IDS = [
+  "missing-prototype"
+];
 var BATCHABLE_SET = new Set(BATCHABLE_RULE_IDS);
+var OPT_IN_BATCHABLE_SET = new Set(
+  OPT_IN_BATCHABLE_RULE_IDS
+);
 var NO_SOURCE_SENTINEL = "_no-source";
 function groupAndBatchSurveyQuestions(questions) {
   if (questions.length === 0) {
@@ -2274,20 +2283,25 @@ function sourceComponentKey(question) {
 }
 function pushIntoBatch(group, question) {
   const sceneWeight = Math.max(question.replicas ?? 1, 1);
-  const isBatchable = BATCHABLE_SET.has(question.ruleId);
+  const batchMode = resolveBatchMode(question.ruleId);
   const last = group.batches.at(-1);
-  if (last !== void 0 && last.ruleId === question.ruleId && isBatchable && last.batchable) {
+  if (last !== void 0 && last.ruleId === question.ruleId && batchMode !== "none" && last.batchMode === batchMode) {
     last.questions.push(question);
     last.totalScenes += sceneWeight;
     return;
   }
   group.batches.push({
     ruleId: question.ruleId,
-    batchable: isBatchable,
+    batchMode,
     questions: [question],
     totalScenes: sceneWeight
   });
 }
+function resolveBatchMode(ruleId) {
+  if (BATCHABLE_SET.has(ruleId)) return "safe";
+  if (OPT_IN_BATCHABLE_SET.has(ruleId)) return "opt-in";
+  return "none";
+}
 
 // src/core/gotcha/survey-generator.ts
 var NODE_PATH_SEPARATOR = " > ";
@@ -2306,12 +2320,18 @@ function generateGotchaSurvey(result, scores, options = {}) {
   const mapped = sorted.map((issue) => mapToQuestion(issue, result.file)).filter((q) => q !== null);
   const questions = deduplicateBySourceComponent(mapped);
   const groupedQuestions = groupAndBatchSurveyQuestions(questions);
+  const PROPAGATION_CANDIDATE_THRESHOLD = 3;
+  const propagationCandidates = questions.filter(
+    (q) => q.isInstanceChild
+  ).length;
+  const suggestedDefaultApply = propagationCandidates >= PROPAGATION_CANDIDATE_THRESHOLD;
   return {
     designGrade: grade,
-    isReadyForCodeGen: isReadyForCodeGen(grade),
+    isReadyForCodeGen: isReadyForCodeGen(grade, options.codegenReadyMinGrade),
     questions,
     groupedQuestions,
-    designKey: options.designKey ?? ""
+    designKey: options.designKey ?? "",
+    suggestedDefaultApply
   };
 }
 function deduplicateSiblingIssues(issues) {
@@ -3563,6 +3583,7 @@ var ConfigFileSchema = z.object({
   excludeNodeTypes: z.array(z.string()).optional(),
   excludeNodeNames: z.array(z.string()).optional(),
   gridBase: z.number().int().positive().optional(),
+  codegenReadyMinGrade: z.enum(["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"]).optional(),
   rules: z.record(z.string(), RuleOverrideSchema).superRefine((rules, ctx) => {
     const unknown = Object.keys(rules).filter((id) => !VALID_RULE_IDS.has(id));
     if (unknown.length > 0) {
@@ -5161,10 +5182,24 @@ defineRule({
 config({ quiet: true });
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../../package.json");
-var server = new McpServer({
-  name: "canicode",
-  version: pkg.version
-});
+var SERVER_INSTRUCTIONS = `canicode has three channels. The MCP tools below cover analysis only \u2014 design write-back is a separate channel.
+
+- **MCP tools** (this server): \`analyze\`, \`gotcha-survey\`, \`list-rules\`, \`docs\`, \`version\`, \`visual-compare\`. Use these for read-only analysis and reports.
+- **Skills** (slash commands, NOT MCP tools): \`/canicode\`, \`/canicode-gotchas\`, \`/canicode-roundtrip\`. Install with \`npx canicode init\` (Claude Code) or \`npx canicode init --cursor-skills\` (Cursor). The roundtrip skill is the only path that writes back to the Figma file via Plugin API.
+- **CLI**: \`npx canicode <command>\` \u2014 same JSON shape as MCP tools, useful for CI / scripting.
+
+If a user asks to "run the roundtrip" or "fix gotchas in Figma" and you don't see \`canicode-roundtrip\` as a slash command, the skill isn't installed yet \u2014 tell them to run \`npx canicode init\`. Don't try to compose roundtrip out of MCP tools; the write-back logic lives in the skill.
+
+Call \`docs\` with topic \`channels\` for the full matrix.`;
+var server = new McpServer(
+  {
+    name: "canicode",
+    version: pkg.version
+  },
+  {
+    instructions: SERVER_INSTRUCTIONS
+  }
+);
 server.tool(
   "analyze",
   `Analyze a Figma design for development-friendliness and AI-friendliness.
@@ -5178,7 +5213,8 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     configPath: z.string().optional().describe("Path to config JSON file for rule overrides"),
     openReport: z.boolean().optional().describe("Open the generated HTML report in the user's browser. Defaults to false \u2014 opt in only when a visible report is the explicit user request (#365). The HTML file is always written to disk regardless."),
     acknowledgments: z.array(AcknowledgmentSchema).optional().describe("(#371 / ADR-019) Pre-resolved acknowledgments from canicode-authored Figma annotations (e.g. via readCanicodeAcknowledgments in a use_figma batch). Each entry includes nodeId and ruleId; newer annotations may also carry intent, sceneWriteOutcome, and codegenDirective from a canicode-json fenced block (#444). Matching issues are flagged acknowledged and contribute half weight to the density score."),
-    scope: z.enum(["page", "component"]).optional().describe("(#404) Override analysis scope \u2014 `page` (screen/section where container bounds are required) or `component` (standalone reusable unit where root FILL is the design contract). Defaults to auto-detection from the root node type: `COMPONENT` / `COMPONENT_SET` / `INSTANCE` roots resolve to `component`, everything else to `page`.")
+    scope: z.enum(["page", "component"]).optional().describe("(#404) Override analysis scope \u2014 `page` (screen/section where container bounds are required) or `component` (standalone reusable unit where root FILL is the design contract). Defaults to auto-detection from the root node type: `COMPONENT` / `COMPONENT_SET` / `INSTANCE` roots resolve to `component`, everything else to `page`."),
+    codegenReadyMinGrade: z.enum(["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"]).optional().describe("Minimum grade for code-gen readiness. Overrides the codegenReadyMinGrade field in configPath. Default: A")
   },
   {
     readOnlyHint: false,
@@ -5186,16 +5222,19 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     openWorldHint: true,
     title: "Analyze Figma Design"
   },
-  async ({ input, token, preset, targetNodeId, configPath, openReport, acknowledgments, scope }) => {
+  async ({ input, token, preset, targetNodeId, configPath, openReport, acknowledgments, scope, codegenReadyMinGrade }) => {
     trackEvent(EVENTS.MCP_TOOL_CALLED, { tool: "analyze" });
     try {
       const { file, nodeId } = await loadFile(input, token);
       const effectiveNodeId = targetNodeId ?? nodeId;
       let configs = preset ? { ...getConfigsWithPreset(preset) } : { ...RULE_CONFIGS };
+      let configFileMinGrade;
       if (configPath) {
         const configFile = await loadConfigFile(configPath);
         configs = mergeConfigs(configs, configFile);
+        configFileMinGrade = configFile.codegenReadyMinGrade;
       }
+      const effectiveMinGrade = codegenReadyMinGrade ?? configFileMinGrade;
       const result = analyzeFile(file, {
         configs,
         ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {},
@@ -5230,7 +5269,7 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
         content: [
           {
             type: "text",
-            text: JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey, designKey: computeDesignKey(input) }), null, 2)
+            text: JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey, designKey: computeDesignKey(input), ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {} }), null, 2)
           }
         ]
       };
@@ -5268,7 +5307,8 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     preset: z.enum(["relaxed", "dev-friendly", "ai-ready", "strict"]).optional().describe("Analysis preset"),
     targetNodeId: z.string().optional().describe("Scope analysis to a specific node ID"),
     configPath: z.string().optional().describe("Path to config JSON file for rule overrides"),
-    scope: z.enum(["page", "component"]).optional().describe("(#404) Override analysis scope \u2014 `page` or `component`. Defaults to auto-detection from the root node type.")
+    scope: z.enum(["page", "component"]).optional().describe("(#404) Override analysis scope \u2014 `page` or `component`. Defaults to auto-detection from the root node type."),
+    codegenReadyMinGrade: z.enum(["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"]).optional().describe("Minimum grade for code-gen readiness. Overrides the codegenReadyMinGrade field in configPath. Default: A")
   },
   {
     readOnlyHint: false,
@@ -5276,23 +5316,29 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     openWorldHint: true,
     title: "Gotcha Survey"
   },
-  async ({ input, token, preset, targetNodeId, configPath, scope }) => {
+  async ({ input, token, preset, targetNodeId, configPath, scope, codegenReadyMinGrade }) => {
     trackEvent(EVENTS.MCP_TOOL_CALLED, { tool: "gotcha-survey" });
     try {
       const { file, nodeId } = await loadFile(input, token);
       const effectiveNodeId = targetNodeId ?? nodeId;
       let configs = preset ? { ...getConfigsWithPreset(preset) } : { ...RULE_CONFIGS };
+      let configFileMinGrade;
       if (configPath) {
         const configFile = await loadConfigFile(configPath);
         configs = mergeConfigs(configs, configFile);
+        configFileMinGrade = configFile.codegenReadyMinGrade;
       }
+      const effectiveMinGrade = codegenReadyMinGrade ?? configFileMinGrade;
       const result = analyzeFile(file, {
         configs,
         ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {},
         ...scope ? { scope } : {}
       });
       const scores = calculateScores(result, configs);
-      const survey = generateGotchaSurvey(result, scores, { designKey: computeDesignKey(input) });
+      const survey = generateGotchaSurvey(result, scores, {
+        designKey: computeDesignKey(input),
+        ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {}
+      });
       trackEvent(EVENTS.ANALYSIS_COMPLETED, {
         nodeCount: result.nodeCount,
         issueCount: result.issues.length,
@@ -5381,6 +5427,7 @@ server.tool(
 
 Available topics:
 - setup: Installation and token configuration
+- channels: Which canicode features are MCP tools vs skills vs CLI \u2014 call this when a user asks for a feature you can't find as an MCP tool
 - scoring: Scoring model formula (density+diversity, severity weights, grades)
 - rules: All rule IDs with default scores and severity
 - config: Config overrides (scores, severity, node exclusions, thresholds)
@@ -5390,7 +5437,7 @@ Available topics:
 
 Use this when the user asks about how to use canicode, configuration, rules, visual comparison, or any feature.`,
   {
-    topic: z.enum(["all", "setup", "scoring", "rules", "config", "visual-compare", "design-tree"]).optional().describe("Topic to retrieve. Default: all")
+    topic: z.enum(["all", "setup", "channels", "scoring", "rules", "config", "visual-compare", "design-tree"]).optional().describe("Topic to retrieve. Default: all")
   },
   {
     readOnlyHint: true,
@@ -5401,6 +5448,23 @@ Use this when the user asks about how to use canicode, configuration, rules, vis
   async ({ topic }) => {
     const selectedTopic = topic ?? "all";
     const inlineTopics = {
+      "channels": `# Channels \u2014 Where Each Feature Lives
+
+canicode is delivered through three channels. Knowing which is which prevents the common confusion where an agent searches the MCP tool list for a feature that actually lives in a skill.
+
+| Feature | Channel | How to invoke |
+|---------|---------|---------------|
+| Analyze a Figma design | MCP tool / CLI | \`analyze\` (this server) or \`npx canicode analyze <url>\` |
+| Generate gotcha questions | MCP tool / CLI | \`gotcha-survey\` or \`npx canicode gotcha-survey <url> --json\` |
+| List rules / get docs / version | MCP tool | \`list-rules\`, \`docs\`, \`version\` |
+| Pixel-compare Figma vs HTML | MCP tool / CLI | \`visual-compare\` |
+| Q&A workflow that saves answers locally | **Skill** (slash command) | \`/canicode-gotchas <url>\` \u2014 install with \`npx canicode init\` |
+| Roundtrip: analyze \u2192 gotcha \u2192 write back to Figma \u2192 re-analyze | **Skill** (slash command) | \`/canicode-roundtrip <url>\` \u2014 install with \`npx canicode init\` |
+| Lightweight analyze-only skill (no MCP install) | **Skill** (slash command) | \`/canicode <url>\` \u2014 install with \`npx canicode init\` |
+
+**Skills are NOT MCP tools.** They are slash commands installed under \`.claude/skills/\` (Claude Code) or \`.cursor/skills/\` (Cursor). If \`canicode-roundtrip\` is not in the slash-command list, the skill isn't installed \u2014 run \`npx canicode init\` (or \`--cursor-skills\` for Cursor).
+
+The roundtrip skill is the **only** path that writes back to the Figma file (via the Figma MCP server's \`use_figma\`). Don't try to compose roundtrip out of \`analyze\` + \`gotcha-survey\` MCP calls \u2014 the write-back orchestration lives inside the skill.`,
       "setup": `# Setup
 
 ## CLI