@warlock.js/core 5.35.0 → 5.37.0

package/esm/index.mjs

@@ -73,7 +73,7 @@ import "./image/index.mjs";
 import { UploadedFile } from "./http/uploaded-file.mjs";
 import { URL_CREDENTIAL_PARAMS, buildRequestLogSnapshot, redactQueryCredentials, redactUrlCredentials, resolveRequestLoggingOptions } from "./http/request-log-snapshot.mjs";
 import { Request } from "./http/request.mjs";
-import { AUTH_GUARD_MARKER, isAuthGuardMiddleware, isUnguardedMutatingRoute, markAuthGuard, reportUnguardedMutatingRoutes, resetUnguardedRouteReports } from "./router/unguarded-route-diagnostics.mjs";
+import { AUTH_GUARD_MARKER, isAuthGuardMiddleware, isRequiredGuardRoute, isUnguardedMutatingRoute, markAuthGuard, reportUnguardedMutatingRoutes, resetUnguardedRouteReports } from "./router/unguarded-route-diagnostics.mjs";
 import { Router, router } from "./router/router.mjs";
 import "./router/index.mjs";
 import { registerHttpPlugins, resolvePublicRoot } from "./http/plugins.mjs";
@@ -169,6 +169,8 @@ import "./secrets/index.mjs";
 import { ERROR_CODES, ERROR_CODES_DOCS_URL, errorCodeDocsUrl, errorCodeOf, explainErrorCode, isWarlockErrorCode } from "./errors/error-codes.mjs";
 import { LocaleDictionaryError, parseLocaleDictionary } from "./localization/parse-locale-dictionary.mjs";
 import { registerGroupedTranslationKeys, registerLocaleDictionary, unregisterLocaleDictionary } from "./localization/register-locale-dictionary.mjs";
+import { EMPTY_TRANSLATION_USAGE, isTranslationKeyUsed, mergeTranslationUsage, readTranslationDeclarations, scanTranslationSource, translationDeclarationUsage, usageOf } from "./localization/translation-usage.mjs";
+import { analyzePageTranslationUsage, analyzeTranslationGraph, readSourceFile, resolveSourceImport } from "./localization/translation-usage-graph.mjs";
 import "./localization/index.mjs";
 import { exampleFromSchema } from "./openapi/postman/example-from-schema.mjs";
 import { DEFAULT_POSTMAN_BASE_URL, POSTMAN_COLLECTION_SCHEMA, openApiToPostmanCollection } from "./openapi/postman/openapi-to-postman-collection.mjs";
@@ -204,4 +206,4 @@ import { colors } from "@mongez/copper";
 
 export * from "@mongez/localization"
 
-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 };
+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, EMPTY_TRANSLATION_USAGE, 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, analyzePageTranslationUsage, analyzeTranslationGraph, 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, isRequiredGuardRoute, isSafeRedirect, isTestMode, isTracingEnabled, isTranslationKeyUsed, isUnguardedMutatingRoute, isUnknownTsExtensionError, isUnresolvedConfigImportError, isUnsupportedTypeStrippingError, isValidIdempotencyKey, isWarlockErrorCode, listEndpoint, listPositionalHandlerSuspects, loadS3, logResponse, logsPath, looksLikePositionalHandler, mailEvents, markAuthGuard, matchesDerivedRouteName, matchesIfMatch, matchesIfNoneMatch, measure, mergeCspDirectives, mergeTranslationUsage, middleware, nodeOnlyCommandError, normalizeOrigin, normalizeRequestPath, normalizeRoutePath, notifyHttpServerRebuilt, nullable, onHttpServerRebuilt, openApiToPostmanCollection, originOf, ownOrigin, parseEntityTag, parseEntityTagList, parseLocaleDictionary, parseRoles, parseSites, parseSize, parseTraceparentTraceId, paths, preflightConfiguredHttpPort, promiseAllObject, publicPath, publicUrl, purgeImageVariants, readSourceFile, readTranslationDeclarations, 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, resolveSourceImport, resolveTracingConfig, resolveWithinRoot, rootPath, routeNameMethodSuffix, router, runDefaultCsrfGuard, runPipeline, safeFetchToBuffer, safeRedirect, sanitizePath, scanTranslationSource, 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, translationDeclarationUsage, uniqueExceptCurrentIdRule, uniqueExceptCurrentUserRule, unregisterLocaleDictionary, unverifiedBuildRuntimeNotice, uploadedFileController, uploadedFileMetadataSchema, uploadsConfig, uploadsPath, uploadsUrl, url, usageOf, useCase, useComputedModel, useComputedSlug, useCurrentUser, useHashedPassword, useRequest, useRequestStore, validateConfigValue, validateCspConfigAtBoot, validateCspDirectives, verifyMailer, verifyPassword, warlockConfigManager, warlockPath, wasMailSentTo, wasMailSentWithSubject, weakEntityTagMatch, wrapResponseInDataKey };

