pyric 0.0.1 → 0.1.0-alpha.10

package/dist/rules/api/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../../src/rules/api/lint.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE1E,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,MAAc;IACjC,MAAM,MAAM,GAAgB,EAAE,CAAC;IAE/B,IAAI,UAAiD,CAAC;IACtD,IAAI,CAAC;QACH,UAAU,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,qEAAqE;QACrE,wEAAwE;QACxE,OAAO;YACL;gBACE,IAAI,EAAE,qBAAqB;gBAC3B,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;gBACnD,MAAM,EAAE,MAAM;aACf;SACF,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,UAAU,EAAE,CAAC;QAC1B,oEAAoE;QACpE,sCAAsC;QACtC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;QACtD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,4EAA4E;IAC5E,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,GAAG,EAAE,CAAC;YACR,KAAK,MAAM,OAAO,IAAI,sBAAsB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClD,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,4CAA4C;IAC9C,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,33 @@
+/**
+ * `rtdbRules(...)` — the deep handle on a Realtime Database ruleset.
+ *
+ * Accepts any of three inputs and normalizes them to one handle:
+ *   - an {@link RtdbRulesDefinition} (the `{ paths }` object)
+ *   - the value {@link defineRtdbRules} returns (an {@link RtdbRulesDocument})
+ *   - compiled `{ rules }` JSON
+ *
+ * Every input supports the full surface. Compiled `{ rules }` JSON is mapped
+ * directly into the RTDB engine, so callers do not need a prior fetch/generate
+ * step before simulation. `toJSON` always returns compiled `rules.json`.
+ */
+import type { RtdbRulesDefinition, RtdbRulesDocument, RtdbRulesJson } from '../rtdb/constraints/document.js';
+import type { RuleIssue } from './issue.js';
+import type { RtdbCase, RtdbExplanation, RtdbSimulationSummary } from './case-types.js';
+export interface RtdbRuleset {
+    /** Structural findings on the compiled ruleset (from `check()`). */
+    lint(): RuleIssue[];
+    /** Run every case. Never throws on a rule outcome. */
+    simulate(cases: RtdbCase[]): RtdbSimulationSummary;
+    /** The structured account of why one case resolved as it did. */
+    explain(oneCase: RtdbCase): RtdbExplanation;
+    /** The compiled `rules.json`. */
+    toJSON(): RtdbRulesJson;
+}
+type RtdbRulesInput = RtdbRulesDefinition | RtdbRulesDocument | RtdbRulesJson;
+/**
+ * Build a deep handle on a Realtime Database ruleset from a definition, a
+ * compiled document, or compiled `{ rules }` JSON.
+ */
+export declare function rtdbRules(input: RtdbRulesInput): RtdbRuleset;
+export {};
+//# sourceMappingURL=rtdb.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rtdb.d.ts","sourceRoot":"","sources":["../../../src/rules/api/rtdb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAEjB,aAAa,EAGd,MAAM,iCAAiC,CAAC;AAOzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EACV,QAAQ,EAER,eAAe,EACf,qBAAqB,EACtB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,IAAI,IAAI,SAAS,EAAE,CAAC;IACpB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,qBAAqB,CAAC;IACnD,iEAAiE;IACjE,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,eAAe,CAAC;IAC5C,iCAAiC;IACjC,MAAM,IAAI,aAAa,CAAC;CACzB;AAED,KAAK,cAAc,GACf,mBAAmB,GACnB,iBAAiB,GACjB,aAAa,CAAC;AAqJlB;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAQ5D"}

package/dist/rules/api/rtdb.js

