pyric 0.0.1 → 0.1.0-alpha.8

package/dist/rules/index.js

@@ -0,0 +1,80 @@
+/**
+ * `pyric/rules` — Pyric-native Firestore rules tooling.
+ *
+ * Sibling to `pyric/firestore` (the modular Web-SDK swap-in). Rules
+ * tooling lives here so non-standard surface (linter, parser, etc.)
+ * doesn't pollute the swap-in namespace.
+ *
+ * Surface:
+ *   - Parser + AST (parser/AST/validator/assembler)
+ *   - Linter (`lintFirestoreRules` + warning/metrics types)
+ *   - 2+modules resolver (`resolveModules`) + stdlib
+ *   - Rules simulator (`SimulateFirestoreRulesHandler` + value
+ *     wrappers — `Timestamp`, `Path`, etc.)
+ *   - Rules Test API client (`TestFirestoreRulesHandler`, takes
+ *     `ProjectScope` per F3)
+ *   - Sentinel expression engine (used by sandbox for $expr
+ *     resolution in declarative transactions)
+ */
+// ─── Parser + AST ────────────────────────────────────────────────────
+export { parseToAST, parseToASTOrError, parseFunctions, } from './grammar/FirestoreParser.js';
+export { assembleRules, assembleExpression as printExpression } from './grammar/FirestoreAssembler.js';
+export { validateFirestoreRules } from './grammar/FirestoreValidator.js';
+// ─── Linter ──────────────────────────────────────────────────────────
+export { lintFirestoreRules } from './linter/linter.js';
+// ─── Rules simulator ─────────────────────────────────────────────────
+export { SimulateFirestoreRulesHandler, SERVER_TIMESTAMP } from './simulator/handler.js';
+export { evaluate, UnsupportedError, TraceRecorder } from './simulator/evaluator.js';
+export { projectAfterState } from './simulator/project-after-state.js';
+export { MapDiff, FirestoreSet } from './simulator/mapdiff.js';
+// ─── Expression DSL primitives (used by sdk's transaction probe + tests)
+export { tokenize } from './simulator/expression/lexer.js';
+export { parse } from './simulator/expression/parser.js';
+// ─── Value wrappers ──────────────────────────────────────────────────
+export { Timestamp } from './simulator/wrappers/timestamp.js';
+export { Path } from './simulator/wrappers/path.js';
+export { Reference, referenceToResourceName } from './simulator/wrappers/reference.js';
+export { Vector } from './simulator/wrappers/vector.js';
+export { Bytes } from './simulator/wrappers/bytes.js';
+export { Duration } from './simulator/wrappers/duration.js';
+export { LatLng } from './simulator/wrappers/latlng.js';
+export { RulesValue, NO_OP } from './simulator/wrappers/base.js';
+// ─── Rules Test API client ───────────────────────────────────────────
+export { TestFirestoreRulesHandler } from './test/handler.js';
+export { FIRESTORE_METHODS, TestCaseSchema, TestIdentitySchema, renderLegacyDebugMessages, projectEvaluatedRule, } from './test/spec.js';
+// ─── Sentinel expression engine ──────────────────────────────────────
+export { resolveExpressionsInData, ExpressionWalkError } from './simulator/expression/walk-data.js';
+export { EvalError } from './simulator/expression/eval-errors.js';
+export { ExpressionLexError, ExpressionParseError, } from './simulator/expression/types.js';
+// ─── Stdlib reference (browser-safe — pure data) ─────────────────────
+// Module-organized reference an agent can call before writing rules.
+// Exposed via the `firestore_rules_stdlib_list` + `_get` tools in
+// `createFirestoreRulesStdlibTools()`; also importable directly for
+// non-agent consumers (docs generators, lint integrations).
+export { STDLIB_MODULES, findModuleByKey, allModuleKeys, suggestKey, } from './stdlib-modules.js';
+export { createFirestoreRulesStdlibTools } from './stdlib-tools.js';
+// Browser-safe `2+modules` resolver — pre-supplies the inlined stdlib
+// content so it works without `node:fs`. Node consumers should keep
+// importing `resolveModules` from `pyric/rules/node`,
+// which falls back to disk reads for stdlib modules and picks up
+// `.rules` edits between builds without re-running the inliner.
+export { resolveModulesBrowser, STDLIB_INLINE } from './modules/resolver-browser.js';
+// ─── Rules deploy (write) — Firebase Rules API client ─────────────────
+// Takes ProjectScope (per F3). Pairs with `firestore_test_rules`
+// (also takes ProjectScope) and `lintFirestoreRules` / `validateFirestoreRules`
+// in the same package — full rules lifecycle on one surface.
+export { WriteFirestoreRulesHandler } from './write/handler.js';
+// ─── Rules inspect (read) — Firebase Rules API client ─────────────────
+// Fetches + parses the deployed Firestore ruleset (list + get latest),
+// returns AST + summary + validator findings. Takes ProjectScope (per
+// F3). Browser-safe — REST + Bearer token only, no firebase-admin.
+// Pairs with WriteFirestoreRulesHandler on the write side.
+export { InspectFirestoreRulesHandler } from './inspect/handler.js';
+export { createFirestoreInspectTool } from './inspect/tools.js';
+// ─── Game-rules generators — declarative rules assembly ───────────────
+// Used by playground game scaffolding to emit Firestore rules for grid
+// games (TTT, C4, Gomoku) without hand-writing the boilerplate.
+export { assembleGameRules, } from './generators/assembler.js';
+export { generateWinLines, defaultCellName, indexToColRow, emptyBoard, } from './generators/grid.js';
+export * from './generators/expressions.js';
+//# sourceMappingURL=index.js.map

