indexwright 0.1.0

package/dist/lint.js

@@ -0,0 +1,110 @@
+import { readFileSync } from 'node:fs';
+import { compareStrings } from './collections.js';
+import { analyse } from './key.js';
+import { MalformedInputError, parseDocument } from './parse.js';
+import { getRule, rules } from './rules/index.js';
+import { RULE_IDS } from './types.js';
+import { VERSION } from './version.js';
+export const DEFAULT_QUOTA = 1000;
+export const DEFAULT_QUOTA_THRESHOLD = 0.8;
+/** Lint documents that are already parsed. The lowest layer; does no I/O. */
+export function lintDocuments(inputs, options = {}) {
+    return assemble(inputs.map((input) => ({ file: input.file, document: input.document, error: null })), options);
+}
+/** Lint raw file contents. A file that does not parse becomes an error, not a thrown exception. */
+export function lintTexts(inputs, options = {}) {
+    return assemble(inputs.map((input) => {
+        try {
+            return { file: input.file, document: parseDocument(input.text), error: null };
+        }
+        catch (error) {
+            return { file: input.file, document: null, error: describe(error) };
+        }
+    }), options);
+}
+/** Lint files on disk. Unreadable files are reported the same way malformed ones are. */
+export function lintFiles(paths, options = {}) {
+    return assemble(paths.map((file) => {
+        try {
+            return { file, document: parseDocument(readFileSync(file, 'utf8')), error: null };
+        }
+        catch (error) {
+            return { file, document: null, error: describe(error) };
+        }
+    }), options);
+}
+function assemble(loaded, options) {
+    const selected = resolveRules(options.rules);
+    const ruleOptions = {
+        quota: options.quota ?? DEFAULT_QUOTA,
+        quotaThreshold: options.quotaThreshold ?? DEFAULT_QUOTA_THRESHOLD,
+    };
+    const findings = [];
+    const errors = [];
+    for (const entry of loaded) {
+        if (!entry.document) {
+            errors.push({ file: entry.file, message: entry.error ?? 'could not be read' });
+            continue;
+        }
+        const context = {
+            file: entry.file,
+            document: entry.document,
+            indexes: analyse(entry.document),
+            options: ruleOptions,
+        };
+        for (const id of selected) {
+            findings.push(...getRule(id).check(context));
+        }
+    }
+    findings.sort(compareFindings);
+    errors.sort((a, b) => compareStrings(a.file, b.file));
+    const byRule = {};
+    for (const id of selected)
+        byRule[id] = 0;
+    for (const finding of findings)
+        byRule[finding.rule] = (byRule[finding.rule] ?? 0) + 1;
+    return {
+        version: VERSION,
+        files: [...loaded.map((entry) => entry.file)].sort(compareStrings),
+        summary: { warnings: findings.length, errors: errors.length, byRule },
+        findings,
+        errors,
+    };
+}
+/** Preserve the canonical rule order (SPEC §5) whatever order the caller asked in. */
+function resolveRules(requested) {
+    if (!requested)
+        return rules.map((rule) => rule.id);
+    const wanted = new Set(requested);
+    return RULE_IDS.filter((id) => wanted.has(id));
+}
+const RULE_ORDER = new Map(RULE_IDS.map((id, position) => [id, position]));
+function compareFindings(a, b) {
+    return (compareStrings(a.file, b.file) ||
+        (RULE_ORDER.get(a.rule) ?? 0) - (RULE_ORDER.get(b.rule) ?? 0) ||
+        compareKeys(a.key, b.key) ||
+        compareStrings(a.message, b.message));
+}
+/** A null key sorts first: it belongs to a file-wide finding, which has no index to sort by. */
+function compareKeys(a, b) {
+    if (a === b)
+        return 0;
+    if (a === null)
+        return -1;
+    if (b === null)
+        return 1;
+    return compareStrings(a, b);
+}
+function describe(error) {
+    if (error instanceof MalformedInputError)
+        return error.message;
+    const code = error.code;
+    if (code === 'ENOENT')
+        return 'no such file';
+    if (code === 'EISDIR')
+        return 'is a directory';
+    if (code === 'EACCES')
+        return 'permission denied';
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=lint.js.map

package/dist/lint.js.map

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

package/dist/parse.d.ts

@@ -0,0 +1,11 @@
+import type { IndexDocument } from './types.js';
+/**
+ * A file that is not a usable index declaration. Reported per file and mapped to exit code 2;
+ * it never aborts the analysis of the other files (SPEC §4).
+ */
+export declare class MalformedInputError extends Error {
+    readonly name = "MalformedInputError";
+}
+export declare function parseDocument(text: string): IndexDocument;
+export declare function validateDocument(raw: unknown): IndexDocument;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,aAAa,EAAc,MAAM,YAAY,CAAC;AAE5E;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAyB;CAChD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAUzD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAa5D"}

package/dist/parse.js

@@ -0,0 +1,88 @@
+/**
+ * A file that is not a usable index declaration. Reported per file and mapped to exit code 2;
+ * it never aborts the analysis of the other files (SPEC §4).
+ */
+export class MalformedInputError extends Error {
+    name = 'MalformedInputError';
+}
+export function parseDocument(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        // The parser quotes the offending source, which can carry newlines; findings are one line each.
+        const detail = error.message.replace(/\s+/g, ' ').trim();
+        throw new MalformedInputError(`invalid JSON: ${detail}`);
+    }
+    return validateDocument(raw);
+}
+export function validateDocument(raw) {
+    if (!isObject(raw)) {
+        throw new MalformedInputError('the top level must be a JSON object');
+    }
+    const indexes = raw['indexes'];
+    if (indexes === undefined) {
+        throw new MalformedInputError('missing "indexes"');
+    }
+    if (!Array.isArray(indexes)) {
+        throw new MalformedInputError('"indexes" must be an array');
+    }
+    const validated = indexes.map((entry, i) => validateIndex(entry, `indexes[${i}]`));
+    return { ...raw, indexes: validated };
+}
+function validateIndex(raw, path) {
+    if (!isObject(raw)) {
+        throw new MalformedInputError(`${path}: must be an object`);
+    }
+    const collectionGroup = requireString(raw['collectionGroup'], `${path}: "collectionGroup"`);
+    const queryScope = requireString(raw['queryScope'], `${path}: "queryScope"`);
+    const fields = raw['fields'];
+    if (!Array.isArray(fields)) {
+        throw new MalformedInputError(`${path}: "fields" must be an array`);
+    }
+    if (fields.length === 0) {
+        throw new MalformedInputError(`${path}: "fields" must not be empty`);
+    }
+    // A repeated fieldPath is odd but occurs in real exports, and refusing to analyse a file is the
+    // harshest thing a warn-only tool can do. It is carried through; R2 compares multisets, so the
+    // repetition does not make "the same fields" ambiguous (SPEC §4, §5).
+    const validatedFields = fields.map((entry, i) => validateField(entry, `${path}.fields[${i}]`));
+    return { ...raw, collectionGroup, queryScope, fields: validatedFields };
+}
+function validateField(raw, path) {
+    if (!isObject(raw)) {
+        throw new MalformedInputError(`${path}: must be an object`);
+    }
+    const fieldPath = requireString(raw['fieldPath'], `${path}: "fieldPath"`);
+    const configured = ['order', 'arrayConfig', 'vectorConfig'].filter((name) => raw[name] !== undefined);
+    if (configured.length === 0) {
+        throw new MalformedInputError(`${path}: needs one of "order", "arrayConfig", or "vectorConfig"`);
+    }
+    if (configured.length > 1) {
+        throw new MalformedInputError(`${path}: declares ${configured.map((name) => `"${name}"`).join(' and ')}; only one is allowed`);
+    }
+    // Values are not checked against an enumeration, so a direction added by a future Firebase
+    // release passes through instead of failing the run (SPEC §4).
+    if (raw['order'] !== undefined)
+        requireString(raw['order'], `${path}: "order"`);
+    if (raw['arrayConfig'] !== undefined)
+        requireString(raw['arrayConfig'], `${path}: "arrayConfig"`);
+    if (raw['vectorConfig'] !== undefined && !isObject(raw['vectorConfig'])) {
+        throw new MalformedInputError(`${path}: "vectorConfig" must be an object`);
+    }
+    return { ...raw, fieldPath };
+}
+function requireString(value, label) {
+    if (typeof value !== 'string') {
+        throw new MalformedInputError(value === undefined ? `${label} is missing` : `${label} must be a string`);
+    }
+    if (value === '') {
+        throw new MalformedInputError(`${label} must not be empty`);
+    }
+    return value;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

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

package/dist/rules/explicit-name-field.d.ts

@@ -0,0 +1,13 @@
+import type { Rule } from '../types.js';
+/**
+ * R3 · explicit-name-field — a trailing `__name__` that restates what Firestore appends anyway.
+ *
+ * Firestore appends the document key implicitly; live exports render it explicitly. A redundant
+ * `__name__` in a hand-maintained file is therefore a signature of a value that round-tripped
+ * through an export. It does not change the resource, but it makes the file inconsistent and can
+ * mask genuine duplicates from naive text comparison.
+ *
+ * A `__name__` whose direction differs from the implicit default is meaningful and is not flagged.
+ */
+export declare const explicitNameField: Rule;
+//# sourceMappingURL=explicit-name-field.d.ts.map

package/dist/rules/explicit-name-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-name-field.d.ts","sourceRoot":"","sources":["../../src/rules/explicit-name-field.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAW,IAAI,EAAe,MAAM,aAAa,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,IAwB/B,CAAC"}

package/dist/rules/explicit-name-field.js

@@ -0,0 +1,35 @@
+import { uniqueSorted } from '../collections.js';
+import { NAME_FIELD } from '../key.js';
+/**
+ * R3 · explicit-name-field — a trailing `__name__` that restates what Firestore appends anyway.
+ *
+ * Firestore appends the document key implicitly; live exports render it explicitly. A redundant
+ * `__name__` in a hand-maintained file is therefore a signature of a value that round-tripped
+ * through an export. It does not change the resource, but it makes the file inconsistent and can
+ * mask genuine duplicates from naive text comparison.
+ *
+ * A `__name__` whose direction differs from the implicit default is meaningful and is not flagged.
+ */
+export const explicitNameField = {
+    id: 'explicit-name-field',
+    description: `a trailing ${NAME_FIELD} that restates the direction Firestore appends implicitly`,
+    check(context) {
+        const flagged = context.indexes.filter((index) => index.redundantNameDirection !== null);
+        // Two byte-identical declarations produce one key and would render as two identical lines.
+        const keys = uniqueSorted(flagged.map((index) => index.key));
+        return keys.map((key) => {
+            const index = flagged.find((candidate) => candidate.key === key);
+            const direction = index?.redundantNameDirection ?? 'ASCENDING';
+            return {
+                rule: 'explicit-name-field',
+                file: context.file,
+                key,
+                message: `the index ends with an explicit ${NAME_FIELD} (${direction}), which is the direction ` +
+                    `Firestore appends implicitly. The entry names the same index either way; writing it ` +
+                    `the shorter way keeps the file comparable by text.`,
+                related: [],
+            };
+        });
+    },
+};
+//# sourceMappingURL=explicit-name-field.js.map

package/dist/rules/explicit-name-field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-name-field.js","sourceRoot":"","sources":["../../src/rules/explicit-name-field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAS;IACrC,EAAE,EAAE,qBAAqB;IACzB,WAAW,EAAE,cAAc,UAAU,2DAA2D;IAEhG,KAAK,CAAC,OAAoB;QACxB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,sBAAsB,KAAK,IAAI,CAAC,CAAC;QACzF,2FAA2F;QAC3F,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAE7D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAW,EAAE;YAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;YACjE,MAAM,SAAS,GAAG,KAAK,EAAE,sBAAsB,IAAI,WAAW,CAAC;YAC/D,OAAO;gBACL,IAAI,EAAE,qBAAqB;gBAC3B,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,GAAG;gBACH,OAAO,EACL,mCAAmC,UAAU,KAAK,SAAS,4BAA4B;oBACvF,sFAAsF;oBACtF,oDAAoD;gBACtD,OAAO,EAAE,EAAE;aACZ,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}

