@pattern-stack/codegen 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- **Noun-verb CLI** — Clipanion-based CLI replacing the legacy single-file handler. Commands: `entity`, `subsystem`, `project`, `dev`. Each noun has a summary pane with dynamic hints. (ADR-015)
+- **UI toolkit** — chalk theme tokens, icons with ASCII fallback, Ora spinners, pane/hints rendering, `--json` mode across all commands. (ADR-016)
+- **Barrel files** — `src/generated/modules.ts` and `src/generated/schema.ts` replace app.module.ts injection. Codegen never touches user-authored files. (ADR-017)
+- **`codegen init`** — scaffolds a consumer project: codegen.config.yaml, tsconfig path aliases, DatabaseModule, runtime shims, empty barrels, example entity YAML.
+- **`codegen dev`** — manages Docker services (Postgres + Redis), starts/stops the NestJS app, shows health dashboard with endpoint probing.
+- **Redis event bus** — `EventsModule.forRoot({ backend: 'redis' })` using ioredis Pub/Sub. Optional peer dependency.
+- **Declarative query methods on repository** — clean-lite-ps repository template now generates `findByX` methods from the `queries:` block.
+- **Smoke test harness** — `just test-smoke` scaffolds a fresh project, generates entities, runs `tsc --noEmit`. Catches template and import regressions.
+- **Consumer setup docs** — `docs/CONSUMER-SETUP.md` covering the full wire-up contract: tsconfig aliases, DatabaseModule, runtime shims, barrels.
+- **Browser-pilot agent** — Playwright + Chrome DevTools + Lighthouse MCP for endpoint verification and visual QA.
+- **Team agents** — architect, builder, coordinator, validator adapted for codegen-patterns workflows.
+- **Dev companion commands** — `/dev-check`, `/dev-test`, `/dev-debug` for interactive development with teammate/subagent fallback.
+- **Claude Code skill** — `.claude/skills/codegen/SKILL.md` teaches Claude the full CLI reference. Install with `just install-skill <target>`.
+
+### Changed
+- **Package renamed** from `@anthropic/codegen` to `@pattern-stack/codegen`.
+- **Repo reorganized** — source under `src/`, shipped runtime under `runtime/`, tests under `src/__tests__/`. Root cut from ~17 directories to 5.
+- **`output/` renamed to `src/formatters/`** for clarity.
+- **`shared/` renamed to `runtime/`** — makes the generator-vs-emitted boundary visible.
+- **`generate.cleanLitePs`** replaced by `generate.architecture: 'clean' | 'clean-lite-ps'` enum. No deprecation shim (no existing users).
+- **`generate.frontend`** added (default `false`). Scanner flips true when `apps/frontend/` detected.
+- **Use case naming** — declarative queries now emit entity-prefixed names (`FindAccountByDomainUseCase`, not `FindByDomainUseCase`). Prevents cross-entity collisions.
+- **WithAnalytics mixin** — preserves abstract base class type and method signatures through the mixin chain.
+- **`baseQuery()`** uses Drizzle `$dynamic()` for consistent return type. Fixes `.where()` chaining in all family repositories.
+- **Subsystem install default path** — `shared/subsystems/` (was `src/shared/subsystems/`).
+- **Drizzle backend filter** — `subsystem install --backend drizzle` now keeps memory backend too (needed for tests).
+
+### Fixed
+- Clean-lite-ps and clean-architecture templates no longer both emit when one is selected.
+- Frontend templates no longer emit when `generate.frontend` is false.
+- `app.module.ts` injection removed entirely (replaced by barrels).
+- Templates dir resolves correctly when CLI invoked from outside the repo.
+- WithAnalytics template import changed from `base-analytics-service` to `with-analytics` (matches runtime filename).
+- EJS HTML-escape in declarative query templates — enum union types (`'active' | 'inactive'`) no longer rendered as `&#39;active&#39;`.
+- Validator includes `belongs_to` foreign key fields in available-fields set for query validation.
+- `MetadataEntityRepository.upsertMany` signature matches base class (conflictTarget now optional).
+- `Column` import from drizzle-orm/pg-core changed to `PgColumn` (matches 0.45 exports).
+- `prompt.js` config imports fixed after `src/` reorg.
+
+### Removed
+- Legacy `src/cli.ts` (25K single-file CLI) — replaced by `src/cli/` noun-verb architecture.
+- 11 Hygen inject templates that mutated `app.module.ts` and `schema.ts`.
+- Stale docs: `CODEGEN-EVOLUTION-PLAN.md`, `SNAKE_CAMEL_SYNC.md`, `context-engine.md`, `v2-initiative-overview.md`, `contact-module-sketch.md`.
+- Empty `tools/` directory.
+
+## [0.2.0] - 2026-04-12
+
+### Added
+- Infrastructure subsystems: events, jobs, cache, storage (ADR-008). Protocol → Backend → Factory pattern.
+- CRM family renamed to Synced (domain-agnostic).
+- Getting Started guide.
+- Declarative query codegen from `queries:` YAML block.
+- Clean-Lite-PS template pipeline.
+- Entity family base classes (synced, activity, metadata, knowledge).
+- BaseRepository and BaseService with behavior injection.
+- Project scanner for convention detection.
+
+## [0.1.0] - 2026-04-12
+
+Initial release. YAML schema, parser, analyzer, Hygen template pipeline, baseline test infrastructure.

