apcore-js 0.4.0 → 0.6.0

package/src/observability/tracing.ts

@@ -1,188 +0,0 @@
-/**
- * Tracing system: Span, SpanExporter implementations, and TracingMiddleware.
- */
-
-import { randomBytes } from 'node:crypto';
-import type { Context } from '../context.js';
-import { Middleware } from '../middleware/base.js';
-
-export interface Span {
-  traceId: string;
-  name: string;
-  startTime: number;
-  spanId: string;
-  parentSpanId: string | null;
-  attributes: Record<string, unknown>;
-  endTime: number | null;
-  status: string;
-  events: Array<Record<string, unknown>>;
-}
-
-export function createSpan(options: {
-  traceId: string;
-  name: string;
-  startTime: number;
-  spanId?: string;
-  parentSpanId?: string | null;
-  attributes?: Record<string, unknown>;
-}): Span {
-  return {
-    traceId: options.traceId,
-    name: options.name,
-    startTime: options.startTime,
-    spanId: options.spanId ?? randomBytes(8).toString('hex'),
-    parentSpanId: options.parentSpanId ?? null,
-    attributes: options.attributes ?? {},
-    endTime: null,
-    status: 'ok',
-    events: [],
-  };
-}
-
-export interface SpanExporter {
-  export(span: Span): void;
-}
-
-export class StdoutExporter implements SpanExporter {
-  export(span: Span): void {
-    process.stdout.write(JSON.stringify(span) + '\n');
-  }
-}
-
-export class InMemoryExporter implements SpanExporter {
-  private _spans: Span[] = [];
-  private _maxSpans: number;
-
-  constructor(maxSpans: number = 10_000) {
-    this._maxSpans = maxSpans;
-  }
-
-  export(span: Span): void {
-    if (this._spans.length >= this._maxSpans) {
-      // Drop oldest half to amortize the cost instead of O(n) shift per insert
-      this._spans = this._spans.slice(Math.floor(this._maxSpans / 2));
-    }
-    this._spans.push(span);
-  }
-
-  getSpans(): Span[] {
-    return [...this._spans];
-  }
-
-  clear(): void {
-    this._spans = [];
-  }
-}
-
-const VALID_STRATEGIES = new Set(['full', 'proportional', 'error_first', 'off']);
-
-export class TracingMiddleware extends Middleware {
-  private _exporter: SpanExporter;
-  private _samplingRate: number;
-  private _samplingStrategy: string;
-
-  constructor(
-    exporter: SpanExporter,
-    samplingRate: number = 1.0,
-    samplingStrategy: string = 'full',
-  ) {
-    super();
-    if (samplingRate < 0.0 || samplingRate > 1.0) {
-      throw new Error(`sampling_rate must be between 0.0 and 1.0, got ${samplingRate}`);
-    }
-    if (!VALID_STRATEGIES.has(samplingStrategy)) {
-      throw new Error(`sampling_strategy must be one of ${[...VALID_STRATEGIES].join(', ')}, got '${samplingStrategy}'`);
-    }
-    this._exporter = exporter;
-    this._samplingRate = samplingRate;
-    this._samplingStrategy = samplingStrategy;
-  }
-
-  private _shouldSample(context: Context): boolean {
-    const existing = context.data['_tracing_sampled'];
-    if (typeof existing === 'boolean') return existing;
-
-    let decision: boolean;
-    if (this._samplingStrategy === 'full') {
-      decision = true;
-    } else if (this._samplingStrategy === 'off') {
-      decision = false;
-    } else {
-      decision = Math.random() < this._samplingRate;
-    }
-
-    context.data['_tracing_sampled'] = decision;
-    return decision;
-  }
-
-  override before(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    context: Context,
-  ): null {
-    this._shouldSample(context);
-
-    const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
-    context.data['_tracing_spans'] = spansStack;
-    const parentSpanId = spansStack.length > 0 ? spansStack[spansStack.length - 1].spanId : null;
-
-    const span = createSpan({
-      traceId: context.traceId,
-      name: 'apcore.module.execute',
-      startTime: performance.now(),
-      parentSpanId,
-      attributes: {
-        moduleId,
-        method: 'execute',
-        callerId: context.callerId,
-      },
-    });
-    spansStack.push(span);
-    return null;
-  }
-
-  override after(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    _output: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
-    if (spansStack.length === 0) return null;
-
-    const span = spansStack.pop()!;
-    span.endTime = performance.now();
-    span.status = 'ok';
-    span.attributes['duration_ms'] = span.endTime - span.startTime;
-    span.attributes['success'] = true;
-
-    if (context.data['_tracing_sampled']) {
-      this._exporter.export(span);
-    }
-    return null;
-  }
-
-  override onError(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    error: Error,
-    context: Context,
-  ): null {
-    const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
-    if (spansStack.length === 0) return null;
-
-    const span = spansStack.pop()!;
-    span.endTime = performance.now();
-    span.status = 'error';
-    span.attributes['duration_ms'] = span.endTime - span.startTime;
-    span.attributes['success'] = false;
-    span.attributes['error_code'] = (error as unknown as Record<string, unknown>)['code'] ?? error.constructor.name;
-
-    const shouldExport =
-      this._samplingStrategy === 'error_first' || context.data['_tracing_sampled'];
-    if (shouldExport) {
-      this._exporter.export(span);
-    }
-    return null;
-  }
-}

