@luckystack/devkit 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `collectFunctionModules()` / `renderFunctionsMap()` — one shared source of truth for server-function discovery and `functions.*` key derivation, consumed by the dev loader, the type-map generator and `scripts/generateServerRequests.ts`. A cross-root duplicate key or a module/namespace collision now fails the build with a diagnostic naming both source files, instead of silently dropping one module from the generated map.
+
+### Fixed
+
+- Test files in a `serverFunctionDirs` root are excluded from function injection. `functions/db.tests.ts` used to be injected as `functions['db.tests']` — imported at boot by the dev loader, declared in the generated `Functions` interface, and baked into the production runtime map. `__tests__` / `__mocks__` folders are skipped too (ADR 0047).
+
+- Server-function discovery no longer diverges between layers. The type-map generator now honours the `RoutingRules.ignore` predicate on function roots (it previously only did so for routes), and both it and the dev loader derive key paths from the same walk that feeds the production map generator.
+
 ## [0.8.4] - 2026-08-17
 
 ### Changed

package/CLAUDE.md

@@ -29,7 +29,11 @@ Dev-time tooling for LuckyStack projects: file-based route discovery + in-memory
 | `initializeAll()` | Runs route-naming validation, then `initializeApis` + `initializeSyncs` + `initializeFunctions` in parallel. | -> docs/loader-pipeline.md |
 | `initializeApis()` | Clears `devApis`, walks the configured `srcDir`, loads every `_api/<name>_v<n>.ts` via dynamic `import()` with a cachebust query, and populates the dev-side route registry. | -> docs/loader-pipeline.md |
 | `initializeSyncs()` | Clears `devSyncs`, walks the configured `srcDir`, loads every `_sync/<name>_server_v<n>.ts` and `<name>_client_v<n>.ts`, and populates the dev-side route registry. | -> docs/loader-pipeline.md |
-| `initializeFunctions()` | Clears `devFunctions`, walks every configured `serverFunctionDirs` root (legacy singular `serverFunctionsDir` still honored when set), builds a nested `Record<string, unknown>` mirror of the on-disk tree, and merges named + default exports per file. | -> docs/loader-pipeline.md |
+| `initializeFunctions()` | Clears `devFunctions`, resolves the module list via `collectFunctionModules()`, imports each one, and builds a nested `Record<string, unknown>` mirror of the on-disk tree from its key path. Dev passes `onConflict` so a duplicate warns + keeps the first claim instead of throwing. | -> docs/loader-pipeline.md |
+| `collectFunctionModules(options?)` | **Single source of truth for function discovery** (ADR 0046). Walks every configured `serverFunctionDirs` root (default `['functions', 'shared']`, legacy singular `serverFunctionsDir` still honored) and derives each module's `functions.*` key path from its location relative to its root — so `shared/rbac/engine.ts` is `functions.rbac.engine`. Skips `node_modules`, test files (`.tests.`/`.test.`/`.spec.` via core's `isTestFile`), `__tests__`/`__mocks__` folders, and paths the `RoutingRules.ignore` predicate rejects. Throws on a cross-root duplicate key or a module/namespace collision; pass `onConflict` to warn + skip instead (dev-loader mode). `roots` overrides the configured roots for tests. Consumed by the dev loader, `functionsMeta.ts`, and BOTH `scripts/generateServerRequests.ts` copies. | -> docs/loader-pipeline.md |
+| `renderFunctionsMap({ modules, importPrefix, varPrefix? })` | Renders discovered modules into the `functions` export of a generated production runtime-map file: `{ imports, source }`, with a NESTED object literal matching what the dev loader builds and `apiTypes.generated.ts` declares. A default-only export is aliased to the file name (`functions.sleep.sleep`). | -> docs/loader-pipeline.md |
+| `formatFunctionKeyPath(keyPath)` / `functionModuleFileName(keyPath)` / `formatFunctionKeyConflict(...)` / `formatFunctionNamespaceConflict(...)` | Key-path helpers + the two canonical collision diagnostics, shared so dev and build-time emit identical wording. | -> docs/loader-pipeline.md |
+| Types: `FunctionModule`, `RenderedFunctionsMap`, `CollectFunctionModulesOptions` | Public typing for the function registry. | -> docs/loader-pipeline.md |
 | `upsertApiFromFile(filePath)` | Hot-reload single API: invalidates the TS Program cache + runtime type resolver cache, re-imports the file with a fresh cachebust, and replaces the matching entry in `devApis`. | -> docs/loader-pipeline.md |
 | `removeApiFromFile(filePath)` | Hot-reload delete: invalidates caches and deletes the matching entry from `devApis`. | -> docs/loader-pipeline.md |
 | `upsertSyncFromFile(filePath)` | Hot-reload single sync: handles both `_server_v<n>` and `_client_v<n>` kinds, invalidates caches, re-imports, replaces the matching entry in `devSyncs`. | -> docs/loader-pipeline.md |
