@ontrails/topography 1.0.0-beta.41

package/src/versioning.ts

@@ -0,0 +1,280 @@
+import {
+  DETOUR_MAX_ATTEMPTS_CAP,
+  TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH,
+  deriveStructuredTrailExamples,
+  ValidationError,
+  deriveCurrentTrailVersionMarker,
+  deriveShortestUnambiguousTrailVersionMarkerPrefix,
+  deriveSupportedTrailVersions,
+  deriveTrailVersionEntryMarker,
+  deriveTrailVersionMarkers,
+  getTrailVersionEntryKind,
+  resolveTrailVersionMarkerPrefix,
+} from '@ontrails/core';
+import type {
+  AnyTrail,
+  TrailVersionEntry,
+  TrailVersionMarkerBinding,
+} from '@ontrails/core';
+
+import type {
+  JsonSchema,
+  TopoGraphEntry,
+  TopoGraphVersionEntry,
+} from './types.js';
+
+type SchemaProjector = (schema: unknown) => JsonSchema;
+
+const sortPlainRecord = <T extends Record<string, unknown>>(value: T): T => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value).toSorted()) {
+    sorted[key] = value[key];
+  }
+  return sorted as T;
+};
+
+const projectVersionDetours = (
+  entry: TrailVersionEntry
+): TopoGraphVersionEntry['detours'] => {
+  const raw = entry as unknown as Record<string, unknown>;
+  const { detours } = raw;
+  if (!Array.isArray(detours) || detours.length === 0) {
+    return undefined;
+  }
+
+  return detours.map((detour) => {
+    const candidate = detour as {
+      readonly maxAttempts?: number | undefined;
+      readonly on?: { readonly name?: string | undefined } | undefined;
+    };
+    return {
+      maxAttempts: Math.max(
+        1,
+        Math.min(candidate.maxAttempts ?? 1, DETOUR_MAX_ATTEMPTS_CAP)
+      ),
+      on: candidate.on?.name ?? 'Error',
+    };
+  });
+};
+
+const projectVersionRuntimeRefs = (
+  entry: TrailVersionEntry,
+  field: 'composes' | 'resources'
+): readonly string[] | undefined => {
+  const raw = entry as unknown as Record<string, unknown>;
+  const values = raw[field];
+  if (!Array.isArray(values) || values.length === 0) {
+    return undefined;
+  }
+
+  const refs: string[] = [];
+  for (const value of values) {
+    if (typeof value === 'string') {
+      refs.push(value);
+      continue;
+    }
+    if (
+      typeof value === 'object' &&
+      value !== null &&
+      typeof (value as { readonly id?: unknown }).id === 'string'
+    ) {
+      refs.push((value as { readonly id: string }).id);
+    }
+  }
+
+  return refs.toSorted();
+};
+
+export const projectTrailVersionEntry = (
+  entry: TrailVersionEntry,
+  projectSchema: SchemaProjector
+): TopoGraphVersionEntry => {
+  const kind = getTrailVersionEntryKind(entry);
+  const examples = deriveStructuredTrailExamples(entry.examples, {
+    provenance: { source: 'trail.versions.examples' },
+  });
+  const projected: Record<string, unknown> = {
+    exampleCount: entry.examples?.length ?? 0,
+    input: projectSchema(entry.input),
+    kind,
+    marker: deriveTrailVersionEntryMarker(entry),
+    output: projectSchema(entry.output),
+  };
+
+  if (examples !== undefined) {
+    projected['examples'] = examples;
+  }
+
+  if (entry.status !== undefined) {
+    projected['status'] = sortPlainRecord({ ...entry.status });
+  }
+
+  if (kind === 'fork') {
+    const composes = projectVersionRuntimeRefs(entry, 'composes');
+    const resources = projectVersionRuntimeRefs(entry, 'resources');
+    const detours = projectVersionDetours(entry);
+    if (composes !== undefined) {
+      projected['composes'] = composes;
+    }
+    if (resources !== undefined) {
+      projected['resources'] = resources;
+    }
+    if (detours !== undefined) {
+      projected['detours'] = detours;
+    }
+  }
+
+  return sortPlainRecord(projected) as unknown as TopoGraphVersionEntry;
+};
+
+export interface TopoGraphVersionMarkerRecord {
+  readonly current: boolean;
+  readonly displayMarker?: string | undefined;
+  readonly marker?: string | undefined;
+  readonly version: number;
+}
+
+export interface TopoGraphVersionMarkerResolution extends TopoGraphVersionMarkerRecord {
+  readonly prefix: string;
+}
+
+export const collectTopoGraphVersionMarkers = (
+  entry: Pick<TopoGraphEntry, 'marker' | 'version' | 'versions'>
+): readonly TrailVersionMarkerBinding[] => {
+  if (entry.version === undefined) {
+    return [];
+  }
+
+  const markers: TrailVersionMarkerBinding[] = [];
+  if (entry.marker !== undefined) {
+    markers.push({ marker: entry.marker, version: entry.version });
+  }
+
+  for (const [version, versionEntry] of Object.entries(entry.versions ?? {})) {
+    const { marker } = versionEntry as { readonly marker?: unknown };
+    if (typeof marker === 'string') {
+      markers.push({ marker, version: Number(version) });
+    }
+  }
+
+  return markers.toSorted((left, right) => left.version - right.version);
+};
+
+export const deriveTopoGraphVersionMarkerRecords = (
+  entry: Pick<TopoGraphEntry, 'marker' | 'version' | 'versions'>
+): readonly TopoGraphVersionMarkerRecord[] => {
+  const markers = collectTopoGraphVersionMarkers(entry);
+  const markerValues = markers.map((candidate) => candidate.marker);
+
+  return markers.map((candidate) => ({
+    ...candidate,
+    current: candidate.version === entry.version,
+    displayMarker: deriveShortestUnambiguousTrailVersionMarkerPrefix(
+      candidate.marker,
+      markerValues
+    ),
+  }));
+};
+
+const hasTopoGraphVersion = (
+  entry: Pick<TopoGraphEntry, 'version' | 'versions'>,
+  version: number
+): boolean =>
+  entry.version === version || Object.hasOwn(entry.versions ?? {}, version);
+
+export const resolveTopoGraphVersionReference = (
+  entry: Pick<TopoGraphEntry, 'marker' | 'version' | 'versions'>,
+  reference: number | string
+): TopoGraphVersionMarkerResolution => {
+  const markers = collectTopoGraphVersionMarkers(entry);
+  const markerValues = markers.map((candidate) => candidate.marker);
+
+  if (typeof reference === 'number') {
+    const match = markers.find((candidate) => candidate.version === reference);
+    if (match !== undefined) {
+      return {
+        ...match,
+        current: match.version === entry.version,
+        displayMarker: deriveShortestUnambiguousTrailVersionMarkerPrefix(
+          match.marker,
+          markerValues
+        ),
+        prefix: String(reference),
+      };
+    }
+    if (!hasTopoGraphVersion(entry, reference)) {
+      throw new ValidationError(
+        `Trail version ${reference} is not in the TopoGraph`
+      );
+    }
+
+    return {
+      current: reference === entry.version,
+      prefix: String(reference),
+      version: reference,
+    };
+  }
+
+  if (/^\d+$/.test(reference)) {
+    const version = Number(reference);
+    if (hasTopoGraphVersion(entry, version)) {
+      return resolveTopoGraphVersionReference(entry, version);
+    }
+    if (reference.length < TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH) {
+      throw new ValidationError(
+        `Trail version ${version} is not in the TopoGraph`
+      );
+    }
+  }
+
+  const markerPrefix = reference.startsWith('@')
+    ? reference.slice(1)
+    : reference;
+  const resolved = resolveTrailVersionMarkerPrefix(markers, markerPrefix);
+  return {
+    ...resolved,
+    current: resolved.version === entry.version,
+    displayMarker: deriveShortestUnambiguousTrailVersionMarkerPrefix(
+      resolved.marker,
+      markerValues
+    ),
+  };
+};
+
+export const projectTrailVersions = (
+  trail: AnyTrail,
+  projectSchema: SchemaProjector
+):
+  | {
+      readonly marker: string;
+      readonly supports: readonly number[];
+      readonly version: number;
+      readonly versions?: Readonly<Record<string, TopoGraphVersionEntry>>;
+    }
+  | undefined => {
+  if (trail.version === undefined) {
+    return undefined;
+  }
+
+  const projectedEntries: Record<string, TopoGraphVersionEntry> = {};
+  for (const [rawVersion, entry] of Object.entries(
+    trail.versions ?? {}
+  ).toSorted(([left], [right]) => Number(left) - Number(right))) {
+    projectedEntries[rawVersion] = projectTrailVersionEntry(
+      entry,
+      projectSchema
+    );
+  }
+
+  const currentMarker = deriveCurrentTrailVersionMarker(trail);
+  deriveTrailVersionMarkers(trail);
+
+  return {
+    marker: currentMarker,
+    supports: deriveSupportedTrailVersions(trail),
+    version: trail.version,
+    ...(Object.keys(projectedEntries).length > 0
+      ? { versions: projectedEntries }
+      : {}),
+  };
+};

