@yschimke/compose-design-map 1.18.0 → 1.19.0

package/design-map.mjs

@@ -406,29 +406,50 @@ export function projectDesignMap(previews, opts = {}) {
 
   const components = [];
   const declarations = [];
+  /**
+   * Whether a component reaches a design reference at all, and what it said if not.
+   *
+   * Read from the ANNOTATIONS, before and independently of capture selection — which is the whole
+   * point. A component publishing several modes with no Light among them is `ambiguousMode`, and
+   * `participates()` is false for every one of its captures; computing absence inside the capture
+   * loop therefore dropped such a component out of `unmapped` / `statedAbsent` entirely and
+   * reported it only as an ambiguous mode. A stated absence would then be fatal under
+   * `--strict --allow-stated-absence`, which is exactly the case that flag exists to accept.
+   *
+   * Keyed by componentId rather than pushed per preview, because a component's absence is one fact
+   * however many captures it publishes.
+   */
+  const unmappedIds = new Map();
+  const statedAbsentIds = new Map();
+  for (const preview of previews) {
+    const catalog = preview.catalog;
+    if (!catalog || catalog.role !== "COMPONENT" || catalog.reference) continue;
+    if (isVariantCapture(preview)) continue;
+    const id = catalog.componentId;
+    if (catalog.noReference) statedAbsentIds.set(id, catalog.noReference);
+    else if (!statedAbsentIds.has(id)) unmappedIds.set(id, true);
+  }
   /** Components carrying neither a reference nor a stated reason for its absence. */
-  const unmapped = [];
+  const unmapped = [...unmappedIds.keys()].filter((id) => !statedAbsentIds.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 = [];
+  const statedAbsent = [...statedAbsentIds].map(([componentId, reason]) => ({
+    componentId,
+    reason,
+  }));
+  /** Every component that reaches no reference, however its absence was spelled. */
+  const referencelessIds = new Set([...unmapped, ...statedAbsentIds.keys()]);
 
   for (const preview of previews) {
     const catalog = preview.catalog;
     if (!catalog || catalog.role !== "COMPONENT") continue;
     if (isVariantCapture(preview) || !selection.participates(preview)) continue;
 
-    if (!catalog.reference) {
-      if (catalog.noReference) {
-        statedAbsent.push({ componentId: catalog.componentId, reason: catalog.noReference });
-      } else {
-        unmapped.push(catalog.componentId);
-      }
-      continue;
-    }
+    if (!catalog.reference) continue;
 
     const code = codeHandle(preview, opts);
     components.push({
@@ -478,7 +499,14 @@ export function projectDesignMap(previews, opts = {}) {
       // Composables whose captures name no mode a reference could pair with — several modes, none
       // of them light. Reported rather than guessed at: pairing `Dark` when the kit drew `Coral`
       // diffs a whole palette.
-      ambiguousMode: selection.ambiguous,
+      // An ambiguous mode is only ever a problem BECAUSE a reference needs one capture to pair
+      // with. A component that reaches no reference has nothing to pair, so which of its captures
+      // the kit drew is not a question anyone is asking — reporting it would be noise on top of the
+      // 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)),
+      ),
       variantRenders: declarations.reduce((n, d) => n + d.renders.length, 0),
       withSet: components.filter((c) => c.refSet).length,
     },

package/emit-design-map.mjs

@@ -4,7 +4,7 @@
  *
  *     npx @yschimke/compose-design-map [--previews <path>] [--out design-map.json]
  *                                      [--variants design-map-variants.json] [--prefix catalog]
- *                                      [--check] [--strict]
+ *                                      [--check] [--strict] [--allow-stated-absence]
  *
  * Run `./gradlew :<module>:composePreviewDiscover` first so the manifest exists.
  *
@@ -32,6 +32,14 @@
  * whose captures name no mode the reference could pair with. The annotation still earns its keep in
  * the default mode, where the three are reported apart so a retired pattern does not read as
  * neglect; `--strict` simply says there are no exceptions.
+ *
+ * `--allow-stated-absence` narrows `--strict` back to what it is usually wanted for: it still fails
+ * on a missing `reference` and on an ambiguous mode, but accepts a component whose absence a
+ * `noReference` explains. That is the posture of a catalog with two doors — one for the components
+ * that reproduce a kit set, one for the components of its own library the kit never published —
+ * where an exception is a fact about the kit rather than a gap. Without it such a catalog has to
+ * drop `--strict` altogether and loses the guard against silence as well. No effect without
+ * `--strict`.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -51,6 +59,7 @@ const VARIANTS_OUT = arg("variants", "design-map-variants.json");
 const PREFIX = arg("prefix", "catalog");
 const CHECK = process.argv.includes("--check");
 const STRICT = process.argv.includes("--strict");
+const ALLOW_STATED_ABSENCE = process.argv.includes("--allow-stated-absence");
 
 if (!fs.existsSync(PREVIEWS)) {
   console.error(
@@ -71,7 +80,16 @@ const { map, variants, diagnostics } = projectDesignMap(manifest.previews ?? [],
 if (STRICT) {
   const missing = [
     ...diagnostics.unmapped.map((id) => `${id} — no reference, and no reason given`),
-    ...diagnostics.statedAbsent.map((s) => `${s.componentId} — ${s.reason}`),
+    // A STATED absence is a gap under plain --strict and not under
+    // `--strict --allow-stated-absence`. The two postures are both real: a catalog whose inventory
+    // is exactly the kit's wants no exceptions at all, while one that also publishes components of
+    // its own library that the kit never drew (wear-m3-catalog's `ButtonGroup`, `Scaffold`) wants
+    // strictness about SILENCE without being failed by the four cases somebody already looked at
+    // and wrote down. Without the opt-in those catalogs cannot use --strict at all, which costs
+    // them the guard against silence too — the thing --strict was actually for.
+    ...(ALLOW_STATED_ABSENCE
+      ? []
+      : diagnostics.statedAbsent.map((s) => `${s.componentId} — ${s.reason}`)),
     // An ambiguous mode is the third way a component ends up outside the map, and the quietest:
     // the reference is there, but nothing says which capture it pairs with, so the component is
     // simply absent. Under --strict that is as much a gap as a missing reference.
@@ -90,7 +108,10 @@ if (STRICT) {
     for (const line of missing) console.error(`  - ${line}`);
     console.error(
       `A catalog that reproduces a kit has nothing to compare these against — remove them, ` +
-        `or drop --strict to publish them unmapped.`,
+        `or drop --strict to publish them unmapped` +
+        (ALLOW_STATED_ABSENCE
+          ? `.`
+          : `, or pass --allow-stated-absence to accept the ones a noReference explains.`),
     );
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yschimke/compose-design-map",
-  "version": "1.18.0",
+  "version": "1.19.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",