@radicool/throughline 0.15.0 → 0.17.0

package/scripts/lib/dtcg.mjs

@@ -0,0 +1,203 @@
+// Shared DTCG reading: flatten a token tree to dot-paths, resolve {alias} chains.
+// Zero dependencies. Consumed by validate-crosswalk.mjs and validate-token-output.mjs,
+// and copied alongside both when a skill installs either gate.
+
+const REF = /^\{([^}]+)\}$/;
+
+// The typographic member names DTCG §9.8 fixes at MUST level, the unit gate a
+// text-role dimension must pass, and this project's $extensions namespace.
+//
+// They live here rather than in sd-native.mjs because textRoleGraph below and
+// sd-native.mjs's preprocess apply the identical rules, and sd-native.mjs
+// already imports this file — so the reverse import would be a cycle. Their
+// full rationale stays at the point of use in sd-native.mjs, which is what the
+// generated references/native-adapter-config.md renders.
+export const TEXT_UNIT_NAMES = new Set(['fontSize', 'letterSpacing', 'lineHeight']);
+export const TEXT_ROLE_UNIT = /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em)$/;
+export const EXT_NS = 'com.radicool.throughline';
+
+// Flatten nested DTCG groups into { "dot.path": rawValue }. Skips $-prefixed meta keys.
+//
+// A node carrying BOTH a $value and children yields its own value AND is descended
+// into — the dual-node pattern, where `text.sm` has `$value: "14px"` plus a
+// `text.sm.lineHeight` child. Stopping at the first $value drops those children,
+// which makes every alias to one unresolvable: the crosswalk gate reported them as
+// "missing from the DTCG source" though they exist, and the output validator could
+// not check them at all.
+export function flattenDtcg(obj, prefix = [], out = {}) {
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+    if (!val || typeof val !== 'object') continue;
+    const path = [...prefix, key];
+    if ('$value' in val) out[path.join('.')] = val.$value;
+    flattenDtcg(val, path, out);
+  }
+  return out;
+}
+
+// Flatten nested DTCG groups into { "dot.path": effectiveType }, applying the
+// $type resolution of DTCG 5.2.2: a token's own $type wins, otherwise the
+// nearest ancestor GROUP's. A node carrying a $value is a token, not a group
+// (DTCG 6.1), so it is not an inheritance source for its children — the same
+// rule hoistDualNodes computes as `inherited`, and the two must agree or two
+// functions in this codebase disagree about the type of the same tree.
+//
+// Separate from flattenDtcg rather than folded into it: that function has four
+// consumers and both validators re-export it, so its return shape is fixed.
+//
+// LIMIT, stated rather than hidden: this reads the RAW source, so it cannot see
+// the $type carry hoistDualNodes applies during preprocessing. An untyped child
+// of a dimension-typed dual node with no enclosing group type is a dimension to
+// the pipeline and undefined here. Reference-derived typing (5.2.2 rule 1) is
+// likewise not resolved — an alias is undefined, but its referent is typed, and
+// the referent is the token an author edits.
+export function flattenDtcgTypes(obj, prefix = [], out = {}, groupType = undefined) {
+  const inherited = '$value' in obj ? groupType : (obj.$type ?? groupType);
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+    if (!val || typeof val !== 'object') continue;
+    const path = [...prefix, key];
+    if ('$value' in val) out[path.join('.')] = val.$type ?? inherited;
+    flattenDtcgTypes(val, path, out, inherited);
+  }
+  return out;
+}
+
+// Follow {alias} chains to a leaf literal. Throws on missing or circular refs.
+export function resolveValue(name, flat, seen = new Set()) {
+  if (!(name in flat)) throw new Error(`token "${name}" not found in DTCG source`);
+  const val = flat[name];
+  if (typeof val === 'string') {
+    const m = val.match(REF);
+    if (m) {
+      if (seen.has(name)) throw new Error(`circular reference at "${name}"`);
+      seen.add(name);
+      return resolveValue(m[1], flat, seen);
+    }
+  }
+  return val;
+}
+
+// A token path defined in more than one source file with differing values means
+// the build's source list spans modes. Style Dictionary dedupes these silently,
+// dropping one whole mode — 864 such collisions produced a light-only build from
+// a dark-default system.
+export function findModeCollisions(sources) {
+  const seen = new Map();
+  for (const { file, dtcg } of sources) {
+    for (const [path, value] of Object.entries(flattenDtcg(dtcg))) {
+      if (!seen.has(path)) seen.set(path, []);
+      seen.get(path).push({ file, value });
+    }
+  }
+  const collisions = [];
+  for (const [path, defs] of seen) {
+    const distinct = new Set(defs.map((d) => JSON.stringify(d.value)));
+    if (defs.length > 1 && distinct.size > 1) collisions.push({ path, defs });
+  }
+  return collisions;
+}
+
+// Deep merge in list order, later source winning — the same later-wins rule
+// validate-token-output.mjs already applies when it flattens a source list, and
+// what Style Dictionary hands preprocess as one dict.
+//
+// Each source is cloned on the way in. Merging the caller's own objects would
+// mutate the token trees it still holds, and the validator reads them again.
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function mergeInto(target, src) {
+  for (const [key, val] of Object.entries(src)) {
+    if (isPlainObject(val) && isPlainObject(target[key])) mergeInto(target[key], val);
+    else target[key] = val;
+  }
+  return target;
+}
+
+export function mergeDtcg(dicts) {
+  const out = {};
+  for (const dict of dicts) mergeInto(out, structuredClone(dict));
+  return out;
+}
+
+// A dimension primitive states no typographic role: text.base: "16px" is a font
+// size only to a human, so it emitted as dp, and an em letterSpacing primitive
+// was dropped from native output entirely. #51 sources the role from the member
+// names DTCG §9.8 fixes, which reaches the semantic tokens and not the
+// primitives they reference. This reaches the primitives, structurally.
+//
+// Reads the UNRESOLVED tree: preprocess resolves aliases in place, so by
+// transform time the graph is gone. Nothing needs carrying, because the
+// inference is applied during preprocessing and only the $extensions stamp
+// survives — see sd-native.mjs's applyTextRoleGraph.
+//
+// A referrer whose leaf name is NOT typographic is counter-evidence, not
+// neutral. A dimension referenced by something that is not a typographic member
+// is a length, which is exactly what the dp default already asserts about it.
+// Treating it as neutral would let one stray fontSize reference convert a whole
+// spacing ramp.
+//
+// Single-pass and deliberately not transitive: a chain through an intermediate
+// whose own leaf name states no role is declined at the second hop, because
+// that intermediate is itself counter-evidence. Only whole-value references
+// count; a reference embedded in an expression is resolved by resolveInPlace
+// but is not evidence of a role.
+export function textRoleGraph(dict) {
+  const edges = [];
+  (function walk(node, prefix) {
+    for (const [key, val] of Object.entries(node)) {
+      if (key.startsWith('$') || !isPlainObject(val)) continue;
+      const path = [...prefix, key];
+      if (typeof val.$value === 'string') {
+        const m = REF.exec(val.$value.trim());
+        if (m) edges.push({ to: m[1], leaf: key });
+      }
+      walk(val, path);
+    }
+  })(dict, []);
+
+  const referrers = new Map();
+  for (const edge of edges) {
+    if (!referrers.has(edge.to)) referrers.set(edge.to, []);
+    referrers.get(edge.to).push(edge);
+  }
+
+  const typographic = new Set();
+  const ambiguous = [];
+  for (const [path, rs] of referrers) {
+    const textLeaves = [...new Set(rs.filter((r) => TEXT_UNIT_NAMES.has(r.leaf)).map((r) => r.leaf))];
+    if (textLeaves.length === 0) continue;
+    const otherLeaves = [...new Set(rs.filter((r) => !TEXT_UNIT_NAMES.has(r.leaf)).map((r) => r.leaf))];
+    if (otherLeaves.length) ambiguous.push({ path, textLeaves, otherLeaves });
+    else typographic.add(path);
+  }
+
+  // A primitive nothing references has no structural signal at all, so it is
+  // never inferred. Reported instead, where its group holds one that was: that
+  // is the strongest hint available without guessing, and a silent gap is the
+  // failure this module exists to prevent. A token whose source already stamps
+  // nativeUnit is closed and is not reported.
+  const inferredGroups = new Set([...typographic].map((p) => p.split('.').slice(0, -1).join('.')));
+  const unreferencedSiblings = [];
+  (function walk(node, prefix) {
+    for (const [key, val] of Object.entries(node)) {
+      if (key.startsWith('$') || !isPlainObject(val)) continue;
+      const path = [...prefix, key];
+      const dotted = path.join('.');
+      const group = prefix.join('.');
+      if (
+        '$value' in val &&
+        val.$type === 'dimension' &&
+        TEXT_ROLE_UNIT.test(String(val.$value).trim()) &&
+        !referrers.has(dotted) &&
+        !('nativeUnit' in (val.$extensions?.[EXT_NS] ?? {})) &&
+        inferredGroups.has(group)
+      ) {
+        unreferencedSiblings.push({ path: dotted, group });
+      }
+      walk(val, path);
+    }
+  })(dict, []);
+
+  return { typographic, ambiguous, unreferencedSiblings };
+}

