apcore-js 0.4.0 → 0.6.0

package/tests/observability/test-metrics.test.ts

@@ -1,186 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { MetricsCollector, MetricsMiddleware } from '../../src/observability/metrics.js';
-import { Context } from '../../src/context.js';
-import { ModuleError } from '../../src/errors.js';
-
-describe('MetricsCollector', () => {
-  it('increments counters', () => {
-    const collector = new MetricsCollector();
-    collector.increment('test_counter', { method: 'GET' });
-    collector.increment('test_counter', { method: 'GET' });
-    const snap = collector.snapshot();
-    expect((snap['counters'] as Record<string, number>)['test_counter|method=GET']).toBe(2);
-  });
-
-  it('observes histogram values', () => {
-    const collector = new MetricsCollector();
-    collector.observe('test_hist', { module: 'a' }, 0.05);
-    collector.observe('test_hist', { module: 'a' }, 0.5);
-    const snap = collector.snapshot();
-    const hists = snap['histograms'] as Record<string, Record<string, number>>;
-    expect(hists['sums']['test_hist|module=a']).toBeCloseTo(0.55);
-    expect(hists['counts']['test_hist|module=a']).toBe(2);
-  });
-
-  it('convenience methods work', () => {
-    const collector = new MetricsCollector();
-    collector.incrementCalls('mod.a', 'success');
-    collector.incrementErrors('mod.a', 'TIMEOUT');
-    collector.observeDuration('mod.a', 0.1);
-
-    const snap = collector.snapshot();
-    const counters = snap['counters'] as Record<string, number>;
-    expect(counters['apcore_module_calls_total|module_id=mod.a,status=success']).toBe(1);
-    expect(counters['apcore_module_errors_total|error_code=TIMEOUT,module_id=mod.a']).toBe(1);
-  });
-
-  it('reset clears all data', () => {
-    const collector = new MetricsCollector();
-    collector.incrementCalls('mod.a', 'success');
-    collector.observeDuration('mod.a', 0.1);
-    collector.reset();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-
-  it('snapshot returns counters and histogram sub-keys', () => {
-    const collector = new MetricsCollector();
-    collector.increment('req_total', { status: '200' });
-    collector.observe('req_duration', { route: '/health' }, 0.01);
-    const snap = collector.snapshot();
-    expect(snap).toHaveProperty('counters');
-    expect(snap).toHaveProperty('histograms');
-    const hists = snap['histograms'] as Record<string, unknown>;
-    expect(hists).toHaveProperty('sums');
-    expect(hists).toHaveProperty('counts');
-    expect(hists).toHaveProperty('buckets');
-  });
-
-  it('exportPrometheus produces valid format', () => {
-    const collector = new MetricsCollector();
-    collector.incrementCalls('mod.a', 'success');
-    collector.observeDuration('mod.a', 0.05);
-    const output = collector.exportPrometheus();
-    expect(output).toContain('# HELP');
-    expect(output).toContain('# TYPE');
-    expect(output).toContain('apcore_module_calls_total');
-    expect(output).toContain('apcore_module_duration_seconds');
-  });
-
-  it('empty collector returns empty prometheus string', () => {
-    const collector = new MetricsCollector();
-    expect(collector.exportPrometheus()).toBe('');
-  });
-
-  it('accepts custom buckets and uses them for observations', () => {
-    const collector = new MetricsCollector([0.1, 0.5, 1.0]);
-    collector.observe('custom_hist', { op: 'read' }, 0.3);
-    const snap = collector.snapshot();
-    const hists = snap['histograms'] as Record<string, Record<string, number>>;
-    // value 0.3 falls in the 0.5 bucket but not 0.1
-    expect(hists['buckets']['custom_hist|op=read|0.1']).toBeUndefined();
-    expect(hists['buckets']['custom_hist|op=read|0.5']).toBe(1);
-    expect(hists['buckets']['custom_hist|op=read|Inf']).toBe(1);
-  });
-
-  it('exportPrometheus omits label braces when metric has no labels', () => {
-    const collector = new MetricsCollector();
-    // increment with empty labels so parseLabels receives '' and formatLabels receives {}
-    collector.increment('no_label_counter', {});
-    const output = collector.exportPrometheus();
-    expect(output).toContain('no_label_counter 1');
-    expect(output).not.toContain('no_label_counter{');
-  });
-});
-
-describe('MetricsMiddleware', () => {
-  it('records call metrics on success', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.after('mod.a', {}, { result: 'ok' }, ctx);
-
-    const snap = collector.snapshot();
-    const counters = snap['counters'] as Record<string, number>;
-    expect(counters['apcore_module_calls_total|module_id=mod.a,status=success']).toBe(1);
-  });
-
-  it('records error metrics on failure with plain Error', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.onError('mod.a', {}, new Error('boom'), ctx);
-
-    const snap = collector.snapshot();
-    const counters = snap['counters'] as Record<string, number>;
-    expect(counters['apcore_module_calls_total|module_id=mod.a,status=error']).toBe(1);
-    expect(counters['apcore_module_errors_total|error_code=Error,module_id=mod.a']).toBe(1);
-  });
-
-  it('records error code from ModuleError.code instead of constructor name', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = Context.create();
-
-    mw.before('mod.b', {}, ctx);
-    mw.onError('mod.b', {}, new ModuleError('CUSTOM_CODE', 'something went wrong'), ctx);
-
-    const snap = collector.snapshot();
-    const counters = snap['counters'] as Record<string, number>;
-    expect(counters['apcore_module_errors_total|error_code=CUSTOM_CODE,module_id=mod.b']).toBe(1);
-  });
-
-  it('after() returns null without recording metrics when starts is undefined', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = new Context('trace-id', null, [], null, null);
-
-    const result = mw.after('mod.a', {}, { result: 'ok' }, ctx);
-
-    expect(result).toBeNull();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-
-  it('after() returns null without recording metrics when starts array is empty', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = new Context('trace-id', null, [], null, null);
-    ctx.data['_metrics_starts'] = [];
-
-    const result = mw.after('mod.a', {}, { result: 'ok' }, ctx);
-
-    expect(result).toBeNull();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-
-  it('onError() returns null without recording metrics when starts is undefined', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = new Context('trace-id', null, [], null, null);
-
-    const result = mw.onError('mod.a', {}, new Error('boom'), ctx);
-
-    expect(result).toBeNull();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-
-  it('onError() returns null without recording metrics when starts array is empty', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = new Context('trace-id', null, [], null, null);
-    ctx.data['_metrics_starts'] = [];
-
-    const result = mw.onError('mod.a', {}, new Error('boom'), ctx);
-
-    expect(result).toBeNull();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-});

package/tests/observability/test-tracing.test.ts

@@ -1,131 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { Context } from '../../src/context.js';
-import {
-  createSpan,
-  InMemoryExporter,
-  StdoutExporter,
-  TracingMiddleware,
-} from '../../src/observability/tracing.js';
-
-describe('Span', () => {
-  it('createSpan creates span with defaults', () => {
-    const span = createSpan({
-      traceId: 'trace-1',
-      name: 'test.span',
-      startTime: 100,
-    });
-    expect(span.traceId).toBe('trace-1');
-    expect(span.name).toBe('test.span');
-    expect(span.startTime).toBe(100);
-    expect(span.spanId).toBeDefined();
-    expect(span.parentSpanId).toBeNull();
-    expect(span.status).toBe('ok');
-    expect(span.events).toEqual([]);
-  });
-});
-
-describe('InMemoryExporter', () => {
-  it('collects and retrieves spans', () => {
-    const exporter = new InMemoryExporter();
-    const span = createSpan({ traceId: 't1', name: 'test', startTime: 0 });
-    exporter.export(span);
-    expect(exporter.getSpans()).toHaveLength(1);
-    expect(exporter.getSpans()[0].traceId).toBe('t1');
-  });
-
-  it('respects max_spans limit', () => {
-    const exporter = new InMemoryExporter(3);
-    for (let i = 0; i < 5; i++) {
-      exporter.export(createSpan({ traceId: `t${i}`, name: 'test', startTime: i }));
-    }
-    const spans = exporter.getSpans();
-    expect(spans).toHaveLength(3);
-    expect(spans[0].traceId).toBe('t2');
-  });
-
-  it('clear removes all spans', () => {
-    const exporter = new InMemoryExporter();
-    exporter.export(createSpan({ traceId: 't1', name: 'test', startTime: 0 }));
-    exporter.clear();
-    expect(exporter.getSpans()).toHaveLength(0);
-  });
-});
-
-describe('TracingMiddleware', () => {
-  it('creates and exports spans on success', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter);
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.after('mod.a', {}, { result: 'ok' }, ctx);
-
-    const spans = exporter.getSpans();
-    expect(spans).toHaveLength(1);
-    expect(spans[0].name).toBe('apcore.module.execute');
-    expect(spans[0].status).toBe('ok');
-    expect(spans[0].attributes['moduleId']).toBe('mod.a');
-  });
-
-  it('creates error spans', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter);
-    const ctx = Context.create();
-
-    mw.before('mod.err', {}, ctx);
-    mw.onError('mod.err', {}, new Error('fail'), ctx);
-
-    const spans = exporter.getSpans();
-    expect(spans).toHaveLength(1);
-    expect(spans[0].status).toBe('error');
-  });
-
-  it('supports nested spans with parent chain', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter);
-    const ctx = Context.create();
-
-    mw.before('mod.outer', {}, ctx);
-    mw.before('mod.inner', {}, ctx);
-    mw.after('mod.inner', {}, {}, ctx);
-    mw.after('mod.outer', {}, {}, ctx);
-
-    const spans = exporter.getSpans();
-    expect(spans).toHaveLength(2);
-    // inner span has outer as parent
-    expect(spans[0].parentSpanId).toBe(spans[1].spanId);
-  });
-
-  it('off strategy does not export', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter, 1.0, 'off');
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.after('mod.a', {}, {}, ctx);
-
-    expect(exporter.getSpans()).toHaveLength(0);
-  });
-
-  it('error_first exports errors even when not sampled', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter, 0.0, 'error_first');
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.onError('mod.a', {}, new Error('fail'), ctx);
-
-    expect(exporter.getSpans()).toHaveLength(1);
-  });
-
-  it('throws on invalid sampling rate', () => {
-    const exporter = new InMemoryExporter();
-    expect(() => new TracingMiddleware(exporter, -0.1)).toThrow();
-    expect(() => new TracingMiddleware(exporter, 1.5)).toThrow();
-  });
-
-  it('throws on invalid sampling strategy', () => {
-    const exporter = new InMemoryExporter();
-    expect(() => new TracingMiddleware(exporter, 1.0, 'invalid')).toThrow();
-  });
-});