package/dist/rules/field-order-variant.d.ts

@@ -0,0 +1,10 @@
+import type { Rule } from '../types.js';
+/**
+ * R2 · field-order-variant — indexes over the same field set, declared in different orders.
+ *
+ * Firestore treats a different field order as a different index, so each variant consumes write
+ * amplification, storage, and quota on its own. Distinct orderings can be genuinely required; the
+ * finding asks for that justification to be recorded, not for a variant to be removed.
+ */
+export declare const fieldOrderVariant: Rule;
+//# sourceMappingURL=field-order-variant.d.ts.map

package/dist/rules/field-order-variant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-order-variant.d.ts","sourceRoot":"","sources":["../../src/rules/field-order-variant.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA0C,IAAI,EAAe,MAAM,aAAa,CAAC;AAK7F;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,IAoC/B,CAAC"}

package/dist/rules/field-order-variant.js

@@ -0,0 +1,60 @@
+import { compareStrings, groupBy, uniqueSorted } from '../collections.js';
+/** A byte no collection id or field path can contain, so grouping keys cannot collide. */
+const SEPARATOR = '\u0000';
+/**
+ * R2 · field-order-variant — indexes over the same field set, declared in different orders.
+ *
+ * Firestore treats a different field order as a different index, so each variant consumes write
+ * amplification, storage, and quota on its own. Distinct orderings can be genuinely required; the
+ * finding asks for that justification to be recorded, not for a variant to be removed.
+ */
+export const fieldOrderVariant = {
+    id: 'field-order-variant',
+    description: 'indexes over the same field set declared in different field orders',
+    check(context) {
+        const findings = [];
+        const groups = [...groupBy(context.indexes, fieldSetKey)].sort(([a], [b]) => compareStrings(a, b));
+        for (const [, indexes] of groups) {
+            if (indexes.length < 2)
+                continue;
+            const orderings = uniqueSorted(indexes.map(fieldSequence));
+            // Byte-identical declarations are not "different orders" and are not this rule's subject.
+            if (orderings.length < 2)
+                continue;
+            const first = indexes[0];
+            const keys = uniqueSorted(indexes.map((index) => index.key));
+            const fieldList = uniqueSorted(first.fields.map((field) => `${field.fieldPath} (${field.direction})`)).join(', ');
+            findings.push({
+                rule: 'field-order-variant',
+                file: context.file,
+                key: keys[0] ?? null,
+                message: `collectionGroup "${first.collectionGroup}" declares ${orderings.length} field orders ` +
+                    `over the same ${first.queryScope}-scoped fields — ${fieldList}. Firestore stores each ` +
+                    `order as a separate index; record which query needs which order.`,
+                related: keys.slice(1),
+            });
+        }
+        return findings;
+    },
+};
+/**
+ * Every boundary is the separator, never `:` or `|`. Directions are not checked against an
+ * enumeration (§4), so a direction that itself contains `a:X|b` would otherwise make two different
+ * field multisets share one grouping key and fire this rule on indexes that do not share a field
+ * set at all.
+ */
+function pair(field) {
+    return `${field.fieldPath}${SEPARATOR}${field.direction}`;
+}
+/**
+ * Same collectionGroup, same queryScope, same multiset of field/direction pairs — order ignored.
+ * Sorting rather than de-duplicating keeps a repeated fieldPath (§4) from collapsing into one.
+ */
+function fieldSetKey(index) {
+    const pairs = index.fields.map(pair).sort(compareStrings);
+    return [index.collectionGroup, index.queryScope, ...pairs].join(SEPARATOR);
+}
+function fieldSequence(index) {
+    return index.fields.map(pair).join(SEPARATOR);
+}
+//# sourceMappingURL=field-order-variant.js.map

