firebase-contract 0.1.0-rc.9 → 0.1.0

package/README.md

@@ -10,7 +10,7 @@ From one contract, generate:
 - **Zod** validation schemas
 - **Data Connect** GraphQL schema (`@table`, keys, directives), query/mutation
   operations (routed per connector), and `Any`↔logical adapters
-- **Firestore** projection schemas (denormalized read model with `_meta_`)
+- **Firestore** projection schemas (denormalized read model; shared field groups via fragments)
 - **API** request/response types, request-validation Zod, and class-validator DTOs
 - **Cloud Task / Pub/Sub** payload envelopes + delivery constants
 - **SQL migrations** for constraints Data Connect can't express (composite FKs,
@@ -34,13 +34,14 @@ fbc init          # scaffold contract.yml + firebase-contract.json
 fbc validate      # parse, resolve imports, semantically validate
 fbc generate      # run every generator declared across the contract graph
 fbc inspect       # print the normalized IR (debugging)
+fbc where <Name>  # locate the yml defining a type (logical / gqlName / fsName / table)
 ```
 
 ### One-command generation
 
 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
+**document-scoped** generator (typescript, zod, …) 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):
 
@@ -50,7 +51,7 @@ project:
   aliases:
     "#contracts/*": libs/contracts/src/*   # out templates may target aliases
 generators:
-  - { generator: typescript-split, out: "#contracts" }
+  - { generator: typescript, out: "#contracts", split: true }
   - { generator: api-types, out: "#contracts/api-types/{api-name}" }
 imports:
   - ./apps/shop/data-connect/schema.yml
@@ -59,7 +60,7 @@ imports:
 ```yaml
 # apps/shop/data-connect/schema.yml
 generators:
-  - { generator: data-connect-graphql-split, out: src }
+  - { generator: data-connect-graphql, out: src, split: true }
   - { generator: sql-migrations, out: . }
 ```
 
@@ -90,19 +91,26 @@ generators:
   - generator: typescript
     out: "#contracts"
     file: models.ts             # rename a single-file/barrel output
-    split: true                 # document scope: switches to typescript-split
+    split: true                 # document scope: per-table split layout
 ```
 
 - **`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.
+  or the barrel of a split layout.
 - **`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.
+  Document scope: `true` selects the generator's per-item split layout
+  (typescript, zod, firestore, data-connect-graphql, data-connect-operations)
+  and errors for generators without one.
 - **`options`** — free-form string map passed through to the generator.
   Currently: `typesImport` (api-types, task-payloads, data-connect-operations)
-  overrides the `./types` import path.
+  overrides the types import path. For api-types and task-payloads this is
+  normally unnecessary: when the option is absent and a `typescript` generator
+  is declared (nearest-first: same yml → root), the import specifier is derived
+  automatically as the relative path from the output file to the declared
+  barrel — moving or renaming the barrel (`out` / `file`) re-derives it. An
+  explicit `typesImport` always wins; without a typescript declaration the
+  generator's built-in default (`./types`) applies.
 - **`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
@@ -115,8 +123,9 @@ generators:
 
 `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.
+(`fbc generate <entry> -o <dir> -g typescript,zod`). `firebase-contract.json`
+holds only a default `entry` — output routing lives in the yml `generators:`
+declarations, so a config file can never silently override them.
 
 
 ### Generated-file headers
@@ -173,8 +182,33 @@ in other contracts (relative paths or npm packages). Imports are resolved
 transitively with cycle/duplicate detection and diamond dedup, so you can split
 a large contract across files that mirror your repo layout.
 
