@sleepy-hollow/framework 0.3.0

package/dist/security.js

@@ -0,0 +1,21 @@
+import {
+  SecurityConfigurationError,
+  composeProjectSecurity,
+  createMemoryRateLimiter,
+  createSecurityRouter,
+  defineSecurity,
+  redactSecurityData
+} from "./chunk-DGTHFZPZ.js";
+import "./chunk-CAPFDC25.js";
+import "./chunk-53TZY5YP.js";
+import "./chunk-LNJDFJGT.js";
+import "./chunk-5WRI5ZAA.js";
+export {
+  SecurityConfigurationError,
+  composeProjectSecurity,
+  createMemoryRateLimiter,
+  createSecurityRouter,
+  defineSecurity,
+  redactSecurityData
+};
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import * as node_http from 'node:http';
+
+type FetchHandler = (request: Request) => Response | Promise<Response>;
+/** Starts the Node HTTP adapter for a framework fetch handler. */
+declare function serve(handler: FetchHandler, options?: {
+    readonly port?: number;
+    readonly hostname?: string;
+}): node_http.Server<typeof node_http.IncomingMessage, typeof node_http.ServerResponse>;
+
+export { type FetchHandler, serve };

package/dist/server.js

@@ -0,0 +1,8 @@
+import {
+  serve
+} from "./chunk-LNJDFJGT.js";
+import "./chunk-5WRI5ZAA.js";
+export {
+  serve
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/testing.d.ts

@@ -0,0 +1,157 @@
+import { T as TestingDiagnostic, P as ProblemExpectation, a as ProblemDetails, R as RequirementEvidence, B as BaselineCheck, b as RedTestResult, c as RedStateResult, C as CriterionTestRegistry, d as TestApplicationOptions, e as TestApplicationContext, f as TestManifest, g as TestExecutionResult, h as TraceabilityReport, i as CriterionTestSpec, j as CriterionTestDescriptor, k as RequirementDependency, l as TestSelection } from './types-Bet36nZS.js';
+export { A as ApprovedCriterion, m as CriterionTrace, J as JsonRequestOptions, n as JsonTestResponse, o as TestApplication, p as TestApplicationFactory, q as TestApplicationFactoryContext, r as TestApplicationFixtures, s as TestApplicationSecurityOptions, t as TestManifestEntry, u as TestResultStatus } from './types-Bet36nZS.js';
+import './types-BC7LJJ6G.js';
+import './types-BUXw3UwN.js';
+import 'drizzle-orm/better-sqlite3';
+import 'better-sqlite3';
+import 'drizzle-orm/node-postgres';
+import 'pg';
+
+/**
+ * Thrown when a testing artifact is refused: a test claiming a criterion that
+ * does not exist, a manifest that does not match the suite, or a red-state run
+ * that is not credible evidence.
+ */
+declare class TestingError extends Error {
+    /** Every fault found, sorted by subject and then code. */
+    readonly diagnostics: readonly TestingDiagnostic[];
+    /**
+     * Builds an error carrying every fault found.
+     *
+     * @param diagnostics The faults; they are sorted for stable output.
+     */
+    constructor(diagnostics: readonly TestingDiagnostic[]);
+}
+
+/**
+ * Builds a registry that registers tests against approved criteria.
+ *
+ * A test claiming a criterion the requirement does not have, or one whose
+ * approval no longer binds, is refused at registration rather than counted.
+ *
+ * @param options The requirements to check against, and the registrar to use.
+ * @returns A registry.
+ * @throws {TestingError} When the supplied requirements are inconsistent.
+ */
+declare function createCriterionRegistry(options: {
+    readonly requirements: readonly RequirementEvidence[];
+    readonly register?: (definition: {
+        readonly name: string;
+        readonly fn: (context?: unknown) => void | Promise<void>;
+        readonly skip?: boolean;
+    }) => void;
+}): CriterionTestRegistry;
+/**
+ * Registers one criterion test without holding a registry.
+ *
+ * @param spec The test, and the criteria it verifies.
+ * @param options The requirements to check against, and the registrar to use.
+ * @returns The descriptor recorded for it.
+ * @throws {TestingError} When the test claims a criterion it may not.
+ */
+declare function criterionTest(spec: CriterionTestSpec, options: {
+    readonly requirements: readonly RequirementEvidence[];
+    readonly register?: (definition: {
+        readonly name: string;
+        readonly fn: (context?: unknown) => void | Promise<void>;
+        readonly skip?: boolean;
+    }) => void;
+}): CriterionTestDescriptor;
+/**
+ * Digests the registered suite into a manifest.
+ *
+ * Comparing manifests across revisions is what makes a deleted or weakened
+ * test visible instead of silent.
+ *
+ * @param options The registered descriptors, and the sources they came from.
+ * @returns The manifest.
+ * @throws {TestingError} When a descriptor's source is missing.
+ */
+declare function createTestManifest(options: {
+    readonly descriptors: ReturnType<CriterionTestRegistry["descriptors"]>;
+    readonly sources: Readonly<Record<string, string>>;
+}): TestManifest;
+/**
+ * Maps criteria to the tests that verify them, and reports what changed.
+ *
+ * Supply the previous manifest to detect removed, changed, and weakened
+ * mappings; without it, only the current run's coverage is reported.
+ *
+ * @param options The requirements, the manifest, the results, and optionally
+ * the previous manifest and the tests a reviewer accepted.
+ * @returns The report, including whether the run supports verification.
+ * @throws {TestingError} When results and manifest disagree.
+ */
+declare function createTraceabilityReport(options: {
+    readonly requirements: readonly RequirementEvidence[];
+    readonly manifest: TestManifest;
+    readonly results: readonly TestExecutionResult[];
+    readonly previousManifest?: TestManifest;
+    readonly reviewedTestIds?: readonly string[];
+}): TraceabilityReport;
+/**
+ * Decides whether a failing run is credible evidence that behaviour is absent.
+ *
+ * A test failing because the behaviour is missing is evidence; one failing to
+ * compile, or against a broken baseline, is not, and is classified as such
+ * rather than accepted.
+ *
+ * @param options The requirement, the baseline checks, the test results, and
+ * the revision, runner, and environment the run was performed in.
+ * @returns The classification, and why it was reached.
+ */
+declare function classifyRedState(options: {
+    readonly requirement: RequirementEvidence;
+    readonly baselineChecks: readonly BaselineCheck[];
+    readonly tests: readonly RedTestResult[];
+    readonly baselineRevision: string;
+    readonly runner: string;
+    readonly environment: string;
+}): RedStateResult;
+/**
+ * Starts an application against an isolated store, for one test.
+ *
+ * Supply either `create` or `routes`, never both. The context is disposable,
+ * so `await using` closes the store and runs cleanup even on failure.
+ *
+ * ```ts
+ * import { createTestApplication } from "@sleepy-hollow/framework/testing";
+ *
+ * await using app = await createTestApplication({ routes: [] });
+ * const { response } = await app.request({ path: "/widgets/w_1" });
+ * ```
+ *
+ * @param options The application to build, and the fixtures to build it with.
+ * @returns The running application, and its store.
+ */
+declare function createTestApplication<Principal = unknown, Credentials = unknown>(options: TestApplicationOptions<Principal, Credentials>): Promise<TestApplicationContext>;
+/**
+ * Asserts a response is the expected problem, and returns it parsed.
+ *
+ * @param response The response to check.
+ * @param expectation The status, type, title, and members required of it.
+ * @returns The parsed problem details.
+ */
+declare function assertProblem(response: Response, expectation: ProblemExpectation): Promise<ProblemDetails>;
+/**
+ * Decides which tests a change requires running.
+ *
+ * Targeting is a claim that the rest cannot be affected, so selection falls
+ * back to running everything whenever a changed file cannot be attributed to a
+ * requirement.
+ *
+ * @param options The changed targets, the requirement graph, the tests, and
+ * whether a shared file no requirement owns was changed.
+ * @returns The tests to run, and why.
+ */
+declare function selectAffectedTests(options: {
+    readonly targets: readonly string[];
+    readonly requirements: readonly RequirementDependency[];
+    readonly tests: readonly {
+        readonly id: string;
+        readonly requirementId: string;
+    }[];
+    readonly hasUnownedSharedChange?: boolean;
+}): TestSelection;
+
+export { BaselineCheck, CriterionTestDescriptor, CriterionTestRegistry, CriterionTestSpec, ProblemDetails, ProblemExpectation, RedStateResult, RedTestResult, RequirementDependency, RequirementEvidence, TestApplicationContext, TestApplicationOptions, TestExecutionResult, TestManifest, TestSelection, TestingDiagnostic, TestingError, TraceabilityReport, assertProblem, classifyRedState, createCriterionRegistry, createTestApplication, createTestManifest, createTraceabilityReport, criterionTest, selectAffectedTests };

package/dist/testing.js

@@ -0,0 +1,29 @@
+import {
+  TestingError,
+  assertProblem,
+  classifyRedState,
+  createCriterionRegistry,
+  createTestApplication,
+  createTestManifest,
+  createTraceabilityReport,
+  criterionTest,
+  selectAffectedTests
+} from "./chunk-D4U3ZY4O.js";
+import "./chunk-BAKXP7IR.js";
+import "./chunk-DGTHFZPZ.js";
+import "./chunk-CAPFDC25.js";
+import "./chunk-53TZY5YP.js";
+import "./chunk-LNJDFJGT.js";
+import "./chunk-5WRI5ZAA.js";
+export {
+  TestingError,
+  assertProblem,
+  classifyRedState,
+  createCriterionRegistry,
+  createTestApplication,
+  createTestManifest,
+  createTraceabilityReport,
+  criterionTest,
+  selectAffectedTests
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-BC7LJJ6G.d.ts

@@ -0,0 +1,131 @@
+/** The HTTP methods a route module may export an operation for. */
+declare const HTTP_METHODS: readonly ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"];
+/** One of the {@linkcode HTTP_METHODS} a route operation may answer. */
+type HttpMethod = (typeof HTTP_METHODS)[number];
+type SchemaOutput<Schema, Fallback> = Schema extends {
+    readonly _zod: {
+        readonly output: infer Output;
+    };
+} ? Output : Schema extends {
+    readonly _output: infer Output;
+} ? Output : Fallback;
+type ReadonlyOutput<Output> = Output extends object ? Readonly<Output> : Output;
+type LocationOutput<Schemas, Location extends PropertyKey, Fallback> = Schemas extends {
+    readonly [Key in Location]: infer Schema;
+} ? ReadonlyOutput<SchemaOutput<Schema, Fallback>> : Fallback;
+type BodyOutput<Schemas> = Schemas extends {
+    readonly body: {
+        readonly schema: infer Schema;
+    };
+} ? ReadonlyOutput<SchemaOutput<Schema, unknown>> : undefined;
+/**
+ * The authenticated caller a handler runs on behalf of.
+ *
+ * Present only on routes whose security declares authentication; a route
+ * declaring `"none"` receives `null` instead, and the type reflects that so a
+ * handler cannot read a principal it was never given.
+ */
+interface RoutePrincipal {
+    /** Stable identifier for the caller, unique within its {@linkcode type}. */
+    readonly id: string;
+    /** What kind of caller this is, as named by the authentication provider. */
+    readonly type: string;
+    /** Additional claims the provider asserted about the caller. */
+    readonly claims?: Readonly<Record<string, unknown>>;
+}
+type SecurityPrincipal<Security> = Security extends {
+    readonly authentication: {
+        readonly mode: "required";
+    };
+} ? RoutePrincipal : Security extends {
+    readonly authentication: {
+        readonly mode: "none";
+    };
+} ? null : RoutePrincipal | null;
+/**
+ * What a route handler receives.
+ *
+ * Each validated location is typed from the route's own schemas, so `params`,
+ * `query`, `headers`, and `body` arrive already parsed rather than as raw
+ * strings the handler has to re-check.
+ */
+interface RouteHandlerContext<Schemas = unknown, Security = unknown> {
+    /** The incoming request, unmodified. */
+    readonly request: Request;
+    /** Path parameters, parsed by the route's `params` schema. */
+    readonly params: LocationOutput<Schemas, "params", Readonly<Record<string, string>>>;
+    /** Query string values, parsed by the route's `query` schema. */
+    readonly query: LocationOutput<Schemas, "query", Readonly<Record<string, unknown>>>;
+    /** Request headers, parsed by the route's `headers` schema. */
+    readonly headers: LocationOutput<Schemas, "headers", Readonly<Record<string, unknown>>>;
+    /** The parsed request body, or `undefined` when the route declares none. */
+    readonly body: BodyOutput<Schemas>;
+    /** Aborts when the client disconnects or the request times out. */
+    readonly signal: AbortSignal;
+    /** The authenticated caller, or `null` on an unauthenticated route. */
+    readonly principal: SecurityPrincipal<Security>;
+    /** Correlates this request across logs and captured evidence. */
+    readonly requestId: string;
+}
+/**
+ * One method's implementation within a route module: its schemas, its security,
+ * its documented contract, and the handler that answers it.
+ */
+interface RouteOperation<Schemas = unknown, Security = unknown, Contract = unknown> {
+    /** Validation schemas for each request location and each response status. */
+    readonly schemas: Schemas;
+    /** Authentication and authorization requirements for this operation. */
+    readonly security: Security;
+    /** Documentation for this operation, such as its summary. */
+    readonly contract: Contract;
+    /** Answers the request once validation and security have passed. */
+    readonly handler: (context: RouteHandlerContext<Schemas, Security>) => Response | Promise<Response>;
+}
+/** A route file's default export: one operation per method it answers. */
+type RouteModule = Partial<Record<HttpMethod, RouteOperation<unknown, unknown, unknown>>>;
+/**
+ * One method of one route after discovery, with its URL path derived from the
+ * file's position in the tree. This is what the router dispatches against.
+ */
+interface NormalizedRoute {
+    /** The method this entry answers. */
+    readonly method: HttpMethod;
+    /** The URL path, with parameters as `[name]` segments. */
+    readonly path: string;
+    /** Path of the file this route was discovered from. */
+    readonly source: string;
+    /** Names of the path parameters, in the order they appear. */
+    readonly parameterNames: readonly string[];
+    /** The operation to invoke for this method. */
+    readonly operation: RouteOperation<unknown, unknown, unknown>;
+}
+/** One reason discovery refused a route tree. */
+interface RoutingDiagnostic {
+    /** Stable machine-readable identifier for this kind of fault. */
+    readonly code: string;
+    /** What is wrong, in one sentence. */
+    readonly summary: string;
+    /** The files this diagnostic was raised against. */
+    readonly files: readonly string[];
+    /** The route path concerned, when the fault is specific to one. */
+    readonly route?: string;
+    /** What to change to resolve it. */
+    readonly correction?: string;
+}
+/**
+ * Thrown when a route tree cannot be discovered.
+ *
+ * Discovery reports every fault it found rather than the first, so one run
+ * surfaces the whole set of corrections.
+ */
+declare class RouteDiscoveryError extends Error {
+    readonly diagnostics: readonly RoutingDiagnostic[];
+    /**
+     * Builds an error whose message lists every diagnostic, one per line.
+     *
+     * @param diagnostics Every fault discovery found, in the order detected.
+     */
+    constructor(diagnostics: readonly RoutingDiagnostic[]);
+}
+
+export { HTTP_METHODS as H, type NormalizedRoute as N, RouteDiscoveryError as R, type HttpMethod as a, type RouteHandlerContext as b, type RouteModule as c, type RouteOperation as d, type RoutePrincipal as e, type RoutingDiagnostic as f };

package/dist/types-BUXw3UwN.d.ts

@@ -0,0 +1,54 @@
+import * as drizzle_orm_better_sqlite3 from 'drizzle-orm/better-sqlite3';
+import BetterSqlite3 from 'better-sqlite3';
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+
+type DatabaseProfile = "sqlite" | "postgres";
+interface EmbeddedSqliteOptions {
+    /** `:memory:` is intended only for tests. Production callers must pass a durable path. */
+    readonly filename: string;
+    readonly busyTimeoutMs?: number;
+    readonly production?: boolean;
+}
+interface PostgresOptions {
+    readonly databaseUrl: string;
+    readonly maxConnections?: number;
+    readonly tls?: boolean;
+}
+interface EmbeddedSqliteDatabase {
+    readonly profile: "sqlite";
+    readonly client: BetterSqlite3.Database;
+    readonly orm: ReturnType<typeof drizzle_orm_better_sqlite3.drizzle>;
+    close(): void;
+}
+interface PostgresDatabase {
+    readonly profile: "postgres";
+    readonly pool: Pool;
+    readonly orm: NodePgDatabase;
+    close(): Promise<void>;
+}
+interface ResourceField {
+    readonly kind: "text" | "integer" | "boolean" | "uuid" | "timestamp" | "json" | "binary";
+    readonly nullable?: boolean;
+    readonly unique?: boolean;
+}
+interface ResourceDefinition {
+    readonly name: string;
+    readonly primaryKey: string;
+    readonly fields: Readonly<Record<string, ResourceField>>;
+}
+interface ResourceRepository<Record extends object> {
+    get(id: string): Promise<Record | undefined>;
+    create(input: Record): Promise<Record>;
+    update(id: string, expectedVersion: number, input: Partial<Record>): Promise<Record>;
+    delete(id: string, expectedVersion: number): Promise<void>;
+    list(options?: {
+        readonly limit?: number;
+        readonly cursor?: string;
+    }): Promise<{
+        readonly items: readonly Record[];
+        readonly cursor?: string;
+    }>;
+}
+
+export type { DatabaseProfile as D, EmbeddedSqliteDatabase as E, PostgresDatabase as P, ResourceDefinition as R, EmbeddedSqliteOptions as a, PostgresOptions as b, ResourceField as c, ResourceRepository as d };