@dereekb/dbx-cli 13.40.0 → 13.42.0

package/eslint/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/dbx-cli/eslint",
-  "version": "13.40.0",
+  "version": "13.42.0",
   "type": "module",
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.40.0",
-    "@dereekb/util": "13.40.0",
+    "@dereekb/dbx-cli": "13.42.0",
+    "@dereekb/util": "13.42.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);
       }
     }
   }
@@ -1525,6 +1660,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)}`,

package/firebase-api-manifest/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/dbx-cli-firebase-api-manifest",
-  "version": "13.40.0",
+  "version": "13.42.0",
   "private": true,
   "type": "module",
   "devDependencies": {
     "ts-morph": "^21.0.0"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.40.0",
-    "@dereekb/util": "13.40.0",
+    "@dereekb/dbx-cli": "13.42.0",
+    "@dereekb/util": "13.42.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.