package/dist/rules/index.js.map

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

package/dist/rules/indexes/extract/annotation-collect.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AST walker that pairs each function-like declaration with its leading
+ * JSDoc-style comment block, parses any `@firestore-*` tags out of it,
+ * and yields the parsed annotations alongside the function name.
+ *
+ * Pure walker — no enumeration logic, no pruning. The orchestrator
+ * (`extractor.ts`) consumes these and threads them into `enumerateShapes`.
+ *
+ * Coverage matches `iterFunctionBodies` (see Issue A1 in the layer-2
+ * progress doc):
+ *   - function declarations
+ *   - arrow / function expressions assigned to a variable
+ * Method declarations on classes are deliberately out of scope for v1
+ * because Firebase query builders are almost never methods. Add when
+ * real-world demand surfaces.
+ */
+import ts from 'typescript';
+import { type AnnotationWarning, type Annotations } from './annotations.js';
+/** One function paired with its parsed annotations. */
+export interface CollectedAnnotation {
+    /** Function name, or `'<anon>'` for an unnamed function expression. */
+    functionName: string;
+    /** Annotations parsed from the function's leading comment block. */
+    annotations: Annotations;
+    /** Warnings raised while parsing those annotations. */
+    warnings: AnnotationWarning[];
+    /**
+     * `true` when the leading comment block contained at least one
+     * `@firestore-*` tag (recognized or not). Useful so the orchestrator
+     * can skip emitting an `AnnotationApplied` summary for functions
+     * without any annotation activity.
+     */
+    hasFirestoreTag: boolean;
+}
+/**
+ * Walk every function-like declaration in a SourceFile and yield one
+ * `CollectedAnnotation` per declaration. Functions without leading
+ * comments still appear with empty annotations and `hasFirestoreTag:
+ * false` — the caller decides whether to keep them.
+ */
+export declare function collectAnnotations(sf: ts.SourceFile): CollectedAnnotation[];
+//# sourceMappingURL=annotation-collect.d.ts.map

package/dist/rules/indexes/extract/annotation-collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-collect.d.ts","sourceRoot":"","sources":["../../../../src/rules/indexes/extract/annotation-collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAoB,KAAK,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE9F,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,WAAW,EAAE,WAAW,CAAC;IACzB,uDAAuD;IACvD,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B;;;;;OAKG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,GAAG,mBAAmB,EAAE,CAiC3E"}

package/dist/rules/indexes/extract/annotation-collect.js

