canicode 0.10.2 → 0.10.4

package/dist/mcp/server.js

@@ -615,6 +615,14 @@ function defineRule(rule) {
   ruleRegistry.register(rule);
   return rule;
 }
+var AcknowledgmentSchema = z.object({
+  nodeId: z.string(),
+  ruleId: z.string()
+});
+z.array(AcknowledgmentSchema);
+function normalizeNodeId(id) {
+  return id.replace(/-/g, ":");
+}
 
 // src/core/engine/rule-engine.ts
 function calculateMaxDepth(node, currentDepth = 0) {
@@ -665,6 +673,7 @@ var RuleEngine = class {
   targetNodeId;
   excludeNamePattern;
   excludeNodeTypes;
+  acknowledgments;
   constructor(options = {}) {
     this.configs = options.configs ?? RULE_CONFIGS;
     this.enabledRuleIds = options.enabledRules ? new Set(options.enabledRules) : null;
@@ -672,6 +681,11 @@ var RuleEngine = class {
     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;
+    this.acknowledgments = new Set(
+      (options.acknowledgments ?? []).map(
+        (a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`
+      )
+    );
   }
   /**
    * Analyze a Figma file and return issues
@@ -706,6 +720,14 @@ var RuleEngine = class {
       void 0,
       void 0
     );
+    if (this.acknowledgments.size > 0) {
+      for (const issue of issues) {
+        const key = `${normalizeNodeId(issue.violation.nodeId)}::${issue.violation.ruleId}`;
+        if (this.acknowledgments.has(key)) {
+          issue.acknowledged = true;
+        }
+      }
+    }
     return {
       file,
       issues,
@@ -1708,8 +1730,6 @@ function resolveTargetProperty(ruleId, subType) {
       if (subType === "horizontal") return "layoutSizingHorizontal";
       return ["layoutSizingHorizontal", "layoutSizingVertical"];
     case "missing-size-constraint":
-      if (subType === "wrap") return "minWidth";
-      if (subType === "max-width") return "maxWidth";
       return ["minWidth", "maxWidth"];
     case "irregular-spacing":
       if (subType === "gap") return "itemSpacing";
@@ -1753,7 +1773,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version = "0.10.2";
+var version = "0.10.4";
 
 // src/core/engine/scoring.ts
 function computeTotalScorePerCategory(configs) {
@@ -1809,7 +1829,8 @@ function calculateScores(result, configs) {
     uniqueRulesPerCategory.get(category).add(ruleId);
     ruleScorePerCategory.get(category).set(ruleId, Math.abs(issue.config.score));
     const ruleCountMap = ruleIssueCountPerCategory.get(category);
-    ruleCountMap.set(ruleId, (ruleCountMap.get(ruleId) ?? 0) + 1);
+    const weight = issue.acknowledged === true ? 0.5 : 1;
+    ruleCountMap.set(ruleId, (ruleCountMap.get(ruleId) ?? 0) + weight);
   }
   for (const category of CATEGORIES) {
     const ruleCountMap = ruleIssueCountPerCategory.get(category);
@@ -1856,7 +1877,8 @@ function calculateScores(result, configs) {
     risk: 0,
     missingInfo: 0,
     suggestion: 0,
-    nodeCount
+    nodeCount,
+    acknowledgedCount: 0
   };
   for (const issue of result.issues) {
     switch (issue.config.severity) {
@@ -1873,6 +1895,7 @@ function calculateScores(result, configs) {
         summary.suggestion++;
         break;
     }
+    if (issue.acknowledged === true) summary.acknowledgedCount++;
   }
   return {
     overall: {
@@ -1923,7 +1946,14 @@ function formatScoreSummary(report) {
   lines.push(`  Risk: ${report.summary.risk}`);
   lines.push(`  Missing Info: ${report.summary.missingInfo}`);
   lines.push(`  Suggestion: ${report.summary.suggestion}`);
-  lines.push(`  Total: ${report.summary.totalIssues}`);
+  if (report.summary.acknowledgedCount > 0) {
+    const unaddressed = report.summary.totalIssues - report.summary.acknowledgedCount;
+    lines.push(
+      `  Total: ${report.summary.totalIssues} (${report.summary.acknowledgedCount} acknowledged via canicode annotations / ${unaddressed} unaddressed)`
+    );
+  } else {
+    lines.push(`  Total: ${report.summary.totalIssues}`);
+  }
   return lines.join("\n");
 }
 function buildResultJson(fileName, result, scores, options) {
@@ -1947,17 +1977,20 @@ function buildResultJson(fileName, result, scores, options) {
       ...applyContext.annotationProperties !== void 0 ? { annotationProperties: applyContext.annotationProperties } : {},
       ...suggestedName !== void 0 ? { suggestedName } : {},
       isInstanceChild: applyContext.isInstanceChild,
-      ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {}
+      ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {},
+      ...issue.acknowledged === true ? { acknowledged: true } : {}
     };
   });
   const json = {
     version,
     analyzedAt: result.analyzedAt,
     ...options?.fileKey && { fileKey: options.fileKey },
+    ...options?.designKey && { designKey: options.designKey },
     fileName,
     nodeCount: result.nodeCount,
     maxDepth: result.maxDepth,
     issueCount: result.issues.length,
+    acknowledgedCount: scores.summary.acknowledgedCount,
     isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade),
     blockingIssueCount: scores.summary.blocking,
     scores: {
@@ -2084,26 +2117,97 @@ var GOTCHA_QUESTIONS = {
   }
 };
 
+// src/core/gotcha/group-and-batch-questions.ts
+var BATCHABLE_RULE_IDS = [
+  "missing-size-constraint",
+  "irregular-spacing",
+  "no-auto-layout",
+  "fixed-size-in-auto-layout"
+];
+var BATCHABLE_SET = new Set(BATCHABLE_RULE_IDS);
+var NO_SOURCE_SENTINEL = "_no-source";
+function groupAndBatchSurveyQuestions(questions) {
+  if (questions.length === 0) {
+    return { groups: [] };
+  }
+  const sorted = [...questions].sort(compareQuestions);
+  const groups = [];
+  let currentGroup = null;
+  let lastGroupKey = null;
+  for (const question of sorted) {
+    const groupKey = sourceComponentKey(question);
+    if (currentGroup === null || groupKey !== lastGroupKey) {
+      currentGroup = {
+        instanceContext: question.instanceContext ?? null,
+        batches: []
+      };
+      groups.push(currentGroup);
+      lastGroupKey = groupKey;
+    }
+    pushIntoBatch(currentGroup, question);
+  }
+  return { groups };
+}
+function compareQuestions(a, b) {
+  const aKey = sourceComponentKey(a);
+  const bKey = sourceComponentKey(b);
+  if (aKey !== bKey) {
+    if (aKey === NO_SOURCE_SENTINEL) return 1;
+    if (bKey === NO_SOURCE_SENTINEL) return -1;
+    return aKey.localeCompare(bKey);
+  }
+  if (a.ruleId !== b.ruleId) return a.ruleId.localeCompare(b.ruleId);
+  if (a.nodeName !== b.nodeName) return a.nodeName.localeCompare(b.nodeName);
+  return a.nodeId.localeCompare(b.nodeId);
+}
+function sourceComponentKey(question) {
+  return question.instanceContext?.sourceComponentId ?? NO_SOURCE_SENTINEL;
+}
+function pushIntoBatch(group, question) {
+  const sceneWeight = Math.max(question.replicas ?? 1, 1);
+  const isBatchable = BATCHABLE_SET.has(question.ruleId);
+  const last = group.batches.at(-1);
+  if (last !== void 0 && last.ruleId === question.ruleId && isBatchable && last.batchable) {
+    last.questions.push(question);
+    last.totalScenes += sceneWeight;
+    return;
+  }
+  group.batches.push({
+    ruleId: question.ruleId,
+    batchable: isBatchable,
+    questions: [question],
+    totalScenes: sceneWeight
+  });
+}
+
 // src/core/gotcha/survey-generator.ts
 var NODE_PATH_SEPARATOR = " > ";
-function generateGotchaSurvey(result, scores) {
+function generateGotchaSurvey(result, scores, options = {}) {
   const grade = scores.overall.grade;
   const relevantIssues = result.issues.filter(
     (issue) => issue.config.severity === "blocking" || issue.config.severity === "risk"
   );
   const deduped = deduplicateSiblingIssues(relevantIssues);
   const sorted = stableSortBySeverity(deduped);
-  const questions = sorted.map((issue) => mapToQuestion(issue, result.file)).filter((q) => q !== null);
+  const mapped = sorted.map((issue) => mapToQuestion(issue, result.file)).filter((q) => q !== null);
+  const questions = deduplicateBySourceComponent(mapped);
+  const groupedQuestions = groupAndBatchSurveyQuestions(questions);
   return {
     designGrade: grade,
     isReadyForCodeGen: isReadyForCodeGen(grade),
-    questions
+    questions,
+    groupedQuestions,
+    designKey: options.designKey ?? ""
   };
 }
 function deduplicateSiblingIssues(issues) {
   const seen = /* @__PURE__ */ new Set();
   const result = [];
   for (const issue of issues) {
+    if (isInstanceChildNodeId(issue.violation.nodeId)) {
+      result.push(issue);
+      continue;
+    }
     const parentPath = getParentPath(issue.violation.nodePath);
     const key = `${parentPath}||${issue.violation.ruleId}`;
     if (!seen.has(key)) {
@@ -2163,6 +2267,50 @@ function mapToQuestion(issue, file) {
     ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {}
   };
 }
+function deduplicateBySourceComponent(questions) {
+  const groups = /* @__PURE__ */ new Map();
+  const order = [];
+  let uniqueCounter = 0;
+  for (const q of questions) {
+    const ic = q.instanceContext;
+    let key;
+    if (ic && ic.sourceComponentId && ic.sourceNodeId) {
+      key = `${ic.sourceComponentId}::${ic.sourceNodeId}::${q.ruleId}`;
+    } else {
+      key = `__unique__${uniqueCounter++}`;
+    }
+    const bucket = groups.get(key);
+    if (bucket) {
+      bucket.push(q);
+    } else {
+      groups.set(key, [q]);
+      order.push(key);
+    }
+  }
+  return order.map((key) => {
+    const group = groups.get(key);
+    const first = group[0];
+    if (group.length === 1) return first;
+    const otherIds = group.slice(1).map((q) => q.nodeId);
+    const sourceComponentName = first.instanceContext?.sourceComponentName;
+    const template = GOTCHA_QUESTIONS[first.ruleId];
+    const renamed = {
+      ...first,
+      replicas: group.length,
+      replicaNodeIds: otherIds
+    };
+    if (sourceComponentName) {
+      renamed.nodeName = sourceComponentName;
+      if (template) {
+        renamed.question = template.question.replace(
+          "{nodeName}",
+          sourceComponentName
+        );
+      }
+    }
+    return renamed;
+  });
+}
 function buildInstanceContext(nodeId, file) {
   const parts = parseInstanceChildNodeId(nodeId);
   if (!parts) return null;
@@ -3494,6 +3642,18 @@ function shutdownMonitoring() {
 // src/core/monitoring/keys.ts
 var POSTHOG_API_KEY = "phc_rBFeG140KqJLpUnlpYDEFgdMM6JozZeqQsf9twXf5Dq" ;
 var SENTRY_DSN = "https://80a836a8300b25f17ef5bbf23afb5b3a@o4511080656207872.ingest.us.sentry.io/4511080661319680" ;
+function isFigmaUrl2(input) {
+  return input.includes("figma.com/");
+}
+z.string();
+function computeDesignKey(input) {
+  if (isFigmaUrl2(input)) {
+    const { fileKey, nodeId } = parseFigmaUrl(input);
+    if (!nodeId) return fileKey;
+    return `${fileKey}#${nodeId.replace(/-/g, ":")}`;
+  }
+  return resolve(input);
+}
 
 // src/core/rules/node-semantics.ts
 function isContainerNode(node) {
@@ -4600,6 +4760,7 @@ var inconsistentNamingConventionCheck = (node, context) => {
   if (nodeConvention && nodeConvention !== dominantConvention && maxCount >= 2) {
     if (isCompatible(nodeConvention, dominantConvention, node.name)) return null;
     const suggested = convertName(node.name, dominantConvention);
+    if (suggested === node.name) return null;
     return {
       ruleId: inconsistentNamingConventionDef.id,
       nodeId: node.id,
@@ -4695,6 +4856,15 @@ function hasStateInComponentMaster(node, context, statePattern) {
   if (!master) return false;
   return hasStateInVariantProps(master, statePattern);
 }
+function canDetermineVariants(node, context) {
+  if (node.type === "COMPONENT") return true;
+  if (node.componentPropertyDefinitions !== void 0) return true;
+  if (node.componentId !== void 0) {
+    const defs = context.file.componentDefinitions;
+    if (defs && defs[node.componentId] !== void 0) return true;
+  }
+  return false;
+}
 var missingInteractionStateDef = {
   id: "missing-interaction-state",
   name: "Missing Interaction State",
@@ -4709,6 +4879,7 @@ var missingInteractionStateCheck = (node, context) => {
   if (!interactiveType) return null;
   const expectedStates = EXPECTED_STATES[interactiveType];
   if (!expectedStates) return null;
+  if (!canDetermineVariants(node, context)) return null;
   const seen = getSeen(context);
   const nodePath = context.path.join(" > ");
   for (const state of expectedStates) {
@@ -4827,7 +4998,9 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
     token: z.string().optional().describe("Figma API token (falls back to FIGMA_TOKEN env var)"),
     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")
+    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) Pre-resolved [{ nodeId, ruleId }] pairs harvested from canicode-authored Figma annotations (e.g. via the `readCanicodeAcknowledgments` Plugin helper inside a use_figma batch). Matching issues are flagged `acknowledged: true` and contribute half weight to the density score so re-analyze surfaces movement after a roundtrip even under ADR-012's annotate-by-default policy.")
   },
   {
     readOnlyHint: false,
@@ -4835,7 +5008,7 @@ 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 }) => {
+  async ({ input, token, preset, targetNodeId, configPath, openReport, acknowledgments }) => {
     trackEvent(EVENTS.MCP_TOOL_CALLED, { tool: "analyze" });
     try {
       const { file, nodeId } = await loadFile(input, token);
@@ -4847,7 +5020,8 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
       }
       const result = analyzeFile(file, {
         configs,
-        ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {}
+        ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {},
+        ...acknowledgments && acknowledgments.length > 0 ? { acknowledgments } : {}
       });
       const scores = calculateScores(result, configs);
       const figmaToken = token ?? process.env["FIGMA_TOKEN"];
@@ -4856,14 +5030,16 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
       const ts = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}-${String(now.getHours()).padStart(2, "0")}-${String(now.getMinutes()).padStart(2, "0")}`;
       ensureReportsDir();
       const reportPath = `${getReportsDir()}/report-${ts}-${file.fileKey}.html`;
-      await new Promise((resolve5, reject) => {
+      await new Promise((resolve6, reject) => {
         writeFile(reportPath, html, "utf-8", (err) => {
           if (err) reject(err);
-          else resolve5();
+          else resolve6();
         });
       });
-      const openCmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-      exec(`${openCmd} "${reportPath}"`);
+      if (openReport === true) {
+        const openCmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+        exec(`${openCmd} "${reportPath}"`);
+      }
       trackEvent(EVENTS.ANALYSIS_COMPLETED, {
         nodeCount: result.nodeCount,
         issueCount: result.issues.length,
@@ -4875,7 +5051,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 }), null, 2)
+            text: JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey, designKey: computeDesignKey(input) }), null, 2)
           }
         ]
       };
@@ -4935,7 +5111,7 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
         ...effectiveNodeId ? { targetNodeId: effectiveNodeId } : {}
       });
       const scores = calculateScores(result, configs);
-      const survey = generateGotchaSurvey(result, scores);
+      const survey = generateGotchaSurvey(result, scores, { designKey: computeDesignKey(input) });
       trackEvent(EVENTS.ANALYSIS_COMPLETED, {
         nodeCount: result.nodeCount,
         issueCount: result.issues.length,
@@ -5056,10 +5232,10 @@ Get your token: Figma \u2192 Settings \u2192 Security \u2192 Personal access tok
 
 ## MCP Server (Claude Code / Cursor / Claude Desktop)
 \`\`\`bash
-claude mcp add canicode -e FIGMA_TOKEN=figd_xxxxxxxxxxxxx -- npx -y -p canicode canicode-mcp
+claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 \`\`\`
 
-Requires FIGMA_TOKEN for live Figma URL analysis.
+Requires FIGMA_TOKEN for live Figma URL analysis. The MCP server reads it from \`~/.canicode/config.json\` (set via \`canicode init --token \u2026\`) or from the host's environment, so do **not** pass \`-e FIGMA_TOKEN=\u2026\` to \`claude mcp add\` \u2014 \`@anthropic-ai/claude-code\`'s current parser rejects short-form flags placed before \`--\`. (#364, #366)
 
 ## CLI only (no MCP server)
 
@@ -5179,16 +5355,16 @@ ${inlineTopics[selectedTopic]}` }]
       };
     }
     const { readFile: readFile3 } = await import('fs/promises');
-    const { resolve: resolve5, dirname: dirname4 } = await import('path');
+    const { resolve: resolve6, dirname: dirname4 } = await import('path');
     const { fileURLToPath } = await import('url');
     try {
       const __dirname = dirname4(fileURLToPath(import.meta.url));
-      const docPath = resolve5(__dirname, "../../docs/CUSTOMIZATION.md");
+      const docPath = resolve6(__dirname, "../../docs/CUSTOMIZATION.md");
       let content;
       try {
         content = await readFile3(docPath, "utf-8");
       } catch {
-        const altPath = resolve5(__dirname, "../docs/CUSTOMIZATION.md");
+        const altPath = resolve6(__dirname, "../docs/CUSTOMIZATION.md");
         content = await readFile3(altPath, "utf-8");
       }
       if (selectedTopic !== "all") {