+**Type names are globally unique.** The namespace is flat across the whole
+import graph: defining the same name twice — same kind (`DUPLICATE_DEFINITION`)
+or across kinds/derived identifiers, e.g. an enum and a model both named
+`Status`, or two enums whose `CONSTANT_CASE` consts collide (`NAME_COLLISION`)
+— aborts generation. Uniqueness is enforced per output namespace with its
+*effective* names, so `fsName`/`gqlName` renames legitimately reuse a name in a
+different output: GraphQL names are checked per `data-connect-graphql` scope
+(services may map distinct logical names onto the same gqlName), and the
+firestore module is checked under `fsName ?? name` alongside doc names. A bare
+type reference therefore always resolves to exactly one definition — use
+`fbc where <Name>` to find it.
+
+**Unknown keys are errors.** Every key the parser does not consume is an
+`UNKNOWN_KEY` error (all reported in one pass), never silently dropped — a
+typo like `optionnal:` must not quietly turn into a required field. There is
+no `version:` field: nothing consumes one, so accepting it would only fake a
+compatibility mechanism that does not exist.
+
+**Out-of-vocabulary values are errors too.** A value outside a field's fixed
+set is `INVALID_VALUE` rather than a silent coercion: `auth: PUBILC` does not
+quietly become `NO_ACCESS`, `dir: Dsec` does not become `ASC`, and a mistyped
+`action` / `single` / `keyArg` / `style.*` is not dropped. The one exception is
+`where.op`, which is warned (`UNKNOWN_WHERE_OP`) not errored — it is emitted
+verbatim into GraphQL and the recognized-operator list may lag Data Connect, so
+a typo is surfaced without rejecting a valid-but-unlisted operator.
+
 ```yaml
-version: 1
 imports:
   - ./apps/shop/data-connect/schema.yml
   - some-shared-package/contract.yml
@@ -211,8 +245,10 @@ export type ProductStatusKey = keyof typeof PRODUCT_STATUS
 export type ProductStatus = (typeof PRODUCT_STATUS)[ProductStatusKey]
 ```
 
-Pass `enumStyle: 'union'` to the TypeScript generator for a plain
-`'OPEN' | 'DONE' | 'DISABLED'` union instead.
+For a plain `'OPEN' | 'DONE' | 'DISABLED'` union instead, construct the
+TypeScript generator with `enumStyle: 'union'` via the programmatic API
+(`createTypeScriptGenerator({ enumStyle: 'union' })`). This is a build-time
+generator option, not a YAML contract field.
 
 ## Models
 
@@ -247,24 +283,24 @@ models:
 
 | option                              | meaning                                                  |
 | ----------------------------------- | -------------------------------------------------------- |
-| `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) |
+| `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) |
 | **constraints** →                   |                                                          |
-| `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                                            |
+| `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                                            |
 
 Constraints flow into the Zod schemas, the API request validation, and the
 class-validator DTOs.
@@ -273,14 +309,14 @@ class-validator DTOs.
 
 | option       | meaning                                                             |
 | ------------ | ------------------------------------------------------------------ |
-| `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))         |
+| `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))         |
 
 ### Embedded vs relation
 
@@ -358,14 +394,14 @@ Everything below exists to reproduce real hand-written `.gql` files byte-for-byt
 
 | option | meaning |
 | --- | --- |
-| `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`) |
+| `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`) |
 
 Inputs support `var` (variable rename), `required` (override optionality),
 `literal` (fixed value, no variable), `flat` (write the FK column directly),
@@ -447,9 +483,9 @@ reality automatically:
 
 - **relations → resolved string ids** (`ownerUser` → `ownerUserId: z.string()`)
 - **timestamps → `z.date()`**, optional fields → `.nullable()`
-- a **`_meta_`** consistency envelope is attached (opt out with `meta: false`)
 - `pick` / `omit` select which base fields survive
 - inline `fields` add denormalized data (flattened DAG edges, stringified JSON)
+- `extends: [<fragment>…]` splices shared fields in (see **Fragments** below)
 
 ```yaml
 firestore:
@@ -467,10 +503,13 @@ firestore:
 ```
 
 Emits Zod schemas + inferred types, mirroring a hand-written Firestore schema
-library. (The simpler `firestore-types` generator just re-types *every* model
-with the Firestore `Timestamp` and does not denormalize.)
+library. (`firestore-types` is the zero-config entry point for projects that
+have not written projections yet: it re-types *every* model with the Firestore
+`Timestamp`, no `firestore:` section needed. Once you declare projections,
+prefer the `firestore` generator — it is the one that understands
+pick/omit/fsName/denormalized fields.)
 
