Skip to content

Documentation consistency sweep + stdlib improvement issues#369

Merged
aallan merged 2 commits into
mainfrom
feat/stdlib-improvement-issues
Mar 27, 2026
Merged

Documentation consistency sweep + stdlib improvement issues#369
aallan merged 2 commits into
mainfrom
feat/stdlib-improvement-issues

Conversation

@aallan

@aallan aallan commented Mar 27, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Owner

Summary

Detail

Roadmap additions - three stdlib improvement issues filed from real-world HTTP+JSON usage patterns:

  • #366 JSON typed accessors (json_as_string, json_get_number, etc.)
  • #367 Markdown content extractors (md_inline_text, md_headings, md_links)
  • #368 HTML convenience accessors (html_query_one, html_tag, html_children)

Module Map refresh - the vera/README.md table was significantly out of date. Key changes since the numbers were written:

  • wasm/calls.py: 223 -> 8,332 lines (now covers all built-in call translation: Json, Html, Http, Map, Set, etc.)
  • environment.py: 302 -> 1,560 lines
  • codegen/api.py: 842 -> 2,023 lines
  • browser/runtime.mjs: 1,123 -> 2,017 lines (gained Http, Json, Html support)
  • smt.py and verifier.py roughly doubled each
  • Added missing wasm/json_serde.py (209) and wasm/html_serde.py (191)
  • Overall total: ~12,850 -> ~32,000 lines of Python

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Updated product roadmap with three new Tier 2 planned features: typed JSON accessors, Markdown content extraction helpers, and HTML convenience accessors.
    • Bumped project status version in README from v0.0.98 to v0.0.100.
    • Updated examples count in site generation to 29 verified examples.
    • Revised module map and sizing information in the project README to reflect expanded components and runtimes.

@aallan
Add JSON, Markdown, HTML stdlib improvement issues to roadmap
1bcdce8 
- #366: JSON typed accessors (json_as_string, json_get_number, etc.)
  — eliminates two-level pattern match for every API field extraction
- #367: Markdown content extractors (md_inline_text, md_headings, etc.)
  — fills structural traversal gap alongside existing query functions
- #368: HTML convenience accessors (html_query_one, html_tag, html_children)
  — adds single-element CSS query and tree traversal primitives

All three arise from real-world usage patterns in HTTP+JSON API clients.
All are pure Vera prelude additions — no new WASM host imports.

Co-Authored-By: Claude <noreply@anthropic.invalid>
@codecov

codecov Bot commented Mar 27, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.32%. Comparing base (9f517cb) to head (c16df0a).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files 
@@           Coverage Diff           @@
##             main     #369   +/-   ##
=======================================
  Coverage   90.32%   90.32%           
=======================================
  Files          49       49           
  Lines       18999    18999           
  Branches      219      219           
=======================================
  Hits        17161    17161           
  Misses       1834     1834           
  Partials        4        4
Flag Coverage Δ
javascript 50.73% <ø> (ø)
python 95.30% <ø> (ø)

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

coderabbitai Bot commented Mar 27, 2026 •
edited
Loading

Copy link
Copy Markdown
📝 Walkthrough

Walkthrough

Updated documentation: added three new Tier 2 interleave features to ROADMAP.md (JSON typed accessors, Markdown content extractors, HTML convenience accessors). Also bumped project version in README.md, adjusted example count in scripts/build_site.py, and updated module-map/statistics in vera/README.md. No code or API signatures changed.

Changes

Cohort / File(s) Summary
Roadmap documentation
ROADMAP.md		 Added three Tier 2 interleave feature entries: JSON typed accessors (json_as_*, json_get_* returning Option<T>), Markdown content extractors (recursive block/inline traversal helpers and filters), and HTML convenience accessors (e.g., html_query_one, small tag/children helpers).
Top-level README
README.md		 Bumped Project Status version string from v0.0.98 to v0.0.100.
Site build script
scripts/build_site.py		 Updated static docs generation text to reflect examples/ contains 29 verified example programs (numeric count change in build_llms_txt).
Module map / docs
vera/README.md		 Updated module-map and size/coverage statistics across compiler/runtime subsections (grammar, core phases, verifier, WASM translation, JSON/HTML marshalling, browser runtime); purely descriptive text changes.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

Suggested labels

compiler, ci, docs

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Title check ⚠️ Warning The title refers to 'documentation consistency sweep' as a primary change, but the main changeset purpose is adding three new stdlib improvement issues to the roadmap (JSON/Markdown/HTML accessors). The title is misleading about the PR's primary objective. Revise the title to reflect the main intent: something like 'Add JSON, Markdown, and HTML stdlib improvement issues to roadmap' or 'Add three stdlib feature requests to Tier 2 interleave roadmap'.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/stdlib-improvement-issues

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

@aallan
Documentation consistency sweep
c16df0a 
- README.md: fix stale version number (v0.0.98 → v0.0.100)
- vera/README.md: update Module Map line counts to v0.0.100 actuals
  — all packages have grown significantly since the table was written
  — wasm/ grew from 2,474 to 12,672 lines (calls.py alone is 8,332)
  — codegen/ grew from 4,279 to 6,098 lines (api.py: 842 → 2,023)
  — environment.py grew from 302 to 1,560 lines
  — smt.py/verifier.py roughly doubled each
  — add missing wasm/json_serde.py (209) and wasm/html_serde.py (191)
  — update runtime.mjs (1,123 → 2,017, gained Http/Json/Html support)
  — update overall total: ~12,850 → ~32,000 lines of Python
