@yschimke/compose-design-map 1.44.0 → 1.46.0

package/design-map.mjs

@@ -68,9 +68,37 @@ const LIGHT_MODE = "Light";
 /** The tag discovery puts in the id of an `@OverrideVariant` reseed: `…_VARIANT_<name>`. */
 const VARIANT_TAG = "_VARIANT_";
 
+/**
+ * The head of a capture's id with the `_VARIANT_<name>` reseed suffix removed, and whether there
+ * was one — `{ head, reseed }`.
+ *
+ * `_VARIANT_` is a legal substring of a Kotlin function name, so a plain `includes()` read the BASE
+ * capture of a composable called `Icon_VARIANT_Only` as a generated reseed. Every `continue` guarded
+ * by that test then dropped the composable outright, including its explicit `noReference` — a
+ * record whose whole purpose is to survive into the diagnostics.
+ *
+ * Discovery appends the tag to the id it has already built (`base.id + "_VARIANT_<name>"`), so the
+ * marker of an actual reseed is the LAST one and the function's own name is still in front of it.
+ * Splitting there and requiring the `.<functionName>` marker to survive in the head distinguishes
+ * the two: `…FooKt.Icon_VARIANT_Only_Light` splits to `…FooKt.Icon`, which no longer contains
+ * `.Icon_VARIANT_Only`, so it is a base capture; a real reseed of `Icon`,
+ * `…FooKt.Icon_Light_VARIANT_pressed`, splits to `…FooKt.Icon_Light`, which still contains `.Icon`.
+ *
+ * A capture that names no function cannot be told apart this way, so it keeps the old reading.
+ */
+function splitVariantTag(preview) {
+  const id = String(preview.id ?? "");
+  const at = id.lastIndexOf(VARIANT_TAG);
+  if (at < 0) return { head: id, reseed: false };
+  const head = id.slice(0, at);
+  const marker = preview.functionName ? `.${preview.functionName}` : null;
+  if (marker && !head.includes(marker)) return { head: id, reseed: false };
+  return { head, reseed: true };
+}
+
 /** Whether a capture is an `@OverrideVariant` reseed rather than a base capture. */
 function isVariantCapture(preview) {
-  return String(preview.id ?? "").includes(VARIANT_TAG);
+  return splitVariantTag(preview).reseed;
 }
 
 /**
@@ -80,13 +108,14 @@ function isVariantCapture(preview) {
  * is the `@Preview` name a multipreview gives the capture — `Light` / `Dark` for a themed pair, and
  * EMPTY for an unnamed single capture. Splitting on the function name rather than pattern-matching
  * the tail is what lets a dark-first catalog be recognised at all: its ids carry no mode segment to
- * match against.
+ * match against. The reseed suffix comes off first, via [splitVariantTag] rather than a bare
+ * substring split, so a function whose own name contains `_VARIANT_` keeps its whole identity.
  *
  * A capture whose id does not contain its own function name is left as its own subject with an
  * empty mode — it cannot be grouped with anything, so it selects itself.
  */
 export function captureIdentity(preview) {
-  const head = String(preview.id ?? "").split(VARIANT_TAG)[0];
+  const { head } = splitVariantTag(preview);
   const marker = preview.functionName ? `.${preview.functionName}` : null;
   const at = marker ? head.lastIndexOf(marker) : -1;
   if (at < 0) return { subject: head, mode: "" };
@@ -408,6 +437,33 @@ export function variantSeeds(preview) {
 }
 
 /** The name a variant render goes by, for a report and for the design-map `state` slot. */
+/**
+ * How a folded variant names itself in the reference diagnostics: `<parentId> [<axis>=<value> …]`.
+ *
+ * Not the bare `componentId` — that is the PARENT's id for a VARIANT role, so reporting a variant's
+ * stated absence under it would read as a finding about a parent that may carry a perfectly good
+ * reference.
+ *
+ * Not [variantName] either, though that is what the variant is called elsewhere: it narrows to the
+ * `state` alone whenever there is one, so two variants of a parent sharing a state and differing
+ * only in `props` produce the SAME name. These labels are map keys, so a collision silently drops
+ * one of the two stated absences — losing exactly the record this diagnostic exists to keep. The
+ * full seed vector is what distinguishes them, so the label is built from that.
+ */
+export function variantAbsenceId(preview) {
+  const parent = preview.catalog?.componentId ?? "(unnamed)";
+  const axes = variantSeeds(preview)
+    .map((seed) => `${seed.key}=${seed.raw}`)
+    .join(" ");
+  // `state` and `props` are both optional, so a variant CAN declare `noReference` and name no axis
+  // at all. Falling back to the bare parent id then publishes "Button — <reason>" for a parent that
+  // may hold a perfectly good reference: it reads as a finding about the parent, and says nothing
+  // about which variant the reason belongs to. The function name is what distinguishes such a
+  // variant, so it stands in for the axes it did not give.
+  const label = axes || preview.functionName || captureIdentity(preview).subject;
+  return label ? `${parent} [${label}]` : parent;
+}
+
 function variantName(preview, seeds) {
   const catalog = preview.catalog;
   const cell = preview.overrides?.name;
@@ -492,8 +548,28 @@ export function variantRendersByComponent(previews, selection = selectCaptures(p
     const seeds = variantSeeds(preview);
     if (!seeds.length) continue;
 
+    // A `@CatalogVariant` may state its OWN kit correspondence, and either spelling changes what a
+    // resolver should do with this render. Without reading them here a variant's declaration is
+    // emitted under the parent's `reference` regardless — which is precisely the mispairing the two
+    // fields were added to prevent.
+    //
+    // `noReference` says the kit exports no cell this render could honestly pair with. Handing it
+    // to the resolver anyway scores it against the PARENT's picture, so it is dropped: the absence
+    // is already reported once, as a stated absence, and a render that says "there is nothing to
+    // compare me to" must not then be compared.
+    if (isCatalogVariant && catalog.noReference) continue;
+
     const list = byComponent.get(catalog.componentId) ?? [];
-    list.push({ previewId: preview.id, name: variantName(preview, seeds), seeds });
+    list.push({
+      previewId: preview.id,
+      name: variantName(preview, seeds),
+      seeds,
+      // `reference` names the variant's own kit cell. Carried onto the render so a resolver pairs
+      // that handle instead of deriving one from the parent's by seed. Additive to the sidecar's
+      // shape — a resolver that does not read it sees exactly what it saw before, which is why the
+      // schema string does not move.
+      ...(isCatalogVariant && catalog.reference ? { reference: catalog.reference } : {}),
+    });
     byComponent.set(catalog.componentId, list);
   }
   return byComponent;
@@ -529,29 +605,87 @@ export function projectDesignMap(previews, opts = {}) {
    * however many captures it publishes.
    */
   const unmappedIds = new Map();
+  /**
+   * Stated absences, keyed by a COLLISION-SAFE identity and carrying the display label separately.
+   *
+   * A component keys on its own id and a variant on its capture subject, each behind its own
+   * prefix. Both are free-form strings from different namespaces — a `@CatalogComponent(id = …)`
+   * may legally be spelled like a capture subject — so sharing one map without tagging the domain
+   * is the same collision one namespace over. Never keyed on the rendered label. The label is built by joining `key=value` pairs, and
+   * discovery splits an annotation prop at its FIRST `=` only, so a value may legally contain both
+   * a space and an `=`: `props = ["a=b c=d"]` is one prop, and renders identically to the two props
+   * `a=b` and `c=d`. Keying on that string would silently drop one of two distinct absences — the
+   * same data loss this diagnostic exists to prevent, one level subtler.
+   */
   const statedAbsentIds = new Map();
+  /** Capture subjects whose absence is stated — a variant is named by subject, not by component. */
+  const referencelessSubjects = new Set();
+  /** Component ids whose absence is stated, for the componentId-keyed ambiguity filter below. */
+  const statedAbsentComponentIds = new Set();
   for (const preview of previews) {
     const catalog = preview.catalog;
-    if (!catalog || catalog.role !== "COMPONENT" || catalog.reference) continue;
+    if (!catalog || catalog.reference) continue;
     if (isVariantCapture(preview)) continue;
+    // A `@CatalogVariant` can now state its own kit correspondence, so its absence is reported
+    // like a component's. Scanning components alone meant folding a render under a parent silently
+    // dropped its stated absence from this accounting — a catalog could lose an audit signal by
+    // restructuring, which is exactly what `statedAbsent` exists to prevent. `--strict` counts a
+    // variant's stated absence the same as a component's: someone looked, and wrote down what they
+    // found, wherever the render sits.
+    //
+    // Reported under the variant's own label, not its parent's id (`componentId` is the PARENT for
+    // a VARIANT), or a folded variant's reason would be reported against a parent that may have a
+    // perfectly good reference of its own. The label is for reading; the KEY is the capture
+    // subject, which cannot collide — see the map's own note above.
+    if (catalog.role === "VARIANT") {
+      if (!catalog.noReference) continue; // silence under a parent is the parent's business
+      const subject = captureIdentity(preview).subject;
+      statedAbsentIds.set(`subject:${subject}`, {
+        label: variantAbsenceId(preview),
+        reason: catalog.noReference,
+      });
+      // The ambiguity filter below matches on componentId, which for a VARIANT is the PARENT's --
+      // so a variant's own stated absence could not suppress its own ambiguous-mode record, and a
+      // parent carrying a good reference left it unsuppressed. `--strict --allow-stated-absence`
+      // then failed on precisely the case that flag exists to accept. A variant render has its own
+      // capture subject, so record that instead of trying to name it by component.
+      referencelessSubjects.add(subject);
+      continue;
+    }
+    if (catalog.role !== "COMPONENT") continue;
     const id = catalog.componentId;
-    if (catalog.noReference) statedAbsentIds.set(id, catalog.noReference);
-    else if (!statedAbsentIds.has(id)) unmappedIds.set(id, true);
+    if (catalog.noReference) {
+      statedAbsentIds.set(`component:${id}`, { label: id, reason: catalog.noReference });
+      statedAbsentComponentIds.add(id);
+      // Unconditional: [unmapped] below filters this set through [statedAbsentComponentIds], which
+      // is the only correct place for it — a component's stated absence may be read from a LATER
+      // capture than the one that first reports it unmapped, and a guard here can only see what has
+      // been read so far. The guard that used to stand here tested a bare `id` against a map now
+      // keyed `component:<id>` / `subject:<id>`, so for an ordinary id it never matched, and for a
+      // component legally named `component:X` it matched the wrong entry and dropped it from
+      // `unmapped` — letting `--strict` pass over a component with no reference and no reason.
+    } else unmappedIds.set(id, true);
   }
   /** Components carrying neither a reference nor a stated reason for its absence. */
-  const unmapped = [...unmappedIds.keys()].filter((id) => !statedAbsentIds.has(id));
+  const unmapped = [...unmappedIds.keys()].filter((id) => !statedAbsentComponentIds.has(id));
   /**
    * Components whose reference is absent for a STATED reason. Reported apart from `unmapped`
    * because they are the opposite situation: someone looked, and what they found is that the kit
    * has nothing live to point at. Rolling the two together is what made a retired pattern read as
    * neglect.
    */
-  const statedAbsent = [...statedAbsentIds].map(([componentId, reason]) => ({
-    componentId,
+  const statedAbsent = [...statedAbsentIds.values()].map(({ label, reason }) => ({
+    componentId: label,
     reason,
   }));
-  /** Every component that reaches no reference, however its absence was spelled. */
-  const referencelessIds = new Set([...unmapped, ...statedAbsentIds.keys()]);
+  /**
+   * Every COMPONENT that reaches no reference, however its absence was spelled — the set the
+   * ambiguity filter tests `componentIds` against. A variant's key is a capture subject rather than
+   * a component id, so it is deliberately absent here and suppressed through
+   * [referencelessSubjects] instead; putting subjects in this set would only add entries no
+   * componentId can ever equal.
+   */
+  const referencelessIds = new Set([...unmapped, ...statedAbsentComponentIds]);
 
   for (const preview of previews) {
     const catalog = preview.catalog;
@@ -614,7 +748,9 @@ export function projectDesignMap(previews, opts = {}) {
       // absence already reported above, and under --strict it would be a second, unfixable failure
       // for the same component.
       ambiguousMode: selection.ambiguous.filter(
-        (a) => !a.componentIds.length || a.componentIds.some((id) => !referencelessIds.has(id)),
+        (a) =>
+          !referencelessSubjects.has(a.subject) &&
+          (!a.componentIds.length || a.componentIds.some((id) => !referencelessIds.has(id))),
       ),
       variantRenders: declarations.reduce((n, d) => n + d.renders.length, 0),
       withSet: components.filter((c) => c.refSet).length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yschimke/compose-design-map",
-  "version": "1.44.0",
+  "version": "1.46.0",
   "description": "Project a compose-preview discovery manifest into design-parity's design-map.json, plus a sidecar of unresolved variant declarations. Dependency-free.",
   "license": "Apache-2.0",
   "type": "module",