@ontrails/trails 1.0.0-beta.18 → 1.0.0-beta.19

package/src/trails/topo-reports.ts

@@ -2,6 +2,7 @@ import {
   DETOUR_MAX_ATTEMPTS_CAP,
   deriveCliPath,
   filterSurfaceTrails,
+  isArchivedTrailVersionEntry,
   zodToJsonSchema,
 } from '@ontrails/core';
 import type { AnyTrail, Signal, Topo } from '@ontrails/core';
@@ -16,6 +17,7 @@ import type {
   TopoGraphEntry,
   TopoGraphFieldOverride,
   TopoGraphLayerReference,
+  TopoGraphVersionEntry,
 } from '@ontrails/topographer';
 import { z } from 'zod';
 
@@ -196,7 +198,7 @@ export interface TrailDetailReport {
     | null;
   readonly examples: readonly unknown[];
   readonly fieldOverrides: readonly TopoGraphFieldOverride[];
-  readonly crosses: readonly string[];
+  readonly composes: readonly string[];
   readonly fires: readonly string[];
   readonly governance: Readonly<Record<string, unknown>> | null;
   readonly id: string;
@@ -211,6 +213,9 @@ export interface TrailDetailReport {
   readonly resources: readonly string[];
   readonly surfaceProjections: readonly ShippedSurfaceProjection[];
   readonly surfaces: readonly string[];
+  readonly supports: readonly number[];
+  readonly version: number | null;
+  readonly versions: Readonly<Record<string, TopoGraphVersionEntry>>;
 }
 
 export interface SignalDetailReport {
@@ -231,13 +236,20 @@ export interface SignalDetailReport {
   readonly producers: readonly string[];
 }
 
-const trailHas = (raw: Record<string, unknown>, key: string): boolean => {
-  if (key === 'examples' || key === 'detours') {
-    return Array.isArray(raw[key]) && (raw[key] as unknown[]).length > 0;
+const countLiveTrailVersionExamples = (trail: AnyTrail): number => {
+  let count = 0;
+  for (const entry of Object.values(trail.versions ?? {})) {
+    if (isArchivedTrailVersionEntry(entry)) {
+      continue;
+    }
+    count += entry.examples?.length ?? 0;
   }
-  return Boolean(raw[key]);
+  return count;
 };
 
+export const countTrailExamples = (trail: AnyTrail): number =>
+  (trail.examples?.length ?? 0) + countLiveTrailVersionExamples(trail);
+
 const detectFeatures = (
   app: Topo
 ): {
@@ -246,18 +258,12 @@ const detectFeatures = (
   hasOutputSchemas: boolean;
   hasResources: boolean;
 } => {
-  const trails = [...app.trails.values()].map(
-    (item) => item as unknown as Record<string, unknown>
-  );
+  const trails = [...app.trails.values()];
   return {
-    hasDetours: trails.some((r) => trailHas(r, 'detours')),
-    hasExamples: trails.some((r) => trailHas(r, 'examples')),
-    hasOutputSchemas: trails.some((r) => trailHas(r, 'output')),
-    hasResources: trails.some(
-      (r) =>
-        Array.isArray(r['resources']) &&
-        (r['resources'] as unknown[]).length > 0
-    ),
+    hasDetours: trails.some((trail) => trail.detours.length > 0),
+    hasExamples: trails.some((trail) => countTrailExamples(trail) > 0),
+    hasOutputSchemas: trails.some((trail) => trail.output !== undefined),
+    hasResources: trails.some((trail) => trail.resources.length > 0),
   };
 };
 
@@ -386,11 +392,7 @@ export const deriveSurveyList = (app: Topo): SurveyListReport => {
     const safety = safetyLabel(
       item as unknown as { intent?: 'read' | 'write' | 'destroy' }
     );
-    const examples = Array.isArray(
-      (item as unknown as { examples?: unknown[] }).examples
-    )
-      ? (item as unknown as { examples: unknown[] }).examples.length
-      : 0;
+    const examples = countTrailExamples(item);
 
     return {
       activatedBy: trailActivation.activatedBy,
@@ -657,6 +659,14 @@ const deriveResolvedSurfaceProjections = (
     : deriveShippedSurfaceProjectionsForTrail(app, trail, topoGraph);
 };
 
+const deriveResolvedTrailVersionDetail = (
+  topoEntry: TopoGraphEntry | undefined
+): Pick<TrailDetailReport, 'supports' | 'version' | 'versions'> => ({
+  supports: topoEntry?.supports ?? [],
+  version: topoEntry?.version ?? null,
+  versions: topoEntry?.versions ?? {},
+});
+
 const deriveResolvedTrailGraphDetail = (
   app: Topo | undefined,
   trailId: string,
@@ -676,6 +686,9 @@ const deriveResolvedTrailGraphDetail = (
   | 'output'
   | 'surfaceProjections'
   | 'surfaces'
+  | 'supports'
+  | 'version'
+  | 'versions'
 > => {
   const topoGraph =
     topoGraphOverride ?? (app === undefined ? undefined : deriveTopoGraph(app));
@@ -714,6 +727,7 @@ const deriveResolvedTrailGraphDetail = (
       topoGraph
     ),
     surfaces: topoEntry?.surfaces ?? [],
+    ...deriveResolvedTrailVersionDetail(topoEntry),
   };
 };
 
@@ -765,9 +779,9 @@ export const deriveTrailDetail = (
       topo: topoLayerNames,
       trail: trailLayerNames,
     },
+    composes: item.composes.toSorted(),
     contourDetails: graphDetail.contourDetails,
     contours: graphDetail.contours,
-    crosses: item.crosses.toSorted(),
     description: item.description ?? null,
     detours: formatTrailDetours(item),
     examples: item.examples ?? [],
@@ -784,7 +798,10 @@ export const deriveTrailDetail = (
     pattern: item.pattern ?? null,
     resources: item.resources.map((resource) => resource.id).toSorted(),
     safety,
+    supports: graphDetail.supports,
     surfaceProjections: graphDetail.surfaceProjections,
     surfaces: graphDetail.surfaces,
+    version: graphDetail.version,
+    versions: graphDetail.versions,
   };
 };

package/src/trails/topo-store-support.ts

@@ -9,6 +9,7 @@ import { Database } from 'bun:sqlite';
 
 import type { Topo } from '@ontrails/core';
 import {
+  ConflictError,
   deriveTrailsDir,
   InternalError,
   openWriteTrailsDb,
@@ -20,7 +21,15 @@ import type {
   TopoSnapshot,
 } from '@ontrails/topographer';
 import type { StoredTopoExport } from '@ontrails/topographer/backend-support';
-import { writeLockManifest, writeTopoGraph } from '@ontrails/topographer';
+import {
+  annotateTopoGraphForces,
+  carryForwardTopoGraphForces,
+  deriveTopoGraphDiff,
+  deriveTopoGraphHash,
+  readTopoGraph,
+  writeLockManifest,
+  writeTopoGraph,
+} from '@ontrails/topographer';
 import {
   createStoredTopoSnapshot,
   getStoredTopoExport,
@@ -85,19 +94,46 @@ export const deriveCurrentTopoExport = (
 
 const writeStoredExportArtifacts = async (
   storedExport: StoredTopoExport,
-  trailsDir: string
+  trailsDir: string,
+  options?: { readonly force?: boolean | undefined }
 ): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'topoPath'>> => {
-  const topoPath = await writeTopoGraph(
-    JSON.parse(storedExport.topoGraphJson) as TopoGraph,
-    { dir: trailsDir }
-  );
-  const lockPath = await writeLockManifest(
-    JSON.parse(storedExport.lockManifestJson) as LockManifest,
-    { dir: trailsDir }
-  );
+  const previousTopo = await readTopoGraph({ dir: trailsDir });
+  const nextTopo = JSON.parse(storedExport.topoGraphJson) as TopoGraph;
+  const diff =
+    previousTopo === null
+      ? undefined
+      : deriveTopoGraphDiff(previousTopo, nextTopo);
+  if (diff !== undefined && diff.breaking.length > 0 && !options?.force) {
+    throw new ConflictError(
+      `Topo contains ${diff.breaking.length} breaking change(s). Add a version entry, revert the change, or rerun with --force.`
+    );
+  }
+
+  const topoGraphBase =
+    previousTopo === null
+      ? nextTopo
+      : carryForwardTopoGraphForces(previousTopo, nextTopo);
+  const topoGraph =
+    diff === undefined || diff.breaking.length === 0
+      ? topoGraphBase
+      : annotateTopoGraphForces(topoGraphBase, diff.breaking);
+  const hash = deriveTopoGraphHash(topoGraph);
+  const lockManifest = {
+    ...(JSON.parse(storedExport.lockManifestJson) as LockManifest),
+    artifacts: [
+      {
+        path: 'topo.lock',
+        role: 'topo',
+        sha256: hash,
+      },
+    ],
+  } satisfies LockManifest;
+
+  const topoPath = await writeTopoGraph(topoGraph, { dir: trailsDir });
+  const lockPath = await writeLockManifest(lockManifest, { dir: trailsDir });
 
   return {
-    hash: storedExport.topoGraphHash,
+    hash,
     lockPath,
     topoPath,
   };
@@ -105,7 +141,7 @@ const writeStoredExportArtifacts = async (
 
 export const exportCurrentTopo = async (
   app: Topo,
-  options?: { readonly rootDir?: string }
+  options?: { readonly force?: boolean | undefined; readonly rootDir?: string }
 ): Promise<Result<TopoExportReport, Error>> => {
   const rootDir = deriveRootDir(options?.rootDir);
   const db = openWriteTrailsDb({ rootDir });
@@ -117,10 +153,20 @@ export const exportCurrentTopo = async (
     }
 
     const { snapshot, storedExport } = persisted.value;
-    const artifacts = await writeStoredExportArtifacts(
-      storedExport,
-      deriveTrailsDir({ rootDir })
-    );
+    let artifacts: Pick<TopoExportReport, 'hash' | 'lockPath' | 'topoPath'>;
+    try {
+      artifacts = await writeStoredExportArtifacts(
+        storedExport,
+        deriveTrailsDir({ rootDir }),
+        { force: options?.force }
+      );
+    } catch (error: unknown) {
+      return Result.err(
+        error instanceof Error
+          ? error
+          : new InternalError('Unable to write topo artifacts')
+      );
+    }
     return Result.ok({ ...artifacts, snapshot });
   } finally {
     db.close();

package/src/trails/topo-support.ts

@@ -62,7 +62,7 @@ export interface TopoExportReport {
   readonly topoPath: string;
 }
 
-export interface TopoVerifyReport {
+export interface TopoValidateReport {
   readonly committedHash: string;
   readonly currentHash: string;
   readonly lockPath: string;

package/src/trails/topo-unpin.ts

@@ -20,7 +20,7 @@ export const topoUnpinTrail = trail('topo.unpin', {
 
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     return Result.ok(
@@ -57,5 +57,5 @@ export const topoUnpinTrail = trail('topo.unpin', {
     removed: z.boolean(),
     snapshot: topoSnapshotOutput.optional(),
   }),
-  permit: { scopes: ['topo:delete'] },
+  permit: { scopes: ['topo:write'] },
 });

package/src/trails/topo.ts

@@ -76,12 +76,12 @@ export const topoTrail = trail('topo', {
   blaze: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
     if (leaseResult.isErr()) {
-      return Result.err(leaseResult.error);
+      return leaseResult;
     }
     const lease = leaseResult.value;
     try {

package/src/trails/{topo-verify.ts → validate.ts}

@@ -1,29 +1,29 @@
-import { Result, trail } from '@ontrails/core';
+import { trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import { tryLoadFreshAppLease } from './load-app.js';
 import { resolveTrailRootDir } from './root-dir.js';
-import { verifyCurrentTopo } from './topo-read-support.js';
+import { validateCurrentTopo } from './topo-read-support.js';
 
-export const topoVerifyTrail = trail('topo.verify', {
+export const validateTrail = trail('validate', {
   blaze: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
     if (leaseResult.isErr()) {
-      return Result.err(leaseResult.error);
+      return leaseResult;
     }
     const lease = leaseResult.value;
     try {
-      return await verifyCurrentTopo(lease.app, { rootDir });
+      return await validateCurrentTopo(lease.app, { rootDir });
     } finally {
       lease.release();
     }
   },
-  description: 'Verify that the committed lockfile matches the current topo',
+  description: 'Validate that committed topo artifacts match the current topo',
   input: z.object({
     module: z.string().optional().describe('Path to the app module'),
     rootDir: z.string().optional().describe('Workspace root directory'),