@transtyle/core 0.1.0-alpha.0

package/src/normalize.js

@@ -0,0 +1,367 @@
+/**
+ * NORMALIZE stage: canonical per-mode IR with alias resolution and provenance
+ * (docs/architecture/pipeline.md#2-normalize).
+ */
+
+import { collectTokens, collectRoleArchetypes, mergeTrees, aliasTarget, comboKey, expandModeMatrix, PROVENANCE, COLOR_ROLES } from '@transtyle/ir';
+import { parseColor } from './color.js';
+
+/** Matches `semantic.color.<role>.solid` — the anchor cell an entire role grid
+ *  (hover/active/tint/outline/on-colors, ~16 slots) fans out from. */
+const ROLE_SOLID = /^semantic\.color\.([\w-]+)\.solid$/;
+
+/**
+ * @returns {{ modes: Record<string, Map<string, Entry>>, modeDimension: string }}
+ * Entry = { type, value, provenance }
+ * Color values are parsed to { l, c, h, alpha }; other types kept as authored.
+ *
+ * Multi-dimension modes (T8, docs/architecture/ir.md#modes): every configured
+ * dimension is resolved independently, then combos are the cross-product,
+ * keyed `dim1val+dim2val+...` (dimension-declaration order). Most exporters
+ * only know about the *first* declared dimension (conventionally
+ * `color-scheme`) — they've always read `normalized.modes.light`/`.dark`, so
+ * those single-dimension-value keys stay as aliases into the combo whose
+ * every OTHER dimension sits at its own default. This is the whole back-compat
+ * story: a single-dimension config (today's Acme/Cathode) degenerates to
+ * exactly the old behavior (combo keys equal old mode names 1:1).
+ */
+export function normalize(tokenTrees, config, diagnostics) {
+  const dimEntries = Object.entries(config.modes ?? {});
+  if (dimEntries.length === 0) dimEntries.push(['color-scheme', { values: ['light'], default: 'light' }]);
+  const dimDefaults = new Map(dimEntries);
+  const primaryDimName = dimEntries[0][0];
+
+  // AL5 mode-shape sweep: the FIRST dimension is the polarity axis — derive.js
+  // reads dark/light off it (`isDark` keys on `modeDimension`), and exporters
+  // bind the `modes.light`/`modes.dark` aliases, which only exist for the
+  // primary dimension's values. So `color-scheme` declared anywhere but first
+  // silently drops dark mode: the authored dark values still land in their
+  // combos, but no exporter can reach them, and nothing warned. Found by
+  // compiling a density-first config against every exporter — all emitted a
+  // dark block filled with light values.
+  //
+  // This is an ERROR, not a warning: the output is guaranteed wrong (a dark
+  // block filled with light values), and a warning ships that under the default
+  // `failOn: error`. There is no coherent "make it work" fix — even a corrected
+  // alias would leave `isDark` false for a non-primary color-scheme, so derived
+  // dark values compute as light. Reordering `modes` is the only fix, so the
+  // build must stop. Gated on `color-scheme` carrying more than one value: with
+  // a single value there is no non-default scheme to drop, so nothing is wrong
+  // and erroring would be a false failure.
+  if (
+    dimEntries.length > 1 &&
+    dimDefaults.has('color-scheme') &&
+    dimDefaults.get('color-scheme').values.length > 1 &&
+    primaryDimName !== 'color-scheme'
+  ) {
+    diagnostics.error(
+      'TST1112',
+      `"color-scheme" is declared but "${primaryDimName}" is the first mode dimension — light/dark is bound to the first dimension, so this design system's dark mode will not reach any exporter.`,
+      { hint: 'List "color-scheme" first in `modes`. Only the first dimension carries light/dark polarity; the others are extra axes exporters mostly drop.' },
+    );
+  }
+
+  // Base layers merge into the token forest; mode-scoped layers inject values
+  // into the same modeValues structure that inline $extensions produce — the
+  // two authoring forms are equivalent by construction (ADR-0009).
+  const merged = mergeTrees(
+    tokenTrees.filter((t) => !t.modeScope).map((t) => t.tree),
+    (p) => diagnostics.warn('TST1103', `Token defined more than once (last wins): ${p}`),
+  );
+  const raw = collectTokens(merged);
+  const roleArchetypes = collectRoleArchetypes(merged, diagnostics);
+
+  for (const layer of tokenTrees.filter((t) => t.modeScope)) {
+    const scopeEntries = Object.entries(layer.modeScope);
+    if (scopeEntries.length !== 1) {
+      diagnostics.error('TST1110', `${layer.file}: a mode-scoped layer must target exactly one dimension`);
+      continue;
+    }
+    const [scopeDim, scopeMode] = scopeEntries[0];
+    if (!config.modes?.[scopeDim]?.values.includes(scopeMode)) {
+      diagnostics.error('TST1109', `${layer.file}: unknown mode "${scopeDim}: ${scopeMode}" (not declared in config.modes)`);
+      continue;
+    }
+    for (const [tokenPath, tok] of collectTokens(layer.tree)) {
+      const base = raw.get(tokenPath);
+      if (!base) {
+        diagnostics.warn('TST1107', `${layer.file}: mode value for unknown token "${tokenPath}" (no default-mode value exists) — skipped`);
+        continue;
+      }
+      base.modeValues[scopeDim] ??= {};
+      if (base.modeValues[scopeDim][scopeMode] !== undefined) {
+        diagnostics.warn('TST1108', `${tokenPath}: ${scopeDim}=${scopeMode} value overridden by later layer ${layer.file}`);
+      }
+      base.modeValues[scopeDim][scopeMode] = tok.value;
+    }
+  }
+
+  // `autoDark` reclassifies a cross-mode carry-over's provenance (see
+  // reportModeCarryOver below for the diagnostic half, and the note there on
+  // why it can only be judged after aliases resolve).
+  const autoDark = Boolean(config?.derivation?.autoDark);
+
+  const combos = expandModeMatrix(dimEntries);
+  const modes = {};
+  const comboDims = {};
+  for (const { key, values } of combos) {
+    const map = new Map();
+    for (const [tokenPath, tok] of raw) {
+      // Per-dimension resolution, applied independently and left-to-right
+      // (docs/architecture/ir.md#modes "resolved per-dimension independently"):
+      // a token overriding on more than one non-default dimension at once is
+      // the rare pathological pair the spec defers; last dimension wins there.
+      let value = tok.value;
+      let overriddenMode = null;
+      let autoDarkCarried = false;
+      for (const [dimName] of dimEntries) {
+        const v = values[dimName];
+        if (v === dimDefaults.get(dimName).default) continue;
+        const override = tok.modeValues?.[dimName]?.[v];
+        if (override !== undefined) { value = override; overriddenMode = `${dimName}=${v}`; }
+        else if (dimName === 'color-scheme' && autoDark) {
+          const role = tokenPath.match(ROLE_SOLID)?.[1];
+          if (role && (COLOR_ROLES.includes(role) || roleArchetypes.has(role))) autoDarkCarried = true;
+        }
+      }
+      map.set(tokenPath, {
+        type: tok.type,
+        rawValue: value,
+        provenance: {
+          kind: autoDarkCarried ? PROVENANCE.DERIVED : PROVENANCE.AUTHORED,
+          mode: overriddenMode ?? key,
+          ...(autoDarkCarried ? { rule: 'auto-dark-carry(constant)@standard@1' } : {}),
+        },
+      });
+    }
+    // Resolve aliases with cycle detection, then parse values.
+    for (const tokenPath of map.keys()) resolveEntry(map, tokenPath, [], diagnostics);
+    modes[key] = map;
+    comboDims[key] = values;
+  }
+
+  // Back-compat aliases: `modes.light` / `modes.dark` (or whatever the first
+  // dimension's values are) point at the combo where every OTHER dimension
+  // sits at ITS OWN default — exactly what every pre-T8 exporter means.
+  const otherDefaults = Object.fromEntries(dimEntries.slice(1).map(([n, d]) => [n, d.default]));
+  const dimNames = dimEntries.map(([n]) => n);
+  for (const v of dimDefaults.get(primaryDimName).values) {
+    modes[v] = modes[comboKey(dimNames, { [primaryDimName]: v, ...otherDefaults })];
+  }
+
+  return {
+    modes,
+    modeDimension: primaryDimName,
+    defaultMode: dimDefaults.get(primaryDimName).default,
+    modeValues: dimDefaults.get(primaryDimName).values,
+    dimensions: Object.fromEntries(dimEntries),
+    dimensionNames: dimNames,
+    comboDims,
+    allCombos: combos.map((c) => c.key),
+    roleArchetypes,
+  };
+}
+
+/** Structural equality for resolved values (colors are `{l,c,h,alpha}`). */
+const sameValue = (a, b) =>
+  a === b || (a !== null && b !== null && typeof a === 'object' && typeof b === 'object' && JSON.stringify(a) === JSON.stringify(b));
+
+/**
+ * TST1204: a role's `.solid` anchor drives its whole grid (~16 derived slots —
+ * hover/active/tint/outline/on-colors), so when the default-mode color reaches
+ * a non-default `color-scheme` value unchanged, the ENTIRE grid is that scheme's
+ * theme. Not an absence (TST1201/1203 cover that): a value that's present, looks
+ * complete, and never changed. Documented, default behavior (`diagnostics.md`,
+ * "My brand color is identical in dark mode") — `info`, not a mistake — but
+ * nothing surfaced it except the docs page.
+ *
+ * **Runs after aliases resolve, and compares resolved values.** It used to run
+ * inside NORMALIZE's per-mode loop, testing only whether the catalog slot itself
+ * carried a mode override — which is false for every design system adopted the
+ * way this project recommends. Carbon binds `semantic.color.danger.solid` to
+ * `{semantic.color.carbon.support-error}`, and it is the *alias target* that
+ * carries the dark value: the alias string is identical in both modes, so the
+ * old check called it a silent carry-over while the emitted dark theme was in
+ * fact a different red. Four of Carbon's seven notes were wrong that way. The
+ * condition is now both halves — no per-mode value authored ON the slot (so an
+ * explicit, deliberately identical dark value stays silent) AND the resolved
+ * colors actually being equal.
+ *
+ * Reported once per (role, scheme value) regardless of how many OTHER dimensions
+ * multiply the combos sharing that fact (`dark+comfortable` and `dark+compact`
+ * are one carry-over, not two). Fires whether or not `autoDark` is on: autoDark
+ * does not compute a distinct color for this slot (docs/exercises/
+ * phase0-shadcn.md F7 — `darkBrandAdjust` is a still-open research question),
+ * so the color genuinely is the carried-over one either way. What autoDark
+ * changes is provenance: without it the carry-over is misclassified `authored`;
+ * with it it's `derived`, so `report.json` shows synthetic dark-theme coverage
+ * honestly. (That reclassification only reaches non-aliased slots — an aliased
+ * carry-over stays `aliased`, which is accurate about where the value came from
+ * but doesn't get autoDark's coverage honesty. Separate question, left alone.)
+ */
+export function reportModeCarryOver(normalized, config, diagnostics) {
+  const DIM = 'color-scheme';
+  const dim = normalized.dimensions?.[DIM];
+  if (!dim) return;
+  const autoDark = Boolean(config?.derivation?.autoDark);
+  const reported = new Set();
+
+  for (const key of normalized.allCombos) {
+    const dims = normalized.comboDims[key];
+    const scheme = dims[DIM];
+    if (scheme === dim.default) continue;
+    const map = normalized.modes[key];
+    const base = normalized.modes[comboKey(normalized.dimensionNames, { ...dims, [DIM]: dim.default })];
+    if (!map || !base) continue;
+
+    for (const [tokenPath, entry] of map) {
+      const role = tokenPath.match(ROLE_SOLID)?.[1];
+      if (!role || !(COLOR_ROLES.includes(role) || normalized.roleArchetypes.has(role))) continue;
+      // Only roles the user actually supplied. Running after DERIVE means every
+      // derived role anchor (`accent.solid` aliasing primary, `danger.solid`
+      // hue-anchored from it) is in the map too, and each of them carries over
+      // for exactly one reason: the authored anchor did. Reporting them would
+      // print eight consequences of one cause — the noise AL5 removed
+      // everywhere else.
+      if (!['authored', 'aliased'].includes(entry.provenance?.kind)) continue;
+      // An explicit per-mode value on the slot itself is a decision, however it
+      // compares — never second-guessed here.
+      if (entry.provenance?.mode === `${DIM}=${scheme}`) continue;
+      const baseline = base.get(tokenPath);
+      if (!baseline || !sameValue(entry.value, baseline.value)) continue;
+
+      const dedupeKey = `${tokenPath}|${scheme}`;
+      if (reported.has(dedupeKey)) continue;
+      reported.add(dedupeKey);
+      diagnostics.info(
+        'TST1204',
+        `${tokenPath} has no authored value for ${DIM}=${scheme} — the ${dim.default}-mode value carries over unchanged, and so does its whole derived grid`,
+        autoDark
+          ? { hint: `Author ${tokenPath} for ${DIM}=${scheme} if this role should differ in that mode. \`derivation.autoDark\` is on, so this carry-over is now classified "derived" in coverage — but it does not yet compute a distinct color (that transform is still an open research question; see the roadmap).` }
+          : { hint: `Author ${tokenPath} for ${DIM}=${scheme} if this role should differ in that mode. This is default behavior — nothing is broken.` },
+      );
+    }
+  }
+}
+
+/**
+ * An alias whose target isn't in the map *yet*. Catalog slots the DERIVE stage
+ * materializes (`radius.full`, the role grid, the elevation ladder) don't exist
+ * at NORMALIZE time, so authoring `{semantic.radius.full}` — the very style
+ * ir.md's component-layer sketch uses — must not be judged dangling here.
+ * These entries are re-resolved by resolveDeferredAliases() after DERIVE; only
+ * then, if the target still doesn't exist, is it a real dangling alias.
+ */
+const DEFERRED = Symbol('deferred-alias');
+/** Resolution failed because of an alias cycle, already reported as TST1104. */
+const CYCLE = Symbol('alias-cycle');
+
+/**
+ * Report one cycle once (AL5). The resolver reaches a two-token loop from both
+ * ends, so the same cycle was printed twice with the chain rotated — two
+ * different message strings describing one mistake, which de-duplication by
+ * message cannot catch. Keying on the sorted member set makes any rotation of
+ * the same loop a single report; the chain is still printed in traversal order,
+ * because that is what shows the user how the loop closes.
+ */
+const reportedCycles = new WeakMap();
+function reportCycle(diagnostics, chain) {
+  let seen = reportedCycles.get(diagnostics);
+  if (!seen) reportedCycles.set(diagnostics, (seen = new Set()));
+  const key = [...new Set(chain)].sort().join('|');
+  if (seen.has(key)) return;
+  seen.add(key);
+  diagnostics.error('TST1104', `Alias cycle: ${chain.join(' → ')}`, {
+    hint: 'Break the loop: one of these tokens has to hold a literal value.',
+  });
+}
+
+function resolveEntry(map, tokenPath, stack, diagnostics) {
+  const entry = map.get(tokenPath);
+  if (!entry) return undefined;
+  if (entry.value !== undefined) return entry;
+  if (entry.pendingAlias) return DEFERRED;
+  if (stack.includes(tokenPath)) {
+    reportCycle(diagnostics, [...stack, tokenPath]);
+    // AL5: a distinct sentinel, not `undefined`. Returning `undefined` made the
+    // caller report TST1105 "dangling alias" on top of the cycle — which is
+    // false (the target exists; it just loops) and doubled the output on the
+    // exact error where the chain is already printed in full.
+    return CYCLE;
+  }
+  let raw = entry.rawValue;
+  const target = aliasTarget(raw);
+  if (target) {
+    // Absent target: possibly derived later — defer rather than erroring.
+    // A target that IS present but failed to resolve (bad color syntax, cycle)
+    // is a genuine failure now, exactly as before.
+    if (!map.has(target)) {
+      entry.pendingAlias = target;
+      return DEFERRED;
+    }
+    const resolved = resolveEntry(map, target, [...stack, tokenPath], diagnostics);
+    if (resolved === DEFERRED) {
+      entry.pendingAlias = target;
+      return DEFERRED;
+    }
+    if (resolved === CYCLE) return CYCLE; // already reported as TST1104
+    if (!resolved) {
+      diagnostics.error('TST1105', `Dangling alias in ${tokenPath}: {${target}}`, {
+        hint: `Nothing resolves to "${target}". Check the tier prefix (option./semantic./component.) and the spelling.`,
+      });
+      return undefined;
+    }
+    entry.type = entry.type ?? resolved.type;
+    entry.value = resolved.value;
+    entry.provenance = { kind: 'aliased', target, mode: entry.provenance.mode };
+    return entry;
+  }
+  try {
+    entry.value = entry.type === 'color' ? parseColor(raw) : raw;
+  } catch (e) {
+    diagnostics.error('TST1106', `${tokenPath}: ${e.message}`);
+    return undefined;
+  }
+  return entry;
+}
+
+/**
+ * Post-DERIVE pass: resolve every alias deferred at NORMALIZE time, now that
+ * the derived catalog slots exist. Still-missing targets are the real dangling
+ * aliases and get TST1105 here — same code, same message, just diagnosed after
+ * the stage that could legitimately have supplied the target.
+ */
+export function resolveDeferredAliases(normalized, diagnostics) {
+  const seen = new Set();
+  for (const map of Object.values(normalized.modes)) {
+    if (!map || seen.has(map)) continue; // modes.light/dark alias the combo maps
+    seen.add(map);
+    for (const tokenPath of [...map.keys()]) resolvePending(map, tokenPath, [], diagnostics);
+  }
+}
+
+function resolvePending(map, tokenPath, stack, diagnostics) {
+  const entry = map.get(tokenPath);
+  if (!entry || !entry.pendingAlias) return entry;
+  if (stack.includes(tokenPath)) {
+    reportCycle(diagnostics, [...stack, tokenPath]);
+    delete entry.pendingAlias;
+    return CYCLE;
+  }
+  const target = entry.pendingAlias;
+  const resolved = map.has(target)
+    ? resolvePending(map, target, [...stack, tokenPath], diagnostics)
+    : undefined;
+  delete entry.pendingAlias;
+  if (resolved === CYCLE) return CYCLE; // already reported as TST1104
+  if (!resolved || resolved.value === undefined) {
+    diagnostics.error('TST1105', `Dangling alias in ${tokenPath}: {${target}}`, {
+      hint: `Nothing resolves to "${target}" — not authored, and not produced by derivation. Check the tier prefix (option./semantic./component.) and the spelling.`,
+    });
+    return undefined;
+  }
+  entry.type = entry.type ?? resolved.type;
+  entry.value = resolved.value;
+  entry.provenance = { kind: 'aliased', target, mode: entry.provenance.mode };
+  return entry;
+}

