clap-ts 0.2.0 → 0.3.0

package/dist/markdown.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Markdown documentation, shaped like the clap-markdown crate's output: one
+ * heading per command, its usage line, then Commands, Arguments and Options
+ * lists, with nested commands appended as deeper headings.
+ *
+ * Suitable for committing next to a README or feeding a docs site.
+ */
+import type { CommandDef, MarkdownOptions } from './types.js';
+export type { MarkdownOptions } from './types.js';
+/**
+ * Render the whole command tree as one markdown document.
+ *
+ * ```ts
+ * writeFileSync('docs/cli.md', renderMarkdownHelp(command));
+ * ```
+ */
+export declare function renderMarkdownHelp(command: CommandDef, opts?: MarkdownOptions): string;

package/dist/markdown.js

@@ -0,0 +1,165 @@
+/**
+ * Markdown documentation, shaped like the clap-markdown crate's output: one
+ * heading per command, its usage line, then Commands, Arguments and Options
+ * lists, with nested commands appended as deeper headings.
+ *
+ * Suitable for committing next to a README or feeding a docs site.
+ */
+import { hasSubCommands, possibleValues, subCommandsOf } from './parser.js';
+/** Escape the markdown that could break a list item or table cell. */
+function esc(text) {
+    return text.replaceAll(/([\\`*_[\]<>|])/g, '\\$1');
+}
+function isVisible(def) {
+    return !def.hidden && !def.hideLongHelp;
+}
+function valuePlaceholder(key, def) {
+    if (def.valueNames && def.valueNames.length > 0) {
+        return def.valueNames.map((n) => `<${n}>`).join(' ');
+    }
+    return `<${def.valueName ?? (def.long ?? key).toUpperCase()}>`;
+}
+function usageLine(path, command) {
+    const argsDef = command.args ?? {};
+    const parts = [...path];
+    if (Object.values(argsDef).some((def) => def.type !== 'positional' && isVisible(def))) {
+        parts.push('[OPTIONS]');
+    }
+    for (const [key, def] of Object.entries(argsDef)) {
+        if (def.type !== 'positional' || !isVisible(def)) {
+            continue;
+        }
+        const name = `<${def.valueName ?? key.toUpperCase()}>`;
+        parts.push(def.required ? name : `[${name}]`);
+    }
+    if (hasSubCommands(command)) {
+        parts.push(`[${command.meta.subcommandValueName ?? 'COMMAND'}]`);
+    }
+    return parts.join(' ');
+}
+/** Trailing notes for one argument: default, env, possible values, required. */
+function notes(def) {
+    const out = [];
+    const values = def.hidePossibleValues ? [] : possibleValues(def).filter((v) => !v.hidden);
+    if (values.length > 0) {
+        if (values.some((v) => v.help)) {
+            out.push('Possible values:');
+            for (const value of values) {
+                out.push(`  - \`${value.name}\`${value.help ? `: ${esc(value.help)}` : ''}`);
+            }
+        }
+        else {
+            out.push(`Possible values: ${values.map((v) => `\`${v.name}\``).join(', ')}`);
+        }
+    }
+    if (def.default !== undefined && !def.hideDefaultValue) {
+        const shown = Array.isArray(def.default) ? def.default.join(', ') : String(def.default);
+        out.push(`Default value: \`${shown}\``);
+    }
+    if (def.env && !def.hideEnv) {
+        out.push(`Environment: \`${def.env}\``);
+    }
+    if (def.required) {
+        out.push('Required.');
+    }
+    return out;
+}
+function renderArgList(entries, label, lines) {
+    for (const [key, def] of entries) {
+        const description = def.longDescription ?? def.description ?? '';
+        lines.push(`* ${label(key, def)}${description ? ` - ${esc(description)}` : ''}`);
+        for (const note of notes(def)) {
+            lines.push(`  ${note}`);
+        }
+    }
+    lines.push('');
+}
+function renderCommand(command, path, depth, lines) {
+    const { meta } = command;
+    const argsDef = command.args ?? {};
+    const heading = '#'.repeat(Math.min(depth, 6));
+    lines.push(`${heading} \`${path.join(' ')}\``);
+    lines.push('');
+    const about = meta.longAbout ?? meta.about ?? meta.description;
+    if (about) {
+        lines.push(esc(about));
+        lines.push('');
+    }
+    lines.push(`**Usage:** \`${usageLine(path, command)}\``);
+    lines.push('');
+    const subs = Object.entries(subCommandsOf(command)).filter(([, def]) => !def.meta.hidden);
+    if (subs.length > 0) {
+        lines.push(`${heading}# Commands`);
+        lines.push('');
+        for (const [name, def] of subs) {
+            const aliases = def.meta.aliases ?? [];
+            const alias = aliases.length > 0 ? ` (${aliases.map((a) => `\`${a}\``).join(', ')})` : '';
+            const description = def.meta.description ?? def.meta.about ?? '';
+            lines.push(`* \`${name}\`${alias}${description ? ` - ${esc(description)}` : ''}`);
+        }
+        lines.push('');
+    }
+    const positionals = Object.entries(argsDef).filter(([, def]) => def.type === 'positional' && isVisible(def));
+    if (positionals.length > 0) {
+        lines.push(`${heading}# Arguments`);
+        lines.push('');
+        renderArgList(positionals, (key, def) => `\`<${def.valueName ?? key.toUpperCase()}>\``, lines);
+    }
+    const options = Object.entries(argsDef).filter(([, def]) => def.type !== 'positional' && isVisible(def));
+    const hasHelp = meta.disableHelpFlag !== true;
+    const hasVersion = meta.version !== undefined && meta.disableVersionFlag !== true;
+    if (options.length > 0 || hasHelp || hasVersion) {
+        lines.push(`${heading}# Options`);
+        lines.push('');
+        renderArgList(options, (key, def) => {
+            // The long form and its placeholder share one code span, as
+            // clap-markdown renders them: `--config <CONFIG>`.
+            const value = def.type !== 'boolean' && def.action !== 'count'
+                ? ` ${valuePlaceholder(key, def)}`
+                : '';
+            const long = `\`--${def.long ?? key}${value}\``;
+            return def.short ? `\`-${def.short}\`, ${long}` : long;
+        }, lines);
+        const builtins = [];
+        if (hasHelp) {
+            builtins.push('* `-h`, `--help` - Print help');
+        }
+        if (hasVersion) {
+            builtins.push('* `-V`, `--version` - Print version');
+        }
+        if (builtins.length > 0) {
+            // The list above already ended with a blank line, so reopen it.
+            lines.splice(lines.length - 1, 0, ...builtins);
+        }
+    }
+    const after = meta.afterLongHelp ?? meta.afterHelp;
+    if (after) {
+        lines.push(esc(after));
+        lines.push('');
+    }
+    for (const [name, sub] of subs) {
+        renderCommand(sub, [...path, name], depth + 1, lines);
+    }
+}
+/**
+ * Render the whole command tree as one markdown document.
+ *
+ * ```ts
+ * writeFileSync('docs/cli.md', renderMarkdownHelp(command));
+ * ```
+ */
+export function renderMarkdownHelp(command, opts) {
+    const name = opts?.name ?? command.meta.binName ?? command.meta.name;
+    const lines = [];
+    if (opts?.title !== undefined) {
+        lines.push(`# ${opts.title}`);
+        lines.push('');
+    }
+    renderCommand(command, [name], opts?.title === undefined ? 1 : 2, lines);
+    if (opts?.footer !== undefined) {
+        lines.push(opts.footer);
+        lines.push('');
+    }
+    // Collapse the runs of blank lines the section joins leave behind.
+    return `${lines.join('\n').replaceAll(/\n{3,}/g, '\n\n').trimEnd()}\n`;
+}

