diff --git a/.eslintrc.json b/.eslintrc.json index 6ce386bd4f..fe2900996c 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -5,6 +5,7 @@ "overrides": [ { "files": ["*.ts", "*.tsx", "*.js", "*.jsx"], + "extends": ["plugin:comment-length/recommended"], "rules": { "@nx/enforce-module-boundaries": [ "error", @@ -34,7 +35,31 @@ "no-constant-condition": 0, "no-nested-ternary": 0, "jsx-a11y/click-events-have-key-events": 0, - "jsx-a11y/no-static-element-interactions": 0 + "jsx-a11y/no-static-element-interactions": 0, + "comment-length/limit-single-line-comments": [ + "warn", + { + "maxLength": 100, + "tabSize": 0, + "ignoreUrls": true + } + ], + "comment-length/limit-multi-line-comments": [ + "warn", + { + "maxLength": 100, + "tabSize": 0, + "ignoreUrls": true + } + ], + "comment-length/limit-tagged-template-literal-comments": [ + "warn", + { + "maxLength": 100, + "tabSize": 0, + "ignoreUrls": true + } + ] } }, { diff --git a/package-lock.json b/package-lock.json index 2972b3a89f..d05475a97a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -98,6 +98,7 @@ "esbuild-plugin-ignore": "1.1.1", "eslint": "8.46.0", "eslint-config-prettier": "8.1.0", + "eslint-plugin-comment-length": "1.7.3", "eslint-plugin-cypress": "^2.13.4", "eslint-plugin-import": "2.27.5", "eslint-plugin-jsx-a11y": "6.7.1", @@ -15988,7 +15989,9 @@ } }, "node_modules/@types/json-schema": { - "version": "7.0.11", + "version": "7.0.15", + "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz", + "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==", "dev": true, "license": "MIT" }, @@ -25204,6 +25207,150 @@ "ms": "^2.1.1" } }, + "node_modules/eslint-plugin-comment-length": { + "version": "1.7.3", + "resolved": "https://registry.npmjs.org/eslint-plugin-comment-length/-/eslint-plugin-comment-length-1.7.3.tgz", + "integrity": "sha512-1MmRc5oY1W/b5p9/O+GQR5Xuod9JmPjfaoV9kAo+reJbx1QgfJNZeqBp6eZXEqyp8Y/2b07Jq5o//8X3LTjauQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/utils": "^6.10.0" + }, + "peerDependencies": { + "eslint": ">=8.0.0" + } + }, + "node_modules/eslint-plugin-comment-length/node_modules/@typescript-eslint/scope-manager": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-6.21.0.tgz", + "integrity": "sha512-OwLUIWZJry80O99zvqXVEioyniJMa+d2GrqpUTqi5/v5D5rOrppJVBPa0yKCblcigC0/aYAzxxqQ1B+DS2RYsg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/types": "6.21.0", + "@typescript-eslint/visitor-keys": "6.21.0" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/eslint-plugin-comment-length/node_modules/@typescript-eslint/types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-6.21.0.tgz", + "integrity": "sha512-1kFmZ1rOm5epu9NZEZm1kckCDGj5UJEf7P1kliH4LKu/RkwpsfqqGmY2OOcUs18lSlQBKLDYBOGxRVtrMN5lpg==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/eslint-plugin-comment-length/node_modules/@typescript-eslint/typescript-estree": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-6.21.0.tgz", + "integrity": "sha512-6npJTkZcO+y2/kr+z0hc4HwNfrrP4kNYh57ek7yCNlrBjWQ1Y0OS7jiZTkgumrvkX5HkEKXFZkkdFNkaW2wmUQ==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "@typescript-eslint/types": "6.21.0", + "@typescript-eslint/visitor-keys": "6.21.0", + "debug": "^4.3.4", + "globby": "^11.1.0", + "is-glob": "^4.0.3", + "minimatch": "9.0.3", + "semver": "^7.5.4", + "ts-api-utils": "^1.0.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/eslint-plugin-comment-length/node_modules/@typescript-eslint/utils": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-6.21.0.tgz", + "integrity": "sha512-NfWVaC8HP9T8cbKQxHcsJBY5YE1O33+jpMwN45qzWWaPDZgLIbo12toGMWnmhvCpd3sIxkpDw3Wv1B3dYrbDQQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@eslint-community/eslint-utils": "^4.4.0", + "@types/json-schema": "^7.0.12", + "@types/semver": "^7.5.0", + "@typescript-eslint/scope-manager": "6.21.0", + "@typescript-eslint/types": "6.21.0", + "@typescript-eslint/typescript-estree": "6.21.0", + "semver": "^7.5.4" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0" + } + }, + "node_modules/eslint-plugin-comment-length/node_modules/@typescript-eslint/visitor-keys": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-6.21.0.tgz", + "integrity": "sha512-JJtkDduxLi9bivAB+cYOVMtbkqdPOhZ+ZI5LC47MIRrDV4Yn2o+ZnW10Nkmr28xRpSpdJ6Sm42Hjf2+REYXm0A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@typescript-eslint/types": "6.21.0", + "eslint-visitor-keys": "^3.4.1" + }, + "engines": { + "node": "^16.0.0 || >=18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/eslint-plugin-comment-length/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/eslint-plugin-comment-length/node_modules/minimatch": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz", + "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/eslint-plugin-cypress": { "version": "2.15.1", "resolved": "https://registry.npmjs.org/eslint-plugin-cypress/-/eslint-plugin-cypress-2.15.1.tgz", @@ -43265,6 +43412,19 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/ts-api-utils": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-1.3.0.tgz", + "integrity": "sha512-UQMIo7pb8WRomKR1/+MFVLTroIvDVtMX3K6OUir8ynLyzB8Jeriont2bTAtmNPa1ekAgN7YPDyf6V+ygrdU+eQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=16" + }, + "peerDependencies": { + "typescript": ">=4.2.0" + } + }, "node_modules/ts-clone-node": { "version": "2.0.4", "dev": true, diff --git a/package.json b/package.json index e182cf73be..951607fe17 100644 --- a/package.json +++ b/package.json @@ -139,6 +139,7 @@ "esbuild-plugin-ignore": "1.1.1", "eslint": "8.46.0", "eslint-config-prettier": "8.1.0", + "eslint-plugin-comment-length": "1.7.3", "eslint-plugin-cypress": "^2.13.4", "eslint-plugin-import": "2.27.5", "eslint-plugin-jsx-a11y": "6.7.1", diff --git a/packages/php-wasm/cli/src/main.ts b/packages/php-wasm/cli/src/main.ts index f9d899b56a..289401cd3c 100644 --- a/packages/php-wasm/cli/src/main.ts +++ b/packages/php-wasm/cli/src/main.ts @@ -61,8 +61,8 @@ async function run() { ' ' )} ${process.argv[1]}`; // Naively replace the PHP binary with the PHP-WASM command - // @TODO: Don't process the command. Lean on the shell to do it, e.g. through - // a PATH or an alias. + // @TODO: Don't process the command. Lean on the shell to do it, e.g. + // through a PATH or an alias. const updatedCommand = command.replace( /^(?:\\ |[^ ])*php\d?(\s|$)/, phpWasmCommand + '$1' diff --git a/packages/php-wasm/fs-journal/src/lib/fs-journal.ts b/packages/php-wasm/fs-journal/src/lib/fs-journal.ts index 7570772283..452f205691 100644 --- a/packages/php-wasm/fs-journal/src/lib/fs-journal.ts +++ b/packages/php-wasm/fs-journal/src/lib/fs-journal.ts @@ -376,8 +376,8 @@ export function normalizeFilesystemOperations( latter.operation === 'RENAME' && former.operation === 'RENAME' ) { - // Normalizing a double rename is a complex scenario so let's just give up. - // There's just too many possible scenarios to handle. + // Normalizing a double rename is a complex scenario so let's just give + // up. There's just too many possible scenarios to handle. // // For example, the following scenario may not be possible to normalize: // RENAME /dir_a /dir_b @@ -395,8 +395,8 @@ export function normalizeFilesystemOperations( // CREATE_DIR /dir_b // CREATE_FILE /dir_b/file_2 // - // But that's not a straightforward transformation so let's just not handle - // it for now. + // But that's not a straightforward transformation so let's just not + // handle it for now. logger.warn( '[FS Journal] Normalizing a double rename is not yet supported:', { @@ -410,8 +410,8 @@ export function normalizeFilesystemOperations( if (former.operation === 'CREATE' || former.operation === 'WRITE') { if (latter.operation === 'RENAME') { if (formerType === 'same_node') { - // Creating a node and then renaming it is equivalent to creating it in - // the new location. + // Creating a node and then renaming it is equivalent to creating + // it in the new location. substitutions[j] = []; substitutions[i] = [ { @@ -421,8 +421,8 @@ export function normalizeFilesystemOperations( ...(substitutions[i] || []), ]; } else if (formerType === 'descendant') { - // Creating a node and then renaming its parent directory is equivalent - // to creating it in the new location. + // Creating a node and then renaming its parent directory is + // equivalent to creating it in the new location. substitutions[j] = []; substitutions[i] = [ { @@ -446,7 +446,8 @@ export function normalizeFilesystemOperations( latter.operation === 'DELETE' && formerType === 'same_node' ) { - // Creating a node and then deleting it is equivalent to doing nothing. + // Creating a node and then deleting it is equivalent to doing + // nothing. substitutions[j] = []; substitutions[i] = []; } diff --git a/packages/php-wasm/logger/src/lib/collectors/collect-service-worker-metrics.ts b/packages/php-wasm/logger/src/lib/collectors/collect-service-worker-metrics.ts index f5cc3542ab..8331484058 100644 --- a/packages/php-wasm/logger/src/lib/collectors/collect-service-worker-metrics.ts +++ b/packages/php-wasm/logger/src/lib/collectors/collect-service-worker-metrics.ts @@ -2,11 +2,13 @@ /** * **Call this inside a service worker.** - * These errors include Playground errors like Asyncify errors. PHP errors won't trigger this event. + * These errors include Playground errors like Asyncify errors. PHP errors + * won't trigger this event. * * Reports service worker metrics. - * Allows the logger to request metrics from the service worker by sending a message. - * The service worker will respond with the number of open Playground tabs. + * Allows the logger to request metrics from the service worker by sending a + * message. The service worker will respond with the number of open Playground + * tabs. * * @param worker The service worker */ diff --git a/packages/php-wasm/logger/src/lib/collectors/collect-window-errors.ts b/packages/php-wasm/logger/src/lib/collectors/collect-window-errors.ts index 33ab8d23c6..12c909bbcd 100644 --- a/packages/php-wasm/logger/src/lib/collectors/collect-window-errors.ts +++ b/packages/php-wasm/logger/src/lib/collectors/collect-window-errors.ts @@ -50,7 +50,8 @@ const addServiceWorkerMessageListener = (loggerInstance: Logger) => { if (event.data?.numberOfOpenPlaygroundTabs === undefined) { return; } - // Each tab sends an activate event on load. Prevent sending the same metrics multiple times if a tab is reloaded. + // Each tab sends an activate event on load. Prevent sending the same + // metrics multiple times if a tab is reloaded. if ( numberOfOpenPlaygroundTabs === event.data?.numberOfOpenPlaygroundTabs diff --git a/packages/php-wasm/logger/src/lib/logger.ts b/packages/php-wasm/logger/src/lib/logger.ts index d329ee3e94..6c324dca21 100644 --- a/packages/php-wasm/logger/src/lib/logger.ts +++ b/packages/php-wasm/logger/src/lib/logger.ts @@ -205,7 +205,8 @@ export const formatLogEntry = ( /** * Add a listener for the Playground crashes. * These crashes include Playground errors like Asyncify errors. - * The callback function will receive an Event object with logs in the detail property. + * The callback function will receive an Event object with logs in the detail + * property. * * @param loggerInstance The logger instance * @param callback The callback function diff --git a/packages/php-wasm/node/src/lib/networking/outbound-ws-to-tcp-proxy.ts b/packages/php-wasm/node/src/lib/networking/outbound-ws-to-tcp-proxy.ts index c8bb8129f3..4eda0b0f35 100644 --- a/packages/php-wasm/node/src/lib/networking/outbound-ws-to-tcp-proxy.ts +++ b/packages/php-wasm/node/src/lib/networking/outbound-ws-to-tcp-proxy.ts @@ -204,7 +204,8 @@ async function onWsConnect(client: any, request: http.IncomingMessage) { clientLog('resolved ' + reqTargetHost + ' -> ' + reqTargetIp); } catch (e) { clientLog("can't resolve " + reqTargetHost + ' due to:', e); - // Send empty binary data to notify requester that connection was initiated + // Send empty binary data to notify requester that connection was + // initiated client.send([]); client.close(3000); return; diff --git a/packages/php-wasm/progress/src/lib/progress-tracker.ts b/packages/php-wasm/progress/src/lib/progress-tracker.ts index 52dece074d..489aaf6545 100644 --- a/packages/php-wasm/progress/src/lib/progress-tracker.ts +++ b/packages/php-wasm/progress/src/lib/progress-tracker.ts @@ -70,16 +70,18 @@ export interface ProgressReceiver { const PROGRESS_EPSILON = 0.00001; /** - * The ProgressTracker class is a tool for tracking progress in an operation that is - * divided into multiple stages. It allows you to create sub-trackers for each stage, - * with individual weights and captions. The main tracker automatically calculates the - * progress based on the weighted sum of each sub-tracker's progress. This makes it easy - * to keep track of a complex, multi-stage process and report progress in a user-friendly way. + * The ProgressTracker class is a tool for tracking progress in an operation + * that is divided into multiple stages. It allows you to create sub-trackers + * for each stage, with individual weights and captions. The main tracker + * automatically calculates the progress based on the weighted sum of each + * sub-tracker's progress. This makes it easy to keep track of a complex, + * multi-stage process and report progress in a user-friendly way. * - * After creating the sub-trackers, you can call the set() method to update the progress - * of the current stage. You can also call the finish() method to mark the current stage - * as complete and move on to the next one. Alternatively, you can call the fillSlowly() - * method to simulate progress filling up slowly to 100% before calling finish(). + * After creating the sub-trackers, you can call the set() method to update the + * progress of the current stage. You can also call the finish() method to mark + * the current stage as complete and move on to the next one. Alternatively, + * you can call the fillSlowly() method to simulate progress filling up slowly + * to 100% before calling finish(). * * @example * ```ts diff --git a/packages/php-wasm/universal/src/lib/emscripten-types.ts b/packages/php-wasm/universal/src/lib/emscripten-types.ts index 1c352e1d75..b021d07b8b 100644 --- a/packages/php-wasm/universal/src/lib/emscripten-types.ts +++ b/packages/php-wasm/universal/src/lib/emscripten-types.ts @@ -1,6 +1,9 @@ /* eslint-disable @typescript-eslint/no-misused-new */ /* eslint-disable @typescript-eslint/no-namespace */ -/** Other WebAssembly declarations, for compatibility with older versions of Typescript */ +/** + * Other WebAssembly declarations, for compatibility with older versions of + * Typescript + */ export namespace Emscripten { export interface RootFS extends Emscripten.FileSystemInstance { @@ -112,12 +115,12 @@ export namespace Emscripten { * to `1` in your Emscripten build. It return a Promise that resolves to an * initialized, ready-to-call `EmscriptenModule` instance. * - * By default, the factory function will be named `Module`. It's recommended to - * use the `EXPORT_ES6` option, in which the factory function will be the - * default export. If used without `EXPORT_ES6`, the factory function will be a - * global variable. You can rename the variable using the `EXPORT_NAME` build - * option. It's left to you to export any global variables as needed in your - * application's types. + * By default, the factory function will be named `Module`. It's recommended + * to use the `EXPORT_ES6` option, in which the factory function will be the + * default export. If used without `EXPORT_ES6`, the factory function will be + * a global variable. You can rename the variable using the `EXPORT_NAME` + * build option. It's left to you to export any global variables as needed in + * your application's types. * @param moduleOverrides Default properties for the initialized module. */ export type EmscriptenModuleFactory< diff --git a/packages/php-wasm/universal/src/lib/load-php-runtime.ts b/packages/php-wasm/universal/src/lib/load-php-runtime.ts index 8c9ed0eff9..191670ab08 100644 --- a/packages/php-wasm/universal/src/lib/load-php-runtime.ts +++ b/packages/php-wasm/universal/src/lib/load-php-runtime.ts @@ -7,7 +7,8 @@ let lastRuntimeId = 0; /** * Loads the PHP runtime with the given arguments and data dependencies. * - * This function handles the entire PHP initialization pipeline. In particular, it: + * This function handles the entire PHP initialization pipeline. In particular, + * it: * * * Instantiates the Emscripten PHP module * * Wires it together with the data dependencies and loads them @@ -25,10 +26,10 @@ let lastRuntimeId = 0; * * **The PHP loader module:** * - * In the basic usage example, `phpLoaderModule` is **not** a vanilla Emscripten module. Instead, - * it's an ESM module that wraps the regular Emscripten output and adds some - * extra functionality. It's generated by the Dockerfile shipped with this repo. - * Here's the API it provides: + * In the basic usage example, `phpLoaderModule` is **not** a vanilla + * Emscripten module. Instead, it's an ESM module that wraps the regular + * Emscripten output and adds some extra functionality. It's generated by the + * Dockerfile shipped with this repo. Here's the API it provides: * * ```js * // php.wasm size in bytes: @@ -78,17 +79,19 @@ let lastRuntimeId = 0; * be quite inconvenient. Fortunately, Emscripten provides a "data dependencies" * feature. * - * Data dependencies consist of a `dependency.data` file and a `dependency.js` loader and - * can be packaged with the [file_packager.py tool]( https://emscripten.org/docs/porting/files/packaging_files.html#packaging-using-the-file-packager-tool). - * This project requires wrapping the Emscripten-generated `dependency.js` file in an ES - * module as follows: + * Data dependencies consist of a `dependency.data` file and a `dependency.js` + * loader and can be packaged with the [file_packager.py tool]( + * https://emscripten.org/docs/porting/files/packaging_files.html#packaging-using-the-file-packager-tool). + * This project requires wrapping the Emscripten-generated `dependency.js` file + * in an ES module as follows: * * 1. Prepend `export default function(emscriptenPHPModule) {'; ` * 2. Prepend `export const dependencyFilename = ''; ` * 3. Prepend `export const dependenciesTotalSize = ;` * 4. Append `}` * - * Be sure to use the `--export-name="emscriptenPHPModule"` file_packager.py option. + * Be sure to use the `--export-name="emscriptenPHPModule"` file_packager.py + * option. * * You want the final output to look as follows: * @@ -102,8 +105,8 @@ let lastRuntimeId = 0; * } * ``` * - * Such a constructions enables loading the `dependency.js` as an ES Module using - * `import("/dependency.js")`. + * Such a constructions enables loading the `dependency.js` as an ES Module + * using `import("/dependency.js")`. * * Once it's ready, you can load PHP and your data dependencies as follows: * diff --git a/packages/php-wasm/universal/src/lib/php-process-manager.ts b/packages/php-wasm/universal/src/lib/php-process-manager.ts index ccb342c354..6ae926526c 100644 --- a/packages/php-wasm/universal/src/lib/php-process-manager.ts +++ b/packages/php-wasm/universal/src/lib/php-process-manager.ts @@ -56,18 +56,20 @@ export class MaxPhpInstancesError extends Error { * * A pool of disposable PHP instances that are spawned to handle a single * request and reaped immediately after. * - * When a new request comes in, PHPProcessManager yields the idle instance to handle it, - * and immediately starts initializing a new idle instance. In other words, for n concurrent - * requests, there are at most n+1 PHP instances running at the same time. + * When a new request comes in, PHPProcessManager yields the idle instance to + * handle it, and immediately starts initializing a new idle instance. In other + * words, for n concurrent requests, there are at most n+1 PHP instances + * running at the same time. * - * A slight nuance is that the first idle instance is not initialized until the first - * concurrent request comes in. This is because many use-cases won't involve parallel - * requests and, for those, we can avoid eagerly spinning up a second PHP instance. + * A slight nuance is that the first idle instance is not initialized until the + * first concurrent request comes in. This is because many use-cases won't + * involve parallel requests and, for those, we can avoid eagerly spinning up a + * second PHP instance. * - * This strategy is inspired by Cowboy, an Erlang HTTP server. Handling a single extra - * request can happen immediately, while handling multiple extra requests requires - * extra time to spin up a few PHP instances. This is a more resource-friendly tradeoff - * than keeping 5 idle instances at all times. + * This strategy is inspired by Cowboy, an Erlang HTTP server. Handling a + * single extra request can happen immediately, while handling multiple extra + * requests requires extra time to spin up a few PHP instances. This is a more + * resource-friendly tradeoff than keeping 5 idle instances at all times. */ export class PHPProcessManager implements AsyncDisposable { private primaryPhp?: PHP; @@ -119,8 +121,9 @@ export class PHPProcessManager implements AsyncDisposable { /** * Get a PHP instance. * - * It could be either the primary PHP instance, an idle disposable PHP instance, - * or a newly spawned PHP instance – depending on the resource availability. + * It could be either the primary PHP instance, an idle disposable PHP + * instance, or a newly spawned PHP instance – depending on the resource + * availability. * * @throws {MaxPhpInstancesError} when the maximum number of PHP instances is reached * and the waiting timeout is exceeded. diff --git a/packages/php-wasm/universal/src/lib/php-request-handler.ts b/packages/php-wasm/universal/src/lib/php-request-handler.ts index 9deb255e2b..6fde8a2842 100644 --- a/packages/php-wasm/universal/src/lib/php-request-handler.ts +++ b/packages/php-wasm/universal/src/lib/php-request-handler.ts @@ -274,8 +274,8 @@ export class PHPRequestHandler { * dispatching it to the PHP runtime. * * The request() method mode behaves like a web server and only works if - * the PHP was initialized with a `requestHandler` option (which the online version - * of WordPress Playground does by default). + * the PHP was initialized with a `requestHandler` option (which the online + * version of WordPress Playground does by default). * * In the request mode, you pass an object containing the request information * (method, headers, body, etc.) and the path to the PHP file to run: @@ -436,9 +436,9 @@ export class PHPRequestHandler { 200, { 'content-length': [`${arrayBuffer.byteLength}`], - // @TODO: Infer the content-type from the arrayBuffer instead of the file path. - // The code below won't return the correct mime-type if the extension - // was tampered with. + // @TODO: Infer the content-type from the arrayBuffer instead of the + // file path. The code below won't return the correct mime-type if the + // extension was tampered with. 'content-type': [inferMimeType(fsPath)], 'accept-ranges': ['bytes'], 'cache-control': ['public, max-age=0'], diff --git a/packages/php-wasm/universal/src/lib/php.ts b/packages/php-wasm/universal/src/lib/php.ts index 3afd021875..7e22e3fcdf 100644 --- a/packages/php-wasm/universal/src/lib/php.ts +++ b/packages/php-wasm/universal/src/lib/php.ts @@ -747,8 +747,8 @@ export class PHP implements Disposable { /* * Emscripten throws WASM failures outside of the promise chain so we need * to listen for them here and rethrow in the correct context. Otherwise we - * get crashes and unhandled promise rejections without any useful error messages - * or stack traces. + * get crashes and unhandled promise rejections without any useful error + * messages or stack traces. */ let errorListener: any; try { diff --git a/packages/php-wasm/util/src/lib/paths.ts b/packages/php-wasm/util/src/lib/paths.ts index dd4b2f8bf3..92dc933785 100644 --- a/packages/php-wasm/util/src/lib/paths.ts +++ b/packages/php-wasm/util/src/lib/paths.ts @@ -112,8 +112,8 @@ export function normalizePath(path: string) { * * For example: * - * > normalizePathsArray(['wordpress', 'wp-content', '..', '', '.', 'wp-includes']) - * ['wordpress', 'wp-includes'] + * > normalizePathsArray(['wordpress', 'wp-content', '..', '', '.', + * 'wp-includes']) ['wordpress', 'wp-includes'] * * @param parts parts of the path to normalize * @param allowAboveRoot allow paths above the root diff --git a/packages/php-wasm/util/src/lib/split-shell-command.ts b/packages/php-wasm/util/src/lib/split-shell-command.ts index dd21404ebd..b81a0fc65c 100644 --- a/packages/php-wasm/util/src/lib/split-shell-command.ts +++ b/packages/php-wasm/util/src/lib/split-shell-command.ts @@ -1,7 +1,7 @@ /** * Naive shell command parser. - * Ensures that commands like `wp option set blogname "My blog name"` are split into - * `['wp', 'option', 'set', 'blogname', 'My blog name']` instead of + * Ensures that commands like `wp option set blogname "My blog name"` are split + * into `['wp', 'option', 'set', 'blogname', 'My blog name']` instead of * `['wp', 'option', 'set', 'blogname', 'My', 'blog', 'name']`. * * @param command @@ -20,9 +20,8 @@ export function splitShellCommand(command: string) { const char = command[i]; if (char === '\\') { // Escaped quotes are treated as normal characters - // This is a very naive approach to escaping, but it's good enough for now. - // @TODO: Iterate on this later, perhaps using bun shell. - // @see https://github.com/WordPress/wordpress-playground/issues/1062 + // This is a very naive approach to escaping, but it's good enough for + // now. @TODO: Iterate on this later, perhaps using bun shell. @see https://github.com/WordPress/wordpress-playground/issues/1062 if (command[i + 1] === '"' || command[i + 1] === "'") { i++; } diff --git a/packages/php-wasm/web-service-worker/src/initialize-service-worker.ts b/packages/php-wasm/web-service-worker/src/initialize-service-worker.ts index cc47d821bf..40be283e7a 100644 --- a/packages/php-wasm/web-service-worker/src/initialize-service-worker.ts +++ b/packages/php-wasm/web-service-worker/src/initialize-service-worker.ts @@ -60,7 +60,8 @@ async function defaultRequestHandler(event: FetchEvent) { ) { const request = await cloneRequest(event.request, { url, - // Omit credentials to avoid causing cache aborts due to presence of cookies + // Omit credentials to avoid causing cache aborts due to presence of + // cookies credentials: 'omit', }); return fetch(request); diff --git a/packages/php-wasm/web/src/lib/api.ts b/packages/php-wasm/web/src/lib/api.ts index 925b9396e4..7ade06f19c 100644 --- a/packages/php-wasm/web/src/lib/api.ts +++ b/packages/php-wasm/web/src/lib/api.ts @@ -159,8 +159,9 @@ function setupTransferHandlers() { }, }); // Augment Comlink's throw handler to include Error the response and source - // information in the serialized error object. BasePHP may throw PHPExecutionFailureError - // which includes those information and we'll want to display them for the user. + // information in the serialized error object. BasePHP may throw + // PHPExecutionFailureError which includes those information and we'll want to + // display them for the user. const throwHandler = Comlink.transferHandlers.get('throw')!; const originalSerialize = throwHandler?.serialize; throwHandler.serialize = ({ value }: any) => { diff --git a/packages/php-wasm/web/src/lib/register-service-worker.ts b/packages/php-wasm/web/src/lib/register-service-worker.ts index 930bcc1eee..9114a912fe 100644 --- a/packages/php-wasm/web/src/lib/register-service-worker.ts +++ b/packages/php-wasm/web/src/lib/register-service-worker.ts @@ -9,7 +9,8 @@ export interface Client extends Remote {} /** * Resolves when the PHP API client is set. * - * This allows us to wait for the PHP API client to be set before proxying service worker messages to the web worker. + * This allows us to wait for the PHP API client to be set before proxying + * service worker messages to the web worker. */ let resolvePhpApi: (api: Client) => void; export const phpApiPromise = new Promise((resolve) => { @@ -71,8 +72,8 @@ export async function registerServiceWorker(scope: string, scriptUrl: string) { } catch (e) { // registration.update() throws if it can't reach the server. // We're swallowing the error to keep the app working in offline mode - // or when playground.wordpress.net is down. We can be sure we have a functional - // service worker at this point because sw.register() succeeded. + // or when playground.wordpress.net is down. We can be sure we have a + // functional service worker at this point because sw.register() succeeded. logger.error('Failed to update service worker.', e); } diff --git a/packages/php-wasm/web/src/lib/setup-post-message-relay.ts b/packages/php-wasm/web/src/lib/setup-post-message-relay.ts index 1a00e6253e..53545772c1 100644 --- a/packages/php-wasm/web/src/lib/setup-post-message-relay.ts +++ b/packages/php-wasm/web/src/lib/setup-post-message-relay.ts @@ -2,10 +2,10 @@ * Setup a postMessage relay between the parent window and a nested iframe. * * When we're running a Playground instance inside an iframe, sometimes that - * iframe will contain another iframe and so on. The parent application, however, - * needs to be able to communicate with the innermost iframe. This function relays - * the communication both ways. Call it in in every iframe layer between the topmost - * window and the innermost iframe. + * iframe will contain another iframe and so on. The parent application, + * however, needs to be able to communicate with the innermost iframe. This + * function relays the communication both ways. Call it in in every iframe + * layer between the topmost window and the innermost iframe. * * @param nestedFrame The nested iframe element * @param expectedOrigin The origin that the nested iframe is expected to be on. If not diff --git a/packages/php-wasm/web/vite.config.ts b/packages/php-wasm/web/vite.config.ts index 8e6d0e75f6..ea41ec1aa8 100644 --- a/packages/php-wasm/web/vite.config.ts +++ b/packages/php-wasm/web/vite.config.ts @@ -39,8 +39,9 @@ export default defineConfig(({ command }) => { * This workaround replaces the actual php_5_6.js modules paths used * in the dev mode with their filenames. Then, the filenames are marked * as external further down in this config. As a result, the final - * bundle contains literal `import('php_5_6.js')` and `import('php_5_6.wasm')` - * statements which allows the consumers to use their own loaders. + * bundle contains literal `import('php_5_6.js')` and + * `import('php_5_6.wasm')` statements which allows the consumers to use + * their own loaders. * * This keeps the dev mode working AND avoids inlining 5mb of * wasm via base64 in the final bundle. diff --git a/packages/playground/blueprints/src/lib/blueprint.ts b/packages/playground/blueprints/src/lib/blueprint.ts index f0b37d7d4c..5eeeb9f3c0 100644 --- a/packages/playground/blueprints/src/lib/blueprint.ts +++ b/packages/playground/blueprints/src/lib/blueprint.ts @@ -39,7 +39,8 @@ export interface Blueprint { */ author: string; /** - * Relevant categories to help users find your Blueprint in the future Blueprints section on WordPress.org. + * Relevant categories to help users find your Blueprint in the future + * Blueprints section on WordPress.org. */ categories?: string[]; }; diff --git a/packages/playground/blueprints/src/lib/compile.ts b/packages/playground/blueprints/src/lib/compile.ts index b1e7248c3c..8b55b6a27e 100644 --- a/packages/playground/blueprints/src/lib/compile.ts +++ b/packages/playground/blueprints/src/lib/compile.ts @@ -190,13 +190,13 @@ export function compileBlueprint( resource: 'url', /** * Use compression for downloading the wp-cli.phar file. - * The official release, hosted at raw.githubusercontent.com, is ~7MB and the - * transfer is uncompressed. playground.wordpress.net supports transfer compression - * and only transmits ~1.4MB. + * The official release, hosted at raw.githubusercontent.com, is ~7MB + * and the transfer is uncompressed. playground.wordpress.net supports + * transfer compression and only transmits ~1.4MB. * * @TODO: minify the wp-cli.phar file. It can be as small as 1MB when all the - * whitespaces and are removed, and even 500KB when libraries like the - * JavaScript parser or Composer are removed. + * whitespaces and are removed, and even 500KB when libraries + * like the JavaScript parser or Composer are removed. */ url: 'https://playground.wordpress.net/wp-cli.phar', }, @@ -204,7 +204,8 @@ export function compileBlueprint( }; /** * If the blueprint does not have a wp-cli step, - * we can install wp-cli as the last step because other steps don't depend on wp-cli. + * we can install wp-cli as the last step because other steps don't depend + * on wp-cli. * * If the blueprint has wp-cli steps, * we need to install wp-cli before running these steps. diff --git a/packages/playground/blueprints/src/lib/resources.ts b/packages/playground/blueprints/src/lib/resources.ts index 8501740cc2..7e12c1b562 100644 --- a/packages/playground/blueprints/src/lib/resources.ts +++ b/packages/playground/blueprints/src/lib/resources.ts @@ -137,7 +137,8 @@ export abstract class Resource { } } /** - * A `Resource` that represents a file in the VFS (virtual file system) of the playground. + * A `Resource` that represents a file in the VFS (virtual file system) of the + * playground. */ export class VFSResource extends Resource { /** @@ -372,7 +373,8 @@ export function toDirectoryZipName(rawInput: string) { } /** - * A decorator for a resource that adds functionality such as progress tracking and caching. + * A decorator for a resource that adds functionality such as progress tracking + * and caching. */ export class DecoratedResource extends Resource { constructor(private resource: T) { @@ -426,7 +428,8 @@ export class CachedResource extends DecoratedResource { } /** - * A decorator for a resource that adds concurrency control functionality through a semaphore. + * A decorator for a resource that adds concurrency control functionality + * through a semaphore. */ export class SemaphoreResource< T extends Resource diff --git a/packages/playground/blueprints/src/lib/steps/activate-plugin.ts b/packages/playground/blueprints/src/lib/steps/activate-plugin.ts index a14b34664f..0d08958340 100644 --- a/packages/playground/blueprints/src/lib/steps/activate-plugin.ts +++ b/packages/playground/blueprints/src/lib/steps/activate-plugin.ts @@ -16,7 +16,11 @@ import { logger } from '@php-wasm/logger'; */ export interface ActivatePluginStep { step: 'activatePlugin'; - /** Path to the plugin directory as absolute path (/wordpress/wp-content/plugins/plugin-name); or the plugin entry file relative to the plugins directory (plugin-name/plugin-name.php). */ + /** + * Path to the plugin directory as absolute path + * (/wordpress/wp-content/plugins/plugin-name); or the plugin entry file + * relative to the plugins directory (plugin-name/plugin-name.php). + */ pluginPath: string; /** Optional. Plugin name to display in the progress bar. */ pluginName?: string; diff --git a/packages/playground/blueprints/src/lib/steps/import-theme-starter-content.spec.ts b/packages/playground/blueprints/src/lib/steps/import-theme-starter-content.spec.ts index fd6ae20ebb..b02dd23d91 100644 --- a/packages/playground/blueprints/src/lib/steps/import-theme-starter-content.spec.ts +++ b/packages/playground/blueprints/src/lib/steps/import-theme-starter-content.spec.ts @@ -26,7 +26,8 @@ describe('Blueprint step importThemeStarterContent', () => { it('Should import theme starter content', async () => { const docroot = php.documentRoot; - // Create a test theme with starter content, Must have at a minimum style.css + index.php + // Create a test theme with starter content, Must have at a minimum + // style.css + index.php php.mkdir(`${docroot}/wp-content/themes/test-theme`); php.writeFile( `${docroot}/wp-content/themes/test-theme/style.css`, diff --git a/packages/playground/blueprints/src/lib/steps/install-asset.ts b/packages/playground/blueprints/src/lib/steps/install-asset.ts index 4d21b62b62..366c8310ec 100644 --- a/packages/playground/blueprints/src/lib/steps/install-asset.ts +++ b/packages/playground/blueprints/src/lib/steps/install-asset.ts @@ -61,7 +61,8 @@ export async function installAsset( let files = await playground.listFiles(tmpUnzippedFilesPath, { prependPath: true, }); - // _unzip_file_ziparchive in WordPress skips the __MACOSX files, and so should we here. + // _unzip_file_ziparchive in WordPress skips the __MACOSX files, and so + // should we here. files = files.filter((name) => !name.endsWith('/__MACOSX')); /** diff --git a/packages/playground/blueprints/src/lib/steps/request.ts b/packages/playground/blueprints/src/lib/steps/request.ts index cceb994ad8..fa5ab4f610 100644 --- a/packages/playground/blueprints/src/lib/steps/request.ts +++ b/packages/playground/blueprints/src/lib/steps/request.ts @@ -26,7 +26,8 @@ import { logger } from '@php-wasm/logger'; export interface RequestStep { step: 'request'; /** - * Request details (See /wordpress-playground/api/universal/interface/PHPRequest) + * Request details (See + * /wordpress-playground/api/universal/interface/PHPRequest) */ request: PHPRequest; } diff --git a/packages/playground/blueprints/src/lib/steps/reset-data.ts b/packages/playground/blueprints/src/lib/steps/reset-data.ts index b56ed981da..5cc4ade576 100644 --- a/packages/playground/blueprints/src/lib/steps/reset-data.ts +++ b/packages/playground/blueprints/src/lib/steps/reset-data.ts @@ -15,8 +15,8 @@ export interface ResetDataStep { } /** - * Deletes WordPress posts and comments and sets the auto increment sequence for the - * posts and comments tables to 0. + * Deletes WordPress posts and comments and sets the auto increment sequence + * for the posts and comments tables to 0. * * @param playground Playground client. */ diff --git a/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts b/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts index ae382b2c9d..f8ea8356e0 100644 --- a/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts +++ b/packages/playground/blueprints/src/lib/steps/run-php-with-options.ts @@ -21,7 +21,8 @@ import { PHPRunOptions } from '@php-wasm/universal'; export interface RunPHPWithOptionsStep { step: 'runPHPWithOptions'; /** - * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions/)) + * Run options (See + * /wordpress-playground/api/universal/interface/PHPRunOptions/)) */ options: PHPRunOptions; } diff --git a/packages/playground/blueprints/src/lib/steps/run-php.ts b/packages/playground/blueprints/src/lib/steps/run-php.ts index c671cf4840..cdeb2066c0 100644 --- a/packages/playground/blueprints/src/lib/steps/run-php.ts +++ b/packages/playground/blueprints/src/lib/steps/run-php.ts @@ -9,7 +9,9 @@ import { StepHandler } from '.'; * * { * "step": "runPHP", - * "code": " 'wp-load.php required for WP functionality', 'post_status' => 'publish')); ?>" + * "code": " 'wp-load.php required for WP + * functionality', 'post_status' => 'publish')); ?>" * } * */ diff --git a/packages/playground/blueprints/src/lib/steps/set-site-language.ts b/packages/playground/blueprints/src/lib/steps/set-site-language.ts index eba23a5084..8c37e3c833 100644 --- a/packages/playground/blueprints/src/lib/steps/set-site-language.ts +++ b/packages/playground/blueprints/src/lib/steps/set-site-language.ts @@ -138,7 +138,8 @@ export const setSiteLanguage: StepHandler = async ( ); } catch (error) { /** - * If a core translation wasn't found we should throw an error because it means the language is not supported or the language code isn't correct. + * If a core translation wasn't found we should throw an error because it + * means the language is not supported or the language code isn't correct. */ if (type === 'core') { throw new Error( @@ -146,8 +147,9 @@ export const setSiteLanguage: StepHandler = async ( ); } /** - * Some languages don't have translations for themes and plugins and will return a 404 and a CORS error. - * In this case, we can just skip the download because Playground can still work without them. + * Some languages don't have translations for themes and plugins and will + * return a 404 and a CORS error. In this case, we can just skip the + * download because Playground can still work without them. */ logger.warn(`Error downloading translations for ${type}: ${error}`); } diff --git a/packages/playground/blueprints/src/lib/steps/wp-cli.ts b/packages/playground/blueprints/src/lib/steps/wp-cli.ts index 292c1bca82..95e444aa5c 100644 --- a/packages/playground/blueprints/src/lib/steps/wp-cli.ts +++ b/packages/playground/blueprints/src/lib/steps/wp-cli.ts @@ -10,7 +10,8 @@ import { phpVar } from '@php-wasm/util'; * * { * "step": "wp-cli", - * "command": "wp post create --post_title='Test post' --post_excerpt='Some content'" + * "command": "wp post create --post_title='Test post' --post_excerpt='Some + * content'" * } * */ @@ -96,8 +97,8 @@ export const wpCLI: StepHandler> = async ( /** * Naive shell command parser. - * Ensures that commands like `wp option set blogname "My blog name"` are split into - * `['wp', 'option', 'set', 'blogname', 'My blog name']` instead of + * Ensures that commands like `wp option set blogname "My blog name"` are split + * into `['wp', 'option', 'set', 'blogname', 'My blog name']` instead of * `['wp', 'option', 'set', 'blogname', 'My', 'blog', 'name']`. * * @param command diff --git a/packages/playground/blueprints/src/lib/steps/zip-wp-content.ts b/packages/playground/blueprints/src/lib/steps/zip-wp-content.ts index 81080cac48..01d8eec14b 100644 --- a/packages/playground/blueprints/src/lib/steps/zip-wp-content.ts +++ b/packages/playground/blueprints/src/lib/steps/zip-wp-content.ts @@ -37,8 +37,8 @@ export const zipWpContent = async ( // This is a bit backwards, so hang on! // We have a list of paths to exclude. // We then *remove* the default theme and the SQLite plugin from that list. - // As a result, we *include* the default theme and the SQLite plugin in the final zip. - // It is hacky and will be removed soon. + // As a result, we *include* the default theme and the SQLite plugin in the + // final zip. It is hacky and will be removed soon. exceptPaths = exceptPaths .filter((path) => !path.startsWith('themes/twenty')) .filter( diff --git a/packages/playground/blueprints/src/lib/utils/flatten-directory.ts b/packages/playground/blueprints/src/lib/utils/flatten-directory.ts index 91d5e8dad5..2d633b54e8 100644 --- a/packages/playground/blueprints/src/lib/utils/flatten-directory.ts +++ b/packages/playground/blueprints/src/lib/utils/flatten-directory.ts @@ -3,8 +3,8 @@ import { dirname, joinPaths } from '@php-wasm/util'; /** * Flattens a directory. - * If the directory contains only one file, it will be moved to the parent directory. - * Otherwise, the directory will be renamed to the default name. + * If the directory contains only one file, it will be moved to the parent + * directory. Otherwise, the directory will be renamed to the default name. * * @param php Playground client. * @param directoryPath The directory to flatten. diff --git a/packages/playground/cli/src/cli.ts b/packages/playground/cli/src/cli.ts index 4727d23b56..c267b69bf6 100644 --- a/packages/playground/cli/src/cli.ts +++ b/packages/playground/cli/src/cli.ts @@ -68,7 +68,8 @@ async function run() { type: 'string', default: 'latest', }) - // @TODO: Support read-only mounts, e.g. via WORKERFS, a custom ReadOnlyNODEFS, or by copying the files into MEMFS + // @TODO: Support read-only mounts, e.g. via WORKERFS, a custom + // ReadOnlyNODEFS, or by copying the files into MEMFS .option('mount', { describe: 'Mount a directory to the PHP runtime. You can provide --mount multiple times. Format: /host/path:/vfs/path', @@ -142,7 +143,8 @@ async function run() { /** * TODO: This exact feature will be provided in the PHP Blueprints library. - * Let's use it when it ships. Let's also use it in the web Playground app. + * Let's use it when it ships. Let's also use it in the web Playground + * app. */ async function zipSite(outfile: string) { // Fake URL for the build @@ -256,7 +258,8 @@ async function run() { let wpDetails: any = undefined; const monitor = new EmscriptenDownloadMonitor(); if (!args.skipWordPressSetup) { - // @TODO: Rename to FetchProgressMonitor. There's nothing Emscripten about that class anymore. + // @TODO: Rename to FetchProgressMonitor. There's nothing Emscripten + // about that class anymore. monitor.addEventListener('progress', (( e: CustomEvent ) => { diff --git a/packages/playground/cli/src/download.ts b/packages/playground/cli/src/download.ts index 1eae2589ba..0f9b804521 100644 --- a/packages/playground/cli/src/download.ts +++ b/packages/playground/cli/src/download.ts @@ -9,7 +9,8 @@ export const CACHE_FOLDER = path.join(os.homedir(), '.wordpress-playground'); /** * @TODO: Look for a common abstraction with the downloads done by the website setup. * These downloads look similar to what the website does to setup WordPress. - * The website could also use service worker caching to speed up the process. + * The website could also use service worker caching to speed up the + * process. */ export async function fetchWordPress( wpVersion = 'latest', @@ -35,7 +36,8 @@ export async function fetchSqliteIntegration( return sqliteZip; } -// @TODO: Support HTTP cache, invalidate the local file if the remote file has changed +// @TODO: Support HTTP cache, invalidate the local file if the remote file has +// changed export async function cachedDownload( remoteUrl: string, cacheKey: string, diff --git a/packages/playground/client/src/index.ts b/packages/playground/client/src/index.ts index 9ca839cdd8..c63a99bde7 100644 --- a/packages/playground/client/src/index.ts +++ b/packages/playground/client/src/index.ts @@ -131,13 +131,14 @@ export async function startPlaygroundWeb({ } /** - * Chrome does not allow Service Workers to be registered from cross-origin iframes - * when third-party cookies are disabled unless `requestStorageAccess()` is called - * and the user grants storage access. + * Chrome does not allow Service Workers to be registered from cross-origin + * iframes when third-party cookies are disabled unless + * `requestStorageAccess()` is called and the user grants storage access. * * However, sandboxed