Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

18.0 KB
Raw Blame
/**
 * Reading a theme file (`src/themes/<id>.css`) the way the token contract describes it, for the
 * contract and contrast tests — and for anyone filling a theme who wants the list of what is
 * still missing without running the suite.
 *
 * A theme file is one `@layer ui-theme` block with a base rule and a dark rule on fixed
 * selectors (tokens.ts, `themes/github.css`):
 *
 *   default theme   base `:root, :root[data-theme="github"]`   dark `:root.dark, :root[data-theme="github"].dark`
 *   any other       base `:root[data-theme="<id>"]`             dark `:root[data-theme="<id>"].dark`
 *
 * The base rule declares every contract name with its light value, plus the gray bridge that
 * re-points Tailwind's own palette variables. The dark rule matches the same root and declares
 * only what dark changes, so a mode is the base rule overlaid with that mode's own rule (light has
 * none of its own). Nothing else is a token.
 *
 * After the theme block, one `@layer ui-accent` block holds the theme's own accent presets
 * (tokens.ts, `ACCENT_PRESETS`), each on the theme's root with `[data-accent="<id>"]` — the
 * default theme's on a bare root as well, spelled `:root:not([data-theme])` so it never matches
 * another theme's root — and optionally a `.dark` rule that lifts the preset for dark mode:
 *
 *   default theme   light `:root:not([data-theme])[data-accent="x"], :root[data-theme="github"][data-accent="x"]`
 *   any other       light `:root[data-theme="<id>"][data-accent="x"]`   dark `…[data-accent="x"].dark`
 *
 * A preset's light rule sets `--ui-accent` and nothing outside the accent group; its dark rule
 * declares only what dark changes. In a mode a preset overlays the theme's values for that mode.
 * The accent tokens a preset leaves alone must follow it anyway: the theme derives them from
 * `--ui-accent` (a `var(--ui-accent)` in their value), or — for the label ink alone — the
 * theme's own ink for the mode, whose pairing with every preset the contrast suite measures.
 * Primer's presets set all six literally (the app's pixels are pinned), which satisfies this
 * trivially.
 */
import { DEFAULT_THEME_ID, THEME_MODES, TOKEN_GROUPS, TOKEN_NAMES } from "../tokens";
import type { ThemeId, ThemeModeName } from "../tokens";
import { parseCssRules, selectorList } from "./css";
import type { CssDeclaration } from "./css";

/** The layer every theme block lives in, so a user accent preset (`@layer ui-accent`) beats it. */
export const THEME_LAYER = "@layer ui-theme";

/** The layer a theme's accent presets live in: after `ui-theme`, so a preset beats the dark rule. */
export const ACCENT_LAYER = "@layer ui-accent";

/** The six names a preset sets: the contract's accent group, and nothing outside it. */
export const ACCENT_TOKEN_NAMES: readonly string[] =
  TOKEN_GROUPS.find((group) => group.id === "color-accent")?.names ?? [];

/** Tailwind palette variables a theme may re-point: the gray bridge, plus white and black. */
export const BRIDGE_VARIABLE = /^--color-(?:white|black|gray-(?:50|[1-9]00|950))$/;

/** The eleven gray steps. A non-default theme re-points all of them, in its base rule (see below). */
export const GRAY_STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;

/** Marker a stub theme file carries in its header comment until its tokens are written. */
export const STUB_MARKER = "Stub:";

const CONTRACT = new Set<string>(TOKEN_NAMES);

/** The canonical selector list of a theme's rule for one mode. */
export function themeSelectors(themeId: ThemeId, mode: ThemeModeName): string[] {
  const attr = `:root[data-theme="${themeId}"]`;
  const suffix = mode === "dark" ? ".dark" : "";
  return themeId === DEFAULT_THEME_ID
    ? [`:root${suffix}`, `${attr}${suffix}`]
    : [`${attr}${suffix}`];
}

/** The canonical selector list of one accent preset's rule for one mode. */
export function accentSelectors(themeId: ThemeId, presetId: string, mode: ThemeModeName): string[] {
  const attr = `[data-accent="${presetId}"]`;
  const suffix = mode === "dark" ? ".dark" : "";
  const own = `:root[data-theme="${themeId}"]${attr}${suffix}`;
  return themeId === DEFAULT_THEME_ID ? [`:root:not([data-theme])${attr}${suffix}`, own] : [own];
}

/** One preset's rules: the light rule (it applies in both modes) and the dark rule alone. */
export interface AccentPresetRules {
  readonly light: ReadonlyMap<string, string>;
  readonly dark: ReadonlyMap<string, string>;
}

