@assure-one/design-system 1.31.0 → 1.33.0

package/codemods/lib/ds-stylesheet.mjs

@@ -0,0 +1,168 @@
+/**
+ * What the design system's own stylesheet declares — the reference side of
+ * every comparison CM-16 makes.
+ *
+ * Read from the installed package, so a consumer always compares its
+ * `globals.css` against the sheet it actually loads:
+ *
+ *   dist/styles.css                    the shipped sheet (always present in
+ *                                      an installed package)
+ *   src/tokens/generated/theme.css     fallback for an unbuilt checkout of
+ *                                      this repository, where the contract
+ *                                      tests run before `pnpm build`
+ *
+ * Only the **default root scope** is read: `@theme`, `:root`, `:host` and
+ * `html`. The `.dark` block and the `[data-brand="…"]` blocks are deliberately
+ * left out — they are unlayered and beat app variables, so a consumer that
+ * activates one (TAX sets `data-brand="tax"`) sees different values than this
+ * model reports. `derive-consumer-preset` (W1-18) takes the element model as
+ * input and does apply them; the difference is recorded in CM-16's report.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { computeCustomProperties } from "./css-values.mjs";
+
+const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
+
+export const DS_SHEET_CANDIDATES = ["dist/styles.css", "src/tokens/generated/theme.css"];
+
+/** Split a selector list on top-level commas. */
+export function selectorParts(selector) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < selector.length; i += 1) {
+    const ch = selector[i];
+    if (ch === "(" || ch === "[") depth += 1;
+    else if (ch === ")" || ch === "]") depth -= 1;
+    else if (ch === "," && depth === 0) {
+      parts.push(selector.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  parts.push(selector.slice(start).trim());
+  return parts.filter(Boolean);
+}
+
+const ROOT_PART = /^(?::root|:host|html)$/;
+
+/** Whether a selector list declares on the default document root. */
+export const isRootSelector = (selector) =>
+  selectorParts(selector).some((p) => ROOT_PART.test(p.replace(/\s+/g, "")));
+
+/** The cascade layer a node sits in (dot-joined for nested layers), or null. */
+export function layerOf(node) {
+  const path = [];
+  for (let p = node; p && p.type !== "root"; p = p.parent) {
+    if (p.type === "atrule" && p.name === "layer") path.unshift(p.params.trim());
+  }
+  return path.join(".") || null;
+}
+
+export function insideAtRule(node, name) {
+  for (let p = node.parent; p && p.type !== "root"; p = p.parent) {
+    if (p.type === "atrule" && p.name === name) return true;
+  }
+  return false;
+}
+
+export function insideKeyframes(node) {
+  for (let p = node.parent; p && p.type !== "root"; p = p.parent) {
+    if (p.type === "atrule" && /keyframes$/.test(p.name)) return true;
+  }
+  return false;
+}
+
+/** Class names a selector list names, without duplicates. */
+export const classNamesOf = (selector) => [
+  ...new Set([...selector.matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)].map((m) => m[1])),
+];
+
+/**
+ * Tailwind's preflight, recognised by the reset it puts in `@layer base` on
+ * `*, ::before, ::after, ::backdrop`. Stable across Tailwind 4 minor versions
+ * and survives minification.
+ */
+function hasPreflight(postcss, root) {
+  let found = false;
+  root.walkRules((rule) => {
+    if (found) return;
+    if (!/::backdrop/.test(rule.selector)) return;
+    if (!selectorParts(rule.selector).includes("*")) return;
+    rule.walkDecls("box-sizing", () => {
+      found = true;
+    });
+  });
+  return found;
+}
+
+let cached = null;
+let overrideRoot = null;
+
+/**
+ * The design system's declared surface.
+ * @param {object} postcss the parser the runner borrowed from the project
+ * @param {{ root?: string }} [options] package root, for tests
+ * @returns {{ from: string, tokens: Map<string,string>, declared: Map<string,string>,
+ *            classes: Set<string>, preflight: boolean, scopes: string[] }}
+ */
+export function dsStylesheet(postcss, { root = overrideRoot ?? packageRoot } = {}) {
+  if (cached && cached.root === root) return cached.value;
+  const rel = DS_SHEET_CANDIDATES.find((c) => existsSync(join(root, c)));
+  if (!rel) {
+    throw new Error(
+      `CM-16 compares the application's stylesheet against the design system's own, but none of ` +
+        `${DS_SHEET_CANDIDATES.join(", ")} exists under ${root}. Run \`pnpm build\` (in this ` +
+        `repository) or reinstall the package.`,
+    );
+  }
+  const css = readFileSync(join(root, rel), "utf8");
+  const parsed = postcss.parse(css, { from: rel });
+  const declared = new Map(); // name -> winning declaration text (source order)
+  const classes = new Set();
+  const scopes = new Set();
+  parsed.walkDecls((decl) => {
+    if (!decl.prop.startsWith("--") || decl.prop.startsWith("--tw-")) return;
+    if (insideKeyframes(decl)) return;
+    const parent = decl.parent;
+    const inTheme = parent?.type === "atrule" && parent.name === "theme";
+    if (inTheme || insideAtRule(decl, "theme")) {
+      declared.set(decl.prop, decl.value.trim());
+      scopes.add("@theme");
+      return;
+    }
+    if (parent?.type !== "rule") return;
+    if (isRootSelector(parent.selector)) {
+      declared.set(decl.prop, decl.value.trim());
+      scopes.add(selectorParts(parent.selector).join(", "));
+    }
+  });
+  parsed.walkRules((rule) => {
+    for (const name of classNamesOf(rule.selector)) classes.add(name);
+  });
+  const winners = new Map([...declared].map(([name, value]) => [name, { value }]));
+  const value = {
+    from: rel,
+    tokens: computeCustomProperties(winners),
+    declared,
+    classes,
+    preflight: hasPreflight(postcss, parsed),
+    scopes: [...scopes].sort(),
+  };
+  cached = { root, value };
+  return value;
+}
+
+/**
+ * Test hook: read the reference sheet from `root` instead of the installed
+ * package, and forget what was cached. The fixtures use it to compare against
+ * a small stylesheet of invented names, so that they neither depend on
+ * `pnpm build` having run nor on the value of a real token
+ * (`tests/codemods/cm-16.test.mjs`). `null` restores the installed package.
+ */
+export const setDsStylesheetRoot = (root) => {
+  overrideRoot = root;
+  cached = null;
+};

package/codemods/lib/environment.mjs

@@ -0,0 +1,72 @@
+/**
+ * What a codemod run needs from its surroundings: the installed design-system
+ * version and, for codemods that parse code, the TypeScript compiler.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
+
+/**
+ * The version of the design-system package these codemods ship in. The
+ * runner is executed from the installed package, so this is the version the
+ * consumer has installed.
+ */
+export function installedDsVersion() {
+  return JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).version;
+}
+
+/** Compares `major.minor.patch[-pre]` strings; prereleases sort before the release. */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core, pre = ""] = String(v).replace(/^v/, "").split("-", 2);
+    return { parts: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre };
+  };
+  const x = parse(a);
+  const y = parse(b);
+  for (let i = 0; i < 3; i += 1) {
+    const d = (x.parts[i] ?? 0) - (y.parts[i] ?? 0);
+    if (d) return Math.sign(d);
+  }
+  if (x.pre === y.pre) return 0;
+  if (!x.pre) return 1;
+  if (!y.pre) return -1;
+  return x.pre < y.pre ? -1 : 1;
+}
+
+/**
+ * A module resolved from the consumer project first and from this package's
+ * own location second. Neither is a dependency of the design system (see
+ * codemods/README.md, "Packaging"): every consumer app already has them, and
+ * codemods are a development-time tool.
+ */
+async function borrow(root, name, hint) {
+  const attempts = [join(root, "package.json"), join(packageRoot, "package.json")];
+  for (const from of attempts) {
+    try {
+      const path = createRequire(from).resolve(name);
+      const mod = await import(pathToFileURL(path).href);
+      return mod.default ?? mod;
+    } catch {
+      // try the next location
+    }
+  }
+  throw new Error(
+    `This codemod ${hint}, but \`${name}\` could not be resolved from ${root}. ` +
+      `Install it in the project (\`pnpm add -D ${name}\`) and run again.`,
+  );
+}
+
+/** The `typescript` module, for codemods that parse code. */
+export const loadTypeScript = (root) =>
+  borrow(root, "typescript", "parses code with the TypeScript compiler");
+
+/**
+ * The `postcss` module, for codemods that parse stylesheets. Every consumer
+ * is a Tailwind 4 application and therefore already has it; using the same
+ * parser as the consumer scanner (W0-28) and `derive-consumer-preset`
+ * (W1-18) is also what keeps the three tools' CSS facts comparable.
+ */
+export const loadPostcss = (root) => borrow(root, "postcss", "parses stylesheets with PostCSS");

