@specverse/engines 6.6.3 → 6.11.2

package/libs/instance-factories/services/templates/prisma/ai-behaviors-generator.ts

@@ -46,6 +46,85 @@ async function validateTypeScript(code: string): Promise<string | null> {
   }
 }
 
+/**
+ * Type-check the generated body in isolation using the TypeScript compiler
+ * API. Returns null if clean, or a concise error string suitable for
+ * passing back to the LLM as a fix-up hint. Skipped silently if the `typescript`
+ * package isn't installed (the realize pipeline still runs full tsc against
+ * the realized output downstream — this is a faster, generator-side filter
+ * to catch the most common LLM mistakes before they hit the user).
+ *
+ * Why bother: the LLM regularly emits patterns that are valid syntax but
+ * fail strict tsc — RegExp index access (`m[1]` is `string | undefined`),
+ * unused locals, undefined references. Reprompting with the tsc error
+ * lets the LLM self-correct without burning a per-step retry.
+ */
+async function validateTypeScriptTypes(code: string): Promise<string | null> {
+  let ts: any;
+  try {
+    ts = await import('typescript');
+    if (ts.default) ts = ts.default;
+  } catch {
+    return null;  // typescript not available — skip
+  }
+  try {
+    const fileName = 'aiBehavior.ts';
+    const sourceFile = ts.createSourceFile(fileName, code, ts.ScriptTarget.ES2022, true);
+    // Mirror the strict shape used by the realized backend's tsconfig so
+    // a body that passes here also passes downstream. Failing to match the
+    // realized strictness means we'd ship code that fails user-side tsc
+    // (defeating the whole point of generator-side validation).
+    const compilerOptions: any = {
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      strict: true,
+      noImplicitAny: false,  // body uses `any` extensively for inputs
+      noUnusedLocals: true,
+      noUnusedParameters: true,
+      noImplicitReturns: true,
+      noUncheckedIndexedAccess: true,
+      noFallthroughCasesInSwitch: true,
+      noEmit: true,
+      skipLibCheck: true,
+      types: [],
+      // Without `lib`, tsc can't resolve Promise / Array / RegExp etc., and
+      // every body fails the basic-types check before it even gets to the
+      // strict-null-check rules we actually want to validate.
+      lib: ['lib.es2022.d.ts'],
+    };
+    const defaultHost = ts.createCompilerHost(compilerOptions);
+    const host: any = {
+      ...defaultHost,
+      getSourceFile: (n: string, target: any) => {
+        if (n === fileName) return sourceFile;
+        return defaultHost.getSourceFile(n, target);
+      },
+      writeFile: () => {},
+      fileExists: (n: string) => n === fileName || defaultHost.fileExists(n),
+      readFile: (n: string) => (n === fileName ? code : defaultHost.readFile(n)),
+    };
+    const program = ts.createProgram([fileName], compilerOptions, host);
+    const diagnostics = [
+      ...program.getSyntacticDiagnostics(sourceFile),
+      ...program.getSemanticDiagnostics(sourceFile),
+    ];
+    if (diagnostics.length === 0) return null;
+    const formatted = diagnostics.slice(0, 5).map((d: any) => {
+      const msg = ts.flattenDiagnosticMessageText(d.messageText, '\n');
+      const pos = d.file && d.start !== undefined
+        ? d.file.getLineAndCharacterOfPosition(d.start)
+        : null;
+      return pos
+        ? `line ${pos.line + 1}, col ${pos.character + 1}: ${msg}`
+        : msg;
+    });
+    return formatted.join('; ');
+  } catch {
+    return null;  // never let validation crash the generator
+  }
+}
+
 /**
  * AI output cache — avoids re-calling Claude for unchanged steps.
  *
@@ -56,7 +135,7 @@ async function validateTypeScript(code: string): Promise<string | null> {
  * produces a new hash. The prompt version is part of the hash so
  * prompt upgrades also invalidate.
  */