export interface ThemeFileAnalysis {
  readonly themeId: ThemeId;
  /**
   * Custom properties each canonical rule declares itself, name → value: `light` is the base rule
   * (it applies in both modes), `dark` the dark rule alone. {@link modeDeclarations} gives what a
   * mode resolves to.
   */
  readonly modes: Readonly<Record<ThemeModeName, ReadonlyMap<string, string>>>;
  /** The theme's accent presets, id → rules, in the order the file declares them. */
  readonly accents: ReadonlyMap<string, AccentPresetRules>;
  /** True once any rule in the file declares a `--ui-*` property. */
  readonly declaresTokens: boolean;
  /** True while the header still carries {@link STUB_MARKER} and nothing is declared. */
  readonly isStub: boolean;
  /** Shape problems: token declarations outside the canonical rules or layer, duplicates. */
  readonly structure: readonly string[];
}

const sameSet = (a: readonly string[], b: readonly string[]) =>
  a.length === b.length && a.every((s) => b.includes(s));

/** The one preset id a selector list names, or null when it names none (or several). */
function presetOf(selectors: readonly string[]): string | null {
  const ids = new Set(
    selectors.map((selector) => /\[data-accent="([\w-]+)"\]/.exec(selector)?.[1] ?? ""),
  );
  const [id, ...rest] = [...ids];
  return id !== undefined && id !== "" && rest.length === 0 ? id : null;
}

export function analyzeThemeFile(css: string, themeId: ThemeId): ThemeFileAnalysis {
  const rules = parseCssRules(css);
  const modes = { light: new Map<string, string>(), dark: new Map<string, string>() };
  const firstLine = { light: new Map<string, number>(), dark: new Map<string, number>() };
  const accents = new Map<string, { light: Map<string, string>; dark: Map<string, string> }>();
  const structure: string[] = [];
  let declaresTokens = false;

  for (const rule of rules) {
    const custom = rule.declarations.filter((d: CssDeclaration) => d.name.startsWith("--"));
    if (rule.declarations.some((d) => d.name.startsWith("--ui-"))) declaresTokens = true;
    if (custom.length === 0) continue;
    const selectors = selectorList(rule.selector);

    const preset = presetOf(selectors);
    if (preset !== null) {
      const mode = THEME_MODES.find((m) => sameSet(selectors, accentSelectors(themeId, preset, m)));
      if (mode === undefined) {
        structure.push(
          `line ${rule.line}: \`${rule.selector}\` declares ${custom[0]!.name} — a preset's rules are ` +
            `${THEME_MODES.map((m) => `\`${accentSelectors(themeId, preset, m).join(", ")}\``).join(" / ")}`,
        );
        continue;
      }
      const layered =
        rule.parents.length === 0 && rule.atRules.length === 1 && rule.atRules[0] === ACCENT_LAYER;
      if (!layered) {
        const where = [...rule.atRules, ...rule.parents].join(" › ") || "top level";
        structure.push(
          `line ${rule.line}: the ${preset} preset's ${mode} rule sits in ${where}; it must sit ` +
            `directly in \`${ACCENT_LAYER}\` so it overrides the theme's dark rule by layer order`,
        );
      }
      const entry = accents.get(preset) ?? { light: new Map(), dark: new Map() };
      for (const declaration of custom) {
        if (entry[mode].has(declaration.name)) {
          structure.push(
            `line ${declaration.line}: ${declaration.name} is declared again for the ${preset} preset (${mode}); the later one silently wins`,
          );
        }
        entry[mode].set(declaration.name, declaration.value);
      }
      accents.set(preset, entry);
      continue;
    }

    const mode = THEME_MODES.find((m) => sameSet(selectors, themeSelectors(themeId, m)));
    if (mode === undefined) {
      structure.push(
        `line ${rule.line}: \`${rule.selector}\` declares ${custom[0]!.name} — tokens belong in the ` +
          `canonical rules (${THEME_MODES.map((m) => `\`${themeSelectors(themeId, m).join(", ")}\``).join(" / ")})`,
      );
      continue;
    }
    if (rule.parents.length > 0 || rule.atRules.length !== 1 || rule.atRules[0] !== THEME_LAYER) {
      const where = [...rule.atRules, ...rule.parents].join(" › ") || "top level";
      structure.push(
        `line ${rule.line}: the ${mode} rule sits in ${where}; it must sit directly in \`${THEME_LAYER}\` ` +
          `so the user's accent presets (\`@layer ui-accent\`) override it`,
      );
    }
    for (const declaration of custom) {
      const seen = firstLine[mode].get(declaration.name);
      if (seen !== undefined) {
        structure.push(
          `line ${declaration.line}: ${declaration.name} is declared again for ${mode} (first at line ${seen}); the later one silently wins`,
        );
      } else firstLine[mode].set(declaration.name, declaration.line);
      modes[mode].set(declaration.name, declaration.value);
    }
  }

  return {
    themeId,
    modes,
    accents,
    declaresTokens,
    isStub: !declaresTokens && css.includes(STUB_MARKER),
    structure,
  };
}

