@oa-sdk/spec-bundler 0.1.0

package/dist/tree-shaker.js

@@ -0,0 +1,523 @@
+import fs from "node:fs";
+import path from "node:path";
+import { maskCodeBlocks, resolveLocalPath } from "./link-rewriter.js";
+import { matchesAnyPattern } from "./resolver.js";
+import { parseDocumentCategory } from "./category-parser.js";
+const TEXT_EXTENSIONS = new Set([
+    ".md",
+    ".mdx",
+    ".tsp",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".txt",
+    ".ts",
+    ".js",
+    ".html",
+]);
+/**
+ * Extracts outgoing local file target candidates from text file content.
+ */
+function extractOutboundReferences(content, extension) {
+    const references = [];
+    if (extension === ".md" || extension === ".mdx") {
+        const { masked } = maskCodeBlocks(content);
+        // 1. Inline links: [text](target) and ![alt](target) (including nested images in labels)
+        // Supports balanced parentheses in destinations and titles in "", '', or ()
+        const linkRegex = /(!?\[)((?:!\[[^\]]*\]\([^)]*\)|[^\]])*)\]\((<[^>]+>|(?:\\.|[^()\s]|\((?:\\.|[^()\s])*\))+)([ \t]+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\)/g;
+        let match;
+        while ((match = linkRegex.exec(masked)) !== null) {
+            references.push(match[3]);
+            if (match[2].includes("![")) {
+                const innerImgRegex = /(!?\[)([^\]]*)\]\((<[^>]+>|(?:\\.|[^()\s]|\((?:\\.|[^()\s])*\))+)([ \t]+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\)/g;
+                let innerMatch;
+                while ((innerMatch = innerImgRegex.exec(match[2])) !== null) {
+                    references.push(innerMatch[3]);
+                }
+            }
+        }
+        // 2. Reference definitions: [label]: target (supports blockquotes, list markers, and destination on next line)
+        const refDefRegex = /^[ \t>]*(?:(?:[-*+]|\d+[.)])[ \t>]+)?\[[^\]]+\]:[ \t]*(?:\r?\n[ \t>]+)?(<[^>]+>|\S+)/gm;
+        while ((match = refDefRegex.exec(masked)) !== null) {
+            references.push(match[1]);
+        }
+        // 3. HTML tags: <img src="target">, <a href="target">
+        const htmlRegex = /(?:src|href)=["']([^"']+)["']/g;
+        while ((match = htmlRegex.exec(masked)) !== null) {
+            references.push(match[1]);
+        }
+    }
+    else if (extension === ".tsp") {
+        // TypeSpec @evidence("target#anchor", "rationale") and imports
+        const evidenceRegex = /@evidence\s*\(\s*["']([^"']+)["']/g;
+        let match;
+        while ((match = evidenceRegex.exec(content)) !== null) {
+            references.push(match[1]);
+        }
+        const importRegex = /import\s+["'](\.[^"']+)["']/g;
+        while ((match = importRegex.exec(content)) !== null) {
+            references.push(match[1]);
+        }
+    }
+    else if (extension === ".json") {
+        // JSON Schema $ref and $schema references
+        const refRegex = /"(?:\$ref|\$schema)"\s*:\s*["']([^"']+)["']/g;
+        let match;
+        while ((match = refRegex.exec(content)) !== null) {
+            references.push(match[1]);
+        }
+    }
+    return references;
+}
+/**
+ * Performs reachability traversal (downstream, upstream, or bidirectional)
+ * starting from declarative entrypoints with category filtering and boundary enforcement.
+ */
+export function pruneUnreachableEntries(entries, config, workspaceRoot) {
+    const traversalMode = config.traversalMode ??
+        (config.preserveTargets === true ? "hybrid" : "reachability");
+    if (config.enabled === false || traversalMode === "explicit") {
+        return {
+            reachableEntries: entries,
+            eliminatedEntries: [],
+            warnings: [],
+            lineage: new Map(),
+            boundaryTerminals: [],
+            boundaryEdges: new Map(),
+        };
+    }
+    const warnings = [];
+    const entrypointsList = config.entrypoints ?? [];
+    if (entrypointsList.length === 0) {
+        if (traversalMode === "hybrid" || config.preserveTargets === true) {
+            return {
+                reachableEntries: entries,
+                eliminatedEntries: [],
+                warnings,
+                lineage: new Map(),
+                boundaryTerminals: [],
+                boundaryEdges: new Map(),
+            };
+        }
+        throw new Error("Tree-shaking failed: none of the specified entrypoints ([]) matched any candidate target.");
+    }
+    // Build reverse and canonical lookup maps
+    const sourceAbsToDest = new Map();
+    const sourceRelToDest = new Map();
+    const destToEntry = new Map();
+    for (const [dest, entry] of entries.entries()) {
+        const absNorm = path.resolve(entry.sourceAbsolutePath);
+        sourceAbsToDest.set(absNorm, dest);
+        sourceRelToDest.set(entry.sourceRelativePath.replace(/\\/g, "/"), dest);
+        destToEntry.set(dest, entry);
+    }
+    // Resolve entrypoints to bundle destinations
+    const entrypointDests = [];
+    for (const rawEp of entrypointsList) {
+        const epClean = rawEp.replace(/\\/g, "/").replace(/^\.\//, "");
+        let matchedDest;
+        if (destToEntry.has(epClean)) {
+            matchedDest = epClean;
+        }
+        else if (sourceRelToDest.has(epClean)) {
+            matchedDest = sourceRelToDest.get(epClean);
+        }
+        else {
+            const absEp = path.resolve(workspaceRoot, rawEp);
+            matchedDest = sourceAbsToDest.get(absEp);
+        }
+        if (matchedDest) {
+            if (!entrypointDests.includes(matchedDest)) {
+                entrypointDests.push(matchedDest);
+            }
+        }
+        else {
+            warnings.push(`Tree-shake entrypoint '${rawEp}' does not match any resolved bundle candidate target.`);
+        }
+    }
+    if (entrypointDests.length === 0) {
+        if (traversalMode === "hybrid" || config.preserveTargets === true) {
+            warnings.push(`Tree-shaking: none of the entrypoints (${JSON.stringify(entrypointsList)}) matched; retaining declared targets.`);
+            return {
+                reachableEntries: entries,
+                eliminatedEntries: [],
+                warnings,
+                lineage: new Map(),
+                boundaryTerminals: [],
+                boundaryEdges: new Map(),
+            };
+        }
+        throw new Error(`Tree-shaking failed: none of the specified entrypoints (${JSON.stringify(entrypointsList)}) matched any candidate target.`);
+    }
+    // Build Bidirectional Reference Graph (outbound & inbound) and parse categories
+    const inboundGraph = new Map();
+    const nodeCategories = new Map();
+    const fileContents = new Map();
+    for (const [dest, entry] of entries.entries()) {
+        const ext = path.posix.extname(dest).toLowerCase();
+        if (!inboundGraph.has(dest))
+            inboundGraph.set(dest, []);
+        if (!TEXT_EXTENSIONS.has(ext) || !fs.existsSync(entry.sourceAbsolutePath)) {
+            continue;
+        }
+        let content = "";
+        try {
+            content = fs.readFileSync(entry.sourceAbsolutePath, "utf8");
+            fileContents.set(dest, content);
+        }
+        catch {
+            continue;
+        }
+        const cat = parseDocumentCategory(content, entry.sourceAbsolutePath);
+        nodeCategories.set(dest, cat);
+        const rawRefs = extractOutboundReferences(content, ext);
+        for (const rawRefWithAngle of rawRefs) {
+            const rawRef = rawRefWithAngle.startsWith("<") && rawRefWithAngle.endsWith(">")
+                ? rawRefWithAngle.slice(1, -1)
+                : rawRefWithAngle;
+            const normalizedRef = rawRef.replace(/\\/g, "/");
+            if (normalizedRef.startsWith("#"))
+                continue;
+            if (!normalizedRef.startsWith("file:") && /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(normalizedRef)) {
+                continue;
+            }
+            const splitIndex = normalizedRef.search(/[#?]/);
+            const basePath = splitIndex === -1 ? normalizedRef : normalizedRef.slice(0, splitIndex);
+            if (!basePath)
+                continue;
+            const resolvedAbs = resolveLocalPath(basePath, entry.sourceAbsolutePath, workspaceRoot);
+            if (!resolvedAbs)
+                continue;
+            const targetDest = sourceAbsToDest.get(resolvedAbs);
+            if (targetDest) {
+                if (!inboundGraph.has(targetDest))
+                    inboundGraph.set(targetDest, []);
+                inboundGraph.get(targetDest).push({ source: dest, rawRef });
+            }
+        }
+    }
+    const direction = config.direction ?? "downstream";
+    const upstreamDepth = config.upstreamDepth ?? 1;
+    const maxDepth = config.maxDepth ?? Infinity;
+    const lineage = new Map();
+    const boundaryTerminalsSet = new Set();
+    const boundaryEdges = new Map();
+    const upstreamNodesSet = new Set();
+    const downstreamNodesSet = new Set();
+    const isCategoryPermitted = (cat) => {
+        if (!cat)
+            return true;
+        if (config.includeCategories && config.includeCategories.length > 0) {
+            if (!config.includeCategories.includes(cat))
+                return false;
+        }
+        if (config.excludeCategories && config.excludeCategories.length > 0) {
+            if (config.excludeCategories.includes(cat))
+                return false;
+        }
+        return true;
+    };
+    // Traversal 1: Upstream (Inbound references from consumers / parent contracts)
+    const traverseUpstream = () => {
+        const queue = entrypointDests.map((dest) => ({
+            dest,
+            depth: 0,
+        }));
+        const seen = new Set(entrypointDests);
+        while (queue.length > 0) {
+            const { dest: currentDest, depth: currentDepth } = queue.shift();
+            if (currentDepth >= upstreamDepth)
+                continue;
+            const inEdges = inboundGraph.get(currentDest) ?? [];
+            for (const edge of inEdges) {
+                const callerDest = edge.source;
+                const callerEntry = destToEntry.get(callerDest);
+                if (!callerEntry)
+                    continue;
+                const relToWorkspace = callerEntry.sourceRelativePath.replace(/\\/g, "/");
+                const matchesStopAt = config.stopAt && config.stopAt.length > 0
+                    ? matchesAnyPattern(relToWorkspace, config.stopAt) ||
+                        matchesAnyPattern(callerDest, config.stopAt)
+                    : false;
+                const outOfScope = config.scope && config.scope.length > 0
+                    ? !(matchesAnyPattern(relToWorkspace, config.scope) ||
+                        matchesAnyPattern(callerDest, config.scope))
+                    : false;
+                const callerCat = nodeCategories.get(callerDest);
+                if (!isCategoryPermitted(callerCat))
+                    continue;
+                if (matchesStopAt || outOfScope) {
+                    boundaryTerminalsSet.add(callerDest);
+                    continue;
+                }
+                if (!seen.has(callerDest)) {
+                    seen.add(callerDest);
+                    upstreamNodesSet.add(callerDest);
+                    lineage.set(callerDest, { parentDest: currentDest, rawRef: edge.rawRef });
+                    queue.push({ dest: callerDest, depth: currentDepth + 1 });
+                }
+            }
+        }
+    };
+    // Traversal 2: Downstream (Outbound references to dependencies / models)
+    const traverseDownstream = (startNodes) => {
+        const queue = startNodes.map((dest) => ({
+            dest,
+            depth: 0,
+        }));
+        const seen = new Set(startNodes);
+        while (queue.length > 0) {
+            const { dest: currentDest, depth: currentDepth } = queue.shift();
+            const currentEntry = destToEntry.get(currentDest);
+            if (!currentEntry)
+                continue;
+            const ext = path.posix.extname(currentDest).toLowerCase();
+            if (!TEXT_EXTENSIONS.has(ext))
+                continue;
+            const content = fileContents.get(currentDest);
+            if (!content)
+                continue;
+            const rawRefs = extractOutboundReferences(content, ext);
+            for (const rawRefWithAngle of rawRefs) {
+                const rawRef = rawRefWithAngle.startsWith("<") && rawRefWithAngle.endsWith(">")
+                    ? rawRefWithAngle.slice(1, -1)
+                    : rawRefWithAngle;
+                const normalizedRef = rawRef.replace(/\\/g, "/");
+                if (normalizedRef.startsWith("#"))
+                    continue;
+                if (!normalizedRef.startsWith("file:") && /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(normalizedRef)) {
+                    continue;
+                }
+                const splitIndex = normalizedRef.search(/[#?]/);
+                const basePath = splitIndex === -1 ? normalizedRef : normalizedRef.slice(0, splitIndex);
+                if (!basePath)
+                    continue;
+                const resolvedAbs = resolveLocalPath(basePath, currentEntry.sourceAbsolutePath, workspaceRoot);
+                if (!resolvedAbs)
+                    continue;
+                const relToWorkspace = path.relative(workspaceRoot, resolvedAbs).replace(/\\/g, "/");
+                const targetDest = sourceAbsToDest.get(resolvedAbs);
+                // Check 1: Terminal boundary patterns (stopAt)
+                const matchesStopAt = config.stopAt && config.stopAt.length > 0
+                    ? matchesAnyPattern(relToWorkspace, config.stopAt) ||
+                        (targetDest ? matchesAnyPattern(targetDest, config.stopAt) : false) ||
+                        matchesAnyPattern(basePath, config.stopAt)
+                    : false;
+                // Check 2: Domain scope boundary (scope)
+                const outOfScope = config.scope && config.scope.length > 0
+                    ? !(matchesAnyPattern(relToWorkspace, config.scope) ||
+                        (targetDest ? matchesAnyPattern(targetDest, config.scope) : false))
+                    : false;
+                // Check 3: Max traversal hop depth
+                const exceedsMaxDepth = currentDepth + 1 > maxDepth;
+                // Check 4: Category filter
+                const targetCat = targetDest ? nodeCategories.get(targetDest) : undefined;
+                const categoryExcluded = !isCategoryPermitted(targetCat);
+                if (matchesStopAt || outOfScope || exceedsMaxDepth || categoryExcluded) {
+                    const terminalTarget = targetDest ?? relToWorkspace;
+                    boundaryTerminalsSet.add(terminalTarget);
+                    const edgeList = boundaryEdges.get(currentDest) ?? [];
+                    if (!edgeList.some((e) => e.target === terminalTarget)) {
+                        edgeList.push({ target: terminalTarget, rawRef });
+                        boundaryEdges.set(currentDest, edgeList);
+                    }
+                    continue;
+                }
+                if (!targetDest) {
+                    boundaryTerminalsSet.add(relToWorkspace);
+                    const edgeList = boundaryEdges.get(currentDest) ?? [];
+                    if (!edgeList.some((e) => e.target === relToWorkspace)) {
+                        edgeList.push({ target: relToWorkspace, rawRef });
+                        boundaryEdges.set(currentDest, edgeList);
+                    }
+                    continue;
+                }
+                if (!seen.has(targetDest)) {
+                    seen.add(targetDest);
+                    downstreamNodesSet.add(targetDest);
+                    lineage.set(targetDest, { parentDest: currentDest, rawRef });
+                    queue.push({ dest: targetDest, depth: currentDepth + 1 });
+                }
+            }
+        }
+    };
+    if (direction === "upstream") {
+        traverseUpstream();
+    }
+    else if (direction === "bidirectional") {
+        traverseUpstream();
+        traverseDownstream([...entrypointDests, ...upstreamNodesSet]);
+    }
+    else {
+        // "downstream" (default)
+        traverseDownstream(entrypointDests);
+    }
+    const visited = new Set([
+        ...entrypointDests,
+        ...upstreamNodesSet,
+        ...downstreamNodesSet,
+    ]);
+    // Partition candidate entries into reachable and eliminated
+    const reachableEntries = new Map();
+    const eliminatedEntries = [];
+    for (const [dest, entry] of entries.entries()) {
+        const isPreserved = traversalMode === "hybrid" ||
+            config.preserveTargets === true ||
+            (config.preserve && config.preserve.length > 0
+                ? matchesAnyPattern(dest, config.preserve) ||
+                    matchesAnyPattern(entry.sourceRelativePath.replace(/\\/g, "/"), config.preserve)
+                : false);
+        const cat = nodeCategories.get(dest);
+        const categoryExcluded = !isCategoryPermitted(cat);
+        if (!categoryExcluded && (visited.has(dest) || isPreserved)) {
+            reachableEntries.set(dest, entry);
+        }
+        else {
+            eliminatedEntries.push(entry);
+        }
+    }
+    return {
+        reachableEntries,
+        eliminatedEntries,
+        warnings,
+        lineage,
+        boundaryTerminals: Array.from(boundaryTerminalsSet),
+        boundaryEdges,
+        upstreamNodes: Array.from(upstreamNodesSet),
+        downstreamNodes: Array.from(downstreamNodesSet),
+        nodeCategories,
+    };
+}
+/**
+ * Traces the provenance chain from an entrypoint down to the given target destination.
+ */
+export function explainReachability(targetDest, lineage, entrypoints, boundaryEdges) {
+    const normTarget = targetDest.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (entrypoints.some((ep) => ep.replace(/\\/g, "/").replace(/^\.\//, "") === normTarget)) {
+        return []; // Is an entrypoint itself
+    }
+    if (lineage.has(normTarget)) {
+        const hops = [];
+        let curr = normTarget;
+        const seen = new Set([curr]);
+        while (lineage.has(curr)) {
+            const edge = lineage.get(curr);
+            hops.unshift({
+                from: edge.parentDest,
+                to: curr,
+                ref: edge.rawRef,
+            });
+            curr = edge.parentDest;
+            if (seen.has(curr))
+                break; // Cycle prevention
+            seen.add(curr);
+        }
+        return hops.length > 0 ? hops : null;
+    }
+    if (boundaryEdges) {
+        for (const [parentDest, terminals] of boundaryEdges.entries()) {
+            const match = terminals.find((t) => t.target === normTarget ||
+                t.target.endsWith(`/${normTarget}`) ||
+                t.rawRef === targetDest);
+            if (match) {
+                const parentHops = explainReachability(parentDest, lineage, entrypoints, boundaryEdges) ?? [];
+                return [
+                    ...parentHops,
+                    {
+                        from: parentDest,
+                        to: match.target,
+                        ref: match.rawRef,
+                    },
+                ];
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Constructs a visual hierarchical dependency tree for bundle inspection.
+ */
+export function buildDependencyTree(entries, config, workspaceRoot) {
+    const { reachableEntries, lineage, boundaryEdges, upstreamNodes, nodeCategories, } = pruneUnreachableEntries(entries, config, workspaceRoot);
+    const upstreamSet = new Set(upstreamNodes ?? []);
+    // Group children by parentDest
+    const parentToChildren = new Map();
+    for (const [childDest, hop] of lineage.entries()) {
+        const list = parentToChildren.get(hop.parentDest) ?? [];
+        list.push(childDest);
+        parentToChildren.set(hop.parentDest, list);
+    }
+    // Build tree nodes recursively
+    const buildNode = (dest, isEntrypoint, visited) => {
+        const entry = reachableEntries.get(dest);
+        const size = entry?.size ?? 0;
+        const childrenDests = parentToChildren.get(dest) ?? [];
+        const children = [];
+        visited.add(dest);
+        for (const child of childrenDests) {
+            if (!visited.has(child)) {
+                children.push(buildNode(child, false, new Set(visited)));
+            }
+        }
+        const terminals = boundaryEdges.get(dest) ?? [];
+        for (const term of terminals) {
+            children.push({
+                path: term.target,
+                size: 0,
+                isEntrypoint: false,
+                isBoundaryTerminal: true,
+                children: [],
+            });
+        }
+        const dir = upstreamSet.has(dest) ? "upstream" : "downstream";
+        const cat = nodeCategories?.get(dest);
+        return {
+            path: dest,
+            size,
+            isEntrypoint,
+            direction: isEntrypoint ? undefined : dir,
+            category: cat,
+            children,
+        };
+    };
+    const trees = [];
+    for (const ep of config.entrypoints) {
+        const cleanEp = ep.replace(/\\/g, "/").replace(/^\.\//, "");
+        let matchedDest = cleanEp;
+        for (const [dest, entry] of entries.entries()) {
+            if (dest === cleanEp ||
+                entry.sourceRelativePath === cleanEp ||
+                entry.sourceAbsolutePath === path.resolve(workspaceRoot, cleanEp)) {
+                matchedDest = dest;
+                break;
+            }
+        }
+        if (reachableEntries.has(matchedDest)) {
+            trees.push(buildNode(matchedDest, true, new Set()));
+        }
+    }
+    return trees;
+}
+/**
+ * Formats a hierarchical dependency tree as human-readable ASCII text.
+ */
+export function renderAsciiTree(nodes, prefix = "") {
+    let output = "";
+    nodes.forEach((node, index) => {
+        const isLast = index === nodes.length - 1;
+        const marker = isLast ? "└── " : "├── ";
+        const nextPrefix = prefix + (isLast ? "    " : "│   ");
+        const sizeFormatted = (node.size / 1024).toFixed(1) + " KB";
+        const entrypointTag = node.isEntrypoint ? " (entrypoint)" : "";
+        const terminalTag = node.isBoundaryTerminal ? " [boundary terminal, not traversed]" : "";
+        const sizeTag = node.isBoundaryTerminal ? "" : ` [${sizeFormatted}]`;
+        const dirTag = node.direction === "upstream" ? " ▲ [UPSTREAM]" : "";
+        const catTag = node.category ? ` [${node.category}]` : "";
+        output += `${prefix}${marker}${node.path}${catTag}${sizeTag}${dirTag}${entrypointTag}${terminalTag}\n`;
+        if (node.children && node.children.length > 0) {
+            output += renderAsciiTree(node.children, nextPrefix);
+        }
+    });
+    return output;
+}
+//# sourceMappingURL=tree-shaker.js.map