canicode 0.12.2 → 0.12.3

package/skills/canicode-roundtrip/helpers.js

@@ -788,6 +788,432 @@ ${footer}`;
     return out;
   }
 
+  // src/core/roundtrip/apply-componentize.ts
+  var COMPONENTIZE_EVENT = "cic_roundtrip_componentize";
+  function isInsideInstance(node) {
+    let current = node.parent;
+    while (current) {
+      if (current.type === "INSTANCE") return true;
+      current = current.parent;
+    }
+    return false;
+  }
+  function isFreeFormParent(node) {
+    const parent = node.parent;
+    if (!parent) return true;
+    const layoutMode = parent["layoutMode"];
+    return layoutMode === void 0 || layoutMode === "NONE";
+  }
+  function resolveFinalName(desired, existing) {
+    if (!existing.has(desired)) {
+      return { finalName: desired, collisionResolved: false };
+    }
+    let counter = 2;
+    while (existing.has(`${desired} ${counter}`)) counter++;
+    return { finalName: `${desired} ${counter}`, collisionResolved: true };
+  }
+  function annotateFallback(node, ruleId, categories, body) {
+    if (!categories) return;
+    upsertCanicodeAnnotation(node, {
+      ruleId,
+      markdown: body,
+      categoryId: categories.flag
+    });
+  }
+  function applyComponentize(options) {
+    const { node, existingComponentNames, ruleId, categories, telemetry } = options;
+    if (isInsideInstance(node)) {
+      annotateFallback(
+        node,
+        ruleId,
+        categories,
+        `**Componentize skipped \u2014 node is inside an INSTANCE subtree.**
+
+Re-running ${ruleId} componentize on a node inside an instance would either throw or destructively detach the surrounding instance (see roundtrip-protocol.md:286). Move the source frame outside the instance, or detach the parent instance intentionally before componentizing.`
+      );
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "skipped-inside-instance"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "componentize skipped: inside instance",
+        outcome: "skipped-inside-instance"
+      };
+    }
+    if (isFreeFormParent(node)) {
+      annotateFallback(
+        node,
+        ruleId,
+        categories,
+        `**Componentize skipped \u2014 parent has no Auto Layout.**
+
+Componentizing and swapping siblings under a free-form parent would require manual coordinate carryover that can mangle layout silently (ADR-023 decision A). Wrap the duplicates in an Auto Layout frame first, then re-run the roundtrip.`
+      );
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "skipped-free-form-parent"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "componentize skipped: free-form parent",
+        outcome: "skipped-free-form-parent"
+      };
+    }
+    const desiredName = typeof node.name === "string" ? node.name : "Component";
+    const { finalName, collisionResolved } = resolveFinalName(
+      desiredName,
+      existingComponentNames
+    );
+    const create = figma.createComponentFromNode;
+    if (typeof create !== "function") {
+      annotateFallback(
+        node,
+        ruleId,
+        categories,
+        `**Componentize skipped \u2014 \`figma.createComponentFromNode\` unavailable.**
+
+The Plugin API host did not expose the Create component primitive in this session. The FRAME has been flagged so the next roundtrip can retry.`
+      );
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "error",
+        reason: "createComponentFromNode-missing"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "componentize skipped: createComponentFromNode unavailable",
+        outcome: "error"
+      };
+    }
+    try {
+      const created = create.call(figma, node);
+      created.name = finalName;
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "componentized",
+        nameCollisionResolved: collisionResolved
+      });
+      const result = {
+        icon: "\u2705",
+        label: collisionResolved ? `componentized as "${finalName}" (renamed from collision)` : `componentized as "${finalName}"`,
+        outcome: "componentized",
+        newComponentId: created.id,
+        finalName
+      };
+      if (collisionResolved) result.nameCollisionResolved = true;
+      return result;
+    } catch (e) {
+      const msg = String(e?.message ?? e);
+      annotateFallback(
+        node,
+        ruleId,
+        categories,
+        `**Componentize failed \u2014 \`createComponentFromNode\` threw.**
+
+Error: \`${msg}\`. The FRAME has been flagged so the designer can inspect the structure (locked layer, unsupported child mix, etc.) before the next roundtrip pass.`
+      );
+      telemetry?.(COMPONENTIZE_EVENT, {
+        ruleId,
+        outcome: "error",
+        reason: msg
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `componentize failed: ${msg}`,
+        outcome: "error"
+      };
+    }
+  }
+
+  // src/core/roundtrip/apply-replace-with-instance.ts
+  var REPLACE_EVENT = "cic_roundtrip_replace_with_instance";
+  function isFreeFormParent2(parent) {
+    if (!parent) return true;
+    const layoutMode = parent["layoutMode"];
+    return layoutMode === void 0 || layoutMode === "NONE";
+  }
+  function annotateFallback2(node, ruleId, categories, body) {
+    if (!node || !categories) return;
+    upsertCanicodeAnnotation(node, {
+      ruleId,
+      markdown: body,
+      categoryId: categories.flag
+    });
+  }
+  function isComponentLike(type) {
+    return type === "COMPONENT" || type === "COMPONENT_SET";
+  }
+  async function applyReplaceWithInstance(options) {
+    const { mainComponentId, targetNodeId, ruleId, categories, telemetry } = options;
+    const [target, main] = await Promise.all([
+      figma.getNodeByIdAsync(targetNodeId),
+      figma.getNodeByIdAsync(mainComponentId)
+    ]);
+    if (!target) {
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "target-missing"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `replace skipped: target node ${targetNodeId} missing`,
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    if (!main) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 main component \`${mainComponentId}\` not found.**
+
+The componentize step (delta 1) likely failed earlier in this batch, or the main was deleted between componentize and swap. The FRAME has been flagged so the next roundtrip pass can re-derive the group.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "main-missing"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `replace skipped: main ${mainComponentId} missing`,
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    if (!isComponentLike(main.type)) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 \`${mainComponentId}\` is not a COMPONENT.**
+
+Resolved to a \`${main.type}\` node. Phase 3's swap step requires the main to be a \`COMPONENT\` or \`COMPONENT_SET\`. Check that componentize ran cleanly on the source frame before this call.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "main-not-component",
+        resolvedType: main.type
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `replace skipped: main is ${main.type}, not COMPONENT`,
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    if (target.id === main.id) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 target and main are the same node.**
+
+This usually means the componentize source was passed in the swap set by mistake. The componentize source becomes the main; only the remaining sibling FRAMEs should be swapped.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "target-is-main"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "replace skipped: target equals main",
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    const parent = target.parent;
+    if (!parent) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 target has no parent.**
+
+Cannot insert a new instance for an orphaned node. The FRAME has been flagged; no swap performed.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-prereq-missing",
+        reason: "no-parent"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "replace skipped: no parent",
+        outcome: "skipped-prereq-missing"
+      };
+    }
+    if (isFreeFormParent2(parent)) {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 parent has no Auto Layout.**
+
+Swapping a sibling FRAME with an instance under a free-form parent would require explicit coordinate carryover that can mangle layout silently (ADR-023 decision A). Wrap the duplicates in an Auto Layout frame first, then re-run the roundtrip.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "skipped-free-form-parent"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "replace skipped: free-form parent",
+        outcome: "skipped-free-form-parent"
+      };
+    }
+    const create = main.createInstance;
+    if (typeof create !== "function") {
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace skipped \u2014 \`createInstance\` unavailable on main.**
+
+The Plugin API host did not expose \`createInstance\` on the resolved main (\`${main.type}\`). The FRAME has been flagged so the next roundtrip can retry once the host catches up.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "error",
+        reason: "createInstance-missing"
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: "replace skipped: createInstance unavailable",
+        outcome: "error"
+      };
+    }
+    try {
+      const instance = create.call(main);
+      const siblings = parent.children ?? [];
+      const idx = siblings.findIndex((s) => s.id === target.id);
+      const insert = parent.insertChild;
+      const append = parent.appendChild;
+      if (idx >= 0 && typeof insert === "function") {
+        insert.call(parent, idx, instance);
+      } else if (typeof append === "function") {
+        append.call(parent, instance);
+      } else {
+        throw new Error(
+          "parent exposes neither insertChild nor appendChild \u2014 cannot insert instance"
+        );
+      }
+      if (typeof target.remove === "function") {
+        target.remove();
+      } else {
+        throw new Error("target node missing `remove` \u2014 cannot detach old FRAME");
+      }
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "replaced"
+      });
+      return {
+        icon: "\u2705",
+        label: `replaced with instance of "${main.name}"`,
+        outcome: "replaced",
+        newInstanceId: instance.id
+      };
+    } catch (e) {
+      const msg = String(e?.message ?? e);
+      annotateFallback2(
+        target,
+        ruleId,
+        categories,
+        `**Replace failed \u2014 Plugin API threw.**
+
+Error: \`${msg}\`. The FRAME has been flagged so the designer can inspect (locked layer, parent restrictions, etc.) before the next roundtrip pass.`
+      );
+      telemetry?.(REPLACE_EVENT, {
+        ruleId,
+        outcome: "error",
+        reason: msg
+      });
+      return {
+        icon: "\u{1F4DD}",
+        label: `replace failed: ${msg}`,
+        outcome: "error"
+      };
+    }
+  }
+
+  // src/core/roundtrip/apply-group-componentize.ts
+  function summarizeReplaceCounts(results) {
+    const total = results.length;
+    if (total === 0) return "";
+    const replaced = results.filter((r) => r.outcome === "replaced").length;
+    const reasons = [];
+    const freeForm = results.filter(
+      (r) => r.outcome === "skipped-free-form-parent"
+    ).length;
+    const prereq = results.filter(
+      (r) => r.outcome === "skipped-prereq-missing"
+    ).length;
+    const error = results.filter((r) => r.outcome === "error").length;
+    if (freeForm > 0) reasons.push(`${freeForm} free-form parent`);
+    if (prereq > 0) reasons.push(`${prereq} prereq missing`);
+    if (error > 0) reasons.push(`${error} error`);
+    const tail = reasons.length > 0 ? ` (${reasons.join(", ")})` : "";
+    return `swapped ${replaced}/${total} siblings${tail}`;
+  }
+  async function applyGroupComponentize(options) {
+    const { question, existingComponentNames, categories, telemetry } = options;
+    const members = question.groupMembers;
+    const firstId = members[0];
+    if (firstId === void 0) {
+      return {
+        outcome: "missing-first-member",
+        replaceResults: [],
+        summary: "group componentize skipped: no members in group"
+      };
+    }
+    const firstNode = await figma.getNodeByIdAsync(firstId);
+    if (!firstNode) {
+      return {
+        outcome: "missing-first-member",
+        replaceResults: [],
+        summary: `group componentize skipped: first member ${firstId} not found`
+      };
+    }
+    const componentizeResult = applyComponentize({
+      node: firstNode,
+      existingComponentNames,
+      ruleId: question.ruleId,
+      ...categories !== void 0 ? { categories } : {},
+      ...telemetry !== void 0 ? { telemetry } : {}
+    });
+    if (componentizeResult.outcome !== "componentized") {
+      return {
+        outcome: "componentize-failed",
+        componentizeResult,
+        replaceResults: [],
+        summary: `group componentize skipped: ${componentizeResult.label}`
+      };
+    }
+    const newComponentId = componentizeResult.newComponentId;
+    const swapTargets = members.slice(1);
+    const replaceResults = [];
+    for (const targetId of swapTargets) {
+      const r = await applyReplaceWithInstance({
+        mainComponentId: newComponentId,
+        targetNodeId: targetId,
+        ruleId: question.ruleId,
+        ...categories !== void 0 ? { categories } : {},
+        ...telemetry !== void 0 ? { telemetry } : {}
+      });
+      replaceResults.push(r);
+    }
+    const swapSummary = summarizeReplaceCounts(replaceResults);
+    const finalName = componentizeResult.finalName ?? "(unnamed)";
+    const summary = swapSummary.length > 0 ? `componentized "${finalName}", ${swapSummary}` : `componentized "${finalName}"`;
+    return {
+      outcome: "componentized-and-swapped",
+      componentizeResult,
+      replaceResults,
+      summary
+    };
+  }
+
   // src/core/roundtrip/remove-canicode-annotations.ts
   var LEGACY_CANICODE_PREFIX = "**[canicode]";
   function isCanicodeAnnotation(annotation, categories) {
@@ -813,7 +1239,10 @@ ${footer}`;
 
   exports.applyAutoFix = applyAutoFix;
   exports.applyAutoFixes = applyAutoFixes;
+  exports.applyComponentize = applyComponentize;
+  exports.applyGroupComponentize = applyGroupComponentize;
   exports.applyPropertyMod = applyPropertyMod;
+  exports.applyReplaceWithInstance = applyReplaceWithInstance;
   exports.applyUnmappedComponentOptOut = applyUnmappedComponentOptOut;
   exports.applyWithInstanceFallback = applyWithInstanceFallback;
   exports.buildIntentionallyUnmappedAnnotationBody = buildIntentionallyUnmappedAnnotationBody;

package/skills/cursor/canicode-roundtrip/SKILL.md

@@ -261,6 +261,92 @@ The name must match **the variable's `name` field exactly** — including any sl
 
 Instance-child guard and per-rule prompts — **[Appendix Strategy B](https://github.com/let-sunny/canicode/blob/main/docs/roundtrip-protocol.md#appendix--strategy-b-structural-modification)**. Decline / guard → Strategy C annotation.
 
+##### Strategy B group componentize — Phase 3 (`missing-component:structure-repetition`)
+
+When `applyStrategy === "structural-mod"` AND `question.ruleId === "missing-component"` AND `question.subType === "structure-repetition"` AND `question.groupMembers` is set, the question represents a fingerprint group of N FRAMEs the user can componentize-and-swap in one batch. The group spans both same-parent siblings and cross-parent matches found by the Stage 3 scope-wide pass (#557). Render the per-question prompt with the **group size** explicitly so the designer knows the scope before answering. Substitute `{nodeName}` with `question.nodeName` and `{others}` with `question.groupMembers.length - 1` (the count excluding the first member that becomes the new component); render in the user's session language:
+
+- Korean: `> "{nodeName}" 외에 동일한 구조의 frame이 {others}개 더 있습니다 (총 {others + 1}개). 모두 컴포넌트화 할까요? (yes/no)`
+- English: `> "{nodeName}" and {others} other frame(s) share the same structure ({others + 1} total). Componentize the whole group? (yes/no)`
+
+On `yes`, compute the file-wide existing component name set once (decision C uses this for the suffix), then call the group orchestrator. On `no` / `skip`, drop the question without writing anything; the gotcha state is captured in the SKILL's section markdown either way.
+
+<!-- adr-016-ack: existingComponentNames computed via figma.root API; orchestration loop lives in applyGroupComponentize -->
+```javascript
+const existingComponentNames = new Set(
+  figma.root
+    .findAllWithCriteria({ types: ["COMPONENT", "COMPONENT_SET"] })
+    .map((c) => c.name)
+);
+const result = await CanICodeRoundtrip.applyGroupComponentize({
+  question: { ruleId: question.ruleId, groupMembers: question.groupMembers },
+  existingComponentNames,
+  categories,
+});
+// result.summary — e.g. `componentized "Card", swapped 3/4 siblings (1 free-form parent)`
+// result.outcome — `componentized-and-swapped` | `componentize-failed` | `missing-first-member`
+//
+// Step 4 report counter mapping (bump ONCE per primitive call, not once per
+// outcome bucket — counters track work performed, not aggregate verdicts):
+//   componentize step:
+//     componentizeResult.outcome === "componentized" → resolved (+1)
+//     componentizeResult.outcome === "skipped-*" or "error" → annotated (+1)
+//   each replace step (iterate result.replaceResults):
+//     replaceResult.outcome === "replaced" → resolved (+1)
+//     replaceResult.outcome === "skipped-*" or "error" → annotated (+1)
+//   missing-first-member → skipped (+1) and no further bumps
+```
+
+Notes:
+- **Free-form parents are refused per ADR-023 decision A.** When the group's parent (or any swap-target's parent) has no Auto Layout, the relevant primitive annotates the source FRAME with a "wrap in Auto Layout first" hint and skips the write. The summary string surfaces the count (`(1 free-form parent)`) so the designer sees the partial outcome at a glance.
+- **Name collision auto-suffixes per ADR-023 decision C** (`Card 2`, `Card 3`, …). The orchestrator passes `existingComponentNames` to the componentize step which resolves the suffix and reports the rename in `result.componentizeResult.finalName`.
+- **Per-member opt-out is not yet wired** — the orchestrator treats `groupMembers` as canonical. If the designer wants to exclude a specific member, that is currently a manual pre-edit (delete the entry from the question payload before calling) or a follow-up enhancement.
+- **No replica fan-out.** Stage 3 questions never carry `replicaNodeIds` (the `#356` instance-child dedupe applies to single-node violations, not group-shaped ones). Iterate `groupMembers` instead.
+
+###### Code Connect handoff for the new component (Phase 3 delta 5, optional)
+
+When `result.outcome === "componentized-and-swapped"` AND `result.componentizeResult.newComponentId` is set, the new component is a candidate for a Code Connect mapping so future roundtrips reuse the just-generated code instead of regenerating markup. This mirrors the Workflow 1 (#509) Step 7 close-out — same pre-check, same MCP tools, just sharing the closing question.
+
+Per ADR-023 decision E this is **silent skip + one-line pointer** when prereqs are absent — Phase 3 does not own onboarding (Workflow 1 / #509 does). The check is the same `npx canicode doctor --figma-url <url>` already run at Step 1.5 (`prereqs.codeConnectReady` cached on the session) — do **not** re-run doctor here. If prereqs were missing, surface ONE line and move on:
+
+> Code Connect 미설정이라 매핑 단계는 건너뜁니다. Workflow 1 (`/canicode-roundtrip <component-url>`)로 setup하면 다음부터 자동 매핑됩니다.
+
+(English: `> Code Connect not configured — skipping mapping. Run Workflow 1 (\`/canicode-roundtrip <component-url>\`) to set it up; subsequent roundtrips map automatically.`)
+
+When prereqs are ready, ask the satisfaction prompt and, on `yes`, register the mapping:
+
+```javascript
+// 1. Probe the just-componentized main for an existing mapping (idempotency)
+const existing = await mcp__figma__get_code_connect_map({
+  componentId: result.componentizeResult.newComponentId,
+});
+if (existing) {
+  // Already mapped — surface and move on. Do not overwrite without consent.
+  return;
+}
+
+// 2. Ask the user (one line, in session language)
+//    Korean: "이 새 component를 Code Connect 매핑으로 등록할까요? (yes/no)"
+//    English: "Register this new component with Code Connect? (yes/no)"
+
+// 3. On yes, fetch suggestions and register the user's choice
+const suggestions = await mcp__figma__get_code_connect_suggestions({
+  componentId: result.componentizeResult.newComponentId,
+  componentName: result.componentizeResult.finalName,
+});
+// Render suggestions to the user; on confirmation:
+await mcp__figma__add_code_connect_map({
+  componentId: result.componentizeResult.newComponentId,
+  codePath: chosenSuggestion.path,        // e.g. "src/components/Card.tsx"
+  codeName: chosenSuggestion.exportName,  // e.g. "Card"
+});
+await mcp__figma__send_code_connect_mappings();
+```
+
+Notes:
+- **Inherits Step 1.5 prereq check.** Do not re-invoke `canicode doctor` — the cached result from Step 1.5 already covers `figma.config.json` + `@figma/code-connect` install + Figma publish status. Skipping the re-check keeps the close-out fast and avoids a second Figma round-trip.
+- **No suggestions match → still surface the option.** When `get_code_connect_suggestions` returns empty, ask the user for a manual `codePath` + `codeName` (one prompt, optional). Skipping is always valid — the new component remains unmapped and Workflow 1 can register it later.
+- **Wraps the Step 4 apply line** with one extra outcome marker: `+ Code Connect: Card → src/components/Card.tsx` on success, `+ Code Connect: skipped (prereq missing)` or `+ Code Connect: skipped (user declined)` on the two skip paths. Counts as part of the Phase 3 group's overall result for Step 5 tally — no new counter, just an annotation appended to the existing line.
+
 #### Strategy C: Annotation — record on the design for designer reference
 
 Rules with `applyStrategy === "annotation"` cannot be auto-fixed via Plugin API. Add the gotcha answer as a Figma annotation so designers see it in Dev Mode. Use the helper — it handles the D1 mutex, D2 in-place upsert, and D4 category assignment. When `question.replicaNodeIds` is present (#356), iterate the merged set so every replica instance gets the annotation:

package/skills/cursor/canicode-roundtrip/helpers-bootstrap.js

@@ -6,7 +6,7 @@
 // globalThis.__canicodeBootstrapResult and throws ReferenceError so the agent re-prepends the
 // installer on the next batch.
 (function __canicodeBootstrap() {
-  var expected = "0.12.2";
+  var expected = "0.12.3";
   var src = figma.root.getSharedPluginData("canicode", "helpersSrc");
   var actual = figma.root.getSharedPluginData("canicode", "helpersVersion");
   if (!src) {