forgebook 0.3.3 → 0.4.1

package/dist/bin/forgebook/migrate/migrateCommand.mjs

@@ -0,0 +1,76 @@
+/**
+ * `forgebook migrate`: the codemods of `forgebook`'s breaking changes, run on a project's configuration and preset modules.
+ * Lists the changes by default, writes them with `--write`.
+ *
+ * @module
+ */
+import { resolve } from "node:path";
+import { EXIT } from "@ensiria/cli-kit/constants";
+import { formatJson } from "@ensiria/cli-kit/files";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { COMMAND, configPathOf } from "../catalogueCommands.js";
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const migrateCommands = (forgebook) => ({
+    migrate: forgebook.command({
+        summary: "Rewrite a project for Forgebook's breaking changes: list them (exit 1 while some are unwritten), then write them with --write.",
+        json: true,
+        positionals: [
+            {
+                name: "files",
+                variadic: true,
+                description: "Other modules holding a preset or a configuration, inside the current folder and outside node_modules; the configuration is always read."
+            }
+        ],
+        options: {
+            write: { type: "boolean", description: "Write the changes; without it they are only listed." },
+            from: {
+                type: "string",
+                valueName: "version",
+                description: "The version of forgebook the project upgrades from (0.3.3): only the changes since, including those that keep an old behaviour."
+            },
+            only: {
+                type: "string",
+                multiple: true,
+                valueName: "id",
+                description: "Only this codemod; repeat for more."
+            }
+        },
+        examples: [
+            { command: `${COMMAND} migrate --from 0.3.3`, description: "What upgrading from 0.3.3 changes." },
+            { command: `${COMMAND} migrate --from 0.3.3 --write`, description: "Make the changes." },
+            {
+                command: `${COMMAND} migrate src/preset.ts --json`,
+                description: "A library's preset too, as an agent asks."
+            }
+        ],
+        run: async ({ positionals, options, io, isJson }) => {
+            const { isMigrationPending, requestProblem, runMigrate } = await import("./migrateRun.js");
+            const { migrateText } = await import("./migrateText.js");
+            const request = {
+                cwd: process.cwd(),
+                config: configPathOf(options.config),
+                modules: positionals.map((file) => resolve(file)),
+                from: options.from,
+                only: options.only.length === 0 ? undefined : options.only,
+                isWrite: options.write === true
+            };
+            const problem = requestProblem(request);
+            if (problem !== undefined)
+                throw new ScriptError(problem, { exitCode: EXIT.usage });
+            let document;
+            try {
+                document = runMigrate(request);
+            }
+            catch (error) {
+                throw new ScriptError(error instanceof Error ? error.message : String(error));
+            }
+            io.stdout.write(isJson ? formatJson(document) : `${migrateText(document)}\n`);
+            if (isMigrationPending(document))
+                throw new ScriptError(document.summary, { exitCode: EXIT.failure, isReported: true });
+        }
+    })
+});

package/dist/bin/forgebook/migrate/migrateRun.d.ts

