canicode 0.12.0 → 0.12.2

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { GetFileResponse, Node } from '@figma/rest-api-spec';
 
-var version = "0.12.0";
+var version = "0.12.2";
 
 declare const SeveritySchema: z.ZodEnum<{
     blocking: "blocking";
@@ -377,6 +377,35 @@ type Category = z.infer<typeof CategorySchema>;
 declare const CATEGORIES: ("pixel-critical" | "responsive-critical" | "code-quality" | "token-management" | "semantic" | "interaction")[];
 declare const CATEGORY_LABELS: Record<Category, string>;
 
+declare const AcknowledgmentSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    ruleId: z.ZodString;
+    intent: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodDefault<z.ZodLiteral<"property">>;
+        field: z.ZodString;
+        value: z.ZodUnknown;
+        scope: z.ZodEnum<{
+            instance: "instance";
+            definition: "definition";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"rule-opt-out">;
+        ruleId: z.ZodString;
+    }, z.core.$strict>], "kind">>>;
+    sceneWriteOutcome: z.ZodOptional<z.ZodObject<{
+        result: z.ZodEnum<{
+            unknown: "unknown";
+            succeeded: "succeeded";
+            "silent-ignored": "silent-ignored";
+            "api-rejected": "api-rejected";
+            "user-declined-propagation": "user-declined-propagation";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    codegenDirective: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Acknowledgment = z.infer<typeof AcknowledgmentSchema>;
+
 /**
  * Rule definition - static metadata (does not change)
  */
@@ -451,6 +480,20 @@ interface RuleContext {
      * sync with `AnalysisNode.type` without a translation layer.
      */
     rootNodeType: string;
+    /**
+     * ADR-022: lookup canicode-authored acknowledgments by `(nodeId, ruleId)`.
+     * The rule engine builds this from `RuleEngineOptions.acknowledgments` and
+     * exposes it to every rule so individual rules can short-circuit (suppress
+     * emission) when an acknowledgment carries a rule-opt-out intent. The
+     * existing density-half-weight semantic (#371) is unchanged — that path
+     * still flags `acknowledged: true` post-emit and is independent of this
+     * helper.
+     *
+     * Returns the matching acknowledgment, or `undefined` when there is no
+     * acknowledgment for the pair. Node ids are normalised by the engine, so
+     * callers can pass URL-style or Plugin-API-style ids interchangeably.
+     */
+    findAcknowledgment: (nodeId: string, ruleId: string) => Acknowledgment | undefined;
 }
 /**
  * Get or initialize per-analysis state for a rule.
@@ -701,6 +744,10 @@ declare const McpAnalyzeResponseSchema: z.ZodObject<{
     }, z.core.$strip>>;
     summary: z.ZodString;
     failedRules: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    codeConnectCoverage: z.ZodOptional<z.ZodObject<{
+        mapped: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 type McpAnalyzeResponse = z.infer<typeof McpAnalyzeResponseSchema>;
 
@@ -1123,31 +1170,6 @@ declare const GotchaSurveySchema: z.ZodObject<{
 }, z.core.$strip>;
 type GotchaSurvey = z.infer<typeof GotchaSurveySchema>;
 
-declare const AcknowledgmentSchema: z.ZodObject<{
-    nodeId: z.ZodString;
-    ruleId: z.ZodString;
-    intent: z.ZodOptional<z.ZodObject<{
-        field: z.ZodString;
-        value: z.ZodUnknown;
-        scope: z.ZodEnum<{
-            instance: "instance";
-            definition: "definition";
-        }>;
-    }, z.core.$strip>>;
-    sceneWriteOutcome: z.ZodOptional<z.ZodObject<{
-        result: z.ZodEnum<{
-            unknown: "unknown";
-            succeeded: "succeeded";
-            "silent-ignored": "silent-ignored";
-            "api-rejected": "api-rejected";
-            "user-declined-propagation": "user-declined-propagation";
-        }>;
-        reason: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    codegenDirective: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-type Acknowledgment = z.infer<typeof AcknowledgmentSchema>;
-
 /**
  * Analysis issue with calculated score and metadata.
  *
@@ -1234,6 +1256,7 @@ declare class RuleEngine {
     private excludeNamePattern;
     private excludeNodeTypes;
     private acknowledgments;
+    private acknowledgmentsByKey;
     private scopeOverride;
     constructor(options?: RuleEngineOptions);
     /**
@@ -1355,6 +1378,50 @@ declare function getCategoryLabel(category: Category): string;
  * Get severity label for display
  */
 declare function getSeverityLabel(severity: Severity): string;
+/**
+ * Code Connect mapping coverage metric (#526 sub-task 3). Surfaces how many of
+ * the file's components are already wired to a code path via a `figma.connect`
+ * declaration. Optional — only computed when the consuming repo has Code
+ * Connect set up (figma.config.json present).
+ */
+interface CodeConnectCoverage {
+    /** Number of components in this file that have a Code Connect mapping. */
+    mapped: number;
+    /** Total components in this file (numerator + unmapped). */
+    total: number;
+}
+/**
+ * Format the coverage line that ships in the analyze summary. Kept exported
+ * so consumers (HTML report, MCP wrapper) render the same wording.
+ */
+declare function formatCodeConnectCoverageLine(coverage: CodeConnectCoverage): string;
+/**
+ * ADR-022 / #526 sub-task 2: standalone analyze hint.
+ *
+ * `canicode analyze` and the MCP `analyze` tool cannot read Figma annotations
+ * directly — the REST `annotations` field is private beta. When the
+ * `unmapped-component` rule fires AND the caller did not supply an
+ * acknowledgments list, surface a one-line hint telling the user that any
+ * roundtrip-recorded opt-outs are invisible to standalone analyze and that
+ * `/canicode-roundtrip` will apply them.
+ *
+ * Returns `null` when:
+ * - no `unmapped-component` issue fired (nothing to explain), or
+ * - acknowledgments were supplied (roundtrip mode — opt-outs already applied
+ *   and any remaining issues are real). `acknowledgmentsProvided` MUST track
+ *   whether the caller passed an ack channel at all, NOT whether the array
+ *   was non-empty: a roundtrip on a clean file legitimately passes `[]` and
+ *   the hint would be misleading there.
+ *
+ * The hint is informational; it never moves the score, never bumps severity,
+ * and is independent of the count of `unmapped-component` issues.
+ */
+declare const 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.";
+declare function formatRoundtripOptOutHintLine(issues: ReadonlyArray<{
+    violation: {
+        ruleId: string;
+    };
+}>, acknowledgmentsProvided: boolean): string | null;
 /**
  * Build a JSON-serializable analysis result summary.
  * Shared by CLI (--json) and MCP server (analyze tool response).
@@ -1363,6 +1430,16 @@ declare function buildResultJson(fileName: string, result: AnalysisResult, score
     fileKey?: string;
     designKey?: string;
     codegenReadyMinGrade?: Grade;
+    codeConnectCoverage?: CodeConnectCoverage;
+    /**
+     * ADR-022 / #526 sub-task 2: when true, the engine was called WITHOUT
+     * an `acknowledgments` channel (standalone CLI / MCP `analyze`) and
+     * `unmapped-component` opt-outs recorded via roundtrip cannot be seen.
+     * Surfaces a `roundtripOptOutHint` field on the JSON response and
+     * appends a hint line to `summary` when at least one
+     * `unmapped-component` issue fired.
+     */
+    roundtripOptOutHintEligible?: boolean;
 }): Record<string, unknown>;
 
 /**
@@ -1904,6 +1981,21 @@ declare class FigmaClient {
      * Download an image URL and return as base64
      */
     fetchImageAsBase64(imageUrl: string): Promise<string>;