package/src/registry/dependencies.ts

@@ -1,99 +0,0 @@
-/**
- * Dependency resolution via Kahn's topological sort.
- */
-
-import { CircularDependencyError, ModuleLoadError } from '../errors.js';
-import type { DependencyInfo } from './types.js';
-
-export function resolveDependencies(
-  modules: Array<[string, DependencyInfo[]]>,
-  knownIds?: Set<string> | null,
-): string[] {
-  if (modules.length === 0) return [];
-
-  const ids = knownIds ?? new Set(modules.map(([id]) => id));
-
-  // Build graph and in-degree
-  const graph = new Map<string, Set<string>>();
-  const inDegree = new Map<string, number>();
-
-  for (const [modId] of modules) {
-    inDegree.set(modId, 0);
-  }
-
-  for (const [moduleId, deps] of modules) {
-    for (const dep of deps) {
-      if (!ids.has(dep.moduleId)) {
-        if (dep.optional) continue;
-        throw new ModuleLoadError(moduleId, `Required dependency '${dep.moduleId}' not found`);
-      }
-      if (!graph.has(dep.moduleId)) graph.set(dep.moduleId, new Set());
-      graph.get(dep.moduleId)!.add(moduleId);
-      inDegree.set(moduleId, (inDegree.get(moduleId) ?? 0) + 1);
-    }
-  }
-
-  // Initialize queue with zero-in-degree nodes (sorted for determinism)
-  const queue: string[] = [...inDegree.entries()]
-    .filter(([, deg]) => deg === 0)
-    .map(([id]) => id)
-    .sort();
-
-  const loadOrder: string[] = [];
-  while (queue.length > 0) {
-    const modId = queue.shift()!;
-    loadOrder.push(modId);
-    const dependents = graph.get(modId);
-    if (dependents) {
-      for (const dependent of [...dependents].sort()) {
-        const newDeg = (inDegree.get(dependent) ?? 1) - 1;
-        inDegree.set(dependent, newDeg);
-        if (newDeg === 0) {
-          queue.push(dependent);
-        }
-      }
-    }
-  }
-
-  // Check for cycles
-  if (loadOrder.length < modules.length) {
-    const ordered = new Set(loadOrder);
-    const remaining = new Set(modules.filter(([id]) => !ordered.has(id)).map(([id]) => id));
-    const cyclePath = extractCycle(modules, remaining);
-    throw new CircularDependencyError(cyclePath);
-  }
-
-  return loadOrder;
-}
-
-function extractCycle(
-  modules: Array<[string, DependencyInfo[]]>,
-  remaining: Set<string>,
-): string[] {
-  const depMap = new Map<string, string[]>();
-  for (const [modId, deps] of modules) {
-    if (remaining.has(modId)) {
-      depMap.set(modId, deps.filter((d) => remaining.has(d.moduleId)).map((d) => d.moduleId));
-    }
-  }
-
-  const start = remaining.values().next().value as string;
-  const visited: string[] = [start];
-  const visitedSet = new Set([start]);
-  let current = start;
-
-  while (true) {
-    const nexts = depMap.get(current) ?? [];
-    if (nexts.length === 0) break;
-    const nxt = nexts[0];
-    if (visitedSet.has(nxt)) {
-      const idx = visited.indexOf(nxt);
-      return [...visited.slice(idx), nxt];
-    }
-    visited.push(nxt);
-    visitedSet.add(nxt);
-    current = nxt;
-  }
-
-  return [...remaining, remaining.values().next().value as string];
-}

