@organon-methodology/testing 0.3.0

package/dist/core/assert-max-value.d.ts

@@ -0,0 +1,79 @@
+/**
+ * assertMaxValue — High-level assertion that combines file resolution with pure validation.
+ *
+ * This is the public API function users call in their tests:
+ * ```typescript
+ * await assertMaxValue({
+ *   files: ['src/config/*.ts'],
+ *   pattern: /ttl:\s*(\d+)/,
+ *   maxValue: 86400,
+ *   unit: 'seconds',
+ * });
+ * ```
+ *
+ * Architecture:
+ * - Uses resolvers/file-resolver.ts to read files and extract values (I/O layer)
+ * - Delegates to assertions/max-value.ts for pure validation (no I/O)
+ * - This module is the composition layer that wires I/O to pure logic
+ *
+ * Invariants:
+ * - INV-TEST-2 (fail-fast): Throws on violation or resolver errors
+ * - INV-TEST-6 (always-async): Returns Promise<void>
+ * - INV-TEST-7 (composable): No module-level mutable state
+ */
+import type { FileSystem } from './resolvers/types.js';
+/**
+ * Options for assertMaxValue.
+ *
+ * Uses the options-object pattern (RFC 001 Design Decision 4: Clarity > Conciseness).
+ */
+export interface MaxValueOptions {
+    /** File paths or glob patterns to scan */
+    files: string[];
+    /** Regex with a capturing group for the numeric value */
+    pattern: RegExp;
+    /** Upper bound (inclusive) that values must not exceed */
+    maxValue: number;
+    /** Optional unit for error messages (e.g., "seconds", "bytes") */
+    unit?: string;
+    /** Optional working directory for glob resolution */
+    cwd?: string;
+    /** Optional FileSystem implementation (defaults to Node.js fs + fast-glob) */
+    fs?: FileSystem;
+    /**
+     * Require at least one value to be extracted (default: true).
+     * When true, throws if no files match the glob or no lines match the pattern.
+     * This prevents silent passes from typos in file globs or regex patterns.
+     * Set to false when the absence of matches is a valid (expected) outcome.
+     */
+    requireMatches?: boolean;
+}
+/**
+ * Error thrown when assertMaxValue encounters resolver-level errors
+ * (e.g., files not found, globs failing, non-numeric captures).
+ */
+export declare class MaxValueResolverError extends Error {
+    readonly resolverErrors: Array<{
+        file: string;
+        message: string;
+    }>;
+    constructor(errors: Array<{
+        file: string;
+        message: string;
+    }>);
+}
+/**
+ * Assert that numeric values extracted from files do not exceed a maximum.
+ *
+ * Workflow:
+ * 1. Expand glob patterns and read files (resolver layer)
+ * 2. Extract numeric values matching the pattern
+ * 3. Validate all values against maxValue (pure assertion)
+ *
+ * @param options - Configuration including files, pattern, maxValue, and optional fs/cwd/unit
+ * @throws {MaxValueResolverError} if files can't be read or values can't be extracted
+ * @throws {MaxValueAssertionError} if any value exceeds maxValue
+ */
+export declare function assertMaxValue(options: MaxValueOptions): Promise<void>;
+export { MaxValueAssertionError } from './assertions/max-value.js';
+//# sourceMappingURL=assert-max-value.d.ts.map

package/dist/core/assert-max-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-max-value.d.ts","sourceRoot":"","sources":["../../src/core/assert-max-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAKvD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,cAAc,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;gBAE7D,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAQ7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAsCf;AAGD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/core/assert-max-value.js

