canicode 0.12.1 → 0.12.3

package/dist/cli/index.js

@@ -1408,7 +1408,24 @@ var EVENTS = {
   // has a single place to wire it up.
   ROUNDTRIP_DEFINITION_WRITE_SKIPPED: `${EVENT_PREFIX}roundtrip_definition_write_skipped`,
   /** CLI `canicode roundtrip-tally` completed successfully. */
-  ROUNDTRIP_TALLY: `${EVENT_PREFIX}roundtrip_tally`
+  ROUNDTRIP_TALLY: `${EVENT_PREFIX}roundtrip_tally`,
+  /**
+   * Phase 3 (#508 / ADR-023): `applyComponentize` outcome — either a
+   * successful `createComponentFromNode` call or one of the guard rejections
+   * (instance-child, free-form parent, error) that route to the Strategy C
+   * annotate-fallback. Surfaces under `props.outcome` so a Node-side reader
+   * can split the funnel.
+   */
+  ROUNDTRIP_COMPONENTIZE: `${EVENT_PREFIX}roundtrip_componentize`,
+  /**
+   * Phase 3 (#508 / ADR-023, #554): `applyReplaceWithInstance` outcome —
+   * either a successful instance swap (`outcome: "replaced"`) or one of the
+   * guard rejections (`"skipped-free-form-parent"`, `"skipped-prereq-missing"`,
+   * `"error"`). The primitive pairs with `ROUNDTRIP_COMPONENTIZE` so a
+   * Node-side reader can correlate componentize+swap pairs across a single
+   * Phase 3 batch.
+   */
+  ROUNDTRIP_REPLACE_WITH_INSTANCE: `${EVENT_PREFIX}roundtrip_replace_with_instance`
 };
 
 // src/core/monitoring/capture.ts
@@ -2515,8 +2532,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) => ({
@@ -3297,6 +3314,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",
@@ -3311,7 +3363,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) {
@@ -3339,37 +3392,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);
@@ -3458,6 +3506,7 @@ 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 codeConnectIsSetUp(context) {
   return getAnalysisState(context, CODE_CONNECT_SETUP_KEY, () => {
     return existsSync(join(process.cwd(), "figma.config.json"));
@@ -3470,6 +3519,9 @@ function codeConnectMappings(context) {
     () => parseCodeConnectMappings(process.cwd())
   );
 }
+function seenMainIds(context) {
+  return getAnalysisState(context, SEEN_MAIN_IDS_KEY, () => /* @__PURE__ */ new Set());
+}
 var unmappedComponentDef = {
   id: "unmapped-component",
   name: "Unmapped Component",
@@ -3479,20 +3531,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(node.id)) return null;
-  const ack = context.findAcknowledgment(node.id, unmappedComponentDef.id);
+  if (mappings.mappedNodeIds.has(mainId)) return null;
+  const ack = context.findAcknowledgment(mainId, unmappedComponentDef.id);
   if (ack && isRuleOptOutIntent(ack.intent) && ack.intent.ruleId === unmappedComponentDef.id) {
     return null;
   }
   return {
     ruleId: unmappedComponentDef.id,
-    nodeId: node.id,
+    nodeId: mainId,
     nodePath: context.path.join(" > "),
-    ...unmappedComponentMsg(node.name)
+    ...unmappedComponentMsg(mainName)
   };
 };
 defineRule({
@@ -3966,6 +4031,7 @@ var RuleEngine = class {
       analysisState,
       scope,
       rootNodeType,
+      rootNode,
       void 0,
       void 0
     );
@@ -4002,7 +4068,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;
@@ -4025,6 +4091,7 @@ var RuleEngine = class {
       analysisState,
       scope,
       rootNodeType,
+      analysisRoot,
       findAcknowledgment: (nodeId, ruleId) => acknowledgmentsByKey.get(`${normalizeNodeId(nodeId)}::${ruleId}`)
     };
     for (const rule of rules) {
@@ -4074,6 +4141,7 @@ var RuleEngine = class {
           analysisState,
           scope,
           rootNodeType,
+          analysisRoot,
           node,
           node.children
         );
@@ -4509,7 +4577,7 @@ function computeApplyContext(violation, instanceContext) {
 }
 
 // package.json
-var version2 = "0.12.1";
+var version2 = "0.12.3";
 
 // src/core/engine/scoring.ts
 var GRADE_ORDER = ["S", "A+", "A", "B+", "B", "C+", "C", "D", "F"];
@@ -6535,7 +6603,11 @@ function mapToQuestion(issue, file) {
     ...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 } : {},
+    // #560 / Phase 3 delta 4a: thread groupMembers through from the
+    // violation. Currently only populated by `missing-component`
+    // Stage 3; non-group rules pass undefined and the field is omitted.
+    ...issue.violation.groupMembers !== void 0 ? { groupMembers: issue.violation.groupMembers } : {}
   };
 }
 function deduplicateBySourceComponent(questions) {
@@ -6771,7 +6843,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(),
@@ -7945,7 +8035,7 @@ function runCodeConnectChecks(cwd) {
 }
 var PUBLISH_CHECK_NAME = "Figma component published in a library";
 async function runFigmaPublishCheck(input) {
-  const { figmaUrl, token, fetchPublishedComponents } = input;
+  const { figmaUrl, token, fetchPublishedComponents, fetchNodeType } = input;
   let parsed;
   try {
     parsed = parseFigmaUrl(figmaUrl);
@@ -8011,6 +8101,23 @@ async function runFigmaPublishCheck(input) {
       detail: `${match.name} (${match.node_id})`
     };
   }
+  if (fetchNodeType) {
+    let nodeType;
+    try {
+      nodeType = await fetchNodeType(parsed.fileKey, canonicalNodeId);
+    } catch {
+      nodeType = void 0;
+    }
+    if (nodeType && nodeType !== "COMPONENT" && nodeType !== "COMPONENT_SET") {
+      return {
+        name: PUBLISH_CHECK_NAME,
+        pass: false,
+        inconclusive: true,
+        detail: `node ${canonicalNodeId} is type ${nodeType} \u2014 Code Connect mapping is per-component`,
+        remediation: "Step 7 (Code Connect close-out) skips on screen-level scope anyway. To verify a specific component, re-invoke doctor with that component's URL."
+      };
+    }
+  }
   return {
     name: PUBLISH_CHECK_NAME,
     pass: false,
@@ -8058,7 +8165,11 @@ function registerDoctor(cli2) {
       const publishCheck = await runFigmaPublishCheck({
         figmaUrl: options.figmaUrl,
         token,
-        fetchPublishedComponents: client ? (fileKey) => client.getPublishedComponents(fileKey) : void 0
+        fetchPublishedComponents: client ? (fileKey) => client.getPublishedComponents(fileKey) : void 0,
+        fetchNodeType: client ? async (fileKey, nodeId) => {
+          const response = await client.getFileNodes(fileKey, [nodeId]);
+          return response.nodes[nodeId]?.document.type;
+        } : void 0
       });
       results.push(publishCheck);
     }