-const PROMPT_VERSION = '9.1.0';
+const PROMPT_VERSION = '9.2.0';
 
 function cacheKey(step: string, modelName: string, operationName: string, functionName: string, inputs: string[]): string {
   const payload = JSON.stringify({ step, modelName, operationName, functionName, inputs: [...inputs].sort(), v: PROMPT_VERSION });
@@ -94,10 +173,33 @@ function cacheWrite(key: string, body: string): void {
  *
  * This is async — it calls the AI engine to generate function bodies.
  */
-export default async function generateAiBehaviors(context: TemplateContext): Promise<string> {
+/** Optional matcher for orm-agnostic step matching. When present, this is
+ * used in place of the prisma library's `matchStep` so that the unmatched
+ * functions' names + inputs are computed by the same conventions library
+ * the consuming controller is using. Without this, mongo-native (or any
+ * non-prisma) controllers would diverge: they'd emit `aiBehaviors.X` calls
+ * with one inputs set while this generator would emit a function with a
+ * different signature. */
+type StepMatcher = (step: string, ctx: any) => {
+  matched: boolean;
+  call?: string;
+  helperMethod?: string;
+  functionName?: string;
+  inputs?: string[];
+  resultVar?: string;
+};
+
+export default async function generateAiBehaviors(
+  context: TemplateContext,
+  matcher?: StepMatcher,
+): Promise<string> {
   const { controller, model } = context;
   if (!controller?.actions) return '';
 
+  // Default matcher = prisma's matchStep for back-compat. Mongo-native
+  // (and any future ORM) passes its own matcher.
+  const stepMatcher: StepMatcher = matcher || (matchStep as any);
+
   const modelName = model?.name || controller.model || 'Model';
   const modelVar = modelName.charAt(0).toLowerCase() + modelName.slice(1);
   // List of all entity-model names available in the realized output. Forwarded
@@ -155,7 +257,7 @@ export default async function generateAiBehaviors(context: TemplateContext): Pro
         resultName: stepAs,
       };
 
-      const result = matchStep(stepText, ctx);
+      const result = stepMatcher(stepText, ctx);
       if (!result.matched && result.functionName) {
         // Avoid duplicate function definitions
         const existing = unmatchedFunctions.find(f => f.functionName === result.functionName);
@@ -229,15 +331,107 @@ export async function generateAiBehaviorsFile(opts: {
   let cacheHits = 0;
   let cacheMisses = 0;
   for (const { functionName, step, operationName, parameterNames, inputs, returns, modelName } of unmatchedFunctions) {
-    // Pure function signature: all inputs as a typed destructured object
-    const signature = inputs.length > 0
-      ? `input: { ${inputs.map(n => `${n}: any`).join('; ')} }`
-      : 'input: Record<string, never>';
-
-    // Inside the body, destructure for readability
-    const destructure = inputs.length > 0
-      ? `  const { ${inputs.join(', ')} } = input;`
-      : '';
+    // Pure function signature + destructure are built AFTER the body so we
+    // can match what the LLM actually references — strict tsc's
+    // noUnusedLocals / noUnusedParameters fire on every input the body
+    // didn't touch. We tolerate underuse rather than re-prompting the LLM:
+    // the body is correct as-is, we just trim the wrapper to fit it.
+    //
+    // Three cases:
+    //   - body uses some inputs: destructure only those
+    //   - body uses none directly but references `input.X`: keep `input`
+    //   - body doesn't touch input at all: prefix signature with `_` so
+    //     noUnusedParameters is happy
+    /** Strip string/template/comment content so identifier-reference checks
+     * don't match `reward` inside a kebab-case string like `'reward-not-granted'`
+     * or `// reward stays as text`. We replace the literal contents with
+     * spaces so positions stay roughly aligned in case of debugging.
+     *
+     * Critical: template-string `${...}` interpolations are EXPRESSIONS, not
+     * literal text — they really do reference `input.X` etc. Strip only the
+     * non-interpolation segments of the template so the expression content
+     * survives the regex check. */
+    const stripLiteralsAndComments = (src: string): string => {
+      let out = src
+        .replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length))
+        .replace(/\/\/[^\n]*/g, (m) => ' '.repeat(m.length))
+        .replace(/(['"])(?:\\.|(?!\1).)*\1/g, (m) => m[0] + ' '.repeat(m.length - 2) + m[0]);
+      // Strip text INSIDE backticks but preserve `${...}` expressions.
+      // We rebuild template contents by replacing literal-text spans
+      // (everything between `\`` and `${`, between `}` and `${`, or
+      // between `}` and the closing `\``) with spaces.
+      out = out.replace(/`((?:\\.|\$\{[^}]*\}|(?!`).)*)`/g, (full, content) => {
+        // Walk the content, copy `${...}` segments verbatim, replace other
+        // characters with spaces.
+        let result = '`';
+        let i = 0;
+        while (i < content.length) {
+          if (content[i] === '\\' && i + 1 < content.length) {
+            result += '  '; i += 2; continue;
+          }
+          if (content[i] === '$' && content[i + 1] === '{') {
+            // copy interpolation verbatim including the `${...}` markers
+            const end = content.indexOf('}', i);
+            const slice = end >= 0 ? content.slice(i, end + 1) : content.slice(i);
+            result += slice;
+            i += slice.length;
+            continue;
+          }
+          result += ' ';
+          i++;
+        }
+        return result + '`';
+      });
+      return out;
+    };
+
+    /** Detect whether the body manages its own input access (so adding our
+     * own destructure would either duplicate-declare or leave us with
+     * unused-locals). Three shapes the LLM emits:
+     *   1. `const { X, Y } = input;`           (destructure)
+     *   2. `const X = input.X;`                (per-property)
+     *   3. `const _X = input.X;`               (per-property with rename)
+     * If ANY of these appear, the body is its own input setup and we
+     * should leave it alone. */
+    const bodyHandlesInputItself = (body: string): boolean => {
+      const codeOnly = stripLiteralsAndComments(body);
+      // Destructure: `const { ... } = input;`
+      if (/(?:const|let|var)\s*\{[^}]+\}\s*=\s*input\b/.test(codeOnly)) return true;
+      // Per-property access: any `(const|let|var) <name> = input.<name>`
+      if (/(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*input\.[A-Za-z_$][\w$]*/.test(codeOnly)) return true;
+      return false;
+    };
+
+    /** Does the body actually USE the local variable `n` (vs only mention
+     * it as an object-literal property name like `step1Result:` in a
+     * return object)? A real usage is `n` followed by something other than
+     * `:` — i.e. accessed in an expression. We approximate by requiring
+     * the next non-whitespace char to be a code-meaningful operator/end. */
+    const isRealReference = (n: string, codeOnly: string): boolean => {
+      const escaped = n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const re = new RegExp(`(?<![A-Za-z0-9_$])${escaped}(?![A-Za-z0-9_$:])`, 'g');
+      return re.test(codeOnly);
+    };
+
+    const buildSignatureAndDestructure = (body: string): { signature: string; destructure: string } => {
+      if (inputs.length === 0) {
+        return { signature: 'input: Record<string, never>', destructure: '' };
+      }
+      const codeOnly = stripLiteralsAndComments(body);
+      const referenced = inputs.filter((n) => isRealReference(n, codeOnly));
+      const usesInputObject = /(?<![A-Za-z0-9_$])input(?![A-Za-z0-9_$])/.test(codeOnly);
+      const sigName = (referenced.length > 0 || usesInputObject) ? 'input' : '_input';
+      const sig = `${sigName}: { ${inputs.map(n => `${n}: any`).join('; ')} }`;
+      // If the body already manages its own input access (destructure or
+      // per-property) OR accesses input.X directly, don't add a wrapper
+      // destructure — would leave us with unused locals (TS6198) or
+      // duplicate declarations (TS2451).
+      const bodyAccessesInputProps = /(?<![A-Za-z0-9_$])input\.[A-Za-z_$]/.test(codeOnly);
+      const destructure = (referenced.length > 0 && !bodyHandlesInputItself(body) && !bodyAccessesInputProps)
+        ? `  const { ${referenced.join(', ')} } = input;`
+        : '';
+      return { signature: sig, destructure };
+    };
 
     // Build return type from spec declaration (if provided)
     // returns can be:
@@ -258,11 +452,14 @@ export async function generateAiBehaviorsFile(opts: {
     let source: 'AI-CACHED' | 'AI-GENERATED' | 'AI-INVALID' | 'STUB' = body ? 'AI-CACHED' : 'STUB';
     if (body) {
       // Validate cache entry — a previously valid entry may have been
-      // corrupted on disk or the validator rules may have changed
+      // corrupted on disk OR the validation rules may have tightened
+      // (e.g. tsc type checks added). A cache hit must still be re-validated
+      // through both gates so old bodies don't leak past the new bar.
       const testCode = `export async function ${functionName}(input: any): Promise<any> {\n${body}\n}`;
-      const validationError = await validateTypeScript(testCode);
-      if (validationError) {
-        console.warn(`      [ai-validate] cached ${functionName} failed validation: ${validationError}`);
+      const syntaxError = await validateTypeScript(testCode);
+      const typeError = syntaxError ? null : await validateTypeScriptTypes(testCode);
+      if (syntaxError || typeError) {
+        console.warn(`      [ai-validate] cached ${functionName} failed validation: ${syntaxError || typeError}`);
         body = null;  // Force regeneration
         source = 'STUB';
       } else {
@@ -285,17 +482,62 @@ export async function generateAiBehaviorsFile(opts: {
         });
 
         if (body) {
-          // Validate the generated body as a standalone function
+          // Two-tier validation:
+          //   1. esbuild syntax check — fast, catches unbalanced braces, etc.
+          //   2. tsc type check — slower, catches `string | undefined` index
+          //      access, unused locals, and undefined references the LLM
+          //      regularly produces. On tsc failure, we re-prompt the LLM
+          //      with the error message appended; only ONE retry to bound
+          //      cost. If that still fails we keep the body but mark it
+          //      AI-INVALID so the user sees it needs review.
           const testCode = `export async function ${functionName}(input: any): Promise<any> {\n${body}\n}`;
-          const validationError = await validateTypeScript(testCode);
-          if (validationError) {
-            console.warn(`      [ai-validate] ${functionName} has syntax error: ${validationError}`);
-            // Don't cache invalid output; treat as failed generation
-            body = `// AI-generated code failed validation: ${validationError}\n  // Step: ${step}\n  throw new Error('AI behavior has invalid syntax — see comment above');`;
+          const syntaxError = await validateTypeScript(testCode);
+          if (syntaxError) {
+            console.warn(`      [ai-validate] ${functionName} has syntax error: ${syntaxError}`);
+            body = `// AI-generated code failed validation: ${syntaxError}\n  // Step: ${step}\n  throw new Error('AI behavior has invalid syntax — see comment above');`;
             source = 'AI-INVALID';
           } else {
-            source = 'AI-GENERATED';
-            cacheWrite(key, body);
+            const typeError = await validateTypeScriptTypes(testCode);
+            if (typeError) {
+              console.warn(`      [ai-validate] ${functionName} type errors: ${typeError}`);
+              try {
+                const retryHint = `Your previous output produced TypeScript type errors:\n${typeError}\n\nFix these specifically — common causes:\n- RegExp match indices are 'string | undefined'; use non-null assertion or extract to a typed variable\n- Strict null checks: guard or assert before use\n- Don't declare locals you never reference\n\nIMPORTANT: The destructure line \`const { ... } = input;\` is added by the wrapper, NOT by you. Output ONLY the function body that goes AFTER that line — do not repeat the destructure or you will produce duplicate-declaration errors.`;
+                const retried = await aiService.generateBehavior({
+                  step: `${step}\n\n${retryHint}`,
+                  modelName,
+                  operationName,
+                  functionName,
+                  parameterNames: inputs,
+                  availableModels,
+                  spec,
+                  returnType,
+                });
+                if (retried) {
+                  const retryCode = `export async function ${functionName}(input: any): Promise<any> {\n${retried}\n}`;
+                  const retrySyntaxError = await validateTypeScript(retryCode);
+                  const retryTypeError = retrySyntaxError ? null : await validateTypeScriptTypes(retryCode);
+                  if (!retrySyntaxError && !retryTypeError) {
+                    body = retried;
+                    source = 'AI-GENERATED';
+                    cacheWrite(key, body);
+                  } else {
+                    // Retry didn't help — keep the original body so the user can fix
+                    // manually, but mark it as INVALID so it stands out.
+                    source = 'AI-INVALID';
+                    cacheWrite(key, body);
+                  }
+                } else {
+                  source = 'AI-INVALID';
+                  cacheWrite(key, body);
+                }
+              } catch {
+                source = 'AI-INVALID';
+                cacheWrite(key, body);
+              }
+            } else {
+              source = 'AI-GENERATED';
+              cacheWrite(key, body);
+            }
           }
         }
       } catch {
@@ -335,8 +577,14 @@ ${inputsDoc}${returnsDoc} * Source: ${source}
    ? 'AI returned code with syntax errors — function throws at runtime. Fix or regenerate.'
    : 'STUB — Claude CLI unavailable. Install Claude Code or implement manually.'}
  */
-export async function ${functionName}(${signature}): Promise<${returnType}> {
-${destructure ? destructure + '\n' : ''}${body}
+export async function ${functionName}(${(() => {
+  const { signature: sig } = buildSignatureAndDestructure(body);
+  return sig;
+})()}): Promise<${returnType}> {
+${(() => {
+  const { destructure } = buildSignatureAndDestructure(body);
+  return destructure ? destructure + '\n' : '';
+})()}${body}
 }`);
   }
 
@@ -356,27 +604,28 @@ ${destructure ? destructure + '\n' : ''}${body}
  * These functions could not be generated from convention patterns.
  * They are called by ${ownerName} when executing operations.
  *
+ * PURE-FUNCTION CONTRACT — these bodies must NOT touch the database, the
+ * event bus, or any external service. Persistence and side effects happen
+ * in the calling controller; this file does pure transformations only.
+ *
  * Options for each function:
  * - Implement manually (recommended for business-critical logic)
  * - Use AI generation: specverse ai generate <function>
  * - Refactor the spec step to use a convention pattern
  *
- * Convention patterns that ARE auto-generated (no AI needed):
- *   "Find {Model} by {field}" → prisma.model.findUniqueOrThrow(...)
- *   "Create {Model}" → prisma.model.create(...)
- *   "Update {Model} {field} to {value}" → prisma.model.update(...)
- *   "Delete {Model}" → prisma.model.delete(...)
- *   "Transition {Model} to {state}" → prisma.model.update({ status: ... })
- *   "Count {Model}s per {Group}" → prisma.model.groupBy(...)
- *   See step-conventions.ts for the full list.
+ * Convention patterns that ARE auto-generated by the realize engine (no
+ * AI needed) — these are emitted inline in the controller, not here:
+ *   "Find {Model} by {field}" → ORM-specific find call
+ *   "Create {Model}"          → ORM-specific create call
+ *   "Update {Model} {field} to {value}"
+ *   "Delete {Model}"
+ *   "Transition {Model} to {state}"
+ *   "Count {Model}s per {Group}"
+ *   See the ORM's step-conventions module for the full list.
  *
  * Generated: ${new Date().toISOString().split('T')[0]}
  */
 
-import { PrismaClient } from '@prisma/client';
-
-const prisma = new PrismaClient();
-
 ${functions.join('\n\n')}
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "6.6.3",
+  "version": "6.11.2",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry, bundles",
   "type": "module",
   "main": "dist/index.js",
@@ -62,26 +62,26 @@
     "@ai-sdk/openai-compatible": "^2.0.41",
     "@ai-sdk/provider": "^3.0.8",
     "@specverse/assets": "^1.6.0",
-    "@specverse/engines": "^6.6.1",
-    "@specverse/entities": "^5.1.0",
+    "@specverse/engines": "^6.8.7",
+    "@specverse/entities": "^5.2.2",
     "@specverse/runtime": "^5.0.1",
     "@specverse/types": "^5.1.0",
     "ai": "^6.0.168",
     "ajv": "^8.17.0",
     "ajv-formats": "^2.1.0",
+    "esbuild": "^0.25.0",
     "glob": "^10.0.0",
     "graphology": "^0.26.0",
     "graphology-communities-louvain": "^2.0.2",
     "handlebars": "^4.7.9",
     "js-yaml": "^4.1.0",
     "semver": "^7.0.0",
+    "typescript": "^5.4.0",
     "yaml": "^2.8.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "esbuild": "^0.25.0",
-    "typescript": "^5.4.0"
+    "@types/node": "^25.5.0"
   },
   "files": [
     "dist",