package/codemods/lib/files.mjs

@@ -0,0 +1,100 @@
+/**
+ * File discovery for codemods. Runs inside consumer projects, so it only uses
+ * Node built-ins. The skip lists and the test-file rule match the consumer
+ * scanner (scripts/scan-consumers/lib/files.mjs) so both tools count the same
+ * files.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+export const EXCLUDED_DIRS = new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  ".vercel",
+  ".swc",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "playwright-report",
+  "storybook-static",
+  "test-results",
+]);
+
+/** Root-relative directories served as-is (Next.js `public/`), never scanned. */
+export const STATIC_DIRS = ["public"];
+
+const CODE_EXT = /\.(?:[cm]?[jt]sx?)$/;
+const CSS_EXT = /\.css$/;
+const TEST_DIRS = new Set(["__tests__", "__mocks__", "__fixtures__", "e2e", "test", "tests"]);
+const TEST_FILE =
+  /(?:\.(?:test|spec|e2e)\.[cm]?[jt]sx?$)|(?:^|\/)(?:jest|vitest|playwright)[.-][^/]*$/;
+
+export const toPosix = (path) => path.split(sep).join("/");
+
+/** `{ kind: "code" | "css" | "other", test }` for a root-relative posix path. */
+export function classifyFile(rel) {
+  const kind = rel.endsWith(".d.ts")
+    ? "other"
+    : CODE_EXT.test(rel)
+      ? "code"
+      : CSS_EXT.test(rel)
+        ? "css"
+        : "other";
+  const segments = rel.split("/");
+  const test =
+    segments.slice(0, -1).some((s) => TEST_DIRS.has(s)) ||
+    TEST_FILE.test(rel) ||
+    /\.stories\.[cm]?[jt]sx?$/.test(rel);
+  return { kind, test };
+}
+
+/** The nearest directory at or above `start` that holds a package.json. */
+export function findProjectRoot(start) {
+  let dir = resolve(start);
+  for (;;) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return resolve(start);
+    dir = parent;
+  }
+}
+
+/**
+ * Code and CSS files under `paths` (files or directories), as sorted
+ * root-relative posix paths. Paths outside `root` are refused.
+ */
+export function collectFiles(root, paths) {
+  const out = new Set();
+  const skipPrefixes = STATIC_DIRS;
+  const consider = (abs) => {
+    const rel = toPosix(relative(root, abs));
+    if (rel.startsWith("..")) throw new Error(`${abs} is outside the project root ${root}`);
+    return rel;
+  };
+  const visit = (abs) => {
+    const rel = consider(abs);
+    if (rel && skipPrefixes.some((p) => rel === p || rel.startsWith(`${p}/`))) return;
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      const child = join(abs, entry.name);
+      if (entry.isDirectory()) {
+        if (!EXCLUDED_DIRS.has(entry.name)) visit(child);
+      } else if (entry.isFile()) {
+        const childRel = consider(child);
+        if (classifyFile(childRel).kind !== "other") out.add(childRel);
+      }
+    }
+  };
+  for (const path of paths.length ? paths : [root]) {
+    const abs = resolve(path);
+    if (!existsSync(abs)) throw new Error(`${path} does not exist`);
+    if (statSync(abs).isDirectory()) visit(abs);
+    else {
+      const rel = consider(abs);
+      if (classifyFile(rel).kind !== "other") out.add(rel);
+    }
+  }
+  return [...out].sort();
+}