-With `firestore-split`, fields whose Zod chain is **identical** to the Data
+With `firestore` + `split: true`, fields whose Zod chain is **identical** to the Data
 Connect schema are reused via `.pick()` — only representation changes are
 restated:
 
@@ -480,7 +519,6 @@ export const ShopSchema = DcShopSchema.pick({
 }).extend({
   createdAt: z.date(),
   updatedAt: z.date().nullable(),
-  _meta_: _Meta_Schema,
 })
 ```
 
@@ -497,6 +535,50 @@ Additional projection options:
 - FS-only enums render as frozen consts (`REVIEW_STATE` + `ReviewStateSchema`),
   co-located with the first projection that references them
 
+### Fragments (`fragments:` + `extends:`)
+
+A **fragment** is a named group of fields declared once and spliced into
+consumers via `extends: [<name>…]` — the way to share a common field across
+many projections (a consistency `_meta_` envelope, audit columns, …) without a
+tool-imposed convention. The fragment field's name, type, and which docs carry
+it are all yours.
+
+The value objects a fragment references can be **pinned** to a fixed split
+output via `out` (+ optional `file`) on the model declaration. A pinned value
+object is *placement-scoped*: emitted only at that location (dependency-ordered,
+with an `index.ts` barrel), imported by consumers via that directory, and
+excluded from the default `typescript`/`zod` barrels — so it lives purely in the
+firestore output. This is what lets a shared envelope sit under `firestore/_/`.
+
+```yaml
+models:
+  MetaOp:
+    out: firestore/_          # → firestore/_/_meta_.ts (+ firestore/_/index.ts)
+    file: _meta_.ts
+    fields:
+      id: { type: string }
+  Meta:
+    out: firestore/_
+    file: _meta_.ts
+    fields:
+      scope: { type: float, nullable: true }
+      op: { type: MetaOp, nullable: true }
+
+fragments:
+  meta:
+    fields:
+      _meta_: { type: Meta }
+
+firestore:
+  Shop:
+    from: Shop
+    extends: [meta]            # appends `_meta_: MetaSchema` (imported from './_')
+```
+
+`extends` referencing a fragment that is not declared is an `UNKNOWN_FRAGMENT`
+error, not a silent no-op — a typo like `extends: [metaa]` fails generation
+rather than quietly dropping the shared fields.
+
 ## Discriminated unions
 
 ```yaml
@@ -553,7 +635,7 @@ project:
 ```
 
 - `services` (`name`/`database`) feed the `FIRESTORE_DATABASES` constants in the
-  `firestore-split` barrel.
+  split `firestore` barrel.
 - `idCodec` pins the Sqids settings as a contract constant; when present, the
   `id-codecs` generator also emits a self-contained `id-core.ts` (the
   encode/decode primitives), so nothing about id encoding lives outside the
@@ -574,18 +656,13 @@ project:
 
 | 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 |
+| `typescript`             | document | `types.ts`; `split: true` → `types/<table>.ts` + barrel | interfaces + const/union enums; split co-locates enums/embedded objects per table |
+| `zod`                    | document | `schemas.ts`; `split: true` → `schemas/<table>.ts` + barrel | `z.object` schemas (constraints, `z.lazy` model refs)  |
+| `data-connect-graphql`   | document | `schema.gql`; `split: true` → `schema/<table>.gql` | `type … @table(name, key)`; `@col`/`@unique`/`@index`/`@default` |
+| `data-connect-operations`| document | `<connector>/operations.gql` + `.ts`; `split: true` → `<connector>/operations/<entity>/{queries,mutations}.gql` | queries/mutations (where ops, orderBy, limit, aggregate, exprs, inc), per connector; split matches the real Data Connect repo layout |
 | `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 |
