@dereekb/dbx-cli 13.41.0 → 13.43.0

package/eslint/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/dbx-cli/eslint",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/dbx-cli": "13.43.0",
+    "@dereekb/util": "13.43.0",
     "@typescript-eslint/utils": "8.59.3",
     "typescript": "5.9.3"
   },

package/firebase-api-manifest/main.js

@@ -22,8 +22,8 @@ function renderGroupedImportLines(imports) {
     set.add(identifier);
     importsByPackage.set(packageName, set);
   }
-  return [...importsByPackage.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([pkg, names]) => {
-    const sortedNames = [...names].sort(compareStrings).join(", ");
+  return Array.from(importsByPackage.entries()).sort(([a], [b]) => a.localeCompare(b)).map(([pkg, names]) => {
+    const sortedNames = Array.from(names).sort(compareStrings).join(", ");
     return `import { ${sortedNames} } from '${pkg}';`;
   });
 }
@@ -695,13 +695,18 @@ function escapeRegExp(value) {
 }
 
 // packages/dbx-cli/manifest-extract/src/lib/extract-models.ts
-import { Node as Node4, Project as Project3 } from "ts-morph";
+import { Node as Node4, SyntaxKind, Project as Project3 } from "ts-morph";
 var READ_LEVEL_VALUES = /* @__PURE__ */ new Set(["system", "owner", "admin-only", "permissions"]);
 var SERVICE_FACTORY_TAG = "dbxModelServiceFactory";
 var MCP_TOOL_NAME_SEGMENT_TAG = "dbxModelMcpToolNameSegment";
 var MODEL_TYPE_VALUE_PATTERN = /^[a-z][A-Za-z0-9_$]*$/;
 var TOOL_NAME_SEGMENT_PATTERN = /^[A-Za-z][A-Za-z0-9_$]*$/;
 var IDENTITY_FN = "firestoreModelIdentity";
+var SINGLE_ITEM_COLLECTION_FN = "singleItemFirestoreCollection";
+var ROOT_SINGLE_ITEM_COLLECTION_FN = "rootSingleItemFirestoreCollection";
+var SINGLE_ITEM_COLLECTION_FN_NAMES = [SINGLE_ITEM_COLLECTION_FN, ROOT_SINGLE_ITEM_COLLECTION_FN];
+var MODEL_IDENTITY_KEY = "modelIdentity";
+var SINGLE_ITEM_IDENTIFIER_KEY = "singleItemIdentifier";
 var CONVERTER_FN_NAMES = ["snapshotConverterFunctions", "firestoreSubObject", "firestoreObjectArray"];
 var SUB_OBJECT_FN = "firestoreSubObject";
 var OBJECT_ARRAY_FN = "firestoreObjectArray";
@@ -718,7 +723,9 @@ function extractModelsFromSource(input) {
   const enums = readEnums(sourceFile);
   const modelGroups = readModelGroups(sourceFile);
   const serviceFactories = readServiceFactories(sourceFile);
-  return { identities, interfaces, converters, enums, modelGroups, serviceFactories };
+  const singleItemCollections = readSingleItemCollections(sourceFile);
+  const stringConstants = readStringConstants(sourceFile);
+  return { identities, interfaces, converters, enums, modelGroups, serviceFactories, singleItemCollections, stringConstants };
 }
 function readIdentities(sourceFile) {
   const out = [];
@@ -838,6 +845,65 @@ function readServiceFactoryModelType(jsDocs) {
   }
   return result;
 }
+function readSingleItemCollections(sourceFile) {
+  const out = [];
+  const text = sourceFile.getFullText();
+  if (SINGLE_ITEM_COLLECTION_FN_NAMES.some((name) => text.includes(name))) {
+    for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      const fnName = readCalleeName(call);
+      if (fnName !== SINGLE_ITEM_COLLECTION_FN && fnName !== ROOT_SINGLE_ITEM_COLLECTION_FN) continue;
+      const entry = buildSingleItemCollection(call, fnName === ROOT_SINGLE_ITEM_COLLECTION_FN);
+      if (entry) out.push(entry);
+    }
+  }
+  return out;
+}
+function readCalleeName(call) {
+  const expression = call.getExpression();
+  return Node4.isPropertyAccessExpression(expression) ? expression.getName() : expression.getText();
+}
+function buildSingleItemCollection(call, root) {
+  let result;
+  const args = call.getArguments();
+  if (args.length > 0) {
+    const config = args[0];
+    if (Node4.isObjectLiteralExpression(config)) {
+      const identityNode = readPropertyValue(config, MODEL_IDENTITY_KEY);
+      if (identityNode && Node4.isIdentifier(identityNode)) {
+        const identifierNode = readPropertyValue(config, SINGLE_ITEM_IDENTIFIER_KEY);
+        result = {
+          identityConst: identityNode.getText(),
+          root,
+          documentId: readStringLiteralText(identifierNode),
+          documentIdConstRef: identifierNode && Node4.isIdentifier(identifierNode) ? identifierNode.getText() : void 0,
+          explicitIdentifier: config.getProperty(SINGLE_ITEM_IDENTIFIER_KEY) !== void 0,
+          line: call.getStartLineNumber()
+        };
+      }
+    }
+  }
+  return result;
+}
+function readStringConstants(sourceFile) {
+  const out = [];
+  for (const statement of sourceFile.getVariableStatements()) {
+    if (!statement.isExported()) continue;
+    for (const decl of statement.getDeclarations()) {
+      const value = readStringLiteralText(decl.getInitializer());
+      if (value !== void 0) {
+        out.push({ name: decl.getName(), value });
+      }
+    }
+  }
+  return out;
+}
+function readStringLiteralText(node) {
+  let current = node;
+  while (current !== void 0 && Node4.isAsExpression(current)) {
+    current = current.getExpression();
+  }
+  return current !== void 0 && (Node4.isStringLiteral(current) || Node4.isNoSubstitutionTemplateLiteral(current)) ? current.getLiteralText() : void 0;
+}
 function readConverters(sourceFile) {
   const out = [];
   for (const statement of sourceFile.getVariableStatements()) {
@@ -1134,14 +1200,17 @@ function findModelFiles(packageRoot) {
       const text = readFileSync6(filePath, "utf8");
       if (!textHasModelMarker(text)) continue;
       const extraction = extractModelsFromSource({ name: filePath, text });
-      if (extraction.identities.length === 0 && extraction.modelGroups.length === 0 && extraction.converters.length === 0 && extraction.serviceFactories.length === 0) continue;
+      if (!hasExtractedArtifact(extraction)) continue;
       out.push({ filePath, extraction });
     }
   }
   return out;
 }
 function textHasModelMarker(text) {
-  return text.includes("firestoreModelIdentity(") || text.includes("@dbxModelGroup") || text.includes("snapshotConverterFunctions") || text.includes("firestoreSubObject") || text.includes("firestoreObjectArray") || text.includes("@dbxModelServiceFactory");
+  return text.includes("firestoreModelIdentity(") || text.includes("@dbxModelGroup") || text.includes("snapshotConverterFunctions") || text.includes("firestoreSubObject") || text.includes("firestoreObjectArray") || text.includes("@dbxModelServiceFactory") || text.includes("singleItemFirestoreCollection") || text.includes("rootSingleItemFirestoreCollection") || text.includes("export enum ");
+}
+function hasExtractedArtifact(extraction) {
+  return extraction.identities.length > 0 || extraction.modelGroups.length > 0 || extraction.converters.length > 0 || extraction.serviceFactories.length > 0 || extraction.singleItemCollections.length > 0 || extraction.enums.length > 0;
 }
 function* walkSourceFiles(dir) {
   for (const entry of readdirSync2(dir).sort()) {
@@ -1156,7 +1225,7 @@ function* walkSourceFiles(dir) {
   }
 }
 function isCandidateSourceFile(name) {
-  return name.endsWith(".ts") && !name.endsWith(".api.ts") && !name.endsWith(".spec.ts") && !name.endsWith(".test.ts") && !name.endsWith(".id.ts") && !name.endsWith(".d.ts");
+  return name.endsWith(".ts") && !name.endsWith(".api.ts") && !name.endsWith(".spec.ts") && !name.endsWith(".test.ts") && !name.endsWith(".d.ts");
 }
 function safeIsDirectory2(p) {
   let result;
@@ -1172,6 +1241,8 @@ function safeIsDirectory2(p) {
 var MAX_NESTED_DEPTH = 8;
 var LONG_NAME_RE = /^[a-z][a-zA-Z0-9]*$/;
 var ENUM_GENERIC_RE = /firestoreEnum<(\w+)>|optionalFirestoreEnum<(\w+)>/;
+var TS_TYPE_TOKEN_RE = /[A-Za-z_$][\w$]*/g;
+var DEFAULT_SINGLE_ITEM_DOCUMENT_ID = "0";
 function assembleModels(input) {
   const registries = buildGlobalRegistries(input.extractions);
   const accumulator = { seen: /* @__PURE__ */ new Set(), entries: [] };
@@ -1185,7 +1256,7 @@ function collectModelEnums(input) {
   const registry = buildEnumRegistry(input.extractions);
   const referenced = collectReferencedEnumNames(input.models);
   const out = {};
-  for (const name of [...referenced].sort((a, b) => a.localeCompare(b))) {
+  for (const name of Array.from(referenced).sort((a, b) => a.localeCompare(b))) {
     const extracted = registry.get(name);
     if (extracted) {
       out[name] = buildModelEnumEntry(extracted);
@@ -1227,17 +1298,31 @@ function buildGlobalRegistries(extractions) {
   const interfaceRegistry = /* @__PURE__ */ new Map();
   const groupByModelName = /* @__PURE__ */ new Map();
   const serviceFactoryByModelType = /* @__PURE__ */ new Map();
+  const enumNames = /* @__PURE__ */ new Set();
+  const singleItemByIdentityConst = /* @__PURE__ */ new Map();
+  const identityByConst = /* @__PURE__ */ new Map();
+  const stringConstants = /* @__PURE__ */ new Map();
   for (const { extraction, sourceFile } of extractions) {
     registerConverters(extraction.converters, converterRegistry);
     registerInterfaces(extraction.interfaces, interfaceRegistry);
     registerModelGroups(extraction.modelGroups, groupByModelName);
+    for (const e of extraction.enums) enumNames.add(e.name);
+    for (const identity of extraction.identities) {
+      if (!identityByConst.has(identity.identityConst)) identityByConst.set(identity.identityConst, identity);
+    }
+    for (const single of extraction.singleItemCollections) {
+      if (!singleItemByIdentityConst.has(single.identityConst)) singleItemByIdentityConst.set(single.identityConst, single);
+    }
+    for (const constant of extraction.stringConstants) {
+      if (!stringConstants.has(constant.name)) stringConstants.set(constant.name, constant.value);
+    }
     for (const factory of extraction.serviceFactories) {
       if (!serviceFactoryByModelType.has(factory.modelType)) {
         serviceFactoryByModelType.set(factory.modelType, { exportName: factory.exportName, sourceFile });
       }
     }
   }
-  return { converterRegistry, interfaceRegistry, groupByModelName, serviceFactoryByModelType };
+  return { converterRegistry, interfaceRegistry, groupByModelName, serviceFactoryByModelType, enumNames, singleItemByIdentityConst, identityByConst, stringConstants };
 }
 function registerConverters(converters, registry) {
   for (const converter of converters) {
@@ -1259,10 +1344,9 @@ function registerModelGroups(modelGroups, registry) {
   }
 }
 function appendEntriesFromSource(source, registries, accumulator) {
-  const enumNames = new Set(source.extraction.enums.map((e) => e.name));
   for (const identity of source.extraction.identities) {
     if (accumulator.seen.has(identity.identityConst)) continue;
-    const entry = buildEntryForIdentity({ identity, source, registries, enumNames });
+    const entry = buildEntryForIdentity({ identity, source, registries });
     if (entry) {
       accumulator.seen.add(identity.identityConst);
       accumulator.entries.push(entry);
@@ -1270,7 +1354,7 @@ function appendEntriesFromSource(source, registries, accumulator) {
   }
 }
 function buildEntryForIdentity(input) {
-  const { identity, source, registries, enumNames } = input;
+  const { identity, source, registries } = input;
   let result;
   if (identity.collectionPrefix !== void 0) {
     const modelName = capitalize(identity.modelType);
@@ -1283,7 +1367,7 @@ function buildEntryForIdentity(input) {
           iface,
           interfaceRegistry: registries.interfaceRegistry,
           converterRegistry: registries.converterRegistry,
-          enumNames,
+          enumNames: registries.enumNames,
           depth: 0,
           visitedConverters: /* @__PURE__ */ new Set()
         });
@@ -1297,6 +1381,12 @@ function buildManifestEntry(input) {
   const { identity, modelName, collectionPrefix, iface, fields, source, registries } = input;
   const modelGroup = registries.groupByModelName.get(modelName);
   const serviceFactory = registries.serviceFactoryByModelType.get(identity.modelType);
+  const single = registries.singleItemByIdentityConst.get(identity.identityConst);
+  const singleItemIdentifier = single ? resolveSingleItemDocumentId(single, registries) : void 0;
+  if (single && singleItemIdentifier === void 0) {
+    console.warn(`[single-item-id-unresolved] ${source.sourceFile}:${single.line} \xB7 ${identity.modelType} \u2192 singleItemIdentifier ${single.documentIdConstRef ?? "(expression)"} could not be resolved to a string; the model's fixed document id is omitted from the manifest`);
+  }
+  const exampleKey = buildExampleKey({ identity, collectionPrefix, singleItemIdentifier, registries });
   return {
     modelType: identity.modelType,
     modelName,
@@ -1304,6 +1394,9 @@ function buildManifestEntry(input) {
     identityConst: identity.identityConst,
     collectionPrefix,
     ...identity.parentIdentityConst ? { parentIdentityConst: identity.parentIdentityConst } : {},
+    ...single ? { singleton: true } : {},
+    ...singleItemIdentifier === void 0 ? {} : { singleItemIdentifier },
+    ...exampleKey === void 0 ? {} : { exampleKey },
     ...iface.description ? { description: iface.description } : {},
     sourcePackage: source.sourcePackage,
     sourceFile: source.sourceFile,
@@ -1314,6 +1407,46 @@ function buildManifestEntry(input) {
     ...serviceFactory ? { serviceFactory } : {}
   };
 }
+function resolveSingleItemDocumentId(single, registries) {
+  let result;
+  if (!single.explicitIdentifier) {
+    result = DEFAULT_SINGLE_ITEM_DOCUMENT_ID;
+  } else if (single.documentId !== void 0) {
+    result = single.documentId;
+  } else if (single.documentIdConstRef !== void 0) {
+    result = registries.stringConstants.get(single.documentIdConstRef);
+  }
+  return result;
+}
+function buildExampleKey(input) {
+  const { identity, collectionPrefix, singleItemIdentifier, registries } = input;
+  const segments = [`${collectionPrefix}/${singleItemIdentifier ?? modelIdPlaceholder(identity.modelType)}`];
+  const visited = /* @__PURE__ */ new Set([identity.identityConst]);
+  let parentConst = identity.parentIdentityConst;
+  let resolved = true;
+  while (resolved && parentConst !== void 0) {
+    const parent = visited.has(parentConst) ? void 0 : registries.identityByConst.get(parentConst);
+    if (parent === void 0) {
+      resolved = false;
+    } else {
+      visited.add(parent.identityConst);
+      segments.unshift(`${collectionNameFor(parent)}/${ancestorDocumentIdFor(parent, registries)}`);
+      parentConst = parent.parentIdentityConst;
+    }
+  }
+  return resolved ? segments.join("/") : void 0;
+}
+function collectionNameFor(identity) {
+  return identity.collectionPrefix ?? identity.modelType.toLowerCase();
+}
+function ancestorDocumentIdFor(identity, registries) {
+  const single = registries.singleItemByIdentityConst.get(identity.identityConst);
+  const documentId = single ? resolveSingleItemDocumentId(single, registries) : void 0;
+  return documentId ?? modelIdPlaceholder(identity.modelType);
+}
+function modelIdPlaceholder(modelType) {
+  return `<${modelType}Id>`;
+}
 function findConverterForInterface(extraction, interfaceName) {
   return extraction.converters.find((c) => c.interfaceName === interfaceName);
 }
@@ -1425,11 +1558,13 @@ function resolveLongName(fieldName, propLongName) {
 function resolveEnumRef(converter, tsType, enumNames) {
   let result;
   if (tsType) {
-    for (const name of enumNames) {
-      const re = new RegExp(String.raw`\b${name}\b`);
-      if (re.test(tsType)) {
-        result = name;
-        break;
+    TS_TYPE_TOKEN_RE.lastIndex = 0;
+    let match = TS_TYPE_TOKEN_RE.exec(tsType);
+    while (result === void 0 && match !== null) {
+      if (enumNames.has(match[0])) {
+        result = match[0];
+      } else {
+        match = TS_TYPE_TOKEN_RE.exec(tsType);
       }
     }
   }
@@ -1453,7 +1588,7 @@ function deriveValidatorName(paramsTypeName) {
 
 // packages/dbx-cli/firebase-api-manifest/src/generate-api-manifest/emit.ts
 async function renderManifest(input) {
-  const { outputFile, entries, projectName, namespace, modelEntries, modelNamespace, enumEntries, enumNamespace, emitConverters = false } = input;
+  const { outputFile, entries, projectName, namespace, modelEntries, modelNamespace, enumEntries, enumNamespace, emitConverters = false, generatorVersion } = input;
   const validatorImports = [];
   for (const entry of entries) {
     if (!entry.packageName || !entry.validatorName) continue;
@@ -1463,7 +1598,7 @@ async function renderManifest(input) {
   const entryLines = entries.map((e) => renderEntry(e));
   const emitModels = Boolean(modelEntries && modelEntries.length > 0 && modelNamespace);
   const emitEnums = Boolean(enumEntries && Object.keys(enumEntries).length > 0 && enumNamespace);
-  const dbxCliTypeNames = ["type CliApiManifest", ...emitModels ? ["type CliModelManifest"] : [], ...emitEnums ? ["type CliEnumManifest"] : []];
+  const dbxCliTypeNames = ["type CliApiManifest", "type CliGeneratedManifestStamp", ...emitModels ? ["type CliModelManifest"] : [], ...emitEnums ? ["type CliEnumManifest"] : []];
   const dbxCliTypeImports = `import { ${dbxCliTypeNames.join(", ")} } from '@dereekb/dbx-cli';`;
   const modelSection = emitModels ? `
 
@@ -1482,6 +1617,8 @@ export const ${enumNamespace}: CliEnumManifest = ${renderEnumManifest(enumEntrie
 ${importLines.join("\n")}
 ${dbxCliTypeImports}
 
+export const ${namespace}_STAMP: CliGeneratedManifestStamp = { generatorVersion: ${JSON.stringify(generatorVersion)} };
+
 export const ${namespace}: CliApiManifest = [
 ${entryLines.join(",\n")}
 ];${modelSection}${enumSection}
@@ -1525,6 +1662,9 @@ function renderModelEntry(entry, emitConverters) {
     `identityConst: ${JSON.stringify(entry.identityConst)}`,
     `collectionPrefix: ${JSON.stringify(entry.collectionPrefix)}`,
     entry.parentIdentityConst ? `parentIdentityConst: ${JSON.stringify(entry.parentIdentityConst)}` : void 0,
+    entry.singleton ? "singleton: true" : void 0,
+    entry.singleItemIdentifier === void 0 ? void 0 : `singleItemIdentifier: ${JSON.stringify(entry.singleItemIdentifier)}`,
+    entry.exampleKey === void 0 ? void 0 : `exampleKey: ${JSON.stringify(entry.exampleKey)}`,
     entry.description ? `description: ${JSON.stringify(entry.description)}` : void 0,
     `sourcePackage: ${JSON.stringify(entry.sourcePackage)}`,
     `sourceFile: ${JSON.stringify(entry.sourceFile)}`,
@@ -1580,6 +1720,22 @@ function renderModelField(field, emitConverters) {
   return `{ ${parts.filter(Boolean).join(", ")} }`;
 }
 
+// packages/dbx-cli/firebase-api-manifest/package.json
+var package_default = {
+  name: "@dereekb/dbx-cli-firebase-api-manifest",
+  version: "13.43.0",
+  private: true,
+  type: "module",
+  devDependencies: {
+    "ts-morph": "^21.0.0"
+  },
+  peerDependencies: {
+    "@dereekb/dbx-cli": "13.43.0",
+    "@dereekb/util": "13.43.0",
+    prettier: "3.8.3"
+  }
+};
+
 // packages/dbx-cli/firebase-api-manifest/src/generate-api-manifest/main.ts
 var WORKSPACE_ROOT = process.cwd();
 async function main() {
@@ -1670,7 +1826,7 @@ async function main() {
   const modelEntries = flags.emitModels ? assembleModels({ extractions: modelSources }) : [];
   const filteredModelEntries = flags.only ? modelEntries.filter((m) => flags.only?.has(m.modelType)) : modelEntries;
   const enumEntries = flags.emitModels ? collectModelEnums({ extractions: modelSources, models: filteredModelEntries }) : {};
-  const formatted = await renderManifest({ outputFile, entries: collected, projectName, namespace, modelEntries: filteredModelEntries, modelNamespace: deriveModelNamespace(flags.project), enumEntries, enumNamespace: deriveEnumNamespace(flags.project), emitConverters: flags.emitModelConverters });
+  const formatted = await renderManifest({ outputFile, entries: collected, projectName, namespace, modelEntries: filteredModelEntries, modelNamespace: deriveModelNamespace(flags.project), enumEntries, enumNamespace: deriveEnumNamespace(flags.project), emitConverters: flags.emitModelConverters, generatorVersion: package_default.version });
   const outcome = writeGeneratedTsFile({ outputFile, contents: formatted });
   console.log(`[${outcome}] ${relative2(WORKSPACE_ROOT, outputFile)}`);
   const groupCount = packageCache.size === 0 ? 0 : new Set(collected.map((c) => c.entry.groupName)).size;

package/firebase-api-manifest/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/dbx-cli-firebase-api-manifest",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "private": true,
   "type": "module",
   "devDependencies": {
     "ts-morph": "^21.0.0"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.41.0",
-    "@dereekb/util": "13.41.0",
+    "@dereekb/dbx-cli": "13.43.0",
+    "@dereekb/util": "13.43.0",
     "prettier": "3.8.3"
   }
 }

package/firestore-indexes/src/generate-firestore-indexes-cli.d.ts

@@ -1,10 +1,18 @@
 /**
  * `generate-firestore-indexes` subcommand entry point.
  *
- * Walks a downstream `-firebase` component for `@dbxModelFirebaseIndex`-
- * tagged factories (the same pipeline `scan-model-firebase-indexes` uses),
- * runs the analyzer, and emits a canonical `firestore.indexes.json`
- * payload via {@link generateFirestoreIndexesJson}.
+ * Walks one or more `-firebase` components/packages for
+ * `@dbxModelFirebaseIndex`-tagged factories (the same pipeline
+ * `scan-model-firebase-indexes` uses), runs the analyzer, and emits a
+ * canonical `firestore.indexes.json` payload via
+ * {@link generateFirestoreIndexesJson}.
+ *
+ * `--component` is repeatable, and that is the supported way to derive a
+ * single deployed indexes file from several packages. Firebase deploys one
+ * indexes file per database, and nothing merges per-package files — a
+ * package's composites otherwise survive in a downstream file only by the
+ * "collections no factory touches" preservation rule, which silently drops
+ * them the moment a local factory touches the same collection.
  *
  * Two modes:
  *

package/firestore-indexes/src/model-firebase-index-analyze.d.ts

@@ -5,8 +5,14 @@
  * extractor and decides, per `(collection, scope, constraintSequence)`,
  * whether the query requires a composite index, a `fieldOverrides[]`
  * variant, or neither (because Firestore's automatic single-field
- * `COLLECTION`-scope index already covers the query). Encodes Firestore's
- * field-order rule for composites:
+ * `COLLECTION`-scope index already covers the query).
+ *
+ * "Neither" also covers a multi-field `COLLECTION`-scope sequence made up
+ * purely of `==` filters: Firestore merges the automatic single-field
+ * indexes to serve those, so emitting a composite would only add write
+ * latency and storage. See {@link isEqualityOnlySequence}.
+ *
+ * Encodes Firestore's field-order rule for composites:
  *
  *   1. Equality (`==`, `in`) fields first, in source order.
  *   2. A single range/inequality field next (direction taken from any
@@ -51,6 +57,10 @@ export type AnalyzerWarning = {
     readonly kind: 'unsupported-array-contains-any';
     readonly factoryName: string;
     readonly field: string;
+} | {
+    readonly kind: 'equality-only-composite-skipped';
+    readonly factoryName: string;
+    readonly fields: readonly string[];
 };
 /**
  * Runs the analyzer over every extracted entry.

package/firestore-query-manifest/main.js

@@ -9,15 +9,15 @@ import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve3 }
 // packages/dbx-cli/firestore-query-manifest/package.json
 var package_default = {
   name: "@dereekb/dbx-cli-firestore-query-manifest",
-  version: "13.41.0",
+  version: "13.43.0",
   private: true,
   type: "module",
   devDependencies: {
     eslint: "10.4.0"
   },
   peerDependencies: {
-    "@dereekb/dbx-cli": "13.41.0",
-    "@dereekb/util": "13.41.0"
+    "@dereekb/dbx-cli": "13.43.0",
+    "@dereekb/util": "13.43.0"
   }
 };
 
@@ -37,8 +37,8 @@ function renderGroupedImportLines(imports) {
     set.add(identifier);
     importsByPackage.set(packageName, set);
   }
-  return [...importsByPackage.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([pkg, names]) => {
-    const sortedNames = [...names].sort(compareStrings).join(", ");
+  return Array.from(importsByPackage.entries()).sort(([a], [b]) => a.localeCompare(b)).map(([pkg, names]) => {
+    const sortedNames = Array.from(names).sort(compareStrings).join(", ");
     return `import { ${sortedNames} } from '${pkg}';`;
   });
 }
@@ -82,9 +82,9 @@ function scanFirestoreRules(source) {
       if (allow.ops.has("list") || allow.ops.has("read")) current.list = mergeAccess(current.list, allow.access);
     }
   });
-  const collections = [...accumulated.entries()].map(([collection, value]) => ({
+  const collections = Array.from(accumulated.entries()).map(([collection, value]) => ({
     collection,
-    paths: [...value.paths].sort(),
+    paths: Array.from(value.paths).sort(),
     get: value.get,
     list: value.list,
     collectionGroup: value.collectionGroup,
@@ -294,7 +294,7 @@ function parentPathsForCollection(scan, collection) {
       parents.add(parentSegments.join("/"));
     }
   }
-  return [...parents];
+  return Array.from(parents);
 }
 
 // packages/dbx-cli/src/lib/scan-helpers/exported-from-package.ts
@@ -422,7 +422,7 @@ function bindQueryFactories(input) {
 
 // packages/dbx-cli/firestore-query-manifest/src/emit.ts
 async function renderQueryManifest(input) {
-  const { outputFile, entries, projectName, namespace } = input;
+  const { outputFile, entries, projectName, namespace, generatorVersion } = input;
   const factoryImports = entries.filter((x) => x.bound).map((x) => ({ packageName: x.entry.module, identifier: x.entry.name }));
   const importLines = renderGroupedImportLines(factoryImports);
   const sorted = [...entries].sort((a, b) => compareStrings(a.entry.slug, b.entry.slug));
@@ -431,7 +431,9 @@ async function renderQueryManifest(input) {
 // Run \`npx nx run ${projectName}:generate-firestore-query-manifest\` to refresh.
 
 ${importLines.join("\n")}
-import { type CliFirestoreQueryManifest } from '@dereekb/dbx-cli';
+import { type CliFirestoreQueryManifest, type CliGeneratedManifestStamp } from '@dereekb/dbx-cli';
+
+export const ${namespace}_STAMP: CliGeneratedManifestStamp = { generatorVersion: ${JSON.stringify(generatorVersion)} };
 
 export const ${namespace}: CliFirestoreQueryManifest = [
 ${sorted.map((x) => renderEntry(x)).join(",\n")}
@@ -670,11 +672,18 @@ function analyzeSequence(input) {
   if (isSingleFieldQuery(buckets)) {
     return analyzeSingleField({ buckets, collection, scope, warnings });
   }
+  if (scope === "COLLECTION" && isEqualityOnlySequence(buckets)) {
+    warnings.push({ kind: "equality-only-composite-skipped", factoryName, fields: buckets.equalities.map((e) => e.fieldPath) });
+    return { kind: "auto", warnings };
+  }
   return analyzeMultiField({ buckets, sequenceEntries: sequence.entries, collection, scope, factoryName, warnings });
 }
 function isSingleFieldQuery(buckets) {
   return buckets.distinctFieldCount === 1;
 }
+function isEqualityOnlySequence(buckets) {
+  return buckets.ranges.length === 0 && buckets.arrays.length === 0 && buckets.orderBys.length === 0 && buckets.equalities.length > 0 && buckets.equalities.every((e) => (e.operator ?? "==") === "==");
+}
 function analyzeSingleField(input) {
   const { buckets, collection, scope, warnings } = input;
   if (scope === "COLLECTION") {
@@ -769,7 +778,7 @@ function collectOrderByDirections(input) {
     }
   }
   for (const [field, dirs] of conflicts) {
-    warnings.push({ kind: "orderby-conflict", factoryName, field, directions: [...dirs] });
+    warnings.push({ kind: "orderby-conflict", factoryName, field, directions: Array.from(dirs) });
   }
   return out;
 }
@@ -1250,7 +1259,7 @@ function composeEntry(input) {
 }
 function resolveConstraintSequences(input) {
   const { candidate, tags, name, line, filePath, warnings } = input;
-  const bodyResult = extractConstraintsFromBody({ decl: candidate.decl, factoryName: name, filePath, dispatcher: tags.dispatcher });
+  const bodyResult = extractConstraintsFromBody({ decl: candidate.decl, factoryName: name, filePath, dispatcher: tags.dispatcher, suppressed: tags.skip || tags.specOnly });
   for (const warning of bodyResult.warnings) {
     warnings.push(warning);
   }
@@ -1331,11 +1340,14 @@ function buildConstraintSequences(input) {
   return sequences;
 }
 function extractConstraintsFromBody(input) {
-  const { decl, factoryName, filePath, dispatcher } = input;
+  const { decl, factoryName, filePath, dispatcher, suppressed } = input;
   const entries = [];
   const conditionalFieldSet = /* @__PURE__ */ new Set();
   const warnings = [];
   const body = decl.getBody();
+  if (suppressed) {
+    return { entries, conditionalFields: [], warnings, skipped: true, dispatcherDelegates: [] };
+  }
   if (dispatcher) {
     const violation = body === void 0 ? void 0 : findFirstConstraintCall(body);
     if (violation !== void 0) {
@@ -2235,7 +2247,7 @@ async function main() {
   for (const warning of queryModes.warnings) {
     console.warn(warning);
   }
-  const formatted = await renderQueryManifest({ outputFile, entries: queryModes.entries, projectName, namespace });
+  const formatted = await renderQueryManifest({ outputFile, entries: queryModes.entries, projectName, namespace, generatorVersion: package_default.version });
   const relOutput = relative2(WORKSPACE_ROOT, outputFile);
   if (flags.check) {
     const current = existsSync3(outputFile) ? readFileSync3(outputFile, "utf8") : void 0;

package/firestore-query-manifest/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dereekb/dbx-cli-firestore-query-manifest",
-  "version": "13.41.0",
+  "version": "13.43.0",
   "private": true,
   "type": "module",
   "devDependencies": {
     "eslint": "10.4.0"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.41.0",
-    "@dereekb/util": "13.41.0"
+    "@dereekb/dbx-cli": "13.43.0",
+    "@dereekb/util": "13.43.0"
   }
 }