@fuzdev/fuz_app 0.1.0

package/dist/testing/entities.d.ts

@@ -0,0 +1,21 @@
+import './assert_dev_env.js';
+/**
+ * Shared test entity factories for `Account`, `Actor`, `Permit`, and `RequestContext`.
+ *
+ * Accepts `Partial<T>` overrides — callers set only what matters to their test.
+ * Uses `create_test_*` names to avoid collisions with real `create_account_with_actor`
+ * from `account_queries.ts`.
+ *
+ * @module
+ */
+import type { Account, Actor, Permit } from '../auth/account_schema.js';
+import type { RequestContext } from '../auth/request_context.js';
+/** Create a test `Account` with sensible defaults. */
+export declare const create_test_account: (overrides?: Partial<Account>) => Account;
+/** Create a test `Actor` with sensible defaults. */
+export declare const create_test_actor: (overrides?: Partial<Actor>) => Actor;
+/** Create a test `Permit` with sensible defaults. */
+export declare const create_test_permit: (overrides?: Partial<Permit>) => Permit;
+/** Create a test `RequestContext` with permits from partial overrides. */
+export declare const create_test_context: (permits?: Array<Partial<Permit>>) => RequestContext;
+//# sourceMappingURL=entities.d.ts.map

package/dist/testing/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/entities.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAC,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE/D,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,GAAI,YAAY,OAAO,CAAC,OAAO,CAAC,KAAG,OAWjE,CAAC;AAEH,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,GAAI,YAAY,OAAO,CAAC,KAAK,CAAC,KAAG,KAQ7D,CAAC;AAEH,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,GAAI,YAAY,OAAO,CAAC,MAAM,CAAC,KAAG,MAU/D,CAAC;AAEH,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,GAAI,UAAS,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAQ,KAAG,cAI3E,CAAC"}

package/dist/testing/entities.js

@@ -0,0 +1,42 @@
+import './assert_dev_env.js';
+/** Create a test `Account` with sensible defaults. */
+export const create_test_account = (overrides) => ({
+    id: 'acct-test',
+    username: 'test_user',
+    email: null,
+    email_verified: false,
+    password_hash: 'hash',
+    created_at: '2024-01-01T00:00:00Z',
+    created_by: null,
+    updated_at: '2024-01-01T00:00:00Z',
+    updated_by: null,
+    ...overrides,
+});
+/** Create a test `Actor` with sensible defaults. */
+export const create_test_actor = (overrides) => ({
+    id: 'actor-test',
+    account_id: 'acct-test',
+    name: 'test_user',
+    created_at: '2024-01-01T00:00:00Z',
+    updated_at: null,
+    updated_by: null,
+    ...overrides,
+});
+/** Create a test `Permit` with sensible defaults. */
+export const create_test_permit = (overrides) => ({
+    id: 'permit-test',
+    actor_id: 'actor-test',
+    role: 'admin',
+    created_at: '2024-01-01T00:00:00Z',
+    expires_at: null,
+    revoked_at: null,
+    revoked_by: null,
+    granted_by: null,
+    ...overrides,
+});
+/** Create a test `RequestContext` with permits from partial overrides. */
+export const create_test_context = (permits = [{}]) => ({
+    account: create_test_account(),
+    actor: create_test_actor(),
+    permits: permits.map((p) => create_test_permit(p)),
+});

package/dist/testing/error_coverage.d.ts

