@gobing-ai/ts-runtime 0.3.0 → 0.3.2

package/src/schema-validation.ts

@@ -1,6 +1,7 @@
 import { parse as parseYaml } from 'yaml';
+import type { FileSystem } from './file-system';
 import { getFs } from './fs';
-import { dirnamePath, isAbsolutePath, joinPath } from './path';
+import { dirnamePath, getProcessCwd, isAbsolutePath, joinPath } from './path';
 
 /** Default time budget for a single remote schema fetch. */
 const REMOTE_SCHEMA_FETCH_TIMEOUT_MS = 5_000;
@@ -8,11 +9,13 @@ const REMOTE_SCHEMA_FETCH_TIMEOUT_MS = 5_000;
 /** Upper bound on a remote schema body. A timeout alone lets a slow multi-GB drip exhaust memory. */
 const REMOTE_SCHEMA_MAX_BYTES = 5 * 1024 * 1024;
 
+/** A single JSON Schema validation failure — records the JSON pointer path and a human-readable message. */
 export interface JsonSchemaViolation {
     path: string;
     message: string;
 }
 
+/** Subset of JSON Schema 2020-12 keywords used for runtime configuration validation. */
 export interface JsonSchema {
     type?: string | string[];
     required?: string[];
@@ -27,6 +30,7 @@ export interface JsonSchema {
     $defs?: Record<string, JsonSchema>;
 }
 
+/** Options for loading and validating structured configuration files (YAML/JSON with `$schema`). */
 export interface StructuredConfigLoadOptions {
     validateSchema?: boolean;
     /**
@@ -42,8 +46,16 @@ export interface StructuredConfigLoadOptions {
      * Injectable for testing.
      */
     resolve?: (specifier: string, from: string) => string;
+    /**
+     * File system used to read the config and local schema files. Defaults to the
+     * deprecated `getFs()` global; supply a {@link FileSystem} from the runtime factory
+     * (`createNodeFileSystem()`) to route reads through the factory path or to inject a
+     * virtual file system in tests.
+     */
+    fileSystem?: Pick<FileSystem, 'readFile'>;
 }
 
+/** Error thrown when structured config validation fails, carrying the list of {@link JsonSchemaViolation}s. */
 export class StructuredConfigSchemaError extends Error {
     constructor(
         message: string,
@@ -54,11 +66,13 @@ export class StructuredConfigSchemaError extends Error {
     }
 }
 
+/** Reads a config file from disk, parses it (YAML or JSON), and validates against its declared `$schema`. */
 export async function loadStructuredConfig(path: string, options: StructuredConfigLoadOptions = {}): Promise<unknown> {
-    const content = await getFs().readFile(path);
+    const content = await (options.fileSystem ?? getFs()).readFile(path);
     return await parseStructuredConfig(content, path, options);
 }
 
+/** Parses a config string (YAML or JSON) and validates against its declared `$schema` if present. */
 export async function parseStructuredConfig(
     content: string,
     source: string,
@@ -71,6 +85,7 @@ export async function parseStructuredConfig(
     return parsed;
 }
 
+/** Extracts the `$schema` reference from a parsed config object, resolves and fetches the schema, then validates. */
 export async function validateDeclaredJsonSchema(
     value: unknown,
     source: string,
@@ -108,6 +123,7 @@ export async function validateDeclaredJsonSchema(
     }
 }
 
+/** Validates a value against a {@link JsonSchema}, returning a list of {@link JsonSchemaViolation}s. Does not throw. */
 export function validateJsonSchema(
     value: unknown,
     schema: JsonSchema,
@@ -309,7 +325,7 @@ function resolvePackageSchema(
             `Package schema ref "${specifier}" referenced by "${source}" must include a path within the package`,
         );
     }
-    const from = isRemoteRef(source) ? process.cwd() : dirnamePath(source);
+    const from = isRemoteRef(source) ? getProcessCwd() : dirnamePath(source);
     try {
         // Resolve the package root via its always-present package.json, then join the subpath.
         // This sidesteps `exports` gating on arbitrary JSON subpaths.
@@ -344,7 +360,7 @@ async function readSchema(schemaLocation: string, options: StructuredConfigLoadO
         }
         return await readBoundedBody(response, schemaLocation);
     }
-    return await getFs().readFile(schemaLocation);
+    return await (options.fileSystem ?? getFs()).readFile(schemaLocation);
 }
 
 /**

package/src/types.ts

@@ -1,18 +1,22 @@
 import type { Config } from './config';
 
+/** Identifier for the target runtime platform. */
 export type RuntimeName = 'node-bun' | 'cloudflare-workers' | 'test';
 
+/** Feature flags describing what a runtime platform supports (filesystem, process execution, persistent storage). */
 export interface RuntimeCapabilities {
     readonly hasFilesystem: boolean;
     readonly hasProcessExecution: boolean;
     readonly hasPersistentStorage: boolean;
 }
 
+/** Options passed to config loading functions, including overrides and environment variable bindings. */
 export interface LoadConfigOptions {
     overrides?: Partial<Config>;
     envBindings?: Record<string, unknown>;
 }
 
+/** Minimal distributed tracing context for W3C trace/span propagation. */
 export interface SpanContext {
     traceId: string;
     spanId: string;