@openuji/speculator 0.3.2 → 0.4.0

package/README.md

@@ -1,73 +1,134 @@
 # Speculator
 
-A TypeScript library for processing ReSpec-like markup and open for intgration in any frontend framework out there
+AST-first specification parser and indexer with schema-central architecture.
 
+Speculator transforms specification documents (Markdown or HTML) into structured AST and semantic indexes. It does **not** render output - that responsibility belongs to separate tools. Speculator provides optional JSON serialization of the AST and indexes for consumption by renderers, linters, or other processors.
 
-## Installation
+## Schema Architecture
 
-```bash
-pnpm install -D @openui/speculator linkdom
-```
+The AST JSON Schema (`schema/spec-ast.schema.json`) is the single source of truth. All pipeline outputs validate against it.
 
+### Core Node Types
 
-## Package Structure
+| Type | Description |
+|------|-------------|
+| `Document` | Root container with metadata, sections, and indexes |
+| `Section` | Grouping with optional heading, supports nesting |
+| `Block` | Block-level: paragraph, heading, codeBlock, example, blockquote, list, table, thematicBreak, html |
+| `Inline` | Inline: text, emphasis, strong, inlineCode, link, image, definition, reference, requirement, issue |
 
-```bash
-speculator/
-├── src/
-│ ├── index.ts
-│ ├── renderer.ts
-│ ├── types.ts
-│ └── utils/
-│ ├── markdown.ts
-│ └── file-loader.ts
-├── tests/
-│ ├── renderer.test.ts
-│ └── fixtures/
-│ ├── intro.md
-│ ├── smooth-scroller.md
-│ └── ujse.webidl
-├── dist/
-├── package.json
-├── tsconfig.json
-├── jest.config.js
-├── .npmignore
-└── README.md
-```
+### Index Markers (Inline)
 
-## Markdown extensions
+Indexes are extracted from inline markers during the post-parse `index` phase:
 
