@dereekb/dbx-cli 13.40.0 → 13.42.0

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.40.0",
+  version: "13.42.0",
   private: true,
   type: "module",
   devDependencies: {
     eslint: "10.4.0"
   },
   peerDependencies: {
-    "@dereekb/dbx-cli": "13.40.0",
-    "@dereekb/util": "13.40.0"
+    "@dereekb/dbx-cli": "13.42.0",
+    "@dereekb/util": "13.42.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}';`;
   });
 }
@@ -62,6 +62,241 @@ function writeGeneratedTsFile(input) {
   return result;
 }
 
+// packages/dbx-cli/firestore-rules/src/firestore-rules-scan.ts
+var RULES_ROOT_PREFIX = /^\/?databases\/\{[^}]*\}\/documents/;
+function scanFirestoreRules(source) {
+  const text = stripComments(source);
+  const accumulated = /* @__PURE__ */ new Map();
+  walkMatchBlocks(text, (block) => {
+    const collection = collectionForPathSegments(block.segments);
+    if (collection == null) return;
+    const current = accumulated.get(collection) ?? (() => {
+      const created = { paths: /* @__PURE__ */ new Set(), get: "unmatched", list: "unmatched", collectionGroup: false };
+      accumulated.set(collection, created);
+      return created;
+    })();
+    current.paths.add("/" + block.segments.join("/"));
+    current.collectionGroup = current.collectionGroup || block.segments.some(isRecursiveWildcard);
+    for (const allow of block.allows) {
+      if (allow.ops.has("get") || allow.ops.has("read")) current.get = mergeAccess(current.get, allow.access);
+      if (allow.ops.has("list") || allow.ops.has("read")) current.list = mergeAccess(current.list, allow.access);
+    }
+  });
+  const collections = Array.from(accumulated.entries()).map(([collection, value]) => ({
+    collection,
+    paths: Array.from(value.paths).sort(),
+    get: value.get,
+    list: value.list,
+    collectionGroup: value.collectionGroup,
+    serverOnly: value.get !== "allowed" && value.list !== "allowed"
+  })).sort((a, b) => a.collection.localeCompare(b.collection));
+  return { collections };
+}
+// @__NO_SIDE_EFFECTS__
+function firestoreRulesAccessForCollection(scan, collection) {
+  return scan.collections.find((x) => x.collection === collection) ?? { collection, paths: [], get: "unmatched", list: "unmatched", collectionGroup: false, serverOnly: true };
+}
+function mergeAccess(current, incoming) {
+  let result;
+  if (current === "allowed" || incoming === "allowed") {
+    result = "allowed";
+  } else if (current === "denied" || incoming === "denied") {
+    result = "denied";
+  } else {
+    result = "unmatched";
+  }
+  return result;
+}
+function collectionForPathSegments(segments) {
+  const candidate = segments.length >= 2 ? segments[segments.length - 2] : void 0;
+  return candidate != null && !isWildcard(candidate) ? candidate : void 0;
+}
+function isWildcard(segment) {
+  return segment.startsWith("{") && segment.endsWith("}");
+}
+function isRecursiveWildcard(segment) {
+  return isWildcard(segment) && segment.includes("=**");
+}
+function stripComments(source) {
+  let result = "";
+  let index = 0;
+  let quote;
+  while (index < source.length) {
+    const char = source[index];
+    const next = source[index + 1];
+    if (quote != null) {
+      result += char;
+      if (char === "\\" && index + 1 < source.length) {
+        result += next;
+        index += 2;
+        continue;
+      }
+      if (char === quote) quote = void 0;
+      index += 1;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+      result += char;
+      index += 1;
+    } else if (char === "/" && next === "/") {
+      while (index < source.length && source[index] !== "\n") index += 1;
+    } else if (char === "/" && next === "*") {
+      index += 2;
+      while (index < source.length && !(source[index] === "*" && source[index + 1] === "/")) index += 1;
+      index += 2;
+    } else {
+      result += char;
+      index += 1;
+    }
+  }
+  return result;
+}
+function walkMatchBlocks(text, visit) {
+  const pathStack = [];
+  const braceFrames = [];
+  let index = 0;
+  while (index < text.length) {
+    const matchStart = findKeyword(text, index, "match");
+    const braceIndex = text.indexOf("{", index);
+    const closeIndex = text.indexOf("}", index);
+    const allowStart = findKeyword(text, index, "allow");
+    const next = Math.min(...[matchStart, braceIndex, closeIndex, allowStart].filter((x) => x >= 0).concat([text.length]));
+    if (next >= text.length) break;
+    if (next === matchStart) {
+      const parsed = parseMatchHeader(text, matchStart);
+      pathStack.push(parsed.segments);
+      braceFrames.push({ isMatch: true, allows: [] });
+      index = parsed.bodyStart;
+    } else if (next === allowStart) {
+      const parsed = parseAllow(text, allowStart);
+      const frame = braceFrames[braceFrames.length - 1];
+      if (frame?.isMatch && parsed) frame.allows.push(parsed.allow);
+      index = parsed ? parsed.end : allowStart + "allow".length;
+    } else if (next === braceIndex) {
+      braceFrames.push({ isMatch: false, allows: [] });
+      index = braceIndex + 1;
+    } else {
+      const frame = braceFrames.pop();
+      if (frame?.isMatch) {
+        const segments = stripRootPrefix(pathStack.flat());
+        visit({ segments, allows: frame.allows });
+        pathStack.pop();
+      }
+      index = closeIndex + 1;
+    }
+  }
+}
+function stripRootPrefix(segments) {
+  const joined = segments.join("/");
+  const stripped = joined.replace(RULES_ROOT_PREFIX, "");
+  return stripped.split("/").filter((x) => x.length > 0);
+}
+function parseMatchHeader(text, start) {
+  const braceIndex = text.indexOf("{", start + "match".length);
+  let cursor = start + "match".length;
+  let path = "";
+  while (cursor < text.length) {
+    const char = text[cursor];
+    if (char === "{") {
+      const close = text.indexOf("}", cursor);
+      const inner = text.slice(cursor, close + 1);
+      if (close > cursor && /^\{[A-Za-z_][\w]*(=\*\*)?\}$/.test(inner)) {
+        path += inner;
+        cursor = close + 1;
+        continue;
+      }
+      break;
+    }
+    if (char === "\n" && path.trim().length > 0) break;
+    path += char;
+    cursor += 1;
+  }
+  const bodyBrace = text.includes("{", cursor - 1) ? text.indexOf("{", cursor) : braceIndex;
+  const segments = path.trim().split("/").map((x) => x.trim()).filter((x) => x.length > 0);
+  return { segments, bodyStart: (bodyBrace >= 0 ? bodyBrace : cursor) + 1 };
+}
+function parseAllow(text, start) {
+  const colonIndex = text.indexOf(":", start);
+  const semiIndex = text.indexOf(";", start);
+  let result;
+  if (colonIndex >= 0 && semiIndex > colonIndex) {
+    const ops = new Set(
+      text.slice(start + "allow".length, colonIndex).split(",").map((x) => x.trim()).filter((x) => x.length > 0)
+    );
+    const condition = text.slice(colonIndex + 1, semiIndex).replace(/^\s*if\s*/, "").trim();
+    result = { allow: { ops, access: condition === "false" ? "denied" : "allowed" }, end: semiIndex + 1 };
+  }
+  return result;
+}
+function findKeyword(text, from, keyword) {
+  let index = text.indexOf(keyword, from);
+  while (index >= 0) {
+    const before = index === 0 ? " " : text[index - 1];
+    const after = text[index + keyword.length] ?? " ";
+    if (!/[\w$]/.test(before) && !/[\w$]/.test(after)) break;
+    index = text.indexOf(keyword, index + keyword.length);
+  }
+  return index;
+}
+
+// packages/dbx-cli/src/lib/firestore/query-mode.ts
+// @__NO_SIDE_EFFECTS__
+function cliFirestoreQueryModeForRules(input) {
+  const { scope, isNested, collectionGroup, list, parentPaths } = input;
+  const base = { list, collectionGroup, ...parentPaths && parentPaths.length > 0 ? { parentPaths } : {} };
+  let result;
+  if (list !== "allowed") {
+    const reason = list === "denied" ? "list-denied" : "list-unmatched";
+    result = { mode: "unavailable", rules: { ...base, reason } };
+  } else if (scope === "COLLECTION_GROUP" && !collectionGroup) {
+    result = { mode: isNested ? "parent-child" : "unavailable", rules: { ...base, reason: "no-collection-group-rule" } };
+  } else if (scope === "COLLECTION" && isNested) {
+    result = { mode: "parent-child", rules: { ...base, reason: "nested-collection-scope" } };
+  } else {
+    result = { mode: "model", rules: base };
+  }
+  return result;
+}
+
+// packages/dbx-cli/firestore-query-manifest/src/annotate-query-mode.ts
+function annotateQueryEntryMode(input) {
+  const { entries, rulesSource } = input;
+  const scan = scanFirestoreRules(rulesSource);
+  let model = 0;
+  const unavailableSlugs = [];
+  const parentChildSlugs = [];
+  const annotated = entries.map((entry) => {
+    const rules = firestoreRulesAccessForCollection(scan, entry.collection);
+    const { mode, rules: entryRules } = cliFirestoreQueryModeForRules({
+      scope: entry.scope,
+      isNested: entry.isNested,
+      collectionGroup: rules.collectionGroup,
+      list: rules.list,
+      parentPaths: parentPathsForCollection(scan, entry.collection)
+    });
+    if (mode === "model") {
+      model += 1;
+    } else if (mode === "parent-child") {
+      parentChildSlugs.push(entry.slug);
+    } else {
+      unavailableSlugs.push(entry.slug);
+    }
+    return { ...entry, queryMode: mode, rules: entryRules };
+  });
+  return { entries: annotated, model, unavailableSlugs, parentChildSlugs };
+}
+function parentPathsForCollection(scan, collection) {
+  const paths = firestoreRulesAccessForCollection(scan, collection).paths;
+  const parents = /* @__PURE__ */ new Set();
+  for (const path of paths) {
+    const segments = path.split("/").filter((x) => x.length > 0);
+    const parentSegments = segments.slice(0, -2);
+    if (parentSegments.length > 0 && !parentSegments.some((x) => x.includes("=**"))) {
+      parents.add(parentSegments.join("/"));
+    }
+  }
+  return Array.from(parents);
+}
+
 // packages/dbx-cli/src/lib/scan-helpers/exported-from-package.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";
 import { dirname as dirname2, isAbsolute, join, resolve } from "node:path";
