@openuji/speculator 0.3.2 → 0.4.0

package/dist/preprocess/include/resolver.js

@@ -0,0 +1,187 @@
+/**
+ * Include Resolver
+ *
+ * Recursively resolves includes from an entry file, building the IncludeGraph
+ * and producing ordered SourceUnits for the composite document.
+ *
+ * Key behaviors:
+ * - Deterministic order: includes are processed in encounter order
+ * - Cycle detection: prevents infinite loops with clear diagnostics
+ * - Content splitting: preserves sourcePos.file for each fragment
+ */
+import { isFileNotFoundError } from '#src/file-provider/types';
+import { inferFormat, createDiagnostic } from '#src/preprocess/types';
+import { scanMarkdownIncludes } from '#src/preprocess/include/scan-markdown';
+import { scanHtmlIncludes } from '#src/preprocess/include/scan-html';
+/**
+ * Count lines up to an offset
+ */
+function countLinesUpTo(content, offset) {
+    let lines = 1;
+    for (let i = 0; i < offset && i < content.length; i++) {
+        if (content[i] === '\n') {
+            lines++;
+        }
+    }
+    return lines;
+}
+/**
+ * Scan content for includes based on format
+ */
+function scanIncludes(content, file, format) {
+    return format === 'markdown'
+        ? scanMarkdownIncludes(content, file)
+        : scanHtmlIncludes(content, file);
+}
+/**
+ * Split content at include points and recursively resolve
+ *
+ * Returns SourceUnits in document order (includes expanded in-place)
+ */
+async function resolveFile(file, format, ctx) {
+    const { fileProvider, includeGraph, diagnostics, activePath, visited } = ctx;
+    // Cycle detection
+    if (activePath.has(file)) {
+        const cycle = [...activePath, file];
+        diagnostics.push(createDiagnostic('error', 'include-cycle', `Include cycle detected: ${cycle.join(' → ')}`, file));
+        return [];
+    }
+    // Check if already processed (for diamond includes - A includes B and C, both include D)
+    const cached = visited.get(file);
+    if (cached) {
+        // Return a single unit for previously visited file
+        return [{
+                file,
+                format: cached.format,
+                content: cached.content,
+                startLine: 1,
+            }];
+    }
+    // Read file
+    let content;
+    try {
+        content = await fileProvider.readText(file);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            diagnostics.push(createDiagnostic('error', 'include-not-found', `Included file not found: ${file}`, file));
+        }
+        else {
+            diagnostics.push(createDiagnostic('error', 'include-not-found', `Failed to read included file: ${file} - ${error instanceof Error ? error.message : String(error)}`, file));
+        }
+        return [];
+    }
+    // Cache for diamond include handling
+    visited.set(file, { content, format });
+    // Mark as active for cycle detection
+    activePath.add(file);
+    try {
+        // Scan for includes
+        const includes = scanIncludes(content, file, format);
+        // Record in include graph
+        if (includes.length > 0) {
+            const edges = includes.map(inc => ({
+                target: fileProvider.resolve(file, inc.relativePath),
+                sourcePos: inc.sourcePos,
+            }));
+            includeGraph.set(file, edges);
+        }
+        // If no includes, return single unit
+        if (includes.length === 0) {
+            return [{
+                    file,
+                    format,
+                    content,
+                    startLine: 1,
+                }];
+        }
+        // Split content at include points and recursively resolve
+        const units = [];
+        let lastEnd = 0;
+        for (const include of includes) {
+            // Add content before this include
+            if (include.startOffset > lastEnd) {
+                const beforeContent = content.slice(lastEnd, include.startOffset);
+                if (beforeContent.trim()) {
+                    units.push({
+                        file,
+                        format,
+                        content: beforeContent,
+                        startLine: countLinesUpTo(content, lastEnd),
+                    });
+                }
+            }
+            // Resolve the included file
+            const includedPath = fileProvider.resolve(file, include.relativePath);
+            const includedFormat = include.format ?? inferFormat(include.relativePath);
+            const includedUnits = await resolveFile(includedPath, includedFormat, ctx);
+            units.push(...includedUnits);
+            lastEnd = include.endOffset;
+            // Skip trailing newline after directive if present
+            if (content[lastEnd] === '\n') {
+                lastEnd++;
+            }
+        }
+        // Add remaining content after last include
+        if (lastEnd < content.length) {
+            const afterContent = content.slice(lastEnd);
+            if (afterContent.trim()) {
+                units.push({
+                    file,
+                    format,
+                    content: afterContent,
+                    startLine: countLinesUpTo(content, lastEnd),
+                });
+            }
+        }
+        return units;
+    }
+    finally {
+        // Remove from active path when done
+        activePath.delete(file);
+    }
+}
+/**
+ * Resolve all includes from an entry file
+ *
+ * @param entry - Canonical path to entry file
+ * @param entryFormat - Format of entry file (inferred if not provided)
+ * @param fileProvider - File provider for reading files
+ * @returns CompositeSource with resolved includes and diagnostics
+ *
+ * @example
+ * ```typescript
+ * const { source, diagnostics } = await resolveIncludes(
+ *   '/spec/format.md',
+ *   'markdown',
+ *   fileProvider
+ * );
+ *
+ * // source.units is ordered by document flow
+ * for (const unit of source.units) {
+ *   console.log(`${unit.file}:${unit.startLine}`);
+ * }
+ * ```
+ */
+export async function resolveIncludes(entry, entryFormat, fileProvider) {
+    const canonicalEntry = fileProvider.canonicalize(entry);
+    const format = entryFormat ?? inferFormat(canonicalEntry);
+    const ctx = {
+        fileProvider,
+        includeGraph: new Map(),
+        diagnostics: [],
+        activePath: new Set(),
+        visited: new Map(),
+    };
+    const units = await resolveFile(canonicalEntry, format, ctx);
+    return {
+        source: {
+            entryFile: canonicalEntry,
+            entryFormat: format,
+            units,
+            includeGraph: ctx.includeGraph,
+        },
+        diagnostics: ctx.diagnostics,
+    };
+}
+//# sourceMappingURL=resolver.js.map

