@oa-sdk/spec-bundler 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,369 @@
+export type DeduplicationStrategy = "warn-overwrite" | "overwrite" | "error";
+export type UnbundledPolicy = "warn" | "error" | "preserve" | "github-fallback";
+export interface TargetMapping {
+    /** Source path or glob pattern relative to the manifest directory */
+    source: string;
+    /** Destination directory or file path inside the bundle */
+    dest: string;
+    /** Optional target-specific glob exclusion patterns */
+    exclude?: string[];
+}
+export interface DeduplicationConfig {
+    /** Strategy to handle destination path collisions (default: "warn-overwrite") */
+    byPath?: DeduplicationStrategy;
+    /** Whether to report/track content hash duplicates (default: true) */
+    byContentHash?: boolean;
+}
+export interface LinkResolutionConfig {
+    /** Whether automatic link resolution and rewriting is enabled (default: true) */
+    enabled?: boolean;
+    /** Whether to rewrite internal relative markdown links according to bundle destination (default: true) */
+    rewriteRelativeLinks?: boolean;
+    /** Whether to normalize file:/// absolute local URLs to bundle relative paths (default: true) */
+    normalizeFileSchemes?: boolean;
+    /** Policy for links pointing to files outside the bundle (default: "warn") */
+    unbundledPolicy?: UnbundledPolicy;
+    /** Upstream Git repository URL base for github-fallback policy (e.g. "https://github.com/samchon/ttsc-ex/blob/master") */
+    gitRepositoryUrl?: string;
+}
+export type DocumentCategory = "feature" | "mechanism" | "error" | "issue" | "convention";
+export type TraversalDirection = "downstream" | "upstream" | "bidirectional";
+export type DocumentFidelity = "full" | "contract-only" | "summary";
+export type TopicWorkPhase = "develop" | "fix" | "test" | "review";
+export type TraversalMode = "hybrid" | "reachability" | "explicit";
+export type LockfileMode = "consolidated" | "split";
+export interface TreeShakeConfig {
+    /** Whether tree-shaking reachability pruning is enabled (default: false) */
+    enabled?: boolean;
+    /** Entrypoint file paths (bundle-dest or relative to workspace) from which reachability is computed */
+    entrypoints: string[];
+    /**
+     * Allowed boundary patterns. Only references matching these globs can be pulled into this bundle/topic.
+     * Traversal strictly halts at boundary edges without pulling in external subgraphs.
+     */
+    scope?: string[];
+    /**
+     * Boundary stop patterns (e.g. globs matching contributing.md, README.md).
+     * References matching these patterns become terminal leaves and are never traversed.
+     */
+    stopAt?: string[];
+    /** Optional maximum traversal hop depth from entrypoints */
+    maxDepth?: number;
+    /** Unconditionally preserved file patterns exempt from tree-shaking pruning (e.g. ambient context docs) */
+    preserve?: string[];
+    /** Whether to log/report pruned files in the bundle result (default: true) */
+    reportEliminated?: boolean;
+    /** Traversal direction (default: "downstream") */
+    direction?: TraversalDirection;
+    /** Maximum traversal depth when traversing upstream (default: 1) */
+    upstreamDepth?: number;
+    /** Allowed document categories (unmatched categories pruned) */
+    includeCategories?: DocumentCategory[];
+    /** Document categories strictly excluded */
+    excludeCategories?: DocumentCategory[];
+    /** Level of detail/fidelity per category or upstream contracts */
+    categoryFidelity?: Partial<Record<DocumentCategory | "upstream" | "default", DocumentFidelity>>;
+    /**
+     * Reachability traversal mode:
+     * - "hybrid" (default): Preserves explicitly declared target files while discovering unlisted dependencies.
+     * - "reachability": Strictly prunes any file not reachable from entrypoints.
+     * - "explicit": Only bundles files matched by targets without reachability expansion.
+     */
+    traversalMode?: TraversalMode;
+    /** Whether to unconditionally preserve all files matched by targets (default: true in hybrid mode) */
+    preserveTargets?: boolean;
+}
+export interface TopicScopeConfig {
+    /** Entrypoint files from which reachability traversal begins */
+    entrypoints?: string[];
+    /** Traversal direction: "downstream" (default), "upstream", or "bidirectional" */
+    direction?: TraversalDirection;
+    /** Maximum traversal depth when traversing upstream (default: 1) */
+    upstreamDepth?: number;
+    /** Maximum traversal hop depth from entrypoints (downstream) */
+    maxDepth?: number;
+    /** Allowed boundary globs for files pulled into this topic */
+    include?: string[];
+    /** Glob patterns strictly excluded from this topic */
+    exclude?: string[];
+    /** Boundary stop patterns where traversal halts without expanding (e.g. globs matching contributing.md, README.md) */
+    stopAt?: string[];
+    /** Optional section heading patterns to slice from markdown documents */
+    sections?: string[];
+    /** Allowed document categories (unmatched categories pruned) */
+    includeCategories?: DocumentCategory[];
+    /** Document categories strictly excluded */
+    excludeCategories?: DocumentCategory[];
+    /** Level of detail/fidelity per category or upstream contracts */
+    categoryFidelity?: Partial<Record<DocumentCategory | "upstream" | "default", DocumentFidelity>>;
+    /** Traversal mode ("hybrid" | "reachability" | "explicit") */
+    traversalMode?: TraversalMode;
+    /** Whether to preserve all declared targets */
+    preserveTargets?: boolean;
+}
+export interface TopicContextConfig {
+    /** Context description or high-level summary */
+    description?: string;
+    /** Custom CONTEXT.md template file path relative to manifest, or inline template string */
+    template?: string;
+    /** Target domain or subsystem identifier (e.g. "paint.canvas") */
+    domain?: string;
+    /** Associated issue / ticket ID (e.g. "SPEC-101", "#42") */
+    issue?: string;
+    /** Category tags (e.g. ["paint", "canvas", "brush"]) */
+    tags?: string[];
+    /** System prompt or task instructions for LLM/agent consumers */
+    prompt?: string;
+    /** Target engineer persona or role */
+    persona?: string;
+    /** Prerequisites or dependent topic names */
+    prerequisites?: string[];
+    /** Declarative list of ambient/background context documents */
+    docs?: TargetMapping[];
+    /** Whether to synthesize CONTEXT.md at bundle root (default: true when context is defined) */
+    generateContextDoc?: boolean;
+    /** Arbitrary structured metadata */
+    metadata?: Record<string, any>;
+}
+export interface TopicProfile {
+    /** Work activity lifecycle phase designated for this topic (develop, fix, test, review) */
+    phase?: TopicWorkPhase;
+    /** Initial worker or author who established this topic definition */
+    author?: string;
+    /** Optional human-readable description of this topic export profile */
+    description?: string;
+    /** Output zip archive or directory path relative to manifest */
+    output?: string;
+    /** Output bundle format (default: inherits from root manifest or "zip") */
+    format?: "zip" | "directory";
+    /** Declarative list of target file mappings designated for this topic */
+    targets: TargetMapping[];
+    /** Optional topic-specific glob exclusion patterns */
+    exclude?: string[];
+    /** Optional topic-specific deduplication rules */
+    deduplicate?: DeduplicationConfig;
+    /** Optional topic-specific markdown/typespec link resolution configuration */
+    linkResolution?: LinkResolutionConfig;
+    /** Optional topic-specific tree-shaking and boundary-scoped reachability configuration */
+    treeShake?: TreeShakeConfig;
+    /** Declarative extraction scope and boundary limits */
+    scope?: TopicScopeConfig;
+    /** Ambient background context, metadata, prompt, and documentation */
+    context?: TopicContextConfig;
+}
+export interface BundleManifest {
+    $schema?: string;
+    name: string;
+    version: string;
+    description?: string;
+    /** Work activity lifecycle phase designated for this manifest/topic */
+    phase?: TopicWorkPhase;
+    /** Initial worker or author who established this manifest/topic definition */
+    author?: string;
+    /** Output zip archive or directory path relative to manifest */
+    output: string;
+    /** Output bundle format (default: "zip") */
+    format?: "zip" | "directory";
+    /** Declarative list of target file mappings */
+    targets: TargetMapping[];
+    /** Global glob exclusion patterns */
+    exclude?: string[];
+    /** Deduplication rules */
+    deduplicate?: DeduplicationConfig;
+    /** Markdown reference link resolution options */
+    linkResolution?: LinkResolutionConfig;
+    /** Declarative tree-shaking reachability configuration */
+    treeShake?: TreeShakeConfig;
+    /** Declarative extraction scope and boundary limits */
+    scope?: TopicScopeConfig;
+    /** Ambient background context, metadata, prompt, and documentation */
+    context?: TopicContextConfig;
+    /** Declarative named topic profiles for repeatable modular documentation bundling */
+    topics?: Record<string, TopicProfile>;
+    /** Lockfile storage mode: "consolidated" (default) or "split" */
+    lockfileMode?: LockfileMode;
+}
+export interface ResolvedFileEntry {
+    sourceAbsolutePath: string;
+    sourceRelativePath: string;
+    /** Normalized POSIX destination path inside bundle (e.g. "skills/my-skill/SKILL.md") */
+    bundleDestPath: string;
+    sha256: string;
+    size: number;
+    mtime: number;
+}
+export interface LockfileEntry {
+    source: string;
+    sha256: string;
+    size: number;
+    mtime: number;
+}
+export interface TopicLockData {
+    generatedAt: string;
+    aggregateHash: string;
+    filesCount: number;
+    totalSizeBytes: number;
+    entries: Record<string, LockfileEntry>;
+}
+export interface BundleLockfile {
+    manifestVersion: string;
+    bundleName: string;
+    generatedAt: string;
+    aggregateHash: string;
+    filesCount: number;
+    totalSizeBytes: number;
+    entries: Record<string, LockfileEntry>;
+    /** Consolidated topic lock data dictionary */
+    topics?: Record<string, TopicLockData>;
+}
+export interface FileStructuralDiff {
+    file: string;
+    type: "markdown" | "typespec" | "other";
+    addedAnchors?: string[];
+    removedAnchors?: string[];
+    addedSymbols?: string[];
+    removedSymbols?: string[];
+    lineDelta?: number;
+}
+export interface SemanticDriftReport {
+    addedFiles: string[];
+    removedFiles: string[];
+    modifiedFiles: FileStructuralDiff[];
+}
+export interface ReachabilityHop {
+    parentDest: string;
+    rawRef: string;
+}
+export interface DependencyTreeNode {
+    path: string;
+    size: number;
+    isEntrypoint: boolean;
+    isBoundaryTerminal?: boolean;
+    direction?: "downstream" | "upstream";
+    category?: DocumentCategory;
+    children: DependencyTreeNode[];
+}
+export interface LinkRewriteRecord {
+    file: string;
+    line: number;
+    column: number;
+    originalHref: string;
+    rewrittenHref: string;
+    targetBundleDest?: string;
+    linkKind: "inline" | "reference-def";
+}
+export interface PlannedArchiveEntry {
+    source: string;
+    dest: string;
+    size: number;
+    sha256: string;
+}
+export interface PackOptions {
+    force?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+    diff?: boolean;
+    topic?: string;
+    treeShake?: boolean;
+    lockfileMode?: LockfileMode;
+}
+export interface LinkDiagnostic {
+    file: string;
+    line: number;
+    column?: number;
+    originalHref: string;
+    rewrittenHref?: string;
+    targetBundleDest?: string;
+    severity: "info" | "warning" | "error";
+    message: string;
+    suggestedTarget?: string;
+    linkKind?: "inline" | "reference-def";
+}
+export interface FreshnessResult {
+    isFresh: boolean;
+    currentAggregateHash: string;
+    lockAggregateHash?: string;
+    added: string[];
+    removed: string[];
+    modified: string[];
+    semanticDiff?: SemanticDriftReport;
+}
+export interface PackResult {
+    outputPath: string;
+    filesCount: number;
+    totalSizeBytes: number;
+    aggregateHash: string;
+    diagnostics: LinkDiagnostic[];
+    skipped: boolean;
+    topic?: string;
+    phase?: TopicWorkPhase;
+    author?: string;
+    dryRun?: boolean;
+    eliminatedFiles?: string[];
+    boundaryTerminals?: string[];
+    upstreamNodes?: string[];
+    direction?: TraversalDirection;
+    categoryBreakdown?: Record<string, number>;
+    plannedEntries?: PlannedArchiveEntry[];
+    rewrites?: LinkRewriteRecord[];
+    predictedLockfile?: BundleLockfile;
+    freshness?: FreshnessResult;
+    unbundledDiagnostics?: LinkDiagnostic[];
+}
+export interface DryRunReport {
+    manifest: string;
+    bundleName: string;
+    bundleVersion: string;
+    outputPath: string;
+    format: "zip" | "directory";
+    topic?: string;
+    phase?: TopicWorkPhase;
+    author?: string;
+    dryRun: true;
+    skipped: boolean;
+    filesCount: number;
+    totalSizeBytes: number;
+    aggregateHash: string;
+    plannedEntries: PlannedArchiveEntry[];
+    rewrites: LinkRewriteRecord[];
+    diagnostics: LinkDiagnostic[];
+    unbundledDiagnostics: LinkDiagnostic[];
+    predictedLockfile: BundleLockfile;
+    freshness: FreshnessResult;
+    eliminatedFiles?: string[];
+    boundaryTerminals?: string[];
+    upstreamNodes?: string[];
+    direction?: TraversalDirection;
+    categoryBreakdown?: Record<string, number>;
+}
+export interface BundleManifestBom {
+    manifestName: string;
+    manifestVersion: string;
+    topic?: string;
+    topicPhase?: TopicWorkPhase;
+    topicAuthor?: string;
+    topicContext?: TopicContextConfig;
+    topicScope?: TopicScopeConfig;
+    direction?: TraversalDirection;
+    categoryBreakdown?: Record<string, number>;
+    generatedAt: string;
+    fileCount: number;
+    files: string[];
+    sourceToBundle: Record<string, string>;
+    bundleToSource: Record<string, string>;
+}
+export interface BundlePathResolution {
+    /** The resolved POSIX relative path inside the bundle (e.g. "scenario/docs/req.md") */
+    bundlePath: string;
+    /** The fragment anchor if present (e.g. "#user-profile"), or undefined */
+    anchor?: string;
+    /** The full rewritten reference including anchor (e.g. "scenario/docs/req.md#user-profile") */
+    fullReference: string;
+    /** Whether the target file actually exists in the bundle archive */
+    existsInBundle: boolean;
+    /** The original query string passed to resolve */
+    originalQuery: string;
+    /** If the file was not found, a suggested closest file candidate inside the bundle */
+    suggestedTarget?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@oa-sdk/spec-bundler",
+  "version": "0.1.0",
+  "description": "Declarative manifest-driven specification bundler with automated markdown link rewriting, deduplication, and lockfile freshness verification.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mineclover/oa-sdk-releases.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "spec-bundler": "./dist/cli.js",
+    "meta-bundler": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}