package/dist/rules/field-order-variant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-order-variant.js","sourceRoot":"","sources":["../../src/rules/field-order-variant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG1E,0FAA0F;AAC1F,MAAM,SAAS,GAAG,QAAQ,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAS;IACrC,EAAE,EAAE,qBAAqB;IACzB,WAAW,EAAE,oEAAoE;IAEjF,KAAK,CAAC,OAAoB;QACxB,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1E,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CACrB,CAAC;QAEF,KAAK,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC;YACjC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YACjC,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;YAC3D,0FAA0F;YAC1F,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAEnC,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAkB,CAAC;YAC1C,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YAC7D,MAAM,SAAS,GAAG,YAAY,CAC5B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,GAAG,CAAC,CACvE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAEb,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,qBAAqB;gBAC3B,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;gBACpB,OAAO,EACL,oBAAoB,KAAK,CAAC,eAAe,cAAc,SAAS,CAAC,MAAM,gBAAgB;oBACvF,iBAAiB,KAAK,CAAC,UAAU,oBAAoB,SAAS,0BAA0B;oBACxF,kEAAkE;gBACpE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;aACvB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC;AAEF;;;;;GAKG;AACH,SAAS,IAAI,CAAC,KAAqB;IACjC,OAAO,GAAG,KAAK,CAAC,SAAS,GAAG,SAAS,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;AAC5D,CAAC;AAED;;;GAGG;AACH,SAAS,WAAW,CAAC,KAAoB;IACvC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC1D,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,UAAU,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,aAAa,CAAC,KAAoB;IACzC,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAChD,CAAC"}