@@ -0,0 +1,61 @@
+import type { MigrateDocument } from "./migrate.types.ts";
+/** What the command was asked. */
+export type MigrateRequest = {
+    /** The folder the command runs in, which the files are named from. */
+    readonly cwd: string;
+    /** The configuration file, absolute; none when there is none and only modules are given. */
+    readonly config?: string | undefined;
+    /** Other modules holding a preset or a configuration, absolute. */
+    readonly modules: readonly string[];
+    /** The version the project upgrades from (`0.3.3`); none to run every rewrite. */
+    readonly from?: string | undefined;
+    /** The codemods to run, by id; none for all that apply. */
+    readonly only?: readonly string[] | undefined;
+    /** Whether to write the files, or only list the changes. */
+    readonly isWrite: boolean;
+};
+/**
+ * Whether one version comes before another: by their numbers, and a prerelease (`0.4.0-rc.1`) before its release, since
+ * a change of 0.4.0 may have landed after its prerelease was cut.
+ *
+ * @param version - the version.
+ * @param other - the version compared with.
+ */
+export declare const isVersionBefore: (version: string, other: string) => boolean;
+/**
+ * Why a request cannot run, or none: a version that is not one, a codemod nobody wrote.
+ *
+ * @param request - the request.
+ */
+export declare const migrateProblem: (request: Pick<MigrateRequest, "from" | "only">) => string | undefined;
+/**
+ * Why a module given by path is not migrated, or none: one under `node_modules` is a package's, which an install puts back,
+ * and one outside the folder the command runs in is another project's. Its link is followed, so a link cannot lead out.
+ *
+ * @param path - the module, absolute and present.
+ * @param cwd - the folder the command runs in.
+ */
+export declare const moduleProblem: (path: string, cwd: string) => string | undefined;
+/**
+ * Why a request cannot run, or none: its version or codemods (`migrateProblem`), no file at all, a file that is not
+ * there, a module that is not the project's own (`moduleProblem`).
+ *
+ * @param request - the request.
+ */
+export declare const requestProblem: (request: MigrateRequest) => string | undefined;
+/**
+ * Runs the codemods a request chooses on its files, and writes them when asked: every file is read and rewritten before
+ * any is written, and each is written whole (`writeMigrated`).
+ *
+ * @param request - the request, already checked with `migrateProblem`.
+ * @returns what changed or would change, what to check, and the notes for the versions crossed.
+ * @throws a `MigrateWriteError` when a file cannot be written, naming those that were.
+ */
+export declare const runMigrate: (request: MigrateRequest) => MigrateDocument;
+/**
+ * Whether a migration leaves work to do: changes listed and not written. Advice and notes are for a person to read, and
+ * leave the exit code at 0, so that a project that went through them ends clean.
+ *
+ * @param document - what `runMigrate` answered.
+ */
+export declare const isMigrationPending: (document: MigrateDocument) => boolean;

package/dist/bin/forgebook/migrate/migrateRun.js

