canicode 0.10.2 → 0.10.4

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { GetFileResponse, Node } from '@figma/rest-api-spec';
 
-var version = "0.10.2";
+var version = "0.10.4";
 
 declare const SeveritySchema: z.ZodEnum<{
     blocking: "blocking";
@@ -652,8 +652,163 @@ declare const GotchaSurveyQuestionSchema: z.ZodObject<{
     suggestedName: z.ZodOptional<z.ZodString>;
     isInstanceChild: z.ZodBoolean;
     sourceChildId: z.ZodOptional<z.ZodString>;
+    replicas: z.ZodOptional<z.ZodNumber>;
+    replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 type GotchaSurveyQuestion = z.infer<typeof GotchaSurveyQuestionSchema>;
+/**
+ * Pre-grouped+batched view of `questions` (#369, #370, #381). Decoupled from
+ * `questions` so consumers that just want the flat list can ignore it; SKILLs
+ * (`canicode-gotchas`, `canicode-roundtrip`) iterate over `groupedQuestions`
+ * to keep sort / partition / batchable-rule decisions out of the LLM's
+ * prose interpretation, per ADR-016.
+ *
+ * Generated by `groupAndBatchSurveyQuestions` in `core/gotcha/`. Sort key is
+ * `(sourceComponentId ?? "_no-source", ruleId, nodeName)`. Source-component
+ * groups are emitted first; the trailing group with `instanceContext: null`
+ * carries every non-instance question.
+ */
+declare const SurveyQuestionBatchSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    batchable: z.ZodBoolean;
+    questions: z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        nodeName: z.ZodString;
+        ruleId: z.ZodString;
+        severity: z.ZodEnum<{
+            blocking: "blocking";
+            risk: "risk";
+            "missing-info": "missing-info";
+            suggestion: "suggestion";
+        }>;
+        question: z.ZodString;
+        hint: z.ZodString;
+        example: z.ZodString;
+        instanceContext: z.ZodOptional<z.ZodObject<{
+            parentInstanceNodeId: z.ZodString;
+            sourceNodeId: z.ZodString;
+            sourceComponentId: z.ZodOptional<z.ZodString>;
+            sourceComponentName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        applyStrategy: z.ZodEnum<{
+            "property-mod": "property-mod";
+            "structural-mod": "structural-mod";
+            annotation: "annotation";
+            "auto-fix": "auto-fix";
+        }>;
+        targetProperty: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        annotationProperties: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+        }, z.core.$strip>>>;
+        suggestedName: z.ZodOptional<z.ZodString>;
+        isInstanceChild: z.ZodBoolean;
+        sourceChildId: z.ZodOptional<z.ZodString>;
+        replicas: z.ZodOptional<z.ZodNumber>;
+        replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    totalScenes: z.ZodNumber;
+}, z.core.$strip>;
+type SurveyQuestionBatch = z.infer<typeof SurveyQuestionBatchSchema>;
+declare const SurveyQuestionGroupSchema: z.ZodObject<{
+    instanceContext: z.ZodNullable<z.ZodObject<{
+        parentInstanceNodeId: z.ZodString;
+        sourceNodeId: z.ZodString;
+        sourceComponentId: z.ZodOptional<z.ZodString>;
+        sourceComponentName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    batches: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        batchable: z.ZodBoolean;
+        questions: z.ZodArray<z.ZodObject<{
+            nodeId: z.ZodString;
+            nodeName: z.ZodString;
+            ruleId: z.ZodString;
+            severity: z.ZodEnum<{
+                blocking: "blocking";
+                risk: "risk";
+                "missing-info": "missing-info";
+                suggestion: "suggestion";
+            }>;
+            question: z.ZodString;
+            hint: z.ZodString;
+            example: z.ZodString;
+            instanceContext: z.ZodOptional<z.ZodObject<{
+                parentInstanceNodeId: z.ZodString;
+                sourceNodeId: z.ZodString;
+                sourceComponentId: z.ZodOptional<z.ZodString>;
+                sourceComponentName: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            applyStrategy: z.ZodEnum<{
+                "property-mod": "property-mod";
+                "structural-mod": "structural-mod";
+                annotation: "annotation";
+                "auto-fix": "auto-fix";
+            }>;
+            targetProperty: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            annotationProperties: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                type: z.ZodString;
+            }, z.core.$strip>>>;
+            suggestedName: z.ZodOptional<z.ZodString>;
+            isInstanceChild: z.ZodBoolean;
+            sourceChildId: z.ZodOptional<z.ZodString>;
+            replicas: z.ZodOptional<z.ZodNumber>;
+            replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        totalScenes: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type SurveyQuestionGroup = z.infer<typeof SurveyQuestionGroupSchema>;
+declare const GroupedSurveySchema: z.ZodObject<{
+    groups: z.ZodArray<z.ZodObject<{
+        instanceContext: z.ZodNullable<z.ZodObject<{
+            parentInstanceNodeId: z.ZodString;
+            sourceNodeId: z.ZodString;
+            sourceComponentId: z.ZodOptional<z.ZodString>;
+            sourceComponentName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        batches: z.ZodArray<z.ZodObject<{
+            ruleId: z.ZodString;
+            batchable: z.ZodBoolean;
+            questions: z.ZodArray<z.ZodObject<{
+                nodeId: z.ZodString;
+                nodeName: z.ZodString;
+                ruleId: z.ZodString;
+                severity: z.ZodEnum<{
+                    blocking: "blocking";
+                    risk: "risk";
+                    "missing-info": "missing-info";
+                    suggestion: "suggestion";
+                }>;
+                question: z.ZodString;
+                hint: z.ZodString;
+                example: z.ZodString;
+                instanceContext: z.ZodOptional<z.ZodObject<{
+                    parentInstanceNodeId: z.ZodString;
+                    sourceNodeId: z.ZodString;
+                    sourceComponentId: z.ZodOptional<z.ZodString>;
+                    sourceComponentName: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                applyStrategy: z.ZodEnum<{
+                    "property-mod": "property-mod";
+                    "structural-mod": "structural-mod";
+                    annotation: "annotation";
+                    "auto-fix": "auto-fix";
+                }>;
+                targetProperty: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                annotationProperties: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    type: z.ZodString;
+                }, z.core.$strip>>>;
+                suggestedName: z.ZodOptional<z.ZodString>;
+                isInstanceChild: z.ZodBoolean;
+                sourceChildId: z.ZodOptional<z.ZodString>;
+                replicas: z.ZodOptional<z.ZodNumber>;
+                replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+            totalScenes: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type GroupedSurvey = z.infer<typeof GroupedSurveySchema>;
 declare const GotchaSurveySchema: z.ZodObject<{
     designGrade: z.ZodEnum<{
         S: "S";
@@ -699,12 +854,95 @@ declare const GotchaSurveySchema: z.ZodObject<{
         suggestedName: z.ZodOptional<z.ZodString>;
         isInstanceChild: z.ZodBoolean;
         sourceChildId: z.ZodOptional<z.ZodString>;
+        replicas: z.ZodOptional<z.ZodNumber>;
+        replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    groupedQuestions: z.ZodObject<{
+        groups: z.ZodArray<z.ZodObject<{
+            instanceContext: z.ZodNullable<z.ZodObject<{
+                parentInstanceNodeId: z.ZodString;
+                sourceNodeId: z.ZodString;
+                sourceComponentId: z.ZodOptional<z.ZodString>;
+                sourceComponentName: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            batches: z.ZodArray<z.ZodObject<{
+                ruleId: z.ZodString;
+                batchable: z.ZodBoolean;
+                questions: z.ZodArray<z.ZodObject<{
+                    nodeId: z.ZodString;
+                    nodeName: z.ZodString;
+                    ruleId: z.ZodString;
+                    severity: z.ZodEnum<{
+                        blocking: "blocking";
+                        risk: "risk";
+                        "missing-info": "missing-info";
+                        suggestion: "suggestion";
+                    }>;
+                    question: z.ZodString;
+                    hint: z.ZodString;
+                    example: z.ZodString;
+                    instanceContext: z.ZodOptional<z.ZodObject<{
+                        parentInstanceNodeId: z.ZodString;
+                        sourceNodeId: z.ZodString;
+                        sourceComponentId: z.ZodOptional<z.ZodString>;
+                        sourceComponentName: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>;
+                    applyStrategy: z.ZodEnum<{
+                        "property-mod": "property-mod";
+                        "structural-mod": "structural-mod";
+                        annotation: "annotation";
+                        "auto-fix": "auto-fix";
+                    }>;
+                    targetProperty: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                    annotationProperties: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        type: z.ZodString;
+                    }, z.core.$strip>>>;
+                    suggestedName: z.ZodOptional<z.ZodString>;
+                    isInstanceChild: z.ZodBoolean;
+                    sourceChildId: z.ZodOptional<z.ZodString>;
+                    replicas: z.ZodOptional<z.ZodNumber>;
+                    replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strip>>;
+                totalScenes: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    designKey: z.ZodString;
 }, z.core.$strip>;
 type GotchaSurvey = z.infer<typeof GotchaSurveySchema>;
 
 /**
- * Analysis issue with calculated score and metadata
+ * Acknowledgment marker — surfaced from a Figma Dev Mode annotation that
+ * canicode itself wrote during a roundtrip. When the analysis pipeline
+ * receives a list of acknowledgments, matching `(nodeId, ruleId)` issues are
+ * flagged `acknowledged: true` and contribute half their normal weight to
+ * the density score (#371).
+ *
+ * This contract is consumed by:
+ * - The MCP `analyze` tool (`acknowledgments?: Acknowledgment[]` input)
+ * - The CLI `analyze --acknowledgments <path>` flag
+ * - `RuleEngineOptions.acknowledgments`
+ *
+ * It is produced by the Plugin-API helper
+ * `extractAcknowledgmentsFromNode` / `readCanicodeAcknowledgments`
+ * (see `src/core/roundtrip/read-acknowledgments.ts`).
+ */
+declare const AcknowledgmentSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    ruleId: z.ZodString;
+}, z.core.$strip>;
+type Acknowledgment = z.infer<typeof AcknowledgmentSchema>;
+
+/**
+ * Analysis issue with calculated score and metadata.
+ *
+ * `acknowledged` (#371) — set when the analysis engine receives an
+ * `acknowledgments` list (typically read from canicode-authored Figma
+ * annotations) whose `(nodeId, ruleId)` matches this issue. Acknowledged
+ * issues still surface in the result (so code-gen retains the context) but
+ * contribute half their normal weight to the density score, so the grade
+ * reflects "the designer has a plan for this" instead of treating the rule
+ * as fully unaddressed.
  */
 interface AnalysisIssue {
     violation: RuleViolation;
@@ -713,6 +951,7 @@ interface AnalysisIssue {
     depth: number;
     maxDepth: number;
     calculatedScore: number;
+    acknowledged?: boolean;
 }
 /**
  * Information about a rule that threw during analysis
@@ -744,6 +983,14 @@ interface RuleEngineOptions {
     targetNodeId?: string;
     excludeNodeNames?: string[];
     excludeNodeTypes?: string[];
+    /**
+     * `(nodeId, ruleId)` pairs sourced from canicode-authored Figma annotations
+     * (#371). Issues whose violation matches an entry are flagged
+     * `acknowledged: true` and contribute half their normal weight to the
+     * density score in `calculateScores`. nodeId may be passed in URL form
+     * (`123-456`) or Plugin-API form (`123:456`) — both normalize to `:`.
+     */
+    acknowledgments?: Acknowledgment[];
 }
 /**
  * Rule engine for analyzing Figma files
@@ -755,6 +1002,7 @@ declare class RuleEngine {
     private targetNodeId;
     private excludeNamePattern;
     private excludeNodeTypes;
+    private acknowledgments;
     constructor(options?: RuleEngineOptions);
     /**
      * Analyze a Figma file and return issues
@@ -811,6 +1059,15 @@ interface ScoreReport {
         missingInfo: number;
         suggestion: number;
         nodeCount: number;
+        /**
+         * Number of issues marked `acknowledged` by an upstream
+         * acknowledgments list (#371). Acknowledged issues are still counted in
+         * `totalIssues` and the per-severity tallies — the count here is purely
+         * additive context so consumers can render
+         * `N issues — A acknowledged / N-A unaddressed`. They contribute half
+         * weight to the density score upstream.
+         */
+        acknowledgedCount: number;
     };
 }
 /**
@@ -858,6 +1115,7 @@ declare function getSeverityLabel(severity: Severity): string;
  */
 declare function buildResultJson(fileName: string, result: AnalysisResult, scores: ScoreReport, options?: {
     fileKey?: string;
+    designKey?: string;
 }): Record<string, unknown>;
 
 /**
@@ -1849,4 +2107,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, 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, DEPTH_WEIGHT_CATEGORIES, DESIGN_TREE_INFO_TYPES, type DesignTreeInfoType, type DesignTreeOptions, type DesignTreeResult, type DesignTreeStripType, type Difficulty, DifficultySchema, type EvaluationAgentInput, type EvaluationAgentOutput, FigmaClient, FigmaClientError, type FigmaClientOptions, FigmaFileLoadError, type FigmaUrlInfo, FigmaUrlInfoSchema, FigmaUrlParseError, type GapAnalyzerOutput, GapAnalyzerOutputSchema, type GapEntry, GapEntrySchema, type GetFileNodesResponse, type GotchaApplyResolution, type GotchaApplyStrategy, type GotchaSurvey, type GotchaSurveyQuestion, GotchaSurveyQuestionSchema, GotchaSurveySchema, type Grade, type GridChildAlign, GridChildAlignSchema, 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 OverflowDirection, OverflowDirectionSchema, type Preset, RULE_ANNOTATION_PROPERTIES, RULE_CONFIGS, RULE_ID_CATEGORY, 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 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 TuningAgentInput, type TuningAgentOutput, type UncoveredStruggle, UncoveredStruggleSchema, UncoveredStrugglesInputSchema, version as VERSION, type VisualCompareCliOptions, VisualCompareCliOptionsSchema, absolutePositionInAutoLayout, analyzeFile, buildFigmaDeepLink, buildResultJson, calculateScores, collectComponentIds, collectInteractionDestinationIds, createRuleEngine, deepNesting, defineRule, detachedInstance, extractRuleScores, fixedSizeInAutoLayout, formatScoreSummary, generateCalibrationReport, generateDesignTree, generateDesignTreeWithStats, getAnalysisState, getAnnotationProperties, getCategoryLabel, getConfigsWithPreset, getRuleOption, 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, variantStructureMismatch };
+export { ALL_STRIP_TYPES, ActivityLogger, type AnalysisAgentInput, type AnalysisAgentOutput, type AnalysisFile, AnalysisFileSchema, type AnalysisIssue, type AnalysisNode, AnalysisNodeSchema, type AnalysisNodeType, AnalysisNodeTypeSchema, type AnalysisResult, 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, DEPTH_WEIGHT_CATEGORIES, DESIGN_TREE_INFO_TYPES, type DesignTreeInfoType, type DesignTreeOptions, type DesignTreeResult, type DesignTreeStripType, type Difficulty, DifficultySchema, type EvaluationAgentInput, type EvaluationAgentOutput, FigmaClient, FigmaClientError, type FigmaClientOptions, FigmaFileLoadError, type FigmaUrlInfo, FigmaUrlInfoSchema, FigmaUrlParseError, type GapAnalyzerOutput, GapAnalyzerOutputSchema, type GapEntry, GapEntrySchema, type GetFileNodesResponse, type GotchaApplyResolution, type GotchaApplyStrategy, 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 OverflowDirection, OverflowDirectionSchema, type Preset, RULE_ANNOTATION_PROPERTIES, RULE_CONFIGS, RULE_ID_CATEGORY, 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 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, extractRuleScores, fixedSizeInAutoLayout, formatScoreSummary, generateCalibrationReport, generateDesignTree, generateDesignTreeWithStats, getAnalysisState, getAnnotationProperties, getCategoryLabel, getConfigsWithPreset, getRuleOption, 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, variantStructureMismatch };

package/dist/index.js

@@ -6,7 +6,7 @@ import 'crypto';
 import { homedir } from 'os';
 
 // package.json
-var version = "0.10.2";
+var version = "0.10.4";
 var SeveritySchema = z.enum([
   "blocking",
   "risk",
@@ -353,12 +353,60 @@ var GotchaSurveyQuestionSchema = z.object({
   annotationProperties: z.array(AnnotationPropertySchema).optional(),
   suggestedName: z.string().optional(),
   isInstanceChild: z.boolean(),
-  sourceChildId: z.string().optional()
+  sourceChildId: z.string().optional(),
+  // #356: when this question collapses N instance-child issues that share the
+  // same `(sourceComponentId, sourceNodeId, ruleId)` tuple, `replicas` is the
+  // total instance count (>=2) and `replicaNodeIds` lists every instance scene
+  // node id OTHER than the kept `nodeId`. Apply step iterates
+  // `[nodeId, ...replicaNodeIds]` so the same answer lands on every replica.
+  // Single-instance questions omit both fields.
+  replicas: z.number().int().min(2).optional(),
+  replicaNodeIds: z.array(z.string()).optional()
+});
+var SurveyQuestionBatchSchema = z.object({
+  ruleId: z.string(),
+  /**
+   * `true` when every member shares an answer-shape uniformly applicable to
+   * all of them (e.g. one `min-width` value covers all FILL children).
+   * The SKILL renders one shared prompt for `batchable: true` batches with
+   * `questions.length >= 2`; everything else falls through to the
+   * single-question template.
+   */
+  batchable: z.boolean(),
+  questions: z.array(GotchaSurveyQuestionSchema),
+  /**
+   * Sum of `max(question.replicas, 1)` across `questions`. Counts the
+   * actual Figma scene fan-out so the SKILL can render `N instances`
+   * accurately even when one batch member already collapses multiple
+   * replicas via the #356 source-component dedupe.
+   */
+  totalScenes: z.number().int().min(1)
+});
+var SurveyQuestionGroupSchema = z.object({
+  /**
+   * Shared `instanceContext` for the group, or `null` for the trailing
+   * non-instance group. The SKILL emits the verbose "Instance note" header
+   * once per non-null group instead of once per question (#370).
+   */
+  instanceContext: InstanceContextSchema.nullable(),
+  batches: z.array(SurveyQuestionBatchSchema)
+});
+var GroupedSurveySchema = z.object({
+  groups: z.array(SurveyQuestionGroupSchema)
 });
 var GotchaSurveySchema = z.object({
   designGrade: GradeSchema2,
   isReadyForCodeGen: z.boolean(),
-  questions: z.array(GotchaSurveyQuestionSchema)
+  questions: z.array(GotchaSurveyQuestionSchema),
+  groupedQuestions: GroupedSurveySchema,
+  /**
+   * #384 — canonical identifier for this design across canicode runs.
+   * Computed by `computeDesignKey(input)` (`<fileKey>#<nodeId>` for Figma
+   * URLs, absolute path for fixtures). The `canicode-gotchas` SKILL reads
+   * this directly when upserting the per-design section, so the SKILL.md
+   * prose no longer parses URLs (per ADR-016).
+   */
+  designKey: z.string()
 });
 
 // src/core/rules/rule-config.ts
@@ -642,6 +690,14 @@ function defineRule(rule) {
   ruleRegistry.register(rule);
   return rule;
 }
+var AcknowledgmentSchema = z.object({
+  nodeId: z.string(),
+  ruleId: z.string()
+});
+z.array(AcknowledgmentSchema);
+function normalizeNodeId(id) {
+  return id.replace(/-/g, ":");
+}
 
 // src/core/engine/rule-engine.ts
 function calculateMaxDepth(node, currentDepth = 0) {
@@ -692,6 +748,7 @@ var RuleEngine = class {
   targetNodeId;
   excludeNamePattern;
   excludeNodeTypes;
+  acknowledgments;
   constructor(options = {}) {
     this.configs = options.configs ?? RULE_CONFIGS;
     this.enabledRuleIds = options.enabledRules ? new Set(options.enabledRules) : null;
@@ -699,6 +756,11 @@ var RuleEngine = class {
     this.targetNodeId = options.targetNodeId;
     this.excludeNamePattern = options.excludeNodeNames && options.excludeNodeNames.length > 0 ? new RegExp(`\\b(${options.excludeNodeNames.join("|")})\\b`, "i") : null;
     this.excludeNodeTypes = options.excludeNodeTypes && options.excludeNodeTypes.length > 0 ? new Set(options.excludeNodeTypes) : null;
+    this.acknowledgments = new Set(
+      (options.acknowledgments ?? []).map(
+        (a) => `${normalizeNodeId(a.nodeId)}::${a.ruleId}`
+      )
+    );
   }
   /**
    * Analyze a Figma file and return issues
@@ -733,6 +795,14 @@ var RuleEngine = class {
       void 0,
       void 0
     );
+    if (this.acknowledgments.size > 0) {
+      for (const issue of issues) {
+        const key = `${normalizeNodeId(issue.violation.nodeId)}::${issue.violation.ruleId}`;
+        if (this.acknowledgments.has(key)) {
+          issue.acknowledged = true;
+        }
+      }
+    }
     return {
       file,
       issues,
@@ -883,8 +953,6 @@ function resolveTargetProperty(ruleId, subType) {
       if (subType === "horizontal") return "layoutSizingHorizontal";
       return ["layoutSizingHorizontal", "layoutSizingVertical"];
     case "missing-size-constraint":
-      if (subType === "wrap") return "minWidth";
-      if (subType === "max-width") return "maxWidth";
       return ["minWidth", "maxWidth"];
     case "irregular-spacing":
       if (subType === "gap") return "itemSpacing";
@@ -984,7 +1052,8 @@ function calculateScores(result, configs) {
     uniqueRulesPerCategory.get(category).add(ruleId);
     ruleScorePerCategory.get(category).set(ruleId, Math.abs(issue.config.score));
     const ruleCountMap = ruleIssueCountPerCategory.get(category);
-    ruleCountMap.set(ruleId, (ruleCountMap.get(ruleId) ?? 0) + 1);
+    const weight = issue.acknowledged === true ? 0.5 : 1;
+    ruleCountMap.set(ruleId, (ruleCountMap.get(ruleId) ?? 0) + weight);
   }
   for (const category of CATEGORIES) {
     const ruleCountMap = ruleIssueCountPerCategory.get(category);
@@ -1031,7 +1100,8 @@ function calculateScores(result, configs) {
     risk: 0,
     missingInfo: 0,
     suggestion: 0,
-    nodeCount
+    nodeCount,
+    acknowledgedCount: 0
   };
   for (const issue of result.issues) {
     switch (issue.config.severity) {
@@ -1048,6 +1118,7 @@ function calculateScores(result, configs) {
         summary.suggestion++;
         break;
     }
+    if (issue.acknowledged === true) summary.acknowledgedCount++;
   }
   return {
     overall: {
@@ -1098,7 +1169,14 @@ function formatScoreSummary(report) {
   lines.push(`  Risk: ${report.summary.risk}`);
   lines.push(`  Missing Info: ${report.summary.missingInfo}`);
   lines.push(`  Suggestion: ${report.summary.suggestion}`);
-  lines.push(`  Total: ${report.summary.totalIssues}`);
+  if (report.summary.acknowledgedCount > 0) {
+    const unaddressed = report.summary.totalIssues - report.summary.acknowledgedCount;
+    lines.push(
+      `  Total: ${report.summary.totalIssues} (${report.summary.acknowledgedCount} acknowledged via canicode annotations / ${unaddressed} unaddressed)`
+    );
+  } else {
+    lines.push(`  Total: ${report.summary.totalIssues}`);
+  }
   return lines.join("\n");
 }
 function getCategoryLabel(category) {
@@ -1134,17 +1212,20 @@ function buildResultJson(fileName, result, scores, options) {
       ...applyContext.annotationProperties !== void 0 ? { annotationProperties: applyContext.annotationProperties } : {},
       ...suggestedName !== void 0 ? { suggestedName } : {},
       isInstanceChild: applyContext.isInstanceChild,
-      ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {}
+      ...applyContext.sourceChildId !== void 0 ? { sourceChildId: applyContext.sourceChildId } : {},
+      ...issue.acknowledged === true ? { acknowledged: true } : {}
     };
   });
   const json = {
     version,
     analyzedAt: result.analyzedAt,
     ...options?.fileKey && { fileKey: options.fileKey },
+    ...options?.designKey && { designKey: options.designKey },
     fileName,
     nodeCount: result.nodeCount,
     maxDepth: result.maxDepth,
     issueCount: result.issues.length,
+    acknowledgedCount: scores.summary.acknowledgedCount,
     isReadyForCodeGen: isReadyForCodeGen(scores.overall.grade),
     blockingIssueCount: scores.summary.blocking,
     scores: {
@@ -3061,6 +3142,7 @@ var inconsistentNamingConventionCheck = (node, context) => {
   if (nodeConvention && nodeConvention !== dominantConvention && maxCount >= 2) {
     if (isCompatible(nodeConvention, dominantConvention, node.name)) return null;
     const suggested = convertName(node.name, dominantConvention);
+    if (suggested === node.name) return null;
     return {
       ruleId: inconsistentNamingConventionDef.id,
       nodeId: node.id,
@@ -3156,6 +3238,15 @@ function hasStateInComponentMaster(node, context, statePattern) {
   if (!master) return false;
   return hasStateInVariantProps(master, statePattern);
 }
+function canDetermineVariants(node, context) {
+  if (node.type === "COMPONENT") return true;
+  if (node.componentPropertyDefinitions !== void 0) return true;
+  if (node.componentId !== void 0) {
+    const defs = context.file.componentDefinitions;
+    if (defs && defs[node.componentId] !== void 0) return true;
+  }
+  return false;
+}
 var missingInteractionStateDef = {
   id: "missing-interaction-state",
   name: "Missing Interaction State",
@@ -3170,6 +3261,7 @@ var missingInteractionStateCheck = (node, context) => {
   if (!interactiveType) return null;
   const expectedStates = EXPECTED_STATES[interactiveType];
   if (!expectedStates) return null;
+  if (!canDetermineVariants(node, context)) return null;
   const seen = getSeen(context);
   const nodePath = context.path.join(" > ");
   for (const state of expectedStates) {
@@ -5046,6 +5138,6 @@ var ActivityLogger = class {
   }
 };
 
-export { ALL_STRIP_TYPES, ActivityLogger, AnalysisFileSchema, AnalysisNodeSchema, AnalysisNodeTypeSchema, AnnotationPropertySchema, CATEGORIES, CATEGORY_LABELS, CalibrationConfigSchema, CalibrationStatusSchema, CategorySchema, CategoryScoreSchema, ConfidenceSchema, ConversionRecordSchema, DEPTH_WEIGHT_CATEGORIES, DESIGN_TREE_INFO_TYPES, DifficultySchema, FigmaClient, FigmaClientError, FigmaFileLoadError, FigmaUrlInfoSchema, FigmaUrlParseError, GapAnalyzerOutputSchema, GapEntrySchema, GotchaSurveyQuestionSchema, GotchaSurveySchema, GridChildAlignSchema, InstanceContextSchema, IssueSchema, LayoutAlignSchema, LayoutConstraintSchema, LayoutModeSchema, LayoutPositioningSchema, LayoutWrapSchema, McpAnalyzeResponseSchema, MismatchCaseSchema, MismatchTypeSchema, NewRuleProposalSchema, NodeIssueSummarySchema, OverflowDirectionSchema, RULE_ANNOTATION_PROPERTIES, RULE_CONFIGS, RULE_ID_CATEGORY, ReportMetadataSchema, ReportSchema, RuleApplyStrategySchema, RuleConfigSchema, RuleDefinitionSchema, RuleEngine, RuleImpactAssessmentSchema, RuleRelatedStruggleSchema, SEVERITY_LABELS, SEVERITY_WEIGHT, SamplingStrategySchema, ScoreAdjustmentSchema, SeveritySchema, StripDeltaResultSchema, StripDeltasArraySchema, StripTypeEnum, UncoveredStruggleSchema, UncoveredStrugglesInputSchema, version as VERSION, VisualCompareCliOptionsSchema, absolutePositionInAutoLayout, analyzeFile, buildFigmaDeepLink, buildResultJson, calculateScores, collectComponentIds, collectInteractionDestinationIds, createRuleEngine, deepNesting, defineRule, detachedInstance, extractRuleScores, fixedSizeInAutoLayout, formatScoreSummary, generateCalibrationReport, generateDesignTree, generateDesignTreeWithStats, getAnalysisState, getAnnotationProperties, getCategoryLabel, getConfigsWithPreset, getRuleOption, 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, variantStructureMismatch };
+export { ALL_STRIP_TYPES, ActivityLogger, AnalysisFileSchema, AnalysisNodeSchema, AnalysisNodeTypeSchema, AnnotationPropertySchema, CATEGORIES, CATEGORY_LABELS, CalibrationConfigSchema, CalibrationStatusSchema, CategorySchema, CategoryScoreSchema, ConfidenceSchema, ConversionRecordSchema, DEPTH_WEIGHT_CATEGORIES, DESIGN_TREE_INFO_TYPES, DifficultySchema, FigmaClient, FigmaClientError, FigmaFileLoadError, FigmaUrlInfoSchema, FigmaUrlParseError, GapAnalyzerOutputSchema, GapEntrySchema, GotchaSurveyQuestionSchema, GotchaSurveySchema, GridChildAlignSchema, GroupedSurveySchema, InstanceContextSchema, IssueSchema, LayoutAlignSchema, LayoutConstraintSchema, LayoutModeSchema, LayoutPositioningSchema, LayoutWrapSchema, McpAnalyzeResponseSchema, MismatchCaseSchema, MismatchTypeSchema, NewRuleProposalSchema, NodeIssueSummarySchema, OverflowDirectionSchema, RULE_ANNOTATION_PROPERTIES, RULE_CONFIGS, RULE_ID_CATEGORY, ReportMetadataSchema, ReportSchema, RuleApplyStrategySchema, RuleConfigSchema, RuleDefinitionSchema, RuleEngine, RuleImpactAssessmentSchema, 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, extractRuleScores, fixedSizeInAutoLayout, formatScoreSummary, generateCalibrationReport, generateDesignTree, generateDesignTreeWithStats, getAnalysisState, getAnnotationProperties, getCategoryLabel, getConfigsWithPreset, getRuleOption, 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, variantStructureMismatch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map