package/esm/localization/index.mjs

@@ -1,4 +1,6 @@
 import { LocaleDictionaryError, parseLocaleDictionary } from "./parse-locale-dictionary.mjs";
 import { registerGroupedTranslationKeys, registerLocaleDictionary, unregisterLocaleDictionary } from "./register-locale-dictionary.mjs";
+import { EMPTY_TRANSLATION_USAGE, isTranslationKeyUsed, mergeTranslationUsage, readTranslationDeclarations, scanTranslationSource, translationDeclarationUsage, usageOf } from "./translation-usage.mjs";
+import { analyzePageTranslationUsage, analyzeTranslationGraph, readSourceFile, resolveSourceImport } from "./translation-usage-graph.mjs";
 
-export { LocaleDictionaryError, parseLocaleDictionary, registerGroupedTranslationKeys, registerLocaleDictionary, unregisterLocaleDictionary };
+export { EMPTY_TRANSLATION_USAGE, LocaleDictionaryError, analyzePageTranslationUsage, analyzeTranslationGraph, isTranslationKeyUsed, mergeTranslationUsage, parseLocaleDictionary, readSourceFile, readTranslationDeclarations, registerGroupedTranslationKeys, registerLocaleDictionary, resolveSourceImport, scanTranslationSource, translationDeclarationUsage, unregisterLocaleDictionary, usageOf };

package/esm/localization/translation-usage-graph.d.mts

@@ -0,0 +1,49 @@
+import { TranslationUsage } from "./translation-usage.mjs";
+//#region ../../packages/core/src/localization/translation-usage-graph.d.ts
+export type TranslationGraphInput = {
+  /** The client entry files a render can execute: the page, its layouts, the root and error pages. */
+  readonly entries: readonly string[];
+  /** Setup files whose `config.translations` declare keys static analysis cannot see. */
+  readonly setupFiles?: readonly string[];
+  /** Source text of a file, or `undefined` when it cannot be read. */
+  readonly readSource: (file: string) => string | undefined;
+  /** Resolves a specifier imported by `importer` to a project file, or `undefined` for a package. */
+  readonly resolveImport: (specifier: string, importer: string) => string | undefined;
+};
+export type TranslationGraphResult = {
+  /** The union of every reachable file's usage and the declared keys. */
+  readonly usage: TranslationUsage;
+  /** Every project file the walk read, so a caller can tell when the answer may have changed. */
+  readonly files: readonly string[];
+};
+/**
+ * Walk the client module graph from `entries` and union what every reachable
+ * file can look up.
+ *
+ * The walk follows value imports, re-exports and dynamic `import()` into
+ * project files only. A package is not followed: packages do not carry
+ * application translation keys. Fail closed: a reachable file that cannot be
+ * read or parsed makes the whole graph dynamic, so the caller ships everything
+ * rather than a set that might be missing a key.
+ */
+export declare function analyzeTranslationGraph(input: TranslationGraphInput): TranslationGraphResult;
+/**
+ * Resolve a specifier for the translation graph: relative paths, and the
+ * `web/` and `app/` conventions under the source root. Anything else is a
+ * package and resolves to `undefined`.
+ */
+export declare function resolveSourceImport(specifier: string, importer: string, appSrcRoot: string): string | undefined;
+/** Read a file as UTF-8, or `undefined` when it is missing or unreadable. */
+export declare function readSourceFile(file: string): string | undefined;
+/**
+ * Analyze a page's client graph against the filesystem: the convenience the
+ * build and the development server both use. `appSrcRoot` is the application's
+ * `src` directory, which the `web/` and `app/` specifiers resolve against.
+ */
+export declare function analyzePageTranslationUsage(input: {
+  readonly appSrcRoot: string;
+  readonly entries: readonly string[];
+  readonly setupFiles?: readonly string[];
+}): TranslationGraphResult;
+//#endregion
+//# sourceMappingURL=translation-usage-graph.d.mts.map