@@ -0,0 +1,210 @@
+/**
+ * What `forgebook migrate` does: picks the codemods for the versions a project crosses, runs them on its configuration and
+ * the preset modules given, and writes the result only when asked.
+ *
+ * @remarks
+ * Nothing of the project runs: each file is read as text and rewritten as text. The command imports this module when it
+ * runs, so the compiler it needs loads for no other command.
+ *
+ * @module
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, relative, sep } from "node:path";
+import { CODEMODS, MIGRATION_NOTES } from "./codemods.js";
+import { writeMigrated } from "./migrateWrite.js";
+import { appliedEdits } from "./objectEdits.js";
+/**
+ * A version read; none when it is not `major.minor.patch` (a `v` before it, a prerelease or build after it allowed).
+ *
+ * @param version - the version.
+ */
+const readVersion = (version) => {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(-[^+]*)?(?:\+.*)?$/.exec(version.trim());
+    return match === null
+        ? undefined
+        : {
+            numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+            isPrerelease: match[4] !== undefined
+        };
+};
+/**
+ * Whether one version comes before another: by their numbers, and a prerelease (`0.4.0-rc.1`) before its release, since
+ * a change of 0.4.0 may have landed after its prerelease was cut.
+ *
+ * @param version - the version.
+ * @param other - the version compared with.
+ */
+export const isVersionBefore = (version, other) => {
+    const left = readVersion(version) ?? { numbers: [0, 0, 0], isPrerelease: false };
+    const right = readVersion(other) ?? { numbers: [0, 0, 0], isPrerelease: false };
+    for (let index = 0; index < 3; index += 1) {
+        const difference = (left.numbers[index] ?? 0) - (right.numbers[index] ?? 0);
+        if (difference !== 0)
+            return difference < 0;
+    }
+    return left.isPrerelease && !right.isPrerelease;
+};
+/**
+ * Why a request cannot run, or none: a version that is not one, a codemod nobody wrote.
+ *
+ * @param request - the request.
+ */
+export const migrateProblem = (request) => {
+    if (request.from !== undefined && readVersion(request.from) === undefined)
+        return `--from ${request.from} is not a version: write it as 0.3.3`;
+    const ids = CODEMODS.map((codemod) => codemod.id);
+    const unknown = (request.only ?? []).filter((id) => !ids.includes(id));
+    return unknown.length === 0
+        ? undefined
+        : `No codemod ${unknown.join(", ")}: the codemods are ${ids.join(", ")}`;
+};
+/**
+ * Why a module given by path is not migrated, or none: one under `node_modules` is a package's, which an install puts back,
+ * and one outside the folder the command runs in is another project's. Its link is followed, so a link cannot lead out.
+ *
+ * @param path - the module, absolute and present.
+ * @param cwd - the folder the command runs in.
+ */
+export const moduleProblem = (path, cwd) => {
+    const real = realpathSync(path);
+    if (real.split(sep).includes("node_modules"))
+        return `${path} is inside node_modules: migrate the package's own sources, not its installed copy`;
+    const inside = relative(realpathSync(cwd), real);
+    if (inside === "" || inside.startsWith("..") || isAbsolute(inside))
+        return `${path} is outside ${cwd}: run forgebook migrate from the project that holds it`;
+    return undefined;
+};
+/**
+ * Why a request cannot run, or none: its version or codemods (`migrateProblem`), no file at all, a file that is not
+ * there, a module that is not the project's own (`moduleProblem`).
+ *
+ * @param request - the request.
+ */
+export const requestProblem = (request) => {
+    const choiceProblem = migrateProblem(request);
+    if (choiceProblem !== undefined)
+        return choiceProblem;
+    if (request.config === undefined && request.modules.length === 0)
+        return "No forgebook.config.ts here, and no file given: run forgebook migrate in the catalogue's folder, or give --config or the files";
+    const missing = [...(request.config === undefined ? [] : [request.config]), ...request.modules].find((file) => !existsSync(file));
+    if (missing !== undefined)
+        return `No file ${missing}`;
+    return request.modules.map((file) => moduleProblem(file, request.cwd)).find((each) => each !== undefined);
+};
+/** The codemods a request runs, and those it does not with why. */
+const chosenCodemods = (request) => {
+    const chosen = [];
+    const skipped = [];
+    for (const codemod of CODEMODS) {
+        const isNamed = request.only?.includes(codemod.id) === true;
+        if (request.only !== undefined && !isNamed) {
+            skipped.push({ codemod: codemod.id, reason: "not named by --only" });
+        }
+        else if (request.from !== undefined && !isVersionBefore(request.from, codemod.breaksIn)) {
+            skipped.push({
+                codemod: codemod.id,
+                reason: `${request.from} already has the change of ${codemod.breaksIn}`
+            });
+        }
+        else if (request.from === undefined && codemod.kind === "keep" && !isNamed) {
+            skipped.push({
+                codemod: codemod.id,
+                reason: `it keeps a behaviour from before ${codemod.breaksIn}, which a project may not want: give --from with the version you upgrade from, or --only ${codemod.id}`
+            });
+        }
+        else {
+            chosen.push(codemod);
+        }
+    }
+    return { chosen, skipped };
+};
+/** An edit's text, without the commas and spaces around it that only join it to its neighbours. */
+const shown = (text) => text.replace(/^[\s,]+|[\s,]+$/g, "");
+/**
+ * Runs the codemods on one file, each on the text the one before it left.
+ *
+ * @param file - the file.
+ * @param name - its name in the document.
+ * @param codemods - the codemods chosen.
+ */
+const migratedText = ({ path, kind }, name, codemods) => {
+    const original = readFileSync(path, "utf8");
+    const changes = [];
+    const advice = [];
+    let text = original;
+    for (const codemod of codemods.filter((each) => each.files.includes(kind))) {
+        const result = codemod.run(text, path);
+        const shownEdits = result.edits.map((edit) => ({
+            file: name,
+            codemod: codemod.id,
+            removed: shown(text.slice(edit.start, edit.end)),
+            added: shown(edit.insert)
+        }));
+        // an edit that only moves a comma is part of the one beside it
+        changes.push(...shownEdits.filter((change) => change.removed !== "" || change.added !== ""));
+        advice.push(...result.advice.map((each) => ({ file: name, codemod: codemod.id, text: each })));
+        text = appliedEdits(text, result.edits);
+    }
+    return { path, original, text, changes, advice };
+};
+/**
+ * A count with its noun, singular for one.
+ *
+ * @param count - the count.
+ * @param noun - the noun, singular; its plural adds an s.
+ */
+const counted = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
+/** The document's sentence: what changed or would, and what to check. */
+const summaryOf = (changes, advice, isWrite) => {
+    const files = counted(new Set(changes.map((change) => change.file)).size, "file");
+    let done = "Nothing to rewrite";
+    if (changes.length > 0)
+        done = isWrite
+            ? `${counted(changes.length, "change")} written to ${files}`
+            : `${counted(changes.length, "change")} to make in ${files}: run again with --write`;
+    return `${done}${advice.length === 0 ? "" : `; ${counted(advice.length, "place")} to check`}.`;
+};
+/**
+ * Runs the codemods a request chooses on its files, and writes them when asked: every file is read and rewritten before
+ * any is written, and each is written whole (`writeMigrated`).
+ *
+ * @param request - the request, already checked with `migrateProblem`.
+ * @returns what changed or would change, what to check, and the notes for the versions crossed.
+ * @throws a `MigrateWriteError` when a file cannot be written, naming those that were.
+ */
+export const runMigrate = (request) => {
+    const { chosen, skipped } = chosenCodemods(request);
+    const fileOf = (path, kind) => ({ path, kind });
+    const files = [
+        ...(request.config === undefined ? [] : [fileOf(request.config, "config")]),
+        ...[...new Set(request.modules)]
+            .filter((path) => path !== request.config)
+            .map((path) => fileOf(path, "module"))
+    ];
+    const nameOf = (path) => relative(request.cwd, path) || path;
+    const migrated = files.map((file) => migratedText(file, nameOf(file.path), chosen));
+    if (request.isWrite)
+        writeMigrated(migrated.filter(({ original, text }) => text !== original), nameOf);
+    const changes = migrated.flatMap((each) => each.changes);
+    const advice = migrated.flatMap((each) => each.advice);
+    return {
+        schema: 1,
+        ...(request.from === undefined ? {} : { from: request.from }),
+        isWritten: request.isWrite && changes.length > 0,
+        files: files.map(({ path }) => nameOf(path)),
+        changes,
+        advice,
+        skipped,
+        notes: MIGRATION_NOTES.filter((note) => note.package !== "forgebook" ||
+            request.from === undefined ||
+            isVersionBefore(request.from, note.breaksIn)),
+        summary: summaryOf(changes, advice, request.isWrite)
+    };
+};
+/**
+ * Whether a migration leaves work to do: changes listed and not written. Advice and notes are for a person to read, and
+ * leave the exit code at 0, so that a project that went through them ends clean.
+ *
+ * @param document - what `runMigrate` answered.
+ */
+export const isMigrationPending = (document) => document.changes.length > 0 && !document.isWritten;