package/src/wayfind/error-facts.ts

@@ -0,0 +1,363 @@
+import {
+  errorClasses,
+  projectErrorClassSurface,
+  surfaceNames,
+} from '@ontrails/core';
+import type {
+  ErrorCategory,
+  ErrorClassRegistryEntry,
+  ErrorClassSurfaceProjection,
+  SurfaceName,
+} from '@ontrails/core';
+import type {
+  TopoGraph,
+  TopoGraphEntry,
+  TopoGraphVersionEntry,
+} from '../types.js';
+
+export type TrailErrorFactKind =
+  | 'documented'
+  | 'handled'
+  | 'inferred'
+  | 'observed';
+
+export type TrailErrorFactsCompleteness =
+  | {
+      readonly reason: 'authored-facts-exhausted';
+      readonly status: 'complete';
+    }
+  | {
+      readonly reason: 'inferred-facts-supplied' | 'observed-facts-supplied';
+      readonly status: 'partial';
+    }
+  | {
+      readonly reason: 'no-exhaustive-emitted-error-contract' | 'not-evaluated';
+      readonly status: 'unknown';
+    };
+
+export interface TrailErrorTaxonomyProjection {
+  readonly category?: ErrorCategory | undefined;
+  readonly dynamicCategory?:
+    | {
+        readonly inheritsCategoryFrom: 'wrapped-error';
+      }
+    | undefined;
+  readonly known: boolean;
+  readonly name: string;
+  readonly retryable?: boolean | undefined;
+  readonly surfaces: readonly ErrorClassSurfaceProjection[];
+}
+
+export type TrailErrorFactProvenance =
+  | {
+      readonly exampleName: string;
+      readonly source: 'trail.examples' | 'trail.versions.examples';
+      readonly trailId: string;
+      readonly version?: number | undefined;
+    }
+  | {
+      readonly detourIndex: number;
+      readonly source: 'trail.detours' | 'trail.versions.detours';
+      readonly trailId: string;
+      readonly version?: number | undefined;
+    }
+  | {
+      readonly detail?: string | undefined;
+      readonly source: 'static-inference';
+      readonly trailId: string;
+      readonly version?: number | undefined;
+    }
+  | {
+      readonly detail?: string | undefined;
+      readonly source: 'runtime-observation';
+      readonly trailId: string;
+      readonly version?: number | undefined;
+    };
+
+export interface TrailErrorFact {
+  readonly completeness: TrailErrorFactsCompleteness;
+  readonly kind: TrailErrorFactKind;
+  readonly provenance: TrailErrorFactProvenance;
+  readonly taxonomy: TrailErrorTaxonomyProjection;
+}
+
+export interface TrailErrorFacts {
+  readonly completeness: {
+    readonly emitted: TrailErrorFactsCompleteness;
+    readonly handled: TrailErrorFactsCompleteness;
+    readonly documented: TrailErrorFactsCompleteness;
+    readonly inferred: TrailErrorFactsCompleteness;
+    readonly observed: TrailErrorFactsCompleteness;
+  };
+  readonly facts: readonly TrailErrorFact[];
+  readonly trailId: string;
+}
+
+export interface TrailErrorEvidenceInput {
+  readonly detail?: string | undefined;
+  readonly errorName: string;
+  readonly trailId: string;
+  readonly version?: number | undefined;
+}
+
+export interface TrailErrorFactsOptions {
+  readonly inferred?: readonly TrailErrorEvidenceInput[] | undefined;
+  readonly observed?: readonly TrailErrorEvidenceInput[] | undefined;
+  readonly surfaces?: readonly SurfaceName[] | undefined;
+}
+
+const errorClassByName: ReadonlyMap<string, ErrorClassRegistryEntry> = new Map(
+  errorClasses.map((entry) => [entry.name, entry])
+);
+
+const taxonomyProjection = (
+  errorName: string,
+  surfaces: readonly SurfaceName[]
+): TrailErrorTaxonomyProjection => {
+  const registryEntry = errorClassByName.get(errorName);
+  if (registryEntry === undefined) {
+    return {
+      known: false,
+      name: errorName,
+      surfaces: [],
+    };
+  }
+
+  if (registryEntry.category === 'dynamic') {
+    return {
+      dynamicCategory: {
+        inheritsCategoryFrom: registryEntry.inheritsCategoryFrom,
+      },
+      known: true,
+      name: registryEntry.name,
+      retryable: registryEntry.retryable,
+      surfaces: [],
+    };
+  }
+
+  return {
+    category: registryEntry.category,
+    known: true,
+    name: registryEntry.name,
+    retryable: registryEntry.retryable,
+    surfaces: surfaces.flatMap((surface) => {
+      const projected = projectErrorClassSurface(surface, errorName);
+      return projected === undefined ? [] : [projected];
+    }),
+  };
+};
+
+const authoredCompleteness: TrailErrorFactsCompleteness = {
+  reason: 'authored-facts-exhausted',
+  status: 'complete',
+};
+
+const emittedCompleteness: TrailErrorFactsCompleteness = {
+  reason: 'no-exhaustive-emitted-error-contract',
+  status: 'unknown',
+};
+
+const notEvaluatedCompleteness: TrailErrorFactsCompleteness = {
+  reason: 'not-evaluated',
+  status: 'unknown',
+};
+
+const inferredCompleteness: TrailErrorFactsCompleteness = {
+  reason: 'inferred-facts-supplied',
+  status: 'partial',
+};
+
+const observedCompleteness: TrailErrorFactsCompleteness = {
+  reason: 'observed-facts-supplied',
+  status: 'partial',
+};
+
+const documentedFacts = (
+  entry: TopoGraphEntry,
+  surfaces: readonly SurfaceName[]
+): TrailErrorFact[] =>
+  (entry.examples ?? []).flatMap((example): TrailErrorFact[] => {
+    if (example.kind !== 'error' || example.error === undefined) {
+      return [];
+    }
+    return [
+      {
+        completeness: authoredCompleteness,
+        kind: 'documented',
+        provenance: {
+          exampleName: example.name,
+          source: 'trail.examples',
+          trailId: entry.id,
+        },
+        taxonomy: taxonomyProjection(example.error, surfaces),
+      },
+    ];
+  });
+
+const handledFacts = (
+  entry: TopoGraphEntry,
+  surfaces: readonly SurfaceName[]
+): TrailErrorFact[] =>
+  (entry.detours ?? []).map(
+    (detour, detourIndex): TrailErrorFact => ({
+      completeness: authoredCompleteness,
+      kind: 'handled',
+      provenance: {
+        detourIndex,
+        source: 'trail.detours',
+        trailId: entry.id,
+      },
+      taxonomy: taxonomyProjection(detour.on, surfaces),
+    })
+  );
+
+const versionDocumentedFacts = (
+  trailId: string,
+  version: number,
+  entry: TopoGraphVersionEntry,
+  surfaces: readonly SurfaceName[]
+): TrailErrorFact[] =>
+  (entry.examples ?? []).flatMap((example): TrailErrorFact[] => {
+    if (example.kind !== 'error' || example.error === undefined) {
+      return [];
+    }
+    return [
+      {
+        completeness: authoredCompleteness,
+        kind: 'documented',
+        provenance: {
+          exampleName: example.name,
+          source: 'trail.versions.examples',
+          trailId,
+          version,
+        },
+        taxonomy: taxonomyProjection(example.error, surfaces),
+      },
+    ];
+  });
+
+const versionHandledFacts = (
+  trailId: string,
+  version: number,
+  entry: TopoGraphVersionEntry,
+  surfaces: readonly SurfaceName[]
+): TrailErrorFact[] =>
+  (entry.detours ?? []).map(
+    (detour, detourIndex): TrailErrorFact => ({
+      completeness: authoredCompleteness,
+      kind: 'handled',
+      provenance: {
+        detourIndex,
+        source: 'trail.versions.detours',
+        trailId,
+        version,
+      },
+      taxonomy: taxonomyProjection(detour.on, surfaces),
+    })
+  );
+
+const versionFacts = (
+  entry: TopoGraphEntry,
+  surfaces: readonly SurfaceName[]
+): TrailErrorFact[] =>
+  Object.entries(entry.versions ?? {}).flatMap(([versionKey, versionEntry]) => {
+    const version = Number.parseInt(versionKey, 10);
+    if (!Number.isFinite(version)) {
+      return [];
+    }
+    return [
+      ...versionDocumentedFacts(entry.id, version, versionEntry, surfaces),
+      ...versionHandledFacts(entry.id, version, versionEntry, surfaces),
+    ];
+  });
+
+const inputFact = (
+  input: TrailErrorEvidenceInput,
+  kind: 'inferred' | 'observed',
+  surfaces: readonly SurfaceName[]
+): TrailErrorFact => ({
+  completeness:
+    kind === 'inferred' ? inferredCompleteness : observedCompleteness,
+  kind,
+  provenance: {
+    ...(input.detail === undefined ? {} : { detail: input.detail }),
+    source: kind === 'inferred' ? 'static-inference' : 'runtime-observation',
+    trailId: input.trailId,
+    ...(input.version === undefined ? {} : { version: input.version }),
+  },
+  taxonomy: taxonomyProjection(input.errorName, surfaces),
+});
+
+const byTrail = (
+  inputs: readonly TrailErrorEvidenceInput[] | undefined
+): ReadonlyMap<string, readonly TrailErrorEvidenceInput[]> => {
+  const map = new Map<string, TrailErrorEvidenceInput[]>();
+  for (const input of inputs ?? []) {
+    const existing = map.get(input.trailId) ?? [];
+    existing.push(input);
+    map.set(input.trailId, existing);
+  }
+  return map;
+};
+
+const sortFacts = (
+  facts: readonly TrailErrorFact[]
+): readonly TrailErrorFact[] =>
+  [...facts].toSorted((left, right) => {
+    const leftVersion = left.provenance.version ?? 0;
+    const rightVersion = right.provenance.version ?? 0;
+    return (
+      leftVersion - rightVersion ||
+      left.kind.localeCompare(right.kind) ||
+      left.taxonomy.name.localeCompare(right.taxonomy.name)
+    );
+  });
+
+export const deriveTrailErrorFacts = (
+  topoGraph: TopoGraph,
+  options: TrailErrorFactsOptions = {}
+): readonly TrailErrorFacts[] => {
+  const surfaces = options.surfaces ?? surfaceNames;
+  const inferredByTrail = byTrail(options.inferred);
+  const observedByTrail = byTrail(options.observed);
+
+  return topoGraph.entries
+    .filter(
+      (entry): entry is TopoGraphEntry & { readonly kind: 'trail' } =>
+        entry.kind === 'trail'
+    )
+    .map((entry): TrailErrorFacts => {
+      const inferredInputs = inferredByTrail.get(entry.id) ?? [];
+      const observedInputs = observedByTrail.get(entry.id) ?? [];
+      const facts = sortFacts([
+        ...documentedFacts(entry, surfaces),
+        ...handledFacts(entry, surfaces),
+        ...versionFacts(entry, surfaces),
+        ...inferredInputs.map((input) =>
+          inputFact(input, 'inferred', surfaces)
+        ),
+        ...observedInputs.map((input) =>
+          inputFact(input, 'observed', surfaces)
+        ),
+      ]);
+
+      return {
+        completeness: {
+          documented: authoredCompleteness,
+          emitted: emittedCompleteness,
+          handled: authoredCompleteness,
+          inferred:
+            inferredInputs.length > 0
+              ? inferredCompleteness
+              : notEvaluatedCompleteness,
+          observed:
+            observedInputs.length > 0
+              ? observedCompleteness
+              : notEvaluatedCompleteness,
+        },
+        facts,
+        trailId: entry.id,
+      };
+    })
+    .toSorted((left, right) => left.trailId.localeCompare(right.trailId));
+};