@assure-one/design-system 1.30.0 → 1.32.0

package/codemods/lib/registry.mjs

@@ -0,0 +1,30 @@
+/**
+ * The codemod program (plan §29) in the order `upgrade` applies it. Only
+ * codemods listed here can be run by id; the sequence is the plan's.
+ */
+export const CODEMODS = [
+  { id: "CM-15", module: "../transforms/cm-15-dom-selectors.mjs" },
+  { id: "CM-16", module: "../transforms/cm-16-globals-css.mjs" },
+];
+
+export const findCodemod = (id) =>
+  CODEMODS.find((c) => c.id.toLowerCase() === String(id).toLowerCase()) ?? null;
+
+export async function loadCodemod(id) {
+  const entry = findCodemod(id);
+  if (!entry) return null;
+  const mod = await import(new URL(entry.module, import.meta.url).href);
+  if (!mod.meta || typeof mod.transform !== "function") {
+    throw new Error(`${entry.id} does not export \`meta\` and \`transform\``);
+  }
+  if (mod.meta.id !== entry.id) {
+    throw new Error(`${entry.id} exports meta.id ${mod.meta.id}`);
+  }
+  return mod;
+}
+
+export async function loadAll() {
+  const out = [];
+  for (const { id } of CODEMODS) out.push(await loadCodemod(id));
+  return out;
+}

package/codemods/lib/report.mjs

