pyric 0.1.0-alpha.20 → 0.1.0-alpha.21

package/src/firestore/lite.ts

@@ -0,0 +1,91 @@
+/**
+ * `pyric/firestore/lite` — a DEFERRED mirror of `firebase/firestore/lite`.
+ *
+ * The Lite SDK is a separate build of Firestore with no local cache, no
+ * listeners and no offline queue. pyric mirrors the full `firebase/firestore`
+ * surface against the in-process sandbox; the Lite build needs its own
+ * cache-free instance identity, so it is deferred rather than aliased — an
+ * alias would silently give Lite consumers listener-backed semantics the real
+ * Lite SDK does not have.
+ *
+ * Every symbol below resolves and links so an app that swaps `firebase` for
+ * `pyric` still loads; touching one throws `PyricDeferredApiError` naming this
+ * subpath. See `../deferred/entry.ts` for the full rationale.
+ *
+ * The value list is the exact public runtime surface of `firebase/firestore/lite`
+ * (Firebase Web SDK 12.13.0). Keep it in sync when this entry graduates to a
+ * real mirror.
+ */
+import { deferredEntry, type DeferredApi } from '../deferred/entry.js';
+
+export { PyricDeferredApiError } from '../deferred/entry.js';
+
+export const {
+  AggregateField, AggregateQuerySnapshot, Bytes, CollectionReference, DocumentReference,
+  DocumentSnapshot, FieldPath, FieldValue, Firestore, FirestoreError, GeoPoint, Query,
+  QueryCompositeFilterConstraint, QueryConstraint, QueryDocumentSnapshot, QueryEndAtConstraint,
+  QueryFieldFilterConstraint, QueryLimitConstraint, QueryOrderByConstraint, QuerySnapshot,
+  QueryStartAtConstraint, Timestamp, Transaction, VectorValue, WriteBatch, addDoc,
+  aggregateFieldEqual, aggregateQuerySnapshotEqual, and, arrayRemove, arrayUnion, average,
+  collection, collectionGroup, connectFirestoreEmulator, count, deleteDoc, deleteField, doc,
+  documentId, endAt, endBefore, getAggregate, getCount, getDoc, getDocs, getFirestore,
+  increment, initializeFirestore, limit, limitToLast, or, orderBy, query, queryEqual, refEqual,
+  runTransaction, serverTimestamp, setDoc, setLogLevel, snapshotEqual, startAfter, startAt,
+  sum, terminate, updateDoc, vector, where, writeBatch,
+} = deferredEntry('firestore/lite');
+
+// Type declarations. Aliased to the deferred placeholder so a consumer's own
+// annotations keep type-checking: every deferred call returns `never`, which is
+// assignable to any of these. Names that Firebase exports as a CLASS appear both
+// here and above — a class is a value and a type, and both meanings must survive
+// the swap.
+export type AddPrefixToKeys = DeferredApi;
+export type AggregateField = DeferredApi;
+export type AggregateFieldType = DeferredApi;
+export type AggregateQuerySnapshot = DeferredApi;
+export type AggregateSpec = DeferredApi;
+export type AggregateSpecData = DeferredApi;
+export type AggregateType = DeferredApi;
+export type Bytes = DeferredApi;
+export type ChildUpdateFields = DeferredApi;
+export type CollectionReference = DeferredApi;
+export type DocumentData = DeferredApi;
+export type DocumentReference = DeferredApi;
+export type DocumentSnapshot = DeferredApi;
+export type EmulatorMockTokenOptions = DeferredApi;
+export type FieldPath = DeferredApi;
+export type FieldValue = DeferredApi;
+export type Firestore = DeferredApi;
+export type FirestoreDataConverter = DeferredApi;
+export type FirestoreError = DeferredApi;
+export type FirestoreErrorCode = DeferredApi;
+export type GeoPoint = DeferredApi;
+export type LogLevel = DeferredApi;
+export type NestedUpdateFields = DeferredApi;
+export type OrderByDirection = DeferredApi;
+export type PartialWithFieldValue = DeferredApi;
+export type Primitive = DeferredApi;
+export type Query = DeferredApi;
+export type QueryCompositeFilterConstraint = DeferredApi;
+export type QueryConstraint = DeferredApi;
+export type QueryConstraintType = DeferredApi;
+export type QueryDocumentSnapshot = DeferredApi;
+export type QueryEndAtConstraint = DeferredApi;
+export type QueryFieldFilterConstraint = DeferredApi;
+export type QueryFilterConstraint = DeferredApi;
+export type QueryLimitConstraint = DeferredApi;
+export type QueryNonFilterConstraint = DeferredApi;
+export type QueryOrderByConstraint = DeferredApi;
+export type QuerySnapshot = DeferredApi;
+export type QueryStartAtConstraint = DeferredApi;
+export type SetOptions = DeferredApi;
+export type Settings = DeferredApi;
+export type Timestamp = DeferredApi;
+export type Transaction = DeferredApi;
+export type TransactionOptions = DeferredApi;
+export type UnionToIntersection = DeferredApi;
+export type UpdateData = DeferredApi;
+export type VectorValue = DeferredApi;
+export type WhereFilterOp = DeferredApi;
+export type WithFieldValue = DeferredApi;
+export type WriteBatch = DeferredApi;