@@ -0,0 +1,69 @@
+/**
+ * AST walker that pairs each function-like declaration with its leading
+ * JSDoc-style comment block, parses any `@firestore-*` tags out of it,
+ * and yields the parsed annotations alongside the function name.
+ *
+ * Pure walker — no enumeration logic, no pruning. The orchestrator
+ * (`extractor.ts`) consumes these and threads them into `enumerateShapes`.
+ *
+ * Coverage matches `iterFunctionBodies` (see Issue A1 in the layer-2
+ * progress doc):
+ *   - function declarations
+ *   - arrow / function expressions assigned to a variable
+ * Method declarations on classes are deliberately out of scope for v1
+ * because Firebase query builders are almost never methods. Add when
+ * real-world demand surfaces.
+ */
+import ts from 'typescript';
+import { parseAnnotations } from './annotations.js';
+/**
+ * Walk every function-like declaration in a SourceFile and yield one
+ * `CollectedAnnotation` per declaration. Functions without leading
+ * comments still appear with empty annotations and `hasFirestoreTag:
+ * false` — the caller decides whether to keep them.
+ */
+export function collectAnnotations(sf) {
+    const out = [];
+    const fullText = sf.getFullText();
+    function record(name, node) {
+        const commentText = leadingCommentTextOf(node, fullText);
+        const { annotations, warnings } = parseAnnotations(commentText);
+        const hasFirestoreTag = /@firestore-[a-zA-Z0-9_-]+/.test(commentText);
+        out.push({ functionName: name, annotations, warnings, hasFirestoreTag });
+    }
+    function visit(n) {
+        if (ts.isFunctionDeclaration(n) && n.body) {
+            const name = n.name?.text ?? '<anon>';
+            record(name, n);
+        }
+        else if (ts.isVariableStatement(n)) {
+            for (const d of n.declarationList.declarations) {
+                if (d.initializer &&
+                    (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))) {
+                    const name = ts.isIdentifier(d.name) ? d.name.text : '<anon>';
+                    // Use the variable statement as the comment anchor — leading
+                    // comments attach to the statement, not the initializer.
+                    record(name, n);
+                }
+            }
+        }
+        ts.forEachChild(n, visit);
+    }
+    visit(sf);
+    return out;
+}
+/**
+ * Concatenate every leading comment range attached to `node` into a
+ * single string. Returns `''` if no leading comments exist.
+ *
+ * `ts.getLeadingCommentRanges` returns spans into the full source text;
+ * we slice them and join with newlines so multi-block leading comments
+ * (rare but legal) all participate in the parse.
+ */
+function leadingCommentTextOf(node, fullText) {
+    const ranges = ts.getLeadingCommentRanges(fullText, node.getFullStart());
+    if (!ranges || ranges.length === 0)
+        return '';
+    return ranges.map(r => fullText.slice(r.pos, r.end)).join('\n');
+}
+//# sourceMappingURL=annotation-collect.js.map

package/dist/rules/indexes/extract/annotation-collect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-collect.js","sourceRoot":"","sources":["../../../../src/rules/indexes/extract/annotation-collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAA4C,MAAM,kBAAkB,CAAC;AAmB9F;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAiB;IAClD,MAAM,GAAG,GAA0B,EAAE,CAAC;IACtC,MAAM,QAAQ,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;IAElC,SAAS,MAAM,CAAC,IAAY,EAAE,IAAa;QACzC,MAAM,WAAW,GAAG,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACzD,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAChE,MAAM,eAAe,GAAG,2BAA2B,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACtE,GAAG,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,SAAS,KAAK,CAAC,CAAU;QACvB,IAAI,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,QAAQ,CAAC;YACtC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAClB,CAAC;aAAM,IAAI,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC,YAAY,EAAE,CAAC;gBAC/C,IACE,CAAC,CAAC,WAAW;oBACb,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,oBAAoB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,EAC7E,CAAC;oBACD,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;oBAC9D,6DAA6D;oBAC7D,yDAAyD;oBACzD,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBAClB,CAAC;YACH,CAAC;QACH,CAAC;QACD,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAAC,IAAa,EAAE,QAAgB;IAC3D,MAAM,MAAM,GAAG,EAAE,CAAC,uBAAuB,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IACzE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClE,CAAC"}

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

