@specverse/engines 6.65.0 → 6.75.0

package/libs/instance-factories/services/templates/mongodb-native/controller-generator.ts

@@ -48,12 +48,20 @@ export default function generateMongoNativeController(context: TemplateContext):
 
   const customActions = generateCustomActions(controller, modelRegistry);
 
-  const validate = generateValidateMethod(model, modelName);
-  const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, collection) : '';
+  // Phase 2 — the guards module only exists for models with declared
+  // constraints, so the import + validate() call site are gated on this
+  // flag. Computed up-front so generateValidateMethod / generateEvolveMethod
+  // / generateDeleteMethod can emit runConstraintGuards.
+  const hasConstraints =
+    Array.isArray((model as any).constraints) &&
+    (model as any).constraints.length > 0;
+
+  const validate = generateValidateMethod(model, modelName, hasConstraints);
+  const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, collection, hasConstraints) : '';
   const retrieve = curedOps.retrieve ? generateRetrieveMethod(modelName, modelVar, collection) : '';
-  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar, collection) : '';
-  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, collection) : '';
-  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar, collection) : '';
+  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar, collection, hasConstraints) : '';
+  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, collection, hasConstraints) : '';
+  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar, collection, hasConstraints) : '';
 
   const hasEventPublishing =
     curedOps.create || curedOps.update || curedOps.evolve || curedOps.delete;
