indexwright 0.1.0

package/SPEC.md

@@ -0,0 +1,386 @@
+# indexwright — Specification
+
+Linter and query-coverage checker for Firestore composite indexes.
+
+Status: **v0.1.0 (draft)**. Pre-1.0: rules and CLI surface may change between minor versions.
+
+---
+
+## 1. Why this exists
+
+Firestore composite indexes are declared as data (`firestore.indexes.json`) and applied as
+whole-state. Three properties of the platform make that declaration hard to get right, and none of
+them are addressed by existing tooling.
+
+**The emulator does not enforce composite indexes.** The Firestore emulator "does not track
+composite indexes and instead executes any valid query." A query that will fail in production with
+`FAILED_PRECONDITION` passes locally. Strict indexing in the emulator is not a planned feature.
+
+**Firestore exposes no per-index usage metrics.** Index entry reads are billed but do not appear in
+the usage dashboard, and there is no index-level metric. You cannot ask the platform which of your
+indexes are actually used, so you cannot safely identify unused ones.
+
+**The index-matching rule is undocumented.** Google's documentation states that field ordering must
+be specified, but does not define how field order maps to query shape — in particular whether the
+relative order of equality and `array-contains` fields before the range fields affects matching.
+This means index changes cannot be validated against documentation; only empirically.
+
+The asymmetry is stark: security rules have an official test harness
+(`@firebase/rules-unit-testing`) and can be verified in the emulator. **Composite indexes have no
+equivalent.** A survey of GitHub and npm found no linter for `firestore.indexes.json`; the only
+adjacent projects are three abandoned index *generators* (0–6 stars, last pushed 2021–2025).
+
+Consequently, index declarations drift into states that are detectable by inspection but that
+nothing inspects: inconsistent `queryScope` within a collection, near-duplicate indexes that differ
+only in field order, artifacts of round-tripping through live exports, and silent approach to the
+per-database index quota.
+
+## 2. What this is not
+
+**indexwright cannot determine whether an index is needed.** That question requires the queries,
+which live in application code, not in the index declaration. No rule in this specification asserts
+that an index is unnecessary, and no output should be read as authorising a deletion.
+
+Deleting a composite index is not symmetric with adding one: an addition does not disturb existing
+queries while it backfills, but a deletion breaks its queries the moment it takes effect, and
+restoring it requires a fresh backfill. **A linter that only sees the declaration must never be the
+basis for a deletion.**
+
+What indexwright asserts is narrower and safer: *these declarations are structurally inconsistent
+with each other, and a human should look.*
+
+## 3. Scope
+
+### v0.1.0
+
+Static analysis of index declaration files. Four rules (§5). No network access, no credentials, no
+Firestore connection.
+
+### Planned
+
+- **v0.2 — query capture.** The Firestore emulator speaks the public Firestore v1 gRPC API in
+  plaintext on a local port. An intercepting proxy can decode `RunQuery` requests and record the
+  observed `StructuredQuery` shapes, yielding a query corpus harvested from execution rather than
+  hand-written. This is language- and framework-independent, because it operates on the wire
+  protocol rather than on source code.
+- **v0.3 — coverage check.** Replay a captured corpus against a throwaway Firestore database that
+  has the candidate index set applied, and report queries that fail with `FAILED_PRECONDITION`.
+  The oracle is Firestore itself; indexwright does not reimplement the undocumented matching rule.
+
+The v0.2/v0.3 split is deliberate: capture is cheap and offline, while the coverage decision is
+delegated to the platform. Reimplementing index matching would risk emitting false
+`FAILED_PRECONDITION` verdicts and blocking development on a rule that is not published.
+
+**Packaging of v0.2/v0.3.** Capture needs a gRPC stack — `@grpc/grpc-js` and protobuf definitions
+for the Firestore v1 API — and hand-writing a decoder for a wire format owned by someone else is
+not a cost worth paying. That collides with §7: `record` and `check` run inside an adopter's
+project, so their dependencies land in an adopter's tree, and the build-time carve-out does not
+reach them.
+
+They therefore ship as a separate package, `@indexwright/record`, which depends on `indexwright`
+for the index model and the `json` contract. **`indexwright` itself acquires no runtime dependency,
+in any version.**
+
+The split is not a workaround; it puts each cost where it is cheapest. `lint` runs on every push,
+in every CI job, in projects that may never touch Firestore from a server — that is where a
+transitive dependency tree is least welcome. `record` runs against a local emulator, in a project
+that is already talking to Firestore server-side and therefore already resolves `@grpc/grpc-js`
+transitively through `@google-cloud/firestore`. The dependency is added where it is very likely
+already resolved, and is absent where it would be new.
+
+The cost is a second package to discover. `indexwright record` in an installation that has only the
+linter must say where the verb lives, not report an unknown command.
+
+**Known limit of v0.2/v0.3:** coverage is bounded by what actually exercises the proxy. A query that
+no test issues is not observed, and absence of observation is not evidence that an index is unused.
+This limit is inherent, not an implementation gap.
+
+## 4. CLI
+
+```
+indexwright lint <file...> [options]
+
+Options:
+  --format <fmt>        text (default) | json | github
+  --max-warnings <n>    exit 1 if warnings exceed n (default: unlimited → always exit 0)
+  --rule <id>           run only the given rule; repeatable
+  --disable <id>        skip the given rule; repeatable
+  --quota <n>           per-database composite index limit for R4 (default: 1000)
+  --quota-threshold <p> warn above this fraction of the limit (default: 0.8)
+```
+
+### Exit codes
+
+| Code | Meaning |
+|-----:|:--------|
+| 0 | Completed. Warnings may have been emitted (default policy). |
+| 1 | Warning count exceeded `--max-warnings`. |
+| 2 | Usage error, unreadable file, or malformed input. |
+
+**The default is exit 0 even with findings.** A linter whose rules have unmeasured false-positive
+rates must not gate a pipeline by default. Adopters opt into enforcement with `--max-warnings`
+once they have measured their own noise level.
+
+### Input
+
+Any file in the `firestore.indexes.json` shape:
+
+```jsonc
+{
+  "indexes": [
+    {
+      "collectionGroup": "…",
+      "queryScope": "COLLECTION" | "COLLECTION_GROUP",
+      "fields": [ { "fieldPath": "…", "order": "ASCENDING" | "DESCENDING" }
+                | { "fieldPath": "…", "arrayConfig": "CONTAINS" }
+                | { "fieldPath": "…", "vectorConfig": { … } } ],
+      "density": "…"          // optional, passed through
+    }
+  ],
+  "fieldOverrides": [ … ]     // parsed, not analysed in v0.1.0
+}
+```
+
+Multiple files may be passed; each is analysed independently. Rules are not applied across files.
+
+### Validation
+
+A file is **malformed** when it is not valid JSON, when the top level is not an object, when
+`indexes` is absent or is not an array, when an index lacks `collectionGroup`, `queryScope`, or a
+non-empty `fields`, or when a field lacks `fieldPath` or declares none — or more than one — of
+`order`, `arrayConfig`, and `vectorConfig`.
+
+Nothing beyond that is refused. The *values* of `queryScope` and `order` are not checked against an
+enumeration, unknown keys anywhere are ignored, and a declaration that repeats a `fieldPath` within
+one index — which does occur in live exports — is carried through rather than rejected. Refusing to
+analyse a file is the harshest outcome available to a tool that otherwise only warns, and it costs
+the reader every other index in the file, so it is reserved for input that cannot be read as an
+index declaration at all.
+
+Malformed input does not abort the run. Each file is read and analysed on its own: files that parse
+are linted and their findings reported, files that do not are reported as errors, and the process
+exits 2 once every file has been handled. Reporting only the first bad file would hide findings in
+the files that were fine.
+
+## 5. Rules
+
+Every rule emits **warnings**, never errors. Each finding carries: rule id, file, a canonical index
+key, and a one-line reason. A finding that concerns the file as a whole rather than any particular
+index carries a **null** key.
+
+A rule whose subject is a *set* of indexes emits one grouped finding for that set, not one finding
+per member. The finding's `key` is the lexicographically smallest member key and `related` holds the
+remaining member keys, sorted ascending and de-duplicated. This keeps the warning count proportional
+to the number of problems rather than to the number of indexes, which matters because
+`--max-warnings` is counted in findings.
+
+### Canonical index key
+
+```
+<collectionGroup>::<queryScope>::<fieldPath>:<direction>|<fieldPath>:<direction>|…
+```
+
+where `direction` is `ASCENDING`, `DESCENDING`, `CONTAINS`, or — for a `vectorConfig` field —
+`VECTOR(<dimension>)`, written `VECTOR(?)` when no dimension is declared. A trailing implicit
+`__name__` entry is stripped before forming the key, so that declarations that differ only in
+whether the document key is written explicitly resolve to the same resource.
+
+### The implicit `__name__` direction
+
+Firestore appends the document key to every composite index, and its direction is not declared, so
+stripping it requires knowing which direction it would have had. indexwright defines that direction
+as **the `order` of the last preceding field that carries an `order`, or `ASCENDING` when no
+preceding field carries one** — the latter arising when the index ends with an `arrayConfig` field.
+
+This is not published behaviour. It is read off live exports, which render the key explicitly:
+`[type ASC, createdAt DESC, __name__ DESC]`, `[public ASC, startAt ASC, __name__ ASC]`, and
+`[isRecommended ASC, tags CONTAINS, __name__ ASC]` are all shapes an export produces.
+
+The definition is used only to decide whether a written `__name__` is redundant, and the decision is
+deliberately one-sided: a trailing `__name__` is stripped **only** when its direction equals the
+value above, and one that differs — `[totalNbUses DESC, __name__ ASC]` occurs in real exports — is
+treated as meaningful and kept. A wrong definition can therefore fail to merge two spellings of one
+index, but can never merge two indexes that are actually distinct.
+
+---
+
+### R1 · `scope-mismatch`
+
+**Detects.** Within one `collectionGroup`, more than one distinct `queryScope` is declared. One
+finding is emitted per affected `collectionGroup`, reporting how many indexes each scope holds.
+
+The scope with the fewest indexes is named as the minority, and the finding's keys are that scope's
+indexes. When no scope holds a strict minority — an even split — the finding says so instead of
+naming one, and reports the keys of the lexicographically first scope. It still fires: the detection
+condition is that the scopes disagree, and an even split is a disagreement. Suppressing it would
+narrow the rule to a shape the rule does not claim.
+
+**Rationale.** A `COLLECTION`-scoped index does not serve a collection-group query, and vice versa.
+When every other index on a collection uses one scope and a newly added one uses the other, the new
+declaration is frequently a mistake that will surface only as a production `FAILED_PRECONDITION`.
+
+**False positives.** Legitimate when an application queries the same collection both as a single
+collection and as a collection group. This is why the rule warns rather than fails.
+
+---
+
+### R2 · `field-order-variant`
+
+**Detects.** Two or more indexes that share `collectionGroup`, `queryScope`, and the same *set* of
+`fieldPath:direction` pairs, but declare them in different orders.
+
+"Same set" means the same *multiset*: a `fieldPath` that repeats within one index is unusual but not
+rejected (§4), and comparing multisets keeps the grouping well defined when it does. The comparison
+runs on the canonicalised field list, so an index that writes `__name__` explicitly groups with one
+that does not. Two indexes that are byte-identical do not constitute different orders and do not
+fire this rule.
+
+**Rationale.** Firestore treats a different field order as a different index. Each variant consumes
+write amplification, storage, and quota independently. Variants proliferate easily: a query change
+that reorders fields adds a new index without removing the old one, and round-tripping through a
+live export can reintroduce an ordering that was intended to be replaced.
+
+**False positives.** Legitimate when distinct queries genuinely require distinct orderings — for
+example, two queries that order by the same two fields in opposite directions. The finding asks for
+that justification to be recorded, not for one variant to be removed.
+
+**Output.** All members of the variant group are listed together, so the reader can judge the set
+rather than one member at a time.
+
+---
+
+### R3 · `explicit-name-field`
+
+**Detects.** An index whose **last** `fields` entry is an explicit `__name__` carrying the implicit
+default direction (§5, *The implicit `__name__` direction*). A `__name__` written anywhere other
+than last, or written last with a direction other than the default, is not flagged.
+
+**Rationale.** Firestore appends the document key implicitly; live exports render it explicitly.
+An explicit `__name__` in a hand-maintained declaration is therefore a signature of a value that
+round-tripped through an export rather than being authored directly. It does not change the
+resource identity, but it makes the file inconsistent and can mask genuine duplicates from
+naive text comparison.
+
+**False positives.** Explicit `__name__` with a direction that differs from the implicit default is
+meaningful and should not be flagged. The rule only fires on a trailing `__name__` matching the
+implicit default.
+
+---
+
+### R4 · `quota-headroom`
+
+**Detects.** The number of composite indexes in the file exceeds `--quota-threshold` of `--quota`.
+
+**Rationale.** Composite indexes are capped per database. 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.
+
+The comparison is a strict `count > quota × threshold`, so the defaults (1000, 0.8) fire at 801.
+
+**False positives.** None in principle; the threshold is configurable because appropriate headroom
+depends on the rate of index growth.
+
+**Output.** The finding is about the file, not about any one index, so its `key` is `null` and its
+`related` is empty. One finding per file at most.
+
+## 6. Output formats
+
+**`text`** — human-readable, grouped by rule, intended for a terminal.
+
+**`json`** — a stable machine-readable shape:
+
+```jsonc
+{
+  "version": "0.1.0",
+  "files": ["…"],
+  "summary": { "warnings": 0, "errors": 0, "byRule": { "scope-mismatch": 0, … } },
+  "findings": [
+    {
+      "rule": "scope-mismatch",
+      "file": "…",
+      "key": "…",             // null for a finding about the file as a whole
+      "message": "…",
+      "related": ["…"]        // other keys in the same finding group; [] when there are none
+    }
+  ],
+  "errors": [
+    { "file": "…", "message": "…" }   // files that could not be read or parsed
+  ]
+}
+```
+
+`files` lists every file the run was given, whether or not it parsed, sorted by path. `byRule` holds
+one entry for every rule that ran after `--rule` and `--disable` were applied, including rules that
+found nothing; a rule that did not run is absent rather than zero. `findings` is sorted by file,
+then by rule in the order of §5, then by key with a null key sorting first. `related` is sorted
+ascending. `errors` is sorted by file. Every field is always present: `related` is `[]` rather than
+omitted, and `errors` is `[]` on a clean run.
+
+**`github`** — GitHub Actions workflow commands (`::warning file=…::`) plus a Markdown summary
+suitable for `$GITHUB_STEP_SUMMARY`.
+
+## 7. Design principles
+
+**Warn, do not fail.** The rules encode heuristics whose false-positive rates are, at v0.1.0,
+unmeasured. Shipping them as blocking checks would teach users to suppress the tool. Enforcement is
+opt-in and per-adopter.
+
+**Never authorise a deletion.** See §2. No output phrasing may suggest that an index is unused or
+safe to remove.
+
+**No dependencies in `indexwright`.** A linter that pulls a dependency tree into a build pipeline
+undermines its own purpose. Argument parsing and formatting are implemented in-tree, and the
+published package declares no runtime dependencies. This is a property of the package rather than
+an aspiration of the project: it holds in every version, and a test asserts it.
+
+The principle is about what lands in an adopter's tree, so build- and test-time tooling that never
+ships is out of its scope. It is not a claim that no part of indexwright may depend on anything.
+Where a verb needs a library it cannot reasonably write — the gRPC stack behind `record` (§3) —
+that verb ships as its own package instead of as a dependency of the linter. What the principle
+forbids is making every adopter of `lint` pay for it.
+
+**No network, no credentials, in `lint`.** Static analysis must be runnable in any environment,
+including a sandboxed CI step with no cloud access. Network use is confined to the planned
+`record`/`check` verbs, which are separate commands in a separate package (§3).
+
+**Delegate undocumented semantics to the platform.** Where Firestore's behaviour is not published —
+principally index matching — indexwright measures rather than models. This bounds what the tool can
+claim, which is the point.
+
+**Deterministic output.** Findings are emitted in a stable sort order (file, rule, key), so that
+output can be diffed across runs.
+
+## 8. Testing
+
+Rules are tested against small hand-written fixtures that isolate one condition each, with explicit
+positive and negative cases.
+
+**Assertions are never written against a real project's index file.** A test that asserts a finding
+count over live data fails whenever that data legitimately changes, which trains maintainers to
+edit the test rather than read it. Fixtures encode the invariant; real files are for manual
+exploration only.
+
+## 9. Compatibility
+
+- Node.js ≥ 22, ESM.
+- Input schema follows the Firebase CLI's `firestore.indexes.json`. Unknown keys are preserved and
+  ignored rather than rejected, so that a newer field does not break linting.
+- Semantic versioning. Pre-1.0, rule additions and message changes may land in minor releases;
+  the `json` output shape is the stable contract and changes only in major releases after 1.0.
+- The package also exports a JavaScript API, so the rules can be run without spawning a process.
+  That API is **provisional**: it is not part of the stable contract before 1.0 and may change in
+  any minor release. Only the `json` output shape carries the compatibility promise.
+- indexwright is published as a family: `indexwright`, the linter, which carries no runtime
+  dependencies, and — from v0.2 — `@indexwright/record`, capture and coverage, which depends on the
+  linter and on a gRPC stack (§3). They version independently; `@indexwright/record` declares the
+  range of `indexwright` whose `json` contract it reads.
+
+## 10. Toward 1.0
+
+1.0 requires, at minimum:
+
+- Measured false-positive rates for R1 and R2 across more than one real project.
+- At least one adopter outside the project of origin.
+- A decision, informed by that data, on whether any rule should default to failing.
+
+Until then the version stays below 1.0 and the README states plainly that the rules are provisional.