package/README.md

@@ -0,0 +1,214 @@
+# codegen-patterns
+
+Define entities in YAML. Generate a full NestJS + Drizzle backend — repositories, services, controllers, DTOs, use cases, module wiring — in one command.
+
+```bash
+codegen entity new entities/contact.yaml
+```
+
+Built for teams that want consistent architecture without hand-writing the same CRUD scaffolding for every entity. Works with two backend layouts (full Clean Architecture or Clean-Lite-PS) and generates infrastructure subsystems (events, jobs, cache, storage) following Protocol → Backend → Factory patterns.
+
+## Install
+
+```bash
+bun install                       # install deps
+mise install                      # pin bun + node versions (optional, recommended)
+```
+
+## Define an Entity
+
+```yaml
+# entities/contact.yaml
+entity:
+  name: contact
+  plural: contacts
+  table: contacts
+  family: synced                    # synced | activity | metadata | knowledge
+
+fields:
+  email:
+    type: string
+    required: true
+    max_length: 255
+    index: true
+  first_name:
+    type: string
+    required: true
+  status:
+    type: enum
+    choices: [active, inactive]
+
+behaviors:
+  - timestamps                      # createdAt, updatedAt
+  - soft_delete                     # deletedAt + automatic query filtering
+
+relationships:
+  account:
+    type: belongs_to
+    target: account
+    foreign_key: account_id
+
+queries:
+  - by: [email]
+    unique: true
+  - by: [account_id]
+    order: created_at desc
+```
+
+## Generate
+
+```bash
+codegen entity new entities/contact.yaml     # one entity
+codegen entity new --all                     # all entities
+codegen entity validate                      # check YAML before generating
+codegen entity list                          # see what's defined
+```
+
+Every run regenerates barrel files (`src/generated/modules.ts` and `src/generated/schema.ts`) so your `app.module.ts` never needs editing after the initial one-line wire-up.
+
+## CLI
+
+The CLI uses a noun-verb pattern. Running any noun alone shows its current state and suggests next steps:
+
+```bash
+codegen                          # project overview
+codegen entity                   # entity summary + hints
+codegen subsystem                # installed vs available
+codegen project                  # config + framework detection
+```
+
+### Entity Commands
+
+```bash
+codegen entity new <yaml>        # generate from YAML
+codegen entity new --all         # regenerate all entities
+codegen entity new --dry-run     # preview without writing
+codegen entity list              # tabular entity list
+codegen entity validate [dir]    # schema + cross-reference checks
+```
+
+### Subsystem Commands
+
+```bash
+codegen subsystem install events     # domain event bus (transactional outbox)
+codegen subsystem install jobs       # background job queue (pg-boss pattern)
+codegen subsystem install cache      # key-value cache with TTL
+codegen subsystem install storage    # file storage (local filesystem)
+codegen subsystem list               # show installed + available
+```
+
+Each subsystem generates a protocol (interface), Drizzle backend (Postgres), memory backend (tests), and a NestJS module with `forRoot({ backend })` factory.
+
+### Project Commands
+
+```bash
+codegen init                     # scaffold a new consumer project
+codegen project scan             # detect conventions → propose config
+codegen project config           # view resolved config
+```
+
+## What Gets Generated
+
+**Clean Architecture** (default, `generate.architecture: clean`):
+```
+domain/{entity}/                   Entity class + repository interface
+application/commands/{entity}/     Create, Update, Delete use cases
+application/queries/{entity}/      GetById, List, declarative queries
+infrastructure/persistence/        Drizzle schema + repository impl
+presentation/rest/                 REST controller
+modules/                           NestJS module wiring
+```
+
+**Clean-Lite-PS** (`generate.architecture: clean-lite-ps`):
+```
+modules/{plural}/
+  {entity}.entity.ts               Drizzle table + types
+  {entity}.repository.ts           Extends family base class
+  {entity}.service.ts              Extends family base service
+  {entity}.controller.ts           REST endpoints
+  {plural}.module.ts               NestJS module
+  dto/                             Create, Update, Output DTOs
+  use-cases/                       FindById, List, declarative queries
+```
+
+## Entity Families
+
+Families provide pre-built base classes with domain-specific query patterns:
+
+| Family | When to Use | Key Methods |
+|--------|-------------|-------------|
+| `synced` | CRM-synced entities (contacts, accounts) | `findByExternalId`, `syncUpsert`, `findAllByUserId` |
+| `activity` | Time-based events (emails, calls, meetings) | `findByDateRange`, `findRecentByOpportunityId` |
+| `metadata` | Key-value data (tags, custom fields) | `findByEntityIdAndType`, `upsertMany` |
+| `knowledge` | Vector-searchable content | Stub (needs pgvector) |
+| *(none)* | Generic CRUD | Base repository + service only |
+
+## Declarative Queries
+
+The `queries:` block generates typed repository methods, use case classes, and module registration:
+
+```yaml
+queries:
+  - by: [email]              # → FindContactByEmailUseCase (unique)
+    unique: true
+  - by: [account_id]         # → FindContactByAccountIdUseCase (ordered)
+    order: created_at desc
+  - by: [user_id, status]    # → FindContactByUserIdAndStatusUseCase (compound)
+```
+
+## Configuration
+
+`codegen.config.yaml` in your project root:
+
+```yaml
+paths:
+  backend_src: src
+  entities_dir: entities
+  generated: src/generated
+
+generate:
+  architecture: clean-lite-ps    # clean | clean-lite-ps
+  frontend: false                # default false; scanner detects apps/frontend/
+  commands: true
+  queries: true
+
+naming:
+  fileCase: kebab-case
+  suffixStyle: dotted            # .entity.ts vs Entity.ts
+  terminology:
+    command: use-case
+    query: use-case
+```
+
+Auto-detect your project's conventions with `codegen project scan`.
+
+## Using in Your Project
+
+See [docs/CONSUMER-SETUP.md](docs/CONSUMER-SETUP.md) for the full consumer contract: tsconfig path aliases, `DatabaseModule` scaffold, runtime shims, and the one-time `app.module.ts` wire-up.
+
+See [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) for a walkthrough of entity YAML authoring.
+
+## Project Layout
+
+```
+src/                        Generator source code
+  cli/                      Clipanion CLI (noun-verb architecture)
+  analyzer/                 Graph building, consistency checking
+  parser/                   YAML loading, cross-reference resolution
+  scanner/                  Project pattern detection
+  schema/                   Zod validation schemas
+  behaviors/                Shared behaviors (timestamps, soft-delete)
+  config/                   Config loader, paths, naming
+  formatters/               Console, JSON, markdown output
+  __tests__/                Unit tests (mirrors src/ structure)
+runtime/                    Code shipped into consumer projects
+  base-classes/             BaseRepository, BaseService, family bases
+  subsystems/               Events, Jobs, Cache, Storage
+templates/                  Hygen EJS templates
+test/                       Baseline snapshots, scaffold integration, smoke test
+docs/                       ADRs, consumer setup, getting started
+```
+
+## License
+
+MIT