@@ -0,0 +1,90 @@
+/**
+ * assertMaxValue — High-level assertion that combines file resolution with pure validation.
+ *
+ * This is the public API function users call in their tests:
+ * ```typescript
+ * await assertMaxValue({
+ *   files: ['src/config/*.ts'],
+ *   pattern: /ttl:\s*(\d+)/,
+ *   maxValue: 86400,
+ *   unit: 'seconds',
+ * });
+ * ```
+ *
+ * Architecture:
+ * - Uses resolvers/file-resolver.ts to read files and extract values (I/O layer)
+ * - Delegates to assertions/max-value.ts for pure validation (no I/O)
+ * - This module is the composition layer that wires I/O to pure logic
+ *
+ * Invariants:
+ * - INV-TEST-2 (fail-fast): Throws on violation or resolver errors
+ * - INV-TEST-6 (always-async): Returns Promise<void>
+ * - INV-TEST-7 (composable): No module-level mutable state
+ */
+import { resolveValues } from './resolvers/file-resolver.js';
+import { validateMaxValue } from './assertions/max-value.js';
+import { createNodeFileSystem } from './resolvers/node-fs.js';
+/**
+ * Error thrown when assertMaxValue encounters resolver-level errors
+ * (e.g., files not found, globs failing, non-numeric captures).
+ */
+export class MaxValueResolverError extends Error {
+    resolverErrors;
+    constructor(errors) {
+        const details = errors
+            .map((e) => `  ${e.file}: ${e.message}`)
+            .join('\n');
+        super(`assertMaxValue resolver errors:\n${details}`);
+        this.name = 'MaxValueResolverError';
+        this.resolverErrors = errors;
+    }
+}
+/**
+ * Assert that numeric values extracted from files do not exceed a maximum.
+ *
+ * Workflow:
+ * 1. Expand glob patterns and read files (resolver layer)
+ * 2. Extract numeric values matching the pattern
+ * 3. Validate all values against maxValue (pure assertion)
+ *
+ * @param options - Configuration including files, pattern, maxValue, and optional fs/cwd/unit
+ * @throws {MaxValueResolverError} if files can't be read or values can't be extracted
+ * @throws {MaxValueAssertionError} if any value exceeds maxValue
+ */
+export async function assertMaxValue(options) {
+    const { files, pattern, maxValue, unit, cwd, fs, requireMatches = true } = options;
+    const resolvedFs = fs ?? createNodeFileSystem();
+    // 0. Fail-fast on empty files array (INV-TEST-2)
+    if (files.length === 0) {
+        throw new MaxValueResolverError([{
+                file: '(none)',
+                message: 'No file patterns provided. The files array must not be empty.',
+            }]);
+    }
+    // 1. Resolve files and extract values
+    const resolved = await resolveValues({ files, pattern, cwd }, resolvedFs);
+    // 2. Fail-fast on resolver errors (INV-TEST-2)
+    if (resolved.errors.length > 0) {
+        throw new MaxValueResolverError(resolved.errors);
+    }
+    // 3. Fail-fast when no values found and requireMatches is true (INV-TEST-2)
+    //    Prevents silent passes from typos in file globs or regex patterns.
+    if (requireMatches && resolved.values.length === 0) {
+        const filesDetail = resolved.filesRead.length === 0
+            ? 'No files matched the glob pattern(s).'
+            : `Searched ${resolved.filesRead.length} file(s) but pattern matched no lines.`;
+        throw new MaxValueResolverError([{
+                file: files.join(', '),
+                message: `No values extracted. ${filesDetail} Check your file globs and regex pattern.`,
+            }]);
+    }
+    // 4. Validate extracted values against the maximum (pure assertion, sync)
+    validateMaxValue({
+        values: resolved.values,
+        maxValue,
+        unit,
+    });
+}
+// Re-export assertion error for consumers
+export { MaxValueAssertionError } from './assertions/max-value.js';
+//# sourceMappingURL=assert-max-value.js.map

package/dist/core/assert-max-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-max-value.js","sourceRoot":"","sources":["../../src/core/assert-max-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAA0B,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AA6B9D;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9B,cAAc,CAA2C;IAEzE,YAAY,MAAgD;QAC1D,MAAM,OAAO,GAAG,MAAM;aACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACvC,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,KAAK,CAAC,oCAAoC,OAAO,EAAE,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAwB;IAExB,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACnF,MAAM,UAAU,GAAG,EAAE,IAAI,oBAAoB,EAAE,CAAC;IAEhD,iDAAiD;IACjD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,qBAAqB,CAAC,CAAC;gBAC/B,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,+DAA+D;aACzE,CAAC,CAAC,CAAC;IACN,CAAC;IAED,sCAAsC;IACtC,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;IAE1E,+CAA+C;IAC/C,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IAED,4EAA4E;IAC5E,wEAAwE;IACxE,IAAI,cAAc,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnD,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YACjD,CAAC,CAAC,uCAAuC;YACzC,CAAC,CAAC,YAAY,QAAQ,CAAC,SAAS,CAAC,MAAM,wCAAwC,CAAC;QAClF,MAAM,IAAI,qBAAqB,CAAC,CAAC;gBAC/B,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;gBACtB,OAAO,EAAE,wBAAwB,WAAW,2CAA2C;aACxF,CAAC,CAAC,CAAC;IACN,CAAC;IAED,0EAA0E;IAC1E,gBAAgB,CAAC;QACf,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,QAAQ;QACR,IAAI;KACL,CAAC,CAAC;AACL,CAAC;AAED,0CAA0C;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/core/assert-naming-convention.d.ts

