@organon-methodology/testing 0.3.0

package/dist/core/invariant-test.js

@@ -0,0 +1,174 @@
+/**
+ * testInvariant — Wrapper that links tests to invariant IDs.
+ *
+ * Invariants enforced:
+ * - INV-TEST-3 (invariant-id-required): Every test must link to an invariant ID.
+ * - INV-TEST-4 (framework-agnostic-core): Core logic has zero test-framework deps.
+ * - INV-TEST-6 (always-async): Test function is always async.
+ * - INV-TEST-7 (composable): No module-level mutable state that affects test outcomes.
+ *
+ * Design:
+ * - The metadata registry is a read-only record of test registrations.
+ *   It stores what tests were registered but does not affect test execution.
+ *   Tests execute identically regardless of registry state (INV-TEST-7).
+ * - The wrapper delegates to a configurable test runner function.
+ *   By default, it uses a pass-through runner that just calls the test function.
+ *   Adapters (e.g., vitest.ts) provide framework-specific runners.
+ */
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Error thrown when testInvariant is called with invalid arguments.
+ */
+export class InvariantTestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvariantTestError';
+    }
+}
+/**
+ * Validate an invariant ID format.
+ *
+ * Valid format: PREFIX-WORD-NUMBER (e.g., "INV-CACHE-1", "INV-TEST-42")
+ * Must be non-empty and follow the ID convention.
+ */
+export function validateInvariantId(id) {
+    if (!id || typeof id !== 'string') {
+        throw new InvariantTestError('Invariant ID is required. Provide a non-empty string (e.g., "INV-CACHE-1").');
+    }
+    const trimmed = id.trim();
+    if (trimmed.length === 0) {
+        throw new InvariantTestError('Invariant ID must not be empty or whitespace-only.');
+    }
+    if (trimmed !== id) {
+        throw new InvariantTestError(`Invariant ID "${id}" contains leading or trailing whitespace. Use "${trimmed}" instead.`);
+    }
+}
+/**
+ * Validate a test description.
+ */
+export function validateDescription(description) {
+    if (!description || typeof description !== 'string') {
+        throw new InvariantTestError('Test description is required. Provide a non-empty string describing what the test verifies.');
+    }
+    const trimmed = description.trim();
+    if (trimmed.length === 0) {
+        throw new InvariantTestError('Test description must not be empty or whitespace-only.');
+    }
+}
+/**
+ * Validate a test function.
+ */
+export function validateTestFn(testFn) {
+    if (typeof testFn !== 'function') {
+        throw new InvariantTestError(`Test function is required. Got ${typeof testFn} instead of a function.`);
+    }
+}
+/**
+ * Create a new empty registry instance.
+ */
+export function createRegistry() {
+    const entries = [];
+    return {
+        register(metadata) {
+            entries.push({ ...metadata });
+        },
+        getAll() {
+            return entries.map((e) => ({ ...e }));
+        },
+        has(invariantId) {
+            return entries.some((e) => e.invariantId === invariantId);
+        },
+        size() {
+            return entries.length;
+        },
+        coveredCount() {
+            return new Set(entries.map((e) => e.invariantId)).size;
+        },
+        clear() {
+            entries.length = 0;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Default registry (module-scoped singleton for convenience)
+// ---------------------------------------------------------------------------
+/**
+ * The default global registry. Used by testInvariant() when no custom
+ * registry is provided. Can be accessed via getDefaultRegistry() for
+ * coverage reporting.
+ */
+const defaultRegistry = createRegistry();
+/**
+ * Get the default global registry for coverage reporting.
+ */
+export function getDefaultRegistry() {
+    return defaultRegistry;
+}
+// ---------------------------------------------------------------------------
+// Core: testInvariant()
+// ---------------------------------------------------------------------------
+/**
+ * Default test runner: executes the async test function directly.
+ * Used when no framework-specific adapter is configured.
+ * Framework adapters (vitest, jest) replace this with their own `it()`/`test()` wrapper.
+ *
+ * Since TestRunner is synchronous (for framework compatibility) but testFn is async,
+ * failures surface as unhandled promise rejections. In Node.js 15+, unhandled
+ * rejections crash the process with a clear error. A .catch() handler wraps the
+ * error with the test name for better diagnostics.
+ */
+const defaultRunner = (testName, testFn, _metadata) => {
+    testFn().catch((err) => {
+        const wrapped = err instanceof Error
+            ? err
+            : new Error(String(err));
+        wrapped.message = `[${testName}] ${wrapped.message}`;
+        // Re-throw as unhandled rejection so Node.js exits non-zero
+        queueMicrotask(() => { throw wrapped; });
+    });
+};
+/**
+ * Register and declare an invariant test.
+ *
+ * This is the primary API for linking tests to invariant IDs (INV-TEST-3).
+ *
+ * Usage:
+ * ```typescript
+ * testInvariant('INV-CACHE-1', 'cache TTL max 24h', async () => {
+ *   await assertMaxValue({ ... });
+ * });
+ * ```
+ *
+ * What it does:
+ * 1. Validates inputs (invariant ID, description, test function)
+ * 2. Registers the test in the metadata registry (for coverage tracking)
+ * 3. Delegates to the configured test runner (framework adapter)
+ *
+ * @param invariantId - The invariant ID this test verifies (e.g., "INV-CACHE-1")
+ * @param description - Human-readable description of what the test checks
+ * @param testFn - Async function that performs assertions
+ * @param options - Optional configuration (custom runner, custom registry)
+ *
+ * @throws {InvariantTestError} if inputs are invalid
+ */
+export function testInvariant(invariantId, description, testFn, options) {
+    // 1. Validate inputs (INV-TEST-2: fail-fast on bad input)
+    validateInvariantId(invariantId);
+    validateDescription(description);
+    validateTestFn(testFn);
+    // 2. Build metadata
+    const metadata = {
+        invariantId,
+        description,
+    };
+    // 3. Register in the registry (for coverage tracking)
+    const registry = options?.registry ?? defaultRegistry;
+    registry.register(metadata);
+    // 4. Delegate to test runner
+    const runner = options?.runner ?? defaultRunner;
+    const testName = `[${invariantId}] ${description}`;
+    runner(testName, testFn, metadata);
+}
+//# sourceMappingURL=invariant-test.js.map

package/dist/core/invariant-test.js.map

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

package/dist/core/resolvers/file-resolver.d.ts

@@ -0,0 +1,92 @@
+/**
+ * File resolver — I/O layer that reads files and feeds data to pure assertions.
+ *
+ * This module handles all file system interactions for assertions.
+ * It expands globs, reads file contents, and extracts pattern matches
+ * that are then validated by pure assertion functions in core/assertions/.
+ *
+ * Design:
+ * - Depends on FileSystem interface (mockable for tests)
+ * - Returns structured data, never throws on I/O errors (wraps them)
+ * - Assertions receive pre-resolved data, never file paths
+ */
+import type { FileSystem } from './types.js';
+/**
+ * A single match found in a file by the resolver.
+ */
+export interface FileMatch {
+    /** Path of the file where the match was found */
+    file: string;
+    /** The line number (1-based) where the match occurred */
+    line: number;
+    /** The full line of text containing the match */
+    lineText: string;
+    /** The raw matched string from the capturing group */
+    rawMatch: string;
+}
+/**
+ * A numeric value extracted from a file by pattern matching.
+ */
+export interface ExtractedValue {
+    /** Path of the file where the value was found */
+    file: string;
+    /** The line number (1-based) where the value was found */
+    line: number;
+    /** The full line of text containing the value */
+    lineText: string;
+    /** The extracted numeric value */
+    value: number;
+    /** The raw string that was parsed as a number */
+    rawValue: string;
+}
+/**
+ * Result of resolving files and extracting numeric values by pattern.
+ */
+export interface ResolvedValues {
+    /** Successfully extracted numeric values */
+    values: ExtractedValue[];
+    /** Files that were resolved and read */
+    filesRead: string[];
+    /** Errors encountered during resolution (e.g., file not found) */
+    errors: ResolverError[];
+}
+/**
+ * An error encountered during file resolution.
+ */
+export interface ResolverError {
+    file: string;
+    message: string;
+}
+/**
+ * Options for resolving numeric values from files.
+ */
+export interface ResolveValuesOptions {
+    /** File paths or glob patterns to scan */
+    files: string[];
+    /** Regex pattern with at least one capturing group for the numeric value */
+    pattern: RegExp;
+    /** Working directory for glob resolution */
+    cwd?: string;
+}
+/**
+ * Expand glob patterns to concrete file paths.
+ *
+ * Non-glob paths (no * or ? characters) are returned as-is.
+ */
+export declare function expandGlobs(files: string[], fs: FileSystem, cwd?: string): Promise<{
+    paths: string[];
+    errors: ResolverError[];
+}>;
+/**
+ * Resolve files and extract numeric values matching a pattern.
+ *
+ * This function:
+ * 1. Expands glob patterns to concrete file paths
+ * 2. Reads each file
+ * 3. Scans each line for the regex pattern
+ * 4. Extracts numeric values from the first capturing group
+ *
+ * Non-numeric captures are reported as errors rather than silently skipped.
+ */
+export declare function resolveValues(options: ResolveValuesOptions, fs: FileSystem): Promise<ResolvedValues>;
+//# sourceMappingURL=file-resolver.d.ts.map

package/dist/core/resolvers/file-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-resolver.d.ts","sourceRoot":"","sources":["../../../src/core/resolvers/file-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,wCAAwC;IACxC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EAAE,EACf,EAAE,EAAE,UAAU,EACd,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAqBvD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,EAC7B,EAAE,EAAE,UAAU,GACb,OAAO,CAAC,cAAc,CAAC,CA0DzB"}

package/dist/core/resolvers/file-resolver.js

@@ -0,0 +1,103 @@
+/**
+ * File resolver — I/O layer that reads files and feeds data to pure assertions.
+ *
+ * This module handles all file system interactions for assertions.
+ * It expands globs, reads file contents, and extracts pattern matches
+ * that are then validated by pure assertion functions in core/assertions/.
+ *
+ * Design:
+ * - Depends on FileSystem interface (mockable for tests)
+ * - Returns structured data, never throws on I/O errors (wraps them)
+ * - Assertions receive pre-resolved data, never file paths
+ */
+import { join } from 'node:path';
+import { readFilesParallel } from './parallel-reader.js';
+/**
+ * Expand glob patterns to concrete file paths.
+ *
+ * Non-glob paths (no * or ? characters) are returned as-is.
+ */
+export async function expandGlobs(files, fs, cwd) {
+    const paths = [];
+    const errors = [];
+    for (const file of files) {
+        if (file.includes('*') || file.includes('?')) {
+            try {
+                const expanded = await fs.glob(file, cwd ? { cwd } : undefined);
+                paths.push(...expanded);
+            }
+            catch (err) {
+                errors.push({
+                    file,
+                    message: `Failed to expand glob: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+        else {
+            paths.push(file);
+        }
+    }
+    return { paths, errors };
+}
+/**
+ * Resolve files and extract numeric values matching a pattern.
+ *
+ * This function:
+ * 1. Expands glob patterns to concrete file paths
+ * 2. Reads each file
+ * 3. Scans each line for the regex pattern
+ * 4. Extracts numeric values from the first capturing group
+ *
+ * Non-numeric captures are reported as errors rather than silently skipped.
+ */
+export async function resolveValues(options, fs) {
+    const { files, pattern, cwd } = options;
+    const { paths, errors } = await expandGlobs(files, fs, cwd);
+    const values = [];
+    const filesRead = [];
+    // Build read paths (prepend cwd when set)
+    const readPaths = paths.map((p) => cwd ? join(cwd, p) : p);
+    // Read all files in parallel with concurrency control
+    const readResults = await readFilesParallel(readPaths, fs);
+    for (let idx = 0; idx < readResults.length; idx++) {
+        const result = readResults[idx];
+        const filePath = paths[idx];
+        if (result.error) {
+            errors.push({
+                file: filePath,
+                message: `Failed to read file: ${result.error}`,
+            });
+            continue;
+        }
+        filesRead.push(filePath);
+        const content = result.content;
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const lineText = lines[i];
+            // Reset regex state for global patterns
+            const localPattern = new RegExp(pattern.source, pattern.flags.replace('g', ''));
+            const match = localPattern.exec(lineText);
+            if (match && match[1] !== undefined) {
+                const rawValue = match[1];
+                const parsed = Number(rawValue);
+                if (Number.isNaN(parsed)) {
+                    errors.push({
+                        file: filePath,
+                        message: `Line ${i + 1}: Captured "${rawValue}" is not a valid number`,
+                    });
+                }
+                else {
+                    values.push({
+                        file: filePath,
+                        line: i + 1,
+                        lineText,
+                        value: parsed,
+                        rawValue,
+                    });
+                }
+            }
+        }
+    }
+    return { values, filesRead, errors };
+}
+//# sourceMappingURL=file-resolver.js.map

package/dist/core/resolvers/file-resolver.js.map

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

package/dist/core/resolvers/import-resolver.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Import resolver — scans files for import/require statements.
+ *
+ * Extracts structured import data from TypeScript/JavaScript files.
+ * Used by assertNoSideEffects to check for forbidden module imports.
+ *
+ * Design:
+ * - Depends on FileSystem interface (mockable for tests)
+ * - Returns structured data for pure assertion validation
+ */
+import type { FileSystem } from './types.js';
+/**
+ * A single import/require match found in a file.
+ */
+export interface ImportMatch {
+    /** Path of the file containing the import */
+    file: string;
+    /** The line number (1-based) where the import was found */
+    line: number;
+    /** The full line of text containing the import */
+    lineText: string;
+    /** The module specifier (e.g., 'fs', 'node:http', './utils') */
+    module: string;
+}
+/**
+ * Extract all import/require module specifiers from a file's content.
+ *
+ * This is a pure function — no I/O. Takes content string, returns matches.
+ */
+export declare function extractImports(file: string, content: string): ImportMatch[];
+/**
+ * Result of resolving imports across multiple files.
+ */
+export interface ResolvedImports {
+    /** All import matches found across files */
+    imports: ImportMatch[];
+    /** Files that were successfully read */
+    filesRead: string[];
+    /** Errors encountered during resolution */
+    errors: Array<{
+        file: string;
+        message: string;
+    }>;
+}
+/**
+ * Resolve imports from files matching glob patterns.
+ *
+ * Expands globs, reads files, and extracts all imports.
+ */
+export declare function resolveImports(options: {
+    files: string[];
+    cwd?: string;
+    fs: FileSystem;
+}): Promise<ResolvedImports>;
+//# sourceMappingURL=import-resolver.d.ts.map

package/dist/core/resolvers/import-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-resolver.d.ts","sourceRoot":"","sources":["../../../src/core/resolvers/import-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;CAChB;AAiBD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,WAAW,EAAE,CAsBf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,2CAA2C;IAC3C,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,UAAU,CAAC;CAChB,GAAG,OAAO,CAAC,eAAe,CAAC,CA0C3B"}

package/dist/core/resolvers/import-resolver.js

@@ -0,0 +1,99 @@
+/**
+ * Import resolver — scans files for import/require statements.
+ *
+ * Extracts structured import data from TypeScript/JavaScript files.
+ * Used by assertNoSideEffects to check for forbidden module imports.
+ *
+ * Design:
+ * - Depends on FileSystem interface (mockable for tests)
+ * - Returns structured data for pure assertion validation
+ */
+import { join } from 'node:path';
+/**
+ * Patterns to match import/require statements.
+ * Captures the module specifier from:
+ * - import ... from 'module'
+ * - import 'module'
+ * - require('module')
+ * - import('module')  (dynamic import)
+ */
+const IMPORT_PATTERNS = [
+    /import\s+.*?\s+from\s+['"]([^'"]+)['"]/,
+    /import\s+['"]([^'"]+)['"]/,
+    /require\(\s*['"]([^'"]+)['"]\s*\)/,
+    /import\(\s*['"]([^'"]+)['"]\s*\)/,
+];
+/**
+ * Extract all import/require module specifiers from a file's content.
+ *
+ * This is a pure function — no I/O. Takes content string, returns matches.
+ */
+export function extractImports(file, content) {
+    const matches = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const lineText = lines[i];
+        for (const pattern of IMPORT_PATTERNS) {
+            const match = pattern.exec(lineText);
+            if (match && match[1]) {
+                matches.push({
+                    file,
+                    line: i + 1,
+                    lineText,
+                    module: match[1],
+                });
+                break; // One match per line is sufficient
+            }
+        }
+    }
+    return matches;
+}
+/**
+ * Resolve imports from files matching glob patterns.
+ *
+ * Expands globs, reads files, and extracts all imports.
+ */
+export async function resolveImports(options) {
+    const { files, cwd, fs } = options;
+    const imports = [];
+    const filesRead = [];
+    const errors = [];
+    // Expand globs
+    const expandedPaths = [];
+    for (const file of files) {
+        if (file.includes('*') || file.includes('?')) {
+            try {
+                const expanded = await fs.glob(file, cwd ? { cwd } : undefined);
+                expandedPaths.push(...expanded);
+            }
+            catch (err) {
+                errors.push({
+                    file,
+                    message: `Failed to expand glob: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+        else {
+            expandedPaths.push(file);
+        }
+    }
+    // Read files and extract imports
+    for (const filePath of expandedPaths) {
+        const readPath = cwd ? join(cwd, filePath) : filePath;
+        let content;
+        try {
+            content = await fs.readFile(readPath);
+        }
+        catch (err) {
+            errors.push({
+                file: filePath,
+                message: `Failed to read file: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            continue;
+        }
+        filesRead.push(filePath);
+        imports.push(...extractImports(filePath, content));
+    }
+    return { imports, filesRead, errors };
+}
+//# sourceMappingURL=import-resolver.js.map

package/dist/core/resolvers/import-resolver.js.map

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

package/dist/core/resolvers/node-fs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Default Node.js FileSystem implementation.
+ *
+ * Uses node:fs/promises for file reading and fast-glob for glob expansion.
+ * This is the default filesystem used by assertMaxValue when no custom
+ * FileSystem is provided.
+ */
+import type { FileSystem } from './types.js';
+/**
+ * Create a FileSystem backed by Node.js built-in modules + fast-glob.
+ */
+export declare function createNodeFileSystem(): FileSystem;
+//# sourceMappingURL=node-fs.d.ts.map

package/dist/core/resolvers/node-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs.d.ts","sourceRoot":"","sources":["../../../src/core/resolvers/node-fs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,CAmBjD"}

package/dist/core/resolvers/node-fs.js

@@ -0,0 +1,32 @@
+/**
+ * Default Node.js FileSystem implementation.
+ *
+ * Uses node:fs/promises for file reading and fast-glob for glob expansion.
+ * This is the default filesystem used by assertMaxValue when no custom
+ * FileSystem is provided.
+ */
+import { readFile, access } from 'node:fs/promises';
+import fg from 'fast-glob';
+/**
+ * Create a FileSystem backed by Node.js built-in modules + fast-glob.
+ */
+export function createNodeFileSystem() {
+    return {
+        async readFile(path) {
+            return readFile(path, 'utf-8');
+        },
+        async glob(pattern, options) {
+            return fg(pattern, { cwd: options?.cwd });
+        },
+        async exists(path) {
+            try {
+                await access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=node-fs.js.map

package/dist/core/resolvers/node-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs.js","sourceRoot":"","sources":["../../../src/core/resolvers/node-fs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,MAAM,WAAW,CAAC;AAG3B;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,IAAY;YACzB,OAAO,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjC,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,OAA0B;YACpD,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QAC5C,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,IAAY;YACvB,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;gBACnB,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/resolvers/parallel-reader.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Parallel reader — batched file reading with concurrency control.
+ *
+ * Provides a shared utility for reading multiple files in parallel
+ * using Promise.allSettled with a configurable concurrency limit
+ * to avoid file descriptor exhaustion.
+ *
+ * Used by file-resolver.ts and other resolvers for efficient I/O.
+ */
+import type { FileSystem } from './types.js';
+/**
+ * Result of reading a single file.
+ */
+export interface FileReadResult {
+    /** The file path that was read */
+    path: string;
+    /** The file content (undefined if reading failed) */
+    content?: string;
+    /** Error message if reading failed */
+    error?: string;
+}
+/**
+ * Read multiple files in parallel with concurrency control.
+ *
+ * Uses Promise.allSettled to ensure all reads complete (or fail)
+ * without aborting on the first error. Files are processed in
+ * batches to avoid exhausting file descriptors.
+ *
+ * @param paths - File paths to read
+ * @param fs - FileSystem implementation
+ * @param concurrency - Maximum number of concurrent reads (default: 50)
+ * @returns Results for each file (success or error)
+ */
+export declare function readFilesParallel(paths: string[], fs: FileSystem, concurrency?: number): Promise<FileReadResult[]>;
+//# sourceMappingURL=parallel-reader.d.ts.map

package/dist/core/resolvers/parallel-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-reader.d.ts","sourceRoot":"","sources":["../../../src/core/resolvers/parallel-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAO7C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EAAE,EACf,EAAE,EAAE,UAAU,EACd,WAAW,GAAE,MAA4B,GACxC,OAAO,CAAC,cAAc,EAAE,CAAC,CAkC3B"}