package/dist/preprocess/include/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../src/preprocess/include/resolver.ts"],"names":[],"mappings":"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"}

package/dist/preprocess/include/scan-html.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HTML Include Scanner
+ *
+ * Scans HTML content for data-include sections.
+ *
+ * Format: <section data-include="./path.md" data-include-format="markdown"></section>
+ *
+ * The scanner uses a simple regex-based approach that handles the common cases
+ * without requiring a full HTML parser dependency.
+ */
+import type { IncludeDirective } from '#src/preprocess/types';
+/**
+ * Scan HTML content for include directives
+ *
+ * @param content - HTML file content
+ * @param file - Canonical path of the file being scanned
+ * @returns Array of include directives in encounter order
+ *
+ * @example
+ * ```typescript
+ * const content = `
+ * <body>
+ *   <section data-include="./intro.md" data-include-format="markdown"></section>
+ * </body>
+ * `;
+ * const includes = scanHtmlIncludes(content, '/spec/format.html');
+ * // Returns: [{ relativePath: './intro.md', format: 'markdown', ... }]
+ * ```
+ */
+export declare function scanHtmlIncludes(content: string, file: string): IncludeDirective[];
+//# sourceMappingURL=scan-html.d.ts.map

package/dist/preprocess/include/scan-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-html.d.ts","sourceRoot":"","sources":["../../../src/preprocess/include/scan-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,uBAAuB,CAAC;AAiD5E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAkClF"}

package/dist/preprocess/include/scan-html.js

