pyric 0.0.1 → 0.1.0-alpha.11

package/dist/rules/rtdb/types.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export const RuleErrorSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+});
+export const RuleLintSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+});
+export const ParsedExpressionSchema = z.object({
+    raw: z.string(),
+    valid: z.boolean(),
+    errors: z.array(RuleErrorSchema),
+    warnings: z.array(RuleLintSchema),
+    referencedIdentifiers: z.array(z.string()),
+});
+export const RtdbRuleExpressionSchema = z.object({
+    raw: z.string(),
+    parsed: ParsedExpressionSchema,
+});
+//# sourceMappingURL=types.js.map

package/dist/rules/rtdb/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rules/rtdb/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE;IAClB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;IACjC,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC3C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,MAAM,EAAE,sBAAsB;CAC/B,CAAC,CAAC"}

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

@@ -0,0 +1,206 @@
+/**
+ * Firestore Security Rules Expression Evaluator.
+ *
+ * Walks the parsed AST and evaluates expressions against a simulated context.
+ * Implements short-circuit evaluation for && and || to match Firestore behavior.
+ *
+ * Layers (built incrementally):
+ *   1. Literals, identifiers, binary ops, comparisons
+ *   2. Member access, bracket access, `in` operator
+ *   3. Function calls, let bindings
+ *   4. Method calls + MapDiff
+ *   5. get()/exists() with mock resolution
+ */
+import type { Expression, FunctionDef } from '../grammar/FirestoreAST.js';
+import { Timestamp } from './wrappers/timestamp.js';
+import { Path } from './wrappers/path.js';
+export interface SimAuth {
+    uid: string;
+    token: Record<string, unknown>;
+}
+export interface SimRequest {
+    auth: SimAuth | null;
+    resource: {
+        data: Record<string, unknown>;
+    };
+    method: string;
+    path: Path;
+    query: Record<string, unknown>;
+    time: Timestamp;
+}
+export interface SimResource {
+    data: Record<string, unknown>;
+    id?: string;
+    __name__?: Path;
+}
+export interface SimulationContext {
+    request: SimRequest;
+    /**
+     * The PRE-WRITE stored document (data + identity), or `null` when no such
+     * document exists. On a `create` the target does not exist yet, so this is
+     * null and any access (`resource.data`, `resource.id`, `resource.__name__`)
+     * errors → DENY, matching production. `request.resource` (the INCOMING
+     * proposed data) is a separate value and is populated on create/update.
+     */
+    resource: SimResource | null;
+    /** Mock documents for get()/exists() calls, keyed by full path. Pre-seeded
+     *  from `functionMocks` (the serializable Test API path) and/or populated
+     *  lazily by {@link getDoc}. */
+    mockDocuments: Map<string, Record<string, unknown>>;
+    /** Lazy fault-in resolver. When a get()/exists() path misses
+     *  {@link mockDocuments}, the evaluator resolves it through this (the DocStore
+     *  point-read) and memoizes the result into mockDocuments. Lets the sandbox
+     *  avoid dumping the whole keyspace into every simulate(); naturally transitive
+     *  for data-dependent get() chains, since the inner get() faults its doc in
+     *  before the outer path string is built. */
+    getDoc?: (path: string) => Record<string, unknown> | null;
+    /** Path variable bindings from match block, e.g. { gameId: 'game1' } */
+    pathVariables: Record<string, string>;
+    /** Function definitions available in scope */
+    functions: Map<string, FunctionDef>;
+    /** Database name for path resolution */
+    database: string;
+    afterStatePath: Path;
+    afterState: Record<string, unknown> | null;
+    existsAfter: boolean;
+    /**
+     * Batch/transaction sibling-write projection (getafter-batch fix).
+     *
+     * `afterState`/`afterStatePath` above only describe the ONE document
+     * this simulate() call is evaluating a rule for. In production,
+     * `getAfter(path)` sees the post-commit state of the ENTIRE atomic
+     * batch/transaction, not just the current write — a rule on doc A can
+     * read what doc B will become once the whole batch lands. Callers that
+     * evaluate a multi-op batch/transaction build ONE projected map up
+     * front (normalized relative path → post-write data, or `null` for a
+     * doc the batch deletes) covering every op in the group, and pass the
+     * SAME map into every per-op simulate() call. Keyed the same way as
+     * `mockDocuments` (normalized relative path, no `/databases/.../documents/`
+     * prefix). A path absent from this map was not written by the batch —
+     * `getAfter` on it falls through to `get()` (current committed data),
+     * matching production. Single-op writes (execute()) omit this map
+     * entirely, so `getAfter` on any path but the op's own target falls
+     * through to `get()` exactly as before.
+     */
+    batchProjection?: Map<string, Record<string, unknown> | null>;
+    /** Optional per-rule expression-trace recorder. When set, the evaluator
+     *  wraps every `evaluate()` call and records the sub-expression tree;
+     *  when absent (the default), the evaluator is unchanged. The handler
+     *  attaches a fresh recorder per allow-rule evaluation so each
+     *  `RuleEvaluation.expressionTrace` is independent. */
+    trace?: TraceRecorder;
+}
+export declare class EvalError extends Error {
+    expr?: Expression | undefined;
+    constructor(message: string, expr?: Expression | undefined);
+}
+/**
+ * Thrown when the simulator encounters a feature it doesn't yet implement
+ * (an unknown built-in function, namespace method, or method on a wrapper
+ * type we haven't added). Distinct from EvalError so the handler can map it
+ * to TestResult.state = 'UNSUPPORTED' instead of a silent DENY — that way
+ * agents see "sim abstained" rather than "your rule is wrong" when the gap
+ * is on our side. See REBUILD_PLAN.md Item 0.A.
+ */
+export declare class UnsupportedError extends EvalError {
+    constructor(message: string, expr?: Expression);
+}
+/**
+ * One entry in the per-rule expression trace recorded by `TraceRecorder`.
+ *
+ * Trace entries are emitted in evaluation order. The tree shape is
+ * reconstructable via `parent`: root entries have `parent: null`, and
+ * each child entry's `parent` is the array index of its evaluating
+ * ancestor. This is denser than nested objects for transport (a tool
+ * call returns a single flat array) and easier for the agent to scan
+ * top-to-bottom.
+ *
+ * `value` carries the evaluation result. For nodes that threw, see
+ * `error`; for short-circuit skips, `skipped: true` is set instead.
+ */
+export interface ExprTraceEntry {
+    /** Pretty-printed source of the expression (via `assembleExpression`). */
+    source: string;
+    /** AST node type — useful for filtering by structural kind. */
+    kind: Expression['type'];
+    /** Index of the parent entry in the trace array; null at the root. */
+    parent: number | null;
+    /** Evaluation result. Undefined when `skipped` or `error` is set. */
+    value?: unknown;
+    /** True for an `&&` / `||` operand that was *not* evaluated due to
+     *  short-circuit. The recorder emits a placeholder entry so the trace
+     *  shape mirrors the surface AST. */
+    skipped?: boolean;
+    /** Error message when the expression threw. The wrapper still re-throws;
+     *  this captures the diagnostic for the caller. */
+    error?: string;
+    /** Set on entries that record a `let` binding evaluation inside a
+     *  user-defined function. `value` holds the bound value. */
+    letBinding?: {
+        name: string;
+    };
+    /** Set on entries recorded *inside* a user-defined function's body
+     *  (after parameter binding). Carries the enclosing function's name
+     *  so the agent can filter the trace by frame —
+     *  `entries.filter(e => e.inlinedFrom?.name === 'isOwner')` — without
+     *  walking the parent chain to find the surrounding `functionCall`.
+     *
+     *  Parameter expressions are *not* tagged: they evaluate in the
+     *  caller's scope, before the frame is entered. The `functionCall`
+     *  entry itself is recorded in the caller's frame too, so a
+     *  top-level `isOwner()` shows `inlinedFrom: undefined` on the
+     *  `functionCall`, but `'isOwner'` on its body children. */
+    inlinedFrom?: {
+        name: string;
+    };
+}
+/**
+ * Records every sub-expression evaluation. Attach to a
+ * `SimulationContext.trace` to enable; the evaluator no-ops when absent
+ * so unsentinel'd callers pay zero cost.
+ *
+ * Recording strategy: each call to `evaluate(expr, ...)` is wrapped via
+ * `capture(expr, fn)`, which reserves a slot in `entries` (assigning
+ * `parent` from the current stack), pushes the slot index, invokes
+ * `fn`, then unwinds. This keeps recursion in the existing evaluator
+ * paths working unchanged — the wrapper sits on top.
+ */
+export declare class TraceRecorder {
+    readonly entries: ExprTraceEntry[];
+    private parents;
+    /** Stack of enclosing user-defined function names. The top of stack is
+     *  stamped onto each pushed entry as `inlinedFrom`. Independent of the
+     *  `parents` stack because parameter expressions evaluate inside the
+     *  capture stack but *outside* the function frame. */
+    private frames;
+    capture<T>(expr: Expression, fn: () => T): T;
+    /** Record an operand the evaluator skipped because the LHS short-circuited.
+     *  Emits an entry under the *current* parent so the trace tree mirrors
+     *  the source AST (skip placeholder is a sibling of the LHS, not nested). */
+    skip(expr: Expression): void;
+    /** Push a user-defined function frame onto the inlinedFrom stack.
+     *  Returns the popped value of the previous top (currently unused —
+     *  callers pair `enterFrame` with `exitFrame()` via the stack, not a
+     *  saved token — but keeping a return value lets future code switch
+     *  to a save/restore idiom without API churn). */
+    enterFrame(name: string): void;
+    /** Pop the topmost frame. Safe to call on an empty stack — no-ops. */
+    exitFrame(): void;
+    private stampFrame;
+    /** Annotate the entry at `index` as a `let` binding — the value was
+     *  bound to `name` in scope. Called from `evaluateFunctionCall` after
+     *  each `let <name> = <expr>` line; the index is the binding root's
+     *  position in the trace (`entries.length` captured BEFORE the call).
+     *  Using a stable index instead of "last entry" is necessary because
+     *  the binding's expression may have recursive children — the most
+     *  recently pushed entry is the deepest leaf, not the root. */
+    markEntryAsLetBinding(index: number, name: string): void;
+}
+/**
+ * Evaluate an expression against the simulation context. The public
+ * entry point — recursive calls inside the evaluator come back through
+ * here, so the optional trace wrapping naturally applies to every
+ * sub-expression.
+ */
+export declare function evaluate(expr: Expression, ctx: SimulationContext, scope?: Record<string, unknown>): unknown;
+//# sourceMappingURL=evaluator.d.ts.map

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

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