apcore-toolkit 0.4.1 → 0.5.1

package/dist/output/verifiers.js.map

@@ -1 +1 @@
-{"version":3,"file":"verifiers.js","sourceRoot":"","sources":["../../src/output/verifiers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"verifiers.js","sourceRoot":"","sources":["../../src/output/verifiers.ts"],"names":[],"mappings":"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"}

package/dist/output/verify-core.d.ts

@@ -0,0 +1,20 @@
+import type { Verifier, VerifyResult } from './types.js';
+export declare class RegistryVerifier implements Verifier {
+    private readonly registry;
+    constructor(registry: {
+        getModule?(id: string): unknown;
+    });
+    verify(_path: string, moduleId: string): VerifyResult;
+}
+/**
+ * Run a chain of verifiers in order, returning the first failure.
+ * If a verifier throws an exception, it is caught and returned as a failure
+ * with the prefix "Verifier crashed:".
+ *
+ * @param verifiers - Ordered list of verifiers to run.
+ * @param path - File path to verify.
+ * @param moduleId - Module ID being verified.
+ * @returns The first failed VerifyResult, or { ok: true } if all pass.
+ */
+export declare function runVerifierChain(verifiers: Verifier[], path: string, moduleId: string): VerifyResult;
+//# sourceMappingURL=verify-core.d.ts.map

package/dist/output/verify-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-core.d.ts","sourceRoot":"","sources":["../../src/output/verify-core.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEzD,qBAAa,gBAAiB,YAAW,QAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;gBAEnD,QAAQ,EAAE;QAAE,SAAS,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE;IAIzD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY;CActD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,QAAQ,EAAE,EACrB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,YAAY,CAYd"}

package/dist/output/verify-core.js

@@ -0,0 +1,59 @@
+// Runtime-neutral verifier primitives.
+//
+// This module contains the `Verifier` implementations and combinators that
+// do not touch the filesystem or any other Node-only API. They live here so
+// the browser subpath entry (`apcore-toolkit/browser`) can expose them
+// without transitively dragging in `node:fs` / `node:module` from the
+// file-based verifiers (`YAMLVerifier`, `SyntaxVerifier`, `MagicBytesVerifier`,
+// `JSONVerifier`) that share the original `verifiers.ts` file.
+//
+// `verifiers.ts` continues to re-export `RegistryVerifier` and
+// `runVerifierChain` from here, so the default package entry point's public
+// API is unchanged.
+export class RegistryVerifier {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    verify(_path, moduleId) {
+        try {
+            if (typeof this.registry.getModule !== 'function') {
+                return { ok: false, error: 'Registry does not have a getModule method' };
+            }
+            const mod = this.registry.getModule(moduleId);
+            if (mod == null) {
+                return { ok: false, error: `Module "${moduleId}" not found in registry` };
+            }
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: `Registry lookup error: ${err.message}`, cause: err };
+        }
+    }
+}
+/**
+ * Run a chain of verifiers in order, returning the first failure.
+ * If a verifier throws an exception, it is caught and returned as a failure
+ * with the prefix "Verifier crashed:".
+ *
+ * @param verifiers - Ordered list of verifiers to run.
+ * @param path - File path to verify.
+ * @param moduleId - Module ID being verified.
+ * @returns The first failed VerifyResult, or { ok: true } if all pass.
+ */
+export function runVerifierChain(verifiers, path, moduleId) {
+    for (const verifier of verifiers) {
+        try {
+            const result = verifier.verify(path, moduleId);
+            if (!result.ok)
+                return result;
+        }
+        catch (e) {
+            const name = verifier.constructor?.name ?? 'UnknownVerifier';
+            const msg = e instanceof Error ? e.message : String(e);
+            return { ok: false, error: `${name} crashed: ${msg}`, cause: e };
+        }
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=verify-core.js.map

package/dist/output/verify-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-core.js","sourceRoot":"","sources":["../../src/output/verify-core.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,uEAAuE;AACvE,sEAAsE;AACtE,gFAAgF;AAChF,+DAA+D;AAC/D,EAAE;AACF,+DAA+D;AAC/D,4EAA4E;AAC5E,oBAAoB;AAIpB,MAAM,OAAO,gBAAgB;IACV,QAAQ,CAAsC;IAE/D,YAAY,QAA6C;QACvD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,KAAa,EAAE,QAAgB;QACpC,IAAI,CAAC;YACH,IAAI,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;gBAClD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,2CAA2C,EAAE,CAAC;YAC3E,CAAC;YACD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAC9C,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;gBAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,QAAQ,yBAAyB,EAAE,CAAC;YAC5E,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,0BAA2B,GAAa,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QAC9F,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAqB,EACrB,IAAY,EACZ,QAAgB;IAEhB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC/C,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,OAAO,MAAM,CAAC;QAChC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,EAAE,IAAI,IAAI,iBAAiB,CAAC;YAC7D,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,aAAa,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACnE,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/output/yaml-writer.d.ts

@@ -1,11 +1,23 @@
 import type { ScannedModule } from '../types.js';
-import type { WriteResult, Verifier } from './types.js';
+import type { WriteResult } from './types.js';
+import type { FileWriteOptions } from './base-writer.js';
+/**
+ * Write scanned modules as YAML binding files.
+ *
+ * Each module is serialised to a `<module_id>.binding.yaml` file in the
+ * specified output directory. The YAML format conforms to the apcore binding
+ * spec (`spec_version: "1.0"`).
+ */
 export declare class YAMLWriter {
-    write(modules: ScannedModule[], outputDir: string, options?: {
-        dryRun?: boolean;
-        verify?: boolean;
-        verifiers?: Verifier[];
-    }): WriteResult[];
+    /**
+     * Serialise modules to YAML and write them to `outputDir`.
+     *
+     * @param modules - Scanned modules to write.
+     * @param outputDir - Directory to write binding files into (created if absent).
+     * @param options - Optional write options: `dryRun`, `verify`, `verifiers`.
+     * @returns Array of WriteResult, one per module.
+     */
+    write(modules: ScannedModule[], outputDir: string, options?: FileWriteOptions): WriteResult[];
     private _buildBinding;
 }
 //# sourceMappingURL=yaml-writer.d.ts.map

package/dist/output/yaml-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"yaml-writer.d.ts","sourceRoot":"","sources":["../../src/output/yaml-writer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKxD,qBAAa,UAAU;IACrB,KAAK,CACH,OAAO,EAAE,aAAa,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;KAAE,GACvE,WAAW,EAAE;IA4EhB,OAAO,CAAC,aAAa;CAqBtB"}
+{"version":3,"file":"yaml-writer.d.ts","sourceRoot":"","sources":["../../src/output/yaml-writer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB;;;;;;;OAOG;IACH,KAAK,CACH,OAAO,EAAE,aAAa,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,gBAAgB,GACzB,WAAW,EAAE;IAqHhB,OAAO,CAAC,aAAa;CA2BtB"}

package/dist/output/yaml-writer.js

@@ -1,24 +1,56 @@
 import yaml from 'js-yaml';
-import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { writeFileSync, mkdirSync, realpathSync, lstatSync, renameSync, unlinkSync } from 'node:fs';
+import { resolve, join, sep } from 'node:path';
 import { annotationsToDict } from '../serializers.js';
 import { createWriteResult } from './types.js';
 import { WriteError } from './errors.js';
-import { YAMLVerifier, runVerifierChain } from './verifiers.js';
+import { YAMLVerifier } from './verifiers.js';
+import { applyVerification } from './base-writer.js';
+/**
+ * Write scanned modules as YAML binding files.
+ *
+ * Each module is serialised to a `<module_id>.binding.yaml` file in the
+ * specified output directory. The YAML format conforms to the apcore binding
+ * spec (`spec_version: "1.0"`).
+ */
 export class YAMLWriter {
+    /**
+     * Serialise modules to YAML and write them to `outputDir`.
+     *
+     * @param modules - Scanned modules to write.
+     * @param outputDir - Directory to write binding files into (created if absent).
+     * @param options - Optional write options: `dryRun`, `verify`, `verifiers`.
+     * @returns Array of WriteResult, one per module.
+     */
     write(modules, outputDir, options) {
         const dryRun = options?.dryRun ?? false;
         const shouldVerify = options?.verify ?? false;
         const verifiers = options?.verifiers ?? [];
+        const errorMode = options?.errorMode ?? 'throw';
         if (modules.length === 0) {
             return [];
         }
         const outputPath = resolve(outputDir);
         if (!dryRun) {
-            mkdirSync(outputPath, { recursive: true });
+            try {
+                mkdirSync(outputPath, { recursive: true });
+            }
+            catch (err) {
+                throw new WriteError(outputPath, err);
+            }
+        }
+        let realOutputPath = outputPath;
+        if (!dryRun) {
+            try {
+                realOutputPath = realpathSync(outputPath);
+            }
+            catch (err) {
+                throw new WriteError(outputPath, err);
+            }
         }
         const results = [];
         const timestamp = new Date().toISOString();
+        const writtenIds = new Map(); // filename → moduleId that claimed it
         for (const module of modules) {
             const bindingData = this._buildBinding(module);
             if (dryRun) {
@@ -27,16 +59,29 @@ export class YAMLWriter {
             }
             let safeId = module.moduleId.replace(/[^a-zA-Z0-9._-]/g, '_');
             safeId = safeId.replace(/\.{2,}/g, '_');
-            const filename = `${safeId}.binding.yaml`;
-            const filePath = resolve(join(outputPath, filename));
-            // Path traversal protection
-            if (!filePath.startsWith(outputPath)) {
-                console.warn('Skipping file outside output directory: %s', filePath);
-                continue;
+            const baseFilename = `${safeId}.binding.yaml`;
+            let filename = baseFilename;
+            let collisionCounter = 0;
+            while (writtenIds.has(filename)) {
+                collisionCounter++;
+                filename = `${safeId}_${collisionCounter}.binding.yaml`;
             }
-            if (existsSync(filePath)) {
-                console.warn('Overwriting existing file: %s', filePath);
+            if (collisionCounter > 0) {
+                console.warn('YAMLWriter: safeId collision — "%s" and "%s" both map to %s; using %s', writtenIds.get(baseFilename), module.moduleId, baseFilename, filename);
             }
+            writtenIds.set(filename, module.moduleId);
+            // Build filePath from the real (symlink-resolved) output dir so the
+            // prefix check below compares canonical paths on both sides.
+            const filePath = resolve(join(realOutputPath, filename));
+            // Block pre-existing symlinks at the target path (TOCTOU mitigation).
+            try {
+                if (lstatSync(filePath).isSymbolicLink()) {
+                    console.warn('Skipping symlink escape at: %s', filePath);
+                    results.push(createWriteResult(module.moduleId, filePath, false, 'Security skip: symlink at target path'));
+                    continue;
+                }
+            }
+            catch { /* file does not exist — safe to write */ }
             const header = `# Auto-generated by apcore-toolkit scanner\n` +
                 `# Generated: ${timestamp}\n` +
                 `# Do not edit manually unless you intend to customize schemas.\n\n`;
@@ -44,48 +89,60 @@ export class YAMLWriter {
                 flowLevel: -1,
                 sortKeys: false,
             });
+            // Atomic write via tmp file + rename.
+            const tmpPath = `${filePath}.${process.pid}.tmp`;
             try {
-                writeFileSync(filePath, header + yamlContent, 'utf-8');
+                writeFileSync(tmpPath, header + yamlContent, 'utf-8');
+                renameSync(tmpPath, filePath);
+                // Post-rename sanity check: verify the result is not a symlink (defence-in-depth).
+                try {
+                    if (lstatSync(filePath).isSymbolicLink()) {
+                        console.warn('YAMLWriter: post-rename symlink detected at %s — possible race', filePath);
+                    }
+                }
+                catch { /* lstat failing here is non-critical */ }
             }
             catch (err) {
-                throw new WriteError(filePath, err);
-            }
-            let result = createWriteResult(module.moduleId, filePath);
-            if (shouldVerify) {
-                const builtinResult = new YAMLVerifier().verify(filePath, module.moduleId);
-                if (!builtinResult.ok) {
-                    result = createWriteResult(module.moduleId, filePath, false, builtinResult.error ?? null);
+                try {
+                    unlinkSync(tmpPath);
                 }
-            }
-            if (result.verified && verifiers.length > 0) {
-                const vResult = runVerifierChain(verifiers, filePath, module.moduleId);
-                if (!vResult.ok) {
-                    result = createWriteResult(module.moduleId, filePath, false, vResult.error ?? null);
+                catch { /* best-effort cleanup */ }
+                if (errorMode === 'collect') {
+                    results.push(createWriteResult(module.moduleId, filePath, false, err instanceof Error ? err.message : String(err)));
+                    continue;
                 }
+                throw new WriteError(filePath, err);
             }
+            const result = applyVerification(createWriteResult(module.moduleId, filePath), new YAMLVerifier(), verifiers, filePath, module.moduleId, shouldVerify);
             results.push(result);
         }
         return results;
     }
     _buildBinding(module) {
+        const binding = {
+            module_id: module.moduleId,
+            target: module.target,
+            description: module.description,
+            documentation: module.documentation,
+            tags: [...module.tags],
+            version: module.version,
+            annotations: annotationsToDict(module.annotations),
+            examples: module.examples.length > 0
+                ? module.examples.map((e) => structuredClone(e))
+                : [],
+            metadata: structuredClone(module.metadata),
+            input_schema: structuredClone(module.inputSchema),
+            output_schema: structuredClone(module.outputSchema),
+        };
+        if (module.suggestedAlias !== null) {
+            binding.suggested_alias = module.suggestedAlias;
+        }
+        if (module.display !== null) {
+            binding.display = structuredClone(module.display);
+        }
         return {
-            bindings: [
-                {
-                    module_id: module.moduleId,
-                    target: module.target,
-                    description: module.description,
-                    documentation: module.documentation,
-                    tags: [...module.tags],
-                    version: module.version,
-                    annotations: annotationsToDict(module.annotations),
-                    examples: module.examples.length > 0
-                        ? module.examples.map((e) => ({ ...e }))
-                        : [],
-                    metadata: structuredClone(module.metadata),
-                    input_schema: structuredClone(module.inputSchema),
-                    output_schema: structuredClone(module.outputSchema),
-                },
-            ],
+            spec_version: "1.0",
+            bindings: [binding],
         };
     }
 }

package/dist/output/yaml-writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"yaml-writer.js","sourceRoot":"","sources":["../../src/output/yaml-writer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"yaml-writer.js","sourceRoot":"","sources":["../../src/output/yaml-writer.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACpG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;;;;;GAMG;AACH,MAAM,OAAO,UAAU;IACrB;;;;;;;OAOG;IACH,KAAK,CACH,OAAwB,EACxB,SAAiB,EACjB,OAA0B;QAE1B,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC;QACxC,MAAM,YAAY,GAAG,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC;QAC9C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;QAC3C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,OAAO,CAAC;QAEhD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QAEtC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,CAAC;gBACH,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,UAAU,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAED,IAAI,cAAc,GAAG,UAAU,CAAC;QAChC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,CAAC;gBACH,cAAc,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,UAAU,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAkB,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC,CAAC,sCAAsC;QAEpF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;YAE/C,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;gBACvD,SAAS;YACX,CAAC;YAED,IAAI,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;YAC9D,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACxC,MAAM,YAAY,GAAG,GAAG,MAAM,eAAe,CAAC;YAC9C,IAAI,QAAQ,GAAG,YAAY,CAAC;YAC5B,IAAI,gBAAgB,GAAG,CAAC,CAAC;YACzB,OAAO,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAChC,gBAAgB,EAAE,CAAC;gBACnB,QAAQ,GAAG,GAAG,MAAM,IAAI,gBAAgB,eAAe,CAAC;YAC1D,CAAC;YACD,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;gBACzB,OAAO,CAAC,IAAI,CACV,uEAAuE,EACvE,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,EAC5B,MAAM,CAAC,QAAQ,EACf,YAAY,EACZ,QAAQ,CACT,CAAC;YACJ,CAAC;YACD,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC1C,oEAAoE;YACpE,6DAA6D;YAC7D,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC;YAEzD,sEAAsE;YACtE,IAAI,CAAC;gBACH,IAAI,SAAS,CAAC,QAAQ,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;oBACzC,OAAO,CAAC,IAAI,CAAC,gCAAgC,EAAE,QAAQ,CAAC,CAAC;oBACzD,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,uCAAuC,CAAC,CAAC,CAAC;oBAC3G,SAAS;gBACX,CAAC;YACH,CAAC;YAAC,MAAM,CAAC,CAAC,yCAAyC,CAAC,CAAC;YAErD,MAAM,MAAM,GACV,8CAA8C;gBAC9C,gBAAgB,SAAS,IAAI;gBAC7B,oEAAoE,CAAC;YAEvE,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;gBACzC,SAAS,EAAE,CAAC,CAAC;gBACb,QAAQ,EAAE,KAAK;aAChB,CAAC,CAAC;YAEH,sCAAsC;YACtC,MAAM,OAAO,GAAG,GAAG,QAAQ,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;YACjD,IAAI,CAAC;gBACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,OAAO,CAAC,CAAC;gBACtD,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;gBAC9B,mFAAmF;gBACnF,IAAI,CAAC;oBACH,IAAI,SAAS,CAAC,QAAQ,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;wBACzC,OAAO,CAAC,IAAI,CAAC,gEAAgE,EAAE,QAAQ,CAAC,CAAC;oBAC3F,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC,CAAC,wCAAwC,CAAC,CAAC;YACtD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC;oBAAC,UAAU,CAAC,OAAO,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;gBAChE,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;oBAC5B,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACpH,SAAS;gBACX,CAAC;gBACD,MAAM,IAAI,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YACtC,CAAC;YAED,MAAM,MAAM,GAAG,iBAAiB,CAC9B,iBAAiB,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAC5C,IAAI,YAAY,EAAE,EAClB,SAAS,EACT,QAAQ,EACR,MAAM,CAAC,QAAQ,EACf,YAAY,CACb,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,aAAa,CAAC,MAAqB;QACzC,MAAM,OAAO,GAA4B;YACvC,SAAS,EAAE,MAAM,CAAC,QAAQ;YAC1B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;YACtB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,WAAW,EAAE,iBAAiB,CAAC,MAAM,CAAC,WAAW,CAAC;YAClD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;gBAClC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;gBAChD,CAAC,CAAC,EAAE;YACN,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC;YAC1C,YAAY,EAAE,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC;YACjD,aAAa,EAAE,eAAe,CAAC,MAAM,CAAC,YAAY,CAAC;SACpD,CAAC;QACF,IAAI,MAAM,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACnC,OAAO,CAAC,eAAe,GAAG,MAAM,CAAC,cAAc,CAAC;QAClD,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC5B,OAAO,CAAC,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACpD,CAAC;QACD,OAAO;YACL,YAAY,EAAE,KAAK;YACnB,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB,CAAC;IACJ,CAAC;CACF"}

package/dist/resolve-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-target.d.ts","sourceRoot":"","sources":["../src/resolve-target.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,OAAO,CAAC,CAwClB"}
+{"version":3,"file":"resolve-target.d.ts","sourceRoot":"","sources":["../src/resolve-target.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,OAAO,CAAC,CAoElB"}

package/dist/resolve-target.js

@@ -1,4 +1,5 @@
-import { resolve, isAbsolute } from 'node:path';
+import { resolve, isAbsolute, sep } from 'node:path';
+import { realpathSync } from 'node:fs';
 /**
  * Dynamically imports a module and resolves a named export.
  *
@@ -19,11 +20,39 @@ export async function resolveTarget(target, allowedPrefixes) {
     }
     const modulePath = target.slice(0, lastColon);
     const exportName = target.slice(lastColon + 1);
-    // Validate file-path imports against allowedPrefixes
+    if (typeof modulePath !== 'string' || modulePath.length === 0) {
+        throw new Error(`Invalid target format: "${target}". Module path must be a non-empty string.`);
+    }
+    // When allowedPrefixes are specified, restrict to file-path imports only.
+    // node: built-ins and bare package names are not under any file prefix.
+    const isNodeBuiltin = modulePath.startsWith('node:');
     const isFilePath = modulePath.startsWith('.') || isAbsolute(modulePath);
+    const isBarePackage = !isFilePath && !isNodeBuiltin;
+    if (allowedPrefixes != null && allowedPrefixes.length > 0 && (isNodeBuiltin || isBarePackage)) {
+        throw new Error(`Import "${modulePath}" is not allowed: only file-path imports are permitted when allowedPrefixes is set.`);
+    }
     if (isFilePath && allowedPrefixes != null && allowedPrefixes.length > 0) {
-        const resolved = resolve(modulePath);
-        const allowed = allowedPrefixes.some((prefix) => resolved.startsWith(resolve(prefix)));
+        let resolved = resolve(modulePath);
+        try {
+            resolved = realpathSync(resolved);
+        }
+        catch (resolveErr) {
+            const code = resolveErr.code;
+            if (code !== 'ENOENT') {
+                // Non-ENOENT errors (ELOOP, EACCES, etc.) indicate a path that cannot
+                // be safely canonicalized — reject rather than fall back to lexical resolve.
+                throw new Error(`Import path "${modulePath}" could not be canonicalized: ${resolveErr.message}`, { cause: resolveErr });
+            }
+            // ENOENT: file will be created; use lexical resolved path for prefix check.
+        }
+        const allowed = allowedPrefixes.some((prefix) => {
+            let resolvedPrefix = resolve(prefix);
+            try {
+                resolvedPrefix = realpathSync(resolvedPrefix);
+            }
+            catch { /* keep logical resolve */ }
+            return resolved === resolvedPrefix || resolved.startsWith(resolvedPrefix + sep);
+        });
         if (!allowed) {
             throw new Error(`Import path "${modulePath}" is not under any allowed prefix: ${allowedPrefixes.join(', ')}`);
         }
@@ -34,7 +63,7 @@ export async function resolveTarget(target, allowedPrefixes) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`Failed to import module "${modulePath}": ${message}`);
+        throw new Error(`Failed to import module "${modulePath}": ${message}`, { cause: err });
     }
     if (mod[exportName] === undefined) {
         throw new Error(`Export "${exportName}" not found in module "${modulePath}".`);

package/dist/resolve-target.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-target.js","sourceRoot":"","sources":["../src/resolve-target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,eAA0B;IAE1B,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,2BAA2B,MAAM,uCAAuC,CACzE,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAE/C,qDAAqD;IACrD,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACxE,IAAI,UAAU,IAAI,eAAe,IAAI,IAAI,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxE,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAC9C,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CACrC,CAAC;QACF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,gBAAgB,UAAU,sCAAsC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC7F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,GAA4B,CAAC;IACjC,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAA4B,CAAC;IAC9D,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,MAAM,OAAO,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,WAAW,UAAU,0BAA0B,UAAU,IAAI,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC,UAAU,CAAC,CAAC;AACzB,CAAC"}
+{"version":3,"file":"resolve-target.js","sourceRoot":"","sources":["../src/resolve-target.ts"],"names":[],"mappings":"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"}

package/dist/safe-keys.d.ts

@@ -0,0 +1,2 @@
+export declare const PROTO_DENY: ReadonlySet<string>;
+//# sourceMappingURL=safe-keys.d.ts.map

package/dist/safe-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-keys.d.ts","sourceRoot":"","sources":["../src/safe-keys.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAIzC,CAAC"}

package/dist/safe-keys.js

@@ -0,0 +1,19 @@
+// JavaScript-specific prototype-pollution guard.
+//
+// This file has no Python or Rust counterpart: the named keys
+// (`__proto__`, `constructor`, `prototype`) are dangerous only under
+// JavaScript's prototype-chain semantics. Python and Rust use attribute
+// lookups / field accesses that are not affected by this vulnerability
+// class, so their SDKs do not need an equivalent.
+//
+// Typed as `Set<string>` (not the literal union inferred by `as const`) so
+// callers can pass arbitrary user-supplied keys to `.has()` without a cast.
+// The runtime check is what matters; the compile-time narrowing from `as const`
+// would force every caller to pre-narrow their key type, which is impractical
+// for keys coming out of `Object.entries`, YAML parses, or OpenAPI schemas.
+export const PROTO_DENY = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+]);
+//# sourceMappingURL=safe-keys.js.map

package/dist/safe-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-keys.js","sourceRoot":"","sources":["../src/safe-keys.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,EAAE;AACF,8DAA8D;AAC9D,qEAAqE;AACrE,wEAAwE;AACxE,uEAAuE;AACvE,kDAAkD;AAClD,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,gFAAgF;AAChF,8EAA8E;AAC9E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC;IACrD,WAAW;IACX,aAAa;IACb,WAAW;CACZ,CAAC,CAAC"}

package/dist/scanner.d.ts

@@ -1,5 +1,19 @@
 import type { ModuleAnnotations } from 'apcore-js';
 import type { ScannedModule } from './types.js';
+/**
+ * Abstract base class for all apcore-toolkit scanners.
+ *
+ * Subclasses implement `scan()` to produce `ScannedModule[]` from a given
+ * source (OpenAPI spec, Express router, file system, etc.).  The base class
+ * provides shared utilities: docstring extraction, module ID deduplication,
+ * and pattern-based include/exclude filtering.
+ *
+ * @example
+ * class MyScanner extends BaseScanner {
+ *   scan(spec: OpenAPISpec): ScannedModule[] { ... }
+ *   getSourceName(): string { return 'my-scanner'; }
+ * }
+ */
 export declare abstract class BaseScanner {
     abstract scan(...args: unknown[]): ScannedModule[] | Promise<ScannedModule[]>;
     abstract getSourceName(): string;
@@ -8,6 +22,14 @@ export declare abstract class BaseScanner {
         documentation: string | null;
         params: Record<string, string>;
     };
+    /**
+     * Apply include/exclude regex filters to a list of scanned modules.
+     *
+     * @param modules - Modules to filter.
+     * @param options - Optional `include` and/or `exclude` regex pattern strings.
+     * @returns Filtered array of modules.
+     * @throws {SyntaxError} When `include` or `exclude` contain an invalid regex pattern.
+     */
     filterModules(modules: ScannedModule[], options?: {
         include?: string;
         exclude?: string;

package/dist/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAYhD,8BAAsB,WAAW;IAC/B,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAC7E,QAAQ,CAAC,aAAa,IAAI,MAAM;IAEhC,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG;QAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC;IAwCD,aAAa,CACX,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/C,aAAa,EAAE;IAgBlB,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAgBpE,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE;CA2B1D"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD;;;;;;;;;;;;;GAaG;AACH,8BAAsB,WAAW;IAC/B,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAC7E,QAAQ,CAAC,aAAa,IAAI,MAAM;IAEhC,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG;QAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC;IAwCD;;;;;;;OAOG;IACH,aAAa,CACX,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/C,aAAa,EAAE;IAgBlB,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAiBpE,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE;CAoC1D"}

package/dist/scanner.js

@@ -1,14 +1,19 @@
 import { DEFAULT_ANNOTATIONS } from 'apcore-js';
 import { cloneModule } from './types.js';
-function safeRegExp(pattern) {
-    try {
-        return new RegExp(pattern);
-    }
-    catch {
-        // If the pattern is invalid regex, treat it as a literal string
-        return new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
-    }
-}
+/**
+ * Abstract base class for all apcore-toolkit scanners.
+ *
+ * Subclasses implement `scan()` to produce `ScannedModule[]` from a given
+ * source (OpenAPI spec, Express router, file system, etc.).  The base class
+ * provides shared utilities: docstring extraction, module ID deduplication,
+ * and pattern-based include/exclude filtering.
+ *
+ * @example
+ * class MyScanner extends BaseScanner {
+ *   scan(spec: OpenAPISpec): ScannedModule[] { ... }
+ *   getSourceName(): string { return 'my-scanner'; }
+ * }
+ */
 export class BaseScanner {
     extractDocstring(func) {
         if (func == null || typeof func !== 'function') {
@@ -16,7 +21,7 @@ export class BaseScanner {
         }
         // Extract JSDoc-style documentation from function's toString representation
         const source = func.toString();
-        const jsdocMatch = source.match(/\/\*\*([\s\S]*?)\*\//);
+        const jsdocMatch = source.match(/^\/\*\*([\s\S]*?)\*\//);
         if (!jsdocMatch) {
             return { description: null, documentation: null, params: {} };
         }
@@ -46,19 +51,29 @@ export class BaseScanner {
         const documentation = descLines.length > 1 ? descLines.join('\n') : null;
         return { description, documentation, params };
     }
+    /**
+     * Apply include/exclude regex filters to a list of scanned modules.
+     *
+     * @param modules - Modules to filter.
+     * @param options - Optional `include` and/or `exclude` regex pattern strings.
+     * @returns Filtered array of modules.
+     * @throws {SyntaxError} When `include` or `exclude` contain an invalid regex pattern.
+     */
     filterModules(modules, options) {
         let result = modules;
         if (options?.include != null) {
-            const re = safeRegExp(options.include);
+            const re = new RegExp(options.include);
             result = result.filter((m) => re.test(m.moduleId));
         }
         if (options?.exclude != null) {
-            const re = safeRegExp(options.exclude);
+            const re = new RegExp(options.exclude);
             result = result.filter((m) => !re.test(m.moduleId));
         }
         return result;
     }
     static inferAnnotationsFromMethod(method) {
+        if (typeof method !== 'string')
+            return { ...DEFAULT_ANNOTATIONS };
         const upper = method.toUpperCase();
         if (upper === 'GET') {
             return { ...DEFAULT_ANNOTATIONS, readonly: true, cacheable: true };
@@ -72,14 +87,23 @@ export class BaseScanner {
         return { ...DEFAULT_ANNOTATIONS };
     }
     deduplicateIds(modules) {
-        const seen = new Map();
+        const seenCount = new Map();
+        // Pre-populate with all original IDs so generated suffixes never collide
+        // with an ID that already exists in the input list.
+        const usedIds = new Set(modules.map((m) => m.moduleId));
         const result = [];
         for (const module of modules) {
             const mid = module.moduleId;
-            const count = seen.get(mid) ?? 0;
-            seen.set(mid, count + 1);
+            const count = seenCount.get(mid) ?? 0;
+            seenCount.set(mid, count + 1);
             if (count > 0) {
-                const newId = `${mid}_${count + 1}`;
+                let counter = count + 1;
+                let newId = `${mid}_${counter}`;
+                while (usedIds.has(newId)) {
+                    counter++;
+                    newId = `${mid}_${counter}`;
+                }
+                usedIds.add(newId);
                 result.push(cloneModule(module, {
                     moduleId: newId,
                     warnings: [