ci(docs): scope the node schema check to the PR's diff, and make it blocking

[krishhgg]

Split out of #1970 so the bash gets reviewed as bash, separately from 600 lines of prose. Adopts the suggestion from the fix/docs review.

The problem

The node README checker ran --all across the corpus. 109 of 124 nodes fail the schema today, so the job was red on every PR from the day it was added — which is why it was marked advisory and kept off the merge path.

That defused the immediate damage but left a worse one: a check that has always failed is a check nobody reads, and the day it fails for a new reason looks identical to the two hundred days before it. The genuinely interesting failures were going to be buried under structural noise like unknown heading '## Modes' — move under ## Notes.

The change

Validate only the nodes whose files the PR actually touched.

• Green by default, so red means this PR broke something
• Blocking immediately — no waiting on a 109-node cleanup before the check protects anything
• The backlog drains on its own. Touching a node obliges you to bring its README along, and it can never grow, because a new or edited node is validated the moment it lands.

services*.json counts as a trigger alongside README.md. The metadata decides which sections are required or forbidden, so a metadata-only change can invalidate a README nobody edited. That also closes a gap where the docs path filter watched only READMEs.

--all keeps a home in a new informational job that writes pass/fail counts to the run summary — a large number is a trend line there rather than a merge blocker. Retire that job when the count reaches zero; the scoped gate keeps it there.

Cross-check

Checked against the existing docs:check gate so two checks cannot disagree about what a good README is. docs:check verifies exported client package READMEs match their docs/ sources — export drift, not document structure. No overlap.

Two bugs CodeRabbit caught in the first version

Both reproduced before fixing.

Under set -euo pipefail, grep exits 1 when nothing matches, so a PR touching no node files died on the command substitution before reaching the check meant to report a clean skip. On a blocking job that would have blocked unrelated PRs outright. The -d test in the trailing loop had the same shape for a deleted node.

grep -c already prints 0 when it matches nothing and exits 1 as well, so || echo 0 emitted a second zero and the summary rendered 0 0.

Scope

Touches .github/workflows/docs-schemas.yml only — a file that triggers exclusively on fix/docs, with no workflow_dispatch or schedule. ci.yml, the shared pipeline, remains a zero-line diff against develop, and nothing on develop references these validators.

Verification

Run under bash rather than the zsh it was written in, since zsh does not word-split unquoted variables and hid a real difference:

• real diff → resolves 8 nodes, all pass, exit 0
• diff with no node files → reaches the skip path, exit 0
• an unmigrated node in the set → exit 1, PR goes red
• counts render as a single 0

Both jobs ran green on #1970 before the split.

🤖 Generated with Claude Code

Summary by CodeRabbit

• CI Improvements
  • Schema validation now runs only for changed, existing node directories.
  • Validation failures now block pull requests when relevant schema files change.
  • Checks safely handle deleted nodes, empty changes, and pull requests without relevant updates.
  • Added an informational full-node validation sweep with pass/fail counts in the workflow summary.

[github-actions]

🤖 Internal: Discord sync marker

Auto-managed by the Discord notification workflow. Stores the linked Discord message ID and forum thread ID. Do not edit or delete.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 75023846-8660-41c4-96e2-922053275d95

📥 Commits

Reviewing files that changed from the base of the PR and between 6e369ed and ab56531.

📒 Files selected for processing (1)

• .github/workflows/docs-schemas.yml

---

📝 Walkthrough

Walkthrough

The workflow now blocks on schema errors in changed node directories. A separate informational job validates the full node corpus and reports passing and failing totals.

Changes

Schema validation

Layer / File(s)	Summary
Changed-node validation .github/workflows/docs-schemas.yml	The schemas job fetches full history, selects changed existing node directories, skips empty or deleted candidates, and runs blocking validation.
Corpus sweep .github/workflows/docs-schemas.yml	The corpus job validates all nodes with failure tolerance and writes passing and failing counts to the GitHub step summary.

Estimated code review effort: 2 (Simple) | ~15 minutes

Merge Risk: ⚪ Minimal · up to ab565

This localized CI workflow change is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

Possibly related PRs

• rocketride-org/rocketride-server#1970: Both update .github/workflows/docs-schemas.yml with changed-node and tolerant corpus validation.
• rocketride-org/rocketride-server#1332: Both update GitHub Actions behavior based on node README.md changes.

Suggested labels: docs, module:nodes

Suggested reviewers: kwit75

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main changes: diff-scoped node schema validation and blocking CI enforcement.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ci/scoped-schema-gate

---

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.}