apcore-js 0.4.0 → 0.6.0

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);
-      }
-    }
-  }
-}

package/src/schema/types.ts

@@ -1,73 +0,0 @@
-/**
- * Schema type definitions and data structures for the apcore schema system.
- */
-
-import type { TSchema } from '@sinclair/typebox';
-import { SchemaValidationError } from '../errors.js';
-
-export enum SchemaStrategy {
-  YamlFirst = 'yaml_first',
-  NativeFirst = 'native_first',
-  YamlOnly = 'yaml_only',
-}
-
-export enum ExportProfile {
-  MCP = 'mcp',
-  OpenAI = 'openai',
-  Anthropic = 'anthropic',
-  Generic = 'generic',
-}
-
-export interface SchemaDefinition {
-  moduleId: string;
-  description: string;
-  inputSchema: Record<string, unknown>;
-  outputSchema: Record<string, unknown>;
-  errorSchema?: Record<string, unknown> | null;
-  definitions: Record<string, unknown>;
-  version: string;
-  documentation?: string | null;
-  schemaUrl?: string | null;
-}
-
-export interface ResolvedSchema {
-  jsonSchema: Record<string, unknown>;
-  schema: TSchema;
-  moduleId: string;
-  direction: string;
-}
-
-export interface SchemaValidationErrorDetail {
-  path: string;
-  message: string;
-  constraint?: string | null;
-  expected?: unknown;
-  actual?: unknown;
-}
-
-export interface SchemaValidationResult {
-  valid: boolean;
-  errors: SchemaValidationErrorDetail[];
-}
-
-export function validationResultToError(result: SchemaValidationResult): SchemaValidationError {
-  if (result.valid) {
-    throw new Error('Cannot convert valid result to error');
-  }
-  const errorDicts = result.errors.map((e) => ({
-    path: e.path,
-    message: e.message,
-    constraint: e.constraint ?? null,
-    expected: e.expected ?? null,
-    actual: e.actual ?? null,
-  }));
-  return new SchemaValidationError('Schema validation failed', errorDicts);
-}
-
-export interface LLMExtensions {
-  llmDescription?: string | null;
-  examples?: unknown[] | null;
-  sensitive: boolean;
-  constraints?: string | null;
-  deprecated?: Record<string, unknown> | null;
-}

package/src/schema/validator.ts

@@ -1,82 +0,0 @@
-/**
- * SchemaValidator — validates runtime data against TypeBox schemas.
- */
-
-import { type TSchema } from '@sinclair/typebox';
-import { Value, type ValueError } from '@sinclair/typebox/value';
-import type { SchemaValidationErrorDetail, SchemaValidationResult } from './types.js';
-import { validationResultToError } from './types.js';
-
-export class SchemaValidator {
-  private _coerceTypes: boolean;
-
-  constructor(coerceTypes: boolean = true) {
-    this._coerceTypes = coerceTypes;
-  }
-
-  validate(data: Record<string, unknown>, schema: TSchema): SchemaValidationResult {
-    if (this._coerceTypes) {
-      try {
-        Value.Decode(schema, data);
-        return { valid: true, errors: [] };
-      } catch {
-        return { valid: false, errors: this._collectErrors(schema, data) };
-      }
-    }
-
-    if (Value.Check(schema, data)) {
-      return { valid: true, errors: [] };
-    }
-    return { valid: false, errors: this._collectErrors(schema, data) };
-  }
-
-  validateInput(data: Record<string, unknown>, schema: TSchema): Record<string, unknown> {
-    return this._validateAndReturn(data, schema);
-  }
-
-  validateOutput(data: Record<string, unknown>, schema: TSchema): Record<string, unknown> {
-    return this._validateAndReturn(data, schema);
-  }
-
-  private _validateAndReturn(data: Record<string, unknown>, schema: TSchema): Record<string, unknown> {
-    if (this._coerceTypes) {
-      try {
-        return Value.Decode(schema, data) as Record<string, unknown>;
-      } catch {
-        const result: SchemaValidationResult = {
-          valid: false,
-          errors: this._collectErrors(schema, data),
-        };
-        throw validationResultToError(result);
-      }
-    }
-
-    if (Value.Check(schema, data)) {
-      return data;
-    }
-
-    const result: SchemaValidationResult = {
-      valid: false,
-      errors: this._collectErrors(schema, data),
-    };
-    throw validationResultToError(result);
-  }
-
-  private _collectErrors(schema: TSchema, data: unknown): SchemaValidationErrorDetail[] {
-    const errors: SchemaValidationErrorDetail[] = [];
-    for (const error of Value.Errors(schema, data)) {
-      errors.push(this._typeboxErrorToDetail(error));
-    }
-    return errors;
-  }
-
-  private _typeboxErrorToDetail(error: ValueError): SchemaValidationErrorDetail {
-    return {
-      path: error.path || '/',
-      message: error.message,
-      constraint: String(error.type),
-      expected: error.schema,
-      actual: error.value,
-    };
-  }
-}

package/src/utils/index.ts

@@ -1,5 +0,0 @@
-export { matchPattern } from './pattern.js';
-
-export function deepCopy<T>(obj: T): T {
-  return JSON.parse(JSON.stringify(obj));
-}

package/src/utils/pattern.ts

@@ -1,30 +0,0 @@
-/**
- * Wildcard pattern matching for module IDs (Algorithm A08).
- */
-
-export function matchPattern(pattern: string, moduleId: string): boolean {
-  if (pattern === '*') return true;
-  if (!pattern.includes('*')) return pattern === moduleId;
-
-  const segments = pattern.split('*');
-  let pos = 0;
-
-  if (!pattern.startsWith('*')) {
-    if (!moduleId.startsWith(segments[0])) return false;
-    pos = segments[0].length;
-  }
-
-  for (let i = 1; i < segments.length; i++) {
-    const segment = segments[i];
-    if (!segment) continue;
-    const idx = moduleId.indexOf(segment, pos);
-    if (idx === -1) return false;
-    pos = idx + segment.length;
-  }
-
-  if (!pattern.endsWith('*')) {
-    if (!moduleId.endsWith(segments[segments.length - 1])) return false;
-  }
-
-  return true;
-}

package/tests/helpers.ts

@@ -1,30 +0,0 @@
-/**
- * Shared test fixtures and helpers.
- */
-
-import { Type } from '@sinclair/typebox';
-import { Context, createIdentity } from '../src/context.js';
-import { FunctionModule } from '../src/decorator.js';
-import { Registry } from '../src/registry/registry.js';
-
-export function createTestModule(options?: {
-  moduleId?: string;
-  description?: string;
-  execute?: (inputs: Record<string, unknown>, context: Context) => Record<string, unknown>;
-}): FunctionModule {
-  return new FunctionModule({
-    execute: options?.execute ?? ((inputs) => ({ echo: inputs['name'] ?? 'world' })),
-    moduleId: options?.moduleId ?? 'test.module',
-    inputSchema: Type.Object({ name: Type.Optional(Type.String()) }),
-    outputSchema: Type.Object({ echo: Type.String() }),
-    description: options?.description ?? 'A test module',
-  });
-}
-
-export function createTestRegistry(): Registry {
-  return new Registry();
-}
-
-export function createTestContext(executor?: unknown): Context {
-  return Context.create(executor, createIdentity('test-user'));
-}