package/dist/runtime/analytics/index.d.ts

@@ -0,0 +1,6 @@
+export { AggregationType, DimensionType, EntityType, MetricType, NonAdditiveDimensionConfig, SemanticFieldConfig, TimeGranularity } from './types.js';
+export { CumulativeMetric, DerivedMetric, MetricDefinition, RatioMetric, SimpleMetric } from './metrics.js';
+export { DimensionSpec, EntitySpec, MeasureSpec, SemanticModelSpec } from './specs.js';
+export { MonetaryMeasures } from './packs/monetary-measures.js';
+export { CrmEntityMeasures } from './packs/crm-entity-measures.js';
+import '../subsystems/analytics/analytics-query.protocol.js';

package/dist/runtime/analytics/index.js

@@ -0,0 +1,49 @@
+// runtime/analytics/types.ts
+var AggregationType = /* @__PURE__ */ ((AggregationType2) => {
+  AggregationType2["SUM"] = "sum";
+  AggregationType2["MIN"] = "min";
+  AggregationType2["MAX"] = "max";
+  AggregationType2["COUNT"] = "count";
+  AggregationType2["COUNT_DISTINCT"] = "count_distinct";
+  AggregationType2["AVERAGE"] = "average";
+  AggregationType2["MEDIAN"] = "median";
+  AggregationType2["PERCENTILE"] = "percentile";
+  AggregationType2["SUM_BOOLEAN"] = "sum_boolean";
+  return AggregationType2;
+})(AggregationType || {});
+var DimensionType = /* @__PURE__ */ ((DimensionType2) => {
+  DimensionType2["CATEGORICAL"] = "categorical";
+  DimensionType2["TIME"] = "time";
+  return DimensionType2;
+})(DimensionType || {});
+var EntityType = /* @__PURE__ */ ((EntityType2) => {
+  EntityType2["PRIMARY"] = "primary";
+  EntityType2["UNIQUE"] = "unique";
+  EntityType2["FOREIGN"] = "foreign";
+  EntityType2["NATURAL"] = "natural";
+  return EntityType2;
+})(EntityType || {});
+var MetricType = /* @__PURE__ */ ((MetricType2) => {
+  MetricType2["SIMPLE"] = "simple";
+  MetricType2["DERIVED"] = "derived";
+  MetricType2["RATIO"] = "ratio";
+  MetricType2["CUMULATIVE"] = "cumulative";
+  MetricType2["CONVERSION"] = "conversion";
+  return MetricType2;
+})(MetricType || {});
+var TimeGranularity = /* @__PURE__ */ ((TimeGranularity2) => {
+  TimeGranularity2["DAY"] = "day";
+  TimeGranularity2["WEEK"] = "week";
+  TimeGranularity2["MONTH"] = "month";
+  TimeGranularity2["QUARTER"] = "quarter";
+  TimeGranularity2["YEAR"] = "year";
+  return TimeGranularity2;
+})(TimeGranularity || {});
+export {
+  AggregationType,
+  DimensionType,
+  EntityType,
+  MetricType,
+  TimeGranularity
+};
+//# sourceMappingURL=index.js.map

