pyric 0.0.1 → 0.1.0-alpha.7

package/dist/rules/rtdb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rtdb.d.ts","sourceRoot":"","sources":["../../src/rules/rtdb.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,oBAAoB,EACpB,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,UAAU,GACX,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,EACL,qBAAqB,EACrB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,GACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,GACf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EACV,gBAAgB,EAChB,cAAc,GACf,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEjE,YAAY,EACV,gBAAgB,EAChB,gBAAgB,IAAI,yBAAyB,EAC7C,MAAM,EACN,QAAQ,EACR,kBAAkB,EAClB,SAAS,EACT,SAAS,EACT,QAAQ,EACR,QAAQ,GACT,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,IAAI,EACJ,GAAG,EACH,GAAG,EACH,GAAG,EACH,IAAI,EACJ,MAAM,EACN,KAAK,EACL,aAAa,EACb,OAAO,EACP,QAAQ,EACR,KAAK,EACL,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EACb,cAAc,EACd,SAAS,EACT,SAAS,EACT,aAAa,EACb,UAAU,EACV,UAAU,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,OAAO,EACP,UAAU,EACV,UAAU,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,EAAE,EACF,GAAG,EACH,EAAE,EACF,GAAG,EACH,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,cAAc,EACd,WAAW,EACX,OAAO,EACP,eAAe,GAChB,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EACV,IAAI,EACJ,OAAO,EACP,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,OAAO,GACR,MAAM,kCAAkC,CAAC"}

package/dist/rules/rtdb.js

@@ -0,0 +1,15 @@
+export { fetchDatabase } from '../database/host.js';
+export { createRtdbRulesTools, } from '../database/tools.js';
+export { getRtdbTools } from '../database/resolver.js';
+export { buildRuleExpression, RtdbMapper, } from '../database/mapper.js';
+export { parseExpression } from '../database/grammar/RtdbExprParser.js';
+export { validateExpression } from '../database/grammar/validator.js';
+export { lintExpression } from '../database/grammar/linter.js';
+export { GenerateIRInputSchema, RtdbIRErrorCode, } from '../database/ir/spec.js';
+export { GenerateIRHandler } from '../database/ir/handler.js';
+export { SimulationInputSchema, SimulateErrorCode, SimulationResultSchema, } from '../database/simulation/spec.js';
+export { SimulateHandler } from '../database/simulation/handler.js';
+export { WriteRulesErrorCode } from '../database/write/spec.js';
+export { WriteRulesHandler } from '../database/write/handler.js';
+export { expr, all, any, not, deny, always, allow, authenticated, ownPath, ownField, isNew, hasChildren, hasChild, fieldIsString, fieldIsNumber, fieldIsBoolean, fieldEnum, immutable, immutableSelf, rootExists, rootEquals, pathOwnerOnly, fieldOwnerOnly, ownerOrNew, hasRole, isMember, required, transition, dataVal, newDataVal, dataExists, newDataExists, newDataIs, dataParentVal, newDataParentVal, newDataParentExists, eq, neq, gt, lte, AUTH_UID, turnGuard, flip, winCheckHelper, schemaRules, ruleset, defineRtdbRules, } from '../database/constraints/index.js';
+//# sourceMappingURL=rtdb.js.map

package/dist/rules/rtdb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rtdb.js","sourceRoot":"","sources":["../../src/rules/rtdb.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,oBAAoB,GAErB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,UAAU,GACX,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,EACL,qBAAqB,EACrB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAMxC,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAKhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAcjE,OAAO,EACL,IAAI,EACJ,GAAG,EACH,GAAG,EACH,GAAG,EACH,IAAI,EACJ,MAAM,EACN,KAAK,EACL,aAAa,EACb,OAAO,EACP,QAAQ,EACR,KAAK,EACL,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EACb,cAAc,EACd,SAAS,EACT,SAAS,EACT,aAAa,EACb,UAAU,EACV,UAAU,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,OAAO,EACP,UAAU,EACV,UAAU,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,EAAE,EACF,GAAG,EACH,EAAE,EACF,GAAG,EACH,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,cAAc,EACd,WAAW,EACX,OAAO,EACP,eAAe,GAChB,MAAM,kCAAkC,CAAC"}

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

@@ -0,0 +1,179 @@
+/**
+ * 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;
+    resource: SimResource;
+    /** 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;
+    /** 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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"}