firebase-contract 0.1.0-rc.5 → 0.1.0-rc.7

package/README.md

@@ -32,36 +32,93 @@ Provides the `firebase-contract` (alias `fbc`) CLI and a programmatic API.
 ```bash
 fbc init          # scaffold contract.yml + firebase-contract.json
 fbc validate      # parse, resolve imports, semantically validate
-fbc generate      # run every `generate:` target declared in the contract graph
+fbc generate      # run every generator declared across the contract graph
 fbc inspect       # print the normalized IR (debugging)
 ```
 
 ### One-command generation
 
-Each contract file can declare its own outputs in a `generate:` section —
-out dirs are relative to that yml file:
+Each contract file declares the generators it uses in a top-level
+`generators:` block — a name plus an output template. Declaring a
+**document-scoped** generator (typescript-split, zod-split, …) runs it once for
+that yml; **api-scoped** generators (api-types, api-validation, api-dto,
+task-payloads) run for the entries that opt in (see below):
+
+```yaml
+# contract.yml (root)
+project:
+  aliases:
+    "#contracts/*": libs/contracts/src/*   # out templates may target aliases
+generators:
+  - { generator: typescript-split, out: "#contracts" }
+  - { generator: api-types, out: "#contracts/api-types/{api-name}" }
+imports:
+  - ./apps/shop/data-connect/schema.yml
+```
 
 ```yaml
 # apps/shop/data-connect/schema.yml
-generate:
-  - { out: src, generators: [data-connect-graphql-split] }
-  - { out: ., generators: [sql-migrations] }
+generators:
+  - { generator: data-connect-graphql-split, out: src }
+  - { generator: sql-migrations, out: . }
 ```
 
+- `out` resolves relative to the declaring yml; `#alias/...` prefixes resolve
+  through the **root** yml's `project.aliases` (relative to the root).
+- Api-scoped templates may use `{api-name}` (kebab-cased name) and `{path}`
+  (REST path with `{param}` segments dropped).
+- Entries reference declarations by name — nearest first (same yml → root).
+
+#### Output settings: `file`, `split`, `options`, `header`
+
+Every declaration (and any entry-level application) can reshape the output —
+the defaults reproduce each generator's built-in layout, so omitting them
+changes nothing:
+
 ```yaml
-# contract.yml (root)
-generate:
-  - out: libs/contracts/src
-    generators: [typescript-split, zod-split, firestore-split, id-codecs]
-imports:
-  - ./apps/shop/data-connect/schema.yml
+generators:
+  - generator: api-dto
+    out: "src/entries/{path}/dto"
+    file: "{api-name}.dto.ts"   # file-name template (default shown)
+    split: true                 # one file per api (api-dto's default)
+  - generator: api-types
+    out: "#contracts/api-types"
+    file: "{api-name}.types.ts" # override the bundled default with per-api files
+    split: true
+    options:
+      typesImport: "../types"   # where `import type { … } from '…'` points
+  - generator: typescript
+    out: "#contracts"
+    file: models.ts             # rename a single-file/barrel output
+    split: true                 # document scope: switches to typescript-split
 ```
 
-`fbc generate contract.yml` then materializes **all** targets across the whole
-import graph in one run. Passing `-o`/`-g` switches to single-target mode
+- **`file`** — output file name. Api scope: a template (`{api-name}`/`{path}`
+  allowed when `split: true`). Document scope: renames the single output file,
+  or the barrel for `-split` variants.
+- **`split`** — api scope: `true` emits one file per api (the `file` template
+  must contain a placeholder), `false` bundles everything into one `file`.
+  Document scope: `true` swaps to the generator's `-split` variant
+  (`typescript` → `typescript-split`, …) and errors when none exists.
+- **`options`** — free-form string map passed through to the generator.
+  Currently: `typesImport` (api-types, task-payloads, data-connect-operations)
+  overrides the `./types` import path.
+- **`header`** — per-generator banner override: `default` for the built-in
+  AUTO-GENERATED banner, any text for a custom comment, `""` to suppress the
+  banner for this generator. Wins over the contract-level `header:` and the
+  CLI `--header` flag.
+- Defaults per generator: `api-types` → `api-types.ts` bundled, `api-validation`
+  → `api-validation.ts` bundled, `task-payloads` → `task-payloads.ts` bundled,
+  `api-dto` → `{api-name}.dto.ts` split.
+- Entry-level settings override the declaration, which overrides the
+  generator's default (same nearest-first rule as `out`).
+
+`fbc generate contract.yml` materializes **all** declared outputs across the
+whole import graph in one run. Passing `-o`/`-g` switches to single-target mode
 (`fbc generate <entry> -o <dir> -g typescript,zod`), and
 `firebase-contract.json` (`entry`, `outDir`, `generators`) can hold defaults.
 
