fix(doc-tests): restore Fastify examples with per-example auto-optimization

[proggeramlug]

Restore the three Fastify documentation examples excluded from the host doc-test CI run. Each example declares // requires: auto-optimize; the harness removes PERRY_NO_AUTO_OPTIMIZE only from that example's compiler process, allowing its specialized Fastify libraries to be built. Ordinary examples retain the prebuilt-library setting. The examples keep their existing run: false behavior and participate in the normal pass/fail report, including compilation failures.

Remove the exclusions from both macOS and Windows workflow commands, document the banner, and reject unknown requirements so a typo cannot silently defeat it. The shared compiler-environment handling also applies to cross-compilation.

Closes #8475. No version bump.

Validation:

• All three examples reproduce the original no-auto compiler error when compiled directly with the parent override.
• All three actual examples compile and link through the updated harness on macOS, with the parent override still set. The specialized archive stamps include external-fastify-pump.
• 12 unit tests and 2 subprocess tests pass. The new subprocess tests fail on the baseline; they verify both preceding/following ordinary examples retain their environment and required compilation failures fail the harness.
• All 62 script lint gates, formatting, all-targets Rust check with -D warnings, and crate Clippy pass. Clippy reports two unchanged warnings (lint.rs sorting and the existing eight-argument run_one).

Local builds used release codegen-units=16 and LTO disabled through environment overrides. No source build profile changed. These examples are compile-only because they need servers or external services; Windows execution remains for CI.

Summary by CodeRabbit

• Documentation

  • Documented how examples requiring auto-optimization are identified and tested.
  • Clarified compile-only examples and handling of unknown requirements.

• Bug Fixes

  • Restored coverage for three Fastify documentation examples across supported platforms.
  • Ensured required examples are compiled with specialized runtime libraries and included in pass/fail reporting.
  • Compilation failures in required examples now correctly fail doc-test runs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: f931d28b-6a48-4e28-9c8d-7a66b8489a41

📥 Commits

Reviewing files that changed from the base of the PR and between d36a1af and 9785639.

📒 Files selected for processing (9)

• .github/workflows/test.yml
• changelog.d/9820-fastify-doc-test-coverage.md
• crates/perry-doc-tests/src/main.rs
• crates/perry-doc-tests/src/tests.rs
• crates/perry-doc-tests/tests/compiler_environment.rs
• docs/examples/README.md
• docs/examples/getting-started/npm_packages.ts
• docs/examples/stdlib/http/fastify_json.ts
• docs/examples/stdlib/overview/snippets.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The doc-test harness now parses requires: auto-optimize, removes the disabling compiler environment variable for marked examples, and rejects unknown requirements. Three Fastify examples are restored to macOS and Windows CI coverage with tests and documentation.

Changes

Doc-test auto-optimize support

Layer / File(s)	Summary
Parse requirements and configure compilation crates/perry-doc-tests/src/main.rs	The harness stores and parses requires: auto-optimize, rejects unknown requirements, and removes PERRY_NO_AUTO_OPTIMIZE for required examples in host and cross-compile paths.
Validate requirement handling and reporting crates/perry-doc-tests/src/tests.rs, crates/perry-doc-tests/tests/compiler_environment.rs	Tests verify Fastify banners, unknown-requirement errors, compiler environment isolation, execution order, and compile failure reporting.
Enable and document Fastify coverage .github/workflows/test.yml, docs/examples/*, docs/examples/README.md, changelog.d/9820-fastify-doc-test-coverage.md	The three Fastify examples declare the requirement, macOS and Windows exclusions are removed, and the behavior is documented.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 97856

This restores Fastify documentation examples to CI while keeping ordinary examples on prebuilt libraries. The restored examples compile without running servers, and no current merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant DocExample as Doc example
  participant DocTests as doc-tests
  participant Perry as perry compiler
  DocExample->>DocTests: declares requires: auto-optimize
  DocTests->>Perry: compile without PERRY_NO_AUTO_OPTIMIZE
  Perry-->>DocTests: compilation result

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 6 files. (3 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR satisfies issue #8475. It restores coverage for all three Fastify examples, adds per-example auto-optimization requirements, preserves ordinary-example behavior, removes workflow exclusions, re…
Out of Scope Changes check	✅ Passed	The changes are within scope of issue #8475. The harness updates, workflow changes, documentation, example directives, changelog entry, and related tests directly support restoring Fastify doc-test co…
Title check	✅ Passed	The title clearly and concisely identifies the primary change: restoring Fastify documentation tests with per-example auto-optimization.
Description check	✅ Passed	The description provides the change summary, implementation details, related issue, validation results, and scope information. It does not reproduce the template headings or checklist, but it covers t…

Full details: Docstring Coverage

Explanation

Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 6 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[proggeramlug]

Landed on main via merge train #9866 (rebase-merged, so your commits keep their authorship). Thanks!