canicode 0.12.0 → 0.12.2

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, writeFileSync, readFileSync, statSync, readdirSync, renameSync, chmodSync, copyFileSync } from 'fs';
-import { join, resolve, dirname, basename, relative } from 'path';
+import { join, resolve, dirname, basename, isAbsolute, sep, relative } from 'path';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
 import { createRequire } from 'module';
@@ -132,6 +132,32 @@ var init_figma_client = __esm({
         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)}`;
@@ -3053,6 +3079,176 @@ defineRule({
   definition: irregularSpacingDef,
   check: irregularSpacingCheck
 });
+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;
+  }
+}
+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",
+    "silent-ignored",
+    "api-rejected",
+    "user-declined-propagation",
+    "unknown"
+  ]),
+  reason: z.string().optional()
+});
+var AcknowledgmentSchema = z.object({
+  nodeId: z.string(),
+  ruleId: z.string(),
+  intent: AcknowledgmentIntentSchema.optional(),
+  sceneWriteOutcome: AcknowledgmentSceneWriteOutcomeSchema.optional(),
+  codegenDirective: z.string().optional()
+});
+var AcknowledgmentListSchema = z.array(AcknowledgmentSchema);
+function normalizeNodeId(id) {
+  return id.replace(/-/g, ":");
+}
+
+// src/core/rules/component/index.ts
 var STYLE_COMPARE_KEYS = ["fills", "strokes", "effects", "cornerRadius", "strokeWeight", "individualStrokeWeights"];
 function detectStyleOverrides(master, instance) {
   const overrides = [];
@@ -3261,11 +3457,23 @@ defineRule({
   check: variantStructureMismatchCheck
 });
 var CODE_CONNECT_SETUP_KEY = "unmapped-component:setup-detected";
+var CODE_CONNECT_MAPPINGS_KEY = "unmapped-component:mappings";
+var SEEN_MAIN_IDS_KEY = "unmapped-component:seen-main-ids";
 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())
+  );
+}
+function seenMainIds(context) {
+  return getAnalysisState(context, SEEN_MAIN_IDS_KEY, () => /* @__PURE__ */ new Set());
+}
 var unmappedComponentDef = {
   id: "unmapped-component",
   name: "Unmapped Component",
@@ -3275,14 +3483,33 @@ var unmappedComponentDef = {
   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;
+  let mainId = null;
+  let mainName = node.name;
+  if (node.type === "COMPONENT" || node.type === "COMPONENT_SET") {
+    if (isInsideInstance(context)) return null;
+    mainId = node.id;
+  } else if (node.type === "INSTANCE" && node.componentId) {
+    mainId = node.componentId;
+    const meta = context.file.components[node.componentId];
+    if (meta?.name) mainName = meta.name;
+  } else {
+    return null;
+  }
+  const seen = seenMainIds(context);
+  if (seen.has(mainId)) return null;
+  seen.add(mainId);
+  const mappings = codeConnectMappings(context);
+  if (mappings.mappedNodeIds.has(mainId)) return null;
+  const ack = context.findAcknowledgment(mainId, unmappedComponentDef.id);
+  if (ack && isRuleOptOutIntent(ack.intent) && ack.intent.ruleId === unmappedComponentDef.id) {
+    return null;
+  }
   return {
     ruleId: unmappedComponentDef.id,
-    nodeId: node.id,
+    nodeId: mainId,
     nodePath: context.path.join(" > "),
-    ...unmappedComponentMsg(node.name)
+    ...unmappedComponentMsg(mainName)
   };
 };
 defineRule({
@@ -3645,32 +3872,6 @@ defineRule({
   definition: missingPrototypeDef,
   check: missingPrototypeCheck
 });
-var AcknowledgmentIntentSchema = z.object({
-  field: z.string(),
-  value: z.unknown(),
-  scope: z.enum(["instance", "definition"])
-});
-var AcknowledgmentSceneWriteOutcomeSchema = z.object({
-  result: z.enum([
-    "succeeded",
-    "silent-ignored",
-    "api-rejected",
-    "user-declined-propagation",
-    "unknown"
-  ]),
-  reason: z.string().optional()
-});
-var AcknowledgmentSchema = z.object({
-  nodeId: z.string(),
-  ruleId: z.string(),
-  intent: AcknowledgmentIntentSchema.optional(),
-  sceneWriteOutcome: AcknowledgmentSceneWriteOutcomeSchema.optional(),
-  codegenDirective: z.string().optional()
-});
-var AcknowledgmentListSchema = z.array(AcknowledgmentSchema);
-function normalizeNodeId(id) {
-  return id.replace(/-/g, ":");
-}
 var AnalysisScopeSchema = z.enum(["page", "component"]);
 var COMPONENT_SCOPE_ROOT_TYPES = /* @__PURE__ */ new Set(["COMPONENT", "COMPONENT_SET", "INSTANCE"]);
 function detectAnalysisScope(rootNode) {
@@ -3727,6 +3928,7 @@ var RuleEngine = class {
   excludeNamePattern;
   excludeNodeTypes;
   acknowledgments;
+  acknowledgmentsByKey;
   scopeOverride;
   constructor(options = {}) {
     this.configs = options.configs ?? RULE_CONFIGS;
@@ -3735,10 +3937,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;
   }
@@ -3822,6 +4029,7 @@ var RuleEngine = class {
     if (this.excludeNamePattern && this.excludeNamePattern.test(node.name)) {
       return;
     }
+    const acknowledgmentsByKey = this.acknowledgmentsByKey;
     const context = {
       file,
       parent,
@@ -3833,7 +4041,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;
@@ -4317,7 +4526,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.12.0";
+var version2 = "0.12.2";
 
 // src/core/engine/scoring.ts
 var GRADE_ORDER = ["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"];
@@ -4509,6 +4718,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) {
@@ -4538,6 +4760,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: version2,
     analyzedAt: result.analyzedAt,
@@ -4557,13 +4787,31 @@ 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;
 }
+
+// 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 };
+}
 function isFigmaUrl2(input) {
   return input.includes("figma.com/");
 }
@@ -5922,8 +6170,17 @@ Analyzing: ${file.name}`);
       const result = analyzeFile(file, analyzeOptions);
       log(`Nodes: ${result.nodeCount} (max depth: ${result.maxDepth})`);
       const scores = calculateScores(result, configs);
