Skip to content

Lua reference: object domains, member ranking, and a live Ruby/Lua deploy - #19

Merged
tony merged 11 commits into
mainfrom
lua-reference
Sep 26, 2026
Merged

tony merged 11 commits into
mainfrom
lua-reference

Conversation

@tony

@tony tony commented Sep 25, 2026

Copy link
Copy Markdown
Contributor

The Lua reference at libtmux.org still opened on Queries, Errors, Runtime and an 82-entry Internal bucket, with no Server, Session, Window or Pane. Two causes: the _internal/ classifier fix never reached en/lua/latest, and Lua had no Session, Window or Pane type to file. Member lists on every port were alphabetical, so Server.sessions sat behind __enter__ and the private helpers.

Changes

  • Deploy: the shell publishes en/ruby/latest and en/lua/latest until those ports' own docs workflows can publish. Previously the shell dropped both trees and nothing else wrote them.
  • Member ranking (member-order.ts): listing accessors first, then operations the concept map shares across ports (by how many ports implement them), then members the guides discuss, public, deprecated, special and private. One comparator drives the sidebar and the page body.
  • Nav rules: a hierarchy bucket's path rule yields to a later bucket's name. Lua's CommandOutcome joins Commands, as TypeScript's twin already had; Rust's Layout, Rotation, SplitDirection, KeyBinding and EnvironmentEntry leave Window/Server/Session. Lua's Fields.* records move to Formats.
  • Resolver: Server:new_session resolves; C, Lua and Ruby filenames stop counting as unresolved symbols.
  • Lua adapter: members copied from a base class carry inheritedFrom.

A follow-up commit on this branch refreshes the Lua model once libtmux/libtmux-lua#3 (per-kind handle classes) merges.

Verification

$ pnpm test
$ node scripts/check-nav.mjs

The member-order test runs the same property against alphabetical order and asserts it fails.

tony added 11 commits September 25, 2026 19:17
why: Member lists sorted alphabetically, and the page body by kind
string first. Python's Server listed `sessions` behind `__enter__`,
`_list_panes` and every private helper; the sidebar and the page did not
even agree on the order.

what:
- Add member-order.ts: tiers listing accessors, query operations
  (search-* and snapshot, which is how Lua lists), concept-mapped
  operations, members the guides discuss, other public members,
  deprecated, special and private members
- Break ties by how many ports implement the member's concept, then its
  place in the concept map, then guide mentions, then name
- Use one comparator for the sidebar and the page body
- Test every port: each list-sessions, list-windows and list-panes
  accessor ranks in its type's first three, and no private or special
  member ranks above a public one; alphabetical order fails both
why: A hierarchy bucket's path rule claimed whatever its object's source
file declared. Lua's `CommandOutcome` sat under Server because it lives
in server.lua, while TypeScript's identical type sat under Commands;
Rust's Layout, Rotation and SplitDirection sat under Window. Lua's
`Fields.Session` record, named after the object, took Session's bucket
from the handle that has the methods.

what:
- Make the Server, Session, Window, Pane and Client path clauses yield
  to a later bucket's name
- File object-named records of a `Fields` module under Formats
- Regenerate the Lua and Rust sidecars; no other port moves
why: `toPath` split on dots, `::` and `->`, so `Server:new_session`
stayed one segment and matched nothing. Every Lua guide writes methods
that way, and those mentions went unlinked. C headers and sources
(`tmux.h`, `options-table.c`) were counted as unresolved symbols.

what:
- Split `Name:method` between two identifiers
- Treat .c, .h, .lua and .rb paths as filenames
- Regenerate mentions.json
why: LuaLS copies a base class's fields into every subclass, so a
subclass page listed its inherited methods as its own.

what:
- Read each class's `extends` records and trace a field to the furthest
  ancestor declaring it at the same file and line
- Set `inheritedFrom` on those members
why: Both ports are marked as publishing their own tree, so the shell
deploy drops en/ruby/latest and en/lua/latest from its artifact. Neither
port's docs workflow can publish yet, so the live pages stay on a build
older than the reference's domain buckets.

what:
- Set `publishesOwnTree: false` for ruby and lua until their workflows
  have published `latest`
