@oa-sdk/spec-bundler 0.1.0

package/dist/context-generator.d.ts

@@ -0,0 +1,14 @@
+import type { TopicProfile, ResolvedFileEntry, DocumentCategory } from "./types.js";
+export interface ContextGeneratorOptions {
+    boundaryTerminals?: string[];
+    upstreamNodes?: string[];
+    nodeCategories?: Map<string, DocumentCategory>;
+}
+/**
+ * Automatically synthesizes a standardized CONTEXT.md file at the bundle root
+ * summarizing the topic's objectives, boundaries, ambient background context,
+ * directional mode (downstream/upstream/bidirectional), and categorized file index.
+ * Supports custom templates via context.template with macro token substitution.
+ */
+export declare function generateTopicContextMarkdown(topicName: string, profile: TopicProfile, files: ResolvedFileEntry[], boundaryTerminalsOrOptions?: string[] | ContextGeneratorOptions): string;
+//# sourceMappingURL=context-generator.d.ts.map

package/dist/context-generator.js

@@ -0,0 +1,297 @@
+import { parseDocumentCategory } from "./category-parser.js";
+import fs from "node:fs";
+const CODE_FENCE = "```";
+/**
+ * Automatically synthesizes a standardized CONTEXT.md file at the bundle root
+ * summarizing the topic's objectives, boundaries, ambient background context,
+ * directional mode (downstream/upstream/bidirectional), and categorized file index.
+ * Supports custom templates via context.template with macro token substitution.
+ */
+export function generateTopicContextMarkdown(topicName, profile, files, boundaryTerminalsOrOptions = []) {
+    const options = Array.isArray(boundaryTerminalsOrOptions)
+        ? { boundaryTerminals: boundaryTerminalsOrOptions }
+        : boundaryTerminalsOrOptions;
+    const boundaryTerminals = options.boundaryTerminals ?? [];
+    const upstreamNodes = new Set(options.upstreamNodes ?? []);
+    const nodeCategories = options.nodeCategories ?? new Map();
+    const context = profile.context ?? {};
+    const scope = profile.scope ?? profile.treeShake ?? { entrypoints: [] };
+    const direction = scope.direction ?? "downstream";
+    // 1. Header & Title
+    const title = context.description || profile.description || `Topic Context: ${topicName}`;
+    // 2. Phase Badge
+    const phaseLabels = {
+        develop: "`🛠️ Development` (Feature Implementation)",
+        fix: "`🐛 Bugfix & Refactoring` (Targeted Fix & Upstream Coordination)",
+        test: "`🧪 Testing & QA` (Contract & Error Invariant Verification)",
+        review: "`🔍 Architecture & Peer Review` (Compact System Briefing)",
+    };
+    const phaseBadge = profile.phase ? phaseLabels[profile.phase] ?? `\`${profile.phase}\`` : "";
+    // 3. Metadata lines
+    const metadataLines = [];
+    metadataLines.push(`- **Topic Identifier**: \`${topicName}\``);
+    if (profile.phase) {
+        metadataLines.push(`- **Work Phase**: ${phaseLabels[profile.phase] ?? `\`${profile.phase}\``}`);
+    }
+    if (profile.author) {
+        metadataLines.push(`- **Initial Author / Worker**: \`${profile.author}\``);
+    }
+    if (context.domain) {
+        metadataLines.push(`- **Domain**: \`${context.domain}\``);
+    }
+    if (context.issue) {
+        metadataLines.push(`- **Target Issue / Ticket**: \`${context.issue}\``);
+    }
+    if (context.persona) {
+        metadataLines.push(`- **Target Role / Persona**: \`${context.persona}\``);
+    }
+    if (context.tags && context.tags.length > 0) {
+        metadataLines.push(`- **Tags**: ${context.tags.map((t) => `\`${t}\``).join(", ")}`);
+    }
+    if (context.prerequisites && context.prerequisites.length > 0) {
+        metadataLines.push(`- **Prerequisites**: ${context.prerequisites.map((p) => `\`${p}\``).join(", ")}`);
+    }
+    if (context.metadata && Object.keys(context.metadata).length > 0) {
+        for (const [k, v] of Object.entries(context.metadata)) {
+            metadataLines.push(`- **${k}**: \`${JSON.stringify(v)}\``);
+        }
+    }
+    const metadataSection = metadataLines.join("\n");
+    // 4. Instructions
+    const instructionLines = [];
+    if (profile.phase === "fix") {
+        instructionLines.push("> [!IMPORTANT]");
+        instructionLines.push("> **Bugfix & Modification Slice (Preserve Upstream Caller Contracts)**: Crafted for targeted bug resolution with upstream consumer coordination. Review upstream contracts before altering behavior.");
+    }
+    else if (profile.phase === "test") {
+        instructionLines.push("> [!TIP]");
+        instructionLines.push("> **Testing & QA Slice (Verification & Acceptance Invariants)**: Focused on acceptance criteria, contract guarantees, and error catalogs for deterministic verification.");
+    }
+    else if (profile.phase === "review") {
+        instructionLines.push("> [!NOTE]");
+        instructionLines.push("> **Review Slice (High-Level Review Contract)**: Condensed contract and architectural summary tailored for efficient PR/RFC evaluation without implementation bloat.");
+    }
+    if (context.prompt) {
+        if (instructionLines.length > 0)
+            instructionLines.push("");
+        instructionLines.push("> [!NOTE]");
+        instructionLines.push(`> ${context.prompt.replace(/\r?\n/g, "\n> ")}`);
+    }
+    const instructionsSection = instructionLines.join("\n");
+    // 5. Scope & Direction
+    const scopeLines = [];
+    const entrypoints = scope.entrypoints ?? [];
+    if (entrypoints.length > 0) {
+        scopeLines.push(`- **Entrypoint(s)**: ${entrypoints.map((e) => `\`${e}\``).join(", ")}`);
+    }
+    scopeLines.push(`- **Traversal Direction**: \`${direction}\``);
+    if (direction === "upstream" || direction === "bidirectional") {
+        scopeLines.push(`  - *Upstream Hop Depth*: ${scope.upstreamDepth ?? 1} (parent consumer / governing contracts)`);
+    }
+    if (scope.include && scope.include.length > 0) {
+        scopeLines.push(`- **Domain Scope (include)**: ${scope.include.map((i) => `\`${i}\``).join(", ")}`);
+    }
+    if (scope.stopAt && scope.stopAt.length > 0) {
+        scopeLines.push(`- **Boundary Stops (stopAt)**: ${scope.stopAt.map((s) => `\`${s}\``).join(", ")}`);
+    }
+    if (scope.maxDepth !== undefined) {
+        scopeLines.push(`- **Maximum Traversal Depth**: ${scope.maxDepth} hop(s)`);
+    }
+    if (scope.sections && scope.sections.length > 0) {
+        scopeLines.push(`- **Section Slices**: ${scope.sections.map((s) => `\`${s}\``).join(", ")}`);
+    }
+    if (scope.includeCategories && scope.includeCategories.length > 0) {
+        scopeLines.push(`- **Allowed Categories**: ${scope.includeCategories.map((c) => `\`${c}\``).join(", ")}`);
+    }
+    if (scope.excludeCategories && scope.excludeCategories.length > 0) {
+        scopeLines.push(`- **Excluded Categories**: ${scope.excludeCategories.map((c) => `\`${c}\``).join(", ")}`);
+    }
+    const scopeSection = scopeLines.join("\n");
+    // 6. Partition files into categories
+    const contextFiles = [];
+    const upstreamFiles = [];
+    const categorized = {
+        feature: [],
+        mechanism: [],
+        error: [],
+        issue: [],
+        convention: [],
+    };
+    for (const f of files) {
+        if (f.bundleDestPath === "CONTEXT.md")
+            continue;
+        if (f.bundleDestPath.startsWith("context/") || f.bundleDestPath.startsWith("_context/")) {
+            contextFiles.push(f);
+            continue;
+        }
+        if (upstreamNodes.has(f.bundleDestPath)) {
+            upstreamFiles.push(f);
+            continue;
+        }
+        let cat = nodeCategories.get(f.bundleDestPath);
+        if (!cat) {
+            try {
+                const raw = fs.readFileSync(f.sourceAbsolutePath, "utf8");
+                cat = parseDocumentCategory(raw, f.sourceAbsolutePath);
+            }
+            catch {
+                cat = "feature";
+            }
+        }
+        categorized[cat].push(f);
+    }
+    // 7. Spec Index sections
+    const indexLines = [];
+    if (upstreamFiles.length > 0) {
+        indexLines.push("## Upstream Consumers & Coordinating Contracts");
+        indexLines.push("");
+        indexLines.push("> [!IMPORTANT]\n> The following parent/caller contracts reference this slice. Review these for compatibility and contract alignment.");
+        indexLines.push("");
+        for (const f of upstreamFiles) {
+            indexLines.push(`- [${f.bundleDestPath}](./${f.bundleDestPath}) (${(f.size / 1024).toFixed(1)} KB)`);
+        }
+        indexLines.push("");
+    }
+    if (categorized.feature.length > 0) {
+        indexLines.push("## Bundled Specifications Index");
+        indexLines.push("");
+        for (const f of categorized.feature) {
+            indexLines.push(`- [${f.bundleDestPath}](./${f.bundleDestPath}) (${(f.size / 1024).toFixed(1)} KB)`);
+        }
+        indexLines.push("");
+    }
+    if (categorized.mechanism.length > 0) {
+        indexLines.push("## Implementation Mechanisms & Behavioral Contracts (HOW)");
+        indexLines.push("");
+        for (const f of categorized.mechanism) {
+            indexLines.push(`- [${f.bundleDestPath}](./${f.bundleDestPath}) (${(f.size / 1024).toFixed(1)} KB)`);
+        }
+        indexLines.push("");
+    }
+    if (categorized.error.length > 0) {
+        indexLines.push("## Error Scenarios & Failure Catalogs (FAILURE)");
+        indexLines.push("");
+        for (const f of categorized.error) {
+            indexLines.push(`- [${f.bundleDestPath}](./${f.bundleDestPath}) (${(f.size / 1024).toFixed(1)} KB)`);
+        }
+        indexLines.push("");
+    }
+    if (categorized.convention.length > 0) {
+        indexLines.push("## Architectural & Specification Conventions (RULE)");
+        indexLines.push("");
+        for (const f of categorized.convention) {
+            indexLines.push(`- [${f.bundleDestPath}](./${f.bundleDestPath}) (${(f.size / 1024).toFixed(1)} KB)`);
+        }
+        indexLines.push("");
+    }
+    if (categorized.issue.length > 0) {
+        indexLines.push("## Issues & Historical Context (WHY)");
+        indexLines.push("");
+        for (const f of categorized.issue) {
+            indexLines.push(`- [${f.bundleDestPath}](./${f.bundleDestPath}) (${(f.size / 1024).toFixed(1)} KB)`);
+        }
+        indexLines.push("");
+    }
+    if (contextFiles.length > 0) {
+        indexLines.push("## Ambient Background Context Documents");
+        indexLines.push("");
+        for (const f of contextFiles) {
+            indexLines.push(`- [${f.bundleDestPath}](./${f.bundleDestPath}) (${(f.size / 1024).toFixed(1)} KB)`);
+        }
+        indexLines.push("");
+    }
+    if (boundaryTerminals.length > 0) {
+        indexLines.push("## Terminal Boundary References (Unbundled Leaves)");
+        indexLines.push("");
+        indexLines.push("The following cross-cutting references were deliberately halted at the topic boundary to prevent transitive repository graph explosion:");
+        indexLines.push("");
+        for (const b of boundaryTerminals) {
+            indexLines.push(`- \`${b}\` *(boundary terminal, not traversed)*`);
+        }
+        indexLines.push("");
+    }
+    const specIndexSection = indexLines.join("\n");
+    // 8. Synthesis Guide
+    const hasTypeSpec = files.some((f) => f.bundleDestPath.endsWith(".tsp") ||
+        f.sourceAbsolutePath.endsWith(".tsp") ||
+        f.sourceRelativePath.endsWith(".tsp"));
+    let synthesisGuideSection = "";
+    if (hasTypeSpec) {
+        const guideLines = [
+            "## Downstream Code Synthesis & DTO Generation (TypeSpec SSOT)",
+            "",
+            "This bundle contains pure TypeSpec (`.tsp`) contract definitions with `@evidence` bindings. Downstream consumer teams can synthesize type-safe DTOs and client SDKs directly without manually writing boilerplate:",
+            "",
+            `${CODE_FENCE}bash`,
+            "# 1. Emit OpenAPI 3.1 enriched with x-samchon-evidence metadata",
+            "tsp-evidence emit --openapi openapi.json --specs specs/**/*.tsp",
+            "",
+            "# 2. Synthesize TypeScript DTOs with verified @evidence annotations",
+            "tsp-evidence synthesize --openapi openapi.json --out-dir src/generated",
+            "",
+            "# 3. Compile or generate polyglot models (Python, Java, Go, OpenAPI generator)",
+            "tsp compile . --emit @typespec/openapi3",
+            CODE_FENCE,
+            "",
+        ];
+        synthesisGuideSection = guideLines.join("\n");
+    }
+    // 9. Custom Template Support
+    if (context.template) {
+        let templateText;
+        if (fs.existsSync(context.template)) {
+            templateText = fs.readFileSync(context.template, "utf8");
+        }
+        else {
+            templateText = context.template;
+        }
+        const replacements = {
+            "{{TITLE}}": title,
+            "{{TOPIC_NAME}}": topicName,
+            "{{DESCRIPTION}}": profile.description ?? "",
+            "{{PHASE_BADGE}}": phaseBadge,
+            "{{METADATA}}": metadataSection,
+            "{{INSTRUCTIONS}}": instructionsSection,
+            "{{SCOPE}}": scopeSection,
+            "{{SPEC_INDEX}}": specIndexSection,
+            "{{SYNTHESIS_GUIDE}}": synthesisGuideSection,
+            "{{DATE}}": new Date().toISOString().split("T")[0],
+            "{{FILE_COUNT}}": String(files.length),
+        };
+        let rendered = templateText;
+        for (const [placeholder, val] of Object.entries(replacements)) {
+            rendered = rendered.split(placeholder).join(val);
+        }
+        return rendered;
+    }
+    // 10. Default Standard Markdown Synthesis
+    const defaultLines = [];
+    defaultLines.push(`# ${title}`);
+    defaultLines.push("");
+    if (profile.description) {
+        defaultLines.push(profile.description);
+        defaultLines.push("");
+    }
+    defaultLines.push("## Topic Metadata");
+    defaultLines.push("");
+    defaultLines.push(metadataSection);
+    defaultLines.push("");
+    if (instructionsSection.length > 0) {
+        defaultLines.push("## Agent Instructions & Guidance");
+        defaultLines.push("");
+        defaultLines.push(instructionsSection);
+        defaultLines.push("");
+    }
+    defaultLines.push("## Extraction Scope & Directionality");
+    defaultLines.push("");
+    defaultLines.push(scopeSection);
+    defaultLines.push("");
+    if (specIndexSection.length > 0) {
+        defaultLines.push(specIndexSection);
+    }
+    if (synthesisGuideSection.length > 0) {
+        defaultLines.push(synthesisGuideSection);
+    }
+    return defaultLines.join("\n");
+}
+//# sourceMappingURL=context-generator.js.map