+      const coverage = computeCodeConnectCoverage(file.components);
+      const optOutHintEligible = acknowledgments === void 0;
+      const optOutHint = optOutHintEligible ? formatRoundtripOptOutHintLine(result.issues, false) : null;
       if (options.json) {
-        console.log(JSON.stringify(buildResultJson(file.name, result, scores, { fileKey: file.fileKey, designKey: computeDesignKey(input), ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {} }), null, 2));
+        console.log(JSON.stringify(buildResultJson(file.name, result, scores, {
+          fileKey: file.fileKey,
+          designKey: computeDesignKey(input),
+          ...effectiveMinGrade ? { codegenReadyMinGrade: effectiveMinGrade } : {},
+          ...coverage ? { codeConnectCoverage: coverage } : {},
+          roundtripOptOutHintEligible: optOutHintEligible
+        }), null, 2));
         if (scores.overall.grade === "F") {
           process.exitCode = 1;
         }
@@ -5931,6 +6188,14 @@ Analyzing: ${file.name}`);
       }
       console.log("\n" + "=".repeat(50));
       console.log(formatScoreSummary(scores));
+      if (coverage) {
+        console.log("");
+        console.log(formatCodeConnectCoverageLine(coverage));
+      }
+      if (optOutHint) {
+        console.log("");
+        console.log(optOutHint);
+      }
       console.log("=".repeat(50));
       const now = /* @__PURE__ */ new Date();
       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")}`;
@@ -6785,8 +7050,8 @@ function renderUpsertedFile(args) {
   }
   let working = currentContent;
   if (state === "missing-heading") {
-    const sep = working.endsWith("\n\n") ? "" : working.endsWith("\n") ? "\n" : "\n\n";
-    working = `${working}${sep}${COLLECTED_GOTCHAS_HEADING}
+    const sep2 = working.endsWith("\n\n") ? "" : working.endsWith("\n") ? "\n" : "\n\n";
+    working = `${working}${sep2}${COLLECTED_GOTCHAS_HEADING}
 `;
   }
   const plan = findOrAppendSection(working, designKey);
@@ -7645,6 +7910,9 @@ function registerConfig(cli2) {
     }
   });
 }
+
+// src/cli/commands/doctor.ts
+init_figma_client();
 var CODE_CONNECT_PKG = "@figma/code-connect";
 var CODE_CONNECT_DOCS = "https://www.figma.com/code-connect-docs/";
 function readPackageJson(cwd) {
@@ -7692,10 +7960,102 @@ function runCodeConnectChecks(cwd) {
   }
   return results;
 }
+var PUBLISH_CHECK_NAME = "Figma component published in a library";
+async function runFigmaPublishCheck(input) {
+  const { figmaUrl, token, fetchPublishedComponents, fetchNodeType } = input;
+  let parsed;
+  try {
+    parsed = parseFigmaUrl(figmaUrl);
+  } catch (err) {
+    const message = err instanceof FigmaUrlParseError ? err.message : String(err);
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: `could not parse URL: ${message}`,
+      remediation: "Pass a valid Figma design URL (figma.com/design/<file>?node-id=<id>)."
+    };
+  }
+  if (!parsed.nodeId) {
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: "URL is missing a node-id",
+      remediation: "Code Connect mapping is per-component \u2014 invoke with a URL that targets a specific node (?node-id=\u2026)."
+    };
+  }
+  if (!token) {
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: "FIGMA_TOKEN not configured \u2014 skipping publish-status check",
+      remediation: "Set FIGMA_TOKEN (env var) or run `canicode config set-token` so doctor can verify this prereq inline."
+    };
+  }
+  if (!fetchPublishedComponents) {
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: "no fetcher wired",
+      remediation: "internal: doctor was called without a Figma client"
+    };
+  }
+  let components;
+  try {
+    components = await fetchPublishedComponents(parsed.fileKey);
+  } catch (err) {
+    const status = err instanceof FigmaClientError ? err.statusCode : void 0;
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: false,
+      inconclusive: true,
+      detail: `Figma API call failed${status ? ` (HTTP ${status})` : ""}: ${message}`,
+      remediation: "Step 7d will rely on the API as the authority; if your token / network is OK, the canicode-roundtrip step itself will surface the publish error inline."
+    };
+  }
+  const canonicalNodeId = parsed.nodeId.replace(/-/g, ":");
+  const match = components.find(
+    (c) => c.node_id === canonicalNodeId || c.node_id === parsed.nodeId
+  );
+  if (match) {
+    return {
+      name: PUBLISH_CHECK_NAME,
+      pass: true,
+      detail: `${match.name} (${match.node_id})`
+    };
+  }
+  if (fetchNodeType) {
+    let nodeType;
+    try {
+      nodeType = await fetchNodeType(parsed.fileKey, canonicalNodeId);
+    } catch {
+      nodeType = void 0;
+    }
+    if (nodeType && nodeType !== "COMPONENT" && nodeType !== "COMPONENT_SET") {
+      return {
+        name: PUBLISH_CHECK_NAME,
+        pass: false,
+        inconclusive: true,
+        detail: `node ${canonicalNodeId} is type ${nodeType} \u2014 Code Connect mapping is per-component`,
+        remediation: "Step 7 (Code Connect close-out) skips on screen-level scope anyway. To verify a specific component, re-invoke doctor with that component's URL."
+      };
+    }
+  }
+  return {
+    name: PUBLISH_CHECK_NAME,
+    pass: false,
+    detail: `node ${canonicalNodeId} is not in the published-components list for file ${parsed.fileKey}`,
+    remediation: "Open the file in Figma \u2192 Assets panel \u2192 Publish library and include this component. Without publishing, `add_code_connect_map` fails with 'Published component not found.'"
+  };
+}
 function formatDoctorReport(results) {
   const lines = ["Code Connect"];
   for (const result of results) {
-    const icon = result.pass ? "\u2705" : "\u274C";
+    const icon = result.pass ? "\u2705" : result.inconclusive ? "\u26A0\uFE0F" : "\u274C";
     const detail = result.detail ? ` (${result.detail})` : "";
     lines.push(`  ${icon} ${result.name}${detail}`);
     if (!result.pass && result.remediation) {
@@ -7703,22 +8063,47 @@ function formatDoctorReport(results) {
     }
   }
   lines.push("");
-  const allPass = results.every((r) => r.pass);
-  lines.push(
-    allPass ? "All checks passed." : "Some checks failed. Fix the items above before running the Code Connect flow."
-  );
+  const blocking = results.filter((r) => !r.pass && !r.inconclusive).length;
+  const inconclusive = results.filter((r) => !r.pass && r.inconclusive).length;
+  if (blocking === 0 && inconclusive === 0) {
+    lines.push("All checks passed.");
+  } else if (blocking === 0) {
+    lines.push(
+      "Blocking checks passed; some checks were skipped (\u26A0\uFE0F) and could not be verified."
+    );
+  } else {
+    lines.push("Some checks failed. Fix the items above before running the Code Connect flow.");
+  }
   return lines.join("\n");
 }
 function registerDoctor(cli2) {
   cli2.command(
     "doctor",
     "Diagnose Code Connect prerequisites (`@figma/code-connect`, `figma.config.json`)"
-  ).action(() => {
+  ).option(
+    "--figma-url <url>",
+    "Optionally check that the target Figma component is published in a library (requires FIGMA_TOKEN)"
+  ).action(async (options) => {
     const cwd = process.cwd();
     const results = runCodeConnectChecks(cwd);
+    if (options.figmaUrl) {
+      const token = getFigmaToken();
+      const client = token ? new FigmaClient({ token }) : void 0;
+      const publishCheck = await runFigmaPublishCheck({
+        figmaUrl: options.figmaUrl,
+        token,
+        fetchPublishedComponents: client ? (fileKey) => client.getPublishedComponents(fileKey) : void 0,
+        fetchNodeType: client ? async (fileKey, nodeId) => {
+          const response = await client.getFileNodes(fileKey, [nodeId]);
+          return response.nodes[nodeId]?.document.type;
+        } : void 0
+      });
+      results.push(publishCheck);
+    }
     console.log(formatDoctorReport(results));
     const passed = results.filter((r) => r.pass).length;
-    const failed = results.length - passed;
+    const inconclusive = results.filter((r) => !r.pass && r.inconclusive).length;
+    const failed = results.length - passed - inconclusive;
     trackEvent(EVENTS.CLI_DOCTOR, {
       passed,
       failed,
@@ -10856,8 +11241,8 @@ ${msg}`);
       if (vectorDir && existsSync(vectorDir)) {
         const vecOutputDir = resolve(outputDir, "vectors");
         mkdirSync(vecOutputDir, { recursive: true });
-        const { readdirSync: readdirSync4, copyFileSync: copyFileSync3 } = await import('fs');
-        const vecFiles = readdirSync4(vectorDir).filter((f) => f.endsWith(".svg") || f === "mapping.json");
+        const { readdirSync: readdirSync5, copyFileSync: copyFileSync3 } = await import('fs');
+        const vecFiles = readdirSync5(vectorDir).filter((f) => f.endsWith(".svg") || f === "mapping.json");
         for (const f of vecFiles) {
           copyFileSync3(resolve(vectorDir, f), resolve(vecOutputDir, f));
         }
@@ -10867,8 +11252,8 @@ ${msg}`);
       if (imageDir && existsSync(imageDir)) {
         const imgOutputDir = resolve(outputDir, "images");
         mkdirSync(imgOutputDir, { recursive: true });
-        const { readdirSync: readdirSync4, copyFileSync: copyFileSync3 } = await import('fs');
-        const imgFiles = readdirSync4(imageDir).filter((f) => f.endsWith(".png") || f.endsWith(".jpg") || f.endsWith(".json"));
+        const { readdirSync: readdirSync5, copyFileSync: copyFileSync3 } = await import('fs');
+        const imgFiles = readdirSync5(imageDir).filter((f) => f.endsWith(".png") || f.endsWith(".jpg") || f.endsWith(".json"));
         for (const f of imgFiles) {
           copyFileSync3(resolve(imageDir, f), resolve(imgOutputDir, f));
         }