API docs

.editorconfig

@@ -91,6 +91,12 @@ max_line_length = unset
 [generated/dart-rest/**]
 max_line_length = unset
 
+# vimanam and the AsyncAPI markdown template render each spec's fields, parameters and payloads as Markdown table
+# rows, and a table row cannot wrap: the Markdown formatter then pads every column to its widest cell. Only the two
+# rendered spec references are exempt; everything else under generated/specs/ keeps the limit.
+[generated/specs/{rest,ws}.md]
+max_line_length = unset
+
 [config/upstream-cache/data.toml]
 max_line_length = 200
 

.mise/config.js.toml

@@ -29,6 +29,18 @@
 "npm:pnpm" = { version = "11", os = ["macos/x64"] }
 # flakiness-junit-xml uploads CI test results to flakiness.io, which tracks each test's flakiness across runs.
 "npm:@flakiness/junit-xml" = "latest"
+# The AsyncAPI generator renders generated/specs/ws.yaml as generated/specs/ws.md through the markdown template.
+# The template is installed here and handed to the generator as a local path, so generation never fetches it. It is
+# pinned because upstream asks templates to be: an unpinned template changes the rendered document on its own.
+#
+# Both reach rollup@2.80.0 through @asyncapi/generator-react-sdk, which aube's trust policy refuses:
+#   trust downgrade for rollup@2.80.0 (trustPolicy=no-downgrade): earlier published version 4.52.4 had trusted
+#   publisher but this version has no trust evidence
+# It is a manually published 2.x backport of a path-traversal fix by rollup's lead maintainer, and its npm gitHead is
+# the commit the v2.80.0 tag names, https://github.com/rollup/rollup/commit/d17ae15336a45c3c59b2a4aacac2b14186035d28.
+# Only that version is excluded, so any other release without trust evidence still fails.
+"npm:@asyncapi/generator" = { version = "latest", trust_policy_excludes = ["rollup@2.80.0"] }
+"npm:@asyncapi/markdown-template" = { version = "2.0.0", trust_policy_excludes = ["rollup@2.80.0"] }
 
 # oxlint + oxfmt are the Rust-native JS/TS linter + formatter from the oxc-project.
 # They are pulled directly from the shared `apps_v<tag>` GitHub release. Aqua's registry entry trips mise's
@@ -178,6 +190,36 @@ dir = "services/ws-modules/js-data1"
 # entry) resolvable -- the same way `pnpm` itself resolves here.
 run = "pnpm install && node build.mjs"
 
+[tasks."gen:ws-md"]
+depends = ["gen:ws-spec"]
+description = "Render generated/specs/ws.yaml as the Markdown reference generated/specs/ws.md (AsyncAPI generator)"
+env = { RUMDL_CACHE_DIR = "{{ config_root }}/target/rumdl-cache" }
+# The generator runs the pinned markdown template from its npm: install, so generation fetches nothing.
+# It is driven through its library API rather than the AsyncAPI CLI, which wraps the same generator in a command
+# framework that sends usage metrics by default and pulls in dependencies this repo does not otherwise need. rumdl's
+# fixes and the Markdown formatter then settle the layout, so the committed file is already what both checks want. The
+# work is staged under target/ and lands in one rename, leaving the committed file whole if any step fails.
+run = """
+stage=target/int-gen/ws-md
+out=generated/specs/ws.md
+generator="$(mise where npm:@asyncapi/generator)/node_modules/@asyncapi/generator"
+template="$(mise where npm:@asyncapi/markdown-template)/node_modules/@asyncapi/markdown-template"
+coreutils mkdir -p "$stage"
+node -e '
+const [generator, template, target, spec] = process.argv.slice(1);
+const Generator = require(generator);
+const options = { forceWrite: true, templateParams: { outFilename: "raw.md" } };
+new Generator(template, target, options).generateFromFile(spec).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+' "$generator" "$template" "$stage" generated/specs/ws.yaml
+rumdl check --fix --fail-on never --silent --config config/rumdl.toml "$stage/raw.md"
+dprint fmt --stdin "$out" <"$stage/raw.md" >"$stage/ws.md"
+coreutils mv -f "$stage/ws.md" "$out"
+"""
+shell = "{{ vars.task_shell }}"
+
 [tasks.oxlint-check]
 description = "Lint JavaScript/TypeScript sources (oxlint)"
 # oxlint walks the working tree from CWD, honouring .gitignore; no path arg needed.

.mise/config.toml

@@ -172,7 +172,7 @@ ls-lint = "latest"
 #   aqua:pvolok/dekit@0.10.0: no asset found: mprocs-0.10.0-darwin-aarch64.tar.gz, mprocs-0.10.0-darwin-universal.tar.gz
 # on mise 2026.9.18. Return to the registry name once its aqua entry knows the `dekit-<triple>` assets.
 "github:pvolok/dekit" = "latest"
-node = "22"
+node = "24"
 osv-scanner = "latest"
 # Aqua has no pipx build for windows/amd64.
 # On Windows the workflow runs `python -m pip install pipx` separately so the
@@ -317,6 +317,15 @@ version = "0.10.0"
 asset_pattern = "{{ vars.musl_pattern }}"
 version = "latest"
 
+# The Markdown linter behind rumdl-check; musl on Linux so the older-glibc image bases can run it.
+[tools."github:rvben/rumdl"]
+asset_pattern = "{{ vars.musl_pattern }}"
+version = "latest"
+
+# Renders generated/specs/rest.yaml as the Markdown reference generated/specs/rest.md.
+[tools."github:noemaforge/vimanam"]
+version = "latest"
+
 # espflash writes ESP32 firmware to a board over USB and shows its defmt log, for a firmware-esp32c6 deployment.
 # Its release holds cargo-espflash beside it, so the pattern names espflash's own assets; on Linux its musl build, for
 # the same reason as coreutils above.
@@ -929,6 +938,7 @@ depends = [
   "readme-mise-version-check",
   "regal-check",
   "repo-check",
+  "rumdl-check",
   "ryl-check",
   "semgrep-check",
   "semgrep-check-rule-tests",
@@ -956,7 +966,7 @@ description = "Run all checks: check:rust + any loaded guest check:<lang>"
 # Rust + universal lint-fix passes.
 # Distinct from fmt:rust (style/whitespace
 # formatters) -- these apply auto-rewrites for actual lint violations.
-depends = ["ast-grep-fix", "cargo-clippy-fix", "cargo-shear-fix", "regal-fix", "semgrep-fix", "typos-fix"]
+depends = ["ast-grep-fix", "cargo-clippy-fix", "cargo-shear-fix", "regal-fix", "rumdl-fix", "semgrep-fix", "typos-fix"]
 description = "Apply Rust + universal lint-fix passes"
 
 [tasks.fix]
@@ -1733,6 +1743,16 @@ fi
 """
 shell = "{{ vars.task_shell }}"
 
+[tasks.rumdl-check]
+description = "Lint every tracked Markdown file (rumdl)"
+env = { RUMDL_CACHE_DIR = "{{ config_root }}/target/rumdl-cache" }
+run = "rumdl check --config config/rumdl.toml ."
+
+[tasks.rumdl-fix]
+description = "Apply rumdl's fixes to every tracked Markdown file"
+env = { RUMDL_CACHE_DIR = "{{ config_root }}/target/rumdl-cache" }
+run = "rumdl check --fix --config config/rumdl.toml ."
+
 [tasks.typos-check]
 alias = "typos"
 run = "typos --config config/typos.toml"
@@ -2718,7 +2738,7 @@ description = "Fetch upstream WASI WIT packages into generated/specs/wit/ at pin
 run = "cargo run -q -p et-int-gen --bin et-int-gen -- fetch-deps"
 
 [tasks."gen:ws-spec"]
-description = "Run et-int-gen: emit the language-agnostic WS specs (YAML/WIT/KDL/JSON) + the Rust REST client"
+description = "Run et-int-gen: emit the language-agnostic WS specs (YAML/Markdown/WIT/KDL/JSON) + the Rust REST client"
 # et-int-gen runs progenitor + prettyplease to produce generated/rust-rest/src/lib.rs.
 # prettyplease's style disagrees with our nightly rustfmt (different import grouping + line width), so
 # the workspace `mise run fmt` would reformat it and `mise run gen-specs-check` would see drift on the
@@ -2748,6 +2768,31 @@ description = "Run et-int-gen: emit the ws-wasi-runner host bindings for the `ru
 # Unlike gen:ws-spec there is no rustfmt post-process; refer to int-gen bindings.rs for details.
 run = "cargo run -q -p et-int-gen --bin et-int-gen -- generate bindings"
 
+[tasks."gen:rest-md"]
+depends = ["gen:ws-spec"]
+description = "Render generated/specs/rest.yaml as the Markdown reference generated/specs/rest.md (vimanam)"
+env = { RUMDL_CACHE_DIR = "{{ config_root }}/target/rumdl-cache" }
+# Two constructs in vimanam's output that the Markdown rules reject are rewritten before formatting.
+# It writes `<br/>` between the paragraphs of a table cell, and an emphasis-only line where an operation has no request
+# or response schema; they become a space and a plain sentence. rumdl's fixes and the Markdown formatter then settle
+# the layout, so the committed file is already what both checks want. The work is staged under target/ and lands in
+# one rename, leaving the committed file whole if any step fails.
+run = """
+stage=target/int-gen/rest-md
+out=generated/specs/rest.md
+coreutils mkdir -p "$stage"
+vimanam generated/specs/rest.yaml --detail full --include-schemas --include-auth --no-report -o "$stage/raw.md"
+goawk '
+{ gsub("<br/>", " ") }
+/^[*]No (request|response) schema available[*]$/ { gsub("[*]", ""); $0 = $0 "." }
+{ print }
+' "$stage/raw.md" >"$stage/tidy.md"
+rumdl check --fix --fail-on never --silent --config config/rumdl.toml "$stage/tidy.md"
+dprint fmt --stdin "$out" <"$stage/tidy.md" >"$stage/rest.md"
+coreutils mv -f "$stage/rest.md" "$out"
+"""
+shell = "{{ vars.task_shell }}"
+
 [tasks.gen-specs]
 # Native `depends` glob anchored by gen:ws-spec (core + Rust client, always loaded).
 # That anchor keeps the glob from matching zero; guest `gen:<lang>` tasks join from their