diff --git a/packages/api-model/src/capabilities.ts b/packages/api-model/src/capabilities.ts new file mode 100644 index 00000000..641fdb17 --- /dev/null +++ b/packages/api-model/src/capabilities.ts @@ -0,0 +1,197 @@ +/** + * Capability manifests: what each port's typed `support.capabilities` registry + * says it can do on each tmux release, as the port itself serializes it. + * + * A port never writes this file by hand. Its own build emits it from the + * registry the library refuses with, and its own drift test fails when the + * two disagree. The site reads the manifest from the same checkout and + * revision as that port's API model, resolves every API name in it through + * the model, and computes each table cell from the release fields. Nothing + * here is a list somebody keeps in step. + */ + +export const CAPABILITY_SCHEMA = 'libtmux-capabilities/1' + +/** A tmux command, and the flags of it a capability depends on. */ +export interface CapabilityCommand { + command: string + flags?: string[] +} + +/** How a library behaves where the capability is not available. */ +export type Handling = 'refuse' | 'fallback' | 'repair' + +/** One positive capability, as the port's registry declares it. */ +export interface CapabilityEntry { + /** Stable id shared by every port (`control-mode`, `buffer-delete-named`). */ + id: string + /** Short name for headings. */ + name: string + /** One sentence: what a caller can do with it. */ + summary: string + /** The first tmux release it works on. */ + since: string + /** Exact releases at or above `since` where it does not work. */ + except?: string[] + /** What the library does below `since` or on an excepted release. */ + handling: Handling + /** The API name of the error a refusal raises. Required when `handling` is `refuse`. */ + error?: string + /** Public API names that need this capability, as the port's API model names them. */ + apis: string[] + /** tmux commands the capability concerns. */ + commands: CapabilityCommand[] +} + +/** A release-specific defect the library works around. Not a capability. */ +export interface Workaround { + id: string + name: string + summary: string + /** Exact releases the workaround applies to. */ + releases: string[] + handling: Exclude + apis: string[] + commands: CapabilityCommand[] +} + +/** The floor from the port's `support.versions`. */ +export interface Floor { + minimum: string +} + +export interface CapabilityManifest { + schema: typeof CAPABILITY_SCHEMA + /** The site's port slug. */ + port: string + floor: Floor + capabilities: CapabilityEntry[] + workarounds: Workaround[] +} + +/** A version tmux has printed: `X.Y`, `X.Ya`, `X.Y-rc`, `X.Y-rcN` or `next-X.Y`. */ +const VERSION = /^(?:next-(0|[1-9]\d*)\.(0|[1-9]\d*)|(0|[1-9]\d*)\.(0|[1-9]\d*)([a-z]?)(?:-rc(\d*))?)$/ + +/** A sortable key in tmux's own order: next-X.Y < X.Y-rc < X.Y-rcN < X.Y < X.Ya. */ +export function tmuxVersionKey(version: string): number[] { + const m = VERSION.exec(version) + if (!m) throw new TypeError(`not a version tmux prints: ${JSON.stringify(version)}`) + if (m[1] !== undefined) return [Number(m[1]), Number(m[2]), 0, 0, 0] + const letter = m[5] ? m[5].charCodeAt(0) - 96 : 0 + if (m[6] !== undefined) { + if (letter) throw new TypeError(`a candidate carries no patch letter: ${JSON.stringify(version)}`) + return [Number(m[3]), Number(m[4]), 1, m[6] === '' ? 0 : Number(m[6]), 0] + } + return [Number(m[3]), Number(m[4]), 2, 0, letter] +} + +export function compareTmuxVersions(a: string, b: string): number { + const ka = tmuxVersionKey(a) + const kb = tmuxVersionKey(b) + for (let i = 0; i < ka.length; i++) if (ka[i] !== kb[i]) return ka[i] - kb[i] + return 0 +} + +/** What a library does with a capability on one release. */ +export type CellState = 'supported' | 'workaround' | 'fallback' | 'refused' | 'repaired' + +export function capabilityState(entry: CapabilityEntry, release: string): CellState { + const available = compareTmuxVersions(release, entry.since) >= 0 && !(entry.except ?? []).includes(release) + if (available) return 'supported' + if (entry.handling === 'fallback') return 'fallback' + if (entry.handling === 'repair') return 'repaired' + return 'refused' +} + +export function workaroundState(entry: Workaround, release: string): CellState { + if (!entry.releases.includes(release)) return 'supported' + return entry.handling === 'repair' ? 'workaround' : 'refused' +} + +const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/ + +function isString(v: unknown): v is string { + return typeof v === 'string' && v.length > 0 +} + +function checkVersion(errors: string[], where: string, v: unknown): void { + if (!isString(v)) { + errors.push(`${where}: expected a tmux version`) + return + } + try { + tmuxVersionKey(v) + } catch (e) { + errors.push(`${where}: ${(e as Error).message}`) + } +} + +function checkCommands(errors: string[], where: string, v: unknown): void { + if (!Array.isArray(v)) { + errors.push(`${where}: expected an array of commands`) + return + } + v.forEach((c, i) => { + if (!c || typeof c !== 'object' || !isString((c as CapabilityCommand).command)) { + errors.push(`${where}[${i}]: expected { command, flags? }`) + return + } + const flags = (c as CapabilityCommand).flags + if (flags !== undefined && (!Array.isArray(flags) || !flags.every((f) => /^-[A-Za-z]$/.test(f)))) { + errors.push(`${where}[${i}].flags: expected single-letter flags such as "-b"`) + } + }) +} + +function checkNames(errors: string[], where: string, v: unknown): void { + if (!Array.isArray(v) || !v.every(isString)) errors.push(`${where}: expected an array of API names`) +} + +/** + * Validate a manifest without a schema library. Every problem is reported, so + * a port fixing its emitter sees the whole list at once. + */ +export function validateManifest(value: unknown): { manifest?: CapabilityManifest; errors: string[] } { + const errors: string[] = [] + const m = value as Partial | null + if (!m || typeof m !== 'object') return { errors: ['manifest: expected an object'] } + if (m.schema !== CAPABILITY_SCHEMA) errors.push(`schema: expected "${CAPABILITY_SCHEMA}"`) + if (!isString(m.port)) errors.push('port: expected the site port slug') + checkVersion(errors, 'floor.minimum', m.floor?.minimum) + const ids = new Set() + const seen = (where: string, id: unknown) => { + if (!isString(id) || !ID.test(id)) errors.push(`${where}.id: expected a kebab-case id`) + else if (ids.has(id)) errors.push(`${where}.id: "${id}" appears twice`) + else ids.add(id) + } + if (!Array.isArray(m.capabilities)) errors.push('capabilities: expected an array') + else { + m.capabilities.forEach((c, i) => { + const at = `capabilities[${i}]` + seen(at, c?.id) + if (!isString(c?.name)) errors.push(`${at}.name: expected a name`) + if (!isString(c?.summary)) errors.push(`${at}.summary: expected a sentence`) + checkVersion(errors, `${at}.since`, c?.since) + ;(c?.except ?? []).forEach((r, j) => checkVersion(errors, `${at}.except[${j}]`, r)) + if (!['refuse', 'fallback', 'repair'].includes(c?.handling as string)) errors.push(`${at}.handling: expected refuse, fallback or repair`) + if (c?.handling === 'refuse' && !isString(c?.error)) errors.push(`${at}.error: a refusal names its error type`) + checkNames(errors, `${at}.apis`, c?.apis) + checkCommands(errors, `${at}.commands`, c?.commands) + }) + } + if (!Array.isArray(m.workarounds)) errors.push('workarounds: expected an array') + else { + m.workarounds.forEach((w, i) => { + const at = `workarounds[${i}]` + seen(at, w?.id) + if (!isString(w?.name)) errors.push(`${at}.name: expected a name`) + if (!isString(w?.summary)) errors.push(`${at}.summary: expected a sentence`) + if (!Array.isArray(w?.releases) || w.releases.length === 0) errors.push(`${at}.releases: expected at least one release`) + else w.releases.forEach((r, j) => checkVersion(errors, `${at}.releases[${j}]`, r)) + if (!['refuse', 'repair'].includes(w?.handling as string)) errors.push(`${at}.handling: expected refuse or repair`) + checkNames(errors, `${at}.apis`, w?.apis) + checkCommands(errors, `${at}.commands`, w?.commands) + }) + } + return errors.length ? { errors } : { manifest: m as CapabilityManifest, errors } +} diff --git a/packages/api-model/src/index.ts b/packages/api-model/src/index.ts index 78809ba6..2980c112 100644 --- a/packages/api-model/src/index.ts +++ b/packages/api-model/src/index.ts @@ -28,3 +28,17 @@ export { parentInventory } from './parent-inventory.ts' export { navSidecarFor, type NavConfig } from './nav-sidecar.ts' export { parsePythonDoc } from './doc/python.ts' +export { + CAPABILITY_SCHEMA, + capabilityState, + compareTmuxVersions, + tmuxVersionKey, + validateManifest, + workaroundState, + type CapabilityCommand, + type CapabilityEntry, + type CapabilityManifest, + type CellState, + type Handling, + type Workaround, +} from './capabilities.ts' diff --git a/packages/api-model/test/capabilities.test.ts b/packages/api-model/test/capabilities.test.ts new file mode 100644 index 00000000..7626f1c3 --- /dev/null +++ b/packages/api-model/test/capabilities.test.ts @@ -0,0 +1,103 @@ +import { describe, expect, it } from 'vitest' +import { + CAPABILITY_SCHEMA, + capabilityState, + compareTmuxVersions, + validateManifest, + workaroundState, + type CapabilityEntry, + type Workaround, +} from '../src/capabilities.ts' + +const control: CapabilityEntry = { + id: 'control-mode', + name: 'Control mode', + summary: 'Attach a library-managed control client.', + since: '3.7', + handling: 'fallback', + apis: ['libtmux.Server.observe'], + commands: [{ command: 'attach-session', flags: ['-C'] }], +} + +const runShell: CapabilityEntry = { + id: 'run-shell-capture', + name: 'Captured run-shell output', + summary: 'Read the standard output of run-shell.', + since: '3.3a', + except: ['3.4'], + handling: 'refuse', + error: 'libtmux.CapabilityUnavailable', + apis: ['libtmux.Server.run_shell'], + commands: [{ command: 'run-shell' }], +} + +const breakPane: Workaround = { + id: 'break-pane-exact-3-7', + name: 'break-pane on 3.7', + summary: 'Exact 3.7 ignores the name given to break-pane; a rename follows.', + releases: ['3.7'], + handling: 'repair', + apis: ['libtmux.Pane.break_out'], + commands: [{ command: 'break-pane', flags: ['-n'] }], +} + +const manifest = { + schema: CAPABILITY_SCHEMA, + port: 'py', + floor: { minimum: '3.3a' }, + capabilities: [control, runShell], + workarounds: [breakPane], +} + +describe('tmux version order', () => { + it('ranks development builds and candidates below the release they name', () => { + const ordered = ['next-3.7', '3.7-rc', '3.7-rc3', '3.7', '3.7a', '3.8', 'next-3.9', '3.10'] + expect([...ordered].reverse().sort(compareTmuxVersions)).toEqual(ordered) + }) + + it('refuses forms tmux never prints', () => { + for (const v of ['master', '3.3a-master', 'next-3.3a', '3.3a-rc1', '03.3a', 'openbsd-7.6']) { + expect(() => compareTmuxVersions(v, '3.3a'), v).toThrow(TypeError) + } + }) +}) + +describe('cells', () => { + it('follows since, except and handling', () => { + expect(capabilityState(control, '3.6')).toBe('fallback') + expect(capabilityState(control, '3.7')).toBe('supported') + expect(capabilityState(control, '3.7-rc')).toBe('fallback') + expect(capabilityState(runShell, '3.3a')).toBe('supported') + expect(capabilityState(runShell, '3.4')).toBe('refused') + expect(capabilityState(runShell, '3.5')).toBe('supported') + }) + + it('marks only the releases a workaround names', () => { + expect(workaroundState(breakPane, '3.7')).toBe('workaround') + expect(workaroundState(breakPane, '3.7a')).toBe('supported') + }) +}) + +describe('validateManifest', () => { + it('accepts a complete manifest', () => { + const { manifest: m, errors } = validateManifest(manifest) + expect(errors).toEqual([]) + expect(m?.capabilities.map((c) => c.id)).toEqual(['control-mode', 'run-shell-capture']) + }) + + const broken: [string, unknown, string][] = [ + ['wrong schema', { ...manifest, schema: 'libtmux-capabilities/0' }, 'schema'], + ['unprintable floor', { ...manifest, floor: { minimum: 'master' } }, 'floor.minimum'], + ['duplicate id', { ...manifest, workarounds: [{ ...breakPane, id: 'control-mode' }] }, 'appears twice'], + ['refusal without an error type', { ...manifest, capabilities: [{ ...runShell, error: undefined }] }, 'names its error type'], + ['non-kebab id', { ...manifest, capabilities: [{ ...control, id: 'ControlMode' }] }, 'kebab-case'], + ['bad since', { ...manifest, capabilities: [{ ...control, since: '3.7-dev' }] }, 'since'], + ['bad flag', { ...manifest, capabilities: [{ ...control, commands: [{ command: 'attach-session', flags: ['C'] }] }] }, 'flags'], + ['empty workaround', { ...manifest, workarounds: [{ ...breakPane, releases: [] }] }, 'releases'], + ] + it.each(broken)('rejects a manifest with %s', (_label, value, message) => { + const { manifest: m, errors } = validateManifest(value) + expect(m).toBeUndefined() + expect(errors.join('\n')).toContain(message) + }) +}) diff --git a/scripts/gen-capabilities.mjs b/scripts/gen-capabilities.mjs new file mode 100644 index 00000000..8091fadd --- /dev/null +++ b/scripts/gen-capabilities.mjs @@ -0,0 +1,149 @@ +#!/usr/bin/env node +/** + * Read each port's capability manifest and write site/src/data/capabilities.json. + * + * A port's `capabilities.json` is emitted by that port from the typed + * `support.capabilities` registry its library refuses with, and the port's own + * drift test keeps the two equal. This script does not interpret prose or + * keep a table: it validates each manifest, resolves every API name in it + * through the port's generated API model, and records the tmux releases the + * matrix columns come from. A name that does not resolve fails the run, so a + * renamed method cannot leave a capability pointing at nothing. + * + * Releases come from tmux's own refs: final tags, the version a release + * branch names in `configure.ac` (3.7d shipped from a branch before it was + * tagged), and the `next-X.Y` that master names. Only releases at or above the + * lowest floor any manifest declares are kept. + * + * Usage: node scripts/gen-capabilities.mjs [--port ] [--manifest =] + * [--tmux ] [--out ] [--check] + */ +import { execFileSync } from 'node:child_process' +import { existsSync, readFileSync, writeFileSync } from 'node:fs' +import { homedir } from 'node:os' +import { dirname, join, resolve } from 'node:path' +import { fileURLToPath } from 'node:url' +import { PORTS } from '../site/src/lib/ports.ts' +import { SymbolIndex } from '../packages/api-model/src/link.ts' +import { compareTmuxVersions, tmuxVersionKey, validateManifest } from '../packages/api-model/src/capabilities.ts' + +const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..') +const args = process.argv.slice(2) +const value = (flag, fallback) => (args.includes(flag) ? args[args.indexOf(flag) + 1] : fallback) +const values = (flag) => args.flatMap((a, i) => (a === flag ? [args[i + 1]] : [])) +const expand = (p) => (p.startsWith('~/') ? join(homedir(), p.slice(2)) : p) +const checking = args.includes('--check') +const only = value('--port') +const out = resolve(value('--out', join(repoRoot, 'site/src/data/capabilities.json'))) +const tmuxCheckout = expand(value('--tmux', '~/study/c/tmux')) +const modelDir = resolve(value('--models', join(repoRoot, 'site/src/data/api'))) + +/** `--manifest py=path/to/capabilities.json` overrides where a port's manifest is read. */ +const overrides = Object.fromEntries(values('--manifest').map((pair) => pair.split('='))) + +/** The manifest sits at the root of the port's checkout, emitted and drift-checked there. */ +function manifestPath(port) { + return overrides[port.slug] ?? join(expand(port.checkout), 'capabilities.json') +} + +function git(...a) { + return execFileSync('git', ['-C', tmuxCheckout, ...a], { encoding: 'utf8' }).trim() +} + +/** Every tmux release a reader can run, from tmux's own refs. */ +function tmuxReleases() { + const versions = new Set() + const add = (v) => { + try { + tmuxVersionKey(v) + versions.add(v) + } catch { + // A ref that names something tmux never prints (a topic branch) is not a release. + } + } + for (const tag of git('tag', '-l').split('\n')) if (/^\d+\.\d+[a-z]?$/.test(tag)) add(tag) + const refs = git('for-each-ref', '--format=%(refname:short)', 'refs/remotes').split('\n') + const named = (ref) => /AC_INIT\(\[tmux\], ([^)]+)\)/.exec(git('show', `${ref}:configure.ac`))?.[1] + for (const ref of refs.filter((r) => /\/release_[\d.]+[a-z]?$/.test(r))) { + const v = named(ref) + if (v && /^\d+\.\d+[a-z]?$/.test(v)) add(v) + } + const master = refs.find((r) => r === 'upstream/master') ?? refs.find((r) => r === 'origin/master') + const next = master && named(master) + if (next?.startsWith('next-')) add(next) + return [...versions].sort(compareTmuxVersions) +} + +/** Resolve a manifest's API name to the public id the reference pages use. */ +function resolver(slug) { + const file = join(modelDir, `${slug}.json`) + if (!existsSync(file)) return undefined + const model = JSON.parse(readFileSync(file, 'utf8')) + const index = new SymbolIndex(model.symbols, () => '', slug) + return (name) => { + const target = index.resolve(name) + return target?.symbol ? (target.symbol.publicId ?? target.symbol.id) : undefined + } +} + +const errors = [] +const ports = {} +for (const port of PORTS) { + if (only && port.slug !== only) continue + const path = manifestPath(port) + if (!existsSync(path)) continue + const { manifest, errors: invalid } = validateManifest(JSON.parse(readFileSync(path, 'utf8'))) + if (!manifest) { + errors.push(...invalid.map((e) => `${port.slug}: ${e}`)) + continue + } + if (manifest.port !== port.slug) errors.push(`${port.slug}: manifest names port "${manifest.port}"`) + const resolve = resolver(port.slug) + if (!resolve) { + errors.push(`${port.slug}: no API model at ${join(modelDir, `${port.slug}.json`)}; run gen-api-model first`) + continue + } + const link = (where, name) => { + const id = resolve(name) + if (!id) errors.push(`${port.slug}: ${where} names "${name}", which is not in the API model`) + return id ?? name + } + const entries = (list, kind) => list.map((e) => ({ + ...e, + apis: e.apis.map((name) => link(`${kind} ${e.id}`, name)), + ...(e.error ? { error: link(`${kind} ${e.id} error`, e.error) } : {}), + })) + ports[port.slug] = { + revision: (() => { + try { + return execFileSync('git', ['-C', dirname(path), 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() + } catch { + return undefined + } + })(), + floor: manifest.floor, + capabilities: entries(manifest.capabilities, 'capability'), + workarounds: entries(manifest.workarounds, 'workaround'), + } +} + +if (errors.length) { + console.error(errors.join('\n')) + process.exit(1) +} + +const floors = Object.values(ports).map((p) => p.floor.minimum) +const lowest = floors.sort(compareTmuxVersions)[0] +const releases = lowest ? tmuxReleases().filter((v) => compareTmuxVersions(v, lowest) >= 0) : [] +const data = `${JSON.stringify({ generated: 'scripts/gen-capabilities.mjs', releases, ports }, null, 2)}\n` + +if (checking) { + const current = existsSync(out) ? readFileSync(out, 'utf8') : '' + if (current !== data) { + console.error(`${out} is stale; run node scripts/gen-capabilities.mjs`) + process.exit(1) + } +} else { + writeFileSync(out, data) + console.log(`wrote ${out}: ${Object.keys(ports).length} ports, ${releases.length} releases`) +} diff --git a/scripts/test-all.sh b/scripts/test-all.sh index f5cbbc02..a3a07570 100755 --- a/scripts/test-all.sh +++ b/scripts/test-all.sh @@ -147,6 +147,12 @@ node scripts/gen-shell-ports.negative.mjs step 'mcp tool matrix' node scripts/gen-mcp-tools.mjs --check +# /reference/capabilities/ and the per-command tables are generated from each +# port's capabilities.json, which the port emits from its typed registry. +# Every API name in a manifest must resolve in that port's model. +step 'capability manifests' +node scripts/gen-capabilities.mjs --check + # Each port's own MCP server, built and run to compare its live tool, # resource and prompt schemas against the committed snapshot in # site/src/data/mcp-protocol/. Skips when the sibling checkouts are absent, diff --git a/site/src/components/api/ApiCapabilities.astro b/site/src/components/api/ApiCapabilities.astro new file mode 100644 index 00000000..52170ba5 --- /dev/null +++ b/site/src/components/api/ApiCapabilities.astro @@ -0,0 +1,136 @@ +--- +/** + * tmux capabilities, generated from each port's own registry. + * + * In a port build: that port's capabilities against every tmux release from + * its floor, with the API each one gates. In the root build: one map of every + * capability against every port that publishes a manifest. No row or cell is + * written here; see site/src/lib/capabilities.ts. + */ +import CapabilityMatrix from '../capabilities/CapabilityMatrix.astro' +import DocsLayout from '../../layouts/DocsLayout.astro' +import { DEFAULT_LOCALE, localeRoot } from '../../i18n/locales' +import { CONTRIBUTE_BRANCH, CONTRIBUTE_REPO } from '../../i18n/contribute' +import { PORT_BY_SLUG, portPageUrl, referenceUrl } from '../../lib/ports' +import { buildTarget } from '../../lib/versions' +import { tmuxCommandSources } from '../../lib/tmux-reference' +import { + capabilityFloor, + capabilityPorts, + capabilityRevision, + mapRows, + portColumns, + portRows, + releaseGroups, + type Row, +} from '../../lib/capabilities' + +interface Props { port?: string; version?: string } +const { port, version = buildTarget(process.env).version } = Astro.props as Props +const name = port ? PORT_BY_SLUG[port].name : 'libtmux' +const library = port ? PORT_BY_SLUG[port].projectName : 'libtmux' +const referenceBase = port ? referenceUrl(PORT_BY_SLUG[port], version, 'core') : `${localeRoot(DEFAULT_LOCALE)}reference/` +const pagePath = 'reference/capabilities' +const pageUrl = `${referenceBase}capabilities/` +const title = port ? `${library} tmux capabilities` : 'tmux capabilities' +const description = port + ? `What ${library} can do on each tmux release, generated from its capability registry.` + : 'What each libtmux port can do on each tmux release, generated from each port\'s capability registry.' + +const floor = port ? capabilityFloor(port) : undefined +const revision = port ? capabilityRevision(port) : undefined +const { capabilities, workarounds } = port ? portRows(port) : { capabilities: mapRows(), workarounds: [] as Row[] } +const published = capabilityPorts() +const commandHref = (command: string) => tmuxCommandSources('latest', command)[0]?.href + +const sections = [...capabilities, ...workarounds] +const headings = [ + ...(capabilities.length ? [{ depth: 2, slug: 'capabilities', text: 'Capabilities' }] : []), + ...(workarounds.length ? [{ depth: 2, slug: 'workarounds', text: 'Release workarounds' }] : []), + ...sections.map((r) => ({ depth: 3, slug: r.id, text: r.label })), +] +--- + + + {port && floor ? ( +

