pyric 0.0.1 → 0.1.0-alpha.8

package/dist/rules/simulator/expression/walk-data.js

@@ -0,0 +1,167 @@
+/**
+ * Item 4.3 — Recursive walker that resolves `{ $expr: "..." }`
+ * wrappers anywhere in a write `data` tree.
+ *
+ * Contract:
+ *  - Walks the input tree once. Returns a NEW tree (the input is
+ *    never mutated).
+ *  - A wrapper is exactly an object whose ONLY key is `$expr` and
+ *    whose `$expr` value is a string. Any other shape with `$expr`
+ *    (extra keys, non-string value) throws `ExpressionWalkError`
+ *    with `code: 'invalid-argument'`.
+ *  - Arrays preserve length and order; wrappers inside arrays are
+ *    resolved in place.
+ *  - The walker DOES NOT recurse into eval results. If `$expr`
+ *    resolves to an object containing a `$expr` key (e.g. from a
+ *    doc read), that nested key is treated as data — not a wrapper.
+ *  - Errors include a path string (`users.0.balance`) so agents can
+ *    locate the offending leaf.
+ *
+ * Pre-mortem-locked behaviors:
+ *  - `null` is a literal value, NOT a target for descent.
+ *  - Top-level `{ $expr: ... }` is allowed. The tool layer enforces
+ *    that the *resolved* top-level data is a plain object before
+ *    handing to the simulator.
+ *  - Sentinel passthrough objects (`{ __type: '...' }`) returned by
+ *    eval are leaf values — the walker doesn't descend into them.
+ */
+import { ExpressionLexError, ExpressionParseError, } from './types.js';
+import { tokenize } from './lexer.js';
+import { parse } from './parser.js';
+import { evaluate } from './evaluator.js';
+import { EvalError, } from './eval-errors.js';
+const EXPR_WRAPPER_KEY = '$expr';
+/**
+ * Errors raised by the walker for shape violations (ambiguous wrapper,
+ * non-string `$expr` value). Distinct from `EvalError` so the tool
+ * layer can label the failure precisely.
+ */
+export class ExpressionWalkError extends Error {
+    code = 'invalid-argument';
+    /** Dotted path to the offending node, e.g. `users.0.balance`. */
+    path;
+    constructor(message, path) {
+        super(message);
+        this.name = 'ExpressionWalkError';
+        this.path = path;
+    }
+}
+export function resolveExpressionsInData(data, env) {
+    return walk(data, env, '');
+}
+function walk(value, env, path) {
+    // Primitives and null pass through unchanged.
+    if (value === null)
+        return null;
+    if (typeof value !== 'object')
+        return value;
+    // Arrays — preserve length, walk each element.
+    if (Array.isArray(value)) {
+        const out = new Array(value.length);
+        for (let i = 0; i < value.length; i += 1) {
+            out[i] = walk(value[i], env, path === '' ? String(i) : `${path}.${i}`);
+        }
+        return out;
+    }
+    // Plain objects. First check for the `$expr` wrapper.
+    const obj = value;
+    if (Object.prototype.hasOwnProperty.call(obj, EXPR_WRAPPER_KEY)) {
+        return resolveWrapper(obj, env, path);
+    }
+    // Regular object — walk each value. (Iterate own keys only; skip
+    // anything inherited from prototype if a malicious shape were
+    // constructed via `Object.create`.)
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        result[key] = walk(obj[key], env, path === '' ? key : `${path}.${key}`);
+    }
+    return result;
+}
+/**
+ * `obj` has a `$expr` key. Validate the wrapper shape, parse +
+ * evaluate, and return the result. Throws `ExpressionWalkError` for
+ * shape problems; eval errors are re-thrown unchanged so the caller
+ * can pick up the AST position.
+ */
+function resolveWrapper(obj, env, path) {
+    const keys = Object.keys(obj);
+    if (keys.length !== 1) {
+        throw new ExpressionWalkError(`expression wrapper at '${path || '<root>'}' must have only the '$expr' key, got [${keys.map((k) => JSON.stringify(k)).join(', ')}]`, path);
+    }
+    const exprValue = obj[EXPR_WRAPPER_KEY];
+    if (typeof exprValue !== 'string') {
+        throw new ExpressionWalkError(`'$expr' value at '${path || '<root>'}' must be a string, got ${describeUnknown(exprValue)}`, path);
+    }
+    const ast = parseAndCache(exprValue, path);
+    const value = evaluateWrapper(ast, env, path);
+    return value;
+}
+/**
+ * Evaluate an expression and re-tag any error with the wrapper path
+ * so downstream messages can say *which* `$expr` failed.
+ *
+ * Eval errors (`EvalError`) keep their original `code` and `pos`;
+ * we just wrap the message. The `cause` chain preserves the original
+ * stack for debugging.
+ */
+function evaluateWrapper(ast, env, path) {
+    try {
+        return evaluate(ast, env);
+    }
+    catch (e) {
+        if (e instanceof EvalError) {
+            const wrapped = new EvalError(e.code, `at '${path || '<root>'}': ${e.message}`, e.pos);
+            // Preserve the original via `cause` so stack traces still show
+            // the underlying failure.
+            wrapped.cause = e;
+            throw wrapped;
+        }
+        throw e;
+    }
+}
+/**
+ * Parse the expression source. We don't cache across walks — each
+ * `walk-data` call is one tx invocation, so re-parsing is cheap and
+ * the per-call cap (256 chars) makes this a non-issue. The function
+ * exists to centralize parse-error tagging.
+ *
+ * Re-tagging is done with explicit `instanceof` switches over the
+ * known error classes (`ExpressionLexError`, `ExpressionParseError`)
+ * rather than `new (e.constructor as typeof Error)(...)`. The
+ * reflection form silently degrades to a plain `Error` if a future
+ * caller throws a different subclass, dropping `code`/`pos`. Explicit
+ * switches let the type checker enforce that every known error class
+ * is handled.
+ */
+function parseAndCache(src, path) {
+    try {
+        return parse(tokenize(src));
+    }
+    catch (e) {
+        if (e instanceof ExpressionLexError) {
+            throw retagLexOrParseError(e, ExpressionLexError, path);
+        }
+        if (e instanceof ExpressionParseError) {
+            throw retagLexOrParseError(e, ExpressionParseError, path);
+        }
+        throw e;
+    }
+}
+/**
+ * Construct a fresh error of the same class, preserving `pos` and
+ * chaining the original via `cause`. Path-prefixed message keeps the
+ * agent oriented to where in the data tree the failure occurred.
+ */
+function retagLexOrParseError(original, ctor, path) {
+    const wrapped = new ctor(`at '${path || '<root>'}': ${original.message}`, original.pos);
+    wrapped.cause = original;
+    return wrapped;
+}
+function describeUnknown(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+//# sourceMappingURL=walk-data.js.map

package/dist/rules/simulator/expression/walk-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk-data.js","sourceRoot":"","sources":["../../../../src/rules/simulator/expression/walk-data.ts"],"names":[],"mappings":"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"}

package/dist/rules/simulator/firestore-set.d.ts

@@ -0,0 +1,25 @@
+export declare class FirestoreSet {
+    private items;
+    constructor(items: Iterable<string>);
+    /** True if the set contains ONLY keys from the provided list/set (and no others). */
+    hasOnly(keys: string[] | FirestoreSet): boolean;
+    /** Value equality against another FirestoreSet (order-insensitive).
+     *  Production supports `set == set` (e.g. `diff.addedKeys() ==
+     *  [uid].toSet()`). */
+    equals(other: unknown): boolean;
+    /** True if the set contains ALL keys from the provided list/set. */
+    hasAll(keys: string[] | FirestoreSet): boolean;
+    /** True if the set contains ANY key from the provided list/set. */
+    hasAny(keys: string[] | FirestoreSet): boolean;
+    /** Number of items in the set. */
+    size(): number;
+    /** Convert to array (for debugging). */
+    toArray(): string[];
+    /** Items in this set but not in `other`. */
+    difference(other: string[] | FirestoreSet): FirestoreSet;
+    /** Items in either set. */
+    union(other: string[] | FirestoreSet): FirestoreSet;
+    /** Items in both sets. */
+    intersection(other: string[] | FirestoreSet): FirestoreSet;
+}
+//# sourceMappingURL=firestore-set.d.ts.map

package/dist/rules/simulator/firestore-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-set.d.ts","sourceRoot":"","sources":["../../../src/rules/simulator/firestore-set.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAc;gBAEf,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC;IAInC,qFAAqF;IACrF,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,OAAO;IAQ/C;;2BAEuB;IACvB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAS/B,oEAAoE;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,OAAO;IAQ9C,mEAAmE;IACnE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,OAAO;IAQ9C,kCAAkC;IAClC,IAAI,IAAI,MAAM;IAId,wCAAwC;IACxC,OAAO,IAAI,MAAM,EAAE;IAUnB,4CAA4C;IAC5C,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY;IASxD,2BAA2B;IAC3B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY;IAOnD,0BAA0B;IAC1B,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY;CAQ3D"}

package/dist/rules/simulator/firestore-set.js

@@ -0,0 +1,89 @@
+export class FirestoreSet {
+    items;
+    constructor(items) {
+        this.items = new Set(items);
+    }
+    /** True if the set contains ONLY keys from the provided list/set (and no others). */
+    hasOnly(keys) {
+        const arr = keys instanceof FirestoreSet ? keys.toArray() : keys;
+        for (const item of this.items) {
+            if (!arr.includes(item))
+                return false;
+        }
+        return true;
+    }
+    /** Value equality against another FirestoreSet (order-insensitive).
+     *  Production supports `set == set` (e.g. `diff.addedKeys() ==
+     *  [uid].toSet()`). */
+    equals(other) {
+        if (!(other instanceof FirestoreSet))
+            return false;
+        if (other.items.size !== this.items.size)
+            return false;
+        for (const item of this.items) {
+            if (!other.items.has(item))
+                return false;
+        }
+        return true;
+    }
+    /** True if the set contains ALL keys from the provided list/set. */
+    hasAll(keys) {
+        const arr = keys instanceof FirestoreSet ? keys.toArray() : keys;
+        for (const key of arr) {
+            if (!this.items.has(key))
+                return false;
+        }
+        return true;
+    }
+    /** True if the set contains ANY key from the provided list/set. */
+    hasAny(keys) {
+        const arr = keys instanceof FirestoreSet ? keys.toArray() : keys;
+        for (const key of arr) {
+            if (this.items.has(key))
+                return true;
+        }
+        return false;
+    }
+    /** Number of items in the set. */
+    size() {
+        return this.items.size;
+    }
+    /** Convert to array (for debugging). */
+    toArray() {
+        return [...this.items];
+    }
+    // Per REBUILD_PLAN type table for Set:
+    //   difference(other: Set) -> Set
+    //   union(other: Set) -> Set
+    //   intersection(other: Set) -> Set
+    // Mirroring hasOnly/hasAll/hasAny, we accept a List (string[]) too.
+    /** Items in this set but not in `other`. */
+    difference(other) {
+        const otherSet = new Set(other instanceof FirestoreSet ? other.toArray() : other);
+        const result = [];
+        for (const item of this.items) {
+            if (!otherSet.has(item))
+                result.push(item);
+        }
+        return new FirestoreSet(result);
+    }
+    /** Items in either set. */
+    union(other) {
+        const otherArr = other instanceof FirestoreSet ? other.toArray() : other;
+        const merged = new Set(this.items);
+        for (const item of otherArr)
+            merged.add(item);
+        return new FirestoreSet(merged);
+    }
+    /** Items in both sets. */
+    intersection(other) {
+        const otherSet = new Set(other instanceof FirestoreSet ? other.toArray() : other);
+        const result = [];
+        for (const item of this.items) {
+            if (otherSet.has(item))
+                result.push(item);
+        }
+        return new FirestoreSet(result);
+    }
+}
+//# sourceMappingURL=firestore-set.js.map

package/dist/rules/simulator/firestore-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore-set.js","sourceRoot":"","sources":["../../../src/rules/simulator/firestore-set.ts"],"names":[],"mappings":"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"}

package/dist/rules/simulator/handler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Firestore Rules Simulation Handler.
+ *
+ * Local simulation of Firestore security rules evaluation.
+ * Same interface as TestFirestoreRulesHandler but runs entirely
+ * in-process — no deployment, no propagation wait, no side effects.
+ *
+ * Consumes TestCase[] and returns TestResult[] in the same format
+ * as the Rules Test API.
+ */
+import type { TestCase, TestFirestoreRulesResult } from '../test/spec.js';
+import { Timestamp } from './wrappers/timestamp.js';
+/** Sentinel value for FieldValue.serverTimestamp() in test data. */
+export declare const SERVER_TIMESTAMP: {
+    readonly __type: "serverTimestamp";
+};
+/**
+ * Recursively replace serverTimestamp sentinels with the actual server time.
+ * Item 1.3: `serverTime` is now a Timestamp wrapper (was ISO string). The
+ * SAME instance is reused across every sentinel hit so `data.createdAt ==
+ * request.time` succeeds via rulesValuesEqual -> Timestamp.equals (field
+ * compare). Without instance reuse, two distinct Timestamp instances would
+ * still equate via field compare — but the single-instance invariant is
+ * documented here so future refactors don't break it accidentally.
+ */
+export declare function resolveServerTimestamps(data: Record<string, unknown>, serverTime: Timestamp): Record<string, unknown>;
+export declare class SimulateFirestoreRulesHandler {
+    /**
+     * Simulate Firestore rules evaluation locally.
+     * Same interface as TestFirestoreRulesHandler.execute().
+     */
+    simulate(source: string, testCases: TestCase[], opts?: {
+        getDoc?: (path: string) => Record<string, unknown> | null;
+    }): TestFirestoreRulesResult;
+}
+//# sourceMappingURL=handler.d.ts.map

package/dist/rules/simulator/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/rules/simulator/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,QAAQ,EAER,wBAAwB,EAIzB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAqRpD,oEAAoE;AACpE,eAAO,MAAM,gBAAgB;;CAAyC,CAAC;AAOvE;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,SAAS,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB;AAgKD,qBAAa,6BAA6B;IACxC;;;OAGG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,QAAQ,EAAE,EACrB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,GACnE,wBAAwB;CAqJ5B"}