@ontrails/core 1.0.0-beta.0

package/src/__tests__/validate-topo.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { Result } from '../result.js';
+import { topo } from '../topo.js';
+import type { TopoIssue } from '../validate-topo.js';
+import { validateTopo } from '../validate-topo.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// oxlint-disable-next-line require-await -- satisfies async interface
+const noop = async () => Result.ok();
+
+const mockTrail = (
+  id: string,
+  overrides?: {
+    examples?: readonly {
+      name: string;
+      input: unknown;
+      expected?: unknown;
+      error?: string;
+    }[];
+    output?: z.ZodType;
+  }
+) => ({
+  id,
+  implementation: noop,
+  input: z.object({ name: z.string() }),
+  kind: 'trail' as const,
+  ...overrides,
+});
+
+const mockHike = (id: string, follows: readonly string[]) => ({
+  follows,
+  id,
+  implementation: noop,
+  input: z.object({ q: z.string() }),
+  kind: 'hike' as const,
+});
+
+const mockEvent = (id: string, from?: readonly string[]) => ({
+  from,
+  id,
+  kind: 'event' as const,
+  payload: z.object({ data: z.string() }),
+});
+
+/** Extract issues from a failed validateTopo result. */
+const extractIssues = (result: Result<void, Error>): TopoIssue[] => {
+  if (result.isOk()) {
+    return [];
+  }
+  const ctx = (result.error as { context?: { issues?: TopoIssue[] } }).context;
+  return (ctx?.issues ?? []) as TopoIssue[];
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('validateTopo', () => {
+  test('valid topo passes', () => {
+    const app = topo('app', {
+      add: mockTrail('entity.add'),
+      onboard: mockHike('entity.onboard', ['entity.add']),
+      updated: mockEvent('entity.updated', ['entity.add']),
+    });
+
+    const result = validateTopo(app);
+    expect(result.isOk()).toBe(true);
+  });
+
+  describe('hike follows', () => {
+    test('hike following non-existent trail fails', () => {
+      const app = topo('app', {
+        onboard: mockHike('entity.onboard', ['entity.missing']),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      expect(issues).toHaveLength(1);
+      expect(issues[0]?.rule).toBe('follows-exist');
+      expect(issues[0]?.message).toContain('entity.missing');
+    });
+
+    test('hike following itself fails', () => {
+      const app = topo('app', {
+        loop: mockHike('entity.loop', ['entity.loop']),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      expect(issues).toHaveLength(1);
+      expect(issues[0]?.rule).toBe('no-self-follow');
+    });
+  });
+
+  describe('example validation', () => {
+    test('example with invalid input fails', () => {
+      const app = topo('app', {
+        show: mockTrail('entity.show', {
+          examples: [{ input: { name: 123 }, name: 'Bad input' }],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      expect(issues).toHaveLength(1);
+      expect(issues[0]?.rule).toBe('example-input-valid');
+      expect(issues[0]?.message).toContain('Bad input');
+    });
+
+    test('example with expected output but no output schema warns', () => {
+      const app = topo('app', {
+        show: mockTrail('entity.show', {
+          examples: [
+            {
+              expected: { result: 'ok' },
+              input: { name: 'test' },
+              name: 'Has expected',
+            },
+          ],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      expect(issues).toHaveLength(1);
+      expect(issues[0]?.rule).toBe('output-schema-present');
+    });
+
+    test('error example with invalid input is allowed', () => {
+      const app = topo('app', {
+        show: mockTrail('entity.show', {
+          examples: [
+            {
+              error: 'ValidationError',
+              input: { name: 123 },
+              name: 'Error case',
+            },
+          ],
+        }),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+  });
+
+  describe('event origins', () => {
+    test('event with non-existent origin fails', () => {
+      const app = topo('app', {
+        updated: mockEvent('entity.updated', ['entity.ghost']),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isErr()).toBe(true);
+
+      const issues = extractIssues(result);
+      expect(issues).toHaveLength(1);
+      expect(issues[0]?.rule).toBe('event-origin-exists');
+      expect(issues[0]?.message).toContain('entity.ghost');
+    });
+
+    test('event without origins is accepted', () => {
+      const app = topo('app', {
+        updated: mockEvent('entity.updated'),
+      });
+
+      const result = validateTopo(app);
+      expect(result.isOk()).toBe(true);
+    });
+  });
+
+  test('collects multiple issues', () => {
+    const app = topo('app', {
+      broken: mockHike('entity.broken', ['entity.missing']),
+      show: mockTrail('entity.show', {
+        examples: [{ input: { name: 123 }, name: 'Bad' }],
+      }),
+      updated: mockEvent('entity.updated', ['entity.ghost']),
+    });
+
+    const result = validateTopo(app);
+    expect(result.isErr()).toBe(true);
+
+    const issues = extractIssues(result);
+    expect(issues).toHaveLength(3);
+  });
+});

package/src/__tests__/validation.test.ts

@@ -0,0 +1,283 @@
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { ValidationError } from '../errors.js';
+import {
+  validateInput,
+  validateOutput,
+  formatZodIssues,
+  zodToJsonSchema,
+} from '../validation.js';
+
+// ---------------------------------------------------------------------------
+// validateInput
+// ---------------------------------------------------------------------------
+
+describe('validateInput', () => {
+  const schema = z.object({
+    age: z.number().min(0),
+    name: z.string(),
+  });
+
+  test('returns Ok for valid data', () => {
+    const result = validateInput(schema, { age: 30, name: 'Alice' });
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ age: 30, name: 'Alice' });
+  });
+
+  test('returns Err with ValidationError for invalid data', () => {
+    const result = validateInput(schema, { name: 123 });
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error).toBeInstanceOf(ValidationError);
+    expect(err.error.category).toBe('validation');
+  });
+
+  test('includes formatted issues in error message', () => {
+    const result = validateInput(schema, {});
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error.message).toContain('name');
+  });
+
+  test('attaches ZodError as cause', () => {
+    const result = validateInput(schema, {});
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error.cause).toBeInstanceOf(z.ZodError);
+  });
+
+  test('attaches issues in context', () => {
+    const result = validateInput(schema, {});
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error.context).toBeDefined();
+    expect(Array.isArray(err.error.context?.['issues'])).toBe(true);
+  });
+
+  test('works with simple string schema', () => {
+    const str = z.string().min(1);
+    expect(validateInput(str, 'hello').isOk()).toBe(true);
+    expect(validateInput(str, '').isErr()).toBe(true);
+    expect(validateInput(str, 42).isErr()).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateOutput
+// ---------------------------------------------------------------------------
+
+describe('validateOutput', () => {
+  const schema = z.object({
+    id: z.string(),
+    score: z.number(),
+  });
+
+  test('returns Ok for valid data', () => {
+    const result = validateOutput(schema, { id: 'abc', score: 42 });
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ id: 'abc', score: 42 });
+  });
+
+  test('returns Err with ValidationError for invalid data', () => {
+    const result = validateOutput(schema, { id: 123 });
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error).toBeInstanceOf(ValidationError);
+    expect(err.error.category).toBe('validation');
+  });
+
+  test('error message includes "Output validation failed" prefix', () => {
+    const result = validateOutput(schema, {});
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error.message).toContain('Output validation failed');
+  });
+
+  test('attaches ZodError as cause', () => {
+    const result = validateOutput(schema, {});
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error.cause).toBeInstanceOf(z.ZodError);
+  });
+
+  test('attaches issues in context', () => {
+    const result = validateOutput(schema, {});
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error.context).toBeDefined();
+    expect(Array.isArray(err.error.context?.['issues'])).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatZodIssues
+// ---------------------------------------------------------------------------
+
+describe('formatZodIssues', () => {
+  test('formats issues with paths', () => {
+    const schema = z.object({ email: z.string().email() });
+    const parsed = schema.safeParse({ email: 'not-email' });
+    expect(parsed.success).toBe(false);
+    const failed1 = parsed as unknown as { error: z.ZodError };
+    const messages1 = formatZodIssues(failed1.error.issues);
+    expect(messages1.length).toBeGreaterThan(0);
+    expect(messages1[0]).toMatch(/^email: /);
+  });
+
+  test('formats root-level issues without path prefix', () => {
+    const schema = z.string();
+    const parsed = schema.safeParse(42);
+    expect(parsed.success).toBe(false);
+    const failed = parsed as unknown as { error: z.ZodError };
+    const messages = formatZodIssues(failed.error.issues);
+    expect(messages.length).toBeGreaterThan(0);
+    // Root issues have no "path: " prefix — message starts directly
+    // (the message itself may contain colons, but won't start with "path: ")
+    expect(messages[0]).not.toMatch(/^\w+: /);
+  });
+
+  test('formats nested paths with dot notation', () => {
+    const schema = z.object({
+      user: z.object({ name: z.string() }),
+    });
+    const parsed = schema.safeParse({ user: { name: 123 } });
+    expect(parsed.success).toBe(false);
+    const failed = parsed as unknown as { error: z.ZodError };
+    const messages = formatZodIssues(failed.error.issues);
+    expect(messages[0]).toMatch(/^user\.name: /);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// zodToJsonSchema
+// ---------------------------------------------------------------------------
+
+describe('zodToJsonSchema', () => {
+  describe('primitives', () => {
+    test('converts z.string()', () => {
+      expect(zodToJsonSchema(z.string())).toEqual({ type: 'string' });
+    });
+
+    test('converts z.number()', () => {
+      expect(zodToJsonSchema(z.number())).toEqual({ type: 'number' });
+    });
+
+    test('converts z.boolean()', () => {
+      expect(zodToJsonSchema(z.boolean())).toEqual({ type: 'boolean' });
+    });
+
+    test('converts z.literal()', () => {
+      expect(zodToJsonSchema(z.literal('hello'))).toEqual({ const: 'hello' });
+      expect(zodToJsonSchema(z.literal(42))).toEqual({ const: 42 });
+    });
+
+    test('converts z.enum()', () => {
+      expect(zodToJsonSchema(z.enum(['a', 'b', 'c']))).toEqual({
+        enum: ['a', 'b', 'c'],
+        type: 'string',
+      });
+    });
+
+    test('converts z.array()', () => {
+      expect(zodToJsonSchema(z.array(z.string()))).toEqual({
+        items: { type: 'string' },
+        type: 'array',
+      });
+    });
+  });
+
+  describe('objects', () => {
+    test('converts z.object() with required fields', () => {
+      const schema = z.object({ age: z.number(), name: z.string() });
+      const result = zodToJsonSchema(schema);
+      expect(result).toEqual({
+        properties: {
+          age: { type: 'number' },
+          name: { type: 'string' },
+        },
+        required: ['age', 'name'],
+        type: 'object',
+      });
+    });
+
+    test('converts z.object() with optional fields', () => {
+      const schema = z.object({
+        name: z.string(),
+        nickname: z.string().optional(),
+      });
+      const result = zodToJsonSchema(schema);
+      expect(result).toEqual({
+        properties: {
+          name: { type: 'string' },
+          nickname: { type: 'string' },
+        },
+        required: ['name'],
+        type: 'object',
+      });
+    });
+
+    test('converts z.object() with default fields', () => {
+      const schema = z.object({
+        name: z.string(),
+        role: z.string().default('user'),
+      });
+      const result = zodToJsonSchema(schema);
+      expect(result).toEqual({
+        properties: {
+          name: { type: 'string' },
+          role: { default: 'user', type: 'string' },
+        },
+        required: ['name'],
+        type: 'object',
+      });
+    });
+
+    test('handles nested objects', () => {
+      const schema = z.object({
+        user: z.object({ name: z.string() }),
+      });
+      expect(zodToJsonSchema(schema)).toEqual({
+        properties: {
+          user: {
+            properties: { name: { type: 'string' } },
+            required: ['name'],
+            type: 'object',
+          },
+        },
+        required: ['user'],
+        type: 'object',
+      });
+    });
+  });
+
+  describe('modifiers and combinators', () => {
+    test('converts z.union()', () => {
+      const schema = z.union([z.string(), z.number()]);
+      expect(zodToJsonSchema(schema)).toEqual({
+        anyOf: [{ type: 'string' }, { type: 'number' }],
+      });
+    });
+
+    test('preserves z.describe()', () => {
+      const schema = z.string().describe('A user name');
+      expect(zodToJsonSchema(schema)).toEqual({
+        description: 'A user name',
+        type: 'string',
+      });
+    });
+
+    test('handles z.nullable()', () => {
+      const schema = z.string().nullable();
+      expect(zodToJsonSchema(schema)).toEqual({
+        anyOf: [{ type: 'string' }, { type: 'null' }],
+      });
+    });
+
+    test('returns empty object for unknown types', () => {
+      // z.any() is not in our coverage list
+      expect(zodToJsonSchema(z.any())).toEqual({});
+    });
+  });
+});

package/src/__tests__/workspace.test.ts

@@ -0,0 +1,183 @@
+import { describe, test, expect } from 'bun:test';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve, join } from 'node:path';
+
+import { NotFoundError } from '../errors.js';
+import {
+  findWorkspaceRoot,
+  isInsideWorkspace,
+  getRelativePath,
+} from '../workspace.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const createTempDir = (): string =>
+  mkdtempSync(join(tmpdir(), 'trails-ws-test-'));
+
+const writeJson = (dir: string, filename: string, data: unknown): void => {
+  writeFileSync(join(dir, filename), JSON.stringify(data, null, 2));
+};
+
+/** Set up nested workspaces: outer > inner > packages/lib. Returns the deepest path. */
+const setupNestedWorkspaces = (outer: string): string => {
+  writeJson(outer, 'package.json', { name: 'outer', workspaces: ['inner/*'] });
+  const inner = join(outer, 'inner', 'nested');
+  mkdirSync(inner, { recursive: true });
+  writeJson(join(outer, 'inner'), 'package.json', {
+    name: 'inner',
+    workspaces: ['packages/*'],
+  });
+  const deep = join(inner, 'packages', 'lib');
+  mkdirSync(deep, { recursive: true });
+  return deep;
+};
+
+// ---------------------------------------------------------------------------
+// findWorkspaceRoot
+// ---------------------------------------------------------------------------
+
+describe('findWorkspaceRoot', () => {
+  test('finds workspace root when started inside a nested directory', async () => {
+    const root = createTempDir();
+    try {
+      writeJson(root, 'package.json', {
+        name: 'my-workspace',
+        workspaces: ['packages/*'],
+      });
+
+      const nested = join(root, 'packages', 'core', 'src');
+      mkdirSync(nested, { recursive: true });
+
+      const result = await findWorkspaceRoot(nested);
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toBe(resolve(root));
+    } finally {
+      rmSync(root, { force: true, recursive: true });
+    }
+  });
+
+  test('skips package.json without workspaces field', async () => {
+    const root = createTempDir();
+    try {
+      // Root has workspaces
+      writeJson(root, 'package.json', {
+        name: 'root',
+        workspaces: ['packages/*'],
+      });
+
+      // Nested package has no workspaces
+      const pkg = join(root, 'packages', 'core');
+      mkdirSync(pkg, { recursive: true });
+      writeJson(pkg, 'package.json', { name: '@scope/core' });
+
+      const result = await findWorkspaceRoot(pkg);
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toBe(resolve(root));
+    } finally {
+      rmSync(root, { force: true, recursive: true });
+    }
+  });
+
+  test('returns the closest workspace root', async () => {
+    const outer = createTempDir();
+    try {
+      const deep = setupNestedWorkspaces(outer);
+      const result = await findWorkspaceRoot(deep);
+      expect(result.isOk()).toBe(true);
+      // Should find inner workspace first (closest ancestor)
+      expect(result.unwrap()).toBe(resolve(join(outer, 'inner')));
+    } finally {
+      rmSync(outer, { force: true, recursive: true });
+    }
+  });
+
+  test('returns NotFoundError when no workspace root exists', async () => {
+    const dir = createTempDir();
+    try {
+      // No package.json at all
+      const result = await findWorkspaceRoot(dir);
+      // This will either find one above in the actual filesystem or fail.
+      // We walk up to /, so it depends on the host. Use a deep isolated path.
+      // Since tmpdir might be under a workspace, let's just check the type
+      // is correct if it does fail. When the host has a workspace root above
+      // tmpdir, the result will be Ok — both outcomes are acceptable.
+      const isAcceptable =
+        // oxlint-disable-next-line no-conditional-in-test -- host-dependent: tmpdir may sit under a real workspace
+        result.isOk() ||
+        (result as unknown as { error: Error }).error instanceof NotFoundError;
+      expect(isAcceptable).toBe(true);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('handles malformed package.json gracefully', async () => {
+    const root = createTempDir();
+    try {
+      // Write invalid JSON
+      writeFileSync(join(root, 'package.json'), 'not json {{{');
+
+      const result = await findWorkspaceRoot(root);
+      // Should not throw — just skip and keep walking.
+      // On some hosts tmpdir sits under a real workspace, so Ok is valid too.
+      const isAcceptable =
+        // oxlint-disable-next-line no-conditional-in-test -- host-dependent: tmpdir may sit under a real workspace
+        result.isOk() ||
+        (result as unknown as { error: Error }).error instanceof NotFoundError;
+      expect(isAcceptable).toBe(true);
+    } finally {
+      rmSync(root, { force: true, recursive: true });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isInsideWorkspace
+// ---------------------------------------------------------------------------
+
+describe('isInsideWorkspace', () => {
+  test('returns true for a file inside the workspace', () => {
+    expect(
+      isInsideWorkspace('/project/packages/core/src/index.ts', '/project')
+    ).toBe(true);
+  });
+
+  test('returns false for a file outside the workspace', () => {
+    expect(isInsideWorkspace('/other/file.ts', '/project')).toBe(false);
+  });
+
+  test('returns false for the workspace root itself', () => {
+    // The root directory itself is not \"inside\" the workspace
+    expect(isInsideWorkspace('/project', '/project')).toBe(false);
+  });
+
+  test('handles relative-looking paths by resolving them', () => {
+    expect(
+      isInsideWorkspace('/project/packages/../packages/core', '/project')
+    ).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getRelativePath
+// ---------------------------------------------------------------------------
+
+describe('getRelativePath', () => {
+  test('returns relative path from workspace root', () => {
+    expect(
+      getRelativePath('/project/packages/core/src/index.ts', '/project')
+    ).toBe('packages/core/src/index.ts');
+  });
+
+  test('returns .. segments for paths outside workspace', () => {
+    const rel = getRelativePath('/other/file.ts', '/project');
+    expect(rel.startsWith('..')).toBe(true);
+  });
+
+  test('returns empty string for the root itself', () => {
+    expect(getRelativePath('/project', '/project')).toBe('');
+  });
+});