@@ -0,0 +1,100 @@
+/**
+ * HTML Include Scanner
+ *
+ * Scans HTML content for data-include sections.
+ *
+ * Format: <section data-include="./path.md" data-include-format="markdown"></section>
+ *
+ * The scanner uses a simple regex-based approach that handles the common cases
+ * without requiring a full HTML parser dependency.
+ */
+import { inferFormat } from '#src/preprocess/types';
+/**
+ * Regular expression to match HTML include sections
+ *
+ * Matches elements with data-include attribute.
+ * Captures the full opening tag to extract both path and optional format.
+ *
+ * This is intentionally simple and doesn't handle all edge cases
+ * (e.g., attributes split across lines, attribute values with escaped quotes).
+ * For complex HTML, a proper parser would be needed.
+ */
+const DATA_INCLUDE_REGEX = /<([a-z][a-z0-9]*)\s+[^>]*data-include\s*=\s*["']([^"']+)["'][^>]*>/gi;
+/**
+ * Extract data-include-format from a tag string
+ */
+function extractFormat(tagString) {
+    const formatMatch = tagString.match(/data-include-format\s*=\s*["']([^"']+)["']/i);
+    if (formatMatch) {
+        const format = formatMatch[1].toLowerCase();
+        if (format === 'markdown' || format === 'html') {
+            return format;
+        }
+    }
+    return undefined;
+}
+/**
+ * Calculate line and column from content offset
+ */
+function getLineColumn(content, offset) {
+    let line = 1;
+    let lastNewline = -1;
+    for (let i = 0; i < offset && i < content.length; i++) {
+        if (content[i] === '\n') {
+            line++;
+            lastNewline = i;
+        }
+    }
+    return {
+        line,
+        column: offset - lastNewline,
+    };
+}
+/**
+ * Scan HTML content for include directives
+ *
+ * @param content - HTML file content
+ * @param file - Canonical path of the file being scanned
+ * @returns Array of include directives in encounter order
+ *
+ * @example
+ * ```typescript
+ * const content = `
+ * <body>
+ *   <section data-include="./intro.md" data-include-format="markdown"></section>
+ * </body>
+ * `;
+ * const includes = scanHtmlIncludes(content, '/spec/format.html');
+ * // Returns: [{ relativePath: './intro.md', format: 'markdown', ... }]
+ * ```
+ */
+export function scanHtmlIncludes(content, file) {
+    const directives = [];
+    // Reset regex state
+    DATA_INCLUDE_REGEX.lastIndex = 0;
+    let match;
+    while ((match = DATA_INCLUDE_REGEX.exec(content)) !== null) {
+        const fullMatch = match[0];
+        const relativePath = match[2];
+        const startOffset = match.index;
+        const endOffset = match.index + fullMatch.length;
+        const { line, column } = getLineColumn(content, startOffset);
+        // Try to get explicit format, fall back to inference
+        const explicitFormat = extractFormat(fullMatch);
+        const format = explicitFormat ?? inferFormat(relativePath);
+        directives.push({
+            relativePath,
+            format,
+            sourcePos: {
+                file,
+                line,
+                column,
+                offset: startOffset,
+            },
+            startOffset,
+            endOffset,
+        });
+    }
+    return directives;
+}
+//# sourceMappingURL=scan-html.js.map

package/dist/preprocess/include/scan-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-html.js","sourceRoot":"","sources":["../../../src/preprocess/include/scan-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,kBAAkB,GAAG,sEAAsE,CAAC;AAElG;;GAEG;AACH,SAAS,aAAa,CAAC,SAAiB;IACpC,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACnF,IAAI,WAAW,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5C,IAAI,MAAM,KAAK,UAAU,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YAC7C,OAAO,MAAM,CAAC;QAClB,CAAC;IACL,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,OAAe,EAAE,MAAc;IAClD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC;IAErB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACtB,IAAI,EAAE,CAAC;YACP,WAAW,GAAG,CAAC,CAAC;QACpB,CAAC;IACL,CAAC;IAED,OAAO;QACH,IAAI;QACJ,MAAM,EAAE,MAAM,GAAG,WAAW;KAC/B,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,IAAY;IAC1D,MAAM,UAAU,GAAuB,EAAE,CAAC;IAE1C,oBAAoB;IACpB,kBAAkB,CAAC,SAAS,GAAG,CAAC,CAAC;IAEjC,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACzD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3B,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC;QAChC,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC;QAEjD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAE7D,qDAAqD;QACrD,MAAM,cAAc,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,cAAc,IAAI,WAAW,CAAC,YAAY,CAAC,CAAC;QAE3D,UAAU,CAAC,IAAI,CAAC;YACZ,YAAY;YACZ,MAAM;YACN,SAAS,EAAE;gBACP,IAAI;gBACJ,IAAI;gBACJ,MAAM;gBACN,MAAM,EAAE,WAAW;aACtB;YACD,WAAW;YACX,SAAS;SACZ,CAAC,CAAC;IACP,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC"}

