@flarum/cli 3.0.12 → 3.0.13

package/lib/steps/upgrade/twopointoh/base.d.ts

@@ -8,6 +8,8 @@ import { ModuleImport } from '../../../utils/ast';
 import { Editor } from 'mem-fs-editor';
 import BaseCommand from '../../../base-command';
 import { PhpProvider } from '../../../providers/php-provider';
+import { Failure } from './step-failures';
+import { Todo } from './todos';
 export type ReplacementResult = {
     imports?: ImportChange[];
     newPath?: string | null;
@@ -28,6 +30,26 @@ export type GitCommit = {
     message: string;
     description: string;
 };
+/**
+ * What a step did, for a program driving the upgrade.
+ */
+export type StepOutcome = {
+    status: 'skipped';
+} | {
+    status: 'no-changes';
+    todos?: Todo[];
+} | {
+    status: 'committed';
+    commit: {
+        sha: string;
+        message: string;
+    };
+    notes: string;
+    todos: Todo[];
+} | {
+    status: 'failed';
+    failures: Failure[];
+};
 export declare abstract class BaseUpgradeStep implements Step<FlarumProviders> {
     abstract type: string;
     composable: boolean;
@@ -37,6 +59,7 @@ export declare abstract class BaseUpgradeStep implements Step<FlarumProviders> {
     protected command: BaseCommand;
     protected php: null | PhpProvider;
     protected step: number;
+    get number(): number;
     protected totalSteps: number;
     protected forceStep: boolean;
     protected root: string;
@@ -47,7 +70,22 @@ export declare abstract class BaseUpgradeStep implements Step<FlarumProviders> {
     abstract replacements(file: string, code: string): Replacement[];
     abstract gitCommit(): GitCommit;
     abstract pauseMessage(): string;
+    /** Whether the step runs for a check, in a worktree that is thrown away. */
+    checking: boolean;
+    /** Work this step leaves that no @TODO comment in a file shows. */
+    protected followUps: Todo[];
+    /**
+     * Leave work for the author that the step can't mark with a @TODO comment,
+     * such as a file that is missing, or a change it can only point out.
+     */
+    protected leaveTodo(file: string, text: string): void;
+    /** The follow-ups, as lines to print under the step's notes. */
+    protected followUpLines(): string[];
     protected fsEditor: null | Editor;
+    /**
+     * Unset until the step runs.
+     */
+    outcome: StepOutcome | null;
     run(fs: Store, paths: Paths, io: IO, providers: FlarumProviders): Promise<Store>;
     applyReplacements(file: string, code: string, advanced: AdvancedContent): Promise<ReplacementResult>;
     ensureImport(file: string, advanced: AdvancedContent, imp: ImportChange): void;

package/lib/steps/upgrade/twopointoh/base.js

@@ -13,10 +13,23 @@ const string_1 = tslib_1.__importDefault(require("string"));
 const simple_git_1 = tslib_1.__importDefault(require("simple-git"));
 const types_1 = require("@babel/types");
 const step_failures_1 = require("./step-failures");
+const todos_1 = require("./todos");
+const terminal_1 = require("../../../utils/terminal");
+/**
+ * The indentation a JSON file's first indented line uses, or the given
+ * fallback when it has none (an empty object, say, or everything on one line).
+ */
+function jsonIndentation(code, fallback) {
+    var _a, _b;
+    return (_b = (_a = code.match(/^[\t ]+(?=\S)/m)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : fallback;
+}
 class BaseUpgradeStep {
     getExposed(_paths, _paramProvider) {
         return (0, pick_deep_1.default)(this.params, this.exposes);
     }
+    get number() {
+        return this.step;
+    }
     constructor(command, root, step, totalSteps, forceStep) {
         this.composable = true;
         this.exposes = [];
@@ -25,7 +38,15 @@ class BaseUpgradeStep {
         this.totalSteps = 0;
         this.forceStep = false;
         this.beforeHook = false;
+        /** Whether the step runs for a check, in a worktree that is thrown away. */
+        this.checking = false;
+        /** Work this step leaves that no @TODO comment in a file shows. */
+        this.followUps = [];
         this.fsEditor = null;
+        /**
+         * Unset until the step runs.
+         */
+        this.outcome = null;
         this.command = command;
         this.step = step;
         this.totalSteps = totalSteps;
@@ -35,14 +56,29 @@ class BaseUpgradeStep {
     before(_file, _code, _advanced) {
         // ...
     }
+    /**
+     * Leave work for the author that the step can't mark with a @TODO comment,
+     * such as a file that is missing, or a change it can only point out.
+     */
+    leaveTodo(file, text) {
+        if (!this.followUps.some((todo) => todo.file === file && todo.text === text)) {
+            this.followUps.push({ file, line: null, text });
+        }
+    }
+    /** The follow-ups, as lines to print under the step's notes. */
+    followUpLines() {
+        return this.followUps.map((todo) => `${chalk_1.default.bgYellow.black(' TO DO ')} ${todo.file}: ${todo.text}`);
+    }
     async run(fs, paths, io, providers) {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d;
         if (this.root !== paths.cwd()) {
             process.chdir(this.root);
         }
         const fsEditor = (0, mem_fs_editor_1.create)(fs);
         this.fsEditor = fsEditor;
         this.php = providers.php;
+        // Until the step gets further: whatever stops it from here on is a failure.
+        this.outcome = { status: 'failed', failures: [] };
         // Stop if there are uncommited changes
         const status = await (0, simple_git_1.default)((_a = paths.requestedDir()) !== null && _a !== void 0 ? _a : paths.cwd()).status();
         if (status === null || status === void 0 ? void 0 : status.files.length) {
@@ -57,18 +93,21 @@ class BaseUpgradeStep {
         if (!this.forceStep && (await this.alreadyCommited((_b = paths.requestedDir()) !== null && _b !== void 0 ? _b : paths.cwd(), this.gitCommit().message))) {
             this.command.log('     => ' + chalk_1.default.bgGreen.bold('    SKIP    '));
             this.command.log('');
+            this.outcome = { status: 'skipped' };
             return fs;
         }
         // Show loading indicator
         let dots = 1;
         let nl = false;
         const progress = () => {
+            if (!(0, terminal_1.isTerminal)())
+                return;
             if (!nl) {
                 this.command.log('');
                 nl = true;
             }
             const filledDots = '.'.repeat(dots) + ' '.repeat(3 - dots);
-            this.command.log('\u001B[A     => ' + chalk_1.default.bold('  WORKING' + filledDots));
+            this.command.log((0, terminal_1.overwrite)() + '     => ' + chalk_1.default.bold('  WORKING' + filledDots));
             dots = (dots + 1) % 4;
         };
         const failures = new step_failures_1.StepFailures();
@@ -162,7 +201,8 @@ class BaseUpgradeStep {
             // and the run refuses to start with a dirty tree, so keeping them would
             // block the re-run this step is asking the author to do.
             await (0, simple_git_1.default)(dir).checkout(['--', '.']);
-            this.command.log('\u001B[A     => ' + chalk_1.default.bgRed.bold('   FAILED   '));
+            this.outcome = { status: 'failed', failures: failures.list() };
+            this.command.log((0, terminal_1.overwrite)() + '     => ' + chalk_1.default.bgRed.bold('   FAILED   '));
             this.command.log('');
             this.command.log(failures.report());
             this.command.log('');
@@ -176,15 +216,28 @@ class BaseUpgradeStep {
             .then((summary) => summary.files.length > 0);
         if (changesMade) {
             await (0, simple_git_1.default)((_d = paths.requestedDir()) !== null && _d !== void 0 ? _d : paths.cwd()).add('.');
-            await this.pauseAndConfirm(this.pauseMessage(), io);
+            const notes = this.pauseMessage();
+            await this.pauseAndConfirm([notes, ...this.followUpLines()].join('\n                     '), io);
             const commit = this.gitCommit();
             const message = commit.message + '\n\n' + commit.description;
-            await (0, create_1.commitAll)((_e = paths.requestedDir()) !== null && _e !== void 0 ? _e : paths.cwd(), message);
-            this.command.log('\u001B[A     => ' + chalk_1.default.bgCyan.bold('   COMMIT   ') + ' ' + chalk_1.default.dim(commit.message));
+            await (0, create_1.commitAll)(dir, message);
+            const sha = (await (0, simple_git_1.default)(dir).revparse(['HEAD'])).trim();
+            this.outcome = {
+                status: 'committed',
+                commit: { sha, message: commit.message },
+                notes: (0, terminal_1.stripAnsi)(notes).trim(),
+                todos: [...(await (0, todos_1.todosAddedBy)(dir, sha)), ...this.followUps],
+            };
+            const label = this.checking ? chalk_1.default.bgYellow.black.bold(' WOULD CHANGE ') : chalk_1.default.bgCyan.bold('   COMMIT   ');
+            this.command.log((0, terminal_1.overwrite)() + '     => ' + label + ' ' + chalk_1.default.dim(commit.message));
             this.command.log('');
         }
         else {
-            this.command.log('\u001B[A     => ' + chalk_1.default.bgGreen.bold(' NO CHANGES '));
+            this.outcome = this.followUps.length > 0 ? { status: 'no-changes', todos: this.followUps } : { status: 'no-changes' };
+            this.command.log((0, terminal_1.overwrite)() + '     => ' + chalk_1.default.bgGreen.bold(' NO CHANGES '));
+            for (const line of this.followUpLines()) {
+                this.command.log('                     ' + line);
+            }
             this.command.log('');
         }
         return fs;
@@ -210,6 +263,11 @@ class BaseUpgradeStep {
                 continue;
             // eslint-disable-next-line no-await-in-loop
             code = await this.updateCode(file, code, result.updated);
+            // Later replacements read the parsed code: parse it again after a text
+            // change, or one that returns a syntax tree would undo this change.
+            if (typeof result.updated === 'string') {
+                advanced = this.advancedContent(file, code);
+            }
             if (((_a = result.imports) === null || _a === void 0 ? void 0 : _a.length) || (result.updated && typeof result.updated !== 'string' && 'program' in result.updated)) {
                 try {
                     advanced = (0, ast_1.parseCode)(code);
@@ -263,8 +321,8 @@ class BaseUpgradeStep {
         if (lang === 'json') {
             // remove comments
             code = code.replace(/^\s*\/\/.*$/gm, '');
-            // remove loose ,
-            code = code.replace(/,\s*}/g, '}');
+            // remove loose , before the end of an object or an array, as tsconfig.json allows
+            code = code.replace(/,(\s*[\]}])/g, '$1');
             try {
                 return JSON.parse(code);
             }
@@ -291,8 +349,11 @@ class BaseUpgradeStep {
             return updated;
         }
         if (lang === 'json') {
-            const space = file === 'composer.json' ? 4 : 2;
-            return JSON.stringify(updated, null, space);
+            // Write the file back the way it was laid out, so the diff only shows
+            // what the step changed.
+            const space = jsonIndentation(code, file === 'composer.json' ? 4 : 2);
+            const json = JSON.stringify(updated, null, space);
+            return code.includes('\r\n') ? json.replace(/\n/g, '\r\n') + (code.endsWith('\r\n') ? '\r\n' : '') : json + (code.endsWith('\n') ? '\n' : '');
         }
         if (updated && 'program' in updated) {
             try {
@@ -306,7 +367,7 @@ class BaseUpgradeStep {
     }
     async pauseAndConfirm(message, io) {
         const stepMarker = chalk_1.default.bgWhite.black.bold('    DONE    ');
-        this.command.log('\u001B[A     => ' + stepMarker + ' ' + message);
+        this.command.log((0, terminal_1.overwrite)() + '     => ' + stepMarker + ' ' + message);
         this.command.log('');
         await this.command.continueWhenReady(io);
     }

package/lib/steps/upgrade/twopointoh/dependencies.d.ts

@@ -1,10 +1,67 @@
-import { BaseUpgradeStep, GitCommit, Replacement } from './base';
+import { AdvancedContent, BaseUpgradeStep, GitCommit, Replacement } from './base';
 export default class Dependencies extends BaseUpgradeStep {
     type: string;
+    /** The TypeScript the extension asked for, when it was not a 4.x. */
+    protected typeScriptWas: string | null;
+    /** What was removed from tsconfig.json, as TypeScript 4.9 doesn't have it. */
+    protected removedCompilerOptions: string[];
+    protected newerSyntax: boolean;
+    /** Constraints left as they were, as they already ask for newer versions. */
+    protected keptNewer: string[];
+    /** Tooling moved from dependencies to devDependencies. */
+    protected movedToDev: string[];
+    /** The typings scripts, and the tooling they run, added to package.json. */
+    protected addedTypings: string[];
     replacements(file: string): Replacement[];
     targets(): string[];
+    advancedContent(file: string, code: string): AdvancedContent;
+    updateCode(file: string, code: string, updated: string | AdvancedContent): Promise<string>;
     gitCommit(): GitCommit;
     pauseMessage(): string;
+    /**
+     * Require at least the given version, leaving a constraint that already
+     * asks for a newer one as it is.
+     */
+    protected raise(dependencies: Record<string, string>, name: string, version: string): void;
     updateComposerJson(): Replacement;
     updatePackageJson(): Replacement;
+    /**
+     * Add the scripts that build and check typings, which a new extension is
+     * scaffolded with and the reusable frontend workflow runs, along with the
+     * tooling they need. Scripts the extension already has are left alone.
+     */
+    protected addTypingsScripts(pkg: Record<string, any>): void;
+    protected hasTsConfig(): boolean;
+    /** The package manager the extension's frontend uses, by its lockfile. */
+    protected packageManager(): 'yarn' | 'npm';
+    /**
+     * Flarum 2.0 extensions only build with their tooling: none of it ends up
+     * in the bundle, so it belongs in devDependencies. Where the extension lists
+     * a tool under both keys, the newer constraint is kept. Other dependencies
+     * may be libraries the bundle includes, so they stay where they are.
+     */
+    protected moveToolingToDevDependencies(pkg: Record<string, any>): void;
+    /**
+     * Drop the compiler options, and option values, TypeScript 4.9 doesn't have:
+     * it refuses a tsconfig.json with any. A tsconfig.json it can read is left
+     * exactly as it was.
+     */
+    updateTsConfig(): Replacement;
+    /**
+     * TypeScript loads every type package in node_modules unless told which,
+     * and 4.9 can't read the @types/node that webpack's minimizer brings along.
+     * Load only the ones the code imports. The file is edited as text so its
+     * comments stay.
+     */
+    limitTypes(): Replacement;
+    /**
+     * A test config extending tsconfig.json would no longer load Jest's globals.
+     */
+    testTypes(): Replacement;
+    /** The extension's js/package.json, or nothing when it has none. */
+    protected packageJson(): Record<string, any>;
+    /**
+     * Put a @TODO above each line using syntax TypeScript 4.9 can't compile.
+     */
+    flagNewerSyntax(): Replacement;
 }