@@ -67,6 +75,7 @@ import { ObjectId, type Filter, type Document } from 'mongodb';
 import { getCollection } from '../db/mongoClient.js';
 ${hasEventPublishing || customActions.needsAiBehaviors ? `import { eventBus } from '../events/eventBus.js';` : ''}
 ${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${controllerName}.ai.js';` : ''}
+${hasConstraints ? `import { runGuards as runConstraintGuards } from './${modelName}.guards.js';` : ''}
 
 const COLLECTION_NAME = '${collection}';
 
@@ -107,17 +116,48 @@ function collectionName(model: any): string {
   return model.name.toLowerCase() + 's';
 }
 
-function generateValidateMethod(model: any, modelName: string): string {
+/**
+ * Phase 2 — when the model has declared constraints, validate() ALSO
+ * calls runConstraintGuards from the per-model .guards.ts and appends
+ * any constraint violation messages to errors[]. Op union widens to
+ * include 'delete' + evolve.<transition>.
+ */
+function generateValidateMethod(model: any, modelName: string, hasConstraints: boolean): string {
+  const opTypeUnion = hasConstraints
+    ? `'create' | 'update' | 'evolve' | 'delete' | \`evolve.\${string}\``
+    : `'create' | 'update' | 'evolve'`;
+
+  const constraintsCheck = hasConstraints
+    ? `
+    // Phase 2 — run model.constraints[] guards matching this operation.
+    // Slice 15b — ctx carries a per-model query helper for subquery sugars.
+    const __guardCtx = {
+      query: (modelName: string) => ({
+        exists: async (predicate: (e: any) => boolean) => {
+          const __col = await getCollection(modelName.toLowerCase() + 's');
+          const all = await __col.find({}).toArray();
+          return all.some(predicate);
+        },
+      }),
+    };
+    const constraintViolations = await runConstraintGuards(_data, _context.operation, _actor, __guardCtx);
+    for (const v of constraintViolations) errors.push(v.message);`
+    : '';
+
+  // Phase 2 actor wiring + Slice 15b — validate is async (awaits subquery
+  // execution in guard ctx); callers must await this.validate(...).
+
   return `
   /**
-   * Validate ${modelName} data — runs before create / update / evolve.
+   * Validate ${modelName} data — runs before create / update / evolve / delete.
    */
-  public validate(
+  public async validate(
     _data: any,
-    _context: { operation: 'create' | 'update' | 'evolve' }
-  ): { valid: boolean; errors: string[] } {
+    _context: { operation: ${opTypeUnion} },
+    _actor: any = null
+  ): Promise<{ valid: boolean; errors: string[] }> {
     const errors: string[] = [];
-${generateValidationLogic(model)}
+${generateValidationLogic(model)}${constraintsCheck}
     return { valid: errors.length === 0, errors };
   }
 `;
@@ -148,13 +188,25 @@ function generateValidationLogic(model: any): string {
   return out.join('\n') || '    // No validation rules defined';
 }
 
-function generateCreateMethod(model: any, modelName: string, modelVar: string, collection: string): string {
+function generateCreateMethod(model: any, modelName: string, modelVar: string, collection: string, hasConstraints: boolean = false): string {
+  const belongsToLoad = hasConstraints ? generateMongoBelongsToLoad(model) : '';
+  const validateSelf = belongsToLoad ? '__mergedSelf' : 'data';
+
   return `
   /**
    * Create a new ${modelName}.
    */
-  public async create(data: any): Promise<any> {
-    const validation = this.validate(data, { operation: 'create' });
+  public async create(data: any, _actor: any = null): Promise<any> {
+${belongsToLoad ? `
+    // Phase 2 Slice 15 — Create-time relation loading. Mirrors prisma's
+    // pattern: for each belongsTo FK in input, load the related doc and
+    // merge into self so constraint guards traversing self.<rel> see
+    // the full related entity, not just the FK id.
+    const __loadedRels: Record<string, any> = {};
+    ${belongsToLoad}
+    const __mergedSelf = { ...data, ...__loadedRels };
+` : ''}
+    const validation = await this.validate(${validateSelf}, { operation: 'create' }, _actor);
     if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
 
     const collection = await getCollection(COLLECTION_NAME);
@@ -167,6 +219,28 @@ function generateCreateMethod(model: any, modelName: string, modelVar: string, c
 `;
 }
 
+function generateMongoBelongsToLoad(model: any): string {
+  const rels = Array.isArray(model.relationships)
+    ? model.relationships
+    : Object.values(model.relationships || {});
+  const belongsToRels = (rels as any[]).filter(r => r.type === 'belongsTo');
+  if (belongsToRels.length === 0) return '';
+
+  return belongsToRels.map((rel: any) => {
+    const relName = rel.name;
+    const targetName = rel.target;
+    const fkField = `${relName}Id`;
+    // Mongo collections are typically named after the model in some casing.
+    // Use the same convention the rest of the generator uses (COLLECTION_NAME
+    // is per-controller). For cross-model loads, use the target's plural-ish
+    // collection name. Since collection naming varies, we use a runtime helper.
+    return `if (data.${fkField}) {
+      const __col_${relName} = await getCollection('${targetName.toLowerCase()}s');
+      __loadedRels.${relName} = await __col_${relName}.findOne(byId(data.${fkField}));
+    }`;
+  }).join('\n    ');
+}
+
 function generateRetrieveMethod(modelName: string, modelVar: string, collection: string): string {
   return `
   /**
@@ -190,13 +264,23 @@ function generateRetrieveMethod(modelName: string, modelVar: string, collection:
 `;
 }
 
-function generateUpdateMethod(modelName: string, modelVar: string, collection: string): string {
+function generateUpdateMethod(modelName: string, modelVar: string, collection: string, hasConstraints: boolean = false): string {
   return `
   /**
    * Update ${modelName}.
    */
-  public async update(id: string, data: any): Promise<any> {
-    const validation = this.validate(data, { operation: 'update' });
+  public async update(id: string, data: any, _actor: any = null): Promise<any> {
+    const collection = await getCollection(COLLECTION_NAME);
+${hasConstraints ? `
+    // Phase 2 — Update self-from-DB. Load + merge before validate so
+    // update-time constraints see the full entity, not just the partial input.
+    const __existing = await collection.findOne(byId(id));
+    if (!__existing) throw new Error('${modelName} not found');
+    const __merged = { ...__existing, ...data };
+    const validation = await this.validate(__merged, { operation: 'update' }, _actor);
+` : `
+    const validation = await this.validate(data, { operation: 'update' }, _actor);
+`}
     if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
 
     // Strip nested objects + id — only scalar fields are written.
@@ -208,7 +292,6 @@ function generateUpdateMethod(modelName: string, modelVar: string, collection: s
       updateData[key] = value;
     }
 
-    const collection = await getCollection(COLLECTION_NAME);
     await collection.updateOne(byId(id), { $set: updateData });
     const ${modelVar} = await collection.findOne(byId(id));
     if (!${modelVar}) throw new Error('${modelName} not found after update');
@@ -219,7 +302,7 @@ function generateUpdateMethod(modelName: string, modelVar: string, collection: s
 `;
 }
 
-function generateEvolveMethod(model: any, modelName: string, modelVar: string, collection: string): string {
+function generateEvolveMethod(model: any, modelName: string, modelVar: string, collection: string, hasConstraints: boolean = false): string {
   const lifecycles = Array.isArray(model.lifecycles)
     ? model.lifecycles
     : (model.lifecycles ? Object.entries(model.lifecycles).map(([name, lc]: [string, any]) => ({ name, ...lc })) : []);
@@ -235,12 +318,26 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string, c
         ...Object.values(validTransitions).flat(),
       ]));
 
+  // Phase 2 — reverse map (currentState -> targetState -> actionName) so
+  // evolve() can pass the correct `evolve.<actionName>` op to validate.
+  const evolveOpsMap: Record<string, Record<string, string>> = {};
+  if (lifecycle?.transitions) {
+    for (const [actionName, t] of Object.entries(lifecycle.transitions as Record<string, any>)) {
+      const from = (t as any).from;
+      const to = (t as any).to;
+      if (typeof from === 'string' && typeof to === 'string') {
+        evolveOpsMap[from] = evolveOpsMap[from] ?? {};
+        evolveOpsMap[from][to] = actionName;
+      }
+    }
+  }
+
   return `
   /**
    * Evolve ${modelName} through lifecycle "${lifecycleName}"
    * States: ${states.join(' → ') || '(none declared)'}
    */
-  public async evolve(id: string, data: any): Promise<any> {
+  public async evolve(id: string, data: any, _actor: any = null): Promise<any> {
     const collection = await getCollection(COLLECTION_NAME);
     const current = await collection.findOne(byId(id));
     if (!current) throw new Error('${modelName} not found');
@@ -257,7 +354,22 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string, c
       throw new Error(\`Invalid transition: \${currentState} → \${targetState}. Allowed: \${allowed.join(', ') || 'none'}\`);
     }
     ` : ''}
-
+${hasConstraints ? `
+    // Phase 2 — resolve the transition's action name so constraints
+    // scoped to \`on: 'evolve.<action>'\` match correctly. EVOLVE_OPS is
+    // baked at codegen from the lifecycle definition.
+    const EVOLVE_OPS: Record<string, Record<string, string>> = ${JSON.stringify(evolveOpsMap)};
+    const currentStateForOp = (current as any)[targetLifecycle];
+    const actionName = EVOLVE_OPS[currentStateForOp]?.[targetState] ?? targetState;
+    const evolveValidation = await this.validate(
+      { ...data, ...current, [targetLifecycle]: targetState },
+      { operation: \`evolve.\${actionName}\` as any },
+      _actor
+    );
+    if (!evolveValidation.valid) {
+      throw new Error(\`Validation failed: \${evolveValidation.errors.join(', ')}\`);
+    }
+` : ''}
     await collection.updateOne(byId(id), { $set: { [targetLifecycle]: targetState } });
     const ${modelVar} = await collection.findOne(byId(id));
     if (!${modelVar}) throw new Error('${modelName} not found after evolve');
@@ -268,14 +380,23 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string, c
 `;
 }
 
-function generateDeleteMethod(modelName: string, modelVar: string, collection: string): string {
+function generateDeleteMethod(modelName: string, modelVar: string, collection: string, hasConstraints: boolean = false): string {
   return `
   /**
    * Delete ${modelName}.
    */
-  public async delete(id: string): Promise<void> {
+  public async delete(id: string, _actor: any = null): Promise<void> {
     const collection = await getCollection(COLLECTION_NAME);
     const ${modelVar} = await collection.findOne(byId(id));
+${hasConstraints ? `
+    // Phase 2 — run delete-scoped constraint guards against the loaded record.
+    if (${modelVar}) {
+      const deleteValidation = await this.validate(${modelVar}, { operation: 'delete' }, _actor);
+      if (!deleteValidation.valid) {
+        throw new Error(\`Validation failed: \${deleteValidation.errors.join(', ')}\`);
+      }
+    }
+` : ''}
     await collection.deleteOne(byId(id));
     if (${modelVar}) {
       await eventBus.publish('${modelName}Deleted', { ...${modelVar}, timestamp: new Date().toISOString() } as any);

package/libs/instance-factories/services/templates/postgres-native/__tests__/controller-with-constraints.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Phase 2 — postgres-native controller-generator emits guards import +
+ * extended validate() body when the model has declared constraints
+ * (mirrors the prisma controller-with-constraints test).
+ *
+ * Smoke-shape test: asserts STRINGS in the generated controller source.
+ */
+
+import { describe, it, expect } from 'vitest';
+import generatePgNativeController from '../controller-generator.js';
+import type { ModelConstraintSpec } from '@specverse/types';
+
+function buildConstrainedModel(): any {
+  const expanded: ModelConstraintSpec = {
+    on: ['create'],
+    requires: {
+      type: 'guard',
+      name: 'Vote_create_requires',
+      body: 'self.poll.votingStatus == "open"',
+      params: 'self: Vote, actor: User',
+      source: {
+        convention: 'compound',
+        entity: 'constraints',
+        input: 'self.poll.votingStatus == "open"',
+      },
+    },
+    source: {
+      authorOn: 'create',
+      authorRequires: 'self.poll.votingStatus == "open"',
+    },
+  };
+  return {
+    name: 'Vote',
+    attributes: [
+      { name: 'id', type: 'UUID', required: true, unique: true, category: 'metadata', auto: 'uuid4' },
+      { name: 'choice', type: 'String', required: true, unique: false, category: 'business' },
+    ],
+    relationships: [],
+    lifecycles: [],
+    behaviors: {},
+    constraints: [expanded],
+  };
+}
+
+function buildUnconstrainedModel(): any {
+  return {
+    name: 'Comment',
+    attributes: [
+      { name: 'id', type: 'UUID', required: true, unique: true, category: 'metadata', auto: 'uuid4' },
+      { name: 'text', type: 'String', required: true, unique: false, category: 'business' },
+    ],
+    relationships: [],
+    lifecycles: [],
+    behaviors: {},
+  };
+}
+
+function buildController(modelName: string): any {
+  return {
+    name: `${modelName}Controller`,
+    model: modelName,
+    modelReference: modelName,
+    cured: { create: {}, retrieve: {}, update: {}, validate: {}, delete: {} },
+  };
+}
+
+describe('Phase 2 — controller-generator with model.constraints', () => {
+  it('emits import for guards module when model has constraints', () => {
+    const code = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(),
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    expect(code).toContain(`import { runGuards as runConstraintGuards } from './Vote.guards.js';`);
+  });
+
+  it('does NOT emit guards import for unconstrained models', () => {
+    const code = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildUnconstrainedModel(),
+      controller: buildController('Comment'),
+      models: [buildUnconstrainedModel()],
+    });
+    expect(code).not.toContain('.guards.js');
+    expect(code).not.toContain('runConstraintGuards');
+  });
+
+  it('extends validate() signature with actor + widens op union', () => {
+    const code = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(),
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    expect(code).toContain('_actor: any = null');
+    // Wider union includes 'delete' and the template-literal evolve.<X>.
+    expect(code).toContain(`'delete'`);
+    expect(code).toContain('`evolve.${string}`');
+  });
+
+  it('emits runConstraintGuards call inside validate() body', () => {
+    const code = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(),
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    expect(code).toContain('await runConstraintGuards(_data, _context.operation, _actor, __guardCtx)');
+  });
+
+  // Slice 14 actor wiring — validate() ALWAYS accepts _actor (default null)
+  // on EVERY controller for uniform route-handler call sites.
+  it('emits _actor param on validate() signature for both constrained AND unconstrained', () => {
+    const constrained = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(),
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    const unconstrained = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildUnconstrainedModel(),
+      controller: buildController('Comment'),
+      models: [buildUnconstrainedModel()],
+    });
+    expect(constrained).toContain('_actor: any = null');
+    expect(unconstrained).toContain('_actor: any = null');
+    expect(unconstrained).not.toContain('runConstraintGuards');
+  });
+
+  it('emits delete() with validate call when constrained', () => {
+    const code = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(),
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    expect(code).toContain('public async delete(id: string, _actor: any = null)');
+    expect(code).toContain(`await this.validate(vote, { operation: 'delete' }, _actor)`);
+  });
+
+  it('emits delete() WITHOUT validate call when unconstrained (backward compat)', () => {
+    const code = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildUnconstrainedModel(),
+      controller: buildController('Comment'),
+      models: [buildUnconstrainedModel()],
+    });
+    expect(code).toContain('public async delete(id: string, _actor: any = null)');
+    const deleteSection = code.substring(code.indexOf('public async delete(id: string'));
+    expect(deleteSection).not.toContain('this.validate(');
+  });
+
+  // Phase 2 carry-over (Update self-from-DB).
+  it('update() loads + merges entity before validate when constrained', () => {
+    const code = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(),
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    const updateSection = code.substring(code.indexOf('public async update(id: string'));
+    expect(updateSection).toContain('__existing');
+    expect(updateSection).toContain('findOneByField');
+    expect(updateSection).toContain('__merged');
+    expect(updateSection).toContain(`await this.validate(__merged, { operation: 'update' }, _actor)`);
+  });
+
+  it('update() uses raw input shape when unconstrained (backward compat)', () => {
+    const code = generatePgNativeController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildUnconstrainedModel(),
+      controller: buildController('Comment'),
+      models: [buildUnconstrainedModel()],
+    });
+    const updateSection = code.substring(code.indexOf('public async update(id: string'));
+    expect(updateSection).not.toContain('__existing');
+    expect(updateSection).not.toContain('__merged');
+    expect(updateSection).toContain(`await this.validate(data, { operation: 'update' }, _actor)`);
+  });
+});