why: libtmux-lua now declares Session, Window, WindowLink, Pane, Client
and Buffer handle classes (libtmux/libtmux-lua#3). The site's Lua model
predated them, so the Session, Window and Pane domains held field
records and the concept map pointed every operation at the generic
Entity.

what:
- Regenerate the Lua model, sidebar and paths from libtmux-lua fd4258b
- Point Lua concepts at the handle class that owns each operation, and
  the session, window and pane concepts at those classes
- Record Configurable, the shared options and hooks base, as unsettled
- Regenerate mentions.json
- Assert each Lua object domain opens on its handle class
why: The port index opened on a grid of module disclosures, and the
domain sections the sidebar leads with came after it. On Lua that grid
is one `libtmux` module holding every type, so the page started with
the flat list the domain buckets exist to replace.

what:
- Render the bucket sections first and the module index after them;
  module anchors are unchanged
why: LuaLS exports `---@field name fun(...)` with its arguments one level
down, under `extends.types`, and each member of a union in a nested
group of its own. The adapter read only `extends.args`, so every Lua
method in the reference rendered as `name()` with no parameters, types
or return, and `Server:handle`'s overloads were lost.

what:
- Collect every function type a field holds, recursing through union
  members, and emit one signature per overload with `overload` set
- Read argument names from LuaLS's name nodes
- Print LuaLS's `(T)?` optionals as `T?`
- Test both shapes; the old adapter fails the new test
why: libtmux-lua 294ebba gives each option, hook and environment call
its own options class (libtmux/libtmux-lua#4), and the adapter now reads
method signatures.

what:
- Regenerate the Lua model, sidebar, paths and mentions from 294ebba
- Move Lua's cross-reference floor to what the assembled tree resolves:
  signatures add links to every parameter and return type, and the eight
  fields that linked `Entity` plus a snapshot record now link one class
why: With method signatures rendered, Lua's builtins became most of what
the reference printed unlinked: `string`, `boolean`, `integer` and
`table` in nearly every parameter list, with no table entry to link them
as the other ports' builtins are.

what:
- Point nil, boolean, number, integer, string, function, table, thread
  and userdata at the manual's Values and Types section, and LuaLS's
  `any` and `unknown` at its annotation docs
- Lower Lua's plain type-name ceiling and raise its cross-reference
  floor to what the assembled tree now measures
@tony
tony merged commit bc24b1c into main Sep 26, 2026
8 checks passed
@tony
tony temporarily deployed to docs-preview-cleanup September 26, 2026 00:32 — with GitHub Actions Inactive
tony added a commit that referenced this pull request Nov 18, 2026
…pability directories

why: The Raku reference pages for the session, window and pane handles cannot
show the "What is on here" capability directory until the model carries the
prose it is built from. libtmux-raku#19 adds the directory to
LibTmux::Model::SessionRef, WindowRef and PaneRef, and the committed model,
guide cache and manifest still described ae97f9f87. The pin is the merge commit
of the PR, which is on master.

what:
- Pin Raku to libtmux/libtmux-raku@cce868d81 and regenerate its model and path
  data (exported with Rakudo 2026.09, the compiler recorded in the previous
  model; the exporter now lives at scripts/export-docs/export-docs.raku and its
  digest moves), tmux usage, source cache, guide cache and manifest packages
  with the repository's generators; the mention index, the example sources and
  the sidebar sidecar come out unchanged
- Adopt the source change between the pins: the model keeps 1069 symbols with
  none added or removed and 3 docs changed, the three handle classes that gain
  the directory
- Re-anchor the reviewed tmux usage rules: the directories added 230 lines
  above the shared transfer and constructor code of Model.rakumod, so the two
  citations of the same-pane check in `PaneRef.join` and `PaneRef.move` and the
  five captured-view constructor reviews now name the line the text is on;
  no claim or rule changed
- Take the rewritten examples README into the guide cache
- Expect the directories of SessionRef (6 rows, 16 references), WindowRef
  (6, 18) and PaneRef (11, 38) in the directory test; the captured views
  Session, Window and Pane carry no directory in the source
- Leave the landing example, its recording and the home fixture at
  9a9838047f15: examples/quickstart.raku is unchanged between that revision
  and the new pin

Source refs: libtmux/libtmux-raku master
cce868d81823db54a0d161a94db4d078d09f1861 (#19), previous pin
ae97f9f87b73db63d4ab3cabb108a195f64e4f6f.

This branch was previously deployed

2 inactive deployments
docs-preview-cleanup — 74e89295 Deployed Sep 26, 2026 by tony via cleanup #13
docs-preview — 74e89295 Deployed Sep 26, 2026 by tony via publish-preview / publish #206
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant