feat(docs): validate network commands and environment variables in docs

[Senatormike001]

Overview

Adds an automated validator for the Stellar network guides so documented network commands and environment variables can no longer drift from the deployment registry.

scripts/check-network-docs.ts discovers every network guide, extracts documented environment variables, connection-table values and shell commands, then checks them against a canonical registry of Stellar passphrases and endpoints. Commands are only parsed (bash -n) and never executed, so no real transaction can be sent from CI.

Related Issue

Closes #158

Changes

Network documentation validator

• [ADD] scripts/lib/network-docs.ts

  • NETWORK_REGISTRY — canonical passphrase, Horizon, Soroban RPC and Friendbot values for testnet, futurenet and mainnet, plus KNOWN_ENV_VARS.
  • extractSection() — pulls KEY=value assignments, non-assignment commands and | Property | Value | connection-table rows out of fenced bash/sh/shell blocks. Multi-line commands are kept as one logical command when they end in \ or leave a quote open, so a curl -d '{ ... }' payload is not split.
  • validateEnvNames() — errors on malformed names, warns on well-formed STELLAR_* names outside the core registry.
  • validateAgainstRegistry() — resolves the network declared by the surrounding block and compares STELLAR_NETWORK_PASSPHRASE, STELLAR_HORIZON_URL and STELLAR_RPC_URL against it; also validates passphrases quoted in connection tables. Placeholders (CPLACEHOLDER_*, <YOUR_API_KEY>) are skipped.
  • normalisePlaceholders() + checkCommandSyntax() — neutralises documented placeholders so <API_KEY> is not mistaken for a shell redirection, then syntax-checks each command through an injected checker.
  • findConflicts() — reports the same variable documented with different values, scoped per network so testnet and mainnet guides never collide.
  • findStaleStamps() — flags <!-- Last verified: ... --> stamps older than 120 days.
  • looksLikeNetworkDoc(), formatFinding(), summarise() — discovery and reporting helpers.

• [ADD] scripts/check-network-docs.ts

  • Recursive MDX/MD discovery (skipping .git, node_modules, .agents, .claude, assets).
  • bashSyntaxCheck() runs bash -n -c — parse only, never execution.
  • Prints every finding and exits non-zero only when errors are found.

• [ADD] scripts/tests/network-docs.test.ts

  • 19 node:test cases covering placeholder detection, extraction (including the multi-line quoted-payload case), name validation, registry mismatches, placeholder tolerance, unknown networks, conflict scoping, syntax-check wiring and stale stamps.

• [MODIFY] package.json

  • Adds check:network-docs and test:network-docs; the existing test script now also runs the network-docs check.

• [MODIFY] .github/workflows/snippets.yml

  • Adds "Check network docs" and "Unit-test the network docs checker" steps to the existing snippet job.

Verification Results

$ pnpm run check:network-docs

WARNING guides/stellar-mainnet-deployment.mdx:137 [ENV_NAME_UNRECOGNISED] "STELLAR_OPERATOR_SECRET" is not a core registry variable — confirm it is intentional.
WARNING guides/stellar-mainnet-deployment.mdx:228 [ENV_NAME_UNRECOGNISED] "STELLAR_RPC_URL_PRIMARY" is not a core registry variable — confirm it is intentional.
WARNING guides/stellar-mainnet-deployment.mdx:229 [ENV_NAME_UNRECOGNISED] "STELLAR_RPC_URL_FALLBACK" is not a core registry variable — confirm it is intentional.
INFO    guides/stellar-mainnet-deployment.mdx:159 [NETWORK_UNDECLARED] Cannot verify STELLAR_RPC_URL — the surrounding block does not set STELLAR_NETWORK.
INFO    guides/stellar-mainnet-deployment.mdx:160 [NETWORK_UNDECLARED] Cannot verify STELLAR_HORIZON_URL — the surrounding block does not set STELLAR_NETWORK.
INFO    guides/stellar-mainnet-deployment.mdx:161 [NETWORK_UNDECLARED] Cannot verify STELLAR_NETWORK_PASSPHRASE — the surrounding block does not set STELLAR_NETWORK.

Network docs scanned: 5
Environment variables validated: 21
Commands syntax-checked (not executed): 21
Findings: 0 error(s), 3 warning(s), 3 info

$ pnpm run test:network-docs
ℹ tests 19
ℹ pass 19
ℹ fail 0

The checker was run against the current develop tree of this repository and passes with zero errors, so it is safe to enable in CI. tsc --noEmit --strict is clean for all three new files.

Acceptance Criteria	Status
Extract documented environment variables and validate their names	✅ extractSection() + validateEnvNames() — 21 variables validated across 5 guides
Check network URLs and passphrases against the deployment registry	✅ validateAgainstRegistry() against NETWORK_REGISTRY, including connection tables
Run safe command syntax checks without sending real transactions	✅ bash -n parse-only over 21 commands; placeholders normalised first
Report stale or conflicting values	✅ findConflicts() (per network) + findStaleStamps() (120-day limit)

[drips-wave]

@Senatormike001 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[truthixify]

The mainnet deployment URL and passphrase block is marked NETWORK_UNDECLARED and only logged as info, so its values are never checked. Please infer the network from the guide or require STELLAR_NETWORK and fail when required values cannot be validated.

[truthixify]

The mainnet deployment URL and passphrase block is marked NETWORK_UNDECLARED and only logged as info, so its values are never checked. Please infer the network from the guide or require STELLAR_NETWORK and fail when required values cannot be validated.