Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
23.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Capture a theme's authored adaptation input as the theme file loads.
 *
 * `astryx theme build` resolves a theme by calling the INSTALLED core's
 * `defineTheme()`. A core that predates ordered adaptations builds its result
 * field by field and drops `adaptations` on the way in, so by the time the
 * build holds a theme object, the author's rules are gone without a trace —
 * and building anyway would emit CSS with every adaptation rule silently
 * missing.
 *
 * Rather than re-deriving the author's intent from the source (which means
 * following factories, barrels, spreads and package resolution — an incomplete
 * JS interpreter, and a bug farm), this watches the real thing happen. The
 * theme is already loaded through jiti; jiti's `virtualModules` lets us hand
 * the theme file a `@astryxdesign/core/theme` whose `defineTheme` is the
 * installed one wrapped in a recorder. Every call — in the theme file, in a
 * relative base, in an installed package, at any depth — hands us the raw
 * input before the old resolver can erase it. The JS engine does the
 * evaluating; we only observe.
 *
 * ## Lineage, not a pile of calls
 *
 * A module can define several themes, and only one of them is the theme being
 * built. Failing a build because SOME theme in the import graph uses
 * adaptations would be wrong — an unused adaptive theme sitting in the same
 * file must not fail its plain sibling. So each returned theme is associated
 * with the input it came from, and capability detection walks only the
 * selected theme's own lineage:
 *
 * - a WeakMap keyed by the returned object, for themes handled by reference;
 * - an enumerable Symbol on the returned object, because a theme is routinely
 *   OBJECT-SPREAD (`{...base, name: 'child'}`) and a spread copies enumerable
 *   symbol keys while a WeakMap entry does not survive it.
 *
 * The Symbol is scoped to one isolated load and stripped before the theme
 * reaches any output path. It cannot leak into a generated file regardless:
 * `JSON.stringify`, `Object.keys` and `Object.entries` all ignore symbol keys.
 *
 * Used only when the installed core cannot compile adaptations. A core that
 * can reports them on the resolved theme itself, which needs none of this.
 *
 * ## Reach, and its one edge
 *
 * jiti hands a module's imports back to itself only when it TRANSPILES that
 * module, so the load runs through jiti's synchronous path (see
 * `importThemeModule`), which transpiles installed ESM packages too — a
 * package whose source calls `defineTheme` is observed like any other module.
 * `patchCommonJs` covers `.cjs` source, which jiti always loads natively, by
 * wrapping the core's own CommonJS exports object for the duration of the
 * load.
 *
 * One combination stays out of reach: a `.cjs` package source resolving an
 * ESM-ONLY core. Node's `require(esm)` hands it a frozen/non-configurable module
 * namespace, which cannot be patched in place. `patchCommonJs` reports that
 * coverage gap; if the selected theme's lineage then contains an unobserved
 * member, the build fails closed rather than assuming erased adaptations were
 * absent. A package's BUILT artifact remains supported because it carries
 * `__adaptations` as observable plain data.
 *
 * The same capture also retains raw typography, color, radius, and motion axes.
 * Older cores resolve those inputs into tokens but do not expose `__axes`; the
 * CLI reconstructs the effective metadata with current core's merge semantics
 * so a later current-core child can extend the built artifact source-equivalently.
 *
 * SYNC: packages/cli/api/theme/build/build.mjs (importThemeModule)
 */

import Module, {createRequire} from 'node:module';
import * as path from 'node:path';

import {findInstalledPackage} from '../../../foundation/fs/paths.mjs';

/**
 * Marks a theme object with the raw input it was resolved from. Enumerable on
 * purpose — an object spread must carry it — and a Symbol on purpose, so it is
 * invisible to every serialization path the build uses.
 */
export const THEME_LINEAGE = Symbol.for('astryx.theme.lineage');

/** Complete private capture retained for cached exports and repeated checks. */
const retainedLineageByReference = new WeakMap();
/**
 * @typedef {object} ThemeLineage
 * @property {any} input - The raw `defineTheme()` argument.
 * @property {any} result - What the installed core returned for it.
 */