@@ -0,0 +1,61 @@
+/**
+ * assertNamingConvention — High-level assertion that checks naming conventions.
+ *
+ * Two modes:
+ * - 'filenames': checks file stems (filename without extension) against the convention
+ * - 'identifiers': extracts identifiers from code via regex and checks them
+ *
+ * Architecture:
+ * - Uses resolvers/string-resolver.ts to extract strings (I/O layer)
+ * - Delegates to assertions/naming-convention.ts for pure validation (no I/O)
+ *
+ * Invariants:
+ * - INV-TEST-2 (fail-fast): Throws on violation or resolver errors
+ * - INV-TEST-6 (always-async): Returns Promise<void>
+ * - INV-TEST-7 (composable): No module-level mutable state
+ */
+import type { FileSystem } from './resolvers/types.js';
+import { type Convention } from './assertions/naming-convention.js';
+/**
+ * Options for assertNamingConvention.
+ */
+export interface NamingConventionOptions {
+    /** Check mode: 'filenames' checks file stems, 'identifiers' extracts from code */
+    mode: 'filenames' | 'identifiers';
+    /** File paths or glob patterns */
+    files: string[];
+    /** The naming convention to enforce */
+    convention: Convention;
+    /** Regex with capturing group for identifier extraction (required for 'identifiers' mode) */
+    pattern?: RegExp;
+    /** Names to exclude from validation */
+    exceptions?: string[];
+    /** Optional working directory */
+    cwd?: string;
+    /** Optional FileSystem implementation */
+    fs?: FileSystem;
+}
+/**
+ * Error thrown when assertNamingConvention encounters resolver-level errors.
+ */
+export declare class NamingConventionResolverError extends Error {
+    readonly resolverErrors: Array<{
+        file: string;
+        message: string;
+    }>;
+    constructor(errors: Array<{
+        file: string;
+        message: string;
+    }>);
+}
+/**
+ * Assert that names follow a specified naming convention.
+ *
+ * @param options - Configuration including mode, files, convention, and optional pattern
+ * @throws {NamingConventionResolverError} if files can't be resolved
+ * @throws {NamingConventionAssertionError} if any name violates the convention
+ */
+export declare function assertNamingConvention(options: NamingConventionOptions): Promise<void>;
+export { NamingConventionAssertionError } from './assertions/naming-convention.js';
+export type { Convention } from './assertions/naming-convention.js';
+//# sourceMappingURL=assert-naming-convention.d.ts.map

package/dist/core/assert-naming-convention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-naming-convention.d.ts","sourceRoot":"","sources":["../../src/core/assert-naming-convention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,mCAAmC,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,IAAI,EAAE,WAAW,GAAG,aAAa,CAAC;IAClC,kCAAkC;IAClC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uCAAuC;IACvC,UAAU,EAAE,UAAU,CAAC;IACvB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,SAAgB,cAAc,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;gBAE7D,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAQ7D;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAwDf;AAGD,OAAO,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACnF,YAAY,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/core/assert-naming-convention.js

