clap-ts 0.3.0 → 0.4.0

package/src/__tests__/deprecation.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for deprecating arguments and commands.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { parseArgs } from '../parser.js';
+import { renderHelp } from '../help.js';
+import { defineCommand } from '../runner.js';
+import { runCli, captureArgs, stripAnsi } from '../testing.js';
+import type { CommandDef } from '../types.js';
+
+describe('deprecated arguments', () => {
+  const command = defineCommand({
+    meta: { name: 'app' },
+    args: {
+      old: { type: 'string', deprecated: true, description: 'Old flag' },
+      stale: { type: 'string', deprecated: 'no longer read', description: 'Stale flag' },
+      current: { type: 'string', description: 'Current flag' },
+      legacy: { type: 'string', deprecated: true, replacedBy: 'current' },
+    },
+    run() {},
+  });
+
+  test('using one warns on stderr', async () => {
+    const { plainStderr } = await runCli(command, ['--old', 'x']);
+    expect(plainStderr).toContain("warning: '--old' is deprecated");
+  });
+
+  test('a string deprecation carries its reason', async () => {
+    const { plainStderr } = await runCli(command, ['--stale', 'x']);
+    expect(plainStderr).toContain("'--stale' is deprecated: no longer read");
+  });
+
+  test('replacedBy names the replacement in the warning', async () => {
+    const { plainStderr } = await runCli(command, ['--legacy', 'x']);
+    expect(plainStderr).toContain("use '--current' instead");
+  });
+
+  test('replacedBy forwards the value', async () => {
+    const { args } = await captureArgs(command, ['--legacy', 'x']);
+    expect(args['current']).toBe('x');
+  });
+
+  test('an explicit replacement wins over the forwarded value', async () => {
+    const { args } = await captureArgs(command, ['--legacy', 'old', '--current', 'new']);
+    expect(args['current']).toBe('new');
+  });
+
+  test('a current argument warns about nothing', async () => {
+    const { plainStderr } = await runCli(command, ['--current', 'x']);
+    expect(plainStderr).toBe('');
+  });
+
+  test('the warning does not fail the run', async () => {
+    const { exitCode } = await runCli(command, ['--old', 'x']);
+    expect(exitCode).toBe(0);
+  });
+
+  test('it warns once even when repeated', () => {
+    const appendable: CommandDef = {
+      meta: { name: 'app' },
+      args: { old: { type: 'string', action: 'append', deprecated: true } },
+    };
+    expect(parseArgs(['--old', 'a', '--old', 'b'], appendable).warnings).toHaveLength(1);
+  });
+
+  test('help labels it', () => {
+    const help = stripAnsi(renderHelp(command));
+    expect(help).toContain('[deprecated]');
+    expect(help).toContain('[deprecated: no longer read]');
+  });
+});
+
+describe('deprecated commands', () => {
+  const root = defineCommand({
+    meta: { name: 'app' },
+    subCommands: {
+      publish: defineCommand({ meta: { name: 'publish', description: 'Publish' }, run() {} }),
+      push: defineCommand({
+        meta: {
+          name: 'push',
+          description: 'Push',
+          deprecated: 'renamed',
+          replacedBy: 'publish',
+        },
+        run() {},
+      }),
+    },
+  });
+
+  test('running one warns', async () => {
+    const { plainStderr, exitCode } = await runCli(root, ['push']);
+    expect(plainStderr).toContain("warning: 'push' is deprecated: renamed; use 'publish' instead");
+    expect(exitCode).toBe(0);
+  });
+
+  test('the current command is quiet', async () => {
+    expect((await runCli(root, ['publish'])).plainStderr).toBe('');
+  });
+
+  test('help labels it in the command list', () => {
+    expect(stripAnsi(renderHelp(root))).toContain('[deprecated: renamed]');
+  });
+});

package/src/__tests__/help.test.ts

