@warlock.js/core 5.34.3 → 5.35.0

package/esm/index.mjs

@@ -28,7 +28,7 @@ import { DEFAULT_CSP_DIRECTIVES, InvalidCspDirectiveError, applyCspHeader, build
 import { HttpErrorCodes } from "./http/error-codes.mjs";
 import { isAllowedCsrfOrigin, normalizeOrigin, originOf, ownOrigin, resolveCsrfOriginVerdict } from "./http/csrf-origin-policy.mjs";
 import { requiresDefaultCsrfGuard, runDefaultCsrfGuard } from "./http/csrf-default-guard.mjs";
-import { BadRequestError, ConflictError, CookieJarUnavailableError, ForbiddenError, HttpError, NotAcceptableError, NotAllowedError, ResourceNotFoundError, ServerError, UnAuthorizedError } from "./http/errors/errors.mjs";
+import { AppError, BadRequestError, ConflictError, CookieJarUnavailableError, ForbiddenError, HttpError, NotAcceptableError, NotAllowedError, ResourceNotFoundError, ServerError, UnAuthorizedError } from "./http/errors/errors.mjs";
 import { deriveTraceId, parseTraceparentTraceId } from "./http/tracing/trace-id.mjs";
 import { buildTracingContext, dispatchPhase, dispatchRequestEnd, dispatchRequestStart, isTracingEnabled, registerTracingHooks, resetTracingConfigForTests, resolveTracingConfig } from "./http/tracing/tracing-dispatcher.mjs";
 import { createRequestStore, t } from "./http/middleware/inject-request-context.mjs";
@@ -101,6 +101,7 @@ import { notifyHttpServerRebuilt, onHttpServerRebuilt } from "./http/server-rebu
 import { escapeHeaderValue } from "./http/escape-header-value.mjs";
 import { isSafeRedirect, safeRedirect } from "./http/safe-redirect.mjs";
 import { requestMemo } from "./http/context/request-memo.mjs";
+import { listEndpoint } from "./http/list-endpoint.mjs";
 import "./http/index.mjs";
 import { existsExceptCurrentIdRule } from "./validation/database/exists-except-current-id.mjs";
 import { existsExceptCurrentUserRule } from "./validation/database/exists-except-current-user.mjs";
@@ -203,4 +204,4 @@ import { colors } from "@mongez/copper";
 
 export * from "@mongez/localization"
 
-export { $registerUseCase, $unregisterUseCase, APP_ROLES, AUTH_GUARD_MARKER, AccessConnector, AiConnector, Application, BOOT_SIGNAL_ENV_KEY, BOOT_SIGNAL_VERSION, BadRequestError, BadSchemaUseCaseError, BaseConnector, BenchmarkProfiler, BenchmarkSnapshots, CLICommand, CacheConnector, CascadeAdapter, CascadeQueryBuilder, CloudDriver, ConfigSpecialHandlers, ConflictError, ConnectorLifecyclePhase, ConnectorPriority, ConnectorsManager, ConsoleChannel, CookieJarUnavailableError, DEFAULT_CSP_DIRECTIVES, DEFAULT_POSTMAN_BASE_URL, DOSpacesDriver, DatabaseCacheDriver, DatabaseConnector, DatabaseLog, DatabaseLogModel, ERROR_CODES, ERROR_CODES_DOCS_URL, FileValidator, ForbiddenError, HeraldConnector, HttpConnector, HttpError, HttpErrorCodes, Image, ImageVariantsConfigError, InvalidConfigError, InvalidCspDirectiveError, LocalDriver, LocaleDictionaryError, LoggerConnector, MAIL_EVENTS, Mail, MailError, MailerConnector, MemorySecretBackend, MimeTypes, NULLABLE_RESOURCE, NoopChannel, NotAcceptableError, NotAllowedError, NotificationsConnector, OPENAPI_JSON_SCHEMA_DIALECT, POSTMAN_COLLECTION_SCHEMA, Path, PortInUseError, Queue, R2Driver, RegisterResource, RepositoryManager, Request, RequestController, RequestLog, Resource, ResourceFieldBuilder, ResourceNotFoundError, Response, ResponseStatus, Restful, RouteNameTakenError, RouteRegistry, Router, S3Driver, SUPPORTED_RUNTIMES_DOCS_URL, ScopedStorage, SecretStore, SecretStoreError, SeederDependencyCycleError, ServerError, SocketConnector, Storage, StorageCapabilityError, StorageConnector, StorageError, StorageFile, StorageNotInitializedError, UPDATE_MANY_BATCH_SIZE, UPLOADS_DEFAULTS, URL_CREDENTIAL_PARAMS, UnAuthorizedError, UnknownSeederDependencyError, UploadedFile, WarlockConfigManager, WarlockError, addUseCaseHistory, anyMatch, app, appLog, appPath, applyCspHeader, assertConfiguredHttpPortIsFree, assertMailCount, assertMailSent, assertNoReservedConnectorNames, assertNodeOnlyCommand, assertPortIsAvailable, assertSitesRequireWebRole, assertUniqueConnectorNames, assertValidConfigModules, assetsUrl, beginHttpDrain, bootstrap, broadcastSocketEvent, broadcastUseCaseResult, buildCspHeaderValue, buildIdempotencyCacheKey, buildOpenApiDocument, buildRequestLogSnapshot, buildTracingContext, cachePath, captureMail, clearPositionalHandlerSuspects, clearTestMailbox, clock, closeAllMailers, closeMailer, closeServerWithTimeout, colors, command, config, configPath, configSpecialHandlers, connectorsManager, container, createHttpApplication, createRequestStore, createUploadedFileController, decrypt, defaultHttpConfigurations, defineConfig, defineConfigSchema, defineResource, deriveTraceId, describeJavaScriptRuntime, describePositionalHandlerSuspect, detectJavaScriptRuntime, dispatchPhase, dispatchRequestEnd, dispatchRequestStart, displayEnvironmentMode, encrypt, ensureFatalIsVisible, env, environment, errorCodeDocsUrl, errorCodeOf, escapeHeaderValue, evaluateConditionalRequest, exampleFromSchema, existsExceptCurrentIdRule, existsExceptCurrentUserRule, explainErrorCode, fetchLatestVersion, fileExtensionRule, fileRule, fileTypeRule, findMailsBySubject, findMailsTo, fireLifecycleEvent, forgetPositionalHandlerSuspects, formatConfigIssues, generateImageVariants, generateMailId, getDefaultMailConfig, getDevelopmentOpenApiDocument, getDevelopmentPostmanCollection, getExplicitMailMode, getHttpReadyReport, getHttpServer, getLastMail, getLocalized, getMailEventName, getMailMode, getMailboxSize, getMailer, getMailerConfig, getMimeType, getPoolStats, getPublicUrl, getRoles, getSites, getSocketServer, getTestMailbox, getUseCase, getUseCaseHistory, getUseCases, globalEventsCallbacksMap, globalUseCasesEvents, hasRole, hashBody, hashPassword, health, hmacHash, httpConfig, ids, imageRule, increaseUseCaseFailedCalls, increaseUseCaseSuccessCalls, inspectHandlerSignature, ipMatches, isAllowedCsrfOrigin, isAuthGuardMiddleware, isBootSignal, isConfigSchema, isDevelopmentMode, isNewerVersion, isNullableResource, isPortAvailable, isPrivateOrReservedIp, isProductionMode, isSafeRedirect, isTestMode, isTracingEnabled, isUnguardedMutatingRoute, isUnknownTsExtensionError, isUnresolvedConfigImportError, isUnsupportedTypeStrippingError, isValidIdempotencyKey, isWarlockErrorCode, listPositionalHandlerSuspects, loadS3, logResponse, logsPath, looksLikePositionalHandler, mailEvents, markAuthGuard, matchesDerivedRouteName, matchesIfMatch, matchesIfNoneMatch, measure, mergeCspDirectives, middleware, nodeOnlyCommandError, normalizeOrigin, normalizeRequestPath, normalizeRoutePath, notifyHttpServerRebuilt, nullable, onHttpServerRebuilt, openApiToPostmanCollection, originOf, ownOrigin, parseEntityTag, parseEntityTagList, parseLocaleDictionary, parseRoles, parseSites, parseSize, parseTraceparentTraceId, paths, preflightConfiguredHttpPort, promiseAllObject, publicPath, publicUrl, purgeImageVariants, redactQueryCredentials, redactUrlCredentials, registerAppConfig, registerConfiguredConnectors, registerDevelopmentOpenApiProvider, registerGroupedTranslationKeys, registerHttpPlugins, registerLocaleDictionary, registerTracingHooks, remedyLines, renderReact, renderReactMail, reportPositionalHandlerSuspects, reportUnguardedMutatingRoutes, requestContext, requestMemo, requiresDefaultCsrfGuard, resetHttpReadyReport, resetMailConfig, resetMailMode, resetRolesCacheForTests, resetTracingConfigForTests, resetUnguardedRouteReports, resolveCspConfig, resolveCsrfOriginVerdict, resolveImageVariant, resolveMailConfig, resolvePublicRoot, resolveRequestLoggingOptions, resolveTracingConfig, resolveWithinRoot, rootPath, routeNameMethodSuffix, router, runDefaultCsrfGuard, runPipeline, safeFetchToBuffer, safeRedirect, sanitizePath, secrets, seeder, sendBootSignal, sendMail, serializeCspDirectives, servesHttp, setBaseUrl, setClockSource, setConfig, setEnvironment, setHttpReadyReport, setIdsSource, setLogConfigurations, setMailConfigurations, setMailMode, shouldPreflightHttpPort, sleep, sluggable, srcPath, startHttpServer, stopHttpApplication, storage, storageConfig, storageConfigurations, storageDriverContext, storagePath, streamReactResponse, strongEntityTagMatch, t, tempPath, toJson, toSingleLineSseField, trackConnectionsForDrain, uniqueExceptCurrentIdRule, uniqueExceptCurrentUserRule, unregisterLocaleDictionary, unverifiedBuildRuntimeNotice, uploadedFileController, uploadedFileMetadataSchema, uploadsConfig, uploadsPath, uploadsUrl, url, useCase, useComputedModel, useComputedSlug, useCurrentUser, useHashedPassword, useRequest, useRequestStore, validateConfigValue, validateCspConfigAtBoot, validateCspDirectives, verifyMailer, verifyPassword, warlockConfigManager, warlockPath, wasMailSentTo, wasMailSentWithSubject, weakEntityTagMatch, wrapResponseInDataKey };
+export { $registerUseCase, $unregisterUseCase, APP_ROLES, AUTH_GUARD_MARKER, AccessConnector, AiConnector, AppError, Application, BOOT_SIGNAL_ENV_KEY, BOOT_SIGNAL_VERSION, BadRequestError, BadSchemaUseCaseError, BaseConnector, BenchmarkProfiler, BenchmarkSnapshots, CLICommand, CacheConnector, CascadeAdapter, CascadeQueryBuilder, CloudDriver, ConfigSpecialHandlers, ConflictError, ConnectorLifecyclePhase, ConnectorPriority, ConnectorsManager, ConsoleChannel, CookieJarUnavailableError, DEFAULT_CSP_DIRECTIVES, DEFAULT_POSTMAN_BASE_URL, DOSpacesDriver, DatabaseCacheDriver, DatabaseConnector, DatabaseLog, DatabaseLogModel, ERROR_CODES, ERROR_CODES_DOCS_URL, FileValidator, ForbiddenError, HeraldConnector, HttpConnector, HttpError, HttpErrorCodes, Image, ImageVariantsConfigError, InvalidConfigError, InvalidCspDirectiveError, LocalDriver, LocaleDictionaryError, LoggerConnector, MAIL_EVENTS, Mail, MailError, MailerConnector, MemorySecretBackend, MimeTypes, NULLABLE_RESOURCE, NoopChannel, NotAcceptableError, NotAllowedError, NotificationsConnector, OPENAPI_JSON_SCHEMA_DIALECT, POSTMAN_COLLECTION_SCHEMA, Path, PortInUseError, Queue, R2Driver, RegisterResource, RepositoryManager, Request, RequestController, RequestLog, Resource, ResourceFieldBuilder, ResourceNotFoundError, Response, ResponseStatus, Restful, RouteNameTakenError, RouteRegistry, Router, S3Driver, SUPPORTED_RUNTIMES_DOCS_URL, ScopedStorage, SecretStore, SecretStoreError, SeederDependencyCycleError, ServerError, SocketConnector, Storage, StorageCapabilityError, StorageConnector, StorageError, StorageFile, StorageNotInitializedError, UPDATE_MANY_BATCH_SIZE, UPLOADS_DEFAULTS, URL_CREDENTIAL_PARAMS, UnAuthorizedError, UnknownSeederDependencyError, UploadedFile, WarlockConfigManager, WarlockError, addUseCaseHistory, anyMatch, app, appLog, appPath, applyCspHeader, assertConfiguredHttpPortIsFree, assertMailCount, assertMailSent, assertNoReservedConnectorNames, assertNodeOnlyCommand, assertPortIsAvailable, assertSitesRequireWebRole, assertUniqueConnectorNames, assertValidConfigModules, assetsUrl, beginHttpDrain, bootstrap, broadcastSocketEvent, broadcastUseCaseResult, buildCspHeaderValue, buildIdempotencyCacheKey, buildOpenApiDocument, buildRequestLogSnapshot, buildTracingContext, cachePath, captureMail, clearPositionalHandlerSuspects, clearTestMailbox, clock, closeAllMailers, closeMailer, closeServerWithTimeout, colors, command, config, configPath, configSpecialHandlers, connectorsManager, container, createHttpApplication, createRequestStore, createUploadedFileController, decrypt, defaultHttpConfigurations, defineConfig, defineConfigSchema, defineResource, deriveTraceId, describeJavaScriptRuntime, describePositionalHandlerSuspect, detectJavaScriptRuntime, dispatchPhase, dispatchRequestEnd, dispatchRequestStart, displayEnvironmentMode, encrypt, ensureFatalIsVisible, env, environment, errorCodeDocsUrl, errorCodeOf, escapeHeaderValue, evaluateConditionalRequest, exampleFromSchema, existsExceptCurrentIdRule, existsExceptCurrentUserRule, explainErrorCode, fetchLatestVersion, fileExtensionRule, fileRule, fileTypeRule, findMailsBySubject, findMailsTo, fireLifecycleEvent, forgetPositionalHandlerSuspects, formatConfigIssues, generateImageVariants, generateMailId, getDefaultMailConfig, getDevelopmentOpenApiDocument, getDevelopmentPostmanCollection, getExplicitMailMode, getHttpReadyReport, getHttpServer, getLastMail, getLocalized, getMailEventName, getMailMode, getMailboxSize, getMailer, getMailerConfig, getMimeType, getPoolStats, getPublicUrl, getRoles, getSites, getSocketServer, getTestMailbox, getUseCase, getUseCaseHistory, getUseCases, globalEventsCallbacksMap, globalUseCasesEvents, hasRole, hashBody, hashPassword, health, hmacHash, httpConfig, ids, imageRule, increaseUseCaseFailedCalls, increaseUseCaseSuccessCalls, inspectHandlerSignature, ipMatches, isAllowedCsrfOrigin, isAuthGuardMiddleware, isBootSignal, isConfigSchema, isDevelopmentMode, isNewerVersion, isNullableResource, isPortAvailable, isPrivateOrReservedIp, isProductionMode, isSafeRedirect, isTestMode, isTracingEnabled, isUnguardedMutatingRoute, isUnknownTsExtensionError, isUnresolvedConfigImportError, isUnsupportedTypeStrippingError, isValidIdempotencyKey, isWarlockErrorCode, listEndpoint, listPositionalHandlerSuspects, loadS3, logResponse, logsPath, looksLikePositionalHandler, mailEvents, markAuthGuard, matchesDerivedRouteName, matchesIfMatch, matchesIfNoneMatch, measure, mergeCspDirectives, middleware, nodeOnlyCommandError, normalizeOrigin, normalizeRequestPath, normalizeRoutePath, notifyHttpServerRebuilt, nullable, onHttpServerRebuilt, openApiToPostmanCollection, originOf, ownOrigin, parseEntityTag, parseEntityTagList, parseLocaleDictionary, parseRoles, parseSites, parseSize, parseTraceparentTraceId, paths, preflightConfiguredHttpPort, promiseAllObject, publicPath, publicUrl, purgeImageVariants, redactQueryCredentials, redactUrlCredentials, registerAppConfig, registerConfiguredConnectors, registerDevelopmentOpenApiProvider, registerGroupedTranslationKeys, registerHttpPlugins, registerLocaleDictionary, registerTracingHooks, remedyLines, renderReact, renderReactMail, reportPositionalHandlerSuspects, reportUnguardedMutatingRoutes, requestContext, requestMemo, requiresDefaultCsrfGuard, resetHttpReadyReport, resetMailConfig, resetMailMode, resetRolesCacheForTests, resetTracingConfigForTests, resetUnguardedRouteReports, resolveCspConfig, resolveCsrfOriginVerdict, resolveImageVariant, resolveMailConfig, resolvePublicRoot, resolveRequestLoggingOptions, resolveTracingConfig, resolveWithinRoot, rootPath, routeNameMethodSuffix, router, runDefaultCsrfGuard, runPipeline, safeFetchToBuffer, safeRedirect, sanitizePath, secrets, seeder, sendBootSignal, sendMail, serializeCspDirectives, servesHttp, setBaseUrl, setClockSource, setConfig, setEnvironment, setHttpReadyReport, setIdsSource, setLogConfigurations, setMailConfigurations, setMailMode, shouldPreflightHttpPort, sleep, sluggable, srcPath, startHttpServer, stopHttpApplication, storage, storageConfig, storageConfigurations, storageDriverContext, storagePath, streamReactResponse, strongEntityTagMatch, t, tempPath, toJson, toSingleLineSseField, trackConnectionsForDrain, uniqueExceptCurrentIdRule, uniqueExceptCurrentUserRule, unregisterLocaleDictionary, unverifiedBuildRuntimeNotice, uploadedFileController, uploadedFileMetadataSchema, uploadsConfig, uploadsPath, uploadsUrl, url, useCase, useComputedModel, useComputedSlug, useCurrentUser, useHashedPassword, useRequest, useRequestStore, validateConfigValue, validateCspConfigAtBoot, validateCspDirectives, verifyMailer, verifyPassword, warlockConfigManager, warlockPath, wasMailSentTo, wasMailSentWithSubject, weakEntityTagMatch, wrapResponseInDataKey };

package/esm/openapi/security.mjs

@@ -14,12 +14,14 @@ function isAuthSource(value) {
 */
 function parseAuthDescriptor(value) {
 	if (typeof value !== "object" || value === null) return;
-	const { sources, userTypes } = value;
+	const { sources, userTypes, required } = value;
+	if (required !== void 0 && typeof required !== "boolean") return void 0;
 	if (!Array.isArray(sources) || sources.length === 0 || !sources.every(isAuthSource)) return;
 	if (userTypes !== void 0 && !(Array.isArray(userTypes) && userTypes.every((type) => typeof type === "string"))) return;
 	return {
 		sources: [...sources],
-		userTypes: Array.isArray(userTypes) ? [...userTypes] : []
+		userTypes: Array.isArray(userTypes) ? [...userTypes] : [],
+		...required === void 0 ? {} : { required }
 	};
 }
 /**
@@ -36,6 +38,8 @@ function readRouteAuth(middleware, warn) {
 	const sources = [];
 	const userTypes = [];
 	let found = false;
+	let required = false;
+	let hasRequiredFlag = false;
 	for (const fn of middleware) {
 		if (typeof fn !== "function") continue;
 		const raw = Reflect.get(fn, AUTH_DESCRIPTOR_SYMBOL);
@@ -46,12 +50,15 @@ function readRouteAuth(middleware, warn) {
 			continue;
 		}
 		found = true;
+		required ||= descriptor.required !== false;
+		hasRequiredFlag ||= descriptor.required !== void 0;
 		for (const source of descriptor.sources) if (!sources.some((existing) => typeof existing === "string" || typeof source === "string" ? existing === source : existing.cookie === source.cookie)) sources.push(source);
 		for (const type of descriptor.userTypes) if (!userTypes.includes(type)) userTypes.push(type);
 	}
 	return found ? {
 		sources,
-		userTypes
+		userTypes,
+		...hasRequiredFlag ? { required } : {}
 	} : void 0;
 }
 /**
@@ -64,7 +71,7 @@ var SecuritySchemes = class {
 		this.cookieSchemeNames = /* @__PURE__ */ new Map();
 	}
 	requirementsFor(descriptor) {
-		return descriptor.sources.map((source) => {
+		const requirements = descriptor.sources.map((source) => {
 			if (source === "header") {
 				this.schemes.bearerAuth = {
 					type: "http",
@@ -75,6 +82,7 @@ var SecuritySchemes = class {
 			}
 			return { [this.cookieScheme(source.cookie)]: [] };
 		});
+		return descriptor.required === false ? [...requirements, {}] : requirements;
 	}
 	cookieScheme(cookie) {
 		const existing = this.cookieSchemeNames.get(cookie);

package/esm/openapi/security.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"security.mjs","names":[],"sources":["../../../../../../../../packages/core/src/openapi/security.ts"],"sourcesContent":["import type {\n  AuthDescriptor,\n  OpenApiSecurityRequirement,\n  OpenApiSecurityScheme,\n  WarningSink,\n} from \"./types\";\n\n/**\n * The marker `authMiddleware()` attaches to the middleware it returns.\n * Core reads it structurally; it never imports the auth package.\n */\nexport const AUTH_DESCRIPTOR_SYMBOL = Symbol.for(\"warlock.auth\");\n\nfunction isAuthSource(value: unknown): value is AuthDescriptor[\"sources\"][number] {\n  if (value === \"header\") {\n    return true;\n  }\n\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as { cookie?: unknown }).cookie === \"string\" &&\n    (value as { cookie: string }).cookie.length > 0\n  );\n}\n\n/**\n * Validate an auth descriptor. Returns `undefined` for anything that is not\n * `{ sources: (\"header\" | { cookie: string })[], userTypes?: string[] }` with at least one source.\n */\nexport function parseAuthDescriptor(value: unknown): AuthDescriptor | undefined {\n  if (typeof value !== \"object\" || value === null) {\n    return undefined;\n  }\n\n  const { sources, userTypes } = value as { sources?: unknown; userTypes?: unknown };\n\n  if (!Array.isArray(sources) || sources.length === 0 || !sources.every(isAuthSource)) {\n    return undefined;\n  }\n\n  if (\n    userTypes !== undefined &&\n    !(Array.isArray(userTypes) && userTypes.every((type) => typeof type === \"string\"))\n  ) {\n    return undefined;\n  }\n\n  return { sources: [...sources], userTypes: Array.isArray(userTypes) ? [...userTypes] : [] };\n}\n\n/**\n * Combine the descriptors of every guard on a route (group middleware is already merged into\n * the route): unique sources, union of user types.\n *\n * Middleware without a descriptor is ordinary middleware and is ignored silently. A function\n * that carries a descriptor of the wrong shape is reported through `warn`.\n *\n * @returns `undefined` when the route has no valid auth descriptor.\n */\nexport function readRouteAuth(middleware: unknown, warn: WarningSink): AuthDescriptor | undefined {\n  if (!Array.isArray(middleware)) {\n    return undefined;\n  }\n\n  const sources: AuthDescriptor[\"sources\"] = [];\n  const userTypes: string[] = [];\n  let found = false;\n\n  for (const fn of middleware) {\n    if (typeof fn !== \"function\") {\n      continue;\n    }\n\n    const raw = Reflect.get(fn, AUTH_DESCRIPTOR_SYMBOL);\n\n    if (raw === undefined) {\n      continue;\n    }\n\n    const descriptor = parseAuthDescriptor(raw);\n\n    if (!descriptor) {\n      warn(\n        \"a middleware carries a malformed warlock.auth descriptor; the route is documented without security.\",\n      );\n\n      continue;\n    }\n\n    found = true;\n\n    for (const source of descriptor.sources) {\n      const duplicate = sources.some((existing) =>\n        typeof existing === \"string\" || typeof source === \"string\"\n          ? existing === source\n          : existing.cookie === source.cookie,\n      );\n\n      if (!duplicate) {\n        sources.push(source);\n      }\n    }\n\n    for (const type of descriptor.userTypes) {\n      if (!userTypes.includes(type)) {\n        userTypes.push(type);\n      }\n    }\n  }\n\n  return found ? { sources, userTypes } : undefined;\n}\n\n/**\n * Collects the security schemes the routes actually use and turns descriptors into\n * per-operation requirements. A dual header + cookie guard is an OR: one requirement each.\n */\nexport class SecuritySchemes {\n  public readonly schemes: Record<string, OpenApiSecurityScheme> = {};\n\n  private readonly cookieSchemeNames = new Map<string, string>();\n\n  public requirementsFor(descriptor: AuthDescriptor): OpenApiSecurityRequirement[] {\n    return descriptor.sources.map((source) => {\n      if (source === \"header\") {\n        this.schemes.bearerAuth = { type: \"http\", scheme: \"bearer\", bearerFormat: \"JWT\" };\n\n        return { bearerAuth: [] };\n      }\n\n      const name = this.cookieScheme(source.cookie);\n\n      return { [name]: [] };\n    });\n  }\n\n  private cookieScheme(cookie: string): string {\n    const existing = this.cookieSchemeNames.get(cookie);\n\n    if (existing) {\n      return existing;\n    }\n\n    // The first cookie keeps the conventional name; a second, different cookie gets its own.\n    const name =\n      this.cookieSchemeNames.size === 0\n        ? \"cookieAuth\"\n        : `cookieAuth_${cookie.replace(/[^A-Za-z0-9._-]/g, \"\")}`;\n\n    this.cookieSchemeNames.set(cookie, name);\n    this.schemes[name] = { type: \"apiKey\", in: \"cookie\", name: cookie };\n\n    return name;\n  }\n\n  public hasSchemes(): boolean {\n    return Object.keys(this.schemes).length > 0;\n  }\n}\n"],"mappings":";;;;;AAWA,MAAa,yBAAyB,OAAO,IAAI,cAAc;AAE/D,SAAS,aAAa,OAA4D;CAChF,IAAI,UAAU,UACZ,OAAO;CAGT,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAA+B,WAAW,YACjD,MAA6B,OAAO,SAAS;AAElD;;;;;AAMA,SAAgB,oBAAoB,OAA4C;CAC9E,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC;CAGF,MAAM,EAAE,SAAS,cAAc;CAE/B,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,QAAQ,WAAW,KAAK,CAAC,QAAQ,MAAM,YAAY,GAChF;CAGF,IACE,cAAc,UACd,EAAE,MAAM,QAAQ,SAAS,KAAK,UAAU,OAAO,SAAS,OAAO,SAAS,QAAQ,IAEhF;CAGF,OAAO;EAAE,SAAS,CAAC,GAAG,OAAO;EAAG,WAAW,MAAM,QAAQ,SAAS,IAAI,CAAC,GAAG,SAAS,IAAI,CAAC;CAAE;AAC5F;;;;;;;;;;AAWA,SAAgB,cAAc,YAAqB,MAA+C;CAChG,IAAI,CAAC,MAAM,QAAQ,UAAU,GAC3B;CAGF,MAAM,UAAqC,CAAC;CAC5C,MAAM,YAAsB,CAAC;CAC7B,IAAI,QAAQ;CAEZ,KAAK,MAAM,MAAM,YAAY;EAC3B,IAAI,OAAO,OAAO,YAChB;EAGF,MAAM,MAAM,QAAQ,IAAI,IAAI,sBAAsB;EAElD,IAAI,QAAQ,QACV;EAGF,MAAM,aAAa,oBAAoB,GAAG;EAE1C,IAAI,CAAC,YAAY;GACf,KACE,qGACF;GAEA;EACF;EAEA,QAAQ;EAER,KAAK,MAAM,UAAU,WAAW,SAO9B,IAAI,CANc,QAAQ,MAAM,aAC9B,OAAO,aAAa,YAAY,OAAO,WAAW,WAC9C,aAAa,SACb,SAAS,WAAW,OAAO,MAGpB,GACX,QAAQ,KAAK,MAAM;EAIvB,KAAK,MAAM,QAAQ,WAAW,WAC5B,IAAI,CAAC,UAAU,SAAS,IAAI,GAC1B,UAAU,KAAK,IAAI;CAGzB;CAEA,OAAO,QAAQ;EAAE;EAAS;CAAU,IAAI;AAC1C;;;;;AAMA,IAAa,kBAAb,MAA6B;;iBACsC,CAAC;2CAE7B,IAAI,IAAoB;;CAE7D,AAAO,gBAAgB,YAA0D;EAC/E,OAAO,WAAW,QAAQ,KAAK,WAAW;GACxC,IAAI,WAAW,UAAU;IACvB,KAAK,QAAQ,aAAa;KAAE,MAAM;KAAQ,QAAQ;KAAU,cAAc;IAAM;IAEhF,OAAO,EAAE,YAAY,CAAC,EAAE;GAC1B;GAIA,OAAO,GAFM,KAAK,aAAa,OAAO,MAEzB,IAAI,CAAC,EAAE;EACtB,CAAC;CACH;CAEA,AAAQ,aAAa,QAAwB;EAC3C,MAAM,WAAW,KAAK,kBAAkB,IAAI,MAAM;EAElD,IAAI,UACF,OAAO;EAIT,MAAM,OACJ,KAAK,kBAAkB,SAAS,IAC5B,eACA,cAAc,OAAO,QAAQ,oBAAoB,EAAE;EAEzD,KAAK,kBAAkB,IAAI,QAAQ,IAAI;EACvC,KAAK,QAAQ,QAAQ;GAAE,MAAM;GAAU,IAAI;GAAU,MAAM;EAAO;EAElE,OAAO;CACT;CAEA,AAAO,aAAsB;EAC3B,OAAO,OAAO,KAAK,KAAK,OAAO,CAAC,CAAC,SAAS;CAC5C;AACF"}
+{"version":3,"file":"security.mjs","names":[],"sources":["../../../../../../../../packages/core/src/openapi/security.ts"],"sourcesContent":["import type {\n  AuthDescriptor,\n  OpenApiSecurityRequirement,\n  OpenApiSecurityScheme,\n  WarningSink,\n} from \"./types\";\n\n/**\n * The marker `authMiddleware()` attaches to the middleware it returns.\n * Core reads it structurally; it never imports the auth package.\n */\nexport const AUTH_DESCRIPTOR_SYMBOL = Symbol.for(\"warlock.auth\");\n\nfunction isAuthSource(value: unknown): value is AuthDescriptor[\"sources\"][number] {\n  if (value === \"header\") {\n    return true;\n  }\n\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as { cookie?: unknown }).cookie === \"string\" &&\n    (value as { cookie: string }).cookie.length > 0\n  );\n}\n\n/**\n * Validate an auth descriptor. Returns `undefined` for anything that is not\n * `{ sources: (\"header\" | { cookie: string })[], userTypes?: string[] }` with at least one source.\n */\nexport function parseAuthDescriptor(value: unknown): AuthDescriptor | undefined {\n  if (typeof value !== \"object\" || value === null) {\n    return undefined;\n  }\n\n  const { sources, userTypes, required } = value as {\n    sources?: unknown;\n    userTypes?: unknown;\n    required?: unknown;\n  };\n  if (required !== undefined && typeof required !== \"boolean\") return undefined;\n\n  if (!Array.isArray(sources) || sources.length === 0 || !sources.every(isAuthSource)) {\n    return undefined;\n  }\n\n  if (\n    userTypes !== undefined &&\n    !(Array.isArray(userTypes) && userTypes.every((type) => typeof type === \"string\"))\n  ) {\n    return undefined;\n  }\n\n  return {\n    sources: [...sources],\n    userTypes: Array.isArray(userTypes) ? [...userTypes] : [],\n    ...(required === undefined ? {} : { required }),\n  };\n}\n\n/**\n * Combine the descriptors of every guard on a route (group middleware is already merged into\n * the route): unique sources, union of user types.\n *\n * Middleware without a descriptor is ordinary middleware and is ignored silently. A function\n * that carries a descriptor of the wrong shape is reported through `warn`.\n *\n * @returns `undefined` when the route has no valid auth descriptor.\n */\nexport function readRouteAuth(middleware: unknown, warn: WarningSink): AuthDescriptor | undefined {\n  if (!Array.isArray(middleware)) {\n    return undefined;\n  }\n\n  const sources: AuthDescriptor[\"sources\"] = [];\n  const userTypes: string[] = [];\n  let found = false;\n  let required = false;\n  let hasRequiredFlag = false;\n\n  for (const fn of middleware) {\n    if (typeof fn !== \"function\") {\n      continue;\n    }\n\n    const raw = Reflect.get(fn, AUTH_DESCRIPTOR_SYMBOL);\n\n    if (raw === undefined) {\n      continue;\n    }\n\n    const descriptor = parseAuthDescriptor(raw);\n\n    if (!descriptor) {\n      warn(\n        \"a middleware carries a malformed warlock.auth descriptor; the route is documented without security.\",\n      );\n\n      continue;\n    }\n\n    found = true;\n    required ||= descriptor.required !== false;\n    hasRequiredFlag ||= descriptor.required !== undefined;\n\n    for (const source of descriptor.sources) {\n      const duplicate = sources.some((existing) =>\n        typeof existing === \"string\" || typeof source === \"string\"\n          ? existing === source\n          : existing.cookie === source.cookie,\n      );\n\n      if (!duplicate) {\n        sources.push(source);\n      }\n    }\n\n    for (const type of descriptor.userTypes) {\n      if (!userTypes.includes(type)) {\n        userTypes.push(type);\n      }\n    }\n  }\n\n  return found ? { sources, userTypes, ...(hasRequiredFlag ? { required } : {}) } : undefined;\n}\n\n/**\n * Collects the security schemes the routes actually use and turns descriptors into\n * per-operation requirements. A dual header + cookie guard is an OR: one requirement each.\n */\nexport class SecuritySchemes {\n  public readonly schemes: Record<string, OpenApiSecurityScheme> = {};\n\n  private readonly cookieSchemeNames = new Map<string, string>();\n\n  public requirementsFor(descriptor: AuthDescriptor): OpenApiSecurityRequirement[] {\n    const requirements: OpenApiSecurityRequirement[] = descriptor.sources.map((source) => {\n      if (source === \"header\") {\n        this.schemes.bearerAuth = { type: \"http\", scheme: \"bearer\", bearerFormat: \"JWT\" };\n\n        return { bearerAuth: [] };\n      }\n\n      const name = this.cookieScheme(source.cookie);\n\n      return { [name]: [] };\n    });\n    return descriptor.required === false ? [...requirements, {}] : requirements;\n  }\n\n  private cookieScheme(cookie: string): string {\n    const existing = this.cookieSchemeNames.get(cookie);\n\n    if (existing) {\n      return existing;\n    }\n\n    // The first cookie keeps the conventional name; a second, different cookie gets its own.\n    const name =\n      this.cookieSchemeNames.size === 0\n        ? \"cookieAuth\"\n        : `cookieAuth_${cookie.replace(/[^A-Za-z0-9._-]/g, \"\")}`;\n\n    this.cookieSchemeNames.set(cookie, name);\n    this.schemes[name] = { type: \"apiKey\", in: \"cookie\", name: cookie };\n\n    return name;\n  }\n\n  public hasSchemes(): boolean {\n    return Object.keys(this.schemes).length > 0;\n  }\n}\n"],"mappings":";;;;;AAWA,MAAa,yBAAyB,OAAO,IAAI,cAAc;AAE/D,SAAS,aAAa,OAA4D;CAChF,IAAI,UAAU,UACZ,OAAO;CAGT,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAA+B,WAAW,YACjD,MAA6B,OAAO,SAAS;AAElD;;;;;AAMA,SAAgB,oBAAoB,OAA4C;CAC9E,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC;CAGF,MAAM,EAAE,SAAS,WAAW,aAAa;CAKzC,IAAI,aAAa,UAAa,OAAO,aAAa,WAAW,OAAO;CAEpE,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,QAAQ,WAAW,KAAK,CAAC,QAAQ,MAAM,YAAY,GAChF;CAGF,IACE,cAAc,UACd,EAAE,MAAM,QAAQ,SAAS,KAAK,UAAU,OAAO,SAAS,OAAO,SAAS,QAAQ,IAEhF;CAGF,OAAO;EACL,SAAS,CAAC,GAAG,OAAO;EACpB,WAAW,MAAM,QAAQ,SAAS,IAAI,CAAC,GAAG,SAAS,IAAI,CAAC;EACxD,GAAI,aAAa,SAAY,CAAC,IAAI,EAAE,SAAS;CAC/C;AACF;;;;;;;;;;AAWA,SAAgB,cAAc,YAAqB,MAA+C;CAChG,IAAI,CAAC,MAAM,QAAQ,UAAU,GAC3B;CAGF,MAAM,UAAqC,CAAC;CAC5C,MAAM,YAAsB,CAAC;CAC7B,IAAI,QAAQ;CACZ,IAAI,WAAW;CACf,IAAI,kBAAkB;CAEtB,KAAK,MAAM,MAAM,YAAY;EAC3B,IAAI,OAAO,OAAO,YAChB;EAGF,MAAM,MAAM,QAAQ,IAAI,IAAI,sBAAsB;EAElD,IAAI,QAAQ,QACV;EAGF,MAAM,aAAa,oBAAoB,GAAG;EAE1C,IAAI,CAAC,YAAY;GACf,KACE,qGACF;GAEA;EACF;EAEA,QAAQ;EACR,aAAa,WAAW,aAAa;EACrC,oBAAoB,WAAW,aAAa;EAE5C,KAAK,MAAM,UAAU,WAAW,SAO9B,IAAI,CANc,QAAQ,MAAM,aAC9B,OAAO,aAAa,YAAY,OAAO,WAAW,WAC9C,aAAa,SACb,SAAS,WAAW,OAAO,MAGpB,GACX,QAAQ,KAAK,MAAM;EAIvB,KAAK,MAAM,QAAQ,WAAW,WAC5B,IAAI,CAAC,UAAU,SAAS,IAAI,GAC1B,UAAU,KAAK,IAAI;CAGzB;CAEA,OAAO,QAAQ;EAAE;EAAS;EAAW,GAAI,kBAAkB,EAAE,SAAS,IAAI,CAAC;CAAG,IAAI;AACpF;;;;;AAMA,IAAa,kBAAb,MAA6B;;iBACsC,CAAC;2CAE7B,IAAI,IAAoB;;CAE7D,AAAO,gBAAgB,YAA0D;EAC/E,MAAM,eAA6C,WAAW,QAAQ,KAAK,WAAW;GACpF,IAAI,WAAW,UAAU;IACvB,KAAK,QAAQ,aAAa;KAAE,MAAM;KAAQ,QAAQ;KAAU,cAAc;IAAM;IAEhF,OAAO,EAAE,YAAY,CAAC,EAAE;GAC1B;GAIA,OAAO,GAFM,KAAK,aAAa,OAAO,MAEzB,IAAI,CAAC,EAAE;EACtB,CAAC;EACD,OAAO,WAAW,aAAa,QAAQ,CAAC,GAAG,cAAc,CAAC,CAAC,IAAI;CACjE;CAEA,AAAQ,aAAa,QAAwB;EAC3C,MAAM,WAAW,KAAK,kBAAkB,IAAI,MAAM;EAElD,IAAI,UACF,OAAO;EAIT,MAAM,OACJ,KAAK,kBAAkB,SAAS,IAC5B,eACA,cAAc,OAAO,QAAQ,oBAAoB,EAAE;EAEzD,KAAK,kBAAkB,IAAI,QAAQ,IAAI;EACvC,KAAK,QAAQ,QAAQ;GAAE,MAAM;GAAU,IAAI;GAAU,MAAM;EAAO;EAElE,OAAO;CACT;CAEA,AAAO,aAAsB;EAC3B,OAAO,OAAO,KAAK,KAAK,OAAO,CAAC,CAAC,SAAS;CAC5C;AACF"}

package/esm/openapi/types.d.mts

@@ -112,6 +112,8 @@ export type OpenApiRouteInput = Pick<Route, "method" | "path" | "handler"> & Par
  * Read structurally and validated; core never imports the auth package.
  */
 export type AuthDescriptor = {
+  /** Absent on legacy descriptors, which require authentication. */
+  required?: boolean;
   sources: ("header" | {
     cookie: string;
   })[];

package/esm/openapi/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/openapi/types.ts"],"mappings":";;;;;YAKY,gBAAgB;YAEhB;EACV;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;;YAGE;EACV;EACA,SAAS;IAAiB,QAAQ;;;YAGxB;EACV;EACA,UAAU;IAAiB,QAAQ;;;YAGzB,6BAA6B;YAE7B;EACV;EACA;EACA;EACA;EACA,aAAa;EACb,cAAc;EACd,WAAW,eAAe;EAC1B,WAAW;;YAGD;EACN;EAAc;EAAkB;;EAChC;EAAgB;EAAc;;YAExB;EACV,UAAU,eAAe;EACzB,kBAAkB,eAAe;;YAGvB;EACV;EACA;EACA;IAAQ;IAAe;IAAiB;;EACxC;IAAY;;EACZ;IAAS;;EACT,OAAO,eAAe,eAAe;EACrC,aAAa;;;;;;YAOH;EACV;EACA;EACA;EACA;;EAEA;;;;;;YAOU;EACV;IAAQ;IAAe;IAAiB;;;EAExC;;EAEA;;;;;;EAMA,uBAAuB;;EAEvB,qBAAqB;;YAGX;EACV,UAAU;EACV;;;YAIU,oBAAoB,KAAK,wCACnC,QACE,KACE;;;;;YASM;EACV;IAAuB;;EACvB;;YAGU,eAAe"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/openapi/types.ts"],"mappings":";;;;;YAKY,gBAAgB;YAEhB;EACV;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;;YAGE;EACV;EACA,SAAS;IAAiB,QAAQ;;;YAGxB;EACV;EACA,UAAU;IAAiB,QAAQ;;;YAGzB,6BAA6B;YAE7B;EACV;EACA;EACA;EACA;EACA,aAAa;EACb,cAAc;EACd,WAAW,eAAe;EAC1B,WAAW;;YAGD;EACN;EAAc;EAAkB;;EAChC;EAAgB;EAAc;;YAExB;EACV,UAAU,eAAe;EACzB,kBAAkB,eAAe;;YAGvB;EACV;EACA;EACA;IAAQ;IAAe;IAAiB;;EACxC;IAAY;;EACZ;IAAS;;EACT,OAAO,eAAe,eAAe;EACrC,aAAa;;;;;;YAOH;EACV;EACA;EACA;EACA;;EAEA;;;;;;YAOU;EACV;IAAQ;IAAe;IAAiB;;;EAExC;;EAEA;;;;;;EAMA,uBAAuB;;EAEvB,qBAAqB;;YAGX;EACV,UAAU;EACV;;;YAIU,oBAAoB,KAAK,wCACnC,QACE,KACE;;;;;YASM;;EAEV;EACA;IAAuB;;EACvB;;YAGU,eAAe"}

package/esm/production/build-budgets.d.mts

@@ -0,0 +1,46 @@
+//#region ../../packages/core/src/production/build-budgets.d.ts
+export type PageBudget = {
+  js?: string;
+  css?: string;
+};
+export type BuildBudgets = {
+  page?: PageBudget;
+  /** Route-path globs supporting *, ** and ?. Later matching entries win per field. */
+  pages?: Record<string, PageBudget>;
+  /** Defaults to error when budgets are configured. */
+  mode?: "error" | "warn";
+};
+export type BudgetPage = {
+  page: string;
+  source: string;
+  js: number;
+  css: number;
+  dynamic: {
+    js: number;
+    css: number;
+  };
+  files: string[];
+  modules: {
+    id: string;
+    bytes: number;
+  }[];
+  delta?: {
+    js: number;
+    css: number;
+  };
+};
+export type BudgetViolation = {
+  page: string;
+  type: "js" | "css";
+  budget: number;
+  actual: number;
+  modules: BudgetPage["modules"];
+};
+export type BuildBudgetReport = {
+  version: 1;
+  compression: "gzip";
+  pages: BudgetPage[];
+  violations: BudgetViolation[];
+};
+//#endregion
+//# sourceMappingURL=build-budgets.d.mts.map

package/esm/production/build-budgets.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-budgets.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/production/build-budgets.ts"],"mappings":";YAGY;EAAe;EAAa;;YAC5B;EACV,OAAO;;EAEP,QAAQ,eAAe;;EAEvB;;YAEU;EACV;EACA;EACA;EACA;EACA;IAAW;IAAY;;EACvB;EACA;IAAW;IAAY;;EACvB;IAAU;IAAY;;;YAEZ;EACV;EACA;EACA;EACA;EACA,SAAS;;YAEC;EACV;EACA;EACA,OAAO;EACP,YAAY"}

package/esm/production/build-budgets.mjs

@@ -0,0 +1,109 @@
+import path from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+
+//#region ../../packages/core/src/production/build-budgets.ts
+const BUILD_BUDGET_REPORT_FILE = "build-budgets.json";
+function parseBudgetSize(size) {
+	const match = /^(\d+(?:\.\d+)?)\s*(b|kb|mb)$/i.exec(size.trim());
+	if (!match) throw new Error(`Invalid build budget ${JSON.stringify(size)}: use bytes, kb or mb, e.g. "150kb".`);
+	const bytes = Number(match[1]) * ({
+		b: 1,
+		kb: 1024,
+		mb: 1048576
+	}[match[2]?.toLowerCase() ?? ""] ?? 0);
+	if (!Number.isFinite(bytes)) throw new Error(`Invalid build budget ${JSON.stringify(size)}.`);
+	return bytes;
+}
+function routeMatches(pattern, route) {
+	if ([
+		"[",
+		"]",
+		"{",
+		"}",
+		"(",
+		")",
+		"!",
+		"\\"
+	].some((token) => pattern.includes(token))) throw new Error(`Invalid build budget glob ${JSON.stringify(pattern)}: supported wildcards are *, ** and ?.`);
+	let expression = "^";
+	for (let i = 0; i < pattern.length; i++) {
+		const character = pattern[i];
+		if (character === "*" && pattern[i + 1] === "*") {
+			i++;
+			if (pattern[i + 1] === "/") {
+				expression += "(?:.*/)?";
+				i++;
+			} else expression += ".*";
+		} else if (character === "*") expression += "[^/]*";
+		else if (character === "?") expression += "[^/]";
+		else expression += character?.replace(/[.+^$|]/g, "\\$&") ?? "";
+	}
+	return new RegExp(`${expression}$`).test(route);
+}
+function evaluateBuildBudgets(pages, budgets, previous) {
+	if (budgets?.mode !== void 0 && budgets.mode !== "error" && budgets.mode !== "warn") throw new Error("build.budgets.mode must be \"error\" or \"warn\".");
+	for (const budget of [budgets?.page, ...Object.values(budgets?.pages ?? {})]) for (const size of Object.values(budget ?? {})) if (size !== void 0) parseBudgetSize(size);
+	for (const pattern of Object.keys(budgets?.pages ?? {})) routeMatches(pattern, "");
+	const violations = [];
+	return {
+		version: 1,
+		compression: "gzip",
+		pages: pages.map((page) => {
+			let limits = { ...budgets?.page };
+			for (const [pattern, override] of Object.entries(budgets?.pages ?? {})) if (routeMatches(pattern, page.page)) limits = {
+				...limits,
+				...override
+			};
+			for (const type of ["js", "css"]) {
+				const configured = limits[type];
+				if (configured === void 0) continue;
+				const budget = parseBudgetSize(configured);
+				if (page[type] > budget) violations.push({
+					page: page.page,
+					type,
+					budget,
+					actual: page[type],
+					modules: page.modules
+				});
+			}
+			const old = previous?.pages.find((entry) => entry.page === page.page && entry.source === page.source);
+			return {
+				...page,
+				delta: old ? {
+					js: page.js - old.js,
+					css: page.css - old.css
+				} : void 0
+			};
+		}).sort((a, b) => b.js + b.css - a.js - a.css || a.page.localeCompare(b.page)),
+		violations
+	};
+}
+async function readBuildBudgetReport(outdir) {
+	try {
+		const report = JSON.parse(await readFile(path.join(outdir, BUILD_BUDGET_REPORT_FILE), "utf8"));
+		if (!report || typeof report !== "object" || report.version !== 1 || report.compression !== "gzip" || !Array.isArray(report.pages)) return void 0;
+		return report;
+	} catch (error) {
+		if (error instanceof SyntaxError || error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+		throw error;
+	}
+}
+const kb = (bytes) => `${(bytes / 1024).toFixed(2)}kb`;
+const delta = (value) => value === void 0 ? "—" : `${value >= 0 ? "+" : ""}${kb(value)}`;
+function formatBuildBudgets(report) {
+	return [
+		"First-visit client assets (gzip); dynamic imports excluded from budgets",
+		"Page | JS | Δ JS | CSS | Δ CSS | Dynamic JS | Dynamic CSS | Largest modules (rendered bytes)",
+		...report.pages.map((page) => `${page.page} | ${kb(page.js)} | ${delta(page.delta?.js)} | ${kb(page.css)} | ${delta(page.delta?.css)} | ${kb(page.dynamic.js)} | ${kb(page.dynamic.css)} | ${page.modules.slice(0, 3).map((module) => `${module.id} (${module.bytes}b)`).join(", ")}`)
+	].join("\n");
+}
+function formatBudgetViolations(report) {
+	return report.violations.map((violation) => `Page ${violation.page}: ${violation.type.toUpperCase()} budget ${kb(violation.budget)}, actual ${kb(violation.actual)} (limit ${violation.budget}b, actual ${violation.actual}b). Biggest modules (rendered bytes): ${violation.modules.map((module) => `${module.id} (${module.bytes}b)`).join(", ") || "none"}`).join("\n");
+}
+async function writeBuildBudgetReport(outdir, report) {
+	await writeFile(path.join(outdir, BUILD_BUDGET_REPORT_FILE), `${JSON.stringify(report, null, 2)}\n`);
+}
+
+//#endregion
+export { BUILD_BUDGET_REPORT_FILE, evaluateBuildBudgets, formatBudgetViolations, formatBuildBudgets, parseBudgetSize, readBuildBudgetReport, writeBuildBudgetReport };
+//# sourceMappingURL=build-budgets.mjs.map

package/esm/production/build-budgets.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-budgets.mjs","names":[],"sources":["../../../../../../../../packages/core/src/production/build-budgets.ts"],"sourcesContent":["import { readFile, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\n\nexport type PageBudget = { js?: string; css?: string };\nexport type BuildBudgets = {\n  page?: PageBudget;\n  /** Route-path globs supporting *, ** and ?. Later matching entries win per field. */\n  pages?: Record<string, PageBudget>;\n  /** Defaults to error when budgets are configured. */\n  mode?: \"error\" | \"warn\";\n};\nexport type BudgetPage = {\n  page: string;\n  source: string;\n  js: number;\n  css: number;\n  dynamic: { js: number; css: number };\n  files: string[];\n  modules: { id: string; bytes: number }[];\n  delta?: { js: number; css: number };\n};\nexport type BudgetViolation = {\n  page: string;\n  type: \"js\" | \"css\";\n  budget: number;\n  actual: number;\n  modules: BudgetPage[\"modules\"];\n};\nexport type BuildBudgetReport = {\n  version: 1;\n  compression: \"gzip\";\n  pages: BudgetPage[];\n  violations: BudgetViolation[];\n};\nexport const BUILD_BUDGET_REPORT_FILE = \"build-budgets.json\";\n\nexport function parseBudgetSize(size: string): number {\n  const match = /^(\\d+(?:\\.\\d+)?)\\s*(b|kb|mb)$/i.exec(size.trim());\n  if (!match)\n    throw new Error(\n      `Invalid build budget ${JSON.stringify(size)}: use bytes, kb or mb, e.g. \"150kb\".`,\n    );\n  const units: Record<string, number> = { b: 1, kb: 1024, mb: 1024 * 1024 };\n  const bytes = Number(match[1]) * (units[match[2]?.toLowerCase() ?? \"\"] ?? 0);\n  if (!Number.isFinite(bytes)) throw new Error(`Invalid build budget ${JSON.stringify(size)}.`);\n  return bytes;\n}\n\nfunction routeMatches(pattern: string, route: string): boolean {\n  if ([\"[\", \"]\", \"{\", \"}\", \"(\", \")\", \"!\", \"\\\\\"].some((token) => pattern.includes(token))) {\n    throw new Error(\n      `Invalid build budget glob ${JSON.stringify(pattern)}: supported wildcards are *, ** and ?.`,\n    );\n  }\n  let expression = \"^\";\n  for (let i = 0; i < pattern.length; i++) {\n    const character = pattern[i];\n    if (character === \"*\" && pattern[i + 1] === \"*\") {\n      i++;\n      if (pattern[i + 1] === \"/\") {\n        expression += \"(?:.*/)?\";\n        i++;\n      } else expression += \".*\";\n    } else if (character === \"*\") expression += \"[^/]*\";\n    else if (character === \"?\") expression += \"[^/]\";\n    else expression += character?.replace(/[.+^$|]/g, \"\\\\$&\") ?? \"\";\n  }\n  return new RegExp(`${expression}$`).test(route);\n}\n\nexport function evaluateBuildBudgets(\n  pages: BudgetPage[],\n  budgets?: BuildBudgets,\n  previous?: BuildBudgetReport,\n): BuildBudgetReport {\n  if (budgets?.mode !== undefined && budgets.mode !== \"error\" && budgets.mode !== \"warn\") {\n    throw new Error('build.budgets.mode must be \"error\" or \"warn\".');\n  }\n  // Validate even overrides that do not match any current route.\n  for (const budget of [budgets?.page, ...Object.values(budgets?.pages ?? {})]) {\n    for (const size of Object.values(budget ?? {})) {\n      if (size !== undefined) parseBudgetSize(size);\n    }\n  }\n  for (const pattern of Object.keys(budgets?.pages ?? {})) routeMatches(pattern, \"\");\n  const violations: BudgetViolation[] = [];\n  const result = pages\n    .map((page) => {\n      let limits = { ...budgets?.page };\n      for (const [pattern, override] of Object.entries(budgets?.pages ?? {})) {\n        if (routeMatches(pattern, page.page)) limits = { ...limits, ...override };\n      }\n      for (const type of [\"js\", \"css\"] as const) {\n        const configured = limits[type];\n        if (configured === undefined) continue;\n        const budget = parseBudgetSize(configured);\n        if (page[type] > budget)\n          violations.push({\n            page: page.page,\n            type,\n            budget,\n            actual: page[type],\n            modules: page.modules,\n          });\n      }\n      const old = previous?.pages.find(\n        (entry) => entry.page === page.page && entry.source === page.source,\n      );\n      return {\n        ...page,\n        delta: old ? { js: page.js - old.js, css: page.css - old.css } : undefined,\n      };\n    })\n    .sort((a, b) => b.js + b.css - a.js - a.css || a.page.localeCompare(b.page));\n  return { version: 1, compression: \"gzip\", pages: result, violations };\n}\n\nexport async function readBuildBudgetReport(\n  outdir: string,\n): Promise<BuildBudgetReport | undefined> {\n  try {\n    const report: BuildBudgetReport = JSON.parse(\n      await readFile(path.join(outdir, BUILD_BUDGET_REPORT_FILE), \"utf8\"),\n    );\n    if (\n      !report ||\n      typeof report !== \"object\" ||\n      report.version !== 1 ||\n      report.compression !== \"gzip\" ||\n      !Array.isArray(report.pages)\n    )\n      return undefined;\n    return report;\n  } catch (error) {\n    if (\n      error instanceof SyntaxError ||\n      (error instanceof Error && \"code\" in error && error.code === \"ENOENT\")\n    )\n      return undefined;\n    throw error;\n  }\n}\n\nconst kb = (bytes: number) => `${(bytes / 1024).toFixed(2)}kb`;\nconst delta = (value: number | undefined) =>\n  value === undefined ? \"—\" : `${value >= 0 ? \"+\" : \"\"}${kb(value)}`;\nexport function formatBuildBudgets(report: BuildBudgetReport): string {\n  return [\n    \"First-visit client assets (gzip); dynamic imports excluded from budgets\",\n    \"Page | JS | Δ JS | CSS | Δ CSS | Dynamic JS | Dynamic CSS | Largest modules (rendered bytes)\",\n    ...report.pages.map(\n      (page) =>\n        `${page.page} | ${kb(page.js)} | ${delta(page.delta?.js)} | ${kb(page.css)} | ${delta(page.delta?.css)} | ${kb(page.dynamic.js)} | ${kb(page.dynamic.css)} | ${page.modules\n          .slice(0, 3)\n          .map((module) => `${module.id} (${module.bytes}b)`)\n          .join(\", \")}`,\n    ),\n  ].join(\"\\n\");\n}\nexport function formatBudgetViolations(report: BuildBudgetReport): string {\n  return report.violations\n    .map(\n      (violation) =>\n        `Page ${violation.page}: ${violation.type.toUpperCase()} budget ${kb(violation.budget)}, actual ${kb(violation.actual)} (limit ${violation.budget}b, actual ${violation.actual}b). Biggest modules (rendered bytes): ${violation.modules.map((module) => `${module.id} (${module.bytes}b)`).join(\", \") || \"none\"}`,\n    )\n    .join(\"\\n\");\n}\nexport async function writeBuildBudgetReport(\n  outdir: string,\n  report: BuildBudgetReport,\n): Promise<void> {\n  await writeFile(\n    path.join(outdir, BUILD_BUDGET_REPORT_FILE),\n    `${JSON.stringify(report, null, 2)}\\n`,\n  );\n}\n"],"mappings":";;;;AAkCA,MAAa,2BAA2B;AAExC,SAAgB,gBAAgB,MAAsB;CACpD,MAAM,QAAQ,iCAAiC,KAAK,KAAK,KAAK,CAAC;CAC/D,IAAI,CAAC,OACH,MAAM,IAAI,MACR,wBAAwB,KAAK,UAAU,IAAI,EAAE,qCAC/C;CAEF,MAAM,QAAQ,OAAO,MAAM,EAAE,KAAK;EADM,GAAG;EAAG,IAAI;EAAM,IAAI;CACtB,EAAE,MAAM,EAAE,EAAE,YAAY,KAAK,OAAO;CAC1E,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,MAAM,IAAI,MAAM,wBAAwB,KAAK,UAAU,IAAI,EAAE,EAAE;CAC5F,OAAO;AACT;AAEA,SAAS,aAAa,SAAiB,OAAwB;CAC7D,IAAI;EAAC;EAAK;EAAK;EAAK;EAAK;EAAK;EAAK;EAAK;CAAI,CAAC,CAAC,MAAM,UAAU,QAAQ,SAAS,KAAK,CAAC,GACnF,MAAM,IAAI,MACR,6BAA6B,KAAK,UAAU,OAAO,EAAE,uCACvD;CAEF,IAAI,aAAa;CACjB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;EACvC,MAAM,YAAY,QAAQ;EAC1B,IAAI,cAAc,OAAO,QAAQ,IAAI,OAAO,KAAK;GAC/C;GACA,IAAI,QAAQ,IAAI,OAAO,KAAK;IAC1B,cAAc;IACd;GACF,OAAO,cAAc;EACvB,OAAO,IAAI,cAAc,KAAK,cAAc;OACvC,IAAI,cAAc,KAAK,cAAc;OACrC,cAAc,WAAW,QAAQ,YAAY,MAAM,KAAK;CAC/D;CACA,OAAO,IAAI,OAAO,GAAG,WAAW,EAAE,CAAC,CAAC,KAAK,KAAK;AAChD;AAEA,SAAgB,qBACd,OACA,SACA,UACmB;CACnB,IAAI,SAAS,SAAS,UAAa,QAAQ,SAAS,WAAW,QAAQ,SAAS,QAC9E,MAAM,IAAI,MAAM,mDAA+C;CAGjE,KAAK,MAAM,UAAU,CAAC,SAAS,MAAM,GAAG,OAAO,OAAO,SAAS,SAAS,CAAC,CAAC,CAAC,GACzE,KAAK,MAAM,QAAQ,OAAO,OAAO,UAAU,CAAC,CAAC,GAC3C,IAAI,SAAS,QAAW,gBAAgB,IAAI;CAGhD,KAAK,MAAM,WAAW,OAAO,KAAK,SAAS,SAAS,CAAC,CAAC,GAAG,aAAa,SAAS,EAAE;CACjF,MAAM,aAAgC,CAAC;CA6BvC,OAAO;EAAE,SAAS;EAAG,aAAa;EAAQ,OA5B3B,MACZ,KAAK,SAAS;GACb,IAAI,SAAS,EAAE,GAAG,SAAS,KAAK;GAChC,KAAK,MAAM,CAAC,SAAS,aAAa,OAAO,QAAQ,SAAS,SAAS,CAAC,CAAC,GACnE,IAAI,aAAa,SAAS,KAAK,IAAI,GAAG,SAAS;IAAE,GAAG;IAAQ,GAAG;GAAS;GAE1E,KAAK,MAAM,QAAQ,CAAC,MAAM,KAAK,GAAY;IACzC,MAAM,aAAa,OAAO;IAC1B,IAAI,eAAe,QAAW;IAC9B,MAAM,SAAS,gBAAgB,UAAU;IACzC,IAAI,KAAK,QAAQ,QACf,WAAW,KAAK;KACd,MAAM,KAAK;KACX;KACA;KACA,QAAQ,KAAK;KACb,SAAS,KAAK;IAChB,CAAC;GACL;GACA,MAAM,MAAM,UAAU,MAAM,MACzB,UAAU,MAAM,SAAS,KAAK,QAAQ,MAAM,WAAW,KAAK,MAC/D;GACA,OAAO;IACL,GAAG;IACH,OAAO,MAAM;KAAE,IAAI,KAAK,KAAK,IAAI;KAAI,KAAK,KAAK,MAAM,IAAI;IAAI,IAAI;GACnE;EACF,CAAC,CAAC,CACD,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,IAAI,CACtB;EAAG;CAAW;AACtE;AAEA,eAAsB,sBACpB,QACwC;CACxC,IAAI;EACF,MAAM,SAA4B,KAAK,MACrC,MAAM,SAAS,KAAK,KAAK,QAAQ,wBAAwB,GAAG,MAAM,CACpE;EACA,IACE,CAAC,UACD,OAAO,WAAW,YAClB,OAAO,YAAY,KACnB,OAAO,gBAAgB,UACvB,CAAC,MAAM,QAAQ,OAAO,KAAK,GAE3B,OAAO;EACT,OAAO;CACT,SAAS,OAAO;EACd,IACE,iBAAiB,eAChB,iBAAiB,SAAS,UAAU,SAAS,MAAM,SAAS,UAE7D,OAAO;EACT,MAAM;CACR;AACF;AAEA,MAAM,MAAM,UAAkB,IAAI,QAAQ,KAAI,CAAE,QAAQ,CAAC,EAAE;AAC3D,MAAM,SAAS,UACb,UAAU,SAAY,MAAM,GAAG,SAAS,IAAI,MAAM,KAAK,GAAG,KAAK;AACjE,SAAgB,mBAAmB,QAAmC;CACpE,OAAO;EACL;EACA;EACA,GAAG,OAAO,MAAM,KACb,SACC,GAAG,KAAK,KAAK,KAAK,GAAG,KAAK,EAAE,EAAE,KAAK,MAAM,KAAK,OAAO,EAAE,EAAE,KAAK,GAAG,KAAK,GAAG,EAAE,KAAK,MAAM,KAAK,OAAO,GAAG,EAAE,KAAK,GAAG,KAAK,QAAQ,EAAE,EAAE,KAAK,GAAG,KAAK,QAAQ,GAAG,EAAE,KAAK,KAAK,QACjK,MAAM,GAAG,CAAC,CAAC,CACX,KAAK,WAAW,GAAG,OAAO,GAAG,IAAI,OAAO,MAAM,GAAG,CAAC,CAClD,KAAK,IAAI,GAChB;CACF,CAAC,CAAC,KAAK,IAAI;AACb;AACA,SAAgB,uBAAuB,QAAmC;CACxE,OAAO,OAAO,WACX,KACE,cACC,QAAQ,UAAU,KAAK,IAAI,UAAU,KAAK,YAAY,EAAE,UAAU,GAAG,UAAU,MAAM,EAAE,WAAW,GAAG,UAAU,MAAM,EAAE,UAAU,UAAU,OAAO,YAAY,UAAU,OAAO,wCAAwC,UAAU,QAAQ,KAAK,WAAW,GAAG,OAAO,GAAG,IAAI,OAAO,MAAM,GAAG,CAAC,CAAC,KAAK,IAAI,KAAK,QAC9S,CAAC,CACA,KAAK,IAAI;AACd;AACA,eAAsB,uBACpB,QACA,QACe;CACf,MAAM,UACJ,KAAK,KAAK,QAAQ,wBAAwB,GAC1C,GAAG,KAAK,UAAU,QAAQ,MAAM,CAAC,EAAE,GACrC;AACF"}

package/esm/production/production-builder.mjs

@@ -3,9 +3,10 @@ import "../utils/index.mjs";
 import { assertNoReservedConnectorNames } from "../connectors/assert-no-reserved-connector-names.mjs";
 import { assertUniqueConnectorNames } from "../connectors/assert-unique-connector-names.mjs";
 import { warlockConfigManager } from "../warlock-config/warlock-config.manager.mjs";
-import { tsconfigManager } from "../dev-server/tsconfig-manager.mjs";
 import { isConfigFile, isEventFile, isLocaleFile, isMainFile, isRouteFile, isWorkerFile } from "../dev-server/special-file-patterns.mjs";
+import { tsconfigManager } from "../dev-server/tsconfig-manager.mjs";
 import { configKeyFromPath } from "../config/config-key-from-path.mjs";
+import { evaluateBuildBudgets, formatBudgetViolations, formatBuildBudgets, readBuildBudgetReport, writeBuildBudgetReport } from "./build-budgets.mjs";
 import { assertGeneratedImportsAreDeclared } from "./assert-generated-imports.mjs";
 import { bundleFrameworkDependencies } from "./bundle-framework-dependencies.mjs";
 import { dedupe, runEmitContributions, runGenerateContributions } from "./build-contributions.mjs";
@@ -124,6 +125,7 @@ var ProductionBuilder = class {
 		assertEsbuildBinaryIsLinked();
 		await this.initializeOptions();
 		const finalOutDir = this.options.outdir;
+		const previousBudgetReport = await readBuildBudgetReport(finalOutDir);
 		const tempOutDir = createTempOutputDir(finalOutDir);
 		let staged;
 		try {
@@ -135,6 +137,15 @@ var ProductionBuilder = class {
 			await this.bundle(tempOutDir);
 			staged = await stageDistAsync(tempOutDir, finalOutDir);
 			await runEmitContributions(this.connectors, this.buildContext());
+			const clientReport = await readBuildBudgetReport(finalOutDir);
+			this.budgetReport = evaluateBuildBudgets(clientReport?.pages ?? [], this.options.budgets, previousBudgetReport);
+			if (clientReport) await writeBuildBudgetReport(finalOutDir, this.budgetReport);
+			if (this.budgetReport.pages.length > 0) console.log(formatBuildBudgets(this.budgetReport));
+			if (this.budgetReport.violations.length > 0) {
+				const message = formatBudgetViolations(this.budgetReport);
+				if (this.options.budgets?.mode !== "warn") throw new Error(message);
+				console.warn(message);
+			}
 			await writeDistBuildManifestAsync(finalOutDir);
 			await commitDistAsync(staged);
 		} catch (error) {
@@ -476,6 +487,7 @@ bootstrap();
 		delete esbuildOptions.esmShim;
 		delete esbuildOptions.banner;
 		delete esbuildOptions.routeRegistrationTimeoutMs;
+		delete esbuildOptions.budgets;
 		await ensureDirectoryAsync(writeOutDir);
 		const alias = this.buildAliasMapFromTsconfig();
 		const perEdgeExternals = !singleBundle && esbuildOptions.packages === void 0;