@organon-methodology/testing 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Organon Methodology Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @organon-methodology/testing
+
+Semantic testing framework for automated tier-4 invariant verification in [Organon](https://github.com/VledicFranco/organon) projects.
+
+## Install
+
+```bash
+npm install --save-dev @organon-methodology/testing
+```
+
+## Assertions
+
+| Assertion | Purpose |
+|-----------|---------|
+| `assertMaxValue` | Enforce numeric limits (line counts, token estimates, array lengths) |
+| `assertFileExists` | Verify required files are present (globs supported) |
+| `assertNamingConvention` | Enforce naming patterns (kebab-case, snake_case, custom regex) |
+| `assertExportsPresent` | Verify modules export expected symbols |
+| `assertNoSideEffects` | Detect forbidden patterns in source files |
+| `assertCustom` | Escape hatch for arbitrary validation logic |
+
+All assertions resolve files from disk using glob patterns and provide structured violation reports.
+
+## Usage with Vitest
+
+```ts
+import { testInvariant } from '@organon-methodology/testing/vitest';
+import { assertMaxValue } from '@organon-methodology/testing';
+
+testInvariant('INV-EXAMPLE-1', 'README files stay under 100 lines', async () => {
+  await assertMaxValue({
+    pattern: '**/README.md',
+    extract: /\n/g,      // count newlines
+    max: 100,
+    cwd: process.cwd(),
+  });
+});
+```
+
+The `testInvariant` adapter wraps your test runner (Vitest) so invariant tests are tracked in a registry and tagged with structured IDs.
+
+## API
+
+### `testInvariant(id, description, fn)`
+
+Registers and runs an invariant test. The `id` must match the pattern `INV-<SCOPE>-<N>`.
+
+### `assertMaxValue(options)`
+
+Resolves files matching `pattern`, extracts numeric values, and fails if any exceed `max`. Options:
+
+- `pattern` — glob pattern for files
+- `extract` — regex or function to extract a count from each file
+- `max` — maximum allowed value
+- `cwd` — working directory for glob resolution
+- `requireMatches` — fail if no files match (default: `true`)
+
+### `assertFileExists(options)`
+
+Verifies that files matching the given patterns exist.
+
+### `assertNamingConvention(options)`
+
+Checks that file names or extracted strings conform to a naming convention (`kebab-case`, `snake_case`, `camelCase`, `PascalCase`, or custom regex).
+
+### `assertExportsPresent(options)`
+
+Parses source files and verifies that expected export names are present.
+
+### `assertNoSideEffects(options)`
+
+Scans files for forbidden patterns (e.g., `console.log`, `process.exit`) and fails if any are found.
+
+### `assertCustom(options)`
+
+Runs an arbitrary validation function. Use when no built-in assertion fits.
+
+## License
+
+MIT

package/dist/adapters/vitest.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Vitest adapter for @organon-methodology/testing.
+ *
+ * Provides a TestRunner that delegates to vitest's `it()` so invariant tests
+ * participate in vitest's lifecycle (reporting, --bail, watch-mode, etc.).
+ *
+ * Usage:
+ * ```typescript
+ * import { testInvariant, assertMaxValue } from '@organon-methodology/testing/vitest';
+ *
+ * testInvariant('INV-FOO-1', 'max cache TTL is 24h', async () => {
+ *   await assertMaxValue({ files: ['src/config.ts'], pattern: /ttl:\s*(\d+)/, maxValue: 86400 });
+ * });
+ * ```
+ *
+ * Invariants:
+ * - INV-TEST-4 (framework-agnostic-core): Core logic stays in invariant-test.ts;
+ *   this file only bridges to vitest's `it()`.
+ */
+import { type TestRunner, type InvariantTestFn, type TestInvariantOptions } from '../core/invariant-test.js';
+/**
+ * A TestRunner that wraps vitest's `it()`.
+ *
+ * vitest's `it()` accepts an async function and tracks the promise internally,
+ * so the async test function integrates naturally.
+ */
+export declare const vitestRunner: TestRunner;
+/**
+ * testInvariant pre-configured with the vitest runner.
+ *
+ * Drop-in replacement for the core testInvariant — same signature,
+ * but tests run through vitest's `it()` instead of the default fire-and-forget runner.
+ */
+export declare function testInvariant(invariantId: string, description: string, testFn: InvariantTestFn, options?: Omit<TestInvariantOptions, 'runner'>): void;
+export { assertMaxValue, MaxValueResolverError, MaxValueAssertionError } from '../core/assert-max-value.js';
+export type { MaxValueOptions } from '../core/assert-max-value.js';
+export type { InvariantTestMetadata, InvariantTestFn, TestRunner, TestInvariantOptions, } from '../core/invariant-test.js';
+export { createRegistry, getDefaultRegistry, InvariantTestError, } from '../core/invariant-test.js';
+export { assertFileExists, FileExistsResolverError, FileExistsAssertionError } from '../core/assert-file-exists.js';
+export type { FileExistsOptions } from '../core/assert-file-exists.js';
+export { assertCustom, CustomAssertionError } from '../core/assert-custom.js';
+export type { CustomAssertionOptions } from '../core/assert-custom.js';
+export { assertNoSideEffects, NoSideEffectsResolverError, NoSideEffectsAssertionError } from '../core/assert-no-side-effects.js';
+export type { NoSideEffectsOptions } from '../core/assert-no-side-effects.js';
+export { assertNamingConvention, NamingConventionResolverError, NamingConventionAssertionError } from '../core/assert-naming-convention.js';
+export type { NamingConventionOptions, Convention } from '../core/assert-naming-convention.js';
+export { assertExportsPresent, ExportsPresentResolverError, ExportsPresentAssertionError } from '../core/assert-exports-present.js';
+export type { ExportsPresentOptions } from '../core/assert-exports-present.js';
+//# sourceMappingURL=vitest.d.ts.map

package/dist/adapters/vitest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.d.ts","sourceRoot":"","sources":["../../src/adapters/vitest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,eAAe,EAEpB,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAMnC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,UAM1B,CAAC;AAMF;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAC7C,IAAI,CAKN;AAMD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC5G,YAAY,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACpH,YAAY,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AACjI,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AAC5I,YAAY,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAE/F,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACpI,YAAY,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/adapters/vitest.js

@@ -0,0 +1,60 @@
+/**
+ * Vitest adapter for @organon-methodology/testing.
+ *
+ * Provides a TestRunner that delegates to vitest's `it()` so invariant tests
+ * participate in vitest's lifecycle (reporting, --bail, watch-mode, etc.).
+ *
+ * Usage:
+ * ```typescript
+ * import { testInvariant, assertMaxValue } from '@organon-methodology/testing/vitest';
+ *
+ * testInvariant('INV-FOO-1', 'max cache TTL is 24h', async () => {
+ *   await assertMaxValue({ files: ['src/config.ts'], pattern: /ttl:\s*(\d+)/, maxValue: 86400 });
+ * });
+ * ```
+ *
+ * Invariants:
+ * - INV-TEST-4 (framework-agnostic-core): Core logic stays in invariant-test.ts;
+ *   this file only bridges to vitest's `it()`.
+ */
+import { it } from 'vitest';
+import { testInvariant as coreTestInvariant, } from '../core/invariant-test.js';
+// ---------------------------------------------------------------------------
+// Vitest runner
+// ---------------------------------------------------------------------------
+/**
+ * A TestRunner that wraps vitest's `it()`.
+ *
+ * vitest's `it()` accepts an async function and tracks the promise internally,
+ * so the async test function integrates naturally.
+ */
+export const vitestRunner = (testName, testFn, _metadata) => {
+    it(testName, testFn);
+};
+// ---------------------------------------------------------------------------
+// Pre-configured testInvariant (convenience)
+// ---------------------------------------------------------------------------
+/**
+ * testInvariant pre-configured with the vitest runner.
+ *
+ * Drop-in replacement for the core testInvariant — same signature,
+ * but tests run through vitest's `it()` instead of the default fire-and-forget runner.
+ */
+export function testInvariant(invariantId, description, testFn, options) {
+    coreTestInvariant(invariantId, description, testFn, {
+        ...options,
+        runner: vitestRunner,
+    });
+}
+// ---------------------------------------------------------------------------
+// Re-exports for single-import convenience
+// ---------------------------------------------------------------------------
+export { assertMaxValue, MaxValueResolverError, MaxValueAssertionError } from '../core/assert-max-value.js';
+export { createRegistry, getDefaultRegistry, InvariantTestError, } from '../core/invariant-test.js';
+// Phase 2/3 assertions
+export { assertFileExists, FileExistsResolverError, FileExistsAssertionError } from '../core/assert-file-exists.js';
+export { assertCustom, CustomAssertionError } from '../core/assert-custom.js';
+export { assertNoSideEffects, NoSideEffectsResolverError, NoSideEffectsAssertionError } from '../core/assert-no-side-effects.js';
+export { assertNamingConvention, NamingConventionResolverError, NamingConventionAssertionError } from '../core/assert-naming-convention.js';
+export { assertExportsPresent, ExportsPresentResolverError, ExportsPresentAssertionError } from '../core/assert-exports-present.js';
+//# sourceMappingURL=vitest.js.map

package/dist/adapters/vitest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.js","sourceRoot":"","sources":["../../src/adapters/vitest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC5B,OAAO,EACL,aAAa,IAAI,iBAAiB,GAKnC,MAAM,2BAA2B,CAAC;AAEnC,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAe,CACtC,QAAgB,EAChB,MAAuB,EACvB,SAAgC,EAC1B,EAAE;IACR,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACvB,CAAC,CAAC;AAEF,8EAA8E;AAC9E,6CAA6C;AAC7C,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,WAAmB,EACnB,WAAmB,EACnB,MAAuB,EACvB,OAA8C;IAE9C,iBAAiB,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE;QAClD,GAAG,OAAO;QACV,MAAM,EAAE,YAAY;KACrB,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,2CAA2C;AAC3C,8EAA8E;AAE9E,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAQ5G,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AAEnC,uBAAuB;AACvB,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGpH,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAG9E,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AAGjI,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AAG5I,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/core/assert-custom.d.ts

@@ -0,0 +1,43 @@
+/**
+ * assertCustom — Thin wrapper for user-defined validation functions.
+ *
+ * No pure validator layer needed — the validator IS the user's function.
+ * This wrapper provides consistent error handling and labeling.
+ *
+ * Invariants:
+ * - INV-TEST-2 (fail-fast): Re-throws user errors wrapped in CustomAssertionError
+ * - INV-TEST-6 (always-async): Returns Promise<void>
+ * - INV-TEST-7 (composable): No module-level mutable state
+ */
+/**
+ * Options for assertCustom.
+ */
+export interface CustomAssertionOptions {
+    /** Human-readable label for the assertion (used in error messages) */
+    label: string;
+    /** The validation function to execute. Throw to signal failure. */
+    validate: () => Promise<void>;
+}
+/**
+ * Error thrown when a custom assertion fails.
+ * Wraps the original error with a label for context.
+ */
+export declare class CustomAssertionError extends Error {
+    /** The label provided for this assertion */
+    readonly label: string;
+    /** The original error thrown by the validation function */
+    readonly cause: Error;
+    constructor(label: string, cause: Error);
+}
+/**
+ * Run a user-defined validation function with consistent error handling.
+ *
+ * If the validation function throws, the error is wrapped in a
+ * CustomAssertionError with the provided label for context.
+ * If it completes without throwing, the assertion passes.
+ *
+ * @param options - Configuration including label and validate function
+ * @throws {CustomAssertionError} if the validate function throws
+ */
+export declare function assertCustom(options: CustomAssertionOptions): Promise<void>;
+//# sourceMappingURL=assert-custom.d.ts.map

package/dist/core/assert-custom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-custom.d.ts","sourceRoot":"","sources":["../../src/core/assert-custom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,4CAA4C;IAC5C,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,SAAgB,KAAK,EAAE,KAAK,CAAC;gBAEjB,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAMxC;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/core/assert-custom.js

@@ -0,0 +1,48 @@
+/**
+ * assertCustom — Thin wrapper for user-defined validation functions.
+ *
+ * No pure validator layer needed — the validator IS the user's function.
+ * This wrapper provides consistent error handling and labeling.
+ *
+ * Invariants:
+ * - INV-TEST-2 (fail-fast): Re-throws user errors wrapped in CustomAssertionError
+ * - INV-TEST-6 (always-async): Returns Promise<void>
+ * - INV-TEST-7 (composable): No module-level mutable state
+ */
+/**
+ * Error thrown when a custom assertion fails.
+ * Wraps the original error with a label for context.
+ */
+export class CustomAssertionError extends Error {
+    /** The label provided for this assertion */
+    label;
+    /** The original error thrown by the validation function */
+    cause;
+    constructor(label, cause) {
+        super(`Custom assertion "${label}" failed: ${cause.message}`);
+        this.name = 'CustomAssertionError';
+        this.label = label;
+        this.cause = cause;
+    }
+}
+/**
+ * Run a user-defined validation function with consistent error handling.
+ *
+ * If the validation function throws, the error is wrapped in a
+ * CustomAssertionError with the provided label for context.
+ * If it completes without throwing, the assertion passes.
+ *
+ * @param options - Configuration including label and validate function
+ * @throws {CustomAssertionError} if the validate function throws
+ */
+export async function assertCustom(options) {
+    const { label, validate } = options;
+    try {
+        await validate();
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        throw new CustomAssertionError(label, error);
+    }
+}
+//# sourceMappingURL=assert-custom.js.map

package/dist/core/assert-custom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-custom.js","sourceRoot":"","sources":["../../src/core/assert-custom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,4CAA4C;IAC5B,KAAK,CAAS;IAC9B,2DAA2D;IAC3C,KAAK,CAAQ;IAE7B,YAAY,KAAa,EAAE,KAAY;QACrC,KAAK,CAAC,qBAAqB,KAAK,aAAa,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAA+B;IAE/B,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAEpC,IAAI,CAAC;QACH,MAAM,QAAQ,EAAE,CAAC;IACnB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,MAAM,IAAI,oBAAoB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,52 @@
+/**
+ * assertExportsPresent — High-level assertion that verifies expected exports exist.
+ *
+ * Simplified backwards-compat check: scans a file for export statements
+ * and verifies that all expected export names are present.
+ *
+ * Architecture:
+ * - Reads file content via FileSystem (I/O layer)
+ * - Extracts export names via regex
+ * - Delegates to assertions/exports-present.ts for pure validation
+ *
+ * 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 assertExportsPresent.
+ */
+export interface ExportsPresentOptions {
+    /** Path to the file to check */
+    file: string;
+    /** Expected export names that must be present */
+    expectedExports: string[];
+    /** Optional working directory */
+    cwd?: string;
+    /** Optional FileSystem implementation */
+    fs?: FileSystem;
+}
+/**
+ * Error thrown when assertExportsPresent encounters resolver-level errors.
+ */
+export declare class ExportsPresentResolverError extends Error {
+    constructor(message: string);
+}
+/**
+ * Extract all exported names from file content.
+ *
+ * Pure function — no I/O.
+ */
+export declare function extractExportNames(content: string): string[];
+/**
+ * Assert that a file contains all expected exports.
+ *
+ * @param options - Configuration including file path and expected exports
+ * @throws {ExportsPresentResolverError} if file can't be read
+ * @throws {ExportsPresentAssertionError} if any expected export is missing
+ */
+export declare function assertExportsPresent(options: ExportsPresentOptions): Promise<void>;
+export { ExportsPresentAssertionError } from './assertions/exports-present.js';
+//# sourceMappingURL=assert-exports-present.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assert-exports-present.d.ts","sourceRoot":"","sources":["../../src/core/assert-exports-present.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAOvD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AA2BD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAqC5D;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAGD,OAAO,EAAE,4BAA4B,EAAE,MAAM,iCAAiC,CAAC"}

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

@@ -0,0 +1,125 @@
+/**
+ * assertExportsPresent — High-level assertion that verifies expected exports exist.
+ *
+ * Simplified backwards-compat check: scans a file for export statements
+ * and verifies that all expected export names are present.
+ *
+ * Architecture:
+ * - Reads file content via FileSystem (I/O layer)
+ * - Extracts export names via regex
+ * - Delegates to assertions/exports-present.ts for pure validation
+ *
+ * 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 { validateExportsPresent, } from './assertions/exports-present.js';
+/**
+ * Error thrown when assertExportsPresent encounters resolver-level errors.
+ */
+export class ExportsPresentResolverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ExportsPresentResolverError';
+    }
+}
+/**
+ * Patterns to extract export names from TypeScript/JavaScript files.
+ *
+ * Captures from:
+ * - export function name
+ * - export async function name
+ * - export class name
+ * - export interface name
+ * - export type name
+ * - export const/let/var name
+ * - export enum name
+ * - export { name, name2 }
+ * - export { name } from '...'
+ */
+const EXPORT_PATTERNS = [
+    /export\s+(?:async\s+)?function\s+(\w+)/,
+    /export\s+class\s+(\w+)/,
+    /export\s+interface\s+(\w+)/,
+    /export\s+type\s+(\w+)/,
+    /export\s+(?:const|let|var)\s+(\w+)/,
+    /export\s+enum\s+(\w+)/,
+];
+const EXPORT_LIST_PATTERN = /export\s*\{([^}]+)\}/;
+/**
+ * Extract all exported names from file content.
+ *
+ * Pure function — no I/O.
+ */
+export function extractExportNames(content) {
+    const names = [];
+    const lines = content.split('\n');
+    for (const line of lines) {
+        // Check named export patterns
+        for (const pattern of EXPORT_PATTERNS) {
+            const match = pattern.exec(line);
+            if (match && match[1]) {
+                names.push(match[1]);
+                break;
+            }
+        }
+        // Check export list pattern: export { a, b, c }
+        const listMatch = EXPORT_LIST_PATTERN.exec(line);
+        if (listMatch && listMatch[1]) {
+            const items = listMatch[1].split(',');
+            for (const item of items) {
+                // Handle "name as alias" — use the original name
+                const trimmed = item.trim();
+                if (!trimmed)
+                    continue;
+                const asMatch = /^(\w+)\s+as\s+/.exec(trimmed);
+                const typedMatch = /^type\s+(\w+)/.exec(trimmed);
+                if (typedMatch) {
+                    names.push(typedMatch[1]);
+                }
+                else if (asMatch) {
+                    names.push(asMatch[1]);
+                }
+                else {
+                    const nameOnly = trimmed.split(/\s/)[0];
+                    if (nameOnly)
+                        names.push(nameOnly);
+                }
+            }
+        }
+    }
+    return names;
+}
+/**
+ * Assert that a file contains all expected exports.
+ *
+ * @param options - Configuration including file path and expected exports
+ * @throws {ExportsPresentResolverError} if file can't be read
+ * @throws {ExportsPresentAssertionError} if any expected export is missing
+ */
+export async function assertExportsPresent(options) {
+    const { file, expectedExports, cwd, fs } = options;
+    const resolvedFs = fs ?? createNodeFileSystem();
+    // Fail-fast on empty inputs (INV-TEST-2)
+    if (expectedExports.length === 0) {
+        throw new ExportsPresentResolverError('No expected exports provided. The expectedExports array must not be empty.');
+    }
+    // Read the file
+    const readPath = cwd ? `${cwd}/${file}` : file;
+    let content;
+    try {
+        content = await resolvedFs.readFile(readPath);
+    }
+    catch (err) {
+        throw new ExportsPresentResolverError(`Failed to read file "${file}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Extract export names
+    const foundExports = extractExportNames(content);
+    // Delegate to pure validator
+    validateExportsPresent(file, expectedExports, foundExports);
+}
+// Re-export for consumers
+export { ExportsPresentAssertionError } from './assertions/exports-present.js';
+//# sourceMappingURL=assert-exports-present.js.map

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * assertFileExists — High-level assertion that checks file existence.
+ *
+ * Architecture:
+ * - Uses FileSystem.exists() to check each file (I/O layer)
+ * - Delegates to assertions/file-exists.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 empty files array
+ * - 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 assertFileExists.
+ */
+export interface FileExistsOptions {
+    /** File paths to check (not globs — existence check only) */
+    files: string[];
+    /** Optional working directory to resolve relative paths */
+    cwd?: string;
+    /** Optional FileSystem implementation (defaults to Node.js fs) */
+    fs?: FileSystem;
+}
+/**
+ * Error thrown when assertFileExists receives invalid input.
+ */
+export declare class FileExistsResolverError extends Error {
+    constructor(message: string);
+}
+/**
+ * Assert that all specified files exist on the filesystem.
+ *
+ * @param options - Configuration including file paths and optional cwd/fs
+ * @throws {FileExistsResolverError} if files array is empty
+ * @throws {FileExistsAssertionError} if any file does not exist
+ */
+export declare function assertFileExists(options: FileExistsOptions): Promise<void>;
+export { FileExistsAssertionError } from './assertions/file-exists.js';
+//# sourceMappingURL=assert-file-exists.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assert-file-exists.d.ts","sourceRoot":"","sources":["../../src/core/assert-file-exists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAQvD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAGD,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC"}

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

@@ -0,0 +1,52 @@
+/**
+ * assertFileExists — High-level assertion that checks file existence.
+ *
+ * Architecture:
+ * - Uses FileSystem.exists() to check each file (I/O layer)
+ * - Delegates to assertions/file-exists.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 empty files array
+ * - INV-TEST-6 (always-async): Returns Promise<void>
+ * - INV-TEST-7 (composable): No module-level mutable state
+ */
+import { join } from 'node:path';
+import { createNodeFileSystem } from './resolvers/node-fs.js';
+import { validateFileExists, } from './assertions/file-exists.js';
+/**
+ * Error thrown when assertFileExists receives invalid input.
+ */
+export class FileExistsResolverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FileExistsResolverError';
+    }
+}
+/**
+ * Assert that all specified files exist on the filesystem.
+ *
+ * @param options - Configuration including file paths and optional cwd/fs
+ * @throws {FileExistsResolverError} if files array is empty
+ * @throws {FileExistsAssertionError} if any file does not exist
+ */
+export async function assertFileExists(options) {
+    const { files, cwd, fs } = options;
+    const resolvedFs = fs ?? createNodeFileSystem();
+    // Fail-fast on empty files array (INV-TEST-2)
+    if (files.length === 0) {
+        throw new FileExistsResolverError('No file paths provided. The files array must not be empty.');
+    }
+    // Resolve existence for each file
+    const entries = [];
+    for (const file of files) {
+        const fullPath = cwd ? join(cwd, file) : file;
+        const exists = await resolvedFs.exists(fullPath);
+        entries.push({ file, exists });
+    }
+    // Delegate to pure validator
+    validateFileExists(entries);
+}
+// Re-export assertion error for consumers
+export { FileExistsAssertionError } from './assertions/file-exists.js';
+//# sourceMappingURL=assert-file-exists.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assert-file-exists.js","sourceRoot":"","sources":["../../src/core/assert-file-exists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EACL,kBAAkB,GAGnB,MAAM,6BAA6B,CAAC;AAcrC;;GAEG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAA0B;IAE1B,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;IACnC,MAAM,UAAU,GAAG,EAAE,IAAI,oBAAoB,EAAE,CAAC;IAEhD,8CAA8C;IAC9C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,uBAAuB,CAC/B,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IAED,kCAAkC;IAClC,MAAM,OAAO,GAAsB,EAAE,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,6BAA6B;IAC7B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED,0CAA0C;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC"}