@@ -0,0 +1,166 @@
+/**
+ * `rtdbRules(...)` — the deep handle on a Realtime Database ruleset.
+ *
+ * Accepts any of three inputs and normalizes them to one handle:
+ *   - an {@link RtdbRulesDefinition} (the `{ paths }` object)
+ *   - the value {@link defineRtdbRules} returns (an {@link RtdbRulesDocument})
+ *   - compiled `{ rules }` JSON
+ *
+ * Every input supports the full surface. Compiled `{ rules }` JSON is mapped
+ * directly into the RTDB engine, so callers do not need a prior fetch/generate
+ * step before simulation. `toJSON` always returns compiled `rules.json`.
+ */
+import { defineRtdbRules } from '../rtdb/constraints/document.js';
+import { compileRtdbRules, simulateRtdbRules, } from '../rtdb/compiled-rules.js';
+import { rtdbFindingToIssue } from './issue.js';
+function isDocument(x) {
+    const o = x;
+    return (typeof o.toJSON === 'function' &&
+        typeof o.simulate === 'function' &&
+        typeof o.check === 'function');
+}
+function isCompiledJson(x) {
+    const o = x;
+    return (typeof o === 'object' &&
+        o !== null &&
+        'rules' in o &&
+        !('paths' in o) &&
+        typeof o.toJSON !== 'function');
+}
+/** A document-backed handle — the full-featured path. */
+class DocumentRtdbRuleset {
+    doc;
+    constructor(doc) {
+        this.doc = doc;
+    }
+    lint() {
+        const check = this.doc.check();
+        return [
+            ...check.errors.map((f) => rtdbFindingToIssue(f, 'error')),
+            ...check.warnings.map((f) => rtdbFindingToIssue(f, 'warning')),
+        ];
+    }
+    runOne(c) {
+        const result = this.doc.simulate({
+            operation: c.operation,
+            path: c.path,
+            auth: c.auth ?? null,
+            ...(c.data !== undefined ? { data: c.data } : {}),
+            ...(c.newData !== undefined ? { newData: c.newData } : {}),
+        });
+        if (!result.success) {
+            // Could not evaluate — report as unsupported rather than throw.
+            return {
+                case: c,
+                ...(c.description !== undefined ? { description: c.description } : {}),
+                expectation: c.expectation,
+                decision: 'UNSUPPORTED',
+                passed: false,
+                unsupported: true,
+                matchedPath: c.path,
+                matchedRule: c.operation,
+                reason: result.error.message,
+            };
+        }
+        const data = result.data;
+        const unsupported = data.unsupported === true;
+        const decision = unsupported
+            ? 'UNSUPPORTED'
+            : data.allowed
+                ? 'ALLOW'
+                : 'DENY';
+        const passed = !unsupported && decision === c.expectation;
+        return {
+            case: c,
+            ...(c.description !== undefined ? { description: c.description } : {}),
+            expectation: c.expectation,
+            decision,
+            passed,
+            unsupported,
+            matchedPath: data.matchedPath,
+            matchedRule: data.matchedRule,
+            reason: data.reason,
+        };
+    }
+    simulate(cases) {
+        const caseResults = cases.map((c) => this.runOne(c));
+        let passed = 0;
+        let failed = 0;
+        let unsupported = 0;
+        for (const r of caseResults) {
+            if (r.unsupported)
+                unsupported++;
+            else if (r.passed)
+                passed++;
+            else
+                failed++;
+        }
+        return { passed, failed, unsupported, cases: caseResults };
+    }
+    explain(oneCase) {
+        const r = this.runOne(oneCase);
+        return {
+            decision: r.decision,
+            expectation: r.expectation,
+            passed: r.passed,
+            unsupported: r.unsupported,
+            matchedPath: r.matchedPath,
+            matchedRule: r.matchedRule,
+            reason: r.reason,
+        };
+    }
+    toJSON() {
+        return this.doc.toJSON();
+    }
+}
+function normalizeAuth(auth) {
+    if (auth === undefined || auth === null)
+        return null;
+    if (typeof auth === 'string')
+        return { uid: auth, token: {} };
+    return { uid: auth.uid, token: auth.token ?? {} };
+}
+/** Internal document adapter for already-compiled Firebase rules JSON. */
+class CompiledRtdbRulesDocument {
+    json;
+    compiled;
+    constructor(json) {
+        this.json = json;
+        this.compiled = compileRtdbRules(json);
+    }
+    toJSON() {
+        return this.json;
+    }
+    compile() {
+        return this.compiled;
+    }
+    check() {
+        return {
+            ok: true,
+            errors: [],
+            warnings: [],
+        };
+    }
+    simulate(input) {
+        return simulateRtdbRules(this.compiled, {
+            operation: input.operation,
+            path: input.path,
+            auth: normalizeAuth(input.auth),
+            mockData: input.mockData ?? input.data ?? {},
+            ...(input.newData !== undefined ? { newData: input.newData } : {}),
+        });
+    }
+}
+/**
+ * Build a deep handle on a Realtime Database ruleset from a definition, a
+ * compiled document, or compiled `{ rules }` JSON.
+ */
+export function rtdbRules(input) {
+    if (isDocument(input))
+        return new DocumentRtdbRuleset(input);
+    if (isCompiledJson(input)) {
+        return new DocumentRtdbRuleset(new CompiledRtdbRulesDocument(input));
+    }
+    return new DocumentRtdbRuleset(defineRtdbRules(input));
+}
+//# sourceMappingURL=rtdb.js.map

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

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