/**
 * A recorder for one isolated theme load.
 *
 * @typedef {object} CoreInterception
 * @property {Record<string, unknown>} modules - `virtualModules` for jiti.
 * @property {(theme: any) => boolean} observed - Whether authored input was captured.
 * @property {(theme: any) => void} retain - Retain capture before stripping.
 * @property {(theme: any) => any} parentOf - Exact authored `extends` value.
 * @property {(theme: any) => any[]} lineageOf - Every raw input that fed a
 *   theme, following its own `extends` chain and spread provenance.
 * @property {(theme: any) => any[]} unobservedIn - Lineage members this
 *   recorder never saw and that carry no adaptation metadata; ask before
 *   `strip`.
 * @property {(theme: any) => Record<string, any> | undefined} capturedAxesOf -
 *   Effective generative-axis metadata reconstructed from captured raw inputs.
 * @property {(theme: any) => void} strip - Remove the marker from a theme and
 *   its reachable bases, before it is used to generate anything.
 * @property {(fromFile: string) => {covered: boolean, undo: () => void}} patchCommonJs -
 *   Cover the one path `virtualModules` cannot reach and report whether every
 *   resolvable CommonJS core namespace could be wrapped.
 */

/**
 * Was this theme produced by a `defineTheme()` call the recorder saw? The
 * temporary symbol must be read before `strip`; retained WeakMap capture remains
 * available for cached retries.
 *
 * @param {any} value
 * @param {WeakMap<object, ThemeLineage>} byReference
 * @returns {boolean}
 */
// prettier-ignore
function wasObserved(value, byReference) { return Boolean(value && typeof value === 'object' && (byReference.has(value) || retainedLineageByReference.has(value) || value[THEME_LINEAGE] !== undefined)); }

const GENERATIVE_AXIS_KEYS = ['typography', 'color', 'radius', 'motion'];

/**
 * Merge generative axes exactly as current core does. The CLI needs this small
 * compatibility copy because the installed core being observed predates both
 * the public adaptation compiler and retained `__axes` metadata.
 *
 * SYNC: packages/core/src/theme/themeAdaptations.ts
 *       (resolveThemeGenerativeAxes, mergeRole)
 *
 * @param {Record<string, any> | undefined} inherited
 * @param {Record<string, any>} own
 * @returns {Record<string, any>}
 */
function mergeGenerativeAxes(inherited, own) {
  /** @param {any} root @param {any} next */
  const mergeRole = (root, next) => {
    if (!root) return next;
    if (!next) return root;
    return {
      ...root,
      ...next,
      weights:
        root.weights || next.weights
          ? {...root.weights, ...next.weights}
          : undefined,
    };
  };

  const inheritedTypography = inherited?.typography;
  const ownTypography = own.typography;
  /** @param {any} inheritedRole @param {any} ownRole @param {boolean} [followsOwnBody] */
  const resolveFamily = (inheritedRole, ownRole, followsOwnBody = false) => {
    const merged = mergeRole(inheritedRole, ownRole);
    if (!merged) return undefined;
    if (ownRole?.family) {
      return {
        ...merged,
        family: ownRole.family,
        fallbacks: ownRole.fallbacks,
      };
    }
    if (followsOwnBody) {
      return {...merged, family: undefined, fallbacks: undefined};
    }
    return {
      ...merged,
      family: inheritedRole?.family,
      fallbacks: inheritedRole?.fallbacks,
    };
  };

  let body = resolveFamily(inheritedTypography?.body, ownTypography?.body);
  let heading = resolveFamily(
    inheritedTypography?.heading,
    ownTypography?.heading,
    Boolean(ownTypography?.body?.family && !ownTypography?.heading?.family),
  );
  let code = resolveFamily(inheritedTypography?.code, ownTypography?.code);
  const weightOwner = ownTypography?.scale
    ? ownTypography
    : inheritedTypography?.scale
      ? inheritedTypography
      : undefined;
  /** @param {any} role @param {any} owner */
  const applyWeights = (role, owner) =>
    role
      ? {...role, weight: owner?.weight, weights: owner?.weights}
      : undefined;
  body = applyWeights(body, weightOwner?.body);
  heading = applyWeights(heading, weightOwner?.heading);
  code = applyWeights(code, weightOwner?.code);

  const typography =
    inheritedTypography || ownTypography
      ? {
          ...inheritedTypography,
          ...ownTypography,
          scale: ownTypography?.scale ?? inheritedTypography?.scale,
          body,
          heading,
          code,
        }
      : undefined;
  const color = own.color ?? inherited?.color;
  const radius = own.radius
    ? {...inherited?.radius, ...own.radius}
    : inherited?.radius;
  const motion = own.motion
    ? {...inherited?.motion, ...own.motion}
    : inherited?.motion;

  return {
    ...(typography ? {typography} : {}),
    ...(color ? {color} : {}),
    ...(radius ? {radius} : {}),
    ...(motion ? {motion} : {}),
  };
}

