@ttt-productions/repo-guards 0.1.26 → 0.1.28

package/dist/modules/firestore/client-guards.d.ts

@@ -13,4 +13,9 @@ export interface FirestoreRuntimeInUiFacts {
 }
 export declare function firestoreRuntimeImports(file: FileView): Hit[];
 export declare const firestoreRuntimeInUiGuard: GenericGuardDefinition<FirestoreRuntimeInUiFacts>;
+export interface FirestoreClientWritesFacts {
+    sanctioned: readonly Reviewed[];
+}
+export declare function firestoreClientWriteHits(file: FileView): Hit[];
+export declare const firestoreClientWritesGuard: GenericGuardDefinition<FirestoreClientWritesFacts>;
 //# sourceMappingURL=client-guards.d.ts.map

package/dist/modules/firestore/client-guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-guards.d.ts","sourceRoot":"","sources":["../../../src/modules/firestore/client-guards.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAqB,KAAK,GAAG,EAAE,MAAM,wBAAwB,CAAC;AASrE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,CA4B1D;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;CAChC;AAED,eAAO,MAAM,qBAAqB,EAAE,sBAAsB,CAAC,qBAAqB,CAwC/E,CAAC;AAEF,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE,SAAS,QAAQ,EAAE,CAAC;CACjC;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,CAoB7D;AAED,eAAO,MAAM,yBAAyB,EAAE,sBAAsB,CAAC,yBAAyB,CA+CvF,CAAC"}
+{"version":3,"file":"client-guards.d.ts","sourceRoot":"","sources":["../../../src/modules/firestore/client-guards.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAqB,KAAK,GAAG,EAAE,MAAM,wBAAwB,CAAC;AASrE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,CA4B1D;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;CAChC;AAED,eAAO,MAAM,qBAAqB,EAAE,sBAAsB,CAAC,qBAAqB,CAwC/E,CAAC;AAEF,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE,SAAS,QAAQ,EAAE,CAAC;CACjC;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,CAoB7D;AAED,eAAO,MAAM,yBAAyB,EAAE,sBAAsB,CAAC,yBAAyB,CA+CvF,CAAC;AAWF,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,SAAS,QAAQ,EAAE,CAAC;CACjC;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,CAwB9D;AAED,eAAO,MAAM,0BAA0B,EAAE,sBAAsB,CAAC,0BAA0B,CAoCzF,CAAC"}

package/dist/modules/firestore/client-guards.js

@@ -153,4 +153,73 @@ export const firestoreRuntimeInUiGuard = {
         ];
     },
 };
+const CLIENT_WRITES = new Set([
+    'setDoc',
+    'updateDoc',
+    'deleteDoc',
+    'addDoc',
+    'writeBatch',
+    'runTransaction',
+]);
+export function firestoreClientWriteHits(file) {
+    const source = file.sourceFile;
+    const hits = [];
+    const namespaces = new Set();
+    for (const site of moduleImports(source, ['import', 'export'])) {
+        if (!FIRESTORE_SDK.test(site.spec) || site.typeOnly)
+            continue;
+        if (site.namespace)
+            namespaces.add(site.namespace);
+        for (const name of site.named)
+            if (!name.typeOnly && CLIENT_WRITES.has(name.imported))
+                hits.push({
+                    index: site.node.getStart(source),
+                    detail: `${name.imported} from '${site.spec}'`,
+                });
+    }
+    forEachNode(source, (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            namespaces.has(node.expression.text) &&
+            CLIENT_WRITES.has(node.name.text))
+            hits.push({ index: node.getStart(source), detail: node.getText(source) });
+    });
+    return hits;
+}
+export const firestoreClientWritesGuard = {
+    id: 'firestoreClientWrites',
+    absentWhen: 'the app stores nothing in Firestore',
+    factProblems(facts) {
+        const problems = [];
+        reviewedProblems(facts?.sanctioned, 'sanctioned', problems);
+        return problems;
+    },
+    build(facts) {
+        return [
+            reviewedAllowlist({
+                title: 'the client never writes Firestore',
+                description: 'Every write goes through a callable that checks it on the server; a client SDK write skips that check and ' +
+                    'every rule the callable enforces. Flagged: a runtime import of a Firestore write function (' +
+                    `${[...CLIENT_WRITES].join(', ')}) from the Firestore SDK, or a call to one through a namespace import, in ` +
+                    "the app's client source. Fix: call the callable that owns the write. A sanctioned site is a reviewed entry " +
+                    'with its why; one that no longer writes is stale.',
+                scope: APP_SOURCE,
+                match: firestoreClientWriteHits,
+                allowlist: facts.sanctioned,
+                samples: {
+                    flags: [
+                        "import { doc, setDoc } from 'firebase/firestore';",
+                        "import { writeBatch as batchOf } from 'firebase/firestore';",
+                        "import * as fs from 'firebase/firestore';\nawait fs.updateDoc(ref, patch);",
+                    ],
+                    passes: [
+                        "import { doc, getDoc, onSnapshot } from 'firebase/firestore';",
+                        "import { type WriteBatch } from 'firebase/firestore';",
+                        'await callable({ id });',
+                    ],
+                },
+            }),
+        ];
+    },
+};
 //# sourceMappingURL=client-guards.js.map

