apcore-js 0.1.0

package/src/schema/ref-resolver.ts

@@ -0,0 +1,235 @@
+/**
+ * $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';
+
+const INLINE_SENTINEL = '__inline__';
+
+function deepCopy<T>(obj: T): T {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+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;
+      return [resolve(base, filePart), pointer];
+    }
+
+    const base = currentFile ? dirname(currentFile) : this._schemasDir;
+    return [resolve(base, refString), ''];
+  }
+
+  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

@@ -0,0 +1,128 @@
+/**
+ * Strict mode conversion for JSON Schemas (Algorithm A23).
+ */
+
+function deepCopy<T>(obj: T): T {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+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 && '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 {
+        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

@@ -0,0 +1,73 @@
+/**
+ * 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

@@ -0,0 +1,82 @@
+/**
+ * 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

@@ -0,0 +1 @@
+export { matchPattern } from './pattern.js';

package/src/utils/pattern.ts

@@ -0,0 +1,30 @@
+/**
+ * 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

@@ -0,0 +1,30 @@
+/**
+ * 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'));
+}