runspec-node 0.17.1 → 0.21.0

package/tests/test_loader.test.ts

@@ -106,6 +106,39 @@ workers = {default = 4, range = [1, 32]}
   expect(raw.runnables['greet'].args['workers'].range).toEqual([1, 32]);
 });
 
+test('normalises pattern / min-length / max-length fields', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[greet]
+description = "hi"
+
+[greet.args]
+slug = {type = "str", pattern = "[a-z]+-[0-9]+", min-length = 3, max-length = 10}
+`);
+  const raw = loadRaw(file);
+  const slug = raw.runnables['greet'].args['slug'];
+  expect(slug.pattern).toBe('[a-z]+-[0-9]+');
+  expect(slug.minLength).toBe(3);
+  expect(slug.maxLength).toBe(10);
+});
+
+test('normalises require-command on a runnable', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[db]
+require-command = true
+
+[db.commands.migrate]
+description = "run migrations"
+`);
+  const raw = loadRaw(file);
+  expect(raw.runnables['db'].requireCommand).toBe(true);
+  // Defaults to false when absent.
+  expect(raw.runnables['db'].commands['migrate'].requireCommand).toBe(false);
+});
+
 test('normalises group fields', () => {
   const dir = tmpDir();
   const file = path.join(dir, 'runspec.toml');

package/tests/test_parser.test.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { parse } from '../src/parser';
+import { parse, loadSpec } from '../src/parser';
 
 function makeTmpConfig(toml: string): string {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-parser-test-'));
@@ -157,3 +157,85 @@ description = "Run it"
     expect(usage.indexOf('<command>')).toBeLessThan(usage.indexOf('-- <extra>'));
   });
 });
+
+// ── require-command ─────────────────────────────────────────────────────────────
+
+describe('require-command', () => {
+  const DB_TOML = `
+[db]
+require-command = true
+[db.commands.migrate]
+[db.commands.seed]
+`;
+
+  test('no command errors and lists commands', () => {
+    const configPath = makeTmpConfig(DB_TOML);
+    let msg = '';
+    try {
+      parse({ scriptName: 'db', argv: [], configPath });
+      throw new Error('expected parse to throw');
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toContain('requires a command');
+    expect(msg).toContain('migrate');
+    expect(msg).toContain('seed');
+  });
+
+  test('valid command passes', () => {
+    const configPath = makeTmpConfig(DB_TOML);
+    const args = parse({ scriptName: 'db', argv: ['migrate'], configPath });
+    expect(args.runspec_command_path).toEqual(['migrate']);
+    expect(args.runspec_command).toBe('migrate');
+  });
+
+  test('nested requirement enforced at each depth', () => {
+    const toml = `
+[app]
+require-command = true
+[app.commands.db]
+require-command = true
+[app.commands.db.commands.migrate]
+`;
+    const configPath = makeTmpConfig(toml);
+    // Choosing the intermediate command isn't enough — db itself requires one.
+    expect(() => parse({ scriptName: 'app', argv: ['db'], configPath })).toThrow(/requires a command/);
+    // Going all the way down satisfies it.
+    const args = parse({ scriptName: 'app', argv: ['db', 'migrate'], configPath });
+    expect(args.runspec_command_path).toEqual(['db', 'migrate']);
+  });
+
+  test('backward compatible: commands without require-command run at root', () => {
+    const toml = `
+[tool]
+[tool.commands.run]
+`;
+    const configPath = makeTmpConfig(toml);
+    const args = parse({ scriptName: 'tool', argv: [], configPath });
+    expect(args.runspec_command_path).toEqual([]);
+  });
+
+  test('loadSpec bypasses enforcement', () => {
+    const configPath = makeTmpConfig(DB_TOML);
+    const spec = loadSpec({ scriptName: 'db', configPath });
+    expect(spec.runspec_command_path).toEqual([]);
+  });
+
+  test('--help still works at a required level', () => {
+    const configPath = makeTmpConfig(DB_TOML);
+    const output: string[] = [];
+    const logSpy = jest.spyOn(console, 'log').mockImplementation((...a) => { output.push(a.join(' ')); });
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => { throw new Error('__exit__'); }) as never);
+    try {
+      parse({ scriptName: 'db', argv: ['--help'], configPath });
+    } catch (e) {
+      if ((e as Error).message !== '__exit__') throw e;
+    } finally {
+      logSpy.mockRestore();
+      exitSpy.mockRestore();
+    }
+    const out = output.join('\n');
+    expect(out).toContain('Commands (required):');
+    expect(out).toContain('migrate');
+  });
+});

