clap-ts 0.3.0 → 0.4.0

package/src/__tests__/log.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Tests for the levelled logger and how it reads verbosity arguments.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { createLogger, levelFromArgs, loggerFrom, LEVELS } from '../log.js';
+import { defineCommand } from '../runner.js';
+import { runCli } from '../testing.js';
+import type { OutputSink } from '../types.js';
+
+function collector(): OutputSink & { text(): string } {
+  const chunks: string[] = [];
+  return {
+    write(chunk: string) {
+      chunks.push(chunk);
+    },
+    text: () => chunks.join(''),
+  };
+}
+
+const plain = { color: false };
+
+describe('createLogger', () => {
+  test('info is the default level', () => {
+    const sink = collector();
+    const log = createLogger({ sink, ...plain });
+    log.info('shown');
+    log.debug('hidden');
+    expect(sink.text()).toBe('info: shown\n');
+  });
+
+  test('a higher level lets more through', () => {
+    const sink = collector();
+    createLogger({ sink, level: 'trace', ...plain }).trace('deep');
+    expect(sink.text()).toBe('trace: deep\n');
+  });
+
+  test('silent writes nothing at all', () => {
+    const sink = collector();
+    const log = createLogger({ sink, level: 'silent', ...plain });
+    for (const level of LEVELS) {
+      if (level !== 'silent') {
+        log[level]('anything');
+      }
+    }
+    expect(sink.text()).toBe('');
+  });
+
+  test('enabled answers without writing', () => {
+    const log = createLogger({ sink: collector(), level: 'warn', ...plain });
+    expect(log.enabled('error')).toBe(true);
+    expect(log.enabled('warn')).toBe(true);
+    expect(log.enabled('info')).toBe(false);
+  });
+
+  test('extra values are appended, objects as JSON', () => {
+    const sink = collector();
+    createLogger({ sink, ...plain }).info('msg', 'a', { b: 1 });
+    expect(sink.text()).toBe('info: msg a {"b":1}\n');
+  });
+
+  test('a prefix leads every line', () => {
+    const sink = collector();
+    createLogger({ sink, prefix: '[tool]', ...plain }).info('hi');
+    expect(sink.text()).toBe('[tool] info: hi\n');
+  });
+
+  test('withLevel keeps the sink', () => {
+    const sink = collector();
+    createLogger({ sink, ...plain }).withLevel('debug').debug('now shown');
+    expect(sink.text()).toBe('debug: now shown\n');
+  });
+
+  test('colour is off when asked', () => {
+    const sink = collector();
+    createLogger({ sink, color: false }).error('e');
+    expect(sink.text()).not.toContain('\x1b[');
+  });
+
+  test('colour is emitted when forced', () => {
+    const sink = collector();
+    createLogger({ sink, color: true }).error('e');
+    expect(sink.text()).toContain('\x1b[');
+  });
+});
+
+describe('levelFromArgs', () => {
+  test('no flags means info', () => {
+    expect(levelFromArgs({})).toBe('info');
+  });
+
+  test('each -v climbs a step', () => {
+    expect(levelFromArgs({ verbose: 1 })).toBe('debug');
+    expect(levelFromArgs({ verbose: 2 })).toBe('trace');
+  });
+
+  test('a boolean verbose counts as one step', () => {
+    expect(levelFromArgs({ verbose: true })).toBe('debug');
+  });
+
+  test('climbing stops at the loudest level', () => {
+    expect(levelFromArgs({ verbose: 99 })).toBe('trace');
+  });
+
+  test('quiet drops to errors only', () => {
+    expect(levelFromArgs({ quiet: true })).toBe('error');
+  });
+
+  test('quiet wins over verbose', () => {
+    expect(levelFromArgs({ quiet: true, verbose: 3 })).toBe('error');
+  });
+
+  test('an explicit level beats both', () => {
+    expect(levelFromArgs({ logLevel: 'warn', quiet: true, verbose: 3 })).toBe('warn');
+  });
+
+  test('an unknown explicit level is ignored', () => {
+    expect(levelFromArgs({ logLevel: 'nonsense' })).toBe('info');
+  });
+
+  test('the key names are configurable', () => {
+    expect(levelFromArgs({ loud: 2 }, { verboseKey: 'loud' })).toBe('trace');
+  });
+});
+
+describe('loggerFrom', () => {
+  test('takes its level from the args and writes to the context stderr', async () => {
+    const command = defineCommand({
+      meta: { name: 'tool' },
+      args: {
+        verbose: { type: 'boolean', short: 'v', action: 'count' },
+        quiet: { type: 'boolean', short: 'q' },
+      },
+      run(ctx) {
+        const log = loggerFrom(ctx, { color: false });
+        log.info('info line');
+        log.debug('debug line');
+      },
+    });
+
+    const quiet = await runCli(command, []);
+    expect(quiet.plainStderr).toContain('info line');
+    expect(quiet.plainStderr).not.toContain('debug line');
+
+    const loud = await runCli(command, ['-v']);
+    expect(loud.plainStderr).toContain('debug line');
+
+    const silent = await runCli(command, ['-q']);
+    expect(silent.plainStderr).toBe('');
+  });
+
+  test('nothing reaches stdout', async () => {
+    const command = defineCommand({
+      meta: { name: 'tool' },
+      run(ctx) {
+        loggerFrom(ctx, { color: false }).info('to stderr');
+      },
+    });
+    const { stdout, plainStderr } = await runCli(command, []);
+    expect(stdout).toBe('');
+    expect(plainStderr).toContain('to stderr');
+  });
+});
+
+describe('values that break a naive serialiser', () => {
+  test('an Error keeps its message rather than becoming {}', () => {
+    const sink = collector();
+    createLogger({ sink, ...plain }).error('failed', new Error('boom'));
+    expect(sink.text()).toContain('boom');
+    expect(sink.text()).not.toContain('{}');
+  });
+
+  test('a cyclic object is named, not thrown on', () => {
+    const sink = collector();
+    const circular: Record<string, unknown> = { a: 1 };
+    circular['self'] = circular;
+    expect(() => createLogger({ sink, ...plain }).info('cycle', circular)).not.toThrow();
+    expect(sink.text()).toContain('[Circular]');
+    expect(sink.text()).toContain('"a":1');
+  });
+
+  test('undefined, bigint and symbol survive', () => {
+    const sink = collector();
+    createLogger({ sink, ...plain }).info('values', undefined, 10n, Symbol('s'));
+    expect(sink.text()).toContain('undefined');
+    expect(sink.text()).toContain('10');
+    expect(sink.text()).toContain('Symbol(s)');
+  });
+});

