firebase-contract 0.1.0-rc.11 → 0.1.0-rc.12

package/README.md

@@ -34,6 +34,7 @@ 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
@@ -103,7 +104,13 @@ generators:
   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
@@ -174,6 +181,18 @@ 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.
+
 ```yaml
 version: 1
 imports:

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;AA6MD;;;;;;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) {

package/dist/lib/_internal/validation/rules.d.ts

@@ -28,5 +28,37 @@ export declare const apis: ValidationRule;
 export declare const firestore: ValidationRule;
 /** Union variants must be known models, each carrying the discriminant field. */
 export declare const unions: ValidationRule;
+/**
+ * Type names must be unique within every output namespace — the export surface
+ * where generated identifiers converge (a split layout still merges into one
+ * barrel, so physical files are irrelevant). Renames (`gqlName` / `fsName`)
+ * deliberately move a type between namespaces, so each namespace is checked
+ * independently against its *effective* names:
+ *
+ * - TypeScript types module: model/enum/union logical names, enum const
+ *   (`CONSTANT_CASE`) and `…Key` companions, plus the reserved `Json` type
+ * - zod schemas module: logical names and their `…Schema` companions
+ * - unions module: union names/schemas plus the variant schemas it imports
+ * - firestore module: doc names, co-located enums/embedded models under
+ *   `fsName ?? name`, plus the `_Meta_…` / `FIRESTORE_DATABASES` runtime
+ *
+ * GraphQL names are checked separately ({@link graphqlNameCollisions}) because
+ * that namespace is scoped per data-connect-graphql declaration, not global.
+ *
+ * Same-kind duplicates are already DUPLICATE_DEFINITION at merge time; this
+ * rule closes every cross-kind and derived-identifier hole. Each colliding
+ * definition pair is reported once (the first namespace that trips).
+ */
+export declare const nameCollisions: ValidationRule;
+/**
+ * GraphQL name uniqueness under `gqlName ?? name`. Unlike {@link nameCollisions}
+ * this is NOT a default rule: a GraphQL schema exists per `data-connect-graphql`
+ * declaration, scoped to the declaring yml's import subtree — distinct services
+ * may intentionally reuse a gqlName (e.g. a `T2…` logical name mapped back to
+ * the plain name inside its own service). The compiler runs this check only
+ * when the entry document itself declares a GraphQL-emitting generator, i.e.
+ * exactly at the scope the schema is generated from.
+ */
+export declare const graphqlNameCollisions: ValidationRule;
 export declare const DEFAULT_RULES: ValidationRule[];
 //# sourceMappingURL=rules.d.ts.map

package/dist/lib/_internal/validation/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/validation/rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAA;AAC9D,OAAO,EAAa,EAAE,EAAgB,MAAM,aAAa,CAAA;AAEzD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,CAAA;AAIrD,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,cAU3B,CAAA;AAEH,6CAA6C;AAC7C,eAAO,MAAM,UAAU,EAAE,cAQpB,CAAA;AAEL,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,EAAE,cAgB9B,CAAA;AAEJ,kFAAkF;AAClF,eAAO,MAAM,UAAU,EAAE,cAiCxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,QAAQ,EAAE,cA+BnB,CAAA;AAEJ,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,EAAE,cAkC9B,CAAA;AAEJ,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,cAU1B,CAAA;AAEH,mGAAmG;AACnG,eAAO,MAAM,UAAU,EAAE,cA+ErB,CAAA;AAEJ,uFAAuF;AACvF,eAAO,MAAM,IAAI,EAAE,cAYf,CAAA;AAEJ,wFAAwF;AACxF,eAAO,MAAM,SAAS,EAAE,cA+BpB,CAAA;AAEJ,iFAAiF;AACjF,eAAO,MAAM,MAAM,EAAE,cAoBjB,CAAA;AAEJ,eAAO,MAAM,aAAa,EAAE,cAAc,EAYzC,CAAA"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../../src/lib/_internal/validation/rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAA;AAG9D,OAAO,EAAa,EAAE,EAAgB,MAAM,aAAa,CAAA;AAEzD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,CAAA;AAIrD,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAE,cAU3B,CAAA;AAEH,6CAA6C;AAC7C,eAAO,MAAM,UAAU,EAAE,cAQpB,CAAA;AAEL,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,EAAE,cAgB9B,CAAA;AAEJ,kFAAkF;AAClF,eAAO,MAAM,UAAU,EAAE,cAiCxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,QAAQ,EAAE,cA+BnB,CAAA;AAEJ,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,EAAE,cAkC9B,CAAA;AAEJ,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,cAU1B,CAAA;AAEH,mGAAmG;AACnG,eAAO,MAAM,UAAU,EAAE,cA+ErB,CAAA;AAEJ,uFAAuF;AACvF,eAAO,MAAM,IAAI,EAAE,cAYf,CAAA;AAEJ,wFAAwF;AACxF,eAAO,MAAM,SAAS,EAAE,cA+BpB,CAAA;AAEJ,iFAAiF;AACjF,eAAO,MAAM,MAAM,EAAE,cAoBjB,CAAA;AAaJ;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,cAAc,EAAE,cA+E5B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAmBnC,CAAA;AAED,eAAO,MAAM,aAAa,EAAE,cAAc,EAazC,CAAA"}

package/dist/lib/_internal/validation/rules.js

@@ -1,4 +1,6 @@
 import { error, warning } from '../diagnostics.js';
+import { constantCase } from '../generators/support/naming.js';
+import { isTable } from '../generators/support/split.js';
 import { findModel } from '../ir/ir.js';
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Every field type must resolve to a known scalar, enum, or model. */
@@ -267,6 +269,122 @@ export const unions = ir => ir.unions.flatMap(union => {
     }
     return diagnostics;
 });
+const RESERVED_OWNER = 'the generated runtime';
+/**
+ * Type names must be unique within every output namespace — the export surface
+ * where generated identifiers converge (a split layout still merges into one
+ * barrel, so physical files are irrelevant). Renames (`gqlName` / `fsName`)
+ * deliberately move a type between namespaces, so each namespace is checked
+ * independently against its *effective* names:
+ *
+ * - TypeScript types module: model/enum/union logical names, enum const
+ *   (`CONSTANT_CASE`) and `…Key` companions, plus the reserved `Json` type
+ * - zod schemas module: logical names and their `…Schema` companions
+ * - unions module: union names/schemas plus the variant schemas it imports
+ * - firestore module: doc names, co-located enums/embedded models under
+ *   `fsName ?? name`, plus the `_Meta_…` / `FIRESTORE_DATABASES` runtime
+ *
+ * GraphQL names are checked separately ({@link graphqlNameCollisions}) because
+ * that namespace is scoped per data-connect-graphql declaration, not global.
+ *
+ * Same-kind duplicates are already DUPLICATE_DEFINITION at merge time; this
+ * rule closes every cross-kind and derived-identifier hole. Each colliding
+ * definition pair is reported once (the first namespace that trips).
+ */
+export const nameCollisions = ir => {
+    const diagnostics = [];
+    const reportedPairs = new Set();
+    const check = (space, claims) => {
+        const first = new Map();
+        for (const claim of claims) {
+            const prev = first.get(claim.identifier);
+            if (!prev) {
+                first.set(claim.identifier, claim);
+                continue;
+            }
+            if (prev.owner === claim.owner)
+                continue;
+            const pair = [prev.owner, claim.owner].sort().join(' vs ');
+            if (reportedPairs.has(pair))
+                continue;
+            reportedPairs.add(pair);
+            diagnostics.push(error('NAME_COLLISION', `${prev.owner} and ${claim.owner} both emit "${claim.identifier}" in the ${space} output`, {
+                file: claim.file ?? prev.file,
+                path: claim.path,
+            }));
+        }
+    };
+    const claim = (owner, file, path, identifiers) => identifiers.map(identifier => ({ owner, identifier, file, path }));
+    // TypeScript types module: the logical namespace every other output derives from.
+    check('TypeScript types', [
+        { owner: RESERVED_OWNER, identifier: 'Json', path: '(generated)' },
+        ...ir.models.flatMap(m => claim(`model "${m.name}"`, m.sourceFile, `models.${m.name}`, [m.name])),
+        ...ir.enums.flatMap(e => claim(`enum "${e.name}"`, e.sourceFile, `enums.${e.name}`, [e.name, `${e.name}Key`, constantCase(e.name)])),
+        ...ir.unions.flatMap(u => claim(`union "${u.name}"`, u.sourceFile, `unions.${u.name}`, [u.name])),
+    ]);
+    // zod schemas module: logical names plus their `…Schema` consts.
+    check('zod schemas', [
+        ...ir.models.flatMap(m => claim(`model "${m.name}"`, m.sourceFile, `models.${m.name}`, [m.name, `${m.name}Schema`])),
+        ...ir.enums.flatMap(e => claim(`enum "${e.name}"`, e.sourceFile, `enums.${e.name}`, [e.name, `${e.name}Schema`])),
+    ]);
+    // unions module: union declarations plus the variant schemas imported into it.
+    const variantOwners = new Map();
+    for (const union of ir.unions)
+        for (const variant of union.variants)
+            variantOwners.set(variant, `model "${variant}"`);
+    check('unions', [
+        ...ir.unions.flatMap(u => claim(`union "${u.name}"`, u.sourceFile, `unions.${u.name}`, [u.name, `${u.name}Schema`])),
+        ...[...variantOwners.entries()].map(([variant, owner]) => {
+            const model = findModel(ir, variant);
+            return { owner, identifier: `${variant}Schema`, file: model?.sourceFile, path: `models.${variant}` };
+        }),
+    ]);
+    // firestore module: doc schemas + co-located enums/embedded models under fsName-effective names.
+    // Tables are imported as `Dc…Schema` aliases, so they don't claim names here.
+    check('firestore', [
+        ...['_Meta_', '_Meta_Schema', '_Meta_Operation', '_Meta_OperationSchema', 'FIRESTORE_DATABASES', 'FirestoreDatabaseKey', 'FirestoreDatabaseId'].map(identifier => ({ owner: RESERVED_OWNER, identifier, path: '(generated)' })),
+        ...ir.firestore.flatMap(d => claim(`firestore doc "${d.name}"`, d.sourceFile, `firestore.${d.name}`, [d.name, `${d.name}Schema`])),
+        ...ir.enums.flatMap(e => {
+            const fs = e.fsName ?? e.name;
+            return claim(`enum "${e.name}"`, e.sourceFile, `enums.${e.name}`, [fs, `${fs}Key`, constantCase(fs), `${fs}Schema`]);
+        }),
+        ...ir.models
+            .filter(m => !isTable(m))
+            .flatMap(m => {
+            const fs = m.fsName ?? m.name;
+            return claim(`model "${m.name}"`, m.sourceFile, `models.${m.name}`, [fs, `${fs}Schema`]);
+        }),
+    ]);
+    return diagnostics;
+};
+/**
+ * GraphQL name uniqueness under `gqlName ?? name`. Unlike {@link nameCollisions}
+ * this is NOT a default rule: a GraphQL schema exists per `data-connect-graphql`
+ * declaration, scoped to the declaring yml's import subtree — distinct services
+ * may intentionally reuse a gqlName (e.g. a `T2…` logical name mapped back to
+ * the plain name inside its own service). The compiler runs this check only
+ * when the entry document itself declares a GraphQL-emitting generator, i.e.
+ * exactly at the scope the schema is generated from.
+ */
+export const graphqlNameCollisions = ir => {
+    const diagnostics = [];
+    const first = new Map();
+    const claims = [
+        ...ir.models.map(m => ({ owner: `model "${m.name}"`, name: m.gqlName ?? m.name, file: m.sourceFile, path: `models.${m.name}` })),
+        ...ir.enums.map(e => ({ owner: `enum "${e.name}"`, name: e.gqlName ?? e.name, file: e.sourceFile, path: `enums.${e.name}` })),
+    ];
+    for (const { owner, name, file, path } of claims) {
+        const prev = first.get(name);
+        if (!prev) {
+            first.set(name, { owner, file, path });
+            continue;
+        }
+        if (prev.owner === owner)
+            continue;
+        diagnostics.push(error('NAME_COLLISION', `${prev.owner} and ${owner} both emit "${name}" in the GraphQL schema output`, { file: file ?? prev.file, path }));
+    }
+    return diagnostics;
+};
 export const DEFAULT_RULES = [
     unresolvedTypes,
     emptyEnums,
@@ -279,4 +397,5 @@ export const DEFAULT_RULES = [
     apis,
     firestore,
     unions,
+    nameCollisions,
 ];

package/dist/lib/cli/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/cli/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAOnC,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,GAAI,SAAS,OAAO,KAAG,IAKnD,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/cli/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAQnC,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,GAAI,SAAS,OAAO,KAAG,IAMnD,CAAA"}

package/dist/lib/cli/commands/index.js

@@ -2,10 +2,12 @@ import { registerGenerate } from './generate.js';
 import { registerInit } from './init.js';
 import { registerInspect } from './inspect.js';
 import { registerValidate } from './validate.js';
+import { registerWhere } from './where.js';
 /** Register every CLI command on the program. */
 export const registerCommands = (program) => {
     registerInit(program);
     registerValidate(program);
     registerGenerate(program);
     registerInspect(program);
+    registerWhere(program);
 };

package/dist/lib/cli/commands/where.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const registerWhere: (program: Command) => void;
+//# sourceMappingURL=where.d.ts.map

package/dist/lib/cli/commands/where.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"where.d.ts","sourceRoot":"","sources":["../../../../src/lib/cli/commands/where.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AA+CnC,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,KAAG,IA2BhD,CAAA"}

package/dist/lib/cli/commands/where.js

@@ -0,0 +1,57 @@
+import { compile } from '../../_internal/compiler/compiler.js';
+import { hasErrors } from '../../_internal/diagnostics.js';
+import { formatDiagnostics } from '../../_internal/format-diagnostics.js';
+import { loadConfig } from '../config.js';
+const definitionsOf = (ir) => [
+    ...ir.models.map(m => ({
+        kind: 'model',
+        name: m.name,
+        sourceFile: m.sourceFile,
+        yamlPath: `models.${m.name}`,
+        renames: [
+            ...(m.gqlName ? [`gqlName: ${m.gqlName}`] : []),
+            ...(m.fsName ? [`fsName: ${m.fsName}`] : []),
+            ...(m.table ? [`table: ${m.table}`] : []),
+        ],
+    })),
+    ...ir.enums.map(e => ({
+        kind: 'enum',
+        name: e.name,
+        sourceFile: e.sourceFile,
+        yamlPath: `enums.${e.name}`,
+        renames: [...(e.gqlName ? [`gqlName: ${e.gqlName}`] : []), ...(e.fsName ? [`fsName: ${e.fsName}`] : [])],
+    })),
+    ...ir.unions.map(u => ({ kind: 'union', name: u.name, sourceFile: u.sourceFile, yamlPath: `unions.${u.name}`, renames: [] })),
+    ...ir.firestore.map(d => ({ kind: 'firestore doc', name: d.name, sourceFile: d.sourceFile, yamlPath: `firestore.${d.name}`, renames: [] })),
+    ...ir.envelopes.map(e => ({ kind: 'envelope', name: e.name, sourceFile: e.sourceFile, yamlPath: `envelopes.${e.name}`, renames: [] })),
+    ...ir.apis.map(a => ({ kind: 'api', name: a.name, sourceFile: a.sourceFile, yamlPath: `apis.${a.name}`, renames: [] })),
+    ...ir.operations.map(o => ({ kind: 'operation', name: o.name, sourceFile: o.sourceFile, yamlPath: `operations.${o.name}`, renames: [] })),
+];
+/** True when the definition is known by `query` under any of its names. */
+const matches = (definition, query) => definition.name === query || definition.renames.some(rename => rename.endsWith(`: ${query}`));
+export const registerWhere = (program) => {
+    program
+        .command('where')
+        .description('Locate the yml that defines a type (matches logical, gqlName, fsName, and table names)')
+        .argument('<name>', 'type name to look up')
+        .argument('[entry]', 'entry contract file')
+        .action((name, entryArg) => {
+        const config = loadConfig();
+        const entry = entryArg ?? config.entry ?? 'contract.yml';
+        const { ir, diagnostics } = compile(entry);
+        if (hasErrors(diagnostics)) {
+            console.error(formatDiagnostics(diagnostics));
+            process.exit(1);
+        }
+        const found = definitionsOf(ir).filter(definition => matches(definition, name));
+        if (found.length === 0) {
+            console.error(`"${name}" is not defined in ${entry} or its imports`);
+            process.exit(1);
+        }
+        for (const definition of found) {
+            const location = definition.sourceFile ?? '(unknown file)';
+            const renames = definition.renames.length > 0 ? `  [${definition.renames.join(', ')}]` : '';
+            console.log(`${definition.kind} ${definition.name}  ${location}  (${definition.yamlPath})${renames}`);
+        }
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-contract",
-  "version": "0.1.0-rc.11",
+  "version": "0.1.0-rc.12",
   "type": "module",
   "bin": {
     "firebase-contract": "./dist/lib/cli/index.js",