Make the toolchain work, and the docs match it - #1
Merged
Conversation
The composer scripts this repo documents did not run. `phpunit` had no configuration, `phpcs` had no ruleset, and `composer check` chains both, so it failed twice over. `composer analyze` reported errors that are inherent to stubs rather than defects here: the generated files sat in PHPStan's `paths`, which asks it to check the bodies of declarations that are empty by definition. They are `scanFiles` now -- the symbols become known without any claim about bodies a stub cannot have -- and `paths` covers the hand-written PHP instead. tests/StubsTest.php asserts the two properties a generated file must hold whatever it contains: it parses (TOKEN_PARSE, so invalid source raises rather than returning a best-effort token list), and it declares something. Those are the two shapes a failed regeneration takes -- a truncated file, and a file that is nothing but its header. Adds CI on push and pull request across PHP 7.4 and 8.3. Nothing ran on a change before. Where the upstream plugin is on WordPress.org, adds a weekly check comparing its latest release against the newest tag here, opening one issue when this package falls behind. Staleness is the failure a stubs package actually has, and it is silent: upstream ships a symbol, this package does not, and the only sign of it appears in somebody else's static analysis. Both version strings are validated as numeric before either reaches an issue body. Adds CHANGELOG.md, reconstructed from the tags.
Follow-ups from the first CI run on this branch: - token_get_all()'s result is asserted rather than discarded; PHPStan reports a bare call as having no effect. - A constants stub is allowed to be empty. Four of these repositories ship one that is header-only, and a plugin defining no constants is legitimate output -- so the declaration check applies to the declaration stubs, where a truncated file is unambiguous. - divi-theme had no cs/analyze/test scripts at all; added, with the phpunit and phpcs dev dependencies they need. - forminator declared php >=7.4 while its stubs use constructor property promotion, which 7.4 cannot parse. The floor is >=8.0, and CI now tests what the package claims.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three of the documented composer scripts did not run, and
composer analyzereported errors inherent to stubs rather than defects here.Broken tooling
phpunithad no configuration;phpcshad no ruleset.composer checkchains both, so it failed twice over.composer analyzehad the generated stubs in PHPStanpaths, which asks it to check the bodies of declarations that are empty by definition —should return X but return statement is missingfor every one, plus unknown-class errors for whatever WordPress internals upstream touches. PHPStan 2.x classifies several of those as non-ignorable, so neither an ignoreErrors pattern nor a baseline can hold them.The stubs are
scanFilesnow — symbols become known without any claim about bodies a stub cannot have.pathscovers the hand-written PHP instead.What replaces it
tests/StubsTest.phpasserts the two properties a generated file must hold whatever it contains:TOKEN_PARSE, so invalid source raises rather than returning a best-effort token listStub files are discovered by glob, so a repo that grows another one is covered without anyone remembering.
CI
ci.yml—cs,analyze,teston push and PR, across PHP 7.4 and 8.3. Nothing ran on a change before.upstream-check.yml(where the plugin is on WordPress.org) — weekly comparison of the latest release against the newest tag here, opening one issue when this package falls behind. Staleness is the failure a stubs package actually has, and it is silent. Both version strings are validated as numeric before reaching an issue body.Plus
CHANGELOG.md, reconstructed from the tags.