@spfn/core 0.3.0-beta.28 → 0.3.0-beta.29

package/dist/codegen/index.d.ts

@@ -429,6 +429,64 @@ declare class ContractGeneratorError extends Error {
     constructor(message: string);
 }
 
+/**
+ * States Generator
+ *
+ * Generates a file naming the states the app declared — their ids and their
+ * manifest — as values a browser root or a server component can execute.
+ *
+ * `defineStateRouter` declares the states, and the browser reads them through
+ * `createStateClient<typeof states>`: a type import, erased at build. So nothing
+ * that runs in the browser says which states the app declared, and importing
+ * the router to find out is not an option — each state's `read()` closes over
+ * repositories and the database. A root that compares the declared ids with the
+ * `manifest` of `GET /state` can report a deploy skew between the Next.js server
+ * and the API before rendering, instead of a screen meeting `state.<id>` as
+ * `undefined`.
+ *
+ * The router is loaded and walked, as the route map's is. A state router is told
+ * apart by the `_stateManifest` marker `defineStateRouter` sets on the router it
+ * derives — the object the snapshot route answers as `manifest` — so the ids
+ * written here and the manifest the server serves come from one value.
+ *
+ * @example
+ * ```typescript
+ * // .spfnrc.ts
+ * import { defineConfig, defineGenerator } from '@spfn/core/codegen';
+ *
+ * export default defineConfig({
+ *     generators: [
+ *         defineGenerator({
+ *             name: '@spfn/core:states',
+ *             routerPath: './src/server/router.ts',
+ *             outputPath: './src/generated/states.ts',
+ *         })
+ *     ]
+ * });
+ * ```
+ */
+
+interface StatesGeneratorConfig {
+    /**
+     * Generator name (required for package-based loading)
+     */
+    name: '@spfn/core:states';
+    /**
+     * Path to the router file (relative to project root) — the one the route map reads
+     * @example './src/server/router.ts'
+     */
+    routerPath: string;
+    /**
+     * Output path for the generated states file (relative to project root)
+     * @default './src/generated/states.ts'
+     */
+    outputPath?: string;
+}
+/** Thrown when the router cannot produce the app's declared states. */
+declare class StatesGeneratorError extends Error {
+    constructor(message: string);
+}
+
 /**
  * Router registration guard
  *
@@ -499,7 +557,7 @@ declare function assertUnconditionalRegistration(scan: RegistrationScan): void;
  * ```typescript
  * // .spfnrc.ts
  * import { defineConfig, defineGenerator } from '@spfn/core/codegen';
- * import type { RouteMapGeneratorConfig, ContractGeneratorConfig } from '@spfn/core/codegen';
+ * import type { RouteMapGeneratorConfig, ContractGeneratorConfig, StatesGeneratorConfig } from '@spfn/core/codegen';
  *
  * export default defineConfig({
  *   generators: [
@@ -513,6 +571,11 @@ declare function assertUnconditionalRegistration(scan: RegistrationScan): void;
  *       routerPath: './src/server/router.ts',
  *       outputDir: './contracts',
  *     }),
+ *     defineGenerator<StatesGeneratorConfig>({
+ *       name: '@spfn/core:states',
+ *       routerPath: './src/server/router.ts',
+ *       outputPath: './src/generated/states.ts',
+ *     }),
  *   ]
  * });
  * ```
@@ -525,4 +588,4 @@ declare function assertUnconditionalRegistration(scan: RegistrationScan): void;
  */
 declare const generators: Record<string, unknown>;
 
-export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, ConditionalRegistrationError, type ContractGeneratorConfig, ContractGeneratorError, type GenerationStats, type Generator, type GeneratorConfig, type GeneratorOptions, type GeneratorTrigger, type OrchestratorOptions, type RegistrationScan, type ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, RouteMapGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
+export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, ConditionalRegistrationError, type ContractGeneratorConfig, ContractGeneratorError, type GenerationStats, type Generator, type GeneratorConfig, type GeneratorOptions, type GeneratorTrigger, type OrchestratorOptions, type RegistrationScan, type ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, RouteMapGeneratorError, type StatesGeneratorConfig, StatesGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };

