apcore-js 0.1.0

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

@@ -0,0 +1,131 @@
+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

@@ -0,0 +1,70 @@
+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

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

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

@@ -0,0 +1,265 @@
+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 {
+  loadMetadata,
+  parseDependencies,
+  mergeModuleMetadata,
+  loadIdMap,
+} from '../../src/registry/metadata.js';
+import { ConfigError, ConfigNotFoundError } from '../../src/errors.js';
+
+describe('loadMetadata', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'metadata-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns empty object for non-existent file', () => {
+    const result = loadMetadata(join(tmpDir, 'does_not_exist.yaml'));
+    expect(result).toEqual({});
+  });
+
+  it('parses valid YAML and returns record', () => {
+    const metaPath = join(tmpDir, '_meta.yaml');
+    writeFileSync(metaPath, 'description: hello\nversion: "2.0.0"\ntags:\n  - alpha\n  - beta\n');
+    const result = loadMetadata(metaPath);
+    expect(result).toEqual({
+      description: 'hello',
+      version: '2.0.0',
+      tags: ['alpha', 'beta'],
+    });
+  });
+
+  it('returns empty object for null YAML content', () => {
+    const metaPath = join(tmpDir, '_meta.yaml');
+    writeFileSync(metaPath, '');
+    const result = loadMetadata(metaPath);
+    expect(result).toEqual({});
+  });
+
+  it('returns empty object for YAML file containing only null', () => {
+    const metaPath = join(tmpDir, '_meta.yaml');
+    writeFileSync(metaPath, 'null\n');
+    const result = loadMetadata(metaPath);
+    expect(result).toEqual({});
+  });
+
+  it('throws ConfigError for invalid YAML syntax', () => {
+    const metaPath = join(tmpDir, '_meta.yaml');
+    writeFileSync(metaPath, ':\n  :\n    bad: {{{\n');
+    expect(() => loadMetadata(metaPath)).toThrow(ConfigError);
+  });
+
+  it('throws ConfigError if YAML content is a list instead of mapping', () => {
+    const metaPath = join(tmpDir, '_meta.yaml');
+    writeFileSync(metaPath, '- item1\n- item2\n');
+    expect(() => loadMetadata(metaPath)).toThrow(ConfigError);
+    expect(() => loadMetadata(metaPath)).toThrow(/must be a YAML mapping/);
+  });
+});
+
+describe('parseDependencies', () => {
+  it('returns empty array for empty input', () => {
+    expect(parseDependencies([])).toEqual([]);
+  });
+
+  it('returns empty array for null/undefined input', () => {
+    expect(parseDependencies(null as unknown as Array<Record<string, unknown>>)).toEqual([]);
+    expect(parseDependencies(undefined as unknown as Array<Record<string, unknown>>)).toEqual([]);
+  });
+
+  it('parses dependencies with moduleId, version, optional', () => {
+    const raw = [
+      { module_id: 'core.auth', version: '1.2.0', optional: true },
+      { module_id: 'core.db', version: '3.0.0', optional: false },
+    ];
+    const result = parseDependencies(raw);
+    expect(result).toEqual([
+      { moduleId: 'core.auth', version: '1.2.0', optional: true },
+      { moduleId: 'core.db', version: '3.0.0', optional: false },
+    ]);
+  });
+
+  it('skips entries without module_id', () => {
+    const raw = [
+      { module_id: 'valid.module' },
+      { version: '1.0.0' },
+      { optional: true },
+      {},
+    ];
+    const result = parseDependencies(raw);
+    expect(result).toHaveLength(1);
+    expect(result[0].moduleId).toBe('valid.module');
+  });
+
+  it('defaults version to null and optional to false', () => {
+    const raw = [{ module_id: 'some.module' }];
+    const result = parseDependencies(raw);
+    expect(result).toEqual([
+      { moduleId: 'some.module', version: null, optional: false },
+    ]);
+  });
+
+  it('handles mixed entries with partial fields', () => {
+    const raw = [
+      { module_id: 'a', version: '1.0.0' },
+      { module_id: 'b', optional: true },
+      { module_id: 'c' },
+    ];
+    const result = parseDependencies(raw);
+    expect(result).toEqual([
+      { moduleId: 'a', version: '1.0.0', optional: false },
+      { moduleId: 'b', version: null, optional: true },
+      { moduleId: 'c', version: null, optional: false },
+    ]);
+  });
+});
+
+describe('mergeModuleMetadata', () => {
+  it('YAML values win over code values for all top-level fields', () => {
+    const moduleObj = {
+      description: 'code desc',
+      name: 'code-name',
+      tags: ['code-tag'],
+      version: '1.0.0',
+      annotations: { codeAnnot: true },
+      examples: [{ code: 'code-example' }],
+      documentation: 'code docs',
+      metadata: { codeKey: 'codeVal' },
+    };
+    const meta = {
+      description: 'yaml desc',
+      name: 'yaml-name',
+      tags: ['yaml-tag'],
+      version: '2.0.0',
+      annotations: { yamlAnnot: true },
+      examples: [{ code: 'yaml-example' }],
+      documentation: 'yaml docs',
+      metadata: { yamlKey: 'yamlVal' },
+    };
+    const result = mergeModuleMetadata(moduleObj, meta);
+    expect(result['description']).toBe('yaml desc');
+    expect(result['name']).toBe('yaml-name');
+    expect(result['tags']).toEqual(['yaml-tag']);
+    expect(result['version']).toBe('2.0.0');
+    expect(result['annotations']).toEqual({ yamlAnnot: true });
+    expect(result['examples']).toEqual([{ code: 'yaml-example' }]);
+    expect(result['documentation']).toBe('yaml docs');
+  });
+
+  it('code values used as fallback when YAML is empty', () => {
+    const moduleObj = {
+      description: 'code desc',
+      name: 'code-name',
+      tags: ['code-tag'],
+      version: '1.0.0',
+      metadata: { codeKey: 'codeVal' },
+    };
+    const meta: Record<string, unknown> = {};
+    const result = mergeModuleMetadata(moduleObj, meta);
+    expect(result['description']).toBe('code desc');
+    expect(result['name']).toBe('code-name');
+    expect(result['tags']).toEqual(['code-tag']);
+    expect(result['version']).toBe('1.0.0');
+    expect(result['metadata']).toEqual({ codeKey: 'codeVal' });
+  });
+
+  it('metadata records are shallow-merged with YAML spread over code', () => {
+    const moduleObj = { metadata: { shared: 'from-code', codeOnly: 'value' } };
+    const meta = { metadata: { shared: 'from-yaml', yamlOnly: 'value' } };
+    const result = mergeModuleMetadata(moduleObj, meta);
+    expect(result['metadata']).toEqual({
+      shared: 'from-yaml',
+      codeOnly: 'value',
+      yamlOnly: 'value',
+    });
+  });
+
+  it('default values used when both code and YAML are absent', () => {
+    const result = mergeModuleMetadata({}, {});
+    expect(result['description']).toBe('');
+    expect(result['name']).toBeNull();
+    expect(result['tags']).toEqual([]);
+    expect(result['version']).toBe('1.0.0');
+    expect(result['annotations']).toBeNull();
+    expect(result['examples']).toEqual([]);
+    expect(result['metadata']).toEqual({});
+    expect(result['documentation']).toBeNull();
+  });
+
+  it('YAML empty array for tags overrides code tags', () => {
+    const moduleObj = { tags: ['code-tag'] };
+    const meta = { tags: [] };
+    const result = mergeModuleMetadata(moduleObj, meta);
+    expect(result['tags']).toEqual([]);
+  });
+});
+
+describe('loadIdMap', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'idmap-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('throws ConfigNotFoundError for non-existent file', () => {
+    expect(() => loadIdMap(join(tmpDir, 'nonexistent.yaml'))).toThrow(ConfigNotFoundError);
+  });
+
+  it('throws ConfigError for invalid YAML syntax', () => {
+    const idMapPath = join(tmpDir, 'id_map.yaml');
+    writeFileSync(idMapPath, ':\n  bad: {{{\n');
+    expect(() => loadIdMap(idMapPath)).toThrow(ConfigError);
+  });
+
+  it('throws ConfigError when mappings key is missing', () => {
+    const idMapPath = join(tmpDir, 'id_map.yaml');
+    writeFileSync(idMapPath, 'some_key: value\n');
+    expect(() => loadIdMap(idMapPath)).toThrow(ConfigError);
+  });
+
+  it('throws ConfigError when mappings is not an array', () => {
+    const idMapPath = join(tmpDir, 'id_map.yaml');
+    writeFileSync(idMapPath, 'mappings:\n  key: value\n');
+    expect(() => loadIdMap(idMapPath)).toThrow(ConfigError);
+  });
+
+  it('parses valid mappings with file, id, and class fields', () => {
+    const idMapPath = join(tmpDir, 'id_map.yaml');
+    writeFileSync(
+      idMapPath,
+      ['mappings:', '  - file: module_a.ts', '    id: custom.module.a', '    class: ModuleA', '  - file: module_b.ts', '    id: custom.module.b', ''].join('\n'),
+    );
+    const result = loadIdMap(idMapPath);
+    expect(result['module_a.ts']).toEqual({ id: 'custom.module.a', class: 'ModuleA' });
+    expect(result['module_b.ts']).toEqual({ id: 'custom.module.b', class: null });
+  });
+
+  it('skips entries without file field', () => {
+    const idMapPath = join(tmpDir, 'id_map.yaml');
+    writeFileSync(
+      idMapPath,
+      ['mappings:', '  - file: valid.ts', '    id: valid.id', '  - id: orphan.id', ''].join('\n'),
+    );
+    const result = loadIdMap(idMapPath);
+    expect(Object.keys(result)).toEqual(['valid.ts']);
+  });
+
+  it('handles empty mappings array', () => {
+    const idMapPath = join(tmpDir, 'id_map.yaml');
+    writeFileSync(idMapPath, 'mappings: []\n');
+    const result = loadIdMap(idMapPath);
+    expect(result).toEqual({});
+  });
+});