@zerotal/core 1.7.4 → 1.8.0

package/src/upgrade/codemods/deprecated-aliases.ts

@@ -0,0 +1,111 @@
+/**
+ * Ledger #4 — retire the deprecated aliases.
+ *
+ * Three pairs, each a live alias somebody depends on, which is exactly why they
+ * could not be dropped in a minor:
+ *
+ * - `BaseModel` → `Model`. The same class object under its original name.
+ * - `routes:types` → `route:types`. Registered as an alias in `CommandRunner`.
+ * - `serve --dev` → `dev`. The flag still works; `dev` is the command it became.
+ *
+ * ## What this deliberately does not do
+ *
+ * **It does not touch `BaseModel` in a type position.** `Model` and `BaseModel`
+ * are the same runtime class, so a value-position rename is cosmetic and safe.
+ * In a generic bound — `<T extends BaseModel>` — the name may be load-bearing
+ * for a reader even though it resolves identically, and in framework source it
+ * genuinely is. Those are reported for a person instead.
+ *
+ * That asymmetry is the whole reason this is a codemod rather than a
+ * find-and-replace: the mixin-composition script learned it the hard way in
+ * 1.3.0, where a blind rename broke import specifiers it had not considered.
+ */
+import type { Change, Codemod, CodemodResult, Manual, SourceFile } from "../types.ts";
+
+/**
+ * `BaseModel` in a class heritage clause — the one place renaming is safe.
+ *
+ * Anchored on `class Name extends`, not on `extends` alone. A generic bound
+ * writes `<T extends BaseModel>` with the same keyword, and matching that was a
+ * real bug the tests caught: it rewrote precisely the type positions this file
+ * says it will not touch.
+ */
+const BASE_MODEL_VALUE = /\bclass\s+(\w+)(\s*<[^>]*>)?\s+extends\s+BaseModel\b/g;
+
+/** `BaseModel` inside a generic bound or a type annotation. Reported, not rewritten. */
+const BASE_MODEL_TYPE = /<[^>]*\bextends\s+BaseModel\b[^>]*>|:\s*BaseModel\b/;
+
+/** The import specifier, which has to follow the rename or the file stops compiling. */
+const BASE_MODEL_IMPORT = /(\bimport\s*\{[^}]*?)\bBaseModel\b([^}]*?\}\s*from\s*["'][^"']*["'])/g;
+
+const COMMAND_ALIASES: { find: RegExp; replace: string; label: string }[] = [
+  { find: /\broutes:types\b/g, replace: "route:types", label: "`routes:types` → `route:types`" },
+  {
+    find: /\b(zt|zerotal)\s+serve\s+--dev\b/g,
+    replace: "$1 dev",
+    label: "`serve --dev` → `dev`",
+  },
+];
+
+export const deprecatedAliases: Codemod = {
+  version: "2.0.0",
+  name: "deprecated-aliases",
+  description: "Retire BaseModel, routes:types and serve --dev in favour of their real names",
+  ledger: 4,
+
+  run(files: SourceFile[]): CodemodResult {
+    const changes: Change[] = [];
+    const manual: Manual[] = [];
+
+    for (const { file, contents } of files) {
+      let next = contents;
+      const notes: string[] = [];
+
+      // Value positions first, then the import that has to agree with them.
+      const valueHits = next.match(BASE_MODEL_VALUE)?.length ?? 0;
+      if (valueHits > 0) {
+        next = next.replace(
+          BASE_MODEL_VALUE,
+          (_match, name: string, generics = "") => `class ${name}${generics} extends Model`,
+        );
+        notes.push(`${valueHits} × \`extends BaseModel\` → \`extends Model\``);
+      }
+
+      if (valueHits > 0 && BASE_MODEL_IMPORT.test(next)) {
+        BASE_MODEL_IMPORT.lastIndex = 0;
+        // `Model` may already be imported alongside it; collapsing to a single
+        // `Model` in that case would produce a duplicate specifier.
+        next = next.replace(BASE_MODEL_IMPORT, (whole, before: string, after: string) =>
+          /\bModel\b\s*[,}]/.test(before + after)
+            ? whole.replace(/\bBaseModel\b\s*,\s*/, "").replace(/,\s*\bBaseModel\b/, "")
+            : `${before}Model${after}`,
+        );
+        notes.push("import specifier updated");
+      }
+
+      for (const { find, replace, label } of COMMAND_ALIASES) {
+        const hits = next.match(find)?.length ?? 0;
+        if (hits === 0) continue;
+        next = next.replace(find, replace);
+        notes.push(`${hits} × ${label}`);
+      }
+
+      // Type positions are a handover, not a rewrite.
+      contents.split("\n").forEach((line, i) => {
+        if (!BASE_MODEL_TYPE.test(line)) return;
+        manual.push({
+          file,
+          line: i + 1,
+          text: line.trim(),
+          reason:
+            "`BaseModel` in a type position. It resolves to the same class as `Model`, so this " +
+            "compiles either way — renaming it is a readability call, not a correctness one.",
+        });
+      });
+
+      if (next !== contents) changes.push({ file, summary: notes.join(", "), contents: next });
+    }
+
+    return { changes, manual };
+  },
+};

