docs: restructure README into purpose-built documents by aallan · Pull Request #407 · aallan/vera

aallan · 2026-03-28T08:47:07Z

Summary

Splits the 821-line README into four focused files, each with a single job:
- README.md (249 lines) — project overview, three canonical examples, getting started
- EXAMPLES.md — full 12-example language tour (contracts through LLM inference)
- DESIGN.md — technical decisions table (19 rows) and prior art (9 references)
- KNOWN_ISSUES.md — bugs and limitations tables, previously buried in README
Updates all CI infrastructure to match:
- New check_examples_doc.py script + pre-commit hook validates all vera blocks in EXAMPLES.md
- check_limitations_sync.py now reads Tier 1 from KNOWN_ISSUES.md instead of README.md
- fix-allowlists and limitations-sync hook triggers updated for new file names
- Hook count 21 → 22 (TESTING.md + CONTRIBUTING.md updated)
Fixes tests broken by the restructure:
- test_readme.py: vera block count 13 → 3 (examples moved to EXAMPLES.md); stale allowlist entry removed
- test_errors.py: _extract_readme_error_block() updated for new section heading ### Errors are instructions; README error block updated to include rationale text matching the canonical E001 diagnostic

Test plan

All 3091 tests pass (pytest tests/ -q)
All 22 pre-commit hooks pass
check_readme_examples.py — 3 vera blocks, all parse
check_examples_doc.py — 12 vera blocks, all parse
check_limitations_sync.py — 32 in KNOWN_ISSUES.md, consistent
check_doc_counts.py — counts consistent

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Added a comprehensive examples guide with runnable language walkthroughs.
- Added a design document and a known-issues/limitations reference.
- Simplified and condensed the README, replacing the long example with a concise safe-divide example.
- Updated contributing and testing docs to reflect new validations and hook count.
New Features
- Pre-commit now runs a new documentation validation that parses example code blocks.
Bug Fixes
- Validation now cross-checks limitations against the dedicated known-issues document.

Split the 821-line README into focused files: - README.md (249 lines): project overview, 3 examples, getting started - EXAMPLES.md: full 12-example language tour (contracts → inference) - DESIGN.md: technical decisions table and prior art - KNOWN_ISSUES.md: bugs and limitations tables (was inline in README) Update CI infrastructure: - New pre-commit hook: check_examples_doc.py validates EXAMPLES.md blocks - check_limitations_sync.py now reads from KNOWN_ISSUES.md (not README.md) - fix-allowlists hook triggers updated to include EXAMPLES.md - limitations-sync hook triggers updated to include KNOWN_ISSUES.md - Hook count 21 → 22 (updated in TESTING.md and CONTRIBUTING.md) Update tests: - test_readme.py: vera block count 13 → 3 (remaining examples in EXAMPLES.md) - test_errors.py: update _extract_readme_error_block() for new section heading - Remove stale allowlist entry pointing to old README line 736 Co-Authored-By: Claude <noreply@anthropic.invalid>

codecov · 2026-03-28T08:47:47Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.30%. Comparing base (c11b246) to head (57ee10e).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #407   +/-   ##
=======================================
  Coverage   90.30%   90.30%           
=======================================
  Files          49       49           
  Lines       19100    19100           
  Branches      220      220           
=======================================
  Hits        17248    17248           
  Misses       1848     1848           
  Partials        4        4

