Align the prep-diff tool with the exporter's normalization rules - #279
Open
sirreal wants to merge 4 commits into
Open
Align the prep-diff tool with the exporter's normalization rules#279sirreal wants to merge 4 commits into
sirreal wants to merge 4 commits into
Conversation
Extracted from the original "Preserve expression output" commit so the diff tool's changes can land separately from the exporter's. The diff normalization must follow the same rules the exporter uses when it strips PHP-Parser's synthetic global namespace prefixes, otherwise the normalized output no longer matches what the exporter produces.
`tests/prep-diff-test.php` was a standalone script that nothing executed: `phpunit.xml.dist` only loads `tests/phpunit/tests/`, and both `composer test` and CI run PHPUnit with that configuration. Move it under `tests/phpunit/tests/` as a test case so that it runs with the rest of the suite. `prep-diff.php` normalized printed expressions with its own prose-oriented regular expression, which also matched global names appearing inside string literals. An argument default of `'see \Foo bar'` was rewritten to `'see Foo bar'`, which is exactly the mangled output the script is meant to expose, so a regression in expression printing diffed clean. Reuse the exporter's `WP_Parser\strip_global_namespace_prefix()` instead, which only strips a prefix at the start of a value. Inline documentation references are unaffected: they never contain whitespace, so both rules produce the same result for them. Diffs of output generated before and after this branch now show the string-literal fix instead of hiding it, which is intended.
The exporter now hands documentation text through as authored: inline references in descriptions and tag content, and the reference tokens of `@see`/`@link` tags. A difference in those fields between two builds is a real behavior change, so the diff normalization must not erase it.
Match the exporter: documentation text is exported as authored, so the diff tool has nothing to reconcile in descriptions, tag content, or the `refers`/`link` tokens — and normalizing them would hide a real change in exactly the fields the exporter promises not to touch. Expression and type fields keep the anchored-prefix normalization the exporter still applies.
sirreal
force-pushed
the
prep-diff-updates
branch
from
August 20, 2026 10:10
87520b5 to
9b41ff9
Compare
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.
Stacked on #262 (base branch:
fix-254). Extracts the diff-tool work from that PR so it can be reviewed separately from the export-semantics changes.The rule
prep-diff.phpnormalizes generated JSON so two exports can be compared without incidental churn. Its normalization must mirror the exporter's own rules exactly — anything it normalizes beyond them is a real behavior change it will hide.After this branch, the tool follows the same split #262 establishes:
description,long_description, and tagcontent,refers, andlink. The exporter now emits these as authored, so the diff tool has nothing to reconcile. Normalizing them would cancel out an intended change on both sides of a diff and report it as no change at all.class,default,extends,type,value, and thetypes/aliases/implementscollections, matching what the exporter still normalizes.Why it matters
Without the final commit, a corpus diff of #262 reports roughly zero documentation-text hunks — the tool strips the author-written backslash from
{@see \parse_blocks()}on both sides, so exactly the change #262 exists to make becomes invisible to review. With this branch, that change shows up: the manual corpus verification quoted in #262's description was produced with this branch'sprep-diff.php.The earlier hand-rolled prose regex had the same failure mode in miniature: it matched inside string literals, rewriting
'see \Foo bar'to'see Foo bar'on both sides. Replacing it with the exporter's own anchored\WP_Parser\strip_global_namespace_prefix()means a regression that re-introduces string corruption now surfaces in the diff instead of vanishing.Commits
02a2035) — the prep-diff changes originally bundled into Preserve documentation and hook string semantics #262's "Preserve expression output" commit: normalization for the fields whose output Preserve documentation and hook string semantics #262 changes.da20168) — relocatestests/prep-diff-test.phptotests/phpunit/tests/prep-diff.phpas a PHPUnit class so CI actually executes it (previously no runner invoked it), and swaps the prose regex for the exporter's shared helper.6ce9808) — pins the pass-through behavior.9b41ff9) — drops the{@see}/{@link}rewrite and removeslinkandrefersfrom the normalized keys.Testing
prep-diff.phpstill runs standalone:php prep-diff.php < export.json.