@flarum/cli 3.0.11 → 3.0.13

package/lib/steps/upgrade/twopointoh/backend/model-factories.d.ts

@@ -0,0 +1,18 @@
+import { BaseUpgradeStep, GitCommit, Replacement } from '../base';
+/**
+ * Give each of the extension's models a factory, written from what its
+ * migrations say about the model's table, so that tests naming the model in
+ * prepareDatabase() need only give the columns they care about.
+ */
+export default class ModelFactories extends BaseUpgradeStep {
+    type: string;
+    /** The factories this step wrote. */
+    protected written: string[];
+    private extension;
+    replacements(file: string): Replacement[];
+    targets(): string[];
+    gitCommit(): GitCommit;
+    pauseMessage(): string;
+    addFactory(): Replacement;
+    private found;
+}

package/lib/steps/upgrade/twopointoh/backend/model-factories.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+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 base_1 = require("../base");
+const extension_models_1 = require("./extension-models");
+/**
+ * Give each of the extension's models a factory, written from what its
+ * migrations say about the model's table, so that tests naming the model in
+ * prepareDatabase() need only give the columns they care about.
+ */
+class ModelFactories extends base_1.BaseUpgradeStep {
+    constructor() {
+        super(...arguments);
+        this.type = 'Model factories for tests';
+        /** The factories this step wrote. */
+        this.written = [];
+        this.extension = null;
+    }
+    replacements(file) {
+        return file.endsWith('.php') ? [this.addFactory()] : [];
+    }
+    targets() {
+        return ['src/**/*.php'];
+    }
+    gitCommit() {
+        return {
+            message: 'chore(2.0): model factories for tests',
+            description: "Flarum 2.0 tests take the columns they leave out from the model's factory.",
+        };
+    }
+    pauseMessage() {
+        const link = 'https://docs.flarum.org/2.x/extend/testing#model-factories';
+        return [
+            `Each model has a factory now. Written by this step: ${this.written.join(', ') || 'none'}.`,
+            'Tests that give prepareDatabase() a model class, rather than its table, take the columns they leave out from it.',
+            'Look for the @TODO comments on columns the migrations gave no default.',
+            chalk_1.default.underline(link),
+        ].join('\n                     ');
+    }
+    addFactory() {
+        return (file, code) => {
+            var _a;
+            const { models, byTable, tables } = this.found();
+            const model = models.find((candidate) => candidate.file === file);
+            if (!model)
+                return null;
+            const factory = path_1.default.posix.join(path_1.default.posix.dirname(file), `${model.class.split('\\').pop()}Factory.php`);
+            const hasFactoryClass = fs_1.default.existsSync(path_1.default.join(this.root, factory));
+            if (model.hasFactory && hasFactoryClass)
+                return null;
+            const result = this.php.run('upgrade.2-0.model-factory', {
+                file,
+                code,
+                data: { columns: (_a = tables[model.table]) !== null && _a !== void 0 ? _a : null, models: byTable },
+            });
+            // A factory the extension already has is its own.
+            if (hasFactoryClass) {
+                return { updated: result.code };
+            }
+            this.written.push(factory);
+            return { updated: result.code, newFiles: [{ path: factory, code: result.factory }] };
+        };
+    }
+    found() {
+        var _a;
+        (_a = this.extension) !== null && _a !== void 0 ? _a : (this.extension = Object.assign(Object.assign({}, (0, extension_models_1.extensionModels)(this.root, this.php)), { tables: (0, extension_models_1.migrationTables)(this.root, this.php) }));
+        return this.extension;
+    }
+}
+exports.default = ModelFactories;

package/lib/steps/upgrade/twopointoh/backend/phpunit-xml.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Convert a PHPUnit 9-era config to the shape the CLI scaffolds for 2.x
+ * extensions: schema resolved from the vendored phpunit, the attributes
+ * PHPUnit 10 removed dropped or renamed, coverage's include list moved to
+ * <source>, the Mockery listener block removed, and warning details enabled
+ * so flarum/testing's query guard is visible in the output.
+ */
+export declare function modernizePhpunitXml(file: string, code: string): string;

