Check capability atoms reference in CI

[jkwak-work]

Motivation

docs/user-guide/a3-02-reference-capability-atoms.md is generated from the
capability definitions under source/slang/*.capdef, but CI did not verify that
PRs changing capability definitions also refreshed the checked-in reference. A
stale generated reference could merge without being noticed until a reviewer
caught it manually.

Proposed solution

Add a CI job that mirrors the existing check-cmdline-ref pattern. The job
reuses the Linux release build artifact, runs slang-capability-generator with
the same .capdef input glob shape as the CMake build rule, writes the generated
document into a temporary location, and diffs it against
docs/user-guide/a3-02-reference-capability-atoms.md.

The CI filter also treats direct edits to generated reference documents as
test-worthy instead of skipping them as ordinary docs-only changes, so
hand-edited generated references still go through their regeneration checks.

Change summary

.github/workflows/ci.yml:36 keeps CI enabled when either
docs/command-line-slangc-reference.md or
docs/user-guide/a3-02-reference-capability-atoms.md is part of the PR diff,
even if the change would otherwise look docs-only.

.github/workflows/ci.yml:433 adds check-capability-atoms-ref, downloads the
slang-tests-linux-x86_64-gcc-release artifact, regenerates the capability atoms
reference, reports a unified diff on mismatch, and includes the job in the
aggregate check-ci gate.

.github/workflows/ci-slang-build-container.yml:164 stages
build/generators/${cmake_config}/bin/slang-capability-generator into the
uploaded test artifact and fails the producer job if that required generator is
missing.

docs/user-guide/a3-02-reference-capability-atoms.md:5 refreshes the checked-in
generated reference to match the current capability definitions.

Concepts and vocabulary

Capability atoms are the individual target, stage, version, extension, and
compound capability names documented in
docs/user-guide/a3-02-reference-capability-atoms.md.

The capability generator is the build tool that reads source/slang/*.capdef,
emits the compiler capability tables, and writes the generated capability atoms
reference when passed --doc.

Process report

The generated document already has a single source of truth:
source/slang/CMakeLists.txt invokes slang-capability-generator with
source/slang/*.capdef inputs and the --doc docs/user-guide/a3-02-reference-capability-atoms.md output. The new CI job uses
the same generator and .capdef glob, but redirects the generated document to
temp/docs/user-guide/a3-02-reference-capability-atoms.md so the repository copy
is left untouched during the check.

This follows the existing check-cmdline-ref shape instead of introducing a
separate build. check-cmdline-ref depends on build-linux-release-gcc-x86_64,
downloads slang-tests-linux-x86_64-gcc-release, regenerates a reference file,
and compares it with the checked-in document. check-capability-atoms-ref uses
the same dependency and artifact path, with the generator binary substituted for
slangc.

The artifact packaging change is required because CMake places generator
binaries under build/generators/${cmake_config}/bin, while the uploaded test
artifact previously copied top-level runtime binaries from
build/${cmake_config}/bin. Copying slang-capability-generator into the
artifact keeps the check tied to the release build that CI already produced and
avoids a redundant configure or build step. The copy now fails fast when the
generator is missing because the downstream check depends on that binary being
part of the artifact contract.

The filter exception is intentionally narrow. General docs-only PRs still skip
the expensive build and test jobs, but a PR that edits either generated
reference runs CI so the reference can be regenerated and compared against the
checked-in file.

[coderabbitai]

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 12e890b3-72a9-49b0-947f-b86e2d8b7639

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

📝 Walkthrough

Walkthrough

The workflows now stage slang-capability-generator, add a CI job that regenerates and diffs the capability atoms reference document, and update the reference document content.

Changes

Capability atoms CI validation

Layer / File(s)	Summary
Stage generator artifact .github/workflows/ci-slang-build-container.yml	Copies slang-capability-generator into the staged binary artifact from build/generators/${cmake_config}/bin/ after verifying the binary exists.
Validate capability atoms reference .github/workflows/ci.yml	Treats the capability-atoms doc as non-skippable, adds check-capability-atoms-ref to regenerate and compare it, and includes that job in check-ci needs.
Refresh capability atoms headings docs/user-guide/a3-02-reference-capability-atoms.md	Updates the top-level heading and rewrites the main targets, stages, versions, extensions, and early compound-capability sections.
Expand compound and other atoms docs/user-guide/a3-02-reference-capability-atoms.md	Updates additional compound-capability groupings, expands ray tracing and shader-execution-reordering entries, and extends the “Other” section with more capability atoms and aliases.

Suggested reviewers

• bmillsNV

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding CI checks for the capability atoms reference.
Description check	✅ Passed	The description accurately describes the CI and documentation sync changes in the pull request.
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.

---

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

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9fab7a72-54a4-481c-b042-9d4d3b7c5f23

📥 Commits

Reviewing files that changed from the base of the PR and between 9f51ba0 and 475122e.

📒 Files selected for processing (2)

• .github/workflows/ci-slang-build-container.yml
• .github/workflows/ci.yml

[jkwak-work]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.