@@ -0,0 +1,312 @@
+/**
+ * Help renderer tests - tests for clap-style help output generation.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { renderHelp } from '../help.js';
+import { stripAnsi } from '../testing.js';
+import type { ArgsDef, CommandDef } from '../types.js';
+
+/** Strip ANSI escape sequences for assertion on content. */
+function cmd(args: ArgsDef, extra?: Partial<CommandDef>): CommandDef {
+  return { meta: { name: 'test' }, args, ...extra };
+}
+
+const basicCommand: CommandDef = {
+  meta: {
+    name: 'my-tool',
+    version: '1.0.0',
+    description: 'A great tool',
+    about: 'A tool that does great things',
+  },
+  args: {
+    verbose: {
+      type: 'boolean',
+      short: 'v',
+      description: 'Enable verbose output',
+    },
+    port: {
+      type: 'number',
+      short: 'p',
+      default: 3000,
+      valueName: 'PORT',
+      description: 'Port to listen on',
+    },
+    env: {
+      type: 'string',
+      short: 'e',
+      env: 'MY_TOOL_ENV',
+      valueParser: ['dev', 'staging', 'prod'],
+      description: 'Environment to use',
+    },
+    file: {
+      type: 'positional',
+      valueName: 'FILE',
+      required: true,
+      description: 'Input file',
+    },
+  },
+};
+
+describe('help rendering', () => {
+  test('includes all sections', () => {
+    const help = stripAnsi(renderHelp(basicCommand));
+    // Header with name and version
+    expect(help).toContain('my-tool');
+    expect(help).toContain('v1.0.0');
+    // About text
+    expect(help).toContain('A tool that does great things');
+    // Usage line
+    expect(help).toContain('Usage:');
+    expect(help).toContain('my-tool');
+    // Arguments section
+    expect(help).toContain('Arguments:');
+    expect(help).toContain('FILE');
+    // Options section
+    expect(help).toContain('Options:');
+    expect(help).toContain('--verbose');
+    expect(help).toContain('--port');
+    expect(help).toContain('--env');
+    // Built-in flags
+    expect(help).toContain('--help');
+    expect(help).toContain('--version');
+  });
+
+  test('aliases shown in help (subcommands)', () => {
+    const command: CommandDef = {
+      meta: { name: 'app' },
+      subCommands: {
+        serve: {
+          meta: { name: 'serve', description: 'Start server', aliases: ['s', 'start'] },
+        },
+      },
+    };
+    const help = stripAnsi(renderHelp(command));
+    expect(help).toContain('serve');
+    expect(help).toContain('s, start');
+  });
+
+  test('default values shown', () => {
+    const help = stripAnsi(renderHelp(basicCommand));
+    expect(help).toContain('[default: 3000]');
+  });
+
+  test('env var names shown', () => {
+    const help = stripAnsi(renderHelp(basicCommand));
+    expect(help).toContain('[env: MY_TOOL_ENV]');
+  });
+
+  test('required markers shown for positionals', () => {
+    const help = stripAnsi(renderHelp(basicCommand));
+    // Required positionals appear as <FILE> in usage line
+    expect(help).toContain('<FILE>');
+  });
+
+  test('possible values shown', () => {
+    const help = stripAnsi(renderHelp(basicCommand));
+    // Help text may wrap across lines; normalize whitespace for matching
+    const normalized = help.replaceAll(/\s+/g, ' ');
+    expect(normalized).toContain('[possible values: dev, staging, prod]');
+  });
+
+  test('short flags shown', () => {
+    const help = stripAnsi(renderHelp(basicCommand));
+    expect(help).toContain('-v');
+    expect(help).toContain('-p');
+    expect(help).toContain('-e');
+  });
+
+  test('hidden args not shown', () => {
+    const command: CommandDef = {
+      meta: { name: 'tool' },
+      args: {
+        visible: { type: 'boolean', description: 'Visible flag' },
+        secret: { type: 'boolean', description: 'Secret flag', hidden: true },
+      },
+    };
+    const help = stripAnsi(renderHelp(command));
+    expect(help).toContain('--visible');
+    expect(help).not.toContain('--secret');
+  });
+
+  test('subcommands section rendered', () => {
+    const command: CommandDef = {
+      meta: { name: 'app' },
+      subCommands: {
+        serve: { meta: { name: 'serve', description: 'Start the server' } },
+        build: { meta: { name: 'build', description: 'Build the project' } },
+      },
+    };
+    const help = stripAnsi(renderHelp(command));
+    expect(help).toContain('Commands:');
+    expect(help).toContain('serve');
+    expect(help).toContain('Start the server');
+    expect(help).toContain('build');
+    expect(help).toContain('Build the project');
+  });
+
+  test('after help text shown', () => {
+    const command: CommandDef = {
+      meta: { name: 'tool', afterHelp: 'For more info visit https://example.com' },
+    };
+    const help = stripAnsi(renderHelp(command));
+    expect(help).toContain('For more info visit https://example.com');
+  });
+
+  test('optional value indicator shown for numArgs.min=0', () => {
+    const command: CommandDef = {
+      meta: { name: 'tool' },
+      args: {
+        level: {
+          type: 'string',
+          valueName: 'LEVEL',
+          numArgs: { min: 0, max: 1 },
+          description: 'Log level',
+        },
+      },
+    };
+    const help = stripAnsi(renderHelp(command));
+    // Optional values shown as [LEVEL] instead of <LEVEL>
+    expect(help).toContain('[LEVEL]');
+  });
+});
+
+describe('hidePossibleValues', () => {
+  test('hides possible values from help', () => {
+    const command = cmd({
+      env: {
+        type: 'string',
+        long: 'env',
+        valueParser: ['dev', 'staging', 'prod'],
+        hidePossibleValues: true,
+      },
+    });
+    const help = stripAnsi(renderHelp(command));
+    expect(help).not.toContain('possible values');
+  });
+
+  test('shows possible values by default', () => {
+    const command = cmd({
+      env: {
+        type: 'string',
+        long: 'env',
+        valueParser: ['dev', 'staging', 'prod'],
+      },
+    });
+    const help = stripAnsi(renderHelp(command));
+    expect(help).toContain('possible values');
+  });
+});
+
+describe('hideShortHelp / hideLongHelp', () => {
+  test('hideShortHelp hides from -h but shows in --help', () => {
+    const command = cmd({
+      advanced: { type: 'boolean', long: 'advanced', description: 'Advanced mode', hideShortHelp: true },
+      basic: { type: 'boolean', long: 'basic', description: 'Basic mode' },
+    });
+    const shortHelp = stripAnsi(renderHelp(command, undefined, true));
+    const longHelp = stripAnsi(renderHelp(command, undefined, false));
+    expect(shortHelp).not.toContain('--advanced');
+    expect(longHelp).toContain('--advanced');
+  });
+
+  test('hideLongHelp hides from --help but shows in -h', () => {
+    const command = cmd({
+      debug: { type: 'boolean', long: 'debug', description: 'Debug mode', hideLongHelp: true },
+    });
+    const shortHelp = stripAnsi(renderHelp(command, undefined, true));
+    const longHelp = stripAnsi(renderHelp(command, undefined, false));
+    expect(shortHelp).toContain('--debug');
+    expect(longHelp).not.toContain('--debug');
+  });
+});
+
+describe('visibleAlias in help', () => {
+  test('visible aliases shown in help output', () => {
+    const command = cmd({
+      output: { type: 'string', long: 'output', visibleAlias: ['out', 'o'], description: 'Output path' },
+    });
+    const help = stripAnsi(renderHelp(command));
+    expect(help).toContain('--out');
+    expect(help).toContain('-o');
+  });
+
+  test('hidden aliases not shown in help', () => {
+    const command = cmd({
+      output: { type: 'string', long: 'output', alias: ['out'], description: 'Output path' },
+    });
+    const help = stripAnsi(renderHelp(command));
+    // Check that --out doesn't appear as a standalone flag display
+    // (--output contains --out as substring, so use regex for exact match)
+    expect(help).not.toMatch(/,\s*--out\b/);
+  });
+});
+
+describe('beforeHelp', () => {
+  test('renders text before help output', () => {
+    const command: CommandDef = {
+      meta: { name: 'tool', beforeHelp: 'WARNING: This tool is experimental.' },
+    };
+    const help = stripAnsi(renderHelp(command));
+    expect(help.indexOf('WARNING')).toBeLessThan(help.indexOf('Usage:'));
+  });
+});
+
+describe('helpHeading', () => {
+  test('groups args under custom headings', () => {
+    const command = cmd({
+      verbose: { type: 'boolean', long: 'verbose', description: 'Verbose' },
+      host: { type: 'string', long: 'host', description: 'Host', helpHeading: 'Network' },
+      port: { type: 'number', long: 'port', description: 'Port', helpHeading: 'Network' },
+    });
+    const help = stripAnsi(renderHelp(command));
+    expect(help).toContain('Options:');
+    expect(help).toContain('Network:');
+    // verbose under Options, host/port under Network
+    const optionsIdx = help.indexOf('Options:');
+    const networkIdx = help.indexOf('Network:');
+    const verboseIdx = help.indexOf('--verbose');
+    const hostIdx = help.indexOf('--host');
+    expect(verboseIdx).toBeGreaterThan(optionsIdx);
+    expect(verboseIdx).toBeLessThan(networkIdx);
+    expect(hostIdx).toBeGreaterThan(networkIdx);
+  });
+});
+
+describe('helpTemplate', () => {
+  test('custom template replaces default rendering', () => {
+    const command: CommandDef = {
+      meta: {
+        name: 'tool',
+        version: '1.0.0',
+        helpTemplate: 'NAME: {name}\nVERSION: {version}\n{usage}\n{options}',
+      },
+      args: {
+        verbose: { type: 'boolean', long: 'verbose', description: 'Verbose' },
+      },
+    };
+    const help = stripAnsi(renderHelp(command));
+    expect(help).toContain('NAME: tool');
+    expect(help).toContain('VERSION: 1.0.0');
+    expect(help).toContain('Usage:');
+    expect(help).toContain('--verbose');
+  });
+});
+
+describe('custom styles', () => {
+  test('style overrides are applied to help', () => {
+    const command: CommandDef = {
+      meta: { name: 'tool', version: '1.0.0' },
+      args: {
+        verbose: { type: 'boolean', long: 'verbose', description: 'Verbose' },
+      },
+    };
+    const customStyles = {
+      heading: (s: string) => `[H]${s}[/H]`,
+      flag: (s: string) => `[F]${s}[/F]`,
+    };
+    const help = renderHelp(command, undefined, false, customStyles);
+    expect(help).toContain('[H]Usage:[/H]');
+    expect(help).toContain('[F]--verbose[/F]');
+  });
+});