Flag	Coverage Δ
javascript	`50.58% <ø> (ø)`
python	`95.31% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

coderabbitai · 2026-03-28T08:48:40Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0d4417a7-1ce7-4650-a931-1fc88573ffa5

📥 Commits

Reviewing files that changed from the base of the PR and between ecb95f3 and 57ee10e.

📒 Files selected for processing (2)

CONTRIBUTING.md
TESTING.md

📝 Walkthrough

Walkthrough

Adds EXAMPLES.md, DESIGN.md, KNOWN_ISSUES.md and refactors README; introduces scripts/check_examples_doc.py and a pre-commit hook to validate vera fenced blocks in EXAMPLES.md; updates pre-commit configuration and limitations-checking to use KNOWN_ISSUES.md; adjusts tests and documentation counts.

Changes

Cohort / File(s)	Summary
Documentation files `README.md`, `EXAMPLES.md`, `DESIGN.md`, `KNOWN_ISSUES.md`	README substantially condensed and example function replaced (`clamp` → `safe_divide`); added `EXAMPLES.md` with runnable Vera feature walkthroughs; added `DESIGN.md` with technical decisions; added `KNOWN_ISSUES.md` as canonical limitations/bugs snapshot.
Pre-commit configuration `.pre-commit-config.yaml`	Updated `fix-allowlists` to include `EXAMPLES.md`; added `examples-doc` hook to run `scripts/check_examples_doc.py`; changed `limitations-sync` to reference `KNOWN_ISSUES.md` instead of `README.md`.
Validation scripts `scripts/check_examples_doc.py`, `scripts/check_limitations_sync.py`	New `check_examples_doc.py` extracts fenced blocks, parses `vera` blocks via `vera.parser`, enforces allowlist and reports stale entries/errors. `check_limitations_sync.py` now targets `KNOWN_ISSUES.md` and adjusted heading extraction/messages.
Tests `tests/test_readme.py`, `tests/test_errors.py`	`test_readme.py` updated expected ```vera block count (13 → 3) and removed prior allowlist entries; `test_errors.py` updated README-section heading detection and broadened section termination conditions.
Contributor / testing docs `CONTRIBUTING.md`, `TESTING.md`, `CLAUDE.md`	Updated pre-commit hook counts (21 → 22) and added documentation of the new examples validation (`python scripts/check_examples_doc.py`) in CONTRIBUTING.md/TESTING.md/CLAUDE.md.

Sequence Diagram(s)

sequenceDiagram
  participant Dev as Developer
  participant Git as Git / pre-commit
  participant Hook as examples-doc hook
  participant Script as scripts/check_examples_doc.py
  participant Parser as vera.parser
  rect rgba(200,200,255,0.5)
    Dev->>Git: git commit
    Git->>Hook: run examples-doc
    Hook->>Script: execute check_examples_doc.py --files EXAMPLES.md
    Script->>Script: extract fenced code blocks
    Script->>Parser: parse each `vera` block
    Parser-->>Script: parse result (ok or error)
    Script->>Hook: exit code/report
    Hook-->>Git: hook passes/fails commit
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Add TextMate bundle for Vera syntax highlighting #364: Adjusts README example allowlists and README-related tests—overlaps test and example reorganisation in this PR.
Fix http.vera example: add main function #358: Modifies README/examples and README-related tests/allowlist handling, related to how examples are validated and located.
docs: split ROADMAP into milestone roadmap + HISTORY build narrative #405: Adds HISTORY.md and coordinated README/ROADMAP changes touching similar documentation surface.

Suggested labels

docs, ci, tests

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarises the primary change: restructuring README into purpose-built, focused documents (EXAMPLES.md, DESIGN.md, KNOWN_ISSUES.md).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/readme-restructure

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

CONTRIBUTING.md (1)

74-122: ⚠️ Potential issue | 🟡 Minor

Update hook/docs list to include EXAMPLES.md validation

The hook count was updated to 22, but the surrounding list still omits the new EXAMPLES.md parser check, which makes this section stale.

📌 Proposed doc update

-- README, SKILL.md, HTML, and spec code blocks parse correctly
+- README, EXAMPLES.md, SKILL.md, HTML, and spec code blocks parse correctly
...
 python scripts/check_readme_examples.py  # verify README code blocks parse
+python scripts/check_examples_doc.py     # verify EXAMPLES.md code blocks parse
 python scripts/check_skill_examples.py   # verify SKILL.md code blocks parse