package/dist/rules/index.d.ts

@@ -0,0 +1,13 @@
+import type { Rule, RuleId } from '../types.js';
+import { explicitNameField } from './explicit-name-field.js';
+import { fieldOrderVariant } from './field-order-variant.js';
+import { quotaHeadroom } from './quota-headroom.js';
+import { scopeMismatch } from './scope-mismatch.js';
+/**
+ * Declaration order is R1 → R4 (SPEC §5), and it is also the sort order of findings within a file.
+ */
+export declare const rules: readonly Rule[];
+export declare function getRule(id: RuleId): Rule;
+export declare function isRuleId(value: string): value is RuleId;
+export { explicitNameField, fieldOrderVariant, quotaHeadroom, scopeMismatch };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EAKhC,CAAC;AAIF,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAIxC;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,MAAM,CAEvD;AAED,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC"}

package/dist/rules/index.js

@@ -0,0 +1,25 @@
+import { explicitNameField } from './explicit-name-field.js';
+import { fieldOrderVariant } from './field-order-variant.js';
+import { quotaHeadroom } from './quota-headroom.js';
+import { scopeMismatch } from './scope-mismatch.js';
+/**
+ * Declaration order is R1 → R4 (SPEC §5), and it is also the sort order of findings within a file.
+ */
+export const rules = [
+    scopeMismatch,
+    fieldOrderVariant,
+    explicitNameField,
+    quotaHeadroom,
+];
+const byId = new Map(rules.map((rule) => [rule.id, rule]));
+export function getRule(id) {
+    const rule = byId.get(id);
+    if (!rule)
+        throw new Error(`unknown rule: ${id}`);
+    return rule;
+}
+export function isRuleId(value) {
+    return byId.has(value);
+}
+export { explicitNameField, fieldOrderVariant, quotaHeadroom, scopeMismatch };
+//# 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":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAoB;IACpC,aAAa;IACb,iBAAiB;IACjB,iBAAiB;IACjB,aAAa;CACd,CAAC;AAEF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAe,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AAEzE,MAAM,UAAU,OAAO,CAAC,EAAU;IAChC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1B,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAClD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,IAAI,CAAC,GAAG,CAAC,KAAe,CAAC,CAAC;AACnC,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC"}