@@ -0,0 +1,119 @@
+/**
+ * Report rendering. Every codemod produces the same JSON report (the machine
+ * form, `runner.mjs`) and the same Markdown rendering of it: what was found,
+ * what was changed and — the `--dry` requirement of plan §29 — what could not
+ * be transformed.
+ */
+
+const bullet = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+export function renderMarkdown(report) {
+  const { codemod, summary } = report;
+  const lines = [];
+  lines.push(`# ${codemod.id} — ${codemod.title}`);
+  lines.push("");
+  lines.push(
+    `Class ${codemod.class}${codemod.class === "X" ? " (report only; no file is modified)" : ""} · ` +
+      `design system ${report.dsVersion} · ${report.dry ? "dry run" : "applied"} · ` +
+      `${report.paths.join(", ")} in ${report.root}`,
+  );
+  lines.push("");
+  lines.push("| Measure | Count |");
+  lines.push("| --- | ---: |");
+  lines.push(`| Files scanned | ${summary.filesScanned} |`);
+  lines.push(`| Findings | ${summary.findings} |`);
+  lines.push(`| … mapped to a registry contract | ${summary.registered} |`);
+  lines.push(`| … not in the registry yet | ${summary.unregistered} |`);
+  lines.push(`| Files ${report.dry ? "that would change" : "changed"} | ${summary.filesChanged} |`);
+  lines.push(`| Could not be transformed | ${summary.notTransformed} |`);
+  lines.push(`| Files with parse errors | ${summary.parseErrors} |`);
+  lines.push("");
+
+  if (report.warnings.length) {
+    lines.push("## Warnings", "");
+    for (const w of report.warnings) lines.push(`- ${w}`);
+    lines.push("");
+  }
+
+  if (Object.keys(summary.byRegistryId).length) {
+    lines.push("## Findings by contract", "");
+    lines.push("| Contract | Findings | Files |");
+    lines.push("| --- | ---: | ---: |");
+    for (const [id, count] of Object.entries(summary.byRegistryId)) {
+      const files = new Set(
+        report.findings.filter((f) => (f.registryId ?? "unregistered") === id).map((f) => f.file),
+      );
+      lines.push(`| ${id} | ${count} | ${files.size} |`);
+    }
+    lines.push("");
+  }
+
+  if (report.findings.length) {
+    lines.push("## Findings", "");
+    const groups = new Map();
+    for (const f of report.findings) {
+      const key = f.registryId ?? "unregistered";
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push(f);
+    }
+    for (const [key, items] of [...groups].sort(([a], [b]) => (a < b ? -1 : 1))) {
+      lines.push(`### ${key} — ${bullet(items.length, "finding")}`, "");
+      for (const f of items) {
+        const where = `${f.file}:${f.line ?? "?"}`;
+        const what = [
+          f.component,
+          f.rule,
+          f.severity && `severity ${f.severity}`,
+          f.gate && `gate ${f.gate}`,
+          f.confidence && `confidence ${f.confidence}`,
+        ]
+          .filter(Boolean)
+          .join(" · ");
+        lines.push(`- \`${where}\` — ${what}`);
+        if (f.match) lines.push(`  - \`${f.match.replace(/`/g, "'")}\``);
+      }
+      lines.push("");
+    }
+  }
+
+  if (report.notTransformed.length) {
+    lines.push("## Could not be transformed", "");
+    for (const n of report.notTransformed) {
+      lines.push(
+        `- \`${n.file}${n.line ? `:${n.line}` : ""}\` — ${n.reason}${n.detail ? `: ${n.detail}` : ""}`,
+      );
+    }
+    lines.push("");
+  }
+
+  if (report.parseErrors.length) {
+    lines.push("## Parse errors", "");
+    for (const e of report.parseErrors.slice(0, 50)) {
+      lines.push(`- \`${e.file}:${e.line ?? "?"}\` — ${e.message}`);
+    }
+    if (report.parseErrors.length > 50) {
+      lines.push(`- … and ${report.parseErrors.length - 50} more`);
+    }
+    lines.push("");
+  }
+
+  if (report.changed.length) {
+    lines.push(`## Files ${report.dry ? "that would change" : "changed"}`, "");
+    for (const rel of report.changed) lines.push(`- \`${rel}\``);
+    lines.push("");
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+/** One line per run, for the terminal. */
+export function renderSummary(report) {
+  const s = report.summary;
+  return (
+    `${report.codemod.id}: ${s.findings} finding(s) in ${s.filesScanned} file(s) — ` +
+    `${s.registered} mapped to a contract, ${s.unregistered} unregistered; ` +
+    `${report.dry ? "would change" : "changed"} ${s.filesChanged} file(s)` +
+    (s.notTransformed ? `; ${s.notTransformed} could not be transformed` : "") +
+    (s.parseErrors ? `; ${s.parseErrors} parse error(s)` : "")
+  );
+}

package/codemods/lib/runner.mjs

@@ -0,0 +1,164 @@
+/**
+ * The codemod runner: guards, file walk, transform, writes, ledger, report.
+ *
+ * One run = one codemod over one project. The runner owns everything the
+ * individual codemods must not repeat: the one-shot and prerequisite guards,
+ * which files are read, that class X never writes, and the report.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { classifyFile, collectFiles } from "./files.mjs";
+import {
+  compareVersions,
+  installedDsVersion,
+  loadPostcss,
+  loadTypeScript,
+} from "./environment.mjs";
+import { appliedIds, guardProblems, readLedger, recordApplied } from "./ledger.mjs";
+import { loadCodemod } from "./registry.mjs";
+
+export const REPORT_SCHEMA = 1;
+
+export class Refused extends Error {
+  constructor(problems) {
+    super(problems.join("\n"));
+    this.name = "Refused";
+    this.problems = problems;
+  }
+}
+
+/**
+ * Runs one codemod.
+ *
+ * @param {string} id codemod id, e.g. "CM-15"
+ * @param {object} options
+ * @param {string} options.root project root (holds package.json and the ledger)
+ * @param {string[]} [options.paths] files or directories (default: the root)
+ * @param {boolean} [options.dry] report only; never write files or the ledger
+ * @param {() => Date} [options.now] clock, for tests
+ * @returns {Promise<object>} the report
+ */
+export async function runCodemod(
+  id,
+  { root, paths = [], dry = false, now = () => new Date() } = {},
+) {
+  const mod = await loadCodemod(id);
+  if (!mod) throw new Refused([`Unknown codemod ${id}. \`run.mjs list\` shows the available ids.`]);
+  const meta = mod.meta;
+  const dsVersion = installedDsVersion();
+  const ledger = readLedger(root);
+  const problems = guardProblems(meta, ledger, dsVersion, compareVersions);
+  // A dry run may preview an already-applied one-shot codemod; missing
+  // prerequisites still refuse, because the preview would be wrong.
+  const blocking = dry ? problems.filter((p) => !p.includes("already applied")) : problems;
+  if (blocking.length) throw new Refused(blocking);
+
+  const ts = meta.usesTypeScript ? await loadTypeScript(root) : null;
+  const postcss = meta.usesPostcss ? await loadPostcss(root) : null;
+  const kinds = new Set(meta.parses ?? ["code"]);
+  const files = collectFiles(root, paths).filter((rel) => {
+    const { kind, test } = classifyFile(rel);
+    return kinds.has(kind) && (meta.includeTests || !test);
+  });
+
+  const findings = [];
+  const notTransformed = [];
+  const parseErrors = [];
+  const changed = [];
+  let scanned = 0;
+
+  for (const rel of files) {
+    const abs = join(root, rel);
+    const source = readFileSync(abs, "utf8");
+    const { kind, test } = classifyFile(rel);
+    const file = { rel, path: abs, source, kind, test };
+    let result;
+    try {
+      result = mod.transform(file, { ts, postcss, meta, root }) ?? {};
+    } catch (error) {
+      notTransformed.push({
+        file: rel,
+        line: null,
+        reason: "error",
+        detail: String(error.message ?? error),
+      });
+      continue;
+    }
+    scanned += 1;
+    const list = Array.isArray(result) ? result : (result.findings ?? []);
+    for (const f of list) findings.push({ file: rel, test, ...f });
+    for (const n of result.notTransformed ?? []) notTransformed.push({ file: rel, ...n });
+    for (const e of result.parseErrors ?? []) parseErrors.push({ file: rel, ...e });
+    const output = Array.isArray(result) ? undefined : result.output;
+    if (output !== undefined && output !== source) {
+      if (meta.class === "X") {
+        throw new Error(`${meta.id} is report-only (class X) but returned a changed ${rel}`);
+      }
+      changed.push(rel);
+      if (!dry) writeFileSync(abs, output);
+    }
+  }
+
+  findings.sort(
+    (a, b) =>
+      a.file.localeCompare(b.file) ||
+      (a.line ?? 0) - (b.line ?? 0) ||
+      a.rule.localeCompare(b.rule) ||
+      String(a.match).localeCompare(String(b.match)),
+  );
+
+  const applied = meta.class !== "X" && !dry && changed.length > 0;
+  const appliedAt = now().toISOString();
+  if (applied)
+    recordApplied(root, { id: meta.id, appliedAt, dsVersion, filesChanged: changed.length });
+
+  return {
+    schema: REPORT_SCHEMA,
+    codemod: { id: meta.id, title: meta.title, class: meta.class, oneShot: Boolean(meta.oneShot) },
+    dsVersion,
+    root,
+    paths: paths.length ? paths : ["."],
+    dry,
+    generatedAt: appliedAt,
+    ledger: {
+      file: ".ds-migrations.json",
+      applied: [...appliedIds(ledger)].sort(),
+      recorded: applied,
+    },
+    summary: {
+      filesScanned: scanned,
+      filesChanged: changed.length,
+      findings: findings.length,
+      registered: findings.filter((f) => f.registryId).length,
+      unregistered: findings.filter((f) => !f.registryId).length,
+      notTransformed: notTransformed.length,
+      parseErrors: parseErrors.length,
+      byRegistryId: countBy(findings, (f) => f.registryId ?? "unregistered"),
+      byRule: countBy(findings, (f) => f.rule),
+    },
+    changed,
+    findings,
+    notTransformed,
+    parseErrors,
+    warnings: dry ? problems.filter((p) => p.includes("already applied")) : [],
+  };
+}
+
+const countBy = (items, key) => {
+  const map = new Map();
+  for (const item of items) map.set(key(item), (map.get(key(item)) ?? 0) + 1);
+  return Object.fromEntries([...map].sort(([a], [b]) => (a < b ? -1 : 1)));
+};
+
+/** Codemods a project has not applied yet, in program order. */
+export async function pendingCodemods(root) {
+  const { CODEMODS } = await import("./registry.mjs");
+  const ids = appliedIds(readLedger(root));
+  const out = [];
+  for (const { id } of CODEMODS) {
+    const mod = await loadCodemod(id);
+    out.push({ ...mod.meta, applied: ids.has(id) });
+  }
+  return out.filter((m) => m.class !== "X" && !m.applied);
+}

package/codemods/run.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Codemod runner for @assure-one/design-system (plan §29).
+ *
+ * From a consumer project:
+ *
+ *   node node_modules/@assure-one/design-system/codemods/run.mjs list
+ *   node node_modules/@assure-one/design-system/codemods/run.mjs CM-15 src --dry
+ *   node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --dry
+ *
+ * Options
+ *   --dry                 report only; write neither files nor the ledger
+ *   --root <dir>          project root (default: nearest package.json above cwd)
+ *   --report <prefix>     write <prefix>.json and <prefix>.md
+ *   --json <file>         write the JSON report
+ *   --md <file>           write the Markdown report
+ *   --print               print the full Markdown report to stdout
+ *   --quiet               print nothing but errors
+ *   --fail-on-findings    exit 1 when a finding maps to a registry contract
+ *
+ * Exit codes: 0 done · 1 findings with --fail-on-findings · 2 usage error
+ * · 3 refused by a ledger or version guard.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import { findProjectRoot } from "./lib/files.mjs";
+import { installedDsVersion } from "./lib/environment.mjs";
+import { renderMarkdown, renderSummary } from "./lib/report.mjs";
+import { CODEMODS, loadAll } from "./lib/registry.mjs";
+import { Refused, pendingCodemods, runCodemod } from "./lib/runner.mjs";
+
+const FLAGS = new Set(["--dry", "--print", "--quiet", "--fail-on-findings", "--help", "-h"]);
+const VALUES = new Set(["--root", "--report", "--json", "--md"]);
+
+function parseArgs(argv) {
+  const options = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (FLAGS.has(arg)) options[arg.replace(/^--?/, "")] = true;
+    else if (VALUES.has(arg)) {
+      const value = argv[i + 1];
+      if (!value) throw new UsageError(`${arg} needs a value`);
+      options[arg.slice(2)] = value;
+      i += 1;
+    } else if (arg.startsWith("-")) throw new UsageError(`Unknown option ${arg}`);
+    else positional.push(arg);
+  }
+  return { options, positional };
+}
+
+class UsageError extends Error {}
+
+const usage = () => `Usage:
+  run.mjs list
+  run.mjs <CM-ID> [paths…] [--dry] [--root dir] [--report prefix] [--print] [--fail-on-findings]
+  run.mjs upgrade [paths…] [--dry]
+
+Codemods: ${CODEMODS.map((c) => c.id).join(", ")} (design system ${installedDsVersion()})
+`;
+
+function writeReport(report, options) {
+  const targets = [];
+  if (options.report)
+    targets.push([`${options.report}.json`, "json"], [`${options.report}.md`, "md"]);
+  if (options.json) targets.push([options.json, "json"]);
+  if (options.md) targets.push([options.md, "md"]);
+  for (const [file, format] of targets) {
+    const path = resolve(file);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(
+      path,
+      format === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderMarkdown(report),
+    );
+  }
+  return targets.map(([file]) => resolve(file));
+}
+
+async function main(argv) {
+  const { options, positional } = parseArgs(argv);
+  if (options.help || options.h || !positional.length) {
+    process.stdout.write(usage());
+    return positional.length ? 0 : 2;
+  }
+  const say = (text) => {
+    if (!options.quiet) process.stdout.write(`${text}\n`);
+  };
+  const command = positional[0];
+  const root = findProjectRoot(options.root ? resolve(options.root) : process.cwd());
+
+  if (command === "list") {
+    const all = await loadAll();
+    say(`Codemods in @assure-one/design-system ${installedDsVersion()}:`);
+    for (const { meta } of all) {
+      const guards = [
+        meta.oneShot ? "one-shot" : null,
+        meta.requires?.codemods?.length ? `after ${meta.requires.codemods.join(", ")}` : null,
+        meta.requires?.dsVersion ? `needs ≥ ${meta.requires.dsVersion}` : null,
+      ].filter(Boolean);
+      say(
+        `  ${meta.id}  [${meta.class}]  ${meta.title}${guards.length ? ` (${guards.join("; ")})` : ""}`,
+      );
+    }
+    const pending = await pendingCodemods(root);
+    say(
+      pending.length
+        ? `Not yet applied in ${root}: ${pending.map((m) => m.id).join(", ")}`
+        : `Nothing to apply in ${root}.`,
+    );
+    return 0;
+  }
+
+  if (command === "upgrade") {
+    const pending = await pendingCodemods(root);
+    if (!pending.length) {
+      say(`Nothing to apply in ${root}; the ledger is up to date.`);
+      return 0;
+    }
+    let code = 0;
+    for (const meta of pending) {
+      const report = await runCodemod(meta.id, {
+        root,
+        paths: positional.slice(1).map((p) => resolve(p)),
+        dry: Boolean(options.dry),
+      });
+      say(renderSummary(report));
+      if (options.print) process.stdout.write(renderMarkdown(report));
+      for (const path of writeReport(report, options)) say(`Report: ${path}`);
+      if (options["fail-on-findings"] && report.summary.registered) code = 1;
+    }
+    return code;
+  }
+
+  const report = await runCodemod(command, {
+    root,
+    paths: positional.slice(1).map((p) => resolve(p)),
+    dry: Boolean(options.dry),
+  });
+  if (options.print) process.stdout.write(renderMarkdown(report));
+  say(renderSummary(report));
+  for (const warning of report.warnings) say(`! ${warning}`);
+  for (const path of writeReport(report, options)) say(`Report: ${path}`);
+  if (report.ledger.recorded) say(`Recorded ${report.codemod.id} in ${root}/${report.ledger.file}`);
+  return options["fail-on-findings"] && report.summary.registered ? 1 : 0;
+}
+
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  if (error instanceof Refused) {
+    process.stderr.write(`Refused:\n${error.problems.map((p) => `  - ${p}`).join("\n")}\n`);
+    process.exitCode = 3;
+  } else if (error instanceof UsageError) {
+    process.stderr.write(`${error.message}\n\n${usage()}`);
+    process.exitCode = 2;
+  } else {
+    process.stderr.write(`${error?.stack ?? error}\n`);
+    process.exitCode = 1;
+  }
+}