@radicool/throughline 0.18.0 → 0.20.0

package/scripts/lib/sd-native.mjs

@@ -12,7 +12,8 @@
 import { readFileSync } from 'node:fs';
 import {
   flattenDtcg,
-  flattenDtcgTypes,
+  flattenPipelineTypes,
+  extNamespace,
   resolveValue,
   findModeCollisions,
   TEXT_UNIT_NAMES,
@@ -83,10 +84,25 @@ export function colorMixToHex8(value) {
 // Marks a node whose AUTHORED $value was a whole-value reference, so the hoist
 // can decline to override the type DTCG 5.2.2 rule 1 already determined from the
 // referent. A WeakSet keyed on the node object, rather than a property written
-// onto it, holds structural idempotency exactly: structuredClone drops the
-// membership along with the rest of the identity, so preprocess(preprocess(x))
-// is deepEqual to preprocess(x) with no leak question to manage.
+// onto it, keeps this mechanism from leaking across calls: structuredClone
+// drops the membership along with the rest of the identity, so a second pass
+// starts clean rather than inheriting the first pass's marks. That is exactly
+// what a property written onto the node would get wrong. It is not on its own a
+// guarantee that preprocess is idempotent — see the limit recorded at
+// nativePlatform's preprocessors line (#90).
 const WAS_REF = new WeakSet();
+
+// The path the AUTHOR wrote for a node the hoist has moved. hoistDualNodes
+// recurses depth-first, so by the time an outer frame takes Object.entries it
+// already contains names the inner frame synthesised — and a collision reported
+// from that frame named a path appearing nowhere in the source (#61). Recording
+// the authored path when a node is hoisted lets the outer frame report what the
+// author can actually search for.
+//
+// Keyed on node identity, like WAS_REF, and safe across calls for the same
+// reason: preprocess structuredClones its input, so every call works on fresh
+// objects.
+const AUTHORED_PATH = new WeakMap();
 const WHOLE_REF = /^\{[^}]+\}$/;
 
 function interpolate(value, flat) {
@@ -159,20 +175,27 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
       for (const [childKey, childVal] of Object.entries(val)) {
         if (childKey.startsWith('$') || !childVal || typeof childVal !== 'object') continue;
         const hoisted = key + childKey[0].toUpperCase() + childKey.slice(1);
-        const from = [...prefix, key, childKey].join('.');
+        const from = AUTHORED_PATH.get(childVal) ?? [...prefix, key, childKey].join('.');
         if (Object.hasOwn(node, hoisted)) {
           const existingNode = node[hoisted];
-          const isGroup = existingNode !== null && typeof existingNode === 'object' && !('$value' in existingNode);
+          // An array has no $value either, and was therefore labelled "(a group)"
+          // (#61). It is neither — an array at this position is malformed DTCG.
+          // Say so, rather than naming a shape the author will go looking for.
+          const isArray = Array.isArray(existingNode);
+          const isGroup =
+            existingNode !== null && typeof existingNode === 'object' && !isArray && !('$value' in existingNode);
           collisions.push({
             from,
             onto: [...prefix, hoisted].join('.'),
             isGroup,
+            isArray,
             claimant: claimedBy.get(hoisted),
-            existing: isGroup
-              ? undefined
-              : existingNode && typeof existingNode === 'object'
-                ? existingNode.$value
-                : existingNode,
+            existing:
+              isGroup || isArray
+                ? undefined
+                : existingNode && typeof existingNode === 'object'
+                  ? existingNode.$value
+                  : existingNode,
           });
           continue;
         }
@@ -195,8 +218,17 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
         // type suits the child badly, because the hoist is not entitled to
         // improve on what the source says; but the carry firing at all is the
         // hoist saying something the source did not.
+        //
+        // A GROUP child is excluded (#67). The carry's premise is that the dual
+        // node was the child's closest $type-bearing ancestor as authored, and
+        // the hoist took that away. For a group child the premise never held:
+        // 5.2.2 inherits from the closest parent GROUP, the dual node is not
+        // one, so it was never that group's inheritance source and the hoist
+        // removed nothing. Carrying there does not repair, it invents — and it
+        // invents for every token beneath the group, not just one node.
         if (
           !('$type' in childVal) &&
+          '$value' in childVal &&
           '$type' in val &&
           !WAS_REF.has(childVal) &&
           inherited === undefined
@@ -204,6 +236,7 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
           childVal.$type = val.$type;
         }
         node[hoisted] = childVal;
+        AUTHORED_PATH.set(childVal, from);
         delete val[childKey];
         claimedBy.set(hoisted, from);
       }
@@ -302,6 +335,9 @@ function classifyTextUnits(node, types, prefix = []) {
       types[path.join('.')] === 'dimension' &&
       TEXT_ROLE_UNIT.test(String(val.$value).trim())
     ) {
+      // extNamespace throws with the token path if the source authored either
+      // level as a primitive — legal DTCG this module does not handle (#62).
+      extNamespace(val, path.join('.'));
       val.$extensions ??= {};
       val.$extensions[EXT_NS] ??= {};
       const ns = val.$extensions[EXT_NS];
@@ -310,7 +346,9 @@ function classifyTextUnits(node, types, prefix = []) {
       // one, so a unitless value is declined by every size transform regardless
       // of what is stamped here (see isRatio, #52). Declining to overwrite IS
       // the feature: it costs no configuration parameter, and it is what makes
-      // the pass idempotent.
+      // STAMPING idempotent — a second pass never rewrites a role a first pass
+      // set. What it does not settle is whether a second pass finds the same
+      // candidates; the hoist can rename a node between the two (#90).
       if (!('nativeUnit' in ns)) ns.nativeUnit = 'text';
     }
     classifyTextUnits(val, types, path);
@@ -333,7 +371,8 @@ function classifyTextUnits(node, types, prefix = []) {
 // A path may name no node at all. resolveInPlace deliberately leaves an
 // unresolvable reference in place for Style Dictionary to report, so the graph
 // can hold an edge to a token that does not exist. Skip it. This is also what
-// keeps the second preprocess pass from throwing, and idempotency with it.
+// keeps the second preprocess pass from throwing — which is a precondition for
+// idempotency, not the whole of it (#90).
 function applyTextRoleGraph(node, typographic, types) {
   for (const path of typographic) {
     let target = node;
@@ -343,6 +382,7 @@ function applyTextRoleGraph(node, typographic, types) {
     if (!target || typeof target !== 'object' || !('$value' in target)) continue;
     if (types[path] !== 'dimension') continue;
     if (!TEXT_ROLE_UNIT.test(String(target.$value).trim())) continue;
+    extNamespace(target, path);
     target.$extensions ??= {};
     target.$extensions[EXT_NS] ??= {};
     const ns = target.$extensions[EXT_NS];
@@ -357,14 +397,16 @@ export function preprocess(dict) {
   // the graph is made of.
   const { typographic } = textRoleGraph(dict);
   const resolved = resolveInPlace(structuredClone(dict), flattenDtcg(dict));
-  // DTCG 5.2.2 types for the whole tree, walked once and shared by both passes
-  // below. Neither writes $type or moves a node, so one map is correct for
-  // both, and sharing it is what makes them agree by construction rather than
-  // by two copies of the same rule staying in step (#85).
+  // Types for the whole tree, walked once and shared by both passes below.
+  // Neither writes $type or moves a node, so one map is correct for both, and
+  // sharing it is what makes them agree by construction rather than by two
+  // copies of the same rule staying in step (#85).
   //
-  // Computed on the RESOLVED clone, which is the tree both passes read.
-  // resolveInPlace rewrites $value strings only, so the types are the source's.
-  const types = flattenDtcgTypes(resolved);
+  // Computed on the RAW dict, not the resolved clone. resolveInPlace only
+  // rewrites $value strings, so paths and types are identical between the two —
+  // except for the carry, whose rule asks whether a value WAS a whole-value
+  // reference, and resolution has already destroyed that (#89).
+  const types = flattenPipelineTypes(dict);
   const out = hoistDualNodes(
     applyTextRoleGraph(classifyTextUnits(resolved, types), typographic, types),
     collisions,
@@ -374,6 +416,9 @@ export function preprocess(dict) {
       .slice(0, 5)
       .map((c) => {
         const line = `  ${c.from} -> ${c.onto}`;
+        if (c.isArray) {
+          return line + ' (an array — neither a token nor a group, and not valid DTCG here)';
+        }
         if (c.isGroup) {
           return line + (c.claimant ? ` (a group, already claimed by the hoist of ${c.claimant})` : ' (a group)');
         }
@@ -501,7 +546,14 @@ const DECLINED_STOCK_TRANSFORMS = {
 // Order is never compared: our lists are hand-ordered for our own reasons and
 // do not inherit stock order. Removals are never reported: a declined name
 // disappearing is a non-event.
-export function auditStockGroups(transformGroups) {
+// `platforms` and `declined` are parameters with the shipped config as their
+// default, so the contradiction branch below is reachable from a test. The
+// single caller passes neither; the audit's contract is unchanged.
+export function auditStockGroups(
+  transformGroups,
+  platforms = PLATFORMS,
+  declined = DECLINED_STOCK_TRANSFORMS,
+) {
   if (typeof transformGroups !== 'object' || transformGroups === null) {
     return [
       "throughline: could not read Style Dictionary's stock transform groups " +
@@ -510,7 +562,29 @@ export function auditStockGroups(transformGroups) {
     ];
   }
   const warnings = [];
-  for (const [platform, preset] of Object.entries(PLATFORMS)) {
+  for (const [platform, preset] of Object.entries(platforms)) {
+    // A name in BOTH lists is a contradiction the unaccounted filter below
+    // cannot see, because either membership alone suppresses the warning (#75).
+    // The config would be saying "we run this" and "we deliberately do not" at
+    // once, and whichever is wrong is silently the loser: if the decline is
+    // right the transform still runs, and if the run is right the decline is a
+    // lie the next maintainer will read as settled. Reported here rather than
+    // guarded at the definition, so it travels with the rest of the audit.
+    //
+    // Checked before stockGroup, because this is wrong regardless of whether
+    // Style Dictionary still has the group to compare against.
+    if (Array.isArray(preset.transforms)) {
+      const contradictory = preset.transforms.filter((name) => Object.hasOwn(declined, name));
+      if (contradictory.length) {
+        warnings.push(
+          `throughline: PLATFORMS['${platform}'] both runs and declines ` +
+            `${contradictory.join(', ')}. A transform cannot be in transforms and in ` +
+            'DECLINED_STOCK_TRANSFORMS at once — one of the two is wrong, and the ' +
+            'audit cannot tell which. This is a throughline packaging defect — ' +
+            'please report it.',
+        );
+      }
+    }
     const group = preset.stockGroup;
     if (!group || !Array.isArray(preset.transforms)) {
       warnings.push(
@@ -534,7 +608,7 @@ export function auditStockGroups(transformGroups) {
     const unaccounted = stock.filter(
       (name) =>
         !preset.transforms.includes(name) &&
-        !Object.hasOwn(DECLINED_STOCK_TRANSFORMS, name),
+        !Object.hasOwn(declined, name),
     );
     if (unaccounted.length) {
       const n = unaccounted.length;
@@ -636,8 +710,21 @@ export function nativePlatform({ platform, buildPath, className = 'Tokens', pack
     // Carried here, not left to the caller: authored() reads the ORIGINAL
     // $value, so without this preprocessor every aliased dimension still holds
     // an unresolved {spacing.space.4}, no size transform fires, and the build
-    // emits bare px literals. preprocess is idempotent, so a project that also
-    // declares it at top level is harmless.
+    // emits bare px literals.
+    //
+    // A project that ALSO declares this preprocessor at top level runs it twice,
+    // which is harmless in every shape measured — and is the wiring our own
+    // usage snippet shows, so it is the common case rather than a corner.
+    //
+    // Stated no wider than it holds (#90): preprocess is idempotent except where
+    // the hoist invents a name the second pass then classifies. `a.font` with a
+    // child `size` camel-joins to `a.fontSize`; the first pass correctly declines
+    // `size`, and the second sees a typographic member name the source never
+    // authored. It changes no emitted output — Style Dictionary runs
+    // typeDtcgDelegate between the two passes and types that child anyway, so
+    // both passes reach the same file — and the repair belongs with the hoist,
+    // which has no way to record the names it invented. Pinned by test rather
+    // than papered over.
     preprocessors: ['dtcg/resolve-dual-node'],
     buildPath,
     options: { outputReferences: false },

package/scripts/lib/source-scan.mjs

@@ -0,0 +1,45 @@
+// Walking a consumer's source tree, shared by every gate that scans one.
+//
+// grep-color-usage.mjs and guard-token-removal.mjs each carried their own copy
+// of this — identical excludes, and a walk that differed only in which file
+// extensions it yielded. The duplication was the shape #57 was filed for: two
+// definitions of one rule, agreeing today, with nothing keeping them in step.
+//
+// The file filter is the caller's, not a built-in: a colour scan wants
+// stylesheets and a symbol guard does not, and neither should have to fork the
+// walker to say so.
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DEFAULT_EXCLUDES = [
+  /(^|\/)node_modules(\/|$)/,
+  /(^|\/)generated(\/|$)/,
+  /\.generated\./,
+  /\.test\./,
+  /\.spec\./,
+  /(^|\/)__tests__(\/|$)/,
+  /(^|\/)dist(\/|$)/,
+  /(^|\/)\.next(\/|$)/,
+  /(^|\/)storybook-static(\/|$)/,
+];
+
+// Every text file a design system's values can hide in.
+export const SOURCE_EXT = /\.(scss|sass|css|tsx?|jsx?|mjs|cjs|vue|svelte|html|svg)$/;
+
+export function* walk(root, { excludes = DEFAULT_EXCLUDES, fileFilter = SOURCE_EXT } = {}) {
+  for (const entry of readdirSync(root)) {
+    const full = join(root, entry);
+    if (excludes.some((re) => re.test(full))) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) yield* walk(full, { excludes, fileFilter });
+    else if (fileFilter.test(full)) yield full;
+  }
+}
+
+// A design system records a component's DISPLAY name — a real manifest holds
+// "Select Menu" — while the code exports <SelectMenu>. Nothing in the schema
+// says `name` is a code identifier, and nothing should be changed to make it
+// one: a display name is right for a doc surface. So the comparison normalises,
+// the same way validate-token-output.mjs already folds adapter naming
+// conventions onto each other.
+export const normalizeName = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');