Skip to content

Declare TypeScript type aliases and list the members they name - #205

Merged
tony merged 5 commits into
mainfrom
alias-declarations
Oct 27, 2026
Merged

tony merged 5 commits into
mainfrom
alias-declarations

Conversation

@tony

@tony tony commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

TypeScript type aliases had no declaration on their reference pages. For example, types.ConnectOptions is declared in libtmux-ts as export type ConnectOptions = ConnectionOptions; (types.ts), but its page showed only the summary: no type ConnectOptions = ConnectionOptions line, no link to ConnectionOptions, and none of its four properties.

Cause. The tree-sitter TypeScript spec read an alias's type field, but the grammar keeps the right-hand side in value, so all 93 TypeScript aliases in ts.json had an empty declaration.

Extraction (fix(api-model))

  • The spec reads value for aliases and stores the text in type, as the Rust and Julia extractors already do. Union and object text keeps its line breaks.
  • ts.json is regenerated at the same libtmux-ts revision (46cccfef). Only the type field of the 93 aliases changed; the symbol count is unchanged (945).
  • Rust's one alias (IndexedHooks) gains its declaration line from the same rendering. No other port changes.

Rendering (feat(site), fix(site))

  • aliasDeclaration in api-sections.ts builds type Name<T> = Value, rendered by ApiEntry.astro with type references linked, and by symbol-markdown.ts as a fenced block.
  • An alias whose right-hand side is one bare reference to another declaration lists that declaration's members under Members of ConnectionOptions, linking to their existing pages. No pages are added. The Markdown export carries the same heading and an "Alias of" line.
  • Only the alias page and its Markdown expand an alias (pageMembersOf). The sidebar, search tree and inventories keep each member under its one real owner.
  • Foo<T>, Foo[], Foo | null, typeof foo and Foo["bar"] do not resolve; a name declared in two modules resolves to the alias's own module, or to nothing when ambiguous. Member resolution applies to TypeScript only.

Checks

  • api-model 1192 passed; site vitest 6296 passed; type-check 0 errors; lint clean.
  • New tests in site/test/type-alias-declaration.test.ts and packages/api-model/test/typescript-aliases.test.ts run on the committed model. Reverting each fix (the model, member-order.ts, ApiEntry.astro, symbol-markdown.ts, the spec) fails its tests; a tree test asserts every member id has exactly one owner.
  • Browser checks --reference-layout, --api-sticky, --api-signatures, --type-parameters, --member-bodies and --reference-previews passed locally. The full check-dev.mjs run shows only the two Lua guide 404s that origin/main shows in the same local setup (guides not staged).
  • An independent review found that alias members leaked into the sidebar and search tree; fixed in e40d5f918 with the one-owner test.

Tool use: Claude Code wrote the brief and this pull request. A Sonnet sub-agent wrote the code and tests, and independent Sonnet reviewers checked it. The maintainer reviews it before merge.

tony added 4 commits October 25, 2026 22:26
why: A TypeScript `type_alias_declaration` keeps its right-hand side in
the grammar's `value` field, and the shared extractor only read `type`.
All 93 aliases in ts.json therefore had no `type` and no signature, so
their pages showed no declaration. `ConnectOptions` in libtmux-ts is
`type ConnectOptions = ConnectionOptions` and had nothing to link.

what:
- Read `value` for a `typealias` member when it has no `type` field,
  keeping the text as written (comments removed, indentation trimmed).
- Regenerate site/src/data/api/ts.json at libtmux-ts 46cccfef, the
  revision the committed model records. Only the `type` field of the
  93 `typealias` symbols changes.
- Test the extracted text for a reference, a union, an object type and
  a generic alias.
why: An alias page showed neither its declaration nor the members of
the type it names. https://libtmux.org/en/ts/latest/reference/types-connectoptions/
did not follow `type ConnectOptions = ConnectionOptions` to the four
properties of `ConnectionOptions`.

what:
- Render `type Name<T> = Value` for TypeScript and Rust aliases that
  record a type, linking each type reference and keeping the line
  breaks of a union or object type. HTML and Markdown share
  `aliasDeclaration`.
- Add `aliasTarget` to api-model: an alias whose right-hand side is one
  bare reference, in its own module or unique in the model, resolves to
  that declaration. A union, object type or applied generic does not.
- `membersOf` lists the target's members on the alias page for
  TypeScript, following alias chains and stopping on cycles. Each row
  is the target's own symbol marked `inheritedFrom`, so it links to the
  existing member page and no page is added. The Markdown export lists
  them under "Inherited members" and names the target in "Alias of".
- Give python-layout's ApiEntry fragment the `alias` binding the
  template now reads.