+| `firestore`              | document | `firestore.ts`; `split: true` → `firestore/<collection>.ts` + barrel | Firestore projection Zod schemas (derived, denormalized); `extends` fragments, pinned value objects under their `out` (e.g. `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) |

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,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;AAC7D,OAAO,EAEL,cAAc,EAGf,MAAM,kBAAkB,CAAA;AAEzB,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;IAC1B,oFAAoF;IACpF,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,mFAAmF;IACnF,GAAG,CAAC,EAAE,IAAI,CAAA;CACX;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;IACP,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,GAAG,CAAC,EAAE,IAAI,CAAA;CACN,KACL,iBA0FF,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,cAgEtE,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;AAI3E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAI5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAEL,cAAc,EAGf,MAAM,kBAAkB,CAAA;AAEzB,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,aAkBzE,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;IAC1B,oFAAoF;IACpF,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B,mFAAmF;IACnF,GAAG,CAAC,EAAE,IAAI,CAAA;CACX;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;AAyOD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,UAAS;IACP,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,GAAG,CAAC,EAAE,IAAI,CAAA;CACN,KACL,iBA0FF,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,cAgEtE,CAAA"}

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

@@ -4,6 +4,7 @@ import { error, hasErrors } from '../diagnostics.js';
 import { buildIr } from '../ir/build-ir.js';
 import { resolveImports } from '../resolver/import-resolver.js';
 import { createFsLoader } from '../resolver/module-loader.js';
+import { graphqlNameCollisions } from '../validation/rules.js';
 import { validateIr } from '../validation/validate.js';
 import { createDefaultRegistry } from '../generators/index.js';
 import { toHeaderComment } from '../generators/support/header.js';
@@ -20,10 +21,18 @@ export const compile = (entryPath, options = {}) => {
     const { documents, diagnostics: importDiagnostics } = resolveImports(entryPath, loader);
     const { ir, diagnostics: buildDiagnostics } = buildIr(documents);
     const validationDiagnostics = validateIr(ir);
+    // A GraphQL schema is generated per data-connect-graphql declaration from the
+    // declaring yml's subtree, so its name uniqueness only holds at that scope —
+    // distinct services may reuse a gqlName. generateAll re-compiles each target
+    // with the declaring yml as entry, which is exactly when this check applies.
+    const entryDoc = documents[documents.length - 1];
+    const graphqlDiagnostics = entryDoc?.generatorDecls?.some(decl => decl.generator === 'data-connect-graphql')
+        ? graphqlNameCollisions(ir)
+        : [];
     return {
         ir,
         documents,
-        diagnostics: [...importDiagnostics, ...buildDiagnostics, ...validationDiagnostics],
+        diagnostics: [...importDiagnostics, ...buildDiagnostics, ...validationDiagnostics, ...graphqlDiagnostics],
     };
 };
 /** `apis:/tasks:/events:` section a raw api belongs to (drives the section defaults lookup). */
@@ -74,6 +83,30 @@ const resolveOutDir = (out, declaringDoc, rootDoc, diagnostics) => {
 /** 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);
+/** Generators whose output imports the shared types barrel via `options.typesImport`. */
+const TYPES_IMPORT_GENERATORS = new Set(['api-types', 'task-payloads']);
+/**
+ * Derive the default `typesImport` specifier from the typescript declaration
+ * itself: the relative path from the job's output directory to the declared
+ * barrel (`out` + `file`, default `types.ts`). The declaration resolves
+ * nearest-first (same yml → root), mirroring how entries resolve declarations,
+ * so both outputs stay in sync when the barrel is moved or renamed. An explicit
+ * `options.typesImport` always wins; without a typescript declaration in scope
+ * the generator's built-in default applies.
+ */
+const deriveTypesImport = (outDir, doc, rootDoc) => {
+    const decl = findGeneratorDecl('typescript', doc, rootDoc);
+    if (!decl)
+        return undefined;
+    const declaringDoc = doc.generatorDecls?.includes(decl) ? doc : rootDoc;
+    // Alias problems are reported when the typescript job itself is built.
+    const barrelDir = resolveOutDir(decl.out, declaringDoc, rootDoc, []);
+    if (barrelDir === undefined)
+        return undefined;
+    const barrel = join(barrelDir, (decl.file ?? 'types.ts').replace(/\.ts$/, ''));
+    const specifier = relative(outDir, barrel);
+    return specifier.startsWith('.') ? specifier : `./${specifier}`;
+};
 /**
  * Build generator jobs from the declaration/application DSL:
  * - api-scoped generators run for entries that opt in (section `defaults` →
@@ -98,14 +131,12 @@ const buildGeneratorJobs = (doc, rootDoc, registry, diagnostics) => {
             const output = {};
             const file = use.file ?? decl?.file;
             const split = use.split ?? decl?.split ?? generator?.defaultOutput?.split;
-            const options = use.options ?? decl?.options;
+            let 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)) {
@@ -123,6 +154,13 @@ const buildGeneratorJobs = (doc, rootDoc, registry, diagnostics) => {
             const outDir = resolveOutDir(expanded, doc, rootDoc, diagnostics);
             if (outDir === undefined)
                 continue;
+            if (TYPES_IMPORT_GENERATORS.has(use.generator) && options?.['typesImport'] === undefined) {
+                const derived = deriveTypesImport(outDir, doc, rootDoc);
+                if (derived !== undefined)
+                    options = { ...(options ?? {}), typesImport: derived };
+            }
+            if (options !== undefined)
+                output.options = options;
             const key = [use.generator, outDir, file ?? '', String(split ?? ''), JSON.stringify(options ?? null), header ?? '\u0001'].join('\u0000');
             const existing = grouped.get(key);
             if (existing) {
@@ -145,25 +183,16 @@ const buildGeneratorJobs = (doc, rootDoc, registry, diagnostics) => {
         }
         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})`));
