@pattern-stack/codegen 0.6.8 → 0.7.0

package/templates/entity/new/clean-lite-ps/service.ejs.t

@@ -17,6 +17,22 @@ import { toEavRows, mergeEavRows } from '@shared/eav-helpers';
 import type { DrizzleTx } from '@shared/types/drizzle';
 import { <%= eavDefinitionPascal %>Repository } from '../<%= eavDefinitionEntityPlural %>/<%= eavDefinitionEntity %>.repository';
 <% } -%>
+<%_ /* CGP-358b — service-layer composition: import target repos for belongs_to relationships */ _%>
+<%_ if (typeof clpBelongsTo !== 'undefined') { _%>
+<%_ const uniqueBelongsToTargets = [...new Map(clpBelongsTo.filter(r => !r.isSelfFk).map(r => [r.relatedEntity, r])).values()]; _%>
+<%_ uniqueBelongsToTargets.forEach(rel => { _%>
+import { <%= rel.relatedEntityPascal %>Repository } from '../<%= rel.relatedPlural %>/<%= rel.relatedEntity %>.repository';
+import type { <%= rel.relatedEntityPascal %> } from '../<%= rel.relatedPlural %>/<%= rel.relatedEntity %>.entity';
+<%_ }) _%>
+<%_ } _%>
+<%_ /* CGP-358b — import target repos for has_many relationships */ _%>
+<%_ if (typeof clpExistingHasMany !== 'undefined') { _%>
+<%_ const uniqueHasManyTargets = [...new Map(clpExistingHasMany.filter(r => !r.isSelfRef).map(r => [r.target, r])).values()]; _%>
+<%_ uniqueHasManyTargets.forEach(rel => { _%>
+import { <%= rel.targetClass %>Repository } from '../<%= rel.targetPlural %>/<%= rel.target %>.repository';
+import type { <%= rel.targetClass %> } from '../<%= rel.targetPlural %>/<%= rel.target %>.entity';
+<%_ }) _%>
+<%_ } _%>
 
 @Injectable()
 export class <%= classNames.service %> extends WithAnalytics(
@@ -43,6 +59,20 @@ export class <%= classNames.service %> extends WithAnalytics(
 <% if (eavValueTable) { -%>
     private readonly definitionRepo: <%= eavDefinitionPascal %>Repository,
 <% } -%>
+<%_ /* CGP-358b — inject target repos for belongs_to (non-self-ref) */ _%>
+<%_ if (typeof clpBelongsTo !== 'undefined') { _%>
+<%_ const uniqueBelongsToTargets2 = [...new Map(clpBelongsTo.filter(r => !r.isSelfFk).map(r => [r.relatedEntity, r])).values()]; _%>
+<%_ uniqueBelongsToTargets2.forEach(rel => { _%>
+    private readonly <%= rel.relatedEntity.replace(/_([a-z])/g, (_, c) => c.toUpperCase()) %>Repo: <%= rel.relatedEntityPascal %>Repository,
+<%_ }) _%>
+<%_ } _%>
+<%_ /* CGP-358b — inject target repos for has_many (non-self-ref) */ _%>
+<%_ if (typeof clpExistingHasMany !== 'undefined') { _%>
+<%_ const uniqueHasManyTargets2 = [...new Map(clpExistingHasMany.filter(r => !r.isSelfRef).map(r => [r.target, r])).values()]; _%>
+<%_ uniqueHasManyTargets2.forEach(rel => { _%>
+    private readonly <%= rel.target.replace(/_([a-z])/g, (_, c) => c.toUpperCase()) %>Repo: <%= rel.targetClass %>Repository,
+<%_ }) _%>
+<%_ } _%>
   ) {
     super(repository);
   }
@@ -67,6 +97,55 @@ export class <%= classNames.service %> extends WithAnalytics(
   }
 <%_ }) _%>
 <% } %>