package/src/__tests__/man.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for man page generation. Where groff is installed the output is also
+ * run through it, so a malformed request fails the suite rather than showing
+ * up in someone's terminal.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { renderManPage, generateManPages } from '../man.js';
+import type { CommandDef } from '../types.js';
+
+const command: CommandDef = {
+  meta: {
+    name: 'my-app',
+    version: '3.0',
+    description: 'Tests man pages',
+    author: 'Salama Ashoush',
+    afterHelp: "Don't forget the apostrophe.",
+  },
+  args: {
+    config: { type: 'string', short: 'c', description: 'some config file', action: 'append' },
+    mode: {
+      type: 'string',
+      description: 'Build mode',
+      valueParser: [{ name: 'fast', help: 'Skip checks' }, { name: 'safe' }],
+    },
+    port: { type: 'number', default: 8080, env: 'APP_PORT', description: 'Port to bind' },
+    secret: { type: 'string', hidden: true },
+    file: { type: 'positional', required: true, description: 'some input file' },
+    choice: { type: 'positional', description: 'a choice' },
+  },
+  subCommands: {
+    test: {
+      meta: { name: 'test', description: 'tests things' },
+      args: { case: { type: 'string', description: 'the case to test' } },
+    },
+    ghost: { meta: { name: 'ghost', hidden: true } },
+  },
+};
+
+const page = renderManPage(command);
+
+describe('man page structure', () => {
+  test('opens with the apostrophe preamble and a title', () => {
+    expect(page.startsWith('.ie \\n(.g .ds Aq \\(aq\n')).toBe(true);
+    expect(page).toContain('.TH my\\-app 1');
+  });
+
+  test('carries the standard sections in order', () => {
+    const order = ['.SH NAME', '.SH SYNOPSIS', '.SH DESCRIPTION', '.SH OPTIONS', '.SH SUBCOMMANDS', '.SH VERSION', '.SH AUTHORS'];
+    let at = -1;
+    for (const section of order) {
+      const found = page.indexOf(section);
+      expect(found).toBeGreaterThan(at);
+      at = found;
+    }
+  });
+
+  test('escapes hyphens and apostrophes', () => {
+    expect(page).toContain('my\\-app');
+    expect(page).toContain('Don\\*(Aqt');
+    // The two preamble lines define \\*(Aq and must keep their literal quotes.
+    const body = page.split('\n').slice(2).join('\n');
+    expect(body).not.toContain("'");
+  });
+
+  test('marks repeatable options and required positionals', () => {
+    expect(page).toContain('\\fB\\-c\\fR|\\fB\\-\\-config\\fR=\\fICONFIG\\fR]...');
+    expect(page).toContain('\\fIfile\\fR');
+    expect(page).toContain('[\\fIchoice\\fR]');
+  });
+
+  test('renders possible values as a bullet list with their help', () => {
+    expect(page).toContain('\\fIPossible values:\\fR');
+    expect(page).toContain('.IP \\(bu 2');
+    expect(page).toContain('fast: Skip checks');
+  });
+
+  test('notes defaults and environment variables', () => {
+    expect(page).toContain('\\fIDefault value:\\fR 8080');
+    expect(page).toContain('\\fIEnvironment:\\fR APP_PORT');
+  });
+
+  test('omits hidden args and subcommands', () => {
+    expect(page).not.toContain('secret');
+    expect(page).not.toContain('ghost');
+  });
+
+  test('lists subcommands by their own page name', () => {
+    expect(page).toContain('my\\-app\\-test(1)');
+  });
+});
+
+describe('generateManPages', () => {
+  const pages = generateManPages(command);
+
+  test('produces one page per visible command', () => {
+    expect([...pages.keys()].sort()).toEqual(['my-app-test.1', 'my-app.1']);
+  });
+
+  test('honours a custom section number', () => {
+    const section8 = generateManPages(command, { section: '8' });
+    expect([...section8.keys()]).toContain('my-app.8');
+    expect(section8.get('my-app.8')).toContain('.TH my\\-app 8');
+  });
+
+  test('a subcommand page describes only that subcommand', () => {
+    const sub = pages.get('my-app-test.1')!;
+    expect(sub).toContain('my\\-app\\-test \\- tests things');
+    expect(sub).toContain('\\-\\-case');
+    expect(sub).not.toContain('\\-\\-config');
+  });
+});
+
+describe('groff accepts the output', () => {
+  const groff = Bun.spawnSync(['sh', '-c', 'command -v groff']).exitCode === 0;
+
+  test.if(groff)('renders every page with no warnings', () => {
+    for (const [name, roff] of generateManPages(command)) {
+      const result = Bun.spawnSync(['groff', '-man', '-Tascii', '-ww'], {
+        stdin: Buffer.from(roff),
+      });
+      const warnings = new TextDecoder().decode(result.stderr).trim();
+      expect(`${name}: ${warnings}`).toBe(`${name}: `);
+      expect(result.exitCode).toBe(0);
+    }
+  });
+
+  test.if(groff)('the rendered text reads back correctly', () => {
+    const result = Bun.spawnSync(['groff', '-man', '-Tascii'], { stdin: Buffer.from(page) });
+    const text = new TextDecoder().decode(result.stdout).replace(/.\x08/g, '');
+    expect(text).toContain('my-app - Tests man pages');
+    expect(text).toContain('Port to bind');
+    expect(text).toContain("Don't forget the apostrophe.");
+  });
+});