package/dist/rules/quota-headroom.d.ts

@@ -0,0 +1,10 @@
+import type { Rule } from '../types.js';
+/**
+ * R4 · quota-headroom — the file is approaching the per-database composite index limit.
+ *
+ * The limit is reached gradually and silently; the first symptom is a failed index creation at
+ * deploy time, which is a poor moment to discover it. Reporting headroom continuously makes the
+ * trend visible.
+ */
+export declare const quotaHeadroom: Rule;
+//# sourceMappingURL=quota-headroom.d.ts.map

package/dist/rules/quota-headroom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-headroom.d.ts","sourceRoot":"","sources":["../../src/rules/quota-headroom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,IAAI,EAAe,MAAM,aAAa,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,IA+B3B,CAAC"}

package/dist/rules/quota-headroom.js

@@ -0,0 +1,40 @@
+/**
+ * R4 · quota-headroom — the file is approaching the per-database composite index limit.
+ *
+ * The limit is reached gradually and silently; the first symptom is a failed index creation at
+ * deploy time, which is a poor moment to discover it. Reporting headroom continuously makes the
+ * trend visible.
+ */
+export const quotaHeadroom = {
+    id: 'quota-headroom',
+    description: 'the declared index count is close to the per-database limit',
+    check(context) {
+        const { quota, quotaThreshold } = context.options;
+        const count = context.document.indexes.length;
+        if (count <= quota * quotaThreshold)
+            return [];
+        const remaining = quota - count;
+        const headroom = remaining > 0
+            ? `${remaining} left before the limit`
+            : remaining === 0
+                ? 'the limit is exactly reached'
+                : `${-remaining} over the limit`;
+        const percent = formatPercent(quotaThreshold);
+        return [
+            {
+                rule: 'quota-headroom',
+                file: context.file,
+                // The subject is the file, not any one index (SPEC §5, R4).
+                key: null,
+                message: `${count} composite indexes declared, above ${percent} of the ${quota}-index limit ` +
+                    `(${headroom}). Index creation fails once the limit is reached, at deploy time.`,
+                related: [],
+            },
+        ];
+    },
+};
+function formatPercent(fraction) {
+    const percent = fraction * 100;
+    return `${Number.isInteger(percent) ? percent : percent.toFixed(1)}%`;
+}
+//# sourceMappingURL=quota-headroom.js.map