package/src/firestore/persistence.ts

@@ -191,7 +191,7 @@ const TAB_MANAGER_SYMBOL: unique symbol = Symbol('pyric/firestore/tabManager');
 const GC_SYMBOL: unique symbol = Symbol('pyric/firestore/gc');
 
 /** Opaque tab-manager config token. Inert — persistence is always on,
- *  and the SharedWorker/`pyric dev` path already is the one shared
+ *  and the SharedWorker/`pyric sandbox` path already is the one shared
  *  store every tab talks to, so there is no separate multi-tab mode
  *  to opt into. Carries the requested kind only for debugging. */
 export interface PersistentTabManager {
@@ -409,7 +409,7 @@ export type LogLevel = 'debug' | 'verbose' | 'info' | 'warn' | 'error' | 'silent
 /**
  * Accepted no-op: the sandbox has no modular-SDK-style logger to wire
  * a level into (it uses host-level `console` logging directly, gated
- * by `pyric dev`'s own flags, not this call). Exists purely so app
+ * by `pyric sandbox`'s own flags, not this call). Exists purely so app
  * code that calls this defensively at startup doesn't crash on a
  * missing export.
  */

package/src/functions/index.ts

@@ -0,0 +1,38 @@
+/**
+ * `pyric/functions` — a DEFERRED mirror of `firebase/functions`.
+ *
+ * Callable Cloud Functions dispatch to deployed server code. Mirroring this
+ * means running the user’s functions, which is the emulator’s job, not the
+ * in-process sandbox’s — deferred pending a decision on the function-host
+ * seam.
+ *
+ * Every symbol below resolves and links so an app that swaps `firebase` for
+ * `pyric` still loads; touching one throws `PyricDeferredApiError` naming this
+ * subpath. See `../deferred/entry.ts` for the full rationale.
+ *
+ * The value list is the exact public runtime surface of `firebase/functions`
+ * (Firebase Web SDK 12.13.0). Keep it in sync when this entry graduates to a
+ * real mirror.
+ */
+import { deferredEntry, type DeferredApi } from '../deferred/entry.js';
+
+export { PyricDeferredApiError } from '../deferred/entry.js';
+
+export const {
+  FunctionsError, connectFunctionsEmulator, getFunctions, httpsCallable, httpsCallableFromURL,
+} = deferredEntry('functions');
+
+// Type declarations. Aliased to the deferred placeholder so a consumer's own
+// annotations keep type-checking: every deferred call returns `never`, which is
+// assignable to any of these. Names that Firebase exports as a CLASS appear both
+// here and above — a class is a value and a type, and both meanings must survive
+// the swap.
+export type Functions = DeferredApi;
+export type FunctionsError = DeferredApi;
+export type FunctionsErrorCode = DeferredApi;
+export type FunctionsErrorCodeCore = DeferredApi;
+export type HttpsCallable = DeferredApi;
+export type HttpsCallableOptions = DeferredApi;
+export type HttpsCallableResult = DeferredApi;
+export type HttpsCallableStreamOptions = DeferredApi;
+export type HttpsCallableStreamResult = DeferredApi;

package/src/performance/index.ts

@@ -0,0 +1,31 @@
+/**
+ * `pyric/performance` — a DEFERRED mirror of `firebase/performance`.
+ *
+ * Performance Monitoring instruments real network and render timings and
+ * ships them to Google. Nothing about it is locally observable, so it is
+ * deferred.
+ *
+ * Every symbol below resolves and links so an app that swaps `firebase` for
+ * `pyric` still loads; touching one throws `PyricDeferredApiError` naming this
+ * subpath. See `../deferred/entry.ts` for the full rationale.
+ *
+ * The value list is the exact public runtime surface of `firebase/performance`
+ * (Firebase Web SDK 12.13.0). Keep it in sync when this entry graduates to a
+ * real mirror.
+ */
+import { deferredEntry, type DeferredApi } from '../deferred/entry.js';
+
+export { PyricDeferredApiError } from '../deferred/entry.js';
+
+export const {
+  getPerformance, initializePerformance, trace,
+} = deferredEntry('performance');
+
+// Type declarations. Aliased to the deferred placeholder so a consumer's own
+// annotations keep type-checking: every deferred call returns `never`, which is
+// assignable to any of these. Names that Firebase exports as a CLASS appear both
+// here and above — a class is a value and a type, and both meanings must survive
+// the swap.
+export type FirebasePerformance = DeferredApi;
+export type PerformanceSettings = DeferredApi;
+export type PerformanceTrace = DeferredApi;

package/src/remote-config/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `pyric/remote-config` — a DEFERRED mirror of `firebase/remote-config`.
+ *
+ * Remote Config serves server-side parameter values with fetch/activate
+ * caching semantics. Mirroring it needs a sandbox-side config store and a
+ * model of the fetch throttle — buildable, not yet built.
+ *
+ * Every symbol below resolves and links so an app that swaps `firebase` for
+ * `pyric` still loads; touching one throws `PyricDeferredApiError` naming this
+ * subpath. See `../deferred/entry.ts` for the full rationale.
+ *
+ * The value list is the exact public runtime surface of `firebase/remote-config`
+ * (Firebase Web SDK 12.13.0). Keep it in sync when this entry graduates to a
+ * real mirror.
+ */
+import { deferredEntry, type DeferredApi } from '../deferred/entry.js';
+
+export { PyricDeferredApiError } from '../deferred/entry.js';
+
+export const {
+  activate, ensureInitialized, fetchAndActivate, fetchConfig, getAll, getBoolean, getNumber,
+  getRemoteConfig, getString, getValue, onConfigUpdate, setCustomSignals,
+  setLogLevel,
+} = deferredEntry('remote-config');
+
+/**
+ * The one deferred symbol that answers instead of throwing: the real SDK
+ * resolves a boolean, and a deferred entry IS unsupported, so the standard
+ * `isSupported().then(ok => ok && get…(app))` guard must run — not crash.
+ */
+export const isSupported = async (): Promise<boolean> => false;
+
+
+// Type declarations. Aliased to the deferred placeholder so a consumer's own
+// annotations keep type-checking: every deferred call returns `never`, which is
+// assignable to any of these. Names that Firebase exports as a CLASS appear both
+// here and above — a class is a value and a type, and both meanings must survive
+// the swap.
+export type ConfigUpdate = DeferredApi;
+export type ConfigUpdateObserver = DeferredApi;
+export type CustomSignals = DeferredApi;
+export type FetchResponse = DeferredApi;
+export type FetchStatus = DeferredApi;
+export type FetchType = DeferredApi;
+export type FirebaseExperimentDescription = DeferredApi;
+export type FirebaseRemoteConfigObject = DeferredApi;
+export type LogLevel = DeferredApi;
+export type RemoteConfig = DeferredApi;
+export type RemoteConfigOptions = DeferredApi;
+export type RemoteConfigSettings = DeferredApi;
+export type Unsubscribe = DeferredApi;
+export type Value = DeferredApi;
+export type ValueSource = DeferredApi;

package/src/rules/grammar/FirestoreValidator.ts

@@ -2,6 +2,7 @@ import type {
   FirestoreRules, MatchBlock, AllowRule, FunctionDef, Expression, Operation,
 } from './FirestoreAST.js';
 import { RULES_BUILTIN_FUNCTIONS } from './builtin-functions.js';
+import { countDocumentAccessCalls } from './document-access-count.js';
 
 export interface ValidationFinding {
   code: string;
@@ -26,8 +27,9 @@ export function validateFirestoreRules(ast: FirestoreRules): ValidationFinding[]
   // SEC-4: Check for default deny
   checkDefaultDeny(rootMatch, findings);
 
-  // QUA-3: Duplicate function names
-  checkDuplicateFunctions(rootMatch, findings);
+  // QUA-3: Duplicate function names in one scope (production compile
+  // rejection, so critical). Nested shadowing is legal and is not flagged.
+  checkDuplicateFunctions(ast, findings);
 
   // QUA-4: Unused functions
   checkUnusedFunctions(rootMatch, allCalls, findings);
@@ -124,12 +126,15 @@ function walkMatch(
       });
     }
 