@@ -0,0 +1,78 @@
+import './assert_dev_env.js';
+import type { RouteSpec } from '../http/route_spec.js';
+/**
+ * Tracks which route × status combinations have been exercised in tests.
+ *
+ * Use `record()` to log an observed status, or `assert_and_record()` to
+ * combine response validation with tracking. After all tests, call
+ * `uncovered()` to find declared error statuses never exercised.
+ */
+export declare class ErrorCoverageCollector {
+    /** Observed route × status keys: `"METHOD /spec-path:STATUS"`. */
+    readonly observed: Set<string>;
+    /**
+     * Record an observed error status for a route.
+     *
+     * Resolves the concrete request path back to the spec template path
+     * (e.g., `/api/accounts/abc` → `/api/accounts/:id`).
+     *
+     * @param route_specs - route specs for path resolution
+     * @param method - HTTP method
+     * @param path - request path (may be concrete)
+     * @param status - observed HTTP status code
+     */
+    record(route_specs: Array<RouteSpec>, method: string, path: string, status: number): void;
+    /**
+     * Validate a response against its route spec and record the status.
+     *
+     * Wraps `assert_response_matches_spec` and records the status code.
+     *
+     * @param route_specs - route specs for schema lookup and path resolution
+     * @param method - HTTP method
+     * @param path - request path
+     * @param response - the Response to validate and record
+     */
+    assert_and_record(route_specs: Array<RouteSpec>, method: string, path: string, response: Response): Promise<void>;
+    /**
+     * Find declared error statuses that were never observed.
+     *
+     * Computes the declared set from `merge_error_schemas` for each route spec,
+     * then subtracts observed keys.
+     *
+     * @param route_specs - route specs to check coverage against
+     * @returns uncovered entries with method, path, and status
+     */
+    uncovered(route_specs: Array<RouteSpec>): Array<{
+        method: string;
+        path: string;
+        status: number;
+    }>;
+}
+/**
+ * Default minimum error coverage threshold for the standard integration
+ * and admin test suites. Conservative — not all error paths are exercisable
+ * in the composable suites. Consumers should increase as their test suites mature.
+ */
+export declare const DEFAULT_INTEGRATION_ERROR_COVERAGE = 0.2;
+/** Options for `assert_error_coverage`. */
+export interface ErrorCoverageOptions {
+    /** Minimum coverage ratio (0–1). Default `0` (informational only). */
+    min_coverage?: number;
+    /** Routes to skip, in `'METHOD /path'` format. */
+    ignore_routes?: Array<string>;
+    /** HTTP status codes to skip. */
+    ignore_statuses?: Array<number>;
+}
+/**
+ * Assert error coverage meets a minimum threshold.
+ *
+ * Computes the ratio of exercised error statuses to total declared error
+ * statuses. When `min_coverage` is 0 (default), logs coverage info without
+ * failing. When > 0, fails if coverage is below the threshold.
+ *
+ * @param collector - the coverage collector with recorded observations
+ * @param route_specs - route specs to check coverage against
+ * @param options - threshold and exclusion configuration
+ */
+export declare const assert_error_coverage: (collector: ErrorCoverageCollector, route_specs: Array<RouteSpec>, options?: ErrorCoverageOptions) => void;
+//# sourceMappingURL=error_coverage.d.ts.map

package/dist/testing/error_coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error_coverage.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/error_coverage.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAe7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAIrD;;;;;;GAMG;AACH,qBAAa,sBAAsB;IAClC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAa;IAE3C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAMzF;;;;;;;;;OASG;IACG,iBAAiB,CACtB,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,EAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,IAAI,CAAC;IAKhB;;;;;;;;OAQG;IACH,SAAS,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC;CAe/F;AAED;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACpC,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,iCAAiC;IACjC,eAAe,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GACjC,WAAW,sBAAsB,EACjC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,UAAU,oBAAoB,KAC5B,IA6CF,CAAC"}

package/dist/testing/error_coverage.js

