@happyvertical/smrt-core 0.46.0 → 0.47.0

package/dist/vite-plugin/sveltekit-generator.js

@@ -1,5 +1,5 @@
 import { MAX_LIST_LIMIT, buildDefaultListOrderBy } from "../query-bounds.js";
-import { CRUD_OPERATIONS, isCrudOperation, resolveCustomActionMetadata, resolveCustomActionNames } from "../generators/custom-action.js";
+import { CRUD_OPERATIONS, createManifestClassNamePredicate, declaredTypeAcceptsDate, isCrudOperation, queryStringDecoderFor, resolveApiMethodExposure, resolveCustomActionMetadata, resolveCustomActionNames, resolveDeclaredScopeMismatch, resolveEffectiveActionMetadata } from "../generators/custom-action.js";
 import { isFrameworkBaseClass } from "../registry/framework-base-classes.js";
 import { generateConditionalGetRouteHelper } from "../generators/conditional-get.js";
 import { AUTO_GENERATED_ROUTE_HEADER } from "./route-header.js";
@@ -596,8 +596,12 @@ function extractRoutePathParamNames(pathSegments) {
 	return pathSegments.filter((segment) => /^\[[^\]]+\]$/.test(segment)).map((segment) => segment.slice(1, -1)).filter(Boolean);
 }
 function resolveApiActionRouteConfig(actionName, actionDef, apiConfig, routeOptions = {}, defaultScope = actionDef.isStatic ? "collection" : "item") {
-	const routeConfig = getApiConfigObject(apiConfig)?.routes?.[actionName];
-	const pathSegments = normalizeCustomRoutePath(actionName, routeConfig?.path, routeOptions);
+	const effective = resolveEffectiveActionMetadata({
+		actionName,
+		method: actionDef,
+		apiConfig
+	});
+	const pathSegments = normalizeCustomRoutePath(actionName, effective.path, routeOptions);
 	return {
 		scope: resolveCustomActionMetadata({
 			actionName,
@@ -605,7 +609,7 @@ function resolveApiActionRouteConfig(actionName, actionDef, apiConfig, routeOpti
 			apiConfig,
 			defaultScope
 		}).scope,
-		method: normalizeApiHttpMethod(routeConfig?.method),
+		method: normalizeApiHttpMethod(effective.httpMethod),
 		pathSegments,
 		pathParamNames: extractRoutePathParamNames(pathSegments)
 	};
@@ -626,11 +630,15 @@ function hasSingleOptionsParameter(actionDef) {
 	const parameters = Array.isArray(actionDef.parameters) ? actionDef.parameters : [];
 	return parameters.length === 1 && parameters[0]?.name === "options";
 }
-function buildActionInvocationArgs(actionDef, optionsIdentifier = "options") {
+function buildActionInvocationArgs(actionDef, optionsIdentifier = "options", httpMethod) {
 	const parameters = Array.isArray(actionDef.parameters) ? actionDef.parameters : [];
 	if (parameters.length === 0) return [];
 	if (hasSingleOptionsParameter(actionDef)) return [optionsIdentifier];
-	return parameters.map((parameter) => buildOptionsPropertyAccess(parameter.name));
+	return parameters.map((parameter, index) => {
+		const access = buildOptionsPropertyAccess(parameter.name);
+		const decoder = httpMethod === "GET" ? queryStringDecoderFor(parameter.type) : declaredTypeAcceptsDate(parameter.type) ? "toCustomActionDate" : void 0;
+		return decoder ? `${decoder}(${access}) as ActionArgs[${index}]` : access;
+	});
 }
 function buildObjectTypeProperty(propertyName) {
 	if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(propertyName)) return propertyName;
@@ -1162,14 +1170,12 @@ async function generateRoutesForObject(projectRoot, className, objectDef, manife
 		const itemRoute = generateItemRouteTemplate(projectRoot, className, objectDef, manifest, includedActions, options, join(routeDir, "[id]"));
 		generatedRoutePaths.push(writeRoute(join(routeDir, "[id]"), "+server.ts", itemRoute));
 	}
-	const customActions = Object.entries(objectDef.methods).filter(([name, method]) => !isCrudOperation(name) && method.isPublic && shouldIncludeInApi(name, apiConfig));
+	const { exposed: customActions, rejected } = resolveApiCustomActions(objectDef, manifest, false);
+	warnUnhostedActions(className, rejected);
 	const actionSpecs = [];
 	for (const [actionName, actionDef] of customActions) {
 		const routeConfig = resolveApiActionRouteConfig(actionName, actionDef, apiConfig, { kebabRoutes: options.kebabRoutes });
-		if (routeConfig.scope === "collection" && !actionDef.isStatic) {
-			console.warn(`[smrt] Skipping ${className}.${actionName} - collection API routes require a static method`);
-			continue;
-		}
+		warnDeclaredScopeMismatch(className, actionName, actionDef, apiConfig, routeConfig.scope);
 		const actionBaseDir = routeConfig.scope === "collection" ? routeDir : join(routeDir, "[id]");
 		actionSpecs.push({
 			routeDir: join(actionBaseDir, ...routeConfig.pathSegments),
@@ -1200,15 +1206,13 @@ async function generateCollectionRoutesForObject(projectRoot, className, objectD
 	const routeDir = join(projectRoot, options.routesDir, objectDef.collection);
 	const lookupClassName = findItemClassRegistryKey(className, objectDef, manifest);
 	const lookupObjectDef = findObjectDefByRegistryKey(manifest, lookupClassName);
-	const customActions = Object.entries(objectDef.methods).filter(([name, method]) => !isCrudOperation(name) && method.isPublic && shouldIncludeInApi(name, apiConfig));
+	const { exposed: customActions, rejected } = resolveApiCustomActions(objectDef, manifest, true);
+	warnUnhostedActions(className, rejected);
 	if (customActions.length === 0) return generatedRoutePaths;
 	const actionSpecs = [];
 	for (const [actionName, actionDef] of customActions) {
 		const routeConfig = resolveApiActionRouteConfig(actionName, actionDef, apiConfig, { kebabRoutes: options.kebabRoutes }, "collection");
-		if (routeConfig.scope !== "collection") {
-			console.warn(`[smrt] Skipping ${className}.${actionName} - collection class methods only support collection-scoped API routes`);
-			continue;
-		}
+		warnDeclaredScopeMismatch(className, actionName, actionDef, apiConfig, routeConfig.scope);
 		actionSpecs.push({
 			routeDir: join(routeDir, ...routeConfig.pathSegments),
 			spec: {
@@ -1246,49 +1250,103 @@ function resolveStandardCrudActions(apiConfig) {
 	return crud;
 }
 /**
-* Check if a custom action should be included in API.
+* Partition an object's custom (non-CRUD) methods into the ones the API
+* exposes and the ones it withholds, with a reason for each rejection.
 *
-* Mirrors the CRUD inclusion path: intersect with `include` (when set), then
-* subtract `exclude`. Both filters apply together, matching principle of least
-* surprise for users supplying both lists.
+* The ONE place route generation, `resolveApiActionSet`, and the knowledge
+* artifact's API projection agree, by all three reading
+* {@link resolveApiMethodExposure}. Before #2686 each re-derived a subset and
+* could disagree — most damagingly, a gate applied only to the coherence
+* resolver would report a method unreachable while the emitter next door still
+* wrote its route file.
 */
-function shouldIncludeInApi(actionName, apiConfig) {
-	if (apiConfig === false) return false;
-	if (apiConfig === true || apiConfig === void 0) return true;
-	if (typeof apiConfig === "object" && apiConfig !== null) {
-		const config = apiConfig;
-		const included = Array.isArray(config.include) ? config.include.includes(actionName) : true;
-		const excluded = Array.isArray(config.exclude) ? config.exclude.includes(actionName) : false;
-		return included && !excluded;
+function resolveApiCustomActions(objectDef, manifest, objectIsCollectionClass, wireability = {}) {
+	const apiConfig = objectDef.decoratorConfig?.api;
+	const isModelClassName = wireability.isModelClassName ?? createManifestClassNamePredicate(manifest);
+	const exposed = [];
+	const rejected = [];
+	for (const [name, method] of Object.entries(objectDef.methods || {})) {
+		const decision = resolveApiMethodExposure({
+			actionName: name,
+			method,
+			apiConfig,
+			isCollectionClass: objectIsCollectionClass,
+			...isModelClassName ? { isModelClassName } : {}
+		});
+		if (decision.exposed) {
+			exposed.push([name, method]);
+			continue;
+		}
+		if (decision.code === "crud-reserved" || decision.code === "not-public") continue;
+		rejected.push([name, decision]);
 	}
-	return true;
+	return {
+		exposed,
+		rejected
+	};
+}
+/**
+* Warn about the one rejection class that would be a structural failure rather
+* than a configuration choice: an action whose declared scope has no receiver
+* to bind. Both emitters carried this warning before #2686 moved the check into
+* the shared resolver, and the message text is preserved.
+*
+* It cannot currently fire — `resolveCustomActionMetadata` collapses a
+* contradicting scope back to the receiver-derived one, as it did before this
+* change; see `resolveActionReceiver` in `generators/custom-action.ts`. The
+* warning a developer actually sees for a contradicting declaration is
+* `warnDeclaredScopeMismatch` below.
+*
+* Every other rejection is silent here and reported with its reason through
+* the knowledge artifact instead, so a normal build is not buried in output
+* for the 2% of methods the heuristic legitimately withholds.
+*/
+function warnUnhostedActions(className, rejected) {
+	for (const [actionName, decision] of rejected) {
+		if (decision.code !== "no-receiver") continue;
+		console.warn(`[smrt] Skipping ${className}.${actionName} - ${decision.reason}`);
+	}
+}
+/**
+* Report a declared `scope` that contradicts the method's actual receiver.
+*
+* The declaration is honored only where it AGREES; nothing in config can move
+* an instance method onto the class. Warning is the whole remedy — the route
+* is still emitted at the receiver-derived URL, so an author who expected the
+* other one learns why it is missing instead of silently getting nothing at
+* either address (#2686).
+*/
+function warnDeclaredScopeMismatch(className, actionName, actionDef, apiConfig, effectiveScope) {
+	const declared = resolveDeclaredScopeMismatch({
+		actionName,
+		method: actionDef,
+		apiConfig,
+		effectiveScope
+	});
+	if (!declared) return;
+	console.warn(`[smrt] ${className}.${actionName} declares scope '${declared}' but its receiver is ${effectiveScope}-scoped, so the declared scope is ignored. A scope describes where a method already lives; it cannot move it. Make ${actionName} static to reach it on the collection, or drop the scope option.`);
 }
 /**
 * Compute the set of action names (standard CRUD + custom methods) that the
 * API exposes for a given object definition. This is the same resolution used
 * to drive route generation, exposed so coherence checks (e.g. CLI vs API)
 * can ask "what does the API expose?" without re-implementing the logic.
+*
+* Pass a class inventory: without one the wire-ability heuristic cannot tell a
+* model class from an options interface and therefore accepts both, so the
+* caller silently disagrees with the emitters on the LARGEST group of withheld
+* methods (see `WireabilityOptions.isModelClassName`). Supply either
+* `manifest`, or `wireability.isModelClassName` when the caller's inventory is
+* the live registry rather than a manifest — `@happyvertical/smrt-users`' CLI
+* resource listing is the second kind. Both stay optional only because this is
+* public API.
 */
-function resolveApiActionSet(objectDef, manifest) {
+function resolveApiActionSet(objectDef, manifest, wireability = {}) {
 	const apiConfig = objectDef.decoratorConfig?.api;
 	if (apiConfig === false) return /* @__PURE__ */ new Set();
 	const objectIsCollectionClass = manifest ? isCollectionManifestClass(manifest, objectDef) : isCollectionClass(objectDef);
 	const actions = objectIsCollectionClass ? /* @__PURE__ */ new Set() : new Set(resolveStandardCrudActions(apiConfig));
-	for (const [name, method] of Object.entries(objectDef.methods || {})) {
-		if (isCrudOperation(name)) continue;
-		if (!method.isPublic) continue;
-		if (!shouldIncludeInApi(name, apiConfig)) continue;
-		const scope = resolveCustomActionMetadata({
-			actionName: name,
-			method,
-			apiConfig,
-			defaultScope: objectIsCollectionClass ? "collection" : method.isStatic ? "collection" : "item"
-		}).scope;
-		if (objectIsCollectionClass) {
-			if (scope !== "collection") continue;
-		} else if (scope === "collection" && !method.isStatic) continue;
-		actions.add(name);
-	}
+	for (const [name] of resolveApiCustomActions(objectDef, manifest, objectIsCollectionClass, wireability).exposed) actions.add(name);
 	return actions;
 }
 /**
@@ -1399,7 +1457,7 @@ function validateCliIncludeAgainstApi(manifest) {
 		return typeof cliConfig === "object" && cliConfig !== null && Array.isArray(cliConfig.include) && cliConfig.include.length > 0;
 	});
 	if (violations.length === 0) return;
-	const messages = violations.flatMap(({ className, unreachable }) => unreachable.map((action) => `[smrt] ${className}.${action} is exposed as a CLI command but is not exposed via the api.\n  Either:\n    - Add '${action}' to api.include, or\n    - Remove '${action}' from cli.include / add it to cli.exclude.\n  The CLI invokes methods over HTTP; methods without API routes are unreachable.\n  If this CLI is intentionally invoked in-process (no HTTP), set\n  \`cli: { skipApiCheck: true }\` on the @smrt() decorator to acknowledge.`));
+	const messages = violations.flatMap(({ className, unreachable }) => unreachable.map((action) => `[smrt] ${className}.${action} is exposed as a CLI command but is not exposed via the api.\n  Either:\n    - Decorate '${action}' with @method({ expose: true }) to route it, or\n    - Add '${action}' to api.include, or\n    - Remove '${action}' from cli.include / add it to cli.exclude.\n  The CLI invokes methods over HTTP; methods without API routes are unreachable.\n  A public method is routed by default only when every parameter can be\n  built from JSON; @method({ expose: true }) overrides that for one method\n  without widening api.include. See withheldSurfaces in the knowledge\n  artifact for the reason this one was withheld (#2686).\n  If this CLI is intentionally invoked in-process (no HTTP), set\n  \`cli: { skipApiCheck: true }\` on the @smrt() decorator to acknowledge.`));
 	throw new Error(messages.join("\n\n"));
 }
 /**
@@ -1687,9 +1745,21 @@ function generateActionRouteTemplate(projectRoot, routeDir, routeSpecs, objectDe
 	const hostModelType = resolveObjectTypeReference(projectRoot, firstSpec.hostClassName, objectDef, options, routeDir);
 	const typeImports = mergeImportStatements([lookupModelType.importStatement, hostModelType.importStatement]);
 	if (routeSpecs.some((spec) => spec.hostType !== hostType || spec.lookupClassName !== lookupClassName || spec.routeConfig.scope !== routeConfig.scope)) throw new Error(`Cannot generate mixed custom route handlers for ${lookupClassName}. All handlers sharing a route path must target the same host type and scope.`);
+	const decoderImports = /* @__PURE__ */ new Set();
+	for (const spec of routeSpecs) {
+		if (hasSingleOptionsParameter(spec.actionDef)) continue;
+		for (const parameter of spec.actionDef.parameters ?? []) {
+			const decoder = spec.routeConfig?.method === "GET" ? queryStringDecoderFor(parameter.type) : declaredTypeAcceptsDate(parameter.type) ? "toCustomActionDate" : void 0;
+			if (decoder) decoderImports.add(decoder);
+		}
+	}
 	const importBlock = [
 		"import { error, json } from '@sveltejs/kit';",
-		"import { normalizeCustomActionFailure, normalizeTypedHttpError } from '@happyvertical/smrt-core';",
+		`import { ${[
+			"normalizeCustomActionFailure",
+			"normalizeTypedHttpError",
+			...[...decoderImports].sort()
+		].join(", ")} } from '@happyvertical/smrt-core';`,
 		hostType === "collection" || routeConfig.scope !== "collection" ? "import { getCollection } from '$lib/server/smrt';" : "import { ObjectRegistry } from '@happyvertical/smrt-core';",
 		typeImports,
 		"import type { RequestHandler } from './$types';"
@@ -1719,7 +1789,7 @@ function generateActionRouteHandler(lookupClassName, actionName, actionDef, rout
 		const receiverExpression = actionDef.isStatic ? "CollectionClass" : "typedCollection";
 		const staticTargetLoad = actionDef.isStatic ? `  const CollectionClass = typedCollection.constructor as typeof ${hostTypeName};\n` : "";
 		const scopedOptions = buildScopedOptionsForTenantRead(actionDef, routeConfig, tenantScoped);
-		const invocationArgs = buildActionInvocationArgs(actionDef, scopedOptions.optionsIdentifier);
+		const invocationArgs = buildActionInvocationArgs(actionDef, scopedOptions.optionsIdentifier, routeConfig.method);
 		return `// Custom collection method: ${actionName}
 export const ${handlerName}: RequestHandler = async (${collectionHandlerArgs}) => {
 ${authGuardLine}
@@ -1751,7 +1821,7 @@ ${optionsLoad}${scopedOptions.source}  let result: unknown;
 	if (routeConfig.scope === "collection") {
 		const optionsLoad = buildActionOptionsLoad(actionName, actionDef, routeConfig, hostTypeName, true);
 		const scopedOptions = buildScopedOptionsForTenantRead(actionDef, routeConfig, tenantScoped);
-		const invocationArgs = buildActionInvocationArgs(actionDef, scopedOptions.optionsIdentifier);
+		const invocationArgs = buildActionInvocationArgs(actionDef, scopedOptions.optionsIdentifier, routeConfig.method);
 		return `// Custom collection action: ${actionName}
 export const ${handlerName}: RequestHandler = async (${collectionHandlerArgs}) => {
 ${authGuardLine}
@@ -1784,7 +1854,7 @@ ${optionsLoad}${scopedOptions.source}  const ClassRef = registered.constructor a
   const item = await collection.get(
     readScope ? { id: params.id, ...readScope } : params.id,
   );` : "  const item = await collection.get(params.id);";
-	const invocationArgs = buildActionInvocationArgs(actionDef);
+	const invocationArgs = buildActionInvocationArgs(actionDef, "options", routeConfig.method);
 	return `// Custom action: ${actionName}
 export const ${handlerName}: RequestHandler = async (${itemHandlerArgs}) => {
 ${authGuardLine}
@@ -1992,6 +2062,6 @@ function updateGeneratedRouteIgnoreBlock(gitignoreContent, generatedPaths) {
 	return `${updatedContent}${managedBlock.join("\n")}\n`;
 }
 //#endregion
-export { findCliApiCoherenceViolations, generateSvelteKitRoutes, methodNameToKebab, resolveApiActionRouteConfig, resolveApiActionSet, validateCliIncludeAgainstApi };
+export { findCliApiCoherenceViolations, generateSvelteKitRoutes, methodNameToKebab, resolveApiActionRouteConfig, resolveApiActionSet, resolveApiCustomActions, validateCliIncludeAgainstApi };
 
 //# sourceMappingURL=sveltekit-generator.js.map