@spfn/core 0.2.0-beta.9 → 0.3.0-beta.2

package/dist/codegen/index.d.ts

@@ -7,6 +7,13 @@ import { HttpMethod } from '@spfn/core/route';
  */
 /**
  * Generator execution trigger types
+ *
+ * Who fires each one:
+ * - `watch`  — `spfn dev`, on the initial pass and every file change
+ * - `manual` — `spfn codegen run` and `spfn contract`
+ * - `build`  — `spfn build`
+ * - `start`  — nothing in the shipped CLI; reserved for a programmatic caller that
+ *              dispatches it through `orchestrator.generateAll('start')`
  */
 type GeneratorTrigger = 'watch' | 'manual' | 'build' | 'start';
 interface GeneratorOptions {
@@ -35,13 +42,14 @@ interface Generator {
     /**
      * When this generator should run
      *
-     * @default ['watch', 'manual', 'build']
+     * @default ['watch', 'manual', 'build'] — every trigger the CLI fires
+     *
+     * Narrowing this is the easy mistake: drop `build` and the generator is silently
+     * skipped during `spfn build`, so whatever it produces ships stale.
      *
      * Examples:
-     * - ['watch', 'build']: Run during development and build (e.g., admin-nav-generator)
-     * - ['build', 'start']: Run during build and server start (e.g., db-migration)
-     * - ['watch', 'manual']: Run during development and manual CLI (e.g., contract-generator)
-     * - ['start']: Run only on server start (e.g., runtime config generator)
+     * - ['watch']: only while `spfn dev` is watching, never from `spfn codegen run`
+     * - ['manual']: only on an explicit run, never mid-edit — for something slow
      */
     runOn?: GeneratorTrigger[];
     /**
@@ -89,11 +97,21 @@ interface OrchestratorOptions {
     cwd?: string;
     /** Enable debug logging */
     debug?: boolean;
+    /**
+     * Rethrow a generator failure instead of only logging it
+     *
+     * Off by default, which keeps watch mode alive through a half-edited file.
+     * A build turns it on: a generator that refuses — a broken contract, a
+     * router that will not load — has to reach the exit code, or the refusal
+     * scrolls past and the build ships anyway.
+     */
+    throwOnError?: boolean;
 }
 declare class CodegenOrchestrator {
     private readonly generators;
     private readonly cwd;
     private readonly debug;
+    private readonly throwOnError;
     private isGenerating;
     private pendingRegenerations;
     private watcher?;
@@ -314,10 +332,15 @@ interface RouteMapGeneratorConfig {
 }
 
 /**
- * Built-in Generators Export
+ * Contract Generator
+ *
+ * Reads the router, writes `contracts/current.json`, and on a build compares it
+ * against the newest released snapshot.
  *
- * Provides a registry of all built-in generators.
- * Custom generators can be added via .spfnrc.ts configuration.
+ * It is a codegen plugin for the same reason the route map is one: hanging off
+ * `spfn build` and `spfn dev` removes "forgot to regenerate the contract" as a
+ * failure mode. On `dev` it only regenerates — refusing a half-finished route
+ * mid-edit would make the feature unusable — and on `build` it also gates.
  *
  * @example
  * ```typescript
@@ -325,18 +348,103 @@ interface RouteMapGeneratorConfig {
  * import { defineConfig, defineGenerator } from '@spfn/core/codegen';
  *
  * export default defineConfig({
+ *     generators: [
+ *         defineGenerator({
+ *             name: '@spfn/core:contract',
+ *             routerPath: './src/server/router.ts',
+ *             outputDir: './contracts',
+ *         })
+ *     ]
+ * });
+ * ```
+ */
+
+interface ContractGeneratorConfig {
+    /**
+     * Generator name (required for package-based loading)
+     */
+    name: '@spfn/core:contract';
+    /**
+     * Path to the router file (relative to project root)
+     * @example './src/server/router.ts'
+     */
+    routerPath: string;
+    /**
+     * Named export holding the router.
+     * @default 'appRouter', falling back to the default export
+     */
+    routerExport?: string;
+    /**
+     * Directory holding current.json, released/ and usage/ (relative to project root)
+     * @default './contracts'
+     */
+    outputDir?: string;
+    /**
+     * Extra file patterns to watch, for routes outside src/server/routes
+     */
+    additionalRouteDirs?: string[];
+}
+/** Thrown when the build must stop. */
+declare class ContractGeneratorError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Router registration guard
+ *
+ * A contract has to describe what production serves. When a route is registered
+ * only under a feature flag or an environment check, the generated contract
+ * describes whichever way the generator happened to run — and the gate then
+ * compares a promise nobody made.
+ *
+ * Object spread is the one way a key can be conditionally present in the object
+ * `defineRouter()` receives, so that is what this reads. A spread of a plain
+ * identifier (`...baseRoutes`) is unconditional and passes; anything computed
+ * inside the spread does not.
+ */
+/** Thrown when the router registers contracted routes conditionally. */
+declare class ConditionalRegistrationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Refuse a router whose route set depends on a condition.
+ *
+ * @param routerPath - path named in the error message
+ * @param source - contents of the router file
+ */
+declare function assertUnconditionalRegistration(routerPath: string, source: string): void;
+
+/**
+ * Built-in Generators Export
+ *
+ * @example
+ * ```typescript
+ * // .spfnrc.ts
+ * import { defineConfig, defineGenerator } from '@spfn/core/codegen';
+ * import type { RouteMapGeneratorConfig, ContractGeneratorConfig } from '@spfn/core/codegen';
+ *
+ * export default defineConfig({
  *   generators: [
- *     defineGenerator({ path: './my-generator.ts' })
+ *     defineGenerator<RouteMapGeneratorConfig>({
+ *       name: '@spfn/core:route-map',
+ *       routerPath: './src/server/router.ts',
+ *       outputPath: './src/generated/route-map.ts',
+ *     }),
+ *     defineGenerator<ContractGeneratorConfig>({
+ *       name: '@spfn/core:contract',
+ *       routerPath: './src/server/router.ts',
+ *       outputDir: './contracts',
+ *     }),
  *   ]
  * });
  * ```
  */
 
 /**
- * Registry of available generators
- *
- * Used by package-based generator loading (e.g., "@spfn/core:route-map")
+ * @internal
+ * Registry of available generators for package-based loading.
+ * DO NOT use directly - use defineGenerator({ name: '@spfn/core:route-map', ... }) instead.
  */
 declare const generators: Record<string, unknown>;
 
-export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, type GenerationStats, type Generator, type GeneratorConfig, type GeneratorOptions, type GeneratorTrigger, type OrchestratorOptions, type ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, 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 ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };

package/dist/codegen/index.js

@@ -1,9 +1,10 @@
 import { watch } from 'chokidar';
-import { join, dirname, resolve, relative } from 'path';
+import { join, relative, sep, dirname, resolve } from 'path';
 import mm from 'micromatch';
 import { logger } from '@spfn/core/logger';
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { createJiti } from 'jiti';
+import { collectContractDocument, writeCurrentDocument, checkContract, formatViolations } from '@spfn/core/contract';
 
 // src/codegen/core/orchestrator.ts
 var orchestratorLogger = logger.child("@spfn/core:orchestrator");
@@ -11,6 +12,7 @@ var CodegenOrchestrator = class {
   generators;
   cwd;
   debug;
+  throwOnError;
   isGenerating = false;
   pendingRegenerations = /* @__PURE__ */ new Set();
   watcher;
@@ -19,6 +21,7 @@ var CodegenOrchestrator = class {
     this.generators = options.generators;
     this.cwd = options.cwd ?? process.cwd();
     this.debug = options.debug ?? false;
+    this.throwOnError = options.throwOnError ?? false;
   }
   /**
    * Close watcher and cleanup resources
@@ -80,6 +83,9 @@ var CodegenOrchestrator = class {
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
         orchestratorLogger.error(`[${generator.name}] \u2717 Generation failed`, err);
+        if (this.throwOnError) {
+          throw err;
+        }
       }
     }
   }
@@ -111,8 +117,10 @@ var CodegenOrchestrator = class {
       });
     }
     this.watcher = watch(watchDirs, {
-      ignored: /(^|[\/\\])\../,
-      // ignore dotfiles
+      // Ignore dotfiles by path segments relative to cwd — matching the absolute
+      // path would ignore everything when the checkout itself lives under a dot
+      // directory (e.g. .claude/worktrees/<name>), leaving zero watched files
+      ignored: (watchedPath) => relative(this.cwd, watchedPath).split(sep).some((segment) => segment.startsWith(".") && segment !== "." && segment !== ".."),
       persistent: true,
       ignoreInitial: true,
       awaitWriteFinish: {
@@ -276,6 +284,11 @@ async function createGeneratorsFromConfig(config, cwd) {
   }
   for (const generatorConfig of config.generators) {
     try {
+      if ("generate" in generatorConfig && typeof generatorConfig.generate === "function") {
+        generators2.push(generatorConfig);
+        configLogger.info(`Generator instance added: ${generatorConfig.name}`);
+        continue;
+      }
       if ("path" in generatorConfig) {
         const generatorPath = generatorConfig.path.startsWith(".") ? join(cwd, generatorConfig.path) : generatorConfig.path;
         configLogger.info(`Loading custom generator: ${generatorPath}`);
@@ -351,17 +364,27 @@ function parseRouterFile(routerPath) {
     let match;
     while ((match = importPattern.exec(content)) !== null) {
       const importPath = match[1];
-      if (importPath.includes("route")) {
+      if (importPath.startsWith(".")) {
         importPaths.push(importPath);
       }
     }
-    const routerPattern = /defineRouter\s*\(\s*\{([^}]+)\}/s;
-    const routerMatch = routerPattern.exec(content);
-    if (routerMatch) {
-      const routerContent = routerMatch[1];
-      const namePattern = /(\w+)\s*[,}]/g;
-      while ((match = namePattern.exec(routerContent)) !== null) {
-        routeNames.push(match[1]);
+    const defineRouterStart = content.indexOf("defineRouter(");
+    if (defineRouterStart !== -1) {
+      const braceStart = content.indexOf("{", defineRouterStart);
+      if (braceStart !== -1) {
+        let depth = 1;
+        let braceEnd = braceStart + 1;
+        while (depth > 0 && braceEnd < content.length) {
+          if (content[braceEnd] === "{") depth++;
+          else if (content[braceEnd] === "}") depth--;
+          braceEnd++;
+        }
+        const routerContent = content.slice(braceStart + 1, braceEnd - 1);
+        const withoutComments = routerContent.replace(/\/\/[^\n]*/g, "");
+        const namePattern = /^\s*(\w+)\s*[,\n]/gm;
+        while ((match = namePattern.exec(withoutComments)) !== null) {
+          routeNames.push(match[1]);
+        }
       }
     }
   } catch (error) {
@@ -404,6 +427,17 @@ function createRouteMapGenerator(config) {
     outputPath = "./src/generated/route-map.ts",
     additionalRouteDirs = []
   } = config;
+  if (!routerPath) {
+    throw new Error(
+      `[@spfn/core:route-map] Missing required "routerPath" option.
+
+Usage:
+  defineGenerator<RouteMapGeneratorConfig>({
+    name: '@spfn/core:route-map',
+    routerPath: './src/server/router.ts',
+  })`
+    );
+  }
   return {
     name: "@spfn/core:route-map",
     watchPatterns: [
@@ -412,7 +446,7 @@ function createRouteMapGenerator(config) {
       "src/server/routes/**/*.ts",
       ...additionalRouteDirs.map((dir) => `${dir}/**/*.ts`)
     ],
-    runOn: ["watch", "build", "start", "manual"],
+    runOn: ["watch", "manual", "build"],
     async generate(options) {
       const { cwd, debug } = options;
       const absoluteRouterPath = join(cwd, routerPath);
@@ -433,7 +467,17 @@ function createRouteMapGenerator(config) {
       for (const importPath of importPaths) {
         let resolvedPath = resolve(routerDir, importPath);
         if (!resolvedPath.endsWith(".ts")) {
-          resolvedPath += ".ts";
+          const withTs = resolvedPath + ".ts";
+          if (existsSync(withTs)) {
+            resolvedPath = withTs;
+          } else {
+            const indexPath = join(resolvedPath, "index.ts");
+            if (existsSync(indexPath)) {
+              resolvedPath = indexPath;
+            } else {
+              resolvedPath = withTs;
+            }
+          }
         }
         if (existsSync(resolvedPath)) {
           const routes = parseRouteFile(resolvedPath);
@@ -458,11 +502,164 @@ function createRouteMapGenerator(config) {
   };
 }
 
+// src/codegen/generators/contract-guard.ts
+var ConditionalRegistrationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConditionalRegistrationError";
+  }
+};
+function defineRouterBlock(source) {
+  const start = source.indexOf("defineRouter(");
+  if (start === -1) {
+    return void 0;
+  }
+  const open = source.indexOf("{", start);
+  if (open === -1) {
+    return void 0;
+  }
+  let depth = 1;
+  let cursor = open + 1;
+  while (depth > 0 && cursor < source.length) {
+    if (source[cursor] === "{") depth++;
+    else if (source[cursor] === "}") depth--;
+    cursor++;
+  }
+  return source.slice(open + 1, cursor - 1).replace(/\/\/[^\n]*/g, "");
+}
+var PLAIN_REFERENCE = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*\s*$/;
+function assertUnconditionalRegistration(routerPath, source) {
+  const block = defineRouterBlock(source);
+  if (!block) {
+    return;
+  }
+  for (const [, expression] of block.matchAll(/\.\.\.\s*([^,\n]+)/g)) {
+    if (PLAIN_REFERENCE.test(expression)) {
+      continue;
+    }
+    throw new ConditionalRegistrationError(
+      `${routerPath} registers routes conditionally: "...${expression.trim()}".
+
+A contract has to describe what production serves. When the route set depends on a flag or an environment, the generated contract describes whichever way the generator happened to run.
+Register contracted routes unconditionally, and gate behaviour inside the handler instead.`
+    );
+  }
+}
+
+// src/codegen/generators/contract.ts
+var genLogger2 = logger.child("@spfn/core:contract-generator");
+var ContractGeneratorError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractGeneratorError";
+  }
+};
+function isRouter(value) {
+  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
+}
+function loadRouter(cwd, absoluteRouterPath, routerExport) {
+  let module;
+  try {
+    const jiti = createJiti(cwd, { interopDefault: true, moduleCache: false });
+    module = jiti(absoluteRouterPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ContractGeneratorError(
+      `Failed to load ${relative(cwd, absoluteRouterPath)}: ${message}
+
+The contract is read from the loaded router, so a route module must be importable without side effects. Check that nothing at module scope opens a connection or reads a missing environment value.`
+    );
+  }
+  const candidates = routerExport ? [routerExport] : ["appRouter", "default", "router"];
+  for (const name of candidates) {
+    const candidate = module[name];
+    if (isRouter(candidate)) {
+      return candidate;
+    }
+  }
+  throw new ContractGeneratorError(
+    `No router found in ${relative(cwd, absoluteRouterPath)}. Looked for: ${candidates.join(", ")}. Set "routerExport" to the export holding the defineRouter() result.`
+  );
+}
+function pinNodeEnv() {
+  if (!process.env.NODE_ENV) {
+    process.env.NODE_ENV = "production";
+    genLogger2.info('NODE_ENV was unset; pinned to "production" so the contract does not depend on the shell');
+  }
+}
+function createContractGenerator(config) {
+  const {
+    routerPath,
+    routerExport,
+    outputDir = "./contracts",
+    additionalRouteDirs = []
+  } = config;
+  if (!routerPath) {
+    throw new Error(
+      `[@spfn/core:contract] Missing required "routerPath" option.
+
+Usage:
+  defineGenerator<ContractGeneratorConfig>({
+    name: '@spfn/core:contract',
+    routerPath: './src/server/router.ts',
+  })`
+    );
+  }
+  return {
+    name: "@spfn/core:contract",
+    watchPatterns: [
+      routerPath,
+      "src/server/routes/**/*.ts",
+      ...additionalRouteDirs.map((dir) => `${dir}/**/*.ts`)
+    ],
+    runOn: ["watch", "build", "manual"],
+    async generate(options) {
+      const { cwd } = options;
+      const absoluteRouterPath = join(cwd, routerPath);
+      const contractsDir = join(cwd, outputDir);
+      if (!existsSync(absoluteRouterPath)) {
+        throw new ContractGeneratorError(
+          `Router file not found: ${routerPath}. The contract generator is configured but has nothing to read.`
+        );
+      }
+      pinNodeEnv();
+      assertUnconditionalRegistration(routerPath, readFileSync(absoluteRouterPath, "utf-8"));
+      const router = loadRouter(cwd, absoluteRouterPath, routerExport);
+      const document = collectContractDocument(router);
+      const changed = writeCurrentDocument(contractsDir, document);
+      genLogger2.info(
+        `${changed ? "Wrote" : "Verified"} ${relative(cwd, join(contractsDir, "current.json"))} (${document.operations.length} contracted operation(s))`
+      );
+      if (options.trigger?.type !== "build") {
+        return;
+      }
+      const result = checkContract(contractsDir, document);
+      for (const warning of result.warnings) {
+        genLogger2.warn(warning);
+      }
+      if (result.violations.length === 0) {
+        if (result.baselineVersion) {
+          genLogger2.info(`Contract is backward compatible with released ${result.baselineVersion}`);
+        }
+        return;
+      }
+      throw new ContractGeneratorError(
+        `This build breaks the contract released as ${result.baselineVersion}:
+
+${formatViolations(result.violations)}
+
+A released client cannot be fixed by redeploying the server. Keep the promise, or cut a new contract version and let the old operation stay until no released app calls it.`
+      );
+    }
+  };
+}
+
 // src/codegen/generators/index.ts
 var generators = {
-  "route-map": createRouteMapGenerator
+  "route-map": createRouteMapGenerator,
+  contract: createContractGenerator
 };
 
-export { CodegenOrchestrator, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
+export { CodegenOrchestrator, ConditionalRegistrationError, ContractGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map