@organon-methodology/testing 0.3.0

package/dist/core/assertions/file-exists.js

@@ -0,0 +1,46 @@
+/**
+ * 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/).
+ */
+/**
+ * Error thrown when a file-exists assertion fails.
+ * Contains structured violation data for programmatic access.
+ */
+export class FileExistsAssertionError extends Error {
+    violations;
+    constructor(violations) {
+        const details = violations
+            .map((v) => `  ${v.file}`)
+            .join('\n');
+        super(`File exists assertion failed: ${violations.length} missing file(s)\n${details}`);
+        this.name = 'FileExistsAssertionError';
+        this.violations = violations;
+    }
+}
+/**
+ * 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 function validateFileExists(entries) {
+    const violations = [];
+    for (const entry of entries) {
+        if (!entry.exists) {
+            violations.push({ file: entry.file });
+        }
+    }
+    if (violations.length > 0) {
+        throw new FileExistsAssertionError(violations);
+    }
+}
+//# sourceMappingURL=file-exists.js.map

package/dist/core/assertions/file-exists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-exists.js","sourceRoot":"","sources":["../../../src/core/assertions/file-exists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoBH;;;GAGG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjC,UAAU,CAAwB;IAElD,YAAY,UAAiC;QAC3C,MAAM,OAAO,GAAG,UAAU;aACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;aACzB,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,KAAK,CACH,iCAAiC,UAAU,CAAC,MAAM,qBAAqB,OAAO,EAAE,CACjF,CAAC;QAEF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA0B;IAC3D,MAAM,UAAU,GAA0B,EAAE,CAAC;IAE7C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAClB,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,wBAAwB,CAAC,UAAU,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,77 @@
+/**
+ * assertMaxValue — Pure assertion that validates numeric values against a maximum.
+ *
+ * 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 reading is handled by the resolver layer (core/resolvers/).
+ */
+/**
+ * A single extracted value to validate against the maximum.
+ * This is the pre-resolved data structure fed by the resolver layer.
+ */
+export interface MaxValueEntry {
+    /** 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;
+}
+/**
+ * Options for the pure max-value assertion.
+ * Operates on pre-resolved values (no file paths or patterns).
+ */
+export interface ValidateMaxValueOptions {
+    /** Pre-resolved numeric values to check */
+    values: MaxValueEntry[];
+    /** Upper bound (inclusive) */
+    maxValue: number;
+    /** Optional unit for error messages (e.g., "seconds", "bytes") */
+    unit?: string;
+}
+/**
+ * A violation found by the max-value assertion.
+ */
+export interface MaxValueViolation {
+    /** File where the violation occurred */
+    file: string;
+    /** Line number (1-based) */
+    line: number;
+    /** The line text */
+    lineText: string;
+    /** The actual value that exceeded the max */
+    actualValue: number;
+    /** The maximum allowed value */
+    maxValue: number;
+    /** Optional unit */
+    unit?: string;
+}
+/**
+ * Error thrown when a max-value assertion fails.
+ * Contains structured violation data for programmatic access
+ * plus a human-readable message.
+ */
+export declare class MaxValueAssertionError extends Error {
+    readonly violations: MaxValueViolation[];
+    constructor(violations: MaxValueViolation[]);
+}
+/**
+ * Validate that all pre-resolved values do not exceed a maximum.
+ *
+ * This is a pure, synchronous function: no I/O, no side effects, deterministic.
+ * The resolver layer feeds pre-extracted values; this function only validates.
+ * Collects all violations before throwing for complete diagnostic output.
+ *
+ * @throws {MaxValueAssertionError} if any value exceeds maxValue (INV-TEST-2: fail-fast)
+ */
+export declare function validateMaxValue(options: ValidateMaxValueOptions): void;
+//# sourceMappingURL=max-value.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"max-value.d.ts","sourceRoot":"","sources":["../../../src/core/assertions/max-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,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;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,2CAA2C;IAC3C,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAgB,UAAU,EAAE,iBAAiB,EAAE,CAAC;gBAEpC,UAAU,EAAE,iBAAiB,EAAE;CAe5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAC/B,IAAI,CAqBN"}

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

@@ -0,0 +1,60 @@
+/**
+ * assertMaxValue — Pure assertion that validates numeric values against a maximum.
+ *
+ * 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 reading is handled by the resolver layer (core/resolvers/).
+ */
+/**
+ * Error thrown when a max-value assertion fails.
+ * Contains structured violation data for programmatic access
+ * plus a human-readable message.
+ */
+export class MaxValueAssertionError extends Error {
+    violations;
+    constructor(violations) {
+        const details = violations
+            .map((v) => {
+            const unitSuffix = v.unit ? ` ${v.unit}` : '';
+            return `  ${v.file}:${v.line} — found ${v.actualValue}${unitSuffix}, max allowed is ${v.maxValue}${unitSuffix}\n    > ${v.lineText.trim()}`;
+        })
+            .join('\n');
+        super(`Max value assertion failed: ${violations.length} violation(s) found\n${details}`);
+        this.name = 'MaxValueAssertionError';
+        this.violations = violations;
+    }
+}
+/**
+ * Validate that all pre-resolved values do not exceed a maximum.
+ *
+ * This is a pure, synchronous function: no I/O, no side effects, deterministic.
+ * The resolver layer feeds pre-extracted values; this function only validates.
+ * Collects all violations before throwing for complete diagnostic output.
+ *
+ * @throws {MaxValueAssertionError} if any value exceeds maxValue (INV-TEST-2: fail-fast)
+ */
+export function validateMaxValue(options) {
+    const { values, maxValue, unit } = options;
+    const violations = [];
+    for (const entry of values) {
+        if (entry.value > maxValue) {
+            violations.push({
+                file: entry.file,
+                line: entry.line,
+                lineText: entry.lineText,
+                actualValue: entry.value,
+                maxValue,
+                unit,
+            });
+        }
+    }
+    if (violations.length > 0) {
+        throw new MaxValueAssertionError(violations);
+    }
+}
+//# sourceMappingURL=max-value.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"max-value.js","sourceRoot":"","sources":["../../../src/core/assertions/max-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkDH;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/B,UAAU,CAAsB;IAEhD,YAAY,UAA+B;QACzC,MAAM,OAAO,GAAG,UAAU;aACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,OAAO,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,WAAW,GAAG,UAAU,oBAAoB,CAAC,CAAC,QAAQ,GAAG,UAAU,WAAW,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9I,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,KAAK,CACH,+BAA+B,UAAU,CAAC,MAAM,wBAAwB,OAAO,EAAE,CAClF,CAAC;QAEF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAgC;IAEhC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IAE3C,MAAM,UAAU,GAAwB,EAAE,CAAC;IAE3C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,KAAK,GAAG,QAAQ,EAAE,CAAC;YAC3B,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,WAAW,EAAE,KAAK,CAAC,KAAK;gBACxB,QAAQ;gBACR,IAAI;aACL,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,51 @@
+/**
+ * validateNamingConvention — Pure assertion that checks strings against naming conventions.
+ *
+ * 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.
+ */
+import type { ExtractedString } from '../resolvers/string-resolver.js';
+/**
+ * Supported naming conventions.
+ */
+export type Convention = 'kebab-case' | 'camelCase' | 'PascalCase' | 'SCREAMING_SNAKE_CASE' | 'snake_case';
+/**
+ * Check if a string matches a naming convention.
+ */
+export declare function matchesConvention(value: string, convention: Convention): boolean;
+/**
+ * A naming convention violation.
+ */
+export interface NamingConventionViolation {
+    /** Path of the file */
+    file: string;
+    /** The line number (1-based), or 0 for file-level checks */
+    line: number;
+    /** The name that violates the convention */
+    value: string;
+    /** The expected convention */
+    convention: Convention;
+}
+/**
+ * Error thrown when a naming convention assertion fails.
+ */
+export declare class NamingConventionAssertionError extends Error {
+    readonly violations: NamingConventionViolation[];
+    constructor(violations: NamingConventionViolation[]);
+}
+/**
+ * Validate that all extracted strings match a naming convention.
+ *
+ * This is a pure, synchronous function: no I/O, no side effects, deterministic.
+ *
+ * @param strings - Pre-resolved strings to validate
+ * @param convention - The naming convention to enforce
+ * @param exceptions - Names to exclude from validation
+ * @throws {NamingConventionAssertionError} if any string violates the convention
+ */
+export declare function validateNamingConvention(strings: ExtractedString[], convention: Convention, exceptions?: string[]): void;
+//# sourceMappingURL=naming-convention.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"naming-convention.d.ts","sourceRoot":"","sources":["../../../src/core/assertions/naming-convention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,YAAY,GACZ,WAAW,GACX,YAAY,GACZ,sBAAsB,GACtB,YAAY,CAAC;AAajB;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,UAAU,GACrB,OAAO,CAET;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,SAAgB,UAAU,EAAE,yBAAyB,EAAE,CAAC;gBAE5C,UAAU,EAAE,yBAAyB,EAAE;CAepD;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,eAAe,EAAE,EAC1B,UAAU,EAAE,UAAU,EACtB,UAAU,GAAE,MAAM,EAAO,GACxB,IAAI,CAoBN"}

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

@@ -0,0 +1,73 @@
+/**
+ * validateNamingConvention — Pure assertion that checks strings against naming conventions.
+ *
+ * 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.
+ */
+/**
+ * Regex patterns for each convention.
+ */
+const CONVENTION_PATTERNS = {
+    'kebab-case': /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/,
+    'camelCase': /^[a-z][a-zA-Z0-9]*$/,
+    'PascalCase': /^[A-Z][a-zA-Z0-9]*$/,
+    'SCREAMING_SNAKE_CASE': /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/,
+    'snake_case': /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/,
+};
+/**
+ * Check if a string matches a naming convention.
+ */
+export function matchesConvention(value, convention) {
+    return CONVENTION_PATTERNS[convention].test(value);
+}
+/**
+ * Error thrown when a naming convention assertion fails.
+ */
+export class NamingConventionAssertionError extends Error {
+    violations;
+    constructor(violations) {
+        const details = violations
+            .map((v) => {
+            const location = v.line > 0 ? `${v.file}:${v.line}` : v.file;
+            return `  ${location} — "${v.value}" does not match ${v.convention}`;
+        })
+            .join('\n');
+        super(`Naming convention assertion failed: ${violations.length} violation(s) found\n${details}`);
+        this.name = 'NamingConventionAssertionError';
+        this.violations = violations;
+    }
+}
+/**
+ * Validate that all extracted strings match a naming convention.
+ *
+ * This is a pure, synchronous function: no I/O, no side effects, deterministic.
+ *
+ * @param strings - Pre-resolved strings to validate
+ * @param convention - The naming convention to enforce
+ * @param exceptions - Names to exclude from validation
+ * @throws {NamingConventionAssertionError} if any string violates the convention
+ */
+export function validateNamingConvention(strings, convention, exceptions = []) {
+    const exceptionSet = new Set(exceptions);
+    const violations = [];
+    for (const entry of strings) {
+        if (exceptionSet.has(entry.value))
+            continue;
+        if (!matchesConvention(entry.value, convention)) {
+            violations.push({
+                file: entry.file,
+                line: entry.line,
+                value: entry.value,
+                convention,
+            });
+        }
+    }
+    if (violations.length > 0) {
+        throw new NamingConventionAssertionError(violations);
+    }
+}
+//# sourceMappingURL=naming-convention.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"naming-convention.js","sourceRoot":"","sources":["../../../src/core/assertions/naming-convention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAcH;;GAEG;AACH,MAAM,mBAAmB,GAA+B;IACtD,YAAY,EAAE,+BAA+B;IAC7C,WAAW,EAAE,qBAAqB;IAClC,YAAY,EAAE,qBAAqB;IACnC,sBAAsB,EAAE,+BAA+B;IACvD,YAAY,EAAE,+BAA+B;CAC9C,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAa,EACb,UAAsB;IAEtB,OAAO,mBAAmB,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACrD,CAAC;AAgBD;;GAEG;AACH,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IACvC,UAAU,CAA8B;IAExD,YAAY,UAAuC;QACjD,MAAM,OAAO,GAAG,UAAU;aACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC7D,OAAO,KAAK,QAAQ,OAAO,CAAC,CAAC,KAAK,oBAAoB,CAAC,CAAC,UAAU,EAAE,CAAC;QACvE,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,KAAK,CACH,uCAAuC,UAAU,CAAC,MAAM,wBAAwB,OAAO,EAAE,CAC1F,CAAC;QAEF,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;QAC7C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA0B,EAC1B,UAAsB,EACtB,aAAuB,EAAE;IAEzB,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IACzC,MAAM,UAAU,GAAgC,EAAE,CAAC;IAEnD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,SAAS;QAE5C,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC;YAChD,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,UAAU;aACX,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,8BAA8B,CAAC,UAAU,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,47 @@
+/**
+ * validateNoSideEffects — Pure assertion that checks imports against a forbidden list.
+ *
+ * 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.
+ */
+import type { ImportMatch } from '../resolvers/import-resolver.js';
+/**
+ * A violation: a forbidden module import was found.
+ */
+export interface NoSideEffectsViolation {
+    /** Path of the file containing the forbidden import */
+    file: string;
+    /** The line number (1-based) */
+    line: number;
+    /** The full line text */
+    lineText: string;
+    /** The forbidden module that was imported */
+    module: string;
+}
+/**
+ * Error thrown when a no-side-effects assertion fails.
+ */
+export declare class NoSideEffectsAssertionError extends Error {
+    readonly violations: NoSideEffectsViolation[];
+    constructor(violations: NoSideEffectsViolation[]);
+}
+/**
+ * Check whether a module specifier matches a forbidden module.
+ *
+ * Matches both bare specifier and node: prefixed specifier.
+ * For example, forbidden 'fs' matches 'fs', 'node:fs', 'fs/promises', 'node:fs/promises'.
+ */
+export declare function isForbidden(moduleSpecifier: string, forbiddenModules: string[]): boolean;
+/**
+ * Validate that no imports match the forbidden module list.
+ *
+ * This is a pure, synchronous function: no I/O, no side effects, deterministic.
+ *
+ * @throws {NoSideEffectsAssertionError} if any forbidden import is found
+ */
+export declare function validateNoSideEffects(imports: ImportMatch[], forbiddenModules: string[]): void;
+//# sourceMappingURL=no-side-effects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"no-side-effects.d.ts","sourceRoot":"","sources":["../../../src/core/assertions/no-side-effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,SAAgB,UAAU,EAAE,sBAAsB,EAAE,CAAC;gBAEzC,UAAU,EAAE,sBAAsB,EAAE;CAejD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,eAAe,EAAE,MAAM,EACvB,gBAAgB,EAAE,MAAM,EAAE,GACzB,OAAO,CAWT;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,EAAE,EACtB,gBAAgB,EAAE,MAAM,EAAE,GACzB,IAAI,CAiBN"}

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

@@ -0,0 +1,70 @@
+/**
+ * validateNoSideEffects — Pure assertion that checks imports against a forbidden list.
+ *
+ * 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 a no-side-effects assertion fails.
+ */
+export class NoSideEffectsAssertionError extends Error {
+    violations;
+    constructor(violations) {
+        const details = violations
+            .map((v) => `  ${v.file}:${v.line} — imports forbidden module "${v.module}"\n    > ${v.lineText.trim()}`)
+            .join('\n');
+        super(`No side effects assertion failed: ${violations.length} forbidden import(s) found\n${details}`);
+        this.name = 'NoSideEffectsAssertionError';
+        this.violations = violations;
+    }
+}
+/**
+ * Check whether a module specifier matches a forbidden module.
+ *
+ * Matches both bare specifier and node: prefixed specifier.
+ * For example, forbidden 'fs' matches 'fs', 'node:fs', 'fs/promises', 'node:fs/promises'.
+ */
+export function isForbidden(moduleSpecifier, forbiddenModules) {
+    for (const forbidden of forbiddenModules) {
+        // Exact match
+        if (moduleSpecifier === forbidden)
+            return true;
+        // node:-prefixed match
+        if (moduleSpecifier === `node:${forbidden}`)
+            return true;
+        // Subpath match (e.g., 'fs/promises' when 'fs' is forbidden)
+        if (moduleSpecifier.startsWith(`${forbidden}/`))
+            return true;
+        if (moduleSpecifier.startsWith(`node:${forbidden}/`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Validate that no imports match the forbidden module list.
+ *
+ * This is a pure, synchronous function: no I/O, no side effects, deterministic.
+ *
+ * @throws {NoSideEffectsAssertionError} if any forbidden import is found
+ */
+export function validateNoSideEffects(imports, forbiddenModules) {
+    const violations = [];
+    for (const imp of imports) {
+        if (isForbidden(imp.module, forbiddenModules)) {
+            violations.push({
+                file: imp.file,
+                line: imp.line,
+                lineText: imp.lineText,
+                module: imp.module,
+            });
+        }
+    }
+    if (violations.length > 0) {
+        throw new NoSideEffectsAssertionError(violations);
+    }
+}
+//# sourceMappingURL=no-side-effects.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"no-side-effects.js","sourceRoot":"","sources":["../../../src/core/assertions/no-side-effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkBH;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpC,UAAU,CAA2B;IAErD,YAAY,UAAoC;QAC9C,MAAM,OAAO,GAAG,UAAU;aACvB,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,gCAAgC,CAAC,CAAC,MAAM,YAAY,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAC/F;aACA,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,KAAK,CACH,qCAAqC,UAAU,CAAC,MAAM,+BAA+B,OAAO,EAAE,CAC/F,CAAC;QAEF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,eAAuB,EACvB,gBAA0B;IAE1B,KAAK,MAAM,SAAS,IAAI,gBAAgB,EAAE,CAAC;QACzC,cAAc;QACd,IAAI,eAAe,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAC/C,uBAAuB;QACvB,IAAI,eAAe,KAAK,QAAQ,SAAS,EAAE;YAAE,OAAO,IAAI,CAAC;QACzD,6DAA6D;QAC7D,IAAI,eAAe,CAAC,UAAU,CAAC,GAAG,SAAS,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7D,IAAI,eAAe,CAAC,UAAU,CAAC,QAAQ,SAAS,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IACpE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAsB,EACtB,gBAA0B;IAE1B,MAAM,UAAU,GAA6B,EAAE,CAAC;IAEhD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAAE,CAAC;YAC9C,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,MAAM,EAAE,GAAG,CAAC,MAAM;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,2BAA2B,CAAC,UAAU,CAAC,CAAC;IACpD,CAAC;AACH,CAAC"}

package/dist/core/invariant-test.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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.
+ */
+/**
+ * Metadata about a registered invariant test.
+ * Stored in the registry for coverage tracking.
+ */
+export interface InvariantTestMetadata {
+    /** Invariant ID (e.g., "INV-CACHE-1") */
+    invariantId: string;
+    /** Human-readable description of what the test verifies */
+    description: string;
+}
+/**
+ * A test function that verifies an invariant.
+ * Always async (INV-TEST-6).
+ */
+export type InvariantTestFn = () => Promise<void>;
+/**
+ * A test runner function provided by framework adapters.
+ * Receives the test name, the async test function, and the invariant metadata.
+ * Framework adapters (e.g., Vitest adapter) wrap this to call `it()` or `test()`.
+ */
+export type TestRunner = (testName: string, testFn: InvariantTestFn, metadata: InvariantTestMetadata) => void;
+/**
+ * Options for configuring testInvariant behavior.
+ */
+export interface TestInvariantOptions {
+    /** Custom test runner (default: passthrough that executes the function) */
+    runner?: TestRunner;
+    /** Custom registry for tracking test registrations (default: global registry) */
+    registry?: InvariantTestRegistry;
+}
+/**
+ * Error thrown when testInvariant is called with invalid arguments.
+ */
+export declare class InvariantTestError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function validateInvariantId(id: string): void;
+/**
+ * Validate a test description.
+ */
+export declare function validateDescription(description: string): void;
+/**
+ * Validate a test function.
+ */
+export declare function validateTestFn(testFn: unknown): asserts testFn is InvariantTestFn;
+/**
+ * Create a new invariant test registry.
+ *
+ * The registry is a simple container that tracks which invariant IDs have
+ * been registered with testInvariant(). It supports:
+ * - Registering tests (invariant ID + description)
+ * - Querying registered tests (for coverage calculation)
+ * - Clearing (for test isolation)
+ *
+ * The registry does NOT affect test execution. Tests run identically
+ * regardless of registry state (INV-TEST-7: composable).
+ */
+export interface InvariantTestRegistry {
+    /** Register a test for an invariant */
+    register(metadata: InvariantTestMetadata): void;
+    /** Get all registered test metadata (snapshot, not a live reference) */
+    getAll(): InvariantTestMetadata[];
+    /** Check if an invariant ID has been registered */
+    has(invariantId: string): boolean;
+    /** Get the count of registered tests (may exceed distinct invariants if multiple tests cover the same ID) */
+    size(): number;
+    /** Get the count of distinct invariant IDs covered */
+    coveredCount(): number;
+    /** Clear all registrations (for test isolation) */
+    clear(): void;
+}
+/**
+ * Create a new empty registry instance.
+ */
+export declare function createRegistry(): InvariantTestRegistry;
+/**
+ * Get the default global registry for coverage reporting.
+ */
+export declare function getDefaultRegistry(): InvariantTestRegistry;
+/**
+ * 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 declare function testInvariant(invariantId: string, description: string, testFn: InvariantTestFn, options?: TestInvariantOptions): void;
+//# sourceMappingURL=invariant-test.d.ts.map

package/dist/core/invariant-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant-test.d.ts","sourceRoot":"","sources":["../../src/core/invariant-test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,qBAAqB,KAC5B,IAAI,CAAC;AAEV;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAMD;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAmBpD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAa7D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,eAAe,CAMjF;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAChD,wEAAwE;IACxE,MAAM,IAAI,qBAAqB,EAAE,CAAC;IAClC,mDAAmD;IACnD,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,6GAA6G;IAC7G,IAAI,IAAI,MAAM,CAAC;IACf,sDAAsD;IACtD,YAAY,IAAI,MAAM,CAAC;IACvB,mDAAmD;IACnD,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,qBAAqB,CA4BtD;AAaD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,qBAAqB,CAE1D;AA2BD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,IAAI,CAoBN"}