pyric 0.0.1 → 0.1.0-alpha.7

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

@@ -0,0 +1,163 @@
+/**
+ * Stable string key for a QueryShape — only used for dedupe inside this
+ * module. Field order matters (it's part of the shape's identity in the
+ * Firestore index sense), so don't sort.
+ */
+function shapeKey(s) {
+    const scope = s.isCollectionGroup ? 'G' : 'C';
+    const filters = s.filters.map(f => `${f.field}${f.op}`).join(',');
+    const orders = s.orders.map(o => `${o.field}:${o.direction}`).join(',');
+    const limit = s.limit ?? '-';
+    return `${scope}:${s.collectionPath}|${filters}|${orders}|L=${limit}`;
+}
+export function enumerateShapes(decl) {
+    // No statically-resolved base path → nothing to emit. Caller can still
+    // surface this as a warning ("partial-base").
+    if (decl.collectionPath === null)
+        return [];
+    const unconditional = [];
+    const branches = new Map();
+    for (const f of decl.fragments) {
+        if (f.branchId === null) {
+            unconditional.push(f);
+            continue;
+        }
+        let entry = branches.get(f.branchId);
+        if (!entry) {
+            entry = { skippable: f.skippable, clauses: new Map() };
+            branches.set(f.branchId, entry);
+        }
+        const clauseId = f.clauseId ?? 0;
+        let clauseFrags = entry.clauses.get(clauseId);
+        if (!clauseFrags) {
+            clauseFrags = [];
+            entry.clauses.set(clauseId, clauseFrags);
+        }
+        clauseFrags.push(f);
+    }
+    // Build the per-branch choice lists. Choice = the fragments that fire
+    // when that clause is taken (or [] when the branch is skipped).
+    const branchChoices = [];
+    for (const branch of branches.values()) {
+        const choices = [];
+        for (const clauseFrags of branch.clauses.values()) {
+            choices.push(clauseFrags);
+        }
+        if (branch.skippable)
+            choices.push([]);
+        branchChoices.push(choices);
+    }
+    // Cartesian product. Start with the empty combo; for each branch,
+    // multiply the running set by that branch's choices.
+    let combos = [[]];
+    for (const choices of branchChoices) {
+        const next = [];
+        for (const acc of combos) {
+            for (const choice of choices) {
+                next.push([...acc, ...choice]);
+            }
+        }
+        combos = next;
+    }
+    // Materialize combos into QueryShapes (each combo + all unconditional).
+    const shapes = [];
+    for (const combo of combos) {
+        const all = [...unconditional, ...combo];
+        const filters = [];
+        const orders = [];
+        let limit = null;
+        for (const f of all) {
+            if (f.kind === 'where' && f.filter)
+                filters.push(f.filter);
+            else if (f.kind === 'orderBy' && f.order)
+                orders.push(f.order);
+            else if (f.kind === 'limit' && f.limit != null)
+                limit = f.limit;
+            // 'unknown' fragments contribute nothing — they're tracked at
+            // the warning level by the orchestrator, not here.
+        }
+        shapes.push({
+            collectionPath: decl.collectionPath,
+            isCollectionGroup: decl.isCollectionGroup,
+            filters,
+            orders,
+            limit,
+        });
+    }
+    // Dedupe — different combos can collapse to the same shape (e.g., when
+    // a skippable branch happens to add nothing).
+    const seen = new Set();
+    const unique = [];
+    for (const s of shapes) {
+        const k = shapeKey(s);
+        if (!seen.has(k)) {
+            seen.add(k);
+            unique.push(s);
+        }
+    }
+    return unique;
+}
+/**
+ * Apply mutex + required annotations to an enumerated shape list.
+ *
+ * - Mutex: a shape is dropped if any mutex group has ≥2 of its fields
+ *   present in the shape's filters or orderBy. (One field from a group
+ *   is fine — the constraint is "at most one".)
+ * - Required: a shape is dropped if it doesn't contain every field in
+ *   `annotations.required` somewhere in filters or orderBy.
+ *
+ * `@firestore-budget` is **not** applied here — that's a soft cap
+ * surfaced as a warning at the orchestrator level, not a prune.
+ *
+ * No-op when `annotations` is `undefined`, empty mutexGroups, and empty
+ * required — returns the input shapes with zero prune counts.
+ */
+export function pruneByAnnotations(shapes, annotations) {
+    if (!annotations || (annotations.mutexGroups.length === 0 && annotations.required.size === 0)) {
+        return { shapes, prunedByMutex: 0, prunedByRequired: 0 };
+    }
+    let prunedByMutex = 0;
+    let prunedByRequired = 0;
+    const kept = [];
+    for (const s of shapes) {
+        const fields = new Set();
+        for (const f of s.filters)
+            fields.add(f.field);
+        for (const o of s.orders)
+            fields.add(o.field);
+        // Mutex check first — if a shape is mutex-violating, attribute to mutex.
+        let mutexViolated = false;
+        for (const group of annotations.mutexGroups) {
+            let hits = 0;
+            for (const g of group) {
+                if (fields.has(g))
+                    hits++;
+                if (hits >= 2) {
+                    mutexViolated = true;
+                    break;
+                }
+            }
+            if (mutexViolated)
+                break;
+        }
+        if (mutexViolated) {
+            prunedByMutex++;
+            continue;
+        }
+        // Required check.
+        let missingRequired = false;
+        for (const r of annotations.required) {
+            if (!fields.has(r)) {
+                missingRequired = true;
+                break;
+            }
+        }
+        if (missingRequired) {
+            prunedByRequired++;
+            continue;
+        }
+        kept.push(s);
+    }
+    return { shapes: kept, prunedByMutex, prunedByRequired };
+}
+//# sourceMappingURL=enumerate.js.map

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

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

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