package/dist/rules/api/values.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Value helpers — small named constructors for the typed values a rules
+ * case carries in its `data` / `resource`.
+ *
+ * These wrap the engine's value-wrapper classes (`Timestamp`, `Bytes`,
+ * `LatLng`, …). The classes themselves are engine-internal: a caller writing
+ * a case should not have to know whether `bytes("hi")` is a class instance
+ * or a tagged object, only that it is "the bytes value for these contents".
+ * The helpers give the front door a stable, class-free vocabulary.
+ */
+import { Timestamp } from '../simulator/wrappers/timestamp.js';
+import { Bytes } from '../simulator/wrappers/bytes.js';
+import { LatLng } from '../simulator/wrappers/latlng.js';
+import { Duration } from '../simulator/wrappers/duration.js';
+import { Reference } from '../simulator/wrappers/reference.js';
+import { Vector } from '../simulator/wrappers/vector.js';
+import { SERVER_TIMESTAMP } from '../simulator/handler.js';
+/**
+ * The server-timestamp sentinel — the case-data equivalent of
+ * `FieldValue.serverTimestamp()`. The simulator resolves it to the request
+ * time, so a rule comparing `data.createdAt == request.time` sees a match.
+ */
+export declare function serverTimestamp(): typeof SERVER_TIMESTAMP;
+/**
+ * A Firestore `timestamp` value.
+ *   - number → milliseconds since the epoch
+ *   - string → ISO-8601
+ *   - object → explicit `{ seconds, nanos }`
+ */
+export declare function timestamp(input: number | string | {
+    seconds: number;
+    nanos?: number;
+}): Timestamp;
+/**
+ * A `bytes` value.
+ *   - string     → UTF-8 encoded
+ *   - Uint8Array → used verbatim
+ */
+export declare function bytes(input: string | Uint8Array): Bytes;
+/** A `latlng` geographic point. */
+export declare function latlng(lat: number, lng: number): LatLng;
+/**
+ * A `duration` value. `unit` is one of the Firestore duration units
+ * (`'w' | 'd' | 'h' | 'm' | 's' | 'ms' | 'ns'`); defaults to seconds.
+ */
+export declare function duration(value: number, unit?: string): Duration;
+/** A `reference` to a document, by its path (e.g. `"users/alice"`). */
+export declare function reference(path: string): Reference;
+/** A `vector` value from its numeric components. */
+export declare function vector(values: readonly number[]): Vector;
+//# sourceMappingURL=values.d.ts.map

package/dist/rules/api/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../../src/rules/api/values.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,OAAO,gBAAgB,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3D,SAAS,CAIX;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,CAEvD;AAED,mCAAmC;AACnC,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAY,GAAG,QAAQ,CAEpE;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAEjD;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAExD"}

package/dist/rules/api/values.js

