Implementation map and handbook maintenance

Use this page to connect a handbook explanation to the code behind it, and to keep the handbook complete when a release adds commands or features.

Source baseline

This edition describes Semaprax 0.9.0, tag v0.9.0. Implementation links below point at that tag. Topic guides link to the living specifications on main. When you reproduce a result, record the version and the commit.

Follow a source file through the compiler

.spx source → parse → resolve and check → checked HIR → cleanup plan
                                                ↓
                                  queries / interpreter / target build

Parsing reads structure. Resolution names declarations and types. HIR records the checked program. Cleanup planning decides how owned values and resources settle. Queries and execution routes read those results for their own jobs. A source program, a semantic report, an approved operation and an executable package are different objects: keep the producing command and revision with each.

Find the code for a topic

The architecture map has the full module map. The completion matrix and quality gates say what is implemented and how it is tested. Read a gate for its named subject and target; a module name does not prove a test result.

Write pages that stay true

• Open each page with what the reader can do after it. Lead with a runnable example, then explain it.
• Define a term at first use and link the glossary.
• Give a runnable example a file name, a working directory, a command and its output. Keep command templates in their own block and say which parts to replace.
• Label private, experimental, preview and main-only features as such.
• When source changes, follow the change through the parser, the checker, the runner and the target. Never change compiler behavior to make an example fit.

Run the handbook checks

Python 3.10 or newer, from the repository root:

python3 scripts/test-check-handbook.py
python3 scripts/check-handbook.py --structure-only
python3 scripts/check-handbook.py --compiler /absolute/path/to/semaprax

The structure check validates local links, that every page has one SUMMARY entry, fence closure and example markers. The compiler-backed run also formats temporary copies of marked modules, checks and runs them, and compares the output. Only blocks marked handbook-smoke or handbook-project-file run. Shell fences never do. Marked examples must pass in the interpreter, so a program that needs --native stays unmarked.

Keep the handbook complete for each release

Run this audit before each release. A release is not documented until every public command and every user-visible feature has a page that is true for that version.

1. Commands. List what the binary accepts and find names no page mentions:

semaprax help all | grep '^semaprax ' | cut -d' ' -f2 | sort -u > commands.txt
for c in $(cat commands.txt); do
  grep -rqE "(^|[^a-z-])$c([^a-z-]|\$)" handbook --include='*.md' || echo "missing: $c"
done

The 0.9.0 audit lists 132 commands and no missing name. Command catalog spells every command in full, so a new command must be added there with its page. A hit in grep shows a mention, not an explanation; open the page. Also read crates/semaprax-harness/src/cli.rs for harness verbs, which help all does not list.

2. Features. Read the new rows and status changes in the completion matrix and the release section of the changelog. Give each user-visible item a row in the tables below.

3. Language and library. Compare semaprax help language and semaprax help library with Cheatsheet, Built-in functions and Standard library. std/catalog.json lists every package. Regenerate the package table in the standard-library page when it changes.

4. Diagnostics. Run semaprax help diagnostic codes and add new indexed codes to Diagnostics reference.

5. Examples. Run the compiler-backed check above.

Coverage by area (0.9.0)

“Page” is where a reader learns it. “Overview” means one section or a short entry with a link to the spec. “Not in the handbook” means private, internal or not shipped.

What 0.9.0 added