@@ -0,0 +1,50 @@
+/**
+ * Pure parser for `@firestore-*` annotations in JSDoc comment blocks.
+ *
+ * Recognized syntax (Layer 2, locked from the P-prune v1 scope):
+ *
+ *   @firestore-mutex { fieldA, fieldB, fieldC }
+ *     — at most one of these fields can be active in any extracted
+ *       shape. Multiple lines = multiple independent groups.
+ *
+ *   @firestore-required fieldA, fieldB
+ *     — every extracted shape must include these fields.
+ *
+ *   @firestore-budget N
+ *     — soft cap on emitted index entries. Surfaces as a warning when
+ *       exceeded; does not drop entries.
+ *
+ * Annotations are additive — the absence of any tag falls back to
+ * Layer 1 behavior. Malformed tags degrade gracefully: a warning is
+ * emitted and the offending tag is ignored.
+ *
+ * This module does no AST work — it operates on raw comment text.
+ * Pairing comments with function declarations happens in
+ * `annotation-collect.ts`.
+ */
+export interface Annotations {
+    /** Each set is one mutex group. A combo violates a group if 2+ fields hit. */
+    mutexGroups: Set<string>[];
+    /** Fields every extracted shape must include. */
+    required: Set<string>;
+    /** Soft cap on emitted entries. Undefined = no cap. */
+    budget?: number;
+}
+export type AnnotationWarningCode = 'unknown-firestore-tag' | 'malformed-mutex' | 'malformed-required' | 'malformed-budget';
+export interface AnnotationWarning {
+    code: AnnotationWarningCode;
+    /** The tag name without the leading `@`, e.g. "firestore-mutex". */
+    tag: string;
+    message: string;
+}
+export interface ParseAnnotationsResult {
+    annotations: Annotations;
+    warnings: AnnotationWarning[];
+}
+/**
+ * Parse `@firestore-*` tags out of a comment block. Returns an empty
+ * `Annotations` with no warnings when the input contains no firestore
+ * tags — this is the additive fallback.
+ */
+export declare function parseAnnotations(commentText: string): ParseAnnotationsResult;
+//# sourceMappingURL=annotations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../../../src/rules/indexes/extract/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,qBAAqB,GAC7B,uBAAuB,GACvB,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,CAyF5E"}

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

