@transtyle/core 0.1.0-alpha.0

package/src/diagnostics.js

@@ -0,0 +1,43 @@
+/** Shared diagnostics collector (docs/specs/validation-and-coverage.md). */
+
+/**
+ * AL5: two behaviors that exist because of what the tool actually did when a
+ * user got something wrong, not because of a design idea.
+ *
+ * 1. `hint` — a separate, optional "here is what to do" line. Keeping it out of
+ *    `message` is what makes actionability structural: the message says what is
+ *    wrong, the hint says what to change, and the CLI renders them distinctly
+ *    (report.json keeps both fields). Before this, advice that the docs page
+ *    already gave was simply absent at the point of failure.
+ *
+ * 2. De-duplication on (severity, code, message). DERIVE and NORMALIZE both run
+ *    once per mode combo, so a single authoring mistake was reported once per
+ *    combo — a 2-token alias cycle printed twelve lines. Identical text repeated
+ *    N times carries no information beyond the first. Anything genuinely
+ *    per-mode already says so in its message (contrast warnings name the mode),
+ *    so those still come through separately.
+ */
+export class Diagnostics {
+  constructor() {
+    this.items = [];
+    this._seen = new Set();
+  }
+  #push(severity, code, message, context) {
+    const key = `${severity} ${code} ${message}`;
+    if (this._seen.has(key)) return;
+    this._seen.add(key);
+    this.items.push({ severity, code, message, ...context });
+  }
+  error(code, message, context = {}) { this.#push('error', code, message, context); }
+  warn(code, message, context = {}) { this.#push('warning', code, message, context); }
+  info(code, message, context = {}) { this.#push('info', code, message, context); }
+  get errors() { return this.items.filter((i) => i.severity === 'error'); }
+  get warnings() { return this.items.filter((i) => i.severity === 'warning'); }
+  /** Did this code already fire? Used to suppress consequences of a root cause. */
+  has(code) { return this.items.some((i) => i.code === code); }
+  shouldFail(failOn = 'error') {
+    if (failOn === 'error') return this.errors.length > 0;
+    if (failOn === 'warning') return this.errors.length > 0 || this.warnings.length > 0;
+    return this.errors.length > 0;
+  }
+}

package/src/diff.js

@@ -0,0 +1,97 @@
+/**
+ * Semantic diff of two resolved IRs (docs/specs/diff.md, ROADMAP P6). Pure and
+ * deterministic: no I/O, no git — the CLI resolves "before" (a git ref) and
+ * "after" (the working tree) via compile() and hands both here.
+ *
+ * The unit of a design-system change is a **semantic slot value in a mode**, not
+ * a token-file line: renaming an option token or restructuring layers that leaves
+ * every resolved value identical is correctly reported as no change, because the
+ * compiled themes are identical. That is the whole point of diffing the resolved
+ * graph rather than the source.
+ */
+
+import { CONTRAST_PAIRS, contrastThreshold, pairRatio } from './checks.js';
+
+/** Canonical, stable string form of a resolved value, for equality only. */
+function canon(value) {
+  if (value === null || value === undefined) return String(value);
+  if (typeof value !== 'object') return String(value);
+  if (Array.isArray(value)) return `[${value.map(canon).join(',')}]`;
+  // plain data objects (color components, typography/shadow composites) — sort
+  // keys so equality is independent of construction order.
+  return `{${Object.keys(value).sort().map((k) => `${k}:${canon(value[k])}`).join(',')}}`;
+}
+
+const provKind = (entry) => entry?.provenance?.kind ?? null;
+
+/**
+ * @returns {{ modes: Array<{ mode, added: string[], removed: string[],
+ *   changed: Array<{ slot, before, after, valueChanged, provChanged }> }>,
+ *   changedSlots: Set<string>, hasChanges: boolean }}
+ */
+export function diffResolved(before, after) {
+  const modeNames = [...new Set([...Object.keys(before.modes), ...Object.keys(after.modes)])].sort();
+  const modes = [];
+  const changedSlots = new Set();
+
+  for (const mode of modeNames) {
+    const b = before.modes[mode] ?? new Map();
+    const a = after.modes[mode] ?? new Map();
+    const slots = [...new Set([...b.keys(), ...a.keys()])].sort();
+    const added = [], removed = [], changed = [];
+
+    for (const slot of slots) {
+      const be = b.get(slot);
+      const ae = a.get(slot);
+      if (!be && ae) { added.push(slot); changedSlots.add(slot); continue; }
+      if (be && !ae) { removed.push(slot); changedSlots.add(slot); continue; }
+      const valueChanged = canon(be.value) !== canon(ae.value);
+      const provChanged = provKind(be) !== provKind(ae);
+      if (valueChanged || provChanged) {
+        changed.push({ slot, before: be, after: ae, valueChanged, provChanged });
+        changedSlots.add(slot);
+      }
+    }
+    modes.push({ mode, added, removed, changed });
+  }
+
+  const hasChanges = modes.some((m) => m.added.length || m.removed.length || m.changed.length);
+  return { modes, changedSlots, hasChanges };
+}
+
+/**
+ * Accessibility regressions introduced by the change (docs/specs/diff.md).
+ *
+ * `check` tells you the contrast is bad *now*; this tells you **this change made
+ * it bad** — which is the question a reviewer has, and the one a passing-CI
+ * baseline can regress on silently. Uses the same pairs and threshold as
+ * `runChecks`, so the two can never disagree about what "passing" means.
+ *
+ * Severities, worst first:
+ *   `regressed` — passed the standard before, fails now (the headline case)
+ *   `worsened`  — already failing, and the ratio dropped further
+ *
+ * A pair that improves, or that fails identically on both sides, is not reported.
+ *
+ * @returns {Array<{ mode, fg, bg, before: number, after: number, status, threshold }>}
+ */
+export function contrastRegressions(before, after, config) {
+  const threshold = contrastThreshold(config);
+  const out = [];
+  for (const mode of Object.keys(after.modes)) {
+    const bMap = before.modes[mode];
+    const aMap = after.modes[mode];
+    if (!bMap || !aMap) continue; // mode added or removed — not a regression
+    for (const [fg, bg] of CONTRAST_PAIRS) {
+      const b = pairRatio(bMap, fg, bg);
+      const a = pairRatio(aMap, fg, bg);
+      if (b === null || a === null) continue;
+      if (b >= threshold && a < threshold) {
+        out.push({ mode, fg, bg, before: b, after: a, status: 'regressed', threshold });
+      } else if (b < threshold && a < threshold && a < b - 0.05) {
+        out.push({ mode, fg, bg, before: b, after: a, status: 'worsened', threshold });
+      }
+    }
+  }
+  return out;
+}

package/src/index.js

@@ -0,0 +1,187 @@
+/**
+ * @transtyle/core — public programmatic API (docs/architecture/overview.md:
+ * "core is a library first, CLI second").
+ */
+
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { loadConfig, loadTokenTrees } from './load.js';
+import { validate } from './schema/validate.js';
+import { configSchema } from './schema/config.schema.js';
+import { normalize, resolveDeferredAliases, reportModeCarryOver } from './normalize.js';
+import { derive } from './derive.js';
+import { runChecks } from './checks.js';
+import { Diagnostics } from './diagnostics.js';
+import { nearestName } from './nearest.js';
+import { formatColor, formatHslTriplet, formatHex, contrastRatio, mix } from './color.js';
+
+export { formatColor, formatHslTriplet, formatHex, contrastRatio, mix } from './color.js';
+export { Diagnostics } from './diagnostics.js';
+export { diffResolved, contrastRegressions } from './diff.js';
+
+/**
+ * Run the pipeline. `emit: false` = `transtyle check` (pipeline minus EMIT —
+ * same code path by design, docs/architecture/pipeline.md).
+ */
+/**
+ * `knownExporters` (AL5) is the caller's list of exporter names it can resolve —
+ * the CLI's OFFICIAL_EXPORTERS keys. Core stays exporter-agnostic (it never
+ * imports one), but TST1301 can then tell "you typo'd" apart from "that
+ * exporter exists, you just haven't configured it", which are opposite fixes.
+ */
+export async function compile({ cwd, targets, emit = true, loadExporter, knownExporters = [] }) {
+  const diagnostics = new Diagnostics();
+  const { config } = await loadConfig(cwd);
+
+  // Config schema validation (audit A8): a typo'd or mis-typed config key is an
+  // error, not a silently-ignored field. Fail before touching tokens — a broken
+  // config shape would only produce misleading downstream diagnostics.
+  for (const { path: p, message } of validate(config, configSchema)) {
+    diagnostics.error('TST1010', `transtyle.config.json: ${p === '(root)' ? '' : p + ' '}${message}`);
+  }
+  if (diagnostics.errors.length > 0) {
+    return { config, diagnostics, results: [], normalized: null };
+  }
+
+  // LOAD + NORMALIZE + DERIVE (shared across targets)
+  const trees = await loadTokenTrees(cwd, config.tokens, diagnostics);
+  const normalized = normalize(trees, config, diagnostics);
+  derive(normalized, config, diagnostics);
+  // Authored aliases pointing at slots DERIVE materializes (e.g. a component
+  // token aliasing `{semantic.radius.full}`) resolve here — see normalize.js.
+  resolveDeferredAliases(normalized, diagnostics);
+
+  // TST1204 (cross-mode carry-over) can only be judged once every alias has a
+  // value: the slot's own text is identical in both modes when the per-mode
+  // value lives on the alias target, which is exactly how the binding-layer
+  // adoption pattern works. See reportModeCarryOver.
+  reportModeCarryOver(normalized, config, diagnostics);
+
+  // The engine's one non-negotiable input (AL5 — see derive.js for why it moved
+  // here). Checked after every alias has had its chance to resolve, and only
+  // when nothing upstream already explains the absence: a dangling alias or an
+  // unparseable color makes this token missing as a *consequence*, and reporting
+  // both sends the user to fix the symptom.
+  const primaryMissing = Object.values(normalized.modes).some(
+    (m) => m.get('semantic.color.primary.solid')?.value === undefined,
+  );
+  const upstream = ['TST1002', 'TST1104', 'TST1105', 'TST1106'].some((c) => diagnostics.has(c));
+  if (primaryMissing && !upstream) {
+    diagnostics.error(
+      'TST1201',
+      'semantic.color.primary.solid is not authored — it is the one token the derivation engine cannot invent.',
+      {
+        // The old text blamed `config derivation.require`, which most configs
+        // (including `transtyle init`'s own scaffold) never set. It is an engine
+        // invariant, not a consequence of configuration.
+        hint: 'Author it as `semantic.color.primary.solid` (your brand color). A bare `semantic.color.primary` is a different path — the role grid anchors on the `.solid` cell.',
+      },
+    );
+  }
+
+  runChecks(normalized, config, diagnostics);
+
+  // derivation.require: listed slots must be authored, not derived. Color
+  // roles require their `.solid` anchor cell (the role grid's authored anchor,
+  // was `.base` pre-revision); other requires (e.g. radius.md) are bare paths.
+  for (const req of config.derivation?.require ?? []) {
+    const kind = normalized.modes[normalized.defaultMode].get(`${req}.solid`)?.provenance.kind
+      ?? normalized.modes[normalized.defaultMode].get(req)?.provenance.kind;
+    if (kind === 'derived' || kind === undefined) {
+      diagnostics.error('TST1202', `Required token is not authored: ${req}`);
+    }
+  }
+
+  const targetNames = targets?.length ? targets : Object.keys(config.targets ?? {});
+  const results = [];
+
+  for (const name of targetNames) {
+    const targetConfig = config.targets?.[name];
+    if (!targetConfig) {
+      // AL5: two different mistakes reached the same dead-end message. A typo
+      // needs the near name; a correctly-spelled exporter that simply isn't in
+      // this config needs to be told to add it. Neither is "check instance
+      // names" with the names withheld.
+      const configured = Object.keys(config.targets ?? {});
+      const near = nearestName(name, configured);
+      const known = knownExporters.includes(name);
+      diagnostics.error(
+        'TST1301',
+        `Target "${name}" is not configured in transtyle.config.json`,
+        {
+          hint: near
+            ? `Did you mean "${near}"? Configured targets: ${configured.join(', ') || '(none)'}`
+            : known
+              ? `"${name}" is a known exporter but this config doesn't use it — add it under "targets" with an "output" directory.`
+              : `Configured targets: ${configured.join(', ') || '(none)'}`,
+        },
+      );
+      continue;
+    }
+    if (diagnostics.errors.length > 0) break; // never emit with errors present
+
+    // Target instances: the config key is the instance name; `exporter` selects
+    // the plugin (defaults to the key), so one exporter can be configured twice
+    // with different options (docs/specs/configuration.md#target-instances).
+    const exporter = await loadExporter(targetConfig.exporter ?? name);
+
+    // Validate this instance's options against the exporter's own schema (audit
+    // A8): unknown or mis-typed options are errors. Exporters without options
+    // reject any options object; exporters with options declare `optionsSchema`.
+    if (targetConfig.options !== undefined) {
+      const schema = exporter.optionsSchema ?? { type: 'object', additionalProperties: false };
+      for (const { path: p, message } of validate(targetConfig.options, schema)) {
+        diagnostics.error('TST1011', `target "${name}" options: ${p === '(root)' ? '' : p + ' '}${message}`);
+      }
+    }
+    if (diagnostics.errors.length > 0) break; // don't emit with invalid options
+
+    // RESOLVE + EMIT: exporter returns file descriptions; only core touches the filesystem.
+    const ctx = {
+      config, targetConfig, formatColor, formatHslTriplet, formatHex, contrastRatio, mix,
+      projectName: config.name ?? 'design-system',
+      // Sibling-target manifest (docs/specs/exporters/storybook.md#composition):
+      // name, exporter, and output dir of every configured target — never their
+      // resolutions. Lets composition-capable exporters reference sibling
+      // ARTIFACT PATHS, keeping the no-cross-target-coupling invariant.
+      siblings: Object.entries(config.targets ?? {}).map(([n, t]) => ({
+        name: n, exporter: t.exporter ?? n, output: t.output ?? `dist/${n}`,
+      })),
+    };
+    const { files, coverage } = exporter.emit(normalized, ctx);
+
+    const outDir = path.resolve(cwd, targetConfig.output ?? `dist/${name}`);
+    const written = [];
+    if (emit) {
+      await mkdir(outDir, { recursive: true });
+      for (const f of files) {
+        await writeFile(path.join(outDir, f.path), f.contents, 'utf8');
+        written.push(path.relative(cwd, path.join(outDir, f.path)));
+      }
+      // Build manifest + machine-readable report (docs/specs/validation-and-coverage.md)
+      const report = buildReport(name, targetConfig, coverage, diagnostics, written);
+      await writeFile(path.join(outDir, 'report.json'), JSON.stringify(report, null, 2) + '\n', 'utf8');
+      written.push(path.relative(cwd, path.join(outDir, 'report.json')));
+    }
+    // `emitted` carries the file *specs* (path + contents) even when emit is
+    // off — `transtyle diff` re-emits both sides in-memory to compute per-target
+    // impact without writing anything. `files` stays the written paths.
+    results.push({ target: name, files: written, coverage, emitted: files });
+  }
+
+  return { config, diagnostics, results, normalized };
+}
+
+function buildReport(target, targetConfig, coverage, diagnostics, files) {
+  const counts = {};
+  for (const item of coverage) counts[item.class] = (counts[item.class] ?? 0) + 1;
+  return {
+    $schema: 'https://transtyle.dev/schemas/report/v0.json',
+    target,
+    options: targetConfig.options ?? {},
+    generatedBy: 'transtyle 0.1.0 (walking skeleton)',
+    coverage: { counts, items: coverage },
+    diagnostics: diagnostics.items,
+    files,
+  };
+}

package/src/load.js

@@ -0,0 +1,136 @@
+/** LOAD stage: config discovery + token file reading (docs/architecture/pipeline.md#1-load). */
+
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+export async function loadConfig(cwd) {
+  const file = path.join(cwd, 'transtyle.config.json');
+  let raw;
+  try {
+    raw = await readFile(file, 'utf8');
+  } catch {
+    throw new Error(`No transtyle.config.json found in ${cwd}`);
+  }
+  const config = JSON.parse(raw);
+  if (!config.tokens?.length) throw new Error('Config error: "tokens" must list at least one glob.');
+  return { config, configPath: file };
+}
+
+/** Minimal glob: supports literal paths and single-`*` segments (e.g. "tokens/*.tokens.json"). */
+async function expandGlob(cwd, pattern) {
+  if (pattern.includes('**')) throw new Error(`Skeleton glob does not support "**": ${pattern}`);
+  const segs = pattern.split('/');
+  let paths = [cwd];
+  for (const seg of segs) {
+    const next = [];
+    for (const p of paths) {
+      if (seg.includes('*')) {
+        const re = new RegExp('^' + seg.split('*').map(escapeRe).join('.*') + '$');
+        let entries = [];
+        try { entries = await readdir(p, { withFileTypes: true }); } catch { /* missing dir */ }
+        for (const e of entries) if (re.test(e.name)) next.push(path.join(p, e.name));
+      } else {
+        next.push(path.join(p, seg));
+      }
+    }
+    paths = next;
+  }
+  return paths.sort(); // deterministic order
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Token entries are strings (globs) or objects `{ files, mode }` — the latter
+ * declares a mode-scoped layer: a pure DTCG file whose values apply to one
+ * mode of one dimension (docs/specs/configuration.md#token-layering).
+ */
+export async function loadTokenTrees(cwd, entries, diagnostics) {
+  const trees = [];
+  const seenExtensionNamespaces = new Set(); // compile-wide, so TST1304 fires once per namespace, not once per file
+  for (const entry of entries) {
+    const globs = typeof entry === 'string' ? [entry] : [].concat(entry.files);
+    const modeScope = typeof entry === 'string' ? undefined : entry.mode;
+    for (const g of globs) {
+      const files = await expandGlob(cwd, g);
+      if (files.length === 0)
+        diagnostics.warn('TST1001', `Token glob matched no files: ${g}`, {
+          // AL5: this is usually the whole story behind every error that
+          // follows, so it should be the one that tells you where it looked.
+          hint: `Resolved relative to ${cwd}. Check the path in "tokens" in transtyle.config.json.`,
+        });
+      for (const f of files) {
+        try {
+          const tree = JSON.parse(await readFile(f, 'utf8'));
+          const rel = path.relative(cwd, f);
+          validateTokenTree(tree, rel, diagnostics, seenExtensionNamespaces);
+          trees.push({ file: rel, tree, modeScope });
+        } catch (e) {
+          // Relative path (AL5): an absolute one buries the filename that
+          // matters at the end of a long, uninformative prefix.
+          diagnostics.error('TST1002', `Failed to parse ${path.relative(cwd, f)}: ${e.message}`);
+        }
+      }
+    }
+  }
+  return trees;
+}
+
+// ---------- structural DTCG validation (T10, docs/specs/validation-and-coverage.md) ----------
+
+/** The DTCG $type set this IR understands (docs/architecture/ir.md#foundation-dtcg-superset). */
+const DTCG_TYPES = new Set([
+  'color', 'dimension', 'fontFamily', 'fontWeight', 'duration', 'cubicBezier', 'number',
+  'typography', 'shadow', 'border', 'gradient', 'transition', 'strokeStyle',
+]);
+/** The three-tier token model (docs/architecture/ir.md#the-three-tier-token-model). */
+const TIERS = new Set(['option', 'semantic', 'component']);
+/** Transtyle's own reserved `$extensions` namespaces (proposal 0001 §4.4) — anything else is foreign. */
+const KNOWN_EXTENSION_NAMESPACES = new Set(['transtyle.modes', 'transtyle.role', 'transtyle.state-mechanism']);
+
+/**
+ * Catches authoring mistakes `collectTokens()`'s permissive walk would
+ * otherwise silently swallow: a top-level group outside the three tiers, a
+ * node that clearly meant to be a token but has no `$value`, an unrecognized
+ * `$type` (still carried, just opaque to derivation), and foreign
+ * `$extensions` namespaces (carried through untouched, surfaced once).
+ * Runs per loaded file, before merging — `seenNamespaces` is shared across
+ * the whole `loadTokenTrees()` call so TST1304 fires once per compile.
+ */
+export function validateTokenTree(tree, file, diagnostics, seenNamespaces = new Set()) {
+  for (const key of Object.keys(tree)) {
+    if (key.startsWith('$')) continue;
+    if (!TIERS.has(key)) {
+      diagnostics.warn('TST1305', `${file}: top-level group "${key}" is not option/semantic/component`);
+    }
+  }
+  const walk = (node, path_) => {
+    if (node === null || typeof node !== 'object' || Array.isArray(node)) return;
+    const localType = node.$type;
+    if (node.$extensions && typeof node.$extensions === 'object') {
+      for (const ns of Object.keys(node.$extensions)) {
+        if (!KNOWN_EXTENSION_NAMESPACES.has(ns) && !seenNamespaces.has(ns)) {
+          seenNamespaces.add(ns);
+          diagnostics.info('TST1304', `${file}: foreign $extensions namespace "${ns}" carried through untouched (not a transtyle namespace)`);
+        }
+      }
+    }
+    const hasValue = '$value' in node;
+    const childKeys = Object.keys(node).filter((k) => !k.startsWith('$'));
+    if (!hasValue && childKeys.length === 0 && localType !== undefined) {
+      diagnostics.error('TST1302', `${path_.join('.')}: declares $type "${localType}" but has neither $value nor child tokens`);
+      return;
+    }
+    if (hasValue) {
+      if (localType !== undefined && !DTCG_TYPES.has(localType)) {
+        diagnostics.warn('TST1306', `${path_.join('.')}: unknown $type "${localType}" — carried through opaque (no type-specific parsing or derivation)`);
+      }
+      return;
+    }
+    for (const [key, child] of Object.entries(node)) {
+      if (key.startsWith('$')) continue;
+      walk(child, [...path_, key]);
+    }
+  };
+  walk(tree, []);
+}

package/src/nearest.js

@@ -0,0 +1,39 @@
+/**
+ * "Did you mean …?" — shared by config validation (unknown key), target
+ * resolution (unknown target instance), and the CLI's `explain` (unknown slot).
+ *
+ * AL5 rationale: every one of those three errors used to end at "X is not
+ * valid" while the code was holding the list of things that ARE valid. A typo
+ * is the most common way each is reached, so the suggestion is not a nicety —
+ * it is usually the entire fix.
+ */
+
+/** Classic Levenshtein edit distance. */
+export function levenshtein(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+  return dp[a.length][b.length];
+}
+
+/**
+ * The closest candidate to `name`, or null when nothing is close enough.
+ * The threshold scales with the name's length (a third of it, at least 1, at
+ * most 3) so short names don't match everything and long ones still tolerate a
+ * couple of slips — guessing wildly is worse than not guessing.
+ */
+export function nearestName(name, candidates) {
+  const limit = Math.max(1, Math.min(3, Math.floor(name.length / 3)));
+  let best = null;
+  for (const c of candidates) {
+    const d = levenshtein(name, c);
+    if (d <= limit && (!best || d < best.d)) best = { c, d };
+  }
+  return best?.c ?? null;
+}