@@ -225,10 +460,16 @@ function renderEntry({ entry, bound }) {
     entry.skip ? "skip: true" : void 0,
     entry.excluded ? "excluded: true" : void 0,
     entry.dispatcher ? "dispatcher: true" : void 0,
+    entry.queryMode ? `queryMode: ${JSON.stringify(entry.queryMode)}` : void 0,
+    entry.rules ? `rules: ${renderRules(entry.rules)}` : void 0,
     bound ? `factory: ${entry.name}` : void 0
   ];
   return `  { ${fields.filter(Boolean).join(", ")} }`;
 }
+function renderRules(rules) {
+  const parts = [`list: ${JSON.stringify(rules.list)}`, `collectionGroup: ${rules.collectionGroup ? "true" : "false"}`, rules.reason ? `reason: ${JSON.stringify(rules.reason)}` : void 0, rules.parentPaths && rules.parentPaths.length > 0 ? `parentPaths: ${JSON.stringify(rules.parentPaths)}` : void 0];
+  return `{ ${parts.filter(Boolean).join(", ")} }`;
+}
 function renderParams(params) {
   const items = params.map((param) => {
     const parts = [`name: ${JSON.stringify(param.name)}`, `type: ${JSON.stringify(param.type)}`, param.description ? `description: ${JSON.stringify(param.description)}` : void 0, `optional: ${param.optional ? "true" : "false"}`];
@@ -429,11 +670,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") {
@@ -528,7 +776,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;
 }
@@ -1009,7 +1257,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);
   }