package/dist/preprocess/include/scan-markdown.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Markdown Include Scanner
+ *
+ * Scans markdown content for :::include directives.
+ *
+ * Format: :::include ./path/to/file.md :::
+ *
+ * The scanner preserves exact position information for each directive
+ * to enable accurate source mapping after include resolution.
+ */
+import type { IncludeDirective } from '#src/preprocess/types';
+/**
+ * Scan markdown content for include directives
+ *
+ * @param content - Markdown file content
+ * @param file - Canonical path of the file being scanned
+ * @returns Array of include directives in encounter order
+ *
+ * @example
+ * ```typescript
+ * const content = `
+ * # Title
+ * :::include ./intro.md :::
+ * ## Next Section
+ * `;
+ * const includes = scanMarkdownIncludes(content, '/spec/format.md');
+ * // Returns: [{ relativePath: './intro.md', ... }]
+ * ```
+ */
+export declare function scanMarkdownIncludes(content: string, file: string): IncludeDirective[];
+//# sourceMappingURL=scan-markdown.d.ts.map

package/dist/preprocess/include/scan-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-markdown.d.ts","sourceRoot":"","sources":["../../../src/preprocess/include/scan-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAmC9D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CA6BtF"}

package/dist/preprocess/include/scan-markdown.js

@@ -0,0 +1,83 @@
+/**
+ * Markdown Include Scanner
+ *
+ * Scans markdown content for :::include directives.
+ *
+ * Format: :::include ./path/to/file.md :::
+ *
+ * The scanner preserves exact position information for each directive
+ * to enable accurate source mapping after include resolution.
+ */
+import { inferFormat } from '#src/preprocess/types';
+/**
+ * Regular expression to match markdown include directives
+ *
+ * Matches: :::include ./path/to/file.md :::
+ *
+ * Captures:
+ * - Group 1: file path (required)
+ *
+ * The directive must be on its own line.
+ */
+const INCLUDE_REGEX = /^[ \t]*:::include\s+(\S+)\s*:::\s*$/gm;
+/**
+ * Calculate line and column from content offset
+ */
+function getLineColumn(content, offset) {
+    let line = 1;
+    let lastNewline = -1;
+    for (let i = 0; i < offset && i < content.length; i++) {
+        if (content[i] === '\n') {
+            line++;
+            lastNewline = i;
+        }
+    }
+    return {
+        line,
+        column: offset - lastNewline,
+    };
+}
+/**
+ * Scan markdown content for include directives
+ *
+ * @param content - Markdown file content
+ * @param file - Canonical path of the file being scanned
+ * @returns Array of include directives in encounter order
+ *
+ * @example
+ * ```typescript
+ * const content = `
+ * # Title
+ * :::include ./intro.md :::
+ * ## Next Section
+ * `;
+ * const includes = scanMarkdownIncludes(content, '/spec/format.md');
+ * // Returns: [{ relativePath: './intro.md', ... }]
+ * ```
+ */
+export function scanMarkdownIncludes(content, file) {
+    const directives = [];
+    // Reset regex state for each call
+    INCLUDE_REGEX.lastIndex = 0;
+    let match;
+    while ((match = INCLUDE_REGEX.exec(content)) !== null) {
+        const relativePath = match[1];
+        const startOffset = match.index;
+        const endOffset = match.index + match[0].length;
+        const { line, column } = getLineColumn(content, startOffset);
+        directives.push({
+            relativePath,
+            format: inferFormat(relativePath),
+            sourcePos: {
+                file,
+                line,
+                column,
+                offset: startOffset,
+            },
+            startOffset,
+            endOffset,
+        });
+    }
+    return directives;
+}
+//# sourceMappingURL=scan-markdown.js.map

package/dist/preprocess/include/scan-markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-markdown.js","sourceRoot":"","sources":["../../../src/preprocess/include/scan-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,aAAa,GAAG,uCAAuC,CAAC;AAE9D;;GAEG;AACH,SAAS,aAAa,CAAC,OAAe,EAAE,MAAc;IAClD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC;IAErB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACtB,IAAI,EAAE,CAAC;YACP,WAAW,GAAG,CAAC,CAAC;QACpB,CAAC;IACL,CAAC;IAED,OAAO;QACH,IAAI;QACJ,MAAM,EAAE,MAAM,GAAG,WAAW;KAC/B,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,IAAY;IAC9D,MAAM,UAAU,GAAuB,EAAE,CAAC;IAE1C,kCAAkC;IAClC,aAAa,CAAC,SAAS,GAAG,CAAC,CAAC;IAE5B,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpD,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC;QAChC,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAEhD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAE7D,UAAU,CAAC,IAAI,CAAC;YACZ,YAAY;YACZ,MAAM,EAAE,WAAW,CAAC,YAAY,CAAC;YACjC,SAAS,EAAE;gBACP,IAAI;gBACJ,IAAI;gBACJ,MAAM;gBACN,MAAM,EAAE,WAAW;aACtB;YACD,WAAW;YACX,SAAS;SACZ,CAAC,CAAC;IACP,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC"}

