@ontrails/core 1.0.0-beta.0

package/src/__tests__/collections.test.ts

@@ -0,0 +1,126 @@
+import { describe, test, expect } from 'bun:test';
+
+import {
+  chunk,
+  dedupe,
+  groupBy,
+  sortBy,
+  isNonEmptyArray,
+} from '../collections';
+
+describe('collections', () => {
+  describe('chunk()', () => {
+    test('splits into even chunks', () => {
+      expect(chunk([1, 2, 3, 4], 2)).toEqual([
+        [1, 2],
+        [3, 4],
+      ]);
+    });
+
+    test('handles remainder', () => {
+      expect(chunk([1, 2, 3, 4, 5], 2)).toEqual([[1, 2], [3, 4], [5]]);
+    });
+
+    test('returns empty array for empty input', () => {
+      expect(chunk([], 3)).toEqual([]);
+    });
+
+    test('single-element chunks', () => {
+      expect(chunk([1, 2, 3], 1)).toEqual([[1], [2], [3]]);
+    });
+
+    test('chunk size larger than array', () => {
+      expect(chunk([1, 2], 10)).toEqual([[1, 2]]);
+    });
+
+    test('throws on size < 1', () => {
+      expect(() => chunk([1], 0)).toThrow(RangeError);
+    });
+  });
+
+  describe('dedupe()', () => {
+    test('removes primitive duplicates', () => {
+      expect(dedupe([1, 2, 2, 3, 1])).toEqual([1, 2, 3]);
+    });
+
+    test('dedupes by key function', () => {
+      const items = [
+        { id: 1, name: 'a' },
+        { id: 2, name: 'b' },
+        { id: 1, name: 'c' },
+      ];
+      const result = dedupe(items, (i) => i.id);
+      expect(result).toEqual([
+        { id: 1, name: 'a' },
+        { id: 2, name: 'b' },
+      ]);
+    });
+
+    test('preserves order', () => {
+      expect(dedupe([3, 1, 2, 1, 3])).toEqual([3, 1, 2]);
+    });
+
+    test('handles empty array', () => {
+      expect(dedupe([])).toEqual([]);
+    });
+  });
+
+  describe('groupBy()', () => {
+    test('groups by key', () => {
+      const items = [
+        { type: 'a', value: 1 },
+        { type: 'b', value: 2 },
+        { type: 'a', value: 3 },
+      ];
+      const groups = groupBy(items, (i) => i.type);
+      expect(groups).toEqual({
+        a: [
+          { type: 'a', value: 1 },
+          { type: 'a', value: 3 },
+        ],
+        b: [{ type: 'b', value: 2 }],
+      });
+    });
+
+    test('returns empty object for empty array', () => {
+      expect(groupBy([], () => 'key')).toEqual({});
+    });
+  });
+
+  describe('sortBy()', () => {
+    test('sorts by numeric key ascending', () => {
+      const items = [{ n: 3 }, { n: 1 }, { n: 2 }];
+      expect(sortBy(items, (i) => i.n)).toEqual([{ n: 1 }, { n: 2 }, { n: 3 }]);
+    });
+
+    test('sorts by string key alphabetically', () => {
+      const items = [{ name: 'charlie' }, { name: 'alice' }, { name: 'bob' }];
+      expect(sortBy(items, (i) => i.name)).toEqual([
+        { name: 'alice' },
+        { name: 'bob' },
+        { name: 'charlie' },
+      ]);
+    });
+
+    test('does not mutate the original array', () => {
+      const original = [{ n: 3 }, { n: 1 }];
+      sortBy(original, (i) => i.n);
+      expect(original[0]?.n).toBe(3);
+    });
+
+    test('returns empty array for empty input', () => {
+      expect(sortBy([], () => 0)).toEqual([]);
+    });
+  });
+
+  describe('isNonEmptyArray()', () => {
+    test('returns true for arrays with elements', () => {
+      expect(isNonEmptyArray([1])).toBe(true);
+      expect(isNonEmptyArray([1, 2, 3])).toBe(true);
+    });
+
+    test('returns false for empty array', () => {
+      expect(isNonEmptyArray([])).toBe(false);
+    });
+  });
+});

package/src/__tests__/context.test.ts