package/codemods/lib/forms.mjs

@@ -0,0 +1,253 @@
+/**
+ * Form-shaped source facts, shared by the two report-only finders of the
+ * forms wave (plan §16): CM-14 (hidden-input mirrors) and CM-20 (Select
+ * sentinels).
+ *
+ * `lib/jsx.mjs` answers "which class tokens sit on which design-system
+ * component" and therefore only records elements that carry a class
+ * attribute. A hidden `<input type="hidden" name="x" value={x} />` carries
+ * none, and a sentinel lives in a prop value, not in a class token — so the
+ * forms codemods need a different view of the same tree:
+ *
+ * - **every** JSX element, design-system and raw alike, in document order;
+ * - each element's attributes, with the string literals and the identifiers
+ *   of the expression behind them (the identifiers are what tie a mirror to
+ *   the control it mirrors);
+ * - the nearest `<form>` ancestor, because the applications do not put a
+ *   mirror next to its control — they collect the mirrors at the top of the
+ *   form ([CU §18]);
+ * - top-level `const NAME = "literal"` declarations, because the sentinels
+ *   are named constants (`const NONE_VALUE = "__none__"`).
+ *
+ * As everywhere in `codemods/lib`, the TypeScript module is passed in: a
+ * codemod never imports a parser itself (`lib/environment.mjs`).
+ */
+import { DS_PACKAGE, createSourceFile } from "./jsx.mjs";
+
+export { DS_PACKAGE };
+
+const isDsSpecifier = (s) => s === DS_PACKAGE || s.startsWith(`${DS_PACKAGE}/`);
+
+/** Attributes whose value is the control's current value, in binding order. */
+export const VALUE_PROPS = ["value", "defaultValue", "checked", "defaultChecked", "selected"];
+
+/** Attributes through which a control writes its value back. */
+export const CHANGE_PROPS = [
+  "onValueChange",
+  "onCheckedChange",
+  "onChange",
+  "onSelect",
+  "onRemove",
+  "onSelectionChange",
+];
+
+/**
+ * Parses one file into form facts.
+ *
+ * Returns:
+ * - `sf`, `lineOf` — the source file and a node → line helper
+ * - `imports` — design-system local name → exported name
+ * - `namespaces` — local names of `import * as X from the package`
+ * - `elements` — every JSX element, in document order, as described below
+ * - `constants` — top-level `const` name → `{ text, line }` for string consts
+ * - `componentsUsed` — the design-system base names used as JSX
+ * - `parseErrors`
+ *
+ * An element is
+ * `{ index, parent, tag, base, component, isDs, line, props, spread, form }`
+ * where `props` is a Map of attribute name → `{ literals, identifiers, text,
+ * line, expression }` and `form` is the index of the nearest `<form>`
+ * ancestor (or `null`).
+ */
+export function analyseForms(ts, text, rel) {
+  const sf = createSourceFile(ts, text, rel);
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+
+  const imports = new Map();
+  const namespaces = new Set();
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    if (!isDsSpecifier(stmt.moduleSpecifier.text)) continue;
+    const clause = stmt.importClause;
+    if (!clause || clause.isTypeOnly) continue;
+    const bindings = clause.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    else if (bindings && ts.isNamedImports(bindings)) {
+      for (const el of bindings.elements) {
+        if (!el.isTypeOnly) imports.set(el.name.text, (el.propertyName ?? el.name).text);
+      }
+    }
+  }
+
+  /** Top-level `const NAME = "text"`, the shape the sentinels are declared in. */
+  const constants = new Map();
+  for (const stmt of sf.statements) {
+    const list = ts.isVariableStatement(stmt) ? stmt.declarationList : null;
+    if (!list || !(list.flags & ts.NodeFlags.Const)) continue;
+    for (const decl of list.declarations) {
+      if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
+      const init = decl.initializer;
+      if (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)) {
+        constants.set(decl.name.text, { text: init.text, line: lineOf(init) });
+      }
+    }
+  }
+
+  /** String literals inside an expression, at any depth below JSX. */
+  const literalsIn = (node, out = []) => {
+    if (!node) return out;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+      out.push(node.text);
+      return out;
+    }
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
+      return out;
+    }
+    // A block body: `forEachChild` stops at the first truthy return, and the
+    // accumulator is always truthy.
+    ts.forEachChild(node, (child) => {
+      literalsIn(child, out);
+    });
+    return out;
+  };
+
+  /**
+   * Identifier names an expression reads. Member names (`a.b`), object keys
+   * and JSX subtrees are excluded: what matters is which bindings the value
+   * depends on, so that two attributes reading `entityType` can be recognised
+   * as two views of the same state.
+   */
+  const identifiersIn = (node, out = new Set()) => {
+    if (!node) return out;
+    if (ts.isIdentifier(node)) {
+      const parent = node.parent;
+      const isMemberName = parent && ts.isPropertyAccessExpression(parent) && parent.name === node;
+      const isKey =
+        parent &&
+        (ts.isPropertyAssignment(parent) || ts.isPropertySignature(parent)) &&
+        parent.name === node;
+      if (!isMemberName && !isKey) out.add(node.text);
+      return out;
+    }
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
+      return out;
+    }
+    ts.forEachChild(node, (child) => {
+      identifiersIn(child, out);
+    });
+    return out;
+  };
+
+  const resolveTag = (tag) => {
+    const members = [];
+    let current = tag;
+    while (ts.isPropertyAccessExpression(current)) {
+      members.unshift(current.name.text);
+      current = current.expression;
+    }
+    if (!ts.isIdentifier(current)) return null;
+    const root = current.text;
+    if (namespaces.has(root) && members.length) {
+      return { base: members[0], component: members.join(".") };
+    }
+    const base = imports.get(root);
+    if (!base) return null;
+    return { base, component: [base, ...members].join(".") };
+  };
+
+  const elements = [];
+  const openingOf = (node) => (ts.isJsxElement(node) ? node.openingElement : node);
+
+  const record = (node, parent, form) => {
+    const opening = openingOf(node);
+    const info = resolveTag(opening.tagName);
+    const tag = opening.tagName.getText(sf);
+    const props = new Map();
+    let spread = false;
+    for (const attr of opening.attributes.properties) {
+      if (ts.isJsxSpreadAttribute(attr)) {
+        spread = true;
+        continue;
+      }
+      if (!ts.isJsxAttribute(attr)) continue;
+      const name = attr.name.getText(sf);
+      const init = attr.initializer;
+      if (init === undefined) {
+        // A bare attribute (`required`) is the boolean `true`.
+        props.set(name, {
+          literals: [],
+          identifiers: [],
+          text: "true",
+          line: lineOf(attr),
+          expression: false,
+        });
+        continue;
+      }
+      const inner = ts.isJsxExpression(init) ? (init.expression ?? null) : init;
+      const isLiteral =
+        inner !== null && (ts.isStringLiteral(inner) || ts.isNoSubstitutionTemplateLiteral(inner));
+      props.set(name, {
+        literals: inner ? literalsIn(inner) : [],
+        identifiers: inner ? [...identifiersIn(inner)] : [],
+        text: inner ? inner.getText(sf) : null,
+        line: lineOf(attr),
+        expression: Boolean(inner) && !isLiteral,
+      });
+    }
+    const entry = {
+      index: elements.length,
+      parent,
+      tag,
+      base: info?.base ?? null,
+      component: info?.component ?? null,
+      isDs: Boolean(info),
+      line: lineOf(opening),
+      props,
+      spread,
+      form,
+      node,
+    };
+    elements.push(entry);
+    return entry;
+  };
+
+  const walk = (node, parent, form) => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const entry = record(node, parent, form);
+      const nextForm = /^(?:form|Form)$/.test(entry.tag) ? entry.index : form;
+      ts.forEachChild(node, (child) => walk(child, entry.index, nextForm));
+      return;
+    }
+    ts.forEachChild(node, (child) => walk(child, parent, form));
+  };
+  walk(sf, null, null);
+
+  const parseErrors = (sf.parseDiagnostics ?? []).map((d) => ({
+    line: d.start === undefined ? null : sf.getLineAndCharacterOfPosition(d.start).line + 1,
+    message: ts.flattenDiagnosticMessageText(d.messageText, " "),
+  }));
+
+  return {
+    sf,
+    lineOf,
+    literalsIn,
+    identifiersIn: (node) => [...identifiersIn(node)],
+    imports,
+    namespaces,
+    elements,
+    constants,
+    componentsUsed: new Set(elements.filter((e) => e.isDs).map((e) => e.base)),
+    parseErrors,
+  };
+}
+
+/** The literal value of an attribute when it is a single string, else `null`. */
+export const literalValue = (prop) =>
+  prop && !prop.expression && prop.literals.length === 1 ? prop.literals[0] : null;
+
+/** Whether `inner` is `outer` or sits below it in the element tree. */
+export function isWithin(elements, inner, outer) {
+  if (outer === null || inner === null) return false;
+  for (let i = inner; i !== null; i = elements[i].parent) if (i === outer) return true;
+  return false;
+}