- Test the declaration, the link, the four members in HTML and
  Markdown, and union and object-type controls on committed data.
why: An alias is another name for its target, not a subtype. The page
labelled the target's properties "Inherited members", with a "Reached
through" line and an "inherited" badge on each row.

what:
- `membersOf` lists the target's members on an alias page without
  `inheritedFrom`; a member the target itself inherits stays marked.
- Add `aliasMembersTarget` so the HTML page and the Markdown export
  agree on when an alias lists a target's members.
- Head the section "Members of `ConnectionOptions`" with the target
  linked, in HTML and Markdown. Rows still link to the existing pages.
- Update the tests; they fail with the old heading.
why: `membersOf` expanded an alias to its target's members for every
caller. `membersByTypeFor` calls it for each owner, and a type alias is
an owner kind, so the reference tree gave `types.ConnectOptions` the
four `ConnectionOptions` rows. The sidebar catalog assigns one parent
per member id, last owner wins, so a member's page could open under
the alias, and the sidebar and search tree listed members twice.

what:
- Restore `membersOf` to the members a symbol declares.
- Add `pageMembersOf`, which also expands an alias, and call it only
  from the type page and its Markdown export.
- Test that the ts reference tree gives each member id one owner, that
  the alias has no member rows, and that the sidebar owner of a
  `ConnectionOptions` member is `ConnectionOptions`. They fail when
  `membersOf` expands aliases again.
- Test that `Foo<T>`, `Foo[]`, `Foo | null`, `typeof foo` and
  `Foo["bar"]` do not resolve, and that a name declared in two modules
  resolves to the alias's own module or to nothing.
why: Rendering alias right-hand sides put identifiers that TypeScript
owns into plain `api-punct` spans, which check-type-links counts. CI
for train #207 measured ts at 41 plain names against a ceiling of 18:
`is`, `in`, mapped-type bindings (`Key`, `K`) and the computed key
`tmuxIdBrand`. A type's own bindings and keywords are not references,
and no name list or exemption is allowed.

what:
- In `linkType` for ts, mark `is`, `in`, `as` and `asserts` as
  keywords unless a field is called that.
- Mark names bound inside the type text, `[Key in Keys]` and
  `infer Item`, and the subject of a type predicate, as declarations.
- Mark a computed member key, `readonly [brand]: Kind`, and a method
  signature in an object type, `execute(request): Result`, as the
  member they declare, and `true` and `false` as syntax.
- Test the roles on a fixture, and on the real committed aliases that
  rendered plain; both fail without the change.
