fix: harden TypeScript and Go documentation validation

[rinceyuan]

Problems

The TypeScript documentation validator catches compiler failures but only records diagnostics associated with extracted example files. A compiler startup failure, global diagnostic, or error confined to an imported file outside the examples can therefore result in every example being reported as valid and exit 0.

On Windows, directly executing nodejs/node_modules/.bin/tsc produces ENOENT. The unchanged validator reported 201 files passed even with a deliberate TS2322 example. Bypassing only the launcher with Node also showed a real compiler exit 2 / TS2688 incorrectly reported as success.

The Go validator writes an unquoted local replacement path into go.mod. A checkout path containing spaces is split into separate tokens and rejected by the Go module parser. This is another portability failure in the same documentation validation tool.

Changes

• Launch the Node SDK TypeScript compiler entry point through process.execPath, without a shell, and disable pretty diagnostics.
• Normalize diagnostic paths, retain document locations, preserve stdout/stderr, and reject failed compilations that produce no failing example result.
• Quote and escape the Go replacement directory when generating go.mod.
• Add six isolated regression tests using the real TypeScript compiler and Go module parser. Run them in the existing Node and Go documentation CI steps. No dependency changes.

Validation

• Windows: Node 24.14.1 and Go 1.24.6; npm --prefix scripts/docs-validation test: 6 passed, 0 skipped.
• WSL Ubuntu 22.04: Node 22.20.0 and Go 1.24.6, fresh npm ci: 6 passed, 0 skipped.
• Before the TypeScript fix, its five tests on Windows gave 1 pass / 4 failures because error scenarios incorrectly exited 0.
• Before the Go quoting fix, the five TypeScript tests passed and the new Go regression failed when go mod edit -json parsed the actual generated go.mod. Afterward it parses and the replacement path round-trips exactly.
• Coverage: valid TypeScript in a path containing spaces, TS2322 with document location, global TS2688, missing compiler, errors outside extracted examples, and a generated Go replacement path containing spaces (including Windows backslashes).
• git diff --check passed.

Limits

The Go regression checks module generation and parsing, not compilation of the full Go documentation corpus. It skips locally if Go is absent; Go CI supplies Go.

The full npm run docs:nodejs command still encounters the existing local missing Node type definitions (TS2688). It now exits 1 and prints that diagnostic rather than falsely reporting all examples valid. I am not claiming the full documentation corpus compiles on this machine.

[Copilot]

🟢 Approval recommended

The implementation addresses the false-success paths with focused cross-platform regression coverage.

0 open findings

What changed in this PR

Ensures TypeScript documentation validation reliably fails for compiler startup, global, and external-file errors across platforms.

Changes:

• Invokes TypeScript through Node and normalizes diagnostic paths.
• Propagates compilation failures not tied to extracted examples.
• Adds regression tests and runs them in documentation CI.

File	Description
scripts/​docs-validation/​validate.ts	Improves compiler execution and failure handling.
scripts/​docs-validation/​validate.test.mjs	Adds five real-compiler regression tests.
scripts/​docs-validation/​package.json	Adds the test command.
.github/​workflows/​sdk-nodejs.yml	Runs validator tests in Linux CI.

🧠 Review effort: Balanced

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.