/** A value that follows `--ui-accent`: it reads the token (with or without a fallback). */
const DERIVED_FROM_ACCENT = /var\(\s*--ui-accent\s*[,)]/;

/**
 * Problems with a theme's accent presets against the list tokens.ts declares for it: the ids
 * and their order, a light rule that sets `--ui-accent` and only accent names, a dark rule that
 * sets only accent names and only what dark changes, values that resolve, every accent token a
 * preset leaves alone derived from `--ui-accent` by the theme (the label ink excepted — the
 * contrast suite measures it against every preset), and the swatch tokens.ts carries for each
 * preset equal to the `--ui-accent` its light rule sets.
 */
export function accentProblems(
  analysis: ThemeFileAnalysis,
  expected: readonly { readonly id: string; readonly swatch: string }[],
): string[] {
  const problems: string[] = [];
  const declared = [...analysis.accents.keys()];
  const expectedIds = expected.map((preset) => preset.id);
  if (declared.join(",") !== expectedIds.join(",")) {
    problems.push(
      `the presets are [${declared.join(", ")}]; tokens.ts lists [${expectedIds.join(", ")}] in that order`,
    );
  }
  for (const { id, swatch } of expected) {
    const rules = analysis.accents.get(id);
    if (rules === undefined) continue;
    if (!rules.light.has("--ui-accent")) {
      problems.push(`${id}: the light rule does not set --ui-accent`);
    }
    for (const mode of THEME_MODES) {
      // A token the preset does not set in this mode takes the theme's value for the mode, which
      // must be a derivation of `--ui-accent` — otherwise the theme's own hover, wash or line
      // would show under the preset's accent.
      const themeValues = modeDeclarations(analysis, mode);
      for (const name of ACCENT_TOKEN_NAMES) {
        if (name === "--ui-accent" || name === "--ui-accent-fg") continue;
        if (rules.light.has(name) || (mode === "dark" && rules.dark.has(name))) continue;
        const value = themeValues.get(name);
        if (value === undefined || !DERIVED_FROM_ACCENT.test(value)) {
          problems.push(
            `${id}: ${name} (${mode}) is neither set by the preset nor derived from --ui-accent by the theme (${value ?? "undeclared"})`,
          );
        }
      }
    }
    for (const [mode, values] of [
      ["light", rules.light],
      ["dark", rules.dark],
    ] as const) {
      for (const [name, value] of values) {
        if (!ACCENT_TOKEN_NAMES.includes(name)) {
          problems.push(`${id}: the ${mode} rule sets ${name}, which is not an accent token`);
        }
        if (value === "") problems.push(`${id}: ${name} (${mode}) has an empty value`);
        for (const ref of value.matchAll(/var\(\s*(--[\w-]+)/g)) {
          if (!CONTRACT.has(ref[1]!)) {
            problems.push(`${id}: ${name} (${mode}) reads ${ref[1]}, not a contract token`);
          }
        }
        if (mode === "dark" && rules.light.get(name) === value) {
          problems.push(
            `${id}: the dark rule repeats ${name}: ${value} — drop it from the dark rule`,
          );
        }
      }
    }
    const accent = rules.light.get("--ui-accent");
    if (accent !== undefined && accent !== swatch) {
      problems.push(
        `${id}: tokens.ts carries the swatch ${swatch}, the light rule sets --ui-accent: ${accent}`,
      );
    }
  }
  return problems;
}

/**
 * What one mode of a theme defines within its own file: the base rule, overlaid in dark with the
 * dark rule. `:root.dark` also matches the base rule, so a name the dark rule leaves out keeps its
 * base value.
 */
export function modeDeclarations(
  analysis: ThemeFileAnalysis,
  mode: ThemeModeName,
): ReadonlyMap<string, string> {
  return mode === "light"
    ? analysis.modes.light
    : new Map([...analysis.modes.light, ...analysis.modes.dark]);
}

/**
 * Contract problems for one mode — the base rule plus that mode's own: missing names, names
 * outside the contract, bad values.
 */
export function contractProblems(analysis: ThemeFileAnalysis, mode: ThemeModeName): string[] {
  const declared = modeDeclarations(analysis, mode);
  const problems: string[] = [];
  const missing = TOKEN_NAMES.filter((name) => !declared.has(name));
  if (missing.length > 0) {
    problems.push(`missing ${missing.length} of ${TOKEN_NAMES.length}: ${missing.join(", ")}`);
  }
  for (const [name, value] of declared) {
    if (name.startsWith("--ui-") && !CONTRACT.has(name)) {
      problems.push(`${name} is not in tokens.ts — add it to the contract or remove it`);
    } else if (!name.startsWith("--ui-") && !BRIDGE_VARIABLE.test(name)) {
      problems.push(
        `${name} is neither a contract token nor a bridged Tailwind palette variable (${BRIDGE_VARIABLE})`,
      );
    }
    if (value === "") problems.push(`${name} has an empty value`);
    for (const ref of value.matchAll(/var\(\s*(--[\w-]+)/g)) {
      const target = ref[1]!;
      if (target.startsWith("--ui-") && !CONTRACT.has(target)) {
        problems.push(`${name} reads ${target}, which is not a contract token`);
      }
    }
  }
  if (analysis.themeId !== DEFAULT_THEME_ID) {
    // The default theme's rules match every <html> (`:root`, `:root.dark`), so a gray step this
    // theme leaves alone renders in the default theme's value — the palette classes the app
    // still spells would mix two themes on one screen.
    const grays = GRAY_STEPS.filter((step) => !declared.has(`--color-gray-${step}`));
    if (grays.length > 0) {
      problems.push(
        `the gray bridge is incomplete — re-point ${grays.map((s) => `--color-gray-${s}`).join(", ")}`,
      );
    }
  }
  return problems;
}

/**
 * Dark-rule declarations that repeat the base rule's value, as `name: value`. The base rule already
 * gives the name that value in dark, so a repeat is a second home for one value — the two drift the
 * first time an edit reaches one of them. The dark rule declares only what dark changes.
 */
export function darkRepeats(analysis: ThemeFileAnalysis): string[] {
  return [...analysis.modes.dark]
    .filter(([name, value]) => analysis.modes.light.get(name) === value)
    .map(([name, value]) => `${name}: ${value}`);
}

/**
 * The value a custom property resolves to for `mode` of a theme, following the cascade the
 * selectors produce: an applied accent preset's rules first (its dark rule, then its light one —
 * they sit in `ui-accent`, after every theme rule), then the mode's own rule, then (dark only)
 * the same theme's base rule, which the dark `<html>` also matches, then the default theme's
 * rules, which match every `<html>`. (Against the default theme's dark rule, another theme's base
 * rule ties on specificity and wins because the theme files are imported after `github.css`.)
 * `var()` references are substituted recursively, fallbacks honoured. `null` when unresolvable.
 */
export function resolveThemeValue(
  name: string,
  mode: ThemeModeName,
  theme: ThemeFileAnalysis,
  defaultTheme: ThemeFileAnalysis,
  preset: AccentPresetRules | null = null,
): string | null {
  const scopes: ReadonlyMap<string, string>[] = [];
  const push = (analysis: ThemeFileAnalysis) => {
    scopes.push(analysis.modes[mode]);
    if (mode === "dark") scopes.push(analysis.modes.light);
  };
  if (preset !== null) {
    if (mode === "dark") scopes.push(preset.dark);
    scopes.push(preset.light);
  }
  push(theme);
  if (defaultTheme !== theme) push(defaultTheme);

  const lookup = (key: string) => {
    for (const scope of scopes) {
      const value = scope.get(key);
      if (value !== undefined) return value;
    }
    return undefined;
  };

  /** Replaces every `var()` in `value`, left to right; `depth` counts reference hops (cycle guard). */
  const substitute = (value: string, depth: number): string | null => {
    if (depth > 32) return null;
    let out = value;
    for (;;) {
      const at = out.indexOf("var(");
      if (at === -1) return out;
      let parens = 0;
      let end = -1;
      for (let i = at + 3; i < out.length; i++) {
        if (out[i] === "(") parens++;
        else if (out[i] === ")" && --parens === 0) {
          end = i;
          break;
        }
      }
      if (end === -1) return null;
      const inner = out.slice(at + 4, end);
      const comma = inner.indexOf(",");
      const ref = (comma === -1 ? inner : inner.slice(0, comma)).trim();
      const fallback = comma === -1 ? undefined : inner.slice(comma + 1).trim();
      const found = lookup(ref);
      const replacement =
        found !== undefined
          ? substitute(found, depth + 1)
          : fallback !== undefined
            ? substitute(fallback, depth + 1)
            : null;
      if (replacement === null) return null;
      out = out.slice(0, at) + replacement + out.slice(end + 1);
    }
  };

  const raw = lookup(name);
  return raw === undefined ? null : substitute(raw, 0);
}