@ontrails/schema 1.0.0-beta.0

package/src/diff.ts

@@ -0,0 +1,398 @@
+/**
+ * Semantic diffing of surface maps.
+ */
+
+import type {
+  DiffEntry,
+  DiffResult,
+  JsonSchema,
+  SurfaceMap,
+  SurfaceMapEntry,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type Severity = DiffEntry['severity'];
+
+interface DetailAccumulator {
+  readonly details: string[];
+  severity: Severity;
+}
+
+const escalate = (acc: DetailAccumulator, severity: Severity): void => {
+  const rank: Record<Severity, number> = { breaking: 2, info: 0, warning: 1 };
+  if (rank[severity] > rank[acc.severity]) {
+    acc.severity = severity;
+  }
+};
+
+const addDetail = (
+  acc: DetailAccumulator,
+  severity: Severity,
+  message: string
+): void => {
+  acc.details.push(message);
+  escalate(acc, severity);
+};
+
+// ---------------------------------------------------------------------------
+// Utility
+// ---------------------------------------------------------------------------
+
+const capitalize = (s: string): string =>
+  `${s.charAt(0).toUpperCase()}${s.slice(1)}`;
+
+// ---------------------------------------------------------------------------
+// Schema field diffing
+// ---------------------------------------------------------------------------
+
+interface SchemaProperties {
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+}
+
+const getProperties = (
+  schema: JsonSchema | undefined
+): Record<string, JsonSchema> => {
+  if (!schema) {
+    return {};
+  }
+  const props = (schema as SchemaProperties).properties;
+  return props ? { ...props } : {};
+};
+
+const getRequired = (schema: JsonSchema | undefined): ReadonlySet<string> => {
+  if (!schema) {
+    return new Set();
+  }
+  const req = (schema as SchemaProperties).required;
+  return new Set(req);
+};
+
+const inferSchemaType = (schema: JsonSchema): string => {
+  if (typeof schema['type'] === 'string') {
+    return schema['type'];
+  }
+  if (schema['const'] !== undefined) {
+    return `const(${String(schema['const'])})`;
+  }
+  if (schema['anyOf']) {
+    return 'union';
+  }
+  if (schema['enum']) {
+    return 'enum';
+  }
+  return 'unknown';
+};
+
+const getType = (schema: JsonSchema | undefined): string =>
+  schema ? inferSchemaType(schema) : 'unknown';
+
+/** Diff a single field that was added. */
+const diffAddedField = (
+  acc: DetailAccumulator,
+  direction: 'input' | 'output',
+  key: string,
+  currRequired: ReadonlySet<string>
+): void => {
+  if (direction === 'input' && currRequired.has(key)) {
+    addDetail(acc, 'breaking', `Required ${direction} field "${key}" added`);
+  } else {
+    const label = direction === 'input' ? `Optional ${direction}` : 'Output';
+    addDetail(acc, 'info', `${label} field "${key}" added`);
+  }
+};
+
+/** Diff a single field present in both prev and curr. */
+const diffModifiedField = (
+  acc: DetailAccumulator,
+  direction: 'input' | 'output',
+  key: string,
+  prevProps: Record<string, JsonSchema>,
+  currProps: Record<string, JsonSchema>,
+  prevRequired: ReadonlySet<string>,
+  currRequired: ReadonlySet<string>
+): void => {
+  const prevType = getType(prevProps[key]);
+  const currType = getType(currProps[key]);
+  if (prevType !== currType) {
+    addDetail(
+      acc,
+      'breaking',
+      `${capitalize(direction)} field "${key}" type changed: ${prevType} -> ${currType}`
+    );
+  }
+  if (
+    direction === 'input' &&
+    !prevRequired.has(key) &&
+    currRequired.has(key)
+  ) {
+    addDetail(
+      acc,
+      'breaking',
+      `Input field "${key}" changed from optional to required`
+    );
+  }
+};
+
+/** Diff a single key across prev/curr schemas. */
+const diffKey = (
+  acc: DetailAccumulator,
+  direction: 'input' | 'output',
+  key: string,
+  prevProps: Record<string, JsonSchema>,
+  currProps: Record<string, JsonSchema>,
+  prevRequired: ReadonlySet<string>,
+  currRequired: ReadonlySet<string>
+): void => {
+  const inPrev = key in prevProps;
+  const inCurr = key in currProps;
+  if (!inPrev && inCurr) {
+    diffAddedField(acc, direction, key, currRequired);
+  } else if (inPrev && !inCurr) {
+    addDetail(
+      acc,
+      'breaking',
+      `${capitalize(direction)} field "${key}" removed`
+    );
+  } else if (inPrev && inCurr) {
+    diffModifiedField(
+      acc,
+      direction,
+      key,
+      prevProps,
+      currProps,
+      prevRequired,
+      currRequired
+    );
+  }
+};
+
+const diffSchemaFields = (
+  acc: DetailAccumulator,
+  direction: 'input' | 'output',
+  prev: JsonSchema | undefined,
+  curr: JsonSchema | undefined
+): void => {
+  const prevProps = getProperties(prev);
+  const currProps = getProperties(curr);
+  const prevRequired = getRequired(prev);
+  const currRequired = getRequired(curr);
+  const allKeys = new Set([
+    ...Object.keys(prevProps),
+    ...Object.keys(currProps),
+  ]);
+
+  for (const key of [...allKeys].toSorted()) {
+    diffKey(
+      acc,
+      direction,
+      key,
+      prevProps,
+      currProps,
+      prevRequired,
+      currRequired
+    );
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Per-entry diffing
+// ---------------------------------------------------------------------------
+
+/** Diff surface additions and removals. */
+const diffSurfaces = (
+  acc: DetailAccumulator,
+  prev: SurfaceMapEntry,
+  curr: SurfaceMapEntry
+): void => {
+  const prevSurfaces = new Set(prev.surfaces);
+  const currSurfaces = new Set(curr.surfaces);
+  for (const s of [...currSurfaces].toSorted()) {
+    if (!prevSurfaces.has(s)) {
+      addDetail(acc, 'info', `Surface "${s}" added`);
+    }
+  }
+  for (const s of [...prevSurfaces].toSorted()) {
+    if (!currSurfaces.has(s)) {
+      addDetail(acc, 'breaking', `Surface "${s}" removed`);
+    }
+  }
+};
+
+/** Diff safety markers, description, and deprecation. */
+const diffMetadata = (
+  acc: DetailAccumulator,
+  prev: SurfaceMapEntry,
+  curr: SurfaceMapEntry
+): void => {
+  for (const marker of ['readOnly', 'destructive', 'idempotent'] as const) {
+    if (prev[marker] !== curr[marker]) {
+      addDetail(
+        acc,
+        'warning',
+        `${marker} changed: ${String(prev[marker] ?? false)} -> ${String(curr[marker] ?? false)}`
+      );
+    }
+  }
+  if (prev.description !== curr.description) {
+    addDetail(acc, 'info', 'Description updated');
+  }
+  if (!prev.deprecated && curr.deprecated) {
+    const msg = curr.replacedBy
+      ? `Deprecated (replaced by ${curr.replacedBy})`
+      : 'Deprecated';
+    addDetail(acc, 'warning', msg);
+  } else if (prev.deprecated && !curr.deprecated) {
+    addDetail(acc, 'info', 'Undeprecated');
+  }
+};
+
+/** Build a follows-changed description from added/removed arrays. */
+const buildFollowsMessage = (added: string[], removed: string[]): string => {
+  const parts: string[] = [];
+  if (added.length > 0) {
+    parts.push(`added "${added.join('", "')}"`);
+  }
+  if (removed.length > 0) {
+    parts.push(`removed "${removed.join('", "')}"`);
+  }
+  return `Follows changed: ${parts.join(', ')}`;
+};
+
+/** Diff follows arrays. */
+const diffFollows = (
+  acc: DetailAccumulator,
+  prev: SurfaceMapEntry,
+  curr: SurfaceMapEntry
+): void => {
+  const prevFollows = new Set(prev.follows);
+  const currFollows = new Set(curr.follows);
+  const added = [...currFollows].filter((f) => !prevFollows.has(f)).toSorted();
+  const removed = [...prevFollows]
+    .filter((f) => !currFollows.has(f))
+    .toSorted();
+  if (added.length > 0 || removed.length > 0) {
+    addDetail(acc, 'warning', buildFollowsMessage(added, removed));
+  }
+};
+
+const diffEntry = (
+  prev: SurfaceMapEntry,
+  curr: SurfaceMapEntry
+): DiffEntry | undefined => {
+  const acc: DetailAccumulator = { details: [], severity: 'info' };
+
+  diffSchemaFields(acc, 'input', prev.input, curr.input);
+  diffSchemaFields(acc, 'output', prev.output, curr.output);
+  diffSurfaces(acc, prev, curr);
+  diffMetadata(acc, prev, curr);
+  diffFollows(acc, prev, curr);
+
+  if (acc.details.length === 0) {
+    return undefined;
+  }
+
+  return {
+    change: 'modified',
+    details: acc.details,
+    id: curr.id,
+    kind: curr.kind,
+    severity: acc.severity,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a semantic diff between two surface maps.
+ *
+ * Classifies each change with a severity:
+ * - `info`: new trail, optional field added, output field added, description change
+ * - `warning`: safety marker change, deprecation, follows change
+ * - `breaking`: trail removed, required input added, field removed, type change, surface removed
+ */
+/** Find entries added in curr that don't exist in prev. */
+const findAdded = (
+  prevById: Map<string, SurfaceMapEntry>,
+  currById: Map<string, SurfaceMapEntry>
+): DiffEntry[] =>
+  [...currById.entries()]
+    .filter(([id]) => !prevById.has(id))
+    .map(([id, entry]) => ({
+      change: 'added' as const,
+      details: [`Trail "${id}" added`],
+      id,
+      kind: entry.kind,
+      severity: 'info' as const,
+    }));
+
+/** Find entries removed from prev that don't exist in curr. */
+const findRemoved = (
+  prevById: Map<string, SurfaceMapEntry>,
+  currById: Map<string, SurfaceMapEntry>
+): DiffEntry[] =>
+  [...prevById.entries()]
+    .filter(([id]) => !currById.has(id))
+    .map(([id, entry]) => ({
+      change: 'removed' as const,
+      details: [`Trail "${id}" removed`],
+      id,
+      kind: entry.kind,
+      severity: 'breaking' as const,
+    }));
+
+/** Find entries modified between prev and curr. */
+const findModified = (
+  prevById: Map<string, SurfaceMapEntry>,
+  currById: Map<string, SurfaceMapEntry>
+): DiffEntry[] => {
+  const results: DiffEntry[] = [];
+  for (const [id, currEntry] of currById) {
+    const prevEntry = prevById.get(id);
+    if (prevEntry) {
+      const diff = diffEntry(prevEntry, currEntry);
+      if (diff) {
+        results.push(diff);
+      }
+    }
+  }
+  return results;
+};
+
+/** Collect all diff entries (added, removed, modified) between two maps. */
+const collectDiffEntries = (
+  prevById: Map<string, SurfaceMapEntry>,
+  currById: Map<string, SurfaceMapEntry>
+): DiffEntry[] => [
+  ...findAdded(prevById, currById),
+  ...findRemoved(prevById, currById),
+  ...findModified(prevById, currById),
+];
+
+export const diffSurfaceMaps = (
+  prev: SurfaceMap,
+  curr: SurfaceMap
+): DiffResult => {
+  const prevById = new Map(prev.entries.map((e) => [e.id, e]));
+  const currById = new Map(curr.entries.map((e) => [e.id, e]));
+  const sorted = collectDiffEntries(prevById, currById).toSorted((a, b) =>
+    a.id.localeCompare(b.id)
+  );
+
+  const breaking = sorted.filter((e) => e.severity === 'breaking');
+  const warnings = sorted.filter((e) => e.severity === 'warning');
+  const info = sorted.filter((e) => e.severity === 'info');
+
+  return {
+    breaking,
+    entries: sorted,
+    hasBreaking: breaking.length > 0,
+    info,
+    warnings,
+  };
+};

package/src/generate.ts

@@ -0,0 +1,219 @@
+/**
+ * Generate a deterministic surface map from a Topo.
+ */
+
+import { zodToJsonSchema } from '@ontrails/core';
+import type { Event, Hike, Topo, Trail } from '@ontrails/core';
+
+import type { JsonSchema, SurfaceMap, SurfaceMapEntry } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Sort object keys lexicographically (shallow). */
+const sortKeys = <T extends Record<string, unknown>>(obj: T): T => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj).toSorted()) {
+    sorted[key] = obj[key];
+  }
+  return sorted as T;
+};
+
+/** Sort object keys recursively for deterministic JSON Schema output. */
+const deepSortKeys = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(deepSortKeys);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = deepSortKeys((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+};
+
+/** Convert a Zod schema to a deterministically-keyed JSON Schema. */
+const toSortedJsonSchema = (schema: unknown): JsonSchema => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const raw = zodToJsonSchema(schema as any);
+  return deepSortKeys(raw) as JsonSchema;
+};
+
+// ---------------------------------------------------------------------------
+// Entry builders
+// ---------------------------------------------------------------------------
+
+/** Extract surfaces from a raw object. */
+const extractSurfaces = (raw: Record<string, unknown>): string[] =>
+  Array.isArray(raw['surfaces'])
+    ? (raw['surfaces'] as string[]).toSorted()
+    : [];
+
+/** Add optional schemas to an entry. */
+const addSchemas = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown>
+): void => {
+  if (t.input) {
+    entry['input'] = toSortedJsonSchema(t.input);
+  }
+  if (t.output) {
+    entry['output'] = toSortedJsonSchema(t.output);
+  }
+};
+
+/** Add safety markers to an entry. */
+const addSafetyMarkers = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown>
+): void => {
+  if (t.readOnly === true) {
+    entry['readOnly'] = true;
+  }
+  if (t.destructive === true) {
+    entry['destructive'] = true;
+  }
+  if (t.idempotent === true) {
+    entry['idempotent'] = true;
+  }
+};
+
+/** Add deprecation and detours to an entry. */
+const addExtendedMetadata = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown>,
+  raw: Record<string, unknown>
+): void => {
+  if (raw['deprecated'] === true) {
+    entry['deprecated'] = true;
+  }
+  if (typeof raw['replacedBy'] === 'string') {
+    entry['replacedBy'] = raw['replacedBy'];
+  }
+  if (t.detours) {
+    const detoursSorted: Record<string, readonly string[]> = {};
+    for (const key of Object.keys(t.detours).toSorted()) {
+      detoursSorted[key] = (t.detours[key] ?? []).toSorted();
+    }
+    entry['detours'] = detoursSorted;
+  }
+};
+
+/** Add optional metadata fields to an entry. */
+const addMetadata = (
+  entry: Record<string, unknown>,
+  t: Trail<unknown, unknown>,
+  raw: Record<string, unknown>
+): void => {
+  if (t.description !== undefined) {
+    entry['description'] = t.description;
+  }
+  addSafetyMarkers(entry, t);
+  addExtendedMetadata(entry, t, raw);
+};
+
+const trailToEntry = (t: Trail<unknown, unknown>): SurfaceMapEntry => {
+  const raw = t as unknown as Record<string, unknown>;
+  const entry: Record<string, unknown> = {
+    exampleCount: Array.isArray(t.examples) ? t.examples.length : 0,
+    id: t.id,
+    kind: t.kind,
+    surfaces: extractSurfaces(raw),
+  };
+
+  addSchemas(entry, t);
+  addMetadata(entry, t, raw);
+
+  return sortKeys(entry) as unknown as SurfaceMapEntry;
+};
+
+const hikeToEntry = (r: Hike<unknown, unknown>): SurfaceMapEntry => {
+  const base = trailToEntry(r as unknown as Trail<unknown, unknown>);
+  const raw = r as unknown as Record<string, unknown>;
+
+  const entry: Record<string, unknown> = {
+    ...base,
+    follows: r.follows.toSorted(),
+    kind: 'hike',
+  };
+
+  // Re-check surfaces on the route itself
+  if (Array.isArray(raw['surfaces'])) {
+    entry['surfaces'] = (raw['surfaces'] as string[]).toSorted();
+  }
+
+  return sortKeys(entry) as unknown as SurfaceMapEntry;
+};
+
+/** Add optional event-specific fields. */
+const addEventFields = (
+  entry: Record<string, unknown>,
+  e: Event<unknown>,
+  raw: Record<string, unknown>
+): void => {
+  if (e.payload) {
+    entry['input'] = toSortedJsonSchema(e.payload);
+  }
+  if (e.description !== undefined) {
+    entry['description'] = e.description;
+  }
+  if (raw['deprecated'] === true) {
+    entry['deprecated'] = true;
+  }
+  if (typeof raw['replacedBy'] === 'string') {
+    entry['replacedBy'] = raw['replacedBy'];
+  }
+};
+
+const eventToEntry = (e: Event<unknown>): SurfaceMapEntry => {
+  const raw = e as unknown as Record<string, unknown>;
+  const entry: Record<string, unknown> = {
+    exampleCount: 0,
+    id: e.id,
+    kind: 'event',
+    surfaces: extractSurfaces(raw),
+  };
+  addEventFields(entry, e, raw);
+  return sortKeys(entry) as unknown as SurfaceMapEntry;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a deterministic surface map from a Topo.
+ *
+ * Entries are sorted alphabetically by id. Object keys within each entry
+ * are sorted lexicographically for stable serialization.
+ */
+export const generateSurfaceMap = (topo: Topo): SurfaceMap => {
+  const entries: SurfaceMapEntry[] = [];
+
+  // Collect all trails
+  for (const t of topo.trails.values()) {
+    entries.push(trailToEntry(t as Trail<unknown, unknown>));
+  }
+
+  // Collect all hikes
+  for (const r of topo.hikes.values()) {
+    entries.push(hikeToEntry(r as Hike<unknown, unknown>));
+  }
+
+  // Collect all events
+  for (const e of topo.events.values()) {
+    entries.push(eventToEntry(e as Event<unknown>));
+  }
+
+  // Sort alphabetically by id
+  const sorted = entries.toSorted((a, b) => a.id.localeCompare(b.id));
+
+  return {
+    entries: sorted,
+    generatedAt: new Date().toISOString(),
+    version: '1.0',
+  };
+};

package/src/hash.ts

@@ -0,0 +1,51 @@
+/**
+ * SHA-256 hashing for surface maps.
+ *
+ * Uses Bun.CryptoHasher for native hashing.
+ */
+
+import type { SurfaceMap } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively sort all object keys for deterministic JSON serialization.
+ * Arrays preserve order; primitives pass through.
+ */
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = canonicalize((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a SHA-256 hash of a surface map.
+ *
+ * The `generatedAt` field is excluded so that identical topos always
+ * produce the same hash regardless of when they were generated.
+ */
+export const hashSurfaceMap = (surfaceMap: SurfaceMap): string => {
+  // Strip generatedAt before hashing
+  const { generatedAt: _unused, ...rest } = surfaceMap;
+
+  const canonical = canonicalize(rest);
+  const json = JSON.stringify(canonical);
+
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(json);
+  return hasher.digest('hex');
+};

package/src/index.ts

@@ -0,0 +1,23 @@
+// Generation
+export { generateSurfaceMap } from './generate.js';
+export { hashSurfaceMap } from './hash.js';
+export { diffSurfaceMaps } from './diff.js';
+
+// File I/O
+export {
+  writeSurfaceMap,
+  readSurfaceMap,
+  writeSurfaceLock,
+  readSurfaceLock,
+} from './io.js';
+
+// Types
+export type {
+  SurfaceMap,
+  SurfaceMapEntry,
+  DiffEntry,
+  DiffResult,
+  JsonSchema,
+  WriteOptions,
+  ReadOptions,
+} from './types.js';