Skip to content

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

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

/* eslint-disable @typescript-eslint/no-require-imports */
/**
 * @file Validates derivedVarRegistry stays in sync with component doc files,
 * AND detects undocumented component CSS custom properties in source files.
 *
 * Three layers of checking:
 * 1. Source scan: finds all component-level CSS vars in .tsx files
 * 2. Doc check: verifies each var is documented in the doc file's vars[]
 * 3. Registry check: verifies themeable vars have derived[] entries that
 *    match the registry
 *
 * Layers 1 and 3 each used to carry a hole that let real vars through:
 *
 * - The source scan skipped every `--_*` name outright, on the theory that a
 *   private var is "internal, not themeable". It is internal, but it is still
 *   documented — `theming.vars[]` takes `private: true` for exactly this
 *   (`--_card-radius`, `--_dropdown-menu-padding`), and the derived-var
 *   pipeline is what theme authors reach it through. Skipping the prefix meant
 *   10 private vars across 12 (component, var) sites were declared in source
 *   and documented nowhere.
 * - Layer 3 narrowed its verdict to vars matching `/radius|padding/`, so any
 *   var whose name did not happen to contain those two words was exempt from
 *   ever needing a derived[] mapping. That is now an explicit allowlist
 *   (VARS_WITHOUT_DERIVED_MAPPING) instead of a name heuristic: a new var must
 *   be given a derived[] entry or be added to the list on purpose.
 */

import {describe, it, expect} from 'vitest';
import {derivedVarRegistry, getDerivedVars} from './derivedVarRegistry';
import {readdirSync, readFileSync} from 'node:fs';
import {join} from 'node:path';

const SRC_DIR = join(__dirname, '..');

type ComponentDocModule = {
  docs?: {
    theming?: {
      targets?: {className: string}[];
      vars?: {name: string}[];
      derived?: DerivedDocEntry[];
    };
  };
};

type DerivedDocEntry = {
  property: string;
  vars?: string[];
  expand?: string;
};

// ---------------------------------------------------------------------------
// Source scanning: find CSS custom property declarations in component files
// ---------------------------------------------------------------------------

/**
 * Structural/runtime vars that are NOT component-specific theming vars.
 * These are set by JS at runtime or cascade through layout — they don't
 * belong in derived[] because they aren't things theme authors write.
 */
const STRUCTURAL_VARS = new Set([
  '--container-padding',
  '--container-padding-inline',
  '--container-padding-inline-start',
  '--container-padding-inline-end',
  '--edge-inset-start',
  '--edge-inset-end',
  '--container-padding-block-start',
  '--container-padding-block-end',
  '--container-max-height',
  '--layout-padding-inner-x',
  '--layout-padding-inner-y',
  '--layout-padding-outer-x',
  '--layout-padding-outer-y',
  '--layout-padding-own-outer-x',
  '--layout-padding-own-outer-y',
  '--layout-content-width',
  '--appshell-header-height',
  '--dialog-dir-x',
  '--dialog-dir-y',
  '--indicator-color',
  '--indicator-width',
  '--table-resize-height',
  '--table-resize-offset',
  // sticky-columns plugin: opaque backdrop (overridable) + the row overlay it
  // replays on pinned cells. Structural/runtime, not themeable design tokens.
  '--table-sticky-background',
  '--table-row-overlay',
  // The width a cell's row divider draws (0 on the last row), which a pinned
  // cell's or a detail panel's own divider reads (Table/rowDivider.ts).
  // Private runtime plumbing, never authored by a theme.
  '--_table-row-divider-width',
  // A gliding row's divider, carried on the row for the glide
  // (Table/glidingDivider.ts). Private runtime plumbing.
  '--_table-row-glide-width',
  '--_table-row-glide-style',
  '--_table-row-glide-color',
  '--_table-row-glide-offset',
  '--separator-display',
  '--astryx-section-padding',
  // Private counterpart of the public token above: one ancestor Section's
  // padding, propagated down the tree. Structural, never authored by a theme.
  '--_section-padding-propagated',
  // Layout's middle row tells LayoutContent that a divider-less header or
  // footer sits beside it (Layout/layoutEdges.stylex.ts). Structural, never
  // authored by a theme.
  '--_layout-flush-block-start',
  '--_layout-flush-block-end',
  // ProgressBar's filled share of the track, written inline from `value` on
  // every render and read by the fill's transform. Runtime state, never
  // authored by a theme.
  '--_progress-bar-fill',
  // ProgressBar's touch layer (ProgressBarTouch) writes these inline on every
  // render: the touch move's duration and curve, the three-step return offset
  // and the touch minimum. The duration and curve are the progress table's
  // motion roles, which no theme sets. Runtime state, never authored by a
  // theme.
  '--_progress-bar-move',
  '--_progress-bar-curve',
  '--_progress-bar-flip',
  '--_progress-bar-min',
  // The reduced-motion pulse's duration, curve and floor, written inline from
  // the progress table on the indeterminate fill. Runtime state, never
  // authored by a theme.
  '--_progress-bar-pulse',
  '--_progress-bar-pulse-curve',
  '--_progress-bar-pulse-floor',
  // The room a layer has above the software keyboard. The layer runtime
  // writes it on each open layer from the keyboard's measured height
  // (Layer/useLayerKeyboardClearance.ts). Runtime geometry, never authored by
  // a theme.
  '--_layer-keyboard-max-block-size',
  // Written beside it: `auto` while the keyboard caps the layer, so the
  // surface scrolls from that commit. Runtime state, never authored by a theme.
  '--_layer-keyboard-overflow',
  // Also beside it: how far above the viewport's bottom a layer ends while the
  // keyboard is up. Runtime geometry, never authored by a theme.
  '--_layer-keyboard-inset-block-end',
]);