package/src/__tests__/markdown.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Tests for markdown documentation output.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { renderMarkdownHelp } from '../markdown.js';
+import type { CommandDef } from '../types.js';
+
+const command: CommandDef = {
+  meta: { name: 'my-app', version: '3.0', description: 'Does things' },
+  args: {
+    config: { type: 'string', short: 'c', description: 'Config file', env: 'APP_CONFIG' },
+    mode: {
+      type: 'string',
+      description: 'Build mode',
+      valueParser: [{ name: 'fast', help: 'Skip checks' }, { name: 'safe' }],
+    },
+    port: { type: 'number', default: 8080, description: 'Port' },
+    plain: { type: 'string', valueParser: ['a', 'b'], description: 'Plain choices' },
+    secret: { type: 'string', hidden: true },
+    file: { type: 'positional', required: true, description: 'Input file' },
+  },
+  subCommands: {
+    test: {
+      meta: { name: 'test', description: 'Tests things', aliases: ['t'] },
+      args: { case: { type: 'string', description: 'Case' } },
+    },
+    ghost: { meta: { name: 'ghost', hidden: true } },
+  },
+};
+
+const doc = renderMarkdownHelp(command);
+
+describe('markdown structure', () => {
+  test('heads each command with its full path', () => {
+    expect(doc).toContain('# `my-app`');
+    expect(doc).toContain('## `my-app test`');
+  });
+
+  test('nests sections one level under their command', () => {
+    expect(doc).toContain('## Options');
+    expect(doc).toContain('### Options');
+  });
+
+  test('gives a usage line per command', () => {
+    expect(doc).toContain('**Usage:** `my-app [OPTIONS] <FILE> [COMMAND]`');
+    expect(doc).toContain('**Usage:** `my-app test [OPTIONS]`');
+  });
+
+  test('lists subcommands with their aliases', () => {
+    expect(doc).toContain('* `test` (`t`) - Tests things');
+  });
+
+  test('pairs the long flag and its placeholder in one code span', () => {
+    expect(doc).toContain('* `-c`, `--config <CONFIG>` - Config file');
+  });
+
+  test('includes the built-in flags', () => {
+    expect(doc).toContain('* `-h`, `--help` - Print help');
+    expect(doc).toContain('* `-V`, `--version` - Print version');
+  });
+});
+
+describe('markdown argument notes', () => {
+  test('spells out possible values that carry help', () => {
+    expect(doc).toContain('Possible values:');
+    expect(doc).toContain('- `fast`: Skip checks');
+  });
+
+  test('keeps plain possible values on one line', () => {
+    expect(doc).toContain('Possible values: `a`, `b`');
+  });
+
+  test('reports defaults, environment and required', () => {
+    expect(doc).toContain('Default value: `8080`');
+    expect(doc).toContain('Environment: `APP_CONFIG`');
+    expect(doc).toContain('Required.');
+  });
+
+  test('omits hidden args and commands', () => {
+    expect(doc).not.toContain('secret');
+    expect(doc).not.toContain('ghost');
+  });
+});
+
+describe('markdown formatting', () => {
+  test('never leaves three blank lines in a row', () => {
+    expect(doc).not.toContain('\n\n\n');
+  });
+
+  test('ends with exactly one newline', () => {
+    expect(doc.endsWith('\n')).toBe(true);
+    expect(doc.endsWith('\n\n')).toBe(false);
+  });
+
+  test('escapes markdown that would break a list item', () => {
+    const tricky: CommandDef = {
+      meta: { name: 'x' },
+      args: { a: { type: 'boolean', description: 'Uses *stars* and _score_ and <tags>' } },
+    };
+    const out = renderMarkdownHelp(tricky);
+    expect(out).toContain('\\*stars\\*');
+    expect(out).toContain('\\_score\\_');
+    expect(out).toContain('\\<tags\\>');
+  });
+
+  test('a title demotes the command headings by one level', () => {
+    const out = renderMarkdownHelp(command, { title: 'CLI Reference', footer: 'Bye.' });
+    expect(out.startsWith('# CLI Reference\n')).toBe(true);
+    expect(out).toContain('## `my-app`');
+    expect(out).toContain('### `my-app test`');
+    expect(out.trimEnd().endsWith('Bye.')).toBe(true);
+  });
+});

