apcore-js 0.5.0 → 0.6.0

package/src/schema/loader.ts

@@ -1,273 +0,0 @@
-/**
- * SchemaLoader — primary entry point for the schema system.
- *
- * Uses TypeBox for schema representation. Since TypeBox schemas ARE JSON Schema,
- * the conversion layer is minimal.
- */
-
-import { readFileSync, existsSync } from 'node:fs';
-import { resolve, join } from 'node:path';
-import { Type, type TSchema } from '@sinclair/typebox';
-import yaml from 'js-yaml';
-import type { Config } from '../config.js';
-import { SchemaNotFoundError, SchemaParseError } from '../errors.js';
-import { RefResolver } from './ref-resolver.js';
-import type { ResolvedSchema, SchemaDefinition } from './types.js';
-import { SchemaStrategy } from './types.js';
-
-export class SchemaLoader {
-  private _config: Config;
-  private _schemasDir: string;
-  private _resolver: RefResolver;
-  private _schemaCache: Map<string, SchemaDefinition> = new Map();
-  private _modelCache: Map<string, [ResolvedSchema, ResolvedSchema]> = new Map();
-
-  constructor(config: Config, schemasDir?: string | null) {
-    this._config = config;
-    if (schemasDir != null) {
-      this._schemasDir = resolve(schemasDir);
-    } else {
-      this._schemasDir = resolve(config.get('schema.root', './schemas') as string);
-    }
-    const maxDepth = (config.get('schema.max_ref_depth', 32) as number);
-    this._resolver = new RefResolver(this._schemasDir, maxDepth);
-  }
-
-  load(moduleId: string): SchemaDefinition {
-    const cached = this._schemaCache.get(moduleId);
-    if (cached) return cached;
-
-    const filePath = join(this._schemasDir, moduleId.replace(/\./g, '/') + '.schema.yaml');
-    if (!existsSync(filePath)) {
-      throw new SchemaNotFoundError(moduleId);
-    }
-
-    let data: unknown;
-    try {
-      data = yaml.load(readFileSync(filePath, 'utf-8'));
-    } catch (e) {
-      throw new SchemaParseError(`Invalid YAML in schema for '${moduleId}': ${e}`);
-    }
-
-    if (data === null || data === undefined || typeof data !== 'object' || Array.isArray(data)) {
-      throw new SchemaParseError(`Schema file for '${moduleId}' is empty or not a mapping`);
-    }
-
-    const dataObj = data as Record<string, unknown>;
-    for (const fieldName of ['input_schema', 'output_schema', 'description']) {
-      if (!(fieldName in dataObj)) {
-        throw new SchemaParseError(`Missing required field: ${fieldName} in schema for '${moduleId}'`);
-      }
-    }
-
-    const definitions: Record<string, unknown> = {
-      ...((dataObj['definitions'] as Record<string, unknown>) ?? {}),
-      ...((dataObj['$defs'] as Record<string, unknown>) ?? {}),
-    };
-
-    const sd: SchemaDefinition = {
-      moduleId: (dataObj['module_id'] as string) ?? moduleId,
-      description: dataObj['description'] as string,
-      inputSchema: dataObj['input_schema'] as Record<string, unknown>,
-      outputSchema: dataObj['output_schema'] as Record<string, unknown>,
-      errorSchema: (dataObj['error_schema'] as Record<string, unknown>) ?? null,
-      definitions,
-      version: (dataObj['version'] as string) ?? '1.0.0',
-      documentation: (dataObj['documentation'] as string) ?? null,
-      schemaUrl: (dataObj['$schema'] as string) ?? null,
-    };
-
-    this._schemaCache.set(moduleId, sd);
-    return sd;
-  }
-
-  resolve(schemaDef: SchemaDefinition): [ResolvedSchema, ResolvedSchema] {
-    const resolvedInput = this._resolver.resolve(schemaDef.inputSchema);
-    const resolvedOutput = this._resolver.resolve(schemaDef.outputSchema);
-
-    const inputSchema = jsonSchemaToTypeBox(resolvedInput);
-    const outputSchema = jsonSchemaToTypeBox(resolvedOutput);
-
-    const inputRs: ResolvedSchema = {
-      jsonSchema: resolvedInput,
-      schema: inputSchema,
-      moduleId: schemaDef.moduleId,
-      direction: 'input',
-    };
-    const outputRs: ResolvedSchema = {
-      jsonSchema: resolvedOutput,
-      schema: outputSchema,
-      moduleId: schemaDef.moduleId,
-      direction: 'output',
-    };
-    return [inputRs, outputRs];
-  }
-
-  getSchema(
-    moduleId: string,
-    nativeInputSchema?: TSchema | null,
-    nativeOutputSchema?: TSchema | null,
-  ): [ResolvedSchema, ResolvedSchema] {
-    const cached = this._modelCache.get(moduleId);
-    if (cached) return cached;
-
-    const strategyMap: Record<string, SchemaStrategy> = {
-      yaml_first: SchemaStrategy.YamlFirst,
-      native_first: SchemaStrategy.NativeFirst,
-      yaml_only: SchemaStrategy.YamlOnly,
-    };
-    const rawStrategy = this._config.get('schema.strategy', 'yaml_first') as string;
-    const strategy = strategyMap[rawStrategy] ?? SchemaStrategy.YamlFirst;
-
-    let result: [ResolvedSchema, ResolvedSchema] | null = null;
-
-    if (strategy === SchemaStrategy.YamlFirst) {
-      try {
-        result = this._loadAndResolve(moduleId);
-      } catch (e) {
-        if (e instanceof SchemaNotFoundError && nativeInputSchema && nativeOutputSchema) {
-          result = this._wrapNative(moduleId, nativeInputSchema, nativeOutputSchema);
-        } else {
-          throw e;
-        }
-      }
-    } else if (strategy === SchemaStrategy.NativeFirst) {
-      if (nativeInputSchema && nativeOutputSchema) {
-        result = this._wrapNative(moduleId, nativeInputSchema, nativeOutputSchema);
-      } else {
-        result = this._loadAndResolve(moduleId);
-      }
-    } else if (strategy === SchemaStrategy.YamlOnly) {
-      result = this._loadAndResolve(moduleId);
-    }
-
-    if (result === null) {
-      throw new SchemaNotFoundError(moduleId);
-    }
-
-    this._modelCache.set(moduleId, result);
-    return result;
-  }
-
-  private _loadAndResolve(moduleId: string): [ResolvedSchema, ResolvedSchema] {
-    const cached = this._modelCache.get(moduleId);
-    if (cached) return cached;
-    const sd = this.load(moduleId);
-    const result = this.resolve(sd);
-    this._modelCache.set(moduleId, result);
-    return result;
-  }
-
-  private _wrapNative(
-    moduleId: string,
-    inputSchema: TSchema,
-    outputSchema: TSchema,
-  ): [ResolvedSchema, ResolvedSchema] {
-    const inputRs: ResolvedSchema = {
-      jsonSchema: inputSchema as unknown as Record<string, unknown>,
-      schema: inputSchema,
-      moduleId,
-      direction: 'input',
-    };
-    const outputRs: ResolvedSchema = {
-      jsonSchema: outputSchema as unknown as Record<string, unknown>,
-      schema: outputSchema,
-      moduleId,
-      direction: 'output',
-    };
-    return [inputRs, outputRs];
-  }
-
-  clearCache(): void {
-    this._schemaCache.clear();
-    this._modelCache.clear();
-    this._resolver.clearCache();
-  }
-}
-
-/**
- * Convert a JSON Schema dict to a TypeBox TSchema.
- * Since TypeBox schemas ARE JSON Schema, this wraps the raw object
- * so it can be used with Value.Check/Value.Decode.
- */
-export function jsonSchemaToTypeBox(schema: Record<string, unknown>): TSchema {
-  const schemaType = schema['type'] as string | undefined;
-
-  let result: TSchema;
-  if (schemaType === 'object') result = convertObjectSchema(schema);
-  else if (schemaType === 'array') result = convertArraySchema(schema);
-  else if (schemaType === 'string') result = convertStringSchema(schema);
-  else if (schemaType === 'integer') result = convertNumericSchema(schema, Type.Integer);
-  else if (schemaType === 'number') result = convertNumericSchema(schema, Type.Number);
-  else if (schemaType === 'boolean') result = Type.Boolean();
-  else if (schemaType === 'null') result = Type.Null();
-  else result = convertCombinatorSchema(schema);
-
-  // Preserve JSON Schema metadata
-  if (typeof schema['description'] === 'string') result['description'] = schema['description'];
-  if (typeof schema['title'] === 'string') result['title'] = schema['title'];
-
-  return result;
-}
-
-function convertObjectSchema(schema: Record<string, unknown>): TSchema {
-  const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined;
-  const required = new Set((schema['required'] as string[]) ?? []);
-
-  if (properties) {
-    const typeboxProps: Record<string, TSchema> = {};
-    for (const [name, propSchema] of Object.entries(properties)) {
-      const propType = jsonSchemaToTypeBox(propSchema);
-      typeboxProps[name] = required.has(name) ? propType : Type.Optional(propType);
-    }
-    return Type.Object(typeboxProps);
-  }
-  return Type.Record(Type.String(), Type.Unknown());
-}
-
-function convertArraySchema(schema: Record<string, unknown>): TSchema {
-  const items = schema['items'] as Record<string, unknown> | undefined;
-  return items ? Type.Array(jsonSchemaToTypeBox(items)) : Type.Array(Type.Unknown());
-}
-
-function convertStringSchema(schema: Record<string, unknown>): TSchema {
-  const opts: Record<string, unknown> = {};
-  for (const key of ['minLength', 'maxLength', 'pattern', 'format']) {
-    if (key in schema) opts[key] = schema[key];
-  }
-  return Type.String(opts);
-}
-
-function convertNumericSchema(
-  schema: Record<string, unknown>,
-  factory: (opts?: Record<string, unknown>) => TSchema,
-): TSchema {
-  const opts: Record<string, unknown> = {};
-  for (const key of ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf']) {
-    if (key in schema) opts[key] = schema[key];
-  }
-  return factory(opts);
-}
-
-function convertCombinatorSchema(schema: Record<string, unknown>): TSchema {
-  if ('enum' in schema) {
-    const values = schema['enum'] as unknown[];
-    return Type.Union(values.map((v) =>
-      v === null ? Type.Null() : Type.Literal(v as string | number | boolean),
-    ));
-  }
-  if ('const' in schema) {
-    const value = schema['const'];
-    return value === null ? Type.Null() : Type.Literal(value as string | number | boolean);
-  }
-  if ('oneOf' in schema) {
-    return Type.Union((schema['oneOf'] as Record<string, unknown>[]).map(jsonSchemaToTypeBox));
-  }
-  if ('anyOf' in schema) {
-    return Type.Union((schema['anyOf'] as Record<string, unknown>[]).map(jsonSchemaToTypeBox));
-  }
-  if ('allOf' in schema) {
-    return Type.Intersect((schema['allOf'] as Record<string, unknown>[]).map(jsonSchemaToTypeBox));
-  }
-  return Type.Unknown();
-}

