Merge train: #183, #184, #185

CONTRIBUTING.md

@@ -159,13 +159,35 @@ grows with a name that wraps, so a related chip's mark is held flush with its
 corner and as tall as the first line. The gate measures the Related APIs chips
 on the Scala Server, Session, Window, Pane and Client pages at 1440 pixels,
 where a name wraps onto several lines, and requires each chip to hold its name
-and clear the next. Each check ends with a negative control that breaks what it
-holds and requires the gate to notice, by the problem it names:
+and clear the next. It reads the chips of the usage table on the `list-panes`
+manual page the same way, and requires a chip with a qualifier to keep the width
+its name needs, with the qualifier beside it or under it. Each check ends with a
+negative control that breaks what it holds and requires the gate to notice, by
+the problem it names:
 
 ```console
 $ node site/scripts/check-dev.mjs --badge-centring
 ```
 
+A link the page marks for a preview card must have a card to show. The preview
+check hovers the C function link of a method page, then asks for the payload of
+every marked link on four pages. It asks only for destinations the dev build
+serves: one version of each port's reference, as its build target says, so the
+Python reference that the other ports link to at `stable` is not asked for. What
+it leaves out is bounded: only reference trees whose publisher owns the version
+tree (`publishesOwnTree`), at versions the dev build does not serve. A payload
+missing on a port the build does serve is reported, and the check fails if it
+would not report one. Both checks run in the publication audit through the full
+`check-dev.mjs` matrix, on its own source mirror and not on the assembly. The
+trees it leaves out are the shell's own in the assembly (each port's shell build
+renders `<slug>/<version>/reference/`), and `reference-previews.test.ts` reads
+every port and tmux tree there and requires a payload beside each page a link is
+marked for:
+
+```console
+$ node site/scripts/check-dev.mjs --reference-previews
+```
+
 Keep the complete assembly, all output suites, link audits, source/model
 freshness, and full browser matrix in the publication audit:
 
@@ -204,6 +226,18 @@ similar names alone do not establish one. An overloaded page can belong to
 several concepts. The page dropdown and "In other ports" use these mappings,
 and tests require every mapped target to resolve.
 
+A tmux command page links the methods that send the command, and a method
+page links the command and the C function behind its scope. Those links come
+from each port's source at the revision its API model was extracted from, not
+from concepts: a method that only reads a captured snapshot has no link, and a
+plan or chain that only records a command is an exclusion with cited lines. After
+a port's model changes revision, regenerate the usage data with the port
+checkouts present:
+
+```console
+$ node scripts/gen-tmux-usage.mjs
+```
+
 "Discussed in" comes from API mentions in guides, including tables and
 sections headed with a port name. After editing those mentions, regenerate
 the index:

justfile

@@ -0,0 +1,38 @@
+# Remove ignored build output. .gitignore decides what that is.
+# https://just.systems/
+
+# List available commands
+default:
+    @just --list
+
+# Remove ignored build output such as node_modules; .env, cache and lock stay.
+[group: 'clean']
+clean:
+    #!/usr/bin/env bash
+    # Untracked files, .env and .env.* files, the .build-cache/ build cache and
+    # the .build.lock file stay. `pnpm run clean` remains the build-aware clean
+    # of generated site output, and takes the lock the same way: it refuses
+    # while an assembly holds it. git clean inherits the descriptor, so killing
+    # this script does not free the lock while files are still going.
+    set -euo pipefail
+    exec 9>>.build.lock
+    flock --nonblock 9 || { printf 'just clean: an assembly holds .build.lock; wait for it to finish.\n' >&2; exit 1; }
+    git clean -fdX -e '!.env' -e '!.env.*' -e '!.build-cache/' -e '!.build.lock'
+
+# Preview what clean will delete. It deletes nothing, so it ignores the lock.
+[group: 'clean']
+clean-dry:
+    git clean -ndX -e '!.env' -e '!.env.*' -e '!.build-cache/' -e '!.build.lock'
+
+# Remove untracked and ignored files, even the cache and lock; .env files stay.
+[group: 'clean']
+[confirm("Remove untracked and ignored files, including node_modules/, the .build-cache/ build cache and the .build.lock file. Files named .env and .env.* stay. Continue?")]
+nuke:
+    #!/usr/bin/env bash
+    # Refuses while an assembly holds .build.lock, as clean does, once the
+    # prompt is answered. git clean -x ignores .gitignore and only preserves -e
+    # patterns, so .env is named here rather than negated.
+    set -euo pipefail
+    exec 9>>.build.lock
+    flock --nonblock 9 || { printf 'just nuke: an assembly holds .build.lock; wait for it to finish.\n' >&2; exit 1; }
+    git clean -fdx -e '.env' -e '.env.*'

packages/api-model/src/languages/jvm-examples.ts

@@ -76,7 +76,7 @@ export function attachCompleteJvmExamples(
     }
     const blocks: NonNullable<DocBlock['examples']> = [{
       lang: 'console',
-      intro: `${program.description.replace(/\n/g, ' ')} Use JDK 25, Git, and tmux 3.2a through 3.7c on Linux, with /bin/cat and /bin/sh available. In an empty directory, fetch the documented library revision:`,
+      intro: `${program.description.replace(/\n/g, ' ')} Use JDK 25, Git, and tmux 3.3a through 3.7c on Linux, with /bin/cat and /bin/sh available. In an empty directory, fetch the documented library revision:`,
       code: `$ git clone https://github.com/${source.repo}.git libtmux-source && \\\n  git -C libtmux-source checkout ${source.revision}\n`,
     }]
     for (const file of files) blocks.push({

packages/api-model/src/parser.ts

@@ -31,6 +31,8 @@ const GRAMMAR = {
   swift: 'swift',
   kotlin: 'kotlin',
   scala: 'scala',
+  ruby: 'ruby',
+  lua: 'lua',
 } as const
 
 export type GrammarName = keyof typeof GRAMMAR