@@ -0,0 +1,144 @@
+/**
+ * Pure parser for `@firestore-*` annotations in JSDoc comment blocks.
+ *
+ * Recognized syntax (Layer 2, locked from the P-prune v1 scope):
+ *
+ *   @firestore-mutex { fieldA, fieldB, fieldC }
+ *     — at most one of these fields can be active in any extracted
+ *       shape. Multiple lines = multiple independent groups.
+ *
+ *   @firestore-required fieldA, fieldB
+ *     — every extracted shape must include these fields.
+ *
+ *   @firestore-budget N
+ *     — soft cap on emitted index entries. Surfaces as a warning when
+ *       exceeded; does not drop entries.
+ *
+ * Annotations are additive — the absence of any tag falls back to
+ * Layer 1 behavior. Malformed tags degrade gracefully: a warning is
+ * emitted and the offending tag is ignored.
+ *
+ * This module does no AST work — it operates on raw comment text.
+ * Pairing comments with function declarations happens in
+ * `annotation-collect.ts`.
+ */
+const KNOWN_TAGS = new Set([
+    'firestore-mutex',
+    'firestore-required',
+    'firestore-budget',
+]);
+/**
+ * Parse `@firestore-*` tags out of a comment block. Returns an empty
+ * `Annotations` with no warnings when the input contains no firestore
+ * tags — this is the additive fallback.
+ */
+export function parseAnnotations(commentText) {
+    const annotations = { mutexGroups: [], required: new Set() };
+    const warnings = [];
+    if (!commentText)
+        return { annotations, warnings };
+    // Normalize JSDoc syntax so the trailing `*/` and per-line ` * `
+    // don't leak into our value captures. We don't care about the
+    // comment structure — only the @firestore-* tags and their args.
+    commentText = stripCommentMarkers(commentText);
+    // ── @firestore-mutex { f1, f2, ... } ──────────────────────────────────
+    // Use a regex that captures the brace contents. Empty braces or no
+    // braces at all are malformed.
+    const mutexAll = commentText.matchAll(/@firestore-mutex\b([^\n]*)/g);
+    for (const m of mutexAll) {
+        const tail = m[1];
+        const braceMatch = tail.match(/\{\s*([^}]*?)\s*\}/);
+        if (!braceMatch) {
+            warnings.push({
+                code: 'malformed-mutex',
+                tag: 'firestore-mutex',
+                message: `@firestore-mutex requires a brace-delimited field list, e.g. \`@firestore-mutex { a, b, c }\` — got: ${tail.trim() || '(empty)'}`,
+            });
+            continue;
+        }
+        const fields = splitFields(braceMatch[1]);
+        if (fields.length === 0) {
+            warnings.push({
+                code: 'malformed-mutex',
+                tag: 'firestore-mutex',
+                message: '@firestore-mutex group is empty — at least one field is required.',
+            });
+            continue;
+        }
+        annotations.mutexGroups.push(new Set(fields));
+    }
+    // ── @firestore-required f1, f2 ────────────────────────────────────────
+    const requiredAll = commentText.matchAll(/@firestore-required\b([^\n@]*)/g);
+    for (const m of requiredAll) {
+        const fields = splitFields(m[1]);
+        if (fields.length === 0) {
+            warnings.push({
+                code: 'malformed-required',
+                tag: 'firestore-required',
+                message: '@firestore-required needs at least one field, e.g. `@firestore-required tenantId`.',
+            });
+            continue;
+        }
+        for (const f of fields)
+            annotations.required.add(f);
+    }
+    // ── @firestore-budget N ───────────────────────────────────────────────
+    const budgetAll = [...commentText.matchAll(/@firestore-budget\b([^\n@]*)/g)];
+    for (const m of budgetAll) {
+        const raw = m[1].trim();
+        const parsed = Number(raw);
+        if (!raw || !Number.isInteger(parsed) || parsed <= 0) {
+            warnings.push({
+                code: 'malformed-budget',
+                tag: 'firestore-budget',
+                message: `@firestore-budget needs a positive integer, e.g. \`@firestore-budget 12\` — got: ${raw || '(empty)'}`,
+            });
+            continue;
+        }
+        // Last write wins if multiple budget tags appear — pick the
+        // tightest cap so the agent sees the strictest constraint.
+        annotations.budget = annotations.budget === undefined ? parsed : Math.min(annotations.budget, parsed);
+    }
+    // ── Unknown @firestore-* tags ─────────────────────────────────────────
+    // Catch typos like @firestore-mutext or @firestore-mutexx so the
+    // agent doesn't silently skip an intended annotation.
+    const allTags = commentText.matchAll(/@(firestore-[a-zA-Z0-9_-]+)/g);
+    const seenUnknown = new Set();
+    for (const m of allTags) {
+        const tag = m[1];
+        if (KNOWN_TAGS.has(tag))
+            continue;
+        if (seenUnknown.has(tag))
+            continue;
+        seenUnknown.add(tag);
+        warnings.push({
+            code: 'unknown-firestore-tag',
+            tag,
+            message: `Unknown annotation '@${tag}'. Recognized: @firestore-mutex, @firestore-required, @firestore-budget.`,
+        });
+    }
+    return { annotations, warnings };
+}
+/**
+ * Split a comma-separated field list. Trims whitespace, drops empties,
+ * and strips trailing commas. Field identifiers themselves are
+ * preserved as written — no validation against actual source.
+ */
+function splitFields(s) {
+    return s.split(',').map(f => f.trim()).filter(Boolean);
+}
+/**
+ * Strip `/*`, `* /`, leading per-line ` * `, and `//` markers so the
+ * downstream regexes don't pick them up as part of value captures.
+ * Preserves newlines so multi-line tags still split correctly.
+ */
+function stripCommentMarkers(s) {
+    // Remove block-comment open/close.
+    s = s.replace(/\/\*+/g, '').replace(/\*+\//g, '');
+    // Remove leading ` * ` (and the bare ` *`) on each line.
+    s = s.replace(/^[ \t]*\*+[ \t]?/gm, '');
+    // Remove `//` line-comment markers (rare for JSDoc, but legal).
+    s = s.replace(/^[ \t]*\/\/[ \t]?/gm, '');
+    return s;
+}
+//# sourceMappingURL=annotations.js.map

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * Small TypeScript-AST helpers used by the rest of the extractor.
+ * Pure utilities — no extractor state, no allocation of context.
+ */
+import ts from 'typescript';
+/**
+ * Returns the literal text of a string-literal or no-substitution
+ * template literal node. Returns `null` for any other expression so the
+ * caller can decide how to handle the dynamic case.
+ */
+export declare function strLit(node: ts.Node): string | null;
+/**
+ * Extract the callee name from a call expression. Handles both bare
+ * identifiers (`query(...)`) and property accesses (`firestore.query(...)`),
+ * returning the **rightmost** identifier in either case so module-style
+ * imports and namespace imports both work.
+ *
+ * Returns `null` for callees we can't resolve statically (e.g.,
+ * `(foo ? a : b)(...)` or `arr[0](...)`).
+ */
+export declare function getCalleeName(call: ts.CallExpression): string | null;
+/**
+ * Find a top-level function (declaration, function-expression assigned to
+ * a `let`/`const`, or arrow function assigned to one) by name and return
+ * the function body node. Returns `null` if no such function exists.
+ *
+ * Used by the extractor to locate the function whose query chain we want
+ * to scan. A more complete implementation would build a real symbol
+ * table; this is enough for the common Firebase-app pattern of one
+ * exported function per query.
+ */
+export declare function findFunctionByName(sf: ts.SourceFile, name: string): ts.Node | null;
+/**
+ * Walk every function-like node in a source file and yield each body.
+ * Used by the orchestrator when no specific function name is given —
+ * scan everything that could contain a query chain.
+ *
+ * Includes function declarations, arrow functions, function expressions,
+ * and method declarations. Class constructors and getters/setters are
+ * also included since they can issue queries too.
+ */
+export declare function iterFunctionBodies(sf: ts.SourceFile): Generator<{
+    name: string;
+    body: ts.Node;
+}>;
+/**
+ * Parse a string of JS/TS source into a SourceFile. Returns `null` if
+ * TypeScript reports a fatal lex error — TypeScript's parser is very
+ * lenient (it'll happily produce a partially-correct AST for malformed
+ * input), so this almost always succeeds. The orchestrator still wraps
+ * the call in a try/catch for the rare hard failure.
+ */
+export declare function parseSource(name: string, source: string): ts.SourceFile;
+//# sourceMappingURL=ast.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../../../src/rules/indexes/extract/ast.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,GAAG,IAAI,CAGnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,GAAG,MAAM,GAAG,IAAI,CAKpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,EAAE,CAAC,IAAI,GAAG,IAAI,CAsBlF;AAED;;;;;;;;GAQG;AACH,wBAAiB,kBAAkB,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAA;CAAE,CAAC,CA4BjG;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,EAAE,CAAC,UAAU,CAKvE"}

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

@@ -0,0 +1,119 @@
+/**
+ * Small TypeScript-AST helpers used by the rest of the extractor.
+ * Pure utilities — no extractor state, no allocation of context.
+ */
+import ts from 'typescript';
+/**
+ * Returns the literal text of a string-literal or no-substitution
+ * template literal node. Returns `null` for any other expression so the
+ * caller can decide how to handle the dynamic case.
+ */
+export function strLit(node) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    return null;
+}
+/**
+ * Extract the callee name from a call expression. Handles both bare
+ * identifiers (`query(...)`) and property accesses (`firestore.query(...)`),
+ * returning the **rightmost** identifier in either case so module-style
+ * imports and namespace imports both work.
+ *
+ * Returns `null` for callees we can't resolve statically (e.g.,
+ * `(foo ? a : b)(...)` or `arr[0](...)`).
+ */
+export function getCalleeName(call) {
+    const e = call.expression;
+    if (ts.isIdentifier(e))
+        return e.text;
+    if (ts.isPropertyAccessExpression(e))
+        return e.name.text;
+    return null;
+}
+/**
+ * Find a top-level function (declaration, function-expression assigned to
+ * a `let`/`const`, or arrow function assigned to one) by name and return
+ * the function body node. Returns `null` if no such function exists.
+ *
+ * Used by the extractor to locate the function whose query chain we want
+ * to scan. A more complete implementation would build a real symbol
+ * table; this is enough for the common Firebase-app pattern of one
+ * exported function per query.
+ */
+export function findFunctionByName(sf, name) {
+    let found = null;
+    function visit(n) {
+        if (found)
+            return;
+        if (ts.isFunctionDeclaration(n) && n.name?.text === name) {
+            found = n.body ?? null;
+            return;
+        }
+        if (ts.isVariableStatement(n)) {
+            for (const d of n.declarationList.declarations) {
+                if (ts.isIdentifier(d.name) && d.name.text === name && d.initializer) {
+                    if (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer)) {
+                        found = d.initializer.body;
+                        return;
+                    }
+                }
+            }
+        }
+        ts.forEachChild(n, visit);
+    }
+    visit(sf);
+    return found;
+}
+/**
+ * Walk every function-like node in a source file and yield each body.
+ * Used by the orchestrator when no specific function name is given —
+ * scan everything that could contain a query chain.
+ *
+ * Includes function declarations, arrow functions, function expressions,
+ * and method declarations. Class constructors and getters/setters are
+ * also included since they can issue queries too.
+ */
+export function* iterFunctionBodies(sf) {
+    function nameOf(n) {
+        if (ts.isFunctionDeclaration(n) || ts.isMethodDeclaration(n)) {
+            const id = n.name;
+            if (id && ts.isIdentifier(id))
+                return id.text;
+        }
+        return '<anon>';
+    }
+    function* visit(n) {
+        if (ts.isFunctionDeclaration(n) && n.body) {
+            yield { name: nameOf(n), body: n.body };
+        }
+        else if (ts.isMethodDeclaration(n) && n.body) {
+            yield { name: nameOf(n), body: n.body };
+        }
+        else if (ts.isVariableStatement(n)) {
+            for (const d of n.declarationList.declarations) {
+                if (d.initializer && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))) {
+                    const name = ts.isIdentifier(d.name) ? d.name.text : '<anon>';
+                    yield { name, body: d.initializer.body };
+                }
+            }
+        }
+        for (const child of n.getChildren()) {
+            yield* visit(child);
+        }
+    }
+    yield* visit(sf);
+}
+/**
+ * Parse a string of JS/TS source into a SourceFile. Returns `null` if
+ * TypeScript reports a fatal lex error — TypeScript's parser is very
+ * lenient (it'll happily produce a partially-correct AST for malformed
+ * input), so this almost always succeeds. The orchestrator still wraps
+ * the call in a try/catch for the rare hard failure.
+ */
+export function parseSource(name, source) {
+    // ScriptKind.JS for the modular Firebase API in JS; TS is a superset
+    // so this still parses .ts correctly. Using JS here means JSDoc tags
+    // are surfaced (we'll use this for the Layer 2 annotation work).
+    return ts.createSourceFile(name, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+}
+//# sourceMappingURL=ast.js.map

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * `classifyQueryCall` — given a `query(...)` call expression, decide whether
+ * it's an INIT (`query(collection(db, "X"), ...)`) or a WRAP
+ * (`query(q, ...constraints)`), and produce the fragments contributed by
+ * the call's constraint arguments.
+ *
+ * One call may produce multiple fragments — `query(q, where(...), orderBy(...))`
+ * yields a `where` and an `orderBy` fragment. Callers wrap each fragment
+ * with branch context (branchId/clauseId/skippable) before storing.
+ */
+import ts from 'typescript';
+import type { Filter, Order } from './types.js';
+/**
+ * A fragment without branch context — `dataflow.ts` adds branchId/clauseId
+ * /skippable when it sees the fragment in its lexical position.
+ */
+export interface ClassifiedFragment {
+    kind: 'where' | 'orderBy' | 'limit' | 'unknown';
+    filter?: Filter;
+    order?: Order;
+    limit?: number;
+}
+export interface ClassifiedCall {
+    /** True iff this call initializes the chain (`query(collection(...))`). */
+    isInit: boolean;
+    /** Present when isInit is true and the path was statically resolvable. */
+    collectionPath?: string | null;
+    /** True when the INIT used `collectionGroup(...)` instead of `collection(...)`. */
+    isCollectionGroup?: boolean;
+    /** Constraints emitted by this call. */
+    fragments: ClassifiedFragment[];
+}
+/**
+ * Classify a `query(...)` call. Caller is expected to have already
+ * confirmed `getCalleeName(call) === 'query'`.
+ *
+ * `varName` is the local that the chain is being built on (typically `q`).
+ * Used to recognize the WRAP shape `query(q, ...)`.
+ */
+export declare function classifyQueryCall(call: ts.CallExpression, varName: string): ClassifiedCall;
+//# sourceMappingURL=classify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../../../src/rules/indexes/extract/classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wCAAwC;IACxC,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAkFD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAuC1F"}