@oa-sdk/spec-bundler 0.1.0

package/dist/section-slicer.d.ts

@@ -0,0 +1,12 @@
+export interface SectionSliceResult {
+    sliced: string;
+    matchedSections: string[];
+    isSliced: boolean;
+}
+/**
+ * Extracts and slices markdown documents by section heading patterns,
+ * preserving document frontmatter and root header while eliminating unreferenced sections.
+ * Automatically retains child sub-headings of matched sections.
+ */
+export declare function sliceMarkdownBySections(content: string, sectionPatterns: string[]): SectionSliceResult;
+//# sourceMappingURL=section-slicer.d.ts.map

package/dist/section-slicer.js

@@ -0,0 +1,114 @@
+import { matchesAnyPattern } from "./resolver.js";
+function parseMarkdownTree(body) {
+    const lines = body.split(/\r?\n/);
+    const leadingLines = [];
+    const rootNodes = [];
+    const stack = [];
+    let isFirstHeading = true;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = line.match(/^(#{1,6})\s+(.+)$/);
+        if (match) {
+            const level = match[1].length;
+            const rawTitle = match[2].trim();
+            const cleanTitle = rawTitle.replace(/\s*\{#[^}]+\}\s*$/, "").trim();
+            // Top-level document title (# Title) at the start is preserved as preamble
+            if (level === 1 && isFirstHeading) {
+                leadingLines.push(line);
+                isFirstHeading = false;
+                continue;
+            }
+            isFirstHeading = false;
+            const newNode = {
+                level,
+                title: cleanTitle,
+                lines: [line],
+                children: [],
+            };
+            // Pop stack until parent has level < newNode.level
+            while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+                stack.pop();
+            }
+            if (stack.length === 0) {
+                rootNodes.push(newNode);
+            }
+            else {
+                stack[stack.length - 1].children.push(newNode);
+            }
+            stack.push(newNode);
+        }
+        else {
+            if (stack.length > 0) {
+                stack[stack.length - 1].lines.push(line);
+            }
+            else {
+                leadingLines.push(line);
+            }
+        }
+    }
+    return { preamble: leadingLines.join("\n").trim(), rootNodes };
+}
+function renderSectionNode(node) {
+    const parts = [node.lines.join("\n")];
+    for (const child of node.children) {
+        parts.push(renderSectionNode(child));
+    }
+    return parts.join("\n\n");
+}
+function filterMatchingSections(nodes, patterns, matchedSections) {
+    const result = [];
+    for (const node of nodes) {
+        const isMatched = matchesAnyPattern(node.title, patterns) ||
+            patterns.some((p) => node.title.toLowerCase() === p.toLowerCase() ||
+                node.title.toLowerCase().startsWith(p.toLowerCase().replace(/\*+$/, "")));
+        if (isMatched) {
+            matchedSections.push(node.title);
+            result.push(renderSectionNode(node));
+        }
+        else {
+            // Check if any child matches
+            const childResults = filterMatchingSections(node.children, patterns, matchedSections);
+            result.push(...childResults);
+        }
+    }
+    return result;
+}
+/**
+ * Extracts and slices markdown documents by section heading patterns,
+ * preserving document frontmatter and root header while eliminating unreferenced sections.
+ * Automatically retains child sub-headings of matched sections.
+ */
+export function sliceMarkdownBySections(content, sectionPatterns) {
+    if (!sectionPatterns || sectionPatterns.length === 0) {
+        return { sliced: content, matchedSections: [], isSliced: false };
+    }
+    // 1. Separate frontmatter
+    const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    const frontmatter = frontmatterMatch ? frontmatterMatch[0] : "";
+    const body = content.slice(frontmatter.length);
+    // 2. Parse hierarchical heading tree
+    const { preamble, rootNodes } = parseMarkdownTree(body);
+    // 3. Filter sections that match patterns
+    const matchedSections = [];
+    const keptSections = filterMatchingSections(rootNodes, sectionPatterns, matchedSections);
+    // If no sections matched patterns, preserve original document intact
+    if (matchedSections.length === 0) {
+        return { sliced: content, matchedSections: [], isSliced: false };
+    }
+    const parts = [];
+    if (frontmatter) {
+        parts.push(frontmatter.trim());
+    }
+    if (preamble) {
+        parts.push(preamble);
+    }
+    if (keptSections.length > 0) {
+        parts.push(keptSections.join("\n\n"));
+    }
+    return {
+        sliced: parts.join("\n\n") + "\n",
+        matchedSections,
+        isSliced: true,
+    };
+}
+//# sourceMappingURL=section-slicer.js.map

package/dist/topic.d.ts

@@ -0,0 +1,62 @@
+import type { BundleManifest, TopicProfile, TargetMapping, TraversalDirection, TopicWorkPhase, TopicScopeConfig } from "./types.js";
+export interface TopicSummary {
+    name: string;
+    phase?: TopicWorkPhase;
+    author?: string;
+    description?: string;
+    output: string;
+    format: "zip" | "directory";
+    targetCount: number;
+    domain?: string;
+    issue?: string;
+    tags?: string[];
+    contextDocsCount?: number;
+    hasScope?: boolean;
+    direction?: TraversalDirection;
+}
+export interface PhasePreset {
+    phase: TopicWorkPhase;
+    defaultDescription: string;
+    scope: TopicScopeConfig;
+    defaultPrompt?: string;
+}
+export declare const PHASE_PRESETS: Record<TopicWorkPhase, PhasePreset>;
+export interface CreateTopicOptions {
+    name: string;
+    phase?: TopicWorkPhase;
+    author?: string;
+    description?: string;
+    entrypoints?: string[];
+    targets?: TargetMapping[];
+    domain?: string;
+    issue?: string;
+    prompt?: string;
+    output?: string;
+    format?: "zip" | "directory";
+}
+/**
+ * Creates a standardized TopicProfile configured with lifecycle phase defaults and worker metadata.
+ */
+export declare function createTopicProfile(options: CreateTopicOptions): TopicProfile;
+/**
+ * Persists a newly created topic profile directly into the manifest file on disk.
+ */
+export declare function addTopicToManifest(manifestPath: string, topicName: string, profile: TopicProfile): {
+    updated: boolean;
+    topicCount: number;
+};
+/**
+ * Computes the default output path for a topic profile if none is explicitly declared.
+ */
+export declare function getDefaultTopicOutput(manifestOutput: string, manifestName: string, topicName: string, format?: "zip" | "directory"): string;
+/**
+ * Lists all declarative topic profiles present in a bundle manifest.
+ */
+export declare function listManifestTopics(manifest: BundleManifest): TopicSummary[];
+/**
+ * Resolves a topic profile from a bundle manifest into an effective standalone BundleManifest.
+ * Integrates extraction scope boundaries, ambient background context documents,
+ * and directional graph reachability rules.
+ */
+export declare function resolveTopicManifest(manifest: BundleManifest, topicName: string): BundleManifest;
+//# sourceMappingURL=topic.d.ts.map

package/dist/topic.js

@@ -0,0 +1,262 @@
+import fs from "node:fs";
+import path from "node:path";
+export const PHASE_PRESETS = {
+    develop: {
+        phase: "develop",
+        defaultDescription: "Feature development context focusing on specification and implementation mechanisms",
+        scope: {
+            direction: "downstream",
+            includeCategories: ["feature", "mechanism", "convention"],
+            categoryFidelity: {
+                mechanism: "full",
+                convention: "full",
+            },
+        },
+        defaultPrompt: "Implement the feature specification following designated mechanisms and architectural conventions.",
+    },
+    fix: {
+        phase: "fix",
+        defaultDescription: "Bugfix and refactoring context with upstream impact coordination and error catalogs",
+        scope: {
+            direction: "bidirectional",
+            upstreamDepth: 1,
+            includeCategories: ["feature", "error", "issue"],
+            categoryFidelity: {
+                upstream: "contract-only",
+                issue: "summary",
+            },
+        },
+        defaultPrompt: "Resolve the issue and verify error handling while preserving compatibility with upstream caller contracts.",
+    },
+    test: {
+        phase: "test",
+        defaultDescription: "Verification and QA context with error catalogs and contract guarantees",
+        scope: {
+            direction: "downstream",
+            includeCategories: ["feature", "error", "mechanism"],
+            categoryFidelity: {
+                mechanism: "contract-only",
+            },
+        },
+        defaultPrompt: "Verify that implementation satisfies all acceptance criteria, contract guarantees, and error recovery scenarios.",
+    },
+    review: {
+        phase: "review",
+        defaultDescription: "Architecture and peer review context with compact summaries across all categories",
+        scope: {
+            direction: "bidirectional",
+            upstreamDepth: 1,
+            includeCategories: ["feature", "mechanism", "convention", "error", "issue"],
+            categoryFidelity: {
+                upstream: "contract-only",
+                default: "summary",
+            },
+        },
+        defaultPrompt: "Review architectural invariants, contract interfaces, and issue background without unnecessary implementation bloat.",
+    },
+};
+/**
+ * Creates a standardized TopicProfile configured with lifecycle phase defaults and worker metadata.
+ */
+export function createTopicProfile(options) {
+    const phase = options.phase ?? "develop";
+    const preset = PHASE_PRESETS[phase];
+    const entrypoints = options.entrypoints ?? [];
+    const targets = options.targets && options.targets.length > 0
+        ? options.targets
+        : [{ source: "specs/**", dest: "specs/" }];
+    const scope = {
+        ...preset.scope,
+        entrypoints: entrypoints.length > 0 ? entrypoints : undefined,
+    };
+    const context = {
+        domain: options.domain,
+        issue: options.issue,
+        prompt: options.prompt ?? preset.defaultPrompt,
+        generateContextDoc: true,
+    };
+    return {
+        phase,
+        author: options.author,
+        description: options.description ?? `${options.name} (${preset.defaultDescription})`,
+        output: options.output,
+        format: options.format ?? "zip",
+        targets,
+        scope,
+        context,
+    };
+}
+/**
+ * Persists a newly created topic profile directly into the manifest file on disk.
+ */
+export function addTopicToManifest(manifestPath, topicName, profile) {
+    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(`Failed to parse manifest JSON at ${manifestPath}: ${err.message}`);
+    }
+    if (!parsed.topics) {
+        parsed.topics = {};
+    }
+    parsed.topics[topicName] = profile;
+    fs.writeFileSync(absPath, JSON.stringify(parsed, null, 2) + "\n", "utf8");
+    return { updated: true, topicCount: Object.keys(parsed.topics).length };
+}
+/**
+ * Computes the default output path for a topic profile if none is explicitly declared.
+ */
+export function getDefaultTopicOutput(manifestOutput, manifestName, topicName, format = "zip") {
+    const dir = path.dirname(manifestOutput);
+    const ext = format === "directory" ? "" : path.extname(manifestOutput) || ".zip";
+    const sanitizedTopic = topicName.replace(/[^a-zA-Z0-9._-]/g, "-");
+    return path.join(dir, `${manifestName}-${sanitizedTopic}${ext}`).replace(/\\/g, "/");
+}
+/**
+ * Lists all declarative topic profiles present in a bundle manifest.
+ */
+export function listManifestTopics(manifest) {
+    if (!manifest.topics || typeof manifest.topics !== "object") {
+        return [];
+    }
+    const summaries = [];
+    for (const [name, profile] of Object.entries(manifest.topics)) {
+        const format = profile.format ?? manifest.format ?? "zip";
+        const output = profile.output ??
+            getDefaultTopicOutput(manifest.output, manifest.name, name, format);
+        const contextDocsCount = Array.isArray(profile.context?.docs)
+            ? profile.context.docs.length
+            : 0;
+        const hasScope = Boolean(profile.scope &&
+            ((profile.scope.entrypoints && profile.scope.entrypoints.length > 0) ||
+                (profile.scope.include && profile.scope.include.length > 0) ||
+                (profile.scope.sections && profile.scope.sections.length > 0)));
+        summaries.push({
+            name,
+            phase: profile.phase,
+            author: profile.author,
+            description: profile.description,
+            output,
+            format,
+            targetCount: Array.isArray(profile.targets) ? profile.targets.length : 0,
+            domain: profile.context?.domain,
+            issue: profile.context?.issue,
+            tags: profile.context?.tags,
+            contextDocsCount,
+            hasScope,
+            direction: profile.scope?.direction,
+        });
+    }
+    return summaries;
+}
+/**
+ * Resolves a topic profile from a bundle manifest into an effective standalone BundleManifest.
+ * Integrates extraction scope boundaries, ambient background context documents,
+ * and directional graph reachability rules.
+ */
+export function resolveTopicManifest(manifest, topicName) {
+    const topics = manifest.topics;
+    if (!topics || !topics[topicName]) {
+        const available = Object.keys(topics ?? {});
+        const hint = available.length > 0
+            ? ` Available topics in manifest: ${available.map((t) => `'${t}'`).join(", ")}`
+            : ` Manifest declares 0 topics under 'topics'.`;
+        throw new Error(`Topic '${topicName}' not found in manifest.${hint}`);
+    }
+    const topicProfile = topics[topicName];
+    const format = topicProfile.format ?? manifest.format ?? "zip";
+    const output = topicProfile.output ??
+        getDefaultTopicOutput(manifest.output, manifest.name, topicName, format);
+    // 1. Process context ambient docs into targets
+    const contextDocs = topicProfile.context?.docs ?? [];
+    const contextTargets = contextDocs.map((doc) => ({
+        source: doc.source,
+        dest: doc.dest ? doc.dest : "context/",
+        exclude: doc.exclude,
+    }));
+    const effectiveTargets = [...topicProfile.targets, ...contextTargets];
+    // 2. Combine topic-level, global, and scope exclusions
+    const combinedExclude = [
+        ...(topicProfile.exclude ?? manifest.exclude ?? []),
+        ...(topicProfile.scope?.exclude ?? []),
+    ];
+    // 3. Resolve effective tree-shaking configuration from scope and treeShake
+    const preservePatterns = contextDocs.length > 0 ? ["context/**", "_context/**"] : [];
+    let effectiveTreeShake;
+    if (topicProfile.treeShake) {
+        effectiveTreeShake = {
+            enabled: topicProfile.treeShake.enabled ?? true,
+            entrypoints: topicProfile.scope?.entrypoints ?? topicProfile.treeShake.entrypoints ?? [],
+            scope: topicProfile.scope?.include ?? topicProfile.treeShake.scope,
+            stopAt: topicProfile.scope?.stopAt ?? topicProfile.treeShake.stopAt,
+            maxDepth: topicProfile.scope?.maxDepth ?? topicProfile.treeShake.maxDepth,
+            direction: topicProfile.scope?.direction ?? topicProfile.treeShake.direction ?? "downstream",
+            upstreamDepth: topicProfile.scope?.upstreamDepth ?? topicProfile.treeShake.upstreamDepth ?? 1,
+            includeCategories: topicProfile.scope?.includeCategories ?? topicProfile.treeShake.includeCategories,
+            excludeCategories: topicProfile.scope?.excludeCategories ?? topicProfile.treeShake.excludeCategories,
+            categoryFidelity: topicProfile.scope?.categoryFidelity ?? topicProfile.treeShake.categoryFidelity,
+            preserve: [
+                ...(topicProfile.treeShake.preserve ?? []),
+                ...preservePatterns,
+            ],
+            reportEliminated: topicProfile.treeShake.reportEliminated ?? true,
+            traversalMode: topicProfile.treeShake.traversalMode ??
+                topicProfile.scope?.traversalMode,
+            preserveTargets: topicProfile.treeShake.preserveTargets ??
+                topicProfile.scope?.preserveTargets,
+        };
+    }
+    else if (topicProfile.scope &&
+        (topicProfile.scope.entrypoints ||
+            topicProfile.scope.include ||
+            topicProfile.scope.stopAt ||
+            topicProfile.scope.maxDepth !== undefined ||
+            topicProfile.scope.direction !== undefined ||
+            topicProfile.scope.includeCategories ||
+            topicProfile.scope.excludeCategories ||
+            topicProfile.scope.categoryFidelity)) {
+        effectiveTreeShake = {
+            enabled: true,
+            entrypoints: topicProfile.scope.entrypoints ?? [],
+            scope: topicProfile.scope.include,
+            stopAt: topicProfile.scope.stopAt,
+            maxDepth: topicProfile.scope.maxDepth,
+            direction: topicProfile.scope.direction ?? "downstream",
+            upstreamDepth: topicProfile.scope.upstreamDepth ?? 1,
+            includeCategories: topicProfile.scope.includeCategories,
+            excludeCategories: topicProfile.scope.excludeCategories,
+            categoryFidelity: topicProfile.scope.categoryFidelity,
+            preserve: preservePatterns,
+            reportEliminated: true,
+            traversalMode: topicProfile.scope.traversalMode ?? "hybrid",
+            preserveTargets: topicProfile.scope.preserveTargets ?? true,
+        };
+    }
+    else {
+        effectiveTreeShake = { enabled: false, entrypoints: [] };
+    }
+    return {
+        ...manifest,
+        name: `${manifest.name}:${topicName}`,
+        description: topicProfile.description ?? manifest.description,
+        output,
+        format,
+        targets: effectiveTargets,
+        exclude: combinedExclude.length > 0 ? combinedExclude : undefined,
+        deduplicate: topicProfile.deduplicate ?? manifest.deduplicate,
+        linkResolution: topicProfile.linkResolution ?? manifest.linkResolution,
+        treeShake: effectiveTreeShake,
+        scope: topicProfile.scope,
+        context: topicProfile.context,
+        phase: topicProfile.phase,
+        author: topicProfile.author,
+        lockfileMode: manifest.lockfileMode,
+    };
+}
+//# sourceMappingURL=topic.js.map

package/dist/tree-shaker.d.ts

@@ -0,0 +1,40 @@
+import type { ResolvedFileEntry, TreeShakeConfig, ReachabilityHop, DependencyTreeNode, DocumentCategory } from "./types.js";
+export interface TreeShakeResult {
+    reachableEntries: Map<string, ResolvedFileEntry>;
+    eliminatedEntries: ResolvedFileEntry[];
+    warnings: string[];
+    lineage: Map<string, ReachabilityHop>;
+    boundaryTerminals: string[];
+    boundaryEdges: Map<string, Array<{
+        target: string;
+        rawRef: string;
+    }>>;
+    upstreamNodes?: string[];
+    downstreamNodes?: string[];
+    nodeCategories?: Map<string, DocumentCategory>;
+}
+/**
+ * Performs reachability traversal (downstream, upstream, or bidirectional)
+ * starting from declarative entrypoints with category filtering and boundary enforcement.
+ */
+export declare function pruneUnreachableEntries(entries: Map<string, ResolvedFileEntry>, config: TreeShakeConfig, workspaceRoot: string): TreeShakeResult;
+/**
+ * Traces the provenance chain from an entrypoint down to the given target destination.
+ */
+export declare function explainReachability(targetDest: string, lineage: Map<string, ReachabilityHop>, entrypoints: string[], boundaryEdges?: Map<string, Array<{
+    target: string;
+    rawRef: string;
+}>>): Array<{
+    from: string;
+    to: string;
+    ref: string;
+}> | null;
+/**
+ * Constructs a visual hierarchical dependency tree for bundle inspection.
+ */
+export declare function buildDependencyTree(entries: Map<string, ResolvedFileEntry>, config: TreeShakeConfig, workspaceRoot: string): DependencyTreeNode[];
+/**
+ * Formats a hierarchical dependency tree as human-readable ASCII text.
+ */
+export declare function renderAsciiTree(nodes: DependencyTreeNode[], prefix?: string): string;
+//# sourceMappingURL=tree-shaker.d.ts.map