pyric 0.0.1 → 0.1.0-alpha.8

package/dist/rules/indexes/extract/types.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Types for the Layer-1 static query extractor.
+ *
+ * The extractor walks TypeScript/JavaScript source, finds Firestore
+ * `query(...)` chains (modular API), enumerates the conditional branches
+ * that may produce them, and emits one or more `QueryShape` per call site.
+ * Composite-index detection then reduces those shapes to an
+ * `IndexesConfig`-shaped output the deploy handler can consume directly.
+ *
+ * No logic in this file — these are the data contracts that the rest of
+ * the extract/ modules pass around.
+ */
+import type { IndexesConfig } from '../types.js';
+import type { Annotations, AnnotationWarning } from './annotations.js';
+export type { Annotations, AnnotationWarning } from './annotations.js';
+/**
+ * Per-function summary of which annotations applied during enumeration
+ * and how many shapes each pruned. Surfaced in `ExtractResult.data` so
+ * the agent can see whether its annotations had the intended effect.
+ */
+export interface AnnotationApplied {
+    /**
+     * The function the prune effect attributes to. For caller-owned
+     * annotations this is the function whose leading comment block carries
+     * them. For annotations on a wrapper that was inlined into a caller
+     * (Layer 2.5), this is the **caller** — the function whose enumerated
+     * shapes were pruned. `inlinedFrom` then names the wrapper.
+     */
+    functionName: string;
+    /** Source file the attributed function was declared in. */
+    file: string;
+    /** Annotations parsed from the source function's leading comment block. */
+    annotations: Annotations;
+    /** Shapes dropped because they violated a `@firestore-mutex` group. */
+    prunedByMutex: number;
+    /** Shapes dropped because they were missing a `@firestore-required` field. */
+    prunedByRequired: number;
+    /** Warnings raised while parsing the source function's annotations. */
+    warnings: AnnotationWarning[];
+    /**
+     * Set when the annotations originated on a wrapper that was inlined
+     * into `functionName`. Names the wrapper so the agent can navigate to
+     * the actual source of the annotation. Absent for caller-owned
+     * annotations.
+     */
+    inlinedFrom?: string;
+}
+/** A single `where("field", "op", value)` constraint. */
+export interface Filter {
+    field: string;
+    /** Operator string as it appears in source: "==", "<", ">=", "in", "array-contains", etc. */
+    op: string;
+}
+/** A single `orderBy("field", "asc"|"desc")` constraint. */
+export interface Order {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+/**
+ * One piece of a query chain produced by walking a function body.
+ *
+ * `kind: 'init'` describes the base — `query(collection(...))`. All other
+ * kinds describe constraints layered on top.
+ *
+ * `branchId`/`clauseId`/`skippable` describe the if/else context where
+ * the fragment was found. Two fragments under the same `branchId` but
+ * different `clauseId` are mutually exclusive. `skippable: true` means
+ * the if-chain has no `else`, so each clause is also "may not run at
+ * all" when enumerating combinations.
+ */
+export interface Fragment {
+    kind: 'init' | 'where' | 'orderBy' | 'limit' | 'unknown';
+    collectionPath?: string | null;
+    isCollectionGroup?: boolean;
+    filter?: Filter;
+    order?: Order;
+    limit?: number;
+    branchId: number | null;
+    clauseId: number | null;
+    skippable: boolean;
+}
+/**
+ * A single function's extracted query state — base + fragments — before
+ * branch enumeration. The orchestrator builds one of these per scanned
+ * function body.
+ */
+export interface QueryBaseDecl {
+    /** The local variable name the chain is built on (typically `q`). */
+    varName: string;
+    /** Last-segment-or-full literal collection path, or `null` if not statically resolvable. */
+    collectionPath: string | null;
+    /** True when the base was created via `collectionGroup(...)`. */
+    isCollectionGroup: boolean;
+    /** All fragments found in source order. */
+    fragments: Fragment[];
+    /**
+     * Names of functions whose bodies were inlined into this decl by the
+     * inter-procedural follower (Layer 2.5). Empty when no inlining
+     * happened. The orchestrator uses this to (a) suppress the
+     * `partial-base` warning for inlined wrappers and (b) attribute the
+     * wrapper's annotations to the caller's `AnnotationApplied` entry.
+     */
+    inlinedFunctions?: string[];
+    /**
+     * Inter-procedural follower diagnostics surfaced from inside the
+     * walker. The orchestrator promotes each into an `ExtractionWarning`.
+     * Optional — absent when no inter-proc work happened.
+     */
+    interProcWarnings?: {
+        code: 'inter-proc-nested' | 'inter-proc-recursion';
+        functionName: string;
+        message: string;
+    }[];
+}
+/**
+ * One enumerated query the source code may issue at runtime. Generated
+ * by the cartesian product across `branchId`s in a `QueryBaseDecl`.
+ */
+export interface QueryShape {
+    collectionPath: string;
+    isCollectionGroup: boolean;
+    filters: Filter[];
+    orders: Order[];
+    limit: number | null;
+}
+/**
+ * One signal the extractor surfaces for a given collection — used by
+ * the agent layer to decide whether to add `@firestore-mutex`
+ * annotations. A high count of shapes for one collection is the
+ * primary over-shoot signal.
+ */
+export interface ExtractionSignal {
+    collectionGroup: string;
+    /** How many shapes the extractor produced for this collection. */
+    shapeCount: number;
+    /**
+     * Distinct fields that appeared in any filter/orderBy across those shapes.
+     * If the count is high relative to typical query usage (≥ 4 fields), the
+     * agent should consider whether some are mutually exclusive.
+     */
+    fieldsTouched: string[];
+    /**
+     * `true` if the extractor produced more shapes than would typically be
+     * needed (heuristic: > 3 shapes for one collection). Hint for the
+     * agent layer to suggest annotations.
+     */
+    overshootSuspected: boolean;
+}
+/** Per-file diagnostic surfaced when the extractor can't fully resolve a query. */
+export interface ExtractionWarning {
+    /** Source file the warning is about. */
+    file: string;
+    /**
+     * - `'partial-base'` — the function body uses a `q` parameter; the
+     *   INIT site lives in a caller (inter-procedural following NYI).
+     * - `'unknown-callee'` — saw a call we don't recognize as
+     *   query/where/orderBy/limit/collection/collectionGroup.
+     * - `'dynamic-arg'` — a `where`/`orderBy` arg was non-literal.
+     * - `'dynamic-direction'` — `orderBy` direction wasn't literally
+     *   "asc"/"desc"; the extractor emitted both.
+     */
+    code: 'partial-base' | 'unknown-callee' | 'dynamic-arg' | 'dynamic-direction' | 'parse-error' | 'budget-exceeded' | 'annotation-malformed' | 'inter-proc-nested' | 'inter-proc-recursion';
+    message: string;
+}
+/**
+ * Final extractor output. The `config` field is shaped exactly like
+ * `firestore.indexes.json` so it can be passed directly to
+ * `firestore_deploy_indexes`.
+ */
+export type ExtractResult = {
+    success: true;
+    data: {
+        config: IndexesConfig;
+        signals: ExtractionSignal[];
+        warnings: ExtractionWarning[];
+        /** Total number of distinct query shapes the extractor enumerated. */
+        shapesEnumerated: number;
+        /**
+         * One entry per function whose leading comment block carried any
+         * `@firestore-*` activity (recognized tag or warning). Empty when
+         * no annotations were used.
+         */
+        annotationsApplied: AnnotationApplied[];
+    };
+} | {
+    success: false;
+    error: {
+        code: 'PARSE_FAILED' | 'EXTRACT_FAILED';
+        message: string;
+        recoverable: boolean;
+    };
+};
+/** Options passed to the extractor. */
+export interface ExtractOptions {
+    /**
+     * Bag of source files keyed by display name. The extractor processes
+     * each independently; inter-procedural call following across files
+     * is NYI (see I1 in the layer-1 progress doc).
+     */
+    files: {
+        name: string;
+        source: string;
+    }[];
+    /**
+     * Optional — the variable name typically used to chain queries.
+     * Defaults to `'q'`. Most Firebase example code uses `q`; if a
+     * codebase uses a different convention, override here.
+     */
+    queryVarName?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rules/indexes/extract/types.d.ts.map

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

package/dist/rules/indexes/extract/types.js

@@ -0,0 +1,14 @@
+/**
+ * Types for the Layer-1 static query extractor.
+ *
+ * The extractor walks TypeScript/JavaScript source, finds Firestore
+ * `query(...)` chains (modular API), enumerates the conditional branches
+ * that may produce them, and emits one or more `QueryShape` per call site.
+ * Composite-index detection then reduces those shapes to an
+ * `IndexesConfig`-shaped output the deploy handler can consume directly.
+ *
+ * No logic in this file — these are the data contracts that the rest of
+ * the extract/ modules pass around.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/rules/indexes/extract/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/rules/indexes/extract/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/rules/indexes/extractHandler.d.ts

@@ -0,0 +1,16 @@
+import type { ExtractResult } from './extract/types.js';
+export interface ExtractIndexesOptions {
+    /** Already-loaded source files. Either `files` or `paths` must be set. */
+    files?: {
+        name: string;
+        source: string;
+    }[];
+    /** Filesystem paths to read. Resolved against the process cwd. */
+    paths?: string[];
+    /** Variable name the extractor walks for the wrap pattern. Defaults to `q`. */
+    queryVarName?: string;
+}
+export declare class ExtractFirestoreIndexesHandler {
+    execute(options: ExtractIndexesOptions): ExtractResult;
+}
+//# sourceMappingURL=extractHandler.d.ts.map

package/dist/rules/indexes/extractHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractHandler.d.ts","sourceRoot":"","sources":["../../../src/rules/indexes/extractHandler.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAaxD,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,8BAA8B;IACzC,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa;CA6DvD"}

package/dist/rules/indexes/extractHandler.js

@@ -0,0 +1,100 @@
+/**
+ * Handler for `firestore_extract_indexes` — Layer 1 of the indexes
+ * pipeline. Statically analyzes JS/TS source for the modular Firestore
+ * client API's `query(collection(...), where(...), orderBy(...))`
+ * pattern and emits a `firestore.indexes.json`-shaped config plus
+ * over-shoot signals + diagnostics.
+ *
+ * The handler is a thin shell over `extractIndexes` from
+ * `./extract/extractor.ts`:
+ *   - If callers pass `paths`, read them from disk into the
+ *     `{ name, source }` shape the extractor expects.
+ *   - If callers pass `files` directly (already-loaded source), forward
+ *     them as-is.
+ *
+ * Unlike the deploy handler this needs no `AgentApp` — extraction is a
+ * pure local AST walk with no network or auth surface.
+ *
+ * BROWSER-CLEAN: no static node imports. The `paths` option (disk reads)
+ * acquires `node:fs`/`node:path` lazily via `process.getBuiltinModule` —
+ * no import statement exists for a bundler to chase, so this module (which
+ * the `pyric/rules` index exports, reachable from browser graphs) bundles
+ * clean. In a browser, `paths` returns a clear EXTRACT_FAILED instead;
+ * `files` (pre-loaded source — the browser shape) is unaffected.
+ */
+import { extractIndexes } from './extract/extractor.js';
+/** Lazily acquire the node builtins the `paths` branch needs. Returns null
+ *  outside node (or on node <20.16, which predates getBuiltinModule). */
+function nodeFsPath() {
+    const get = globalThis.process?.getBuiltinModule;
+    if (typeof get !== 'function')
+        return null;
+    const fs = get.call(process, 'node:fs');
+    const path = get.call(process, 'node:path');
+    if (!fs || !path)
+        return null;
+    return { readFileSync: fs.readFileSync, resolve: path.resolve };
+}
+export class ExtractFirestoreIndexesHandler {
+    execute(options) {
+        // Validate inputs before doing any work — the extractor itself
+        // tolerates an empty file list, but a caller passing neither
+        // `files` nor `paths` is almost certainly a bug.
+        const haveFiles = Array.isArray(options.files) && options.files.length > 0;
+        const havePaths = Array.isArray(options.paths) && options.paths.length > 0;
+        if (!haveFiles && !havePaths) {
+            return {
+                success: false,
+                error: {
+                    code: 'EXTRACT_FAILED',
+                    message: 'Must provide at least one of `files` or `paths`.',
+                    recoverable: true,
+                },
+            };
+        }
+        const files = [];
+        if (haveFiles)
+            files.push(...options.files);
+        if (havePaths) {
+            const node = nodeFsPath();
+            if (!node) {
+                return {
+                    success: false,
+                    error: {
+                        code: 'EXTRACT_FAILED',
+                        message: 'The `paths` option reads from disk and requires a Node runtime — pass `files` with pre-loaded source instead.',
+                        recoverable: true,
+                    },
+                };
+            }
+            for (const p of options.paths) {
+                const abs = node.resolve(p);
+                let source;
+                try {
+                    source = node.readFileSync(abs, 'utf-8');
+                }
+                catch (e) {
+                    // One unreadable path shouldn't kill the whole extraction —
+                    // the extractor will report per-file warnings for parse
+                    // errors, but reads happen here. Surface the read failure as
+                    // the same shape so callers don't need a separate code path.
+                    const message = e instanceof Error ? e.message : String(e);
+                    return {
+                        success: false,
+                        error: {
+                            code: 'EXTRACT_FAILED',
+                            message: `Failed to read '${p}': ${message}`,
+                            recoverable: false,
+                        },
+                    };
+                }
+                files.push({ name: p, source });
+            }
+        }
+        return extractIndexes({
+            files,
+            queryVarName: options.queryVarName,
+        });
+    }
+}
+//# sourceMappingURL=extractHandler.js.map

package/dist/rules/indexes/extractHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractHandler.js","sourceRoot":"","sources":["../../../src/rules/indexes/extractHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD;yEACyE;AACzE,SAAS,UAAU;IACjB,MAAM,GAAG,GAAI,UAA2E,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnH,IAAI,OAAO,GAAG,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAsE,CAAC;IAC7G,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAmD,CAAC;IAC9F,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,EAAE,YAAY,EAAE,EAAE,CAAC,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;AAClE,CAAC;AAWD,MAAM,OAAO,8BAA8B;IACzC,OAAO,CAAC,OAA8B;QACpC,+DAA+D;QAC/D,6DAA6D;QAC7D,iDAAiD;QACjD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3E,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3E,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,EAAE,CAAC;YAC7B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EAAE,kDAAkD;oBAC3D,WAAW,EAAE,IAAI;iBAClB;aACF,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAuC,EAAE,CAAC;QACrD,IAAI,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,GAAI,OAAO,CAAC,KAA4C,CAAC,CAAC;QAEpF,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;YAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE;wBACL,IAAI,EAAE,gBAAgB;wBACtB,OAAO,EAAE,+GAA+G;wBACxH,WAAW,EAAE,IAAI;qBAClB;iBACF,CAAC;YACJ,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,KAAM,EAAE,CAAC;gBAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBAC5B,IAAI,MAAc,CAAC;gBACnB,IAAI,CAAC;oBACH,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;gBAC3C,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,4DAA4D;oBAC5D,wDAAwD;oBACxD,6DAA6D;oBAC7D,6DAA6D;oBAC7D,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;oBAC3D,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE;4BACL,IAAI,EAAE,gBAAgB;4BACtB,OAAO,EAAE,mBAAmB,CAAC,MAAM,OAAO,EAAE;4BAC5C,WAAW,EAAE,KAAK;yBACnB;qBACF,CAAC;gBACJ,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QAED,OAAO,cAAc,CAAC;YACpB,KAAK;YACL,YAAY,EAAE,OAAO,CAAC,YAAY;SACnC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/rules/indexes/extractTool.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser-safe `firestore_extract_indexes` factory. Returns a single
+ * `ToolHandler` wrapping the inner `extractIndexes()` AST pass with
+ * inline `files` only (no `paths` mode — that's Node-only and lives
+ * on the legacy SDK's `firestore_extract_indexes` defineTool entry,
+ * soon to be retired).
+ *
+ * Split from the broader rules-tooling factories so browser callers
+ * (the playground's deploy + extract surfaces) can opt into just
+ * the static-analysis tool without pulling in any other rules
+ * machinery.
+ */
+import type { ToolHandler } from '@inbrowser/agent';
+export declare function createFirestoreExtractTool(): ToolHandler;
+//# sourceMappingURL=extractTool.d.ts.map

package/dist/rules/indexes/extractTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractTool.d.ts","sourceRoot":"","sources":["../../../src/rules/indexes/extractTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQpD,wBAAgB,0BAA0B,IAAI,WAAW,CAoDxD"}

package/dist/rules/indexes/extractTool.js

@@ -0,0 +1,55 @@
+import { extractIndexes } from './extract/extractor.js';
+export function createFirestoreExtractTool() {
+    return {
+        name: 'firestore_extract_indexes',
+        description: 'Statically extract composite-index requirements from JS/TS source that uses the Firebase modular SDK\'s `query(collection(...), where(...), orderBy(...))` pattern. Returns a `firestore.indexes.json`-shaped `config`, per-collection `signals` (overshootSuspected = enumerated shapes > 3 — cue to add JSDoc annotations on the function), `annotationsApplied`, and per-file `warnings`. Recognized JSDoc annotations: `@firestore-mutex { f1, f2 }` (drop combos with 2+ of these together), `@firestore-required f1, f2` (drop combos missing any required field), `@firestore-budget N` (soft cap; surfaces warning when exceeded). Layer 2.5 follows same-file wrapper calls one level deep. Limits: same-file only, single-level inlining, root-context only, chain var must appear by identifier in the args.',
+        parameters: {
+            type: 'object',
+            properties: {
+                files: {
+                    type: 'array',
+                    minItems: 1,
+                    description: 'Inline source files to scan.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string', description: 'File name for diagnostics — does not need to exist on disk.' },
+                            source: { type: 'string', description: 'JS/TS source to scan.' },
+                        },
+                        required: ['name', 'source'],
+                    },
+                },
+                queryVarName: {
+                    type: 'string',
+                    description: 'Variable name the extractor walks for the wrap pattern. Defaults to "q".',
+                },
+            },
+            required: ['files'],
+        },
+        async execute(args) {
+            const { files, queryVarName } = args;
+            try {
+                const result = extractIndexes({
+                    files,
+                    ...(queryVarName !== undefined && { queryVarName }),
+                });
+                return {
+                    ok: result.success,
+                    summary: result.success
+                        ? `Extracted ${result.data.config.indexes.length} composite index(es) from ${result.data.shapesEnumerated} query shape(s)`
+                        : `firestore_extract_indexes failed: ${result.error.message}`,
+                    data: result,
+                };
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return {
+                    ok: false,
+                    summary: `firestore_extract_indexes failed: ${message}`,
+                    data: { success: false, error: { code: 'EXTRACT_INDEXES_FAILED', message, recoverable: false } },
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=extractTool.js.map

package/dist/rules/indexes/extractTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractTool.js","sourceRoot":"","sources":["../../../src/rules/indexes/extractTool.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAOxD,MAAM,UAAU,0BAA0B;IACxC,OAAO;QACL,IAAI,EAAE,2BAA2B;QACjC,WAAW,EACT,yxBAAyxB;QAC3xB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,OAAO;oBACb,QAAQ,EAAE,CAAC;oBACX,WAAW,EAAE,8BAA8B;oBAC3C,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6DAA6D,EAAE;4BACpG,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,uBAAuB,EAAE;yBACjE;wBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;qBAC7B;iBACF;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,0EAA0E;iBACxF;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;QACD,KAAK,CAAC,OAAO,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAA0B,CAAC;YAC3D,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,cAAc,CAAC;oBAC5B,KAAK;oBACL,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,CAAC;iBACpD,CAAC,CAAC;gBACH,OAAO;oBACL,EAAE,EAAE,MAAM,CAAC,OAAO;oBAClB,OAAO,EAAE,MAAM,CAAC,OAAO;wBACrB,CAAC,CAAC,aAAa,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,6BAA6B,MAAM,CAAC,IAAI,CAAC,gBAAgB,iBAAiB;wBAC1H,CAAC,CAAC,qCAAqC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE;oBAC/D,IAAI,EAAE,MAAM;iBACb,CAAC;YACJ,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC3D,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,OAAO,EAAE,qCAAqC,OAAO,EAAE;oBACvD,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE;iBACjG,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/rules/indexes/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Firestore composite-index wire types.
+ *
+ * Mirrors the shape used by `firebase-tools/src/firestore/api-types.ts` and
+ * the v1 REST API at
+ * `firestore.googleapis.com/v1/projects/{p}/databases/{d}/collectionGroups/{g}/indexes`.
+ *
+ * The `firestore.indexes.json` file (the Firebase config file consumed by
+ * `firebase deploy --only firestore:indexes`) wraps these types with a
+ * top-level `indexes`/`fieldOverrides` envelope and adds a
+ * `collectionGroup` field to each entry. That shape is captured by
+ * `IndexesConfig` below.
+ */
+export type QueryScope = 'COLLECTION' | 'COLLECTION_GROUP';
+export type IndexFieldOrder = 'ASCENDING' | 'DESCENDING';
+export type ArrayConfig = 'CONTAINS';
+export type IndexState = 'CREATING' | 'READY' | 'NEEDS_REPAIR';
+export type ApiScope = 'ANY_API' | 'DATASTORE_MODE_API' | 'MONGODB_COMPATIBLE_API';
+export type Density = 'DENSE' | 'SPARSE_ALL' | 'SPARSE_ANY' | 'DENSITY_UNSPECIFIED';
+export interface VectorConfig {
+    dimension: number;
+    flat?: Record<string, never>;
+}
+export interface IndexField {
+    fieldPath: string;
+    order?: IndexFieldOrder;
+    arrayConfig?: ArrayConfig;
+    vectorConfig?: VectorConfig;
+}
+/** REST wire shape — the body posted to .../indexes. */
+export interface Index {
+    /** Server-assigned. Present on read responses, not on create requests. */
+    name?: string;
+    queryScope: QueryScope;
+    fields: IndexField[];
+    /** Server-assigned. */
+    state?: IndexState;
+    apiScope?: ApiScope;
+    density?: Density;
+    multikey?: boolean;
+    unique?: boolean;
+}
+/**
+ * The shape of `firestore.indexes.json`. Each entry adds `collectionGroup`
+ * (which the wire format conveys via the URL `parent` parameter, not the
+ * body) so the file is self-describing.
+ */
+export interface IndexesConfigEntry extends Index {
+    collectionGroup: string;
+}
+export interface IndexesConfig {
+    indexes: IndexesConfigEntry[];
+    fieldOverrides?: unknown[];
+}
+/**
+ * Long-running-operation handle returned by index creation. The full
+ * Operation resource has more fields; we only need name + done state for
+ * polling. See google.longrunning.Operation.
+ */
+export interface IndexOperation {
+    /** `projects/.../operations/<id>` — opaque. Use to poll status. */
+    name: string;
+    done?: boolean;
+    error?: {
+        code: number;
+        message: string;
+    };
+    /** When done and successful, response is the created Index. */
+    response?: Index;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rules/indexes/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rules/indexes/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,kBAAkB,CAAC;AAC3D,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,YAAY,CAAC;AACzD,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC;AACrC,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,cAAc,CAAC;AAE/D,MAAM,MAAM,QAAQ,GAChB,SAAS,GACT,oBAAoB,GACpB,wBAAwB,CAAC;AAE7B,MAAM,MAAM,OAAO,GACf,OAAO,GACP,YAAY,GACZ,YAAY,GACZ,qBAAqB,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,wDAAwD;AACxD,MAAM,WAAW,KAAK;IACpB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,uBAAuB;IACvB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,KAAK;IAC/C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB"}

package/dist/rules/indexes/types.js

@@ -0,0 +1,15 @@
+/**
+ * Firestore composite-index wire types.
+ *
+ * Mirrors the shape used by `firebase-tools/src/firestore/api-types.ts` and
+ * the v1 REST API at
+ * `firestore.googleapis.com/v1/projects/{p}/databases/{d}/collectionGroups/{g}/indexes`.
+ *
+ * The `firestore.indexes.json` file (the Firebase config file consumed by
+ * `firebase deploy --only firestore:indexes`) wraps these types with a
+ * top-level `indexes`/`fieldOverrides` envelope and adds a
+ * `collectionGroup` field to each entry. That shape is captured by
+ * `IndexesConfig` below.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rules/indexes/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

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

@@ -0,0 +1,6 @@
+import type { ProjectScope } from '../../project-scope.js';
+import type { InspectFirestoreRulesResult } from './spec.js';
+export declare class InspectFirestoreRulesHandler {
+    execute(scope: ProjectScope): Promise<InspectFirestoreRulesResult>;
+}
+//# sourceMappingURL=handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/rules/inspect/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,2BAA2B,EAAgB,MAAM,WAAW,CAAC;AAO3E,qBAAa,4BAA4B;IACjC,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,2BAA2B,CAAC;CA+FzE"}