@@ -0,0 +1,92 @@
+/**
+ * assertNamingConvention — High-level assertion that checks naming conventions.
+ *
+ * Two modes:
+ * - 'filenames': checks file stems (filename without extension) against the convention
+ * - 'identifiers': extracts identifiers from code via regex and checks them
+ *
+ * Architecture:
+ * - Uses resolvers/string-resolver.ts to extract strings (I/O layer)
+ * - Delegates to assertions/naming-convention.ts for pure validation (no I/O)
+ *
+ * Invariants:
+ * - INV-TEST-2 (fail-fast): Throws on violation or resolver errors
+ * - INV-TEST-6 (always-async): Returns Promise<void>
+ * - INV-TEST-7 (composable): No module-level mutable state
+ */
+import { createNodeFileSystem } from './resolvers/node-fs.js';
+import { resolveFileStems, resolveStringsByPattern } from './resolvers/string-resolver.js';
+import { validateNamingConvention, } from './assertions/naming-convention.js';
+/**
+ * Error thrown when assertNamingConvention encounters resolver-level errors.
+ */
+export class NamingConventionResolverError extends Error {
+    resolverErrors;
+    constructor(errors) {
+        const details = errors
+            .map((e) => `  ${e.file}: ${e.message}`)
+            .join('\n');
+        super(`assertNamingConvention resolver errors:\n${details}`);
+        this.name = 'NamingConventionResolverError';
+        this.resolverErrors = errors;
+    }
+}
+/**
+ * Assert that names follow a specified naming convention.
+ *
+ * @param options - Configuration including mode, files, convention, and optional pattern
+ * @throws {NamingConventionResolverError} if files can't be resolved
+ * @throws {NamingConventionAssertionError} if any name violates the convention
+ */
+export async function assertNamingConvention(options) {
+    const { mode, files, convention, pattern, exceptions, cwd, fs } = options;
+    const resolvedFs = fs ?? createNodeFileSystem();
+    // Fail-fast on empty files array (INV-TEST-2)
+    if (files.length === 0) {
+        throw new NamingConventionResolverError([{
+                file: '(none)',
+                message: 'No file patterns provided. The files array must not be empty.',
+            }]);
+    }
+    // Fail-fast on identifiers mode without pattern
+    if (mode === 'identifiers' && !pattern) {
+        throw new NamingConventionResolverError([{
+                file: '(none)',
+                message: 'The pattern option is required for identifiers mode.',
+            }]);
+    }
+    if (mode === 'filenames') {
+        const resolved = await resolveFileStems({ files, cwd, fs: resolvedFs });
+        if (resolved.errors.length > 0) {
+            throw new NamingConventionResolverError(resolved.errors);
+        }
+        if (resolved.strings.length === 0) {
+            throw new NamingConventionResolverError([{
+                    file: files.join(', '),
+                    message: 'No files matched the glob pattern(s). Check your file globs.',
+                }]);
+        }
+        validateNamingConvention(resolved.strings, convention, exceptions);
+    }
+    else {
+        const resolved = await resolveStringsByPattern({
+            files,
+            pattern: pattern,
+            cwd,
+            fs: resolvedFs,
+        });
+        if (resolved.errors.length > 0) {
+            throw new NamingConventionResolverError(resolved.errors);
+        }
+        if (resolved.filesRead.length === 0) {
+            throw new NamingConventionResolverError([{
+                    file: files.join(', '),
+                    message: 'No files matched the glob pattern(s). Check your file globs.',
+                }]);
+        }
+        validateNamingConvention(resolved.strings, convention, exceptions);
+    }
+}
+// Re-export for consumers
+export { NamingConventionAssertionError } from './assertions/naming-convention.js';
+//# sourceMappingURL=assert-naming-convention.js.map

package/dist/core/assert-naming-convention.js.map

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

package/dist/core/assert-no-side-effects.d.ts

@@ -0,0 +1,55 @@
+/**
+ * assertNoSideEffects — High-level assertion that checks for forbidden imports.
+ *
+ * Architecture:
+ * - Uses resolvers/import-resolver.ts to scan files for imports (I/O layer)
+ * - Delegates to assertions/no-side-effects.ts for pure validation (no I/O)
+ * - This module is the composition layer that wires I/O to pure logic
+ *
+ * Invariants:
+ * - INV-TEST-2 (fail-fast): Throws on violation or resolver errors
+ * - INV-TEST-6 (always-async): Returns Promise<void>
+ * - INV-TEST-7 (composable): No module-level mutable state
+ */
+import type { FileSystem } from './resolvers/types.js';
+/**
+ * Options for assertNoSideEffects.
+ */
+export interface NoSideEffectsOptions {
+    /** File paths or glob patterns to scan */
+    files: string[];
+    /** Module names to forbid (e.g., ['fs', 'http', 'vitest']) */
+    forbiddenModules: string[];
+    /** Optional working directory for glob resolution */
+    cwd?: string;
+    /** Optional FileSystem implementation */
+    fs?: FileSystem;
+    /**
+     * Require at least one file to be scanned (default: true).
+     * When true, throws if no files match the glob patterns.
+     */
+    requireMatches?: boolean;
+}
+/**
+ * Error thrown when assertNoSideEffects encounters resolver-level errors.
+ */
+export declare class NoSideEffectsResolverError extends Error {
+    readonly resolverErrors: Array<{
+        file: string;
+        message: string;
+    }>;
+    constructor(errors: Array<{
+        file: string;
+        message: string;
+    }>);
+}
+/**
+ * Assert that files do not import any forbidden modules.
+ *
+ * @param options - Configuration including files, forbiddenModules, and optional fs/cwd
+ * @throws {NoSideEffectsResolverError} if files can't be read or globs fail
+ * @throws {NoSideEffectsAssertionError} if any forbidden import is found
+ */
+export declare function assertNoSideEffects(options: NoSideEffectsOptions): Promise<void>;
+export { NoSideEffectsAssertionError } from './assertions/no-side-effects.js';
+//# sourceMappingURL=assert-no-side-effects.d.ts.map

