canicode 0.12.2 → 0.12.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.12.2";
+var version = "0.12.4";
 
 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.4";
 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) => ({
@@ -2972,6 +2993,10 @@ var deepNesting = defineRule({
 function isOnGrid(value, gridBase) {
   return value % gridBase === 0;
 }
+function hasOwnBoundVariables(obj) {
+  const bv = obj["boundVariables"];
+  return bv !== void 0 && bv !== null && Object.keys(bv).length > 0;
+}
 var rawValueDef = {
   id: "raw-value",
   name: "Raw Value",
@@ -2986,6 +3011,7 @@ var rawValueCheck = (node, context) => {
     if (!hasStyleReference(node, "fill") && !hasBoundVariable(node, "fills")) {
       for (const fill of node.fills) {
         const fillObj = fill;
+        if (hasOwnBoundVariables(fillObj)) continue;
         if (fillObj["type"] === "SOLID" && fillObj["color"]) {
           const c = fillObj["color"];
           const hex = `#${Math.round((c["r"] ?? 0) * 255).toString(16).padStart(2, "0")}${Math.round((c["g"] ?? 0) * 255).toString(16).padStart(2, "0")}${Math.round((c["b"] ?? 0) * 255).toString(16).padStart(2, "0")}`.toUpperCase();
@@ -3020,9 +3046,10 @@ var rawValueCheck = (node, context) => {
     }
   }
   if (node.effects && Array.isArray(node.effects) && node.effects.length > 0) {
-    if (!hasStyleReference(node, "effect")) {
+    if (!hasStyleReference(node, "effect") && !hasBoundVariable(node, "effects")) {
       for (const effect of node.effects) {
         const effectObj = effect;
+        if (hasOwnBoundVariables(effectObj)) continue;
         if (effectObj["type"] === "DROP_SHADOW" || effectObj["type"] === "INNER_SHADOW") {
           const shadowType = effectObj["type"] === "DROP_SHADOW" ? "drop shadow" : "inner shadow";
           const offset = effectObj["offset"];
@@ -3053,6 +3080,7 @@ var rawValueCheck = (node, context) => {
   }
   const spacingKeys = ["paddingLeft", "paddingRight", "paddingTop", "paddingBottom", "itemSpacing"];
   for (const key of spacingKeys) {
+    if (key === "itemSpacing" && node.primaryAxisAlignItems === "SPACE_BETWEEN") continue;
     const value = node[key];
     if (value !== void 0 && value > 0 && !hasBoundVariable(node, key)) {
       const label = key === "itemSpacing" ? "gap" : key.replace("padding", "padding-").toLowerCase();
@@ -3085,14 +3113,15 @@ var irregularSpacingCheck = (node, context, options) => {
   const spacingEntries = [];
   for (const key of ["paddingLeft", "paddingRight", "paddingTop", "paddingBottom"]) {
     const v = node[key];
-    if (v !== void 0 && v > 0) spacingEntries.push({ value: v, subType: "padding" });
+    if (v !== void 0 && v > 0) spacingEntries.push({ key, value: v, subType: "padding" });
   }
-  if (node.itemSpacing !== void 0 && node.itemSpacing > 0) {
-    spacingEntries.push({ value: node.itemSpacing, subType: "gap" });
+  if (node.itemSpacing !== void 0 && node.itemSpacing > 0 && node.primaryAxisAlignItems !== "SPACE_BETWEEN") {
+    spacingEntries.push({ key: "itemSpacing", value: node.itemSpacing, subType: "gap" });
   }
   const commonValues = [1, 2];
   for (const entry of spacingEntries) {
     if (commonValues.includes(entry.value)) continue;
+    if (hasBoundVariable(node, entry.key)) continue;
     if (!isOnGrid(entry.value, gridBase)) {
       return {
         ruleId: irregularSpacingDef.id,
@@ -3281,6 +3310,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 +3359,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 +3388,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);
@@ -3443,17 +3503,28 @@ var variantStructureMismatch = defineRule({
 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 browserCwd() {
+  return typeof process !== "undefined" && typeof process.cwd === "function" ? process.cwd() : null;
+}
 function codeConnectIsSetUp(context) {
   return getAnalysisState(context, CODE_CONNECT_SETUP_KEY, () => {
-    return existsSync(join(process.cwd(), "figma.config.json"));
+    const cwd = browserCwd();
+    if (cwd === null) return false;
+    return existsSync(join(cwd, "figma.config.json"));
   });
 }
 function codeConnectMappings(context) {
-  return getAnalysisState(
-    context,
-    CODE_CONNECT_MAPPINGS_KEY,
-    () => parseCodeConnectMappings(process.cwd())
-  );
+  return getAnalysisState(context, CODE_CONNECT_MAPPINGS_KEY, () => {
+    const cwd = browserCwd();
+    if (cwd === null) {
+      return {
+        mappedNodeIds: /* @__PURE__ */ new Set(),
+        scannedFiles: [],
+        skipReason: "no-config"
+      };
+    }
+    return parseCodeConnectMappings(cwd);
+  });
 }
 function seenMainIds(context) {
   return getAnalysisState(context, SEEN_MAIN_IDS_KEY, () => /* @__PURE__ */ new Set());