🥽 fix: Stop the DocumentDB Guard Flagging Mongoose's Document $where (#15686)

The DocumentDB compatibility guard flagged Mongoose per-document save-condition bag reads and writes (document.$where) in tenantIsolation.ts as the unsupported $where operator, leaving dev red on Tests: data-schemas. The guard now judges a dotted $where only where the syntax is unambiguous: a call in any form, or code assigned through any operator or wrapper, is an offense; a read or a non-literal assignment is not claimed, with filter.$where = predicate stated as the one declared limit and the method sweep and live cluster run as its backstop. Every other way of writing the operator remains an offense. unwrapExpression also peels angle-bracket assertions, closing a gap in pipeline-update detection.

Author: danny-avila

packages/data-schemas/src/methods/documentdb.spec.ts

@@ -23,8 +23,9 @@ import ts from 'typescript';
  * that talks to MongoDB — this package, `packages/api`, and `api` — because the
  * regression class is repo-wide and new backend code lands in `packages/api`.
  * Dataflow is followed within a file only — a pipeline imported from another
- * module is out of reach — and the method sweep and the live cluster run are
- * the completeness backstops, not this guard.
+ * module is out of reach — and a dotted `$where` is judged only where syntax is
+ * unambiguous (see `isUnjudgedDottedWhere`); the method sweep and the live
+ * cluster run are the completeness backstops, not this guard.
  * If a construct here becomes genuinely necessary, the fix is a compatible
  * rewrite, not an exception list: `misc/documentdb/audit.documentdb.spec.ts`
  * re-adjudicates any of this against a real cluster.
@@ -186,11 +187,13 @@ function parse(fileName: string, source: string): ts.SourceFile {
   return ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true);
 }
 