-Additional [MarkdownIt](https://github.com/markdown-it/markdown-it) plugins can be
-applied by passing them in `markdownOptions.extensions`:
+| Marker Type | Description | Extracted To |
+|-------------|-------------|--------------|
+| `definition` | Term definition (dfn) | `indexes.definitions[]` |
+| `reference` | Cross-reference | `indexes.references[]` |
+| `requirement` | RFC 2119 keyword | `indexes.requirements[]` |
+| `issue` | Open issue/TODO | `indexes.issues[]` |
+| `example` (block) | Code example | `indexes.examples[]` |
 
-```ts
-import { parseMarkdown } from '@openui/speculator';
-import anchor from 'markdown-it-anchor';
+### Semantic vs Computed Boundaries
 
-parseMarkdown('# Title', { markdownOptions: { extensions: [anchor] } });
-```
+| Category | In AST | Computed | Notes |
+|----------|--------|----------|-------|
+| Semantic nodes | ✓ | ✗ | Core AST structure |
+| Indexes | ✓ | ✗ | Extracted, not computed |
+| `computed.toc` | ✓ optional | ✓ | Marked `x-computed: true` |
+| `computed.headingNumbers` | ✓ optional | ✓ | Marked `x-computed: true` |
+| `computed.wordCount` | ✓ optional | ✓ | Marked `x-computed: true` |
 
-Each entry can be a plugin function or a `[plugin, options]` tuple and will be
-installed after the built-in ReSpec shorthand plugins.
+**Key Distinction:**
+- **Semantic AST**: Node structure + indexes. Always valid. Use `SemanticDocument` type.
+- **Full AST**: Semantic + computed fields. Use `FullDocument` type.
 
-## Mermaid diagrams
+## TypeScript Types
 
-Render [Mermaid](https://mermaid.js.org/) code blocks by enabling the
-`mermaid` option when parsing Markdown:
+Generate types from schema:
 
-```ts
-import { parseMarkdown } from '@openui/speculator';
+```bash
+npm run generate:types
+```
 
-const md = '```mermaid\nflowchart TD;A-->B;\n```';
-const html = parseMarkdown(md, { mermaid: true });
+This generates `src/types/ast.generated.ts` with:
+- All node types
+- `SemanticDocument` - AST without computed fields
+- `FullDocument` - AST with computed fields
+- Type guards: `isDocument()`, `isSection()`, `isBlock()`, `isInline()`, etc.
+
+## Runtime Validation
+
+```typescript
+import { validateAST, assertValidAST, ASTValidator } from './src/validation/validate';
+
+// Quick validation
+const result = validateAST(ast, 'semantic'); // or 'full'
+if (!result.valid) {
+  console.error(result.errors);
+}
+
+// Assertion-style (throws on failure)
+assertValidAST(ast, 'semantic');
+
+// Per-stage validation
+const validator = new ASTValidator();
+validator.validateAtStage(ast, 'parse');    // semantic mode
+validator.validateAtStage(ast, 'transform'); // semantic mode
+validator.validateAtStage(ast, 'resolve');   // semantic mode
+validator.validateAtStage(ast, 'index');     // semantic mode
+validator.validateAtStage(ast, 'compute');   // full mode
 ```
 
-Configuration can be passed directly to Mermaid if needed:
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Validate schema syntax
+npm run validate:schema
+
+# Generate TypeScript types
+npm run generate:types
+
+# Build
+npm run build
 
-```ts
-parseMarkdown(md, {
-  mermaid: { theme: 'forest' },
-});
+# Test
+npm run test
 ```
 
+## Pipeline Phases
 
+```
+loadConfig → loadEntry → preprocessIncludes → parse → transform → resolve → index → (compute?)
+                                                                              ↓
+                                                                    Extract indexes from
+                                                                    inline markers
+```
+
+The pipeline produces:
+- **AST**: Structured document tree with semantic nodes
+- **Indexes**: Extracted definitions, references, requirements, issues, examples
+- **JSON Output**: Optional serialization of AST and indexes for external tools
+
+## Source Position Tracking
+
+Every node can have a `sourcePos` with:
+- `file` - Canonical file path (preserves include origins)
+- `line`, `column` - 1-indexed position
+- `offset` - 0-indexed byte offset
+- `endLine`, `endColumn`, `endOffset` - End position (optional)
+
+```typescript
+interface SourcePos {
+  file: string;
+  line: number;    // 1-indexed
+  column: number;  // 1-indexed
+  offset?: number; // 0-indexed
+  endLine?: number;
+  endColumn?: number;
+  endOffset?: number;
+}
+```

package/dist/file-provider/__tests__/compliance.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for FileProvider compliance across implementations
+ */
+export {};
+//# sourceMappingURL=compliance.test.d.ts.map

package/dist/file-provider/__tests__/compliance.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compliance.test.d.ts","sourceRoot":"","sources":["../../../src/file-provider/__tests__/compliance.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/file-provider/__tests__/compliance.test.js

@@ -0,0 +1,52 @@
+/**
+ * Tests for FileProvider compliance across implementations
+ */
+import { describe, it, expect } from 'vitest';
+import { MemoryFileProvider, NodeFileProvider, FileNotFoundError } from '#src/file-provider/index';
+import * as path from 'path';
+// Helper to test common compliance requirements
+function runComplianceTests(name, provider) {
+    describe(`${name} Compliance`, () => {
+        it('canonicalizes paths deterministically', () => {
+            // Different inputs should map to same canonical path
+            const p1 = provider.canonicalize('/foo/bar/../baz.md');
+            const p2 = provider.canonicalize('/foo/baz.md');
+            expect(p1).toBe(p2);
+        });
+        it('resolves relative paths correctly', () => {
+            const from = provider.canonicalize('/docs/spec/index.md');
+            const resolved = provider.resolve(from, '../images/logo.png');
+            const expected = provider.canonicalize('/docs/images/logo.png');
+            expect(resolved).toBe(expected);
+        });
+        it('resolves sibling paths correctly', () => {
+            const from = provider.canonicalize('/docs/intro.md');
+            const resolved = provider.resolve(from, './setup.md');
+            const expected = provider.canonicalize('/docs/setup.md');
+            expect(resolved).toBe(expected);
+        });
+    });
+}
+describe('MemoryFileProvider', () => {
+    const provider = new MemoryFileProvider({
+        '/foo/bar.md': 'content'
+    });
+    runComplianceTests('MemoryFileProvider', provider);
+    it('reads existing files', async () => {
+        const content = await provider.readText('/foo/bar.md');
+        expect(content).toBe('content');
+    });
+    it('throws FileNotFoundError for missing files', async () => {
+        await expect(provider.readText('/missing.md'))
+            .rejects.toThrow(FileNotFoundError);
+    });
+});
+describe('NodeFileProvider', () => {
+    const provider = new NodeFileProvider();
+    runComplianceTests('NodeFileProvider', provider);
+    it('canonicalizes to absolute paths', () => {
+        const p = provider.canonicalize('foo.md');
+        expect(path.isAbsolute(p)).toBe(true);
+    });
+});
+//# sourceMappingURL=compliance.test.js.map

package/dist/file-provider/__tests__/compliance.test.js.map

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

package/dist/file-provider/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * FileProvider exports
+ */
+export { FileProvider, FileNotFoundError, FileReadError, isFileNotFoundError, isFileReadError } from '#src/file-provider/types';
+export { MemoryFileProvider } from '#src/file-provider/memory';
+export { NodeFileProvider } from '#src/file-provider/node';
+export { WebFileProvider } from '#src/file-provider/web';
+//# sourceMappingURL=index.d.ts.map

package/dist/file-provider/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/file-provider/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACH,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,eAAe,EAClB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/file-provider/index.js

@@ -0,0 +1,10 @@
+/**
+ * FileProvider exports
+ */
+// Types and interface
+export { FileNotFoundError, FileReadError, isFileNotFoundError, isFileReadError } from '#src/file-provider/types';
+// Implementations
+export { MemoryFileProvider } from '#src/file-provider/memory';
+export { NodeFileProvider } from '#src/file-provider/node';
+export { WebFileProvider } from '#src/file-provider/web';
+//# sourceMappingURL=index.js.map

package/dist/file-provider/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/file-provider/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,sBAAsB;AACtB,OAAO,EAEH,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,eAAe,EAClB,MAAM,0BAA0B,CAAC;AAElC,kBAAkB;AAClB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/file-provider/memory.d.ts

@@ -0,0 +1,46 @@
+/**
+ * MemoryFileProvider - In-memory file provider for testing
+ *
+ * Uses a simple Map to store files. Paths are normalized to forward slashes.
+ * Useful for unit tests and documentation examples.
+ */
+import { FileProvider } from '#src/file-provider/types';
+/**
+ * In-memory file provider
+ *
+ * @example
+ * ```typescript
+ * const provider = new MemoryFileProvider({
+ *   '/spec/index.md': '# Main\n:::include ./intro.md :::',
+ *   '/spec/intro.md': '## Introduction\nContent here...'
+ * });
+ *
+ * const content = await provider.readText('/spec/index.md');
+ * const resolved = provider.resolve('/spec/index.md', './intro.md');
+ * // resolved === '/spec/intro.md'
+ * ```
+ */
+export declare class MemoryFileProvider implements FileProvider {
+    private files;
+    constructor(files?: Record<string, string>);
+    /**
+     * Add or update a file in memory
+     */
+    setFile(path: string, content: string): void;
+    /**
+     * Remove a file from memory
+     */
+    deleteFile(path: string): boolean;
+    /**
+     * Check if a file exists
+     */
+    hasFile(path: string): boolean;
+    /**
+     * Get all file paths
+     */
+    listFiles(): string[];
+    readText(path: string): Promise<string>;
+    resolve(fromFile: string, relativePath: string): string;
+    canonicalize(path: string): string;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/file-provider/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/file-provider/memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACH,YAAY,EAEf,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;GAcG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACnD,OAAO,CAAC,KAAK,CAAsB;gBAEvB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM;IAO9C;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5C;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAIf,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW7C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAevD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CA0BrC"}

package/dist/file-provider/memory.js

@@ -0,0 +1,99 @@
+/**
+ * MemoryFileProvider - In-memory file provider for testing
+ *
+ * Uses a simple Map to store files. Paths are normalized to forward slashes.
+ * Useful for unit tests and documentation examples.
+ */
+import { FileNotFoundError } from '#src/file-provider/types';
+/**
+ * In-memory file provider
+ *
+ * @example
+ * ```typescript
+ * const provider = new MemoryFileProvider({
+ *   '/spec/index.md': '# Main\n:::include ./intro.md :::',
+ *   '/spec/intro.md': '## Introduction\nContent here...'
+ * });
+ *
+ * const content = await provider.readText('/spec/index.md');
+ * const resolved = provider.resolve('/spec/index.md', './intro.md');
+ * // resolved === '/spec/intro.md'
+ * ```
+ */
+export class MemoryFileProvider {
+    files;
+    constructor(files = {}) {
+        this.files = new Map();
+        for (const [path, content] of Object.entries(files)) {
+            this.files.set(this.canonicalize(path), content);
+        }
+    }
+    /**
+     * Add or update a file in memory
+     */
+    setFile(path, content) {
+        this.files.set(this.canonicalize(path), content);
+    }
+    /**
+     * Remove a file from memory
+     */
+    deleteFile(path) {
+        return this.files.delete(this.canonicalize(path));
+    }
+    /**
+     * Check if a file exists
+     */
+    hasFile(path) {
+        return this.files.has(this.canonicalize(path));
+    }
+    /**
+     * Get all file paths
+     */
+    listFiles() {
+        return Array.from(this.files.keys());
+    }
+    async readText(path) {
+        const canonical = this.canonicalize(path);
+        const content = this.files.get(canonical);
+        if (content === undefined) {
+            throw new FileNotFoundError(canonical);
+        }
+        return content;
+    }
+    resolve(fromFile, relativePath) {
+        // Get directory of source file
+        const fromCanonical = this.canonicalize(fromFile);
+        const lastSlash = fromCanonical.lastIndexOf('/');
+        const fromDir = lastSlash > 0 ? fromCanonical.slice(0, lastSlash) : '/';
+        // Handle absolute paths
+        if (relativePath.startsWith('/')) {
+            return this.canonicalize(relativePath);
+        }
+        // Combine and canonicalize
+        return this.canonicalize(`${fromDir}/${relativePath}`);
+    }
+    canonicalize(path) {
+        // Normalize to forward slashes
+        let normalized = path.replace(/\\/g, '/');
+        // Ensure absolute path
+        if (!normalized.startsWith('/')) {
+            normalized = '/' + normalized;
+        }
+        // Split and resolve . and ..
+        const parts = normalized.split('/');
+        const resolved = [];
+        for (const part of parts) {
+            if (part === '' || part === '.') {
+                continue;
+            }
+            if (part === '..') {
+                resolved.pop();
+            }
+            else {
+                resolved.push(part);
+            }
+        }
+        return '/' + resolved.join('/');
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/file-provider/memory.js.map

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

package/dist/file-provider/node.d.ts

@@ -0,0 +1,32 @@
+/**
+ * NodeFileProvider - Node.js file system provider
+ *
+ * Uses Node.js fs module for file operations.
+ * Paths are canonicalized using path.resolve and path.normalize.
+ */
+import { FileProvider } from '#src/file-provider/types';
+/**
+ * Node.js file provider
+ *
+ * @example
+ * ```typescript
+ * const provider = new NodeFileProvider();
+ *
+ * const content = await provider.readText('/project/spec/index.md');
+ * const resolved = provider.resolve('/project/spec/index.md', './intro.md');
+ * // resolved === '/project/spec/intro.md'
+ * ```
+ */
+export declare class NodeFileProvider implements FileProvider {
+    private basePath;
+    /**
+     * Create a Node.js file provider
+     *
+     * @param basePath - Optional base path for relative paths (defaults to cwd)
+     */
+    constructor(basePath?: string);
+    readText(filePath: string): Promise<string>;
+    resolve(fromFile: string, relativePath: string): string;
+    canonicalize(filePath: string): string;
+}
+//# sourceMappingURL=node.d.ts.map

package/dist/file-provider/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/file-provider/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACH,YAAY,EAGf,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACjD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;OAIG;gBACS,QAAQ,CAAC,EAAE,MAAM;IAIvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAejD,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAavD,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CASzC"}

package/dist/file-provider/node.js

@@ -0,0 +1,65 @@
+/**
+ * NodeFileProvider - Node.js file system provider
+ *
+ * Uses Node.js fs module for file operations.
+ * Paths are canonicalized using path.resolve and path.normalize.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { FileNotFoundError, FileReadError } from '#src/file-provider/types';
+/**
+ * Node.js file provider
+ *
+ * @example
+ * ```typescript
+ * const provider = new NodeFileProvider();
+ *
+ * const content = await provider.readText('/project/spec/index.md');
+ * const resolved = provider.resolve('/project/spec/index.md', './intro.md');
+ * // resolved === '/project/spec/intro.md'
+ * ```
+ */
+export class NodeFileProvider {
+    basePath;
+    /**
+     * Create a Node.js file provider
+     *
+     * @param basePath - Optional base path for relative paths (defaults to cwd)
+     */
+    constructor(basePath) {
+        this.basePath = basePath ?? process.cwd();
+    }
+    async readText(filePath) {
+        const canonical = this.canonicalize(filePath);
+        try {
+            return await fs.readFile(canonical, 'utf-8');
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error) {
+                if (error.code === 'ENOENT') {
+                    throw new FileNotFoundError(canonical);
+                }
+            }
+            throw new FileReadError(canonical, error instanceof Error ? error : undefined);
+        }
+    }
+    resolve(fromFile, relativePath) {
+        const fromCanonical = this.canonicalize(fromFile);
+        const fromDir = path.dirname(fromCanonical);
+        // Handle absolute paths
+        if (path.isAbsolute(relativePath)) {
+            return this.canonicalize(relativePath);
+        }
+        // Resolve relative to source file's directory
+        return this.canonicalize(path.join(fromDir, relativePath));
+    }
+    canonicalize(filePath) {
+        // Make absolute if relative
+        const absolutePath = path.isAbsolute(filePath)
+            ? filePath
+            : path.join(this.basePath, filePath);
+        // Normalize (resolves . and ..)
+        return path.normalize(absolutePath);
+    }
+}
+//# sourceMappingURL=node.js.map

package/dist/file-provider/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../src/file-provider/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAEH,iBAAiB,EACjB,aAAa,EAChB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,gBAAgB;IACjB,QAAQ,CAAS;IAEzB;;;;OAIG;IACH,YAAY,QAAiB;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,QAAgB;QAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAE9C,IAAI,CAAC;YACD,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;gBAC5C,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACrD,MAAM,IAAI,iBAAiB,CAAC,SAAS,CAAC,CAAC;gBAC3C,CAAC;YACL,CAAC;YACD,MAAM,IAAI,aAAa,CAAC,SAAS,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACnF,CAAC;IACL,CAAC;IAED,OAAO,CAAC,QAAgB,EAAE,YAAoB;QAC1C,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAE5C,wBAAwB;QACxB,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;QAC3C,CAAC;QAED,8CAA8C;QAC9C,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,YAAY,CAAC,QAAgB;QACzB,4BAA4B;QAC5B,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1C,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAEzC,gCAAgC;QAChC,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IACxC,CAAC;CACJ"}

package/dist/file-provider/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * FileProvider - Isomorphic file access abstraction
+ *
+ * Provides a minimal interface for reading files and resolving paths
+ * across different environments (Node.js, Web, Memory).
+ */
+/**
+ * Error thrown when a file cannot be found
+ */
+export declare class FileNotFoundError extends Error {
+    readonly path: string;
+    readonly code = "FILE_NOT_FOUND";
+    constructor(path: string);
+}
+/**
+ * Error thrown when a file cannot be read
+ */
+export declare class FileReadError extends Error {
+    readonly path: string;
+    readonly cause?: Error | undefined;
+    readonly code = "FILE_READ_ERROR";
+    constructor(path: string, cause?: Error | undefined);
+}
+/**
+ * Minimal isomorphic file provider interface
+ *
+ * All paths are expected to be canonical after canonicalize() is called.
+ * Implementations must ensure deterministic behavior for the same inputs.
+ */
+export interface FileProvider {
+    /**
+     * Read file contents as UTF-8 text
+     *
+     * @param path - Canonical file path
+     * @returns File contents as string
+     * @throws FileNotFoundError if file doesn't exist
+     * @throws FileReadError if file cannot be read
+     */
+    readText(path: string): Promise<string>;
+    /**
+     * Resolve a relative path from a source file's location
+     *
+     * @param fromFile - Canonical path of the file containing the reference
+     * @param relativePath - Relative path to resolve (e.g., "./foo.md", "../bar.md")
+     * @returns Canonical resolved path
+     */
+    resolve(fromFile: string, relativePath: string): string;
+    /**
+     * Convert a path to its canonical form
+     *
+     * Canonical paths are:
+     * - Absolute (no relative segments)
+     * - Normalized (no . or .. segments)
+     * - Consistent across platform (forward slashes for web/memory)
+     *
+     * @param path - Path to canonicalize
+     * @returns Canonical path
+     */
+    canonicalize(path: string): string;
+}
+/**
+ * Type guard for FileNotFoundError
+ */
+export declare function isFileNotFoundError(error: unknown): error is FileNotFoundError;
+/**
+ * Type guard for FileReadError
+ */
+export declare function isFileReadError(error: unknown): error is FileReadError;
+//# sourceMappingURL=types.d.ts.map

package/dist/file-provider/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/file-provider/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAGZ,IAAI,EAAE,MAAM;IAFxC,QAAQ,CAAC,IAAI,oBAAoB;gBAEL,IAAI,EAAE,MAAM;CAI3C;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAIhB,IAAI,EAAE,MAAM;aACZ,KAAK,CAAC,EAAE,KAAK;IAJjC,QAAQ,CAAC,IAAI,qBAAqB;gBAGd,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,KAAK,YAAA;CAKpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAExD;;;;;;;;;;OAUG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAG9E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAGtE"}