- scripts/build_site.py: fix example count (28 → 29)
- Regenerate site assets

Co-Authored-By: Claude <noreply@anthropic.invalid>
@aallan aallan changed the title Add JSON/Markdown/HTML stdlib improvement issues to roadmap Documentation consistency sweep + stdlib improvement issues Mar 27, 2026
coderabbitai[bot]
coderabbitai Bot reviewed Mar 27, 2026
View reviewed changes

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents 
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@scripts/build_site.py`:
- Line 110: Update the examples count in the documentation string that currently
reads "[examples/]({REPO}/tree/main/examples): 29 verified example programs \";
change the numeric literal "29" to "31" so the text reflects the actual number
of .vera files in the examples directory.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 662d0924-7d1e-4a23-858c-241539557aa9

📥 Commits

Reviewing files that changed from the base of the PR and between 1bcdce8 and c16df0a.

⛔ Files ignored due to path filters (1)
  • docs/llms.txt is excluded by !docs/**
📒 Files selected for processing (3)
  • README.md
  • scripts/build_site.py
  • vera/README.md

Comment thread scripts/build_site.py
@aallan

aallan commented Mar 27, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai re #3001563293: CodeRabbit ran fd -e vera . examples/ which searches recursively. Locally ls examples/*.vera | wc -l gives exactly 29 — matching what check_doc_counts.py independently validates. 29 is correct, no change needed.

@coderabbitai

coderabbitai Bot commented Mar 27, 2026

Copy link
Copy Markdown

Tip

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

@aallan, understood — thank you for clarifying. The fd -e vera . examples/ command I used searches recursively and produced a stale result; the correct count is 29, corroborated by both ls examples/*.vera | wc -l and check_doc_counts.py. My review comment was incorrect. I'll update the long-term memory accordingly.

✏️ Learnings added 
Learnt from: aallan
URL: https://github.com/aallan/vera/pull/369

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.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

⛔ Learnings removed 
Learnt from: CR
Repo: aallan/vera PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-26T09:52:26.969Z
Learning: Applies to examples/**/*.vera : All 28 examples in `examples/` must pass `vera check` and `vera verify`
🧠 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: CR
Repo: aallan/vera PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-26T09:52:26.969Z
Learning: Applies to examples/**/*.vera : All 28 examples in `examples/` must pass `vera check` and `vera verify`

Learnt from: CR
Repo: aallan/vera PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-26T13:29:37.409Z
Learning: Applies to examples/**/*.vera : Example Vera programs must pass both `vera check` and `vera verify`

Learnt from: CR
Repo: aallan/vera PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-26T13:29:37.409Z
Learning: Applies to **/*.vera : All Vera programs must pass `vera check` and `vera verify`

Learnt from: CR
Repo: aallan/vera PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2026-03-24T23:43:04.384Z
Learning: Applies to examples/**/*.vera : Update examples in examples/ if an existing example demonstrates a feature, or add a new one when adding or modifying built-in functions

Learnt from: CR
Repo: aallan/vera PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-26T09:52:26.969Z
Learning: Applies to examples/**/*.vera : Pre-commit hooks must validate that all examples pass

Learnt from: CR
Repo: aallan/vera PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-26T09:52:26.969Z
Learning: Applies to **/*.vera : Recursive functions need a `decreases()` clause

Learnt from: CR
Repo: aallan/vera PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-26T09:52:26.969Z
Learning: Applies to tests/conformance/**/*.vera : All 62 conformance programs in `tests/conformance/` must pass their declared level

Learnt from: aallan
Repo: aallan/vera PR: 350
File: tests/test_codegen.py:8630-8633
Timestamp: 2026-03-25T16:32:11.316Z
Learning: Repo aallan/vera PR `#350`: tests/test_codegen.py includes explicit WAT import‑gating coverage for JSON host imports — tests test_json_parse_wat_import, test_json_stringify_wat_import, and test_json_no_imports_when_unused verify that "vera.json_parse"/"vera.json_stringify" imports are emitted only when referenced and absent when unused.

Learnt from: aallan
Repo: aallan/vera PR: 350
File: vera/wasm/calls.py:4456-4463
Timestamp: 2026-03-25T14:53:24.176Z
Learning: Repo aallan/vera: In vera/wasm/calls.py, JSON host-import helpers must record usage via self._json_ops_used.add("json_parse") and self._json_ops_used.add("json_stringify") inside CallsMixin._translate_json_parse/_translate_json_stringify so codegen propagates result.json_ops_used and conditional imports are injected in assembly/api; otherwise WAT may reference $vera.json_parse/$vera.json_stringify without matching imports.

@aallan aallan merged commit cfb8457 into main Mar 27, 2026
17 checks passed
@aallan aallan deleted the feat/stdlib-improvement-issues branch March 27, 2026 15:11
This was referenced Apr 17, 2026
Merged
Merged
@coderabbitai coderabbitai Bot mentioned this pull request Apr 24, 2026
Merged
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@coderabbitai coderabbitai[bot] coderabbitai[bot] left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@aallan