package/dist/args.d.ts

@@ -0,0 +1,26 @@
+import type { OutputFormat, RuleId } from './types.js';
+/** Anything the user could have typed differently. Mapped to exit code 2. */
+export declare class UsageError extends Error {
+    readonly name = "UsageError";
+}
+export interface LintCommand {
+    kind: 'lint';
+    files: string[];
+    format: OutputFormat;
+    maxWarnings: number;
+    rules: RuleId[];
+    quota: number;
+    quotaThreshold: number;
+}
+export type Command = LintCommand | {
+    kind: 'help';
+} | {
+    kind: 'version';
+};
+/**
+ * Parsed in-tree rather than with a dependency (SPEC §7). Supports `--flag value` and
+ * `--flag=value`, and `--` to end option parsing.
+ */
+export declare function parseArgs(argv: readonly string[]): Command;
+export declare function usage(): string;
+//# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEvD,6EAA6E;AAC7E,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,gBAAgB;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAI3E;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA6E1D;AA+DD,wBAAgB,KAAK,IAAI,MAAM,CA0B9B"}

package/dist/args.js

@@ -0,0 +1,170 @@
+import { DEFAULT_QUOTA, DEFAULT_QUOTA_THRESHOLD } from './lint.js';
+import { isRuleId, rules } from './rules/index.js';
+import { RULE_IDS } from './types.js';
+/** Anything the user could have typed differently. Mapped to exit code 2. */
+export class UsageError extends Error {
+    name = 'UsageError';
+}
+const FORMATS = ['text', 'json', 'github'];
+/**
+ * Parsed in-tree rather than with a dependency (SPEC §7). Supports `--flag value` and
+ * `--flag=value`, and `--` to end option parsing.
+ */
+export function parseArgs(argv) {
+    if (argv.length === 0)
+        throw new UsageError('no command given');
+    if (argv.includes('--help') || argv.includes('-h'))
+        return { kind: 'help' };
+    if (argv.includes('--version'))
+        return { kind: 'version' };
+    const [command, ...rest] = argv;
+    if (command !== 'lint') {
+        throw new UsageError(`unknown command "${command}"; the only command is "lint"`);
+    }
+    const files = [];
+    let format = 'text';
+    let maxWarnings = Number.POSITIVE_INFINITY;
+    let quota = DEFAULT_QUOTA;
+    let quotaThreshold = DEFAULT_QUOTA_THRESHOLD;
+    const selected = [];
+    const disabled = [];
+    for (let i = 0; i < rest.length; i += 1) {
+        const argument = rest[i];
+        if (argument === '--') {
+            files.push(...rest.slice(i + 1));
+            break;
+        }
+        if (!argument.startsWith('--')) {
+            files.push(argument);
+            continue;
+        }
+        const equals = argument.indexOf('=');
+        const name = equals === -1 ? argument : argument.slice(0, equals);
+        const inlineValue = equals === -1 ? null : argument.slice(equals + 1);
+        const takeValue = () => {
+            if (inlineValue !== null)
+                return inlineValue;
+            const next = rest[i + 1];
+            if (next === undefined)
+                throw new UsageError(`${name} needs a value`);
+            i += 1;
+            return next;
+        };
+        switch (name) {
+            case '--format':
+                format = parseFormat(takeValue());
+                break;
+            case '--max-warnings':
+                maxWarnings = parseCount(takeValue(), name);
+                break;
+            case '--rule':
+                selected.push(parseRuleId(takeValue(), name));
+                break;
+            case '--disable':
+                disabled.push(parseRuleId(takeValue(), name));
+                break;
+            case '--quota':
+                quota = parsePositiveInteger(takeValue(), name);
+                break;
+            case '--quota-threshold':
+                quotaThreshold = parseFraction(takeValue(), name);
+                break;
+            default:
+                throw new UsageError(`unknown option "${name}"`);
+        }
+    }
+    if (files.length === 0)
+        throw new UsageError('no input files given');
+    return {
+        kind: 'lint',
+        // De-duplicated so a shell glob that repeats a path does not double every finding.
+        files: [...new Set(files)],
+        format,
+        maxWarnings,
+        rules: resolveRules(selected, disabled),
+        quota,
+        quotaThreshold,
+    };
+}
+function resolveRules(selected, disabled) {
+    const base = selected.length > 0 ? new Set(selected) : new Set(RULE_IDS);
+    for (const id of disabled)
+        base.delete(id);
+    if (base.size === 0) {
+        throw new UsageError('--rule and --disable leave no rules to run');
+    }
+    return RULE_IDS.filter((id) => base.has(id));
+}
+function parseFormat(value) {
+    if (!FORMATS.includes(value)) {
+        throw new UsageError(`unknown format "${value}"; expected one of ${FORMATS.join(', ')}`);
+    }
+    return value;
+}
+/** A typo must not silently produce a clean run, so an unknown rule id is a usage error. */
+function parseRuleId(value, option) {
+    if (!isRuleId(value)) {
+        throw new UsageError(`unknown rule "${value}" for ${option}; expected one of ${RULE_IDS.join(', ')}`);
+    }
+    return value;
+}
+/** A plain decimal numeral, with or without a fractional part: `5`, `0.8`, `.8`, `-1`. */
+const DECIMAL = /^-?(\d+(\.\d*)?|\.\d+)$/;
+/**
+ * `Number` reads `""` as 0, ignores surrounding whitespace, and reads `"0x10"` as 16. A CI step
+ * that writes `--max-warnings=$LIMIT` with `LIMIT` unset would therefore turn "unlimited" into
+ * "zero tolerance" silently, so an option value has to be a numeral and nothing else. `NaN` fails
+ * every caller's range check, which reports it as the usage error it is.
+ */
+function toNumber(value) {
+    return DECIMAL.test(value) ? Number(value) : Number.NaN;
+}
+function parseCount(value, option) {
+    const parsed = toNumber(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new UsageError(`${option} needs a non-negative integer, got "${value}"`);
+    }
+    return parsed;
+}
+function parsePositiveInteger(value, option) {
+    const parsed = toNumber(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new UsageError(`${option} needs a positive integer, got "${value}"`);
+    }
+    return parsed;
+}
+function parseFraction(value, option) {
+    const parsed = toNumber(value);
+    if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1) {
+        throw new UsageError(`${option} needs a number in (0, 1], got "${value}"`);
+    }
+    return parsed;
+}
+export function usage() {
+    const ruleLines = rules.map((rule) => `  ${rule.id.padEnd(21)}${rule.description}`);
+    return [
+        'indexwright lint <file...> [options]',
+        '',
+        'Lints Firestore composite index declarations. Every rule emits warnings, never errors.',
+        'No finding indicates that an index is unused or safe to delete.',
+        '',
+        'Options:',
+        '  --format <fmt>        text (default) | json | github',
+        '  --max-warnings <n>    exit 1 if warnings exceed n (default: unlimited)',
+        '  --rule <id>           run only the given rule; repeatable',
+        '  --disable <id>        skip the given rule; repeatable',
+        `  --quota <n>           per-database composite index limit (default: ${DEFAULT_QUOTA})`,
+        `  --quota-threshold <p> warn above this fraction of the limit (default: ${DEFAULT_QUOTA_THRESHOLD})`,
+        '  -h, --help            show this message',
+        '      --version         show the version',
+        '',
+        'Rules:',
+        ...ruleLines,
+        '',
+        'Exit codes:',
+        '  0  completed; warnings may have been emitted',
+        '  1  warning count exceeded --max-warnings',
+        '  2  usage error, unreadable file, or malformed input',
+    ].join('\n');
+}
+//# sourceMappingURL=args.js.map

package/dist/args.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+export interface Streams {
+    out(text: string): void;
+    err(text: string): void;
+}
+/**
+ * Exit codes (SPEC §4): 0 completed, 1 warnings over the budget, 2 usage error or unusable input.
+ * A file that could not be analysed is a 2 regardless of `--max-warnings`, because the run did not
+ * cover what it was asked to cover.
+ */
+export declare function run(argv: readonly string[], streams: Streams): number;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAWA,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CA2CrE"}