package/src/upgrade/codemods/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Every codemod, in one list.
+ *
+ * The runner orders by version, so the order here is only what a reader sees.
+ * A codemod belongs here the moment its ledger entry is decided, even if the
+ * release that needs it is some way off — the roadmap's rule is that every
+ * ledger entry which *can* have a codemod has one before 2.0 ships, and the way
+ * that rule fails is by everyone assuming there is time.
+ */
+import type { Codemod } from "../types.ts";
+import { deprecatedAliases } from "./deprecated-aliases.ts";
+
+export const CODEMODS: Codemod[] = [deprecatedAliases];
+
+export { deprecatedAliases };

package/src/upgrade/runner.ts

@@ -0,0 +1,148 @@
+/**
+ * The upgrade runner: read the tree once, apply the codemods a version gap
+ * calls for, and report before writing anything.
+ *
+ * `scripts/codemod-mixin-composition.ts` proved the shape on a real 1.3.0 break
+ * — walk the tree, rewrite call sites, fix the imports a find-and-replace would
+ * have broken, offer `--dry`. This generalises that one-off into something a
+ * release can hand to users, which is what `zt upgrade` has to be if the 2.0
+ * ledger is ever going to be payable.
+ *
+ * Three properties it keeps:
+ *
+ * **Nothing is written until the whole plan is known.** Codemods return the new
+ * contents rather than writing, so a run that fails halfway leaves no
+ * half-upgraded tree, and `--dry` is the same code path as the real thing rather
+ * than a separate one that can drift from it.
+ *
+ * **Running twice is safe.** Every codemod is expected to be idempotent, and the
+ * second run is the test: it should report no changes. That matters because the
+ * first thing anyone does after an upgrade that printed warnings is run it again.
+ *
+ * **What it could not do is the headline.** See `Manual` in `./types.ts`.
+ */
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join, extname, relative } from "node:path";
+import type { Change, Codemod, Manual, SourceFile } from "./types.ts";
+import { compareVersions } from "./types.ts";
+
+/** Never walked. Build output and dependencies are not the app's source. */
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".zerotal",
+  ".release-tarballs",
+]);
+
+const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".md", ".mdx"];
+
+export interface UpgradePlan {
+  /** Codemods selected for this version gap, in the order they will run. */
+  codemods: Codemod[];
+  /** Every rewrite, keyed by file — later codemods see earlier ones' output. */
+  changes: Map<string, Change>;
+  manual: Manual[];
+  /** Files read, for the "scanned N files" line. */
+  scanned: number;
+}
+
+/** Every source file under `root`, relative-pathed and forward-slashed. */
+export async function collectFiles(root: string, extensions: string[]): Promise<SourceFile[]> {
+  const wanted = new Set(extensions);
+  const out: SourceFile[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return; // unreadable directory is not a reason to abandon an upgrade
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(full);
+        continue;
+      }
+      if (!wanted.has(extname(entry.name))) continue;
+      out.push({
+        file: relative(root, full).replace(/\\/g, "/"),
+        contents: await readFile(full, "utf8"),
+      });
+    }
+  }
+
+  await walk(root);
+  return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+
+/**
+ * The codemods that apply to a move from `from` to `to`.
+ *
+ * Exclusive of `from`, inclusive of `to`: an app already on 1.8.0 has paid
+ * 1.8.0's codemods, and an app moving *to* 2.0.0 owes 2.0.0's.
+ */
+export function selectCodemods(all: Codemod[], from: string, to: string): Codemod[] {
+  return all
+    .filter((c) => compareVersions(c.version, from) > 0 && compareVersions(c.version, to) <= 0)
+    .sort((a, b) => compareVersions(a.version, b.version) || a.name.localeCompare(b.name));
+}
+
+/**
+ * Build the plan without touching disk.
+ *
+ * Codemods run in sequence over the *accumulated* contents, so a later one sees
+ * what an earlier one produced. Two codemods rewriting the same line is a real
+ * possibility across a version range, and the alternative — each reading the
+ * original — silently drops one of them.
+ */
+export async function planUpgrade(
+  root: string,
+  codemods: Codemod[],
+  from: string,
+  to: string,
+): Promise<UpgradePlan> {
+  const selected = selectCodemods(codemods, from, to);
+  const extensions = [...new Set(selected.flatMap((c) => c.extensions ?? DEFAULT_EXTENSIONS))];
+  const files = await collectFiles(root, extensions.length ? extensions : DEFAULT_EXTENSIONS);
+
+  const current = new Map(files.map((f) => [f.file, f.contents]));
+  const changes = new Map<string, Change>();
+  const manual: Manual[] = [];
+
+  for (const codemod of selected) {
+    const wanted = new Set(codemod.extensions ?? DEFAULT_EXTENSIONS);
+    const input: SourceFile[] = [...current]
+      .filter(([file]) => wanted.has(extname(file)))
+      .map(([file, contents]) => ({ file, contents }));
+
+    const result = codemod.run(input);
+    for (const change of result.changes) {
+      current.set(change.file, change.contents);
+      const existing = changes.get(change.file);
+      changes.set(change.file, {
+        file: change.file,
+        // One line per file in the report, so a file touched by two codemods
+        // reads as one entry naming both rather than appearing twice.
+        summary: existing ? `${existing.summary}; ${change.summary}` : change.summary,
+        contents: change.contents,
+      });
+    }
+    manual.push(...result.manual);
+  }
+
+  return { codemods: selected, changes, manual, scanned: files.length };
+}
+
+/** Write the plan. Separate from building it, so `--dry` shares every other step. */
+export async function applyPlan(root: string, plan: UpgradePlan): Promise<number> {
+  for (const change of plan.changes.values()) {
+    await writeFile(join(root, change.file), change.contents, "utf8");
+  }
+  return plan.changes.size;
+}

