@ontrails/trails 1.0.0-beta.13 → 1.0.0-beta.15

package/src/__tests__/survey.test.ts

@@ -1,19 +1,30 @@
 import { describe, expect, test } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
 
-import { Result, provision, topo, trail } from '@ontrails/core';
+import { ConflictError, Result, resource, topo, trail } from '@ontrails/core';
 import {
-  generateTrailheadMap,
-  hashTrailheadMap,
-  diffTrailheadMaps,
+  deriveSurfaceMap,
+  deriveSurfaceMapHash,
+  deriveSurfaceMapDiff,
+  writeSurfaceMap,
 } from '@ontrails/schema';
-import type { TrailheadMap } from '@ontrails/schema';
+import type { SurfaceMap } from '@ontrails/schema';
 import { z } from 'zod';
 
 import {
-  generateBriefReport,
-  generateSurveyList,
-  generateTrailDetail,
+  deriveBriefReport,
+  deriveSurveyList,
+  deriveTrailDetail,
+  surveyTrail,
 } from '../trails/survey.js';
+import { loadApp } from '../trails/load-app.js';
 import type {
   BriefReport,
   SurveyListReport,
@@ -30,9 +41,13 @@ const helloTrail = trail('hello', {
     return Result.ok({ message: `Hello, ${name}!` });
   },
   description: 'Say hello',
-  detours: {
-    NotFoundError: ['search'],
-  },
+  detours: [
+    {
+      on: ConflictError,
+      /* oxlint-disable-next-line require-await -- test stub */
+      recover: async () => Result.ok({ message: 'recovered' }),
+    },
+  ],
   examples: [
     {
       expected: { message: 'Hello, world!' },
@@ -43,8 +58,8 @@ const helloTrail = trail('hello', {
   input: z.object({ name: z.string().optional() }),
   intent: 'read',
   output: z.object({ message: z.string() }),
-  provisions: [
-    provision('db.main', {
+  resources: [
+    resource('db.main', {
       create: () => Result.ok({ source: 'factory' }),
     }),
   ],
@@ -57,62 +72,124 @@ const byeTrail = trail('bye', {
   output: z.object({ message: z.string() }),
 });
 
-const [dbProvision] = helloTrail.provisions;
-if (!dbProvision) {
+const [dbResource] = helloTrail.resources;
+if (!dbResource) {
   throw new Error('Expected helloTrail to declare db.main');
 }
 
 const app = topo('test-app', {
   bye: byeTrail,
-  dbProvision,
+  dbResource,
   hello: helloTrail,
 });
 
+const expectOk = <T>(result: Result<T, Error>): T => {
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
+const writeSurveyAppFixture = (
+  dir: string,
+  options?: { withBye?: boolean }
+) => {
+  mkdirSync(join(dir, 'src'), { recursive: true });
+  const byeSource = options?.withBye
+    ? `
+const bye = trail('bye', {
+  blaze: async (input) => Result.ok({ message: \`Bye, \${input.name ?? 'world'}!\` }),
+  input: z.object({ name: z.string().optional() }),
+  intent: 'read',
+  output: z.object({ message: z.string() }),
+});
+`
+    : '';
+  const topoMembers = options?.withBye
+    ? '{ bye, dbMain, hello }'
+    : '{ dbMain, hello }';
+  writeFileSync(
+    join(dir, 'src', 'app.ts'),
+    `import { Result, resource, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+const hello = trail('hello', {
+  blaze: async (input) => Result.ok({ message: \`Hello, \${input.name ?? 'world'}!\` }),
+  input: z.object({ name: z.string().optional() }),
+  intent: 'read',
+  output: z.object({ message: z.string() }),
+  resources: [
+    resource('db.main', {
+      create: () => Result.ok({ source: 'factory' }),
+    }),
+  ],
+});
+
+const [dbMain] = hello.resources;
+if (!dbMain) {
+  throw new Error('expected hello to declare db.main');
+}
+
+${byeSource}
+
+export const app = topo('survey-fixture', ${topoMembers});
+`
+  );
+};
+
+const repoTempDir = (): string =>
+  join(
+    resolve(import.meta.dir, '../..'),
+    '.tmp-tests',
+    `trails-survey-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
 describe('trails survey', () => {
-  test('generateTrailheadMap includes all trails', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    expect(trailheadMap.entries.length).toBe(3);
-    const ids = trailheadMap.entries.map((e) => e.id);
+  test('deriveSurfaceMap includes all trails', () => {
+    const surfaceMap = deriveSurfaceMap(app);
+    expect(surfaceMap.entries.length).toBe(3);
+    const ids = surfaceMap.entries.map((e) => e.id);
     expect(ids).toContain('hello');
     expect(ids).toContain('bye');
     expect(ids).toContain('db.main');
   });
 
-  test('trailhead map entries have expected fields', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    const hello = trailheadMap.entries.find((e) => e.id === 'hello');
+  test('surface map entries have expected fields', () => {
+    const surfaceMap = deriveSurfaceMap(app);
+    const hello = surfaceMap.entries.find((e) => e.id === 'hello');
     expect(hello).toBeDefined();
+    expect(hello?.cli?.path).toEqual(['hello']);
     expect(hello?.kind).toBe('trail');
     expect(hello?.intent).toBe('read');
     expect(hello?.exampleCount).toBe(1);
-    expect(hello?.provisions).toEqual(['db.main']);
+    expect(hello?.resources).toEqual(['db.main']);
   });
 
   test('JSON output is valid JSON', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    const json = JSON.stringify(trailheadMap, null, 2);
-    const parsed = JSON.parse(json) as TrailheadMap;
+    const surfaceMap = deriveSurfaceMap(app);
+    const json = JSON.stringify(surfaceMap, null, 2);
+    const parsed = JSON.parse(json) as SurfaceMap;
     expect(parsed.version).toBe('1.0');
     expect(parsed.entries.length).toBe(3);
   });
 
-  test('hashTrailheadMap produces stable hash', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    const hash1 = hashTrailheadMap(trailheadMap);
-    const hash2 = hashTrailheadMap(trailheadMap);
+  test('deriveSurfaceMapHash produces stable hash', () => {
+    const surfaceMap = deriveSurfaceMap(app);
+    const hash1 = deriveSurfaceMapHash(surfaceMap);
+    const hash2 = deriveSurfaceMapHash(surfaceMap);
     expect(hash1).toBe(hash2);
     // SHA-256 hex
     expect(hash1.length).toBe(64);
   });
 
-  test('diffTrailheadMaps detects added trails', () => {
-    const prev = generateTrailheadMap(topo('test', { hello: helloTrail }));
-    const curr = generateTrailheadMap(app);
-    const diff = diffTrailheadMaps(prev, curr);
+  test('deriveSurfaceMapDiff detects added trails', () => {
+    const prev = deriveSurfaceMap(topo('test', { hello: helloTrail }));
+    const curr = deriveSurfaceMap(app);
+    const diff = deriveSurfaceMapDiff(prev, curr);
 
     expect(diff.info.length).toBeGreaterThan(0);
     const addedBye = diff.info.find((e) => e.id === 'bye');
@@ -120,10 +197,10 @@ describe('trails survey', () => {
     expect(addedBye?.change).toBe('added');
   });
 
-  test('diffTrailheadMaps detects removed trails', () => {
-    const prev = generateTrailheadMap(app);
-    const curr = generateTrailheadMap(topo('test', { hello: helloTrail }));
-    const diff = diffTrailheadMaps(prev, curr);
+  test('deriveSurfaceMapDiff detects removed trails', () => {
+    const prev = deriveSurfaceMap(app);
+    const curr = deriveSurfaceMap(topo('test', { hello: helloTrail }));
+    const diff = deriveSurfaceMapDiff(prev, curr);
 
     expect(diff.hasBreaking).toBe(true);
     const removedBye = diff.breaking.find((e) => e.id === 'bye');
@@ -131,9 +208,9 @@ describe('trails survey', () => {
     expect(removedBye?.change).toBe('removed');
   });
 
-  test('diffTrailheadMaps returns empty for identical maps', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    const diff = diffTrailheadMaps(trailheadMap, trailheadMap);
+  test('deriveSurfaceMapDiff returns empty for identical maps', () => {
+    const surfaceMap = deriveSurfaceMap(app);
+    const diff = deriveSurfaceMapDiff(surfaceMap, surfaceMap);
     expect(diff.entries.length).toBe(0);
     expect(diff.hasBreaking).toBe(false);
   });
@@ -145,72 +222,156 @@ describe('trails survey', () => {
 
 describe('trails survey --brief', () => {
   test('produces a valid capability report', () => {
-    const report = generateBriefReport(app);
+    const report = deriveBriefReport(app);
     expect(report.name).toBe('test-app');
     expect(report.contractVersion).toBe('2026-03');
   });
 
   test('report includes correct trail count', () => {
-    const report = generateBriefReport(app);
+    const report = deriveBriefReport(app);
     expect(report.trails).toBe(2);
     expect(report.signals).toBe(0);
-    expect(report.provisions).toBe(1);
+    expect(report.resources).toBe(1);
   });
 
   test('detects features in use', () => {
-    const report = generateBriefReport(app);
+    const report = deriveBriefReport(app);
     expect(report.features.outputSchemas).toBe(true);
     expect(report.features.examples).toBe(true);
     expect(report.features.detours).toBe(true);
     expect(report.features.signals).toBe(false);
-    expect(report.features.provisions).toBe(true);
+    expect(report.features.resources).toBe(true);
   });
 
   test('JSON output is valid', () => {
-    const report = generateBriefReport(app);
+    const report = deriveBriefReport(app);
     const json = JSON.stringify(report, null, 2);
     const parsed = JSON.parse(json) as BriefReport;
     expect(parsed.name).toBe('test-app');
     expect(parsed.trails).toBe(2);
-    expect(parsed.provisions).toBe(1);
+    expect(parsed.resources).toBe(1);
   });
 
   test('empty app reports zero features', () => {
     const emptyApp = topo('empty', {});
-    const report = generateBriefReport(emptyApp);
+    const report = deriveBriefReport(emptyApp);
     expect(report.trails).toBe(0);
     expect(report.features.outputSchemas).toBe(false);
     expect(report.features.examples).toBe(false);
     expect(report.features.detours).toBe(false);
-    expect(report.features.provisions).toBe(false);
+    expect(report.features.resources).toBe(false);
   });
 });
 
 describe('trails survey detail', () => {
-  test('trail detail includes declared provisions, crossings, and intent', () => {
-    const detail = generateTrailDetail(helloTrail);
+  test('trail detail includes declared resources, crossings, and intent', () => {
+    const detail = deriveTrailDetail(helloTrail);
     const parsed = structuredClone(detail) as TrailDetailReport;
 
     expect(parsed.crosses).toEqual([]);
     expect(parsed.intent).toBe('read');
-    expect(parsed.provisions).toEqual(['db.main']);
+    expect(parsed.resources).toEqual(['db.main']);
   });
 });
 
-describe('trails survey provisions section', () => {
-  test('list output includes provision lifetime and health status', () => {
-    const report = generateSurveyList(app);
+describe('trails survey resources section', () => {
+  test('list output includes resource lifetime and health status', () => {
+    const report = deriveSurveyList(app);
     const parsed = structuredClone(report) as SurveyListReport;
-    const db = parsed.provisions.find((entry) => entry.id === 'db.main');
+    const db = parsed.resources.find((entry) => entry.id === 'db.main');
 
-    expect(parsed.provisionCount).toBe(1);
+    expect(parsed.resourceCount).toBe(1);
     expect(db).toEqual({
       description: null,
       health: 'none',
       id: 'db.main',
-      kind: 'provision',
+      kind: 'resource',
       lifetime: 'singleton',
       usedBy: ['hello'],
     });
   });
 });
+
+describe('trails survey generate', () => {
+  test('delegates to topo export and writes a structured lock', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeSurveyAppFixture(dir);
+
+      const generated = expectOk(
+        await surveyTrail.blaze({ generate: true, module: './src/app.ts' }, {
+          cwd: dir,
+        } as never)
+      ) as {
+        readonly hash: string;
+        readonly lockPath: string;
+        readonly mapPath: string;
+      };
+
+      expect(generated.hash).toHaveLength(64);
+      expect(existsSync(join(dir, '.trails', '_surface.json'))).toBe(true);
+      expect(existsSync(join(dir, '.trails', 'trails.lock'))).toBe(true);
+      expect(
+        JSON.parse(readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8'))
+      ).toMatchObject({
+        hash: generated.hash,
+        version: 1,
+      });
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});
+
+describe('trails survey diffSaved', () => {
+  test('returns an error when no saved surface map exists yet', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeSurveyAppFixture(dir);
+
+      const result = await surveyTrail.blaze(
+        { diffSaved: true, module: './src/app.ts' },
+        { cwd: dir } as never
+      );
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error.message).toContain('Run `trails topo export` first');
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('diffs against the saved local surface map', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeSurveyAppFixture(dir);
+      const baselineApp = await loadApp('./src/app.ts', dir);
+      await writeSurfaceMap(deriveSurfaceMap(baselineApp), {
+        dir: join(dir, '.trails'),
+      });
+
+      writeSurveyAppFixture(dir, { withBye: true });
+
+      const result = await surveyTrail.blaze(
+        { diffSaved: true, module: './src/app.ts' },
+        { cwd: dir } as never
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value).toMatchObject({
+        hasBreaking: false,
+        info: [
+          expect.objectContaining({
+            change: 'added',
+            id: 'bye',
+          }),
+        ],
+      });
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});