@ontrails/core 0.2.0

package/src/version-resolution.ts

@@ -0,0 +1,308 @@
+import {
+  AmbiguousError,
+  TrailsError,
+  ValidationError,
+  VersionNotSupportedError,
+} from './errors.js';
+import { Result } from './result.js';
+import {
+  deriveSupportedTrailVersions,
+  getTrailVersionEntryKind,
+  isArchivedTrailVersionEntry,
+} from './trail.js';
+import type {
+  AnyTrail,
+  TrailVersionForkEntry,
+  TrailVersionRevisionEntry,
+} from './trail.js';
+import {
+  TRAIL_VERSION_MARKER_LENGTH,
+  TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH,
+  deriveTrailVersionMarkers,
+} from './version-marker.js';
+
+export type TrailVersionReference = number | string;
+
+export interface ParsedTrailVersionReference {
+  readonly id: string;
+  readonly version?: TrailVersionReference | undefined;
+}
+
+export type ResolvedTrailVersion =
+  | {
+      readonly current: true;
+      readonly kind: 'current';
+      readonly marker?: string | undefined;
+      readonly version?: number | undefined;
+    }
+  | {
+      readonly current: false;
+      readonly deprecated: boolean;
+      readonly entry: TrailVersionForkEntry;
+      readonly kind: 'fork';
+      readonly marker?: string | undefined;
+      readonly version: number;
+    }
+  | {
+      readonly current: false;
+      readonly deprecated: boolean;
+      readonly entry: TrailVersionRevisionEntry;
+      readonly kind: 'revision';
+      readonly marker?: string | undefined;
+      readonly version: number;
+    };
+
+interface ParsedVersionReference {
+  readonly display: number | string;
+  readonly markerPrefix?: string | undefined;
+  readonly number?: number | undefined;
+}
+
+type MarkerResolvableTrail = Pick<
+  AnyTrail,
+  | 'composes'
+  | 'detours'
+  | 'id'
+  | 'input'
+  | 'output'
+  | 'resources'
+  | 'version'
+  | 'versions'
+>;
+
+const versionRefPattern = /^(.+)@(.+)$/;
+const positiveIntegerPattern = /^[1-9]\d*$/;
+const markerPrefixPattern = /^[0-9a-fA-F]+$/;
+
+const parsePositiveInteger = (value: string): number | undefined => {
+  if (!positiveIntegerPattern.test(value)) {
+    return undefined;
+  }
+  const version = Number(value);
+  return Number.isSafeInteger(version) ? version : undefined;
+};
+
+const isInlineVersionReference = (value: string): boolean =>
+  parsePositiveInteger(value) !== undefined ||
+  (value.length >= TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH &&
+    value.length <= TRAIL_VERSION_MARKER_LENGTH &&
+    markerPrefixPattern.test(value));
+
+const unsupportedVersion = (
+  trail: Pick<AnyTrail, 'id' | 'version' | 'versions'>,
+  requested: number | string,
+  reason: string
+): VersionNotSupportedError => {
+  const supported = deriveSupportedTrailVersions(trail);
+  return new VersionNotSupportedError(trail.id, requested, supported, reason);
+};
+
+export const parseTrailIdVersionReference = (
+  id: string
+): Result<ParsedTrailVersionReference, ValidationError> => {
+  const match = versionRefPattern.exec(id);
+  if (match === null) {
+    return Result.ok({ id });
+  }
+
+  const [, baseId, rawVersion] = match;
+  if (baseId === undefined || rawVersion === undefined) {
+    return Result.err(
+      new ValidationError(
+        'Trail version reference must use trail.id@N or trail.id@<marker-prefix>'
+      )
+    );
+  }
+  if (!isInlineVersionReference(rawVersion)) {
+    return Result.ok({ id });
+  }
+
+  return Result.ok({ id: baseId, version: rawVersion });
+};
+
+const parseVersionReference = (
+  reference: TrailVersionReference
+): Result<ParsedVersionReference, Error> => {
+  if (typeof reference === 'number') {
+    return Number.isSafeInteger(reference) && reference > 0
+      ? Result.ok({ display: reference, number: reference })
+      : Result.err(
+          new ValidationError(
+            'Trail version reference must be a positive integer'
+          )
+        );
+  }
+
+  const markerRequested = reference.startsWith('@');
+  const raw = markerRequested ? reference.slice(1) : reference;
+  if (raw.length === 0) {
+    return Result.err(
+      new ValidationError('Trail version reference must not be empty')
+    );
+  }
+
+  const number = parsePositiveInteger(raw);
+  if (!markerRequested && number !== undefined) {
+    return Result.ok({
+      display: reference,
+      markerPrefix:
+        raw.length >= TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH &&
+        raw.length <= TRAIL_VERSION_MARKER_LENGTH &&
+        markerPrefixPattern.test(raw)
+          ? raw.toLowerCase()
+          : undefined,
+      number,
+    });
+  }
+
+  if (
+    raw.length >= TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH &&
+    raw.length <= TRAIL_VERSION_MARKER_LENGTH &&
+    markerPrefixPattern.test(raw)
+  ) {
+    return Result.ok({
+      display: reference,
+      markerPrefix: raw.toLowerCase(),
+    });
+  }
+
+  return Result.err(
+    new ValidationError(
+      'Trail version reference must be a positive integer or marker prefix'
+    )
+  );
+};
+
+const trailHasVersion = (
+  trail: Pick<AnyTrail, 'version' | 'versions'>,
+  version: number
+): boolean =>
+  trail.version === version || trail.versions?.[version] !== undefined;
+
+const resolveMarkerReference = (
+  trail: MarkerResolvableTrail,
+  requested: number | string,
+  prefix: string
+): Result<{ readonly marker: string; readonly version: number }, Error> => {
+  let records: ReturnType<typeof deriveTrailVersionMarkers>;
+  try {
+    records = deriveTrailVersionMarkers(trail);
+  } catch (error: unknown) {
+    return Result.err(
+      error instanceof TrailsError
+        ? error
+        : new ValidationError(
+            `Trail version marker derivation failed: ${String(error)}`
+          )
+    );
+  }
+  const matches = records.filter((record) => record.marker.startsWith(prefix));
+
+  if (matches.length === 0) {
+    return Result.err(unsupportedVersion(trail, requested, 'marker missing'));
+  }
+  if (matches.length > 1) {
+    return Result.err(
+      new AmbiguousError(
+        `Trail version marker prefix ${prefix} is ambiguous across versions ${matches.map((record) => record.version).join(', ')}`
+      )
+    );
+  }
+
+  const match = matches[0] as (typeof matches)[number];
+
+  return Result.ok({ marker: match.marker, version: match.version });
+};
+
+const resolveRequestedVersionNumber = (
+  trail: MarkerResolvableTrail,
+  reference: TrailVersionReference
+): Result<
+  { readonly marker?: string | undefined; readonly version: number },
+  Error
+> => {
+  const parsed = parseVersionReference(reference);
+  if (parsed.isErr()) {
+    return parsed;
+  }
+
+  const { display, markerPrefix, number } = parsed.value;
+  if (number !== undefined && trailHasVersion(trail, number)) {
+    return Result.ok({ version: number });
+  }
+
+  if (markerPrefix !== undefined) {
+    const marker = resolveMarkerReference(trail, display, markerPrefix);
+    if (marker.isOk()) {
+      return marker;
+    }
+    if (number === undefined) {
+      return marker;
+    }
+  }
+
+  return Result.err(unsupportedVersion(trail, display, 'missing'));
+};
+
+export const resolveTrailVersion = (
+  trail: MarkerResolvableTrail,
+  reference?: TrailVersionReference | undefined
+): Result<ResolvedTrailVersion, Error> => {
+  if (reference === undefined) {
+    return Result.ok({
+      current: true,
+      kind: 'current',
+      ...(trail.version === undefined ? {} : { version: trail.version }),
+    });
+  }
+
+  if (trail.version === undefined) {
+    return Result.err(unsupportedVersion(trail, reference, 'unversioned'));
+  }
+
+  const requested = resolveRequestedVersionNumber(trail, reference);
+  if (requested.isErr()) {
+    return requested;
+  }
+
+  if (requested.value.version === trail.version) {
+    return Result.ok({
+      current: true,
+      kind: 'current',
+      ...(requested.value.marker === undefined
+        ? {}
+        : { marker: requested.value.marker }),
+      version: trail.version,
+    });
+  }
+
+  const entry = trail.versions?.[requested.value.version];
+  if (entry === undefined) {
+    return Result.err(unsupportedVersion(trail, reference, 'missing'));
+  }
+  if (isArchivedTrailVersionEntry(entry)) {
+    return Result.err(unsupportedVersion(trail, reference, 'archived'));
+  }
+
+  const kind = getTrailVersionEntryKind(entry);
+  const base = {
+    current: false,
+    deprecated: entry.status?.state === 'deprecated',
+    ...(requested.value.marker === undefined
+      ? {}
+      : { marker: requested.value.marker }),
+    version: requested.value.version,
+  } as const;
+
+  return kind === 'fork'
+    ? Result.ok({
+        ...base,
+        entry: entry as TrailVersionForkEntry,
+        kind,
+      })
+    : Result.ok({
+        ...base,
+        entry: entry as TrailVersionRevisionEntry,
+        kind,
+      });
+};