+ {library} (libtmux for {name}) requires tmux {floor} or newer. Each capability below needs a newer + tmux release, or avoids one release. Before it sends a command, {library} checks the version of + the running tmux server. The tables and every link on this page are generated from the library's + capability registry{revision && <> at {revision.slice(0, 12)}}. +

+ ) : !port && published.length > 0 ? ( +

+ Every libtmux port supports tmux from its floor up. Each capability below needs a newer release on + some ports; a cell gives the release a port needs. Rows and cells are generated from each port's + capability registry, so a port appears here once it publishes one. +

+ ) : null} + + {published.length === 0 ? ( +

No port publishes a capability registry on this build yet.

+ ) : port && !floor ? ( +

{library} does not publish a capability registry on this build yet.

+ ) : ( + <> +

Capabilities

+ + {workarounds.length > 0 && ( + <> +

Release workarounds

+

A tmux release that gets one command wrong. {library} repairs the result, or refuses the call, on that release only.

+ + + )} + {sections.map((row) => ( +
+

{row.label}

+

{row.summary}

+
+
tmux
+
{row.requirement}
+ {row.error && (<>
Refusal
{row.error.href ? {row.error.label} : {row.error.label}}
)} + {row.apis.length > 0 && ( + <> +
API
+
{row.apis.map((api) => api.href ? {api.label} : {api.label})}
+ + )} + {row.commands.length > 0 && ( + <> +
Commands
+
{row.commands.map((c) => { + const href = commandHref(c.command) + const text = [c.command, ...(c.flags ?? [])].join(' ') + return href ? {text} : {text} + })}
+ + )} +
+
+ ))} + + )} + diff --git a/site/src/components/api/ApiReference.astro b/site/src/components/api/ApiReference.astro index c2287e0f..50d5586b 100644 --- a/site/src/components/api/ApiReference.astro +++ b/site/src/components/api/ApiReference.astro @@ -21,6 +21,9 @@ import { pagePortsFor } from '../../lib/page-ports-for' import { pageBreadcrumbs } from '../../lib/sidebar' import BaseLayout from '../../layouts/BaseLayout.astro' import { withRoot } from '../../lib/site-root' +import CommandSupport from '../capabilities/CommandSupport.astro' +import { commandRows } from '../../lib/capabilities' +import { tmuxSourceCommands } from '../../lib/tmux-reference' import { API_MODELS, API_NAV, PORT_NAME, indexFor, isMemberOwner, ownersOf, pageSlug, referenceAlternatives, topLevelTypesOf } from '../../lib/api-models' import { PORT_BY_SLUG, referenceUrl } from '../../lib/ports' import { productApiHref } from '../../lib/product-api' @@ -357,6 +360,9 @@ const pageSections: ApiSection[] = glossary ? apiGlossaryHeadings(glossaryContex ...(otherInherited.length ? [{ id: 'api-inherited', label: 'Inherited members', count: otherInherited.length }] : []), ] : [] const relationshipSections = owner && model ? apiRelationshipSections(model, owner) : [] +const tmuxCommandNames = source && owner ? tmuxSourceCommands(source.version, owner).map((command) => command.name) : [] +const supportedCommands = tmuxCommandNames.filter((name) => commandRows(name).length > 0) +if (supportedCommands.length) pageSections.push({ id: 'api-libtmux-support', label: 'Support in libtmux', count: supportedCommands.reduce((n, name) => n + commandRows(name).length, 0) }) const paths = (source?.paths ?? []).filter((path) => !owner || path.symbols.some((symbol) => symbol.id === owner.id)) if (relationshipSections.some((section) => ['api-calls', 'api-called-by'].includes(section.id))) pageSections.push({ id: 'api-call-network', label: 'Call neighborhood' }) if (paths.length) pageSections.push({ id: 'api-source-paths', label: 'Paths through the source', count: paths.length }) @@ -827,6 +833,7 @@ const bases = owner && 'extends' in owner ? owner.extends ?? [] : [] )} + {supportedCommands.map((name) => )} {related.length > 0 &&

Related types#

diff --git a/site/src/components/capabilities/CapabilityMatrix.astro b/site/src/components/capabilities/CapabilityMatrix.astro new file mode 100644 index 00000000..01b06466 --- /dev/null +++ b/site/src/components/capabilities/CapabilityMatrix.astro @@ -0,0 +1,84 @@ +--- +/** + * A map of capabilities against columns (tmux releases, or ports). + * + * Every column has the same width (`table-layout: fixed`), so the eye reads + * down a release and across a capability without text reflowing the grid. + * The first column stays put while the releases scroll. A cell carries an + * icon and, for screen readers, the same words the legend uses. + */ +import { CELL_LABEL, type Column, type Row } from '../../lib/capability-cells' + +interface Props { + caption: string + columns: Column[] + rows: Row[] + /** Width of each data column. Ports need more room for "3.7+" than releases need. */ + columnWidth?: 'narrow' | 'wide' + /** Heading of the first column. */ + rowHeader?: string +} + +const { caption, columns, rows, columnWidth = 'narrow', rowHeader = 'Capability' } = Astro.props as Props +const minimum = columnWidth === 'wide' ? '4.5rem' : '3.5rem' + +const ICON: Record = { + supported: '✓', + workaround: '◐', + repaired: '◐', + fallback: '↺', + refused: '✕', + absent: '–', +} + +const TONE: Record = { + supported: 'text-emerald-700 dark:text-emerald-400', + workaround: 'text-sky-700 dark:text-sky-400', + repaired: 'text-sky-700 dark:text-sky-400', + fallback: 'text-amber-700 dark:text-amber-400', + refused: 'text-rose-700 dark:text-rose-400', + absent: 'text-muted', +} +--- + +
+ + + + + {columns.map(() => )} + + + + + {columns.map((c) => ( + + ))} + + + + {rows.map((row) => ( + + + {row.cells.map((cell, i) => ( + + ))} + + ))} + +
{caption}
{rowHeader}{c.label}
+ {row.label} + + + {cell.text && } + {CELL_LABEL[cell.state]}{cell.text ? `, ${cell.text}` : ''} +
+
+ +
    + {(['supported', 'workaround', 'fallback', 'refused', 'absent'] as const) + .filter((s) => rows.some((r) => r.cells.some((c) => c.state === s || (s === 'workaround' && c.state === 'repaired')))) + .map((s) => ( +
  • {CELL_LABEL[s]}
    • + ))} +
diff --git a/site/src/components/capabilities/CommandSupport.astro b/site/src/components/capabilities/CommandSupport.astro new file mode 100644 index 00000000..8e94346d --- /dev/null +++ b/site/src/components/capabilities/CommandSupport.astro @@ -0,0 +1,24 @@ +--- +/** + * Which libtmux ports gate this tmux command, and on which releases. + * + * Rendered on the command's tmux reference page. Rows come from every port + * capability or workaround that names the command; nothing renders when no + * port publishes one. + */ +import CapabilityMatrix from './CapabilityMatrix.astro' +import { commandRows, portColumns } from '../../lib/capabilities' +import { DEFAULT_LOCALE, localeRoot } from '../../i18n/locales' + +interface Props { command: string } +const { command } = Astro.props as Props +const map = `${localeRoot(DEFAULT_LOCALE)}reference/capabilities/` +const rows = commandRows(command).map((row) => ({ ...row, href: `${map}#${row.id}` })) +--- +{rows.length > 0 && ( +
+

Support in libtmux#

+

Releases each libtmux port needs before it sends {command} for these features, from each port's capability registry.

+ +
+)} diff --git a/site/src/content/docs/guides/index.md b/site/src/content/docs/guides/index.md index b0c677a7..aca5f8bc 100644 --- a/site/src/content/docs/guides/index.md +++ b/site/src/content/docs/guides/index.md @@ -35,7 +35,7 @@ cards: body: Use isolated tmux servers and manage test cleanup. - label: tmux support href: tmux-support/ - body: Find the tmux release every port requires and how an older daemon is refused. + body: Find the tmux release every port requires and which features need a newer one. --- Use these guides to run tmux tasks from a terminal or a shell script. Start diff --git a/site/src/content/docs/guides/tmux-support.md b/site/src/content/docs/guides/tmux-support.md index 1d7c9b11..99c74029 100644 --- a/site/src/content/docs/guides/tmux-support.md +++ b/site/src/content/docs/guides/tmux-support.md @@ -1,7 +1,7 @@ --- supportedPorts: [] title: tmux support -description: The tmux release every libtmux port requires and how a library refuses an older daemon. +description: The tmux release every libtmux port requires, how a library refuses an older daemon, and which optional features need a newer release. sidebar: label: tmux support group: Guides @@ -11,7 +11,8 @@ tableOfContents: true Every libtmux port, the MCP servers and the workspace builders support tmux 3.3a and newer. A daemon older than 3.3a is refused before the requested -operation has any effect. +operation has any effect. A few optional features need a newer release; each +one is refused on its own and does not raise the minimum for anything else. ## The core minimum @@ -46,3 +47,32 @@ The check assumes tmux's built-in commands keep their meaning. A [`command-alias`](/tmux/latest/manual/full/#OPTIONS) that redefines a built-in command the library uses to identify or guard the daemon is outside this guarantee, as are the contents of user-written aliases and shell programs a library only forwards. + +## Optional features + +Some operations depend on behavior that only newer releases have, or that a +particular release gets wrong. A library decides from the daemon's release +before it dispatches the operation, then either keeps working through another +path or refuses with an error that names the requirement. Each optional +feature is refused on its own and never raises the minimum for anything else. + +Each port records these features in a typed capability registry: the release +each one needs, what the library does on an earlier release, and the API that +depends on it. The [capability map](/reference/capabilities/) and each port's +own capability page are generated from those registries, so they name the +methods involved and change when the code does. + +Two details limit what these gates cover. Control mode also needs a tmux +client that is compatible with the daemon; a client older than the daemon can +fail to register even when the daemon qualifies. Guards apply to library-chosen +operations and to literal tmux command items, including items in a batch. They +do not look inside opaque shell text or the body of a configured alias. + +Libraries also keep their own readiness, buffering and cleanup rules on +current releases. A command reply marks completion only where the command says +it does. Where a result depends on a pane's application, a library waits on a +marker or a state check, and a cursor position is a heuristic, not a promise. + +MCP servers apply the same core check to each tool call. A tool that needs a +newer release reports that requirement and does not raise the server's +minimum. diff --git a/site/src/data/capabilities.json b/site/src/data/capabilities.json new file mode 100644 index 00000000..b2520005 --- /dev/null +++ b/site/src/data/capabilities.json @@ -0,0 +1,5 @@ +{ + "generated": "scripts/gen-capabilities.mjs", + "releases": [], + "ports": {} +} diff --git a/site/src/lib/capabilities.ts b/site/src/lib/capabilities.ts new file mode 100644 index 00000000..f5e398bb --- /dev/null +++ b/site/src/lib/capabilities.ts @@ -0,0 +1,191 @@ +/** + * Rows for the capability pages, computed from site/src/data/capabilities.json. + * + * That file is generated by scripts/gen-capabilities.mjs from each port's own + * capability manifest, which the port emits from its typed registry. Nothing + * here stores a cell: every state comes from a capability's `since`, + * `except` and `handling` against the release columns, and every API link + * comes from the port's API model. + */ +import { + capabilityState, + compareTmuxVersions, + workaroundState, + type CapabilityCommand, + type CellState, + type Handling, +} from '@libtmux/api-model' +import data from '../data/capabilities.json' +import { PORT_NAME, referenceHref } from './api-models' +import { PORTS } from './ports' +import type { ApiLink, Column, Row } from './capability-cells' + +export type { ApiLink, Cell, Column, Row } from './capability-cells' +export { CELL_LABEL } from './capability-cells' + +interface PortEntry { + id: string + name: string + summary: string + since?: string + except?: string[] + releases?: string[] + handling: Handling + error?: string + apis: string[] + commands: CapabilityCommand[] +} + +interface PortCapabilities { + revision?: string + floor: { minimum: string } + capabilities: PortEntry[] + workarounds: PortEntry[] +} + +const DATA = data as { releases: string[]; ports: Record } + +/** Ports that publish a manifest, in the site's port order. */ +export function capabilityPorts(): string[] { + return PORTS.map((p) => p.slug).filter((slug) => slug in DATA.ports) +} + +export function capabilityFloor(port: string): string | undefined { + return DATA.ports[port]?.floor.minimum +} + +export function capabilityRevision(port: string): string | undefined { + return DATA.ports[port]?.revision +} + +function releasesFrom(floor?: string): string[] { + return DATA.releases.filter((v) => !floor || compareTmuxVersions(v, floor) >= 0) +} + +const releaseLabel = (v: string) => v.replace(/^next-/, 'next ') +const releaseTitle = (v: string) => (v.startsWith('next-') ? `tmux ${v}, the development build` : `tmux ${v}`) + +/** + * Release columns with neighbours merged where no cell changes. + * + * Fourteen releases do not fit beside a capability name, and most of them + * behave alike for any one port. A column per run of identical releases + * ("3.5 – 3.6b") keeps every column the same width and every change visible. + */ +export function releaseGroups(port: string): Column[] { + const entry = DATA.ports[port] + if (!entry) return [] + const signature = (release: string) => [ + ...entry.capabilities.map((e) => capabilityState(e as never, release)), + ...entry.workarounds.map((e) => workaroundState(e as never, release)), + ].join() + const groups: string[][] = [] + for (const release of releasesFrom(entry.floor.minimum)) { + const last = groups.at(-1) + if (last && signature(last[0]) === signature(release)) last.push(release) + else groups.push([release]) + } + return groups.map((g) => ({ + key: g[0], + label: g.length === 1 ? releaseLabel(g[0]) : `${releaseLabel(g[0])} – ${releaseLabel(g.at(-1)!)}`, + title: g.length === 1 ? releaseTitle(g[0]) : `tmux ${g.join(', ')}`, + })) +} + +function link(port: string, publicId: string): ApiLink { + return { label: publicId, href: referenceHref(port, publicId) } +} + +function requirement(entry: PortEntry): string { + if (entry.releases) return `Applies to ${entry.releases.join(', ')}` + const except = entry.except?.length ? `, not ${entry.except.join(', ')}` : '' + return `${entry.since} and later${except}` +} + +/** One port's capabilities and workarounds against its release columns. */ +export function portRows(port: string): { capabilities: Row[]; workarounds: Row[] } { + const entry = DATA.ports[port] + if (!entry) return { capabilities: [], workarounds: [] } + const columns = releaseGroups(port) + const row = (e: PortEntry, state: (release: string) => CellState): Row => ({ + id: e.id, + label: e.name, + summary: e.summary, + cells: columns.map((c) => ({ state: state(c.key) })), + apis: e.apis.map((id) => link(port, id)), + error: e.error ? link(port, e.error) : undefined, + commands: e.commands, + requirement: requirement(e), + }) + return { + capabilities: entry.capabilities.map((e) => row(e, (r) => capabilityState(e as never, r))), + workarounds: entry.workarounds.map((e) => row(e, (r) => workaroundState(e as never, r))), + } +} + +export function portColumns(): Column[] { + return capabilityPorts().map((slug) => ({ key: slug, label: PORT_NAME[slug] ?? slug, title: PORT_NAME[slug] ?? slug })) +} + +/** + * Capabilities × ports. A cell names the release the port needs, so the map + * answers "can I use this on my tmux" without opening each port's page. + */ +export function mapRows(): Row[] { + const ports = capabilityPorts() + const byId = new Map }>() + for (const port of ports) { + for (const e of DATA.ports[port].capabilities) { + const slot = byId.get(e.id) ?? { entry: e, ports: new Map() } + slot.ports.set(port, e) + byId.set(e.id, slot) + } + } + return [...byId.values()].map(({ entry, ports: present }) => ({ + id: entry.id, + label: entry.name, + summary: entry.summary, + cells: ports.map((port) => { + const e = present.get(port) + if (!e) return { state: 'absent' as const } + const except = e.except?.length ? ` (not ${e.except.join(', ')})` : '' + return { state: 'supported' as const, text: `${e.since}+${except}` } + }), + apis: [], + commands: entry.commands, + requirement: requirement(entry), + })) +} + +/** + * Entries × ports for one tmux command, for its reference page: the MDN + * compatibility-table shape, where a cell gives the release a port needs. + */ +export function commandRows(command: string): Row[] { + const ports = capabilityPorts() + const byId = new Map }>() + for (const port of ports) { + const { capabilities, workarounds } = DATA.ports[port] + for (const e of [...capabilities, ...workarounds]) { + if (!e.commands.some((c) => c.command === command)) continue + const slot = byId.get(e.id) ?? { entry: e, ports: new Map() } + slot.ports.set(port, e) + byId.set(e.id, slot) + } + } + return [...byId.values()].map(({ entry, ports: present }) => ({ + id: entry.id, + label: entry.name, + summary: entry.summary, + cells: ports.map((port) => { + const e = present.get(port) + if (!e) return { state: 'absent' as const } + if (e.releases) return { state: 'workaround' as const, text: `not ${e.releases.join(', ')}` } + const except = e.except?.length ? ` (not ${e.except.join(', ')})` : '' + return { state: 'supported' as const, text: `${e.since}+${except}` } + }), + apis: [], + commands: entry.commands, + requirement: requirement(entry), + })) +} diff --git a/site/src/lib/capability-cells.ts b/site/src/lib/capability-cells.ts new file mode 100644 index 00000000..2df8a834 --- /dev/null +++ b/site/src/lib/capability-cells.ts @@ -0,0 +1,43 @@ +/** Cell and row shapes for the capability matrix, kept free of data imports. */ +import type { CapabilityCommand, CellState } from '@libtmux/api-model' + +export interface Column { + key: string + label: string + title: string +} + +export interface Cell { + state: CellState | 'absent' + /** Short text shown with the icon, such as the release a port needs. */ + text?: string +} + +export interface ApiLink { + label: string + href?: string +} + +export interface Row { + id: string + label: string + /** Where the row's name links; its anchor on this page when unset. */ + href?: string + summary: string + cells: Cell[] + apis: ApiLink[] + error?: ApiLink + commands: CapabilityCommand[] + /** Releases in words: "3.7 and later", "3.3a and later, not 3.4". */ + requirement: string +} + +export const CELL_LABEL: Record = { + supported: 'Works', + workaround: 'Works with a workaround', + repaired: 'Repaired after the command', + fallback: 'Uses another path', + refused: 'Refused with an error', + absent: 'No entry in this port', +} + diff --git a/site/src/pages/reference/capabilities.astro b/site/src/pages/reference/capabilities.astro new file mode 100644 index 00000000..3e006b13 --- /dev/null +++ b/site/src/pages/reference/capabilities.astro @@ -0,0 +1,5 @@ +--- +import ApiCapabilities from '../../components/api/ApiCapabilities.astro' +const port = process.env.LIBTMUX_DOCS_PORT +--- + diff --git a/site/test/api-glossary-navigation.test.ts b/site/test/api-glossary-navigation.test.ts index fd65f624..f5aa44b8 100644 --- a/site/test/api-glossary-navigation.test.ts +++ b/site/test/api-glossary-navigation.test.ts @@ -28,6 +28,7 @@ import * as pagePorts from '../src/lib/page-ports-for' import * as markdown from '../src/lib/markdown-twins' import * as manual from '../src/lib/tmux-manual-data' import * as reference from '../src/lib/tmux-reference' +import * as capabilities from '../src/lib/capabilities' import * as locales from '../src/i18n/locales' import * as resolve from '../src/i18n/resolve' import * as contribute from '../src/i18n/contribute' @@ -54,7 +55,7 @@ async function components() { 'api-labels': labels, 'word-break': wordBreak, ports, 'product-api': products, versions, 'site-root': roots, sidebar, 'documentation-navigation': documentation, 'page-ports-for': pagePorts, 'markdown-twins': markdown, 'tmux-manual-data': manual, 'tmux-reference': reference, - branding, + branding, capabilities, }).map(([name, exports]) => [new URL(`../src/lib/${name}.ts`, import.meta.url).href, exports])), ...Object.fromEntries(Object.entries({ locales, resolve, contribute, ui }).map(([name, exports]) => [new URL(`../src/i18n/${name}.ts`, import.meta.url).href, exports])), diff --git a/site/test/capabilities.test.ts b/site/test/capabilities.test.ts new file mode 100644 index 00000000..f8e70e5e --- /dev/null +++ b/site/test/capabilities.test.ts @@ -0,0 +1,35 @@ +import { spawnSync } from 'node:child_process' +import { mkdtempSync, readFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join, resolve } from 'node:path' +import { describe, expect, it } from 'vitest' + +const root = resolve(import.meta.dirname, '../..') +const fixtures = join(import.meta.dirname, 'fixtures/capabilities') + +function generate(manifest: string) { + const out = join(mkdtempSync(join(tmpdir(), 'capabilities-')), 'capabilities.json') + const run = spawnSync('node', ['scripts/gen-capabilities.mjs', '--port', 'py', '--manifest', `py=${join(fixtures, manifest)}`, '--out', out], { + cwd: root, + encoding: 'utf8', + }) + return { run, out } +} + +describe('gen-capabilities', () => { + it('links every API name in a manifest to the API model', () => { + const { run, out } = generate('py.json') + expect(run.status, run.stderr).toBe(0) + const data = JSON.parse(readFileSync(out, 'utf8')) + const entry = data.ports.py.capabilities[0] + expect(entry.apis).toEqual(['libtmux.Server.new_session']) + expect(entry.error).toBe('libtmux.exc.VersionTooLow') + expect(data.releases[0]).toBe('3.3a') + }) + + it('fails on a name the API model does not have', () => { + const { run } = generate('py-unresolved.json') + expect(run.status).toBe(1) + expect(run.stderr).toContain('"libtmux.Server.no_such_method", which is not in the API model') + }) +}) diff --git a/site/test/capability-matrix.test.ts b/site/test/capability-matrix.test.ts new file mode 100644 index 00000000..bf116190 --- /dev/null +++ b/site/test/capability-matrix.test.ts @@ -0,0 +1,77 @@ +import { readFileSync, realpathSync } from 'node:fs' +import { createRequire } from 'node:module' +import { pathToFileURL } from 'node:url' +import { describe, expect, it, vi } from 'vitest' +import { experimental_AstroContainer } from 'astro/container' +import { Window } from 'happy-dom' +import * as cellsModule from '../src/lib/capability-cells' +import type { Column, Row } from '../src/lib/capability-cells' + +/** Compile the component the way the site's other component tests do, with its one helper bound. */ +async function loadMatrix() { + vi.stubGlobal('__capabilityCells', cellsModule) + const astroRequire = createRequire(realpathSync(new URL('../node_modules/astro/package.json', import.meta.url))) + const { transform } = await import(astroRequire.resolve('@astrojs/compiler-rs')) + const runtime = pathToFileURL(astroRequire.resolve('astro/compiler-runtime')).href + const file = new URL('../src/components/capabilities/CapabilityMatrix.astro', import.meta.url) + const result = await transform(readFileSync(file, 'utf8'), { filename: file.pathname, internalURL: 'astro/compiler-runtime', + resultScopedSlot: true, scopedStyleStrategy: 'attribute', resolvePath: (specifier: string) => specifier }) + expect(result.diagnostics.filter((d: { severity: string }) => d.severity === 'error')).toEqual([]) + const bridge = `export const { CELL_LABEL } = globalThis.__capabilityCells;` + const code = result.code.replaceAll('"astro/compiler-runtime"', JSON.stringify(runtime)) + .replaceAll('"../../lib/capability-cells"', JSON.stringify(`data:text/javascript;base64,${Buffer.from(bridge).toString('base64')}`)) + return (await import(/* @vite-ignore */ `data:text/javascript;base64,${Buffer.from(code).toString('base64')}`)).default +} + +const columns: Column[] = ['3.3a', '3.4', '3.7', 'next-3.9'].map((v) => ({ key: v, label: v, title: `tmux ${v}` })) +const rows: Row[] = [ + { + id: 'control-mode', label: 'Control mode', summary: 'Attach a control client.', requirement: '3.7 and later', + apis: [], commands: [], + cells: [{ state: 'fallback' }, { state: 'fallback' }, { state: 'supported' }, { state: 'supported' }], + }, + { + id: 'buffer-delete-named', label: 'Named buffer delete with a much longer label', summary: 'Delete by name.', requirement: '3.4 and later', + apis: [], commands: [], + cells: [{ state: 'refused' }, { state: 'supported' }, { state: 'supported' }, { state: 'supported' }], + }, +] + +async function render() { + const container = await experimental_AstroContainer.create() + const html = await container.renderToString(await loadMatrix(), { props: { caption: 'test', columns, rows } }) + const window = new Window() + window.document.body.innerHTML = html + return window.document +} + +describe('CapabilityMatrix', () => { + it('shares the width left by the name column equally among the data columns', async () => { + const doc = await render() + const table = doc.querySelector('table')! + expect(table.className).toContain('table-fixed') + expect(table.className).toContain('w-full') + const cols = [...doc.querySelectorAll('col')] + expect(cols[0].getAttribute('class')).toMatch(/w-\[/) + const data = cols.slice(1).map((c) => c.getAttribute('style')) + expect(data).toHaveLength(columns.length) + // A fixed layout splits the remaining width evenly among columns without a width. + expect(data.every((style) => style === null)).toBe(true) + }) + + it('fills every row with one cell per column, each labelled for screen readers', async () => { + const doc = await render() + for (const tr of doc.querySelectorAll('tbody tr')) { + const cells = tr.querySelectorAll('td') + expect(cells).toHaveLength(columns.length) + for (const td of cells) expect(td.querySelector('.sr-only')?.textContent).toBeTruthy() + } + expect(doc.querySelectorAll('thead th')).toHaveLength(columns.length + 1) + }) + + it('lists only the states the table uses in its legend', async () => { + const doc = await render() + const legend = [...doc.querySelectorAll('[aria-label="Legend"] li')].map((li) => li.textContent?.trim()) + expect(legend).toEqual(['✓Works', '↺Uses another path', '✕Refused with an error']) + }) +}) diff --git a/site/test/fixtures/capabilities/py-unresolved.json b/site/test/fixtures/capabilities/py-unresolved.json new file mode 100644 index 00000000..35faa541 --- /dev/null +++ b/site/test/fixtures/capabilities/py-unresolved.json @@ -0,0 +1 @@ +{"schema": "libtmux-capabilities/1", "port": "py", "floor": {"minimum": "3.3a"}, "capabilities": [{"id": "buffer-delete-named", "name": "Named buffer delete", "summary": "Delete a buffer by name.", "since": "3.4", "handling": "refuse", "error": "libtmux.exc.VersionTooLow", "apis": ["libtmux.Server.new_session", "libtmux.Server.no_such_method"], "commands": [{"command": "delete-buffer", "flags": ["-b"]}]}], "workarounds": []} \ No newline at end of file diff --git a/site/test/fixtures/capabilities/py.json b/site/test/fixtures/capabilities/py.json new file mode 100644 index 00000000..acded1be --- /dev/null +++ b/site/test/fixtures/capabilities/py.json @@ -0,0 +1 @@ +{"schema": "libtmux-capabilities/1", "port": "py", "floor": {"minimum": "3.3a"}, "capabilities": [{"id": "buffer-delete-named", "name": "Named buffer delete", "summary": "Delete a buffer by name.", "since": "3.4", "handling": "refuse", "error": "libtmux.exc.VersionTooLow", "apis": ["libtmux.Server.new_session"], "commands": [{"command": "delete-buffer", "flags": ["-b"]}]}], "workarounds": []} \ No newline at end of file diff --git a/site/test/tmux-support-page.test.ts b/site/test/tmux-support-page.test.ts new file mode 100644 index 00000000..b8913692 --- /dev/null +++ b/site/test/tmux-support-page.test.ts @@ -0,0 +1,50 @@ +import { readFileSync } from 'node:fs' +import { dirname, join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { describe, expect, it } from 'vitest' + +/** + * The guide explains optional features; it does not keep their facts. + * + * Which release a feature needs and what each port does are generated from + * the ports' capability registries onto the capability pages. A table typed + * into this guide would drift from them, so the guide links there instead. + */ +const PAGE = join(dirname(fileURLToPath(import.meta.url)), '../src/content/docs/guides/tmux-support.md') + +/** Markdown table rows that state a tmux release, which only generated pages may hold. */ +export function releaseRows(text: string): string[] { + return text.split('\n').filter((line) => /^\|.*\b3\.\d+[a-z]?\b.*\|\s*$/.test(line)) +} + +/** A count of ports such as "5/8" or "five of eight" summarizes instead of naming. */ +export function ratios(text: string): string[] { + return text.match(/\b\d+\s*\/\s*\d+\b|\b(?:one|two|three|four|five|six|seven|eight|\d+)\s+of\s+(?:the\s+)?(?:\d+|one|two|three|four|five|six|seven|eight|nine|ports)\b/gi) ?? [] +} + +describe('tmux support page', () => { + const page = readFileSync(PAGE, 'utf8') + + it('detects a ratio', () => { + expect(ratios('Qualified on 5/8 ports')).toEqual(['5/8']) + expect(ratios('Five of eight ports pass')).toEqual(['Five of eight']) + expect(ratios('Python needs 3.7 and Go needs 3.4')).toEqual([]) + }) + + it('detects a hand-kept release row', () => { + expect(releaseRows('| Named buffers | tmux 3.4 | refused |')).toHaveLength(1) + expect(releaseRows('Named buffers need tmux 3.4.')).toEqual([]) + }) + + it('keeps no table of release requirements', () => { + expect(releaseRows(page)).toEqual([]) + }) + + it('links to the generated capability map', () => { + expect(page).toContain('(/reference/capabilities/)') + }) + + it('names port results instead of counting them', () => { + expect(ratios(page)).toEqual([]) + }) +})