Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@
"yoast/phpunit-polyfills": "^1.1.0",
"gutenberg/gutenberg-coding-standards": "@dev",
"phpstan/extension-installer": "1.4.3",
"phpstan/phpstan": "2.3.4",
"phpstan/phpstan": "2.3.5",
"phpstan/phpstan-phpunit": "2.1.1",
"php-stubs/wordpress-stubs": "@dev",
"php-stubs/wordpress-tests-stubs": "7.1.0",
Expand Down Expand Up @@ -69,6 +69,10 @@
"lint": "phpcs --standard=phpcs.xml.dist",
"phpstan": "@php tools/phpstan/generate-wordpress-stubs.php --quiet && phpstan analyse --memory-limit=2G",
"phpstan:baselines": "@phpstan --configuration=phpstan.neon.dist --generate-baseline=tools/phpstan/baseline.neon --allow-empty-baseline",
"phpstan:fix": [
"@phpstan --configuration=phpstan.neon.dist --fix",
"@phpstan --configuration=phpstan.neon.dist"
],
"phpstan:generate-wordpress-stubs": "@php tools/phpstan/generate-wordpress-stubs.php",
"test": "phpunit",
"test:watch": "phpunit-watcher watch < /dev/tty"
Expand Down
10 changes: 7 additions & 3 deletions docs/contributors/code/coding-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -829,10 +829,14 @@ First run `composer install` and `npm run build`, which generates PHP files that

#### The baseline