package/dist/preprocess/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Preprocess Module - Public API
+ *
+ * The preprocess stage handles:
+ * - Loading and normalizing spec configuration
+ * - Resolving includes to produce ordered SourceUnits
+ * - Preserving source file information for accurate error reporting
+ */
+export { preprocess, validateEntry } from '#src/preprocess/pipeline';
+export type { PreprocessOptions } from '#src/preprocess/pipeline';
+export type { SourceFormat, IncludeDirective, SourceUnit, IncludeGraph, IncludeEdge, CompositeSource, PersonEntry, SpecConfig, PreprocessedSpec, DiagnosticSeverity, PreprocessDiagnosticCode, Diagnostic, PreprocessResult, } from '#src/preprocess/types';
+export { inferFormat, createDiagnostic } from '#src/preprocess/types';
+export { loadRespecConfig, normalizeRespecConfig, createDefaultConfig, } from '#src/preprocess/config/index';
+export type { RawRespecConfig, RawPersonEntry } from '#src/preprocess/config/index';
+export { scanMarkdownIncludes, scanHtmlIncludes, resolveIncludes, } from '#src/preprocess/include/index';
+//# sourceMappingURL=index.d.ts.map

package/dist/preprocess/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/preprocess/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACrE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,YAAY,EACR,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,UAAU,EACV,gBAAgB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGtE,OAAO,EACH,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,GACtB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAGpF,OAAO,EACH,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,GAClB,MAAM,+BAA+B,CAAC"}

package/dist/preprocess/index.js

@@ -0,0 +1,16 @@
+/**
+ * Preprocess Module - Public API
+ *
+ * The preprocess stage handles:
+ * - Loading and normalizing spec configuration
+ * - Resolving includes to produce ordered SourceUnits
+ * - Preserving source file information for accurate error reporting
+ */
+// Main orchestrator
+export { preprocess, validateEntry } from '#src/preprocess/pipeline';
+export { inferFormat, createDiagnostic } from '#src/preprocess/types';
+// Config submodule (for advanced use)
+export { loadRespecConfig, normalizeRespecConfig, createDefaultConfig, } from '#src/preprocess/config/index';
+// Include submodule (for advanced use)
+export { scanMarkdownIncludes, scanHtmlIncludes, resolveIncludes, } from '#src/preprocess/include/index';
+//# sourceMappingURL=index.js.map

package/dist/preprocess/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/preprocess/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oBAAoB;AACpB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAoBrE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEtE,sCAAsC;AACtC,OAAO,EACH,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,GACtB,MAAM,8BAA8B,CAAC;AAGtC,uCAAuC;AACvC,OAAO,EACH,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,GAClB,MAAM,+BAA+B,CAAC"}

package/dist/preprocess/pipeline.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Preprocess Pipeline
+ *
+ * Orchestrates configuration loading and include resolution.
+ * This is the main entry point for the preprocess stage.
+ */
+import type { FileProvider } from '#src/file-provider/types';
+import type { SourceFormat, PreprocessResult, Diagnostic } from '#src/preprocess/types';
+/**
+ * Options for preprocessing a specification
+ */
+export interface PreprocessOptions {
+    /** Path to entry file (format.md or format.html) */
+    entry: string;
+    /** Optional explicit format (inferred from extension if not provided) */
+    entryFormat?: SourceFormat;
+    /** Path to config file (optional) */
+    configPath?: string;
+    /** File provider for reading files */
+    fileProvider: FileProvider;
+}
+/**
+ * Preprocess a specification document
+ *
+ * Loads configuration (if provided) and resolves all includes
+ * to produce a PreprocessedSpec ready for parsing.
+ *
+ * @param options - Preprocess options
+ * @returns PreprocessResult with spec and diagnostics
+ *
+ * @example
+ * ```typescript
+ * const result = await preprocess({
+ *   entry: '/specs/my-spec/format.md',
+ *   configPath: '/specs/my-spec/config.respec.json',
+ *   fileProvider: new NodeFileProvider(),
+ * });
+ *
+ * if (result.hasErrors) {
+ *   console.error('Preprocess errors:', result.diagnostics);
+ * } else {
+ *   // result.result contains PreprocessedSpec
+ *   for (const unit of result.result.source.units) {
+ *     console.log(`Processing: ${unit.file}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function preprocess(options: PreprocessOptions): Promise<PreprocessResult>;
+/**
+ * Quick check if an entry file exists and is readable
+ */
+export declare function validateEntry(entry: string, fileProvider: FileProvider): Promise<{
+    valid: boolean;
+    diagnostics: Diagnostic[];
+}>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/preprocess/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/preprocess/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EACR,YAAY,EAEZ,gBAAgB,EAChB,UAAU,EACb,MAAM,uBAAuB,CAAC;AAK/B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IAEd,yEAAyE;IACzE,WAAW,CAAC,EAAE,YAAY,CAAC;IAE3B,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,sCAAsC;IACtC,YAAY,EAAE,YAAY,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+CtF;AAED;;GAEG;AACH,wBAAsB,aAAa,CAC/B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,GAC3B,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC,CAgBxD"}

