@pattern-stack/codegen 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,7 @@
   },
   "files": [
     "dist",
+    "runtime",
     "templates",
     "CHANGELOG.md",
     "README.md",

package/runtime/analytics/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Analytics layer — public API
+ *
+ * Re-exports types, metrics, specs, and measure packs.
+ */
+export {
+  AggregationType,
+  DimensionType,
+  EntityType,
+  MetricType,
+  TimeGranularity,
+} from './types';
+export type {
+  NonAdditiveDimensionConfig,
+  SemanticFieldConfig,
+} from './types';
+export type {
+  SimpleMetric,
+  DerivedMetric,
+  RatioMetric,
+  CumulativeMetric,
+  MetricDefinition,
+} from './metrics';
+export type {
+  MeasureSpec,
+  DimensionSpec,
+  EntitySpec,
+  SemanticModelSpec,
+} from './specs';
+export type { MonetaryMeasures } from './packs/monetary-measures';
+export type { CrmEntityMeasures } from './packs/crm-entity-measures';

package/runtime/analytics/metrics.ts

@@ -0,0 +1,85 @@
+/**
+ * Metric composition types for the analytics layer.
+ *
+ * Ported from the Python reference (pattern_stack/atoms/semantic/metrics.py).
+ * These interfaces describe the four metric types that can be declared on
+ * entity YAML specs and compiled into cube.js metric definitions.
+ */
+
+import type { AggregationType, TimeGranularity } from './types';
+
+// ============================================================================
+// Metric interfaces
+// ============================================================================
+
+/**
+ * A simple metric based on a single measure.
+ *
+ * Example:
+ *   { type: 'simple', measure: 'amount' }
+ *   { type: 'simple', measure: 'amount', agg: 'count', filter: "status = 'completed'" }
+ */
+export interface SimpleMetric {
+  type: 'simple';
+  measure: string;
+  agg?: AggregationType;
+  filter?: string;
+  description?: string;
+  label?: string;
+}
+
+/**
+ * A derived metric computed from an expression over other metrics.
+ *
+ * Example:
+ *   { type: 'derived', expr: 'total_revenue / order_count', metrics: ['total_revenue', 'order_count'] }
+ */
+export interface DerivedMetric {
+  type: 'derived';
+  expr: string;
+  metrics: string[];
+  description?: string;
+  label?: string;
+}
+
+/**
+ * A ratio metric computing numerator / denominator.
+ *
+ * Example:
+ *   { type: 'ratio', numerator: 'won_deals', denominator: 'total_deals' }
+ */
+export interface RatioMetric {
+  type: 'ratio';
+  numerator: string | SimpleMetric;
+  denominator: string | SimpleMetric;
+  filter?: string;
+  description?: string;
+  label?: string;
+}
+
+/**
+ * A cumulative metric for time-series accumulation.
+ *
+ * Specify either window OR grain_to_date, not both.
+ *
+ * Example:
+ *   { type: 'cumulative', measure: 'revenue', window: '28 days' }
+ *   { type: 'cumulative', measure: 'order_count', grain_to_date: 'month' }
+ */
+export interface CumulativeMetric {
+  type: 'cumulative';
+  measure: string;
+  window?: string;
+  grain_to_date?: TimeGranularity;
+  description?: string;
+  label?: string;
+}
+
+/**
+ * Union type of all metric definitions.
+ */
+export type MetricDefinition =
+  | SimpleMetric
+  | DerivedMetric
+  | RatioMetric
+  | CumulativeMetric;

package/runtime/analytics/packs/crm-entity-measures.ts

@@ -0,0 +1,20 @@
+/**
+ * CrmEntityMeasures — measure pack interface for CRM entities.
+ *
+ * Entities that include the 'crm_entity' measure pack implement this
+ * interface on their generated analytics provider.
+ */
+
+import type { AnalyticsQueryOpts, ResultRow } from '../../subsystems/analytics/analytics-query.protocol';
+
+export interface CrmEntityMeasures {
+  /**
+   * Count of active (non-deleted) entities.
+   */
+  activeCount(opts?: AnalyticsQueryOpts): Promise<ResultRow[]>;
+
+  /**
+   * Count of entities created in the last N days.
+   */
+  createdInLastNDays(n: number, opts?: AnalyticsQueryOpts): Promise<ResultRow[]>;
+}

package/runtime/analytics/packs/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Measure packs — public API
+ */
+export type { MonetaryMeasures } from './monetary-measures';
+export type { CrmEntityMeasures } from './crm-entity-measures';

package/runtime/analytics/packs/monetary-measures.ts

@@ -0,0 +1,20 @@
+/**
+ * MonetaryMeasures — measure pack interface for revenue / monetary fields.
+ *
+ * Entities that include the 'monetary' measure pack implement this interface
+ * on their generated analytics provider.
+ */
+
+import type { AnalyticsQueryOpts, ResultRow } from '../../subsystems/analytics/analytics-query.protocol';
+
+export interface MonetaryMeasures {
+  /**
+   * Total revenue (sum of the monetary measure).
+   */
+  totalRevenue(opts?: AnalyticsQueryOpts): Promise<ResultRow[]>;
+
+  /**
+   * Revenue broken down by a dimension.
+   */
+  revenueBy(dimension: string, opts?: AnalyticsQueryOpts): Promise<ResultRow[]>;
+}

package/runtime/analytics/specs.ts

@@ -0,0 +1,54 @@
+/**
+ * Intermediate spec types for the analytics layer.
+ *
+ * Ported from the Python reference (pattern_stack/atoms/semantic/manifest.py).
+ * These interfaces are the intermediate representation used when extracting
+ * semantic metadata from entity YAML and converting it into cube.js schema.
+ */
+
+import type { AggregationType, DimensionType, EntityType, NonAdditiveDimensionConfig, TimeGranularity } from './types';
+import type { MetricDefinition } from './metrics';
+
+// ============================================================================
+// Spec interfaces
+// ============================================================================
+
+export interface MeasureSpec {
+  name: string;
+  agg: AggregationType;
+  expr?: string;
+  agg_time_dimension?: string;
+  non_additive_dimension?: NonAdditiveDimensionConfig;
+  description?: string;
+  label?: string;
+}
+
+export interface DimensionSpec {
+  name: string;
+  dimension_type: DimensionType;
+  expr?: string;
+  time_granularity?: TimeGranularity;
+  is_partition?: boolean;
+  description?: string;
+  label?: string;
+}
+
+export interface EntitySpec {
+  name: string;
+  entity_type: EntityType;
+  expr?: string;
+  role?: string;
+  description?: string;
+  label?: string;
+}
+
+export interface SemanticModelSpec {
+  name: string;
+  table_name: string;
+  measures: MeasureSpec[];
+  dimensions: DimensionSpec[];
+  entities: EntitySpec[];
+  metrics: MetricDefinition[];
+  primary_entity?: string;
+  default_agg_time_dimension?: string;
+}

package/runtime/analytics/types.ts

@@ -0,0 +1,105 @@
+/**
+ * Semantic type definitions for the analytics layer.
+ *
+ * These types mirror MetricFlow / dbt-semantic-interfaces enums but are
+ * defined locally so consumers don't need the full dependency for basic
+ * field configuration. When the cube.js backend is used, these values
+ * map 1:1 to cube measure/dimension types.
+ */
+
+// ============================================================================
+// Enums
+// ============================================================================
+
+export enum AggregationType {
+  SUM = 'sum',
+  MIN = 'min',
+  MAX = 'max',
+  COUNT = 'count',
+  COUNT_DISTINCT = 'count_distinct',
+  AVERAGE = 'average',
+  MEDIAN = 'median',
+  PERCENTILE = 'percentile',
+  SUM_BOOLEAN = 'sum_boolean',
+}
+
+export enum DimensionType {
+  CATEGORICAL = 'categorical',
+  TIME = 'time',
+}
+
+export enum EntityType {
+  PRIMARY = 'primary',
+  UNIQUE = 'unique',
+  FOREIGN = 'foreign',
+  NATURAL = 'natural',
+}
+
+export enum MetricType {
+  SIMPLE = 'simple',
+  DERIVED = 'derived',
+  RATIO = 'ratio',
+  CUMULATIVE = 'cumulative',
+  CONVERSION = 'conversion',
+}
+
+/**
+ * Time granularity for time dimensions.
+ *
+ * Sub-day granularities (hour, minute, second) are intentionally omitted
+ * because cube.js does not support them.
+ */
+export enum TimeGranularity {
+  DAY = 'day',
+  WEEK = 'week',
+  MONTH = 'month',
+  QUARTER = 'quarter',
+  YEAR = 'year',
+}
+
+// ============================================================================
+// Config interfaces
+// ============================================================================
+
+/**
+ * Configuration for non-additive dimensions on measures.
+ *
+ * Non-additive dimensions specify that a measure cannot be summed across
+ * certain dimensions. For example, inventory balances cannot be summed
+ * across time — you need the latest value, not the sum.
+ */
+export interface NonAdditiveDimensionConfig {
+  name: string;
+  window_choice?: AggregationType;
+  window_groupings?: string[];
+}
+
+/**
+ * Complete semantic configuration for a field.
+ *
+ * Used to store all semantic metadata on a field definition for later
+ * extraction by the manifest builder / cube schema generator.
+ */
+export interface SemanticFieldConfig {
+  // Measure configuration
+  measure?: boolean;
+  agg?: AggregationType;
+  agg_time_dimension?: string;
+  non_additive_dimension?: NonAdditiveDimensionConfig;
+
+  // Dimension configuration
+  dimension?: boolean;
+  dimension_type?: DimensionType;
+  time_granularity?: TimeGranularity;
+  is_partition?: boolean;
+
+  // Entity configuration
+  entity?: boolean;
+  entity_type?: EntityType;
+  entity_role?: string;
+
+  // Common
+  semantic_expr?: string;
+  semantic_label?: string;
+  visibility?: 'internal' | 'agent' | 'public';
+}

package/runtime/base-classes/activity-entity-repository.ts

@@ -0,0 +1,50 @@
+/**
+ * ActivityEntityRepository<TEntity>
+ *
+ * Family-specific base for activity entities (emails, calls, meetings, notes).
+ * Adds date-range queries, user/opportunity scoping, and recency ordering.
+ *
+ * Concrete repos extend this and declare their table + behaviors.
+ */
+import { eq, between, desc } from 'drizzle-orm';
+import { BaseRepository } from './base-repository';
+
+export abstract class ActivityEntityRepository<TEntity> extends BaseRepository<TEntity> {
+  /**
+   * Find activities within a date range (inclusive).
+   */
+  async findByDateRange(start: Date, end: Date): Promise<TEntity[]> {
+    const rows = await this.baseQuery()
+      .where(between(this.table['occurredAt'], start, end));
+    return rows as TEntity[];
+  }
+
+  /**
+   * Find all activities for a specific user.
+   */
+  async findByUserId(userId: string): Promise<TEntity[]> {
+    const rows = await this.baseQuery()
+      .where(eq(this.table['userId'], userId));
+    return rows as TEntity[];
+  }
+
+  /**
+   * Find all activities for a specific opportunity.
+   */
+  async findByOpportunityId(opportunityId: string): Promise<TEntity[]> {
+    const rows = await this.baseQuery()
+      .where(eq(this.table['opportunityId'], opportunityId));
+    return rows as TEntity[];
+  }
+
+  /**
+   * Find the most recent activities for an opportunity, ordered by occurredAt desc.
+   */
+  async findRecentByOpportunityId(opportunityId: string, limit = 10): Promise<TEntity[]> {
+    const rows = await this.baseQuery()
+      .where(eq(this.table['opportunityId'], opportunityId))
+      .orderBy(desc(this.table['occurredAt']))
+      .limit(limit);
+    return rows as TEntity[];
+  }
+}

package/runtime/base-classes/activity-entity-service.ts

@@ -0,0 +1,48 @@
+/**
+ * ActivityEntityService<TRepo, TEntity>
+ *
+ * Family-specific base service for activity entities.
+ * Delegates to an activity repository that provides date-range,
+ * user, and opportunity queries.
+ */
+import { BaseService, type IBaseRepository } from './base-service';
+
+export interface IActivityEntityRepository<TEntity> extends IBaseRepository<TEntity> {
+  findByDateRange(start: Date, end: Date): Promise<TEntity[]>;
+  findByUserId(userId: string): Promise<TEntity[]>;
+  findByOpportunityId(opportunityId: string): Promise<TEntity[]>;
+  findRecentByOpportunityId(opportunityId: string, limit?: number): Promise<TEntity[]>;
+}
+
+export abstract class ActivityEntityService<
+  TRepo extends IActivityEntityRepository<TEntity>,
+  TEntity,
+> extends BaseService<TRepo, TEntity> {
+  /**
+   * Find activities within a date range (inclusive).
+   */
+  findByDateRange(start: Date, end: Date): Promise<TEntity[]> {
+    return this.repository.findByDateRange(start, end);
+  }
+
+  /**
+   * Find all activities for a specific user.
+   */
+  findByUser(userId: string): Promise<TEntity[]> {
+    return this.repository.findByUserId(userId);
+  }
+
+  /**
+   * Find all activities for a specific opportunity.
+   */
+  findByOpportunity(opportunityId: string): Promise<TEntity[]> {
+    return this.repository.findByOpportunityId(opportunityId);
+  }
+
+  /**
+   * Find the most recent activities for an opportunity.
+   */
+  findRecent(opportunityId: string, limit?: number): Promise<TEntity[]> {
+    return this.repository.findRecentByOpportunityId(opportunityId, limit);
+  }
+}

package/runtime/base-classes/base-read-use-cases.ts

@@ -0,0 +1,88 @@
+/**
+ * Base read use cases
+ *
+ * Abstract base classes for auto-generated per-entity read use cases.
+ * Controllers always import use case classes — never services directly (ADR-003).
+ *
+ * Each entity gets a single generated file with two named exports:
+ *   - ContactFindByIdUseCase extends BaseFindByIdUseCase<ContactService, Contact>
+ *   - ContactListUseCase extends BaseListUseCase<ContactService, Contact>
+ *
+ * Note: @Injectable() is applied on concrete use case classes (not here),
+ * matching the pattern established by BaseRepository and BaseService.
+ */
+
+// ============================================================================
+// BaseFindByIdUseCase
+// ============================================================================
+
+/**
+ * Structural interface for any service that supports findById.
+ * Keeps base use cases decoupled from concrete service implementations.
+ */
+export interface IFindByIdService<TEntity> {
+  findById(id: string): Promise<TEntity | null>;
+}
+
+/**
+ * Base class for generated FindById use cases.
+ *
+ * Generated usage:
+ * ```typescript
+ * @Injectable()
+ * export class ContactFindByIdUseCase extends BaseFindByIdUseCase<ContactService, Contact> {
+ *   constructor(service: ContactService) { super(service); }
+ * }
+ * ```
+ */
+export abstract class BaseFindByIdUseCase<
+  TService extends IFindByIdService<TEntity>,
+  TEntity,
+> {
+  constructor(protected readonly service: TService) {}
+
+  /**
+   * Find a single entity by its primary key.
+   * Returns null if not found.
+   */
+  execute(id: string): Promise<TEntity | null> {
+    return this.service.findById(id);
+  }
+}
+
+// ============================================================================
+// BaseListUseCase
+// ============================================================================
+
+/**
+ * Structural interface for any service that supports list.
+ */
+export interface IListService<TEntity> {
+  list(options?: unknown): Promise<TEntity[]>;
+}
+
+/**
+ * Base class for generated List use cases.
+ *
+ * Generated usage:
+ * ```typescript
+ * @Injectable()
+ * export class ContactListUseCase extends BaseListUseCase<ContactService, Contact> {
+ *   constructor(service: ContactService) { super(service); }
+ * }
+ * ```
+ */
+export abstract class BaseListUseCase<
+  TService extends IListService<TEntity>,
+  TEntity,
+> {
+  constructor(protected readonly service: TService) {}
+
+  /**
+   * List all entities (no filters).
+   * Controllers that need filtered lists should use a dedicated use case.
+   */
+  execute(): Promise<TEntity[]> {
+    return this.service.list();
+  }
+}