As per coding guidelines **/*.md: Review Markdown files for factual accuracy against the codebase, broken links, and outdated information.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@CONTRIBUTING.md` around lines 74 - 122, Update the documentation list of
pre-commit hooks to include the new EXAMPLES.md parser validation: add an item
like "EXAMPLES.md parser/validation" to the bullet list and ensure the stated
hook count (22) and any related sentences reflect this addition; specifically
update the section that mentions documentation-source changes and the
`site-assets` hook (and references to `scripts/build_site.py` /
`scripts/check_site_assets.py`) so it documents that EXAMPLES.md is validated by
the site-assets/check scripts.

TESTING.md (1)

348-369: ⚠️ Potential issue | 🟡 Minor

Hook table is still out of sync with the new doc split

The section says 22 hooks, but the table is missing check_examples_doc.py, and the check_limitations_sync.py description still points to README instead of KNOWN_ISSUES.md.

📌 Proposed doc update

 | `check_readme_examples.py` | README code blocks parse correctly |
+| `check_examples_doc.py` | EXAMPLES.md code blocks parse correctly |
 | `check_skill_examples.py` | SKILL.md code blocks parse correctly |
...
-| `check_limitations_sync.py` | Limitation tables consistent across README, vera/README, and spec |
+| `check_limitations_sync.py` | Limitation tables consistent across KNOWN_ISSUES.md, vera/README.md, and spec |

As per coding guidelines **/*.md: Review Markdown files for factual accuracy against the codebase, broken links, and outdated information.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@TESTING.md` around lines 348 - 369, Update the hook summary and table under
the "After running `pre-commit install`, every commit is checked by 22 hooks:"
paragraph: increment the count to 23, add the missing row for
`check_examples_doc.py` (describe it as "Documentation examples pass `vera
check` + `vera verify`" or similar), and change the description for
`check_limitations_sync.py` to reference `KNOWN_ISSUES.md` instead of README;
edit the table entries in TESTING.md where the hooks are listed (look for the
existing `check_examples.py` / `check_limitations_sync.py` rows) to make these
three concrete edits so the doc matches the codebase.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@CONTRIBUTING.md`:
- Around line 74-122: Update the documentation list of pre-commit hooks to
include the new EXAMPLES.md parser validation: add an item like "EXAMPLES.md
parser/validation" to the bullet list and ensure the stated hook count (22) and
any related sentences reflect this addition; specifically update the section
that mentions documentation-source changes and the `site-assets` hook (and
references to `scripts/build_site.py` / `scripts/check_site_assets.py`) so it
documents that EXAMPLES.md is validated by the site-assets/check scripts.

In `@TESTING.md`:
- Around line 348-369: Update the hook summary and table under the "After
running `pre-commit install`, every commit is checked by 22 hooks:" paragraph:
increment the count to 23, add the missing row for `check_examples_doc.py`
(describe it as "Documentation examples pass `vera check` + `vera verify`" or
similar), and change the description for `check_limitations_sync.py` to
reference `KNOWN_ISSUES.md` instead of README; edit the table entries in
TESTING.md where the hooks are listed (look for the existing `check_examples.py`
/ `check_limitations_sync.py` rows) to make these three concrete edits so the
doc matches the codebase.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: aa8eda59-fd1d-4103-836e-c3f93b10c465

📥 Commits

Reviewing files that changed from the base of the PR and between c11b246 and ecb95f3.

📒 Files selected for processing (12)

.pre-commit-config.yaml
CLAUDE.md
CONTRIBUTING.md
DESIGN.md
EXAMPLES.md
KNOWN_ISSUES.md
README.md
TESTING.md
scripts/check_examples_doc.py
scripts/check_limitations_sync.py
tests/test_errors.py
tests/test_readme.py

CONTRIBUTING.md: - Add EXAMPLES.md to bullet list of doc files whose code blocks are checked - Add check_examples_doc.py to Validation Scripts section TESTING.md: - Add missing check_examples_doc.py row to pre-commit hook table - Update check_limitations_sync.py description: README → KNOWN_ISSUES.md - Fix check_examples.py example count: 29 → 30 Hook count stays at 22 (was already correct after the restructure commit). Co-Authored-By: Claude <noreply@anthropic.invalid>

