@ontrails/schema 1.0.0-beta.0

package/src/io.ts

@@ -0,0 +1,115 @@
+/**
+ * File I/O for surface maps and lock files.
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type { ReadOptions, SurfaceMap, WriteOptions } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_DIR = '.trails';
+const SURFACE_MAP_FILE = '_surface.json';
+const SURFACE_LOCK_FILE = 'surface.lock';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const isNotFound = (err: unknown): boolean =>
+  typeof err === 'object' &&
+  err !== null &&
+  (err as NodeJS.ErrnoException).code === 'ENOENT';
+
+const resolveDir = (options?: ReadOptions | WriteOptions): string =>
+  options?.dir ?? DEFAULT_DIR;
+
+const ensureDir = async (dir: string): Promise<void> => {
+  await mkdir(dir, { recursive: true });
+};
+
+// ---------------------------------------------------------------------------
+// Surface Map
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a surface map to `<dir>/_surface.json`.
+ *
+ * Creates the directory if it doesn't exist. Returns the file path.
+ */
+export const writeSurfaceMap = async (
+  surfaceMap: SurfaceMap,
+  options?: WriteOptions
+): Promise<string> => {
+  const dir = resolveDir(options);
+  await ensureDir(dir);
+  const filePath = join(dir, SURFACE_MAP_FILE);
+  const json = `${JSON.stringify(surfaceMap, null, 2)}\n`;
+  await Bun.write(filePath, json);
+  return filePath;
+};
+
+/**
+ * Read a surface map from `<dir>/_surface.json`.
+ *
+ * Returns `null` if the file doesn't exist.
+ */
+export const readSurfaceMap = async (
+  options?: ReadOptions
+): Promise<SurfaceMap | null> => {
+  const dir = resolveDir(options);
+  const filePath = join(dir, SURFACE_MAP_FILE);
+  try {
+    const content = await Bun.file(filePath).text();
+    return JSON.parse(content) as SurfaceMap;
+  } catch (error: unknown) {
+    if (isNotFound(error)) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Surface Lock
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a hash to `<dir>/surface.lock` as a single line.
+ *
+ * Creates the directory if it doesn't exist. Returns the file path.
+ */
+export const writeSurfaceLock = async (
+  hash: string,
+  options?: WriteOptions
+): Promise<string> => {
+  const dir = resolveDir(options);
+  await ensureDir(dir);
+  const filePath = join(dir, SURFACE_LOCK_FILE);
+  await Bun.write(filePath, `${hash}\n`);
+  return filePath;
+};
+
+/**
+ * Read the hash from `<dir>/surface.lock`.
+ *
+ * Returns `null` if the file doesn't exist.
+ */
+export const readSurfaceLock = async (
+  options?: ReadOptions
+): Promise<string | null> => {
+  const dir = resolveDir(options);
+  const filePath = join(dir, SURFACE_LOCK_FILE);
+  try {
+    const content = await Bun.file(filePath).text();
+    return content.trim();
+  } catch (error: unknown) {
+    if (isNotFound(error)) {
+      return null;
+    }
+    throw error;
+  }
+};

package/src/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Types for surface maps, diffing, and lock files.
+ */
+
+// ---------------------------------------------------------------------------
+// JSON Schema (lightweight alias)
+// ---------------------------------------------------------------------------
+
+/** A JSON Schema object produced by zodToJsonSchema. */
+export type JsonSchema = Readonly<Record<string, unknown>>;
+
+// ---------------------------------------------------------------------------
+// Surface Map
+// ---------------------------------------------------------------------------
+
+export interface SurfaceMapEntry {
+  readonly id: string;
+  readonly kind: 'trail' | 'hike' | 'event';
+  readonly surfaces: readonly string[];
+  readonly input?: JsonSchema | undefined;
+  readonly output?: JsonSchema | undefined;
+  readonly readOnly?: boolean | undefined;
+  readonly destructive?: boolean | undefined;
+  readonly idempotent?: boolean | undefined;
+  readonly deprecated?: boolean | undefined;
+  readonly replacedBy?: string | undefined;
+  readonly follows?: readonly string[] | undefined;
+  readonly detours?: Readonly<Record<string, readonly string[]>> | undefined;
+  readonly exampleCount: number;
+  readonly description?: string | undefined;
+}
+
+export interface SurfaceMap {
+  readonly version: string;
+  readonly generatedAt: string;
+  readonly entries: readonly SurfaceMapEntry[];
+}
+
+// ---------------------------------------------------------------------------
+// Diff
+// ---------------------------------------------------------------------------
+
+export interface DiffEntry {
+  readonly id: string;
+  readonly kind: 'trail' | 'hike' | 'event';
+  readonly change: 'added' | 'removed' | 'modified';
+  readonly severity: 'info' | 'warning' | 'breaking';
+  readonly details: readonly string[];
+}
+
+export interface DiffResult {
+  readonly entries: readonly DiffEntry[];
+  readonly breaking: readonly DiffEntry[];
+  readonly warnings: readonly DiffEntry[];
+  readonly info: readonly DiffEntry[];
+  readonly hasBreaking: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// I/O options
+// ---------------------------------------------------------------------------
+
+export interface WriteOptions {
+  /** Directory to write to. Defaults to ".trails/" */
+  readonly dir?: string | undefined;
+}
+
+export interface ReadOptions {
+  /** Directory to read from. Defaults to ".trails/" */
+  readonly dir?: string | undefined;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/diff.ts","./src/generate.ts","./src/hash.ts","./src/index.ts","./src/io.ts","./src/types.ts"],"version":"5.9.3"}