+        const output = {};
+        // Document scope: `split: true` selects the generator's per-item layout
+        // (dispatched inside the generator); reject it when none exists.
+        if (decl.split !== undefined) {
+            if (decl.split === true && generator.splittable !== true) {
+                diagnostics.push(error('UNSUPPORTED_SPLIT', `Generator "${decl.generator}" has no split layout (${doc.filePath})`));
                 continue;
             }
+            output.split = decl.split;
         }
-        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})`));
@@ -181,7 +210,7 @@ const buildGeneratorJobs = (doc, rootDoc, registry, diagnostics) => {
             continue;
         jobs.push({
             source: doc.filePath,
-            generatorName,
+            generatorName: decl.generator,
             outDir,
             ...(Object.keys(output).length > 0 ? { output } : {}),
             ...(decl.header !== undefined ? { header: decl.header } : {}),

package/dist/lib/_internal/generators/api/api-dto-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-dto-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/api/api-dto-generator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,SAAS,EAAgC,MAAM,iBAAiB,CAAA;AAoHxF,eAAO,MAAM,qBAAqB,QAAO,SAuBvC,CAAA"}
+{"version":3,"file":"api-dto-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/api/api-dto-generator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,SAAS,EAAgC,MAAM,iBAAiB,CAAA;AA8GxF,eAAO,MAAM,qBAAqB,QAAO,SAuBvC,CAAA"}

package/dist/lib/_internal/generators/api/api-dto-generator.js

@@ -3,6 +3,7 @@ import { pascalCase, singleQuote } from '../support/naming.js';
 import { isRelation, relationFkName } from '../support/relations.js';
 import { selectApis } from '../generator.js';
 import { headerBlocks } from '../support/header.js';
+import { jsdoc } from '../support/jsdoc.js';
 import { emitApiFiles, resolveOutput } from '../support/templates.js';
 const SCALAR_TS = {
     string: 'string',
@@ -96,14 +97,6 @@ const decoratorsFor = (ir, field, used) => {
     }
     return out;
 };
-const jsdoc = (description, indent) => {
-    if (!description)
-        return '';
-    const lines = description.split('\n');
-    if (lines.length === 1)
-        return `${indent}/** ${lines[0]} */\n`;
-    return `${indent}/**\n${lines.map(line => `${indent} * ${line}`.trimEnd()).join('\n')}\n${indent} */\n`;
-};
 const renderDto = (ir, api, used) => {
     const fields = payloadFields(ir, api.request);
     const className = `${pascalCase(api.name)}Dto`;

package/dist/lib/_internal/generators/api/api-types-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-types-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/api/api-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,SAAS,EAAgC,MAAM,iBAAiB,CAAA;AAsFxF,eAAO,MAAM,uBAAuB,QAAO,SA+BzC,CAAA"}
+{"version":3,"file":"api-types-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/api/api-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,SAAS,EAAgC,MAAM,iBAAiB,CAAA;AA4FxF,eAAO,MAAM,uBAAuB,QAAO,SA+BzC,CAAA"}

package/dist/lib/_internal/generators/api/api-types-generator.js

@@ -2,6 +2,7 @@ import { pascalCase } from '../support/naming.js';
 import { isRelation, relationFkName, relationFkType } from '../support/relations.js';
 import { selectApis } from '../generator.js';
 import { headerBlocks } from '../support/header.js';
+import { jsdoc } from '../support/jsdoc.js';
 import { emitApiFiles, resolveOutput } from '../support/templates.js';
 const SCALAR_TS = {
     string: 'string',
@@ -34,8 +35,7 @@ const renderField = (ir, field) => {
     const name = isRelation(field) ? relationFkName(field) : field.name;
     const optional = field.optional ? '?' : '';
     const nullable = field.nullable ? ' | null' : '';
-    const doc = field.description ? `  /** ${field.description} */\n` : '';
-    return `${doc}  ${name}${optional}: ${renderFieldTsType(ir, field)}${nullable}`;
+    return `${jsdoc(field.description, '  ')}  ${name}${optional}: ${renderFieldTsType(ir, field)}${nullable}`;
 };
 const renderPayloadType = (ir, payload, typeName) => {
     if (payload.isVoid) {
@@ -74,9 +74,15 @@ const apiComment = (api) => {
     const bits = [`kind: ${api.kind}`];
     if (api.method)
         bits.push(`method: ${api.method}`);
-    if (api.description)
-        bits.unshift(api.description);
-    return `// ${api.name} — ${bits.join(' | ')}`;
+    const description = api.description?.split('\n') ?? [];
+    // Single-line descriptions stay inline; multi-line ones get their own
+    // comment lines so literal-block yml descriptions survive verbatim.
+    if (description.length <= 1) {
+        if (description[0])
+            bits.unshift(description[0]);
+        return `// ${api.name} — ${bits.join(' | ')}`;
+    }
+    return [`// ${api.name} — ${bits.join(' | ')}`, ...description.map(line => `// ${line}`.trimEnd())].join('\n');
 };
 /**
  * Generates request/response TypeScript types for each API endpoint. A payload

package/dist/lib/_internal/generators/api/task-payload-generator.js

@@ -3,6 +3,7 @@ import { constantCase, pascalCase, singleQuote } from '../support/naming.js';
 import { isRelation, relationFkName, relationFkType } from '../support/relations.js';
 import { selectApis } from '../generator.js';
 import { headerBlocks } from '../support/header.js';
+import { jsdoc } from '../support/jsdoc.js';
 import { emitApiFiles, resolveOutput } from '../support/templates.js';
 const SCALAR_TS = {
     string: 'string',
@@ -30,13 +31,12 @@ const fieldTs = (ir, field) => {
 };
 const renderMember = (ir, field) => {
     const name = isRelation(field) ? relationFkName(field) : field.name;
-    const doc = field.description ? `  /** ${field.description} */\n` : '';
     const nullable = field.nullable ? ' | null' : '';
-    return `${doc}  ${name}${field.optional ? '?' : ''}: ${fieldTs(ir, field)}${nullable}`;
+    return `${jsdoc(field.description, '  ')}  ${name}${field.optional ? '?' : ''}: ${fieldTs(ir, field)}${nullable}`;
 };
 const payloadFields = (ir, payload) => payload.model ? (findModel(ir, payload.model)?.fields ?? []) : payload.fields;
 const renderEnvelope = (env) => {
-    const doc = env.description ? `/** ${env.description} */\n` : '';
+    const doc = jsdoc(env.description, '');
     const members = env.fields.map(field => `  ${field.name}${field.optional ? '?' : ''}: ${SCALAR_TS[field.type.kind === 'scalar' ? field.type.name : 'string']}`).join('\n');
     return `${doc}export type ${env.name}<T> = T & {\n${members}\n}`;
 };

package/dist/lib/_internal/generators/data-connect/graphql-generator.d.ts

@@ -5,11 +5,4 @@ import { Generator } from '../generator.js';
  * comment, matching the "JSON is Any, logical type preserved" rule.
  */
 export declare const createDataConnectGraphqlGenerator: () => Generator;
-/**
- * Split variant matching the real Data Connect layout: one file per table at
- * `schema/<table_name>.gql`, with each enum co-located in the file of the first
- * model that references it (leftover enums go to `schema/_enums.gql`). The `Any`
- * scalar is not declared — Data Connect provides it built-in.
- */
-export declare const createDataConnectGraphqlSplitGenerator: () => Generator;
 //# sourceMappingURL=graphql-generator.d.ts.map

package/dist/lib/_internal/generators/data-connect/graphql-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphql-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/data-connect/graphql-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,SAAS,EAAoB,MAAM,iBAAiB,CAAA;AA+I5E;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,QAAO,SA+BnD,CAAA;AAaF;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC,QAAO,SAmCxD,CAAA"}
+{"version":3,"file":"graphql-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/_internal/generators/data-connect/graphql-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,SAAS,EAAoB,MAAM,iBAAiB,CAAA;AAgJ5E;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,QAAO,SAmClD,CAAA"}

package/dist/lib/_internal/generators/data-connect/graphql-generator.js

@@ -2,6 +2,7 @@ import { headerBlocks } from '../support/header.js';
 import { constantCase, pluralize, snakeCase } from '../support/naming.js';
 import { isRelation } from '../support/relations.js';
 import { outputFile } from '../support/templates.js';
+import { withSplitVariant } from '../support/split-variant.js';
 // Data Connect built-in scalars. `json` and embedded model objects are stored
 // as `Any` — the logical type is preserved in a comment and restored by the
 // Data Connect adapter generator.
@@ -131,7 +132,7 @@ const commentBanner = (header) => header
  * model fields become the `Any` scalar while retaining their logical type as a
  * comment, matching the "JSON is Any, logical type preserved" rule.
  */
-export const createDataConnectGraphqlGenerator = () => ({
+export const createDataConnectGraphqlGenerator = () => withSplitVariant({
     name: 'data-connect-graphql',
     description: 'Data Connect GraphQL schema',
     generate(ir, context) {
@@ -154,7 +155,7 @@ export const createDataConnectGraphqlGenerator = () => ({
         }
         return [{ path: outputFile(context, 'schema.gql'), content: `${blocks.join('\n\n')}\n` }];
     },
-});
+}, createDataConnectGraphqlSplitLayout());
 const renderEnumGql = (irEnum, rename) => {
     const lines = [...commentLines(irEnum.description, '')];
     lines.push(`enum ${gqlOf(rename, irEnum.name)} {`);
@@ -171,8 +172,8 @@ const renderEnumGql = (irEnum, rename) => {
  * model that references it (leftover enums go to `schema/_enums.gql`). The `Any`
  * scalar is not declared — Data Connect provides it built-in.
  */
-export const createDataConnectGraphqlSplitGenerator = () => ({
-    name: 'data-connect-graphql-split',
+const createDataConnectGraphqlSplitLayout = () => ({
+    name: 'data-connect-graphql',
     description: 'Data Connect GraphQL schema, one file per table (schema/<table>.gql)',
     generate(ir, context) {
         const banner = headerBlocks(context, commentBanner);