package/src/upgrade/types.ts

@@ -0,0 +1,78 @@
+/**
+ * What an upgrade codemod is, and what it has to report.
+ *
+ * The shape is built around one belief: **the interesting output of an upgrade
+ * tool is what it could not do.** A codemod that rewrites nine call sites and
+ * silently walks past a tenth it did not understand is worse than one that
+ * rewrites nothing, because the nine give the impression the job is finished.
+ * So a codemod returns two lists, and the runner prints the second one louder.
+ */
+
+/** A file the codemod would rewrite, or did. */
+export interface Change {
+  /** Repo-relative path, forward slashes. */
+  file: string;
+  /** What changed, in a line a person can scan — "3 × `BaseModel` → `Model`". */
+  summary: string;
+  /** The rewritten contents. Held rather than written, so `--dry` costs nothing extra. */
+  contents: string;
+}
+
+/**
+ * Something the codemod recognised and deliberately did not touch.
+ *
+ * Not an error — a handover. Each one is a place the author has to look, with
+ * enough detail to find it and a reason that explains why a machine should not
+ * decide.
+ */
+export interface Manual {
+  file: string;
+  /** 1-based, so it can be clicked. */
+  line: number;
+  /** The line as it stands. */
+  text: string;
+  /** Why this one is a person's call. */
+  reason: string;
+}
+
+export interface CodemodResult {
+  changes: Change[];
+  manual: Manual[];
+}
+
+/** One file handed to a codemod. */
+export interface SourceFile {
+  file: string;
+  contents: string;
+}
+
+export interface Codemod {
+  /**
+   * The release that makes this necessary.
+   *
+   * Codemods run in version order, and only those between the app's current
+   * version and the target. A codemod for 2.0.0 does not run on an app moving
+   * from 1.6 to 1.7.
+   */
+  version: string;
+  /** Stable identifier, for `--only` and for reporting. */
+  name: string;
+  /** One line, shown in the plan before anything is written. */
+  description: string;
+  /** The ledger entry this pays, if it pays one. */
+  ledger?: number;
+  /** Files this wants to see. Keeps a codemod from scanning what it cannot use. */
+  extensions?: string[];
+  run(files: SourceFile[]): CodemodResult;
+}
+
+/** Compare two `x.y.z` strings numerically. */
+export function compareVersions(a: string, b: string): number {
+  const left = a.split(".").map(Number);
+  const right = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}