package/tests/registry/test-dependencies.test.ts

@@ -1,70 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { resolveDependencies } from '../../src/registry/dependencies.js';
-import { CircularDependencyError, ModuleLoadError } from '../../src/errors.js';
-
-describe('resolveDependencies', () => {
-  it('returns empty for empty input', () => {
-    expect(resolveDependencies([])).toEqual([]);
-  });
-
-  it('returns single module', () => {
-    const result = resolveDependencies([['mod.a', []]]);
-    expect(result).toEqual(['mod.a']);
-  });
-
-  it('resolves linear dependency chain', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.b', [{ moduleId: 'mod.a', optional: false, version: null }]],
-      ['mod.a', []],
-    ];
-    const result = resolveDependencies(modules);
-    expect(result.indexOf('mod.a')).toBeLessThan(result.indexOf('mod.b'));
-  });
-
-  it('resolves diamond dependency', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.d', [{ moduleId: 'mod.b', optional: false, version: null }, { moduleId: 'mod.c', optional: false, version: null }]],
-      ['mod.b', [{ moduleId: 'mod.a', optional: false, version: null }]],
-      ['mod.c', [{ moduleId: 'mod.a', optional: false, version: null }]],
-      ['mod.a', []],
-    ];
-    const result = resolveDependencies(modules);
-    expect(result.indexOf('mod.a')).toBeLessThan(result.indexOf('mod.b'));
-    expect(result.indexOf('mod.a')).toBeLessThan(result.indexOf('mod.c'));
-    expect(result.indexOf('mod.b')).toBeLessThan(result.indexOf('mod.d'));
-    expect(result.indexOf('mod.c')).toBeLessThan(result.indexOf('mod.d'));
-  });
-
-  it('throws CircularDependencyError on cycle', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.a', [{ moduleId: 'mod.b', optional: false, version: null }]],
-      ['mod.b', [{ moduleId: 'mod.a', optional: false, version: null }]],
-    ];
-    expect(() => resolveDependencies(modules)).toThrow(CircularDependencyError);
-  });
-
-  it('throws ModuleLoadError for missing required dependency', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.a', [{ moduleId: 'mod.missing', optional: false, version: null }]],
-    ];
-    expect(() => resolveDependencies(modules)).toThrow(ModuleLoadError);
-  });
-
-  it('skips optional missing dependencies', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.a', [{ moduleId: 'mod.missing', optional: true, version: null }]],
-    ];
-    const result = resolveDependencies(modules);
-    expect(result).toEqual(['mod.a']);
-  });
-
-  it('independent modules in deterministic order', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.c', []],
-      ['mod.a', []],
-      ['mod.b', []],
-    ];
-    const result = resolveDependencies(modules);
-    expect(result).toEqual(['mod.a', 'mod.b', 'mod.c']);
-  });
-});