package/lib/steps/upgrade/twopointoh/backend/phpunit-xml.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modernizePhpunitXml = void 0;
+/**
+ * Convert a PHPUnit 9-era config to the shape the CLI scaffolds for 2.x
+ * extensions: schema resolved from the vendored phpunit, the attributes
+ * PHPUnit 10 removed dropped or renamed, coverage's include list moved to
+ * <source>, the Mockery listener block removed, and warning details enabled
+ * so flarum/testing's query guard is visible in the output.
+ */
+function modernizePhpunitXml(file, code) {
+    // The schema path is relative to the config file's own directory.
+    const prefix = '../'.repeat(file.split('/').length - 1);
+    let updated = code.replace(/xsi:noNamespaceSchemaLocation="[^"]*"/, `xsi:noNamespaceSchemaLocation="${prefix}vendor/phpunit/phpunit/phpunit.xsd"`);
+    // Attributes removed in PHPUnit 10.
+    updated = updated.replace(/[\t ]*(?:convert(?:Deprecations|Errors|Notices|Warnings)ToExceptions|forceCoversAnnotation|verbose|printerClass)="[^"]*"\r?\n/g, '');
+    updated = updated.replace(/backupStaticAttributes=/g, 'backupStaticProperties=');
+    // New settings, inserted next to their neighbours in the scaffolded order.
+    if (!updated.includes('cacheDirectory=')) {
+        updated = updated.replace(/(\n([\t ]*)backupGlobals="[^"]*")/, '$1\n$2cacheDirectory=".phpunit.cache"');
+    }
+    if (!updated.includes('displayDetailsOnTestsThatTriggerWarnings=')) {
+        updated = updated.replace(/(\n([\t ]*)colors="[^"]*")/, '$1\n$2displayDetailsOnTestsThatTriggerWarnings="true"');
+    }
+    // The include list lives in <source> now; coverage configuration as it
+    // existed in 9.x is gone.
+    updated = updated.replace(/<coverage[^>]*>/, '<source>').replace(/<\/coverage>/, '</source>');
+    // Test listeners were removed in PHPUnit 10 (Mockery integration works
+    // without one).
+    updated = updated.replace(/[\t ]*<listeners>[\S\s]*?<\/listeners>\r?\n?/, '');
+    return updated;
+}
+exports.modernizePhpunitXml = modernizePhpunitXml;

package/lib/steps/upgrade/twopointoh/backend/phpunit.d.ts

@@ -1,6 +1,8 @@
 import { BaseUpgradeStep, GitCommit, Replacement } from '../base';
 export default class PhpUnit extends BaseUpgradeStep {
     type: string;
+    /** Core's models and the extension's, by table, for prepareDatabase() to name. */
+    private models;
     replacements(file: string): Replacement[];
     targets(): string[];
     gitCommit(): GitCommit;

package/lib/steps/upgrade/twopointoh/backend/phpunit.js

@@ -3,44 +3,57 @@ 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 phpunit_xml_1 = require("./phpunit-xml");
+const extension_models_1 = require("./extension-models");
 class PhpUnit extends base_1.BaseUpgradeStep {
     constructor() {
         super(...arguments);
-        this.type = 'PHPUnit 9 to 11 changes';
+        this.type = 'PHPUnit 9 to 12 changes';
+        /** Core's models and the extension's, by table, for prepareDatabase() to name. */
+        this.models = null;
     }
     replacements(file) {
-        if (!file.endsWith('.php'))
-            return [];
-        return [
-            (_file, code) => ({
-                updated: this.php.run('upgrade.2-0.phpunit', { file, code }).code,
-            }),
-            (file, code) => {
-                if (!file.endsWith('.xml'))
-                    return null;
-                return {
-                    updated: code.replace('xsi:noNamespaceSchemaLocation="([^"]+)"', 'xsi:noNamespaceSchemaLocation="../vendor/phpunit/phpunit/phpunit.xsd"'),
-                };
-            },
-        ];
+        if (file.endsWith('.php')) {
+            return [
+                (_file, code) => {
+                    var _a;
+                    (_a = this.models) !== null && _a !== void 0 ? _a : (this.models = (0, extension_models_1.extensionModels)(this.root, this.php).byTable);
+                    return {
+                        updated: this.php.run('upgrade.2-0.phpunit', { file, code, data: { models: this.models } }).code,
+                    };
+                },
+            ];
+        }
+        // The XML rewrite previously sat behind the .php guard above (making it
+        // unreachable) and used String.replace with regex syntax in a string
+        // (matching nothing) — every upgraded extension kept its 9.3-era config.
+        if (/(^|\/)phpunit(\.[\w-]+)?\.xml$/.test(file)) {
+            return [
+                (xmlFile, code) => ({
+                    updated: (0, phpunit_xml_1.modernizePhpunitXml)(xmlFile, code),
+                }),
+            ];
+        }
+        return [];
     }
     targets() {
-        return ['tests/**/*'];
+        return ['tests/**/*', 'phpunit.xml', 'phpunit.*.xml'];
     }
     gitCommit() {
         return {
-            message: 'chore(2.0): Backend tests + PHPUnit 9 to 11 changes',
-            description: 'Flarum 2.0 uses PHPUnit 11 and encourages use of model factories for easier cross-database testing.',
+            message: 'chore(2.0): Backend tests + PHPUnit 9 to 12 changes',
+            description: 'Flarum 2.0 uses PHPUnit 12 and encourages use of model factories for easier cross-database testing.',
         };
     }
     pauseMessage() {
         const links = [
             'https://github.com/sebastianbergmann/phpunit/blob/9.6/DEPRECATIONS.md',
             'https://github.com/sebastianbergmann/phpunit/blob/10.5/DEPRECATIONS.md',
-            'https://github.com/sebastianbergmann/phpunit/blob/11.3.0/DEPRECATIONS.md',
+            'https://github.com/sebastianbergmann/phpunit/blob/11.5/DEPRECATIONS.md',
+            'https://github.com/sebastianbergmann/phpunit/blob/12.5/DEPRECATIONS.md',
         ];
-        const dbLink = 'http://localhost:3000/extend/testing#model-factories';
-        return `Flarum 2.0 uses PHPUnit 11. The tool has applied the most significant changes, but you might still run into other deprecations.
+        const dbLink = 'https://docs.flarum.org/2.x/extend/testing#model-factories';
+        return `Flarum 2.0 uses PHPUnit 12. The tool has applied the most significant changes, and left @TODO comments on what it could not, but you might still run into other deprecations.
                      Please refer to the following links for more information:
                      ${links.map((link) => chalk_1.default.underline(link)).join('\n                     ')}
 

package/lib/steps/upgrade/twopointoh/backend/search.d.ts

@@ -21,6 +21,15 @@ export default class Search extends BaseUpgradeStep {
     protected searchers: Record<string, string>;
     before(file: string, code: string, _advanced: AdvancedContent): void;
     replacements(_file: string): Replacement[];
+    /**
+     * The translations a gambit's stub uses: its key, and a key-value gambit's
+     * hint, which the search shows beside it. Only the author can say what the
+     * hint should be, so it is left for them to write.
+     */
+    gambitTranslations(gambit: Gambit): {
+        key: string;
+        value: string;
+    }[];
     targets(): string[];
     gitCommit(): GitCommit;
     pauseMessage(): string;

package/lib/steps/upgrade/twopointoh/backend/search.js

@@ -9,6 +9,10 @@ const gambit_1 = require("../../../stubs/frontend/gambit");
 const search_gambit_1 = require("../../../js/search-gambit");
 const base_2 = require("../../../locale/base");
 const model_name_1 = require("../../../../utils/model-name");
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const path_1 = tslib_1.__importDefault(require("path"));
+/** A gambit with an is: pattern, such as is:private, rather than a key and value. */
+const isBoolean = (gambit) => gambit.pattern.includes('is:');
 class Search extends base_1.BaseUpgradeStep {
     constructor() {
         super(...arguments);
@@ -116,10 +120,6 @@ class Search extends base_1.BaseUpgradeStep {
                 if (this.gambits.length > 0 && Object.keys(((_a = this.data.collectedData.extendData) === null || _a === void 0 ? void 0 : _a.searchers) || {}).length > 0) {
                     const result = await this.command.runSteps(new step_manager_1.StepManager().silentGroup((steps) => {
                         this.gambits.forEach((gambit, index) => {
-                            let gambitKey = gambit.pattern.replace('is:', '');
-                            if (gambitKey.includes(':')) {
-                                gambitKey = gambitKey.split(':')[0];
-                            }
                             const relatedSearcher = Object.keys(this.data.collectedData.extendData.searchers).find((searcher) => {
                                 const filters = this.data.collectedData.extendData.searchers[searcher].filters || [];
                                 return filters.some((filter) => {
@@ -130,11 +130,11 @@ class Search extends base_1.BaseUpgradeStep {
                             if (relatedSearcher) {
                                 type = (0, model_name_1.pluralKebabCaseModel)(relatedSearcher.split('\\').pop().replace('Searcher', ''));
                             }
-                            steps
+                            const gambitSteps = steps
                                 .namedStep(`gambit-${index}`, new gambit_1.GenerateGambitStub(this.command.STUB_PATH, (0, gen_ext_scaffolder_1.genExtScaffolder)()), {}, [], {
                                 frontend: 'common',
                                 className: gambit.name,
-                                type: gambit.pattern.includes('is:') ? 'boolean' : 'key-value',
+                                type: isBoolean(gambit) ? 'boolean' : 'key-value',
                                 filterKey: gambit.filterKey,
                             })
                                 .step(new search_gambit_1.GenerateSearchGambitExtender(), {}, [
@@ -146,10 +146,9 @@ class Search extends base_1.BaseUpgradeStep {
                             ], {
                                 frontend: 'common',
                                 modelType: type,
-                            })
-                                .step(new base_2.LocaleStep((0, gen_ext_scaffolder_1.genExtScaffolder)()), {}, [], {
-                                key: `lib.gambits.${gambit.filterKey}.key`,
-                                value: gambitKey,
+                            });
+                            this.gambitTranslations(gambit).forEach((translation) => {
+                                gambitSteps.step(new base_2.LocaleStep((0, gen_ext_scaffolder_1.genExtScaffolder)()), {}, [], translation);
                             });
                             delete this.gambits[index];
                         });
@@ -171,6 +170,25 @@ class Search extends base_1.BaseUpgradeStep {
             },
         ];
     }
+    /**
+     * The translations a gambit's stub uses: its key, and a key-value gambit's
+     * hint, which the search shows beside it. Only the author can say what the
+     * hint should be, so it is left for them to write.
+     */
+    gambitTranslations(gambit) {
+        let gambitKey = gambit.pattern.replace('is:', '');
+        if (gambitKey.includes(':')) {
+            gambitKey = gambitKey.split(':')[0];
+        }
+        const translations = [{ key: `lib.gambits.${gambit.filterKey}.key`, value: gambitKey }];
+        if (!isBoolean(gambit)) {
+            const hint = `lib.gambits.${gambit.filterKey}.hint`;
+            const locale = fs_1.default.existsSync(path_1.default.join(this.root, 'resources/locale/en.yml')) ? 'resources/locale/en.yml' : 'locale/en.yml';
+            translations.push({ key: hint, value: gambitKey });
+            this.leaveTodo(locale, `describe what the ${gambitKey} gambit takes in ${hint}, which the search shows beside it.`);
+        }
+        return translations;
+    }
     targets() {
         return ['src/**/*', 'extend.php'];
     }

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;