apcore-js 0.1.1 → 0.2.0

package/src/registry/registry.ts

@@ -13,6 +13,20 @@ import { scanExtensions, scanMultiRoot } from './scanner.js';
 import type { DependencyInfo, ModuleDescriptor } from './types.js';
 import { validateModule } from './validation.js';
 
+/**
+ * Standard registry event names.
+ */
+export const REGISTRY_EVENTS = Object.freeze({
+  REGISTER: "register",
+  UNREGISTER: "unregister",
+} as const);
+
+/**
+ * Valid module ID pattern. Only lowercase letters, digits, underscores, and dots.
+ * Hyphens are prohibited to ensure bijective MCP/OpenAI tool name normalization.
+ */
+export const MODULE_ID_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+
 type EventCallback = (moduleId: string, module: unknown) => void;
 
 export class Registry {
@@ -20,8 +34,8 @@ export class Registry {
   private _modules: Map<string, unknown> = new Map();
   private _moduleMeta: Map<string, Record<string, unknown>> = new Map();
   private _callbacks: Map<string, EventCallback[]> = new Map([
-    ['register', []],
-    ['unregister', []],
+    [REGISTRY_EVENTS.REGISTER, []],
+    [REGISTRY_EVENTS.UNREGISTER, []],
   ]);
   private _idMap: Record<string, Record<string, unknown>> = {};
   private _schemaCache: Map<string, Record<string, unknown>> = new Map();
@@ -63,6 +77,18 @@ export class Registry {
   }
 
   async discover(): Promise<number> {
+    const discovered = this._scanRoots();
+    this._applyIdMapOverrides(discovered);
+
+    const rawMetadata = this._loadAllMetadata(discovered);
+    const resolvedModules = await this._resolveAllEntryPoints(discovered, rawMetadata);
+    const validModules = this._validateAll(resolvedModules);
+    const loadOrder = this._resolveLoadOrder(validModules, rawMetadata);
+
+    return this._registerInOrder(loadOrder, validModules, rawMetadata);
+  }
+
+  private _scanRoots(): import('./types.js').DiscoveredModule[] {
     let maxDepth = 8;
     let followSymlinks = false;
     if (this._config !== null) {
@@ -70,112 +96,125 @@ export class Registry {
       followSymlinks = (this._config.get('extensions.follow_symlinks', false) as boolean);
     }
 
-    // Step 1: Scan extension roots
     const hasNamespace = this._extensionRoots.some((r) => 'namespace' in r);
-    let discovered;
     if (this._extensionRoots.length > 1 || hasNamespace) {
-      discovered = scanMultiRoot(this._extensionRoots, maxDepth, followSymlinks);
-    } else {
-      const rootPath = this._extensionRoots[0]['root'] as string;
-      discovered = scanExtensions(rootPath, maxDepth, followSymlinks);
+      return scanMultiRoot(this._extensionRoots, maxDepth, followSymlinks);
     }
+    return scanExtensions(this._extensionRoots[0]['root'] as string, maxDepth, followSymlinks);
+  }
 
-    // Step 2: Apply ID Map overrides
-    if (Object.keys(this._idMap).length > 0) {
-      const resolvedRoots = this._extensionRoots.map((r) => resolve(r['root'] as string));
-      for (const dm of discovered) {
-        for (const root of resolvedRoots) {
-          try {
-            const relPath = dm.filePath.startsWith(root)
-              ? dm.filePath.slice(root.length + 1)
-              : null;
-            if (relPath && relPath in this._idMap) {
-              dm.canonicalId = this._idMap[relPath]['id'] as string;
-              break;
-            }
-          } catch {
-            continue;
+  private _applyIdMapOverrides(discovered: import('./types.js').DiscoveredModule[]): void {
+    if (Object.keys(this._idMap).length === 0) return;
+
+    const resolvedRoots = this._extensionRoots.map((r) => resolve(r['root'] as string));
+    for (const dm of discovered) {
+      for (const root of resolvedRoots) {
+        try {
+          const relPath = dm.filePath.startsWith(root)
+            ? dm.filePath.slice(root.length + 1)
+            : null;
+          if (relPath && relPath in this._idMap) {
+            dm.canonicalId = this._idMap[relPath]['id'] as string;
+            break;
           }
+        } catch (e) {
+          console.warn(`[apcore:registry] Failed to apply ID map for ${dm.canonicalId}:`, e);
+          continue;
         }
       }
     }
+  }
 
-    // Step 3: Load metadata
+  private _loadAllMetadata(
+    discovered: import('./types.js').DiscoveredModule[],
+  ): Map<string, Record<string, unknown>> {
     const rawMetadata = new Map<string, Record<string, unknown>>();
     for (const dm of discovered) {
-      rawMetadata.set(
-        dm.canonicalId,
-        dm.metaPath ? loadMetadata(dm.metaPath) : {},
-      );
+      rawMetadata.set(dm.canonicalId, dm.metaPath ? loadMetadata(dm.metaPath) : {});
     }
+    return rawMetadata;
+  }
 
-    // Step 4: Resolve entry points
+  private async _resolveAllEntryPoints(
+    discovered: import('./types.js').DiscoveredModule[],
+    rawMetadata: Map<string, Record<string, unknown>>,
+  ): Promise<Map<string, unknown>> {
     const resolvedModules = new Map<string, unknown>();
     for (const dm of discovered) {
       const meta = rawMetadata.get(dm.canonicalId) ?? {};
       try {
         const mod = await resolveEntryPoint(dm.filePath, meta);
         resolvedModules.set(dm.canonicalId, mod);
-      } catch {
-        continue;
+      } catch (e) {
+        console.warn(`[apcore:registry] Failed to resolve entry point for ${dm.canonicalId}:`, e);
       }
     }
+    return resolvedModules;
+  }
 
-    // Step 5: Validate modules
+  private _validateAll(resolvedModules: Map<string, unknown>): Map<string, unknown> {
     const validModules = new Map<string, unknown>();
     for (const [modId, mod] of resolvedModules) {
-      const errors = validateModule(mod);
-      if (errors.length === 0) {
+      if (validateModule(mod).length === 0) {
         validModules.set(modId, mod);
       }
     }
+    return validModules;
+  }
 
-    // Step 6: Collect dependencies
+  private _resolveLoadOrder(
+    validModules: Map<string, unknown>,
+    rawMetadata: Map<string, Record<string, unknown>>,
+  ): string[] {
     const modulesWithDeps: Array<[string, DependencyInfo[]]> = [];
     for (const modId of validModules.keys()) {
       const meta = rawMetadata.get(modId) ?? {};
       const depsRaw = (meta['dependencies'] as Array<Record<string, unknown>>) ?? [];
-      const deps = depsRaw.length > 0 ? parseDependencies(depsRaw) : [];
-      modulesWithDeps.push([modId, deps]);
+      modulesWithDeps.push([modId, depsRaw.length > 0 ? parseDependencies(depsRaw) : []]);
     }
-
-    // Step 7: Resolve dependency order
     const knownIds = new Set(modulesWithDeps.map(([id]) => id));
-    const loadOrder = resolveDependencies(modulesWithDeps, knownIds);
+    return resolveDependencies(modulesWithDeps, knownIds);
+  }
 
-    // Step 8: Register in dependency order
-    let registeredCount = 0;
+  private _registerInOrder(
+    loadOrder: string[],
+    validModules: Map<string, unknown>,
+    rawMetadata: Map<string, Record<string, unknown>>,
+  ): number {
+    let count = 0;
     for (const modId of loadOrder) {
       const mod = validModules.get(modId)!;
-      const meta = rawMetadata.get(modId) ?? {};
-
       const modObj = mod as Record<string, unknown>;
-      const mergedMeta = mergeModuleMetadata(modObj, meta);
+      const mergedMeta = mergeModuleMetadata(modObj, rawMetadata.get(modId) ?? {});
 
       this._modules.set(modId, mod);
       this._moduleMeta.set(modId, mergedMeta);
 
-      // Call onLoad if available
       if (typeof modObj['onLoad'] === 'function') {
         try {
           (modObj['onLoad'] as () => void)();
-        } catch {
+        } catch (e) {
+          console.warn(`[apcore:registry] onLoad failed for ${modId}, skipping:`, e);
           this._modules.delete(modId);
           this._moduleMeta.delete(modId);
           continue;
         }
       }
 
-      this._triggerEvent('register', modId, mod);
-      registeredCount++;
+      this._triggerEvent(REGISTRY_EVENTS.REGISTER, modId, mod);
+      count++;
     }
-
-    return registeredCount;
+    return count;
   }
 
   register(moduleId: string, module: unknown): void {
-    if (!moduleId) {
-      throw new InvalidInputError('module_id must be a non-empty string');
+    if (!moduleId || typeof moduleId !== "string") {
+      throw new InvalidInputError("Module ID must be a non-empty string");
+    }
+    if (!MODULE_ID_PATTERN.test(moduleId)) {
+      throw new InvalidInputError(
+        `Invalid module ID: "${moduleId}". Must match pattern: ${MODULE_ID_PATTERN} (lowercase, digits, underscores, dots only; no hyphens)`,
+      );
     }
 
     if (this._modules.has(moduleId)) {
@@ -195,7 +234,7 @@ export class Registry {
       }
     }
 
-    this._triggerEvent('register', moduleId, module);
+    this._triggerEvent(REGISTRY_EVENTS.REGISTER, moduleId, module);
   }
 
   unregister(moduleId: string): boolean {
@@ -211,12 +250,12 @@ export class Registry {
     if (typeof modObj['onUnload'] === 'function') {
       try {
         (modObj['onUnload'] as () => void)();
-      } catch {
-        // Swallow
+      } catch (e) {
+        console.warn(`[apcore:registry] onUnload failed for ${moduleId}:`, e);
       }
     }
 
-    this._triggerEvent('unregister', moduleId, module);
+    this._triggerEvent(REGISTRY_EVENTS.UNREGISTER, moduleId, module);
     return true;
   }
 
@@ -291,8 +330,11 @@ export class Registry {
   }
 
   on(event: string, callback: EventCallback): void {
-    if (!this._callbacks.has(event)) {
-      throw new InvalidInputError(`Invalid event: ${event}. Must be 'register' or 'unregister'`);
+    const validEvents = Object.values(REGISTRY_EVENTS) as string[];
+    if (!validEvents.includes(event)) {
+      throw new InvalidInputError(
+        `Invalid event: ${event}. Must be one of: ${validEvents.map((e) => `'${e}'`).join(', ')}`,
+      );
     }
     this._callbacks.get(event)!.push(callback);
   }
@@ -302,8 +344,8 @@ export class Registry {
     for (const cb of callbacks) {
       try {
         cb(moduleId, module);
-      } catch {
-        // Swallow callback errors
+      } catch (e) {
+        console.warn(`[apcore:registry] Event callback error for '${event}' on ${moduleId}:`, e);
       }
     }
   }

package/src/registry/schema-export.ts

@@ -6,15 +6,12 @@ import type { TSchema } from '@sinclair/typebox';
 import json from 'js-yaml';
 import type { ModuleAnnotations, ModuleExample } from '../module.js';
 import { ModuleNotFoundError } from '../errors.js';
+import { deepCopy } from '../utils/index.js';
 import { SchemaExporter } from '../schema/exporter.js';
 import { stripExtensions, toStrictSchema } from '../schema/strict.js';
 import { ExportProfile, type SchemaDefinition } from '../schema/types.js';
 import type { Registry } from './registry.js';
 
-function deepCopy<T>(obj: T): T {
-  return JSON.parse(JSON.stringify(obj));
-}
-
 export function getSchema(registry: Registry, moduleId: string): Record<string, unknown> | null {
   const module = registry.get(moduleId);
   if (module === null) return null;

package/src/schema/exporter.ts

@@ -3,13 +3,10 @@
  */
 
 import type { ModuleAnnotations, ModuleExample } from '../module.js';
+import { deepCopy } from '../utils/index.js';
 import { applyLlmDescriptions, stripExtensions, toStrictSchema } from './strict.js';
 import { ExportProfile, type SchemaDefinition } from './types.js';
 
-function deepCopy<T>(obj: T): T {
-  return JSON.parse(JSON.stringify(obj));
-}
-
 export class SchemaExporter {
   export(
     schemaDef: SchemaDefinition,

package/src/schema/loader.ts

@@ -191,80 +191,69 @@ export class SchemaLoader {
 export function jsonSchemaToTypeBox(schema: Record<string, unknown>): TSchema {
   const schemaType = schema['type'] as string | undefined;
 
-  if (schemaType === 'object') {
-    const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined;
-    const required = new Set((schema['required'] as string[]) ?? []);
-
-    if (properties) {
-      const typeboxProps: Record<string, TSchema> = {};
-      for (const [name, propSchema] of Object.entries(properties)) {
-        const propType = jsonSchemaToTypeBox(propSchema);
-        typeboxProps[name] = required.has(name) ? propType : Type.Optional(propType);
-      }
-      return Type.Object(typeboxProps);
-    }
-    return Type.Record(Type.String(), Type.Unknown());
-  }
+  if (schemaType === 'object') return convertObjectSchema(schema);
+  if (schemaType === 'array') return convertArraySchema(schema);
+  if (schemaType === 'string') return convertStringSchema(schema);
+  if (schemaType === 'integer') return convertNumericSchema(schema, Type.Integer);
+  if (schemaType === 'number') return convertNumericSchema(schema, Type.Number);
+  if (schemaType === 'boolean') return Type.Boolean();
+  if (schemaType === 'null') return Type.Null();
 
-  if (schemaType === 'array') {
-    const items = schema['items'] as Record<string, unknown> | undefined;
-    if (items) {
-      return Type.Array(jsonSchemaToTypeBox(items));
+  return convertCombinatorSchema(schema);
+}
+
+function convertObjectSchema(schema: Record<string, unknown>): TSchema {
+  const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined;
+  const required = new Set((schema['required'] as string[]) ?? []);
+
+  if (properties) {
+    const typeboxProps: Record<string, TSchema> = {};
+    for (const [name, propSchema] of Object.entries(properties)) {
+      const propType = jsonSchemaToTypeBox(propSchema);
+      typeboxProps[name] = required.has(name) ? propType : Type.Optional(propType);
     }
-    return Type.Array(Type.Unknown());
+    return Type.Object(typeboxProps);
   }
+  return Type.Record(Type.String(), Type.Unknown());
+}
 
-  if (schemaType === 'string') {
-    const opts: Record<string, unknown> = {};
-    if ('minLength' in schema) opts['minLength'] = schema['minLength'];
-    if ('maxLength' in schema) opts['maxLength'] = schema['maxLength'];
-    if ('pattern' in schema) opts['pattern'] = schema['pattern'];
-    if ('format' in schema) opts['format'] = schema['format'];
-    return Type.String(opts);
-  }
+function convertArraySchema(schema: Record<string, unknown>): TSchema {
+  const items = schema['items'] as Record<string, unknown> | undefined;
+  return items ? Type.Array(jsonSchemaToTypeBox(items)) : Type.Array(Type.Unknown());
+}
 
-  if (schemaType === 'integer') {
-    const opts: Record<string, unknown> = {};
-    if ('minimum' in schema) opts['minimum'] = schema['minimum'];
-    if ('maximum' in schema) opts['maximum'] = schema['maximum'];
-    if ('exclusiveMinimum' in schema) opts['exclusiveMinimum'] = schema['exclusiveMinimum'];
-    if ('exclusiveMaximum' in schema) opts['exclusiveMaximum'] = schema['exclusiveMaximum'];
-    if ('multipleOf' in schema) opts['multipleOf'] = schema['multipleOf'];
-    return Type.Integer(opts);
+function convertStringSchema(schema: Record<string, unknown>): TSchema {
+  const opts: Record<string, unknown> = {};
+  for (const key of ['minLength', 'maxLength', 'pattern', 'format']) {
+    if (key in schema) opts[key] = schema[key];
   }
+  return Type.String(opts);
+}
 
-  if (schemaType === 'number') {
-    const opts: Record<string, unknown> = {};
-    if ('minimum' in schema) opts['minimum'] = schema['minimum'];
-    if ('maximum' in schema) opts['maximum'] = schema['maximum'];
-    if ('exclusiveMinimum' in schema) opts['exclusiveMinimum'] = schema['exclusiveMinimum'];
-    if ('exclusiveMaximum' in schema) opts['exclusiveMaximum'] = schema['exclusiveMaximum'];
-    if ('multipleOf' in schema) opts['multipleOf'] = schema['multipleOf'];
-    return Type.Number(opts);
+function convertNumericSchema(
+  schema: Record<string, unknown>,
+  factory: (opts?: Record<string, unknown>) => TSchema,
+): TSchema {
+  const opts: Record<string, unknown> = {};
+  for (const key of ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf']) {
+    if (key in schema) opts[key] = schema[key];
   }
+  return factory(opts);
+}
 
-  if (schemaType === 'boolean') return Type.Boolean();
-  if (schemaType === 'null') return Type.Null();
-
+function convertCombinatorSchema(schema: Record<string, unknown>): TSchema {
   if ('enum' in schema) {
     const values = schema['enum'] as unknown[];
     return Type.Union(values.map((v) => Type.Literal(v as string | number | boolean)));
   }
-
   if ('oneOf' in schema) {
-    const schemas = schema['oneOf'] as Record<string, unknown>[];
-    return Type.Union(schemas.map((s) => jsonSchemaToTypeBox(s)));
+    return Type.Union((schema['oneOf'] as Record<string, unknown>[]).map(jsonSchemaToTypeBox));
   }
-
   if ('anyOf' in schema) {
-    const schemas = schema['anyOf'] as Record<string, unknown>[];
-    return Type.Union(schemas.map((s) => jsonSchemaToTypeBox(s)));
+    return Type.Union((schema['anyOf'] as Record<string, unknown>[]).map(jsonSchemaToTypeBox));
   }
-
   if ('allOf' in schema) {
-    const schemas = schema['allOf'] as Record<string, unknown>[];
-    return Type.Intersect(schemas.map((s) => jsonSchemaToTypeBox(s)));
+    return Type.Intersect((schema['allOf'] as Record<string, unknown>[]).map(jsonSchemaToTypeBox));
   }
-
   return Type.Unknown();
 }

package/src/schema/ref-resolver.ts

@@ -6,13 +6,10 @@ 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__';
 
-function deepCopy<T>(obj: T): T {
-  return JSON.parse(JSON.stringify(obj));
-}
-
 export class RefResolver {
   private _schemasDir: string;
   private _maxDepth: number;

package/src/schema/strict.ts

@@ -2,9 +2,7 @@
  * Strict mode conversion for JSON Schemas (Algorithm A23).
  */
 
-function deepCopy<T>(obj: T): T {
-  return JSON.parse(JSON.stringify(obj));
-}
+import { deepCopy } from '../utils/index.js';
 
 export function toStrictSchema(schema: Record<string, unknown>): Record<string, unknown> {
   const result = deepCopy(schema);

package/src/utils/index.ts

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

package/tests/integration/test-e2e-flow.test.ts

@@ -72,21 +72,21 @@ describe('E2E Flow', () => {
     });
     const modB = new FunctionModule({
       execute: (inputs) => ({ value: (inputs['x'] as number) + 10 }),
-      moduleId: 'math.addTen',
+      moduleId: 'math.add_ten',
       inputSchema: Type.Object({ x: Type.Number() }),
       outputSchema: Type.Object({ value: Type.Number() }),
       description: 'Add ten',
     });
     registry.register('math.double', modA);
-    registry.register('math.addTen', modB);
+    registry.register('math.add_ten', modB);
 
     const executor = new Executor({ registry });
-    const ctx = Context.create(executor, createIdentity('test-user'));
+    const ctx = Context.create(executor, createIdentity('test_user'));
 
     const r1 = await executor.call('math.double', { x: 5 }, ctx);
     expect(r1['value']).toBe(10);
 
-    const r2 = await executor.call('math.addTen', { x: r1['value'] as number }, ctx);
+    const r2 = await executor.call('math.add_ten', { x: r1['value'] as number }, ctx);
     expect(r2['value']).toBe(20);
   });
 

package/tests/schema/test-annotations.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for schema/annotations.ts — annotation conflict resolution.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { mergeAnnotations, mergeExamples, mergeMetadata } from '../../src/schema/annotations.js';
+import { DEFAULT_ANNOTATIONS } from '../../src/module.js';
+import type { ModuleAnnotations, ModuleExample } from '../../src/module.js';
+
+describe('mergeAnnotations', () => {
+  it('returns defaults when both inputs are null', () => {
+    const result = mergeAnnotations(null, null);
+    expect(result).toEqual(DEFAULT_ANNOTATIONS);
+  });
+
+  it('returns defaults when both inputs are undefined', () => {
+    const result = mergeAnnotations(undefined, undefined);
+    expect(result).toEqual(DEFAULT_ANNOTATIONS);
+  });
+
+  it('applies code annotations over defaults', () => {
+    const codeAnnotations: ModuleAnnotations = {
+      readonly: true,
+      destructive: false,
+      idempotent: true,
+      requiresApproval: false,
+      openWorld: false,
+    };
+    const result = mergeAnnotations(null, codeAnnotations);
+    expect(result.readonly).toBe(true);
+    expect(result.idempotent).toBe(true);
+    expect(result.openWorld).toBe(false);
+  });
+
+  it('yaml annotations override code annotations', () => {
+    const codeAnnotations: ModuleAnnotations = {
+      readonly: true,
+      destructive: false,
+      idempotent: false,
+      requiresApproval: false,
+      openWorld: true,
+    };
+    const yamlAnnotations = { readonly: false, destructive: true };
+    const result = mergeAnnotations(yamlAnnotations, codeAnnotations);
+    expect(result.readonly).toBe(false);
+    expect(result.destructive).toBe(true);
+    expect(result.idempotent).toBe(false);
+  });
+
+  it('ignores unknown yaml keys', () => {
+    const yamlAnnotations = { unknownKey: 'value', readonly: true };
+    const result = mergeAnnotations(yamlAnnotations, null);
+    expect(result.readonly).toBe(true);
+    expect((result as unknown as Record<string, unknown>)['unknownKey']).toBeUndefined();
+  });
+});
+
+describe('mergeExamples', () => {
+  it('returns empty array when both inputs are null', () => {
+    expect(mergeExamples(null, null)).toEqual([]);
+  });
+
+  it('returns empty array when both inputs are undefined', () => {
+    expect(mergeExamples(undefined, undefined)).toEqual([]);
+  });
+
+  it('returns yaml examples when present', () => {
+    const yamlExamples = [
+      { title: 'Test', inputs: { a: 1 }, output: { b: 2 }, description: 'desc' },
+    ];
+    const result = mergeExamples(yamlExamples, null);
+    expect(result).toHaveLength(1);
+    expect(result[0].title).toBe('Test');
+    expect(result[0].inputs).toEqual({ a: 1 });
+    expect(result[0].output).toEqual({ b: 2 });
+    expect(result[0].description).toBe('desc');
+  });
+
+  it('uses code examples when yaml is null', () => {
+    const codeExamples: ModuleExample[] = [
+      { title: 'Code', inputs: { x: 1 }, output: { y: 2 } },
+    ];
+    const result = mergeExamples(null, codeExamples);
+    expect(result).toEqual(codeExamples);
+  });
+
+  it('yaml examples take precedence over code examples', () => {
+    const yamlExamples = [{ title: 'YAML', inputs: {}, output: {} }];
+    const codeExamples: ModuleExample[] = [
+      { title: 'Code', inputs: {}, output: {} },
+    ];
+    const result = mergeExamples(yamlExamples, codeExamples);
+    expect(result).toHaveLength(1);
+    expect(result[0].title).toBe('YAML');
+  });
+
+  it('handles yaml examples with missing optional fields', () => {
+    const yamlExamples = [{ title: 'Minimal' }];
+    const result = mergeExamples(yamlExamples as Array<Record<string, unknown>>, null);
+    expect(result[0].inputs).toEqual({});
+    expect(result[0].output).toEqual({});
+    expect(result[0].description).toBeUndefined();
+  });
+});
+
+describe('mergeMetadata', () => {
+  it('returns empty object when both inputs are null', () => {
+    expect(mergeMetadata(null, null)).toEqual({});
+  });
+
+  it('returns code metadata when yaml is null', () => {
+    const code = { key: 'value' };
+    expect(mergeMetadata(null, code)).toEqual({ key: 'value' });
+  });
+
+  it('returns yaml metadata when code is null', () => {
+    const yaml = { key: 'value' };
+    expect(mergeMetadata(yaml, null)).toEqual({ key: 'value' });
+  });
+
+  it('yaml overrides code on conflicting keys', () => {
+    const code = { a: 1, b: 2 };
+    const yaml = { b: 3, c: 4 };
+    const result = mergeMetadata(yaml, code);
+    expect(result).toEqual({ a: 1, b: 3, c: 4 });
+  });
+
+  it('does not mutate input objects', () => {
+    const code = { a: 1 };
+    const yaml = { b: 2 };
+    mergeMetadata(yaml, code);
+    expect(code).toEqual({ a: 1 });
+    expect(yaml).toEqual({ b: 2 });
+  });
+});