@@ -76,7 +80,7 @@ Internal modules (not exported from `index.ts`, but live in this package):
 | `typeMap/extractors.ts` | TypeChecker-backed extractors for `data` / `serverOutput` / `clientOutput` / stream payload types. | -> docs/type-map-generation.md |
 | `typeMap/apiMeta.ts` | Extracts `httpMethod`, `rateLimit`, `auth` from API files. | -> docs/type-map-generation.md |
 | `typeMap/routeMeta.ts` | Filename -> `pagePath` / `apiName` / `apiVersion` / `syncName` / `syncVersion`. | -> docs/type-map-generation.md |
-| `typeMap/functionsMeta.ts` | Builds the `Functions` interface text emitted into `apiTypes.generated.ts`. | -> docs/type-map-generation.md |
+| `typeMap/functionsMeta.ts` | Builds the `Functions` interface text emitted into `apiTypes.generated.ts`. Discovery comes from `collectFunctionModules()`; this module only parses each file's exports and places it at its key path. | -> docs/type-map-generation.md |
 | `typeMap/emitter.ts` + `emitterArtifacts.ts` | Renders generated files to disk via `@luckystack/core`-resolved paths. | -> docs/type-map-generation.md |
 | `typeMap/zodEmitter.ts` | Generates the runtime Zod schemas for API inputs. | -> docs/type-map-generation.md |
 | `templateInjector.ts` + `templates/*.ts` | Detects empty `_api/`, `_sync/`, AND `page.tsx` files and injects starter content. Sync server/client pairing is auto-resolved. Page files get the `dashboard` template when the path contains `admin\|dashboard\|settings\|billing\|account\|profile`, else the `plain` template. Pages in invalid placements (inside a reserved framework folder, or directly inside an `_<folder>` with no URL segment left) get a commented diagnostic block instead of a usable template so the placement issue is visible at creation time. | -> docs/hot-reload.md |

package/dist/index.d.ts

@@ -20,6 +20,79 @@ declare const assertNoDuplicateNormalizedRouteKeys: ({ srcDir, context, }: {
     context: string;
 }) => void;
 