/**
 * Extract component-specific CSS custom property names from a source file.
 * Matches patterns like '--_card-radius': or '--_chat-composer-padding':
 * Excludes structural/runtime vars and standard token vars (--color-*,
 * --spacing-*, etc.).
 *
 * Private (`--_*`) vars are INCLUDED. They are internal in the sense that a
 * theme author does not set them directly, but they are still part of the
 * documented theming surface (`theming.vars[]` with `private: true`) and are
 * how derived[] entries connect a standard CSS property to a component.
 */
function extractComponentVars(filePath: string): string[] {
  const content = readFileSync(filePath, 'utf-8');
  const varPattern = /['"](--(\w[\w-]*))['"]\s*:/g;
  const vars = new Set<string>();
  let match;

  while ((match = varPattern.exec(content)) !== null) {
    const varName = match[1];
    // Skip token vars (--color-*, --spacing-*, --radius-*, etc.)
    if (
      /^--(color|spacing|radius|shadow|duration|ease|transition|font|text|size)-/.test(
        varName,
      )
    ) {
      continue;
    }
    // Skip structural vars
    if (STRUCTURAL_VARS.has(varName)) {
      continue;
    }
    // Skip vars that start with structural prefixes
    if (/^--(container-|layout-|edge-|component-)/.test(varName)) {
      continue;
    }
    vars.add(varName);
  }
  return [...vars];
}

// ---------------------------------------------------------------------------
// Discovery: scan all component directories
// ---------------------------------------------------------------------------

interface ComponentInfo {
  dir: string;
  sourceVars: string[];
  docVars: string[];
  docDerived: {property: string; vars?: string[]; expand?: string}[];
  docTargetKeys: string[];
}

function discoverComponents(): ComponentInfo[] {
  const results: ComponentInfo[] = [];
  const dirs = readdirSync(SRC_DIR, {withFileTypes: true})
    .filter(d => d.isDirectory())
    .map(d => d.name);

  for (const dir of dirs) {
    const dirPath = join(SRC_DIR, dir);
    const dirEntries = readdirSync(dirPath);
    // Find source files with component vars (.tsx and .ts, excluding tests/docs)
    const sourceFiles = dirEntries
      .filter(
        f =>
          (f.endsWith('.tsx') || f.endsWith('.ts')) &&
          !f.includes('.test.') &&
          !f.endsWith('.doc.mjs') &&
          !f.endsWith('.d.ts'),
      )
      .map(f => join(dirPath, f));

    const allVars = new Set<string>();
    for (const f of sourceFiles) {
      for (const v of extractComponentVars(f)) {
        allVars.add(v);
      }
    }

    // Only check component directories (those with a doc file named after the
    // directory). Match against the on-disk listing rather than existsSync so
    // the comparison is case-exact everywhere — on case-insensitive
    // filesystems (macOS, Windows) existsSync('theme/theme.doc.mjs') matches
    // theme/Theme.doc.mjs and pulls in a directory that CI never checks.
    if (!dirEntries.includes(`${dir}.doc.mjs`)) {
      continue;
    }
    const docPath = join(dirPath, `${dir}.doc.mjs`);

    let docVars: string[] = [];
    let docDerived: DerivedDocEntry[] = [];
    let docTargetKeys: string[] = [];
    try {
      const mod = require(docPath) as ComponentDocModule;
      docVars = (mod.docs?.theming?.vars || []).map(v => v.name);
      docDerived = mod.docs?.theming?.derived || [];
      docTargetKeys = (mod.docs?.theming?.targets || []).map(t =>
        t.className.replace(/^astryx-/, ''),
      );
    } catch {
      /* skip */
    }

    // A directory earns a check by declaring a var OR by documenting a
    // derived[] entry. Bailing on the var count alone (as this did) hid every
    // component that is themeable purely through an expansion strategy —
    // `{property: 'padding', expand: 'container'}` names no var, so such a
    // component declares nothing and its registry↔doc consistency check
    // silently never ran.
    if (allVars.size === 0 && docDerived.length === 0) {
      continue;
    }

    results.push({
      dir,
      sourceVars: [...allVars],
      docVars,
      docDerived,
      docTargetKeys,
    });
  }
  return results;
}

// ---------------------------------------------------------------------------
// Known mapping: doc dir → registry key
// ---------------------------------------------------------------------------

const DIR_TO_REGISTRY_KEY: Record<string, string> = {
  Avatar: 'avatar',
  Banner: 'banner',
  BottomSheet: 'bottom-sheet',
  Button: 'button',
  Card: 'card',
  Chat: 'chat-composer',
  ContextMenu: 'context-menu',
  Dialog: 'dialog',
  Drawer: 'drawer',
  DropdownMenu: 'dropdown-menu',
  Field: 'field',
  HoverCard: 'hover-card',
  Icon: 'icon',
  Item: 'item',
  NumberInput: 'number-input',
  Popover: 'popover',
  ProgressBar: 'progress-bar-mark',
  Section: 'section',
  SegmentedControl: 'segmented-control',
  TextArea: 'text-area',
};

/**
 * Vars that are intentionally set by one component for use by another
 * (cross-component vars). These are documented in the *consuming* component's
 * doc, not the *setting* component's doc.
 *
 * e.g. Carousel and Thumbnail set --_button-radius for their child Buttons,
 * but --_button-radius is documented in Button's doc.
 */
/**
 * Private system variables a component sets that are never a theming surface:
 * no component documents them, and a theme never writes them. Each is named
 * by the record that requires it.
 */
const PRIVATE_SYSTEM_VARS = new Set([
  // Text and Heading FR3: a container that wraps with `overflow-wrap:
  // anywhere` passes it to the Text inside it; Text reads it with a
  // `break-word` fallback. scripts/text-overflow-wrap-anywhere.test.mjs
  // keeps every such container setting it.
  '--_astryx-text-overflow-wrap',
  // List FR5 and the container-padding record's corner geometry: a bleeding
  // List passes its first and last rows the container corner they take.
  '--_list-corner-start-start',
  '--_list-corner-start-end',
  '--_list-corner-end-start',
  '--_list-corner-end-end',
  // The container-padding record's corner geometry: a rounded Card, Dialog,
  // or BottomSheet hands its block-edge radius to the shared corner
  // publication beside container().
  '--_container-corner-block-start',
  '--_container-corner-block-end',
]);

const CROSS_COMPONENT_VARS: Record<string, string[]> = {
  Carousel: ['--_button-radius'],
  Thumbnail: ['--_button-radius'],
  Chat: ['--_button-radius'],
  // AvatarGroupOverflow sets the overlap for the Avatars it lays out; Avatar
  // owns and documents it (and sets it itself when it is the group root).
  AvatarGroup: ['--_avatar-group-overlap'],
  // BreadcrumbItem tunes the DropdownMenu it opens.
  Breadcrumbs: ['--_dropdown-menu-radius', '--_dropdown-menu-padding'],
  // SelectableCard draws its selection ring through the Card shadow slot.
  SelectableCard: ['--_card-ring'],
  // Toolbar offsets the TabList indicator it hosts.
  Toolbar: ['--_tab-indicator-bottom'],
  // The destructive item variant recolors the Item it renders; Item owns,
  // documents and reads both slots.
  DropdownMenu: ['--_item-label-color', '--_item-description-color'],
  // List's edge="flush" zeroes the inline inset of the Item each ListItem
  // renders; Item owns, documents and reads it.
  List: ['--_item-inset-inline'],
  // A layer content root stops an outer Stepper's connector gap; Stepper owns,
  // documents and reads it.
  Layer: ['--step-connector-gap'],
};

/**
 * Documented vars that intentionally have NO derived[] entry — a theme author
 * cannot reach them by writing a standard CSS property, only by targeting the
 * component's own theming surface.
 *
 * This replaces a `/radius|padding/` name test that exempted every var whose
 * name did not contain those words. Each entry is a deliberate classification,
 * so a NEW var has to be argued into the list rather than slipping past on its
 * name. The list should shrink over time, not grow.
 */
const VARS_WITHOUT_DERIVED_MAPPING = new Set([
  // No standard CSS property maps onto these — they are component behaviors.
  '--button-focus-offset',
  '--button-icon-only-aspect',
  '--_avatar-group-overlap',
  '--_field-status-overlap',
  '--_codeblock-gutter-width',
  '--_tab-indicator-bottom',
  // Hit-area outset on a ::after overlay, and whether that overlay is
  // generated at all — `inset` and `content` on a pseudo-element are not
  // properties a theme author sets on the component.
  '--_thumbnail-hit-inset',
  '--_power-search-sheet-hit-inset',
  // The border width a host draws where its touch hit layer reaches past,
  // such as a divided ListItem's divider (0 on the last row).
  // The ::after layer adds it to its offset, so the band starts past the
  // border. It is the layer's geometry, not a property a theme author sets. A
  // theme changes the divider through `--border-width`, which this follows.
  '--_hit-border-bottom',
  // The interaction overlay's colour on the ::after layer of the cards:
  // written by the component's own hover and mouse `:active` arms, never a
  // value a theme author sets; the overlay colours themselves are the shared
  // interaction tokens.
  '--_press-overlay',
  // The touch press's paint at its current strength, declared once by the
  // shared overlay styles on the element the controller writes to and read
  // by whatever paints it. A theme sets `--color-overlay-pressed`, not this.
  '--_press-paint',
  '--_press-paint-image',
  // A checkbox row's touch press image, which an indicator that paints its
  // own press inherits. The row writes it from the press paint above.
  '--_indicator-press-image',
  // A CheckboxList row's own press paint, handed to its checkbox's box:
  // written by the row's own press arms, never a value a theme author sets.
  '--_checkbox-row-press-paint',
  '--_power-search-sheet-hit-content',
  // Placement and swipe lifecycle values are private Toast behavior. A theme
  // author controls the surface transform/opacity as a whole, not these values.
  '--_toast-slide-y',
  '--_toast-swipe-y',
  '--_toast-swipe-exit-y',
  '--_toast-swipe-opacity',
  '--_toast-swipe-scale',
  // Set by each ChatMessage article from its own content and read as its
  // avatar's top margin, so the avatar lines up with a name row. Content
  // state, not a value a theme author sets.
  '--_chat-avatar-offset',
  // Indentation and row-spacing metrics: --tree-list-indent is the authorable
  // step, --_tree-indent the per-row distance TreeListItem computes from it.
  // --tree-list-row-gap is applied as half a padding-block on each row wrapper,
  // not as gap on the list, so no standard property on the tree-list target
  // maps onto it; a theme sets the var directly.
  '--tree-list-indent',
  '--_tree-indent',
  '--tree-list-row-gap',
  // Published by each treeitem while it has keyboard focus and read as its
  // row's z-index, so the focused row paints above the guide lines. Focus
  // state, not a value a theme author sets.
  '--_tree-focus-z',
  // Clipped on the ONE side each on-track connector segment faces the
  // indicator from — trailing above the node, leading below it, mirrored
  // again per axis. No standard property maps onto this purpose-based seam:
  // one clip must cover the segment and its pseudo-element fill together.
  '--step-connector-gap',
  // Composed into a single box-shadow list on the card, so neither maps 1:1
  // onto boxShadow — setting one through a derived entry would clobber the
  // other.
  '--_card-elevation',
  '--_card-ring',
  // The colour inside that composed ring, for a variant only a theme knows.
  // It is one component of one shadow in the list, so no standard property
  // maps onto it either — a theme sets it beside the fill it has to contrast.
  '--selectable-card-ring-color',
  // The spinner's ring is drawn as an SVG circle, so none of its five vars is
  // a CSS property of the element carrying the theme target: `width` and
  // `borderWidth` would name a box the ring is not, a `color` mapping would
  // take the label's text color with it, and the arc fraction is a pure
  // dash-length multiplier with no standard property to attach to. They are
  // public vars a theme sets directly under a size- or shade-variant key.
  '--spinner-diameter',
  '--spinner-stroke-width',
  '--spinner-color',
  '--spinner-track-color',
  '--spinner-arc-fraction',
  // Set by a PARENT component (e.g. the destructive dropdown/context menu
  // item) to recolor the two text lines it renders. A single standard `color`
  // property cannot map onto both lines, and the root color is not what they
  // control — a theme reaches them by setting the vars directly.
  '--_item-label-color',
  '--_item-description-color',
]);

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

describe('component CSS vars are documented and themeable', () => {
  const components = discoverComponents();

  for (const {dir, sourceVars, docVars, docDerived} of components) {
    const crossVars = new Set(CROSS_COMPONENT_VARS[dir] || []);

    it(`${dir}: all source vars are in doc file`, () => {
      const undocumented = sourceVars.filter(
        v =>
          !docVars.includes(v) &&
          !crossVars.has(v) &&
          !PRIVATE_SYSTEM_VARS.has(v),
      );
      expect(
        undocumented,
        `${dir} has undocumented CSS vars in source: ${undocumented.join(', ')}. ` +
          `Add them to ${dir}.doc.mjs theming.vars[] and add a derived[] ` +
          `entry mapping the standard CSS property to the internal var.`,
      ).toEqual([]);
    });

    it(`${dir}: documented vars have derived entries for theming`, () => {
      // Every var that maps to a standard CSS property should have a
      // derived entry so theme authors can write standard CSS.
      const derivedVarNames = new Set(docDerived.flatMap(d => d.vars || []));
      const derivedExpands = docDerived
        .filter(d => d.expand)
        .map(d => d.expand);
      const hasContainerExpand = derivedExpands.includes('container');

      const missingDerived = docVars.filter(varName => {
        // Cross-component vars are handled by the owning component
        if (crossVars.has(varName)) {
          return false;
        }
        // Check if this var is covered by a derived entry
        if (derivedVarNames.has(varName)) {
          return false;
        }
        // Container expansion covers padding-related vars
        if (hasContainerExpand && varName.includes('padding')) {
          return false;
        }
        return true;
      });

      // Everything that is not explicitly classified as unmappable must have
      // a derived[] entry. (This was a `/radius|padding/` name test, which
      // exempted any var whose name lacked those words.)
      const themeableVars = missingDerived.filter(
        v => !VARS_WITHOUT_DERIVED_MAPPING.has(v),
      );

      expect(
        themeableVars,
        `${dir} has vars that should be themeable via derived[]: ${themeableVars.join(', ')}. ` +
          `Add derived[] entries in ${dir}.doc.mjs mapping standard CSS ` +
          `properties (borderRadius, padding) to these internal vars — or, if ` +
          `no standard property maps onto them, add them to ` +
          `VARS_WITHOUT_DERIVED_MAPPING with the reason.`,
      ).toEqual([]);
    });
  }
});

describe('derivedVarRegistry ↔ doc file consistency', () => {
  const components = discoverComponents();

  for (const {dir, docDerived, docTargetKeys} of components) {
    const key = DIR_TO_REGISTRY_KEY[dir];
    if (!key || docDerived.length === 0) {
      continue;
    }

    it(`${dir} (${key}): registry matches doc derived`, () => {
      const registryEntries = derivedVarRegistry[key];
      expect(registryEntries).toBeDefined();
      expect(registryEntries).toEqual(docDerived);
    });

    // generateThemeRules looks the registry up by the theme's components key,
    // so a key that is not one of the doc's targets never expands.
    it(`${dir} (${key}): registry key is a documented theming target`, () => {
      expect(docTargetKeys).toContain(key);
    });
  }

  // Catch new doc files with derived that have no registry key mapping
  it('every doc with theming.derived has a registry mapping', () => {
    const missing: string[] = [];
    for (const {dir, docDerived} of components) {
      if (docDerived.length === 0) {
        continue;
      }
      const key = DIR_TO_REGISTRY_KEY[dir];
      if (!key) {
        missing.push(
          `${dir}: has theming.derived but no DIR_TO_REGISTRY_KEY mapping. ` +
            `Add the mapping and a derivedVarRegistry entry.`,
        );
      } else if (!derivedVarRegistry[key]) {
        missing.push(
          `${dir} (${key}): has theming.derived but no derivedVarRegistry entry.`,
        );
      }
    }
    expect(missing).toEqual([]);
  });

  it('registry has no orphan entries', () => {
    const validKeys = new Set(Object.values(DIR_TO_REGISTRY_KEY));
    const orphans = Object.keys(derivedVarRegistry).filter(
      k => !validKeys.has(k),
    );
    expect(orphans).toEqual([]);
  });
});

describe('getDerivedVars', () => {
  it('returns matching entries for card borderRadius', () => {
    const result = getDerivedVars('card', 'borderRadius');
    expect(result).toHaveLength(1);
    expect(result[0].vars).toEqual(['--_card-radius']);
  });

  it('returns empty for unknown component', () => {
    expect(getDerivedVars('unknown', 'borderRadius')).toEqual([]);
  });

  it('does not resolve removed target aliases', () => {
    expect(getDerivedVars('hovercard', 'borderRadius')).toEqual([]);
    expect(getDerivedVars('textarea', 'paddingInline')).toEqual([]);
    expect(getDerivedVars('progressbar-mark', 'width')).toEqual([]);
  });

  it('returns empty for unregistered property', () => {
    expect(getDerivedVars('card', 'color')).toEqual([]);
  });

  it('marks text-area paddingInline as replacing the source property', () => {
    const result = getDerivedVars('text-area', 'paddingInline');
    expect(result).toHaveLength(1);
    expect(result[0].vars).toEqual(['--_textarea-inline-padding']);
    expect(result[0].replaces).toBe(true);
  });

  it('marks icon width and height as replacing the source property', () => {
    // spec:AST-087 FR10: the glyph reads these vars for its dimension, so a
    // raw width/height beside them would only compete with its size styles.
    for (const [property, varName] of [
      ['width', '--_icon-width'],
      ['height', '--_icon-height'],
    ]) {
      const result = getDerivedVars('icon', property);
      expect(result).toHaveLength(1);
      expect(result[0].vars).toEqual([varName]);
      expect(result[0].replaces).toBe(true);
    }
  });

  it('marks progress-bar-mark width and height as replacing the source property', () => {
    for (const [property, varName] of [
      ['width', '--_progressbar-mark-width'],
      ['height', '--_progressbar-mark-height'],
    ]) {
      const result = getDerivedVars('progress-bar-mark', property);
      expect(result).toHaveLength(1);
      expect(result[0].vars).toEqual([varName]);
      expect(result[0].replaces).toBe(true);
    }
  });
});

// ---------------------------------------------------------------------------
// Read check: a registered var nothing reads is a dead theming knob
// ---------------------------------------------------------------------------

/**
 * Every source file under packages/core/src, concatenated once.
 *
 * `--_popover-radius` shipped documented and registered while `usePopover`
 * hardcoded its radius, so `popover: {borderRadius}` set a var no element ever
 * read. Sync between source, docs and registry cannot catch that: the three
 * agreed with each other, and none of them required a reader.
 */
function readAllSource(dir: string): string {
  let out = '';
  for (const entry of readdirSync(dir, {withFileTypes: true})) {
    const path = join(dir, entry.name);
    if (entry.isDirectory()) {
      out += readAllSource(path);
    } else if (
      (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx')) &&
      !entry.name.includes('.test.') &&
      !entry.name.endsWith('.d.ts')
    ) {
      out += readFileSync(path, 'utf-8');
    }
  }
  return out;
}

describe('registered derived vars are read by component styles', () => {
  const source = readAllSource(SRC_DIR);

  for (const [component, entries] of Object.entries(derivedVarRegistry)) {
    for (const varName of entries.flatMap(e => e.vars ?? [])) {
      it(`${component}: ${varName} is read via var()`, () => {
        expect(
          source.includes(`var(${varName})`) ||
            source.includes(`var(${varName},`),
          `${varName} is registered as the derived var for a CSS property on ` +
            `\`${component}\`, but no component reads it. A theme setting that ` +
            `property would write a var nothing consumes. Read it in the ` +
            `element's StyleX styles, or drop the derived entry.`,
        ).toBe(true);
      });
    }
  }
});