package/scripts/lib/native-literal.mjs

@@ -0,0 +1,205 @@
+// Is an emitted value a well-formed Swift or Kotlin literal?
+//
+// A CSS function and a native call expression look alike until you check the
+// callee. `linear-gradient` is not a valid identifier — the hyphen disqualifies
+// it — while `UIColor` is. `calc` IS a valid identifier, but `1rem + 2px` is
+// not a literal. Parsing rather than pattern-matching rejects all of them
+// without naming any of them, which is the point: the next unanticipated case
+// is caught by the same rule.
+//
+// Two consumers — sd-native.mjs's output filter, and
+// validate-token-output.mjs's invalid-literal rule. Its own module for the same
+// reason lib/dtcg.mjs is one: shared by both token gates.
+//
+// This asserts LITERAL well-formedness, not that the file compiles. A call to
+// an undefined function still parses.
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*/;
+
+// Swift and Kotlin disagree about numeric literals in OPPOSITE directions, so
+// one shared rule necessarily over-accepts on one platform or false-fails on
+// the other. Both sides measured rather than assumed:
+//
+//   Swift, via `swiftc -parse`: `.5` and `-.5` are rejected — the compiler says
+//   "it must be written '0.5'" — while `0100` and `00` compile.
+//
+//   Kotlin, via `kotlinc` 2.4.10: `0100` and `00` are rejected outright —
+//   "leading zeros are not allowed in integer literals" — while `.5` and `-.5`
+//   compile, which is why they stay accepted here. This matches the spec's
+//   lexical grammar exactly: IntegerLiteral is
+//   `DecDigitNoZero {DecDigitOrSeparator} DecDigit | DecDigit`, and
+//   DoubleLiteral is `[DecDigits] '.' DecDigits [DoubleExponent]`.
+//
+// Hex compiles on both and stays. A leading-zero integer is caught by the
+// trailing-input rule at the end of parseLiteral rather than by the regex:
+// `0100` matches only `0`, leaving `100` unconsumed.
+const NUMBER_SWIFT = /^-?(?:0[xX][0-9a-fA-F]+|\d+(?:\.\d+)?)/;
+const NUMBER_KOTLIN = /^-?(?:0[xX][0-9a-fA-F]+|(?:0|[1-9]\d*)(?:\.\d+)?|\.\d+)/;
+
+// The union of both, for a caller that names no platform. Every real consumer
+// passes a GRAMMAR entry, which overrides this.
+const NUMBER = /^-?(?:0[xX][0-9a-fA-F]+|\d+(?:\.\d+)?|\.\d+)/;
+
+// `escapes` are the characters legal after a backslash inside a string.
+// \$ escapes Kotlin's template interpolation; it is not a valid Swift escape,
+// so a shared set would over-accept on iOS.
+export const GRAMMAR = {
+  'ios-swift': {
+    number: NUMBER_SWIFT,
+    suffixes: [],
+    units: [],
+    escapes: ['0', '\\', 't', 'n', 'r', '"', "'", 'u'],
+  },
+  'android-kotlin': {
+    number: NUMBER_KOTLIN,
+    suffixes: ['f', 'F', 'L'],
+    units: ['dp', 'sp', 'em'],
+    escapes: ['\\', 't', 'n', 'r', '"', "'", '$', 'u'],
+  },
+};
+
+// CSS constructs that validate-token-output.mjs diagnoses BY NAME.
+//
+// These are unimplemented rescues, not values with no native form: `calc` and
+// `var` are valid identifiers, and `color-mix` has a rescue in sd-native.mjs
+// that merely did not match this variant. So they must reach the output and
+// fail loudly under no-foreign-syntax, never be silently dropped by a filter.
+// Kept here, beside the grammar, so the build and the gate cannot drift apart.
+export const CSS_CONSTRUCT = /^(?:color-mix|calc|var)\s*\(/;
+
+export function parseLiteral(value, grammar = {}) {
+  const s = String(value);
+  const suffixes = grammar.suffixes ?? [];
+  const units = grammar.units ?? [];
+  const escapes = new Set(grammar.escapes ?? []);
+  const numberRe = grammar.number ?? NUMBER;
+  let i = 0;
+
+  const ws = () => {
+    while (i < s.length && /\s/.test(s[i])) i += 1;
+  };
+
+  // Longest match wins, so a short unit cannot shadow a longer one.
+  const take = (words) => {
+    let best = null;
+    for (const w of words) {
+      if (s.startsWith(w, i) && (best === null || w.length > best.length)) best = w;
+    }
+    if (best !== null) i += best.length;
+    return best !== null;
+  };
+
+  const string = () => {
+    i += 1; // opening quote
+    while (i < s.length) {
+      if (s[i] === '\\') {
+        if (!escapes.has(s[i + 1])) return false;
+        i += 2;
+        continue;
+      }
+      if (s[i] === '"') {
+        i += 1;
+        return true;
+      }
+      if (s[i] === '\n') return false;
+      i += 1;
+    }
+    return false; // unterminated
+  };
+
+  const number = () => {
+    const m = s.slice(i).match(numberRe);
+    if (!m) return false;
+    i += m[0].length;
+    if (take(units.map((u) => `.${u}`))) return true;
+    take(suffixes);
+    return true;
+  };
+
+  const literal = () => {
+    ws();
+    if (i >= s.length) return false;
+    if (s[i] === '"') return string();
+
+    // A parenthesised NUMBER, optionally with a unit. Compose letter spacing
+    // needs `(-0.03).em`, because `-0.03.em` parses as `-(0.03.em)` and
+    // kotlinc rejects it with "unresolved reference 'unaryMinus'" unless
+    // TextUnit defines that operator. The parenthesised form compiles either
+    // way, so it is what the transform emits.
+    //
+    // Deliberately not expression support: only a single number may sit inside
+    // the parens. Accepting `(1 + 2)` would make this gate vouch for
+    // arithmetic it cannot evaluate, which is the failure class the module
+    // exists to prevent.
+    if (s[i] === '(') {
+      const save = i;
+      i += 1;
+      ws();
+      const inner = s.slice(i).match(numberRe);
+      if (!inner) {
+        i = save;
+        return false;
+      }
+      i += inner[0].length;
+      ws();
+      if (s[i] !== ')') {
+        i = save;
+        return false;
+      }
+      i += 1;
+      if (take(units.map((u) => `.${u}`))) return true;
+      take(suffixes);
+      return true;
+    }
+
+    const rest = s.slice(i);
+    const bool = rest.match(/^(?:true|false)(?![A-Za-z0-9_])/);
+    if (bool) {
+      i += bool[0].length;
+      return true;
+    }
+    if (numberRe.test(rest)) return number();
+
+    const id = rest.match(IDENT);
+    if (!id) return false;
+    i += id[0].length;
+    ws();
+    if (s[i] !== '(') return false; // a bare identifier is not a literal
+    i += 1;
+    ws();
+    if (s[i] === ')') {
+      i += 1;
+      return true;
+    }
+    for (;;) {
+      ws();
+      const save = i;
+      const label = s.slice(i).match(IDENT);
+      if (label) {
+        i += label[0].length;
+        ws();
+        if (s[i] === ':') i += 1;
+        else i = save; // not a label after all; re-read as a literal
+      }
+      if (!literal()) return false;
+      ws();
+      if (s[i] === ',') {
+        i += 1;
+        continue;
+      }
+      if (s[i] === ')') {
+        i += 1;
+        return true;
+      }
+      return false;
+    }
+  };
+
+  if (!literal()) return { ok: false, offset: i, rest: s.slice(i) };
+  ws();
+  // Trailing input after a complete literal is a failure: `400 garbage`.
+  if (i !== s.length) return { ok: false, offset: i, rest: s.slice(i) };
+  return { ok: true };
+}
+
+export const isValidLiteral = (value, grammar) => parseLiteral(value, grammar).ok;