package/dist/runtime/analytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../runtime/analytics/types.ts"],"sourcesContent":["/**\n * Semantic type definitions for the analytics layer.\n *\n * These types mirror MetricFlow / dbt-semantic-interfaces enums but are\n * defined locally so consumers don't need the full dependency for basic\n * field configuration. When the cube.js backend is used, these values\n * map 1:1 to cube measure/dimension types.\n */\n\n// ============================================================================\n// Enums\n// ============================================================================\n\nexport enum AggregationType {\n  SUM = 'sum',\n  MIN = 'min',\n  MAX = 'max',\n  COUNT = 'count',\n  COUNT_DISTINCT = 'count_distinct',\n  AVERAGE = 'average',\n  MEDIAN = 'median',\n  PERCENTILE = 'percentile',\n  SUM_BOOLEAN = 'sum_boolean',\n}\n\nexport enum DimensionType {\n  CATEGORICAL = 'categorical',\n  TIME = 'time',\n}\n\nexport enum EntityType {\n  PRIMARY = 'primary',\n  UNIQUE = 'unique',\n  FOREIGN = 'foreign',\n  NATURAL = 'natural',\n}\n\nexport enum MetricType {\n  SIMPLE = 'simple',\n  DERIVED = 'derived',\n  RATIO = 'ratio',\n  CUMULATIVE = 'cumulative',\n  CONVERSION = 'conversion',\n}\n\n/**\n * Time granularity for time dimensions.\n *\n * Sub-day granularities (hour, minute, second) are intentionally omitted\n * because cube.js does not support them.\n */\nexport enum TimeGranularity {\n  DAY = 'day',\n  WEEK = 'week',\n  MONTH = 'month',\n  QUARTER = 'quarter',\n  YEAR = 'year',\n}\n\n// ============================================================================\n// Config interfaces\n// ============================================================================\n\n/**\n * Configuration for non-additive dimensions on measures.\n *\n * Non-additive dimensions specify that a measure cannot be summed across\n * certain dimensions. For example, inventory balances cannot be summed\n * across time — you need the latest value, not the sum.\n */\nexport interface NonAdditiveDimensionConfig {\n  name: string;\n  window_choice?: AggregationType;\n  window_groupings?: string[];\n}\n\n/**\n * Complete semantic configuration for a field.\n *\n * Used to store all semantic metadata on a field definition for later\n * extraction by the manifest builder / cube schema generator.\n */\nexport interface SemanticFieldConfig {\n  // Measure configuration\n  measure?: boolean;\n  agg?: AggregationType;\n  agg_time_dimension?: string;\n  non_additive_dimension?: NonAdditiveDimensionConfig;\n\n  // Dimension configuration\n  dimension?: boolean;\n  dimension_type?: DimensionType;\n  time_granularity?: TimeGranularity;\n  is_partition?: boolean;\n\n  // Entity configuration\n  entity?: boolean;\n  entity_type?: EntityType;\n  entity_role?: string;\n\n  // Common\n  semantic_expr?: string;\n  semantic_label?: string;\n  visibility?: 'internal' | 'agent' | 'public';\n}\n"],"mappings":";AAaO,IAAK,kBAAL,kBAAKA,qBAAL;AACL,EAAAA,iBAAA,SAAM;AACN,EAAAA,iBAAA,SAAM;AACN,EAAAA,iBAAA,SAAM;AACN,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,oBAAiB;AACjB,EAAAA,iBAAA,aAAU;AACV,EAAAA,iBAAA,YAAS;AACT,EAAAA,iBAAA,gBAAa;AACb,EAAAA,iBAAA,iBAAc;AATJ,SAAAA;AAAA,GAAA;AAYL,IAAK,gBAAL,kBAAKC,mBAAL;AACL,EAAAA,eAAA,iBAAc;AACd,EAAAA,eAAA,UAAO;AAFG,SAAAA;AAAA,GAAA;AAKL,IAAK,aAAL,kBAAKC,gBAAL;AACL,EAAAA,YAAA,aAAU;AACV,EAAAA,YAAA,YAAS;AACT,EAAAA,YAAA,aAAU;AACV,EAAAA,YAAA,aAAU;AAJA,SAAAA;AAAA,GAAA;AAOL,IAAK,aAAL,kBAAKC,gBAAL;AACL,EAAAA,YAAA,YAAS;AACT,EAAAA,YAAA,aAAU;AACV,EAAAA,YAAA,WAAQ;AACR,EAAAA,YAAA,gBAAa;AACb,EAAAA,YAAA,gBAAa;AALH,SAAAA;AAAA,GAAA;AAcL,IAAK,kBAAL,kBAAKC,qBAAL;AACL,EAAAA,iBAAA,SAAM;AACN,EAAAA,iBAAA,UAAO;AACP,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,aAAU;AACV,EAAAA,iBAAA,UAAO;AALG,SAAAA;AAAA,GAAA;","names":["AggregationType","DimensionType","EntityType","MetricType","TimeGranularity"]}