package/dist/codegen/index.js

@@ -497,6 +497,21 @@ function conditionKind(compiler2, expression) {
 function spreadText(file, expression) {
   return expression.getText(file).replace(/\s+/g, " ");
 }
+
+// src/codegen/generators/emit.ts
+function toObjectKey(name) {
+  if (name === "__proto__") {
+    return `[${JSON.stringify(name)}]`;
+  }
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+var SINGLE_QUOTABLE = /^[\x20-\x26\x28-\x5B\x5D-\x7E]*$/;
+function toStringLiteral(value) {
+  if (SINGLE_QUOTABLE.test(value)) {
+    return `'${value}'`;
+  }
+  return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
 var loadLogger = logger.child("@spfn/core:codegen");
 function pinNodeEnv() {
   if (process.env.NODE_ENV) {
@@ -833,19 +848,6 @@ function collectRouteMap(router) {
   assertNoPackageCollision(collection);
   return collection;
 }
-function toObjectKey(name) {
-  if (name === "__proto__") {
-    return `[${JSON.stringify(name)}]`;
-  }
-  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
-}
-var SINGLE_QUOTABLE = /^[\x20-\x26\x28-\x5B\x5D-\x7E]*$/;
-function toStringLiteral(value) {
-  if (SINGLE_QUOTABLE.test(value)) {
-    return `'${value}'`;
-  }
-  return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
-}
 function describeMount(mount) {
   if (mount.count === 0) {
     return `${mount.label} \u2014 no routes${mount.skipped ? ` (${mount.skipped})` : ""}`;
@@ -1114,13 +1116,156 @@ A released client cannot be fixed by redeploying the server. Keep the promise, o
     }
   };
 }
+var genLogger3 = logger.child("@spfn/core:states-generator");
+var StatesGeneratorError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StatesGeneratorError";
+  }
+};
+var ROUTER_EXPORTS2 = ["appRouter", "default", "router"];
+function loadRouter3(cwd, absoluteRouterPath) {
+  const module = loadRouterModule({
+    cwd,
+    absoluteRouterPath,
+    subject: "state manifest",
+    fail: (message) => new StatesGeneratorError(message)
+  });
+  const resolved = resolveRouterExport(module, ROUTER_EXPORTS2);
+  if (resolved) {
+    return resolved;
+  }
+  throw new StatesGeneratorError(
+    `No router found in ${relative(cwd, absoluteRouterPath)}. Looked for: ${ROUTER_EXPORTS2.join(", ")}. Export the defineRouter() result under one of those names.`
+  );
+}
+function collectStates(router, trail, visited, into) {
+  if (visited.has(router)) {
+    return 0;
+  }
+  visited.add(router);
+  let stateRouters = addStates(router, trail.join("."), into) ? 1 : 0;
+  for (const [name, entry] of Object.entries(router.routes)) {
+    if (isRouter(entry)) {
+      stateRouters += collectStates(entry, [...trail, name], visited, into);
+    }
+  }
+  for (const [index, nested] of (router._packageRouters ?? []).entries()) {
+    stateRouters += collectStates(nested, [...trail, `packages[${index}]`], visited, into);
+  }
+  return stateRouters;
+}
+function addStates(router, trail, into) {
+  if (!Object.hasOwn(router, "_stateManifest")) {
+    return false;
+  }
+  for (const [id, entry] of Object.entries(router._stateManifest ?? {})) {
+    const existing = into.get(id);
+    if (existing) {
+      throw new StatesGeneratorError(
+        `Two state routers both declare a state "${id}" (${existing.trail} and ${trail}). The browser addresses a state by its id alone and the generated manifest holds one entry per id, so one of the two would be read through the other's routes. Rename one of the states, or mount one of the two routers only.`
+      );
+    }
+    into.set(id, { entry, trail });
+  }
+  return true;
+}
+function collectDeclaredStates(router, routerPath) {
+  const states = /* @__PURE__ */ new Map();
+  if (collectStates(router, ["router"], /* @__PURE__ */ new Set(), states) === 0) {
+    throw new StatesGeneratorError(
+      `No state router is mounted by ${routerPath}. The @spfn/core:states generator is configured, but nothing it reads mounts a defineStateRouter(...).router, so the file it would write could not say which states the app declared, and every id the server serves would read as a skew. Mount the state router \u2014 \`appRouter.packages([states.router])\` \u2014 or remove the generator from .spfnrc.ts.`
+    );
+  }
+  return states;
+}
+function entryLine2(id, entry) {
+  return `    ${toObjectKey(id)}: { key: [${entry.key.map(toStringLiteral).join(", ")}], write: ${entry.write} },`;
+}
+function generateStatesContent(states, nodeEnv) {
+  const ids = [...states.keys()];
+  return [
+    "/**",
+    " * State Manifest (Auto-generated)",
+    " *",
+    " * DO NOT EDIT - This file is generated by @spfn/core:states generator",
+    " *",
+    ` * Generated with NODE_ENV=${nodeEnv}. A state router mounted only under one environment is`,
+    " * named here only when the generator ran under it, so this line changing is that",
+    " * difference rather than an edit.",
+    " *",
+    " * Compare `stateManifest` with the `manifest` of `GET <state path>` (or of the snapshot a",
+    " * server component read): an id here that the server's manifest lacks, or an entry that",
+    " * differs, is a deploy skew between this build and the API.",
+    " */",
+    "",
+    `export const stateIds = [${ids.map(toStringLiteral).join(", ")}] as const;`,
+    "",
+    "export type StateId = (typeof stateIds)[number];",
+    "",
+    "export const stateManifest: Readonly<Record<StateId, { readonly key: readonly string[]; readonly write: boolean }>> = {",
+    ...ids.map((id) => entryLine2(id, states.get(id).entry)),
+    "};",
+    ""
+  ].join("\n");
+}
+function createStatesGenerator(config) {
+  const { routerPath, outputPath = "./src/generated/states.ts" } = config;
+  if (!routerPath) {
+    throw new Error(
+      `[@spfn/core:states] Missing required "routerPath" option.
+
+Usage:
+  defineGenerator<StatesGeneratorConfig>({
+    name: '@spfn/core:states',
+    routerPath: './src/server/router.ts',
+  })`
+    );
+  }
+  return {
+    name: "@spfn/core:states",
+    watchPatterns: [
+      routerPath,
+      "src/server/states.ts",
+      "src/server/states/**/*.ts",
+      "src/server/routes/**/*.ts"
+    ],
+    runOn: ["watch", "manual", "build"],
+    async generate(options) {
+      const { cwd, debug } = options;
+      const absoluteRouterPath = join(cwd, routerPath);
+      const absoluteOutputPath = join(cwd, outputPath);
+      if (!existsSync(absoluteRouterPath)) {
+        genLogger3.warn(`Router file not found: ${absoluteRouterPath}`);
+        return;
+      }
+      pinNodeEnv();
+      const { router, exportName } = loadRouter3(cwd, absoluteRouterPath);
+      assertUnconditionalRegistration({
+        routerPath,
+        source: readFileSync(absoluteRouterPath, "utf-8"),
+        exportName,
+        subject: "state manifest"
+      });
+      const states = collectDeclaredStates(router, routerPath);
+      if (debug) {
+        genLogger3.info(`Found ${states.size} states`, { ids: [...states.keys()] });
+      }
+      mkdirSync(dirname(absoluteOutputPath), { recursive: true });
+      const nodeEnv = process.env.NODE_ENV ?? "unset";
+      writeFileSync(absoluteOutputPath, generateStatesContent(states, nodeEnv), "utf-8");
+      genLogger3.info(`Generated states: ${relative(cwd, absoluteOutputPath)} (${states.size} states)`);
+    }
+  };
+}
 
 // src/codegen/generators/index.ts
 var generators = {
   "route-map": createRouteMapGenerator,
-  contract: createContractGenerator
+  contract: createContractGenerator,
+  states: createStatesGenerator
 };
 
-export { CodegenOrchestrator, ConditionalRegistrationError, ContractGeneratorError, RouteMapGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
+export { CodegenOrchestrator, ConditionalRegistrationError, ContractGeneratorError, RouteMapGeneratorError, StatesGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map