package/dist/preprocess/pipeline.js

@@ -0,0 +1,100 @@
+/**
+ * Preprocess Pipeline
+ *
+ * Orchestrates configuration loading and include resolution.
+ * This is the main entry point for the preprocess stage.
+ */
+import { inferFormat } from '#src/preprocess/types';
+import { loadRespecConfig, normalizeRespecConfig, createDefaultConfig } from '#src/preprocess/config/index';
+import { resolveIncludes } from '#src/preprocess/include/index';
+/**
+ * Preprocess a specification document
+ *
+ * Loads configuration (if provided) and resolves all includes
+ * to produce a PreprocessedSpec ready for parsing.
+ *
+ * @param options - Preprocess options
+ * @returns PreprocessResult with spec and diagnostics
+ *
+ * @example
+ * ```typescript
+ * const result = await preprocess({
+ *   entry: '/specs/my-spec/format.md',
+ *   configPath: '/specs/my-spec/config.respec.json',
+ *   fileProvider: new NodeFileProvider(),
+ * });
+ *
+ * if (result.hasErrors) {
+ *   console.error('Preprocess errors:', result.diagnostics);
+ * } else {
+ *   // result.result contains PreprocessedSpec
+ *   for (const unit of result.result.source.units) {
+ *     console.log(`Processing: ${unit.file}`);
+ *   }
+ * }
+ * ```
+ */
+export async function preprocess(options) {
+    const { entry, entryFormat, configPath, fileProvider } = options;
+    const diagnostics = [];
+    // Canonicalize entry path
+    const canonicalEntry = fileProvider.canonicalize(entry);
+    const format = entryFormat ?? inferFormat(canonicalEntry);
+    // Load config if provided
+    let config;
+    if (configPath) {
+        const configResult = await loadRespecConfig(fileProvider, configPath);
+        diagnostics.push(...configResult.diagnostics);
+        if (configResult.config) {
+            config = normalizeRespecConfig(configResult.config);
+        }
+        else {
+            // Config load failed, use defaults but continue
+            config = createDefaultConfig();
+        }
+    }
+    else {
+        config = createDefaultConfig();
+    }
+    // Resolve includes
+    const includeResult = await resolveIncludes(canonicalEntry, format, fileProvider);
+    diagnostics.push(...includeResult.diagnostics);
+    // Check for errors
+    const hasErrors = diagnostics.some(d => d.severity === 'error');
+    // Even with errors, return partial result if we have units
+    if (includeResult.source.units.length === 0 && hasErrors) {
+        return {
+            diagnostics,
+            hasErrors,
+        };
+    }
+    return {
+        result: {
+            config,
+            source: includeResult.source,
+        },
+        diagnostics,
+        hasErrors,
+    };
+}
+/**
+ * Quick check if an entry file exists and is readable
+ */
+export async function validateEntry(entry, fileProvider) {
+    const diagnostics = [];
+    const canonicalEntry = fileProvider.canonicalize(entry);
+    try {
+        await fileProvider.readText(canonicalEntry);
+        return { valid: true, diagnostics };
+    }
+    catch {
+        diagnostics.push({
+            severity: 'error',
+            code: 'include-not-found',
+            message: `Entry file not found: ${canonicalEntry}`,
+            file: canonicalEntry,
+        });
+        return { valid: false, diagnostics };
+    }
+}
+//# sourceMappingURL=pipeline.js.map