@@ -0,0 +1,66 @@
+/**
+ * Value helpers — small named constructors for the typed values a rules
+ * case carries in its `data` / `resource`.
+ *
+ * These wrap the engine's value-wrapper classes (`Timestamp`, `Bytes`,
+ * `LatLng`, …). The classes themselves are engine-internal: a caller writing
+ * a case should not have to know whether `bytes("hi")` is a class instance
+ * or a tagged object, only that it is "the bytes value for these contents".
+ * The helpers give the front door a stable, class-free vocabulary.
+ */
+import { Timestamp } from '../simulator/wrappers/timestamp.js';
+import { Bytes } from '../simulator/wrappers/bytes.js';
+import { LatLng } from '../simulator/wrappers/latlng.js';
+import { Duration } from '../simulator/wrappers/duration.js';
+import { Reference } from '../simulator/wrappers/reference.js';
+import { Vector } from '../simulator/wrappers/vector.js';
+import { SERVER_TIMESTAMP } from '../simulator/handler.js';
+/**
+ * The server-timestamp sentinel — the case-data equivalent of
+ * `FieldValue.serverTimestamp()`. The simulator resolves it to the request
+ * time, so a rule comparing `data.createdAt == request.time` sees a match.
+ */
+export function serverTimestamp() {
+    return SERVER_TIMESTAMP;
+}
+/**
+ * A Firestore `timestamp` value.
+ *   - number → milliseconds since the epoch
+ *   - string → ISO-8601
+ *   - object → explicit `{ seconds, nanos }`
+ */
+export function timestamp(input) {
+    if (typeof input === 'number')
+        return Timestamp.fromMillis(input);
+    if (typeof input === 'string')
+        return Timestamp.fromIsoString(input);
+    return new Timestamp(input.seconds, input.nanos ?? 0);
+}
+/**
+ * A `bytes` value.
+ *   - string     → UTF-8 encoded
+ *   - Uint8Array → used verbatim
+ */
+export function bytes(input) {
+    return typeof input === 'string' ? Bytes.fromUtf8(input) : new Bytes(input);
+}
+/** A `latlng` geographic point. */
+export function latlng(lat, lng) {
+    return new LatLng(lat, lng);
+}
+/**
+ * A `duration` value. `unit` is one of the Firestore duration units
+ * (`'w' | 'd' | 'h' | 'm' | 's' | 'ms' | 'ns'`); defaults to seconds.
+ */
+export function duration(value, unit = 's') {
+    return Duration.fromValue(value, unit);
+}
+/** A `reference` to a document, by its path (e.g. `"users/alice"`). */
+export function reference(path) {
+    return new Reference(path);
+}
+/** A `vector` value from its numeric components. */
+export function vector(values) {
+    return new Vector(values);
+}
+//# sourceMappingURL=values.js.map

package/dist/rules/api/values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.js","sourceRoot":"","sources":["../../../src/rules/api/values.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,KAA4D;IAE5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACrE,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,KAA0B;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,GAAW;IAC7C,OAAO,IAAI,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,OAAe,GAAG;IACxD,OAAO,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,MAAM,CAAC,MAAyB;IAC9C,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/rules/generators/assembler.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Assembles a complete Firestore security rules file for a grid-based game.
+ *
+ * Optimization levels (applied automatically based on board size):
+ * - Small boards (≤42 cells): nested board map, static enumeration, single win function
+ * - Medium boards (43-121 cells): flat layout, dynamic access, MapDiff, directional win split
+ *
+ * Uses the stdlib convention: host/guest/currentTurn/status.
+ */
+import type { GridConfig } from './grid.js';
+export interface GameConfig {
+    collection: string;
+    grid: GridConfig;
+    winLineCount: number;
+    hasGravity: boolean;
+    hasLobby: boolean;
+}
+export declare function assembleGameRules(config: GameConfig): string;
+//# sourceMappingURL=assembler.d.ts.map

package/dist/rules/generators/assembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembler.d.ts","sourceRoot":"","sources":["../../../src/rules/generators/assembler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAW5C,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AA0BD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAW5D"}

package/dist/rules/generators/assembler.js