package/esm/localization/translation-usage-graph.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-usage-graph.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/localization/translation-usage-graph.ts"],"mappings":";;YAkBY;;WAED;;WAEA;;WAEA,aAAa;;WAEb,gBAAgB,mBAAmB;;YAGlC;;WAED,OAAO;;WAEP;;;;;;;;;;;;wBAaK,wBAAwB,OAAO,wBAAwB;;;;;;wBAqEvD,oBACd,mBACA,kBACA;;wBAiCc,eAAe;;;;;;wBAaf,4BAA4B;WACjC;WACA;WACA;IACP"}

package/esm/localization/translation-usage-graph.mjs

@@ -0,0 +1,128 @@
+import { EMPTY_TRANSLATION_USAGE, mergeTranslationUsage, readTranslationDeclarations, scanTranslationSource, translationDeclarationUsage, usageOf } from "./translation-usage.mjs";
+import path from "node:path";
+import fsSync from "node:fs";
+
+//#region ../../packages/core/src/localization/translation-usage-graph.ts
+/** Source files the walk reads. */
+const CODE_FILE = /\.[cm]?[jt]sx?$/;
+/** Extensions tried, in order, for an extension-less specifier. */
+const SOURCE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".mts",
+	".js",
+	".jsx",
+	".mjs"
+];
+/**
+* Walk the client module graph from `entries` and union what every reachable
+* file can look up.
+*
+* The walk follows value imports, re-exports and dynamic `import()` into
+* project files only. A package is not followed: packages do not carry
+* application translation keys. Fail closed: a reachable file that cannot be
+* read or parsed makes the whole graph dynamic, so the caller ships everything
+* rather than a set that might be missing a key.
+*/
+function analyzeTranslationGraph(input) {
+	const seen = /* @__PURE__ */ new Set();
+	const files = [];
+	const usages = [];
+	const queue = [...input.entries];
+	for (const setupFile of input.setupFiles ?? []) {
+		files.push(setupFile);
+		usages.push(readDeclarations(input, setupFile));
+	}
+	for (let file = queue.pop(); file !== void 0; file = queue.pop()) {
+		if (seen.has(file)) continue;
+		seen.add(file);
+		files.push(file);
+		const text = input.readSource(file);
+		if (text === void 0) {
+			usages.push(unreadable(file, "the file could not be read"));
+			continue;
+		}
+		try {
+			const scan = scanTranslationSource(file, text);
+			usages.push(scan.usage);
+			for (const specifier of scan.imports) {
+				const resolved = input.resolveImport(specifier, file);
+				if (resolved !== void 0 && !seen.has(resolved)) queue.push(resolved);
+			}
+		} catch (error) {
+			usages.push(unreadable(file, `the file could not be parsed (${error instanceof Error ? error.message : String(error)})`));
+		}
+	}
+	return {
+		usage: mergeTranslationUsage(usages),
+		files
+	};
+}
+function readDeclarations(input, setupFile) {
+	const text = input.readSource(setupFile);
+	if (text === void 0) return unreadable(setupFile, "the setup file could not be read");
+	const entries = readTranslationDeclarations(setupFile, text);
+	if (entries === void 0) return EMPTY_TRANSLATION_USAGE;
+	return mergeTranslationUsage(entries.map((entry) => translationDeclarationUsage(entry, setupFile)));
+}
+/** A dynamic usage that names the file which forced it. */
+function unreadable(file, reason) {
+	return usageOf({
+		dynamic: true,
+		dynamicSites: [{
+			file,
+			line: 1,
+			column: 1,
+			text: `<${reason}>`
+		}]
+	});
+}
+/**
+* Resolve a specifier for the translation graph: relative paths, and the
+* `web/` and `app/` conventions under the source root. Anything else is a
+* package and resolves to `undefined`.
+*/
+function resolveSourceImport(specifier, importer, appSrcRoot) {
+	let base;
+	if (specifier.startsWith(".")) base = path.resolve(path.dirname(importer), specifier);
+	else if (specifier.startsWith("web/") || specifier.startsWith("app/")) base = path.join(appSrcRoot, specifier);
+	else return;
+	const candidates = [
+		base,
+		...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`),
+		...SOURCE_EXTENSIONS.map((extension) => path.join(base, `index${extension}`))
+	];
+	if (/\.jsx?$/.test(base)) {
+		const stripped = base.replace(/\.jsx?$/, "");
+		candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${stripped}${extension}`));
+	}
+	return candidates.find((candidate) => CODE_FILE.test(candidate) && isFile(candidate));
+}
+function isFile(candidate) {
+	return fsSync.statSync(candidate, { throwIfNoEntry: false })?.isFile() === true;
+}
+/** Read a file as UTF-8, or `undefined` when it is missing or unreadable. */
+function readSourceFile(file) {
+	try {
+		return fsSync.readFileSync(file, "utf8");
+	} catch {
+		return;
+	}
+}
+/**
+* Analyze a page's client graph against the filesystem: the convenience the
+* build and the development server both use. `appSrcRoot` is the application's
+* `src` directory, which the `web/` and `app/` specifiers resolve against.
+*/
+function analyzePageTranslationUsage(input) {
+	return analyzeTranslationGraph({
+		entries: input.entries,
+		setupFiles: input.setupFiles,
+		readSource: readSourceFile,
+		resolveImport: (specifier, importer) => resolveSourceImport(specifier, importer, input.appSrcRoot)
+	});
+}
+
+//#endregion
+export { analyzePageTranslationUsage, analyzeTranslationGraph, readSourceFile, resolveSourceImport };
+//# sourceMappingURL=translation-usage-graph.mjs.map