package/dist/output.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Structured terminal output: tables, key-value blocks and trees.
+ *
+ * ```ts
+ * import { table, keyValue, tree } from 'clap-ts/output';
+ *
+ * ctx.stdout.write(table(rows, { columns: [{ key: 'name' }, { key: 'size', align: 'right' }] }));
+ * ```
+ *
+ * Everything returns a string rather than writing, so the same call works
+ * against `ctx.stdout`, a file, or an assertion. Widths follow the terminal,
+ * and colour is only emitted when the destination can show it.
+ */
+/** Columns a single code point occupies: 0, 1 or 2. */
+export declare function codePointWidth(cp: number): number;
+/**
+ * Visible width of a string: ANSI escapes skipped, wide characters counted as
+ * two columns, combining marks as none.
+ *
+ * A single pass with no allocation. Measuring by `String.length` lines a table
+ * up wrongly the moment a cell holds CJK or an emoji, and stripping escapes
+ * with a replace allocates a string per cell.
+ */
+export declare function displayWidth(text: string): number;
+/**
+ * Truncate to a visible width, ending in an ellipsis when it does not fit.
+ *
+ * Walks code points rather than code units, so a surrogate pair is never split
+ * into a lone half, and a wide character is never counted as one column.
+ */
+export declare function truncate(text: string, width: number): string;
+export type Align = 'left' | 'right' | 'center';
+export interface Column<T> {
+    /** Property to read from each row. */
+    readonly key: keyof T & string;
+    /** Header text; defaults to the key. */
+    readonly header?: string;
+    /** Column alignment (default left). */
+    readonly align?: Align;
+    /** Cap this column's width, truncating what does not fit. */
+    readonly maxWidth?: number;
+    /** Render a cell; defaults to String(value), with undefined and null as ''. */
+    readonly render?: (value: T[keyof T & string], row: T) => string;
+}
+export interface TableOptions<T> {
+    readonly columns: readonly Column<T>[];
+    /** Show the header row (default true). */
+    readonly header?: boolean;
+    /** Gap between columns (default 2 spaces). */
+    readonly gap?: number;
+    /** Total width to fit; defaults to the terminal width. */
+    readonly width?: number;
+    /** Draw a rule under the header (default false). */
+    readonly rule?: boolean;
+    /** Left indent for every line. */
+    readonly indent?: number;
+    /** Style the header; defaults to bold when colour is on. */
+    readonly headerStyle?: (text: string) => string;
+}
+/** Whether the destination can show colour, matching how help decides. */
+export declare function colorEnabled(): boolean;
+/**
+ * Render rows as aligned columns.
+ *
+ * Columns are sized to their widest cell, then shrunk from the widest down
+ * until the whole table fits the available width. Nothing is truncated while
+ * anything still fits, so a narrow terminal costs the sprawling column first
+ * rather than every column equally.
+ */
+export declare function table<T extends Record<string, unknown>>(rows: readonly T[], opts: TableOptions<T>): string;
+export interface KeyValueOptions {
+    /** Left indent for every line. */
+    readonly indent?: number;
+    /** Separator between key and value (default ': '). */
+    readonly separator?: string;
+    /** Total width to wrap within; defaults to the terminal width. */
+    readonly width?: number;
+    /** Style the keys; defaults to bold when colour is on. */
+    readonly keyStyle?: (text: string) => string;
+}
+/**
+ * Render pairs as an aligned block, wrapping long values under their key.
+ *
+ * ```
+ * Name:    clap-ts
+ * Version: 0.3.0
+ * ```
+ */
+export declare function keyValue(pairs: readonly (readonly [string, string])[] | Record<string, string>, opts?: KeyValueOptions): string;
+/** A node in a tree, with whatever children it has. */
+export interface TreeNode {
+    readonly label: string;
+    readonly children?: readonly TreeNode[];
+}
+export interface TreeOptions {
+    /** Use ASCII connectors instead of box-drawing characters. */
+    readonly ascii?: boolean;
+    /** Left indent for every line. */
+    readonly indent?: number;
+}
+/**
+ * Render a tree with connector lines.
+ *
+ * ```
+ * root
+ * ├── one
+ * │   └── nested
+ * └── two
+ * ```
+ */
+export declare function tree(root: TreeNode | readonly TreeNode[], opts?: TreeOptions): string;