@@ -0,0 +1,135 @@
+import './assert_dev_env.js';
+/**
+ * Error reachability coverage tracking.
+ *
+ * Tracks which declared error statuses are actually exercised in tests.
+ * `ErrorCoverageCollector` records status codes observed during test runs,
+ * then `assert_error_coverage` compares against declared error schemas
+ * to find uncovered error paths.
+ *
+ * @module
+ */
+import { assert } from 'vitest';
+import { merge_error_schemas } from '../http/schema_helpers.js';
+import { find_route_spec, assert_response_matches_spec } from './integration_helpers.js';
+/**
+ * Tracks which route × status combinations have been exercised in tests.
+ *
+ * Use `record()` to log an observed status, or `assert_and_record()` to
+ * combine response validation with tracking. After all tests, call
+ * `uncovered()` to find declared error statuses never exercised.
+ */
+export class ErrorCoverageCollector {
+    /** Observed route × status keys: `"METHOD /spec-path:STATUS"`. */
+    observed = new Set();
+    /**
+     * Record an observed error status for a route.
+     *
+     * Resolves the concrete request path back to the spec template path
+     * (e.g., `/api/accounts/abc` → `/api/accounts/:id`).
+     *
+     * @param route_specs - route specs for path resolution
+     * @param method - HTTP method
+     * @param path - request path (may be concrete)
+     * @param status - observed HTTP status code
+     */
+    record(route_specs, method, path, status) {
+        const spec = find_route_spec(route_specs, method, path);
+        const spec_path = spec ? spec.path : path;
+        this.observed.add(`${method} ${spec_path}:${status}`);
+    }
+    /**
+     * Validate a response against its route spec and record the status.
+     *
+     * Wraps `assert_response_matches_spec` and records the status code.
+     *
+     * @param route_specs - route specs for schema lookup and path resolution
+     * @param method - HTTP method
+     * @param path - request path
+     * @param response - the Response to validate and record
+     */
+    async assert_and_record(route_specs, method, path, response) {
+        await assert_response_matches_spec(route_specs, method, path, response);
+        this.record(route_specs, method, path, response.status);
+    }
+    /**
+     * Find declared error statuses that were never observed.
+     *
+     * Computes the declared set from `merge_error_schemas` for each route spec,
+     * then subtracts observed keys.
+     *
+     * @param route_specs - route specs to check coverage against
+     * @returns uncovered entries with method, path, and status
+     */
+    uncovered(route_specs) {
+        const missing = [];
+        for (const spec of route_specs) {
+            const merged = merge_error_schemas(spec);
+            if (!merged)
+                continue;
+            for (const status_str of Object.keys(merged)) {
+                const status = Number(status_str);
+                const key = `${spec.method} ${spec.path}:${status}`;
+                if (!this.observed.has(key)) {
+                    missing.push({ method: spec.method, path: spec.path, status });
+                }
+            }
+        }
+        return missing;
+    }
+}
+/**
+ * Default minimum error coverage threshold for the standard integration
+ * and admin test suites. Conservative — not all error paths are exercisable
+ * in the composable suites. Consumers should increase as their test suites mature.
+ */
+export const DEFAULT_INTEGRATION_ERROR_COVERAGE = 0.2;
+/**
+ * Assert error coverage meets a minimum threshold.
+ *
+ * Computes the ratio of exercised error statuses to total declared error
+ * statuses. When `min_coverage` is 0 (default), logs coverage info without
+ * failing. When > 0, fails if coverage is below the threshold.
+ *
+ * @param collector - the coverage collector with recorded observations
+ * @param route_specs - route specs to check coverage against
+ * @param options - threshold and exclusion configuration
+ */
+export const assert_error_coverage = (collector, route_specs, options) => {
+    const min_coverage = options?.min_coverage ?? 0;
+    const ignore_routes = new Set(options?.ignore_routes);
+    const ignore_statuses = new Set(options?.ignore_statuses);
+    let total = 0;
+    let covered = 0;
+    const uncovered_entries = [];
+    for (const spec of route_specs) {
+        const route_key = `${spec.method} ${spec.path}`;
+        if (ignore_routes.has(route_key))
+            continue;
+        const merged = merge_error_schemas(spec);
+        if (!merged)
+            continue;
+        for (const status_str of Object.keys(merged)) {
+            const status = Number(status_str);
+            if (ignore_statuses.has(status))
+                continue;
+            total++;
+            const key = `${spec.method} ${spec.path}:${status}`;
+            if (collector.observed.has(key)) {
+                covered++;
+            }
+            else {
+                uncovered_entries.push(`${route_key} → ${status}`);
+            }
+        }
+    }
+    const ratio = total > 0 ? covered / total : 1;
+    console.log(`[error coverage] ${covered}/${total} (${(ratio * 100).toFixed(1)}%)` +
+        (uncovered_entries.length > 0
+            ? `\n  uncovered:\n    ${uncovered_entries.join('\n    ')}`
+            : ''));
+    if (min_coverage > 0) {
+        assert.ok(ratio >= min_coverage, `Error coverage ${(ratio * 100).toFixed(1)}% below threshold ${(min_coverage * 100).toFixed(1)}%` +
+            `\n  uncovered:\n    ${uncovered_entries.join('\n    ')}`);
+    }
+};

package/dist/testing/integration.d.ts

@@ -0,0 +1,37 @@
+import './assert_dev_env.js';
+import type { SessionOptions } from '../auth/session_cookie.js';
+import type { AppServerContext, AppServerOptions } from '../server/app_server.js';
+import type { RouteSpec } from '../http/route_spec.js';
+import { type DbFactory } from './db.js';
+/**
+ * Configuration for `describe_standard_integration_tests`.
+ */
+export interface StandardIntegrationTestOptions {
+    /** Session config for cookie-based auth. */
+    session_options: SessionOptions<string>;
+    /** Route spec factory — same one used in production. */
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** Optional overrides for `AppServerOptions`. */
+    app_options?: Partial<Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>>;
+    /**
+     * Database factories to run tests against. Default: pglite only.
+     * Pass consumer factories (e.g. `[pglite_factory, pg_factory]`) to also test against PostgreSQL.
+     */
+    db_factories?: Array<DbFactory>;
+}
+/**
+ * Standard integration test suite for fuz_app auth routes.
+ *
+ * Exercises login/logout, cookie attributes, session security, session
+ * revocation, password change (incl. API token revocation), origin
+ * verification, bearer auth (incl. browser context rejection on mutations),
+ * token revocation, cross-account isolation, expired credential rejection,
+ * signup invite edge cases, and response body validation.
+ *
+ * Each test group asserts that required routes exist, failing with a descriptive
+ * message if the consumer's route specs are misconfigured.
+ *
+ * @param options - session config and route factory
+ */
+export declare const describe_standard_integration_tests: (options: StandardIntegrationTestOptions) => void;
+//# sourceMappingURL=integration.d.ts.map

package/dist/testing/integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAGrD,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AAgBjB;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC9C,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAeD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mCAAmC,GAC/C,SAAS,8BAA8B,KACrC,IAk+CF,CAAC"}