package/dist/runtime/analytics/metrics.d.ts

@@ -0,0 +1,75 @@
+import { TimeGranularity, AggregationType } from './types.js';
+
+/**
+ * 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.
+ */
+
+/**
+ * A simple metric based on a single measure.
+ *
+ * Example:
+ *   { type: 'simple', measure: 'amount' }
+ *   { type: 'simple', measure: 'amount', agg: 'count', filter: "status = 'completed'" }
+ */
+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'] }
+ */
+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' }
+ */
+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' }
+ */
+interface CumulativeMetric {
+    type: 'cumulative';
+    measure: string;
+    window?: string;
+    grain_to_date?: TimeGranularity;
+    description?: string;
+    label?: string;
+}
+/**
+ * Union type of all metric definitions.
+ */
+type MetricDefinition = SimpleMetric | DerivedMetric | RatioMetric | CumulativeMetric;
+
+export type { CumulativeMetric, DerivedMetric, MetricDefinition, RatioMetric, SimpleMetric };

package/dist/runtime/analytics/metrics.js

@@ -0,0 +1 @@
+//# sourceMappingURL=metrics.js.map

package/dist/runtime/analytics/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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

@@ -0,0 +1,21 @@
+import { AnalyticsQueryOpts, ResultRow } from '../../subsystems/analytics/analytics-query.protocol.js';
+
+/**
+ * CrmEntityMeasures — measure pack interface for CRM entities.
+ *
+ * Entities that include the 'crm_entity' measure pack implement this
+ * interface on their generated analytics provider.
+ */
+
+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[]>;
+}
+
+export type { CrmEntityMeasures };