+    /**
+     * 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."
+     */
+    getPublishedComponents(fileKey: string): Promise<Array<{
+        key: string;
+        node_id: string;
+        name: string;
+    }>>;
     getFileNodes(fileKey: string, nodeIds: string[]): Promise<GetFileNodesResponse>;
 }
 declare class FigmaClientError extends Error {
@@ -2394,4 +2486,4 @@ declare class ActivityLogger {
     getLogPath(): string;
 }
 
-export { ALL_STRIP_TYPES, ActivityLogger, type AnalysisAgentInput, type AnalysisAgentOutput, type AnalysisFile, AnalysisFileSchema, type AnalysisIssue, type AnalysisNode, AnalysisNodeSchema, type AnalysisNodeType, AnalysisNodeTypeSchema, type AnalysisResult, type AnalysisScope, AnalysisScopeSchema, AnnotationPropertySchema, CATEGORIES, CATEGORY_LABELS, type CalibrationConfig, type CalibrationConfigInput, CalibrationConfigSchema, type CalibrationRun, type CalibrationStatus, CalibrationStatusSchema, type Category, CategorySchema, type CategoryScore, type CategoryScoreResult, CategoryScoreSchema, type Confidence, ConfidenceSchema, type ConversionRecord, ConversionRecordSchema, DEFAULT_CODEGEN_READY_MIN_GRADE, DEPTH_WEIGHT_CATEGORIES, DESIGN_TREE_INFO_TYPES, type DesignTreeInfoType, type DesignTreeOptions, type DesignTreeResult, type DesignTreeStripType, type Detection, DetectionSchema, type Difficulty, DifficultySchema, type EvaluationAgentInput, type EvaluationAgentOutput, FigmaClient, FigmaClientError, type FigmaClientOptions, FigmaFileLoadError, type FigmaUrlInfo, FigmaUrlInfoSchema, FigmaUrlParseError, GRADE_ORDER, type GapAnalyzerOutput, GapAnalyzerOutputSchema, type GapEntry, GapEntrySchema, type GetFileNodesResponse, type GotchaApplyResolution, type GotchaApplyStrategy, GotchaDetectionSchema, GotchaOutputChannelSchema, GotchaPersistenceIntentSchema, type GotchaSurvey, type GotchaSurveyQuestion, GotchaSurveyQuestionSchema, GotchaSurveySchema, type Grade, type GridChildAlign, GridChildAlignSchema, type GroupedSurvey, GroupedSurveySchema, type InstanceChildIdParts, type InstanceContext, InstanceContextSchema, type Issue, IssueSchema, type LayoutAlign, LayoutAlignSchema, type LayoutConstraint, LayoutConstraintSchema, type LayoutMode, LayoutModeSchema, type LayoutPositioning, LayoutPositioningSchema, type LayoutWrap, LayoutWrapSchema, type McpAnalyzeResponse, McpAnalyzeResponseSchema, type MismatchCase, MismatchCaseSchema, type MismatchType, MismatchTypeSchema, type NewRuleProposal, NewRuleProposalSchema, type NodeIssueDetail, type NodeIssueSummary, NodeIssueSummarySchema, type OutputChannel, OutputChannelSchema, type OverflowDirection, OverflowDirectionSchema, type PersistenceIntent, PersistenceIntentSchema, type Preset, RULE_ANNOTATION_PROPERTIES, RULE_CONFIGS, RULE_ID_CATEGORY, RULE_PURPOSE, type Report, type ReportMetadata, ReportMetadataSchema, ReportSchema, type Rule, type RuleApplyStrategy, RuleApplyStrategySchema, type RuleCheckFn, type RuleConfig, RuleConfigSchema, type RuleContext, type RuleDefinition, RuleDefinitionSchema, RuleEngine, type RuleEngineOptions, type RuleFailure, type RuleId, RuleImpactAssessmentSchema, type RulePurpose, RulePurposeSchema, type RuleRelatedStruggle, RuleRelatedStruggleSchema, type RuleViolation, SEVERITY_LABELS, SEVERITY_WEIGHT, type SamplingStrategy, SamplingStrategySchema, type ScoreAdjustment, ScoreAdjustmentSchema, type ScoreReport, type Severity, SeveritySchema, type StripDeltaForEval, type StripDeltaResult, StripDeltaResultSchema, StripDeltasArraySchema, StripTypeEnum, type SurveyQuestionBatch, SurveyQuestionBatchSchema, type SurveyQuestionGroup, SurveyQuestionGroupSchema, type TuningAgentInput, type TuningAgentOutput, type UncoveredStruggle, UncoveredStruggleSchema, UncoveredStrugglesInputSchema, version as VERSION, type VisualCompareCliOptions, VisualCompareCliOptionsSchema, absolutePositionInAutoLayout, analyzeFile, buildFigmaDeepLink, buildResultJson, calculateScores, collectComponentIds, collectInteractionDestinationIds, createRuleEngine, deepNesting, defineRule, detachedInstance, detectAnalysisScope, extractRuleScores, fixedSizeInAutoLayout, formatScoreSummary, generateCalibrationReport, generateDesignTree, generateDesignTreeWithStats, getAnalysisState, getAnnotationProperties, getCategoryLabel, getConfigsWithPreset, getRuleOption, getRulePurpose, getSeverityLabel, gradeToClassName, inconsistentNamingConvention, irregularSpacing, isInstanceChildNodeId, isReadyForCodeGen, loadFigmaFileFromJson, missingComponent, missingInteractionState, missingPrototype, missingSizeConstraint, noAutoLayout, nonLayoutContainer, nonSemanticName, nonStandardNaming, parseFigmaJson, parseFigmaUrl, parseInstanceChildNodeId, rawValue, resolveComponentDefinitions, resolveGotchaApplyTarget, resolveInteractionDestinations, ruleRegistry, runAnalysisAgent, runCalibrationAnalyze, runCalibrationEvaluate, runEvaluationAgent, runTuningAgent, stripDeltaToDifficulty, stripDesignTree, supportsDepthWeight, toCommentableNodeId, tokenDeltaToDifficulty, transformComponentMasterNodes, transformFigmaResponse, transformFileNodesResponse, unmappedComponent, variantStructureMismatch };
+export { ALL_STRIP_TYPES, ActivityLogger, type AnalysisAgentInput, type AnalysisAgentOutput, type AnalysisFile, AnalysisFileSchema, type AnalysisIssue, type AnalysisNode, AnalysisNodeSchema, type AnalysisNodeType, AnalysisNodeTypeSchema, type AnalysisResult, type AnalysisScope, AnalysisScopeSchema, AnnotationPropertySchema, CATEGORIES, CATEGORY_LABELS, type CalibrationConfig, type CalibrationConfigInput, CalibrationConfigSchema, type CalibrationRun, type CalibrationStatus, CalibrationStatusSchema, type Category, CategorySchema, type CategoryScore, type CategoryScoreResult, CategoryScoreSchema, type CodeConnectCoverage, type Confidence, ConfidenceSchema, type ConversionRecord, ConversionRecordSchema, DEFAULT_CODEGEN_READY_MIN_GRADE, DEPTH_WEIGHT_CATEGORIES, DESIGN_TREE_INFO_TYPES, type DesignTreeInfoType, type DesignTreeOptions, type DesignTreeResult, type DesignTreeStripType, type Detection, DetectionSchema, type Difficulty, DifficultySchema, type EvaluationAgentInput, type EvaluationAgentOutput, FigmaClient, FigmaClientError, type FigmaClientOptions, FigmaFileLoadError, type FigmaUrlInfo, FigmaUrlInfoSchema, FigmaUrlParseError, GRADE_ORDER, type GapAnalyzerOutput, GapAnalyzerOutputSchema, type GapEntry, GapEntrySchema, type GetFileNodesResponse, type GotchaApplyResolution, type GotchaApplyStrategy, GotchaDetectionSchema, GotchaOutputChannelSchema, GotchaPersistenceIntentSchema, type GotchaSurvey, type GotchaSurveyQuestion, GotchaSurveyQuestionSchema, GotchaSurveySchema, type Grade, type GridChildAlign, GridChildAlignSchema, type GroupedSurvey, GroupedSurveySchema, type InstanceChildIdParts, type InstanceContext, InstanceContextSchema, type Issue, IssueSchema, type LayoutAlign, LayoutAlignSchema, type LayoutConstraint, LayoutConstraintSchema, type LayoutMode, LayoutModeSchema, type LayoutPositioning, LayoutPositioningSchema, type LayoutWrap, LayoutWrapSchema, type McpAnalyzeResponse, McpAnalyzeResponseSchema, type MismatchCase, MismatchCaseSchema, type MismatchType, MismatchTypeSchema, type NewRuleProposal, NewRuleProposalSchema, type NodeIssueDetail, type NodeIssueSummary, NodeIssueSummarySchema, type OutputChannel, OutputChannelSchema, type OverflowDirection, OverflowDirectionSchema, type PersistenceIntent, PersistenceIntentSchema, type Preset, ROUNDTRIP_OPT_OUT_HINT, RULE_ANNOTATION_PROPERTIES, RULE_CONFIGS, RULE_ID_CATEGORY, RULE_PURPOSE, type Report, type ReportMetadata, ReportMetadataSchema, ReportSchema, type Rule, type RuleApplyStrategy, RuleApplyStrategySchema, type RuleCheckFn, type RuleConfig, RuleConfigSchema, type RuleContext, type RuleDefinition, RuleDefinitionSchema, RuleEngine, type RuleEngineOptions, type RuleFailure, type RuleId, RuleImpactAssessmentSchema, type RulePurpose, RulePurposeSchema, type RuleRelatedStruggle, RuleRelatedStruggleSchema, type RuleViolation, SEVERITY_LABELS, SEVERITY_WEIGHT, type SamplingStrategy, SamplingStrategySchema, type ScoreAdjustment, ScoreAdjustmentSchema, type ScoreReport, type Severity, SeveritySchema, type StripDeltaForEval, type StripDeltaResult, StripDeltaResultSchema, StripDeltasArraySchema, StripTypeEnum, type SurveyQuestionBatch, SurveyQuestionBatchSchema, type SurveyQuestionGroup, SurveyQuestionGroupSchema, type TuningAgentInput, type TuningAgentOutput, type UncoveredStruggle, UncoveredStruggleSchema, UncoveredStrugglesInputSchema, version as VERSION, type VisualCompareCliOptions, VisualCompareCliOptionsSchema, absolutePositionInAutoLayout, analyzeFile, buildFigmaDeepLink, buildResultJson, calculateScores, collectComponentIds, collectInteractionDestinationIds, createRuleEngine, deepNesting, defineRule, detachedInstance, detectAnalysisScope, extractRuleScores, fixedSizeInAutoLayout, formatCodeConnectCoverageLine, formatRoundtripOptOutHintLine, formatScoreSummary, generateCalibrationReport, generateDesignTree, generateDesignTreeWithStats, getAnalysisState, getAnnotationProperties, getCategoryLabel, getConfigsWithPreset, getRuleOption, getRulePurpose, getSeverityLabel, gradeToClassName, inconsistentNamingConvention, irregularSpacing, isInstanceChildNodeId, isReadyForCodeGen, loadFigmaFileFromJson, missingComponent, missingInteractionState, missingPrototype, missingSizeConstraint, noAutoLayout, nonLayoutContainer, nonSemanticName, nonStandardNaming, parseFigmaJson, parseFigmaUrl, parseInstanceChildNodeId, rawValue, resolveComponentDefinitions, resolveGotchaApplyTarget, resolveInteractionDestinations, ruleRegistry, runAnalysisAgent, runCalibrationAnalyze, runCalibrationEvaluate, runEvaluationAgent, runTuningAgent, stripDeltaToDifficulty, stripDesignTree, supportsDepthWeight, toCommentableNodeId, tokenDeltaToDifficulty, transformComponentMasterNodes, transformFigmaResponse, transformFileNodesResponse, unmappedComponent, variantStructureMismatch };

package/dist/index.js

@@ -1,12 +1,12 @@
 import { z } from 'zod';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync } from 'fs';