+
 ### Generated-file headers
 
 By default no banner is emitted. Opt in per run or per contract:
@@ -162,24 +219,24 @@ models:
 
 | option                              | meaning                                                  |
 | ----------------------------------- | -------------------------------------------------------- |
-| `type`                              | scalar name, or an enum/model name                       |
-| `optional`                          | value may be absent (`field?`)                           |
-| `list`                              | value is an array of `type`                              |
-| `id`                                | marks the (single) primary identifier                    |
-| `unique`                            | field-level unique → `@unique`                           |
-| `relation`                          | model-typed field is a foreign-key relation (see below)  |
-| `col`                               | Data Connect column dataType (Int64 PKs default to `bigserial`) |
-| `default`                           | `@default(expr: …)` on the DC column                     |
-| `literal`                           | pin to one literal value (union discriminant tags)       |
-| `nullable`                          | value may be `null` (`.nullable()` / `\| null`)          |
-| `description`                       | doc comment carried into generated output                |
-| `jsdoc`                             | render the description as a JSDoc block (Firestore fields) |
+| `type`                              | document | scalar name, or an enum/model name                       |
+| `optional`                          | document | value may be absent (`field?`)                           |
+| `list`                              | document | value is an array of `type`                              |
+| `id`                                | document | marks the (single) primary identifier                    |
+| `unique`                            | document | field-level unique → `@unique`                           |
+| `relation`                          | document | model-typed field is a foreign-key relation (see below)  |
+| `col`                               | document | Data Connect column dataType (Int64 PKs default to `bigserial`) |
+| `default`                           | document | `@default(expr: …)` on the DC column                     |
+| `literal`                           | document | pin to one literal value (union discriminant tags)       |
+| `nullable`                          | document | value may be `null` (`.nullable()` / `\| null`)          |
+| `description`                       | document | doc comment carried into generated output                |
+| `jsdoc`                             | document | render the description as a JSDoc block (Firestore fields) |
 | **constraints** →                   |                                                          |
-| `min` / `max`                       | numeric bounds                                           |
-| `minLength` / `maxLength`           | string/array length bounds                               |
-| `nonempty`                          | non-empty string/array                                   |
-| `pattern`                           | regex the string must match                              |
-| `email` / `url`                     | string format                                            |
+| `min` / `max`                       | document | numeric bounds                                           |
+| `minLength` / `maxLength`           | document | string/array length bounds                               |
+| `nonempty`                          | document | non-empty string/array                                   |
+| `pattern`                           | document | regex the string must match                              |
+| `email` / `url`                     | document | string format                                            |
 
 Constraints flow into the Zod schemas, the API request validation, and the
 class-validator DTOs.
@@ -188,14 +245,14 @@ class-validator DTOs.
 
 | option       | meaning                                                             |
 | ------------ | ------------------------------------------------------------------ |