-/** Peels casts and parentheses so `[...] as PipelineStage[]` is still an array. */
+/** Peels casts, assertions and parentheses so `[...] as PipelineStage[]` and
+ * `<PipelineStage[]>[...]` are still arrays. */
 function unwrapExpression(expression: ts.Expression): ts.Expression {
   let current = expression;
   while (
     ts.isAsExpression(current) ||
+    ts.isTypeAssertionExpression(current) ||
     ts.isSatisfiesExpression(current) ||
     ts.isParenthesizedExpression(current) ||
     ts.isNonNullExpression(current)
@@ -404,15 +407,114 @@ function findPipelineUpdates(sourceFile: ts.SourceFile): string[] {
  * ignoring prose — the rewrites explain themselves by naming the construct —
  * and type members, which never reach the engine (Mongoose documents declare
  * a `$where` field). */
+/** The operator's value is code; the document bag's value is field predicates. */
+function isJavaScriptSource(expression: ts.Expression): boolean {
+  const unwrapped = unwrapExpression(expression);
+  return (
+    ts.isStringLiteralLike(unwrapped) ||
+    ts.isTemplateExpression(unwrapped) ||
+    ts.isArrowFunction(unwrapped) ||
+    ts.isFunctionExpression(unwrapped)
+  );
+}
+
+/**
+ * A dotted `$where` is Mongoose's per-document save-condition bag on a document
+ * (`mongoose/lib/model.js` copies its keys into the save filter as ordinary field
+ * predicates, so nothing named `$where` reaches the server) and the JavaScript
+ * evaluation operator on a query or filter, and syntax alone cannot tell the two
+ * apart. So it is judged only where the syntax is unambiguous: a CALL
+ * (`query.$where(js)`, parenthesised, or through `call`/`apply`/`bind`) or an
+ * assignment of CODE (a string, template, arrow or function). A read, or an
+ * assignment of anything else — `document.$where = { … }` in
+ * `tenantIsolation.ts`, but equally `filter.$where = predicate` — is not claimed
+ * either way; for the latter the method sweep and the live cluster run are the
+ * backstop. Every other way of writing the operator (`{ $where: … }`,
+ * `'$where'`, `obj['$where']`) remains an offense.
+ */
+const CALL_FORWARDERS = new Set(['call', 'apply', 'bind']);
+const CODE_ASSIGNMENT_OPERATORS = new Set([
+  ts.SyntaxKind.EqualsToken,
+  ts.SyntaxKind.PlusEqualsToken,
+  ts.SyntaxKind.QuestionQuestionEqualsToken,
+  ts.SyntaxKind.BarBarEqualsToken,
+  ts.SyntaxKind.AmpersandAmpersandEqualsToken,
+]);
+
+/** Steps outward through the wrappers `unwrapExpression` peels inward, so a
+ * call on or an assignment to `(x)`, `x as T`, `<T>x`, `x satisfies T` or `x!`
+ * is still one on `x`. */
+function outermostWrapper(node: ts.Node): ts.Node {
+  let current = node;
+  while (
+    ts.isParenthesizedExpression(current.parent) ||
+    ts.isAsExpression(current.parent) ||
+    ts.isTypeAssertionExpression(current.parent) ||
+    ts.isSatisfiesExpression(current.parent) ||
+    ts.isNonNullExpression(current.parent)
+  ) {
+    current = current.parent;
+  }
+  return current;
+}
+
+function isInvoked(callee: ts.Node): boolean {
+  const use = outermostWrapper(callee).parent;
+  return ts.isCallExpression(use) && use.expression === outermostWrapper(callee);
+}
+
+/** The member name a node is accessed through, whether dotted (`x.call`) or by a
+ * string element (`x['call']`). */
+function memberName(use: ts.Node, receiver: ts.Node): string | undefined {
+  if (ts.isPropertyAccessExpression(use) && use.expression === receiver) {
+    return use.name.text;
+  }
+  if (ts.isElementAccessExpression(use) && use.expression === receiver) {
+    const argument = unwrapExpression(use.argumentExpression);
+    return ts.isStringLiteralLike(argument) ? argument.text : undefined;
+  }
+  return undefined;
+}
+
+/** A direct call, or a call through `call`/`apply`/`bind` — the forwarder itself
+ * must be invoked, so a bag field that merely shares one of those names is not a call. */
+function isCalled(access: ts.PropertyAccessExpression): boolean {
+  if (isInvoked(access)) {
+    return true;
+  }
+  const target = outermostWrapper(access);
+  const forwarder = memberName(target.parent, target);
+  return forwarder != null && CALL_FORWARDERS.has(forwarder) && isInvoked(target.parent);
+}
+
+function isUnjudgedDottedWhere(node: ts.Node): boolean {
+  if (!ts.isIdentifier(node) || node.text !== '$where') {
+    return false;
+  }
+  const access = node.parent;
+  if (!ts.isPropertyAccessExpression(access) || access.name !== node || isCalled(access)) {
+    return false;
+  }
+  const target = outermostWrapper(access);
+  const use = target.parent;
+  const assignsCode =
+    ts.isBinaryExpression(use) &&
+    use.left === target &&
+    CODE_ASSIGNMENT_OPERATORS.has(use.operatorToken.kind) &&
+    isJavaScriptSource(use.right);
+  return !assignsCode;
+}
+
 function findForbiddenTokens(sourceFile: ts.SourceFile): string[] {
   if (OPERATOR_GUARDS.has(sourceFile.fileName)) {
     return [];
   }
   const offenses: string[] = [];
   const visit = (node: ts.Node): void => {
     if (
-      ts.isStringLiteralLike(node) ||
-      (ts.isIdentifier(node) && !ts.isPropertySignature(node.parent))
+      !isUnjudgedDottedWhere(node) &&
+      (ts.isStringLiteralLike(node) ||
+        (ts.isIdentifier(node) && !ts.isPropertySignature(node.parent)))
     ) {
       for (const token of FORBIDDEN_TOKENS) {
         if (node.text === token || node.text.startsWith(`${token}.`)) {
@@ -676,6 +778,10 @@ describe('Amazon DocumentDB compatibility', () => {
         'annotated variable with a builder initializer',
         `const update: PipelineStage[] = importedBuilder();\nModel.updateMany(filter, update);`,
       ],
+      [
+        'angle-bracket cast literal',
+        `Model.updateOne(filter, <PipelineStage[]>[{ $set: { a: 1 } }]);`,
+      ],
     ])('flags a pipeline update: %s', (_shape, source) => {
       expect(findPipelineUpdates(parse('fixture.ts', source))).not.toEqual([]);
     });
@@ -730,6 +836,105 @@ describe('Amazon DocumentDB compatibility', () => {
           parse('fixture.ts', `interface Doc { $where: Record<string, unknown> }`),
         ),
       ).toEqual([]);
+      /** A dotted `$where` is judged only where the syntax is unambiguous. Not
+       * claimed either way — Mongoose's document save-condition bag in
+       * `tenantIsolation.ts` is read and written exactly like this: */
+      expect(findForbiddenTokens(parse('fixture.ts', `const where = document.$where;`))).toEqual(
+        [],
+      );
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `document.$where = { tenantId: predicate };`)),
+      ).toEqual([]);
+      expect(
+        findForbiddenTokens(
+          parse('fixture.ts', `document.$where = Object.keys(rest).length > 0 ? rest : undefined;`),
+        ),
+      ).toEqual([]);
+      /** ...including a non-literal assigned to a filter, which no syntax can tell
+       * from the bag write; the method sweep and the live run are the backstop. */
+      expect(findForbiddenTokens(parse('fixture.ts', `filter.$where = predicate;`))).toEqual([]);
+      /** ...and a bag field that happens to be named like a call forwarder. */
+      expect(findForbiddenTokens(parse('fixture.ts', `document.$where.call = expected;`))).toEqual(
+        [],
+      );
+      /** Every way of writing the operator itself is an offense: */
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `const filter = { $where: 'this.a == 1' };`)),
+      ).not.toEqual([]);
+      expect(findForbiddenTokens(parse('fixture.ts', `const op = '$where';`))).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `filter['$where'] = 'this.a == 1';`)),
+      ).not.toEqual([]);
+      /** ...and so is a dotted `$where` that is called or assigned code: */
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `filter.$where = 'this.a == 1';`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', 'filter.$where = `this.a == ${value}`;')),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `filter.$where = () => this.a == 1;`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `query.$where(function () { return true; });`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `Model.find().$where('this.a == 1');`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `(query.$where)('this.a == 1');`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `query.$where.call(query, 'this.a == 1');`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `query.$where.apply(query, ['this.a == 1']);`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `const w = query.$where.bind(query);`)),
+      ).not.toEqual([]);
+      expect(findForbiddenTokens(parse('fixture.ts', `this.$where('this.a == 1');`))).not.toEqual(
+        [],
+      );
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `document.$where('this.a == 1');`)),
+      ).not.toEqual([]);
+      /** The assignment target and the assigned value may each be wrapped, the
+       * operator may append, and a forwarder may be reached by element access. */
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `(filter.$where as string) = 'this.a == 1';`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `filter.$where! = 'this.a == 1';`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `filter.$where += ' && this.b == 2';`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `filter.$where = <string>'this.a == 1';`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `query.$where['call'](query, 'this.a == 1');`)),
+      ).not.toEqual([]);
+      /** Compound assignments of code, and calls through TypeScript's transparent
+       * wrappers, are the same two shapes spelled differently. */
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `filter.$where ??= 'this.a == 1';`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `filter.$where ||= () => this.a == 1;`)),
+      ).not.toEqual([]);
+      expect(
+        findForbiddenTokens(
+          parse('fixture.ts', `(query.$where as typeof query.$where)('this.a == 1');`),
+        ),
+      ).not.toEqual([]);
+      expect(findForbiddenTokens(parse('fixture.ts', `query.$where!('this.a == 1');`))).not.toEqual(
+        [],
+      );
+      expect(
+        findForbiddenTokens(parse('fixture.ts', `(query.$where!).call(query, 'this.a == 1');`)),
+      ).not.toEqual([]);
     });
 
     it.each([