@@ -0,0 +1,292 @@
+/**
+ * Assembles a complete Firestore security rules file for a grid-based game.
+ *
+ * Optimization levels (applied automatically based on board size):
+ * - Small boards (≤42 cells): nested board map, static enumeration, single win function
+ * - Medium boards (43-121 cells): flat layout, dynamic access, MapDiff, directional win split
+ *
+ * Uses the stdlib convention: host/guest/currentTurn/status.
+ */
+import { generateWinLines } from './grid.js';
+import { winCheckExpr, splitWinLinesByDirection, gravityExpr, cellEmptyExpr, boardIntegrityExpr, placementExpr, } from './expressions.js';
+const SMALL_BOARD_THRESHOLD = 42;
+/** A single Firestore path segment we are willing to interpolate into a
+ *  `match /<collection>/{gameId}` block. Deliberately stricter than
+ *  Firestore's own collection-id rules: alphanumerics, dash, underscore,
+ *  1–64 chars. Anything else (slashes, braces, whitespace, newlines) could
+ *  break out of the match block and inject arbitrary rules, so we reject it
+ *  rather than escape it. */
+const COLLECTION_SEGMENT = /^[A-Za-z0-9_-]{1,64}$/;
+/** Validate a caller-supplied collection name before it is interpolated into
+ *  generated rules source. Throws on anything that isn't a plain path
+ *  segment — every caller of the public `pyric/rules` generator is safe by
+ *  default, no escaping required at the call site. */
+function assertSafeCollection(collection) {
+    if (typeof collection !== 'string' || !COLLECTION_SEGMENT.test(collection)) {
+        throw new Error(`assembleGameRules: invalid collection ${JSON.stringify(collection)} — ` +
+            `must match ${COLLECTION_SEGMENT} (a single Firestore path segment: ` +
+            `letters, digits, "-" or "_", 1–64 chars). Rejected to prevent rules injection.`);
+    }
+}
+export function assembleGameRules(config) {
+    const { grid, winLineCount, hasGravity, hasLobby, collection } = config;
+    assertSafeCollection(collection);
+    const totalCells = grid.cols * grid.rows;
+    const lines = generateWinLines(grid.cols, grid.rows, winLineCount);
+    const useOptimized = totalCells > SMALL_BOARD_THRESHOLD;
+    if (useOptimized) {
+        return assembleOptimized(config, lines);
+    }
+    return assembleClassic(config, lines);
+}
+// ---- Classic: nested board map, static enumeration ----
+function assembleClassic(config, lines) {
+    const { grid, hasGravity, hasLobby, collection } = config;
+    const totalCells = grid.cols * grid.rows;
+    const placementChecks = [`(${placementExpr(grid)})`];
+    if (hasGravity) {
+        placementChecks.unshift(`(${gravityExpr(grid)})`);
+    }
+    else {
+        placementChecks.unshift(`(${cellEmptyExpr(grid)})`);
+    }
+    const validMoveBody = placementChecks.join('\n          && ');
+    const integrityBody = boardIntegrityExpr(grid);
+    const commonMove = `request.auth != null
+        && resource.data.status == 'playing'
+        && (
+          (resource.data.currentTurn == 'host' && request.auth.uid == resource.data.host)
+          || (resource.data.currentTurn == 'guest' && request.auth.uid == resource.data.guest)
+        )
+        && (
+          (resource.data.currentTurn == 'host' && request.resource.data.currentTurn == 'guest')
+          || (resource.data.currentTurn == 'guest' && request.resource.data.currentTurn == 'host')
+        )
+        && request.resource.data.moveCount == resource.data.moveCount + 1
+        && request.resource.data.host == resource.data.host
+        && request.resource.data.guest == resource.data.guest`;
+    const locChecks = `&& request.resource.data.lastCol >= 0 && request.resource.data.lastCol <= ${grid.cols - 1}
+        && request.resource.data.lastRow >= 0 && request.resource.data.lastRow <= ${grid.rows - 1}`;
+    return `rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+
+    function hasWonHost(b) {
+      return ${winCheckExpr('host', lines, grid)};
+    }
+
+    function hasWonGuest(b) {
+      return ${winCheckExpr('guest', lines, grid)};
+    }
+
+    function validMove(nc, nr, mark, b, ob) {
+      return ${validMoveBody};
+    }
+
+    function boardOk(nc, nr, b, ob) {
+      return ${integrityBody};
+    }
+
+    match /${collection}/{gameId} {
+      allow read: if request.auth != null;
+${lobbyRules(hasLobby)}
+      // --- Normal move (game continues) ---
+      allow update: if ${commonMove}
+        ${locChecks}
+        && request.resource.data.status == 'playing'
+        && request.resource.data.winner == ''
+        && validMove(
+            request.resource.data.lastCol,
+            request.resource.data.lastRow,
+            resource.data.currentTurn,
+            request.resource.data.board,
+            resource.data.board
+          )${totalCells <= SMALL_BOARD_THRESHOLD ? `
+        && boardOk(
+            request.resource.data.lastCol,
+            request.resource.data.lastRow,
+            request.resource.data.board,
+            resource.data.board
+          )` : ''};
+
+      // --- Winning move (host) ---
+      allow update: if ${commonMove}
+        ${locChecks}
+        && request.resource.data.status == 'won'
+        && request.resource.data.winner == 'host'
+        && hasWonHost(request.resource.data.board);
+
+      // --- Winning move (guest) ---
+      allow update: if ${commonMove}
+        ${locChecks}
+        && request.resource.data.status == 'won'
+        && request.resource.data.winner == 'guest'
+        && hasWonGuest(request.resource.data.board);
+
+      // --- Draw ---
+      allow update: if ${commonMove}
+        && request.resource.data.moveCount == ${totalCells}
+        && request.resource.data.status == 'draw'
+        && request.resource.data.winner == '';
+    }
+  }
+}
+`;
+}
+// ---- Optimized: flat layout, dynamic access, MapDiff, directional win split ----
+function assembleOptimized(config, lines) {
+    const { grid, hasGravity, hasLobby, collection } = config;
+    const totalCells = grid.cols * grid.rows;
+    const dirs = splitWinLinesByDirection(lines, grid.cols);
+    function dirWinFn(name, mark, dirLines) {
+        if (dirLines.length === 0)
+            return `    function ${name}(b) { return false; }`;
+        return `    function ${name}(b) {
+      return ${winCheckExpr(mark, dirLines, grid)};
+    }`;
+    }
+    const winFunctions = [
+        dirWinFn('wonHH', 'host', dirs.horizontal),
+        dirWinFn('wonHV', 'host', dirs.vertical),
+        dirWinFn('wonHD1', 'host', dirs.diagUp),
+        dirWinFn('wonHD2', 'host', dirs.diagDown),
+        dirWinFn('wonGH', 'guest', dirs.horizontal),
+        dirWinFn('wonGV', 'guest', dirs.vertical),
+        dirWinFn('wonGD1', 'guest', dirs.diagUp),
+        dirWinFn('wonGD2', 'guest', dirs.diagDown),
+    ].join('\n\n');
+    const commonMove = `request.auth != null
+        && resource.data.status == 'playing'
+        && (
+          (resource.data.currentTurn == 'host' && request.auth.uid == resource.data.host)
+          || (resource.data.currentTurn == 'guest' && request.auth.uid == resource.data.guest)
+        )
+        && (
+          (resource.data.currentTurn == 'host' && request.resource.data.currentTurn == 'guest')
+          || (resource.data.currentTurn == 'guest' && request.resource.data.currentTurn == 'host')
+        )
+        && request.resource.data.moveCount == resource.data.moveCount + 1
+        && request.resource.data.host == resource.data.host
+        && request.resource.data.guest == resource.data.guest`;
+    // Dynamic cell validation + MapDiff integrity
+    const dynamicPlacement = `&& resource.data[request.resource.data.lastMove] == ''
+        && request.resource.data[request.resource.data.lastMove] == resource.data.currentTurn
+        && request.resource.data.diff(resource.data).affectedKeys().hasOnly(
+            ['lastMove', 'currentTurn', 'moveCount', request.resource.data.lastMove]
+          )`;
+    const dynamicWinPlacement = `&& resource.data[request.resource.data.lastMove] == ''
+        && request.resource.data[request.resource.data.lastMove] == resource.data.currentTurn`;
+    return `rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+
+${winFunctions}
+
+    match /${collection}/{gameId} {
+      allow read: if request.auth != null;
+${lobbyRulesOptimized(hasLobby)}
+      // --- Normal move (flat layout + MapDiff integrity) ---
+      allow update: if ${commonMove}
+        ${dynamicPlacement}
+        && request.resource.data.status == 'playing'
+        && request.resource.data.winner == '';
+
+      // --- Winning move (host) ---
+      allow update: if ${commonMove}
+        ${dynamicWinPlacement}
+        && request.resource.data.status == 'won'
+        && request.resource.data.winner == 'host'
+        && (wonHH(request.resource.data) || wonHV(request.resource.data) || wonHD1(request.resource.data) || wonHD2(request.resource.data));
+
+      // --- Winning move (guest) ---
+      allow update: if ${commonMove}
+        ${dynamicWinPlacement}
+        && request.resource.data.status == 'won'
+        && request.resource.data.winner == 'guest'
+        && (wonGH(request.resource.data) || wonGV(request.resource.data) || wonGD1(request.resource.data) || wonGD2(request.resource.data));
+
+      // --- Draw ---
+      allow update: if ${commonMove}
+        && request.resource.data.moveCount == ${totalCells}
+        && request.resource.data.status == 'draw'
+        && request.resource.data.winner == '';
+    }
+  }
+}
+`;
+}
+// ---- Lobby rules ----
+function lobbyRules(hasLobby) {
+    if (!hasLobby)
+        return `
+      allow create: if request.auth != null
+        && request.resource.data.host == request.auth.uid
+        && request.resource.data.currentTurn == 'host'
+        && request.resource.data.status == 'playing'
+        && request.resource.data.winner == ''
+        && request.resource.data.moveCount == 0;
+`;
+    return `
+      allow create: if request.auth != null
+        && request.resource.data.host == request.auth.uid
+        && request.resource.data.guest == ''
+        && request.resource.data.currentTurn == 'host'
+        && request.resource.data.status == 'waiting'
+        && request.resource.data.winner == ''
+        && request.resource.data.moveCount == 0
+        && request.resource.data.lastCol == -1
+        && request.resource.data.lastRow == -1;
+
+      allow update: if request.auth != null
+        && resource.data.status == 'waiting'
+        && request.resource.data.status == 'playing'
+        && resource.data.guest == ''
+        && request.resource.data.guest == request.auth.uid
+        && request.auth.uid != resource.data.host
+        && request.resource.data.host == resource.data.host
+        && request.resource.data.currentTurn == resource.data.currentTurn
+        && request.resource.data.winner == resource.data.winner
+        && request.resource.data.moveCount == resource.data.moveCount
+        && request.resource.data.lastCol == resource.data.lastCol
+        && request.resource.data.lastRow == resource.data.lastRow
+        && request.resource.data.board == resource.data.board;
+
+      allow delete: if request.auth != null
+        && resource.data.status == 'waiting'
+        && request.auth.uid == resource.data.host;
+`;
+}
+function lobbyRulesOptimized(hasLobby) {
+    if (!hasLobby)
+        return `
+      allow create: if request.auth != null
+        && request.resource.data.host == request.auth.uid
+        && request.resource.data.currentTurn == 'host'
+        && request.resource.data.status == 'playing'
+        && request.resource.data.winner == ''
+        && request.resource.data.moveCount == 0;
+`;
+    return `
+      allow create: if request.auth != null
+        && request.resource.data.host == request.auth.uid
+        && request.resource.data.guest == ''
+        && request.resource.data.currentTurn == 'host'
+        && request.resource.data.status == 'waiting'
+        && request.resource.data.winner == ''
+        && request.resource.data.moveCount == 0
+        && request.resource.data.lastMove == '';
+
+      allow update: if request.auth != null
+        && resource.data.status == 'waiting'
+        && request.resource.data.status == 'playing'
+        && resource.data.guest == ''
+        && request.resource.data.guest == request.auth.uid
+        && request.auth.uid != resource.data.host
+        && request.resource.data.diff(resource.data).affectedKeys().hasOnly(['guest', 'status']);
+
+      allow delete: if request.auth != null
+        && resource.data.status == 'waiting'
+        && request.auth.uid == resource.data.host;
+`;
+}
+//# sourceMappingURL=assembler.js.map