package/src/__tests__/output.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Tests for structured terminal output: tables, key-value blocks and trees.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { table, keyValue, tree, truncate, displayWidth } from '../output.js';
+import { stripAnsi } from '../testing.js';
+
+const rows = [
+  { name: 'parser.ts', size: 32832, kind: 'source' },
+  { name: 'completions.ts', size: 26550, kind: 'source' },
+  { name: 'index.ts', size: 828, kind: 'entry' },
+];
+
+const plainHeader = { headerStyle: (t: string) => t };
+
+describe('displayWidth and truncate', () => {
+  test('width ignores ANSI escapes', () => {
+    expect(displayWidth('\x1b[1mbold\x1b[22m')).toBe(4);
+  });
+
+  test('truncate leaves short text alone', () => {
+    expect(truncate('abc', 10)).toBe('abc');
+  });
+
+  test('truncate ends in an ellipsis', () => {
+    expect(truncate('abcdefgh', 4)).toBe('abc…');
+  });
+
+  test('truncate handles degenerate widths', () => {
+    expect(truncate('abc', 1)).toBe('…');
+    expect(truncate('abc', 0)).toBe('');
+  });
+});
+
+describe('table', () => {
+  const opts = { columns: [{ key: 'name' as const }, { key: 'size' as const }], ...plainHeader };
+
+  test('aligns columns to their widest cell', () => {
+    const lines = table(rows, opts).trimEnd().split('\n');
+    // 'completions.ts' is the widest name, so every size starts two past it.
+    const column = 'completions.ts'.length + 2;
+    expect(lines[0]!.indexOf('size')).toBe(column);
+    expect(lines[1]!.indexOf('32832')).toBe(column);
+    expect(lines[3]!.indexOf('828')).toBe(column);
+  });
+
+  test('emits a header by default and drops it on request', () => {
+    expect(table(rows, opts)).toContain('name');
+    expect(table(rows, { ...opts, header: false })).not.toContain('name  ');
+  });
+
+  test('right alignment pushes values to the column edge', () => {
+    const out = table(rows, {
+      columns: [{ key: 'name' }, { key: 'size', align: 'right' }],
+      ...plainHeader,
+    });
+    const lines = out.trimEnd().split('\n');
+    const ends = lines.slice(1).map((l) => l.length);
+    expect(new Set(ends).size).toBe(1);
+  });
+
+  test('a render function formats the cell', () => {
+    const out = table(rows, {
+      columns: [{ key: 'name' }, { key: 'size', render: (v) => `${String(v)} B` }],
+      ...plainHeader,
+    });
+    expect(out).toContain('32832 B');
+  });
+
+  test('never exceeds the requested width', () => {
+    for (const width of [80, 40, 24, 16]) {
+      const out = table(rows, {
+        columns: [{ key: 'name' }, { key: 'size' }, { key: 'kind' }],
+        width,
+        ...plainHeader,
+      });
+      for (const line of out.trimEnd().split('\n')) {
+        expect(stripAnsi(line).length).toBeLessThanOrEqual(width);
+      }
+    }
+  });
+
+  test('maxWidth truncates a single column', () => {
+    const out = table(rows, {
+      columns: [{ key: 'name', maxWidth: 6 }],
+      ...plainHeader,
+    });
+    expect(out).toContain('compl…');
+  });
+
+  test('indent shifts every line', () => {
+    const out = table(rows, { ...opts, indent: 4 });
+    for (const line of out.trimEnd().split('\n')) {
+      expect(line.startsWith('    ')).toBe(true);
+    }
+  });
+
+  test('a rule sits under the header', () => {
+    expect(table(rows, { ...opts, rule: true }).split('\n')[1]).toMatch(/^─+\s+─+$/);
+  });
+
+  test('no columns yields nothing', () => {
+    expect(table(rows, { columns: [] })).toBe('');
+  });
+
+  test('no rows still yields the header', () => {
+    expect(table([], opts).trimEnd()).toBe('name  size');
+  });
+
+  test('undefined and null cells render empty', () => {
+    const sparse = [{ a: undefined, b: null, c: 'x' }];
+    const out = table(sparse as never, {
+      columns: [{ key: 'a' }, { key: 'b' }, { key: 'c' }],
+      ...plainHeader,
+    });
+    expect(out.trimEnd().split('\n')[1]?.trim()).toBe('x');
+  });
+});
+
+describe('keyValue', () => {
+  const plainKey = { keyStyle: (t: string) => t };
+
+  test('aligns values past the widest key', () => {
+    const [first, second] = keyValue({ Name: 'clap-ts', Version: '0.3.0' }, plainKey)
+      .trimEnd()
+      .split('\n');
+    expect(first!.indexOf('clap-ts')).toBe(second!.indexOf('0.3.0'));
+  });
+
+  test('accepts pairs as well as an object', () => {
+    expect(keyValue([['a', '1']], plainKey)).toBe(keyValue({ a: '1' }, plainKey));
+  });
+
+  test('wraps a long value under its key', () => {
+    const out = keyValue({ Key: 'one two three four five six seven eight' }, { width: 20, ...plainKey });
+    const lines = out.trimEnd().split('\n');
+    expect(lines.length).toBeGreaterThan(1);
+    expect(lines[1]!.startsWith('     ')).toBe(true);
+  });
+
+  test('nothing in, nothing out', () => {
+    expect(keyValue({})).toBe('');
+  });
+
+  test('the separator is configurable', () => {
+    expect(keyValue({ a: '1' }, { separator: ' = ', ...plainKey })).toBe('a = 1\n');
+  });
+});
+
+describe('tree', () => {
+  const sample = {
+    label: 'demo',
+    children: [{ label: 'serve', children: [{ label: '--port' }] }, { label: 'build' }],
+  };
+
+  test('draws connectors, with the last child closing the branch', () => {
+    expect(tree(sample)).toBe('demo\n├── serve\n│   └── --port\n└── build\n');
+  });
+
+  test('ascii mode avoids box-drawing characters', () => {
+    const out = tree(sample, { ascii: true });
+    expect(out).toContain('|-- serve');
+    expect(out).toContain('`-- build');
+    expect(out).not.toMatch(/[├└│─]/);
+  });
+
+  test('a leaf is just its label', () => {
+    expect(tree({ label: 'only' })).toBe('only\n');
+  });
+
+  test('several roots each start at column zero', () => {
+    expect(tree([{ label: 'a' }, { label: 'b' }])).toBe('a\nb\n');
+  });
+
+  test('indent shifts every line', () => {
+    for (const line of tree(sample, { indent: 2 }).trimEnd().split('\n')) {
+      expect(line.startsWith('  ')).toBe(true);
+    }
+  });
+});
+
+// ---- Character width ----
+
+describe('width of characters a terminal renders differently', () => {
+  test('wide East Asian characters count as two columns', () => {
+    expect(displayWidth('日本語')).toBe(6);
+    expect(displayWidth('한국어')).toBe(6);
+    expect(displayWidth('ａｂｃ')).toBe(6); // fullwidth latin
+  });
+
+  test('emoji count as two columns', () => {
+    expect(displayWidth('\u{1f389}')).toBe(2);
+    expect(displayWidth('\u{1f680}\u{1f680}')).toBe(4);
+  });
+
+  test('a skin tone modifier adds nothing of its own', () => {
+    expect(displayWidth('\u{1f44d}\u{1f3fd}')).toBe(2);
+  });
+
+  test('combining marks add nothing', () => {
+    expect(displayWidth('é')).toBe(1); // decomposed
+    expect(displayWidth('é')).toBe(1); // precomposed
+  });
+
+  test('zero width and control characters add nothing', () => {
+    expect(displayWidth('a​b')).toBe(2);
+    expect(displayWidth('ab')).toBe(2);
+  });
+
+  test('ANSI escapes are skipped, including non-colour ones', () => {
+    expect(displayWidth('\x1b[1m\x1b[32mhi\x1b[39m\x1b[22m')).toBe(2);
+    expect(displayWidth('\x1b[2Khi')).toBe(2);
+  });
+
+  test('a table of wide text still aligns', () => {
+    const out = table(
+      [
+        { a: '日本語のファイル', b: '1' },
+        { a: 'ascii.ts', b: '22' },
+      ],
+      { columns: [{ key: 'a' }, { key: 'b' }], headerStyle: (t) => t },
+    );
+    const [, wide, plain] = out.trimEnd().split('\n');
+    // Both second columns start at the same visible column.
+    expect(displayWidth(wide!.slice(0, wide!.indexOf('1')))).toBe(
+      displayWidth(plain!.slice(0, plain!.indexOf('22'))),
+    );
+  });
+});
+
+describe('truncate respects character boundaries', () => {
+  test('never leaves half a surrogate pair', () => {
+    for (const width of [1, 2, 3, 4, 5]) {
+      const out = truncate('\u{1f389}\u{1f389}\u{1f389}', width);
+      expect(out).not.toMatch(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])/);
+      expect(displayWidth(out)).toBeLessThanOrEqual(width);
+    }
+  });
+
+  test('the result never exceeds the requested width', () => {
+    const samples = ['abcdefghij', '日本語のフ', '\u{1f389} party', 'éé'];
+    for (const text of samples) {
+      for (const width of [1, 2, 3, 5, 8]) {
+        expect(displayWidth(truncate(text, width))).toBeLessThanOrEqual(width);
+      }
+    }
+  });
+});