package/tests/test_run_summary.test.ts

@@ -6,7 +6,11 @@ import {
   getLogger,
   emitRunSummary,
   _resetForTest,
+  _handleUncaught,
+  buildExcStructured,
+  formatCompactTrace,
   RUN_SUMMARY_LOGGER,
+  EXCEPTION_LOGGER,
 } from '../src/logging_setup';
 
 function tmpDir(): string {
@@ -260,3 +264,98 @@ test('sudo user_target written to audit record', () => {
   expect(summary.extra.user).toBe('alice');
   expect(summary.extra.user_target).toBe('root');
 });
+
+// ── uncaught exceptions ────────────────────────────────────────────────────────
+
+function readExcRecord(dir: string): Record<string, any> | undefined {
+  const content = fs.readFileSync(path.join(dir, 'logs', 'myscript.log'), 'utf-8');
+  return content.trim().split('\n').map(l => JSON.parse(l)).find(o => o.logger === EXCEPTION_LOGGER);
+}
+
+test('uncaught exception writes a structured record even with summary off', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir, { summary: false }));
+  const cap = captureStderr();
+  _handleUncaught(new TypeError('invalid quality 200'));
+  cap.restore();
+  const rec = readExcRecord(dir);
+  expect(rec).toBeDefined();
+  expect(rec!.level).toBe('CRITICAL');
+  expect(rec!.exc_structured.type).toBe('TypeError');
+  expect(rec!.exc_structured.message).toBe('invalid quality 200');
+  expect(Array.isArray(rec!.exc_structured.frames)).toBe(true);
+  expect(rec!.exc).toBeDefined(); // full stack string also present
+});
+
+test('without --debug the console shows a one-liner, not a traceback', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir, { debug: false }));
+  const cap = captureStderr();
+  _handleUncaught(new Error('boom'));
+  cap.restore();
+  const joined = cap.lines.join('');
+  expect(joined).toContain('ERROR: Error: boom');
+  expect(joined).toContain('run with --debug');
+  expect(joined).not.toContain('\n    at '); // no raw V8 stack dump
+  expect(readExcRecord(dir)).toBeDefined();
+});
+
+test('with --debug the console shows a compact aligned trace', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir, { debug: true }));
+  const cap = captureStderr();
+  _handleUncaught(new Error('boom'));
+  cap.restore();
+  const joined = cap.lines.join('');
+  expect(joined).toContain('Error: boom');
+  expect(joined).not.toContain('run with --debug'); // hint only in quiet mode
+});
+
+test('the exception record is not echoed to the console handlers', () => {
+  const dir = tmpDir();
+  const stdoutLines: string[] = [];
+  const stderrLines: string[] = [];
+  const o = jest.spyOn(process.stdout, 'write').mockImplementation((c) => { stdoutLines.push(String(c)); return true; });
+  const e = jest.spyOn(process.stderr, 'write').mockImplementation((c) => { stderrLines.push(String(c)); return true; });
+  configureLogging(makeCfg(dir, { debug: false }));
+  _handleUncaught(new Error('boom'));
+  o.mockRestore();
+  e.mockRestore();
+  // The structured JSON record is file-only; only our one-liner hits stderr.
+  expect(stdoutLines.join('')).not.toContain('uncaught exception');
+  expect(stderrLines.join('')).not.toContain('"logger":"runspec.exception"');
+});
+
+test('buildExcStructured parses frames innermost-last with module', () => {
+  const err = new Error('x');
+  err.stack = [
+    'Error: x',
+    '    at inner (/app/deep.js:5:10)',
+    '    at outer (/app/main.js:20:3)',
+  ].join('\n');
+  const es = buildExcStructured(err);
+  expect(es.type).toBe('Error');
+  expect(es.frames.map(f => f.func)).toEqual(['outer', 'inner']); // innermost last
+  expect(es.module).toBe('deep');
+  expect(es.frames[0]).toEqual({ func: 'outer', file: '/app/main.js', line: 20, code: null });
+});
+
+test('formatCompactTrace drops internal runspec frames but keeps user frames', () => {
+  const err = new Error('x');
+  // RUNSPEC_PKG_DIR is the dir of the logging_setup module (the package source).
+  const pkgDir = path.resolve(__dirname, '..', 'src');
+  const frames = [
+    { func: 'parse', file: path.join(pkgDir, 'parser.ts'), line: 10, code: null },
+    { func: 'main', file: '/app/deploy.js', line: 42, code: null },
+  ];
+  const out = formatCompactTrace(err, frames);
+  expect(out).toContain('deploy.js:42');
+  expect(out).not.toContain('parser.ts:10');
+});
+
+test('formatCompactTrace falls back to full list when every frame is internal', () => {
+  const err = new Error('x');
+  const pkgDir = path.resolve(__dirname, '..', 'src');
+  const frames = [{ func: 'parse', file: path.join(pkgDir, 'parser.ts'), line: 10, code: null }];
+  expect(formatCompactTrace(err, frames)).toContain('parser.ts:10');
+});