package/dist/runtime/analytics/packs/crm-entity-measures.js

@@ -0,0 +1 @@
+//# sourceMappingURL=crm-entity-measures.js.map

package/dist/runtime/analytics/packs/crm-entity-measures.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/runtime/analytics/packs/index.d.ts

@@ -0,0 +1,3 @@
+export { MonetaryMeasures } from './monetary-measures.js';
+export { CrmEntityMeasures } from './crm-entity-measures.js';
+import '../../subsystems/analytics/analytics-query.protocol.js';

package/dist/runtime/analytics/packs/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/runtime/analytics/packs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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

@@ -0,0 +1,21 @@
+import { AnalyticsQueryOpts, ResultRow } from '../../subsystems/analytics/analytics-query.protocol.js';
+
+/**
+ * MonetaryMeasures — measure pack interface for revenue / monetary fields.
+ *
+ * Entities that include the 'monetary' measure pack implement this interface
+ * on their generated analytics provider.
+ */
+
+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[]>;
+}
+
+export type { MonetaryMeasures };

package/dist/runtime/analytics/packs/monetary-measures.js

@@ -0,0 +1 @@
+//# sourceMappingURL=monetary-measures.js.map

package/dist/runtime/analytics/packs/monetary-measures.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/runtime/analytics/specs.d.ts

@@ -0,0 +1,49 @@
+import { DimensionType, TimeGranularity, EntityType, AggregationType, NonAdditiveDimensionConfig } from './types.js';
+import { MetricDefinition } from './metrics.js';
+
+/**
+ * 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.
+ */
+
+interface MeasureSpec {
+    name: string;
+    agg: AggregationType;
+    expr?: string;
+    agg_time_dimension?: string;
+    non_additive_dimension?: NonAdditiveDimensionConfig;
+    description?: string;
+    label?: string;
+}
+interface DimensionSpec {
+    name: string;
+    dimension_type: DimensionType;
+    expr?: string;
+    time_granularity?: TimeGranularity;
+    is_partition?: boolean;
+    description?: string;
+    label?: string;
+}
+interface EntitySpec {
+    name: string;
+    entity_type: EntityType;
+    expr?: string;
+    role?: string;
+    description?: string;
+    label?: string;
+}
+interface SemanticModelSpec {
+    name: string;
+    table_name: string;
+    measures: MeasureSpec[];
+    dimensions: DimensionSpec[];
+    entities: EntitySpec[];
+    metrics: MetricDefinition[];
+    primary_entity?: string;
+    default_agg_time_dimension?: string;
+}
+
+export type { DimensionSpec, EntitySpec, MeasureSpec, SemanticModelSpec };

package/dist/runtime/analytics/specs.js

@@ -0,0 +1 @@
+//# sourceMappingURL=specs.js.map

package/dist/runtime/analytics/specs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/runtime/analytics/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+declare enum AggregationType {
+    SUM = "sum",
+    MIN = "min",
+    MAX = "max",
+    COUNT = "count",
+    COUNT_DISTINCT = "count_distinct",
+    AVERAGE = "average",
+    MEDIAN = "median",
+    PERCENTILE = "percentile",
+    SUM_BOOLEAN = "sum_boolean"
+}
+declare enum DimensionType {
+    CATEGORICAL = "categorical",
+    TIME = "time"
+}
+declare enum EntityType {
+    PRIMARY = "primary",
+    UNIQUE = "unique",
+    FOREIGN = "foreign",
+    NATURAL = "natural"
+}
+declare 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.
+ */
+declare enum TimeGranularity {
+    DAY = "day",
+    WEEK = "week",
+    MONTH = "month",
+    QUARTER = "quarter",
+    YEAR = "year"
+}
+/**
+ * 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.
+ */
+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.
+ */
+interface SemanticFieldConfig {
+    measure?: boolean;
+    agg?: AggregationType;
+    agg_time_dimension?: string;
+    non_additive_dimension?: NonAdditiveDimensionConfig;
+    dimension?: boolean;
+    dimension_type?: DimensionType;
+    time_granularity?: TimeGranularity;
+    is_partition?: boolean;
+    entity?: boolean;
+    entity_type?: EntityType;
+    entity_role?: string;
+    semantic_expr?: string;
+    semantic_label?: string;
+    visibility?: 'internal' | 'agent' | 'public';
+}
+
+export { AggregationType, DimensionType, EntityType, MetricType, type NonAdditiveDimensionConfig, type SemanticFieldConfig, TimeGranularity };