package/dist/bin/forgebook/migrate/migrateText.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What `forgebook migrate` prints for a person: each file's changes, what to check, the codemods not run and the notes.
+ *
+ * @module
+ */
+import type { MigrateDocument } from "./migrate.types.ts";
+/**
+ * The answer as a person reads it.
+ *
+ * @param document - what `runMigrate` answered.
+ */
+export declare const migrateText: (document: MigrateDocument) => string;

package/dist/bin/forgebook/migrate/migrateText.js

@@ -0,0 +1,30 @@
+/**
+ * The answer as a person reads it.
+ *
+ * @param document - what `runMigrate` answered.
+ */
+export const migrateText = (document) => {
+    const lines = [];
+    for (const file of new Set(document.changes.map((change) => change.file))) {
+        lines.push(file);
+        for (const change of document.changes.filter((each) => each.file === file)) {
+            const removed = change.removed === "" ? [] : change.removed.split("\n").map((line) => `  - ${line.trim()}`);
+            const added = change.added === "" ? [] : change.added.split("\n").map((line) => `  + ${line.trim()}`);
+            lines.push(...removed, ...added, `    (${change.codemod})`);
+        }
+    }
+    if (document.advice.length > 0) {
+        lines.push("", "To check:");
+        lines.push(...document.advice.map((each) => `  ${each.file}: ${each.text} (${each.codemod})`));
+    }
+    if (document.skipped.length > 0) {
+        lines.push("", "Not run:");
+        lines.push(...document.skipped.map((each) => `  ${each.codemod}: ${each.reason}`));
+    }
+    if (document.notes.length > 0) {
+        lines.push("", "Breaking changes with no codemod, to check by hand:");
+        lines.push(...document.notes.map((note) => `  ${note.id} (${note.package} ${note.breaksIn}): ${note.text}`));
+    }
+    lines.push("", document.summary);
+    return lines.join("\n").replace(/^\n+/, "");
+};