package/dist/rules/quota-headroom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-headroom.js","sourceRoot":"","sources":["../../src/rules/quota-headroom.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAS;IACjC,EAAE,EAAE,gBAAgB;IACpB,WAAW,EAAE,6DAA6D;IAE1E,KAAK,CAAC,OAAoB;QACxB,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;QAClD,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC;QAC9C,IAAI,KAAK,IAAI,KAAK,GAAG,cAAc;YAAE,OAAO,EAAE,CAAC;QAE/C,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;QAChC,MAAM,QAAQ,GACZ,SAAS,GAAG,CAAC;YACX,CAAC,CAAC,GAAG,SAAS,wBAAwB;YACtC,CAAC,CAAC,SAAS,KAAK,CAAC;gBACf,CAAC,CAAC,8BAA8B;gBAChC,CAAC,CAAC,GAAG,CAAC,SAAS,iBAAiB,CAAC;QACvC,MAAM,OAAO,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;QAE9C,OAAO;YACL;gBACE,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,4DAA4D;gBAC5D,GAAG,EAAE,IAAI;gBACT,OAAO,EACL,GAAG,KAAK,sCAAsC,OAAO,WAAW,KAAK,eAAe;oBACpF,IAAI,QAAQ,oEAAoE;gBAClF,OAAO,EAAE,EAAE;aACZ;SACF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,SAAS,aAAa,CAAC,QAAgB;IACrC,MAAM,OAAO,GAAG,QAAQ,GAAG,GAAG,CAAC;IAC/B,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AACxE,CAAC"}

package/dist/rules/scope-mismatch.d.ts

@@ -0,0 +1,10 @@
+import type { Rule } from '../types.js';
+/**
+ * R1 · scope-mismatch — one `collectionGroup` declaring more than one `queryScope`.
+ *
+ * A `COLLECTION`-scoped index does not serve a collection-group query, and vice versa, so an
+ * odd-one-out is frequently a mistake that only surfaces as a production `FAILED_PRECONDITION`.
+ * Querying a collection both ways is legitimate, which is why this warns rather than fails.
+ */
+export declare const scopeMismatch: Rule;
+//# sourceMappingURL=scope-mismatch.d.ts.map

