Add worked examples, skeleton templates, and validator rule registry#9
Merged
Merged
Conversation
The validator failed at import time because no-dialog-apis.ts imported a non-existent helper (lineFromOffset, ctx.lineStarts) and several other rule files were stubs that imported the same missing symbol. Rewrite the broken rule against the existing parser API, delete the five unimplemented stubs (aria-landmarks, contrast-minimum, no-empty-elements, no-inline-styles-except-root, responsive-images) so they can't silently regress the test run, and implement three concrete rules that the user-facing docs promised: lang-attribute (error, Rule 13), focus-visible (warning, Rule 14), and print-media-query (warning, Rule 7). Introduce src/rule-registry.ts as the single source of truth for which rules are active. The CLI entry imports ALL_RULES from there, so README claims and runtime behavior can no longer drift. Extend the test suite (10 → 12 tests) with negative fixtures for the new rules, and update valid.html so it satisfies the now-stricter rule set (adds :focus-visible and @media print blocks). The dialog-apis fixture is rewritten to put alert/prompt/confirm calls in a script block so the test asserts the rule fires on exactly three call sites, not on the inline handlers that an unrelated rule would also catch. bloom-validator/README.md is rewritten to list the 10 active rules, the security-hardening sub-rules, and a "Planned (not yet enforced)" list so removed stubs are tracked as roadmap items rather than disappearing silently.
Rich templates (annotated-pr-review, exploration-code-approaches, incident-timeline, status-report) shipped with stray hex literals outside :root, no <main> landmark, and no focus/print styles — every one failed bloom-validator. Promote each stray color into a :root token (--sand, --sand-deep, --diff-del, --diff-add, --code-fg, --code-fg-muted), wrap their body content in <main>, and add :focus-visible + @media print blocks so each artifact prints cleanly and announces focus state. The ten thin 20-line templates (accessibility-report, api-documentation, architecture-decision, dependency-audit, design-review, migration-plan, monthly-review, onboarding-guide, sprint-retro, weekly-digest) were indistinguishable from each other and contained literal "Generated: placeholder date" / "Template for X content" copy. Rewrite each as a clearly-labeled skeleton with a leading skeleton-purpose comment, data-template="<slot>" markers in place of placeholder strings, and a print media query so a user can tell at a glance that they are starter scaffolds, not production examples. Add examples/ with three fully worked artifacts that the README has been claiming exist: - pr-review-example.html — annotated PR review with real-shaped Go diffs, risk chips, file cards, comment bubbles, and a next-steps checklist - incident-report-example.html — INC-2026-0143 SEV-2 postmortem with timeline, root cause diff, impact table, and action items - design-system-example.html — living design-system reference with copyable color tokens, the full type scale, and a composed preview All 5 production templates, 10 skeletons, and 3 examples pass bloom-validator with zero issues.
README and docs/harness-setup.md previously led every harness section with
a marketplace install command — most of those listings are not live yet
("after submission", "after listing lands"). A first-time reader would
copy a command that fails before they ever discovered the manual install
buried as a fallback.
Flip the order. Every harness section now leads with the manual install,
which works today against the harness's current release. Speculative
marketplace commands move to a clearly labeled "Planned marketplace
install — not yet live" subsection. The README's file tree is regenerated
from the actual filesystem (removing names like design-system-reference.html,
animation-sandbox.html, triage-board.html, etc. that did not exist on disk),
the validator section lists the 10 rules that the registry actually loads,
and the construction-rules summary picks up the new rule 7 wording.
Add .github/workflows/ci.yml so every push and PR runs:
- the validator's own 12-test node:test suite
- bloom-validate over templates/*.html
- bloom-validate over templates/skeletons/*.html
- bloom-validate over examples/*.html
A green CI run is now a precondition for cutting a release.
Add docs/public-readiness.md with the truth/install/validation/demo/
out-of-box checklist this repo holds itself to before a public release,
and docs/release-checklist.md with the per-release process — version
bumps across the three version-bearing files, the audit script, the
release-branch flow, tagging, and rollback procedure.
A review-comment bubble in the PR review example used the literal word TODO
in user-facing text, which the public-readiness checklist explicitly bans
("No template, skeleton, or example contains the strings Lorem, placeholder
date, TODO ..."). The release-checklist grep would have flagged this on
the next release attempt.
Replace the meta phrasing with a concrete review note that fits the
example's narrative: the second test case asserts only the happy path
and needs the cache-expiry branch added before merge.
grep -RIn -E '\b(Lorem|placeholder date|TODO|Template for)' templates/
examples/ is now clean. Validator still reports zero issues.
The previous invocation — node bloom-validator/src/index.ts templates/*.html
templates/skeletons/*.html examples/*.html — relied on shell glob expansion,
which silently fails on PowerShell and CMD. Windows contributors would see
the validator look for a literal file named templates/*.html and exit 2.
Add bloom-validator/scripts/validate-all.mjs that:
- resolves the file list in Node via readdirSync over a fixed set of
artifact directories (templates, templates/skeletons, examples)
- derives the validator path from import.meta.url, so it works whether
invoked via npm run validate-all (cwd = bloom-validator) or directly
as node bloom-validator/scripts/validate-all.mjs from any cwd
- propagates the validator's exit code
Wire it up as `npm run validate-all` and use it everywhere the three-line
shell invocation appeared:
- .github/workflows/ci.yml replaces three separate steps with one
- README.md "Validation" + "Contributing" point to the new command
- docs/public-readiness.md audit script uses it
- docs/release-checklist.md audit collapses to two lines
- bloom-validator/README.md documents npm test and npm run validate-all
as the canonical commands
Verified end-to-end: npm test still 12/12, npm run validate-all reports
18 clean artifacts and exits 0.
SunnyDevendranadh
added a commit
that referenced
this pull request
May 19, 2026
Merge pull request #9 from SunnyDevendranadh/claude/bloom-public-read…
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This release adds production-ready examples, starter templates, and refactors the validator to use a centralized rule registry.
Summary
Bloom now ships with three worked examples (
pr-review-example.html,incident-report-example.html,design-system-example.html) demonstrating real-world artifact patterns. The validator has been refactored to use a rule registry for cleaner rule management, and 10 skeleton templates provide starting points for common document types.Key changes
Examples & documentation
examples/showing PR reviews, incident reports, and design systems with interactive componentsdocs/release-checklist.mdanddocs/public-readiness.mdto formalize release and quality standardsREADME.mdanddocs/harness-setup.mdto clarify that manual installs are the primary path (marketplace installs marked as "Planned")ci.yml) to validate templates and run validator testsValidator refactoring
bloom-validator/src/rule-registry.tsto centralize rule imports and exportslangAttribute,focusVisible,noDialogApis, etc.) and addedidfield to each rulelangAttributerule (rule-13) to validate<html lang>attribute presence and validityfocusVisiblerule (rule-14) with regex-based detection of interactive elements and focus stylesaria-landmarks,contrast-minimum,no-empty-elements,no-inline-styles-except-root,responsive-images)Templates
templates/totemplates/skeletons/(accessibility-report, api-documentation, architecture-decision, dependency-audit, design-review, migration-plan, monthly-review, onboarding-guide, sprint-retro, weekly-digest)annotated-pr-review.htmland other templates with additional CSS variables (--sand,--sand-deep,--code-fg,--code-fg-muted,--diff-del,--diff-add) for richer stylingTest fixtures
invalid-lang.htmlandinvalid-print-focus.htmltest fixturesinvalid-dialog-apis.htmlfixture with improved formatting and structurevalid.htmlfixture to include focus-visible and print media query stylesNotable implementation details