Errors that predate the analysis are recorded in [`tools/phpstan/baseline.neon`](https://github.com/WordPress/gutenberg/blob/HEAD/tools/phpstan/baseline.neon). When a change fixes one of them, PHPStan reports the baseline entry as unmatched. Regenerate the baseline in either of these ways, and commit the result:
Errors that predate the analysis are recorded in [`tools/phpstan/baseline.neon`](https://github.com/WordPress/gutenberg/blob/HEAD/tools/phpstan/baseline.neon). When a change fixes one of them, PHPStan reports the baseline entry as unmatched, or its count as too high, and marks the error with 🔧. Remove the entry or lower its count in either of these ways, and commit the result:

- `composer phpstan:baselines`, with PHP and Composer installed on your computer.
- `npm run typecheck:php:baselines`, in the local environment.
- `composer phpstan:fix`, with PHP and Composer installed on your computer.
- `npm run typecheck:php:fix`, in the local environment.

This runs PHPStan with `--fix` over all the paths, since PHPStan reports no out-of-date entries when it analyzes only some files, and then runs the analysis again, since `--fix` reports only what it fixed. The script fails when errors remain, and also when there is nothing to fix. Both runs use `phpstan.neon.dist`, even when a local `phpstan.neon` exists, since a configuration at another rule level can report a baselined error with a different message, which would make `--fix` remove entries the default configuration still needs.

Unlike regenerating the baseline with `composer phpstan:baselines` (or `npm run typecheck:php:baselines`), `--fix` never adds an entry, so it does not record any other errors the change introduces as accepted. It also removes an `@phpstan-ignore` comment that no longer ignores anything, and fixes any other error marked with 🔧, so review the diff before committing it.

#### WordPress stubs

Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,7 @@
"typecheck": "npm run --workspace @wordpress/build-scripts typecheck --",
"typecheck:php": "wp-env run --env-cwd='wp-content/plugins/gutenberg' cli composer run-script phpstan --",
"typecheck:php:baselines": "wp-env run --env-cwd='wp-content/plugins/gutenberg' cli composer run-script phpstan:baselines --",
"typecheck:php:fix": "wp-env run --env-cwd='wp-content/plugins/gutenberg' cli composer run-script phpstan:fix --",
"wp-env": "wp-env",
"wp-env-test": "wp-env --config .wp-env.test.json",
"test:unit:consumers": "npm run --workspace @wordpress/validation-tools test-vitest-consumers --"
Expand Down
3 changes: 2 additions & 1 deletion phpstan.neon.dist
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ includes:
# The base configuration file for using PHPStan with the Gutenberg codebase.
- tools/phpstan/base.neon

# Preexisting errors that should be ignored. Regenerate with `composer phpstan:baselines`.
# Preexisting errors that should be ignored. Regenerate with `composer phpstan:baselines`, or remove the entries
# for fixed errors with `composer phpstan:fix`.
# https://phpstan.org/user-guide/baseline
- tools/phpstan/baseline.neon

Expand Down
2 changes: 1 addition & 1 deletion tools/phpstan/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Tooling for the [PHPStan](https://phpstan.org/) static analysis of the PHP in th
## Contents

- `base.neon`: the shared configuration, which `phpstan.neon.dist` at the repository root includes along with the baseline.
- `baseline.neon`: the errors that predate the analysis, regenerated with `composer phpstan:baselines`.
- `baseline.neon`: the errors that predate the analysis, regenerated with `composer phpstan:baselines`. Entries whose errors were fixed are removed with `composer phpstan:fix`.
- `bootstrap.php`, `polyfills.stub`, `wp-build-templates.php`, and `src/`: what PHPStan loads to analyze the code, including the parser for the `wp-build` PHP templates.
- `generate-wordpress-stubs.php` and `wordpress-stubs/`: the WordPress stubs generated from core trunk, and the script that generates them.
- `report.ts`: reports the errors in a PHPStan JSON report as annotations and in the job summary in CI.
Expand Down
51 changes: 36 additions & 15 deletions tools/phpstan/report.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,8 @@ interface PhpstanError {
identifier: string | null;
/** Tip shown with the error, if any. */
tip: string | null;
/** Whether running PHPStan with `--fix` fixes the error. */
fixable: boolean;
}

/**
Expand All @@ -65,6 +67,7 @@ interface PhpstanReportMessage {
line?: number | null;
identifier?: string;
tip?: string;
fixable?: boolean;
}

/**
Expand All @@ -80,7 +83,7 @@ interface PhpstanReport {

/**
* Whether an error means a baseline entry records more occurrences of an error
* than there are now, because some were fixed. Regenerating the baseline fixes
* than there are now, because some were fixed. `composer phpstan:fix` fixes
* it.
*
* @param error The error.
Expand Down Expand Up @@ -118,6 +121,10 @@ const ANNOTATION_LIMIT = 10;
*/
const SUMMARY_LIMIT = 500;

// Added to the annotation of an error that PHPStan can fix itself, such as an out-of-date baseline entry.
const FIX_HINT =
'This can be fixed automatically by running `composer phpstan:fix` (or `npm run typecheck:php:fix`).';

/**
* Escapes the message of a workflow command.
*
Expand Down Expand Up @@ -182,6 +189,7 @@ function readErrors( reportPath: string ): PhpstanError[] | null {
message,
identifier: null,
tip: null,
fixable: false,
} ) );

for ( const [ key, file ] of Object.entries( report.files ) ) {
Expand All @@ -197,6 +205,7 @@ function readErrors( reportPath: string ): PhpstanError[] | null {
message: message.message,
identifier: message.identifier ?? null,
tip: message.tip ?? null,
fixable: message.fixable ?? false,
} );
}
}
Expand All @@ -222,9 +231,13 @@ function annotate( errors: PhpstanError[] ): void {
if ( error.line ) {
properties.push( `line=${ error.line }` );
}
const message = error.tip
? `${ error.message }\n${ error.tip }`
: error.message;
const message = [
error.message,
error.tip,
error.fixable ? FIX_HINT : null,
]
.filter( Boolean )
.join( '\n' );
process.stdout.write(
`::error ${ properties.join( ',' ) }::${ escapeData( message ) }\n`
);
Expand Down Expand Up @@ -277,27 +290,27 @@ function buildSummary( errors: PhpstanError[] ): string {
'### The baseline is out of date',
'An entry in `tools/phpstan/baseline.neon` records an error that now occurs fewer times, or not at all.'
);
sections.push(
'**If this pull request fixed one of them, this is expected**, and there is nothing to change in the code: remove the out-of-date entries by running PHPStan with `--fix`, and commit the result.',
'```bash\ncomposer phpstan:fix\n```',
'or, in the local environment:',
'```bash\nnpm run typecheck:php:fix\n```'
);
if (
errors.some(
( error ) =>
! isStaleBaselineEntry( error ) &&
! isExceededBaselineEntry( error )
)
) {
// Regenerating now would record those errors in the baseline.
/*
* `--fix` only lowers or removes baseline entries, whereas regenerating
* the baseline now would record those errors in it.
*/
sections.push(
'This run also reports other errors, which are listed below. **Fix those first**, since regenerating the baseline would record them as accepted errors. When a pull request changes a line with a baselined error, the error can also come back as a new one with a different message, so that its baseline entry no longer matches: fix it rather than regenerating the baseline. Once only out-of-date entries are left, regenerate the baseline and commit the result.'
);
} else {
sections.push(
'**If this pull request fixed one of them, this is expected**, and there is nothing to change in the code: regenerate the baseline and commit the result.'
'This run also reports other errors, which are listed below, and which still need to be fixed. `--fix` leaves them reported, but **do not regenerate the baseline** with `composer phpstan:baselines` until they are fixed, since that would record them as accepted errors. When a pull request changes a line with a baselined error, the error can also come back as a new one with a different message, so that its baseline entry no longer matches: fix the new error rather than baselining it.'
);
}
sections.push(
'```bash\ncomposer phpstan:baselines\n```',
'or, in the local environment:',
'```bash\nnpm run typecheck:php:baselines\n```'
);
}

if ( errors.some( isExceededBaselineEntry ) ) {
Expand All @@ -316,6 +329,8 @@ function buildSummary( errors: PhpstanError[] ): string {
? `<code>${ escapeHtml( error.identifier ) }</code>`
: ''
}</td><td>${ escapeHtml( error.message ) }${
error.fixable ? ' 🔧' : ''
}${
error.tip ? `<br><em>${ escapeHtml( error.tip ) }</em>` : ''
}</td></tr>`
);
Expand All @@ -333,6 +348,12 @@ function buildSummary( errors: PhpstanError[] ): string {
);
}

if ( errors.some( ( error ) => error.fixable ) ) {
sections.push(
'Errors marked with 🔧 can be fixed automatically by running `composer phpstan:fix` (or `npm run typecheck:php:fix`).'
);
}

if ( errors.length > ANNOTATION_LIMIT ) {
sections.push(
`Only the first ${ ANNOTATION_LIMIT } errors are shown as annotations on the pull request.`
Expand Down
Loading