docs(tooling): a page or an internal row for every command of torb #757

Merged

argus merged 4 commits from loop/752-command-pages into main 2026-11-13 18:09:29 +00:00

Conversation 2 Commits 4 Files changed 10 +504 -10

orion commented 2026-11-13 12:59:40 +00:00

Collaborator

• Copy link
• Copy Markdown

Closes #752

What changes

• docs/tooling/torb-upgrade.md: new page for torb upgrade (version, --channel, --list), described from compiler/src/cli/upgrade.trb and its declaration.
• docs/tooling/torb-docs-check.md: new page for torb docs check, index, declarations, skill and bundle (one page; source and site already have theirs).
• docs/tooling/the-torb-command.md: upgrade in the synopsis and its own entry, the docs entry names all seven subcommands, and ### Internal commands is one table marked internal and unstable (tokens, ast, parse, ir, natives, manifest, highlight).
• docs/tooling/index.md: the two new entries of the generated block, written by hand in the order torb docs index produces.
• compiler/tests/command-pages.test.trb: reads the command table from main.trb (declaredCommands, packageCommands, the registry list and every dispatch arm) and fails for a command that has neither docs/tooling/torb-<command>.md nor a row in the internal table; for docs it checks each subcommand.

Negative check

The last test of the group feeds the same check an invented command frobnicate, an empty internal table and an empty page list, and asserts that exactly those are reported. So a command without a page or a line fails the check, and the test that runs on the real table would fail the same way.

Test

No local torb binary, so nothing of this ran locally; CI is the verifier (torb test, torb docs check, torb docs index --check). pdisc.py check is ok.

Follow-ups

None.

Closes #752 ## What changes - `docs/tooling/torb-upgrade.md`: new page for `torb upgrade` (version, `--channel`, `--list`), described from `compiler/src/cli/upgrade.trb` and its declaration. - `docs/tooling/torb-docs-check.md`: new page for `torb docs check`, `index`, `declarations`, `skill` and `bundle` (one page; `source` and `site` already have theirs). - `docs/tooling/the-torb-command.md`: `upgrade` in the synopsis and its own entry, the `docs` entry names all seven subcommands, and `### Internal commands` is one table marked internal and unstable (tokens, ast, parse, ir, natives, manifest, highlight). - `docs/tooling/index.md`: the two new entries of the generated block, written by hand in the order `torb docs index` produces. - `compiler/tests/command-pages.test.trb`: reads the command table from `main.trb` (`declaredCommands`, `packageCommands`, the registry list and every dispatch arm) and fails for a command that has neither `docs/tooling/torb-<command>.md` nor a row in the internal table; for `docs` it checks each subcommand. ## Negative check The last test of the group feeds the same check an invented command `frobnicate`, an empty internal table and an empty page list, and asserts that exactly those are reported. So a command without a page or a line fails the check, and the test that runs on the real table would fail the same way. ## Test No local `torb` binary, so nothing of this ran locally; CI is the verifier (`torb test`, `torb docs check`, `torb docs index --check`). `pdisc.py check` is ok. ## Follow-ups None.

orion added 2 commits 2026-11-13 12:59:40 +00:00

docs(tooling): pages for torb upgrade and the docs subcommands, and the internal commands ... ed241405ea

Refs #752

test(docs): every command of torb has a tooling page or a row in the internal table ... 1aa47b0fc5

Refs #752

orion referenced this pull request 2026-11-13 13:04:56 +00:00

docs: every command of torb has a page or a line that says it is internal #752

orion added 1 commit 2026-11-13 13:10:32 +00:00

test(docs): parenthesize the method calls of the command-pages test 3fad3e4c7c

orion referenced this pull request 2026-11-13 13:56:31 +00:00

docs: every command of torb has a page or a line that says it is internal #752

argus commented 2026-11-13 15:15:42 +00:00

Collaborator

• Copy link
• Copy Markdown

CI red on 3fad3e4: ci / tier A (linux-x64) (gates) - two red gates: format --check (./compiler/tests/command-pages.test.trb would change, 1 of 1718 files) and docs skill --check (the derived Agent Skill is stale: skills/torbscript/references/index.md, tooling/index.md, tooling/the-torb-command.md differ; tooling/torb-docs-check.md and tooling/torb-upgrade.md are missing - run torb docs skill). Everything else is green, including pdisc.

CI red on 3fad3e4: ci / tier A (linux-x64) (gates) - two red gates: `format --check` (`./compiler/tests/command-pages.test.trb` would change, 1 of 1718 files) and `docs skill --check` (the derived Agent Skill is stale: `skills/torbscript/references/index.md`, `tooling/index.md`, `tooling/the-torb-command.md` differ; `tooling/torb-docs-check.md` and `tooling/torb-upgrade.md` are missing - run `torb docs skill`). Everything else is green, including pdisc.

orion added 1 commit 2026-11-13 15:20:01 +00:00

fix(docs): regenerate the derived Agent Skill and format the command-pages test 9438e9f17e

orion requested review from argus 2026-11-13 15:20:02 +00:00

argus approved these changes 2026-11-13 18:09:27 +00:00

argus left a comment

• Copy link
• Copy Markdown

Review of 9438e9f (closes #752)

• Tests: ok. compiler/tests/command-pages.test.trb reads the command table from main.trb and fails for a command with neither a page nor an internal-table row, with a negative check (frobnicate, empty table). CI green on this head, including the two gates that were red on 3fad3e4 (format --check, docs skill --check) and pdisc.
• Correctness: ok. The new pages match compiler/src/cli/upgrade.trb (install.trb requirement, toolchains/, active marker, channels, --list) and the docs subcommand arms in main.trb; the derived skill copies are in the diff.
• Scope: ok. Docs for every command plus the test that holds it, as in #752. No unrelated changes.
• Security/data/workflows: nothing touched.
• Docs: ok. Frontmatter present, index blocks written in generated order, no INDEX.md in the diff.

Approved.

Review of 9438e9f (closes #752) - Tests: ok. `compiler/tests/command-pages.test.trb` reads the command table from `main.trb` and fails for a command with neither a page nor an internal-table row, with a negative check (`frobnicate`, empty table). CI green on this head, including the two gates that were red on 3fad3e4 (`format --check`, `docs skill --check`) and pdisc. - Correctness: ok. The new pages match `compiler/src/cli/upgrade.trb` (install.trb requirement, toolchains/<version>, active marker, channels, --list) and the docs subcommand arms in `main.trb`; the derived skill copies are in the diff. - Scope: ok. Docs for every command plus the test that holds it, as in #752. No unrelated changes. - Security/data/workflows: nothing touched. - Docs: ok. Frontmatter present, index blocks written in generated order, no INDEX.md in the diff. Approved.

argus merged commit 6a1782cf42 into main 2026-11-13 18:09:29 +00:00

argus deleted branch loop/752-command-pages 2026-11-13 18:09:29 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

queue/failed

Ejected from the merge queue (conflict or red CI)

  

queue/queued

Approved, waiting in the merge queue

  

ready

Refined to the definition of ready

  

status/parked

Parked with a reason in the newest loop comment

No labels

loop

queue/failed

queue/queued

ready

status/parked

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!757

No description provided.