canicode 0.11.5 → 0.12.1

package/dist/mcp/server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { writeFile, existsSync, statSync, mkdirSync, chmodSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
-import { join, resolve, basename, dirname } from 'path';
+import { writeFile, existsSync, statSync, mkdirSync, readFileSync, chmodSync, writeFileSync, readdirSync, copyFileSync } from 'fs';
+import { join, resolve, basename, dirname, isAbsolute, sep } from 'path';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
 import { createRequire } from 'module';
@@ -302,7 +302,14 @@ var SeveritySchema = z.enum([
   "blocking",
   "risk",
   "missing-info",
-  "suggestion"
+  "suggestion",
+  /**
+   * `note` is the zero-impact tier (#519): findings render in the report but
+   * never move the grade. Used for annotation-primary rules whose value is the
+   * nudge, not the score (e.g. unmapped Code Connect components, info-collection
+   * rules whose answers belong in figma-implement-design context, not in linting).
+   */
+  "note"
 ]);
 
 // src/core/contracts/rule.ts
@@ -348,6 +355,7 @@ var RULE_ID_CATEGORY = {
   "detached-instance": "code-quality",
   "variant-structure-mismatch": "code-quality",
   "deep-nesting": "code-quality",
+  "unmapped-component": "code-quality",
   // Token Management
   "raw-value": "token-management",
   "irregular-spacing": "token-management",
@@ -378,6 +386,12 @@ var RULE_PURPOSE = {
   "detached-instance": "violation",
   "variant-structure-mismatch": "violation",
   "deep-nesting": "violation",
+  // #520: unmapped-component is annotation-primary. Fires only when the
+  // user has Code Connect set up at all (figma.config.json present in cwd).
+  // The gotcha drives the user to /canicode-roundtrip for actual mapping
+  // registration via the Figma MCP tools — analyze itself does not parse
+  // mapping declarations (deferred to v1.5).
+  "unmapped-component": "info-collection",
   // Token Management
   "raw-value": "violation",
   "irregular-spacing": "violation",
@@ -421,12 +435,12 @@ var RULE_CONFIGS = {
     enabled: true
   },
   "missing-size-constraint": {
-    // #403: severity downgraded `risk → missing-info` and score from
-    // -8 → -1 to match the new info-collection purpose. Keeping the
-    // rule enabled (not disabled) so its gotchas still surface in the
-    // survey — see RULE_PURPOSE entry above for the full rationale.
-    severity: "missing-info",
-    score: -1,
+    // #403 → #519: info-collection rule. Score is 0 (severity `note`):
+    // its value is the gotcha annotation, not the grade impact. Survey-
+    // generator includes this rule via the `purpose === "info-collection"`
+    // branch so the gotcha keeps surfacing.
+    severity: "note",
+    score: 0,
     enabled: true
   },
   // ── Code Quality ──
@@ -458,6 +472,16 @@ var RULE_CONFIGS = {
       maxDepth: 5
     }
   },
+  "unmapped-component": {
+    // #520 / #519: zero-impact tier. Fires per main component when Code
+    // Connect is set up in the consuming repo (figma.config.json at cwd).
+    // Score is 0 because the rule's value is the gotcha + roundtrip handoff,
+    // not the grade signal — designers who deliberately do not map (e.g.
+    // marketing-only banners) are not punished.
+    severity: "note",
+    score: 0,
+    enabled: true
+  },
   // ── Token Management ──
   "raw-value": {
     severity: "missing-info",
@@ -479,15 +503,15 @@ var RULE_CONFIGS = {
   // is minimal. Score stays at -1 so re-enabling `missing-prototype` on
   // fixtures that lack `interactionDestinations` (#139) cannot swing grades.
   "missing-interaction-state": {
-    severity: "missing-info",
-    score: -1,
-    // uncalibrated: no metric to validate score (#210), kept at -1 to preserve category visibility
+    severity: "note",
+    // #519: info-collection rule, zero-score tier
+    score: 0,
     enabled: true
   },
   "missing-prototype": {
-    severity: "missing-info",
-    score: -1,
-    // #406: info-collection — annotation is primary output; score kept minimal so #139 fixtures don't skew calibration
+    severity: "note",
+    // #519: info-collection — annotation is primary output, no grade impact
+    score: 0,
     enabled: true
   },
   // ── Semantic ──
@@ -671,11 +695,31 @@ function defineRule(rule) {
   ruleRegistry.register(rule);
   return rule;
 }
-var AcknowledgmentIntentSchema = z.object({
+var PropertyAcknowledgmentIntentSchema = z.object({
+  kind: z.literal("property").default("property"),
   field: z.string(),
   value: z.unknown(),
   scope: z.enum(["instance", "definition"])
 });
+var RuleOptOutAcknowledgmentIntentSchema = z.object({
+  kind: z.literal("rule-opt-out"),
+  ruleId: z.string()
+}).strict();
+var AcknowledgmentIntentSchema = z.preprocess((raw) => {
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw;
+    if (obj["kind"] === void 0) {
+      return { ...obj, kind: "property" };
+    }
+  }
+  return raw;
+}, z.discriminatedUnion("kind", [
+  PropertyAcknowledgmentIntentSchema,
+  RuleOptOutAcknowledgmentIntentSchema
+]));
+function isRuleOptOutIntent(intent) {
+  return intent !== void 0 && intent.kind === "rule-opt-out";
+}
 var AcknowledgmentSceneWriteOutcomeSchema = z.object({
   result: z.enum([
     "succeeded",
@@ -753,6 +797,7 @@ var RuleEngine = class {
   excludeNamePattern;
   excludeNodeTypes;
   acknowledgments;
+  acknowledgmentsByKey;
   scopeOverride;
   constructor(options = {}) {
     this.configs = options.configs ?? RULE_CONFIGS;
@@ -761,10 +806,15 @@ 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;
+    const ackList = options.acknowledgments ?? [];
     this.acknowledgments = new Set(
-      (options.acknowledgments ?? []).map(
-        (a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`
-      )
+      ackList.map((a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`)
+    );
+    this.acknowledgmentsByKey = new Map(
+      ackList.map((a) => [
+        `${normalizeNodeId(a.nodeId)}::${a.ruleId}`,
+        a
+      ])
     );
     this.scopeOverride = options.scope;
   }
@@ -848,6 +898,7 @@ var RuleEngine = class {
     if (this.excludeNamePattern && this.excludeNamePattern.test(node.name)) {
       return;
     }
+    const acknowledgmentsByKey = this.acknowledgmentsByKey;
     const context = {
       file,
       parent,
@@ -859,7 +910,8 @@ var RuleEngine = class {
       siblings,
       analysisState,
       scope,
-      rootNodeType
+      rootNodeType,
+      findAcknowledgment: (nodeId, ruleId) => acknowledgmentsByKey.get(`${normalizeNodeId(nodeId)}::${ruleId}`)
     };
     for (const rule of rules) {
       const ruleId = rule.definition.id;
@@ -1023,6 +1075,32 @@ var FigmaClient = class _FigmaClient {
     const buffer = await response.arrayBuffer();
     return Buffer.from(buffer).toString("base64");
   }
+  /**
+   * Get the components a file has published to a team library.
+   *
+   * `GET /v1/files/:file_key/components` returns only components that have
+   * been pushed via the Publish Library action — local-but-unpublished
+   * components are absent. This is the authoritative way to detect whether
+   * a Figma component is mappable via Code Connect (#532): `add_code_connect_map`
+   * requires a published component and otherwise fails with "Published
+   * component not found."
+   */
+  async getPublishedComponents(fileKey) {
+    const url = `${FIGMA_API_BASE}/files/${fileKey}/components`;
+    const response = await fetch(url, {
+      headers: { "X-Figma-Token": this.token }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new FigmaClientError(
+        `Failed to fetch published components: ${response.status} ${response.statusText}`,
+        response.status,
+        error
+      );
+    }
+    const data = await response.json();
+    return data.meta?.components ?? [];
+  }
   async getFileNodes(fileKey, nodeIds) {
     const ids = nodeIds.join(",");
     const url = `${FIGMA_API_BASE}/files/${fileKey}/nodes?ids=${encodeURIComponent(ids)}`;
@@ -1805,6 +1883,7 @@ var STRATEGY_BY_RULE = {
   // Strategy C — annotation only
   "absolute-position-in-auto-layout": "annotation",
   "variant-structure-mismatch": "annotation",
+  "unmapped-component": "annotation",
   // Strategy D — auto-fix lower-severity issues from analyze output
   "non-standard-naming": "auto-fix",
   "inconsistent-naming-convention": "auto-fix",
@@ -1839,6 +1918,7 @@ function resolveTargetProperty(ruleId, subType) {
     case "raw-value":
     case "missing-interaction-state":
     case "missing-prototype":
+    case "unmapped-component":
       return void 0;
   }
 }
@@ -1863,7 +1943,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version = "0.11.5";
+var version = "0.12.1";
 
 // src/core/engine/scoring.ts
 var GRADE_ORDER = ["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"];
@@ -1970,6 +2050,7 @@ function calculateScores(result, configs) {
     risk: 0,
     missingInfo: 0,
     suggestion: 0,
+    note: 0,
     nodeCount,
     acknowledgedCount: 0
   };
@@ -1987,6 +2068,9 @@ function calculateScores(result, configs) {
       case "suggestion":
         summary.suggestion++;
         break;
+      case "note":
+        summary.note++;
+        break;
     }
     if (issue.acknowledged === true) summary.acknowledgedCount++;
   }
@@ -2018,7 +2102,8 @@ function initializeCategoryScores() {
         blocking: 0,
         risk: 0,
         "missing-info": 0,
-        suggestion: 0
+        suggestion: 0,
+        note: 0
       }
     };
   }
@@ -2039,6 +2124,7 @@ function formatScoreSummary(report) {
   lines.push(`  Risk: ${report.summary.risk}`);
   lines.push(`  Missing Info: ${report.summary.missingInfo}`);
   lines.push(`  Suggestion: ${report.summary.suggestion}`);
+  lines.push(`  Note: ${report.summary.note}`);
   if (report.summary.acknowledgedCount > 0) {
     const unaddressed = report.summary.totalIssues - report.summary.acknowledgedCount;
     lines.push(
@@ -2049,6 +2135,19 @@ function formatScoreSummary(report) {
   }
   return lines.join("\n");
 }
+function formatCodeConnectCoverageLine(coverage) {
+  const { mapped, total } = coverage;
+  const pct = total === 0 ? 0 : Math.round(mapped / total * 100);
+  return `Code Connect coverage: ${mapped}/${total} components (${pct}%) mapped`;
+}
+var ROUNDTRIP_OPT_OUT_HINT = "Some components may carry roundtrip-recorded opt-outs that this standalone analyze cannot see (Figma REST annotations field is in private beta). Run /canicode-roundtrip to apply opt-outs.";
+function formatRoundtripOptOutHintLine(issues, acknowledgmentsProvided) {
+  const hasUnmapped = issues.some(
+    (issue) => issue.violation.ruleId === "unmapped-component"
+  );
+  if (!hasUnmapped) return null;
+  return ROUNDTRIP_OPT_OUT_HINT;
+}
 function buildResultJson(fileName, result, scores, options) {
   const issuesByRule = {};
   for (const issue of result.issues) {
@@ -2078,6 +2177,14 @@ function buildResultJson(fileName, result, scores, options) {
       ...issue.acknowledged === true ? { acknowledged: true } : {}
     };
   });
+  const optOutHint = options?.roundtripOptOutHintEligible ? formatRoundtripOptOutHintLine(result.issues) : null;
+  const summaryParts = [formatScoreSummary(scores)];
+  if (options?.codeConnectCoverage) {
+    summaryParts.push(formatCodeConnectCoverageLine(options.codeConnectCoverage));
+  }
+  if (optOutHint) {
+    summaryParts.push(optOutHint);
+  }
   const json = {
     version,
     analyzedAt: result.analyzedAt,
@@ -2097,13 +2204,153 @@ function buildResultJson(fileName, result, scores, options) {
     },
     issuesByRule,
     issues,
-    summary: formatScoreSummary(scores)
+    summary: summaryParts.join("\n\n")
   };
+  if (options?.codeConnectCoverage) {
+    json["codeConnectCoverage"] = options.codeConnectCoverage;
+  }
+  if (optOutHint) {
+    json["roundtripOptOutHint"] = optOutHint;
+  }
   if (result.failedRules.length > 0) {
     json["failedRules"] = result.failedRules;
   }
   return json;
 }
+var FIGMA_CONFIG_FILENAME = "figma.config.json";
+var FIGMA_CONNECT_FILE_GLOB = /\.figma\.(tsx?|jsx?)$/;
+var NODE_ID_QUERY_RE = /[?&]node-id=([0-9A-Za-z%:\-_]+)/;
+function parseCodeConnectMappings(cwd) {
+  const configPath = join(cwd, FIGMA_CONFIG_FILENAME);
+  if (!existsSync(configPath)) {
+    return {
+      mappedNodeIds: /* @__PURE__ */ new Set(),
+      scannedFiles: [],
+      skipReason: "no-config",
+      skippedReason: `${FIGMA_CONFIG_FILENAME} not found at ${cwd}`
+    };
+  }
+  let config2;
+  try {
+    config2 = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch (err) {
+    return {
+      mappedNodeIds: /* @__PURE__ */ new Set(),
+      scannedFiles: [],
+      skipReason: "malformed-config",
+      skippedReason: `malformed ${FIGMA_CONFIG_FILENAME}: ${err.message}`
+    };
+  }
+  const includes = config2.codeConnect?.include ?? config2.include ?? [];
+  if (includes.length === 0) {
+    return {
+      mappedNodeIds: /* @__PURE__ */ new Set(),
+      scannedFiles: [],
+      skipReason: "no-includes",
+      skippedReason: `${FIGMA_CONFIG_FILENAME} has no codeConnect.include paths`
+    };
+  }
+  const candidateFiles = /* @__PURE__ */ new Set();
+  for (const includePattern of includes) {
+    for (const file of resolveInclude(cwd, includePattern)) {
+      candidateFiles.add(file);
+    }
+  }
+  const mappedNodeIds = /* @__PURE__ */ new Set();
+  const scannedFiles = [];
+  for (const file of candidateFiles) {
+    scannedFiles.push(file);
+    let contents;
+    try {
+      contents = readFileSync(file, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const nodeId of extractNodeIdsFromSource(contents)) {
+      mappedNodeIds.add(nodeId);
+    }
+  }
+  return { mappedNodeIds, scannedFiles };
+}
+function resolveInclude(cwd, includePattern) {
+  const results = [];
+  const absolute = isAbsolute(includePattern) ? includePattern : resolve(cwd, includePattern);
+  const segments = absolute.split(sep);
+  let firstGlobIdx = segments.findIndex((s) => /[*?{[]/.test(s));
+  if (firstGlobIdx === -1) {
+    if (existsSync(absolute)) {
+      const stat = statSync(absolute);
+      if (stat.isFile() && FIGMA_CONNECT_FILE_GLOB.test(absolute)) {
+        results.push(absolute);
+      } else if (stat.isDirectory()) {
+        walkDir(absolute, results);
+      }
+    }
+    return results;
+  }
+  const rootSegments = segments.slice(0, firstGlobIdx);
+  const root = rootSegments.length === 0 ? sep : rootSegments.join(sep);
+  if (!existsSync(root)) return results;
+  const rootStat = statSync(root);
+  if (!rootStat.isDirectory()) return results;
+  walkDir(root, results);
+  const prefix = rootSegments.join(sep) + sep;
+  return results.filter((f) => f.startsWith(prefix) || rootSegments.length === 0);
+}
+function walkDir(dir, out) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry === "node_modules" || entry.startsWith(".")) continue;
+    const full = join(dir, entry);
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      walkDir(full, out);
+    } else if (stat.isFile() && FIGMA_CONNECT_FILE_GLOB.test(full)) {
+      out.push(full);
+    }
+  }
+}
+function extractNodeIdsFromSource(source) {
+  const nodeIds = /* @__PURE__ */ new Set();
+  const re = new RegExp(NODE_ID_QUERY_RE, "g");
+  let match;
+  while ((match = re.exec(source)) !== null) {
+    const raw = match[1];
+    if (!raw) continue;
+    const decoded = safeDecode(raw);
+    nodeIds.add(decoded.replace(/-/g, ":"));
+  }
+  return nodeIds;
+}
+function safeDecode(raw) {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+// src/core/rules/component/code-connect-coverage.ts
+function computeCodeConnectCoverage(components, cwd = process.cwd()) {
+  const result = parseCodeConnectMappings(cwd);
+  if (result.skipReason === "no-config") return void 0;
+  const componentNodeIds = Object.keys(components);
+  let mapped = 0;
+  for (const nodeId of componentNodeIds) {
+    if (result.mappedNodeIds.has(nodeId)) mapped++;
+  }
+  return { mapped, total: componentNodeIds.length };
+}
 z.object({
   ruleId: z.string(),
   detection: z.literal("rule-based"),
@@ -2165,6 +2412,12 @@ var GOTCHA_QUESTION_CONTENT = {
     hint: "Describe which variant has the correct structure, or if they should all match",
     example: "Default variant is canonical \u2014 other variants should toggle child visibility instead of adding/removing elements"
   },
+  "unmapped-component": {
+    ruleId: "unmapped-component",
+    question: '"{nodeName}" has no Code Connect mapping yet. Should we register one so figma-implement-design reuses your code?',
+    hint: "Skip if this component is intentionally unmapped (e.g. marketing-only banner). Otherwise run /canicode-roundtrip on the component to walk through registration.",
+    example: "Yes \u2014 map to src/components/Button.tsx so future screens reuse the existing implementation"
+  },
   "deep-nesting": {
     ruleId: "deep-nesting",
     question: '"{nodeName}" is deeply nested. Can some intermediate layers be flattened or extracted?',
@@ -2310,10 +2563,7 @@ function generateGotchaSurvey(result, scores, options = {}) {
   const relevantIssues = result.issues.filter((issue) => {
     const severity = issue.config.severity;
     if (severity === "blocking" || severity === "risk") return true;
-    if (severity === "missing-info") {
-      return getRulePurpose(issue.violation.ruleId) === "info-collection";
-    }
-    return false;
+    return getRulePurpose(issue.violation.ruleId) === "info-collection";
   });
   const deduped = deduplicateSiblingIssues(relevantIssues);
   const sorted = stableSortBySeverity(deduped);
@@ -2494,7 +2744,8 @@ function severityDot(sev) {
     blocking: "sev-blocking",
     risk: "sev-risk",
     "missing-info": "sev-missing",
-    suggestion: "sev-suggestion"
+    suggestion: "sev-suggestion",
+    note: "sev-note"
   };
   return map[sev];
 }
@@ -2503,7 +2754,8 @@ function severityBadge(sev) {
     blocking: "sev-blocking",
     risk: "sev-risk",
     "missing-info": "sev-missing",
-    suggestion: "sev-suggestion"
+    suggestion: "sev-suggestion",
+    note: "sev-note"
   };
   return map[sev];
 }
@@ -2561,6 +2813,7 @@ ${CATEGORIES.map((cat) => {
         ${renderSummaryDot("sev-risk", scores.summary.risk, "Risk")}
         ${renderSummaryDot("sev-missing", scores.summary.missingInfo, "Missing Info")}
         ${renderSummaryDot("sev-suggestion", scores.summary.suggestion, "Suggestion")}
+        ${renderSummaryDot("sev-note", scores.summary.note, "Note")}
         <div class="rpt-summary-total">
           <span class="rpt-summary-count">${scores.summary.totalIssues}</span>
           <span class="rpt-summary-label">Total</span>
@@ -2775,7 +3028,7 @@ function groupIssuesByRule(issues) {
     group.issues.push(issue);
     group.totalScore += issue.calculatedScore;
   }
-  const SEVERITY_RANK = { blocking: 0, risk: 1, "missing-info": 2, suggestion: 3 };
+  const SEVERITY_RANK = { blocking: 0, risk: 1, "missing-info": 2, suggestion: 3, note: 4 };
   return [...byRule.values()].sort((a, b) => {
     const sevDiff = (SEVERITY_RANK[a.severity] ?? 4) - (SEVERITY_RANK[b.severity] ?? 4);
     return sevDiff !== 0 ? sevDiff : a.totalScore - b.totalScore;
@@ -2843,6 +3096,7 @@ body {
 .sev-risk { background: var(--amber); }
 .sev-missing { background: #a1a1aa; }
 .sev-suggestion { background: var(--green); }
+.sev-note { background: #d4d4d8; }
 
 /* ---- Print ---- */
 @media print {
@@ -3239,6 +3493,7 @@ body {
 .rpt-issue-score.sev-risk     { background: var(--amber-bg); color: #d97706; border-color: rgba(245,158,11,0.2); }
 .rpt-issue-score.sev-missing  { background: #f4f4f5; color: #71717a; border-color: rgba(113,113,122,0.2); }
 .rpt-issue-score.sev-suggestion { background: var(--green-bg); color: #16a34a; border-color: rgba(34,197,94,0.2); }
+.rpt-issue-score.sev-note     { background: #f4f4f5; color: #71717a; border-color: rgba(113,113,122,0.2); }
 
 .rpt-issue-body {
   padding: 12px;
@@ -3644,6 +3899,8 @@ var EVENTS = {
   // CLI
   CLI_COMMAND: `${EVENT_PREFIX}cli_command`,
   CLI_INIT: `${EVENT_PREFIX}cli_init`,
+  CLI_CONFIG_SET_TOKEN: `${EVENT_PREFIX}cli_config_set_token`,
+  CLI_DOCTOR: `${EVENT_PREFIX}cli_doctor`,
   // Roundtrip (ADR-012)
   // Wiring point for the roundtrip helper's `telemetry` callback. No Node-side
   // orchestrator reads this yet — the helper ships in a sandbox-pure IIFE that
@@ -4061,6 +4318,10 @@ var missingComponentMsg = {
     suggestion: `Create a new variant for this style combination`
   })
 };
+var unmappedComponentMsg = (componentName) => ({
+  message: `"${componentName}" has no Code Connect mapping`,
+  suggestion: `Run /canicode-roundtrip on this component to register a mapping so figma-implement-design reuses your code instead of regenerating markup. Skip if intentionally unmapped.`
+});
 var detachedInstanceMsg = (name, componentName) => ({
   message: `"${name}" may be a detached instance of component "${componentName}"`,
   suggestion: `Restore as an instance of "${componentName}" or create a new variant`
@@ -4612,8 +4873,6 @@ defineRule({
   definition: irregularSpacingDef,
   check: irregularSpacingCheck
 });
-
-// src/core/rules/component/index.ts
 var STYLE_COMPARE_KEYS = ["fills", "strokes", "effects", "cornerRadius", "strokeWeight", "individualStrokeWeights"];
 function detectStyleOverrides(master, instance) {
   const overrides = [];
@@ -4821,6 +5080,49 @@ defineRule({
   definition: variantStructureMismatchDef,
   check: variantStructureMismatchCheck
 });
+var CODE_CONNECT_SETUP_KEY = "unmapped-component:setup-detected";
+var CODE_CONNECT_MAPPINGS_KEY = "unmapped-component:mappings";
+function codeConnectIsSetUp(context) {
+  return getAnalysisState(context, CODE_CONNECT_SETUP_KEY, () => {
+    return existsSync(join(process.cwd(), "figma.config.json"));
+  });
+}
+function codeConnectMappings(context) {
+  return getAnalysisState(
+    context,
+    CODE_CONNECT_MAPPINGS_KEY,
+    () => parseCodeConnectMappings(process.cwd())
+  );
+}
+var unmappedComponentDef = {
+  id: "unmapped-component",
+  name: "Unmapped Component",
+  category: "code-quality",
+  why: "Without a Code Connect mapping, figma-implement-design regenerates the same markup every time this component appears in a screen \u2014 wasting tokens and risking drift.",
+  impact: "Future roundtrips on screens containing this component cannot reuse your existing code; they regenerate markup that may not match the canonical implementation.",
+  fix: "Run /canicode-roundtrip on this component to register a mapping. Figma's get_code_connect_map will skip if a mapping already exists."
+};
+var unmappedComponentCheck = (node, context) => {
+  if (node.type !== "COMPONENT" && node.type !== "COMPONENT_SET") return null;
+  if (isInsideInstance(context)) return null;
+  if (!codeConnectIsSetUp(context)) return null;
+  const mappings = codeConnectMappings(context);
+  if (mappings.mappedNodeIds.has(node.id)) return null;
+  const ack = context.findAcknowledgment(node.id, unmappedComponentDef.id);
+  if (ack && isRuleOptOutIntent(ack.intent) && ack.intent.ruleId === unmappedComponentDef.id) {
+    return null;
+  }
+  return {
+    ruleId: unmappedComponentDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    ...unmappedComponentMsg(node.name)
+  };
+};
+defineRule({
+  definition: unmappedComponentDef,
+  check: unmappedComponentCheck
+});
 
 // src/core/rules/naming/index.ts
 function capitalize(s) {
@@ -5211,9 +5513,9 @@ 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"),
-    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`."),
+    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. The HTML file is always written to disk regardless."),
+    acknowledgments: z.array(AcknowledgmentSchema).optional().describe("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. Matching issues are flagged acknowledged and contribute half weight to the density score."),
+    scope: z.enum(["page", "component"]).optional().describe("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")
   },
   {
@@ -5248,10 +5550,10 @@ 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((resolve6, reject) => {
+      await new Promise((resolve7, reject) => {
         writeFile(reportPath, html, "utf-8", (err) => {
           if (err) reject(err);
-          else resolve6();
+          else resolve7();
         });
       });
       if (openReport === true) {
@@ -5265,11 +5567,19 @@ Provide a Figma URL or fixture path via the input parameter. Requires FIGMA_TOKE
         percentage: scores.overall.percentage,
         source: isJsonFile(input) || isFixtureDir(input) ? "fixture" : "figma"
       });
+      const coverage = computeCodeConnectCoverage(file.components);
+      const optOutHintEligible = acknowledgments === void 0;
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey, designKey: computeDesignKey(input), ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {} }), null, 2)
+            text: JSON.stringify(buildResultJson(file.name, result, scores, {
+              fileKey: file.fileKey,
+              designKey: computeDesignKey(input),
+              ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {},
+              ...coverage ? { codeConnectCoverage: coverage } : {},
+              roundtripOptOutHintEligible: optOutHintEligible
+            }), null, 2)
           }
         ]
       };
@@ -5307,7 +5617,7 @@ 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("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")
   },
   {
@@ -5480,7 +5790,7 @@ Get your token: Figma \u2192 Settings \u2192 Security \u2192 Personal access tok
 claude mcp add canicode -- npx --yes --package=canicode canicode-mcp
 \`\`\`
 
-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)
+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 \`--\`.
 
 ## CLI only (no MCP server)
 
@@ -5600,16 +5910,16 @@ ${inlineTopics[selectedTopic]}` }]
       };
     }
     const { readFile: readFile3 } = await import('fs/promises');
-    const { resolve: resolve6, dirname: dirname4 } = await import('path');
+    const { resolve: resolve7, dirname: dirname4 } = await import('path');
     const { fileURLToPath } = await import('url');
     try {
       const __dirname = dirname4(fileURLToPath(import.meta.url));
-      const docPath = resolve6(__dirname, "../../docs/CUSTOMIZATION.md");
+      const docPath = resolve7(__dirname, "../../docs/CUSTOMIZATION.md");
       let content;
       try {
         content = await readFile3(docPath, "utf-8");
       } catch {
-        const altPath = resolve6(__dirname, "../docs/CUSTOMIZATION.md");
+        const altPath = resolve7(__dirname, "../docs/CUSTOMIZATION.md");
         content = await readFile3(altPath, "utf-8");
       }
       if (selectedTopic !== "all") {