package/dist/bin/forgebook/migrate/migrateWrite.d.ts

@@ -0,0 +1,27 @@
+/** A file to write: where, and its new text. */
+export type MigratedWrite = {
+    /** The file's path, absolute. */
+    readonly path: string;
+    /** Its new text. */
+    readonly text: string;
+};
+/** A write that stopped: which files were replaced before it did, by their names in the document. */
+export declare class MigrateWriteError extends Error {
+    /** The files replaced before the error, as the document names them. */
+    readonly written: readonly string[];
+    /**
+     * The error.
+     *
+     * @param message - what failed.
+     * @param written - the files replaced before it.
+     */
+    constructor(message: string, written: readonly string[]);
+}
+/**
+ * Writes the migrated files, each through a temporary file renamed over it.
+ *
+ * @param files - the files whose text changed.
+ * @param nameOf - a file's name in the document, for the error.
+ * @throws a `MigrateWriteError` naming the files already replaced, the temporary files removed.
+ */
+export declare const writeMigrated: (files: readonly MigratedWrite[], nameOf: (path: string) => string) => void;

package/dist/bin/forgebook/migrate/migrateWrite.js

@@ -0,0 +1,66 @@
+/**
+ * How `forgebook migrate --write` puts its files on disk: each written whole beside its target and renamed over it, so a
+ * file is either as it was or as migrated, never half written.
+ *
+ * @remarks
+ * Every new text is written to its temporary file first, and only then are they renamed, one after the other: a disk that
+ * is full or a folder that cannot be written stops the run before any file is replaced. A rename can still fail midway
+ * (a file locked on Windows), so the error names the files already replaced. A link is followed to the file it points at,
+ * which is what gets replaced, and the link stays a link.
+ *
+ * @module
+ */
+import { realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+/** A write that stopped: which files were replaced before it did, by their names in the document. */
+export class MigrateWriteError extends Error {
+    /** The files replaced before the error, as the document names them. */
+    written;
+    /**
+     * The error.
+     *
+     * @param message - what failed.
+     * @param written - the files replaced before it.
+     */
+    constructor(message, written) {
+        super(message);
+        this.name = "MigrateWriteError";
+        this.written = written;
+    }
+}
+/**
+ * The temporary file beside a target: in its folder, so that the rename stays on one disk and is atomic.
+ *
+ * @param target - the target's real path.
+ */
+const temporaryOf = (target) => `${target}.forgebook-migrate-${process.pid}.tmp`;
+/**
+ * Writes the migrated files, each through a temporary file renamed over it.
+ *
+ * @param files - the files whose text changed.
+ * @param nameOf - a file's name in the document, for the error.
+ * @throws a `MigrateWriteError` naming the files already replaced, the temporary files removed.
+ */
+export const writeMigrated = (files, nameOf) => {
+    const staged = [];
+    const written = [];
+    try {
+        for (const { path, text } of files) {
+            const target = realpathSync(path);
+            const temporary = temporaryOf(target);
+            // listed before it is written, so that a write that fails halfway is removed too
+            staged.push({ path, target, temporary });
+            writeFileSync(temporary, text, { mode: statSync(target).mode });
+        }
+        for (const { path, target, temporary } of staged) {
+            renameSync(temporary, target);
+            written.push(nameOf(path));
+        }
+    }
+    catch (error) {
+        for (const { temporary } of staged)
+            rmSync(temporary, { force: true });
+        const reason = error instanceof Error ? error.message : String(error);
+        const done = written.length === 0 ? "no file was changed" : `already written: ${written.join(", ")}`;
+        throw new MigrateWriteError(`Could not write the migrated files (${reason}); ${done}`, written);
+    }
+};

package/dist/bin/forgebook/migrate/objectEdits.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The text edits the codemods of `forgebook migrate` share: a file parsed, a configuration's object found, properties of an
+ * object literal removed or added, and edits applied.
+ *
+ * @remarks
+ * The file is edited as text, at the places the compiler's tree gives, so everything a codemod does not touch keeps its
+ * formatting and comments: printing the tree again would rewrite the whole file in the printer's style. A property alone on
+ * its lines is removed with its lines; one sharing a line with others is cut out of it.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import type { TextEdit } from "./migrate.types.ts";
+/**
+ * A file's tree, with each node's parent set.
+ *
+ * @param text - the file's text.
+ * @param path - its path, for the kind of script.
+ */
+export declare const parsedFile: (text: string, path: string) => ts.SourceFile;
+/**
+ * A property's name as written, when it is a plain one (`play`, `"propGroups.choice"`); none for a spread, a method or a
+ * computed name.
+ *
+ * @param element - the object literal's element.
+ */
+export declare const propertyName: (element: ts.ObjectLiteralElementLike) => string | undefined;
+/**
+ * The object literal an expression stands for, as written in the file (through a name it declares, `satisfies`, `as`);
+ * none when it is built some other way.
+ *
+ * @param expression - the expression.
+ * @param file - the file.
+ */
+export declare const objectLiteralOf: (expression: ts.Expression, file: ts.SourceFile) => ts.ObjectLiteralExpression | undefined;
+/**
+ * The object a configuration file exports by default, as written in it; none when the file builds it some other way (a
+ * function's result, an import).
+ *
+ * @param file - the configuration's tree.
+ */
+export declare const defaultExportObject: (file: ts.SourceFile) => ts.ObjectLiteralExpression | undefined;
+/**
+ * The edits that remove some of an object literal's properties, keeping the others as written. Removing all of them leaves
+ * `{}`.
+ *
+ * @param file - the file's tree.
+ * @param object - the object literal.
+ * @param removed - the properties to remove, of that object.
+ */
+export declare const removalEdits: (file: ts.SourceFile, object: ts.ObjectLiteralExpression, removed: ReadonlySet<ts.ObjectLiteralElementLike>) => TextEdit[];
+/**
+ * The edit that adds a property to an object literal before one of its properties, or after the last when none is given,
+ * in the object's own layout: on a line of its own when the properties are, inline when they share one.
+ *
+ * @param file - the file's tree.
+ * @param object - the object literal.
+ * @param property - the property's text (`play: "on"`), with no comma.
+ * @param before - the property it goes before; none for the end.
+ * @returns the edits: one, or two when the last property needs a comma before the new one.
+ */
+export declare const insertionEdit: (file: ts.SourceFile, object: ts.ObjectLiteralExpression, property: string, before: ts.ObjectLiteralElementLike | undefined) => TextEdit[];
+/**
+ * A text with edits applied, from the last to the first so that each offset still holds.
+ *
+ * @param text - the text.
+ * @param edits - the edits, in any order.
+ * @throws when two edits overlap, which would make the result depend on their order.
+ */
+export declare const appliedEdits: (text: string, edits: readonly TextEdit[]) => string;