@specverse/engines 6.66.0 → 6.76.0

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

@@ -49,12 +49,17 @@ export default function generatePgNativeController(context: TemplateContext): st
 
   const customActions = generateCustomActions(controller, modelRegistry);
 
-  const validate = generateValidateMethod(model, modelName);
-  const create = curedOps.create ? generateCreateMethod(modelName, modelVar) : '';
+  // Phase 2 — guards module gating (see prisma + mongo for the same pattern).
+  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, hasConstraints) : '';
   const retrieve = curedOps.retrieve ? generateRetrieveMethod(modelName, modelVar) : '';
-  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar) : '';
-  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar) : '';
-  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar) : '';
+  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar, hasConstraints) : '';
+  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, hasConstraints) : '';
+  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar, hasConstraints) : '';
 
   const hasEventPublishing =
     curedOps.create || curedOps.update || curedOps.evolve || curedOps.delete;
@@ -83,6 +88,7 @@ export default function generatePgNativeController(context: TemplateContext): st
 import { ${helperImports} } from '../db/pgClient.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 TABLE_NAME = '${table}';
 
@@ -111,17 +117,45 @@ function tableName(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. Op union widens to 'delete' + evolve.<X>.
+ */
+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 all = await findAll(modelName);
+          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 };
   }
 `;
@@ -152,13 +186,24 @@ function generateValidationLogic(model: any): string {
   return out.join('\n') || '    // No validation rules defined';
 }
 
-function generateCreateMethod(modelName: string, modelVar: string): string {
+function generateCreateMethod(model: any, modelName: string, modelVar: string, hasConstraints: boolean = false): string {
+  const belongsToLoad = hasConstraints ? generatePgBelongsToLoad(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 row and
+    // merge into self for constraint guards.
+    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 ${modelVar} = await insertOne(TABLE_NAME, { ...data });
@@ -169,6 +214,25 @@ function generateCreateMethod(modelName: string, modelVar: string): string {
 `;
 }
 