package/src/schema/config.schema.js

@@ -0,0 +1,92 @@
+/**
+ * The `transtyle.config.json` schema — source of truth for BOTH the runtime
+ * validator (validate.js, used in compile()) and the published editor schema
+ * (scripts/gen-schemas.mjs → website/public/schemas/config/v0.json). Written in
+ * the JSON Schema subset validate.js understands; scripts/check-schemas.mjs
+ * proves the published file and this object stay identical.
+ *
+ * Matches docs/specs/configuration.md. `additionalProperties: false` at the top
+ * level and inside each target is what makes a typo an error (audit A8) instead
+ * of a silently-ignored key.
+ *
+ * NOTE: exporter `options` are intentionally `additionalProperties: true` here —
+ * each exporter validates its own options against its own schema at load time
+ * (index.js + exporter `optionsSchema`), because the shape depends on which
+ * exporter the instance selects, which this static schema can't know.
+ */
+
+const tokenLayer = {
+  anyOf: [
+    { type: 'string' },
+    {
+      type: 'object',
+      required: ['files', 'mode'],
+      additionalProperties: false,
+      properties: {
+        files: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
+        mode: { type: 'object', additionalProperties: { type: 'string' } },
+      },
+    },
+  ],
+};
+
+const modeDimension = {
+  type: 'object',
+  required: ['values'],
+  additionalProperties: false,
+  properties: {
+    values: { type: 'array', minItems: 1, items: { type: 'string' } },
+    default: { type: 'string' },
+  },
+};
+
+const target = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    output: { type: 'string' },
+    exporter: { type: 'string' },
+    options: { type: 'object' }, // validated per-exporter at load time; see note above
+  },
+};
+
+export const configSchema = {
+  type: 'object',
+  required: ['tokens'],
+  additionalProperties: false,
+  properties: {
+    $schema: { type: 'string' },
+    name: { type: 'string' },
+    tokens: { type: 'array', minItems: 1, items: tokenLayer },
+    modes: { type: 'object', additionalProperties: modeDimension },
+    derivation: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        rules: { type: 'string' },
+        autoDark: { type: 'boolean' },
+        require: { type: 'array', items: { type: 'string' } },
+      },
+    },
+    targets: { type: 'object', additionalProperties: target },
+    check: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        failOn: { type: 'string', enum: ['error', 'warning', 'approximation'] },
+        contrast: {
+          type: 'object',
+          additionalProperties: false,
+          properties: { standard: { type: 'string', enum: ['wcag21-aa', 'wcag21-aaa'] } },
+        },
+      },
+    },
+  },
+};
+
+/** Metadata added only to the *published* file (gen-schemas.mjs), not used at runtime. */
+export const configSchemaMeta = {
+  $id: 'https://transtyle.dev/schemas/config/v0.json',
+  title: 'Transtyle config (transtyle.config.json)',
+  description: 'Schema for a Transtyle project configuration file. See https://transtyle.dev/docs/configuration/.',
+};

