@pattern-stack/codegen 0.6.7 → 0.7.0

package/dist/src/index.d.ts

@@ -3453,6 +3453,149 @@ declare const RelationshipDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObjec
 }>;
 type RelationshipDefinition = z.infer<typeof RelationshipDefinitionSchema>;
 
+/**
+ * Top-level junction YAML shape.
+ *
+ *   pattern: Junction
+ *   between: [opportunity, contact]
+ *   temporal: true        # optional, default true
+ *   sourced: true         # optional, default true
+ *   fields:
+ *     role:
+ *       type: enum
+ *       values: [champion, decision_maker, influencer]
+ *   queries:
+ *     - by: [opportunity_id]
+ *
+ * Fields use the same shape as entity fields — validated downstream by the
+ * template / codegen layer using the existing `FieldDefinitionSchema`.
+ * This schema accepts the shape loosely (`z.any()`) and applies only the
+ * reserved-column collision check; matches the relationship-schema
+ * precedent (`relationship-definition.schema.ts` line ~250).
+ */
+declare const JunctionDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    /** Discriminator literal — `pattern: Junction`. */
+    pattern: z.ZodLiteral<"Junction">;
+    /**
+     * Exactly two endpoint entity names. Both intra- and cross-domain
+     * pairings are accepted; entity existence is validated by the
+     * analyzer in a later leaf.
+     */
+    between: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    /**
+     * Emit BaseJunctionFields temporal columns (`started_at`, `ended_at`,
+     * `matched_at`). Default true. Matches Relationship's `temporal` toggle.
+     */
+    temporal: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    /**
+     * Emit BaseJunctionFields sourcing columns (`sourced_from`,
+     * `confidence`). Default true. Matches Relationship's `sourced` toggle.
+     */
+    sourced: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    /**
+     * Junction-specific fields beyond `BaseJunctionFields`. Includes the
+     * per-pairing role enum (declared inline; never shared across
+     * pairings). Shape is validated downstream by the codegen layer
+     * using the existing entity FieldDefinitionSchema.
+     */
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    /**
+     * Declarative queries — same syntax as entity queries. Shape is
+     * validated downstream by the codegen layer.
+     */
+    queries: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    /**
+     * Per-side opt-out for parent-service fan-out (CGP-60). When a side
+     * is `false`, the `_inject-parent-service-*` templates emit nothing
+     * on that side (and the corresponding module wiring is skipped).
+     * The junction service body is always emitted regardless. Defaults
+     * to `{ left: true, right: true }`.
+     */
+    expose_on_parent: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        left: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        right: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        left: boolean;
+        right: boolean;
+    }, {
+        left?: boolean | undefined;
+        right?: boolean | undefined;
+    }>>>;
+}, "strict", z.ZodTypeAny, {
+    pattern: "Junction";
+    temporal: boolean;
+    sourced: boolean;
+    between: [string, string];
+    expose_on_parent: {
+        left: boolean;
+        right: boolean;
+    };
+    fields?: Record<string, any> | undefined;
+    queries?: any[] | undefined;
+}, {
+    pattern: "Junction";
+    between: [string, string];
+    fields?: Record<string, any> | undefined;
+    queries?: any[] | undefined;
+    temporal?: boolean | undefined;
+    sourced?: boolean | undefined;
+    expose_on_parent?: {
+        left?: boolean | undefined;
+        right?: boolean | undefined;
+    } | undefined;
+}>, {
+    pattern: "Junction";
+    temporal: boolean;
+    sourced: boolean;
+    between: [string, string];
+    expose_on_parent: {
+        left: boolean;
+        right: boolean;
+    };
+    fields?: Record<string, any> | undefined;
+    queries?: any[] | undefined;
+}, {
+    pattern: "Junction";
+    between: [string, string];
+    fields?: Record<string, any> | undefined;
+    queries?: any[] | undefined;
+    temporal?: boolean | undefined;
+    sourced?: boolean | undefined;
+    expose_on_parent?: {
+        left?: boolean | undefined;
+        right?: boolean | undefined;
+    } | undefined;
+}>, {
+    pattern: "Junction";
+    temporal: boolean;
+    sourced: boolean;
+    between: [string, string];
+    expose_on_parent: {
+        left: boolean;
+        right: boolean;
+    };
+    fields?: Record<string, any> | undefined;
+    queries?: any[] | undefined;
+}, {
+    pattern: "Junction";
+    between: [string, string];
+    fields?: Record<string, any> | undefined;
+    queries?: any[] | undefined;
+    temporal?: boolean | undefined;
+    sourced?: boolean | undefined;
+    expose_on_parent?: {
+        left?: boolean | undefined;
+        right?: boolean | undefined;
+    } | undefined;
+}>;
+type JunctionDefinition = z.infer<typeof JunctionDefinitionSchema>;
+declare function validateJunctionDefinition(data: unknown): JunctionDefinition;
+declare function safeValidateJunctionDefinition(data: unknown): {
+    success: boolean;
+    data?: JunctionDefinition;
+    error?: z.ZodError;
+};
+
 interface LoadResult {
     success: true;
     definition: EntityDefinition;
@@ -3485,6 +3628,27 @@ type LoadRelationshipResult = RelationshipLoadResult | RelationshipLoadError;
  * Load and validate a relationship definition from a YAML file
  */
 declare function loadRelationshipFromYaml(filePath: string): LoadRelationshipResult;
+interface JunctionLoadResult {
+    success: true;
+    definition: JunctionDefinition;
+    filePath: string;
+}
+interface JunctionLoadError {
+    success: false;
+    error: string;
+    details?: string[];
+    filePath: string;
+}
+type LoadJunctionResult = JunctionLoadResult | JunctionLoadError;
+/**
+ * Load and validate a junction definition from a YAML file.
+ *
+ * Mirrors {@link loadRelationshipFromYaml}: existence check → readFileSync →
+ * parseYaml → `JunctionDefinitionSchema.safeParse`. Returns a discriminated
+ * result; callers are expected to aggregate into `AnalysisIssue`s rather
+ * than throw.
+ */
+declare function loadJunctionFromYaml(filePath: string): LoadJunctionResult;
 
 /**
  * Entity Loader
@@ -3860,6 +4024,28 @@ declare const ActivityPattern: PatternDefinition<unknown>;
  */
 declare const BasePattern: PatternDefinition<unknown>;
 
+/**
+ * JunctionPattern — top-level discriminator for explicit many-to-many
+ * junction YAML files.
+ *
+ * Unlike `Activity` / `Synced` / `Metadata` (which attach to an entity via
+ * `pattern:` / `patterns:`), `Junction` IS the top-level YAML shape — a
+ * junction file's discriminator is `pattern: Junction`, not `entity:`.
+ * It therefore does not declare `repositoryClass` / `serviceClass`: the
+ * downstream Hygen-template leaf emits a dedicated junction repo/service
+ * per pairing.
+ *
+ * `columns` is set to `BaseJunctionFields` for two reasons:
+ *   1. Registry-side declaration of the shared shape — discoverable through
+ *      `getPattern('Junction').columns` by the downstream template leaf.
+ *   2. Satisfies the registry's `assertHasContribution()` check, which
+ *      insists every pattern contribute at least one of columns / repo /
+ *      service class. (See spec §"Open Questions Q3"; recommendation (a).)
+ *
+ * See `.ai-docs/stacks/codegen-app-patterns/specs/58.md`.
+ */
+declare const JunctionPattern: PatternDefinition<{}>;
+
 /**
  * KnowledgePattern — replaces `family: knowledge`.
  *
@@ -3900,6 +4086,27 @@ declare const MetadataPattern: PatternDefinition<unknown>;
  */
 declare const SyncedPattern: PatternDefinition<unknown>;
 
+/**
+ * BaseJunctionFields — shared column shape every junction table carries.
+ *
+ * Per-pairing role columns and pairing-specific fields are declared in the
+ * consumer YAML's `fields:` block and are NOT part of this shape.
+ *
+ * Exposed as a TS const so two consumers can import it:
+ *   - `junction.pattern.ts`              — registers it as the pattern's
+ *                                          column contribution so the
+ *                                          registry's `assertHasContribution()`
+ *                                          check passes structurally.
+ *   - `junction-definition.schema.ts`    — uses the name set for the
+ *                                          reserved-column collision check
+ *                                          on the consumer's `fields:` block.
+ *
+ * See ADR-031 and `.ai-docs/stacks/codegen-app-patterns/specs/58.md`.
+ */
+
+declare const BaseJunctionFields: readonly PatternColumnContribution[];
+declare const BASE_JUNCTION_FIELD_NAMES: ReadonlySet<string>;
+
 /**
  * Pattern Registry — library + app pattern storage and discovery.
  *
@@ -4137,4 +4344,4 @@ declare function validateEntities(entitiesDir: string): {
     errors: string[];
 };
 
-export { ActivityPattern, type AnalysisIssue, type AnalysisResult, type AnalyzeDomainOptions, type AnyPatternDefinition, BasePattern, type CodegenManifest, type DomainGraph, type DomainStatistics, type EntityNode, KnowledgePattern, type LoadAppPatternsResult, type ManifestEntity, type ManifestField, type ManifestRelationship, type ManifestSuggestion, MetadataPattern, type OrchestrationPatternDefinition, type OrchestrationProjectContext, type OrchestrationRegistrySpec, type OutputFormat, type ParsedEntity, type ParsedEvent, type ParsedField, type ParsedProviderSync, type ParsedQuery, type ParsedRelationship, type ParsedRelationshipDefinition, type ParsedSync, type ParsedTypeDirection, type PathHop, type PatternColumnContribution, type PatternDefinition, type PatternKind, type PatternProjectContext, type RelationshipEdge, type Severity, SyncedPattern, type TransitivePath, type TransitiveSuggestion, analyzeDomain, buildDomainGraph, checkConsistency, computeStatistics, defineOrchestrationPattern, definePattern, findCircularDependencies, findOrphanEntities, formatConsole, formatJson, formatMarkdown, formatMermaidGraph, getAllOrchestrationPatterns, getAllPatternNames, getAppPatternNames, getLibraryPatternNames, getOrchestrationPattern, getOrchestrationPatternNames, getPattern, getRelatedEntities, isDomainPattern, isOrchestrationPattern, isPatternDefinition, loadAppPatterns, loadEntities, loadEntityFromYaml, loadRelationshipFromYaml, loadRelationships, registerLibraryPattern, validateEntities, validateOrchestrationProject, validatePatternComposition, validatePatternProject };
+export { ActivityPattern, type AnalysisIssue, type AnalysisResult, type AnalyzeDomainOptions, type AnyPatternDefinition, BASE_JUNCTION_FIELD_NAMES, BaseJunctionFields, BasePattern, type CodegenManifest, type DomainGraph, type DomainStatistics, type EntityNode, type JunctionDefinition, JunctionDefinitionSchema, JunctionPattern, KnowledgePattern, type LoadAppPatternsResult, type ManifestEntity, type ManifestField, type ManifestRelationship, type ManifestSuggestion, MetadataPattern, type OrchestrationPatternDefinition, type OrchestrationProjectContext, type OrchestrationRegistrySpec, type OutputFormat, type ParsedEntity, type ParsedEvent, type ParsedField, type ParsedProviderSync, type ParsedQuery, type ParsedRelationship, type ParsedRelationshipDefinition, type ParsedSync, type ParsedTypeDirection, type PathHop, type PatternColumnContribution, type PatternDefinition, type PatternKind, type PatternProjectContext, type RelationshipEdge, type Severity, SyncedPattern, type TransitivePath, type TransitiveSuggestion, analyzeDomain, buildDomainGraph, checkConsistency, computeStatistics, defineOrchestrationPattern, definePattern, findCircularDependencies, findOrphanEntities, formatConsole, formatJson, formatMarkdown, formatMermaidGraph, getAllOrchestrationPatterns, getAllPatternNames, getAppPatternNames, getLibraryPatternNames, getOrchestrationPattern, getOrchestrationPatternNames, getPattern, getRelatedEntities, isDomainPattern, isOrchestrationPattern, isPatternDefinition, loadAppPatterns, loadEntities, loadEntityFromYaml, loadJunctionFromYaml, loadRelationshipFromYaml, loadRelationships, registerLibraryPattern, safeValidateJunctionDefinition, validateEntities, validateJunctionDefinition, validateOrchestrationProject, validatePatternComposition, validatePatternProject };

package/dist/src/index.js

@@ -1754,6 +1754,90 @@ function deriveUniqueConstraint(config) {
   return columns;
 }
 
+// src/schema/junction-definition.schema.ts
+import { z as z6 } from "zod";
+
+// src/patterns/library/base-junction-fields.ts
+var BaseJunctionFields = [
+  { name: "is_primary", type: "boolean" },
+  { name: "started_at", type: "timestamp" },
+  { name: "ended_at", type: "timestamp" },
+  { name: "sourced_from", type: "text" },
+  { name: "confidence", type: "numeric(5,4)" },
+  { name: "matched_at", type: "timestamp" }
+];
+var BASE_JUNCTION_FIELD_NAMES = new Set(
+  BaseJunctionFields.map((c) => c.name)
+);
+
+// src/schema/junction-definition.schema.ts
+var EntityNameSchema = z6.string().regex(/^[a-z][a-z0-9_]*$/, "Entity reference must be snake_case");
+var JunctionDefinitionSchema = z6.object({
+  /** Discriminator literal — `pattern: Junction`. */
+  pattern: z6.literal("Junction"),
+  /**
+   * Exactly two endpoint entity names. Both intra- and cross-domain
+   * pairings are accepted; entity existence is validated by the
+   * analyzer in a later leaf.
+   */
+  between: z6.tuple([EntityNameSchema, EntityNameSchema]),
+  /**
+   * Emit BaseJunctionFields temporal columns (`started_at`, `ended_at`,
+   * `matched_at`). Default true. Matches Relationship's `temporal` toggle.
+   */
+  temporal: z6.boolean().optional().default(true),
+  /**
+   * Emit BaseJunctionFields sourcing columns (`sourced_from`,
+   * `confidence`). Default true. Matches Relationship's `sourced` toggle.
+   */
+  sourced: z6.boolean().optional().default(true),
+  /**
+   * Junction-specific fields beyond `BaseJunctionFields`. Includes the
+   * per-pairing role enum (declared inline; never shared across
+   * pairings). Shape is validated downstream by the codegen layer
+   * using the existing entity FieldDefinitionSchema.
+   */
+  fields: z6.record(z6.string(), z6.any()).optional(),
+  /**
+   * Declarative queries — same syntax as entity queries. Shape is
+   * validated downstream by the codegen layer.
+   */
+  queries: z6.array(z6.any()).optional(),
+  /**
+   * Per-side opt-out for parent-service fan-out (CGP-60). When a side
+   * is `false`, the `_inject-parent-service-*` templates emit nothing
+   * on that side (and the corresponding module wiring is skipped).
+   * The junction service body is always emitted regardless. Defaults
+   * to `{ left: true, right: true }`.
+   */
+  expose_on_parent: z6.object({
+    left: z6.boolean().optional().default(true),
+    right: z6.boolean().optional().default(true)
+  }).optional().default({ left: true, right: true })
+}).strict().refine((d) => d.between[0] !== d.between[1], {
+  message: "`between` endpoints must be distinct",
+  path: ["between"]
+}).refine(
+  (d) => {
+    const fieldNames = Object.keys(d.fields ?? {});
+    return !fieldNames.some((n) => BASE_JUNCTION_FIELD_NAMES.has(n));
+  },
+  {
+    message: "`fields:` block redeclares a reserved BaseJunctionFields column (is_primary, started_at, ended_at, sourced_from, confidence, matched_at)",
+    path: ["fields"]
+  }
+);
+function validateJunctionDefinition(data) {
+  return JunctionDefinitionSchema.parse(data);
+}
+function safeValidateJunctionDefinition(data) {
+  const result = JunctionDefinitionSchema.safeParse(data);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  return { success: false, error: result.error };
+}
+
 // src/utils/yaml-loader.ts
 function loadEntityFromYaml(filePath) {
   if (!existsSync(filePath)) {
@@ -1852,6 +1936,51 @@ function loadRelationshipFromYaml(filePath) {
     filePath
   };
 }
+function loadJunctionFromYaml(filePath) {
+  if (!existsSync(filePath)) {
+    return {
+      success: false,
+      error: `File not found: ${filePath}`,
+      filePath
+    };
+  }
+  let content;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch (err) {
+    return {
+      success: false,
+      error: `Failed to read file: ${filePath}`,
+      details: [err instanceof Error ? err.message : String(err)],
+      filePath
+    };
+  }
+  let parsed;
+  try {
+    parsed = parseYaml(content);
+  } catch (err) {
+    return {
+      success: false,
+      error: `Invalid YAML syntax in ${filePath}`,
+      details: [err instanceof Error ? err.message : String(err)],
+      filePath
+    };
+  }
+  const result = JunctionDefinitionSchema.safeParse(parsed);
+  if (!result.success) {
+    return {
+      success: false,
+      error: `Validation failed for ${filePath}`,
+      details: formatZodErrors(result.error),
+      filePath
+    };
+  }
+  return {
+    success: true,
+    definition: result.data,
+    filePath
+  };
+}
 
 // src/parser/load-entities.ts
 function transformToEntity(result) {
@@ -3754,6 +3883,16 @@ var BasePattern = definePattern({
   description: "Identity pattern \u2014 base CRUD, no extra columns or methods"
 });
 
+// src/patterns/library/junction.pattern.ts
+import { z as z7 } from "zod";
+var JunctionPatternConfigSchema = z7.object({}).strict();
+var JunctionPattern = definePattern({
+  name: "Junction",
+  description: "Explicit many-to-many junction with role + temporal + sourcing metadata",
+  columns: [...BaseJunctionFields],
+  configSchema: JunctionPatternConfigSchema
+});
+
 // src/patterns/library/knowledge.pattern.ts
 var KnowledgePattern = definePattern({
   name: "Knowledge",
@@ -3818,6 +3957,7 @@ registerLibraryPattern(SyncedPattern);
 registerLibraryPattern(ActivityPattern);
 registerLibraryPattern(KnowledgePattern);
 registerLibraryPattern(MetadataPattern);
+registerLibraryPattern(JunctionPattern);
 
 // src/index.ts
 async function analyzeDomain(entitiesDir, relationshipsOrOptions) {
@@ -3872,7 +4012,11 @@ function validateEntities(entitiesDir) {
 }
 export {
   ActivityPattern,
+  BASE_JUNCTION_FIELD_NAMES,
+  BaseJunctionFields,
   BasePattern,
+  JunctionDefinitionSchema,
+  JunctionPattern,
   KnowledgePattern,
   MetadataPattern,
   SyncedPattern,
@@ -3902,10 +4046,13 @@ export {
   loadAppPatterns,
   loadEntities,
   loadEntityFromYaml,
+  loadJunctionFromYaml,
   loadRelationshipFromYaml,
   loadRelationships,
   registerLibraryPattern,
+  safeValidateJunctionDefinition,
   validateEntities,
+  validateJunctionDefinition,
   validateOrchestrationProject,
   validatePatternComposition,
   validatePatternProject