package/codemods/lib/ledger.mjs

@@ -0,0 +1,84 @@
+/**
+ * Consumer-side codemod ledger (`.ds-migrations.json`, plan §29).
+ *
+ *   { "schema": 1, "applied": [{ "id", "appliedAt", "dsVersion", "filesChanged" }] }
+ *
+ * The ledger lives in the consumer project root and is committed there. It
+ * records every transforming codemod that was applied (class A and R), so
+ * that one-shot codemods refuse to run twice and `upgrade` can run exactly
+ * the codemods a project is missing. Report-only codemods (class X) and dry
+ * runs never write it.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const LEDGER_FILE = ".ds-migrations.json";
+export const LEDGER_SCHEMA = 1;
+
+const COMMENT =
+  "Codemods from @assure-one/design-system applied to this project. Written by the codemod runner; commit it with the codemod's changes.";
+
+export const ledgerPath = (root) => join(root, LEDGER_FILE);
+
+/**
+ * `{ schema, applied }`. A missing file is an empty ledger. Entries written
+ * as bare ids (`["CM-05"]`) are accepted and read as `{ id }`.
+ */
+export function readLedger(root) {
+  const path = ledgerPath(root);
+  if (!existsSync(path)) return { schema: LEDGER_SCHEMA, applied: [] };
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON: ${error.message}`);
+  }
+  const list = Array.isArray(data) ? data : data?.applied;
+  if (!Array.isArray(list)) throw new Error(`${path} has no "applied" list`);
+  const applied = list.map((entry) => {
+    const normalized = typeof entry === "string" ? { id: entry } : entry;
+    if (!normalized || typeof normalized.id !== "string") {
+      throw new Error(`${path} has an entry without an id: ${JSON.stringify(entry)}`);
+    }
+    return normalized;
+  });
+  return { schema: data?.schema ?? LEDGER_SCHEMA, applied };
+}
+
+export const appliedIds = (ledger) => new Set(ledger.applied.map((e) => e.id));
+
+/** Appends one entry and writes the file (stable key order, trailing newline). */
+export function recordApplied(root, { id, appliedAt, dsVersion, filesChanged }) {
+  const ledger = readLedger(root);
+  const applied = [...ledger.applied, { id, appliedAt, dsVersion, filesChanged }];
+  const body = { $comment: COMMENT, schema: LEDGER_SCHEMA, applied };
+  writeFileSync(ledgerPath(root), `${JSON.stringify(body, null, 2)}\n`);
+  return { schema: LEDGER_SCHEMA, applied };
+}
+
+/**
+ * Why `meta` may not be applied to a project with this ledger and installed
+ * DS version, or `null`. Checked before any file is read.
+ */
+export function guardProblems(meta, ledger, dsVersion, compareVersions) {
+  const problems = [];
+  const ids = appliedIds(ledger);
+  if (meta.oneShot && ids.has(meta.id)) {
+    const when = ledger.applied.find((e) => e.id === meta.id)?.appliedAt;
+    problems.push(
+      `${meta.id} is a one-shot codemod and the ledger shows it was already applied${when ? ` (${when})` : ""}.`,
+    );
+  }
+  for (const required of meta.requires?.codemods ?? []) {
+    if (!ids.has(required)) {
+      problems.push(`${meta.id} needs ${required} to be applied first (not in ${LEDGER_FILE}).`);
+    }
+  }
+  const minimum = meta.requires?.dsVersion;
+  if (minimum && compareVersions(dsVersion, minimum) < 0) {
+    problems.push(
+      `${meta.id} needs @assure-one/design-system ${minimum} or later; ${dsVersion} is installed.`,
+    );
+  }
+  return problems;
+}