@flarum/cli 3.0.11 → 3.0.13

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

@@ -3,10 +3,106 @@ 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_4_9_1 = require("./typescript-4-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";
+// Syntax TypeScript 4.9 can't compile, each checked against typescript@4.9.5.
+const NEWER_SYNTAX = [
+    [/(?:\bfrom|^\s*import)\s+(["'])[^\n"']*\1\s+with\s*{/, 'import attributes (TypeScript 5.3); use `assert` instead of `with`'],
+    [/^\s*export\s+type\s+\*/, '`export type *` (TypeScript 5.0)'],
+    [/[,<]\s*const\s+[$A-Z_a-z][\w$]*\s*(?:extends\b|[,=>])/, '`const` type parameters (TypeScript 5.0)'],
+    [/^\s*(?:await\s+)?using\s+[$A-Z_a-z][\w$]*\s*[:=]/, '`using` declarations (TypeScript 5.2)'],
+];
+// 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. Others, such as the',
+    "@types/node webpack brings along, use syntax TypeScript 4.9 can't read.",
+];
+/**
+ * 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)));
+const isTypeScript = (file) => /\.tsx?$/.test(file);
+/** Whether a version constraint stays within TypeScript 4: `4.9.5`, `^4.5.4`, `~4.7`, `4.x`. */
+const isFourX = (constraint) => {
+    const version = constraint.trim().replace(/^\^|^~/, '');
+    return version === '4' || version.startsWith('4.');
+};
+/**
+ * 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 was not a 4.x. */
+        this.typeScriptWas = null;
+        /** What was removed from tsconfig.json, as TypeScript 4.9 doesn't have it. */
+        this.removedCompilerOptions = [];
+        this.newerSyntax = false;
+        /** 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 +112,31 @@ 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;
+            default:
+                if (isTypeScript(file)) {
+                    replacements.push(this.flagNewerSyntax());
+                }
         }
         return replacements;
     }
     targets() {
-        return ['composer.json', 'js/package.json'];
+        return ['composer.json', 'js/package.json', 'js/tsconfig.json', 'js/tsconfig.test.json', 'js/src/**/*.ts', 'js/src/**/*.tsx'];
+    }
+    // TypeScript sources are only searched, line by line: parsing them would
+    // fail on the very syntax being looked for, and reformatting would change
+    // more than the lines flagged.
+    advancedContent(file, code) {
+        return isTypeScript(file) ? null : super.advancedContent(file, code);
+    }
+    async updateCode(file, code, updated) {
+        return isTypeScript(file) && typeof updated === 'string' ? updated : super.updateCode(file, code, updated);
     }
     gitCommit() {
         return {
@@ -33,9 +149,34 @@ 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 ^4.9.5: Flarum 2.0 builds and checks its typings with TypeScript 4.9.`,
+            this.removedCompilerOptions.length > 0 &&
+                `Removed from js/tsconfig.json, as TypeScript 4.9 does not have them: ${this.removedCompilerOptions.join(', ')}.`,
+            this.newerSyntax && 'Some TypeScript uses syntax 4.9 cannot compile; look for the @TODO comments.',
+            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 +193,7 @@ class Dependencies extends base_1.BaseUpgradeStep {
                     }
                 });
                 if (key === 'flarum/core') {
-                    composer.require[key] = '^2.0.0-beta';
+                    this.raise(composer.require, key, '^2.0.0');
                 }
                 else if (key.startsWith('flarum/') && value !== '*') {
                     composer.require[key] = '*';
@@ -67,17 +208,20 @@ class Dependencies extends base_1.BaseUpgradeStep {
                     }
                 });
                 if (['flarum/core', 'flarum/testing', 'flarum/phpstan'].includes(key)) {
-                    composer['require-dev'][key] = '^2.0.0-beta';
+                    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.2';
+                this.raise(composer.require, 'php', '^8.3');
             }
+            // 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,
@@ -86,20 +230,42 @@ class Dependencies extends base_1.BaseUpgradeStep {
     }
     updatePackageJson() {
         return (_file, _code, advanced) => {
+            var _a;
             advanced = advanced;
+            // The versions a new extension is scaffolded with. 3.0.6 is the first
+            // flarum-webpack-config that loads an extension's code-split chunks from
+            // its own build, and 3.0.7 the first that exports a default export as its
+            // value, not under a name taken from its code.
             const map = {
-                'flarum-webpack-config': '^3.0.0',
+                'flarum-webpack-config': '^3.0.7',
                 'flarum-tsconfig': '^2.0.0',
                 '@flarum/jest-config': '^2.0.0',
-                'webpack': "^5.65.0",
-                'webpack-cli': "^4.9.1",
+                webpack: '^5.104.1',
+                'webpack-cli': '^4.9.1',
+                // What Flarum 2.0 builds and checks its typings with.
+                typescript: '^4.9.5',
             };
-            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 || {})) {
+                    if (key === 'typescript' && !isFourX(String(dependencies[key]))) {
+                        this.typeScriptWas = dependencies[key];
+                    }
+                    // TypeScript is the exception: it comes down to what Flarum checks
+                    // typings with, whatever the extension asked for.
+                    if (key === 'typescript') {
+                        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)) {
@@ -113,5 +279,167 @@ 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 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() {
+        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_4_9_1.compilerOptions, name) ? typescript_4_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_4_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];
+                }
+            }
+            if (Array.isArray(tsconfig.extends)) {
+                this.leaveTodo('js/tsconfig.json', 'It extends a list of configs, which TypeScript 4.9 cannot read. Extend one, and move the rest into it.');
+            }
+            this.removedCompilerOptions.push(...removed);
+            return removed.length > 0 ? { updated: tsconfig } : null;
+        };
+    }
+    /**
+     * 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() {
+        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;
+        };
+    }
+    /** 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 {};
+        }
+    }
+    /**
+     * Put a @TODO above each line using syntax TypeScript 4.9 can't compile.
+     */
+    flagNewerSyntax() {
+        return (_file, code) => {
+            const flagged = [];
+            for (const line of code.split('\n')) {
+                for (const [pattern, what] of NEWER_SYNTAX) {
+                    if (!pattern.test(line))
+                        continue;
+                    const indent = line.slice(0, line.length - line.trimStart().length);
+                    const todo = `${indent}// @TODO: Flarum 2.0 builds with TypeScript 4.9, which has no ${what}.`;
+                    // An earlier run already flagged it.
+                    if (flagged.slice(-NEWER_SYNTAX.length).some((previous) => previous.trim() === todo.trim()))
+                        continue;
+                    flagged.push(line.endsWith('\r') ? `${todo}\r` : todo);
+                    this.newerSyntax = true;
+                }
+                flagged.push(line);
+            }
+            const updated = flagged.join('\n');
+            return updated === code ? null : { updated };
+        };
+    }
 }
 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 {};