aallan · 2026-03-28T09:03:55Z

@coderabbitai Both outside-diff comments addressed in 57ee10e:

CONTRIBUTING.md — added EXAMPLES.md to the bullet list of validated doc files; added check_examples_doc.py to the Validation Scripts section.

TESTING.md — added the missing check_examples_doc.py row to the hook table; updated check_limitations_sync.py description from "README" → "KNOWN_ISSUES.md"; fixed example count 29 → 30.

Note: the hook count stays at 22 (not 23 as suggested) — check_doc_counts.py confirms this is already correct, since the new hook was already included in the count when it was incremented 21 → 22 in the restructure commit.

coderabbitai · 2026-03-28T09:04:12Z

Tip

For best results, initiate chat on the files or code changes.

@aallan Thanks for the detailed update — all confirmed:

CONTRIBUTING.md: EXAMPLES.md and check_examples_doc.py additions noted ✓
TESTING.md: check_examples_doc.py hook row, KNOWN_ISSUES.md description correction, and example count 29 → 30 all look correct ✓

And you're right to push back on the hook count — if check_examples_doc.py was already factored into the 21 → 22 increment in the restructure commit, then 22 is correct and my suggestion of 23 was mistaken. check_doc_counts.py is the canonical authority here.

🧠 Learnings used

Learnt from: aallan
Repo: aallan/vera PR: 0
File: :0-0
Timestamp: 2026-03-25T16:24:36.297Z
Learning: In repo aallan/vera, the script `scripts/check_doc_counts.py` automatically validates that documented example and conformance program counts in TESTING.md, CLAUDE.md, and related docs match the actual file counts (`ls examples/*.vera | wc -l`, etc.). Do not flag count mismatches as bugs without first verifying against this script.

Learnt from: aallan
Repo: aallan/vera PR: 0
File: :0-0
Timestamp: 2026-03-27T15:10:20.845Z
Learning: Applies to examples/**/*.vera (repo aallan/vera): There are 29 example programs in `examples/` (top-level only; `ls examples/*.vera | wc -l` = 29). All must pass `vera check` and `vera verify`. The canonical count is validated by `scripts/check_doc_counts.py`; always defer to that script before flagging count mismatches.

Learnt from: CR
Repo: aallan/vera PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2026-03-24T23:43:04.384Z
Learning: Update relevant documentation and tests with code changes

coderabbitai Bot reviewed Mar 28, 2026

View reviewed changes

aallan merged commit b9cabf2 into main Mar 28, 2026
17 checks passed

aallan deleted the docs/readme-restructure branch March 28, 2026 10:58

coderabbitai Bot mentioned this pull request Mar 29, 2026

fix: correct stale conformance counts in SKILL.md and AGENTS.md; extend check_doc_counts.py #423

Merged

coderabbitai Bot mentioned this pull request Apr 7, 2026

feat: vera check --explain-slots, v0.0.108 #446

Merged

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: restructure README into purpose-built documents#407

docs: restructure README into purpose-built documents#407
aallan merged 2 commits into
mainfrom
docs/readme-restructure

aallan commented Mar 28, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

codecov Bot commented Mar 28, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Mar 28, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested labels

Uh oh!

coderabbitai Bot left a comment

Uh oh!

aallan commented Mar 28, 2026

Uh oh!

coderabbitai Bot commented Mar 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

aallan commented Mar 28, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

codecov Bot commented Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coderabbitai Bot commented Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested labels

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

aallan commented Mar 28, 2026

Uh oh!

coderabbitai Bot commented Mar 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

aallan commented Mar 28, 2026 •

edited by coderabbitai Bot

Loading

codecov Bot commented Mar 28, 2026 •

edited

Loading

coderabbitai Bot commented Mar 28, 2026 •

edited

Loading