-    // SEM-3: get()/exists() budget exceeded
-    const docReads = countDocReads(cond, new Map(localScope.map(f => [f.name, f])));
+    // SEM-3: document access budget exceeded. Production allows exactly 10
+    // get/exists/getAfter/existsAfter reads per request evaluation; the
+    // 11th fails, so the finding fires only ABOVE 10 (same boundary as the
+    // linter's GET_COUNT error and the simulator's runtime LookupBudget).
+    const docReads = countDocumentAccessCalls(cond, fnMap);
     if (docReads > 10) {
       findings.push({
         code: 'SEM-3', severity: 'high', path: pathStr, operation: opStr,
-        message: `Rule at ${pathStr} has ${docReads} document reads (get/exists) — exceeds the 10-call budget`,
+        message: `Rule at ${pathStr} may perform ${docReads} document access calls (get/exists/getAfter/existsAfter), which exceeds the 10-call budget`,
       });
     }
 
@@ -323,21 +328,6 @@ function referencesResourceData(expr: Expression): boolean {
   );
 }
 
-function countDocReads(expr: Expression, functions: Map<string, FunctionDef>, visited = new Set<string>()): number {
-  let count = 0;
-  walkExpr(expr, e => {
-    if (e.type === 'functionCall' && (e.name === 'get' || e.name === 'exists' || e.name === 'getAfter')) {
-      count++;
-    }
-    // Follow user-defined function calls
-    if (e.type === 'functionCall' && functions.has(e.name) && !visited.has(e.name)) {
-      visited.add(e.name);
-      count += countDocReads(functions.get(e.name)!.body, functions, visited);
-    }
-  });
-  return count;
-}
-
 function collectFunctionCalls(expr: Expression): string[] {
   const calls: string[] = [];
   walkExpr(expr, e => {
@@ -357,22 +347,48 @@ function collectAllFunctions(match: MatchBlock): Set<string> {
 }
 
 // ---- QUA-3: Duplicate functions ----
+//
+// Production REJECTS two declarations of one function name in the SAME
+// scope at compile time, so this is severity 'critical': the write gate
+// (`write/handler.ts`) blocks only critical validator findings, and
+// 'medium' folded to a mere warning that deployed anyway.
+//
+// A scope is one declaration list: the global list above `service`, the
+// list directly inside `service`, or one match block's own list. A nested
+// match block that redeclares a name from an enclosing scope SHADOWS it and
+// is legal: the simulator implements shadowing in
+// `simulator/match-resolution.ts`, and the production capture in
+// `conformance/rules-corpus/storage/function-scopes-and-shadowing.ts` pins
+// inner-shadows-outer as accepted. Flagging that would block a ruleset
+// production deploys.
+//
+// The code stays QUA-3 (already registered and asserted by consumers);
+// `DUPLICATE_FUNCTION` was considered and rejected, because the module
+// resolver already uses that name for its own error code
+// (`modules/resolver-core.ts`), and colliding would make mixed issue
+// lists ambiguous.
+
+function checkDuplicateFunctions(ast: FirestoreRules, findings: ValidationFinding[]) {
+  checkDupsInScope(ast.functions ?? [], 'global scope', findings);
+  checkDupsInScope(ast.service.functions ?? [], `service ${ast.service.name}`, findings);
+  checkDupsInMatchScopes(ast.service.match, findings);
+}
 
-function checkDuplicateFunctions(match: MatchBlock, findings: ValidationFinding[]) {
+function checkDupsInMatchScopes(match: MatchBlock, findings: ValidationFinding[]) {
   checkDupsInScope(match.functions, match.path.raw, findings);
-  for (const child of match.children) checkDuplicateFunctions(child, findings);
+  for (const child of match.children) checkDupsInMatchScopes(child, findings);
 }
 
-function checkDupsInScope(fns: FunctionDef[], path: string, findings: ValidationFinding[]) {
-  const seen = new Set<string>();
+function checkDupsInScope(fns: readonly FunctionDef[], scope: string, findings: ValidationFinding[]) {
+  const declared = new Set<string>();
   for (const fn of fns) {
-    if (seen.has(fn.name)) {
+    if (declared.has(fn.name)) {
       findings.push({
-        code: 'QUA-3', severity: 'medium', path,
-        message: `Duplicate function '${fn.name}' in scope at ${path}`,
+        code: 'QUA-3', severity: 'critical', path: scope,
+        message: `Duplicate function '${fn.name}' declared twice in ${scope}. Production rejects duplicate function declarations in one scope at compile time`,
       });
     }
-    seen.add(fn.name);
+    declared.add(fn.name);
   }
 }
 

package/src/rules/grammar/document-access-count.ts

@@ -0,0 +1,75 @@
+import type { Expression, FunctionDef } from './FirestoreAST.js';
+
+/**
+ * The four built-in document access calls production counts against a
+ * request's 10-read budget.
+ */
+const DOCUMENT_ACCESS_BUILTINS = new Set(['get', 'exists', 'getAfter', 'existsAfter']);
+
+/**
+ * Count the document access calls (get/exists/getAfter/existsAfter)
+ * reachable from a rule condition, expanding each user-defined function
+ * once PER CALL SITE. `isOwner(a) && isOwner(b) && isOwner(c)` with three
+ * gets inside `isOwner` costs nine, matching production where each call
+ * performs its own reads (different arguments mean different paths).
+ * A function's `let` bindings evaluate on every call, so their reads count
+ * too. The call stack guards recursion only, and entries unwind on return,
+ * so sibling call sites each pay full price.
+ *
+ * This is a static over-approximation: production caches repeated reads of
+ * the SAME path within a request (see site-docs
+ * secure/firestore-rules-limits.md), but path identity is not decidable
+ * statically, so every call site is charged. The cache-aware, distinct-path
+ * count is the runtime concern of LookupBudget in
+ * simulator/lookup-budget.ts, which counts what an evaluation actually
+ * reads rather than what a condition could reach.
+ *
+ * This is the single walker behind both static consumers: the validator's
+ * SEM-3 finding and the linter's GET_COUNT warning.
+ */
+export function countDocumentAccessCalls(
+  expr: Expression,
+  functions: Map<string, FunctionDef>,
+  callStack: Set<string> = new Set<string>(),
+): number {
+  let count = 0;
+
+  const visit = (e: Expression): void => {
+    switch (e.type) {
+      case 'functionCall':
+        if (DOCUMENT_ACCESS_BUILTINS.has(e.name)) {
+          count++;
+        } else {
+          const fn = functions.get(e.name);
+          const isExpandable = fn !== undefined && !callStack.has(e.name);
+          if (isExpandable) {
+            callStack.add(e.name);
+            for (const binding of fn!.lets) visit(binding.value);
+            visit(fn!.body);
+            callStack.delete(e.name); // unwind: count once per call site, not once per rule
+          }
+        }
+        e.args.forEach(visit);
+        break;
+      case 'binaryOp': visit(e.left); visit(e.right); break;
+      case 'unaryOp': visit(e.operand); break;
+      case 'ternary': visit(e.condition); visit(e.consequent); visit(e.alternate); break;
+      case 'methodCall': visit(e.object); e.args.forEach(visit); break;
+      case 'memberAccess': visit(e.object); break;
+      case 'bracketAccess': visit(e.object); visit(e.index); break;
+      case 'sliceAccess': visit(e.object); visit(e.start); visit(e.end); break;
+      case 'inExpr': visit(e.element); visit(e.collection); break;
+      case 'isExpr': visit(e.value); break;
+      case 'listLiteral': e.elements.forEach(visit); break;
+      case 'mapLiteral': e.entries.forEach((entry) => { visit(entry.key); visit(entry.value); }); break;
+      case 'pathLiteral':
+        for (const segment of e.segments) {
+          if (typeof segment !== 'string') visit(segment);
+        }
+        break;
+    }
+  };
+
+  visit(expr);
+  return count;
+}

package/src/rules/linter/ast-utils.ts

@@ -218,44 +218,10 @@ export function maxCallDepth(start: string, graph: Map<string, string[]>, visite
   return 1 + max;
 }
 
-/**
- * Count get() and exists() calls reachable from an expression,
- * following function calls transitively.
- */
-export function countGetCalls(expr: Expression, functions: Map<string, FunctionDef>, visited = new Set<string>()): number {
-  let count = 0;
-  const walk = (e: Expression) => {
-    switch (e.type) {
-      case 'functionCall':
-        if (e.name === 'get' || e.name === 'exists') {
-          count++;
-        } else if (functions.has(e.name) && !visited.has(e.name)) {
-          visited.add(e.name);
-          const fn = functions.get(e.name)!;
-          walk(fn.body);
-          for (const b of fn.lets) walk(b.value);
-        }
-        e.args.forEach(walk);
-        break;
-      case 'binaryOp': walk(e.left); walk(e.right); break;
-      case 'unaryOp': walk(e.operand); break;
-      case 'methodCall': walk(e.object); e.args.forEach(walk); break;
-      case 'memberAccess': walk(e.object); break;
-      case 'bracketAccess': walk(e.object); walk(e.index); break;
-      case 'ternary': walk(e.condition); walk(e.consequent); walk(e.alternate); break;
-      case 'inExpr': walk(e.element); walk(e.collection); break;
-      case 'isExpr': walk(e.value); break;
-      case 'listLiteral': e.elements.forEach(walk); break;
-      case 'mapLiteral': e.entries.forEach(en => { walk(en.key); walk(en.value); }); break;
-    }
-  };
-  walk(expr);
-  return count;
-}
-
 /**
  * Count how many times each user-defined function is called in an expression.
- * Unlike countGetCalls (which deduplicates), this counts raw call-site occurrences.
+ * Counts raw call-site occurrences at the top level only: it does not expand
+ * nested user-function bodies the way countDocumentAccessCalls does.
  */
 export function countFunctionCallSites(expr: Expression, fnNames: Set<string>): Map<string, number> {
   const counts = new Map<string, number>();