+interface FunctionModule {
+    /**
+     * Key path under the injected `functions` object. `shared/rbac/engine.ts`
+     * with root `shared` yields `['rbac', 'engine']`, reachable as
+     * `functions.rbac.engine`.
+     */
+    keyPath: string[];
+    /** Workspace-relative, forward-slash path to the source file (with `.ts`). */
+    sourcePath: string;
+    /** Workspace-relative, forward-slash root directory that claimed this key path. */
+    rootPath: string;
+}
+/** Dotted rendering of a key path, e.g. `rbac.engine`. */
+declare const formatFunctionKeyPath: (keyPath: string[]) => string;
+/**
+ * Last segment of a key path — the module's file name, which is also the alias
+ * a default-only export is published under (`functions.sleep.sleep`).
+ *
+ * Discovery never produces an empty key path; the guard exists so the callers
+ * get a real string instead of threading `string | undefined` through every
+ * emitter.
+ */
+declare const functionModuleFileName: (keyPath: string[]) => string;
+declare const formatFunctionKeyConflict: (keyPath: string[], firstSourcePath: string, secondSourcePath: string) => string;
+declare const formatFunctionNamespaceConflict: (moduleKeyPath: string[], moduleSourcePath: string, nestedKeyPath: string[], nestedSourcePath: string) => string;
+interface CollectFunctionModulesOptions {
+    /**
+     * Override the configured roots (absolute paths). Tests pass this;
+     * production callers omit it and get `getServerFunctionDirs()`.
+     */
+    roots?: string[];
+    /**
+     * When provided, a collision REPORTS through this callback and the offending
+     * module is skipped instead of throwing. The dev loader passes it so a
+     * duplicate does not hard-crash a running dev server; the build-time
+     * generators omit it so the same duplicate fails the build loudly.
+     */
+    onConflict?: (message: string) => void;
+}
+/**
+ * Discover every server function module across the configured
+ * `paths.serverFunctionDirs` roots (default `['functions', 'shared']`), in
+ * config order, and derive its `functions.*` key path from its location
+ * relative to the root that owns it.
+ *
+ * Throws on a cross-root key collision or a module/namespace collision (unless
+ * `onConflict` is supplied), so a broken registry fails the BUILD instead of
+ * producing a map that is silently missing entries at runtime.
+ */
+declare const collectFunctionModules: (options?: CollectFunctionModulesOptions) => FunctionModule[];
+interface RenderedFunctionsMap {
+    /** `import * as fn0 from '...'` lines, in emission order. */
+    imports: string[];
+    /** The full `export const functions = { ... };` declaration. */
+    source: string;
+}
+/**
+ * Render discovered modules into the `functions` export of a generated
+ * production runtime-map file. The emitted object is NESTED, matching what the
+ * dev loader builds and what `apiTypes.generated.ts` declares.
+ *
+ * @param modules      Output of {@link collectFunctionModules}.
+ * @param importPrefix Prefix that turns a workspace-relative source path into a
+ *                     specifier relative to the generated file (`'../../'` for
+ *                     the standard `server/prod/` output location).
+ * @param varPrefix    Import alias prefix; aliases are `<varPrefix><n>`.
+ */
+declare const renderFunctionsMap: ({ modules, importPrefix, varPrefix, }: {
+    modules: FunctionModule[];
+    importPrefix: string;
+    varPrefix?: string;
+}) => RenderedFunctionsMap;
+
 interface RoutingRules {
     /** Folder name that marks an API directory. Default: `_api`. */
     apiMarker: string;
@@ -204,4 +277,4 @@ interface ValidateDeployResult {
 }
 declare const validateDeploy: ({ services, deploy, env, }: ValidateDeployInput) => ValidateDeployResult;
 
-export { API_VERSION_TOKEN_REGEX, BUILT_IN_TEMPLATE_FILENAMES, BUILT_IN_TEMPLATE_KINDS, type BuiltInTemplateKind, DEFAULT_DASHBOARD_PATH_PATTERN, type RegisterTemplateKindOptions, type RoutingRules, SYNC_VERSION_TOKEN_REGEX, type TemplateKind, type TemplateMatchContext, type TemplateRule, type ValidateDeployInput, type ValidateDeployResult, type ValidationFinding, type ValidationSeverity, apiMarkerSegment, assertNoDuplicateNormalizedRouteKeys, assertValidRouteNaming, clearRuntimeTypeResolverCache, clearTemplateOverrides, clearTemplateRules, devApis, devFunctions, devSyncs, generateTypeMapFile, getInputTypeFromFile, getRegisteredTemplate, getRoutingRules, getSyncClientDataType, getTemplateRules, initializeAll, initializeApis, initializeFunctions, initializeSyncs, isApiFileName, isSyncClientFileName, isSyncFileName, isSyncServerFileName, listRegisteredTemplateKinds, registerDefaultTemplateRules, registerRoutingRules, registerTemplate, registerTemplateKind, registerTemplateRule, removeApiFromFile, removeSyncFromFile, resolveRuntimeTypeText, resolveTemplateKind, setupWatchers, syncMarkerSegment, upsertApiFromFile, upsertSyncFromFile, validateDeploy };
+export { API_VERSION_TOKEN_REGEX, BUILT_IN_TEMPLATE_FILENAMES, BUILT_IN_TEMPLATE_KINDS, type BuiltInTemplateKind, type CollectFunctionModulesOptions, DEFAULT_DASHBOARD_PATH_PATTERN, type FunctionModule, type RegisterTemplateKindOptions, type RenderedFunctionsMap, type RoutingRules, SYNC_VERSION_TOKEN_REGEX, type TemplateKind, type TemplateMatchContext, type TemplateRule, type ValidateDeployInput, type ValidateDeployResult, type ValidationFinding, type ValidationSeverity, apiMarkerSegment, assertNoDuplicateNormalizedRouteKeys, assertValidRouteNaming, clearRuntimeTypeResolverCache, clearTemplateOverrides, clearTemplateRules, collectFunctionModules, devApis, devFunctions, devSyncs, formatFunctionKeyConflict, formatFunctionKeyPath, formatFunctionNamespaceConflict, functionModuleFileName, generateTypeMapFile, getInputTypeFromFile, getRegisteredTemplate, getRoutingRules, getSyncClientDataType, getTemplateRules, initializeAll, initializeApis, initializeFunctions, initializeSyncs, isApiFileName, isSyncClientFileName, isSyncFileName, isSyncServerFileName, listRegisteredTemplateKinds, registerDefaultTemplateRules, registerRoutingRules, registerTemplate, registerTemplateKind, registerTemplateRule, removeApiFromFile, removeSyncFromFile, renderFunctionsMap, resolveRuntimeTypeText, resolveTemplateKind, setupWatchers, syncMarkerSegment, upsertApiFromFile, upsertSyncFromFile, validateDeploy };