+function generatePgBelongsToLoad(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`;
+    // Postgres table names follow the same casing convention as the model.
+    // findOneByField('Vote', 'id', x) loads from the "Vote" table.
+    return `if (data.${fkField}) {
+      __loadedRels.${relName} = await findOneByField('${targetName}', 'id', data.${fkField});
+    }`;
+  }).join('\n    ');
+}
+
 function generateRetrieveMethod(modelName: string, _modelVar: string): string {
   return `
   /**
@@ -193,13 +257,22 @@ function generateRetrieveMethod(modelName: string, _modelVar: string): string {
 `;
 }
 
-function generateUpdateMethod(modelName: string, modelVar: string): string {
+function generateUpdateMethod(modelName: string, modelVar: 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> {
+${hasConstraints ? `
+    // Phase 2 — Update self-from-DB. Load + merge before validate so
+    // update-time constraints see the full entity, not just partial input.
+    const __existing = await findOneByField(TABLE_NAME, 'id', 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.
@@ -221,7 +294,7 @@ function generateUpdateMethod(modelName: string, modelVar: string): string {
 `;
 }
 
-function generateEvolveMethod(model: any, modelName: string, modelVar: string): string {
+function generateEvolveMethod(model: any, modelName: string, modelVar: 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 +308,25 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string):
         ...Object.values(validTransitions).flat(),
       ]));
 
+  // Phase 2 — reverse map (currentState -> targetState -> actionName).
+  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 current = await findOneByField(TABLE_NAME, 'id', id);
     if (!current) throw new Error('${modelName} not found');
 
@@ -256,7 +342,20 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string):
       throw new Error(\`Invalid transition: \${currentState} → \${targetState}. Allowed: \${allowed.join(', ') || 'none'}\`);
     }
     ` : ''}
-
+${hasConstraints ? `
+    // Phase 2 — resolve transition action name + call validate with evolve.<action>.
+    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 updateOneById(TABLE_NAME, id, { [targetLifecycle]: targetState });
     const ${modelVar} = await findOneByField(TABLE_NAME, 'id', id);
     if (!${modelVar}) throw new Error('${modelName} not found after evolve');
@@ -267,13 +366,22 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string):
 `;
 }
 
-function generateDeleteMethod(modelName: string, modelVar: string): string {
+function generateDeleteMethod(modelName: string, modelVar: 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 ${modelVar} = await findOneByField(TABLE_NAME, 'id', 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 deleteOneById(TABLE_NAME, id);
     if (${modelVar}) {
       await eventBus.publish('${modelName}Deleted', { ...${modelVar}, timestamp: new Date().toISOString() } as any);

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

@@ -0,0 +1,261 @@
+/**
+ * Phase 2 — prisma controller-generator emits guards import + extended
+ * validate() body when the model has declared constraints.
+ *
+ * This is a smoke-shape test: we assert STRINGS in the generated controller
+ * source, not runtime behavior of the controller. The runtime behavior is
+ * covered by the end-to-end realize integration test (Task #8).
+ */
+
+import { describe, it, expect } from 'vitest';
+import generatePrismaController 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 = generatePrismaController({
+      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 = generatePrismaController({
+      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 = generatePrismaController({
+      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 = generatePrismaController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(),
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    expect(code).toContain('await runConstraintGuards(_data, _context.operation, _actor, __guardCtx)');
+  });
+
+  // Phase 2 Slice 14 actor wiring — validate() ALWAYS accepts _actor (default
+  // null) on EVERY controller, so route handlers can pass `(request as any).user`
+  // without per-model knowledge of whether constraints exist. Unconstrained
+  // controllers just ignore the param.
+  it('emits _actor param on validate() signature for both constrained AND unconstrained', () => {
+    const constrained = generatePrismaController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(),
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    const unconstrained = generatePrismaController({
+      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');
+    // Unconstrained controllers still don't pull in the guards module.
+    expect(unconstrained).not.toContain('runConstraintGuards');
+  });
+
+  it('emits delete() with validate call when constrained', () => {
+    const code = generatePrismaController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(),
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    // Slice 14 — delete() now takes (id, _actor) and threads _actor to validate.
+    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 = generatePrismaController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildUnconstrainedModel(),
+      controller: buildController('Comment'),
+      models: [buildUnconstrainedModel()],
+    });
+    // Slice 14 — delete still accepts _actor for uniform route handler calls.
+    expect(code).toContain('public async delete(id: string, _actor: any = null)');
+    // Original delete just does findUnique + delete + publish — no validate.
+    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 = generatePrismaController({
+      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('findUnique');
+    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 = generatePrismaController({
+      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)`);
+  });
+
+  // Phase 2 Slice 15 — Create-time relation loading. Mirrors the
+  // Update self-from-DB pattern but for create: load each belongsTo
+  // related entity from input FKs before calling validate, so guards
+  // traversing self.<rel>.<field> see the loaded entity.
+  it('create() loads belongsTo relations into self when constrained', () => {
+    const constrainedWithRels = {
+      ...buildConstrainedModel(),
+      relationships: [
+        { name: 'poll', type: 'belongsTo', target: 'Poll' },
+        { name: 'voter', type: 'belongsTo', target: 'User' },
+      ],
+    };
+    const code = generatePrismaController({
+      spec: {} as any,
+      factory: {} as any,
+      model: constrainedWithRels,
+      controller: buildController('Vote'),
+      models: [constrainedWithRels],
+    });
+    const createSection = code.substring(code.indexOf('public async create(data: any'));
+    expect(createSection).toContain('__loadedRels');
+    expect(createSection).toContain('if (data.pollId)');
+    expect(createSection).toContain('prisma.poll.findUnique');
+    expect(createSection).toContain('if (data.voterId)');
+    expect(createSection).toContain('prisma.user.findUnique');
+    expect(createSection).toContain('__mergedSelf = { ...data, ...__loadedRels }');
+    expect(createSection).toContain(`await this.validate(__mergedSelf, { operation: 'create' }, _actor)`);
+  });
+
+  it('create() skips relation loading when unconstrained (backward compat)', () => {
+    const unconstrainedWithRels = {
+      ...buildUnconstrainedModel(),
+      relationships: [{ name: 'author', type: 'belongsTo', target: 'User' }],
+    };
+    const code = generatePrismaController({
+      spec: {} as any,
+      factory: {} as any,
+      model: unconstrainedWithRels,
+      controller: buildController('Comment'),
+      models: [unconstrainedWithRels],
+    });
+    const createSection = code.substring(code.indexOf('public async create(data: any'));
+    expect(createSection).not.toContain('__loadedRels');
+    expect(createSection).not.toContain('__mergedSelf');
+    expect(createSection).toContain(`await this.validate(data, { operation: 'create' }, _actor)`);
+  });
+
+  it('create() with constraints but no belongsTo skips the load block', () => {
+    // hasConstraints but model has no relationships — still emits
+    // simple validate(data, ...) since there's nothing to load.
+    const code = generatePrismaController({
+      spec: {} as any,
+      factory: {} as any,
+      model: buildConstrainedModel(), // no relationships
+      controller: buildController('Vote'),
+      models: [buildConstrainedModel()],
+    });
+    const createSection = code.substring(code.indexOf('public async create(data: any'));
+    expect(createSection).not.toContain('__loadedRels');
+    expect(createSection).toContain(`await this.validate(data, { operation: 'create' }, _actor)`);
+  });
+});