@@ -0,0 +1,66 @@
+import { describe, test, expect } from 'bun:test';
+
+import { createTrailContext } from '../context.js';
+import type { TrailContext } from '../types.js';
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+describe('createTrailContext', () => {
+  test('generates a requestId in UUID format', () => {
+    const ctx = createTrailContext();
+    expect(ctx.requestId).toMatch(UUID_RE);
+  });
+
+  test('defaults cwd to process.cwd()', () => {
+    const ctx = createTrailContext();
+    expect(ctx.cwd).toBe(process.cwd());
+  });
+
+  test('defaults env to process.env', () => {
+    const ctx = createTrailContext();
+    expect(ctx.env).toBeTruthy();
+    expect(ctx.env).toBe(process.env);
+  });
+
+  test('provides a non-aborted signal by default', () => {
+    const ctx = createTrailContext();
+    expect(ctx.signal).toBeInstanceOf(AbortSignal);
+    expect(ctx.signal.aborted).toBe(false);
+  });
+
+  test('override values take precedence', () => {
+    const ac = new AbortController();
+    ac.abort();
+
+    const ctx = createTrailContext({
+      cwd: '/custom/dir',
+      env: { CUSTOM: 'yes' },
+      requestId: 'custom-id',
+      signal: ac.signal,
+      workspaceRoot: '/tmp',
+    });
+
+    expect(ctx.cwd).toBe('/custom/dir');
+    expect(ctx.env).toEqual({ CUSTOM: 'yes' });
+    expect(ctx.requestId).toBe('custom-id');
+    expect(ctx.signal.aborted).toBe(true);
+    expect(ctx.workspaceRoot).toBe('/tmp');
+  });
+
+  test('TrailContext is extensible with custom fields', () => {
+    const ctx: TrailContext = createTrailContext({
+      customField: 42,
+      nested: { key: 'value' },
+    });
+
+    expect(ctx['customField']).toBe(42);
+    expect(ctx['nested']).toEqual({ key: 'value' });
+  });
+
+  test('each call generates a unique requestId', () => {
+    const a = createTrailContext();
+    const b = createTrailContext();
+    expect(a.requestId).not.toBe(b.requestId);
+  });
+});

package/src/__tests__/derive.test.ts