package/src/schema/report.schema.js

@@ -0,0 +1,65 @@
+/**
+ * The `report.json` schema — the machine-readable build report core emits per
+ * target (docs/specs/validation-and-coverage.md). Source of truth for the
+ * published file (scripts/gen-schemas.mjs → website/public/schemas/report/v0.json).
+ * Unlike the config schema this is not enforced on user input — core *produces*
+ * reports — but scripts/check-schemas.mjs validates every generated report
+ * against it, so the published schema can never drift from what we actually emit.
+ */
+
+const coverageItem = {
+  type: 'object',
+  required: ['variable', 'slot', 'class'],
+  additionalProperties: false,
+  properties: {
+    variable: { type: 'string' },
+    slot: { type: 'string' },
+    class: { type: 'string', enum: ['native', 'derived', 'approximated', 'dropped', 'unsupported'] },
+    provenance: { type: 'string', enum: ['authored', 'aliased', 'derived', 'defaulted'] },
+    note: { type: 'string' },
+  },
+};
+
+const diagnostic = {
+  type: 'object',
+  required: ['severity', 'code', 'message'],
+  additionalProperties: true,
+  properties: {
+    severity: { type: 'string', enum: ['error', 'warning', 'info'] },
+    code: { type: 'string' },
+    message: { type: 'string' },
+    // AL5: optional, and deliberately separate from `message` — what is wrong
+    // and what to change are different sentences, and tools consuming the
+    // report (editors, CI annotations) want to place them differently.
+    hint: { type: 'string' },
+  },
+};
+
+export const reportSchema = {
+  type: 'object',
+  required: ['target', 'generatedBy', 'coverage', 'diagnostics', 'files'],
+  additionalProperties: false,
+  properties: {
+    $schema: { type: 'string' },
+    target: { type: 'string' },
+    options: { type: 'object' },
+    generatedBy: { type: 'string' },
+    coverage: {
+      type: 'object',
+      required: ['counts', 'items'],
+      additionalProperties: false,
+      properties: {
+        counts: { type: 'object', additionalProperties: { type: 'integer' } },
+        items: { type: 'array', items: coverageItem },
+      },
+    },
+    diagnostics: { type: 'array', items: diagnostic },
+    files: { type: 'array', items: { type: 'string' } },
+  },
+};
+
+export const reportSchemaMeta = {
+  $id: 'https://transtyle.dev/schemas/report/v0.json',
+  title: 'Transtyle build report (report.json)',
+  description: 'Schema for a Transtyle per-target build report. See https://transtyle.dev/docs/diagnostics/.',
+};

