@flarum/cli 3.0.12 → 3.0.14

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

@@ -3,10 +3,101 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const base_1 = require("./base");
 const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const typescript_5_9_1 = require("./typescript-5-9");
+// What `fl init` gave 1.x extensions. `sed -i` with no suffix is GNU sed's
+// form: BSD sed, as on macOS, takes the next argument as the suffix and fails.
+// With the suffix attached, both work.
+const GNU_POST_BUILD_TYPINGS = "find dist-typings -type f -name '*.d.ts' -print0 | xargs -0 sed -i 's,../src/@types,@types,g'";
+const PORTABLE_POST_BUILD_TYPINGS = "find dist-typings -type f -name '*.d.ts' -print0 | xargs -0 sed -i.bak 's,../src/@types,@types,g' && find dist-typings -type f -name '*.d.ts.bak' -delete";
+// Packages an extension only needs to build, check and test its frontend.
+const BUILD_TOOLING = new Set([
+    '@flarum/jest-config',
+    '@flarum/prettier-config',
+    'flarum-tsconfig',
+    'flarum-webpack-config',
+    'prettier',
+    'typescript',
+    'typescript-coverage-report',
+    'webpack',
+    'webpack-cli',
+]);
+// The scripts that build and check an extension's typings, as the reusable
+// frontend workflow runs them.
+const TYPINGS_SCRIPTS = ['clean-typings', 'build-typings', 'post-build-typings', 'check-typings', 'check-typings-coverage'];
+// What those scripts run.
+const TYPINGS_TOOLING = ['typescript', 'typescript-coverage-report'];
+/** The package.json `fl init` gives a new extension, for the given package manager. */
+function scaffoldedPackageJson(packageManager) {
+    const skeleton = fs_1.default.readFileSync(path_1.default.resolve(__dirname, '../../../../boilerplate/skeleton/extension/js/package.json'), 'utf8');
+    // EJS placeholders only appear inside strings, so it parses as JSON.
+    return JSON.parse(skeleton.replace(/<%= params\.jsPackageManager %>/g, packageManager));
+}
+const TYPES_COMMENT = [
+    'Only load the type packages the code imports, not every one in',
+    'node_modules, such as the @types/node webpack brings along.',
+];
+/**
+ * The tsconfig.json with an option first in its compilerOptions, and the
+ * comment lines above it, indented as the options there are. Null when it has
+ * no compilerOptions to put it in.
+ */
+function insertCompilerOption(code, comment, option) {
+    var _a;
+    const open = code.match(/"compilerOptions"\s*:\s*{/);
+    if (!open)
+        return null;
+    const at = open.index + open[0].length;
+    const eol = code.includes('\r\n') ? '\r\n' : '\n';
+    const next = code.slice(at).match(/\r?\n([\t ]*)\S/);
+    const indent = (_a = next === null || next === void 0 ? void 0 : next[1]) !== null && _a !== void 0 ? _a : '    ';
+    const lines = [...(comment !== null && comment !== void 0 ? comment : []).map((line) => `// ${line}`), `${option},`];
+    return code.slice(0, at) + lines.map((line) => eol + indent + line).join('') + code.slice(at);
+}
+/** Dependencies in the alphabetical order package managers keep them in. */
+const sortedByName = (dependencies) => Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b)));
+/**
+ * Whether a TypeScript constraint could resolve to TypeScript 6 or newer:
+ * `^6.0.3`, `>=4.2`, `latest`, `*`. A caret, tilde or exact constraint on 4 or
+ * 5 can't.
+ */
+const allowsSixOrNewer = (constraint) => {
+    const match = constraint.trim().match(/^[=^~]?\s*v?(\d+)(?:\.|$)/);
+    return !match || Number(match[1]) >= 6;
+};
+/**
+ * The lowest version a simple constraint allows, as [major, minor, patch]:
+ * `^5.1.4`, `~4.7`, `>=8.3`, `5.x`. Null for anything else, such as `*`, a
+ * range with `||` or a prerelease.
+ */
+const lowestVersion = (constraint) => {
+    const match = constraint.trim().match(/^(?:\^|~|>=|=)?\s*v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/);
+    return match ? match.slice(1).map((part) => (part && /^\d+$/.test(part) ? Number(part) : 0)) : null;
+};
+/** Whether a constraint asks for a newer version than another does. */
+const asksForNewer = (constraint, than) => {
+    const asked = lowestVersion(constraint);
+    const other = lowestVersion(than);
+    if (!asked || !other)
+        return false;
+    const differs = asked.findIndex((part, i) => part !== other[i]);
+    return differs !== -1 && asked[differs] > other[differs];
+};
 class Dependencies extends base_1.BaseUpgradeStep {
     constructor() {
         super(...arguments);
         this.type = 'Update the extension dependencies to the latest versions.';
+        /** The TypeScript the extension asked for, when it allowed TypeScript 6 or newer. */
+        this.typeScriptWas = null;
+        /** What was removed from tsconfig.json, as TypeScript 5.9 refuses it. */
+        this.removedCompilerOptions = [];
+        /** Constraints left as they were, as they already ask for newer versions. */
+        this.keptNewer = [];
+        /** Tooling moved from dependencies to devDependencies. */
+        this.movedToDev = [];
+        /** The typings scripts, and the tooling they run, added to package.json. */
+        this.addedTypings = [];
     }
     replacements(file) {
         const replacements = [];
@@ -16,11 +107,18 @@ class Dependencies extends base_1.BaseUpgradeStep {
                 break;
             case 'js/package.json':
                 replacements.push(this.updatePackageJson());
+                break;
+            case 'js/tsconfig.json':
+                replacements.push(this.updateTsConfig(), this.limitTypes());
+                break;
+            case 'js/tsconfig.test.json':
+                replacements.push(this.testTypes());
+                break;
         }
         return replacements;
     }
     targets() {
-        return ['composer.json', 'js/package.json'];
+        return ['composer.json', 'js/package.json', 'js/tsconfig.json', 'js/tsconfig.test.json'];
     }
     gitCommit() {
         return {
@@ -33,9 +131,33 @@ class Dependencies extends base_1.BaseUpgradeStep {
         const composerUpdate = chalk_1.default.bgYellowBright('composer update');
         const yarn = chalk_1.default.bgYellowBright('yarn');
         const npm = chalk_1.default.bgYellowBright('npm install');
-        return `Dependencies updated. Please review the changes and update any other dependency versions as needed.
-                     It is recommended to run ${composerInstall} or ${composerUpdate} and ${yarn} or ${npm} now.
-                     But you may also leave that until the upgrade process is over.`;
+        const notes = [
+            this.typeScriptWas &&
+                `TypeScript ${this.typeScriptWas} was brought down to ^5.9.3: flarum-tsconfig resolves modules the way TypeScript 6 refuses without ignoreDeprecations.`,
+            this.removedCompilerOptions.length > 0 &&
+                `Removed from js/tsconfig.json, as TypeScript 5.9 refuses them: ${this.removedCompilerOptions.join(', ')}.`,
+            this.addedTypings.length > 0 && `Added what the reusable frontend workflow runs to build and check typings: ${this.addedTypings.join(', ')}.`,
+            this.movedToDev.length > 0 && `Moved to devDependencies, as the extension only builds with them: ${this.movedToDev.join(', ')}.`,
+            this.keptNewer.length > 0 && `Kept, as they already ask for newer versions than Flarum 2.0 needs: ${this.keptNewer.join(', ')}.`,
+        ].filter(Boolean);
+        return [
+            'Dependencies updated. Please review the changes and update any other dependency versions as needed.',
+            ...notes,
+            `It is recommended to run ${composerInstall} or ${composerUpdate} and ${yarn} or ${npm} now.`,
+            'But you may also leave that until the upgrade process is over.',
+        ].join('\n                     ');
+    }
+    /**
+     * Require at least the given version, leaving a constraint that already
+     * asks for a newer one as it is.
+     */
+    raise(dependencies, name, version) {
+        if (asksForNewer(String(dependencies[name]), version)) {
+            this.keptNewer.push(`${name} ${dependencies[name]}`);
+        }
+        else {
+            dependencies[name] = version;
+        }
     }
     updateComposerJson() {
         return (_file, _code, advanced) => {
@@ -52,7 +174,7 @@ class Dependencies extends base_1.BaseUpgradeStep {
                     }
                 });
                 if (key === 'flarum/core') {
-                    composer.require[key] = '^2.0.0';
+                    this.raise(composer.require, key, '^2.0.0');
                 }
                 else if (key.startsWith('flarum/') && value !== '*') {
                     composer.require[key] = '*';
@@ -67,22 +189,20 @@ class Dependencies extends base_1.BaseUpgradeStep {
                     }
                 });
                 if (['flarum/core', 'flarum/testing', 'flarum/phpstan'].includes(key)) {
-                    composer['require-dev'][key] = '^2.0.0';
+                    this.raise(composer['require-dev'], key, '^2.0.0');
                 }
                 else if (key.startsWith('flarum/') && value.startsWith('^1')) {
                     composer['require-dev'][key] = '*';
                 }
             }
+            // An extension using newer PHP than Flarum 2.0 needs keeps asking for it.
             if (composer.require.php) {
-                composer.require.php = '^8.3';
+                this.raise(composer.require, 'php', '^8.3');
             }
-            // 2.0 constraints resolve to prereleases while the line is in RC, so the
-            // extension has to accept them — with stable preferred wherever one
-            // exists, so only Flarum itself comes from the beta channel.
-            composer['minimum-stability'] = 'beta';
-            composer['prefer-stable'] = true;
+            // Flarum 2.0 is stable, so its constraints resolve without changing the
+            // extension's minimum stability.
             if (composer.require['fof/extend']) {
-                composer.require['fof/extend'] = '^2.0.0';
+                this.raise(composer.require, 'fof/extend', '^2.0.0');
             }
             return {
                 updated: composer,
@@ -91,20 +211,47 @@ class Dependencies extends base_1.BaseUpgradeStep {
     }
     updatePackageJson() {
         return (_file, _code, advanced) => {
+            var _a;
             advanced = advanced;
+            // The versions a new extension is scaffolded with. 3.1.0 is the first
+            // flarum-webpack-config that supplies TypeScript 5.9 and only asks for
+            // webpack as a peer, and @flarum/jest-config 2.1.0 tests with the mithril
+            // Flarum ships.
             const map = {
-                'flarum-webpack-config': '^3.0.0',
+                'flarum-webpack-config': '^3.1.0',
                 'flarum-tsconfig': '^2.0.0',
-                '@flarum/jest-config': '^2.0.0',
-                webpack: '^5.65.0',
+                '@flarum/jest-config': '^2.1.0',
+                webpack: '^5.104.1',
                 'webpack-cli': '^4.9.1',
+                // What Flarum builds and checks its typings with.
+                typescript: '^5.9.3',
             };
-            const dependencies = advanced.dependencies || advanced.devDependencies;
-            for (const [key] of Object.entries(dependencies)) {
-                if (map[key]) {
-                    dependencies[key] = map[key];
+            // Extensions list the tooling under either key, often split between both.
+            for (const dependencies of [advanced.dependencies, advanced.devDependencies]) {
+                for (const key of Object.keys(dependencies || {})) {
+                    // TypeScript is the exception: it moves to what Flarum checks typings
+                    // with, whatever the extension asked for. flarum-tsconfig resolves
+                    // modules the way TypeScript 6 refuses, so a newer one comes down,
+                    // unless the extension's tsconfig already resolves them another way.
+                    if (key === 'typescript' && allowsSixOrNewer(String(dependencies[key])) && this.tsConfigReadsWithSixOrNewer()) {
+                        this.keptNewer.push(`${key} ${dependencies[key]}`);
+                    }
+                    else if (key === 'typescript') {
+                        if (allowsSixOrNewer(String(dependencies[key]))) {
+                            this.typeScriptWas = dependencies[key];
+                        }
+                        dependencies[key] = map[key];
+                    }
+                    else if (map[key]) {
+                        this.raise(dependencies, key, map[key]);
+                    }
                 }
             }
+            if (((_a = advanced.scripts) === null || _a === void 0 ? void 0 : _a['post-build-typings']) === GNU_POST_BUILD_TYPINGS) {
+                advanced.scripts['post-build-typings'] = PORTABLE_POST_BUILD_TYPINGS;
+            }
+            this.addTypingsScripts(advanced);
+            this.moveToolingToDevDependencies(advanced);
             // Remove duplicates from devDependencies
             if (advanced.dependencies && advanced.devDependencies) {
                 for (const [key] of Object.entries(advanced.dependencies)) {
@@ -118,5 +265,155 @@ class Dependencies extends base_1.BaseUpgradeStep {
             };
         };
     }
+    /**
+     * 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.
+     */
+    addTypingsScripts(pkg) {
+        const missing = TYPINGS_SCRIPTS.filter((name) => { var _a; return !((_a = pkg.scripts) === null || _a === void 0 ? void 0 : _a[name]); });
+        if (missing.length === 0)
+            return;
+        if (!this.hasTsConfig()) {
+            this.leaveTodo('js/tsconfig.json', 'Add a tsconfig.json, then the scripts that build and check typings, which the reusable frontend workflow runs: ' + missing.join(', ') + '.');
+            return;
+        }
+        const scaffolded = scaffoldedPackageJson(this.packageManager());
+        pkg.scripts = Object.assign({}, pkg.scripts);
+        for (const name of missing) {
+            pkg.scripts[name] = scaffolded.scripts[name];
+        }
+        const listed = Object.assign(Object.assign({}, pkg.dependencies), pkg.devDependencies);
+        const tooling = TYPINGS_TOOLING.filter((name) => !listed[name]);
+        if (tooling.length > 0) {
+            pkg.devDependencies = sortedByName(Object.assign(Object.assign({}, pkg.devDependencies), Object.fromEntries(tooling.map((name) => [name, scaffolded.devDependencies[name]]))));
+        }
+        this.addedTypings.push(...missing, ...tooling);
+    }
+    hasTsConfig() {
+        return fs_1.default.existsSync(path_1.default.join(this.root, 'js/tsconfig.json'));
+    }
+    /** The package manager the extension's frontend uses, by its lockfile. */
+    packageManager() {
+        return fs_1.default.existsSync(path_1.default.join(this.root, 'js/yarn.lock')) ? '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.
+     */
+    moveToolingToDevDependencies(pkg) {
+        const moving = Object.keys(pkg.dependencies || {}).filter((name) => BUILD_TOOLING.has(name) || name.startsWith('@types/'));
+        if (moving.length === 0)
+            return;
+        const devDependencies = Object.assign({}, pkg.devDependencies);
+        for (const name of moving) {
+            if (!devDependencies[name] || asksForNewer(String(pkg.dependencies[name]), String(devDependencies[name]))) {
+                devDependencies[name] = pkg.dependencies[name];
+            }
+            delete pkg.dependencies[name];
+        }
+        pkg.devDependencies = sortedByName(devDependencies);
+        this.movedToDev.push(...moving);
+    }
+    /**
+     * Drop the compiler options, and option values, TypeScript 5.9 refuses: it
+     * won't read a tsconfig.json with any. A tsconfig.json it can read is left
+     * exactly as it was.
+     */
+    updateTsConfig() {
+        return (_file, _code, advanced) => {
+            const tsconfig = advanced;
+            const options = tsconfig.compilerOptions || {};
+            const removed = [];
+            for (const [name, value] of Object.entries(options)) {
+                const known = Object.prototype.hasOwnProperty.call(typescript_5_9_1.compilerOptions, name) ? typescript_5_9_1.compilerOptions[name] : null;
+                if (!known) {
+                    removed.push(name);
+                    delete options[name];
+                }
+                else if (name === 'lib' && Array.isArray(value)) {
+                    const kept = value.filter((lib) => typeof lib === 'string' && typescript_5_9_1.libs.includes(lib.toLowerCase()));
+                    for (const lib of value.filter((lib) => !kept.includes(lib))) {
+                        removed.push(`lib "${lib}"`);
+                    }
+                    if (kept.length === 0) {
+                        delete options.lib;
+                    }
+                    else if (kept.length < value.length) {
+                        options.lib = kept;
+                    }
+                }
+                else if (Array.isArray(known) && typeof value === 'string' && !known.includes(value.toLowerCase())) {
+                    removed.push(`${name} "${value}"`);
+                    delete options[name];
+                }
+            }
+            this.removedCompilerOptions.push(...removed);
+            return removed.length > 0 ? { updated: tsconfig } : null;
+        };
+    }
+    /**
+     * TypeScript loads every type package in node_modules unless told which,
+     * including 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() {
+        return (_file, code, advanced) => {
+            var _a;
+            if (((_a = advanced === null || advanced === void 0 ? void 0 : advanced.compilerOptions) === null || _a === void 0 ? void 0 : _a.types) !== undefined)
+                return null;
+            const updated = insertCompilerOption(code, TYPES_COMMENT, '"types": []');
+            if (!updated)
+                return null;
+            const globals = Object.keys(Object.assign(Object.assign({}, this.packageJson().dependencies), this.packageJson().devDependencies)).filter((name) => name.startsWith('@types/') && name !== '@types/jest');
+            if (globals.length > 0) {
+                this.leaveTodo('js/tsconfig.json', `It only loads the type packages the code imports now. If the code uses the globals of ${globals.join(', ')}, list them in compilerOptions.types.`);
+            }
+            return { updated };
+        };
+    }
+    /**
+     * A test config extending tsconfig.json would no longer load Jest's globals.
+     */
+    testTypes() {
+        return (_file, code, advanced) => {
+            var _a;
+            if (((_a = advanced === null || advanced === void 0 ? void 0 : advanced.compilerOptions) === null || _a === void 0 ? void 0 : _a.types) !== undefined)
+                return null;
+            const pkg = this.packageJson();
+            const listed = Object.assign(Object.assign({}, pkg.dependencies), pkg.devDependencies);
+            if (!['@flarum/jest-config', 'jest', '@types/jest'].some((name) => listed[name]))
+                return null;
+            const updated = insertCompilerOption(code, null, '"types": ["jest"]');
+            return updated ? { updated } : null;
+        };
+    }
+    /**
+     * Whether TypeScript 6 and newer accept the extension's tsconfig.json: it
+     * replaces the moduleResolution flarum-tsconfig sets, which they refuse, and
+     * sets no baseUrl, which they refuse too.
+     */
+    tsConfigReadsWithSixOrNewer() {
+        var _a, _b;
+        try {
+            const code = fs_1.default.readFileSync(path_1.default.join(this.root, 'js/tsconfig.json'), 'utf8');
+            const options = (_b = (_a = this.advancedContent('js/tsconfig.json', code)) === null || _a === void 0 ? void 0 : _a.compilerOptions) !== null && _b !== void 0 ? _b : {};
+            return ['bundler', 'node16', 'nodenext'].includes(String(options.moduleResolution).toLowerCase()) && options.baseUrl === undefined;
+        }
+        catch (_c) {
+            return false;
+        }
+    }
+    /** The extension's js/package.json, or nothing when it has none. */
+    packageJson() {
+        try {
+            return JSON.parse(fs_1.default.readFileSync(path_1.default.join(this.root, 'js/package.json'), 'utf8'));
+        }
+        catch (_a) {
+            return {};
+        }
+    }
 }
 exports.default = Dependencies;

package/lib/steps/upgrade/twopointoh/frontend/admin-extender.d.ts

@@ -0,0 +1,86 @@
+import { Binding, NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { BaseUpgradeStep, GitCommit, Replacement } from '../base';
+/** A registration chain written directly in an admin initializer. */
+type Registration = {
+    statement: NodePath<t.ExpressionStatement>;
+    calls: t.CallExpression[];
+    /** What for() names, when it is a string the upgrade can read. */
+    context: string | null;
+    /** Why it can't move, if it can't. */
+    reason: string | null;
+    imports: Map<string, Binding>;
+    constants: Set<Binding>;
+    /** Whether its arguments use app without importing it. */
+    usesGlobalApp: boolean;
+};
+/**
+ * Flarum 2.0 registers an extension's settings, permissions and page with the
+ * Admin extender, in admin/extend, which is declarative and runs when the admin
+ * mounts, rather than through the registry in an initializer.
+ *
+ * Registrations move only when they would do the same thing from there: each
+ * uses nothing the initializer declares, and nothing else registers with the
+ * registry as the admin boots, since registering later than that would change
+ * their order. Otherwise, all of the extension's registrations stay, with a
+ * @TODO saying why.
+ */
+export default class AdminExtender extends BaseUpgradeStep {
+    type: string;
+    protected moved: string[];
+    protected left: string[];
+    replacements(file: string): Replacement[];
+    targets(): string[];
+    gitCommit(): GitCommit;
+    pauseMessage(): string;
+    protected upgrade(file: string, code: string): Promise<{
+        updated: string;
+    } | null>;
+    /**
+     * The registration chains written as statements of an admin initializer,
+     * `app.initializers.add(name, () => { ... })`.
+     */
+    protected registrations(program: NodePath<t.Program>): Registration[];
+    protected registration(statement: NodePath<t.ExpressionStatement>, initializer: NodePath<t.Function>, chain: Chain): Registration;
+    /**
+     * Why nothing can move because of other code using the registry: in another
+     * admin file, or in this one other than in a registration chain or in a
+     * function that runs later, through extend() or override().
+     */
+    protected otherRegistryUse(program: NodePath<t.Program>, registrations: Registration[], file: string): string | null;
+    /**
+     * Where the extender goes: the admin/extend the index exports, or a new one.
+     */
+    protected target(program: NodePath<t.Program>, file: string): Target | {
+        reason: string;
+    };
+    protected leave(file: string, code: string, registrations: Registration[], blocked: string | null): {
+        updated: string;
+    } | null;
+    protected move(file: string, code: string, program: NodePath<t.Program>, registrations: Registration[], target: Target): Promise<{
+        updated: string;
+    } | {
+        updated: string;
+        newFiles: {
+            path: string;
+            code: string;
+        }[];
+    } | null>;
+    /** The extension's ID, as core makes it from the package name. */
+    protected extensionId(): string | null;
+}
+type Chain = {
+    root: t.CallExpression;
+    calls: t.CallExpression[];
+};
+type Target = {
+    file: string;
+    /** The code of the extend file the index exports, if it already exists. */
+    existing: string | null;
+    /** The extenders outside admin the index exported, which the new file spreads. */
+    common: {
+        source: string;
+        declaration: t.ExportNamedDeclaration;
+    } | null;
+};
+export {};