Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 0 additions & 63 deletions .github/workflows/2026.yml

This file was deleted.

24 changes: 24 additions & 0 deletions .github/workflows/build-fr-zensical.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
name: Deploy CR26 to GitHub Pages

on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

jobs:
site:
uses: FedRAMP/shared-workflows/.github/workflows/build-fr-zensical.yml@v1
with:
# Requires the shared workflow's deploy input before this caller is merged.
deploy: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
use-bun: true
submodules: true
venv-path: tools/.venv
build-script: tools/scripts/build-ci.sh
5 changes: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ bunx tsc -p tsconfig.json --noEmit
- `bun run check`: run tests, TypeScript checks, and non-failing content style warnings.
- `bun run build`: regenerate `src/` and build `html/`.
- `bun run sync`: update the `tools/rules` submodule.
- CI intentionally runs `bun run sync` to build the latest `FedRAMP/rules` `main`, rather than the submodule revision recorded in this repository. Preserve this behavior; repeat builds of a site commit may consume newer rules.
- `bunx tsc -p tsconfig.json --noEmit`: type-check the Bun and Node scripts.

Generic read-only commands such as `git`, `rg`, and `sed` may run from the repository root.
Expand Down Expand Up @@ -104,3 +105,7 @@ Generated definitions must remain one alphabetical list of `##` term headings. D
When the user asks for a changelog, branch changelog, public change summary, or summary of all changes on the current branch, use `$public-branch-changelog` from `.agents/skills/public-branch-changelog/SKILL.md`.

This workflow is mandatory for those requests. Agents without skill support should read that file and follow it directly.

## Source-derived tests

Tests comparing generated output with rules or manual content must read the current local source files and derive expected content from them. Do not freeze production wording, identifiers, counts, dates, or destinations in assertions. Keep source expectations independent of generator view models; use small synthetic fixtures with explicit expected results for behavior and edge cases. NIST expectations come from the vendored OSCAL catalog, not copied control facts.
24 changes: 24 additions & 0 deletions tools/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -531,3 +531,27 @@ Other generated FRR, KSI, CTL, and full control reference pages receive
Definitions, ruleset indexes, summaries, deadlines, and manual pages are unaffected.
Navigation changes update this selection on the next generation, including during
`bun run dev`. Omitting `generated.search` disables this policy.

## Testing source fidelity

`test-support/sources.ts` (under `scripts/`) takes one in-memory snapshot per test
process of the local rules JSON, configuration, navigation, vendored OSCAL catalog,
and manual content. Fixture loaders return clones; tests never sync or modify the
source files. Restart the test process after changing sources.

Source-contract checks derive record membership and text from those inputs and
mapping filters, independently of `collectArtifacts` view models. They compare
Markdown and rendered HTML, including definitions, rules, indicators, controls,
baselines, deadlines, summary tables, and trigrams. The expected output inventory
comes from source and configuration. Manual copy checks enumerate `content/` first
so missing copies fail, and compare assets byte-for-byte. HTML checks account for
rendering syntax while retaining source wording and punctuation.

Synthetic fixtures remain appropriate for formatting, filtering, escaping and
failure behavior. Do not add fixed production examples or snapshots to these
checks. `source-contract.test.ts` deliberately corrupts outputs to test that the
comparison helpers detect drift. The build integration test explicitly invokes
the full build before inspecting output; fixture builds use temporary directories.
Run `bun run check` for the full gate. The configured Zensical build may need
network access for fonts; a font-download failure is a build-environment failure,
not a reason to weaken content assertions.
1 change: 1 addition & 0 deletions tools/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
"sync": "./scripts/sync-rules-submodule.sh",
"check": "bun run ./scripts/check.ts",
"check:style": "bun run ./scripts/style-warnings.ts",
"check:site": "bun run ./scripts/verify-site.ts",
"test": "bun test"
},
"devDependencies": {
Expand Down
31 changes: 31 additions & 0 deletions tools/scripts/build-ci.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
#!/usr/bin/env bash
set -euo pipefail

# Resolve tools/ regardless of the caller's working directory.
cd "$(dirname "${BASH_SOURCE[0]}")/.."

echo "::group::Install Bun dependencies"
bun install --frozen-lockfile
echo "::endgroup::"

echo "::group::Sync rules"
# CI deliberately builds the latest upstream main, not the recorded gitlink.
bun run sync
echo "::endgroup::"

echo "::group::Clear previous build output"

# Start without old HTML that could mask missing build output.
rm -rf ../html

echo "::endgroup::"

echo "::group::Build site and run tests and checks"
# The integration test in bun run check runs the full build and verifies its
# output. Keep that tested artifact for upload instead of rebuilding afterward.
bun run check
echo "::endgroup::"

echo "::group::Verify generated output"
bun run check:site
echo "::endgroup::"
Loading