@yschimke/compose-design-map 1.44.0 → 1.45.0

package/design-map.mjs

@@ -408,6 +408,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;
@@ -529,29 +556,80 @@ 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);
+    } else if (!statedAbsentIds.has(id)) 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 +692,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.45.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",