package/dist/core/assert-no-side-effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-no-side-effects.d.ts","sourceRoot":"","sources":["../../src/core/assert-no-side-effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAQvD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAgB,cAAc,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;gBAE7D,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAQ7D;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAqCf;AAGD,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/core/assert-no-side-effects.js

@@ -0,0 +1,72 @@
+/**
+ * assertNoSideEffects — High-level assertion that checks for forbidden imports.
+ *
+ * Architecture:
+ * - Uses resolvers/import-resolver.ts to scan files for imports (I/O layer)
+ * - Delegates to assertions/no-side-effects.ts for pure validation (no I/O)
+ * - This module is the composition layer that wires I/O to pure logic
+ *
+ * Invariants:
+ * - INV-TEST-2 (fail-fast): Throws on violation or resolver errors
+ * - INV-TEST-6 (always-async): Returns Promise<void>
+ * - INV-TEST-7 (composable): No module-level mutable state
+ */
+import { createNodeFileSystem } from './resolvers/node-fs.js';
+import { resolveImports } from './resolvers/import-resolver.js';
+import { validateNoSideEffects, } from './assertions/no-side-effects.js';
+/**
+ * Error thrown when assertNoSideEffects encounters resolver-level errors.
+ */
+export class NoSideEffectsResolverError extends Error {
+    resolverErrors;
+    constructor(errors) {
+        const details = errors
+            .map((e) => `  ${e.file}: ${e.message}`)
+            .join('\n');
+        super(`assertNoSideEffects resolver errors:\n${details}`);
+        this.name = 'NoSideEffectsResolverError';
+        this.resolverErrors = errors;
+    }
+}
+/**
+ * Assert that files do not import any forbidden modules.
+ *
+ * @param options - Configuration including files, forbiddenModules, and optional fs/cwd
+ * @throws {NoSideEffectsResolverError} if files can't be read or globs fail
+ * @throws {NoSideEffectsAssertionError} if any forbidden import is found
+ */
+export async function assertNoSideEffects(options) {
+    const { files, forbiddenModules, cwd, fs, requireMatches = true } = options;
+    const resolvedFs = fs ?? createNodeFileSystem();
+    // Fail-fast on empty inputs (INV-TEST-2)
+    if (files.length === 0) {
+        throw new NoSideEffectsResolverError([{
+                file: '(none)',
+                message: 'No file patterns provided. The files array must not be empty.',
+            }]);
+    }
+    if (forbiddenModules.length === 0) {
+        throw new NoSideEffectsResolverError([{
+                file: '(none)',
+                message: 'No forbidden modules provided. The forbiddenModules array must not be empty.',
+            }]);
+    }
+    // Resolve imports from files
+    const resolved = await resolveImports({ files, cwd, fs: resolvedFs });
+    // Fail-fast on resolver errors (INV-TEST-2)
+    if (resolved.errors.length > 0) {
+        throw new NoSideEffectsResolverError(resolved.errors);
+    }
+    // Fail-fast when no files found and requireMatches is true
+    if (requireMatches && resolved.filesRead.length === 0) {
+        throw new NoSideEffectsResolverError([{
+                file: files.join(', '),
+                message: 'No files matched the glob pattern(s). Check your file globs.',
+            }]);
+    }
+    // Delegate to pure validator
+    validateNoSideEffects(resolved.imports, forbiddenModules);
+}
+// Re-export assertion error for consumers
+export { NoSideEffectsAssertionError } from './assertions/no-side-effects.js';
+//# sourceMappingURL=assert-no-side-effects.js.map