package/src/registry/entry-point.ts

@@ -1,64 +0,0 @@
-/**
- * Entry point resolution for discovered module files.
- */
-
-import { ModuleLoadError } from '../errors.js';
-import { validateModule } from './validation.js';
-
-export function snakeToPascal(name: string): string {
-  if (!name) return '';
-  return name.split('_').map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join('');
-}
-
-function isModuleClass(obj: unknown): boolean {
-  if (typeof obj !== 'object' || obj === null) return false;
-  const record = obj as Record<string, unknown>;
-  return (
-    record['inputSchema'] != null &&
-    typeof record['inputSchema'] === 'object' &&
-    record['outputSchema'] != null &&
-    typeof record['outputSchema'] === 'object' &&
-    typeof record['description'] === 'string' &&
-    typeof record['execute'] === 'function'
-  );
-}
-
-export async function resolveEntryPoint(
-  filePath: string,
-  meta?: Record<string, unknown> | null,
-): Promise<unknown> {
-  let loaded: Record<string, unknown>;
-  try {
-    loaded = await import(filePath);
-  } catch (e) {
-    throw new ModuleLoadError(filePath, `Failed to import module: ${e}`);
-  }
-
-  // Meta override mode
-  if (meta && 'entry_point' in meta) {
-    const className = (meta['entry_point'] as string).split(':').pop()!;
-    const cls = loaded[className];
-    if (cls == null) {
-      throw new ModuleLoadError(filePath, `Entry point class '${className}' not found`);
-    }
-    return cls;
-  }
-
-  // Auto-infer: look for default export first, then named exports
-  if (loaded['default'] && isModuleClass(loaded['default'])) {
-    return loaded['default'];
-  }
-
-  const candidates: unknown[] = [];
-  for (const [, value] of Object.entries(loaded)) {
-    if (isModuleClass(value)) {
-      candidates.push(value);
-    }
-  }
-
-  if (candidates.length === 1) return candidates[0];
-  if (candidates.length === 0) {
-    throw new ModuleLoadError(filePath, 'No Module subclass found in file');
-  }
-  throw new ModuleLoadError(filePath, 'Ambiguous entry point: multiple Module subclasses found');
-}

package/src/registry/metadata.ts