package/dist/rules/scope-mismatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-mismatch.d.ts","sourceRoot":"","sources":["../../src/rules/scope-mismatch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA0B,IAAI,EAAe,MAAM,aAAa,CAAC;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,IA6C3B,CAAC"}

package/dist/rules/scope-mismatch.js

@@ -0,0 +1,45 @@
+import { compareStrings, groupBy, uniqueSorted } from '../collections.js';
+/**
+ * R1 · scope-mismatch — one `collectionGroup` declaring more than one `queryScope`.
+ *
+ * A `COLLECTION`-scoped index does not serve a collection-group query, and vice versa, so an
+ * odd-one-out is frequently a mistake that only surfaces as a production `FAILED_PRECONDITION`.
+ * Querying a collection both ways is legitimate, which is why this warns rather than fails.
+ */
+export const scopeMismatch = {
+    id: 'scope-mismatch',
+    description: 'one collectionGroup declares more than one queryScope',
+    check(context) {
+        const findings = [];
+        const byCollectionGroup = [...groupBy(context.indexes, (index) => index.collectionGroup)].sort(([a], [b]) => compareStrings(a, b));
+        for (const [collectionGroup, indexes] of byCollectionGroup) {
+            const byScope = groupBy(indexes, (index) => index.queryScope);
+            if (byScope.size < 2)
+                continue;
+            // Fewest indexes first; ties broken by scope name so the choice never depends on file order.
+            const ranked = [...byScope].sort(([aScope, a], [bScope, b]) => a.length - b.length || compareStrings(aScope, bScope));
+            const [flaggedScope, flaggedIndexes] = ranked[0];
+            const runnerUp = ranked[1];
+            const isStrictMinority = flaggedIndexes.length < runnerUp[1].length;
+            const census = [...byScope]
+                .sort(([a], [b]) => compareStrings(a, b))
+                .map(([scope, list]) => `${scope} (${list.length})`)
+                .join(', ');
+            const keys = uniqueSorted(flaggedIndexes.map((index) => index.key));
+            const verdict = isStrictMinority
+                ? `${flaggedScope} is the minority`
+                : 'No scope is in the minority';
+            findings.push({
+                rule: 'scope-mismatch',
+                file: context.file,
+                key: keys[0] ?? null,
+                message: `collectionGroup "${collectionGroup}" declares more than one queryScope: ${census}. ` +
+                    `${verdict}; confirm that each scope is intended, since an index of one scope does not ` +
+                    `serve a query of the other.`,
+                related: keys.slice(1),
+            });
+        }
+        return findings;
+    },
+};
+//# sourceMappingURL=scope-mismatch.js.map

package/dist/rules/scope-mismatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-mismatch.js","sourceRoot":"","sources":["../../src/rules/scope-mismatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG1E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAS;IACjC,EAAE,EAAE,gBAAgB;IACpB,WAAW,EAAE,uDAAuD;IAEpE,KAAK,CAAC,OAAoB;QACxB,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,MAAM,iBAAiB,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAC5F,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CACnC,CAAC;QAEF,KAAK,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,IAAI,iBAAiB,EAAE,CAAC;YAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAC9D,IAAI,OAAO,CAAC,IAAI,GAAG,CAAC;gBAAE,SAAS;YAE/B,6FAA6F;YAC7F,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAC9B,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CACpF,CAAC;YACF,MAAM,CAAC,YAAY,EAAE,cAAc,CAAC,GAAG,MAAM,CAAC,CAAC,CAA8B,CAAC;YAC9E,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAA8B,CAAC;YACxD,MAAM,gBAAgB,GAAG,cAAc,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAEpE,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC;iBACxB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;iBACxC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC;iBACnD,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,MAAM,IAAI,GAAG,YAAY,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YAEpE,MAAM,OAAO,GAAG,gBAAgB;gBAC9B,CAAC,CAAC,GAAG,YAAY,kBAAkB;gBACnC,CAAC,CAAC,6BAA6B,CAAC;YAClC,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI;gBACpB,OAAO,EACL,oBAAoB,eAAe,wCAAwC,MAAM,IAAI;oBACrF,GAAG,OAAO,8EAA8E;oBACxF,6BAA6B;gBAC/B,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;aACvB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC"}