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

package/src/trails/survey.ts

@@ -20,6 +20,7 @@ import {
   createTopoStore,
   deriveTopoGraphDiff,
   deriveTopoGraph,
+  resolveTopoGraphVersionReference,
   TOPO_GRAPH_SCHEMA_VERSION,
   readTopoGraph,
 } from '@ontrails/topographer';
@@ -84,6 +85,21 @@ interface SurveyDiffReport {
   readonly warnings: readonly DiffEntry[];
 }
 
+interface DiffInput {
+  readonly against?: string | undefined;
+  readonly breakingOnly?: boolean | undefined;
+  readonly breaks?: boolean | undefined;
+  readonly forces?: boolean | undefined;
+  readonly module?: string | undefined;
+  readonly rootDir?: string | undefined;
+  readonly target?: string | undefined;
+}
+
+interface ParsedDiffTarget {
+  readonly id: string;
+  readonly versions?: ReadonlySet<number> | undefined;
+}
+
 const formatDiff = (diff: DiffResult, against: string): SurveyDiffReport => ({
   against,
   breaking: diff.breaking,
@@ -93,6 +109,252 @@ const formatDiff = (diff: DiffResult, against: string): SurveyDiffReport => ({
   warnings: diff.warnings,
 });
 
+const partitionDiffEntries = (entries: readonly DiffEntry[]): DiffResult => {
+  const sorted = [...entries].toSorted((left, right) =>
+    left.id.localeCompare(right.id)
+  );
+  const breaking = sorted.filter((entry) => entry.severity === 'breaking');
+  const warnings = sorted.filter((entry) => entry.severity === 'warning');
+  const info = sorted.filter((entry) => entry.severity === 'info');
+
+  return {
+    breaking,
+    entries: sorted,
+    hasBreaking: breaking.length > 0,
+    info,
+    warnings,
+  };
+};
+
+const parseVersionRange = (
+  reference: string
+): ReadonlySet<number> | undefined => {
+  const match = /^(\d+)\.\.(\d+)$/.exec(reference);
+  if (match === null) {
+    return undefined;
+  }
+  const start = Number(match[1]);
+  const end = Number(match[2]);
+  if (start < 1 || end < start) {
+    throw new ValidationError(
+      `Diff version range must use ascending positive versions: ${reference}`
+    );
+  }
+
+  return new Set(
+    Array.from({ length: end - start + 1 }, (_value, index) => start + index)
+  );
+};
+
+const findDiffTargetEntry = (
+  previous: TopoGraph,
+  current: TopoGraph,
+  id: string
+) =>
+  current.entries.find((entry) => entry.id === id) ??
+  previous.entries.find((entry) => entry.id === id);
+
+const parseDiffTarget = (
+  previous: TopoGraph,
+  current: TopoGraph,
+  target: string | undefined
+): Result<ParsedDiffTarget | undefined, Error> => {
+  if (target === undefined || target.length === 0) {
+    return Result.ok();
+  }
+
+  const separator = target.lastIndexOf('@');
+  const id = separator === -1 ? target : target.slice(0, separator);
+  const reference =
+    separator === -1 ? undefined : target.slice(separator + 1).trim();
+  if (id.length === 0 || reference === '') {
+    return Result.err(
+      new ValidationError('Diff target must use trail.id or trail.id@version')
+    );
+  }
+
+  const entry = findDiffTargetEntry(previous, current, id);
+  if (entry === undefined) {
+    return Result.err(new NotFoundError(`Trail not found for diff: ${id}`));
+  }
+
+  if (reference === undefined) {
+    return Result.ok({ id });
+  }
+
+  try {
+    const range = parseVersionRange(reference);
+    if (range !== undefined) {
+      return Result.ok({ id, versions: range });
+    }
+
+    return Result.ok({
+      id,
+      versions: new Set([
+        resolveTopoGraphVersionReference(entry, reference).version,
+      ]),
+    });
+  } catch (error: unknown) {
+    return Result.err(
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+};
+
+const detailVersions = (detail: string): readonly number[] => {
+  const match = /^(?:Live version|Version) (\d+)\b/.exec(detail);
+  if (match !== null) {
+    return [Number(match[1])];
+  }
+
+  const supportMatch = /^Supported versions (?:added|removed): (.+)$/.exec(
+    detail
+  );
+  if (supportMatch === null) {
+    return [];
+  }
+
+  return (supportMatch[1] ?? '')
+    .split(',')
+    .map((part) => Number(part.trim()))
+    .filter((version) => Number.isInteger(version) && version > 0);
+};
+
+type DiffSeverity = DiffEntry['severity'];
+
+const severityRank: Record<DiffSeverity, number> = {
+  breaking: 2,
+  info: 0,
+  warning: 1,
+};
+
+const higherSeverity = (
+  left: DiffSeverity,
+  right: DiffSeverity
+): DiffSeverity => (severityRank[right] > severityRank[left] ? right : left);
+
+const versionStatus = (detail: string): string | undefined =>
+  /^Version \d+ (?:added|removed) \(([^)]+)\)$/.exec(detail)?.[1];
+
+const visibleDetailSeverity = (detail: string): DiffSeverity => {
+  if (detail.startsWith('Force event ')) {
+    return 'warning';
+  }
+  if (detail.startsWith('Supported versions removed: ')) {
+    return 'breaking';
+  }
+  if (detail.startsWith('Supported versions added: ')) {
+    return 'info';
+  }
+  if (
+    /^Live version \d+ (?:added without examples|example coverage removed)$/.test(
+      detail
+    )
+  ) {
+    return 'warning';
+  }
+  if (detail.startsWith('Live version ') && detail.includes(' examples: ')) {
+    return 'info';
+  }
+  if (/^Version \d+ status changed: .+ -> archived$/.test(detail)) {
+    return 'warning';
+  }
+  if (detail.startsWith('Version ') && detail.includes(' status changed: ')) {
+    return 'info';
+  }
+
+  const status = versionStatus(detail);
+  if (detail.startsWith('Version ') && detail.includes(' removed (')) {
+    return status === 'archived' ? 'warning' : 'breaking';
+  }
+  if (detail.startsWith('Version ') && detail.includes(' added (')) {
+    return status === 'archived' ? 'info' : 'warning';
+  }
+  if (
+    /^Version \d+ (?:kind changed:|Required (?:input|contour) field ".+" added|(?:Input|Output|Contour) field ".+" (?:removed|type changed:|changed from optional to required))/.test(
+      detail
+    )
+  ) {
+    return 'breaking';
+  }
+  if (
+    /^Version \d+ (?:marker changed:|Optional (?:input|contour) field ".+" added|Output field ".+" added)/.test(
+      detail
+    )
+  ) {
+    return 'info';
+  }
+
+  return 'info';
+};
+
+const visibleDetailsSeverity = (details: readonly string[]): DiffSeverity => {
+  let severity: DiffSeverity = 'info';
+  for (const detail of details) {
+    severity = higherSeverity(severity, visibleDetailSeverity(detail));
+  }
+  return severity;
+};
+
+const detailsChanged = (
+  previous: readonly string[],
+  next: readonly string[]
+): boolean =>
+  previous.length !== next.length ||
+  previous.some((detail, index) => detail !== next[index]);
+
+const filterDetails = (
+  details: readonly string[],
+  target: ParsedDiffTarget | undefined,
+  forcesOnly: boolean
+): readonly string[] => {
+  const visible = forcesOnly
+    ? details.filter((detail) => detail.startsWith('Force event '))
+    : [...details];
+  if (target?.versions === undefined || forcesOnly) {
+    return visible;
+  }
+
+  return visible.filter((detail) => {
+    const versions = detailVersions(detail);
+    return versions.some((version) => target.versions?.has(version));
+  });
+};
+
+const filterDiff = (
+  diff: DiffResult,
+  target: ParsedDiffTarget | undefined,
+  options: Pick<DiffInput, 'breakingOnly' | 'breaks' | 'forces'>
+): DiffResult => {
+  const entries = diff.entries.flatMap((entry): DiffEntry[] => {
+    if (target !== undefined && entry.id !== target.id) {
+      return [];
+    }
+    const details = filterDetails(
+      entry.details,
+      target,
+      options.forces === true
+    );
+    if (details.length === 0) {
+      return [];
+    }
+    return [
+      {
+        ...entry,
+        details,
+        severity: detailsChanged(entry.details, details)
+          ? visibleDetailsSeverity(details)
+          : entry.severity,
+      },
+    ];
+  });
+
+  const partitioned = partitionDiffEntries(entries);
+  return options.breakingOnly === true || options.breaks === true
+    ? partitionDiffEntries(partitioned.breaking)
+    : partitioned;
+};
+
 const createDiffExampleInput = (): {
   readonly against: string;
   readonly module: string;
@@ -191,7 +453,7 @@ const readAgainstTopoGraph = async (
     return map === null
       ? Result.err(
           new NotFoundError(
-            'No saved TopoGraph found. Run `trails topo compile` first.'
+            'No saved TopoGraph found. Run `trails compile` first.'
           )
         )
       : Result.ok({ against: 'saved', map });
@@ -218,21 +480,25 @@ const readAgainstTopoGraph = async (
 const buildSurveyDiff = async (
   app: Topo,
   rootDir: string,
-  breakingOnly: boolean,
-  against?: string | undefined
+  input: DiffInput
 ): Promise<Result<SurveyDiffReport, Error>> => {
   const currentMap = deriveTopoGraph(app);
-  const previous = await readAgainstTopoGraph(rootDir, against);
+  const previous = await readAgainstTopoGraph(rootDir, input.against);
   if (previous.isErr()) {
     return previous;
   }
 
-  const diff = deriveTopoGraphDiff(previous.value.map, currentMap);
-  return Result.ok(
-    breakingOnly
-      ? formatDiff({ ...diff, info: [], warnings: [] }, previous.value.against)
-      : formatDiff(diff, previous.value.against)
+  const target = parseDiffTarget(previous.value.map, currentMap, input.target);
+  if (target.isErr()) {
+    return target;
+  }
+
+  const diff = filterDiff(
+    deriveTopoGraphDiff(previous.value.map, currentMap),
+    target.value,
+    input
   );
+  return Result.ok(formatDiff(diff, previous.value.against));
 };
 
 const buildSurveyLookup = (
@@ -404,6 +670,32 @@ const diffOutput = z.object({
   warnings: z.array(diffEntryOutput),
 });
 
+const diffInputSchema = z.object({
+  against: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Saved TopoGraph target: "saved", a workspace path (topo.lock, .json file, or directory with topo.lock), then a pin/snapshot id'
+    ),
+  breakingOnly: z
+    .boolean()
+    .default(false)
+    .describe('Legacy alias for --breaks; only show breaking changes'),
+  breaks: z.boolean().default(false).describe('Only show breaking changes'),
+  forces: z
+    .boolean()
+    .default(false)
+    .describe('Only show graph force audit events'),
+  module: z.string().optional().describe('Path to the app module'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+  target: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Trail or trail version target, such as user.create@1..2'),
+});
+
 const surveyMatchOutput = z.discriminatedUnion('kind', [
   z.object({
     detail: trailDetailOutput,
@@ -537,7 +829,7 @@ export const surveySurfacesTrail = trail('survey.surfaces', {
 export const surveyDiffTrail = trail('survey.diff', {
   blaze: async (input, ctx) =>
     withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
-      buildSurveyDiff(app, rootDir, input.breakingOnly, input.against)
+      buildSurveyDiff(app, rootDir, input)
     ),
   description: 'Diff the current topo against a saved TopoGraph',
   examples: [
@@ -562,21 +854,36 @@ export const surveyDiffTrail = trail('survey.diff', {
       name: 'Reject empty breaking-only target',
     },
   ],
-  input: z.object({
-    against: z
-      .string()
-      .min(1)
-      .optional()
-      .describe(
-        'Saved TopoGraph target: "saved", a workspace path (topo.lock, .json file, or directory with topo.lock), then a pin/snapshot id'
-      ),
-    breakingOnly: z
-      .boolean()
-      .default(false)
-      .describe('Only show breaking changes'),
-    module: z.string().optional().describe('Path to the app module'),
-    rootDir: z.string().optional().describe('Workspace root directory'),
-  }),
+  input: diffInputSchema,
+  intent: 'read',
+  output: diffOutput,
+});
+
+export const diffTrail = trail('diff', {
+  args: ['target'],
+  blaze: async (input, ctx) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
+      buildSurveyDiff(app, rootDir, input)
+    ),
+  description: 'Diff the current topo against a saved TopoGraph',
+  examples: [
+    {
+      description: 'Compare current topo to a saved TopoGraph directory',
+      input: createDiffExampleInput(),
+      name: 'Diff against baseline',
+    },
+    {
+      description: 'Show only breaking contract drift',
+      input: { ...createDiffExampleInput(), breaks: true },
+      name: 'Breaking changes',
+    },
+    {
+      description: 'Show graph-only force audit events',
+      input: { ...createDiffExampleInput(), forces: true },
+      name: 'Force audit events',
+    },
+  ],
+  input: diffInputSchema,
   intent: 'read',
   output: diffOutput,
 });

package/src/trails/topo-history.ts

@@ -13,7 +13,7 @@ export const topoHistoryTrail = trail('topo.history', {
   blaze: (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     return Result.ok(listTopoHistory({ limit: input.limit, rootDir }));

package/src/trails/topo-output-schemas.ts

@@ -137,6 +137,32 @@ export const shippedSurfaceInventoryOutput = z.object({
     .readonly(),
 });
 
+const trailVersionEntryOutput = z.object({
+  composes: z.array(z.string()).readonly().optional(),
+  detours: z
+    .array(
+      z.object({
+        maxAttempts: z.number(),
+        on: z.string(),
+      })
+    )
+    .readonly()
+    .optional(),
+  exampleCount: z.number(),
+  examples: z.array(z.unknown()).readonly().optional(),
+  input: jsonSchemaOutput,
+  kind: z.enum(['revision', 'fork']),
+  marker: z.string(),
+  output: jsonSchemaOutput,
+  resources: z.array(z.string()).readonly().optional(),
+  status: z
+    .object({
+      state: z.enum(['deprecated', 'archived']),
+    })
+    .catchall(z.unknown())
+    .optional(),
+});
+
 export const trailDetailOutput = z.object({
   activatedBy: z.array(z.string()).readonly(),
   activates: z.array(z.string()).readonly(),
@@ -163,9 +189,9 @@ export const trailDetailOutput = z.object({
     topo: z.array(z.string()).readonly(),
     trail: z.array(z.string()).readonly(),
   }),
+  composes: z.array(z.string()).readonly(),
   contourDetails: z.array(contourDetailOutput).readonly(),
   contours: z.array(z.string()).readonly(),
-  crosses: z.array(z.string()).readonly(),
   description: z.string().nullable(),
   detours: z
     .array(
@@ -190,8 +216,11 @@ export const trailDetailOutput = z.object({
   pattern: z.string().nullable(),
   resources: z.array(z.string()).readonly(),
   safety: z.string(),
+  supports: z.array(z.number()).readonly(),
   surfaceProjections: z.array(surfaceProjectionOutput).readonly(),
   surfaces: z.array(z.string()).readonly(),
+  version: z.number().nullable(),
+  versions: z.record(z.string(), trailVersionEntryOutput),
 });
 
 export const resourceDetailOutput = z.object({

package/src/trails/topo-pin.ts

@@ -13,12 +13,12 @@ export const topoPinTrail = trail('topo.pin', {
   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 {
@@ -48,4 +48,5 @@ export const topoPinTrail = trail('topo.pin', {
   output: z.object({
     snapshot: topoSnapshotOutput,
   }),
+  permit: { scopes: ['topo:write'] },
 });

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

@@ -18,7 +18,15 @@ import {
   SURFACE_LAYER_NAMES_KEY,
   ValidationError,
 } from '@ontrails/core';
-import { deriveTopoGraph, readLockManifest } from '@ontrails/topographer';
+import {
+  deriveTopoGraph,
+  deriveTopoGraphDiff,
+  deriveTopoGraphHash,
+  readLockManifest,
+  readTopoGraph,
+  stripTopoGraphForces,
+} from '@ontrails/topographer';
+import type { TopoGraph } from '@ontrails/topographer';
 
 import type {
   BriefReport,
@@ -28,6 +36,7 @@ import type {
   TrailDetailReport,
 } from './topo-reports.js';
 import {
+  countTrailExamples,
   deriveBriefReport,
   deriveResourceDetail,
   deriveSignalDetail,
@@ -36,7 +45,7 @@ import {
 } from './topo-reports.js';
 import type { ActivationGraphReport } from './topo-activation.js';
 import { deriveActivationGraph } from './topo-activation.js';
-import type { TopoSummaryReport, TopoVerifyReport } from './topo-support.js';
+import type { TopoSummaryReport, TopoValidateReport } from './topo-support.js';
 import { deriveRootDir, LOCK_PATH } from './topo-support.js';
 import { deriveCurrentTopoExport } from './topo-store-support.js';
 
@@ -129,7 +138,7 @@ export const buildCurrentGuideEntries = (
     .list()
     .map((trail) => ({
       description: trail.description ?? '(no description)',
-      exampleCount: trail.examples?.length ?? 0,
+      exampleCount: countTrailExamples(trail),
       id: trail.id,
       kind: 'trail' as const,
     }))
@@ -209,10 +218,10 @@ export const buildCurrentTopoMatches = (
   return matches;
 };
 
-export const verifyCurrentTopo = async (
+export const validateCurrentTopo = async (
   app: Topo,
   options?: { readonly rootDir?: string }
-): Promise<Result<TopoVerifyReport, Error>> => {
+): Promise<Result<TopoValidateReport, Error>> => {
   const rootDir = deriveRootDir(options?.rootDir);
   let lockManifest: Awaited<ReturnType<typeof readLockManifest>>;
   try {
@@ -234,7 +243,7 @@ export const verifyCurrentTopo = async (
   if (lockManifest === null) {
     return Result.err(
       new NotFoundError(
-        'No committed trails.lock found. Run `trails topo compile` first.'
+        'No committed trails.lock found. Run `trails compile` first.'
       )
     );
   }
@@ -243,6 +252,9 @@ export const verifyCurrentTopo = async (
   if (currentExport.isErr()) {
     return currentExport;
   }
+  const currentTopo = JSON.parse(
+    currentExport.value.topoGraphJson
+  ) as TopoGraph;
   const currentHash = currentExport.value.topoGraphHash;
   const topoArtifact = lockManifest.artifacts.find(
     (artifact) => artifact.role === 'topo' && artifact.path === 'topo.lock'
@@ -250,15 +262,44 @@ export const verifyCurrentTopo = async (
   if (topoArtifact === undefined) {
     return Result.err(
       new NotFoundError(
-        'No topo.lock artifact found in trails.lock. Run `trails topo compile` first.'
+        'No topo.lock artifact found in trails.lock. Run `trails compile` first.'
       )
     );
   }
 
   if (topoArtifact.sha256 !== currentHash) {
+    const committedTopo = await readTopoGraph({
+      dir: deriveTrailsDir({ rootDir }),
+    });
+    if (committedTopo !== null) {
+      const committedHash = deriveTopoGraphHash(committedTopo);
+      const forceStrippedHash = deriveTopoGraphHash(
+        stripTopoGraphForces(committedTopo)
+      );
+      if (
+        committedHash === topoArtifact.sha256 &&
+        forceStrippedHash === currentHash
+      ) {
+        return Result.ok({
+          committedHash: topoArtifact.sha256,
+          currentHash,
+          lockPath: LOCK_PATH,
+          stale: false,
+        });
+      }
+    }
+    const breakingSummary =
+      committedTopo === null
+        ? ''
+        : (() => {
+            const diff = deriveTopoGraphDiff(committedTopo, currentTopo);
+            return diff.breaking.length > 0
+              ? ` Breaking changes detected: ${diff.breaking.length}.`
+              : '';
+          })();
     return Result.err(
       new ConflictError(
-        'trails.lock is stale. Run `trails topo compile` to refresh it.'
+        `trails.lock is stale. Run \`trails compile\` to refresh it.${breakingSummary}`
       )
     );
   }