package/src/schema/ref-resolver.ts

@@ -1,244 +0,0 @@
-/**
- * $ref resolution for JSON Schema documents following Algorithm A05.
- */
-
-import { readFileSync, existsSync } from 'node:fs';
-import { resolve, dirname, join } from 'node:path';
-import yaml from 'js-yaml';
-import { SchemaCircularRefError, SchemaNotFoundError, SchemaParseError } from '../errors.js';
-import { deepCopy } from '../utils/index.js';
-
-const INLINE_SENTINEL = '__inline__';
-
-export class RefResolver {
-  private _schemasDir: string;
-  private _maxDepth: number;
-  private _fileCache: Map<string, Record<string, unknown>> = new Map();
-
-  constructor(schemasDir: string, maxDepth: number = 32) {
-    this._schemasDir = resolve(schemasDir);
-    this._maxDepth = maxDepth;
-  }
-
-  resolve(schema: Record<string, unknown>, currentFile?: string | null): Record<string, unknown> {
-    const result = deepCopy(schema);
-    this._fileCache.set(INLINE_SENTINEL, result);
-    try {
-      this._resolveNode(result, currentFile ?? null, new Set(), 0);
-    } finally {
-      this._fileCache.delete(INLINE_SENTINEL);
-    }
-    return result;
-  }
-
-  resolveRef(
-    refString: string,
-    currentFile: string | null,
-    visitedRefs?: Set<string>,
-    depth: number = 0,
-    siblingKeys?: Record<string, unknown> | null,
-  ): unknown {
-    const visited = visitedRefs ?? new Set<string>();
-
-    if (visited.has(refString)) {
-      throw new SchemaCircularRefError(refString);
-    }
-
-    if (depth >= this._maxDepth) {
-      throw new SchemaCircularRefError(
-        `Maximum reference depth ${this._maxDepth} exceeded resolving: ${refString}`,
-      );
-    }
-
-    visited.add(refString);
-
-    const [filePath, jsonPointer] = this._parseRef(refString, currentFile);
-    const document = this._loadFile(filePath);
-    const target = this._resolveJsonPointer(document, jsonPointer, refString);
-
-    let result: unknown = deepCopy(target);
-
-    if (siblingKeys && typeof result === 'object' && result !== null && !Array.isArray(result)) {
-      Object.assign(result as Record<string, unknown>, siblingKeys);
-    }
-
-    const effectiveFile = filePath === INLINE_SENTINEL ? currentFile : filePath;
-
-    if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
-      const resultObj = result as Record<string, unknown>;
-      if ('$ref' in resultObj) {
-        const nestedRef = resultObj['$ref'] as string;
-        delete resultObj['$ref'];
-        const nestedSiblings = Object.keys(resultObj).length > 0 ? { ...resultObj } : null;
-        result = this.resolveRef(nestedRef, effectiveFile, visited, depth + 1, nestedSiblings);
-      }
-    }
-
-    this._resolveNode(result, effectiveFile, visited, depth + 1);
-    return result;
-  }
-
-  private _resolveNode(
-    node: unknown,
-    currentFile: string | null,
-    visitedRefs: Set<string>,
-    depth: number,
-  ): unknown {
-    if (typeof node === 'object' && node !== null && !Array.isArray(node)) {
-      const nodeObj = node as Record<string, unknown>;
-      if ('$ref' in nodeObj) {
-        const refString = nodeObj['$ref'] as string;
-        const siblingKeys: Record<string, unknown> = {};
-        for (const [k, v] of Object.entries(nodeObj)) {
-          if (k !== '$ref') siblingKeys[k] = v;
-        }
-        const resolved = this.resolveRef(
-          refString,
-          currentFile,
-          new Set(visitedRefs),
-          depth,
-          Object.keys(siblingKeys).length > 0 ? siblingKeys : null,
-        );
-        // Clear and replace
-        for (const key of Object.keys(nodeObj)) delete nodeObj[key];
-        if (typeof resolved === 'object' && resolved !== null && !Array.isArray(resolved)) {
-          Object.assign(nodeObj, resolved as Record<string, unknown>);
-        } else {
-          return resolved;
-        }
-      } else {
-        for (const key of Object.keys(nodeObj)) {
-          const result = this._resolveNode(nodeObj[key], currentFile, visitedRefs, depth);
-          if (result !== nodeObj[key]) {
-            nodeObj[key] = result;
-          }
-        }
-      }
-    } else if (Array.isArray(node)) {
-      for (let i = 0; i < node.length; i++) {
-        const result = this._resolveNode(node[i], currentFile, visitedRefs, depth);
-        if (result !== node[i]) {
-          node[i] = result;
-        }
-      }
-    }
-    return node;
-  }
-
-  private _parseRef(refString: string, currentFile: string | null): [string, string] {
-    if (refString.startsWith('#')) {
-      const pointer = refString.slice(1);
-      if (currentFile) return [currentFile, pointer];
-      return [INLINE_SENTINEL, pointer];
-    }
-
-    if (refString.startsWith('apcore://')) {
-      return this._convertCanonicalToPath(refString);
-    }
-
-    if (refString.includes('#')) {
-      const [filePart, pointer] = refString.split('#', 2);
-      const base = currentFile ? dirname(currentFile) : this._schemasDir;
-      const resolvedPath = resolve(base, filePart);
-      this._assertWithinSchemasDir(resolvedPath, refString);
-      return [resolvedPath, pointer];
-    }
-
-    const base = currentFile ? dirname(currentFile) : this._schemasDir;
-    const resolvedPath = resolve(base, refString);
-    this._assertWithinSchemasDir(resolvedPath, refString);
-    return [resolvedPath, ''];
-  }
-
-  private _assertWithinSchemasDir(resolvedPath: string, refString: string): void {
-    if (!resolvedPath.startsWith(this._schemasDir + '/') && resolvedPath !== this._schemasDir) {
-      throw new SchemaNotFoundError(
-        `Reference '${refString}' resolves outside schemas directory`,
-      );
-    }
-  }
-
-  private _convertCanonicalToPath(uri: string): [string, string] {
-    const remainder = uri.slice('apcore://'.length);
-    const parts = remainder.split('/');
-    const canonicalId = parts[0];
-    const pointerParts = parts.slice(1);
-
-    const fileRel = canonicalId.replace(/\./g, '/') + '.schema.yaml';
-    const filePath = resolve(this._schemasDir, fileRel);
-
-    const pointer = pointerParts.length > 0 ? '/' + pointerParts.join('/') : '';
-    return [filePath, pointer];
-  }
-
-  private _resolveJsonPointer(document: unknown, pointer: string, refString: string): unknown {
-    if (!pointer) return document;
-
-    let segments = pointer.split('/');
-    if (segments.length > 0 && segments[0] === '') {
-      segments = segments.slice(1);
-    }
-
-    let current = document;
-    for (const rawSegment of segments) {
-      const segment = rawSegment.replace(/~1/g, '/').replace(/~0/g, '~');
-      if (typeof current === 'object' && current !== null && !Array.isArray(current)) {
-        const obj = current as Record<string, unknown>;
-        if (segment in obj) {
-          current = obj[segment];
-        } else {
-          throw new SchemaNotFoundError(`${refString} (segment '${segment}' not found)`);
-        }
-      } else {
-        throw new SchemaNotFoundError(`${refString} (segment '${segment}' not found)`);
-      }
-    }
-    return current;
-  }
-
-  private _loadFile(filePath: string): Record<string, unknown> {
-    if (filePath === INLINE_SENTINEL) {
-      return this._fileCache.get(INLINE_SENTINEL) ?? {};
-    }
-
-    const resolved = resolve(filePath);
-    const cached = this._fileCache.get(resolved);
-    if (cached !== undefined) return cached;
-
-    if (!existsSync(resolved)) {
-      throw new SchemaNotFoundError(resolved);
-    }
-
-    const content = readFileSync(resolved, 'utf-8');
-    if (!content.trim()) {
-      this._fileCache.set(resolved, {});
-      return {};
-    }
-
-    let parsed: unknown;
-    try {
-      parsed = yaml.load(content);
-    } catch (e) {
-      throw new SchemaParseError(`Invalid YAML in ${resolved}: ${e}`);
-    }
-
-    if (parsed === null || parsed === undefined) {
-      this._fileCache.set(resolved, {});
-      return {};
-    }
-
-    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-      throw new SchemaParseError(
-        `Schema file ${resolved} must be a YAML mapping, got ${typeof parsed}`,
-      );
-    }
-
-    const result = parsed as Record<string, unknown>;
-    this._fileCache.set(resolved, result);
-    return result;
-  }
-
-  clearCache(): void {
-    this._fileCache.clear();
-  }
-}