package/esm/localization/translation-usage-graph.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-usage-graph.mjs","names":["fs"],"sources":["../../../../../../../../packages/core/src/localization/translation-usage-graph.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport {\n  EMPTY_TRANSLATION_USAGE,\n  mergeTranslationUsage,\n  readTranslationDeclarations,\n  scanTranslationSource,\n  translationDeclarationUsage,\n  usageOf,\n  type TranslationUsage,\n} from \"./translation-usage\";\n\n/** Source files the walk reads. */\nconst CODE_FILE = /\\.[cm]?[jt]sx?$/;\n\n/** Extensions tried, in order, for an extension-less specifier. */\nconst SOURCE_EXTENSIONS = [\".ts\", \".tsx\", \".mts\", \".js\", \".jsx\", \".mjs\"];\n\nexport type TranslationGraphInput = {\n  /** The client entry files a render can execute: the page, its layouts, the root and error pages. */\n  readonly entries: readonly string[];\n  /** Setup files whose `config.translations` declare keys static analysis cannot see. */\n  readonly setupFiles?: readonly string[];\n  /** Source text of a file, or `undefined` when it cannot be read. */\n  readonly readSource: (file: string) => string | undefined;\n  /** Resolves a specifier imported by `importer` to a project file, or `undefined` for a package. */\n  readonly resolveImport: (specifier: string, importer: string) => string | undefined;\n};\n\nexport type TranslationGraphResult = {\n  /** The union of every reachable file's usage and the declared keys. */\n  readonly usage: TranslationUsage;\n  /** Every project file the walk read, so a caller can tell when the answer may have changed. */\n  readonly files: readonly string[];\n};\n\n/**\n * Walk the client module graph from `entries` and union what every reachable\n * file can look up.\n *\n * The walk follows value imports, re-exports and dynamic `import()` into\n * project files only. A package is not followed: packages do not carry\n * application translation keys. Fail closed: a reachable file that cannot be\n * read or parsed makes the whole graph dynamic, so the caller ships everything\n * rather than a set that might be missing a key.\n */\nexport function analyzeTranslationGraph(input: TranslationGraphInput): TranslationGraphResult {\n  const seen = new Set<string>();\n  const files: string[] = [];\n  const usages: TranslationUsage[] = [];\n  const queue = [...input.entries];\n\n  for (const setupFile of input.setupFiles ?? []) {\n    files.push(setupFile);\n    usages.push(readDeclarations(input, setupFile));\n  }\n\n  for (let file = queue.pop(); file !== undefined; file = queue.pop()) {\n    if (seen.has(file)) continue;\n    seen.add(file);\n    files.push(file);\n\n    const text = input.readSource(file);\n\n    if (text === undefined) {\n      usages.push(unreadable(file, \"the file could not be read\"));\n      continue;\n    }\n\n    try {\n      const scan = scanTranslationSource(file, text);\n      usages.push(scan.usage);\n\n      for (const specifier of scan.imports) {\n        const resolved = input.resolveImport(specifier, file);\n        if (resolved !== undefined && !seen.has(resolved)) queue.push(resolved);\n      }\n    } catch (error) {\n      usages.push(\n        unreadable(\n          file,\n          `the file could not be parsed (${error instanceof Error ? error.message : String(error)})`,\n        ),\n      );\n    }\n  }\n\n  return { usage: mergeTranslationUsage(usages), files };\n}\n\nfunction readDeclarations(input: TranslationGraphInput, setupFile: string): TranslationUsage {\n  const text = input.readSource(setupFile);\n  if (text === undefined) return unreadable(setupFile, \"the setup file could not be read\");\n\n  const entries = readTranslationDeclarations(setupFile, text);\n  if (entries === undefined) return EMPTY_TRANSLATION_USAGE;\n\n  return mergeTranslationUsage(\n    entries.map((entry) => translationDeclarationUsage(entry, setupFile)),\n  );\n}\n\n/** A dynamic usage that names the file which forced it. */\nfunction unreadable(file: string, reason: string): TranslationUsage {\n  return usageOf({\n    dynamic: true,\n    dynamicSites: [{ file, line: 1, column: 1, text: `<${reason}>` }],\n  });\n}\n\n/**\n * Resolve a specifier for the translation graph: relative paths, and the\n * `web/` and `app/` conventions under the source root. Anything else is a\n * package and resolves to `undefined`.\n */\nexport function resolveSourceImport(\n  specifier: string,\n  importer: string,\n  appSrcRoot: string,\n): string | undefined {\n  let base: string;\n\n  if (specifier.startsWith(\".\")) {\n    base = path.resolve(path.dirname(importer), specifier);\n  } else if (specifier.startsWith(\"web/\") || specifier.startsWith(\"app/\")) {\n    base = path.join(appSrcRoot, specifier);\n  } else {\n    return undefined;\n  }\n\n  const candidates = [\n    base,\n    ...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`),\n    ...SOURCE_EXTENSIONS.map((extension) => path.join(base, `index${extension}`)),\n  ];\n\n  // TypeScript sources imported with their emitted `.js` extension.\n  if (/\\.jsx?$/.test(base)) {\n    const stripped = base.replace(/\\.jsx?$/, \"\");\n    candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${stripped}${extension}`));\n  }\n\n  // Only code is walked: a JSON, CSS or asset import carries no translation lookup.\n  return candidates.find((candidate) => CODE_FILE.test(candidate) && isFile(candidate));\n}\n\nfunction isFile(candidate: string): boolean {\n  return fs.statSync(candidate, { throwIfNoEntry: false })?.isFile() === true;\n}\n\n/** Read a file as UTF-8, or `undefined` when it is missing or unreadable. */\nexport function readSourceFile(file: string): string | undefined {\n  try {\n    return fs.readFileSync(file, \"utf8\");\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Analyze a page's client graph against the filesystem: the convenience the\n * build and the development server both use. `appSrcRoot` is the application's\n * `src` directory, which the `web/` and `app/` specifiers resolve against.\n */\nexport function analyzePageTranslationUsage(input: {\n  readonly appSrcRoot: string;\n  readonly entries: readonly string[];\n  readonly setupFiles?: readonly string[];\n}): TranslationGraphResult {\n  return analyzeTranslationGraph({\n    entries: input.entries,\n    setupFiles: input.setupFiles,\n    readSource: readSourceFile,\n    resolveImport: (specifier, importer) =>\n      resolveSourceImport(specifier, importer, input.appSrcRoot),\n  });\n}\n"],"mappings":"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"}