package/dist/output.js

@@ -0,0 +1,356 @@
+/**
+ * Structured terminal output: tables, key-value blocks and trees.
+ *
+ * ```ts
+ * import { table, keyValue, tree } from 'clap-ts/output';
+ *
+ * ctx.stdout.write(table(rows, { columns: [{ key: 'name' }, { key: 'size', align: 'right' }] }));
+ * ```
+ *
+ * Everything returns a string rather than writing, so the same call works
+ * against `ctx.stdout`, a file, or an assertion. Widths follow the terminal,
+ * and colour is only emitted when the destination can show it.
+ */
+import { styleText } from 'node:util';
+/**
+ * Character width tables.
+ *
+ * Flat sorted [start, end, ...] pairs searched by bisection: a handful of
+ * comparisons per non-ASCII code point, and no allocation. Covers the East
+ * Asian Wide and Fullwidth ranges plus emoji, which is what actually breaks
+ * column alignment in a terminal.
+ */
+const WIDE = Int32Array.from([
+    0x1100, 0x115f, 0x2329, 0x232a, 0x2e80, 0x303e, 0x3041, 0x33ff,
+    0x3400, 0x4dbf, 0x4e00, 0x9fff, 0xa000, 0xa4cf, 0xa960, 0xa97f,
+    0xac00, 0xd7a3, 0xf900, 0xfaff, 0xfe10, 0xfe19, 0xfe30, 0xfe6f,
+    0xff00, 0xff60, 0xffe0, 0xffe6,
+    0x1f004, 0x1f004, 0x1f0cf, 0x1f0cf, 0x1f18e, 0x1f18e, 0x1f191, 0x1f19a,
+    0x1f200, 0x1f320, 0x1f32d, 0x1f335, 0x1f337, 0x1f37c, 0x1f37e, 0x1f393,
+    0x1f3a0, 0x1f3ca, 0x1f3cf, 0x1f3d3, 0x1f3e0, 0x1f3f0, 0x1f3f4, 0x1f3f4,
+    0x1f3f8, 0x1f43e, 0x1f440, 0x1f440, 0x1f442, 0x1f4fc, 0x1f4ff, 0x1f53d,
+    0x1f54b, 0x1f54e, 0x1f550, 0x1f567, 0x1f57a, 0x1f57a, 0x1f595, 0x1f596,
+    0x1f5a4, 0x1f5a4, 0x1f5fb, 0x1f64f, 0x1f680, 0x1f6c5, 0x1f6cc, 0x1f6cc,
+    0x1f6d0, 0x1f6d2, 0x1f6eb, 0x1f6ec, 0x1f6f4, 0x1f6fc, 0x1f7e0, 0x1f7eb,
+    0x1f90c, 0x1f93a, 0x1f93c, 0x1f945, 0x1f947, 0x1f9ff, 0x1fa70, 0x1faff,
+    0x20000, 0x3fffd,
+]);
+/** Marks, joiners and selectors that occupy no column of their own. */
+const ZERO = Int32Array.from([
+    0x0300, 0x036f, 0x0483, 0x0489, 0x0591, 0x05bd, 0x0610, 0x061a,
+    0x064b, 0x065f, 0x0670, 0x0670, 0x06d6, 0x06dc, 0x0730, 0x074a,
+    0x07eb, 0x07f3, 0x0816, 0x0819, 0x081b, 0x0823, 0x0825, 0x0827,
+    0x0829, 0x082d, 0x0859, 0x085b, 0x08e3, 0x0903, 0x093a, 0x093c,
+    0x0941, 0x0948, 0x094d, 0x094d, 0x0951, 0x0957, 0x1ab0, 0x1aff,
+    0x1dc0, 0x1dff, 0x200b, 0x200f, 0x2028, 0x202e, 0x2060, 0x2064,
+    0x20d0, 0x20f0, 0xfe00, 0xfe0f, 0xfe20, 0xfe2f, 0xfeff, 0xfeff,
+    0x1f3fb, 0x1f3ff, 0xe0100, 0xe01ef,
+]);
+/** Whether a code point falls inside a flat sorted range table. */
+function inRanges(table, cp) {
+    let low = 0;
+    let high = table.length / 2 - 1;
+    while (low <= high) {
+        const mid = (low + high) >> 1;
+        if (cp < table[mid * 2]) {
+            high = mid - 1;
+        }
+        else if (cp > table[mid * 2 + 1]) {
+            low = mid + 1;
+        }
+        else {
+            return true;
+        }
+    }
+    return false;
+}
+/** Columns a single code point occupies: 0, 1 or 2. */
+export function codePointWidth(cp) {
+    if (cp < 0x7f) {
+        // C0 controls take no space; everything else printable takes one.
+        return cp < 0x20 ? 0 : 1;
+    }
+    if (cp < 0xa0) {
+        return 0;
+    }
+    if (inRanges(ZERO, cp)) {
+        return 0;
+    }
+    return inRanges(WIDE, cp) ? 2 : 1;
+}
+const ESC = 0x1b;
+/**
+ * Visible width of a string: ANSI escapes skipped, wide characters counted as
+ * two columns, combining marks as none.
+ *
+ * A single pass with no allocation. Measuring by `String.length` lines a table
+ * up wrongly the moment a cell holds CJK or an emoji, and stripping escapes
+ * with a replace allocates a string per cell.
+ */
+export function displayWidth(text) {
+    let width = 0;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code === ESC) {
+            i = skipEscape(text, i);
+            continue;
+        }
+        if (code < 0x7f) {
+            if (code >= 0x20) {
+                width++;
+            }
+            continue;
+        }
+        // Combine a surrogate pair into one code point before measuring.
+        let cp = code;
+        if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+            const low = text.charCodeAt(i + 1);
+            if (low >= 0xdc00 && low <= 0xdfff) {
+                cp = (code - 0xd800) * 0x400 + low - 0xdc00 + 0x10000;
+                i++;
+            }
+        }
+        width += codePointWidth(cp);
+    }
+    return width;
+}
+/** Index of the last character of a CSI sequence starting at `start`. */
+function skipEscape(text, start) {
+    if (text.charCodeAt(start + 1) !== 0x5b) {
+        return start;
+    }
+    let i = start + 2;
+    while (i < text.length) {
+        const code = text.charCodeAt(i);
+        // Parameter and intermediate bytes run until a final byte in @ to ~.
+        if (code >= 0x40 && code <= 0x7e) {
+            return i;
+        }
+        i++;
+    }
+    return text.length;
+}
+const ANSI = /\x1b\[[0-9;]*m/g;
+function stripAnsi(text) {
+    return text.replace(ANSI, '');
+}
+/**
+ * Pad to a visible width, so styled text lines up with plain text.
+ *
+ * `known` skips re-measuring when the caller already has the width, which the
+ * table always does after truncating.
+ */
+function pad(text, width, align, known) {
+    const filler = ' '.repeat(Math.max(0, width - (known ?? displayWidth(text))));
+    if (align === 'right') {
+        return filler + text;
+    }
+    if (align === 'center') {
+        const left = Math.floor(filler.length / 2);
+        return ' '.repeat(left) + text + ' '.repeat(filler.length - left);
+    }
+    return text + filler;
+}
+/**
+ * Truncate to a visible width, ending in an ellipsis when it does not fit.
+ *
+ * Walks code points rather than code units, so a surrogate pair is never split
+ * into a lone half, and a wide character is never counted as one column.
+ */
+export function truncate(text, width) {
+    return fit(text, width).text;
+}
+/** Truncate and report the resulting visible width, measuring only once. */
+function fit(text, width) {
+    const actual = displayWidth(text);
+    if (width <= 0) {
+        return { text: '', width: 0 };
+    }
+    if (actual <= width) {
+        return { text, width: actual };
+    }
+    if (width === 1) {
+        return { text: '…', width: 1 };
+    }
+    const budget = width - 1;
+    let used = 0;
+    let out = '';
+    for (const char of stripAnsi(text)) {
+        const cost = codePointWidth(char.codePointAt(0));
+        if (used + cost > budget) {
+            break;
+        }
+        used += cost;
+        out += char;
+    }
+    return { text: `${out}…`, width: used + 1 };
+}
+function terminalWidth() {
+    const columns = process.stdout?.columns;
+    return typeof columns === 'number' && columns > 0 ? columns : 80;
+}
+/** Whether the destination can show colour, matching how help decides. */
+export function colorEnabled() {
+    return styleText('red', 'x') !== 'x';
+}
+function defaultCell(value) {
+    return value === undefined || value === null ? '' : String(value);
+}
+/**
+ * Render rows as aligned columns.
+ *
+ * Columns are sized to their widest cell, then shrunk from the widest down
+ * until the whole table fits the available width. Nothing is truncated while
+ * anything still fits, so a narrow terminal costs the sprawling column first
+ * rather than every column equally.
+ */
+export function table(rows, opts) {
+    const { columns } = opts;
+    if (columns.length === 0) {
+        return '';
+    }
+    const gap = opts.gap ?? 2;
+    const indent = opts.indent ?? 0;
+    const showHeader = opts.header !== false;
+    const headerStyle = opts.headerStyle ?? (colorEnabled() ? (t) => styleText('bold', t) : (t) => t);
+    const headers = columns.map((c) => c.header ?? c.key);
+    const cells = rows.map((row) => columns.map((c) => (c.render ? c.render(row[c.key], row) : defaultCell(row[c.key]))));
+    const widths = columns.map((c, i) => {
+        let width = showHeader ? displayWidth(headers[i]) : 0;
+        for (const line of cells) {
+            width = Math.max(width, displayWidth(line[i]));
+        }
+        return c.maxWidth === undefined ? width : Math.min(width, c.maxWidth);
+    });
+    // Shrink the widest column repeatedly until the table fits.
+    const available = (opts.width ?? terminalWidth()) - indent;
+    const overhead = gap * (columns.length - 1);
+    let total = widths.reduce((sum, w) => sum + w, 0) + overhead;
+    while (total > available) {
+        let widest = 0;
+        for (let i = 1; i < widths.length; i++) {
+            if (widths[i] > widths[widest]) {
+                widest = i;
+            }
+        }
+        if (widths[widest] <= 3) {
+            break;
+        }
+        widths[widest]--;
+        total--;
+    }
+    const spacer = ' '.repeat(gap);
+    const prefix = ' '.repeat(indent);
+    const lines = [];
+    const renderRow = (values, style) => {
+        const parts = values.map((value, i) => {
+            const cut = fit(value, widths[i]);
+            // Styling adds escapes but no columns, so the measured width still holds.
+            const shown = style ? style(cut.text) : cut.text;
+            return pad(shown, widths[i], columns[i]?.align ?? 'left', cut.width);
+        });
+        return (prefix + parts.join(spacer)).trimEnd();
+    };
+    if (showHeader) {
+        lines.push(renderRow(headers, headerStyle));
+        if (opts.rule === true) {
+            lines.push(prefix + widths.map((w) => '─'.repeat(w)).join(spacer));
+        }
+    }
+    for (const line of cells) {
+        lines.push(renderRow(line));
+    }
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Render pairs as an aligned block, wrapping long values under their key.
+ *
+ * ```
+ * Name:    clap-ts
+ * Version: 0.3.0
+ * ```
+ */
+export function keyValue(pairs, opts) {
+    const entries = Array.isArray(pairs)
+        ? pairs
+        : Object.entries(pairs);
+    if (entries.length === 0) {
+        return '';
+    }
+    const separator = opts?.separator ?? ': ';
+    const indent = opts?.indent ?? 0;
+    const keyStyle = opts?.keyStyle ?? (colorEnabled() ? (t) => styleText('bold', t) : (t) => t);
+    const keyWidth = Math.max(...entries.map(([key]) => displayWidth(key)));
+    const valueColumn = indent + keyWidth + separator.length;
+    const available = Math.max(20, (opts?.width ?? terminalWidth()) - valueColumn);
+    const lines = [];
+    for (const [key, value] of entries) {
+        const label = ' '.repeat(indent) + keyStyle(key + separator) + ' '.repeat(keyWidth - displayWidth(key));
+        const wrapped = wrap(value, available);
+        lines.push((label + wrapped[0]).trimEnd());
+        for (const rest of wrapped.slice(1)) {
+            lines.push(' '.repeat(valueColumn) + rest);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** Break text into lines no wider than `width`, on whitespace. */
+function wrap(text, width) {
+    if (displayWidth(text) <= width) {
+        return [text];
+    }
+    const lines = [];
+    let current = '';
+    for (const word of text.split(/\s+/)) {
+        if (current.length === 0) {
+            current = word;
+        }
+        else if (displayWidth(current) + 1 + displayWidth(word) <= width) {
+            current += ` ${word}`;
+        }
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current.length > 0) {
+        lines.push(current);
+    }
+    return lines;
+}
+/**
+ * Render a tree with connector lines.
+ *
+ * ```
+ * root
+ * ├── one
+ * │   └── nested
+ * └── two
+ * ```
+ */
+export function tree(root, opts) {
+    const ascii = opts?.ascii === true;
+    const glyphs = ascii
+        ? { branch: '|-- ', last: '`-- ', pipe: '|   ', blank: '    ' }
+        : { branch: '├── ', last: '└── ', pipe: '│   ', blank: '    ' };
+    const prefix = ' '.repeat(opts?.indent ?? 0);
+    const lines = [];
+    const walk = (node, ancestry, isLast, isRoot) => {
+        if (isRoot) {
+            lines.push(prefix + node.label);
+        }
+        else {
+            lines.push(prefix + ancestry + (isLast ? glyphs.last : glyphs.branch) + node.label);
+        }
+        const children = node.children ?? [];
+        const childAncestry = isRoot ? '' : ancestry + (isLast ? glyphs.blank : glyphs.pipe);
+        children.forEach((child, i) => {
+            walk(child, childAncestry, i === children.length - 1, false);
+        });
+    };
+    const roots = Array.isArray(root) ? root : [root];
+    roots.forEach((node) => {
+        walk(node, '', true, true);
+    });
+    return `${lines.join('\n')}\n`;
+}