canicode 0.12.2 → 0.12.3

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.2";
+var version = "0.12.3";
 
 declare const SeveritySchema: z.ZodEnum<{
     blocking: "blocking";
@@ -480,6 +480,26 @@ interface RuleContext {
      * sync with `AnalysisNode.type` without a translation layer.
      */
     rootNodeType: string;
+    /**
+     * #557: Root node of the current analysis subtree. Set by
+     * `RuleEngine.analyze` to the same node `traverseAndCheck` walks — i.e.
+     * `file.document` for full-file analysis or the resolved subtree when
+     * `targetNodeId` scopes the run.
+     *
+     * Distinct from `file.document`, which is **always** the full file root.
+     * Rules that build scope-wide indices (e.g. Stage 3 fingerprint pass in
+     * `missing-component`) MUST walk `analysisRoot`, not `file.document` —
+     * walking the full file under a scoped run produces silent false
+     * negatives because the index's first-occurrence id may resolve to a
+     * node outside the current scope, and the in-scope duplicate then never
+     * matches as "first" so the issue never surfaces.
+     *
+     * Optional purely so existing rule unit tests that construct
+     * `RuleContext` literals do not have to backfill the field. The engine
+     * always sets it; rule code reading this should default to
+     * `context.file.document` for safety on the unit-test path.
+     */
+    analysisRoot?: AnalysisNode;
     /**
      * ADR-022: lookup canicode-authored acknowledgments by `(nodeId, ruleId)`.
      * The rule engine builds this from `RuleEngineOptions.acknowledgments` and
@@ -519,6 +539,19 @@ interface RuleViolation {
      * string keeps lowercase prose.
      */
     suggestedName?: string;
+    /**
+     * Phase 3 (#508 / #560): when a rule emits a single issue that represents
+     * a group of N nodes (e.g. `missing-component:structure-repetition` —
+     * one issue per fingerprint group covering N qualifying FRAMEs), this
+     * lists every node id in the group **including** `nodeId`. Document
+     * order, scope-aware. Apply primitives (componentize + replace-with-
+     * instance) iterate this list to drive the full componentize+swap loop
+     * from a single user answer.
+     *
+     * Optional: rules that emit one issue per node (the typical path) leave
+     * this undefined.
+     */
+    groupMembers?: string[];
 }
 /**
  * Rule check function signature
@@ -836,6 +869,7 @@ declare const GotchaSurveyQuestionSchema: z.ZodObject<{
     sourceChildId: z.ZodOptional<z.ZodString>;
     replicas: z.ZodOptional<z.ZodNumber>;
     replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    groupMembers: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 type GotchaSurveyQuestion = z.infer<typeof GotchaSurveyQuestionSchema>;
 /**
@@ -903,6 +937,7 @@ declare const SurveyQuestionBatchSchema: z.ZodObject<{
         sourceChildId: z.ZodOptional<z.ZodString>;
         replicas: z.ZodOptional<z.ZodNumber>;
         replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        groupMembers: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     totalScenes: z.ZodNumber;
 }, z.core.$strip>;
@@ -967,6 +1002,7 @@ declare const SurveyQuestionGroupSchema: z.ZodObject<{
             sourceChildId: z.ZodOptional<z.ZodString>;
             replicas: z.ZodOptional<z.ZodNumber>;
             replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            groupMembers: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
         totalScenes: z.ZodNumber;
     }, z.core.$strip>>;
@@ -1033,6 +1069,7 @@ declare const GroupedSurveySchema: z.ZodObject<{
                 sourceChildId: z.ZodOptional<z.ZodString>;
                 replicas: z.ZodOptional<z.ZodNumber>;
                 replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                groupMembers: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>;
             totalScenes: z.ZodNumber;
         }, z.core.$strip>>;
@@ -1098,6 +1135,7 @@ declare const GotchaSurveySchema: z.ZodObject<{
         sourceChildId: z.ZodOptional<z.ZodString>;
         replicas: z.ZodOptional<z.ZodNumber>;
         replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        groupMembers: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     groupedQuestions: z.ZodObject<{
         groups: z.ZodArray<z.ZodObject<{
@@ -1160,6 +1198,7 @@ declare const GotchaSurveySchema: z.ZodObject<{
                     sourceChildId: z.ZodOptional<z.ZodString>;
                     replicas: z.ZodOptional<z.ZodNumber>;
                     replicaNodeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    groupMembers: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 }, z.core.$strip>>;
                 totalScenes: z.ZodNumber;
             }, z.core.$strip>>;

package/dist/index.js

@@ -6,7 +6,7 @@ import 'crypto';
 import { homedir } from 'os';
 
 // package.json
-var version = "0.12.2";
+var version = "0.12.3";
 var SeveritySchema = z.enum([
   "blocking",
   "risk",
@@ -423,7 +423,25 @@ var GotchaSurveyQuestionSchema = z.object({
   // `[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()
+  replicaNodeIds: z.array(z.string()).optional(),
+  /**
+   * Phase 3 (#508 / #560 / delta 4a): every node id in the rule's emitted
+   * group, including `nodeId`. Currently only populated for
+   * `missing-component:structure-repetition` (Stage 3) — one question per
+   * fingerprint group, the apply step (delta 4b) iterates this list to
+   * componentize the first member and swap the rest.
+   *
+   * Distinct from `replicas` / `replicaNodeIds`: those collapse N
+   * instance-child questions that pre-existed as separate violations into
+   * one. `groupMembers` carries N original group members from a single
+   * group-shaped violation that never became N separate issues. The apply
+   * step distinguishes by which field is set.
+   */
+  // `.min(2)` locks the contract: a group-shaped emit always carries at
+  // least 2 members (Stage 3 short-circuits below `structureMinRepetitions`
+  // = 2). A future rule emitting `[]` or `[oneId]` is a programming error,
+  // not a runtime case to handle gracefully.
+  groupMembers: z.array(z.string()).min(2).optional()
 });
 var SurveyQuestionBatchSchema = z.object({
   ruleId: z.string(),
@@ -995,6 +1013,7 @@ var RuleEngine = class {
       analysisState,
       scope,
       rootNodeType,
+      rootNode,
       void 0,
       void 0
     );
@@ -1031,7 +1050,7 @@ var RuleEngine = class {
   /**
    * Recursively traverse the tree and run rules
    */
-  traverseAndCheck(node, file, rules, maxDepth, issues, failedRules, depth, path, ancestorTypes, componentDepth, analysisState, scope, rootNodeType, parent, siblings) {
+  traverseAndCheck(node, file, rules, maxDepth, issues, failedRules, depth, path, ancestorTypes, componentDepth, analysisState, scope, rootNodeType, analysisRoot, parent, siblings) {
     const nodePath = [...path, node.name];
     const isComponentBoundary = node.type === "COMPONENT" || node.type === "COMPONENT_SET" || node.type === "INSTANCE";
     const currentComponentDepth = isComponentBoundary ? 0 : componentDepth;
@@ -1054,6 +1073,7 @@ var RuleEngine = class {
       analysisState,
       scope,
       rootNodeType,
+      analysisRoot,
       findAcknowledgment: (nodeId, ruleId) => acknowledgmentsByKey.get(`${normalizeNodeId(nodeId)}::${ruleId}`)
     };
     for (const rule of rules) {
@@ -1103,6 +1123,7 @@ var RuleEngine = class {
           analysisState,
           scope,
           rootNodeType,
+          analysisRoot,
           node,
           node.children
         );
@@ -2545,8 +2566,8 @@ var missingComponentMsg = {
     message: `"${name}" appears ${count} times`,
     suggestion: `Extract as a reusable component`
   }),
-  structureRepetition: (name, siblingCount) => ({
-    message: `"${name}" and ${siblingCount} sibling frame(s) share the same internal structure`,
+  structureRepetition: (name, matchCount) => ({
+    message: `"${name}" and ${matchCount} other frame(s) share the same internal structure`,
     suggestion: `Extract a shared component from the repeated structure`
   }),
   styleOverride: (componentName, overrides) => ({
@@ -3281,6 +3302,41 @@ function getSeenStage1(context) {
 function getSeenStage4(context) {
   return getAnalysisState(context, SEEN_STAGE4_KEY, () => /* @__PURE__ */ new Set());
 }
+function stage3GroupsKey(maxDepth) {
+  return `missing-component:stage3Groups:depth=${maxDepth}`;
+}
+function nodeQualifiesForStage3(node, parent, insideInstance) {
+  if (insideInstance) return false;
+  if (node.type !== "FRAME") return false;
+  if (parent?.type === "COMPONENT_SET") return false;
+  if (!node.children || node.children.length === 0) return false;
+  return true;
+}
+function buildStage3Groups(root, maxFingerprintDepth) {
+  const groups = /* @__PURE__ */ new Map();
+  const walk = (node, parent, ancestorIsInstance) => {
+    const insideInstance = ancestorIsInstance || node.type === "INSTANCE";
+    if (nodeQualifiesForStage3(node, parent, ancestorIsInstance)) {
+      const fp = buildFingerprint(node, maxFingerprintDepth);
+      const existing = groups.get(fp);
+      if (existing) existing.memberIds.push(node.id);
+      else groups.set(fp, { memberIds: [node.id] });
+    }
+    if (node.children) {
+      for (const child of node.children) walk(child, node, insideInstance);
+    }
+  };
+  walk(root, null, false);
+  return groups;
+}
+function getStage3Groups(context, maxFingerprintDepth) {
+  const root = context.analysisRoot ?? context.file.document;
+  return getAnalysisState(
+    context,
+    stage3GroupsKey(maxFingerprintDepth),
+    () => buildStage3Groups(root, maxFingerprintDepth)
+  );
+}
 var missingComponentDef = {
   id: "missing-component",
   name: "Missing Component",
@@ -3295,7 +3351,8 @@ var missingComponentCheck = (node, context, options) => {
     const matchingComponent = Object.values(components).find(
       (c) => c.name.toLowerCase() === node.name.toLowerCase()
     );
-    const frameNames = collectFrameNames(context.file.document);
+    const scopeRoot = context.analysisRoot ?? context.file.document;
+    const frameNames = collectFrameNames(scopeRoot);
     const sameNameFrames = frameNames.get(node.name);
     const firstFrame = sameNameFrames?.[0];
     if (matchingComponent) {
@@ -3323,37 +3380,32 @@ var missingComponentCheck = (node, context, options) => {
         };
       }
     }
-    if (isInsideInstance(context)) return null;
-    if (context.parent?.type === "COMPONENT_SET") return null;
-    if (!node.children || node.children.length === 0) return null;
+    if (!nodeQualifiesForStage3(node, context.parent ?? null, isInsideInstance(context))) {
+      return null;
+    }
     const structureMinRepetitions = options?.["structureMinRepetitions"] ?? getRuleOption("missing-component", "structureMinRepetitions", 2);
     const maxFingerprintDepth = options?.["maxFingerprintDepth"] ?? getRuleOption("missing-component", "maxFingerprintDepth", 3);
+    const groups = getStage3Groups(context, maxFingerprintDepth);
     const fingerprint = buildFingerprint(node, maxFingerprintDepth);
-    const siblings = context.siblings ?? [];
-    const qualifyingSiblings = siblings.filter(
-      (s) => s.type === "FRAME" && s.children !== void 0 && s.children.length > 0
-    );
-    const matchingNodes = qualifyingSiblings.filter(
-      (s) => buildFingerprint(s, maxFingerprintDepth) === fingerprint
-    );
-    const selfIsInSiblings = qualifyingSiblings.some((s) => s.id === node.id);
-    const count = selfIsInSiblings ? matchingNodes.length : matchingNodes.length + 1;
-    if (count >= structureMinRepetitions) {
-      const firstMatch = qualifyingSiblings.find(
-        (s) => buildFingerprint(s, maxFingerprintDepth) === fingerprint
-      );
-      const firstMatchId = firstMatch?.id ?? node.id;
-      if (firstMatchId === node.id) {
-        return {
-          ruleId: missingComponentDef.id,
-          subType: "structure-repetition",
-          nodeId: node.id,
-          nodePath: context.path.join(" > "),
-          ...missingComponentMsg.structureRepetition(node.name, count - 1)
-        };
-      }
-    }
-    return null;
+    const group = groups.get(fingerprint);
+    if (!group) return null;
+    if (group.memberIds.length < structureMinRepetitions) return null;
+    if (group.memberIds[0] !== node.id) return null;
+    return {
+      ruleId: missingComponentDef.id,
+      subType: "structure-repetition",
+      nodeId: node.id,
+      nodePath: context.path.join(" > "),
+      ...missingComponentMsg.structureRepetition(
+        node.name,
+        group.memberIds.length - 1
+      ),
+      // #560 / delta 4a: surface the full group so the apply step can drive
+      // the componentize+swap loop from a single user answer. `nodeId` is
+      // the document-order first member; the rest are siblings or cross-
+      // parent matches found by the scope-wide pass (#557).
+      groupMembers: [...group.memberIds]
+    };
   }
   if (node.type === "INSTANCE" && node.componentId) {
     const seenStage4 = getSeenStage4(context);