@@ -0,0 +1,159 @@
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { deriveFields } from '../derive.js';
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('derive', () => {
+  describe('primitive types', () => {
+    test('z.string() derives string field', () => {
+      const schema = z.object({ name: z.string() });
+      const fields = deriveFields(schema);
+      expect(fields).toHaveLength(1);
+      expect(fields[0]).toMatchObject({
+        label: 'Name',
+        name: 'name',
+        required: true,
+        type: 'string',
+      });
+    });
+
+    test('z.number() derives number field', () => {
+      const schema = z.object({ count: z.number() });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'count',
+        required: true,
+        type: 'number',
+      });
+    });
+
+    test('z.boolean() derives boolean field', () => {
+      const schema = z.object({ verbose: z.boolean() });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'verbose',
+        required: true,
+        type: 'boolean',
+      });
+    });
+  });
+
+  describe('enum and multiselect', () => {
+    test('z.enum() derives enum field with options', () => {
+      const schema = z.object({ color: z.enum(['red', 'green', 'blue']) });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'color',
+        required: true,
+        type: 'enum',
+      });
+      expect(fields[0]?.options).toEqual([
+        { value: 'red' },
+        { value: 'green' },
+        { value: 'blue' },
+      ]);
+    });
+
+    test('z.array(z.enum()) derives multiselect field', () => {
+      const schema = z.object({
+        tags: z.array(z.enum(['a', 'b', 'c'])),
+      });
+      const fields = deriveFields(schema);
+      expect(fields[0]).toMatchObject({
+        name: 'tags',
+        required: true,
+        type: 'multiselect',
+      });
+      expect(fields[0]?.options).toEqual([
+        { value: 'a' },
+        { value: 'b' },
+        { value: 'c' },
+      ]);
+    });
+  });
+
+  describe('modifiers', () => {
+    test('.describe() sets label', () => {
+      const schema = z.object({
+        name: z.string().describe('Your full name'),
+      });
+      const fields = deriveFields(schema);
+      expect(fields[0]?.label).toBe('Your full name');
+    });
+
+    test('.default() sets default and marks not required', () => {
+      const schema = z.object({
+        port: z.number().default(3000),
+      });
+      const fields = deriveFields(schema);
+      expect(fields[0]?.required).toBe(false);
+      expect(fields[0]?.default).toBe(3000);
+    });
+
+    test('.optional() marks not required', () => {
+      const schema = z.object({
+        nickname: z.string().optional(),
+      });
+      const fields = deriveFields(schema);
+      expect(fields[0]?.required).toBe(false);
+    });
+  });
+
+  describe('overrides', () => {
+    test('override label replaces derived label', () => {
+      const schema = z.object({
+        name: z.string().describe('Derived label'),
+      });
+      const fields = deriveFields(schema, {
+        name: { label: 'Override label' },
+      });
+      expect(fields[0]?.label).toBe('Override label');
+    });
+
+    test('override options enrich enum values with labels and hints', () => {
+      const schema = z.object({
+        color: z.enum(['red', 'green', 'blue']),
+      });
+      const fields = deriveFields(schema, {
+        color: {
+          options: [
+            { hint: 'Hot color', label: 'Red', value: 'red' },
+            { label: 'Green', value: 'green' },
+          ],
+        },
+      });
+      expect(fields[0]?.options).toEqual([
+        { hint: 'Hot color', label: 'Red', value: 'red' },
+        { label: 'Green', value: 'green' },
+        { value: 'blue' },
+      ]);
+    });
+  });
+
+  describe('sorting and edge cases', () => {
+    test('returns fields sorted by name', () => {
+      const schema = z.object({
+        alpha: z.string(),
+        middle: z.string(),
+        zebra: z.string(),
+      });
+      const fields = deriveFields(schema);
+      expect(fields.map((f) => f.name)).toEqual(['alpha', 'middle', 'zebra']);
+    });
+
+    test('returns empty array for non-object schema', () => {
+      expect(deriveFields(z.string())).toEqual([]);
+    });
+
+    test('humanizes camelCase field names', () => {
+      const schema = z.object({ firstName: z.string() });
+      const fields = deriveFields(schema);
+      expect(fields[0]?.label).toBe('First Name');
+    });
+  });
+});

package/src/__tests__/errors.test.ts

