wp-php-toolkit/bytestream

Fix documentation accuracy issues

Fix documentation accuracy issues

Fix documentation accuracy issues

Fix documentation accuracy issues

Fix documentation accuracy issues

Fix documentation accuracy issues

Fix documentation accuracy issues

Summary

The toolkit now documents itself using only its own runtime and its
own structured-data parsers. No Python in CI; no hand-rolled regex over
markdown or HTML.

What changed

Parsers

Behavioural parity

• 87/87 snippets match their captured stdout. The PHP normalizer
  mirrors the Python regex set 1:1, so existing expected-output blocks
  stay valid.
• docs/reference/*.html render correctly: 9 <php-snippet> + 9
  fallback + 9 expected-output triples on html.html, 4 pitfall callouts
  (the bold-lead pattern is preserved), see-also list intact.
• --update verified end-to-end:
• When an expected-output block has drifted, the rewritten content is
  byte-for-byte the original.
• When no expected-output exists for a snippet, --update inserts a
  fresh block in the right place; resulting README is byte-identical to
  one with the block authored manually.

Frontmatter format change: see_also is a proper YAML list

# Before (repeated keys — not standard YAML)
see_also: a | A | reason
see_also: b | B | reason

# After
see_also:
  - a | A | reason
  - b | B | reason

Webuni\FrontMatter\FrontMatter correctly types it as a sequence; any
frontmatter-aware tool reading the README sees the same shape. All 18
component READMEs migrated.

Workflows simplified

• snippet-tests.yml drops the actions/setup-python step.
• docs.yml swaps python3 bin/build-reference.py for php bin/build-reference.php.

Remaining preg_* calls (all on plain text, not HTML)

• slugify() — heading text → URL-safe slug.
• normalize() — scrubs noise from snippet stdout (tempfile paths, git
  hashes, timestamps).
• One pattern in run-snippets that matches the require '...autoload.php'; line in the snippet's PHP source to inject the
  local-prelude polyfill.

These operate on plain strings, not HTML, so they're not what the "no
regex over HTML" rule was about.

Test plan

• Verify docs snippets workflow passes (87/87).
• Deploy docs to GitHub Pages runs cleanly on push to trunk.
• Local preview: bash bin/build-docs-bundle.sh && php bin/serve-docs.php — http://localhost:8787 renders all reference pages
  with snippets.
• php bin/run-snippets.php --update (no-op, no drift) leaves all
  READMEs untouched.

Summary

The toolkit now documents itself using only its own runtime and its
own structured-data parsers. No Python in CI; no hand-rolled regex over
markdown or HTML.

What changed

Parsers

Behavioural parity

• 87/87 snippets match their captured stdout. The PHP normalizer
  mirrors the Python regex set 1:1, so existing expected-output blocks
  stay valid.
• docs/reference/*.html render correctly: 9 <php-snippet> + 9
  fallback + 9 expected-output triples on html.html, 4 pitfall callouts
  (the bold-lead pattern is preserved), see-also list intact.
• --update verified end-to-end:
• When an expected-output block has drifted, the rewritten content is
  byte-for-byte the original.
• When no expected-output exists for a snippet, --update inserts a
  fresh block in the right place; resulting README is byte-identical to
  one with the block authored manually.

Frontmatter format change: see_also is a proper YAML list

# Before (repeated keys — not standard YAML)
see_also: a | A | reason
see_also: b | B | reason

# After
see_also:
  - a | A | reason
  - b | B | reason

Webuni\FrontMatter\FrontMatter correctly types it as a sequence; any
frontmatter-aware tool reading the README sees the same shape. All 18
component READMEs migrated.

Workflows simplified

• snippet-tests.yml drops the actions/setup-python step.
• docs.yml swaps python3 bin/build-reference.py for php bin/build-reference.php.

Remaining preg_* calls (all on plain text, not HTML)

• slugify() — heading text → URL-safe slug.
• normalize() — scrubs noise from snippet stdout (tempfile paths, git
  hashes, timestamps).
• One pattern in run-snippets that matches the require '...autoload.php'; line in the snippet's PHP source to inject the
  local-prelude polyfill.

These operate on plain strings, not HTML, so they're not what the "no
regex over HTML" rule was about.

Test plan

• Verify docs snippets workflow passes (87/87).
• Deploy docs to GitHub Pages runs cleanly on push to trunk.
• Local preview: bash bin/build-docs-bundle.sh && php bin/serve-docs.php — http://localhost:8787 renders all reference pages
  with snippets.
• php bin/run-snippets.php --update (no-op, no drift) leaves all
  READMEs untouched.