test(e2e): migrate docs validation to Vitest

[cv]

Summary

Migrates the docs-validation E2E check from the legacy test/e2e shell wrapper into a Vitest live scenario. The nightly docs-validation job now builds the checkout CLI, runs the scenario directly through e2e-scenarios-live, and uploads fixture artifacts.

Related Issue

Refs #4941

Changes

• Add test/e2e-scenario/live/docs-validation.test.ts with CLI docs parity checks and local-only link validation.
• Replace test/e2e/test-docs-validation.sh in nightly-e2e.yaml with direct Vitest execution and artifact upload.
• Extend test/e2e-script-workflow.test.ts to lock the new workflow contract and keep the retired shell path out.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: bb99a1e9-d794-483c-902f-352068d29cfa

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/e2e-migrate-docs-validation

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: docs-validation-e2e
Optional E2E: None

Dispatch hint: docs-validation-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/codex/e2e-simplify-migration-tracking
Head: HEAD
Confidence: high

Required E2E

• docs-validation-e2e (low): Directly validates the changed nightly E2E job and the newly migrated Vitest scenario replacing test/e2e/test-docs-validation.sh.

Optional E2E

• None.

New E2E recommendations

• None.

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: docs-validation-e2e

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: e2e-scenarios-all
Optional scenario E2E: None

Dispatch required scenario E2E:

• gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref>

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/codex/e2e-simplify-migration-tracking
Head: HEAD
Confidence: high

Required scenario E2E

• e2e-scenarios-all: The PR adds a new free-standing live Vitest scenario test under test/e2e-scenario/live. It is scenario-E2E runtime surface, but it is not a live-supported typed registry scenario ID in the trusted checkout, so it cannot be safely targeted by ID; run the canonical scenario fan-out.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref>

Optional scenario E2E

• None.

Relevant changed files

• test/e2e-scenario/live/docs-validation.test.ts

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 2 worth checking, 0 nice ideas
Since last review: 0 prior items resolved, 2 still apply, 0 new items found

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• Source-of-truth review needed: .coderabbit.yaml docs-validation path-specific guidance: The advisor marked localized patch analysis as missing.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: .coderabbit.yaml has path: "test/e2e/test-docs-validation.sh" and path: "docs/reference/commands.md" while the PR deletes the shell wrapper and the checker uses docs/reference/commands.mdx.
• Update stale docs-validation review guidance (.coderabbit.yaml:670): The PR deletes the legacy docs-validation shell wrapper and moves the active scenario to Vitest, but path-specific review guidance still targets the deleted wrapper and the obsolete commands.md path. That leaves future review/advisor guidance out of sync with the new source of truth.
  • Recommendation: Retarget the docs-validation guidance to test/e2e-scenario/live/docs-validation.test.ts and docs/reference/commands.mdx, or remove the deleted-file entry. Consider adding a static config check that path-specific guidance entries only reference existing files.
  • Evidence: .coderabbit.yaml still contains path: "test/e2e/test-docs-validation.sh" at line 670 and path: "docs/reference/commands.md" at line 686, while this PR deletes test/e2e/test-docs-validation.sh and the active docs checker reads docs/reference/commands.mdx.

🌱 Nice ideas

• None.

Consider writing more tests for

• **Runtime validation** — Assert docs-validation-e2e.permissions.contents remains read in test/e2e-script-workflow.test.ts.. Static workflow contract coverage is good, but the changed surface is a GitHub Actions job that now depends on setup-node, npm ci --ignore-scripts, Vitest project gating, fixture artifact creation, and the check-docs.sh runtime path.
• **Runtime validation** — Validate the selective docs-validation-e2e path creates scenario.json and shell probe artifacts under e2e-artifacts/vitest/docs-validation/.. Static workflow contract coverage is good, but the changed surface is a GitHub Actions job that now depends on setup-node, npm ci --ignore-scripts, Vitest project gating, fixture artifact creation, and the check-docs.sh runtime path.
• **Runtime validation** — Validate the runtime path executes both check-docs.sh --only-cli and check-docs.sh --only-links --local-only through the Vitest fixture.. Static workflow contract coverage is good, but the changed surface is a GitHub Actions job that now depends on setup-node, npm ci --ignore-scripts, Vitest project gating, fixture artifact creation, and the check-docs.sh runtime path.
• **Runtime validation** — Add a static config check that path-specific review guidance entries in .coderabbit.yaml only reference files that exist.. Static workflow contract coverage is good, but the changed surface is a GitHub Actions job that now depends on setup-node, npm ci --ignore-scripts, Vitest project gating, fixture artifact creation, and the check-docs.sh runtime path.
• **Acceptance clause:** Refs Adopt Vitest fixtures as the E2E scenario execution model #4941 — add test evidence or identify existing coverage. The PR body references Adopt Vitest fixtures as the E2E scenario execution model #4941, but deterministic linked issue context was empty, so no issue body or comments were available to extract acceptance clauses.
• **.coderabbit.yaml docs-validation path-specific guidance** — No regression test currently verifies that path-specific review guidance entries reference existing files.. .coderabbit.yaml has path: "test/e2e/test-docs-validation.sh" and path: "docs/reference/commands.md" while the PR deletes the shell wrapper and the checker uses docs/reference/commands.mdx.

Since last review details

Current findings:

• Source-of-truth review needed: .coderabbit.yaml docs-validation path-specific guidance: The advisor marked localized patch analysis as missing.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: .coderabbit.yaml has path: "test/e2e/test-docs-validation.sh" and path: "docs/reference/commands.md" while the PR deletes the shell wrapper and the checker uses docs/reference/commands.mdx.
• Update stale docs-validation review guidance (.coderabbit.yaml:670): The PR deletes the legacy docs-validation shell wrapper and moves the active scenario to Vitest, but path-specific review guidance still targets the deleted wrapper and the obsolete commands.md path. That leaves future review/advisor guidance out of sync with the new source of truth.
  • Recommendation: Retarget the docs-validation guidance to test/e2e-scenario/live/docs-validation.test.ts and docs/reference/commands.mdx, or remove the deleted-file entry. Consider adding a static config check that path-specific guidance entries only reference existing files.
  • Evidence: .coderabbit.yaml still contains path: "test/e2e/test-docs-validation.sh" at line 670 and path: "docs/reference/commands.md" at line 686, while this PR deletes test/e2e/test-docs-validation.sh and the active docs checker reads docs/reference/commands.mdx.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

[wscurran]

✨
Related open issues:

• #4941 Adopt Vitest fixtures as the E2E scenario execution model

[cv]

Closing as superseded by #5185. The docs-validation Vitest coverage and nightly lane update have already landed there, with the current migration policy of keeping the legacy shell file present for now and deferring deletion. #5098 now records test/e2e/test-docs-validation.sh as converted by #5185. Any remaining useful idea should come back as a fresh, focused follow-up against current main.