@@ -1,111 +0,0 @@
-/**
- * Metadata and ID map loading for the registry system.
- */
-
-import { readFileSync, existsSync } from 'node:fs';
-import yaml from 'js-yaml';
-import { ConfigError, ConfigNotFoundError } from '../errors.js';
-import type { DependencyInfo } from './types.js';
-
-export function loadMetadata(metaPath: string): Record<string, unknown> {
-  if (!existsSync(metaPath)) return {};
-
-  const content = readFileSync(metaPath, 'utf-8');
-  let parsed: unknown;
-  try {
-    parsed = yaml.load(content);
-  } catch (e) {
-    throw new ConfigError(`Invalid YAML in metadata file: ${metaPath}`);
-  }
-
-  if (parsed === null || parsed === undefined) return {};
-  if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new ConfigError(`Metadata file must be a YAML mapping: ${metaPath}`);
-  }
-
-  return parsed as Record<string, unknown>;
-}
-
-export function parseDependencies(depsRaw: Array<Record<string, unknown>>): DependencyInfo[] {
-  if (!depsRaw || depsRaw.length === 0) return [];
-
-  const result: DependencyInfo[] = [];
-  for (const dep of depsRaw) {
-    const moduleId = dep['module_id'] as string | undefined;
-    if (!moduleId) {
-      console.warn(`[apcore:metadata] Dependency entry missing 'module_id', skipping`);
-      continue;
-    }
-    result.push({
-      moduleId,
-      version: (dep['version'] as string) ?? null,
-      optional: (dep['optional'] as boolean) ?? false,
-    });
-  }
-  return result;
-}
-
-export function mergeModuleMetadata(
-  moduleObj: Record<string, unknown>,
-  meta: Record<string, unknown>,
-): Record<string, unknown> {
-  const codeDesc = (moduleObj['description'] as string) ?? '';
-  const codeName = (moduleObj['name'] as string) ?? null;
-  const codeTags = (moduleObj['tags'] as string[]) ?? [];
-  const codeVersion = (moduleObj['version'] as string) ?? '1.0.0';
-  const codeAnnotations = moduleObj['annotations'] ?? null;
-  const codeExamples = (moduleObj['examples'] as unknown[]) ?? [];
-  const codeMetadata = (moduleObj['metadata'] as Record<string, unknown>) ?? {};
-  const codeDocs = (moduleObj['documentation'] as string) ?? null;
-
-  const yamlMetadata = (meta['metadata'] as Record<string, unknown>) ?? {};
-  const mergedMetadata = { ...codeMetadata, ...yamlMetadata };
-
-  return {
-    description: (meta['description'] as string) || codeDesc,
-    name: (meta['name'] as string) || codeName,
-    tags: meta['tags'] != null ? meta['tags'] : codeTags || [],
-    version: (meta['version'] as string) || codeVersion,
-    annotations: meta['annotations'] != null ? meta['annotations'] : codeAnnotations,
-    examples: meta['examples'] != null ? meta['examples'] : codeExamples || [],
-    metadata: mergedMetadata,
-    documentation: (meta['documentation'] as string) || codeDocs,
-  };
-}
-
-export function loadIdMap(idMapPath: string): Record<string, Record<string, unknown>> {
-  if (!existsSync(idMapPath)) {
-    throw new ConfigNotFoundError(idMapPath);
-  }
-
-  const content = readFileSync(idMapPath, 'utf-8');
-  let parsed: unknown;
-  try {
-    parsed = yaml.load(content);
-  } catch (e) {
-    throw new ConfigError(`Invalid YAML in ID map file: ${idMapPath}`);
-  }
-
-  if (typeof parsed !== 'object' || parsed === null || !('mappings' in (parsed as Record<string, unknown>))) {
-    throw new ConfigError("ID map must contain a 'mappings' list");
-  }
-
-  const mappings = (parsed as Record<string, unknown>)['mappings'];
-  if (!Array.isArray(mappings)) {
-    throw new ConfigError("ID map must contain a 'mappings' list");
-  }
-
-  const result: Record<string, Record<string, unknown>> = {};
-  for (const entry of mappings) {
-    const filePath = (entry as Record<string, unknown>)['file'] as string;
-    if (!filePath) {
-      console.warn(`[apcore:metadata] ID map entry missing 'file' field, skipping`);
-      continue;
-    }
-    result[filePath] = {
-      id: ((entry as Record<string, unknown>)['id'] as string) ?? filePath,
-      class: (entry as Record<string, unknown>)['class'] ?? null,
-    };
-  }
-  return result;
-}