baldart 4.64.0 → 4.66.0

package/src/utils/tokens-generator.js

@@ -0,0 +1,165 @@
+// Tokens generator — thin orchestrator over the DTCG SSOT (since v4.65.0).
+//
+// DTCG (`.tokens.json`, W3C Design Tokens Community Group: `$type`/`$value`,
+// `{ref}` aliases) is the design-token source of truth. This class reads it,
+// resolves aliases, and fans out to the per-format emitters in
+// `token-emitters/` to write the stack-native artifacts (tokens.ts, CSS vars).
+// Zero npm dependency — DTCG parsing is plain JSON traversal. Mirrors the thin-
+// wrapper shape of `graphify-installer.js` (detect / isStale / build).
+//
+// Authoritative design: framework/docs/COMPONENT-MANIFEST-LAYER.md.
+
+const fs = require('fs');
+const path = require('path');
+const emitters = require('./token-emitters');
+
+class TokensGenerator {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  /** True when the DTCG source file exists. */
+  detect(source) {
+    if (!source) return false;
+    try { return fs.statSync(path.join(this.cwd, source)).isFile(); }
+    catch (_) { return false; }
+  }
+
+  /** Read + JSON.parse the DTCG source. Throws a clear error on bad input. */
+  load(source) {
+    const abs = path.join(this.cwd, source);
+    let raw;
+    try { raw = fs.readFileSync(abs, 'utf8'); }
+    catch (e) { throw new Error(`cannot read design tokens at ${source}: ${e.message}`); }
+    try { return JSON.parse(raw); }
+    catch (e) { throw new Error(`${source} is not valid JSON: ${e.message}`); }
+  }
+
+  /**
+   * Flatten the DTCG tree to leaf tokens. A node is a token when it carries
+   * `$value`. `$type` is inherited from the nearest ancestor that declares it.
+   * Returns Map<dotId, { type, raw }> in source order.
+   */
+  flatten(tree) {
+    const out = new Map();
+    const walk = (node, prefix, inheritedType) => {
+      if (!node || typeof node !== 'object') return;
+      const type = Object.prototype.hasOwnProperty.call(node, '$type') ? node.$type : inheritedType;
+      if (Object.prototype.hasOwnProperty.call(node, '$value')) {
+        out.set(prefix, { type, raw: node.$value });
+        return;
+      }
+      for (const key of Object.keys(node)) {
+        if (key.startsWith('$')) continue; // $type / $description / $extensions
+        walk(node[key], prefix ? `${prefix}.${key}` : key, type);
+      }
+    };
+    walk(tree, '', undefined);
+    return out;
+  }
+
+  /**
+   * Resolve `{a.b.c}` aliases to concrete values (chains + cycle guard).
+   * Returns Map<dotId, { type, value }> in the same order as `flat`.
+   */
+  resolve(flat) {
+    const resolved = new Map();
+    const resolveOne = (id, seen) => {
+      if (resolved.has(id)) return resolved.get(id);
+      const tok = flat.get(id);
+      if (!tok) throw new Error(`token reference {${id}} does not resolve to a known token`);
+      let value = tok.raw;
+      if (typeof value === 'string') {
+        const m = value.match(/^\{([^}]+)\}$/);
+        if (m) {
+          const ref = m[1];
+          if (seen.has(ref)) throw new Error(`cyclic token reference: ${[...seen, ref].join(' → ')}`);
+          const target = resolveOne(ref, new Set([...seen, id]));
+          value = target.value;
+        }
+      }
+      const entry = { type: tok.type, value };
+      resolved.set(id, entry);
+      return entry;
+    };
+    for (const id of flat.keys()) resolveOne(id, new Set());
+    return resolved;
+  }
+
+  /** Build the nested object of resolved VALUES (DTCG tree minus $wrappers). */
+  nest(resolved) {
+    const root = {};
+    for (const [id, tok] of resolved) {
+      const parts = id.split('.');
+      let cur = root;
+      for (let i = 0; i < parts.length - 1; i++) {
+        cur[parts[i]] = cur[parts[i]] || {};
+        cur = cur[parts[i]];
+      }
+      cur[parts[parts.length - 1]] = tok.value;
+    }
+    return root;
+  }
+
+  /**
+   * Produce { outputs: [{ format, path, content }], resolved } WITHOUT writing.
+   * Used by both build() and isStale().
+   */
+  render({ source, outputs }) {
+    const tree = this.load(source);
+    const flat = this.flatten(tree);
+    if (flat.size === 0) throw new Error(`${source} contains no DTCG tokens ($value leaves)`);
+    const resolved = this.resolve(flat);
+    const nested = this.nest(resolved);
+    const rendered = [];
+    for (const o of outputs || []) {
+      const r = emitters.emit(o.format, { resolved, nested });
+      if (!r.ok) throw new Error(r.error);
+      rendered.push({ format: o.format, path: o.path, content: r.content });
+    }
+    return { outputs: rendered, resolved };
+  }
+
+  /**
+   * Build: render + write every output. Returns { ok, written:[paths] } or
+   * { ok:false, error }.
+   */
+  build({ source, outputs }) {
+    let r;
+    try { r = this.render({ source, outputs }); }
+    catch (e) { return { ok: false, error: e.message }; }
+    const written = [];
+    for (const o of r.outputs) {
+      const abs = path.join(this.cwd, o.path);
+      try {
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, o.content, 'utf8');
+        written.push(o.path);
+      } catch (e) {
+        return { ok: false, error: `failed writing ${o.path}: ${e.message}`, written };
+      }
+    }
+    return { ok: true, written, tokenCount: r.resolved.size };
+  }
+
+  /**
+   * isStale: true when any output on disk differs from a fresh render (i.e. a
+   * hand-edit to a generated file, or the source changed without a rebuild).
+   * Returns { stale, reasons:[{path, reason}] } or { stale:false } / error.
+   */
+  isStale({ source, outputs }) {
+    if (!this.detect(source)) return { stale: false, sourceMissing: true };
+    let r;
+    try { r = this.render({ source, outputs }); }
+    catch (e) { return { stale: true, error: e.message, reasons: [] }; }
+    const reasons = [];
+    for (const o of r.outputs) {
+      const abs = path.join(this.cwd, o.path);
+      let onDisk;
+      try { onDisk = fs.readFileSync(abs, 'utf8'); }
+      catch (_) { reasons.push({ path: o.path, reason: 'missing' }); continue; }
+      if (onDisk !== o.content) reasons.push({ path: o.path, reason: 'out-of-date' });
+    }
+    return { stale: reasons.length > 0, reasons };
+  }
+}
+
+module.exports = TokensGenerator;