package/src/schema/strict.ts

@@ -1,136 +0,0 @@
-/**
- * Strict mode conversion for JSON Schemas (Algorithm A23).
- */
-
-import { deepCopy } from '../utils/index.js';
-
-export function toStrictSchema(schema: Record<string, unknown>): Record<string, unknown> {
-  const result = deepCopy(schema);
-  stripExtensions(result);
-  convertToStrict(result);
-  return result;
-}
-
-export function applyLlmDescriptions(node: unknown): void {
-  if (typeof node !== 'object' || node === null || Array.isArray(node)) return;
-
-  const obj = node as Record<string, unknown>;
-  if ('x-llm-description' in obj) {
-    obj['description'] = obj['x-llm-description'];
-  }
-
-  if ('properties' in obj && typeof obj['properties'] === 'object' && obj['properties'] !== null) {
-    for (const prop of Object.values(obj['properties'] as Record<string, unknown>)) {
-      applyLlmDescriptions(prop);
-    }
-  }
-  if ('items' in obj && typeof obj['items'] === 'object') {
-    applyLlmDescriptions(obj['items']);
-  }
-  for (const keyword of ['oneOf', 'anyOf', 'allOf']) {
-    if (keyword in obj && Array.isArray(obj[keyword])) {
-      for (const sub of obj[keyword] as unknown[]) {
-        applyLlmDescriptions(sub);
-      }
-    }
-  }
-  for (const defsKey of ['definitions', '$defs']) {
-    if (defsKey in obj && typeof obj[defsKey] === 'object' && obj[defsKey] !== null) {
-      for (const defn of Object.values(obj[defsKey] as Record<string, unknown>)) {
-        applyLlmDescriptions(defn);
-      }
-    }
-  }
-}
-
-export function stripExtensions(node: unknown): void {
-  if (typeof node !== 'object' || node === null || Array.isArray(node)) return;
-
-  const obj = node as Record<string, unknown>;
-  const keysToRemove = Object.keys(obj).filter(
-    (k) => (typeof k === 'string' && k.startsWith('x-')) || k === 'default',
-  );
-  for (const k of keysToRemove) {
-    delete obj[k];
-  }
-
-  for (const value of Object.values(obj)) {
-    if (typeof value === 'object' && value !== null) {
-      if (Array.isArray(value)) {
-        for (const item of value) {
-          if (typeof item === 'object' && item !== null) {
-            stripExtensions(item);
-          }
-        }
-      } else {
-        stripExtensions(value);
-      }
-    }
-  }
-}
-
-function convertToStrict(node: unknown): void {
-  if (typeof node !== 'object' || node === null || Array.isArray(node)) return;
-
-  const obj = node as Record<string, unknown>;
-
-  if (obj['type'] === 'object' && 'properties' in obj) {
-    obj['additionalProperties'] = false;
-    const existingRequired = new Set(
-      Array.isArray(obj['required']) ? (obj['required'] as string[]) : [],
-    );
-    const properties = obj['properties'] as Record<string, unknown>;
-    const allNames = Object.keys(properties);
-    const optionalNames = allNames.filter((n) => !existingRequired.has(n));
-
-    for (const name of optionalNames) {
-      const prop = properties[name] as Record<string, unknown>;
-      if ('type' in prop) {
-        if (typeof prop['type'] === 'string') {
-          prop['type'] = [prop['type'], 'null'];
-        } else if (Array.isArray(prop['type'])) {
-          if (!(prop['type'] as string[]).includes('null')) {
-            (prop['type'] as string[]).push('null');
-          }
-        }
-      } else if ('oneOf' in prop && Array.isArray(prop['oneOf'])) {
-        const variants = prop['oneOf'] as Record<string, unknown>[];
-        if (!variants.some((v) => v['type'] === 'null')) {
-          variants.push({ type: 'null' });
-        }
-      } else if ('anyOf' in prop && Array.isArray(prop['anyOf'])) {
-        const variants = prop['anyOf'] as Record<string, unknown>[];
-        if (!variants.some((v) => v['type'] === 'null')) {
-          variants.push({ type: 'null' });
-        }
-      } else {
-        properties[name] = { oneOf: [prop, { type: 'null' }] };
-      }
-    }
-
-    obj['required'] = [...allNames].sort();
-  }
-
-  if ('properties' in obj && typeof obj['properties'] === 'object' && obj['properties'] !== null) {
-    for (const prop of Object.values(obj['properties'] as Record<string, unknown>)) {
-      convertToStrict(prop);
-    }
-  }
-  if ('items' in obj && typeof obj['items'] === 'object') {
-    convertToStrict(obj['items']);
-  }
-  for (const keyword of ['oneOf', 'anyOf', 'allOf']) {
-    if (keyword in obj && Array.isArray(obj[keyword])) {
-      for (const sub of obj[keyword] as unknown[]) {
-        convertToStrict(sub);
-      }
-    }
-  }
-  for (const defsKey of ['definitions', '$defs']) {
-    if (defsKey in obj && typeof obj[defsKey] === 'object' && obj[defsKey] !== null) {
-      for (const defn of Object.values(obj[defsKey] as Record<string, unknown>)) {
-        convertToStrict(defn);
-      }
-    }
-  }
-}