@assure-one/design-system 1.30.0 → 1.32.0

package/codemods/lib/css-selectors.mjs

@@ -0,0 +1,33 @@
+/**
+ * Rule selectors of a CSS file with their line numbers, without a CSS
+ * parser dependency. Comments and strings are blanked (keeping offsets), then
+ * every `prelude {` whose prelude is not an at-rule is a selector. Good
+ * enough for finding selectors; not a validator.
+ */
+export function cssSelectors(text) {
+  const blank = (s) => s.replace(/[^\n]/g, " ");
+  const clean = text
+    .replace(/\/\*[\s\S]*?\*\//g, blank)
+    .replace(
+      /"(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*'/g,
+      (m) => m[0] + blank(m.slice(1, -1)) + m[0],
+    );
+  const out = [];
+  let start = 0;
+  for (let i = 0; i < clean.length; i += 1) {
+    const ch = clean[i];
+    if (ch === "{" || ch === "}" || ch === ";") {
+      if (ch === "{") {
+        const prelude = clean.slice(start, i);
+        const offset = start + (prelude.length - prelude.trimStart().length);
+        const selector = text.slice(offset, i).trim();
+        if (selector && !selector.startsWith("@") && !/^[\d.%,\s]+$|^(?:from|to)$/.test(selector)) {
+          const line = text.slice(0, offset).split("\n").length;
+          out.push({ selector: selector.replace(/\s+/g, " "), line });
+        }
+      }
+      start = i + 1;
+    }
+  }
+  return out;
+}

package/codemods/lib/css-values.mjs

@@ -0,0 +1,223 @@
+/**
+ * Custom-property values: normalisation for comparison, and `var()`
+ * resolution. Dependency-free and pure — no file system, no CSS parser — so
+ * it can ship inside the package and run from a consumer project.
+ *
+ * It is the single implementation shared by
+ * `scripts/derive-consumer-preset` (W1-18) and CM-16: the two tools must
+ * agree on when two declarations of the same token "differ", or their counts
+ * cannot be compared. `scripts/derive-consumer-preset/lib/normalize.mjs` and
+ * `…/lib/cascade.mjs` re-export from here.
+ *
+ * Two values are "the same" when their normalised text is equal. The
+ * normalisation is conservative: it only removes differences that cannot
+ * change rendering (case of hex colours and keywords, short hex, whitespace,
+ * quotes around font names, `calc()` over px/rem only, trailing zeros). It
+ * does not convert between colour spaces: `#6c42f8` and an `oklab(...)`
+ * spelling of the same colour stay different, and the report shows both.
+ */
+
+const ROOT_FONT_SIZE_PX = 16;
+
+export function normalizeValue(value) {
+  if (value == null) return value;
+  let v = String(value).trim().replace(/\s+/g, " ");
+  v = v
+    .replace(/\s*,\s*/g, ",")
+    .replace(/\(\s+/g, "(")
+    .replace(/\s+\)/g, ")");
+  // Minifiers drop optional whitespace: `…) infinite` -> `…)infinite`, `16 / 9` -> `16/9`.
+  v = v.replace(/\)\s*(?=[\w#.-])/g, ") ").replace(/\s*\/\s*/g, "/");
+  v = v.replace(/#([0-9a-f]{3,8})\b/gi, (_, hex) => `#${expandHex(hex.toLowerCase())}`);
+  v = v.replace(/["']([^"',]+)["']/g, "$1");
+  v = evaluateCalcs(v);
+  v = v.replace(/(\d*\.\d*?)0+(?=[a-z%]|\b)/gi, (m, num) =>
+    num.endsWith(".") ? num.slice(0, -1) : num,
+  );
+  v = v.replace(/(^|[\s(,])0\.(\d)/g, "$1.$2");
+  if (/^[A-Za-z-]+$/.test(v)) v = v.toLowerCase();
+  if (/^-?\d*\.?\d+rem$/.test(v)) v = `${lengthToPx(v)}px`;
+  return v;
+}
+
+function expandHex(hex) {
+  if (hex.length === 3 || hex.length === 4) return [...hex].map((c) => c + c).join("");
+  return hex;
+}
+
+/** Evaluate innermost calc() expressions made only of px/rem/unitless terms. */
+export function evaluateCalcs(value) {
+  let prev;
+  let v = value;
+  do {
+    prev = v;
+    v = v.replace(/calc\(([^()]*)\)/g, (whole, expr) => {
+      const result = evaluateLength(expr);
+      return result === null ? whole : result;
+    });
+  } while (v !== prev);
+  return v;
+}
+
+/**
+ * Evaluate `a op b op c` where terms are px, rem or unitless numbers.
+ * Returns a px string ("8px") or a unitless number string, or null.
+ */
+export function evaluateLength(expr) {
+  const tokens = expr.match(/-?\d*\.?\d+(?:px|rem)?|[+\-*/]/g);
+  if (!tokens || tokens.join("").replace(/\s/g, "") !== expr.replace(/\s/g, "")) return null;
+  // Terms: { n: number, unit: "px" | "" }
+  const terms = [];
+  const ops = [];
+  let expectTerm = true;
+  for (const t of tokens) {
+    if (expectTerm) {
+      const m = /^(-?\d*\.?\d+)(px|rem)?$/.exec(t);
+      if (!m) return null;
+      const n = Number(m[1]) * (m[2] === "rem" ? ROOT_FONT_SIZE_PX : 1);
+      terms.push({ n, unit: m[2] ? "px" : "" });
+      expectTerm = false;
+    } else {
+      if (!/^[+\-*/]$/.test(t)) return null;
+      ops.push(t);
+      expectTerm = true;
+    }
+  }
+  if (expectTerm) return null;
+  // * and / first
+  for (let i = 0; i < ops.length; ) {
+    if (ops[i] === "*" || ops[i] === "/") {
+      const a = terms[i];
+      const b = terms[i + 1];
+      let r;
+      if (ops[i] === "*") {
+        if (a.unit && b.unit) return null;
+        r = { n: a.n * b.n, unit: a.unit || b.unit };
+      } else {
+        if (b.unit || b.n === 0) return null;
+        r = { n: a.n / b.n, unit: a.unit };
+      }
+      terms.splice(i, 2, r);
+      ops.splice(i, 1);
+    } else i++;
+  }
+  let acc = terms[0];
+  for (let i = 0; i < ops.length; i++) {
+    const b = terms[i + 1];
+    if (acc.unit !== b.unit) return null;
+    acc = { n: ops[i] === "+" ? acc.n + b.n : acc.n - b.n, unit: acc.unit };
+  }
+  const n = Math.round(acc.n * 10000) / 10000;
+  return `${n}${acc.unit}`;
+}
+
+/** Normalise a length-ish value to px when it is a plain rem/px value. */
+export function lengthToPx(value) {
+  const m = /^(-?\d*\.?\d+)(px|rem)$/.exec(String(value).trim());
+  if (!m) return null;
+  return Number(m[1]) * (m[2] === "rem" ? ROOT_FONT_SIZE_PX : 1);
+}
+
+export function sameValue(a, b) {
+  if (a === undefined || b === undefined) return a === b;
+  const na = normalizeValue(a);
+  const nb = normalizeValue(b);
+  if (na === nb) return true;
+  const pa = lengthToPx(na);
+  const pb = lengthToPx(nb);
+  return pa !== null && pa === pb;
+}
+
+/** Names referenced through `var(--name…)` in a value, in order. */
+export function referencedVars(value) {
+  return [...String(value).matchAll(/var\(\s*(--[\w-]+)/g)].map((m) => m[1]);
+}
+
+const INVALID = Symbol("invalid");
+
+/**
+ * Compute custom-property values for one element.
+ * @param {Map<string, {value: string}>} winners own declarations
+ * @param {Map<string, string>} inherited parent's (or, for CM-16, the design
+ *   system sheet's) computed values
+ * @returns {Map<string, string>} computed values (invalid ones omitted)
+ */
+export function computeCustomProperties(winners, inherited = new Map()) {
+  const computed = new Map();
+  const state = new Map(); // prop -> "visiting" | "done"
+  const visit = (prop) => {
+    if (!winners.has(prop)) return inherited.has(prop) ? inherited.get(prop) : undefined;
+    if (state.get(prop) === "done") return computed.has(prop) ? computed.get(prop) : INVALID;
+    if (state.get(prop) === "visiting") return INVALID;
+    state.set(prop, "visiting");
+    const value = substitute(winners.get(prop).value, visit);
+    state.set(prop, "done");
+    if (value === INVALID) computed.delete(prop);
+    else computed.set(prop, value);
+    return value;
+  };
+  for (const prop of winners.keys()) visit(prop);
+  const out = new Map(inherited);
+  for (const prop of winners.keys()) {
+    if (computed.has(prop)) out.set(prop, computed.get(prop));
+    else out.delete(prop); // guaranteed-invalid: behaves as unset for custom props
+  }
+  return out;
+}
+
+/** Replace every var() in `value`; returns INVALID when a cycle is hit. */
+function substitute(value, lookup) {
+  let out = "";
+  let i = 0;
+  while (i < value.length) {
+    const start = value.indexOf("var(", i);
+    if (start === -1 || (start > 0 && /[\w-]/.test(value[start - 1]))) {
+      if (start === -1) {
+        out += value.slice(i);
+        break;
+      }
+      out += value.slice(i, start + 4);
+      i = start + 4;
+      continue;
+    }
+    out += value.slice(i, start);
+    const end = matchParen(value, start + 3);
+    if (end === -1) {
+      out += value.slice(start);
+      break;
+    }
+    const inner = value.slice(start + 4, end);
+    const comma = topLevelComma(inner);
+    const name = (comma === -1 ? inner : inner.slice(0, comma)).trim();
+    const fallback = comma === -1 ? null : inner.slice(comma + 1).trim();
+    const resolved = lookup(name);
+    if (resolved === INVALID) return INVALID;
+    if (resolved !== undefined) out += resolved;
+    else if (fallback !== null) {
+      const fb = substitute(fallback, lookup);
+      if (fb === INVALID) return INVALID;
+      out += fb;
+    } else out += `var(${name})`; // external: keep it visible
+    i = end + 1;
+  }
+  return out;
+}
+
+function matchParen(s, open) {
+  let depth = 0;
+  for (let i = open; i < s.length; i++) {
+    if (s[i] === "(") depth++;
+    else if (s[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+function topLevelComma(s) {
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "(") depth++;
+    else if (s[i] === ")") depth--;
+    else if (s[i] === "," && depth === 0) return i;
+  }
+  return -1;
+}

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/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;
+}