@oa-sdk/spec-bundler 0.1.0

package/dist/index.js

@@ -0,0 +1,705 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { resolveBundleTargets } from "./resolver.js";
+import { rewriteMarkdownContent, rewriteTypeSpecContent, verifyBundleLinkIntegrity, findClosestFile, } from "./link-rewriter.js";
+import { createZipArchive, extractZipArchive, readZipArchive, } from "./archiver.js";
+import { checkFreshness, getLockfilePath, writeLockfile, calculateAggregateHash, generateLockfileData, } from "./freshness.js";
+import { pruneUnreachableEntries, buildDependencyTree, renderAsciiTree, } from "./tree-shaker.js";
+import { validateManifestSchema } from "./schema.js";
+import { resolveTopicManifest } from "./topic.js";
+import { generateTopicContextMarkdown } from "./context-generator.js";
+import { parseDocumentCategory, extractDocumentFidelity } from "./category-parser.js";
+export * from "./types.js";
+export * from "./resolver.js";
+export * from "./link-rewriter.js";
+export * from "./archiver.js";
+export * from "./freshness.js";
+export * from "./tree-shaker.js";
+export * from "./schema.js";
+export * from "./topic.js";
+export * from "./section-slicer.js";
+export * from "./context-generator.js";
+export * from "./category-parser.js";
+/**
+ * Loads and validates a bundle manifest file from disk.
+ */
+export function loadManifest(manifestPath) {
+    const absPath = path.resolve(process.cwd(), manifestPath);
+    if (!fs.existsSync(absPath)) {
+        throw new Error(`Manifest file not found: ${manifestPath}`);
+    }
+    const raw = fs.readFileSync(absPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`JSON syntax error in manifest ${manifestPath}: ${err.message}`);
+    }
+    const errors = validateManifestSchema(parsed);
+    if (errors.length > 0) {
+        throw new Error(`Invalid manifest format in ${manifestPath}:\n  - ${errors.join("\n  - ")}`);
+    }
+    return parsed;
+}
+/**
+ * Executes packaging: target resolution, deduplication, markdown link rewriting,
+ * ZIP creation, and lockfile synchronization. Supports dryRun preview.
+ */
+export function createBundle(manifestPath, options = {}) {
+    const absManifest = path.resolve(process.cwd(), manifestPath);
+    const baseDir = path.dirname(absManifest);
+    const rawManifest = loadManifest(manifestPath);
+    const manifest = options.topic
+        ? resolveTopicManifest(rawManifest, options.topic)
+        : rawManifest;
+    if (options.treeShake !== undefined) {
+        if (!manifest.treeShake) {
+            manifest.treeShake = { enabled: options.treeShake, entrypoints: [] };
+        }
+        else {
+            manifest.treeShake = { ...manifest.treeShake, enabled: options.treeShake };
+        }
+    }
+    const effectiveLockfileMode = options.lockfileMode ?? manifest.lockfileMode;
+    const lockfilePath = getLockfilePath(absManifest, options.topic, effectiveLockfileMode);
+    // Freshness check: if not forced and not dry-run, skip if already fresh.
+    // In dryRun mode, always execute simulation to provide full prediction records.
+    if (!options.force && !options.dryRun) {
+        const freshness = checkFreshness(manifest, baseDir, lockfilePath, {
+            topic: options.topic,
+            diff: options.diff,
+            lockfileMode: effectiveLockfileMode,
+        });
+        if (freshness.isFresh) {
+            const outputPath = path.resolve(baseDir, manifest.output);
+            const stat = fs.existsSync(outputPath) ? fs.statSync(outputPath) : { size: 0 };
+            return {
+                outputPath,
+                filesCount: 0,
+                totalSizeBytes: stat.size,
+                aggregateHash: freshness.currentAggregateHash,
+                diagnostics: [],
+                skipped: true,
+                topic: options.topic,
+            };
+        }
+    }
+    // 1. Resolve targets & deduplicate
+    const { entries, warnings } = resolveBundleTargets(manifest, baseDir);
+    // 1.5. Tree-shaking reachability pruning
+    let activeEntries = entries;
+    let eliminatedFiles = [];
+    let boundaryTerminals = [];
+    let upstreamNodes = [];
+    let nodeCategories = new Map();
+    if (manifest.treeShake?.enabled) {
+        const treeShakeResult = pruneUnreachableEntries(entries, manifest.treeShake, baseDir);
+        activeEntries = treeShakeResult.reachableEntries;
+        eliminatedFiles = treeShakeResult.eliminatedEntries.map((e) => e.bundleDestPath);
+        boundaryTerminals = treeShakeResult.boundaryTerminals ?? [];
+        upstreamNodes = treeShakeResult.upstreamNodes ?? [];
+        nodeCategories = treeShakeResult.nodeCategories ?? new Map();
+        warnings.push(...treeShakeResult.warnings);
+    }
+    const resolvedList = Array.from(activeEntries.values());
+    // 2. Build reverse lookup map: absoluteSourcePath -> bundleDestPath
+    const sourceAbsToBundleDest = new Map();
+    for (const entry of resolvedList) {
+        sourceAbsToBundleDest.set(path.resolve(entry.sourceAbsolutePath), entry.bundleDestPath);
+        if (!nodeCategories.has(entry.bundleDestPath)) {
+            const cat = parseDocumentCategory("", entry.sourceAbsolutePath);
+            nodeCategories.set(entry.bundleDestPath, cat);
+        }
+    }
+    // 3. Process contents (apply markdown link rewriting)
+    const allDiagnostics = [];
+    const processedContents = new Map();
+    for (const entry of resolvedList) {
+        let rawBuffer = fs.readFileSync(entry.sourceAbsolutePath);
+        if ((entry.bundleDestPath.endsWith(".md") || entry.bundleDestPath.endsWith(".mdx"))) {
+            let rawText = rawBuffer.toString("utf8");
+            // Apply category parsing and section/fidelity slicing (skipping ambient context docs)
+            const isContextDoc = entry.bundleDestPath.startsWith("context/") ||
+                entry.bundleDestPath.startsWith("_context/");
+            if (!isContextDoc) {
+                const category = nodeCategories.get(entry.bundleDestPath) ??
+                    parseDocumentCategory(rawText, entry.sourceAbsolutePath);
+                nodeCategories.set(entry.bundleDestPath, category);
+                const fidelityMap = manifest.scope?.categoryFidelity ?? manifest.treeShake?.categoryFidelity;
+                const isUpstream = upstreamNodes.includes(entry.bundleDestPath);
+                const fidelity = (isUpstream && fidelityMap?.["upstream"]) ||
+                    fidelityMap?.[category] ||
+                    fidelityMap?.["default"] ||
+                    "full";
+                if (fidelity !== "full" || (manifest.scope?.sections && manifest.scope.sections.length > 0)) {
+                    const fidelityResult = extractDocumentFidelity(rawText, category, fidelity, manifest.scope?.sections);
+                    if (fidelityResult.isModified) {
+                        rawText = fidelityResult.content;
+                    }
+                }
+            }
+            if (manifest.linkResolution?.enabled !== false) {
+                const { rewritten, diagnostics } = rewriteMarkdownContent(rawText, entry.sourceAbsolutePath, entry.bundleDestPath, sourceAbsToBundleDest, baseDir, manifest.linkResolution);
+                allDiagnostics.push(...diagnostics);
+                rawText = rewritten;
+            }
+            rawBuffer = Buffer.from(rawText, "utf8");
+        }
+        else if (entry.bundleDestPath.endsWith(".tsp") &&
+            manifest.linkResolution?.enabled !== false) {
+            const rawText = rawBuffer.toString("utf8");
+            const { rewritten, diagnostics } = rewriteTypeSpecContent(rawText, entry.sourceAbsolutePath, entry.bundleDestPath, sourceAbsToBundleDest, baseDir, manifest.linkResolution);
+            allDiagnostics.push(...diagnostics);
+            rawBuffer = Buffer.from(rewritten, "utf8");
+        }
+        processedContents.set(entry.bundleDestPath, rawBuffer);
+    }
+    // 3.5. Synthesize CONTEXT.md at bundle root if context is declared
+    if (manifest.context && manifest.context.generateContextDoc !== false) {
+        const topicName = options.topic ?? manifest.name;
+        const contextContent = generateTopicContextMarkdown(topicName, {
+            phase: manifest.phase,
+            author: manifest.author,
+            description: manifest.description,
+            targets: manifest.targets,
+            scope: manifest.scope,
+            context: manifest.context,
+            treeShake: manifest.treeShake,
+        }, resolvedList, {
+            boundaryTerminals,
+            upstreamNodes,
+            nodeCategories,
+        });
+        processedContents.set("CONTEXT.md", Buffer.from(contextContent, "utf8"));
+    }
+    // 4. Dead link post-verification
+    const deadLinkSeverity = manifest.linkResolution?.unbundledPolicy === "warn"
+        ? "warning"
+        : manifest.linkResolution?.unbundledPolicy === "error"
+            ? "error"
+            : "warning";
+    const deadLinkDiags = verifyBundleLinkIntegrity(processedContents, {
+        severity: deadLinkSeverity,
+        unbundledPolicy: manifest.linkResolution?.unbundledPolicy,
+    });
+    const existingDiagKeys = new Set(allDiagnostics.map((d) => `${d.file}:${d.line}:${d.column ?? 1}:${d.originalHref}`));
+    for (const diag of deadLinkDiags) {
+        const key = `${diag.file}:${diag.line}:${diag.column ?? 1}:${diag.originalHref}`;
+        if (!existingDiagKeys.has(key)) {
+            allDiagnostics.push(diag);
+            existingDiagKeys.add(key);
+        }
+    }
+    // 5. Output packaging calculation
+    const outputPath = path.resolve(baseDir, manifest.output);
+    const format = manifest.format ?? "zip";
+    let totalBytes = 0;
+    for (const buf of processedContents.values()) {
+        totalBytes += buf.length;
+    }
+    const aggregateHash = calculateAggregateHash(resolvedList);
+    const predictedLockfile = generateLockfileData(manifest, resolvedList);
+    const freshness = checkFreshness(manifest, baseDir, lockfilePath, {
+        topic: options.topic,
+        diff: options.diff,
+        lockfileMode: effectiveLockfileMode,
+    });
+    const plannedEntries = resolvedList.map((entry) => ({
+        source: entry.sourceRelativePath,
+        dest: entry.bundleDestPath,
+        size: processedContents.get(entry.bundleDestPath)?.length ?? entry.size,
+        sha256: entry.sha256,
+    }));
+    if (processedContents.has("CONTEXT.md")) {
+        const contextBuf = processedContents.get("CONTEXT.md");
+        const contextSha = crypto.createHash("sha256").update(contextBuf).digest("hex");
+        plannedEntries.push({
+            source: "(synthesized)",
+            dest: "CONTEXT.md",
+            size: contextBuf.length,
+            sha256: contextSha,
+        });
+    }
+    const rewrites = allDiagnostics
+        .filter((d) => d.severity === "info" &&
+        d.rewrittenHref !== undefined &&
+        d.originalHref !== d.rewrittenHref)
+        .map((d) => ({
+        file: d.file,
+        line: d.line,
+        column: d.column ?? 1,
+        originalHref: d.originalHref,
+        rewrittenHref: d.rewrittenHref,
+        targetBundleDest: d.targetBundleDest,
+        linkKind: d.linkKind ?? "inline",
+    }));
+    const unbundledDiagnostics = allDiagnostics.filter((d) => d.message.includes("Unbundled") ||
+        d.message.includes("unbundled") ||
+        d.message.includes("not part of this bundle"));
+    const direction = manifest.treeShake?.direction ?? manifest.scope?.direction ?? "downstream";
+    const categoryBreakdown = {};
+    for (const entry of resolvedList) {
+        const cat = nodeCategories.get(entry.bundleDestPath) ?? "feature";
+        categoryBreakdown[cat] = (categoryBreakdown[cat] ?? 0) + 1;
+    }
+    if (options.dryRun) {
+        return {
+            outputPath,
+            filesCount: processedContents.size,
+            totalSizeBytes: totalBytes,
+            aggregateHash,
+            diagnostics: allDiagnostics,
+            skipped: false,
+            dryRun: true,
+            topic: options.topic,
+            phase: manifest.phase,
+            author: manifest.author,
+            eliminatedFiles: eliminatedFiles.length > 0 ? eliminatedFiles : undefined,
+            boundaryTerminals: boundaryTerminals.length > 0 ? boundaryTerminals : undefined,
+            upstreamNodes: upstreamNodes.length > 0 ? upstreamNodes : undefined,
+            direction,
+            categoryBreakdown,
+            plannedEntries,
+            rewrites,
+            predictedLockfile,
+            freshness,
+            unbundledDiagnostics,
+        };
+    }
+    // Only create directory and write files when NOT dryRun
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    if (format === "zip") {
+        const zipEntries = [];
+        for (const [bundlePath, buf] of processedContents.entries()) {
+            zipEntries.push({
+                path: bundlePath,
+                data: buf,
+            });
+        }
+        // Embed manifest BOM with bidirectional path mapping
+        const sourceToBundle = {};
+        const bundleToSource = {};
+        for (const entry of resolvedList) {
+            const src = entry.sourceRelativePath.replace(/\\/g, "/");
+            const dst = entry.bundleDestPath.replace(/\\/g, "/");
+            sourceToBundle[src] = dst;
+            bundleToSource[dst] = src;
+        }
+        if (processedContents.has("CONTEXT.md")) {
+            sourceToBundle["(synthesized)"] = "CONTEXT.md";
+            bundleToSource["CONTEXT.md"] = "(synthesized)";
+        }
+        const bomManifest = {
+            manifestName: manifest.name,
+            manifestVersion: manifest.version,
+            topic: options.topic,
+            topicPhase: manifest.phase,
+            topicAuthor: manifest.author,
+            topicContext: manifest.context,
+            topicScope: manifest.scope,
+            direction,
+            categoryBreakdown,
+            generatedAt: new Date().toISOString(),
+            fileCount: zipEntries.length,
+            files: zipEntries.map((e) => e.path),
+            sourceToBundle,
+            bundleToSource,
+        };
+        zipEntries.push({
+            path: "META-INF/bundle.manifest.json",
+            data: Buffer.from(JSON.stringify(bomManifest, null, 2), "utf8"),
+        });
+        const zipBuffer = createZipArchive(zipEntries);
+        fs.writeFileSync(outputPath, zipBuffer);
+    }
+    else if (format === "directory") {
+        const sourceToBundle = {};
+        const bundleToSource = {};
+        for (const entry of resolvedList) {
+            const src = entry.sourceRelativePath.replace(/\\/g, "/");
+            const dst = entry.bundleDestPath.replace(/\\/g, "/");
+            sourceToBundle[src] = dst;
+            bundleToSource[dst] = src;
+        }
+        if (processedContents.has("CONTEXT.md")) {
+            sourceToBundle["(synthesized)"] = "CONTEXT.md";
+            bundleToSource["CONTEXT.md"] = "(synthesized)";
+        }
+        for (const [bundlePath, buf] of processedContents.entries()) {
+            const targetFile = path.join(outputPath, bundlePath);
+            fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+            fs.writeFileSync(targetFile, buf);
+        }
+        const bomManifest = {
+            manifestName: manifest.name,
+            manifestVersion: manifest.version,
+            topic: options.topic,
+            topicPhase: manifest.phase,
+            topicAuthor: manifest.author,
+            topicContext: manifest.context,
+            topicScope: manifest.scope,
+            direction,
+            categoryBreakdown,
+            generatedAt: new Date().toISOString(),
+            fileCount: processedContents.size,
+            files: Array.from(processedContents.keys()),
+            sourceToBundle,
+            bundleToSource,
+        };
+        const metaInfDir = path.join(outputPath, "META-INF");
+        fs.mkdirSync(metaInfDir, { recursive: true });
+        fs.writeFileSync(path.join(metaInfDir, "bundle.manifest.json"), JSON.stringify(bomManifest, null, 2), "utf8");
+    }
+    // 6. Write updated lockfile
+    const lockfile = writeLockfile(lockfilePath, manifest, resolvedList, {
+        topic: options.topic,
+        lockfileMode: effectiveLockfileMode,
+    });
+    return {
+        outputPath,
+        filesCount: processedContents.size,
+        totalSizeBytes: totalBytes,
+        aggregateHash: lockfile.aggregateHash,
+        diagnostics: allDiagnostics,
+        skipped: false,
+        dryRun: false,
+        topic: options.topic,
+        phase: manifest.phase,
+        author: manifest.author,
+        eliminatedFiles: eliminatedFiles.length > 0 ? eliminatedFiles : undefined,
+        boundaryTerminals: boundaryTerminals.length > 0 ? boundaryTerminals : undefined,
+        upstreamNodes: upstreamNodes.length > 0 ? upstreamNodes : undefined,
+        direction,
+        categoryBreakdown,
+        plannedEntries,
+        rewrites,
+        predictedLockfile: lockfile,
+        freshness: {
+            isFresh: true,
+            currentAggregateHash: lockfile.aggregateHash,
+            lockAggregateHash: lockfile.aggregateHash,
+            added: [],
+            removed: [],
+            modified: [],
+        },
+        unbundledDiagnostics,
+    };
+}
+/**
+ * Inspects a bundle manifest, returning its dependency reachability tree, size breakdown,
+ * and provenance lineage for all files.
+ */
+export function inspectBundle(manifestPath, options = {}) {
+    const absManifest = path.resolve(process.cwd(), manifestPath);
+    const baseDir = path.dirname(absManifest);
+    const rawManifest = loadManifest(manifestPath);
+    const manifest = options.topic
+        ? resolveTopicManifest(rawManifest, options.topic)
+        : rawManifest;
+    const { entries, warnings: resolveWarnings } = resolveBundleTargets(manifest, baseDir);
+    const allWarnings = [...resolveWarnings];
+    let treeConfig = manifest.treeShake;
+    if (!treeConfig || !treeConfig.entrypoints || treeConfig.entrypoints.length === 0) {
+        const rootDests = [];
+        for (const [dest] of entries.entries()) {
+            if (!dest.includes("/"))
+                rootDests.push(dest);
+        }
+        treeConfig = {
+            enabled: true,
+            entrypoints: rootDests.length > 0 ? rootDests : Array.from(entries.keys()).slice(0, 5),
+        };
+    }
+    const treeShakeResult = pruneUnreachableEntries(entries, treeConfig, baseDir);
+    allWarnings.push(...treeShakeResult.warnings);
+    const treeNodes = buildDependencyTree(entries, treeConfig, baseDir);
+    const asciiTree = renderAsciiTree(treeNodes);
+    let totalSizeBytes = 0;
+    for (const e of treeShakeResult.reachableEntries.values()) {
+        totalSizeBytes += e.size;
+    }
+    return {
+        manifest,
+        tree: treeNodes,
+        asciiTree,
+        reachableCount: treeShakeResult.reachableEntries.size,
+        eliminatedCount: treeShakeResult.eliminatedEntries.length,
+        totalSizeBytes,
+        warnings: allWarnings,
+        lineage: treeShakeResult.lineage,
+        boundaryTerminals: treeShakeResult.boundaryTerminals,
+        boundaryEdges: treeShakeResult.boundaryEdges,
+        upstreamNodes: treeShakeResult.upstreamNodes,
+        nodeCategories: treeShakeResult.nodeCategories,
+    };
+}
+/**
+ * Verifies integrity, dead links, and drift for a manifest without packaging.
+ */
+export function verifyBundle(manifestPath, options) {
+    const absManifest = path.resolve(process.cwd(), manifestPath);
+    const baseDir = path.dirname(absManifest);
+    const rawManifest = loadManifest(manifestPath);
+    const manifest = options?.topic
+        ? resolveTopicManifest(rawManifest, options.topic)
+        : rawManifest;
+    const effectiveLockfileMode = rawManifest.lockfileMode;
+    const lockfilePath = getLockfilePath(absManifest, options?.topic, effectiveLockfileMode);
+    const freshness = checkFreshness(manifest, baseDir, lockfilePath, {
+        topic: options?.topic,
+        diff: options?.checkAnchors,
+        lockfileMode: effectiveLockfileMode,
+    });
+    const { entries, warnings } = resolveBundleTargets(manifest, baseDir);
+    let activeEntries = entries;
+    let upstreamNodes = [];
+    let nodeCategories = new Map();
+    if (manifest.treeShake?.enabled) {
+        const treeShakeResult = pruneUnreachableEntries(entries, manifest.treeShake, baseDir);
+        activeEntries = treeShakeResult.reachableEntries;
+        upstreamNodes = treeShakeResult.upstreamNodes ?? [];
+        nodeCategories = treeShakeResult.nodeCategories ?? new Map();
+        warnings.push(...treeShakeResult.warnings);
+    }
+    const sourceAbsToBundleDest = new Map();
+    for (const entry of activeEntries.values()) {
+        sourceAbsToBundleDest.set(path.resolve(entry.sourceAbsolutePath), entry.bundleDestPath);
+    }
+    const processedContents = new Map();
+    const resolvedList = Array.from(activeEntries.values());
+    for (const entry of resolvedList) {
+        let rawBuffer = fs.readFileSync(entry.sourceAbsolutePath);
+        if ((entry.bundleDestPath.endsWith(".md") || entry.bundleDestPath.endsWith(".mdx"))) {
+            let rawText = rawBuffer.toString("utf8");
+            const isContextDoc = entry.bundleDestPath.startsWith("context/") ||
+                entry.bundleDestPath.startsWith("_context/");
+            if (!isContextDoc) {
+                const category = nodeCategories.get(entry.bundleDestPath) ??
+                    parseDocumentCategory(rawText, entry.sourceAbsolutePath);
+                nodeCategories.set(entry.bundleDestPath, category);
+                const fidelityMap = manifest.scope?.categoryFidelity ?? manifest.treeShake?.categoryFidelity;
+                const isUpstream = upstreamNodes.includes(entry.bundleDestPath);
+                const fidelity = (isUpstream && fidelityMap?.["upstream"]) ||
+                    fidelityMap?.[category] ||
+                    fidelityMap?.["default"] ||
+                    "full";
+                if (fidelity !== "full" || (manifest.scope?.sections && manifest.scope.sections.length > 0)) {
+                    const fidelityResult = extractDocumentFidelity(rawText, category, fidelity, manifest.scope?.sections);
+                    if (fidelityResult.isModified) {
+                        rawText = fidelityResult.content;
+                    }
+                }
+            }
+            if (manifest.linkResolution?.enabled !== false) {
+                const { rewritten } = rewriteMarkdownContent(rawText, entry.sourceAbsolutePath, entry.bundleDestPath, sourceAbsToBundleDest, baseDir, manifest.linkResolution);
+                rawText = rewritten;
+            }
+            rawBuffer = Buffer.from(rawText, "utf8");
+        }
+        else if (entry.bundleDestPath.endsWith(".tsp") &&
+            manifest.linkResolution?.enabled !== false) {
+            const rawText = rawBuffer.toString("utf8");
+            const { rewritten } = rewriteTypeSpecContent(rawText, entry.sourceAbsolutePath, entry.bundleDestPath, sourceAbsToBundleDest, baseDir, manifest.linkResolution);
+            rawBuffer = Buffer.from(rewritten, "utf8");
+        }
+        processedContents.set(entry.bundleDestPath, rawBuffer);
+    }
+    if (manifest.context && manifest.context.generateContextDoc !== false) {
+        const topicName = options?.topic ?? manifest.name;
+        const contextContent = generateTopicContextMarkdown(topicName, {
+            description: manifest.description,
+            targets: manifest.targets,
+            scope: manifest.scope,
+            context: manifest.context,
+            treeShake: manifest.treeShake,
+        }, resolvedList, []);
+        processedContents.set("CONTEXT.md", Buffer.from(contextContent, "utf8"));
+    }
+    const deadLinkSeverity = manifest.linkResolution?.unbundledPolicy === "warn"
+        ? "warning"
+        : manifest.linkResolution?.unbundledPolicy === "error"
+            ? "error"
+            : "warning";
+    const deadLinks = verifyBundleLinkIntegrity(processedContents, {
+        severity: deadLinkSeverity,
+        unbundledPolicy: manifest.linkResolution?.unbundledPolicy,
+        checkAnchors: options?.checkAnchors,
+    });
+    return { freshness, deadLinks, warnings };
+}
+/**
+ * Extracts an archive file into target destination directory.
+ */
+export function unpackBundle(archivePath, destDir) {
+    const absArchive = path.resolve(process.cwd(), archivePath);
+    const absDest = path.resolve(process.cwd(), destDir);
+    const zipBuffer = fs.readFileSync(absArchive);
+    return extractZipArchive(zipBuffer, absDest);
+}
+/**
+ * Resolves a source path, relative reference, or TypeSpec citation to its
+ * exact coordinate within a packaged bundle archive or extracted directory.
+ */
+export function resolveBundlePath(archiveInput, queryReference, options) {
+    let fileList = [];
+    let sourceToBundle = {};
+    let bundleToSource = {};
+    if (Buffer.isBuffer(archiveInput)) {
+        const entries = readZipArchive(archiveInput);
+        fileList = Array.from(entries.keys()).map((k) => k.replace(/\\/g, "/"));
+        const manifestBuf = entries.get("META-INF/bundle.manifest.json");
+        if (manifestBuf) {
+            try {
+                const parsed = JSON.parse(manifestBuf.toString("utf8"));
+                if (parsed.sourceToBundle && typeof parsed.sourceToBundle === "object") {
+                    sourceToBundle = parsed.sourceToBundle;
+                }
+                if (parsed.bundleToSource && typeof parsed.bundleToSource === "object") {
+                    bundleToSource = parsed.bundleToSource;
+                }
+            }
+            catch {
+                // ignore malformed manifest
+            }
+        }
+    }
+    else if (typeof archiveInput === "string") {
+        const absPath = path.resolve(process.cwd(), archiveInput);
+        if (!fs.existsSync(absPath)) {
+            throw new Error(`Archive input path does not exist: ${archiveInput}`);
+        }
+        const stat = fs.statSync(absPath);
+        if (stat.isFile()) {
+            const zipBuf = fs.readFileSync(absPath);
+            const entries = readZipArchive(zipBuf);
+            fileList = Array.from(entries.keys()).map((k) => k.replace(/\\/g, "/"));
+            const manifestBuf = entries.get("META-INF/bundle.manifest.json");
+            if (manifestBuf) {
+                try {
+                    const parsed = JSON.parse(manifestBuf.toString("utf8"));
+                    if (parsed.sourceToBundle && typeof parsed.sourceToBundle === "object") {
+                        sourceToBundle = parsed.sourceToBundle;
+                    }
+                    if (parsed.bundleToSource && typeof parsed.bundleToSource === "object") {
+                        bundleToSource = parsed.bundleToSource;
+                    }
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        else if (stat.isDirectory()) {
+            const bomPath = path.join(absPath, "META-INF", "bundle.manifest.json");
+            if (fs.existsSync(bomPath)) {
+                try {
+                    const parsed = JSON.parse(fs.readFileSync(bomPath, "utf8"));
+                    if (parsed.sourceToBundle && typeof parsed.sourceToBundle === "object") {
+                        sourceToBundle = parsed.sourceToBundle;
+                    }
+                    if (parsed.bundleToSource && typeof parsed.bundleToSource === "object") {
+                        bundleToSource = parsed.bundleToSource;
+                    }
+                }
+                catch {
+                    // ignore
+                }
+            }
+            const walk = (dir, rel = "") => {
+                for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+                    const itemRel = rel ? `${rel}/${item.name}` : item.name;
+                    if (item.isDirectory()) {
+                        walk(path.join(dir, item.name), itemRel);
+                    }
+                    else {
+                        fileList.push(itemRel.replace(/\\/g, "/"));
+                    }
+                }
+            };
+            walk(absPath);
+        }
+    }
+    else {
+        throw new Error("Invalid archive input: expected Buffer or string path");
+    }
+    const existingFiles = new Set(fileList);
+    // 1. Split query reference into base path, anchor, and query
+    const normalizedQuery = queryReference.replace(/\\/g, "/");
+    const hashIdx = normalizedQuery.indexOf("#");
+    const queryIdx = normalizedQuery.indexOf("?");
+    let splitIdx = -1;
+    if (hashIdx !== -1 && queryIdx !== -1) {
+        splitIdx = Math.min(hashIdx, queryIdx);
+    }
+    else if (hashIdx !== -1) {
+        splitIdx = hashIdx;
+    }
+    else if (queryIdx !== -1) {
+        splitIdx = queryIdx;
+    }
+    const basePath = splitIdx === -1 ? normalizedQuery : normalizedQuery.slice(0, splitIdx);
+    const suffix = splitIdx === -1 ? "" : normalizedQuery.slice(splitIdx);
+    const anchor = hashIdx !== -1 ? normalizedQuery.slice(hashIdx) : undefined;
+    const cleanBase = basePath.replace(/^\/+/, "").replace(/^\.\//, "");
+    // 2. Resolve to bundle path
+    let resolvedBundlePath;
+    // Case A: Query is already a valid bundle path
+    if (existingFiles.has(cleanBase)) {
+        resolvedBundlePath = cleanBase;
+    }
+    // Case B: Direct match in sourceToBundle mapping
+    if (!resolvedBundlePath && sourceToBundle[cleanBase]) {
+        resolvedBundlePath = sourceToBundle[cleanBase];
+    }
+    // Case C: Normalized path in sourceToBundle or existingFiles
+    if (!resolvedBundlePath) {
+        const normalizedClean = path.posix.normalize(cleanBase);
+        if (sourceToBundle[normalizedClean]) {
+            resolvedBundlePath = sourceToBundle[normalizedClean];
+        }
+        else if (existingFiles.has(normalizedClean)) {
+            resolvedBundlePath = normalizedClean;
+        }
+    }
+    // Case D: If baseDir is provided, resolve relative to baseDir inside bundle
+    if (!resolvedBundlePath && options?.baseDir) {
+        const fromBase = path.posix.normalize(path.posix.join(options.baseDir, cleanBase));
+        if (existingFiles.has(fromBase)) {
+            resolvedBundlePath = fromBase;
+        }
+    }
+    // Case E: Suffix / partial path matching in sourceToBundle (e.g. "req.md" or "docs/req.md" matching "templates/.../docs/req.md")
+    if (!resolvedBundlePath) {
+        for (const [srcKey, bundleVal] of Object.entries(sourceToBundle)) {
+            if (srcKey === cleanBase || srcKey.endsWith(`/${cleanBase}`)) {
+                resolvedBundlePath = bundleVal;
+                break;
+            }
+        }
+    }
+    // Case F: Basename match in existing files if unique
+    if (!resolvedBundlePath) {
+        const baseName = path.posix.basename(cleanBase).toLowerCase();
+        const matches = Array.from(existingFiles).filter((f) => path.posix.basename(f).toLowerCase() === baseName);
+        if (matches.length === 1) {
+            resolvedBundlePath = matches[0];
+        }
+    }
+    const existsInBundle = resolvedBundlePath !== undefined && existingFiles.has(resolvedBundlePath);
+    const finalBundlePath = resolvedBundlePath ?? cleanBase;
+    const fullReference = `${finalBundlePath}${suffix}`;
+    const suggestedTarget = !existsInBundle
+        ? (findClosestFile(cleanBase, existingFiles) ?? undefined)
+        : undefined;
+    return {
+        bundlePath: finalBundlePath,
+        anchor,
+        fullReference,
+        existsInBundle,
+        originalQuery: queryReference,
+        suggestedTarget,
+    };
+}
+//# sourceMappingURL=index.js.map