-import { resolve, join, basename, dirname } from 'path';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync, readdirSync } from 'fs';
+import { resolve, join, basename, dirname, isAbsolute, sep } from 'path';
 import { readFile, writeFile, appendFile } from 'fs/promises';
 import 'crypto';
 import { homedir } from 'os';
 
 // package.json
-var version = "0.12.0";
+var version = "0.12.2";
 var SeveritySchema = z.enum([
   "blocking",
   "risk",
@@ -359,7 +359,14 @@ var McpAnalyzeResponseSchema = z.object({
   issuesByRule: z.record(z.string(), z.number().int().min(0)),
   issues: z.array(McpIssueSchema),
   summary: z.string(),
-  failedRules: z.array(z.string()).optional()
+  failedRules: z.array(z.string()).optional(),
+  /**
+   * #526 sub-task 3 — Code Connect mapping coverage. Optional: only emitted
+   * when the consuming repo has `figma.config.json`. Numerator = components in
+   * this file with a discovered `figma.connect` declaration; denominator =
+   * total components in the file.
+   */
+  codeConnectCoverage: z.object({ mapped: z.number().int().min(0), total: z.number().int().min(0) }).optional()
 });
 var GradeSchema2 = z.enum(["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"]);
 var InstanceContextSchema = z.object({
@@ -836,11 +843,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",
@@ -913,6 +940,7 @@ var RuleEngine = class {
   excludeNamePattern;
   excludeNodeTypes;
   acknowledgments;
+  acknowledgmentsByKey;
   scopeOverride;
   constructor(options = {}) {
     this.configs = options.configs ?? RULE_CONFIGS;
@@ -921,10 +949,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;
   }
@@ -1008,6 +1041,7 @@ var RuleEngine = class {
     if (this.excludeNamePattern && this.excludeNamePattern.test(node.name)) {
       return;
     }
+    const acknowledgmentsByKey = this.acknowledgmentsByKey;
     const context = {
       file,
       parent,
@@ -1019,7 +1053,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;
@@ -1378,6 +1413,20 @@ function getSeverityLabel(severity) {
   };
   return labels[severity];
 }
+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) {
+  if (acknowledgmentsProvided) return null;
+  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) {
@@ -1407,6 +1456,14 @@ function buildResultJson(fileName, result, scores, options) {
       ...issue.acknowledged === true ? { acknowledged: true } : {}
     };
   });
+  const optOutHint = options?.roundtripOptOutHintEligible ? formatRoundtripOptOutHintLine(result.issues, false) : null;
+  const summaryParts = [formatScoreSummary(scores)];
+  if (options?.codeConnectCoverage) {
+    summaryParts.push(formatCodeConnectCoverageLine(options.codeConnectCoverage));
+  }
+  if (optOutHint) {
+    summaryParts.push(optOutHint);
+  }
   const json = {
     version,
     analyzedAt: result.analyzedAt,
@@ -1426,8 +1483,14 @@ 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;
   }
@@ -3046,6 +3109,130 @@ var irregularSpacing = 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 config;
+  try {
+    config = 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 = config.codeConnect?.include ?? config.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/index.ts
 var STYLE_COMPARE_KEYS = ["fills", "strokes", "effects", "cornerRadius", "strokeWeight", "individualStrokeWeights"];
 function detectStyleOverrides(master, instance) {
   const overrides = [];
@@ -3254,11 +3441,23 @@ var variantStructureMismatch = 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",
@@ -3268,14 +3467,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)
   };
 };
 var unmappedComponent = defineRule({
@@ -3785,6 +4003,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)}`;
@@ -5427,6 +5671,6 @@ var ActivityLogger = class {
   }
 };
 
-export { ALL_STRIP_TYPES, ActivityLogger, AnalysisFileSchema, AnalysisNodeSchema, AnalysisNodeTypeSchema, AnalysisScopeSchema, AnnotationPropertySchema, CATEGORIES, CATEGORY_LABELS, CalibrationConfigSchema, CalibrationStatusSchema, CategorySchema, CategoryScoreSchema, ConfidenceSchema, ConversionRecordSchema, DEFAULT_CODEGEN_READY_MIN_GRADE, DEPTH_WEIGHT_CATEGORIES, DESIGN_TREE_INFO_TYPES, DetectionSchema, DifficultySchema, FigmaClient, FigmaClientError, FigmaFileLoadError, FigmaUrlInfoSchema, FigmaUrlParseError, GRADE_ORDER, GapAnalyzerOutputSchema, GapEntrySchema, GotchaDetectionSchema, GotchaOutputChannelSchema, GotchaPersistenceIntentSchema, GotchaSurveyQuestionSchema, GotchaSurveySchema, GridChildAlignSchema, GroupedSurveySchema, InstanceContextSchema, IssueSchema, LayoutAlignSchema, LayoutConstraintSchema, LayoutModeSchema, LayoutPositioningSchema, LayoutWrapSchema, McpAnalyzeResponseSchema, MismatchCaseSchema, MismatchTypeSchema, NewRuleProposalSchema, NodeIssueSummarySchema, OutputChannelSchema, OverflowDirectionSchema, PersistenceIntentSchema, RULE_ANNOTATION_PROPERTIES, RULE_CONFIGS, RULE_ID_CATEGORY, RULE_PURPOSE, ReportMetadataSchema, ReportSchema, RuleApplyStrategySchema, RuleConfigSchema, RuleDefinitionSchema, RuleEngine, RuleImpactAssessmentSchema, RulePurposeSchema, RuleRelatedStruggleSchema, SEVERITY_LABELS, SEVERITY_WEIGHT, SamplingStrategySchema, ScoreAdjustmentSchema, SeveritySchema, StripDeltaResultSchema, StripDeltasArraySchema, StripTypeEnum, SurveyQuestionBatchSchema, SurveyQuestionGroupSchema, UncoveredStruggleSchema, UncoveredStrugglesInputSchema, version as VERSION, VisualCompareCliOptionsSchema, absolutePositionInAutoLayout, analyzeFile, buildFigmaDeepLink, buildResultJson, calculateScores, collectComponentIds, collectInteractionDestinationIds, createRuleEngine, deepNesting, defineRule, detachedInstance, detectAnalysisScope, extractRuleScores, fixedSizeInAutoLayout, formatScoreSummary, generateCalibrationReport, generateDesignTree, generateDesignTreeWithStats, getAnalysisState, getAnnotationProperties, getCategoryLabel, getConfigsWithPreset, getRuleOption, getRulePurpose, getSeverityLabel, gradeToClassName, inconsistentNamingConvention, irregularSpacing, isInstanceChildNodeId, isReadyForCodeGen, loadFigmaFileFromJson, missingComponent, missingInteractionState, missingPrototype, missingSizeConstraint, noAutoLayout, nonLayoutContainer, nonSemanticName, nonStandardNaming, parseFigmaJson, parseFigmaUrl, parseInstanceChildNodeId, rawValue, resolveComponentDefinitions, resolveGotchaApplyTarget, resolveInteractionDestinations, ruleRegistry, runAnalysisAgent, runCalibrationAnalyze, runCalibrationEvaluate, runEvaluationAgent, runTuningAgent, stripDeltaToDifficulty, stripDesignTree, supportsDepthWeight, toCommentableNodeId, tokenDeltaToDifficulty, transformComponentMasterNodes, transformFigmaResponse, transformFileNodesResponse, unmappedComponent, variantStructureMismatch };
+export { ALL_STRIP_TYPES, ActivityLogger, AnalysisFileSchema, AnalysisNodeSchema, AnalysisNodeTypeSchema, AnalysisScopeSchema, AnnotationPropertySchema, CATEGORIES, CATEGORY_LABELS, CalibrationConfigSchema, CalibrationStatusSchema, CategorySchema, CategoryScoreSchema, ConfidenceSchema, ConversionRecordSchema, DEFAULT_CODEGEN_READY_MIN_GRADE, DEPTH_WEIGHT_CATEGORIES, DESIGN_TREE_INFO_TYPES, DetectionSchema, DifficultySchema, FigmaClient, FigmaClientError, FigmaFileLoadError, FigmaUrlInfoSchema, FigmaUrlParseError, GRADE_ORDER, GapAnalyzerOutputSchema, GapEntrySchema, GotchaDetectionSchema, GotchaOutputChannelSchema, GotchaPersistenceIntentSchema, GotchaSurveyQuestionSchema, GotchaSurveySchema, GridChildAlignSchema, GroupedSurveySchema, InstanceContextSchema, IssueSchema, LayoutAlignSchema, LayoutConstraintSchema, LayoutModeSchema, LayoutPositioningSchema, LayoutWrapSchema, McpAnalyzeResponseSchema, MismatchCaseSchema, MismatchTypeSchema, NewRuleProposalSchema, NodeIssueSummarySchema, OutputChannelSchema, OverflowDirectionSchema, PersistenceIntentSchema, ROUNDTRIP_OPT_OUT_HINT, RULE_ANNOTATION_PROPERTIES, RULE_CONFIGS, RULE_ID_CATEGORY, RULE_PURPOSE, ReportMetadataSchema, ReportSchema, RuleApplyStrategySchema, RuleConfigSchema, RuleDefinitionSchema, RuleEngine, RuleImpactAssessmentSchema, RulePurposeSchema, RuleRelatedStruggleSchema, SEVERITY_LABELS, SEVERITY_WEIGHT, SamplingStrategySchema, ScoreAdjustmentSchema, SeveritySchema, StripDeltaResultSchema, StripDeltasArraySchema, StripTypeEnum, SurveyQuestionBatchSchema, SurveyQuestionGroupSchema, UncoveredStruggleSchema, UncoveredStrugglesInputSchema, version as VERSION, VisualCompareCliOptionsSchema, absolutePositionInAutoLayout, analyzeFile, buildFigmaDeepLink, buildResultJson, calculateScores, collectComponentIds, collectInteractionDestinationIds, createRuleEngine, deepNesting, defineRule, detachedInstance, detectAnalysisScope, extractRuleScores, fixedSizeInAutoLayout, formatCodeConnectCoverageLine, formatRoundtripOptOutHintLine, formatScoreSummary, generateCalibrationReport, generateDesignTree, generateDesignTreeWithStats, getAnalysisState, getAnnotationProperties, getCategoryLabel, getConfigsWithPreset, getRuleOption, getRulePurpose, getSeverityLabel, gradeToClassName, inconsistentNamingConvention, irregularSpacing, isInstanceChildNodeId, isReadyForCodeGen, loadFigmaFileFromJson, missingComponent, missingInteractionState, missingPrototype, missingSizeConstraint, noAutoLayout, nonLayoutContainer, nonSemanticName, nonStandardNaming, parseFigmaJson, parseFigmaUrl, parseInstanceChildNodeId, rawValue, resolveComponentDefinitions, resolveGotchaApplyTarget, resolveInteractionDestinations, ruleRegistry, runAnalysisAgent, runCalibrationAnalyze, runCalibrationEvaluate, runEvaluationAgent, runTuningAgent, stripDeltaToDifficulty, stripDesignTree, supportsDepthWeight, toCommentableNodeId, tokenDeltaToDifficulty, transformComponentMasterNodes, transformFigmaResponse, transformFileNodesResponse, unmappedComponent, variantStructureMismatch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map