@tony
tony merged commit 35791fd into main Oct 27, 2026
tony added a commit that referenced this pull request Oct 27, 2026
…ublishing (#207)

why: main's push deploy at 8d14bb3 failed because composing
objects-full.inv required every port's default version to have a
published targets.json. The site still offered a stable channel that no
libtmux release stands behind, the 0.1.0 releases were undocumented,
TypeScript aliases had no declaration, and tmux links sat in rows. These
eight reviewed changes ship together so one CI run gates them and one
deploy wave publishes them.

what:
- #206: compose falls back to a port's latest catalog when its default
  has none and lists a port with neither as missing, so the root site
  publishes; only a 404 counts as absent
- #202: tmux and cross-port links get their own sections on API
  reference pages, in HTML and the Markdown export
- #205: TypeScript type aliases show their declaration and the members
  of the type they name, with type syntax in its grammar role (6 plain
  type names, from 18)
- #204: PowerShell's .NET dependency is navigated at 0.1.0
- #200: the site documents the 0.1.0 releases and drops stable from its
  wording
- #201: the stable docs channel is removed; latest pages canonicalise to
  the newest final tag
- #208: sidebar guide lines and bucket-heading weight apply in every
  layout, and the glossary is the last row and the last search result
- #209: native documentation sidebars show the Sphinx toctree

Each PR is merged on this branch with its own "Title (#N)" merge
commit; the conflict resolutions are recorded in the PR body.
@tony
tony temporarily deployed to docs-preview-cleanup October 27, 2026 02:12 — with GitHub Actions Inactive
tony added a commit to libtmux/libtmux-ts that referenced this pull request Oct 28, 2026
why: The site still presented libtmux as an alpha: badges, notices,
install commands and examples carried alpha pins and prerelease flags,
and a docs channel stood for a release state that no libtmux release
has. A Sphinx project had no inventory to link to, tmux commands and
cross-port links sat in small rows under each declaration, TypeScript
aliases showed no declaration, and native Python documentation pages
listed every page in one flat sidebar column.

what:
- Publish `objects.inv` and `targets.json` at the root of each port
  version, naming the pages, headings, workspace table rows, MCP schema
  fields, command options and API declarations the build rendered, and
  stop the build when an API declaration has no rendered target
  (`inventory.ts`, `inventory-publisher.ts`, `inventory-targets.ts`,
  `targets.ts`; libtmux/docs#166)
- Link the footer of a port page to the inventory of its port version,
  to the full inventory and to a guide on linking from Sphinx, and list
  the same inventory and target files in the `docs.json` manifest
  (`SiteFooter.astro`, `inventory-links.ts`, `docs.json.ts`;
  libtmux/docs#166)
- Export the rows of the shared workspace command and configuration
  tables as Sphinx option, setting and environment variable targets, and
  keep a page's identity across a move through `inventoryId` and
  `inventoryAliases` in its frontmatter (`rehype-row-anchors.ts`,
  `load.md`, `panes.md`, `environment.md`, `content.config.ts`;
  libtmux/docs#166)
- Link the AI policy, which the root site publishes at
  `/meta/ai-policy/`, from the footer (`SiteFooter.astro`,
  `ai-policy.md`; libtmux/docs#194)
- Show a final release on its badge as its series, 0.x for 0.1.0, with
  the line "Released; the API may change.", and replace the alpha notice
  with an early-release notice that returns once for a reader who
  dismissed it (`ports.ts`, `registry.json`, `PrereleaseNotice.astro`;
  libtmux/docs#200)
- Remove the stable docs channel: a release tag publishes at its own
  version, a prerelease also as `next`, and the newest final release tag
  is the default and indexed version, or `latest` while the port has
  none; an older tag pushed later does not take the default
  (`port-docs-identity.sh`, `publish-plan.mjs`, `gen-versions.mjs`,
  `versions.ts`; libtmux/docs#201)
- Leave a release-numbering label such as 0.1.N plain in prose instead
  of resolving it as an API name (`resolver.ts`; libtmux/docs#204)
- Give a symbol's tmux commands, tmux C declarations, hooks, options and
  formats, Guides and equivalents in other ports their own sections on
  its API reference page and in its Markdown export, ahead of Related
  types (`api-tmux-sections.ts`, `ApiTmuxSections.astro`,
  `ApiReference.astro`; libtmux/docs#202)
- Draw the nested guide line in every sidebar layout, set Grouped's
  group headings bold as Outline's are, and make the API glossary the
  last row of the reference sidebar and the last search result
  (`api-tree.css`, `ApiTree.astro`, `api-tree.ts`; libtmux/docs#208)
- Open the preview card of a glossary link only after the pointer rests
  on it for a second, and let Escape cancel a card that has not opened
  (`link-preview-browser.ts`; libtmux/docs#211)
- Let Tab move from the footer's inventory help link to the link in its
  tooltip at once (`SiteFooter.astro`; libtmux/docs#211)
- Set the title of an index-style reference page, such as API reference,
  in the sans face (`ApiReference.astro`; libtmux/docs#211)
- Read the right-hand side of a TypeScript type alias in the extractor,
  which had left it empty, and show the alias on its reference page as
  type Name = Value with its type references linked (`spec.ts`,
  `api-sections.ts`, `ApiEntry.astro`; libtmux/docs#205)
- List the members of the one declaration an alias names under Members
  of that declaration, linking their existing pages (`member-order.ts`,
  `ApiReference.astro`; libtmux/docs#205)
- Render TypeScript type syntax as syntax and not as unresolved type
  names: the is, in, as and asserts words, true and false, the names
  that in and infer bind, and the member names inside an object type
  (`link.ts`; libtmux/docs#205)
- Set the section titles of the MCP reference in the sans face, and keep
  its sidebar guide line under the parent label and not through the
  row's own text (`ProtocolReference.astro`, `api-tree.css`;
  libtmux/docs#211)

Shared source: libtmux/docs
From: 00045828e6457d142d58933f603665a2ead35811
To:   e1ab401f7d6fca5ac9c418bc6c77ca382320cd2e
tony added a commit to libtmux/libtmux-rs that referenced this pull request Oct 28, 2026
why: The site still presented libtmux as an alpha: badges, notices,
install commands and examples carried alpha pins and prerelease flags,
and a docs channel stood for a release state that no libtmux release
has. A Sphinx project had no inventory to link to, tmux commands and
cross-port links sat in small rows under each declaration, TypeScript
aliases showed no declaration, and native Python documentation pages
listed every page in one flat sidebar column.

what:
- Publish `objects.inv` and `targets.json` at the root of each port
  version, naming the pages, headings, workspace table rows, MCP schema
  fields, command options and API declarations the build rendered, and
  stop the build when an API declaration has no rendered target
  (`inventory.ts`, `inventory-publisher.ts`, `inventory-targets.ts`,
  `targets.ts`; libtmux/docs#166)
- Link the footer of a port page to the inventory of its port version,
  to the full inventory and to a guide on linking from Sphinx, and list
  the same inventory and target files in the `docs.json` manifest
  (`SiteFooter.astro`, `inventory-links.ts`, `docs.json.ts`;
  libtmux/docs#166)
- Export the rows of the shared workspace command and configuration
  tables as Sphinx option, setting and environment variable targets, and
  keep a page's identity across a move through `inventoryId` and
  `inventoryAliases` in its frontmatter (`rehype-row-anchors.ts`,
  `load.md`, `panes.md`, `environment.md`, `content.config.ts`;
  libtmux/docs#166)
- Link the AI policy, which the root site publishes at
  `/meta/ai-policy/`, from the footer (`SiteFooter.astro`,
  `ai-policy.md`; libtmux/docs#194)
- Show a final release on its badge as its series, 0.x for 0.1.0, with
  the line "Released; the API may change.", and replace the alpha notice
  with an early-release notice that returns once for a reader who
  dismissed it (`ports.ts`, `registry.json`, `PrereleaseNotice.astro`;
  libtmux/docs#200)
- Remove the stable docs channel: a release tag publishes at its own
  version, a prerelease also as `next`, and the newest final release tag
  is the default and indexed version, or `latest` while the port has
  none; an older tag pushed later does not take the default
  (`port-docs-identity.sh`, `publish-plan.mjs`, `gen-versions.mjs`,
  `versions.ts`; libtmux/docs#201)
- Leave a release-numbering label such as 0.1.N plain in prose instead
  of resolving it as an API name (`resolver.ts`; libtmux/docs#204)
- Give a symbol's tmux commands, tmux C declarations, hooks, options and
  formats, Guides and equivalents in other ports their own sections on
  its API reference page and in its Markdown export, ahead of Related
  types (`api-tmux-sections.ts`, `ApiTmuxSections.astro`,
  `ApiReference.astro`; libtmux/docs#202)
- Draw the nested guide line in every sidebar layout, set Grouped's
  group headings bold as Outline's are, and make the API glossary the
  last row of the reference sidebar and the last search result
  (`api-tree.css`, `ApiTree.astro`, `api-tree.ts`; libtmux/docs#208)
- Open the preview card of a glossary link only after the pointer rests
  on it for a second, and let Escape cancel a card that has not opened
  (`link-preview-browser.ts`; libtmux/docs#211)
- Let Tab move from the footer's inventory help link to the link in its
  tooltip at once (`SiteFooter.astro`; libtmux/docs#211)
- Set the title of an index-style reference page, such as API reference,
  in the sans face (`ApiReference.astro`; libtmux/docs#211)
- Show the typed fields of a Rust struct or payload variant in a Name,
  Type and Description table, beside the member list when the struct has
  methods (`api-sections.ts`, `ApiScalarMembers.astro`,
  `ApiReference.astro`; libtmux/docs#197)
- Add the crates of each Rust example with `cargo add` from crates.io at
  the workspace version the revision declares, instead of building from
  a clone, and state the minimum Rust version in place of a pinned
  toolchain file (`rust-examples.ts`; libtmux/docs#196)
- Install the Rust workspace CLI and MCP server with `cargo install` and
  no alpha version, and say on the workspace internals page that
  releases are numbered 0.1.N and any release may change the API
  (`ports.ts`, `install-matrix.ts`, `index.md`; libtmux/docs#200)
- Show a Rust type alias on its reference page as a declaration line,
  type Name = Value (`api-sections.ts`; libtmux/docs#205)
- Install the Rust MCP server with `tmux-mcp@0.1.0`, and depend on
  libtmux and tmux-mcp 0.1.0 in the MCP inspect-sessions example in
  place of git revisions (`connect-client.md`, `inspect-sessions.md`;
  libtmux/docs#212)
- Set the section titles of the MCP reference in the sans face, and keep
  its sidebar guide line under the parent label and not through the
  row's own text (`ProtocolReference.astro`, `api-tree.css`;
  libtmux/docs#211)

Shared source: libtmux/docs
From: 00045828e6457d142d58933f603665a2ead35811
To:   e1ab401f7d6fca5ac9c418bc6c77ca382320cd2e

This branch was previously deployed

1 inactive deployment
docs-preview-cleanup — 4acf6320 Deployed Oct 27, 2026 by tony via cleanup #182
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