package/dist/core/assert-no-side-effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-no-side-effects.js","sourceRoot":"","sources":["../../src/core/assert-no-side-effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EACL,qBAAqB,GAEtB,MAAM,iCAAiC,CAAC;AAqBzC;;GAEG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnC,cAAc,CAA2C;IAEzE,YAAY,MAAgD;QAC1D,MAAM,OAAO,GAAG,MAAM;aACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACvC,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,KAAK,CAAC,yCAAyC,OAAO,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAA6B;IAE7B,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAC5E,MAAM,UAAU,GAAG,EAAE,IAAI,oBAAoB,EAAE,CAAC;IAEhD,yCAAyC;IACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,0BAA0B,CAAC,CAAC;gBACpC,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,+DAA+D;aACzE,CAAC,CAAC,CAAC;IACN,CAAC;IAED,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,0BAA0B,CAAC,CAAC;gBACpC,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,8EAA8E;aACxF,CAAC,CAAC,CAAC;IACN,CAAC;IAED,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;IAEtE,4CAA4C;IAC5C,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,0BAA0B,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxD,CAAC;IAED,2DAA2D;IAC3D,IAAI,cAAc,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,0BAA0B,CAAC,CAAC;gBACpC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;gBACtB,OAAO,EAAE,8DAA8D;aACxE,CAAC,CAAC,CAAC;IACN,CAAC;IAED,6BAA6B;IAC7B,qBAAqB,CAAC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;AAC5D,CAAC;AAED,0CAA0C;AAC1C,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/core/assertions/exports-present.d.ts

@@ -0,0 +1,38 @@
+/**
+ * validateExportsPresent — Pure assertion that checks expected exports exist.
+ *
+ * Invariants enforced:
+ * - INV-TEST-1 (assertion-logic-pure): No I/O imports. Operates on pre-resolved data.
+ * - INV-TEST-2 (fail-fast): Throws on violation (collects all before throwing).
+ * - INV-TEST-7 (composable): No module-level mutable state.
+ *
+ * This module must NEVER import fs, http, process, or any I/O module.
+ */
+/**
+ * A missing export violation.
+ */
+export interface ExportsPresentViolation {
+    /** The expected export name that was not found */
+    name: string;
+    /** The file that was scanned */
+    file: string;
+}
+/**
+ * Error thrown when an exports-present assertion fails.
+ */
+export declare class ExportsPresentAssertionError extends Error {
+    readonly violations: ExportsPresentViolation[];
+    constructor(violations: ExportsPresentViolation[]);
+}
+/**
+ * Validate that all expected export names are present in the found exports list.
+ *
+ * This is a pure, synchronous function: no I/O, no side effects, deterministic.
+ *
+ * @param file - The file being checked (for error messages)
+ * @param expectedExports - Names that must be exported
+ * @param foundExports - Names that were actually found as exports
+ * @throws {ExportsPresentAssertionError} if any expected export is missing
+ */
+export declare function validateExportsPresent(file: string, expectedExports: string[], foundExports: string[]): void;
+//# sourceMappingURL=exports-present.d.ts.map

package/dist/core/assertions/exports-present.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports-present.d.ts","sourceRoot":"","sources":["../../../src/core/assertions/exports-present.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAgB,UAAU,EAAE,uBAAuB,EAAE,CAAC;gBAE1C,UAAU,EAAE,uBAAuB,EAAE;CAYlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,EAAE,EACzB,YAAY,EAAE,MAAM,EAAE,GACrB,IAAI,CAaN"}

package/dist/core/assertions/exports-present.js