-| `key`        | composite primary key field names (else the `id: true` field)      |
-| `table`      | table name override (default: snake_case pluralization)            |
-| `gqlName`    | GraphQL type name override                                          |
-| `fsName`     | Firestore-side rename (avoid collisions with table models)          |
-| `directives` | `multi` = each type-level directive on its own line                 |
-| `footer`     | trailing comment block after the closing `}` in the schema file     |
-| `indexes`    | composite `@index`/`@unique` (`{ fields, name?, unique?, expand? }` — `expand` renders args one per line) |
-| `sql`        | raw SQL constraints (see [SQL migrations](#sql-migrations))         |
+| `key`        | document | composite primary key field names (else the `id: true` field)      |
+| `table`      | document | table name override (default: snake_case pluralization)            |
+| `gqlName`    | document | GraphQL type name override                                          |
+| `fsName`     | document | Firestore-side rename (avoid collisions with table models)          |
+| `directives` | document | `multi` = each type-level directive on its own line                 |
+| `footer`     | document | trailing comment block after the closing `}` in the schema file     |
+| `indexes`    | document | composite `@index`/`@unique` (`{ fields, name?, unique?, expand? }` — `expand` renders args one per line) |
+| `sql`        | document | raw SQL constraints (see [SQL migrations](#sql-migrations))         |
 
 ### Embedded vs relation
 
@@ -273,14 +330,14 @@ Everything below exists to reproduce real hand-written `.gql` files byte-for-byt
 
 | option | meaning |
 | --- | --- |
-| `gqlName` | rendered operation name (the yml key stays unique across services) |
-| `footer` | trailing `# …` comment block after the operation |
-| `raw` | emit the operation body verbatim (multi-model queries, `_or` keyset cursors — field checks are skipped) |
-| `single: id \| key` | single-row lookup (`product(id: $id)` / `product(key: { … })`) |
-| `keyArg` / `keyVars` | update/delete key argument form and variable renames |
-| `whereAnd: true` | render conditions as an `_and: [ … ]` array |
-| `entityDir` | override the `operations/<entity>/` output directory |
-| `style` | formatting hints: `signature`, `args`, `data`, `orderBy`, `auth`, `key`, `and`, `where` (`inline`/`multi`/`compact`/`bare`) |
+| `gqlName` | document | rendered operation name (the yml key stays unique across services) |
+| `footer` | document | trailing `# …` comment block after the operation |
+| `raw` | document | emit the operation body verbatim (multi-model queries, `_or` keyset cursors — field checks are skipped) |
+| `single: id \| document | key` | single-row lookup (`product(id: $id)` / `product(key: { … })`) |
+| `keyArg` / `keyVars` | document | update/delete key argument form and variable renames |
+| `whereAnd: true` | document | render conditions as an `_and: [ … ]` array |
+| `entityDir` | document | override the `operations/<entity>/` output directory |
+| `style` | document | formatting hints: `signature`, `args`, `data`, `orderBy`, `auth`, `key`, `and`, `where` (`inline`/`multi`/`compact`/`bare`) |
 
 Inputs support `var` (variable rename), `required` (override optionality),
 `literal` (fixed value, no variable), `flat` (write the FK column directly),
@@ -296,11 +353,13 @@ name as long as their connector sets don't overlap.
 
 ## API endpoints
 
-Model application endpoints (Cloud Task / callable / https / pubsub). Generates
-request/response types (`api-types`), request-validation Zod (`api-validation`),
-class-validator DTOs (`api-dto`), and — for `task`/`pubsub` — payload contracts
-(`task-payloads`). A payload references a model or declares inline fields; a void
-response maps to `void`.
+Model application endpoints in three kind-implied sections — `apis:` (https /
+callable, keyed by REST path), `tasks:` (Cloud Tasks), and `events:` (Pub/Sub).
+The api-scoped generators — request/response types (`api-types`),
+request-validation Zod (`api-validation`), class-validator DTOs (`api-dto`),
+and payload contracts (`task-payloads`) — run for the entries that opt in via
+the section `defaults` or the entry's own `generators:`. A payload references a
+model or declares inline fields; a void response maps to `void`.
 
 ```yaml
 envelopes:
@@ -310,9 +369,10 @@ envelopes:
       opId: string
       enqueuedAt: int
 
-apis:
+tasks:                                     # Cloud Tasks (kind implied)
+  defaults:
+    generators: [task-payloads]            # section default: applies to entries below
   createCatalog:
-    kind: task                             # product | callable | https | pubsub
     envelope: RetryTaskPayload             # wraps the product data
     maxAttempts: 3
     request:
@@ -322,17 +382,31 @@ apis:
     response:
       void: true
 
+events:                                    # Pub/Sub (kind implied)
   generateAiResponse:
-    kind: pubsub
     topic: ai-review-generate-response
     timeoutSeconds: 540
-
-  getShopBySlug:
-    kind: callable
+    generators: [task-payloads]
+
+apis:                                      # https/callable, keyed by REST path
+  defaults:
+    generators: [api-types, api-validation]
+  /shops/{slug}:
+    operationId: getShopBySlug
+    kind: callable                         # https (default) | callable
     request: { fields: { slug: { type: string, nonempty: true } } }
     response: { model: Shop }
+    generators:                            # entry-level wins over section defaults;
+      - api-types                          # an inline out overrides the declared template
+      - { generator: api-dto, out: "src/entries/{path}" }
 ```
 
+Generator application resolves in two tiers — the section `defaults`
+(`apis:/tasks:/events:` → `defaults.generators`) and the entry's own
+`generators:` (which replaces the defaults). `apis:` keys must be REST paths
+(`/...` or `METHOD /...` so the same route can appear once per verb) with an
+`operationId`; tasks and Pub/Sub events live in their own sections.
+
 For `createCatalog` this yields `CreateCatalogTaskData`, `CreateCatalogTaskPayload =
 RetryTaskPayload<CreateCatalogTaskData>`, and `CREATE_CATALOG_MAX_ATTEMPTS`, plus the
 request types, Zod schema, and DTO.
@@ -446,6 +520,8 @@ project:
   idCodec:
     minLength: 8
     alphabet: <your-shuffled-sqids-alphabet>
+  aliases:
+    "#contracts/*": libs/contracts/src/*
 ```
 
 - `services` (`name`/`database`) feed the `FIRESTORE_DATABASES` constants in the
@@ -454,6 +530,9 @@ project:
   `id-codecs` generator also emits a self-contained `id-core.ts` (the
   encode/decode primitives), so nothing about id encoding lives outside the
   contract.
+- `aliases` maps `#alias/...` out-template prefixes to paths relative to the
+  **root** yml, so imported contracts can target shared libs without relative
+  path gymnastics (longest prefix wins).
 - `codebases` / service `location` + `connectors` are consumed by the optional
   `config` generator (preview), which emits per-service `dataconnect.yaml`,
   per-connector `connector.yaml`, and the `FIRESTORE_DATABASES` /
@@ -465,32 +544,37 @@ project:
 
 # Generators
 
-| name                     | output                        | notes                                                  |
-| ------------------------ | ----------------------------- | ------------------------------------------------------ |
-| `typescript`             | `types.ts`                    | interfaces + const/union enums                         |
-| `typescript-split`       | `types/<table>.ts` + `types.ts` barrel | one file per table; enums/embedded objects co-located |
-| `zod`                    | `schemas.ts`                  | `z.object` schemas (constraints, `z.lazy` model refs)  |
-| `zod-split`              | `schemas/<table>.ts` + `schemas.ts` barrel | split variant of `zod`                    |
-| `data-connect-graphql`   | `schema.gql`                  | `type … @table(name, key)`; `@col`/`@unique`/`@index`/`@default` |
-| `data-connect-graphql-split` | `schema/<table>.gql`     | same schema, one file per table (enums co-located) |
-| `data-connect-operations`| `<connector>/operations.gql` + `.ts` | queries/mutations (where ops, orderBy, limit, aggregate, exprs, inc), per connector |
-| `data-connect-operations-split` | `<connector>/operations/<entity>/{queries,mutations}.gql` | real Data Connect repo layout; shared types stay in `typescript`/`zod` outputs |
-| `data-connect-adapter`   | `data-connect-adapters.ts`    | convert `Any` rows ⇄ logical types                     |
-| `firestore-types`        | `firestore-types.ts`          | naive TS types with Firestore `Timestamp` (all models) |
-| `firestore`              | `firestore.ts`                | Firestore projection Zod schemas (derived, denormalized) |
-| `firestore-split`        | `firestore/<collection>.ts` + `firestore.ts` barrel | one file per projection; `_meta_` under `firestore/_/`; DC-schema `.pick()` reuse; `FIRESTORE_DATABASES` constants in the barrel |
-| `api-types`              | `api-types.ts`                | endpoint request/response types                        |
-| `api-validation`         | `api-validation.ts`           | endpoint request-validation Zod                        |
-| `api-dto`                | `api-dtos.ts`                 | class-validator DTO classes                            |
-| `task-payloads`          | `task-payloads.ts`            | envelopes + `*TaskData`/`*TaskPayload` + constants     |
-| `sql-migrations`         | `migrations/constraints.sql`  | composite FK / CHECK / index SQL                       |
-| `id-codecs`              | `id-codecs.ts` (+ `id-core.ts`) | typed per-entity id encode/decode wrappers; emits the Sqids primitives when `project.idCodec` is set |
-| `unions`                 | `unions.ts`                   | Zod discriminated unions + TS union types              |
-| `config`                 | `dataconnect.yaml`, `connector.yaml`, `constants.ts` | DC configs + sync constants (preview — see [Project config](#project-config)) |
+| name                     | scope    | output                        | notes                                                  |
+| ------------------------ | -------- | ----------------------------- | ------------------------------------------------------ |
+| `typescript`             | document | `types.ts`                    | interfaces + const/union enums                         |
+| `typescript-split`       | document | `types/<table>.ts` + `types.ts` barrel | one file per table; enums/embedded objects co-located |
+| `zod`                    | document | `schemas.ts`                  | `z.object` schemas (constraints, `z.lazy` model refs)  |
+| `zod-split`              | document | `schemas/<table>.ts` + `schemas.ts` barrel | split variant of `zod`                    |
+| `data-connect-graphql`   | document | `schema.gql`                  | `type … @table(name, key)`; `@col`/`@unique`/`@index`/`@default` |
+| `data-connect-graphql-split` | document | `schema/<table>.gql`     | same schema, one file per table (enums co-located) |
+| `data-connect-operations`| document | `<connector>/operations.gql` + `.ts` | queries/mutations (where ops, orderBy, limit, aggregate, exprs, inc), per connector |
+| `data-connect-operations-split` | document | `<connector>/operations/<entity>/{queries,mutations}.gql` | real Data Connect repo layout; shared types stay in `typescript`/`zod` outputs |
+| `data-connect-adapter`   | document | `data-connect-adapters.ts`    | convert `Any` rows ⇄ logical types                     |
+| `firestore-types`        | document | `firestore-types.ts`          | naive TS types with Firestore `Timestamp` (all models) |
+| `firestore`              | document | `firestore.ts`                | Firestore projection Zod schemas (derived, denormalized) |
+| `firestore-split`        | document | `firestore/<collection>.ts` + `firestore.ts` barrel | one file per projection; `_meta_` under `firestore/_/`; DC-schema `.pick()` reuse; `FIRESTORE_DATABASES` constants in the barrel |
+| `api-types`              | api | `api-types.ts`                | endpoint request/response types                        |
+| `api-validation`         | api | `api-validation.ts`           | endpoint request-validation Zod                        |
+| `api-dto`                | api | `<operation>.dto.ts` per api  | class-validator DTO classes (NestJS `dto/` convention) |
+| `task-payloads`          | api | `task-payloads.ts`            | envelopes + `*TaskData`/`*TaskPayload` + constants     |
+| `sql-migrations`         | document | `migrations/constraints.sql`  | composite FK / CHECK / index SQL                       |
+| `id-codecs`              | document | `id-codecs.ts` (+ `id-core.ts`) | typed per-entity id encode/decode wrappers; emits the Sqids primitives when `project.idCodec` is set |
+| `unions`                 | document | `unions.ts`                   | Zod discriminated unions + TS union types              |
+| `config`                 | document | `dataconnect.yaml`, `connector.yaml`, `constants.ts` | DC configs + sync constants (preview — see [Project config](#project-config)) |
 
 Each generator emits nothing when its section is absent, so a small contract
 produces a small output. Select a subset with `-g`.
 
+**Scope** decides how a `generators:` declaration takes effect: `document`
+generators run once for the yml that declares them; `api` generators run only
+for the entries that apply them (section `defaults.generators` → entry
+`generators:`, entry wins).
+
 ### The `Any` boundary
 
 Data Connect stores JSON and embedded objects as the `Any` scalar, erasing the
@@ -518,7 +602,7 @@ const result = generate('contract.yml', {
   write: true,
 })
 
-// Every `generate:` target declared across the import graph:
+// Every generator declared across the import graph:
 const all = generateAll('contract.yml', { write: true })
 ```
 

package/dist/lib/_internal/compiler/compiler.d.ts

@@ -43,10 +43,11 @@ export interface GenerateAllResult {
     ok: boolean;
 }
 /**
- * Run every `generate:` target declared across the entry contract and its
- * (transitive) imports — the one-command flow: each contract file states where
- * its own outputs go, and `fbc generate <root>` materializes all of them.
- * Output dirs resolve relative to the declaring yml file.
+ * Run every generator declared across the entry contract and its (transitive)
+ * imports — the one-command flow: each contract file declares its generators
+ * (`generators:` + section defaults / entry applications) and
+ * `fbc generate <root>` materializes all of them. Output dirs resolve relative
+ * to the declaring yml (or the root yml for `#alias/...` templates).
  */
 export declare const generateAll: (entryPath: string, options?: {
     registry?: GeneratorRegistry;

package/dist/lib/_internal/compiler/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/compiler/compiler.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAoB,MAAM,mBAAmB,CAAA;AAEhE,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAEvD,OAAO,EAAkB,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAG3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAE5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAE7D,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,EAAE,CAAA;IACN,SAAS,EAAE,WAAW,EAAE,CAAA;IACxB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,WAAW,MAAM,EAAE,UAAS,cAAmB,KAAG,aAUzE,CAAA;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,KAAK,EAAE,aAAa,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,oBAAoB,EAAE,CAAA;IAC/B,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,EAAE,EAAE,OAAO,CAAA;CACZ;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,UAAS;IAAE,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,KACjH,iBA8BF,CAAA;AAED,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,EAAE,KAAG,SAUlD,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,EAAE,CAAA;IACN,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,oFAAoF;IACpF,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB,0DAA0D;IAC1D,EAAE,EAAE,OAAO,CAAA;CACZ;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,SAAS,eAAe,KAAG,cAuCtE,CAAA"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/compiler/compiler.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAoB,MAAM,mBAAmB,CAAA;AAEhE,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA;AAChC,OAAO,EAAU,WAAW,EAAqC,MAAM,2BAA2B,CAAA;AAElG,OAAO,EAAkB,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAG3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAI5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAE7D,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,EAAE,CAAA;IACN,SAAS,EAAE,WAAW,EAAE,CAAA;IACxB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,WAAW,MAAM,EAAE,UAAS,cAAmB,KAAG,aAUzE,CAAA;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,KAAK,EAAE,aAAa,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,oBAAoB,EAAE,CAAA;IAC/B,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,EAAE,EAAE,OAAO,CAAA;CACZ;AAmND;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,UAAS;IAAE,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,KACjH,iBAuDF,CAAA;AAED,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,EAAE,KAAG,SAUlD,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,EAAE,CAAA;IACN,WAAW,EAAE,UAAU,EAAE,CAAA;IACzB,oFAAoF;IACpF,KAAK,EAAE,aAAa,EAAE,CAAA;IACtB,0DAA0D;IAC1D,EAAE,EAAE,OAAO,CAAA;CACZ;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,SAAS,eAAe,KAAG,cAuCtE,CAAA"}

package/dist/lib/_internal/compiler/compiler.js

@@ -7,6 +7,7 @@ import { createFsLoader } from '../resolver/module-loader.js';
 import { validateIr } from '../validation/validate.js';
 import { createDefaultRegistry } from '../generators/index.js';
 import { toHeaderComment } from '../generators/support/header.js';
+import { API_PLACEHOLDER_RE, expandApiPlaceholders } from '../generators/support/templates.js';
 /**
  * Run the front end of the pipeline: resolve imports, build the IR, and run
  * semantic validation. Generators are intentionally not involved here — the CLI
@@ -24,11 +25,175 @@ export const compile = (entryPath, options = {}) => {
         diagnostics: [...importDiagnostics, ...buildDiagnostics, ...validationDiagnostics],
     };
 };
+/** `apis:/tasks:/events:` section a raw api belongs to (drives the section defaults lookup). */
+const sectionOf = (api) => {
+    if (api.kind === 'task')
+        return 'tasks';
+    if (api.kind === 'pubsub')
+        return 'events';
+    return 'apis';
+};
+const expandOutTemplate = (template, api, diagnostics, source) => {
+    if (!API_PLACEHOLDER_RE.test(template))
+        return template;
+    if (!api) {
+        diagnostics.push(error('INVALID_OUT_TEMPLATE', `"${template}" uses api placeholders but the generator is document-scoped (${source})`));
+        return undefined;
+    }
+    const out = expandApiPlaceholders(template, api);
+    if (out === undefined) {
+        diagnostics.push(error('INVALID_OUT_TEMPLATE', `"${template}" uses {path} but api "${api.name}" has no REST path (${source})`));
+    }
+    return out;
+};
+/**
+ * Resolve an out template to an absolute directory. `#alias/...` prefixes are
+ * matched against the root document's `project.aliases` (longest prefix wins)
+ * and resolve relative to the root yml; everything else resolves relative to
+ * the declaring yml — same as the legacy `generate:` form.
+ */
+const resolveOutDir = (out, declaringDoc, rootDoc, diagnostics) => {
+    if (!out.startsWith('#')) {
+        return join(dirname(declaringDoc.filePath), out);
+    }
+    const aliases = rootDoc.project?.aliases ?? {};
+    const candidates = Object.entries(aliases)
+        .map(([pattern, target]) => ({ prefix: pattern.endsWith('/*') ? pattern.slice(0, -2) : pattern, pattern, target }))
+        .filter(({ prefix }) => out === prefix || out.startsWith(`${prefix}/`))
+        .sort((a, b) => b.prefix.length - a.prefix.length);
+    const match = candidates[0];
+    if (!match) {
+        diagnostics.push(error('UNKNOWN_ALIAS', `No project.aliases entry matches "${out}" (declare it in the root contract)`));
+        return undefined;
+    }
+    const rest = out.slice(match.prefix.length).replace(/^\//, '');
+    const targetBase = match.target.endsWith('/*') ? match.target.slice(0, -2) : match.target;
+    return join(dirname(rootDoc.filePath), targetBase, rest);
+};
+/** Find a generator declaration by name — nearest first: the declaring yml, then the root yml. */
+const findGeneratorDecl = (name, doc, rootDoc) => doc.generatorDecls?.find(decl => decl.generator === name) ??
+    rootDoc.generatorDecls?.find(decl => decl.generator === name);
 /**
- * Run every `generate:` target declared across the entry contract and its
- * (transitive) imports — the one-command flow: each contract file states where
- * its own outputs go, and `fbc generate <root>` materializes all of them.
- * Output dirs resolve relative to the declaring yml file.
+ * Build generator jobs from the declaration/application DSL:
+ * - api-scoped generators run for entries that opt in (section `defaults` →
+ *   entry `generators:`, entry wins; no file-level tier by design)
+ * - document-scoped generators run once per yml that declares them
+ */
+const buildGeneratorJobs = (doc, rootDoc, registry, diagnostics) => {
+    const jobs = [];
+    const grouped = new Map();
+    for (const [apiName, rawApi] of Object.entries(doc.apis)) {
+        const uses = rawApi.generators ?? doc.sectionDefaults?.[sectionOf(rawApi)];
+        for (const use of uses ?? []) {
+            const decl = findGeneratorDecl(use.generator, doc, rootDoc);
+            const template = use.out ?? decl?.out;
+            if (template === undefined) {
+                diagnostics.push(error('UNKNOWN_GENERATOR_DECL', `Api "${apiName}" applies generator "${use.generator}" but no declaration with an "out" was found (${doc.filePath})`));
+                continue;
+            }
+            // Output settings resolve nearest-first: entry use → declaration → the
+            // generator's built-in default (applied by the generator itself).
+            const generator = registry.get(use.generator);
+            const output = {};
+            const file = use.file ?? decl?.file;
+            const split = use.split ?? decl?.split ?? generator?.defaultOutput?.split;
+            const options = use.options ?? decl?.options;
+            const header = use.header ?? decl?.header;
+            if (file !== undefined)
+                output.file = file;
+            if (split !== undefined)
+                output.split = split;
+            if (options !== undefined)
+                output.options = options;
+            // Split mode needs a per-api file name; bundled mode cannot expand one.
+            const effectiveFile = file ?? generator?.defaultOutput?.file;
+            if (effectiveFile !== undefined && split === false && API_PLACEHOLDER_RE.test(effectiveFile)) {
+                diagnostics.push(error('INVALID_OUT_TEMPLATE', `file "${effectiveFile}" uses api placeholders but split is false for generator "${use.generator}" — set a plain file name (${doc.filePath})`));
+                continue;
+            }
+            if (effectiveFile !== undefined && split === true && !API_PLACEHOLDER_RE.test(effectiveFile)) {
+                diagnostics.push(error('INVALID_OUT_TEMPLATE', `split is true for generator "${use.generator}" but file "${effectiveFile}" has no {api-name}/{path} placeholder, so per-api files would overwrite each other (${doc.filePath})`));
+                continue;
+            }
+            const api = { name: apiName, ...(rawApi.path !== undefined ? { path: rawApi.path } : {}) };
+            const expanded = expandOutTemplate(template, api, diagnostics, doc.filePath);
+            if (expanded === undefined)
+                continue;
+            const outDir = resolveOutDir(expanded, doc, rootDoc, diagnostics);
+            if (outDir === undefined)
+                continue;
+            const key = [use.generator, outDir, file ?? '', String(split ?? ''), JSON.stringify(options ?? null), header ?? '\u0001'].join('\u0000');
+            const existing = grouped.get(key);
+            if (existing) {
+                existing.apiNames?.push(apiName);
+            }
+            else {
+                const job = { source: doc.filePath, generatorName: use.generator, outDir, apiNames: [apiName], output };
+                if (header !== undefined)
+                    job.header = header;
+                grouped.set(key, job);
+                jobs.push(job);
+            }
+        }
+    }
+    for (const decl of doc.generatorDecls ?? []) {
+        const generator = registry.get(decl.generator);
+        if (!generator) {
+            diagnostics.push(error('UNKNOWN_GENERATOR', `Unknown generator "${decl.generator}" (${doc.filePath})`));
+            continue;
+        }
+        if ((generator.scope ?? 'document') === 'api')
+            continue; // applied via entries, not by declaration
+        // Document-scoped `split` toggles between a generator and its `-split`
+        // variant (e.g. typescript ⇄ typescript-split) instead of reshaping output.
+        let generatorName = decl.generator;
+        if (decl.split === true && !generatorName.endsWith('-split')) {
+            const splitName = `${generatorName}-split`;
+            if (registry.get(splitName)) {
+                generatorName = splitName;
+            }
+            else {
+                diagnostics.push(error('UNSUPPORTED_SPLIT', `Generator "${decl.generator}" has no split variant (${doc.filePath})`));
+                continue;
+            }
+        }
+        else if (decl.split === false && generatorName.endsWith('-split')) {
+            const baseName = generatorName.slice(0, -'-split'.length);
+            if (registry.get(baseName))
+                generatorName = baseName;
+        }
+        const output = {};
+        if (decl.file !== undefined) {
+            if (API_PLACEHOLDER_RE.test(decl.file)) {
+                diagnostics.push(error('INVALID_OUT_TEMPLATE', `file "${decl.file}" uses api placeholders but generator "${decl.generator}" is document-scoped (${doc.filePath})`));
+                continue;
+            }
+            output.file = decl.file;
+        }
+        if (decl.options !== undefined)
+            output.options = decl.options;
+        const expanded = expandOutTemplate(decl.out, undefined, diagnostics, doc.filePath);
+        if (expanded === undefined)
+            continue;
+        const outDir = resolveOutDir(expanded, doc, rootDoc, diagnostics);
+        if (outDir === undefined)
+            continue;
+        jobs.push({
+            source: doc.filePath,
+            generatorName,
+            outDir,
+            ...(Object.keys(output).length > 0 ? { output } : {}),
+            ...(decl.header !== undefined ? { header: decl.header } : {}),
+        });
+    }
+    return jobs;
+};
+/**
+ * Run every generator declared across the entry contract and its (transitive)
+ * imports — the one-command flow: each contract file declares its generators
+ * (`generators:` + section defaults / entry applications) and
+ * `fbc generate <root>` materializes all of them. Output dirs resolve relative
+ * to the declaring yml (or the root yml for `#alias/...` templates).
  */
 export const generateAll = (entryPath, options = {}) => {
     const { documents, diagnostics } = compile(entryPath, options);
@@ -38,27 +203,46 @@ export const generateAll = (entryPath, options = {}) => {
     const collected = [...diagnostics];
     const targets = [];
     let ok = true;
-    for (const doc of documents) {
-        for (const output of doc.outputs ?? []) {
-            const outDir = join(dirname(doc.filePath), output.out);
-            const result = generate(doc.filePath, {
-                outDir,
-                generators: output.generators,
-                registry: options.registry,
-                write: options.write,
-                ...(options.context ? { context: options.context } : {}),
-                ...(options.loader ? { loader: options.loader } : {}),
-            });
-            // Per-target compiles revisit shared imports; keep only new diagnostics.
-            for (const diagnostic of result.diagnostics) {
-                if (!collected.some(d => d.code === diagnostic.code && d.message === diagnostic.message)) {
-                    collected.push(diagnostic);
-                }
+    const registry = options.registry ?? createDefaultRegistry();
+    // Import order puts dependencies first, so the entry (root) document is last.
+    const rootDoc = documents[documents.length - 1];
+    const mergeDiagnostics = (incoming) => {
+        // Per-target compiles revisit shared imports; keep only new diagnostics.
+        for (const diagnostic of incoming) {
+            if (!collected.some(d => d.code === diagnostic.code && d.message === diagnostic.message)) {
+                collected.push(diagnostic);
             }
-            if (!result.ok)
-                ok = false;
-            targets.push({ source: doc.filePath, outDir, generators: output.generators, files: result.files });
         }
+    };
+    const runTarget = (doc, outDir, generators, apiNames, output, header) => {
+        const result = generate(doc.filePath, {
+            outDir,
+            generators,
+            registry,
+            write: options.write,
+            context: {
+                ...options.context,
+                ...(apiNames ? { apiNames } : {}),
+                ...(output ? { output } : {}),
+                // Per-generator header beats the CLI/contract-level one ('' disables it).
+                ...(header !== undefined ? { header: toHeaderComment(header) } : {}),
+            },
+            ...(options.loader ? { loader: options.loader } : {}),
+        });
+        mergeDiagnostics(result.diagnostics);
+        if (!result.ok)
+            ok = false;
+        targets.push({ source: doc.filePath, outDir, generators, files: result.files });
+    };
+    for (const doc of documents) {
+        // Declaration/application DSL (`generators:` + section defaults / entry `generators:`).
+        const jobDiagnostics = [];
+        for (const job of buildGeneratorJobs(doc, rootDoc, registry, jobDiagnostics)) {
+            runTarget(doc, job.outDir, [job.generatorName], job.apiNames, job.output, job.header);
+        }
+        mergeDiagnostics(jobDiagnostics);
+        if (hasErrors(jobDiagnostics))
+            ok = false;
     }
     return { targets, diagnostics: collected, ok };
 };