@@ -0,0 +1,3 @@
+import type { ExtractOptions, ExtractResult } from './types.js';
+export declare function extractIndexes(options: ExtractOptions): ExtractResult;
+//# sourceMappingURL=extractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../../../src/rules/indexes/extract/extractor.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAEV,cAAc,EACd,aAAa,EAMd,MAAM,YAAY,CAAC;AAWpB,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CA+KrE"}

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

@@ -0,0 +1,274 @@
+/**
+ * Top-level extractor — runs the full pipeline (parse → scan → enumerate
+ * → composite-detect → dedupe) over a bag of files and produces an
+ * `ExtractResult` carrying:
+ *
+ *   - `config` — `firestore.indexes.json`-shaped, ready for
+ *     `firestore_deploy_indexes`.
+ *   - `signals` — per-collection over-shoot hints the agent layer can
+ *     act on (Layer 2: add `@firestore-mutex` annotations).
+ *   - `warnings` — per-file diagnostics (partial-base, unknown-callee,
+ *     dynamic-arg).
+ */
+import ts from 'typescript';
+import { iterFunctionBodies, parseSource } from './ast.js';
+import { collectAnnotations } from './annotation-collect.js';
+import { scanFunctionBody } from './dataflow.js';
+import { enumerateShapes, pruneByAnnotations } from './enumerate.js';
+import { needsCompositeIndex, shapeToIndexEntry, indexEntryKey } from './composite.js';
+/**
+ * Heuristic for over-shoot detection: > 3 distinct shapes for one
+ * collection is suspicious. Most real apps have 1–3 query patterns
+ * per collection — anything higher usually means the cartesian
+ * blowup from cross-product over independent optional filters.
+ */
+const OVERSHOOT_THRESHOLD = 3;
+export function extractIndexes(options) {
+    const queryVarName = options.queryVarName ?? 'q';
+    const allShapes = [];
+    const warnings = [];
+    const annotationsApplied = [];
+    /** Tightest budget across all functions that declared one. */
+    let tightestBudget;
+    for (const file of options.files) {
+        let sf;
+        try {
+            sf = parseSource(file.name, file.source);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            warnings.push({ file: file.name, code: 'parse-error', message });
+            continue;
+        }
+        // Build a name → annotations map for the file. Functions without a
+        // leading @firestore-* tag are absent from the map (so the prune
+        // step is a true no-op for them).
+        const annByFn = new Map();
+        for (const collected of collectAnnotations(sf)) {
+            if (collected.hasFirestoreTag)
+                annByFn.set(collected.functionName, collected);
+            // Surface annotation parser warnings as extractor warnings too,
+            // so consumers see them in the unified `warnings` channel.
+            for (const w of collected.warnings) {
+                warnings.push({
+                    file: file.name,
+                    code: 'annotation-malformed',
+                    message: `Function '${collected.functionName}': ${w.message}`,
+                });
+            }
+        }
+        // Layer 2.5: build a same-file resolver so wrapper calls
+        // (`q = applyFilters(q, ...)`) inline at the caller's call site.
+        const resolver = makeFileResolver(sf);
+        const records = [];
+        const inlinedAcrossFile = new Set();
+        for (const fn of iterFunctionBodies(sf)) {
+            const decl = scanFunctionBody(fn.body, queryVarName, resolver);
+            records.push({ fnName: fn.name, decl });
+            if (decl.inlinedFunctions) {
+                for (const f of decl.inlinedFunctions)
+                    inlinedAcrossFile.add(f);
+            }
+        }
+        // Second pass: emit warnings, enumerate shapes, apply annotations.
+        for (const { fnName, decl } of records) {
+            // Promote inter-proc warnings to the unified channel regardless
+            // of whether the function had a base — they're useful diagnostics.
+            if (decl.interProcWarnings) {
+                for (const w of decl.interProcWarnings) {
+                    warnings.push({
+                        file: file.name,
+                        code: w.code,
+                        message: `Function '${fnName}': ${w.message}`,
+                    });
+                }
+            }
+            if (decl.fragments.length === 0 && decl.collectionPath === null) {
+                // Function doesn't touch the chain — skip without a warning.
+                continue;
+            }
+            if (decl.collectionPath === null) {
+                // Suppress `partial-base` for wrappers that were already inlined
+                // into a caller in this file — the caller's INIT covers them.
+                if (inlinedAcrossFile.has(fnName))
+                    continue;
+                warnings.push({
+                    file: file.name,
+                    code: 'partial-base',
+                    message: `Function '${fnName}' uses '${queryVarName}' but no INIT (\`query(collection(...))\`) found in the same body or any same-file caller — base may live in another module (cross-file following NYI).`,
+                });
+                continue;
+            }
+            // Surface any unknown fragments as warnings before enumerating.
+            surfaceFragmentWarnings(file.name, fnName, decl.fragments, warnings);
+            const enumerated = enumerateShapes(decl);
+            const sources = [];
+            const callerAnn = annByFn.get(fnName);
+            if (callerAnn)
+                sources.push({ annotations: callerAnn.annotations, warnings: callerAnn.warnings });
+            if (decl.inlinedFunctions) {
+                for (const wrapperName of decl.inlinedFunctions) {
+                    const wrapperAnn = annByFn.get(wrapperName);
+                    if (wrapperAnn) {
+                        sources.push({
+                            annotations: wrapperAnn.annotations,
+                            warnings: wrapperAnn.warnings,
+                            inlinedFrom: wrapperName,
+                        });
+                    }
+                }
+            }
+            if (sources.length === 0) {
+                allShapes.push(...enumerated);
+            }
+            else {
+                // Apply each source's prune to the running shape list. Each source
+                // gets its own AnnotationApplied entry attributed to the caller,
+                // with `inlinedFrom` set when the annotation came from a wrapper.
+                let currentShapes = enumerated;
+                for (const src of sources) {
+                    const pruned = pruneByAnnotations(currentShapes, src.annotations);
+                    annotationsApplied.push({
+                        functionName: fnName,
+                        file: file.name,
+                        annotations: src.annotations,
+                        prunedByMutex: pruned.prunedByMutex,
+                        prunedByRequired: pruned.prunedByRequired,
+                        warnings: src.warnings,
+                        ...(src.inlinedFrom ? { inlinedFrom: src.inlinedFrom } : {}),
+                    });
+                    if (src.annotations.budget !== undefined) {
+                        tightestBudget = tightestBudget === undefined
+                            ? src.annotations.budget
+                            : Math.min(tightestBudget, src.annotations.budget);
+                    }
+                    currentShapes = pruned.shapes;
+                }
+                allShapes.push(...currentShapes);
+            }
+        }
+    }
+    // Composite filter + dedupe by index-entry key.
+    const seen = new Set();
+    const entries = [];
+    for (const s of allShapes) {
+        if (!needsCompositeIndex(s))
+            continue;
+        const entry = shapeToIndexEntry(s);
+        const k = indexEntryKey(entry);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        entries.push(entry);
+    }
+    // @firestore-budget — soft cap. Warn but don't drop entries.
+    if (tightestBudget !== undefined && entries.length > tightestBudget) {
+        warnings.push({
+            file: '<config>',
+            code: 'budget-exceeded',
+            message: `Emitted ${entries.length} composite index entries — exceeds tightest @firestore-budget of ${tightestBudget}. Consider adding more @firestore-mutex groups before deploying.`,
+        });
+    }
+    const signals = buildSignals(allShapes);
+    return {
+        success: true,
+        data: {
+            config: { indexes: entries },
+            signals,
+            warnings,
+            shapesEnumerated: allShapes.length,
+            annotationsApplied,
+        },
+    };
+}
+function surfaceFragmentWarnings(file, fnName, fragments, warnings) {
+    let unknownCount = 0;
+    for (const f of fragments) {
+        if (f.kind === 'unknown')
+            unknownCount += 1;
+    }
+    if (unknownCount > 0) {
+        warnings.push({
+            file,
+            code: 'unknown-callee',
+            message: `Function '${fnName}' contained ${unknownCount} unrecognized constraint call(s) — these were skipped. Custom helpers wrapping where/orderBy aren't followed in v1.`,
+        });
+    }
+}
+/**
+ * Build a `CallResolver` that knows about every function-like
+ * declaration in `sf`. Used by the orchestrator to inline same-file
+ * wrappers when the dataflow walker hits `q = wrapper(q, ...)`.
+ *
+ * Coverage matches `iterFunctionBodies`:
+ *   - top-level `function name() {}` declarations
+ *   - `const name = (q) => { ... }` arrow expressions
+ *   - `const name = function (q) { ... }` function expressions
+ *
+ * Method declarations and nested function decls are out of scope for
+ * v1 (Issue B1 in the layer 2.5 progress doc).
+ */
+function makeFileResolver(sf) {
+    const byName = new Map();
+    function visit(n) {
+        if (ts.isFunctionDeclaration(n) && n.name && n.body) {
+            if (!byName.has(n.name.text))
+                byName.set(n.name.text, { body: n.body, params: n.parameters });
+        }
+        else if (ts.isVariableStatement(n)) {
+            for (const d of n.declarationList.declarations) {
+                if (ts.isIdentifier(d.name)
+                    && d.initializer
+                    && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))) {
+                    if (!byName.has(d.name.text)) {
+                        byName.set(d.name.text, { body: d.initializer.body, params: d.initializer.parameters });
+                    }
+                }
+            }
+        }
+        ts.forEachChild(n, visit);
+    }
+    visit(sf);
+    return (functionName, chainArgIndex) => {
+        const entry = byName.get(functionName);
+        if (!entry)
+            return null;
+        const param = entry.params[chainArgIndex];
+        if (!param || !ts.isIdentifier(param.name))
+            return null;
+        return { body: entry.body, chainParamName: param.name.text };
+    };
+}
+function buildSignals(shapes) {
+    // Group shapes by their derived collectionGroup (last path segment).
+    const groups = new Map();
+    for (const s of shapes) {
+        const cg = s.collectionPath.split('/').pop() || s.collectionPath;
+        let bucket = groups.get(cg);
+        if (!bucket) {
+            bucket = [];
+            groups.set(cg, bucket);
+        }
+        bucket.push(s);
+    }
+    const signals = [];
+    for (const [collectionGroup, bucket] of groups) {
+        const fields = new Set();
+        for (const s of bucket) {
+            for (const f of s.filters)
+                fields.add(f.field);
+            for (const o of s.orders)
+                fields.add(o.field);
+        }
+        signals.push({
+            collectionGroup,
+            shapeCount: bucket.length,
+            fieldsTouched: Array.from(fields).sort(),
+            overshootSuspected: bucket.length > OVERSHOOT_THRESHOLD,
+        });
+    }
+    // Sort for deterministic output.
+    signals.sort((a, b) => a.collectionGroup.localeCompare(b.collectionGroup));
+    return signals;
+}
+//# sourceMappingURL=extractor.js.map

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

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