package/dist/freshness.d.ts

@@ -0,0 +1,41 @@
+import type { BundleLockfile, BundleManifest, FreshnessResult, LockfileMode, ResolvedFileEntry, SemanticDriftReport } from "./types.js";
+/**
+ * Calculates a deterministic master aggregate hash across all resolved file entries.
+ */
+export declare function calculateAggregateHash(entries: ResolvedFileEntry[]): string;
+/**
+ * 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 declare function getLockfilePath(manifestPath: string, topic?: string, lockfileMode?: LockfileMode): string;
+/**
+ * Reads and parses an existing lockfile. Returns null if missing or invalid.
+ */
+export declare function readLockfile(lockfilePath: string): BundleLockfile | null;
+/**
+ * Generates an in-memory lockfile object without disk mutation.
+ */
+export declare function generateLockfileData(manifest: BundleManifest, entries: ResolvedFileEntry[], generatedAt?: string): BundleLockfile;
+/**
+ * Writes a formatted lockfile to disk.
+ * If writing in consolidated mode with a topic, updates the topic entry inside bundle.manifest.lock.json.
+ */
+export declare function writeLockfile(lockfilePath: string, manifest: BundleManifest, entries: ResolvedFileEntry[], options?: {
+    topic?: string;
+    lockfileMode?: LockfileMode;
+}): BundleLockfile;
+/**
+ * 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 declare function checkFreshness(manifest: BundleManifest, baseDir: string, lockfilePath: string, options?: {
+    topic?: string;
+    diff?: boolean;
+    lockfileMode?: LockfileMode;
+}): FreshnessResult;
+/**
+ * Computes semantic structural diff between source files on disk and the built bundle/lockfile.
+ * Detects modified anchors in Markdown and symbols in TypeSpec.
+ */
+export declare function computeSemanticDiff(manifest: BundleManifest, baseDir: string, currentEntries: ResolvedFileEntry[], lockfile: BundleLockfile | null, topic?: string): SemanticDriftReport;
+//# sourceMappingURL=freshness.d.ts.map