@oa-sdk/spec-bundler 0.1.0

package/dist/freshness.js

@@ -0,0 +1,365 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { resolveBundleTargets } from "./resolver.js";
+import { pruneUnreachableEntries } from "./tree-shaker.js";
+import { extractDocumentAnchors } from "./link-rewriter.js";
+import { readZipArchive } from "./archiver.js";
+/**
+ * Calculates a deterministic master aggregate hash across all resolved file entries.
+ */
+export function calculateAggregateHash(entries) {
+    const sorted = [...entries].sort((a, b) => a.bundleDestPath.localeCompare(b.bundleDestPath));
+    const hash = crypto.createHash("sha256");
+    for (const entry of sorted) {
+        hash.update(`${entry.bundleDestPath}:${entry.sha256}:${entry.size}\n`);
+    }
+    return hash.digest("hex");
+}
+/**
+ * Returns the lockfile path corresponding to a manifest file and optional topic profile.
+ * Supports consolidated lockfile mode (bundle.manifest.lock.json) or split topic lockfiles.
+ */
+export function getLockfilePath(manifestPath, topic, lockfileMode) {
+    const dir = path.dirname(manifestPath);
+    let base = path.basename(manifestPath);
+    if (base.endsWith(".lock.json")) {
+        base = base.slice(0, -".lock.json".length);
+    }
+    else if (base.endsWith(".json")) {
+        base = base.slice(0, -".json".length);
+    }
+    if (topic && base.endsWith(`.${topic}`)) {
+        base = base.slice(0, -(`.${topic}`.length));
+    }
+    if (lockfileMode === "consolidated") {
+        return path.join(dir, `${base}.lock.json`);
+    }
+    const topicSuffix = topic ? `.${topic}` : "";
+    return path.join(dir, `${base}${topicSuffix}.lock.json`);
+}
+/**
+ * Reads and parses an existing lockfile. Returns null if missing or invalid.
+ */
+export function readLockfile(lockfilePath) {
+    if (!fs.existsSync(lockfilePath))
+        return null;
+    try {
+        const raw = fs.readFileSync(lockfilePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Generates an in-memory lockfile object without disk mutation.
+ */
+export function generateLockfileData(manifest, entries, generatedAt) {
+    const aggregateHash = calculateAggregateHash(entries);
+    let totalSizeBytes = 0;
+    const entriesMap = {};
+    for (const entry of entries) {
+        totalSizeBytes += entry.size;
+        entriesMap[entry.bundleDestPath] = {
+            source: entry.sourceRelativePath,
+            sha256: entry.sha256,
+            size: entry.size,
+            mtime: entry.mtime,
+        };
+    }
+    return {
+        manifestVersion: manifest.version,
+        bundleName: manifest.name,
+        generatedAt: generatedAt ?? new Date().toISOString(),
+        aggregateHash,
+        filesCount: entries.length,
+        totalSizeBytes,
+        entries: entriesMap,
+    };
+}
+/**
+ * Writes a formatted lockfile to disk.
+ * If writing in consolidated mode with a topic, updates the topic entry inside bundle.manifest.lock.json.
+ */
+export function writeLockfile(lockfilePath, manifest, entries, options) {
+    const mode = options?.lockfileMode ?? manifest.lockfileMode;
+    const topic = options?.topic;
+    if (mode === "consolidated" && topic) {
+        const consolidatedPath = getLockfilePath(lockfilePath, undefined, "consolidated");
+        let rootLockfile = readLockfile(consolidatedPath);
+        if (!rootLockfile) {
+            rootLockfile = {
+                manifestVersion: manifest.version,
+                bundleName: manifest.name.split(":")[0],
+                generatedAt: new Date().toISOString(),
+                aggregateHash: "",
+                filesCount: 0,
+                totalSizeBytes: 0,
+                entries: {},
+                topics: {},
+            };
+        }
+        if (!rootLockfile.topics) {
+            rootLockfile.topics = {};
+        }
+        const topicAggregateHash = calculateAggregateHash(entries);
+        let totalSizeBytes = 0;
+        const entriesMap = {};
+        for (const entry of entries) {
+            totalSizeBytes += entry.size;
+            entriesMap[entry.bundleDestPath] = {
+                source: entry.sourceRelativePath,
+                sha256: entry.sha256,
+                size: entry.size,
+                mtime: entry.mtime,
+            };
+        }
+        rootLockfile.topics[topic] = {
+            generatedAt: new Date().toISOString(),
+            aggregateHash: topicAggregateHash,
+            filesCount: entries.length,
+            totalSizeBytes,
+            entries: entriesMap,
+        };
+        fs.mkdirSync(path.dirname(consolidatedPath), { recursive: true });
+        fs.writeFileSync(consolidatedPath, JSON.stringify(rootLockfile, null, 2), "utf8");
+        return { ...rootLockfile, aggregateHash: topicAggregateHash };
+    }
+    const lockfile = generateLockfileData(manifest, entries);
+    fs.mkdirSync(path.dirname(lockfilePath), { recursive: true });
+    fs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2), "utf8");
+    return lockfile;
+}
+/**
+ * Evaluates whether the bundle is fresh or has drifted compared to the lockfile and output file.
+ * Supports consolidated lockfile reading and semantic structural diff computing.
+ */
+export function checkFreshness(manifest, baseDir, lockfilePath, options) {
+    let { entries: currentMap } = resolveBundleTargets(manifest, baseDir);
+    if (manifest.treeShake?.enabled) {
+        const treeShakeResult = pruneUnreachableEntries(currentMap, manifest.treeShake, baseDir);
+        currentMap = treeShakeResult.reachableEntries;
+    }
+    const currentEntries = Array.from(currentMap.values());
+    const currentAggregateHash = calculateAggregateHash(currentEntries);
+    const topic = options?.topic;
+    let lockfile = readLockfile(lockfilePath);
+    // If topic specified and topic-specific lockfile was not found or lacks entries, check consolidated lockfile
+    if ((!lockfile || !lockfile.entries || Object.keys(lockfile.entries).length === 0) && topic) {
+        const consolidatedPath = getLockfilePath(lockfilePath, undefined, "consolidated");
+        const consolidatedLock = readLockfile(consolidatedPath);
+        if (consolidatedLock?.topics?.[topic]) {
+            lockfile = {
+                manifestVersion: consolidatedLock.manifestVersion,
+                bundleName: `${consolidatedLock.bundleName}:${topic}`,
+                generatedAt: consolidatedLock.topics[topic].generatedAt,
+                aggregateHash: consolidatedLock.topics[topic].aggregateHash,
+                filesCount: consolidatedLock.topics[topic].filesCount,
+                totalSizeBytes: consolidatedLock.topics[topic].totalSizeBytes,
+                entries: consolidatedLock.topics[topic].entries,
+            };
+        }
+    }
+    else if (topic && lockfile?.topics?.[topic]) {
+        const topicData = lockfile.topics[topic];
+        lockfile = {
+            manifestVersion: lockfile.manifestVersion,
+            bundleName: `${lockfile.bundleName}:${topic}`,
+            generatedAt: topicData.generatedAt,
+            aggregateHash: topicData.aggregateHash,
+            filesCount: topicData.filesCount,
+            totalSizeBytes: topicData.totalSizeBytes,
+            entries: topicData.entries,
+        };
+    }
+    if (!lockfile) {
+        const result = {
+            isFresh: false,
+            currentAggregateHash,
+            lockAggregateHash: undefined,
+            added: Array.from(currentMap.keys()),
+            removed: [],
+            modified: [],
+        };
+        if (options?.diff) {
+            result.semanticDiff = computeSemanticDiff(manifest, baseDir, currentEntries, null, topic);
+        }
+        return result;
+    }
+    const added = [];
+    const removed = [];
+    const modified = [];
+    const lockKeys = new Set(Object.keys(lockfile.entries));
+    const currentKeys = new Set(currentMap.keys());
+    for (const key of currentKeys) {
+        if (!lockKeys.has(key)) {
+            added.push(key);
+        }
+        else {
+            const lockEntry = lockfile.entries[key];
+            const currentEntry = currentMap.get(key);
+            if (lockEntry.sha256 !== currentEntry.sha256) {
+                modified.push(key);
+            }
+        }
+    }
+    for (const key of lockKeys) {
+        if (!currentKeys.has(key)) {
+            removed.push(key);
+        }
+    }
+    const outputPath = path.resolve(baseDir, manifest.output);
+    const outputExists = fs.existsSync(outputPath);
+    const isFresh = outputExists &&
+        currentAggregateHash === lockfile.aggregateHash &&
+        added.length === 0 &&
+        removed.length === 0 &&
+        modified.length === 0;
+    const result = {
+        isFresh,
+        currentAggregateHash,
+        lockAggregateHash: lockfile.aggregateHash,
+        added,
+        removed,
+        modified,
+    };
+    if (options?.diff && !isFresh) {
+        result.semanticDiff = computeSemanticDiff(manifest, baseDir, currentEntries, lockfile, topic);
+    }
+    return result;
+}
+/**
+ * Computes semantic structural diff between source files on disk and the built bundle/lockfile.
+ * Detects modified anchors in Markdown and symbols in TypeSpec.
+ */
+export function computeSemanticDiff(manifest, baseDir, currentEntries, lockfile, topic) {
+    const currentMap = new Map(currentEntries.map((e) => [e.bundleDestPath, e]));
+    let lockEntries = {};
+    if (lockfile) {
+        if (topic && lockfile.topics?.[topic]) {
+            lockEntries = lockfile.topics[topic].entries;
+        }
+        else {
+            lockEntries = lockfile.entries ?? {};
+        }
+    }
+    const currentKeys = new Set(currentMap.keys());
+    const lockKeys = new Set(Object.keys(lockEntries));
+    const addedFiles = [];
+    const removedFiles = [];
+    const modifiedFiles = [];
+    for (const key of currentKeys) {
+        if (!lockKeys.has(key)) {
+            addedFiles.push(key);
+        }
+        else if (lockEntries[key].sha256 !== currentMap.get(key).sha256) {
+            const entry = currentMap.get(key);
+            const diff = analyzeFileStructuralDiff(entry, baseDir, manifest);
+            modifiedFiles.push(diff);
+        }
+    }
+    for (const key of lockKeys) {
+        if (!currentKeys.has(key)) {
+            removedFiles.push(key);
+        }
+    }
+    return {
+        addedFiles,
+        removedFiles,
+        modifiedFiles,
+    };
+}
+function analyzeFileStructuralDiff(currentEntry, baseDir, manifest) {
+    const ext = path.extname(currentEntry.sourceAbsolutePath).toLowerCase();
+    let currentContent = "";
+    try {
+        currentContent = fs.readFileSync(currentEntry.sourceAbsolutePath, "utf8");
+    }
+    catch { }
+    let previousContent = null;
+    const outputPath = path.resolve(baseDir, manifest.output);
+    if (fs.existsSync(outputPath)) {
+        if (manifest.format === "directory" || !manifest.output.endsWith(".zip")) {
+            const prevFilePath = path.join(outputPath, currentEntry.bundleDestPath);
+            if (fs.existsSync(prevFilePath)) {
+                try {
+                    previousContent = fs.readFileSync(prevFilePath, "utf8");
+                }
+                catch { }
+            }
+        }
+        else {
+            try {
+                const zipBuffer = fs.readFileSync(outputPath);
+                const archive = readZipArchive(zipBuffer);
+                const fileBuffer = archive.get(currentEntry.bundleDestPath);
+                if (fileBuffer) {
+                    previousContent = fileBuffer.toString("utf8");
+                }
+            }
+            catch { }
+        }
+    }
+    if (ext === ".md" || ext === ".mdx") {
+        const currentAnchorSet = extractDocumentAnchors(currentContent);
+        const currentAnchors = Array.from(currentAnchorSet.explicit.size > 0
+            ? currentAnchorSet.explicit
+            : currentAnchorSet.slugs);
+        const prevAnchorSet = previousContent !== null ? extractDocumentAnchors(previousContent) : null;
+        const prevAnchors = prevAnchorSet
+            ? Array.from(prevAnchorSet.explicit.size > 0
+                ? prevAnchorSet.explicit
+                : prevAnchorSet.slugs)
+            : [];
+        const addedAnchors = currentAnchors.filter((a) => !prevAnchors.includes(a));
+        const removedAnchors = prevAnchors.filter((a) => !currentAnchors.includes(a));
+        const lineDelta = previousContent !== null
+            ? currentContent.split("\n").length -
+                previousContent.split("\n").length
+            : undefined;
+        return {
+            file: currentEntry.bundleDestPath,
+            type: "markdown",
+            addedAnchors: addedAnchors.length > 0 ? addedAnchors : undefined,
+            removedAnchors: removedAnchors.length > 0 ? removedAnchors : undefined,
+            lineDelta,
+        };
+    }
+    if (ext === ".tsp") {
+        const extractSymbols = (code) => {
+            const symbols = [];
+            const regex = /(?:model|scalar|interface|enum|op)\s+([A-Za-z0-9_]+)/g;
+            let m;
+            while ((m = regex.exec(code)) !== null) {
+                symbols.push(m[1]);
+            }
+            return symbols;
+        };
+        const currentSymbols = extractSymbols(currentContent);
+        const prevSymbols = previousContent !== null ? extractSymbols(previousContent) : [];
+        const addedSymbols = currentSymbols.filter((s) => !prevSymbols.includes(s));
+        const removedSymbols = prevSymbols.filter((s) => !currentSymbols.includes(s));
+        const lineDelta = previousContent !== null
+            ? currentContent.split("\n").length -
+                previousContent.split("\n").length
+            : undefined;
+        return {
+            file: currentEntry.bundleDestPath,
+            type: "typespec",
+            addedSymbols: addedSymbols.length > 0 ? addedSymbols : undefined,
+            removedSymbols: removedSymbols.length > 0 ? removedSymbols : undefined,
+            lineDelta,
+        };
+    }
+    const lineDelta = previousContent !== null
+        ? currentContent.split("\n").length -
+            previousContent.split("\n").length
+        : undefined;
+    return {
+        file: currentEntry.bundleDestPath,
+        type: "other",
+        lineDelta,
+    };
+}
+//# sourceMappingURL=freshness.js.map

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import type { BundleManifest, FreshnessResult, LinkDiagnostic, PackResult, BundlePathResolution } from "./types.js";
+import type { PackOptions, DependencyTreeNode, ReachabilityHop, DocumentCategory } from "./types.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 declare function loadManifest(manifestPath: string): BundleManifest;
+/**
+ * Executes packaging: target resolution, deduplication, markdown link rewriting,
+ * ZIP creation, and lockfile synchronization. Supports dryRun preview.
+ */
+export declare function createBundle(manifestPath: string, options?: PackOptions): PackResult;
+/**
+ * Inspects a bundle manifest, returning its dependency reachability tree, size breakdown,
+ * and provenance lineage for all files.
+ */
+export declare function inspectBundle(manifestPath: string, options?: {
+    topic?: string;
+}): {
+    manifest: BundleManifest;
+    tree: DependencyTreeNode[];
+    asciiTree: string;
+    reachableCount: number;
+    eliminatedCount: number;
+    totalSizeBytes: number;
+    warnings: string[];
+    lineage: Map<string, ReachabilityHop>;
+    boundaryTerminals?: string[];
+    boundaryEdges?: Map<string, Array<{
+        target: string;
+        rawRef: string;
+    }>>;
+    upstreamNodes?: string[];
+    nodeCategories?: Map<string, DocumentCategory>;
+};
+/**
+ * Verifies integrity, dead links, and drift for a manifest without packaging.
+ */
+export declare function verifyBundle(manifestPath: string, options?: {
+    checkAnchors?: boolean;
+    topic?: string;
+}): {
+    freshness: FreshnessResult;
+    deadLinks: LinkDiagnostic[];
+    warnings: string[];
+};
+/**
+ * Extracts an archive file into target destination directory.
+ */
+export declare function unpackBundle(archivePath: string, destDir: string): {
+    extractedCount: number;
+    files: string[];
+};
+/**
+ * Resolves a source path, relative reference, or TypeSpec citation to its
+ * exact coordinate within a packaged bundle archive or extracted directory.
+ */
+export declare function resolveBundlePath(archiveInput: string | Buffer, queryReference: string, options?: {
+    baseDir?: string;
+}): BundlePathResolution;
+//# sourceMappingURL=index.d.ts.map