package/esm/localization/translation-usage.d.mts

@@ -0,0 +1,85 @@
+//#region ../../packages/core/src/localization/translation-usage.d.ts
+/**
+ * What one page (or one module) can look up in the translation table, derived
+ * from static source. Consumers decide what to ship; this type only says which
+ * keys a client render may ask for.
+ *
+ * - `keys` are exact keys. A key also delivers its whole subtree, so a declared
+ *   group (`"members"`) and a literal leaf (`"members.title"`) use one matching
+ *   rule.
+ * - `prefixes` come from template keys with a static prefix
+ *   (`` trans(`statuses.${status}`) `` gives `"statuses."`). Every key that
+ *   starts with one is reachable.
+ * - `dynamic` is set when a lookup key cannot be known before render. The
+ *   consumer must then assume every key is reachable.
+ */
+export type TranslationUsage = {
+  readonly keys: readonly string[];
+  readonly prefixes: readonly string[];
+  /**
+   * Key-shaped string literals written anywhere in the walked modules, outside
+   * a recognized lookup (a helper's argument, a constant, an object that maps to
+   * keys, a prop). A literal counts as used when it equals an existing key,
+   * names a group or subtree, or is the base of plural variants
+   * (`"cart.items"` reaches `"cart.items_one"` and `"cart.items_other"`).
+   */
+  readonly literals: readonly string[];
+  /** The static heads of template literals with substitutions, which reach every key that starts with one. */
+  readonly literalPrefixes: readonly string[];
+  readonly dynamic: boolean;
+  /** Where each unresolvable lookup was written, for diagnostics. */
+  readonly dynamicSites: readonly TranslationDynamicSite[];
+};
+export type TranslationDynamicSite = {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+  /** The source text of the lookup's key argument, as written. */
+  readonly text: string;
+};
+/** What one source file contributes: its own usage plus the modules it loads at run time. */
+export type TranslationSourceScan = {
+  readonly usage: TranslationUsage;
+  /** Specifiers of value imports, re-exports and dynamic `import()` calls. */
+  readonly imports: readonly string[];
+};
+/** Build a usage value from parts, deduplicated and frozen. */
+export declare function usageOf(parts: {
+  readonly keys?: readonly string[];
+  readonly prefixes?: readonly string[];
+  readonly literals?: readonly string[];
+  readonly literalPrefixes?: readonly string[];
+  readonly dynamic?: boolean;
+  readonly dynamicSites?: readonly TranslationDynamicSite[];
+}): TranslationUsage;
+export declare const EMPTY_TRANSLATION_USAGE: TranslationUsage;
+/**
+ * Turn one `config.translations` entry into the usage it declares.
+ *
+ * `"statuses.*"` declares every key under `statuses.`, `"members"` declares a
+ * key and its subtree, and `"*"` declares everything. A wildcard anywhere but
+ * the final `.*`, or an empty entry, is refused rather than guessed at.
+ */
+export declare function translationDeclarationUsage(entry: string, file: string): TranslationUsage;
+/** The union of several usages: a dynamic lookup anywhere makes the union dynamic. */
+export declare function mergeTranslationUsage(usages: readonly TranslationUsage[]): TranslationUsage;
+/** Whether a usage can reach `key`. A dynamic usage reaches every key. */
+export declare function isTranslationKeyUsed(usage: TranslationUsage, key: string): boolean;
+/**
+ * Scan one source file for translation lookups and the modules it loads.
+ *
+ * Literal keys, static-prefix templates, identifiers bound to a module-level
+ * string constant, and choices between those (`a ? "x" : "y"`) all resolve. Any
+ * other key expression is `dynamic`, and so is a translator that escapes as a
+ * value (passed on, returned, stored): whoever receives it can call it with any
+ * key.
+ */
+export declare function scanTranslationSource(fileName: string, text: string): TranslationSourceScan;
+/**
+ * The `config.translations` declaration of a page's setup file, as its raw
+ * entries. Read statically, like `config.route`, so the build never runs the
+ * file. `undefined` when the file declares none.
+ */
+export declare function readTranslationDeclarations(fileName: string, text: string): readonly string[] | undefined;
+//#endregion
+//# sourceMappingURL=translation-usage.d.mts.map

package/esm/localization/translation-usage.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-usage.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/localization/translation-usage.ts"],"mappings":";;;;;;;;;;;;;;;YAgBY;WACD;WACA;;;;;;;;WAQA;;WAEA;WACA;;WAEA,uBAAuB;;YAGtB;WACD;WACA;WACA;;WAEA;;;YAIC;WACD,OAAO;;WAEP;;;wBA+BK,QAAQ;WACb;WACA;WACA;WACA;WACA;WACA,wBAAwB;IAC/B;qBAWS,yBAAyB;;;;;;;;wBAStB,4BAA4B,eAAe,eAAe;;wBAsB1D,sBAAsB,iBAAiB,qBAAqB;;wBA2B5D,qBAAqB,OAAO,kBAAkB;;;;;;;;;;wBAsK9C,sBAAsB,kBAAkB,eAAe;;;;;;wBAwIvD,4BACd,kBACA"}