/**
 * Wrap an installed core module so every `defineTheme()` call records the raw
 * input against the theme it produced.
 *
 * Both entry points a theme can import core through are wrapped, each from its
 * OWN namespace: `@astryxdesign/core/theme` keeps the theme namespace, and the
 * package root keeps the root namespace, which exports far more (components,
 * hooks) than the theme subpath. Mapping the root at the theme namespace would
 * silently delete every one of those exports from a theme file that imports a
 * component. Every real export is preserved on each; one function is wrapped.
 *
 * Current-Core family builds also use this private recorder for exact parents;
 * standalone builds with current Core do not.
 *
 * @param {any} coreThemeModule - The installed `@astryxdesign/core/theme` namespace.
 * @param {any} [coreRootModule] - The installed `@astryxdesign/core` namespace,
 *   or a function that loads it. A function is called once, on first use.
 * @returns {CoreInterception}
 */
export function interceptCore(coreThemeModule, coreRootModule) {
  /** @type {WeakMap<object, ThemeLineage>} */
  const byReference = new WeakMap();

  /** @param {any} value @param {ThemeLineage} lineage */
  const mark = (value, lineage) => {
    if (!value || typeof value !== 'object') return;
    byReference.set(value, lineage);
    retainedLineageByReference.set(value, lineage);
    try {
      // Enumerable so a spread of this theme carries it; configurable so it
      // can be removed again before the theme is used for output.
      Object.defineProperty(value, THEME_LINEAGE, {
        value: lineage,
        enumerable: true,
        configurable: true,
        writable: true,
      });
    } catch {
      // A frozen or sealed theme keeps the WeakMap association only.
    }
  };

  /** @param {any} value @returns {ThemeLineage | undefined} */
  // prettier-ignore
  const lineageFor = value => value && typeof value === 'object' ? byReference.get(value) ?? retainedLineageByReference.get(value) ?? value[THEME_LINEAGE] : undefined;

  /**
   * One namespace, spread so exports this file does not know about still
   * reach the theme file, with `defineTheme` (if present) wrapped.
   * @param {any} namespace
   * @returns {any}
   */
  const wrapNamespace = namespace => {
    if (!namespace) return namespace;
    const real = namespace.defineTheme;
    if (typeof real !== 'function') return {...namespace};
    return {
      ...namespace,
      /** @param {any} input */
      defineTheme(input) {
        const result = real.call(namespace, input);
        mark(result, {input, result});
        return result;
      },
    };
  };

  const modules = {
    '@astryxdesign/core/theme': wrapNamespace(coreThemeModule),
  };
  /** @type {any} */
  let wrappedRoot;
  let rootRead = false;
  // jiti reads a virtual module only when a theme imports its specifier. So
  // the root, which loads all of Core, loads only for a theme that asks.
  Object.defineProperty(modules, '@astryxdesign/core', {
    enumerable: true,
    configurable: true,
    get() {
      if (!rootRead) {
        const root =
          typeof coreRootModule === 'function'
            ? coreRootModule()
            : coreRootModule;
        // Falls back to the theme namespace only when the root could not be
        // imported at all; a partial root is better than none, and a core
        // missing its own root entry is already broken.
        wrappedRoot = wrapNamespace(root ?? coreThemeModule);
        rootRead = true;
      }
      return wrappedRoot;
    },
  });

  return {
    modules,

    // prettier-ignore
    observed(theme) { return wasObserved(theme, byReference); },
    // prettier-ignore
    retain(theme) { const lineage = lineageFor(theme); if (lineage && theme && typeof theme === 'object') retainedLineageByReference.set(theme, lineage); },
    // prettier-ignore
    parentOf(theme) { const input = lineageFor(theme)?.input; return input && typeof input === 'object' && 'extends' in input ? input.extends : theme && typeof theme === 'object' ? theme.extends : undefined; },
    lineageOf(theme) {
      /** @type {any[]} */
      const inputs = [];
      /** @type {Set<any>} */
      const seen = new Set();
      /** @type {any[]} */
      const queue = [theme];

      while (queue.length > 0) {
        const value = queue.pop();
        if (!value || typeof value !== 'object' || seen.has(value)) continue;
        seen.add(value);

        // The theme itself is evidence: a built module or a plain object
        // literal carries its adaptation metadata directly, having never gone
        // through `defineTheme` at all.
        inputs.push(value);

        const lineage = lineageFor(value);
        if (lineage) {
          // The raw input is where an erased `adaptations` still lives, and
          // its own `extends` is the next link in the chain.
          if (lineage.input && typeof lineage.input === 'object') {
            queue.push(lineage.input);
          }
        }
        if (value.extends) queue.push(value.extends);
      }
      return inputs;
    },

    unobservedIn(theme) {
      // Lineage members this recorder never saw AND that carry no adaptation
      // metadata of their own. On a degraded load these are exactly the
      // themes whose adaptations, if any, were erased unobserved. Retained
      // WeakMap capture keeps this answer stable after a cached retry.
      //
      // A RAW INPUT reached through an observed result is itself evidence —
      // it is the very object the recorder captured, and only the result
      // carries the marker. Counting it as unobserved would fail every
      // degraded build, including themes whose whole lineage was seen.
      /** @type {Set<any>} */
      const observedInputs = new Set();
      for (const value of this.lineageOf(theme)) {
        const lineage = lineageFor(value);
        if (lineage?.input && typeof lineage.input === 'object') {
          observedInputs.add(lineage.input);
        }
      }

      return this.lineageOf(theme).filter(
        value =>
          value &&
          typeof value === 'object' &&
          !wasObserved(value, byReference) &&
          !observedInputs.has(value) &&
          value.adaptations === undefined &&
          value.__adaptations === undefined &&
          value.__adaptationRules === undefined,
      );
    },

    capturedAxesOf(theme) {
      /** @type {Set<any>} */
      const seen = new Set();

      /** @param {any} value @returns {Record<string, any> | undefined} */
      const visit = value => {
        if (!value || typeof value !== 'object' || seen.has(value)) {
          return undefined;
        }
        seen.add(value);

        // A built/current theme already carries the effective metadata. An
        // empty object is meaningful: it proves there are no inherited axes.
        if (value.__axes !== undefined) {
          return value.__axes &&
            typeof value.__axes === 'object' &&
            !Array.isArray(value.__axes)
            ? value.__axes
            : undefined;
        }

        const lineage = lineageFor(value);
        const input =
          lineage?.input && typeof lineage.input === 'object'
            ? lineage.input
            : value;
        const inherited = visit(input.extends);
        /** @type {Record<string, any>} */
        const own = {};
        for (const key of GENERATIVE_AXIS_KEYS) {
          if (input[key] !== undefined) own[key] = input[key];
        }
        if (!inherited && Object.keys(own).length === 0) return undefined;
        return mergeGenerativeAxes(inherited, own);
      };

      return visit(theme);
    },

    strip(theme) {
      /** @type {Set<any>} */
      const seen = new Set();
      /** @type {any[]} */
      const queue = [theme];
      while (queue.length > 0) {
        const value = queue.pop();
        if (!value || typeof value !== 'object' || seen.has(value)) continue;
        seen.add(value);
        const lineage = lineageFor(value);
        if (lineage) retainedLineageByReference.set(value, lineage);
        if (Object.hasOwn(value, THEME_LINEAGE)) {
          try {
            delete value[THEME_LINEAGE];
          } catch {
            // Best effort: a non-configurable marker is still invisible to
            // JSON.stringify / Object.keys, so it cannot reach output.
          }
        }
        if (lineage?.input && typeof lineage.input === 'object') {
          queue.push(lineage.input);
        }
        if (value.extends) queue.push(value.extends);
      }
    },

    patchCommonJs(fromFile) {
      // jiti hands a module's imports back to itself only when it transpiles
      // that module, and it never transpiles a `.cjs` file — so a package
      // whose source is `.cjs` requires the real core natively and
      // `virtualModules` never sees it. Patch mutable CommonJS exports in place;
      // when require(esm) returns a non-configurable module namespace, report
      // the coverage gap so the caller can reject any selected lineage member
      // whose adaptation intent could not be observed.
      /** @type {Array<() => void>} */
      const undo = [];
      let covered = true;

      // Only a core the theme's OWN node_modules chain can reach is one a
      // `.cjs` source dependency beside it could require. `require` also folds
      // NODE_PATH in, and pnpm's isolated layout puts every package in
      // `node_modules/.pnpm/node_modules` — which Vitest puts on NODE_PATH.
      // An ambient hit there belongs to no dependency here, so wrapping it
      // proves nothing and failing to wrap it gaps nothing.
      if (!findInstalledPackage(path.dirname(fromFile), '@astryxdesign/core')) {
        return {covered, undo: () => {}};
      }

      const requireFromTheme = createRequire(fromFile);
      /**
       * Wraps `defineTheme` on a CommonJS exports object in place, so a call
       * from a `.cjs` dependency is recorded. False when it cannot be wrapped.
       * @param {any} cjs
       */
      const wrap = cjs => {
        const real = cjs?.defineTheme;
        if (typeof real !== 'function') return true;
        const descriptor = Object.getOwnPropertyDescriptor(cjs, 'defineTheme');
        if (!descriptor || !(descriptor.writable || descriptor.configurable)) {
          return false;
        }
        try {
          Object.defineProperty(cjs, 'defineTheme', {
            ...descriptor,
            value: /** @param {any} input */ input => {
              const result = real.call(cjs, input);
              mark(result, {input, result});
              return result;
            },
          });
          undo.push(() =>
            Object.defineProperty(cjs, 'defineTheme', descriptor),
          );
          return true;
        } catch {
          // ESM namespace exotic objects may report a writable descriptor but
          // still reject redefinition. This is a real coverage failure, not an
          // absent CommonJS entry: a `.cjs` dependency can call the function
          // while the recorder cannot wrap it.
          return false;
        }
      };

      // An entry that CommonJS cannot resolve or load cannot be used by a
      // `.cjs` source dependency either, so it creates no unobserved path. It
      // is skipped, as are the entries of a package config CommonJS cannot
      // read. Throwing instead would fail every theme beside such an install.
      /** @param {string} specifier @returns {string | null} */
      const resolveEntry = specifier => {
        try {
          return requireFromTheme.resolve(specifier);
        } catch {
          return null;
        }
      };
      const themeFile = resolveEntry('@astryxdesign/core/theme');
      const rootFile = resolveEntry('@astryxdesign/core');

      // The theme subpath is small, so it is wrapped now.
      if (themeFile) {
        /** @type {any} */
        let themeExports = null;
        try {
          themeExports = requireFromTheme(themeFile);
        } catch {
          // A dependency that requires it fails the same way.
        }
        if (themeExports && !wrap(themeExports)) covered = false;
      }

      // The root loads all of Core, so it is wrapped only once this load
      // requires it. Every CommonJS require goes through `Module._load`,
      // which is watched for the load's duration. The watch reads the require
      // cache, where the root's file is keyed by its real path. So any
      // request that loads that file counts, however it is spelled. A load
      // that never requires the root leaves no path through it to observe.
      if (rootFile) {
        /** @type {any} */
        const loader = Module;
        /** Wraps the root once its file has run; false until then. */
        const wrapLoadedRoot = () => {
          const loaded = loader._cache[rootFile];
          // A CommonJS module is cached before its body runs, so a require
          // inside the root's own body sees it partly built.
          if (!loaded?.loaded) return false;
          if (!wrap(loaded.exports)) covered = false;
          return true;
        };
        if (!wrapLoadedRoot()) {
          const load = loader._load;
          /** @this {any} @param {...any} args */
          const watch = function (...args) {
            const exports = load.apply(this, args);
            if (loader._load === watch && wrapLoadedRoot()) {
              loader._load = load;
            }
            return exports;
          };
          loader._load = watch;
          // Theme loads never overlap: each caller awaits one at a time. The
          // watch is still removed only while it is the one installed.
          undo.push(() => {
            if (loader._load === watch) loader._load = load;
          });
        }
      }
      return {
        /** Read after the load: a root required during it counts. */
        get covered() {
          return covered;
        },
        undo() {
          for (const restore of undo.reverse()) {
            try {
              restore();
            } catch {
              /* best effort */
            }
          }
        },
      };
    },
  };
}