package/src/__tests__/install.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Tests for installing completions and man pages.
+ */
+
+import { describe, test, expect, afterEach, beforeEach } from 'bun:test';
+import { mkdtempSync, rmSync, readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { completionTarget, installCompletions, installManPages, withInstallers } from '../install.js';
+import { defineCommand } from '../runner.js';
+import { runCli } from '../testing.js';
+import type { Shell } from '../types.js';
+
+const main = defineCommand({
+  meta: { name: 'demo', version: '1.0', description: 'A demo' },
+  args: { verbose: { type: 'boolean', short: 'v', description: 'Verbose' } },
+  subCommands: { serve: defineCommand({ meta: { name: 'serve', description: 'Serve' }, run() {} }) },
+  run() {},
+});
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'clap-ts-install-'));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('completionTarget', () => {
+  test('names the file the way each shell expects', () => {
+    expect(completionTarget('bash', 'demo').file).toBe('demo');
+    expect(completionTarget('zsh', 'demo').file).toBe('_demo');
+    expect(completionTarget('fish', 'demo').file).toBe('demo.fish');
+    expect(completionTarget('nushell', 'demo').file).toBe('demo.nu');
+  });
+
+  test('reports a manual step only where sourcing is not automatic', () => {
+    expect(completionTarget('bash', 'demo').manualStep).toBeUndefined();
+    expect(completionTarget('fish', 'demo').manualStep).toBeUndefined();
+    expect(completionTarget('zsh', 'demo').manualStep).toContain('fpath');
+    expect(completionTarget('powershell', 'demo').manualStep).toContain('$PROFILE');
+  });
+});
+
+describe('installCompletions', () => {
+  test('writes the script and reports the path', () => {
+    const result = installCompletions(main, 'bash', { dir });
+    expect(result.paths).toEqual([join(dir, 'demo')]);
+    expect(readFileSync(result.paths[0]!, 'utf8')).toContain('# bash completion for demo');
+  });
+
+  test('a dry run reports the path and writes nothing', () => {
+    const result = installCompletions(main, 'bash', { dir: join(dir, 'nested'), dryRun: true });
+    expect(result.dryRun).toBe(true);
+    expect(existsSync(join(dir, 'nested'))).toBe(false);
+  });
+
+  test('creates the directory when it is missing', () => {
+    installCompletions(main, 'fish', { dir: join(dir, 'a', 'b') });
+    expect(existsSync(join(dir, 'a', 'b', 'demo.fish'))).toBe(true);
+  });
+
+  test('every shell installs', () => {
+    for (const shell of ['bash', 'zsh', 'fish', 'powershell', 'elvish', 'nushell'] as Shell[]) {
+      const result = installCompletions(main, shell, { dir: join(dir, shell) });
+      expect(readFileSync(result.paths[0]!, 'utf8').length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('installManPages', () => {
+  test('writes one page per command', () => {
+    const result = installManPages(main, { dir });
+    expect(readdirSync(dir).sort()).toEqual(['demo-serve.1', 'demo.1']);
+    expect(result.paths).toHaveLength(2);
+    expect(readFileSync(join(dir, 'demo.1'), 'utf8')).toContain('.TH demo 1');
+  });
+
+  test('a dry run writes nothing', () => {
+    installManPages(main, { dir: join(dir, 'nested'), dryRun: true });
+    expect(existsSync(join(dir, 'nested'))).toBe(false);
+  });
+});
+
+describe('withInstallers', () => {
+  const wrapped = withInstallers(main);
+
+  test('printing still works', async () => {
+    const { stdout } = await runCli(wrapped, ['completions', 'bash']);
+    expect(stdout).toContain('# bash completion for demo');
+  });
+
+  test('man prints roff', async () => {
+    const { stdout } = await runCli(wrapped, ['man']);
+    expect(stdout).toContain('.TH demo 1');
+  });
+
+  test('install reports what it would do', async () => {
+    const { stdout, exitCode } = await runCli(wrapped, [
+      'completions',
+      'install',
+      'zsh',
+      '--dryRun',
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('would write');
+    expect(stdout).toContain('_demo');
+    expect(stdout).toContain('note:');
+  });
+
+  test('an unknown shell is rejected with the valid ones listed', async () => {
+    const { plainStderr, exitCode } = await runCli(wrapped, ['completions', 'nope']);
+    expect(exitCode).toBe(2);
+    expect(plainStderr).toContain('possible values: bash, zsh, fish, powershell, elvish, nushell');
+  });
+
+  test('the original subcommands survive', async () => {
+    expect(wrapped.subCommands!['serve']).toBeDefined();
+  });
+});