@@ -1090,11 +1338,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) {
@@ -1985,7 +2236,16 @@ async function main() {
   for (const warning of warnings) {
     console.warn(warning);
   }
-  const formatted = await renderQueryManifest({ outputFile, entries: collected, projectName, namespace });
+  const queryModes = applyQueryModes({ collected, rules: flags.rules });
+  if (queryModes.kind === "failure") {
+    console.error(queryModes.message);
+    process.exit(1);
+    return;
+  }
+  for (const warning of queryModes.warnings) {
+    console.warn(warning);
+  }
+  const formatted = await renderQueryManifest({ outputFile, entries: queryModes.entries, projectName, namespace });
   const relOutput = relative2(WORKSPACE_ROOT, outputFile);
   if (flags.check) {
     const current = existsSync3(outputFile) ? readFileSync3(outputFile, "utf8") : void 0;
@@ -2000,12 +2260,38 @@ async function main() {
     console.log(`[${outcome}] ${relOutput}`);
   }
   const boundCount = collected.filter((x) => x.bound).length;
-  console.log(`Summary: ${flags.components.length} component(s) \xB7 ${collected.length} entries \xB7 ${boundCount} invocable \xB7 ${collected.length - boundCount} unbound \xB7 ${droppedSpecOnly} spec-only dropped`);
+  console.log(`Summary: ${flags.components.length} component(s) \xB7 ${collected.length} entries \xB7 ${boundCount} bound \xB7 ${collected.length - boundCount} unbound \xB7 ${droppedSpecOnly} spec-only dropped \xB7 rules: ${queryModes.summary}`);
   if (flags.strict && boundCount < collected.length) {
     console.error(`[strict] ${collected.length - boundCount} factor(y|ies) failed to bind \u2014 failing build.`);
     process.exit(1);
   }
 }
+function applyQueryModes(input) {
+  const { collected, rules } = input;
+  let result;
+  if (rules) {
+    const rulesFile = resolveWorkspacePath(rules);
+    if (existsSync3(rulesFile)) {
+      const annotated = annotateQueryEntryMode({ entries: collected.map((x) => x.entry), rulesSource: readFileSync3(rulesFile, "utf8") });
+      const entries = annotated.entries.map((entry, index) => ({ ...collected[index], entry }));
+      const warnings = annotated.unavailableSlugs.map((slug) => `[query-unavailable] ${slug} \u2014 no client can run this query; see \`firestore-queries ${slug}\`.`);
+      if (annotated.parentChildSlugs.length > 0) {
+        warnings.push(`[query-parent-child] ${annotated.parentChildSlugs.length} quer${annotated.parentChildSlugs.length === 1 ? "y" : "ies"} run only with --parent: ${annotated.parentChildSlugs.join(", ")}`);
+      }
+      result = {
+        kind: "success",
+        entries,
+        warnings,
+        summary: `${annotated.model} model \xB7 ${annotated.parentChildSlugs.length} parent-child \xB7 ${annotated.unavailableSlugs.length} unavailable`
+      };
+    } else {
+      result = { kind: "failure", message: `[rules] ${relative2(WORKSPACE_ROOT, rulesFile)} does not exist \u2014 fix --rules or drop it.` };
+    }
+  } else {
+    result = { kind: "success", entries: collected, warnings: [], summary: "not scanned (pass --rules=<firestore.rules> to resolve query modes)" };
+  }
+  return result;
+}
 function resolveWorkspacePath(value) {
   return isAbsolute2(value) ? value : resolve3(WORKSPACE_ROOT, value);
 }
@@ -2017,6 +2303,7 @@ function parseFlags(argv) {
   const components = [];
   let output;
   let project;
+  let rules;
   let strict = false;
   let check = false;
   for (const arg of argv) {
@@ -2031,9 +2318,12 @@ function parseFlags(argv) {
       output = arg.slice("--output=".length);
     } else if (arg.startsWith("--project=")) {
       project = arg.slice("--project=".length);
+    } else if (arg.startsWith("--rules=")) {
+      const value = arg.slice("--rules=".length).trim();
+      if (value) rules = value;
     }
   }
-  return { components, output, project, strict, check };
+  return { components, output, project, rules, strict, check };
 }
 function printUsageAndExit() {
   console.error(String.raw`generate-firestore-query-manifest
@@ -2043,7 +2333,7 @@ Usage:
     --project=<name> \
     --component=<component-dir> [--component=<component-dir> ...] \
     --output=<path-to-query.manifest.generated.ts> \
-    [--strict] [--check]
+    [--rules=<path-to-firestore.rules>] [--strict] [--check]
 
 Required flags:
   --component=<dir>  A "-firebase" component root to scan. Repeatable.
@@ -2051,6 +2341,10 @@ Required flags:
 
 Optional:
   --project=<name>   Project name for the regenerate banner; also derives the constant name.
+  --rules=<path>     The app's firestore.rules. Stamps each entry with how it must be invoked
+                     (model / parent-child / unavailable), so a catalogued-but-unrunnable query is
+                     flagged at generation time instead of surfacing as AUTH_FORBIDDEN at call
+                     time. Omitted => unknown.
   --strict           Fail when any tagged factory is not exported from its component barrel.
   --check            Do not write; fail when the committed file is out of date.`);
   process.exit(1);

package/firestore-query-manifest/package.json

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