package/tests/registry/test-entry-point.test.ts

@@ -1,133 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { pathToFileURL } from 'node:url';
-import { snakeToPascal, resolveEntryPoint } from '../../src/registry/entry-point.js';
-import { ModuleLoadError } from '../../src/errors.js';
-
-function validModuleSource(name: string): string {
-  return `{
-  inputSchema: { type: 'object' },
-  outputSchema: { type: 'object' },
-  description: '${name} module',
-  execute: function() { return {}; },
-}`;
-}
-
-describe('snakeToPascal', () => {
-  it('returns empty string for empty input', () => {
-    expect(snakeToPascal('')).toBe('');
-  });
-
-  it('capitalises a single word', () => {
-    expect(snakeToPascal('hello')).toBe('Hello');
-  });
-
-  it('converts two-word snake_case', () => {
-    expect(snakeToPascal('hello_world')).toBe('HelloWorld');
-  });
-
-  it('converts multi-word snake_case', () => {
-    expect(snakeToPascal('my_module_name')).toBe('MyModuleName');
-  });
-
-  it('capitalises a word with no underscores', () => {
-    expect(snakeToPascal('already')).toBe('Already');
-  });
-});
-
-describe('resolveEntryPoint', () => {
-  let tmpDir: string;
-
-  beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), 'apcore-entry-test-'));
-  });
-
-  afterEach(() => {
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  function fileUrl(filePath: string): string {
-    return pathToFileURL(filePath).href;
-  }
-
-  it('throws ModuleLoadError for a non-existent file path', async () => {
-    const badPath = fileUrl(join(tmpDir, 'does_not_exist.js'));
-    await expect(resolveEntryPoint(badPath)).rejects.toThrow(ModuleLoadError);
-  });
-
-  it('finds default export that satisfies isModuleClass', async () => {
-    const filePath = join(tmpDir, 'default_mod.mjs');
-    writeFileSync(filePath, `const mod = ${validModuleSource('Default')};\nexport default mod;\n`);
-    const result = await resolveEntryPoint(fileUrl(filePath));
-    expect(result).toBeDefined();
-    expect((result as Record<string, unknown>)['description']).toBe('Default module');
-  });
-
-  it('finds a single named export that satisfies isModuleClass', async () => {
-    const filePath = join(tmpDir, 'named_mod.mjs');
-    writeFileSync(filePath, `export const MyModule = ${validModuleSource('Named')};\n`);
-    const result = await resolveEntryPoint(fileUrl(filePath));
-    expect(result).toBeDefined();
-    expect((result as Record<string, unknown>)['description']).toBe('Named module');
-  });
-
-  it('throws ModuleLoadError when no export satisfies isModuleClass', async () => {
-    const filePath = join(tmpDir, 'no_valid.mjs');
-    writeFileSync(filePath, `export const notAModule = { foo: 'bar' };\nexport const alsoNot = 42;\n`);
-    await expect(resolveEntryPoint(fileUrl(filePath))).rejects.toThrow(ModuleLoadError);
-    await expect(resolveEntryPoint(fileUrl(filePath))).rejects.toThrow(/No Module subclass found/);
-  });
-
-  it('throws ModuleLoadError when multiple exports satisfy isModuleClass', async () => {
-    const filePath = join(tmpDir, 'ambiguous.mjs');
-    writeFileSync(filePath, `export const ModuleA = ${validModuleSource('A')};\nexport const ModuleB = ${validModuleSource('B')};\n`);
-    await expect(resolveEntryPoint(fileUrl(filePath))).rejects.toThrow(ModuleLoadError);
-    await expect(resolveEntryPoint(fileUrl(filePath))).rejects.toThrow(/Ambiguous entry point/);
-  });
-
-  it('uses meta entry_point to find a specific named class', async () => {
-    const filePath = join(tmpDir, 'meta_override.mjs');
-    writeFileSync(filePath, `export const Alpha = ${validModuleSource('Alpha')};\nexport const Beta = ${validModuleSource('Beta')};\n`);
-    const meta = { entry_point: 'some.path:Beta' };
-    const result = await resolveEntryPoint(fileUrl(filePath), meta);
-    expect((result as Record<string, unknown>)['description']).toBe('Beta module');
-  });
-
-  it('throws ModuleLoadError when meta entry_point class does not exist', async () => {
-    const filePath = join(tmpDir, 'meta_missing.mjs');
-    writeFileSync(filePath, `export const Alpha = ${validModuleSource('Alpha')};\n`);
-    const meta = { entry_point: 'mod:NonExistent' };
-    await expect(resolveEntryPoint(fileUrl(filePath), meta)).rejects.toThrow(ModuleLoadError);
-    await expect(resolveEntryPoint(fileUrl(filePath), meta)).rejects.toThrow(/Entry point class 'NonExistent' not found/);
-  });
-
-  it('prefers default export over named exports when both are valid', async () => {
-    const filePath = join(tmpDir, 'default_priority.mjs');
-    writeFileSync(filePath, `const def = ${validModuleSource('DefaultPriority')};\nexport default def;\nexport const Named = ${validModuleSource('NamedSibling')};\n`);
-    const result = await resolveEntryPoint(fileUrl(filePath));
-    expect((result as Record<string, unknown>)['description']).toBe('DefaultPriority module');
-  });
-
-  it('falls back to auto-infer when meta is null', async () => {
-    const filePath = join(tmpDir, 'null_meta.mjs');
-    writeFileSync(filePath, `export const OnlyModule = ${validModuleSource('OnlyMeta')};\n`);
-    const result = await resolveEntryPoint(fileUrl(filePath), null);
-    expect((result as Record<string, unknown>)['description']).toBe('OnlyMeta module');
-  });
-
-  it('ignores exports missing execute function', async () => {
-    const filePath = join(tmpDir, 'missing_execute.mjs');
-    writeFileSync(filePath, `export const Incomplete = {\n  inputSchema: { type: 'object' },\n  outputSchema: { type: 'object' },\n  description: 'no execute',\n};\nexport const Complete = ${validModuleSource('Complete')};\n`);
-    const result = await resolveEntryPoint(fileUrl(filePath));
-    expect((result as Record<string, unknown>)['description']).toBe('Complete module');
-  });
-
-  it('ignores primitive and null exports', async () => {
-    const filePath = join(tmpDir, 'primitives.mjs');
-    writeFileSync(filePath, `export const aNumber = 42;\nexport const aString = 'hello';\nexport const aNull = null;\nexport const Valid = ${validModuleSource('Valid')};\n`);
-    const result = await resolveEntryPoint(fileUrl(filePath));
-    expect((result as Record<string, unknown>)['description']).toBe('Valid module');
-  });
-});