package/src/schema/validate.js

@@ -0,0 +1,93 @@
+/**
+ * A tiny, zero-dependency validator for the JSON Schema *subset* Transtyle's
+ * own schemas use (docs/specs/configuration.md, audit A7/A8). We do NOT ship a
+ * full JSON Schema engine (ajv) — core has zero external dependencies by policy
+ * (VISION non-goal / package.json). Instead, the config and report schemas are
+ * written in that subset (see config.schema.js / report.schema.js), this walker
+ * validates against them, and `scripts/gen-schemas.mjs` publishes the very same
+ * objects as real draft-2020-12 files for editors and the website. One source of
+ * truth, two consumers — `scripts/check-schemas.mjs` asserts they never diverge.
+ *
+ * Supported keywords: type, enum, const, required, properties,
+ * additionalProperties (boolean | schema), items, minItems, anyOf. That is
+ * exactly what our schemas need and no more — extend deliberately.
+ */
+
+import { nearestName } from '../nearest.js';
+
+const typeOf = (v) =>
+  v === null ? 'null'
+  : Array.isArray(v) ? 'array'
+  : typeof v === 'object' ? 'object'
+  : typeof v === 'number' ? (Number.isInteger(v) ? 'integer' : 'number')
+  : typeof v; // 'string' | 'boolean'
+
+/** integer also satisfies number; everything else is exact. */
+function typeMatches(value, type) {
+  const actual = typeOf(value);
+  const types = Array.isArray(type) ? type : [type];
+  return types.some((t) => t === actual || (t === 'number' && actual === 'integer'));
+}
+
+/**
+ * Validate `value` against `schema`. Returns an array of { path, message }
+ * (empty = valid). `path` is a dotted JSON path from the document root.
+ */
+export function validate(value, schema, path = '') {
+  const errors = [];
+  const push = (p, message) => errors.push({ path: p || '(root)', message });
+
+  if (schema.const !== undefined && value !== schema.const) {
+    push(path, `must equal ${JSON.stringify(schema.const)}`);
+  }
+  if (schema.enum && !schema.enum.some((e) => e === value)) {
+    push(path, `must be one of ${schema.enum.map((e) => JSON.stringify(e)).join(', ')}`);
+    return errors; // an out-of-enum value fails nothing else usefully
+  }
+  if (schema.type && !typeMatches(value, schema.type)) {
+    push(path, `must be ${Array.isArray(schema.type) ? schema.type.join(' or ') : schema.type}, got ${typeOf(value)}`);
+    return errors; // wrong type → downstream keyword checks are noise
+  }
+
+  if (schema.anyOf) {
+    const branchErrors = schema.anyOf.map((s) => validate(value, s, path));
+    if (!branchErrors.some((e) => e.length === 0)) {
+      push(path, `does not match any allowed shape`);
+    }
+  }
+
+  if (typeOf(value) === 'object' && (schema.properties || schema.required || 'additionalProperties' in schema)) {
+    for (const key of schema.required ?? []) {
+      if (!(key in value)) push(path, `missing required property "${key}"`);
+    }
+    const props = schema.properties ?? {};
+    const addl = schema.additionalProperties;
+    for (const [key, v] of Object.entries(value)) {
+      const childPath = path ? `${path}.${key}` : key;
+      if (props[key]) {
+        errors.push(...validate(v, props[key], childPath));
+      } else if (addl === false) {
+        // AL5: pushed at the PARENT path, not childPath — the message already
+        // names the key, and prefixing the child path rendered as
+        // `targts unknown property "targts"`. The near-miss suggestion is the
+        // whole point of rejecting unknown keys instead of ignoring them: a
+        // typo'd `targts` is otherwise a config that silently does nothing.
+        const near = nearestName(key, Object.keys(props));
+        push(path, `unknown property "${key}"${near ? ` — did you mean "${near}"?` : ''}`);
+      } else if (addl && typeof addl === 'object') {
+        errors.push(...validate(v, addl, childPath));
+      }
+    }
+  }
+
+  if (typeOf(value) === 'array') {
+    if (schema.minItems != null && value.length < schema.minItems) {
+      push(path, `must have at least ${schema.minItems} item${schema.minItems === 1 ? '' : 's'}`);
+    }
+    if (schema.items) {
+      value.forEach((item, i) => errors.push(...validate(item, schema.items, `${path}[${i}]`)));
+    }
+  }
+
+  return errors;
+}