@@ -0,0 +1,309 @@
+import { describe, test, expect } from 'bun:test';
+
+import {
+  TrailsError,
+  ValidationError,
+  AmbiguousError,
+  AssertionError,
+  NotFoundError,
+  AlreadyExistsError,
+  ConflictError,
+  PermissionError,
+  TimeoutError,
+  RateLimitError,
+  NetworkError,
+  InternalError,
+  AuthError,
+  CancelledError,
+  exitCodeMap,
+  statusCodeMap,
+  jsonRpcCodeMap,
+  retryableMap,
+  isRetryable,
+  isTrailsError,
+} from '../errors.js';
+import type { ErrorCategory } from '../errors.js';
+
+// ---------------------------------------------------------------------------
+// Error class matrix
+// ---------------------------------------------------------------------------
+
+const errorMatrix: readonly {
+  Class: new (
+    message: string,
+    options?: { cause?: Error; context?: Record<string, unknown> }
+  ) => TrailsError;
+  category: ErrorCategory;
+  retryable: boolean;
+  name: string;
+}[] = [
+  {
+    Class: ValidationError,
+    category: 'validation',
+    name: 'ValidationError',
+    retryable: false,
+  },
+  {
+    Class: AmbiguousError,
+    category: 'validation',
+    name: 'AmbiguousError',
+    retryable: false,
+  },
+  {
+    Class: AssertionError,
+    category: 'internal',
+    name: 'AssertionError',
+    retryable: false,
+  },
+  {
+    Class: NotFoundError,
+    category: 'not_found',
+    name: 'NotFoundError',
+    retryable: false,
+  },
+  {
+    Class: AlreadyExistsError,
+    category: 'conflict',
+    name: 'AlreadyExistsError',
+    retryable: false,
+  },
+  {
+    Class: ConflictError,
+    category: 'conflict',
+    name: 'ConflictError',
+    retryable: false,
+  },
+  {
+    Class: PermissionError,
+    category: 'permission',
+    name: 'PermissionError',
+    retryable: false,
+  },
+  {
+    Class: TimeoutError,
+    category: 'timeout',
+    name: 'TimeoutError',
+    retryable: true,
+  },
+  {
+    Class: RateLimitError,
+    category: 'rate_limit',
+    name: 'RateLimitError',
+    retryable: true,
+  },
+  {
+    Class: NetworkError,
+    category: 'network',
+    name: 'NetworkError',
+    retryable: true,
+  },
+  {
+    Class: InternalError,
+    category: 'internal',
+    name: 'InternalError',
+    retryable: false,
+  },
+  { Class: AuthError, category: 'auth', name: 'AuthError', retryable: false },
+  {
+    Class: CancelledError,
+    category: 'cancelled',
+    name: 'CancelledError',
+    retryable: false,
+  },
+];
+
+describe('error classes', () => {
+  // oxlint-disable-next-line prefer-each -- describe.each loses type safety on heterogeneous class matrix
+  for (const { Class, category, retryable, name } of errorMatrix) {
+    describe(name, () => {
+      test('sets correct category', () => {
+        const err = new Class('test');
+        expect(err.category).toBe(category);
+      });
+
+      test('sets correct retryable', () => {
+        const err = new Class('test');
+        expect(err.retryable).toBe(retryable);
+      });
+
+      test('sets message', () => {
+        const err = new Class('something went wrong');
+        expect(err.message).toBe('something went wrong');
+      });
+
+      test('sets name to constructor name', () => {
+        const err = new Class('test');
+        expect(err.name).toBe(name);
+      });
+
+      test('sets cause when provided', () => {
+        const cause = new Error('root cause');
+        const err = new Class('test', { cause });
+        expect(err.cause).toBe(cause);
+      });
+
+      test('sets context when provided', () => {
+        const ctx = { action: 'delete', userId: 'u_123' };
+        const err = new Class('test', { context: ctx });
+        expect(err.context).toEqual(ctx);
+      });
+
+      test('context is undefined when not provided', () => {
+        const err = new Class('test');
+        expect(err.context).toBeUndefined();
+      });
+
+      test('is instanceof TrailsError', () => {
+        const err = new Class('test');
+        expect(err).toBeInstanceOf(TrailsError);
+      });
+
+      test('is instanceof Error', () => {
+        const err = new Class('test');
+        expect(err).toBeInstanceOf(Error);
+      });
+
+      test('is instanceof its own class', () => {
+        const err = new Class('test');
+        expect(err).toBeInstanceOf(Class);
+      });
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// RateLimitError.retryAfter
+// ---------------------------------------------------------------------------
+
+describe('RateLimitError.retryAfter', () => {
+  test('stores retryAfter when provided', () => {
+    const err = new RateLimitError('slow down', { retryAfter: 30 });
+    expect(err.retryAfter).toBe(30);
+  });
+
+  test('retryAfter is undefined when not provided', () => {
+    const err = new RateLimitError('slow down');
+    expect(err.retryAfter).toBeUndefined();
+  });
+
+  test('retryAfter coexists with cause and context', () => {
+    const cause = new Error('upstream');
+    const err = new RateLimitError('slow down', {
+      cause,
+      context: { endpoint: '/api' },
+      retryAfter: 60,
+    });
+    expect(err.retryAfter).toBe(60);
+    expect(err.cause).toBe(cause);
+    expect(err.context).toEqual({ endpoint: '/api' });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Taxonomy maps
+// ---------------------------------------------------------------------------
+
+describe('exitCodeMap', () => {
+  test('maps all categories to expected exit codes', () => {
+    expect(exitCodeMap.validation).toBe(1);
+    expect(exitCodeMap.not_found).toBe(2);
+    expect(exitCodeMap.conflict).toBe(3);
+    expect(exitCodeMap.permission).toBe(4);
+    expect(exitCodeMap.timeout).toBe(5);
+    expect(exitCodeMap.rate_limit).toBe(6);
+    expect(exitCodeMap.network).toBe(7);
+    expect(exitCodeMap.internal).toBe(8);
+    expect(exitCodeMap.auth).toBe(9);
+    expect(exitCodeMap.cancelled).toBe(130);
+  });
+});
+
+describe('statusCodeMap', () => {
+  test('maps all categories to expected HTTP status codes', () => {
+    expect(statusCodeMap.validation).toBe(400);
+    expect(statusCodeMap.not_found).toBe(404);
+    expect(statusCodeMap.conflict).toBe(409);
+    expect(statusCodeMap.permission).toBe(403);
+    expect(statusCodeMap.timeout).toBe(504);
+    expect(statusCodeMap.rate_limit).toBe(429);
+    expect(statusCodeMap.network).toBe(502);
+    expect(statusCodeMap.internal).toBe(500);
+    expect(statusCodeMap.auth).toBe(401);
+    expect(statusCodeMap.cancelled).toBe(499);
+  });
+});
+
+describe('jsonRpcCodeMap', () => {
+  test('maps all categories to expected JSON-RPC codes', () => {
+    expect(jsonRpcCodeMap.validation).toBe(-32_602);
+    expect(jsonRpcCodeMap.not_found).toBe(-32_601);
+    expect(jsonRpcCodeMap.conflict).toBe(-32_603);
+    expect(jsonRpcCodeMap.permission).toBe(-32_600);
+    expect(jsonRpcCodeMap.timeout).toBe(-32_603);
+    expect(jsonRpcCodeMap.rate_limit).toBe(-32_603);
+    expect(jsonRpcCodeMap.network).toBe(-32_603);
+    expect(jsonRpcCodeMap.internal).toBe(-32_603);
+    expect(jsonRpcCodeMap.auth).toBe(-32_600);
+    expect(jsonRpcCodeMap.cancelled).toBe(-32_603);
+  });
+});
+
+describe('retryableMap', () => {
+  test('only timeout, rate_limit, and network are retryable', () => {
+    expect(retryableMap.timeout).toBe(true);
+    expect(retryableMap.rate_limit).toBe(true);
+    expect(retryableMap.network).toBe(true);
+
+    expect(retryableMap.validation).toBe(false);
+    expect(retryableMap.not_found).toBe(false);
+    expect(retryableMap.conflict).toBe(false);
+    expect(retryableMap.permission).toBe(false);
+    expect(retryableMap.internal).toBe(false);
+    expect(retryableMap.auth).toBe(false);
+    expect(retryableMap.cancelled).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Helper functions
+// ---------------------------------------------------------------------------
+
+describe('isRetryable', () => {
+  test('returns true for retryable errors', () => {
+    expect(isRetryable(new TimeoutError('timed out'))).toBe(true);
+    expect(isRetryable(new RateLimitError('too fast'))).toBe(true);
+    expect(isRetryable(new NetworkError('disconnected'))).toBe(true);
+  });
+
+  test('returns false for non-retryable errors', () => {
+    expect(isRetryable(new ValidationError('bad input'))).toBe(false);
+    expect(isRetryable(new NotFoundError('missing'))).toBe(false);
+    expect(isRetryable(new AuthError('unauthorized'))).toBe(false);
+    expect(isRetryable(new InternalError('oops'))).toBe(false);
+    expect(isRetryable(new CancelledError('aborted'))).toBe(false);
+  });
+
+  test('returns false for plain Error', () => {
+    expect(isRetryable(new Error('generic'))).toBe(false);
+  });
+});
+
+describe('isTrailsError', () => {
+  test('returns true for TrailsError subclasses', () => {
+    expect(isTrailsError(new ValidationError('bad'))).toBe(true);
+    expect(isTrailsError(new NetworkError('down'))).toBe(true);
+    expect(isTrailsError(new CancelledError('stop'))).toBe(true);
+  });
+
+  test('returns false for plain Error', () => {
+    expect(isTrailsError(new Error('nope'))).toBe(false);
+  });
+
+  test('returns false for non-error values', () => {
+    expect(isTrailsError(null)).toBe(false);
+    expect(isTrailsError()).toBe(false);
+    expect(isTrailsError('string')).toBe(false);
+    expect(isTrailsError(42)).toBe(false);
+    expect(isTrailsError({})).toBe(false);
+  });
+});