package/dist/modules/firestore/client-guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-guards.js","sourceRoot":"","sources":["../../../src/modules/firestore/client-guards.ts"],"names":[],"mappings":"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","sourcesContent":["import ts from 'typescript';\nimport type { GenericGuardDefinition } from '../../node/suite/config.js';\nimport type { Scope } from '../../node/reader.js';\nimport type { Reviewed } from '../../node/layout.js';\nimport type { FileView } from '../../reader/view.js';\nimport { reviewedAllowlist, type Hit } from '../../shapes/shapes.js';\nimport { forEachNode } from '../../support/ast.js';\nimport { namesProblem, reviewedProblems } from '../../support/facts.js';\nimport { moduleImports } from '../../support/imports.js';\nimport { isUnder } from '../../support/text.js';\n\nconst FIRESTORE_SDK = /^firebase\\/firestore(?:\\/|$)/;\nconst APP_SOURCE: Scope = { roots: ['app'], kinds: ['code'], tests: false };\n\nexport function liveSubscriptionHits(file: FileView): Hit[] {\n  const source = file.sourceFile;\n  const snapshotNames = new Set(['onSnapshot']);\n  const namespaces = new Set<string>();\n  for (const site of moduleImports(source, ['import'])) {\n    if (!site.topLevel || !FIRESTORE_SDK.test(site.spec)) continue;\n    if (site.namespace) namespaces.add(site.namespace);\n    for (const name of site.named)\n      if (name.imported === 'onSnapshot') snapshotNames.add(name.local);\n  }\n  const hits: Hit[] = [];\n  const at = (node: ts.Node, detail: string) => hits.push({ index: node.getStart(source), detail });\n  forEachNode(source, (node) => {\n    if (ts.isPropertyAssignment(node) && ts.isObjectLiteralExpression(node.parent)) {\n      const key =\n        ts.isIdentifier(node.name) || ts.isStringLiteral(node.name) ? node.name.text : null;\n      if (key === 'subscribe' && node.initializer.kind !== ts.SyntaxKind.FalseKeyword)\n        at(node, `subscribe: ${node.initializer.getText(source)}`);\n    } else if (ts.isShorthandPropertyAssignment(node) && node.name.text === 'subscribe') {\n      at(node, '{ subscribe }');\n    } else if (ts.isCallExpression(node)) {\n      const callee = node.expression;\n      if (ts.isIdentifier(callee) && snapshotNames.has(callee.text)) at(node, `${callee.text}(…)`);\n      else if (ts.isPropertyAccessExpression(callee) && callee.name.text === 'onSnapshot')\n        at(node, `${callee.getText(source)}(…)`);\n    }\n  });\n  return hits;\n}\n\nexport interface LiveSubscriptionFacts {\n  allowlist: readonly Reviewed[];\n}\n\nexport const liveSubscriptionGuard: GenericGuardDefinition<LiveSubscriptionFacts> = {\n  id: 'firestoreLiveSubscriptions',\n  absentWhen: 'the app stores nothing in Firestore',\n  factProblems(facts) {\n    const problems: string[] = [];\n    reviewedProblems(facts?.allowlist, 'allowlist', problems);\n    return problems;\n  },\n  build(facts) {\n    return [\n      reviewedAllowlist({\n        title: 'every live Firestore subscription is on the reviewed list',\n        description:\n          'A live read bills a document read on every change for as long as it is mounted, so it is a reviewed exception: ' +\n          'a file that declares live mode — a subscribe option set to anything but a literal false, the { subscribe } ' +\n          \"shorthand, or an onSnapshot call under any name the file bound the Firestore SDK's to — is on the reviewed \" +\n          'list with why it needs real-time delivery. Fix: read once and keep it fresh through the cache, or add the ' +\n          'reviewed entry. An entry whose file no longer subscribes is stale.',\n        scope: APP_SOURCE,\n        match: liveSubscriptionHits,\n        allowlist: facts.allowlist,\n        samples: {\n          flags: [\n            'useFirestoreDoc({ docPath, queryKey, subscribe: true });',\n            'useBatchFirestoreDocs({ ids, subscribe: isLive });',\n            'useFirestoreCollection({ collectionPath, subscribe, enabled });',\n            \"import { doc, onSnapshot as listen } from 'firebase/firestore';\\nconst stop = listen(doc(db, p), render);\",\n            \"import * as fs from 'firebase/firestore';\\nconst stop = fs.onSnapshot(ref, handle);\",\n          ],\n          passes: [\n            \"useBatchFirestoreDocs({ db, collectionPath, ids, transport: 'get' });\",\n            'useFirestoreDoc({ docPath, queryKey, subscribe: false });',\n            'const unsubscribe = cache.subscribe((event) => handle(event));',\n            'return useSyncExternalStore(subscribe, readValue, getServerValue);',\n            '// subscribe: true is a reviewed exception\\nconst x = 1;',\n          ],\n        },\n      }),\n    ];\n  },\n};\n\nexport interface FirestoreRuntimeInUiFacts {\n  uiFolders: readonly string[];\n  sanctioned: readonly Reviewed[];\n}\n\nexport function firestoreRuntimeImports(file: FileView): Hit[] {\n  const source = file.sourceFile;\n  const hits: Hit[] = [];\n  for (const site of moduleImports(source, ['import', 'export', 'dynamic'])) {\n    if (!FIRESTORE_SDK.test(site.spec)) continue;\n    const at = site.node.getStart(source);\n    if (site.kind === 'import') {\n      const typeOnly =\n        !site.sideEffect &&\n        (site.typeOnly ||\n          (!site.defaultName &&\n            !site.namespace &&\n            site.named.length > 0 &&\n            site.named.every((n) => n.typeOnly)));\n      if (!typeOnly) hits.push({ index: at, detail: `import from '${site.spec}'` });\n    } else if (site.kind === 'export') {\n      if (!site.typeOnly) hits.push({ index: at, detail: `re-export from '${site.spec}'` });\n    } else hits.push({ index: at, detail: `import('${site.spec}')` });\n  }\n  return hits;\n}\n\nexport const firestoreRuntimeInUiGuard: GenericGuardDefinition<FirestoreRuntimeInUiFacts> = {\n  id: 'firestoreRuntimeInUi',\n  absentWhen: 'the app stores nothing in Firestore',\n  factProblems(facts) {\n    const problems: string[] = [];\n    namesProblem(facts?.uiFolders, 'uiFolders', problems);\n    reviewedProblems(facts?.sanctioned, 'sanctioned', problems);\n    return problems;\n  },\n  build(facts) {\n    const inUi = (path: string) => facts.uiFolders.some((folder) => isUnder(path, folder));\n    return [\n      reviewedAllowlist({\n        title: 'no component or route imports the Firestore runtime',\n        description:\n          'A component or route that reaches into Firestore bypasses the cache, the query keys, and every server check ' +\n          'at once. Flagged: a runtime import, re-export, or dynamic import of the Firestore SDK (a type-only import ' +\n          'passes) in the UI folders. Fix: read through a hook, write through a callable. A sanctioned root provider is ' +\n          'a reviewed entry with its why; one that no longer imports the runtime is stale.',\n        scope: APP_SOURCE,\n        match: (file) => (inUi(file.path) ? firestoreRuntimeImports(file) : []),\n        allowlist: facts.sanctioned,\n        samples: {\n          flags: [\n            {\n              path: `${facts.uiFolders[0]}/probe.tsx`,\n              text: \"import { doc, getDoc } from 'firebase/firestore';\",\n            },\n            {\n              path: `${facts.uiFolders[0]}/probe.tsx`,\n              text: 'import {\\n  updateDoc,\\n} from \"firebase/firestore\";',\n            },\n          ],\n          passes: [\n            {\n              path: `${facts.uiFolders[0]}/typed.tsx`,\n              text: \"import type { Timestamp } from 'firebase/firestore';\",\n            },\n            {\n              path: `${facts.uiFolders[0]}/typed.tsx`,\n              text: \"import { type Timestamp } from 'firebase/firestore';\",\n            },\n          ],\n        },\n      }),\n    ];\n  },\n};\n"]}
+{"version":3,"file":"client-guards.js","sourceRoot":"","sources":["../../../src/modules/firestore/client-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAK5B,OAAO,EAAE,iBAAiB,EAAY,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,MAAM,aAAa,GAAG,8BAA8B,CAAC;AACrD,MAAM,UAAU,GAAU,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAE5E,MAAM,UAAU,oBAAoB,CAAC,IAAc;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;IAC/B,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/D,IAAI,IAAI,CAAC,SAAS;YAAE,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACnD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAC3B,IAAI,IAAI,CAAC,QAAQ,KAAK,YAAY;gBAAE,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,IAAI,GAAU,EAAE,CAAC;IACvB,MAAM,EAAE,GAAG,CAAC,IAAa,EAAE,MAAc,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAClG,WAAW,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QAC3B,IAAI,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/E,MAAM,GAAG,GACP,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACtF,IAAI,GAAG,KAAK,WAAW,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,YAAY;gBAC7E,EAAE,CAAC,IAAI,EAAE,cAAc,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC/D,CAAC;aAAM,IAAI,EAAE,CAAC,6BAA6B,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACpF,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QAC5B,CAAC;aAAM,IAAI,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;YAC/B,IAAI,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;gBAAE,EAAE,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC;iBACxF,IAAI,EAAE,CAAC,0BAA0B,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,YAAY;gBACjF,EAAE,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAMD,MAAM,CAAC,MAAM,qBAAqB,GAAkD;IAClF,EAAE,EAAE,4BAA4B;IAChC,UAAU,EAAE,qCAAqC;IACjD,YAAY,CAAC,KAAK;QAChB,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC1D,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,KAAK,CAAC,KAAK;QACT,OAAO;YACL,iBAAiB,CAAC;gBAChB,KAAK,EAAE,2DAA2D;gBAClE,WAAW,EACT,iHAAiH;oBACjH,6GAA6G;oBAC7G,6GAA6G;oBAC7G,4GAA4G;oBAC5G,oEAAoE;gBACtE,KAAK,EAAE,UAAU;gBACjB,KAAK,EAAE,oBAAoB;gBAC3B,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,OAAO,EAAE;oBACP,KAAK,EAAE;wBACL,0DAA0D;wBAC1D,oDAAoD;wBACpD,iEAAiE;wBACjE,2GAA2G;wBAC3G,qFAAqF;qBACtF;oBACD,MAAM,EAAE;wBACN,uEAAuE;wBACvE,2DAA2D;wBAC3D,gEAAgE;wBAChE,oEAAoE;wBACpE,0DAA0D;qBAC3D;iBACF;aACF,CAAC;SACH,CAAC;IACJ,CAAC;CACF,CAAC;AAOF,MAAM,UAAU,uBAAuB,CAAC,IAAc;IACpD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;IAC/B,MAAM,IAAI,GAAU,EAAE,CAAC;IACvB,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;QAC1E,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAC7C,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,MAAM,QAAQ,GACZ,CAAC,IAAI,CAAC,UAAU;gBAChB,CAAC,IAAI,CAAC,QAAQ;oBACZ,CAAC,CAAC,IAAI,CAAC,WAAW;wBAChB,CAAC,IAAI,CAAC,SAAS;wBACf,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;wBACrB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC5C,IAAI,CAAC,QAAQ;gBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,gBAAgB,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;QAChF,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAClC,IAAI,CAAC,IAAI,CAAC,QAAQ;gBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,mBAAmB,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;QACxF,CAAC;;YAAM,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAsD;IAC1F,EAAE,EAAE,sBAAsB;IAC1B,UAAU,EAAE,qCAAqC;IACjD,YAAY,CAAC,KAAK;QAChB,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;QACtD,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;QAC5D,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACvF,OAAO;YACL,iBAAiB,CAAC;gBAChB,KAAK,EAAE,qDAAqD;gBAC5D,WAAW,EACT,8GAA8G;oBAC9G,4GAA4G;oBAC5G,+GAA+G;oBAC/G,iFAAiF;gBACnF,KAAK,EAAE,UAAU;gBACjB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvE,SAAS,EAAE,KAAK,CAAC,UAAU;gBAC3B,OAAO,EAAE;oBACP,KAAK,EAAE;wBACL;4BACE,IAAI,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY;4BACvC,IAAI,EAAE,mDAAmD;yBAC1D;wBACD;4BACE,IAAI,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY;4BACvC,IAAI,EAAE,sDAAsD;yBAC7D;qBACF;oBACD,MAAM,EAAE;wBACN;4BACE,IAAI,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY;4BACvC,IAAI,EAAE,sDAAsD;yBAC7D;wBACD;4BACE,IAAI,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY;4BACvC,IAAI,EAAE,sDAAsD;yBAC7D;qBACF;iBACF;aACF,CAAC;SACH,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,QAAQ;IACR,WAAW;IACX,WAAW;IACX,QAAQ;IACR,YAAY;IACZ,gBAAgB;CACjB,CAAC,CAAC;AAMH,MAAM,UAAU,wBAAwB,CAAC,IAAc;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;IAC/B,MAAM,IAAI,GAAU,EAAE,CAAC;IACvB,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;QAC/D,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ;YAAE,SAAS;QAC9D,IAAI,IAAI,CAAC,SAAS;YAAE,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACnD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;gBACpD,IAAI,CAAC,IAAI,CAAC;oBACR,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;oBACjC,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,UAAU,IAAI,CAAC,IAAI,GAAG;iBAC/C,CAAC,CAAC;IACT,CAAC;IACD,WAAW,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QAC3B,IACE,EAAE,CAAC,0BAA0B,CAAC,IAAI,CAAC;YACnC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC;YAChC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YACpC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAEjC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAuD;IAC5F,EAAE,EAAE,uBAAuB;IAC3B,UAAU,EAAE,qCAAqC;IACjD,YAAY,CAAC,KAAK;QAChB,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;QAC5D,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,KAAK,CAAC,KAAK;QACT,OAAO;YACL,iBAAiB,CAAC;gBAChB,KAAK,EAAE,mCAAmC;gBAC1C,WAAW,EACT,4GAA4G;oBAC5G,6FAA6F;oBAC7F,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,4EAA4E;oBAC5G,6GAA6G;oBAC7G,mDAAmD;gBACrD,KAAK,EAAE,UAAU;gBACjB,KAAK,EAAE,wBAAwB;gBAC/B,SAAS,EAAE,KAAK,CAAC,UAAU;gBAC3B,OAAO,EAAE;oBACP,KAAK,EAAE;wBACL,mDAAmD;wBACnD,6DAA6D;wBAC7D,4EAA4E;qBAC7E;oBACD,MAAM,EAAE;wBACN,+DAA+D;wBAC/D,uDAAuD;wBACvD,yBAAyB;qBAC1B;iBACF;aACF,CAAC;SACH,CAAC;IACJ,CAAC;CACF,CAAC","sourcesContent":["import ts from 'typescript';\nimport type { GenericGuardDefinition } from '../../node/suite/config.js';\nimport type { Scope } from '../../node/reader.js';\nimport type { Reviewed } from '../../node/layout.js';\nimport type { FileView } from '../../reader/view.js';\nimport { reviewedAllowlist, type Hit } from '../../shapes/shapes.js';\nimport { forEachNode } from '../../support/ast.js';\nimport { namesProblem, reviewedProblems } from '../../support/facts.js';\nimport { moduleImports } from '../../support/imports.js';\nimport { isUnder } from '../../support/text.js';\n\nconst FIRESTORE_SDK = /^firebase\\/firestore(?:\\/|$)/;\nconst APP_SOURCE: Scope = { roots: ['app'], kinds: ['code'], tests: false };\n\nexport function liveSubscriptionHits(file: FileView): Hit[] {\n  const source = file.sourceFile;\n  const snapshotNames = new Set(['onSnapshot']);\n  const namespaces = new Set<string>();\n  for (const site of moduleImports(source, ['import'])) {\n    if (!site.topLevel || !FIRESTORE_SDK.test(site.spec)) continue;\n    if (site.namespace) namespaces.add(site.namespace);\n    for (const name of site.named)\n      if (name.imported === 'onSnapshot') snapshotNames.add(name.local);\n  }\n  const hits: Hit[] = [];\n  const at = (node: ts.Node, detail: string) => hits.push({ index: node.getStart(source), detail });\n  forEachNode(source, (node) => {\n    if (ts.isPropertyAssignment(node) && ts.isObjectLiteralExpression(node.parent)) {\n      const key =\n        ts.isIdentifier(node.name) || ts.isStringLiteral(node.name) ? node.name.text : null;\n      if (key === 'subscribe' && node.initializer.kind !== ts.SyntaxKind.FalseKeyword)\n        at(node, `subscribe: ${node.initializer.getText(source)}`);\n    } else if (ts.isShorthandPropertyAssignment(node) && node.name.text === 'subscribe') {\n      at(node, '{ subscribe }');\n    } else if (ts.isCallExpression(node)) {\n      const callee = node.expression;\n      if (ts.isIdentifier(callee) && snapshotNames.has(callee.text)) at(node, `${callee.text}(…)`);\n      else if (ts.isPropertyAccessExpression(callee) && callee.name.text === 'onSnapshot')\n        at(node, `${callee.getText(source)}(…)`);\n    }\n  });\n  return hits;\n}\n\nexport interface LiveSubscriptionFacts {\n  allowlist: readonly Reviewed[];\n}\n\nexport const liveSubscriptionGuard: GenericGuardDefinition<LiveSubscriptionFacts> = {\n  id: 'firestoreLiveSubscriptions',\n  absentWhen: 'the app stores nothing in Firestore',\n  factProblems(facts) {\n    const problems: string[] = [];\n    reviewedProblems(facts?.allowlist, 'allowlist', problems);\n    return problems;\n  },\n  build(facts) {\n    return [\n      reviewedAllowlist({\n        title: 'every live Firestore subscription is on the reviewed list',\n        description:\n          'A live read bills a document read on every change for as long as it is mounted, so it is a reviewed exception: ' +\n          'a file that declares live mode — a subscribe option set to anything but a literal false, the { subscribe } ' +\n          \"shorthand, or an onSnapshot call under any name the file bound the Firestore SDK's to — is on the reviewed \" +\n          'list with why it needs real-time delivery. Fix: read once and keep it fresh through the cache, or add the ' +\n          'reviewed entry. An entry whose file no longer subscribes is stale.',\n        scope: APP_SOURCE,\n        match: liveSubscriptionHits,\n        allowlist: facts.allowlist,\n        samples: {\n          flags: [\n            'useFirestoreDoc({ docPath, queryKey, subscribe: true });',\n            'useBatchFirestoreDocs({ ids, subscribe: isLive });',\n            'useFirestoreCollection({ collectionPath, subscribe, enabled });',\n            \"import { doc, onSnapshot as listen } from 'firebase/firestore';\\nconst stop = listen(doc(db, p), render);\",\n            \"import * as fs from 'firebase/firestore';\\nconst stop = fs.onSnapshot(ref, handle);\",\n          ],\n          passes: [\n            \"useBatchFirestoreDocs({ db, collectionPath, ids, transport: 'get' });\",\n            'useFirestoreDoc({ docPath, queryKey, subscribe: false });',\n            'const unsubscribe = cache.subscribe((event) => handle(event));',\n            'return useSyncExternalStore(subscribe, readValue, getServerValue);',\n            '// subscribe: true is a reviewed exception\\nconst x = 1;',\n          ],\n        },\n      }),\n    ];\n  },\n};\n\nexport interface FirestoreRuntimeInUiFacts {\n  uiFolders: readonly string[];\n  sanctioned: readonly Reviewed[];\n}\n\nexport function firestoreRuntimeImports(file: FileView): Hit[] {\n  const source = file.sourceFile;\n  const hits: Hit[] = [];\n  for (const site of moduleImports(source, ['import', 'export', 'dynamic'])) {\n    if (!FIRESTORE_SDK.test(site.spec)) continue;\n    const at = site.node.getStart(source);\n    if (site.kind === 'import') {\n      const typeOnly =\n        !site.sideEffect &&\n        (site.typeOnly ||\n          (!site.defaultName &&\n            !site.namespace &&\n            site.named.length > 0 &&\n            site.named.every((n) => n.typeOnly)));\n      if (!typeOnly) hits.push({ index: at, detail: `import from '${site.spec}'` });\n    } else if (site.kind === 'export') {\n      if (!site.typeOnly) hits.push({ index: at, detail: `re-export from '${site.spec}'` });\n    } else hits.push({ index: at, detail: `import('${site.spec}')` });\n  }\n  return hits;\n}\n\nexport const firestoreRuntimeInUiGuard: GenericGuardDefinition<FirestoreRuntimeInUiFacts> = {\n  id: 'firestoreRuntimeInUi',\n  absentWhen: 'the app stores nothing in Firestore',\n  factProblems(facts) {\n    const problems: string[] = [];\n    namesProblem(facts?.uiFolders, 'uiFolders', problems);\n    reviewedProblems(facts?.sanctioned, 'sanctioned', problems);\n    return problems;\n  },\n  build(facts) {\n    const inUi = (path: string) => facts.uiFolders.some((folder) => isUnder(path, folder));\n    return [\n      reviewedAllowlist({\n        title: 'no component or route imports the Firestore runtime',\n        description:\n          'A component or route that reaches into Firestore bypasses the cache, the query keys, and every server check ' +\n          'at once. Flagged: a runtime import, re-export, or dynamic import of the Firestore SDK (a type-only import ' +\n          'passes) in the UI folders. Fix: read through a hook, write through a callable. A sanctioned root provider is ' +\n          'a reviewed entry with its why; one that no longer imports the runtime is stale.',\n        scope: APP_SOURCE,\n        match: (file) => (inUi(file.path) ? firestoreRuntimeImports(file) : []),\n        allowlist: facts.sanctioned,\n        samples: {\n          flags: [\n            {\n              path: `${facts.uiFolders[0]}/probe.tsx`,\n              text: \"import { doc, getDoc } from 'firebase/firestore';\",\n            },\n            {\n              path: `${facts.uiFolders[0]}/probe.tsx`,\n              text: 'import {\\n  updateDoc,\\n} from \"firebase/firestore\";',\n            },\n          ],\n          passes: [\n            {\n              path: `${facts.uiFolders[0]}/typed.tsx`,\n              text: \"import type { Timestamp } from 'firebase/firestore';\",\n            },\n            {\n              path: `${facts.uiFolders[0]}/typed.tsx`,\n              text: \"import { type Timestamp } from 'firebase/firestore';\",\n            },\n          ],\n        },\n      }),\n    ];\n  },\n};\n\nconst CLIENT_WRITES = new Set([\n  'setDoc',\n  'updateDoc',\n  'deleteDoc',\n  'addDoc',\n  'writeBatch',\n  'runTransaction',\n]);\n\nexport interface FirestoreClientWritesFacts {\n  sanctioned: readonly Reviewed[];\n}\n\nexport function firestoreClientWriteHits(file: FileView): Hit[] {\n  const source = file.sourceFile;\n  const hits: Hit[] = [];\n  const namespaces = new Set<string>();\n  for (const site of moduleImports(source, ['import', 'export'])) {\n    if (!FIRESTORE_SDK.test(site.spec) || site.typeOnly) continue;\n    if (site.namespace) namespaces.add(site.namespace);\n    for (const name of site.named)\n      if (!name.typeOnly && CLIENT_WRITES.has(name.imported))\n        hits.push({\n          index: site.node.getStart(source),\n          detail: `${name.imported} from '${site.spec}'`,\n        });\n  }\n  forEachNode(source, (node) => {\n    if (\n      ts.isPropertyAccessExpression(node) &&\n      ts.isIdentifier(node.expression) &&\n      namespaces.has(node.expression.text) &&\n      CLIENT_WRITES.has(node.name.text)\n    )\n      hits.push({ index: node.getStart(source), detail: node.getText(source) });\n  });\n  return hits;\n}\n\nexport const firestoreClientWritesGuard: GenericGuardDefinition<FirestoreClientWritesFacts> = {\n  id: 'firestoreClientWrites',\n  absentWhen: 'the app stores nothing in Firestore',\n  factProblems(facts) {\n    const problems: string[] = [];\n    reviewedProblems(facts?.sanctioned, 'sanctioned', problems);\n    return problems;\n  },\n  build(facts) {\n    return [\n      reviewedAllowlist({\n        title: 'the client never writes Firestore',\n        description:\n          'Every write goes through a callable that checks it on the server; a client SDK write skips that check and ' +\n          'every rule the callable enforces. Flagged: a runtime import of a Firestore write function (' +\n          `${[...CLIENT_WRITES].join(', ')}) from the Firestore SDK, or a call to one through a namespace import, in ` +\n          \"the app's client source. Fix: call the callable that owns the write. A sanctioned site is a reviewed entry \" +\n          'with its why; one that no longer writes is stale.',\n        scope: APP_SOURCE,\n        match: firestoreClientWriteHits,\n        allowlist: facts.sanctioned,\n        samples: {\n          flags: [\n            \"import { doc, setDoc } from 'firebase/firestore';\",\n            \"import { writeBatch as batchOf } from 'firebase/firestore';\",\n            \"import * as fs from 'firebase/firestore';\\nawait fs.updateDoc(ref, patch);\",\n          ],\n          passes: [\n            \"import { doc, getDoc, onSnapshot } from 'firebase/firestore';\",\n            \"import { type WriteBatch } from 'firebase/firestore';\",\n            'await callable({ id });',\n          ],\n        },\n      }),\n    ];\n  },\n};\n"]}

package/dist/modules/firestore/guards.d.ts

@@ -1,5 +1,5 @@
 import type { Absent, GenericGuardDefinition } from '../../node/suite/config.js';
-import { type FirestoreRuntimeInUiFacts, type LiveSubscriptionFacts } from './client-guards.js';
+import { type FirestoreClientWritesFacts, type FirestoreRuntimeInUiFacts, type LiveSubscriptionFacts } from './client-guards.js';
 import { type TestPathFacts, type WriteGuardFacts } from './guard.js';
 import { type CollectionGroupIndexFacts } from './index-guard.js';
 import { type PathAssemblyFacts, type RetiredSegmentFacts } from './path-guards.js';
@@ -21,6 +21,7 @@ export type FirestoreGuardFacts = {
     firestoreCounterDecrements: NoFacts | Absent;
     firestoreLiveSubscriptions: LiveSubscriptionFacts | Absent;
     firestoreRuntimeInUi: FirestoreRuntimeInUiFacts | Absent;
+    firestoreClientWrites: FirestoreClientWritesFacts | Absent;
     firestoreRandomUuidSites: RandomUuidFacts | Absent;
     firestoreTimestampNow: NoFacts | Absent;
     rulesClaimNames: RulesClaimFacts;

package/dist/modules/firestore/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/modules/firestore/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAA6B,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACjG,OAAO,EAA6B,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,MAAM,mBAAmB,GAAG;IAChC,eAAe,EAAE,eAAe,GAAG,MAAM,CAAC;IAC1C,kBAAkB,EAAE,aAAa,GAAG,MAAM,CAAC;IAC3C,wBAAwB,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3C,qBAAqB,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAClD,wBAAwB,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACvD,+BAA+B,EAAE,yBAAyB,GAAG,MAAM,CAAC;IACpE,oBAAoB,EAAE,wBAAwB,GAAG,MAAM,CAAC;IACxD,qBAAqB,EAAE,0BAA0B,GAAG,MAAM,CAAC;IAC3D,yBAAyB,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5C,0BAA0B,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7C,0BAA0B,EAAE,qBAAqB,GAAG,MAAM,CAAC;IAC3D,oBAAoB,EAAE,yBAAyB,GAAG,MAAM,CAAC;IACzD,wBAAwB,EAAE,eAAe,GAAG,MAAM,CAAC;IACnD,qBAAqB,EAAE,OAAO,GAAG,MAAM,CAAC;IACxC,eAAe,EAAE,eAAe,CAAC;IACjC,eAAe,EAAE,gBAAgB,CAAC;CACnC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAiBxB,CAAC"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/modules/firestore/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAIL,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAA6B,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACjG,OAAO,EAA6B,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,MAAM,mBAAmB,GAAG;IAChC,eAAe,EAAE,eAAe,GAAG,MAAM,CAAC;IAC1C,kBAAkB,EAAE,aAAa,GAAG,MAAM,CAAC;IAC3C,wBAAwB,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3C,qBAAqB,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAClD,wBAAwB,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACvD,+BAA+B,EAAE,yBAAyB,GAAG,MAAM,CAAC;IACpE,oBAAoB,EAAE,wBAAwB,GAAG,MAAM,CAAC;IACxD,qBAAqB,EAAE,0BAA0B,GAAG,MAAM,CAAC;IAC3D,yBAAyB,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5C,0BAA0B,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7C,0BAA0B,EAAE,qBAAqB,GAAG,MAAM,CAAC;IAC3D,oBAAoB,EAAE,yBAAyB,GAAG,MAAM,CAAC;IACzD,qBAAqB,EAAE,0BAA0B,GAAG,MAAM,CAAC;IAC3D,wBAAwB,EAAE,eAAe,GAAG,MAAM,CAAC;IACnD,qBAAqB,EAAE,OAAO,GAAG,MAAM,CAAC;IACxC,eAAe,EAAE,eAAe,CAAC;IACjC,eAAe,EAAE,gBAAgB,CAAC;CACnC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAkBxB,CAAC"}

package/dist/modules/firestore/guards.js

@@ -1,4 +1,4 @@
-import { firestoreRuntimeInUiGuard, liveSubscriptionGuard, } from './client-guards.js';
+import { firestoreClientWritesGuard, firestoreRuntimeInUiGuard, liveSubscriptionGuard, } from './client-guards.js';
 import { testPathGuard, writeGuard } from './guard.js';
 import { collectionGroupIndexGuard } from './index-guard.js';
 import { literalSegmentGuard, pathAssemblyGuard, retiredSegmentGuard, } from './path-guards.js';
@@ -19,6 +19,7 @@ export const FIRESTORE_GUARDS = Object.freeze([
     counterDecrementGuard,
     liveSubscriptionGuard,
     firestoreRuntimeInUiGuard,
+    firestoreClientWritesGuard,
     randomUuidGuard,
     timestampNowGuard,
     rulesClaimGuard,

package/dist/modules/firestore/guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../../src/modules/firestore/guards.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,qBAAqB,GAGtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,UAAU,EAA4C,MAAM,YAAY,CAAC;AACjG,OAAO,EAAE,yBAAyB,EAAkC,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAwB,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAyB,MAAM,yBAAyB,CAAC;AAClF,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GAErB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,GAGzB,MAAM,qBAAqB,CAAC;AAsB7B,MAAM,CAAC,MAAM,gBAAgB,GAAiD,MAAM,CAAC,MAAM,CAAC;IAC1F,UAAU;IACV,aAAa;IACb,mBAAmB;IACnB,iBAAiB;IACjB,mBAAmB;IACnB,yBAAyB;IACzB,wBAAwB;IACxB,0BAA0B;IAC1B,oBAAoB;IACpB,qBAAqB;IACrB,qBAAqB;IACrB,yBAAyB;IACzB,eAAe;IACf,iBAAiB;IACjB,eAAe;IACf,gBAAgB;CAC+B,CAAC,CAAC","sourcesContent":["import type { Absent, GenericGuardDefinition } from '../../node/suite/config.js';\nimport {\n  firestoreRuntimeInUiGuard,\n  liveSubscriptionGuard,\n  type FirestoreRuntimeInUiFacts,\n  type LiveSubscriptionFacts,\n} from './client-guards.js';\nimport { testPathGuard, writeGuard, type TestPathFacts, type WriteGuardFacts } from './guard.js';\nimport { collectionGroupIndexGuard, type CollectionGroupIndexFacts } from './index-guard.js';\nimport {\n  literalSegmentGuard,\n  pathAssemblyGuard,\n  retiredSegmentGuard,\n  type PathAssemblyFacts,\n  type RetiredSegmentFacts,\n} from './path-guards.js';\nimport { rulesClaimGuard, type RulesClaimFacts } from './rules-claim-guard.js';\nimport { rulesMirrorGuard, type RulesMirrorFacts } from './rules-mirror-guard.js';\nimport {\n  counterDecrementGuard,\n  randomUuidGuard,\n  timestampNowGuard,\n  transactionReadGuard,\n  type RandomUuidFacts,\n} from './server-guards.js';\nimport {\n  storageObjectMetadataGuard,\n  storageUploadOriginGuard,\n  type StorageObjectMetadataFacts,\n  type StorageUploadOriginFacts,\n} from './storage-guards.js';\nimport type { NoFacts } from './support.js';\n\nexport type FirestoreGuardFacts = {\n  firestoreWrites: WriteGuardFacts | Absent;\n  firestoreTestPaths: TestPathFacts | Absent;\n  firestoreLiteralSegments: NoFacts | Absent;\n  firestorePathAssembly: PathAssemblyFacts | Absent;\n  firestoreRetiredSegments: RetiredSegmentFacts | Absent;\n  firestoreCollectionGroupIndexes: CollectionGroupIndexFacts | Absent;\n  storageUploadOrigins: StorageUploadOriginFacts | Absent;\n  storageObjectMetadata: StorageObjectMetadataFacts | Absent;\n  firestoreTransactionReads: NoFacts | Absent;\n  firestoreCounterDecrements: NoFacts | Absent;\n  firestoreLiveSubscriptions: LiveSubscriptionFacts | Absent;\n  firestoreRuntimeInUi: FirestoreRuntimeInUiFacts | Absent;\n  firestoreRandomUuidSites: RandomUuidFacts | Absent;\n  firestoreTimestampNow: NoFacts | Absent;\n  rulesClaimNames: RulesClaimFacts;\n  rulesMirrorCore: RulesMirrorFacts;\n};\n\nexport const FIRESTORE_GUARDS: ReadonlyArray<GenericGuardDefinition<never>> = Object.freeze([\n  writeGuard,\n  testPathGuard,\n  literalSegmentGuard,\n  pathAssemblyGuard,\n  retiredSegmentGuard,\n  collectionGroupIndexGuard,\n  storageUploadOriginGuard,\n  storageObjectMetadataGuard,\n  transactionReadGuard,\n  counterDecrementGuard,\n  liveSubscriptionGuard,\n  firestoreRuntimeInUiGuard,\n  randomUuidGuard,\n  timestampNowGuard,\n  rulesClaimGuard,\n  rulesMirrorGuard,\n] as ReadonlyArray<GenericGuardDefinition<never>>);\n"]}
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../../src/modules/firestore/guards.ts"],"names":[],"mappings":"AACA,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,qBAAqB,GAItB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,UAAU,EAA4C,MAAM,YAAY,CAAC;AACjG,OAAO,EAAE,yBAAyB,EAAkC,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAwB,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAyB,MAAM,yBAAyB,CAAC;AAClF,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GAErB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,GAGzB,MAAM,qBAAqB,CAAC;AAuB7B,MAAM,CAAC,MAAM,gBAAgB,GAAiD,MAAM,CAAC,MAAM,CAAC;IAC1F,UAAU;IACV,aAAa;IACb,mBAAmB;IACnB,iBAAiB;IACjB,mBAAmB;IACnB,yBAAyB;IACzB,wBAAwB;IACxB,0BAA0B;IAC1B,oBAAoB;IACpB,qBAAqB;IACrB,qBAAqB;IACrB,yBAAyB;IACzB,0BAA0B;IAC1B,eAAe;IACf,iBAAiB;IACjB,eAAe;IACf,gBAAgB;CAC+B,CAAC,CAAC","sourcesContent":["import type { Absent, GenericGuardDefinition } from '../../node/suite/config.js';\nimport {\n  firestoreClientWritesGuard,\n  firestoreRuntimeInUiGuard,\n  liveSubscriptionGuard,\n  type FirestoreClientWritesFacts,\n  type FirestoreRuntimeInUiFacts,\n  type LiveSubscriptionFacts,\n} from './client-guards.js';\nimport { testPathGuard, writeGuard, type TestPathFacts, type WriteGuardFacts } from './guard.js';\nimport { collectionGroupIndexGuard, type CollectionGroupIndexFacts } from './index-guard.js';\nimport {\n  literalSegmentGuard,\n  pathAssemblyGuard,\n  retiredSegmentGuard,\n  type PathAssemblyFacts,\n  type RetiredSegmentFacts,\n} from './path-guards.js';\nimport { rulesClaimGuard, type RulesClaimFacts } from './rules-claim-guard.js';\nimport { rulesMirrorGuard, type RulesMirrorFacts } from './rules-mirror-guard.js';\nimport {\n  counterDecrementGuard,\n  randomUuidGuard,\n  timestampNowGuard,\n  transactionReadGuard,\n  type RandomUuidFacts,\n} from './server-guards.js';\nimport {\n  storageObjectMetadataGuard,\n  storageUploadOriginGuard,\n  type StorageObjectMetadataFacts,\n  type StorageUploadOriginFacts,\n} from './storage-guards.js';\nimport type { NoFacts } from './support.js';\n\nexport type FirestoreGuardFacts = {\n  firestoreWrites: WriteGuardFacts | Absent;\n  firestoreTestPaths: TestPathFacts | Absent;\n  firestoreLiteralSegments: NoFacts | Absent;\n  firestorePathAssembly: PathAssemblyFacts | Absent;\n  firestoreRetiredSegments: RetiredSegmentFacts | Absent;\n  firestoreCollectionGroupIndexes: CollectionGroupIndexFacts | Absent;\n  storageUploadOrigins: StorageUploadOriginFacts | Absent;\n  storageObjectMetadata: StorageObjectMetadataFacts | Absent;\n  firestoreTransactionReads: NoFacts | Absent;\n  firestoreCounterDecrements: NoFacts | Absent;\n  firestoreLiveSubscriptions: LiveSubscriptionFacts | Absent;\n  firestoreRuntimeInUi: FirestoreRuntimeInUiFacts | Absent;\n  firestoreClientWrites: FirestoreClientWritesFacts | Absent;\n  firestoreRandomUuidSites: RandomUuidFacts | Absent;\n  firestoreTimestampNow: NoFacts | Absent;\n  rulesClaimNames: RulesClaimFacts;\n  rulesMirrorCore: RulesMirrorFacts;\n};\n\nexport const FIRESTORE_GUARDS: ReadonlyArray<GenericGuardDefinition<never>> = Object.freeze([\n  writeGuard,\n  testPathGuard,\n  literalSegmentGuard,\n  pathAssemblyGuard,\n  retiredSegmentGuard,\n  collectionGroupIndexGuard,\n  storageUploadOriginGuard,\n  storageObjectMetadataGuard,\n  transactionReadGuard,\n  counterDecrementGuard,\n  liveSubscriptionGuard,\n  firestoreRuntimeInUiGuard,\n  firestoreClientWritesGuard,\n  randomUuidGuard,\n  timestampNowGuard,\n  rulesClaimGuard,\n  rulesMirrorGuard,\n] as ReadonlyArray<GenericGuardDefinition<never>>);\n"]}

package/dist/modules/frontend-actions/client.d.ts

@@ -47,12 +47,11 @@ export interface PartialMockFacts {
         module: string;
         why: string;
     }>;
+    passThroughHelpers: ReadonlyArray<{
+        owner: string;
+        names: readonly string[];
+    }>;
     sharedFakes?: Pick<SharedFakeFacts, 'importAliases' | 'fakes'>;
 }
-export declare function moduleMockCalls(code: string, module: string): Array<{
-    call: string;
-    index: number;
-}>;
-export declare function spreadsImportOriginal(call: string): boolean;
 export declare const partialMockGuard: GenericGuardDefinition<PartialMockFacts>;
 //# sourceMappingURL=client.d.ts.map

package/dist/modules/frontend-actions/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/modules/frontend-actions/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,GAAG,EACT,MAAM,wBAAwB,CAAC;AAwBhC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,SAAS,QAAQ,EAAE,CAAC;CAClC;AAED,eAAO,MAAM,oBAAoB,EAAE,sBAAsB,CAAC,oBAAoB,CAuD7E,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CACtC;AAED,eAAO,MAAM,mBAAmB,EAAE,sBAAsB,CAAC,mBAAmB,CAkC3E,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,mBAAmB,EAAE,sBAAsB,CAAC,mBAAmB,CAqC3E,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAA;KAAE,CAAC,CAAC;IAChG,iBAAiB,EAAE,SAAS,cAAc,EAAE,CAAC;CAC9C;AAKD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,GAChD,GAAG,EAAE,CAeP;AAED,eAAO,MAAM,kBAAkB,EAAE,sBAAsB,CAAC,kBAAkB,CAgFzE,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAKpD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,CA0B/D;AAED,eAAO,MAAM,eAAe,EAAE,sBAAsB,CAAC,eAAe,CAiCnE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,oBAAoB,EAAE,sBAAsB,CAAC,oBAAoB,CAsC7E,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,gBAAgB,EAAE,sBAAsB,CAAC,gBAAgB,CAoCrE,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,WAAW,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC;CAChE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAcxC;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI3D;AA2CD,eAAO,MAAM,gBAAgB,EAAE,sBAAsB,CAAC,gBAAgB,CA+ErE,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/modules/frontend-actions/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,GAAG,EACT,MAAM,wBAAwB,CAAC;AAkChC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,SAAS,QAAQ,EAAE,CAAC;CAClC;AAED,eAAO,MAAM,oBAAoB,EAAE,sBAAsB,CAAC,oBAAoB,CAuD7E,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CACtC;AAED,eAAO,MAAM,mBAAmB,EAAE,sBAAsB,CAAC,mBAAmB,CAkC3E,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,mBAAmB,EAAE,sBAAsB,CAAC,mBAAmB,CAqC3E,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAA;KAAE,CAAC,CAAC;IAChG,iBAAiB,EAAE,SAAS,cAAc,EAAE,CAAC;CAC9C;AAKD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,GAChD,GAAG,EAAE,CAeP;AAED,eAAO,MAAM,kBAAkB,EAAE,sBAAsB,CAAC,kBAAkB,CAgFzE,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAKpD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,CA0B/D;AAED,eAAO,MAAM,eAAe,EAAE,sBAAsB,CAAC,eAAe,CAiCnE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,oBAAoB,EAAE,sBAAsB,CAAC,oBAAoB,CAsC7E,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,gBAAgB,EAAE,sBAAsB,CAAC,gBAAgB,CAoCrE,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,kBAAkB,EAAE,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC/E,WAAW,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC;CAChE;AAoFD,eAAO,MAAM,gBAAgB,EAAE,sBAAsB,CAAC,gBAAgB,CA0GrE,CAAC"}

package/dist/modules/frontend-actions/client.js

@@ -1,9 +1,10 @@
 import ts from 'typescript';
 import { matchPattern, ownerOnly, reviewedAllowlist, } from '../../shapes/shapes.js';
-import { allowlistProblems, importAliasesProblem, namesProblem, reviewedProblems, textProblem, isList, } from '../../support/facts.js';
+import { allowlistProblems, importAliasesProblem, namesProblem, reviewedProblems, pathProblem, textProblem, isList, } from '../../support/facts.js';
 import { fromStatements, namesModule } from '../../support/imports.js';
 import { escapeRegExp, isUnder } from '../../support/text.js';
-import { isPlainString } from '../../support/ast.js';
+import { isPlainString, lineOfNode, unwrap } from '../../support/ast.js';
+import { awaited, bindingsOf, calledExport, factoryFunction, parameterName, returnedExpressions, } from '../../support/mock-factories.js';
 import { aliasList, resolveSpecifier } from '../../support/resolve-specifier.js';
 const APP_CODE = { roots: ['app'], kinds: ['code'], tests: false };
 const dottedPattern = (spelling) => spelling
@@ -366,28 +367,13 @@ export const dateOfBirthGuard = {
         ];
     },
 };
-export function moduleMockCalls(code, module) {
-    const opener = new RegExp(`vi\\.(?:mock|doMock)\\(\\s*(['"\`])${escapeRegExp(module)}\\1`, 'g');
-    const calls = [];
-    for (let m = opener.exec(code); m; m = opener.exec(code)) {
-        const open = code.indexOf('(', m.index);
-        let depth = 0;
-        let end = open;
-        for (; end < code.length; end++) {
-            if (code[end] === '(')
-                depth++;
-            else if (code[end] === ')' && --depth === 0)
-                break;
-        }
-        calls.push({ call: code.slice(m.index, end + 1), index: m.index });
-    }
-    return calls;
-}
-export function spreadsImportOriginal(call) {
-    if (/\.\.\.\s*\(\s*await\s+importOriginal\b/.test(call))
+const MOCK_CALLS = new Set(['vi.mock', 'vi.doMock']);
+function spreadsImportOriginal(code, original = 'importOriginal') {
+    const name = escapeRegExp(original);
+    if (new RegExp(`\\.\\.\\.\\s*\\(\\s*await\\s+${name}\\b`).test(code))
         return true;
-    const binding = /const\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+importOriginal\b/.exec(call);
-    return binding !== null && new RegExp(`\\.\\.\\.\\s*${escapeRegExp(binding[1])}\\b`).test(call);
+    const binding = new RegExp(`const\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*await\\s+${name}\\b`).exec(code);
+    return binding !== null && new RegExp(`\\.\\.\\.\\s*${escapeRegExp(binding[1])}\\b`).test(code);
 }
 function factoryLoads(call) {
     const loads = [];
@@ -407,20 +393,24 @@ function functionText(file, name) {
     }
     return null;
 }
-function ownerKeepsRealExports(context, owner, aliases) {
+function ownerKeepsRealExports(context, owner, aliases, passesThrough) {
     if (!context.reader.exists(owner))
         return false;
     const file = context.file(owner);
     if (spreadsImportOriginal(file.code))
         return true;
+    const calls = (local) => new RegExp(`\\b${escapeRegExp(local)}\\s*[<(]`).test(file.code);
     for (const site of file.imports) {
         if (site.typeOnly)
             continue;
         const target = resolveSpecifier(context.reader, owner, site.spec, aliases);
+        for (const name of site.named)
+            if (!name.typeOnly && passesThrough(target, name.imported) && calls(name.local))
+                return true;
         if (target === site.spec || !context.reader.exists(target))
             continue;
         for (const name of site.named) {
-            if (name.typeOnly || !new RegExp(`\\b${escapeRegExp(name.local)}\\s*[<(]`).test(file.code))
+            if (name.typeOnly || !calls(name.local))
                 continue;
             const helper = functionText(context.file(target), name.imported);
             if (helper !== null && spreadsImportOriginal(helper))
@@ -429,6 +419,25 @@ function ownerKeepsRealExports(context, owner, aliases) {
     }
     return false;
 }
+function returnsThroughPassThrough(fn, resolve, passesThrough) {
+    const original = parameterName(fn);
+    const bindings = bindingsOf(fn, resolve);
+    const returns = returnedExpressions(fn);
+    return (returns.length > 0 &&
+        returns.every((returned) => {
+            const call = returned ? awaited(returned) : null;
+            if (!call || !ts.isCallExpression(call))
+                return false;
+            const target = calledExport(call, bindings, resolve);
+            const [first] = call.arguments;
+            const passed = first ? unwrap(first) : null;
+            return (target !== null &&
+                passesThrough(target.path, target.name) &&
+                passed !== null &&
+                ts.isIdentifier(passed) &&
+                passed.text === original);
+        }));
+}
 export const partialMockGuard = {
     id: 'partialMocks',
     absentWhen: false,
@@ -440,6 +449,13 @@ export const partialMockGuard = {
             textProblem(r?.module, 'a package root', problems);
             textProblem(r?.why, `package root ${String(r?.module)}'s why`, problems);
         }
+        if (!isList(facts.passThroughHelpers))
+            problems.push('passThroughHelpers is missing (declare [] when there is none)');
+        else
+            for (const helper of facts.passThroughHelpers) {
+                pathProblem(helper?.owner, "a passThroughHelpers entry's owner", problems);
+                namesProblem(helper?.names, `passThroughHelpers entry ${String(helper?.owner)}'s names`, problems);
+            }
         if (facts.sharedFakes !== undefined) {
             importAliasesProblem(facts.sharedFakes?.importAliases, 'sharedFakes.importAliases', problems);
             if (!isList(facts.sharedFakes?.fakes))
@@ -451,15 +467,20 @@ export const partialMockGuard = {
         return [
             {
                 title: "a mock of a listed package root keeps the root's real exports",
-                description: 'A `vi.mock` of a listed package root spreads the real module: ' +
-                    "`vi.mock(import('<root>'), async (importOriginal) => ({ ...(await importOriginal()), <override> }))`. A factory that " +
-                    'returns only the exports one test steers deletes the rest, and code that needs them fails away from the ' +
-                    "assertion. A mock whose factory loads the root's shared fake passes when that fake spreads the real module. " +
+                description: 'A `vi.mock` of a listed package root, named by a string or through `import()`, keeps the real ' +
+                    'module: its factory spreads its own `importOriginal` ' +
+                    '(`({ ...(await importOriginal()), <override> })`), returns on every path through a listed ' +
+                    'pass-through helper handed that `importOriginal` (`passThroughModule(importOriginal, { <override> })`), ' +
+                    "or loads the root's shared fake that keeps the real module. A factory that returns only the " +
+                    'exports one test steers — through a stub helper too — deletes the rest, and code that needs them ' +
+                    'fails away from the assertion. ' +
                     facts.packageRoots.map((r) => `${r.module}: ${r.why}.`).join(' '),
                 run(context) {
                     const findings = [];
+                    const roots = new Set(facts.packageRoots.map((r) => r.module));
                     const mocked = new Set();
                     const aliases = aliasList(facts.sharedFakes?.importAliases ?? {});
+                    const passesThrough = (path, name) => facts.passThroughHelpers.some((h) => h.owner === path && h.names.includes(name));
                     const ownerOf = (module, rootName) => facts.sharedFakes?.fakes.find((f) => f.module === module &&
                         context.reader.exists(f.owner) &&
                         context.file(f.owner).rootName === rootName)?.owner;
@@ -467,7 +488,7 @@ export const partialMockGuard = {
                         const owner = ownerOf(module, file.rootName);
                         return (owner !== undefined &&
                             factoryLoads(call).some((spec) => resolveSpecifier(context.reader, file.path, spec, aliases) === owner) &&
-                            ownerKeepsRealExports(context, owner, aliases));
+                            ownerKeepsRealExports(context, owner, aliases, passesThrough));
                     };
                     const files = context.files({
                         roots: ['app', 'functions'],
@@ -476,16 +497,25 @@ export const partialMockGuard = {
                         optionalRoots: ['functions'],
                     });
                     for (const file of files) {
-                        for (const { module } of facts.packageRoots) {
-                            for (const { call, index } of moduleMockCalls(file.code, module)) {
-                                mocked.add(module);
-                                if (!spreadsImportOriginal(call) && !loadsKeepingOwner(file, module, call))
-                                    findings.push({
-                                        file: file.path,
-                                        line: file.lineOf(index),
-                                        detail: `a full-module mock of ${module}`,
-                                    });
-                            }
+                        const resolve = (spec) => resolveSpecifier(context.reader, file.path, spec, aliases);
+                        for (const site of file.imports) {
+                            if (site.kind !== 'mock' || !MOCK_CALLS.has(site.callee ?? ''))
+                                continue;
+                            if (!roots.has(site.spec) || !ts.isCallExpression(site.node))
+                                continue;
+                            mocked.add(site.spec);
+                            const call = site.node.getText(file.sourceFile);
+                            const factory = site.node.arguments[1];
+                            const fn = factory ? factoryFunction(factory) : null;
+                            if (spreadsImportOriginal(call, (fn && parameterName(fn)) ?? 'importOriginal') ||
+                                (fn !== null && returnsThroughPassThrough(fn, resolve, passesThrough)) ||
+                                loadsKeepingOwner(file, site.spec, call))
+                                continue;
+                            findings.push({
+                                file: file.path,
+                                line: lineOfNode(file, site.node),
+                                detail: `a full-module mock of ${site.spec}`,
+                            });
                         }
                     }
                     for (const { module } of facts.packageRoots) {