@@ -0,0 +1,47 @@
+/**
+ * validateExportsPresent — Pure assertion that checks expected exports exist.
+ *
+ * Invariants enforced:
+ * - INV-TEST-1 (assertion-logic-pure): No I/O imports. Operates on pre-resolved data.
+ * - INV-TEST-2 (fail-fast): Throws on violation (collects all before throwing).
+ * - INV-TEST-7 (composable): No module-level mutable state.
+ *
+ * This module must NEVER import fs, http, process, or any I/O module.
+ */
+/**
+ * Error thrown when an exports-present assertion fails.
+ */
+export class ExportsPresentAssertionError extends Error {
+    violations;
+    constructor(violations) {
+        const details = violations
+            .map((v) => `  ${v.file} — missing export "${v.name}"`)
+            .join('\n');
+        super(`Exports present assertion failed: ${violations.length} missing export(s)\n${details}`);
+        this.name = 'ExportsPresentAssertionError';
+        this.violations = violations;
+    }
+}
+/**
+ * Validate that all expected export names are present in the found exports list.
+ *
+ * This is a pure, synchronous function: no I/O, no side effects, deterministic.
+ *
+ * @param file - The file being checked (for error messages)
+ * @param expectedExports - Names that must be exported
+ * @param foundExports - Names that were actually found as exports
+ * @throws {ExportsPresentAssertionError} if any expected export is missing
+ */
+export function validateExportsPresent(file, expectedExports, foundExports) {
+    const foundSet = new Set(foundExports);
+    const violations = [];
+    for (const name of expectedExports) {
+        if (!foundSet.has(name)) {
+            violations.push({ name, file });
+        }
+    }
+    if (violations.length > 0) {
+        throw new ExportsPresentAssertionError(violations);
+    }
+}
+//# sourceMappingURL=exports-present.js.map

package/dist/core/assertions/exports-present.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports-present.js","sourceRoot":"","sources":["../../../src/core/assertions/exports-present.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH;;GAEG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrC,UAAU,CAA4B;IAEtD,YAAY,UAAqC;QAC/C,MAAM,OAAO,GAAG,UAAU;aACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,sBAAsB,CAAC,CAAC,IAAI,GAAG,CAAC;aACtD,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,KAAK,CACH,qCAAqC,UAAU,CAAC,MAAM,uBAAuB,OAAO,EAAE,CACvF,CAAC;QAEF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAY,EACZ,eAAyB,EACzB,YAAsB;IAEtB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,UAAU,GAA8B,EAAE,CAAC;IAEjD,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,4BAA4B,CAAC,UAAU,CAAC,CAAC;IACrD,CAAC;AACH,CAAC"}

package/dist/core/assertions/file-exists.d.ts

@@ -0,0 +1,45 @@
+/**
+ * validateFileExists — Pure assertion that validates file existence results.
+ *
+ * Invariants enforced:
+ * - INV-TEST-1 (assertion-logic-pure): No I/O imports. Operates on pre-resolved data.
+ * - INV-TEST-2 (fail-fast): Throws on violation (collects all before throwing for better diagnostics).
+ * - INV-TEST-6 (always-async): Public API is async; pure validators are sync.
+ * - INV-TEST-7 (composable): No module-level mutable state.
+ *
+ * This module must NEVER import fs, http, process, or any I/O module.
+ * File existence checking is handled by the resolver layer (core/resolvers/).
+ */
+/**
+ * A single file existence check result fed by the resolver layer.
+ */
+export interface FileExistsEntry {
+    /** Path of the file that was checked */
+    file: string;
+    /** Whether the file exists */
+    exists: boolean;
+}
+/**
+ * A violation: a file that was expected to exist but doesn't.
+ */
+export interface FileExistsViolation {
+    /** Path of the missing file */
+    file: string;
+}
+/**
+ * Error thrown when a file-exists assertion fails.
+ * Contains structured violation data for programmatic access.
+ */
+export declare class FileExistsAssertionError extends Error {
+    readonly violations: FileExistsViolation[];
+    constructor(violations: FileExistsViolation[]);
+}
+/**
+ * Validate that all checked files exist.
+ *
+ * This is a pure, synchronous function: no I/O, no side effects, deterministic.
+ *
+ * @throws {FileExistsAssertionError} if any file does not exist (INV-TEST-2: fail-fast)
+ */
+export declare function validateFileExists(entries: FileExistsEntry[]): void;
+//# sourceMappingURL=file-exists.d.ts.map

package/dist/core/assertions/file-exists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-exists.d.ts","sourceRoot":"","sources":["../../../src/core/assertions/file-exists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,SAAgB,UAAU,EAAE,mBAAmB,EAAE,CAAC;gBAEtC,UAAU,EAAE,mBAAmB,EAAE;CAY9C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,IAAI,CAYnE"}