package/src/version-runtime.ts

@@ -0,0 +1,120 @@
+import { InternalError, ValidationError } from './errors.js';
+import { Result } from './result.js';
+import type { ExecuteTrailOptions } from './execute.js';
+import { getTrailVersionEntryKind } from './trail.js';
+import type { AnyTrail, TrailVersionEntry } from './trail.js';
+import { validateInput, validateOutput } from './validation.js';
+
+export type TrailVersionCurrentExecutor<
+  Options extends ExecuteTrailOptions = ExecuteTrailOptions,
+> = (
+  trail: AnyTrail,
+  input: unknown,
+  options?: Options
+) => Promise<Result<unknown, Error>>;
+
+const normalizeTransposeError = (
+  trail: AnyTrail,
+  version: number,
+  phase: 'input' | 'output',
+  error: unknown
+): InternalError => {
+  const message = error instanceof Error ? error.message : String(error);
+  const options: { cause?: Error; context: Record<string, unknown> } = {
+    context: { phase, trailId: trail.id, version },
+  };
+  if (error instanceof Error) {
+    options.cause = error;
+  }
+  return new InternalError(
+    `Trail "${trail.id}" version ${version} transpose.${phase} failed: ${message}`,
+    options
+  );
+};
+
+const runTransposeInput = async (
+  trail: AnyTrail,
+  version: number,
+  entry: TrailVersionEntry,
+  input: unknown
+): Promise<Result<unknown, Error>> => {
+  if (entry.transpose === undefined) {
+    return Result.ok(input);
+  }
+
+  try {
+    return Result.ok(await entry.transpose.input({ input }));
+  } catch (error: unknown) {
+    return Result.err(normalizeTransposeError(trail, version, 'input', error));
+  }
+};
+
+const runTransposeOutput = async (
+  trail: AnyTrail,
+  version: number,
+  entry: TrailVersionEntry,
+  output: unknown
+): Promise<Result<unknown, Error>> => {
+  if (entry.transpose === undefined) {
+    return Result.ok(output);
+  }
+
+  try {
+    return Result.ok(await entry.transpose.output({ output }));
+  } catch (error: unknown) {
+    return Result.err(normalizeTransposeError(trail, version, 'output', error));
+  }
+};
+
+export const executeTrailRevision = async <
+  Options extends ExecuteTrailOptions = ExecuteTrailOptions,
+>(
+  trail: AnyTrail,
+  version: number,
+  entry: TrailVersionEntry,
+  rawInput: unknown,
+  options: Options | undefined,
+  executeCurrentTrail: TrailVersionCurrentExecutor<Options>
+): Promise<Result<unknown, Error>> => {
+  if (getTrailVersionEntryKind(entry) !== 'revision') {
+    return Result.err(
+      new ValidationError(
+        `Trail "${trail.id}" version ${version} is not a revision entry`
+      )
+    );
+  }
+
+  const historicalInput = validateInput(entry.input, rawInput);
+  if (historicalInput.isErr()) {
+    return historicalInput;
+  }
+
+  const currentInput = await runTransposeInput(
+    trail,
+    version,
+    entry,
+    historicalInput.value
+  );
+  if (currentInput.isErr()) {
+    return currentInput;
+  }
+
+  const currentOutput = await executeCurrentTrail(
+    trail,
+    currentInput.value,
+    options
+  );
+  if (currentOutput.isErr()) {
+    return currentOutput;
+  }
+
+  const historicalOutput = await runTransposeOutput(
+    trail,
+    version,
+    entry,
+    currentOutput.value
+  );
+  return historicalOutput.isErr()
+    ? historicalOutput
+    : validateOutput(entry.output, historicalOutput.value);
+};