Preserve documentation and hook string semantics

[sirreal]

Fixes #254.

What changed

• Stop applying namespace cleanup to every exported string.
• Normalize AST names at expression and metadata boundaries, preserving established JSON for defaults, constants, references, and call metadata.
• Export literal hook names with PHP string semantics.

Why

The PHP-Parser 5 compatibility cleanup treated documentation and hook literals as identifiers. It removed meaningful backslashes. Simply deleting that cleanup also caused broad JSON churn such as false becoming \false.

Keep syntax normalization where it belongs. Leave text alone.

Side effects

• Printing single-segment names without the leading backslash restores Method_Call_Reflector's factory-function class mapping, which had been dead since the PHP-Parser upgrade: get_current_screen()->add_help_tab() now exports uses.methods[].class as WP_Screen (likewise wp_get_theme() → WP_Theme, _get_list_table() → WP_List_Table, and the other mapped factories). Pinned by test.

Testing

• npm run test:phpunit — 28 tests, 158 assertions; 11 pre-existing PHPUnit deprecation warnings.
• php tests/prep-diff-test.php
• Full wp-includes export: expected documentation escapes remain; no stray global prefixes in defaults, constant values, references, or call-class metadata.

---

Update: documentation text is now exported as authored

The final commits settle the remaining question from review: what happens to a backslash that an author actually typed inside documentation prose.

Documentation text fields are now exported byte-for-byte as authored, backslashes included:

• description and long_description
• tag content, description, refers, and link

So a docblock that says {@see \parse_blocks()} or @see \json_last_error() exports with the leading \ intact, instead of having it silently removed. Previously the export stripped it, which corrupted references to global functions in namespaced code and made the exported text differ from the source.

Deliberate deviation: type fields keep the global-prefix strip

Type fields are not treated as documentation text. Tag types and argument type still have the global namespace prefix stripped.

This is intentional, not an oversight. The vendored phpDocumentor (Type\Collection::expand() in reflection-docblock) prefixes every non-keyword type with \ while resolving a docblock. By the time the parser sees a type, the author's original spelling is gone: @param Foo and @param \Foo both arrive as \Foo. There is no information left to preserve. Dropping the strip would not restore author intent — it would stamp a synthetic \ onto essentially every typed parameter in the corpus, churning the JSON for no gain.

A test pins this boundary: an author writing @param \Global_Prefixed_Type still exports Global_Prefixed_Type.

The governing principle: documentation text is preserved as authored; resolver output is normalized.

Corpus verification

Regenerated the full export over WordPress 7.0.4 wp-includes (1039 PHP files) and diffed against the merge base (66f26b0). Both sides used identical vendor trees (composer.lock is unchanged by this PR; all 59 packages byte-identical) and the same PHP engine, normalized with the corrected prep-diff from #279.

Whole PR vs. merge base — 102 hunks, 109 changed values, every one accounted for:

Count	Category
28	Documentation text gains an author-written backslash — {@see \parse_blocks()}, refers: \json_last_error(), {@see \mb_convert_encoding()}, \utf8_decode()
72	Expression strings drop a synthetic backslash — \true → true, \null → null, \compact( → compact(, \COOKIEHASH → COOKIEHASH, \PHP_INT_MAX → PHP_INT_MAX
9	uses.methods[].class factory mapping restored — wp_get_theme() → WP_Theme, get_current_screen() → WP_Screen
0	Unclassified

The 72 expression changes break down as hook arguments (26), uses.methods[].class call expressions (27), property defaults (15), and constant values (4). These, and the 9 factory mappings, are this PR's stated purpose — see "What changed" and "Side effects" above.

Isolating the final as-authored commit (0b4d163..edac50a) — 20 hunks, 22 changed values, 100% documentation text. No hook field, expression, type, uses, or extends value moves.

Zero changes corpus-wide to type, types, extends, implements, aliases, or hook name — confirming the types deviation above holds in practice: no synthetic \ is stamped onto any type in 1039 files.

Warning

This PR has no automated corpus verification. The numbers above are the only corpus evidence — please review them rather than looking for a green check.

The "Corpus Diff" CI workflow does not exist on this branch; it is still unmerged in #284. And once it does land, running it against fix-254 as-is would under-report these changes anyway: this branch's prep-diff.php normalizes documentation text away, so the doc-text changes that are the point of this PR would be silently cancelled out on both sides of the diff and reported as ~0 hunks. #279 fixes exactly that, which is why the numbers above were produced with #279's prep-diff instead.

Testing (updated)

• Full PHPUnit suite on PHP 7.4: 167 tests, 463 assertions, all passing. (The three Error processing file lines in the output are assertions from the Blueprint error-handling fixtures, not failures.)
• CI green on PHP 7.4 and 8.4.