package/tests/test_types.test.ts

@@ -15,6 +15,38 @@ test('coerces number to string', () => {
   expect(coerce(42, spec({ type: 'str' }))).toBe('42');
 });
 
+// ── str validation: pattern / min-length / max-length (str only) ───────────────
+
+test('str matches pattern', () => {
+  expect(coerce('PROJ-123', spec({ type: 'str', pattern: '[A-Z]+-[0-9]+' }))).toBe('PROJ-123');
+});
+
+test('str violates pattern', () => {
+  expect(() => coerce('proj-123', spec({ type: 'str', pattern: '[A-Z]+-[0-9]+' }))).toThrow();
+});
+
+test('pattern is anchored (fullmatch, not substring)', () => {
+  expect(() => coerce('PROJ-123-extra', spec({ type: 'str', pattern: '[A-Z]+-[0-9]+' }))).toThrow();
+});
+
+test('anchored pattern wraps top-level alternation correctly', () => {
+  // ^(?:a|b)$ accepts only "a" or "b" exactly, not a string ending in "b".
+  expect(coerce('a', spec({ type: 'str', pattern: 'a|b' }))).toBe('a');
+  expect(() => coerce('xb', spec({ type: 'str', pattern: 'a|b' }))).toThrow();
+});
+
+test('str respects minLength', () => {
+  expect(() => coerce('ab', spec({ type: 'str', minLength: 3 }))).toThrow();
+});
+
+test('str respects maxLength', () => {
+  expect(() => coerce('abcdef', spec({ type: 'str', maxLength: 5 }))).toThrow();
+});
+
+test('str within length bounds passes', () => {
+  expect(coerce('hello', spec({ type: 'str', minLength: 3, maxLength: 10 }))).toBe('hello');
+});
+
 // ── int ───────────────────────────────────────────────────────────────────────
 
 test('coerces integer string', () => {
@@ -97,6 +129,47 @@ test('rejects invalid choice', () => {
   expect(() => coerce('xml', spec({ type: 'choice', options: ['json', 'csv'] }))).toThrow();
 });
 
+// ── multiple (per-item coercion) ───────────────────────────────────────────────
+
+test('multiple returns a list of coerced items', () => {
+  expect(coerce(['a', 'b', 'c'], spec({ type: 'str', multiple: true }))).toEqual(['a', 'b', 'c']);
+});
+
+test('multiple int coerces each item', () => {
+  expect(coerce(['1', '2', '3'], spec({ type: 'int', multiple: true }))).toEqual([1, 2, 3]);
+});
+
+test('multiple applies pattern per item', () => {
+  const s = spec({ type: 'str', multiple: true, pattern: '[a-z]+' });
+  expect(coerce(['ab', 'cd'], s)).toEqual(['ab', 'cd']);
+});
+
+test('multiple wraps a scalar value into a one-item list', () => {
+  expect(coerce('solo', spec({ type: 'str', multiple: true }))).toEqual(['solo']);
+});
+
+test('multiple collects all failing items with index and value', () => {
+  const s = spec({ name: 'tag', type: 'str', multiple: true, pattern: '[a-z]+' });
+  let msg = '';
+  try {
+    coerce(['ab', 'XY', 'z9', 'de'], s);
+  } catch (e) {
+    msg = (e as Error).message;
+  }
+  expect(msg).toContain('2 of 4 item(s) failed');
+  expect(msg).toContain('item 2 ("XY")');
+  expect(msg).toContain('item 3 ("z9")');
+});
+
+test('multiple range applies per item', () => {
+  const s = spec({ name: 'n', type: 'int', multiple: true, range: [1, 10] });
+  expect(() => coerce(['5', '99'], s)).toThrow(/item 2 \("99"\)/);
+});
+
+test('rest type is not treated as per-item', () => {
+  expect(coerce(['--flag', 'value'], spec({ type: 'rest' }))).toEqual(['--flag', 'value']);
+});
+
 // ── custom types ──────────────────────────────────────────────────────────────
 
 test('registerType adds custom coercer', () => {