@ontrails/schema 1.0.0-beta.0

package/src/__tests__/generate.test.ts

@@ -0,0 +1,252 @@
+import { describe, test, expect } from 'bun:test';
+
+import { trail, hike, event, topo, Result } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { generateSurfaceMap } from '../generate.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const topoFrom = (...modules: Record<string, unknown>[]): Topo =>
+  topo('test-app', ...modules);
+
+const noop = () => Result.ok(null as unknown);
+
+const getFirstEntry = (map: ReturnType<typeof generateSurfaceMap>) => {
+  const [entry] = map.entries;
+  expect(entry).toBeDefined();
+  if (!entry) {
+    throw new Error('Expected surface map entry');
+  }
+  return entry;
+};
+
+const expectSchemaProperties = (
+  schema: unknown,
+  properties: Record<string, unknown>
+) => {
+  expect(schema).toEqual(
+    expect.objectContaining({
+      properties: expect.objectContaining(properties),
+      type: 'object',
+    })
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('generateSurfaceMap', () => {
+  describe('entries', () => {
+    test('produces entries for all trails in the topo', () => {
+      const a = trail('a.create', {
+        implementation: noop,
+        input: z.object({ name: z.string() }),
+      });
+      const b = trail('b.list', {
+        implementation: noop,
+        input: z.object({}),
+      });
+      const tp = topoFrom({ a, b });
+      const map = generateSurfaceMap(tp);
+
+      expect(map.entries).toHaveLength(2);
+      expect(map.entries.map((e) => e.id)).toEqual(['a.create', 'b.list']);
+    });
+
+    test('entries are sorted alphabetically by id', () => {
+      const z2 = trail('z.trail', {
+        implementation: noop,
+        input: z.object({}),
+      });
+      const a2 = trail('a.trail', {
+        implementation: noop,
+        input: z.object({}),
+      });
+      const m2 = trail('m.trail', {
+        implementation: noop,
+        input: z.object({}),
+      });
+      const tp = topoFrom({ a2, m2, z2 });
+      const map = generateSurfaceMap(tp);
+
+      expect(map.entries.map((e) => e.id)).toEqual([
+        'a.trail',
+        'm.trail',
+        'z.trail',
+      ]);
+    });
+
+    test('trail with input/output schemas produces valid JSON Schema entries', () => {
+      const t = trail('entity.create', {
+        implementation: noop,
+        input: z.object({ age: z.number(), name: z.string() }),
+        output: z.object({ id: z.string(), name: z.string() }),
+      });
+      const map = generateSurfaceMap(topoFrom({ t }));
+      const entry = getFirstEntry(map);
+
+      expect(entry.input).toBeDefined();
+      expect(entry.output).toBeDefined();
+      expectSchemaProperties(entry.input, {
+        age: { type: 'number' },
+        name: { type: 'string' },
+      });
+      expectSchemaProperties(entry.output, {
+        id: { type: 'string' },
+        name: { type: 'string' },
+      });
+    });
+
+    test('trail without output schema has output undefined', () => {
+      const t = trail('fire.forget', {
+        implementation: noop,
+        input: z.object({ msg: z.string() }),
+      });
+      const tp = topoFrom({ t });
+      const map = generateSurfaceMap(tp);
+
+      expect(map.entries[0]?.output).toBeUndefined();
+    });
+
+    test('hike entries include follows array', () => {
+      const base = trail('user.get', {
+        implementation: noop,
+        input: z.object({ id: z.string() }),
+      });
+      const r = hike('user.update', {
+        follows: ['user.get'],
+        implementation: noop,
+        input: z.object({ id: z.string(), name: z.string() }),
+      });
+      const tp = topoFrom({ base, r });
+      const map = generateSurfaceMap(tp);
+      const hikeEntry = map.entries.find((e) => e.id === 'user.update');
+      expect(hikeEntry).toBeDefined();
+
+      expect(hikeEntry?.kind).toBe('hike');
+      expect(hikeEntry?.follows).toEqual(['user.get']);
+    });
+
+    test("event entries are included with kind 'event'", () => {
+      const e = event('user.created', {
+        description: 'A user was created',
+        payload: z.object({ userId: z.string() }),
+      });
+      const entry = getFirstEntry(generateSurfaceMap(topoFrom({ e })));
+
+      expect(entry.kind).toBe('event');
+      expect(entry.id).toBe('user.created');
+      expect(entry.description).toBe('A user was created');
+      expect(entry.input).toBeDefined();
+    });
+  });
+
+  describe('metadata', () => {
+    test('safety markers are included when set', () => {
+      const t = trail('safe.trail', {
+        destructive: false,
+        idempotent: true,
+        implementation: noop,
+        input: z.object({}),
+        readOnly: true,
+      });
+      const entry = getFirstEntry(generateSurfaceMap(topoFrom({ t })));
+
+      expect(entry.readOnly).toBe(true);
+      expect(entry.destructive).toBeUndefined();
+      expect(entry.idempotent).toBe(true);
+    });
+
+    test('exampleCount reflects the number of examples', () => {
+      const t = trail('with.examples', {
+        examples: [
+          { expected: { y: 2 }, input: { x: 1 }, name: 'basic' },
+          { expected: { y: 0 }, input: { x: 0 }, name: 'zero' },
+          { expected: { y: -2 }, input: { x: -1 }, name: 'negative' },
+        ],
+        implementation: noop,
+        input: z.object({ x: z.number() }),
+        output: z.object({ y: z.number() }),
+      });
+      const tp = topoFrom({ t });
+      const map = generateSurfaceMap(tp);
+
+      expect(map.entries[0]?.exampleCount).toBe(3);
+    });
+
+    test('detours are included and sorted', () => {
+      const t = trail('with.detours', {
+        detours: {
+          onError: ['notify.admin', 'log.error'],
+          onSuccess: ['cache.invalidate'],
+        },
+        implementation: noop,
+        input: z.object({}),
+      });
+      const entry = getFirstEntry(generateSurfaceMap(topoFrom({ t })));
+
+      expect(entry.detours).toEqual({
+        onError: ['log.error', 'notify.admin'],
+        onSuccess: ['cache.invalidate'],
+      });
+    });
+
+    test('description is included when present', () => {
+      const t = trail('described', {
+        description: 'A described trail',
+        implementation: noop,
+        input: z.object({}),
+      });
+      const tp = topoFrom({ t });
+      const map = generateSurfaceMap(tp);
+
+      expect(map.entries[0]?.description).toBe('A described trail');
+    });
+  });
+
+  describe('stability', () => {
+    test('determinism: same topo produces identical output', () => {
+      const t = trail('stable', {
+        description: 'Stable trail',
+        implementation: noop,
+        input: z.object({ a: z.string(), b: z.number() }),
+        output: z.object({ c: z.boolean() }),
+        readOnly: true,
+      });
+      const tp = topoFrom({ t });
+
+      const map1 = generateSurfaceMap(tp);
+      const map2 = generateSurfaceMap(tp);
+
+      expect(map1.entries).toEqual(map2.entries);
+      expect(map1.version).toBe(map2.version);
+    });
+
+    test('version is set to 1.0', () => {
+      const t = trail('v.check', {
+        implementation: noop,
+        input: z.object({}),
+      });
+      const tp = topoFrom({ t });
+      const map = generateSurfaceMap(tp);
+
+      expect(map.version).toBe('1.0');
+    });
+
+    test('generatedAt is an ISO timestamp', () => {
+      const t = trail('ts.check', {
+        implementation: noop,
+        input: z.object({}),
+      });
+      const tp = topoFrom({ t });
+      const map = generateSurfaceMap(tp);
+
+      expect(new Date(map.generatedAt).toISOString()).toBe(map.generatedAt);
+    });
+  });
+});

package/src/__tests__/hash.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, expect } from 'bun:test';
+
+import { hashSurfaceMap } from '../hash.js';
+import type { SurfaceMap } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const makeSurfaceMap = (overrides?: Partial<SurfaceMap>): SurfaceMap => ({
+  entries: [
+    {
+      exampleCount: 2,
+      id: 'user.create',
+      input: {
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+        type: 'object',
+      },
+      kind: 'trail',
+      output: {
+        properties: { id: { type: 'string' } },
+        required: ['id'],
+        type: 'object',
+      },
+      surfaces: ['cli', 'mcp'],
+    },
+  ],
+  generatedAt: '2025-01-01T00:00:00.000Z',
+  version: '1.0',
+  ...overrides,
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('hashSurfaceMap', () => {
+  test('produces a valid SHA-256 hex string (64 characters)', () => {
+    const hash = hashSurfaceMap(makeSurfaceMap());
+    expect(hash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test('same surface map produces the same hash (deterministic)', () => {
+    const map = makeSurfaceMap();
+    const hash1 = hashSurfaceMap(map);
+    const hash2 = hashSurfaceMap(map);
+    expect(hash1).toBe(hash2);
+  });
+
+  test('different surface maps produce different hashes', () => {
+    const map1 = makeSurfaceMap();
+    const map2 = makeSurfaceMap({
+      entries: [
+        {
+          exampleCount: 0,
+          id: 'user.delete',
+          input: { type: 'object' },
+          kind: 'trail',
+          surfaces: [],
+        },
+      ],
+    });
+
+    expect(hashSurfaceMap(map1)).not.toBe(hashSurfaceMap(map2));
+  });
+
+  test('generatedAt does not affect the hash', () => {
+    const map1 = makeSurfaceMap({ generatedAt: '2025-01-01T00:00:00.000Z' });
+    const map2 = makeSurfaceMap({ generatedAt: '2099-12-31T23:59:59.999Z' });
+
+    expect(hashSurfaceMap(map1)).toBe(hashSurfaceMap(map2));
+  });
+
+  test('hash is stable across invocations', () => {
+    const map = makeSurfaceMap();
+    const hashes = Array.from({ length: 10 }, () => hashSurfaceMap(map));
+    const unique = new Set(hashes);
+    expect(unique.size).toBe(1);
+  });
+
+  test('key order in entry does not affect hash', () => {
+    // Build two maps with same data but different insertion order
+    const map1 = makeSurfaceMap({
+      entries: [
+        {
+          exampleCount: 0,
+          id: 'test',
+          input: {
+            properties: { a: { type: 'string' }, b: { type: 'number' } },
+            type: 'object',
+          },
+          kind: 'trail',
+          surfaces: [],
+        },
+      ],
+    });
+    const map2 = makeSurfaceMap({
+      entries: [
+        {
+          exampleCount: 0,
+          id: 'test',
+          input: {
+            properties: { a: { type: 'string' }, b: { type: 'number' } },
+            type: 'object',
+          },
+          kind: 'trail',
+          surfaces: [],
+        },
+      ],
+    });
+
+    expect(hashSurfaceMap(map1)).toBe(hashSurfaceMap(map2));
+  });
+});

package/src/__tests__/io.test.ts

@@ -0,0 +1,137 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtemp, rm, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  writeSurfaceMap,
+  readSurfaceMap,
+  writeSurfaceLock,
+  readSurfaceLock,
+} from '../io.js';
+import type { SurfaceMap } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const makeSurfaceMap = (): SurfaceMap => ({
+  entries: [
+    {
+      description: 'Create a user',
+      exampleCount: 1,
+      id: 'user.create',
+      input: { properties: { name: { type: 'string' } }, type: 'object' },
+      kind: 'trail',
+      surfaces: ['cli'],
+    },
+  ],
+  generatedAt: '2025-01-01T00:00:00.000Z',
+  version: '1.0',
+});
+
+// ---------------------------------------------------------------------------
+// Setup / Teardown
+// ---------------------------------------------------------------------------
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'trails-schema-test-'));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { force: true, recursive: true });
+});
+
+// ---------------------------------------------------------------------------
+// Surface Map tests
+// ---------------------------------------------------------------------------
+
+describe('writeSurfaceMap / readSurfaceMap', () => {
+  test('writes valid JSON to _surface.json', async () => {
+    const map = makeSurfaceMap();
+    const filePath = await writeSurfaceMap(map, { dir: tempDir });
+
+    expect(filePath).toBe(join(tempDir, '_surface.json'));
+
+    const content = await readFile(filePath, 'utf8');
+    const parsed = JSON.parse(content);
+    expect(parsed.version).toBe('1.0');
+    expect(parsed.entries).toHaveLength(1);
+  });
+
+  test('reads it back and produces identical data', async () => {
+    const map = makeSurfaceMap();
+    await writeSurfaceMap(map, { dir: tempDir });
+    const result = await readSurfaceMap({ dir: tempDir });
+
+    expect(result).toEqual(map);
+  });
+
+  test('returns null for missing file', async () => {
+    const result = await readSurfaceMap({ dir: join(tempDir, 'nonexistent') });
+    expect(result).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Surface Lock tests
+// ---------------------------------------------------------------------------
+
+describe('writeSurfaceLock / readSurfaceLock', () => {
+  test('writes a single line with the hash', async () => {
+    const hash = 'abc123def456'.repeat(4);
+    const filePath = await writeSurfaceLock(hash, { dir: tempDir });
+
+    expect(filePath).toBe(join(tempDir, 'surface.lock'));
+
+    const content = await readFile(filePath, 'utf8');
+    expect(content.trim()).toBe(hash);
+    // Single line (content is hash + newline)
+    expect(content).toBe(`${hash}\n`);
+  });
+
+  test('reads the hash back', async () => {
+    const hash = 'deadbeef'.repeat(8);
+    await writeSurfaceLock(hash, { dir: tempDir });
+    const result = await readSurfaceLock({ dir: tempDir });
+
+    expect(result).toBe(hash);
+  });
+
+  test('returns null for missing file', async () => {
+    const result = await readSurfaceLock({ dir: join(tempDir, 'nonexistent') });
+    expect(result).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Default directory
+// ---------------------------------------------------------------------------
+
+describe('default directory', () => {
+  test('defaults to .trails/', async () => {
+    // We can't easily test the actual default without polluting the repo,
+    // so we verify the custom directory option works and trust the default
+    const map = makeSurfaceMap();
+    const customDir = join(tempDir, 'custom-trails');
+    const filePath = await writeSurfaceMap(map, { dir: customDir });
+
+    expect(filePath).toBe(join(customDir, '_surface.json'));
+
+    const result = await readSurfaceMap({ dir: customDir });
+    expect(result).toEqual(map);
+  });
+
+  test('custom directory option works for lock files', async () => {
+    const customDir = join(tempDir, 'custom-lock-dir');
+    const hash = 'a1b2c3d4e5f6'.repeat(5);
+    const filePath = await writeSurfaceLock(hash, { dir: customDir });
+
+    expect(filePath).toBe(join(customDir, 'surface.lock'));
+
+    const result = await readSurfaceLock({ dir: customDir });
+    expect(result).toBe(hash);
+  });
+});