+<%_ /* CGP-358b — service-layer composition methods for relationships */ _%>
+<%_ const hasBelongsToComposition = typeof clpBelongsTo !== 'undefined' && clpBelongsTo.length > 0; _%>
+<%_ const hasHasManyComposition = typeof clpExistingHasMany !== 'undefined' && clpExistingHasMany.length > 0; _%>
+<%_ if (hasBelongsToComposition || hasHasManyComposition) { _%>
+  // ═══════════════════════════════════════════════════════════════════════
+  // Relationship composition methods (CGP-358b / CGP-62)
+  // Two queries, no SQL JOIN. Core-contract path; relations() const stays
+  // as opt-in extension for hand-written Drizzle queries.
+  // ═══════════════════════════════════════════════════════════════════════
+<%_ } _%>
+<%_ if (hasBelongsToComposition) { _%>
+<%_ clpBelongsTo.forEach(rel => { _%>
+<%_ const relCamel = rel.relatedEntity.replace(/_([a-z])/g, (_, c) => c.toUpperCase()); _%>
+<%_ const entityCamel = entityName.replace(/_([a-z])/g, (_, c) => c.toUpperCase()); _%>
+
+  /**
+   * Fetch the <%= rel.relatedEntityPascal %> parent for this <%= entityNamePascal %>.
+   * Two repo calls: find self by id → find target by FK.
+   */
+  async <%= rel.relationKey %>(<%- entityCamel %>Id: string): Promise<<%= rel.relatedEntityPascal %> | null> {
+    const entity = await this.repository.findById(<%- entityCamel %>Id);
+    if (!entity) return null;
+<%_ if (rel.isSelfFk) { _%>
+    return entity.<%= rel.camelField %> ? this.repository.findById(entity.<%= rel.camelField %>) : null;
+<%_ } else { _%>
+    return entity.<%= rel.camelField %> ? this.<%= relCamel %>Repo.findById(entity.<%= rel.camelField %>) : null;
+<%_ } _%>
+  }
+<%_ }) _%>
+<%_ } _%>
+<%_ if (hasHasManyComposition) { _%>
+<%_ clpExistingHasMany.forEach(rel => { _%>
+<%_ const relCamel = rel.target.replace(/_([a-z])/g, (_, c) => c.toUpperCase()); _%>
+<%_ const entityCamel = entityName.replace(/_([a-z])/g, (_, c) => c.toUpperCase()); _%>
+<%_ const fkPascal = rel.inverseForeignKeyPascal; _%>
+
+  /**
+   * Fetch <%= rel.name %> for this <%= entityNamePascal %> by FK traversal.
+   * Single repo call with optional cursor/limit pagination.
+   */
+  async <%= rel.name %>(<%- entityCamel %>Id: string, opts?: { cursor?: string; limit?: number }): Promise<<%= rel.targetClass %>[]> {
+<%_ if (rel.isSelfRef) { _%>
+    return this.repository.findBy<%= fkPascal %>(<%- entityCamel %>Id, opts);
+<%_ } else { _%>
+    return this.<%= relCamel %>Repo.findBy<%= fkPascal %>(<%- entityCamel %>Id, opts);
+<%_ } _%>
+  }
+<%_ }) _%>
+<%_ } _%>
 <% if (eavEnabled) { %>
   /**
    * EAV paired read (ADR-13): fetch the entity and merge dynamic `field_values`

package/templates/entity/new/prompt.js

@@ -568,6 +568,7 @@ export default {
       moduleToGetByIdQuery: importHelpers.moduleToQuery(name, fileNames.getByIdQuery.replace('.ts', '')),
       moduleToListQuery: importHelpers.moduleToQuery(name, fileNames.listQuery.replace('.ts', '')),
       moduleToDeclarativeQueries: importHelpers.moduleToQuery(name, 'declarative-queries'),
+      moduleToRelationshipQueries: importHelpers.moduleToQuery(name, 'relationships.queries'),
       moduleToCreateCommand: importHelpers.moduleToCommand(name, fileNames.createCommand.replace('.ts', '')),
       moduleToUpdateCommand: importHelpers.moduleToCommand(name, fileNames.updateCommand.replace('.ts', '')),
       moduleToDeleteCommand: importHelpers.moduleToCommand(name, fileNames.deleteCommand.replace('.ts', '')),

package/templates/junction/new/_inject-parent-module-clp-left.ejs.t

@@ -0,0 +1,8 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.left ? parentModulePathLeft : '' %>"
+inject: true
+after: "    DatabaseModule,"
+skip_if: "<%= classNames.module %>"
+---
+    // CGP-60 — junction module (forwardRef breaks the parent↔junction module cycle)
+    forwardRef(() => <%= classNames.module %>),

package/templates/junction/new/_inject-parent-module-clp-right.ejs.t

@@ -0,0 +1,8 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.right ? parentModulePathRight : '' %>"
+inject: true
+after: "    DatabaseModule,"
+skip_if: "<%= classNames.module %>"
+---
+    // CGP-60 — junction module (forwardRef breaks the parent↔junction module cycle)
+    forwardRef(() => <%= classNames.module %>),

package/templates/junction/new/_inject-parent-module-import-clp-left.ejs.t

@@ -0,0 +1,9 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.left ? parentModulePathLeft : '' %>"
+inject: true
+after: "from '@nestjs/common';"
+skip_if: "<%= classNames.module %> }"
+---
+// CGP-60 — junction module wiring
+import { forwardRef } from '@nestjs/common';
+import { <%= classNames.module %> } from '<%= junctionModuleImportFromLeft %>';

package/templates/junction/new/_inject-parent-module-import-clp-right.ejs.t

@@ -0,0 +1,9 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.right ? parentModulePathRight : '' %>"
+inject: true
+after: "from '@nestjs/common';"
+skip_if: "<%= classNames.module %> }"
+---
+// CGP-60 — junction module wiring
+import { forwardRef } from '@nestjs/common';
+import { <%= classNames.module %> } from '<%= junctionModuleImportFromRight %>';

package/templates/junction/new/_inject-parent-service-clp-left.ejs.t

@@ -0,0 +1,51 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.left ? parentServicePathLeft : '' %>"
+inject: true
+before: "// Inherited from"
+skip_if: "<%= injectionMarkerLeft %>"
+---
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // CGP-60 — fan-out to <%= rightEntityPascal %> (junction: <%= name %>)
+  // Delegates to <%= classNames.service %>. Per-junction marker keeps
+  // idempotency; multiple junctions on the same parent each emit their own
+  // block. `forwardRef` resolves the circular module import (parent module
+  // imports junction module; junction module imports parent modules for
+  // repo DI).
+  // ═══════════════════════════════════════════════════════════════════════
+  <%= injectionMarkerLeft %>
+
+  @Inject(forwardRef(() => <%= classNames.service %>))
+  private readonly <%= entityNameCamel %>Service!: <%= classNames.service %>;
+
+  async attach<%= rightEntityPascal %>(
+    <%= leftEntityCamel %>Id: string,
+    <%= rightEntityCamel %>Id: string,
+    link?: <%= entityNamePascal %>LinkInput,
+  ): Promise<<%= entityNamePascal %>> {
+    return this.<%= entityNameCamel %>Service.attach(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id, link);
+  }
+
+  async detach<%= rightEntityPascal %>(
+    <%= leftEntityCamel %>Id: string,
+    <%= rightEntityCamel %>Id: string,
+  ): Promise<void> {
+    return this.<%= entityNameCamel %>Service.detach(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id);
+  }
+
+  async <%= rightEntityPlural %>List(
+    <%= leftEntityCamel %>Id: string,
+    opts?: { cursor?: string; limit?: number },
+  ): Promise<Array<{ entity: <%= rightEntityPascal %>; link: <%= entityNamePascal %> }>> {
+    return this.<%= entityNameCamel %>Service.listAssoc('left', <%= leftEntityCamel %>Id, opts) as Promise<
+      Array<{ entity: <%= rightEntityPascal %>; link: <%= entityNamePascal %> }>
+    >;
+  }
+
+  async <%= rightEntityPlural %>SetPrimary(
+    <%= leftEntityCamel %>Id: string,
+    <%= rightEntityCamel %>Id: string,
+  ): Promise<void> {
+    return this.<%= entityNameCamel %>Service.setPrimary(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id);
+  }
+

package/templates/junction/new/_inject-parent-service-clp-right.ejs.t

@@ -0,0 +1,48 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.right ? parentServicePathRight : '' %>"
+inject: true
+before: "// Inherited from"
+skip_if: "<%= injectionMarkerRight %>"
+---
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // CGP-60 — fan-out to <%= leftEntityPascal %> (junction: <%= name %>)
+  // Delegates to <%= classNames.service %>. See left-side block for the
+  // forwardRef + per-junction marker rationale.
+  // ═══════════════════════════════════════════════════════════════════════
+  <%= injectionMarkerRight %>
+
+  @Inject(forwardRef(() => <%= classNames.service %>))
+  private readonly <%= entityNameCamel %>Service!: <%= classNames.service %>;
+
+  async addTo<%= leftEntityPascal %>(
+    <%= rightEntityCamel %>Id: string,
+    <%= leftEntityCamel %>Id: string,
+    link?: <%= entityNamePascal %>LinkInput,
+  ): Promise<<%= entityNamePascal %>> {
+    return this.<%= entityNameCamel %>Service.attach(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id, link);
+  }
+
+  async removeFrom<%= leftEntityPascal %>(
+    <%= rightEntityCamel %>Id: string,
+    <%= leftEntityCamel %>Id: string,
+  ): Promise<void> {
+    return this.<%= entityNameCamel %>Service.detach(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id);
+  }
+
+  async <%= leftEntityPlural %>List(
+    <%= rightEntityCamel %>Id: string,
+    opts?: { cursor?: string; limit?: number },
+  ): Promise<Array<{ entity: <%= leftEntityPascal %>; link: <%= entityNamePascal %> }>> {
+    return this.<%= entityNameCamel %>Service.listAssoc('right', <%= rightEntityCamel %>Id, opts) as Promise<
+      Array<{ entity: <%= leftEntityPascal %>; link: <%= entityNamePascal %> }>
+    >;
+  }
+
+  async <%= leftEntityPlural %>SetPrimary(
+    <%= rightEntityCamel %>Id: string,
+    <%= leftEntityCamel %>Id: string,
+  ): Promise<void> {
+    return this.<%= entityNameCamel %>Service.setPrimary(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id);
+  }
+

package/templates/junction/new/_inject-parent-service-import-clp-left.ejs.t

@@ -0,0 +1,11 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.left ? parentServicePathLeft : '' %>"
+inject: true
+after: "from '@nestjs/common';"
+skip_if: "<%= classNames.service %> }"
+---
+// CGP-60 — junction service + types (forwardRef resolves circular module dep)
+import { forwardRef } from '@nestjs/common';
+import { <%= classNames.service %>, <%= entityNamePascal %>LinkInput } from '<%= junctionServiceImportFromLeft %>';
+import type { <%= entityNamePascal %> } from '../<%= entityNamePlural %>/<%= name %>.entity';
+import type { <%= rightEntityPascal %> } from '<%= rightEntityImportFromJunction %>';

package/templates/junction/new/_inject-parent-service-import-clp-right.ejs.t

@@ -0,0 +1,11 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.right ? parentServicePathRight : '' %>"
+inject: true
+after: "from '@nestjs/common';"
+skip_if: "<%= classNames.service %> }"
+---
+// CGP-60 — junction service + types (forwardRef resolves circular module dep)
+import { forwardRef } from '@nestjs/common';
+import { <%= classNames.service %>, <%= entityNamePascal %>LinkInput } from '<%= junctionServiceImportFromRight %>';
+import type { <%= entityNamePascal %> } from '../<%= entityNamePlural %>/<%= name %>.entity';
+import type { <%= leftEntityPascal %> } from '<%= leftEntityImportFromJunction %>';

package/templates/junction/new/entity.ejs.t

@@ -0,0 +1,111 @@
+---
+to: "<%= outputPaths.entity %>"
+force: true
+---
+import {
+<%_ drizzleImports.filter(i => i !== 'relations').forEach(i => { _%>
+  <%= i %>,
+<%_ }) _%>
+} from 'drizzle-orm/pg-core';
+import { relations, type InferSelectModel } from 'drizzle-orm';
+import { <%= leftTable %> } from '../<%= leftTable %>/<%= leftEntity %>.entity';
+<%_ if (leftEntity !== rightEntity) { _%>
+import { <%= rightTable %> } from '../<%= rightTable %>/<%= rightEntity %>.entity';
+<%_ } _%>
+
+// ============================================================================
+// Enums
+// ============================================================================
+<%_ if (hasRole) { _%>
+
+export const <%= roleEnumName %> = pgEnum('<%= name %>_role', [
+<%_ roleEnumValues.forEach(v => { _%>
+  '<%= v %>',
+<%_ }) _%>
+]);
+<%_ } _%>
+<%_ processedCustomFields.filter(f => f.hasChoices).forEach(field => { _%>
+
+export const <%= field.enumName %> = pgEnum('<%= name %>_<%= field.name %>', [
+<%_ field.choices.forEach(c => { _%>
+  '<%= c %>',
+<%_ }) _%>
+]);
+<%_ }) _%>
+
+// ============================================================================
+// Table
+// ============================================================================
+
+export const <%= tableVarName %> = pgTable(
+  '<%= tableName %>',
+  {
+    // FK columns — composite primary key (no surrogate id: Q4 resolution)
+    <%= leftColumnCamel %>: uuid('<%= leftColumn %>').notNull().references(() => <%= leftTable %>.id, { onDelete: '<%= onDeleteLeft %>' }),
+    <%= rightColumnCamel %>: uuid('<%= rightColumn %>').notNull().references(() => <%= rightTable %>.id, { onDelete: '<%= onDeleteRight %>' }),
+<%_ if (hasRole) { _%>
+
+    // Role enum (per-pairing; declared in junction YAML's fields.role.choices)
+    role: <%= roleEnumName %>('role'),
+<%_ } _%>
+
+    // BaseJunctionFields — is_primary is always emitted
+    isPrimary: boolean('is_primary').notNull().default(false),
+<%_ if (temporal) { _%>
+
+    // Temporal window (temporal: true, default)
+    startedAt: timestamp('started_at'),
+    endedAt: timestamp('ended_at'),
+<%_ } _%>
+<%_ if (sourced) { _%>
+
+    // Provenance (sourced: true, default)
+    sourcedFrom: text('sourced_from'),
+    confidence: numeric('confidence', { precision: 5, scale: 4 }),
+    matchedAt: timestamp('matched_at'),
+<%_ } _%>
+<%_ if (hasCustomFields) { _%>
+
+    // Custom fields
+<%_ processedCustomFields.forEach(field => { _%>
+<%_ if (field.hasChoices) { _%>
+    <%= field.camelName %>: <%= field.enumName %>('<%= field.name %>'),
+<%_ } else if (field.drizzleType === 'uuid') { _%>
+    <%= field.camelName %>: uuid('<%= field.name %>'),
+<%_ } else { _%>
+    <%= field.camelName %>: <%= field.drizzleType %>('<%= field.name %>'),
+<%_ } _%>
+<%_ }) _%>
+<%_ } _%>
+
+    // Timestamps
+    createdAt: timestamp('created_at').notNull().defaultNow(),
+    updatedAt: timestamp('updated_at').notNull().defaultNow(),
+  },
+  (table) => [
+    // Composite primary key on the two FK columns (Q4 resolution: no surrogate id)
+    primaryKey({ columns: [table.<%= leftColumnCamel %>, table.<%= rightColumnCamel %>] }),
+  ],
+);
+
+export type <%= classNames.entity %> = InferSelectModel<typeof <%= tableVarName %>>;
+export type <%= classNames.entity %>Insert = typeof <%= tableVarName %>.$inferInsert;
+
+// ============================================================================
+// Relations — extension-path metadata for db.query.X.findMany({ with: ... })
+// Generated code does NOT consume these; they exist for hand-written admin
+// queries and for #60's fan-out methods once they land.
+// ============================================================================
+
+export const <%= tableVarName %>Relations = relations(<%= tableVarName %>, ({ one }) => ({
+  <%= leftEntity %>: one(<%= leftTable %>, {
+    fields: [<%= tableVarName %>.<%= leftColumnCamel %>],
+    references: [<%= leftTable %>.id],
+  }),
+<%_ if (leftEntity !== rightEntity) { _%>
+  <%= rightEntity %>: one(<%= rightTable %>, {
+    fields: [<%= tableVarName %>.<%= rightColumnCamel %>],
+    references: [<%= rightTable %>.id],
+  }),
+<%_ } _%>
+}));

package/templates/junction/new/index.ejs.t

@@ -0,0 +1,15 @@
+---
+to: "<%= outputPaths.index %>"
+force: true
+---
+/**
+ * <%= classNames.entity %> module barrel export
+ * Generated by junction codegen — do not edit directly
+ */
+
+// Value exports (module, service)
+export { <%= classNames.module %> } from './<%= entityNamePlural %>.module';
+export { <%= classNames.service %> } from './<%= name %>.service';
+
+// Type-only exports (entity)
+export type { <%= classNames.entity %> } from './<%= name %>.entity';

package/templates/junction/new/module.ejs.t

@@ -0,0 +1,37 @@
+---
+to: "<%= outputPaths.module %>"
+force: true
+---
+import { Module, forwardRef } from '@nestjs/common';
+import { DatabaseModule } from '@shared/database/database.module';
+
+import { <%= classNames.repository %> } from './<%= name %>.repository';
+import { <%= classNames.service %> } from './<%= name %>.service';
+import { <%= leftModuleClass %> } from '<%= leftModuleImportFromJunction %>';
+import { <%= rightModuleClass %> } from '<%= rightModuleImportFromJunction %>';
+
+// Note: No controller — junctions are not directly addressable HTTP resources
+// in v1 (Q1 resolution). They are accessed via the canonical port of one of
+// the two parent entities. Add a controller in a follow-up if a consumer
+// surfaces a need for direct HTTP access to junction rows.
+
+@Module({
+  imports: [
+    DatabaseModule,
+    // CGP-60 — parent modules provide the left/right repositories that the
+    // junction service injects for the canonical `list` composition path.
+    // forwardRef resolves the parent↔junction module cycle (parent modules
+    // also import this module to wire fan-out).
+    forwardRef(() => <%= leftModuleClass %>),
+    forwardRef(() => <%= rightModuleClass %>),
+    // TODO: Add subsystem modules as needed (EventsSubsystemModule, etc.)
+  ],
+  controllers: [],
+  providers: [
+    <%= classNames.repository %>,
+    <%= classNames.service %>,
+    // TODO: Register hand-written use cases here
+  ],
+  exports: [<%= classNames.service %>],  // Only service is exported (ADR-002)
+})
+export class <%= classNames.module %> {}