indexwright 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The shapes indexwright reads and produces.
+ *
+ * The input types mirror `firestore.indexes.json` loosely on purpose: unknown keys are carried
+ * through rather than rejected, so a field added by a future Firebase release does not break
+ * linting (SPEC §9).
+ */
+/** One entry of an index's `fields` array. */
+export interface IndexField {
+    fieldPath: string;
+    /** `ASCENDING` or `DESCENDING` in practice; not validated against an enumeration. */
+    order?: string;
+    /** `CONTAINS` in practice; not validated against an enumeration. */
+    arrayConfig?: string;
+    vectorConfig?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** One entry of the document's `indexes` array. */
+export interface CompositeIndex {
+    collectionGroup: string;
+    /** `COLLECTION` or `COLLECTION_GROUP` in practice; not validated against an enumeration. */
+    queryScope: string;
+    fields: IndexField[];
+    [key: string]: unknown;
+}
+/** A parsed and validated `firestore.indexes.json`. */
+export interface IndexDocument {
+    indexes: CompositeIndex[];
+    fieldOverrides?: unknown[];
+    [key: string]: unknown;
+}
+/** A field reduced to the two things the canonical key is built from. */
+export interface CanonicalField {
+    fieldPath: string;
+    /** `ASCENDING`, `DESCENDING`, `CONTAINS`, or `VECTOR(<dimension>)`. */
+    direction: string;
+}
+/** An index with its canonical form precomputed, so every rule shares one interpretation. */
+export interface AnalysedIndex {
+    /** The declaration as written, including any keys indexwright does not understand. */
+    readonly source: CompositeIndex;
+    /** Position within the document's `indexes` array, for messages that need to point at one. */
+    readonly position: number;
+    readonly collectionGroup: string;
+    readonly queryScope: string;
+    /** Canonicalised fields: a trailing implicit `__name__` has been removed. */
+    readonly fields: readonly CanonicalField[];
+    readonly key: string;
+    /**
+     * The direction of a trailing `__name__` that matched the implicit default and was therefore
+     * removed, or `null` when the declaration had no redundant `__name__`.
+     */
+    readonly redundantNameDirection: string | null;
+}
+export declare const RULE_IDS: readonly ["scope-mismatch", "field-order-variant", "explicit-name-field", "quota-headroom"];
+export type RuleId = (typeof RULE_IDS)[number];
+/** A single warning. Never an error: see SPEC §7. */
+export interface Finding {
+    rule: RuleId;
+    file: string;
+    /** `null` when the finding is about the file rather than about one index. */
+    key: string | null;
+    message: string;
+    /** Other keys in the same finding group, sorted ascending. `[]` when there are none. */
+    related: string[];
+}
+/** A file that could not be read or parsed. Distinct from a finding. */
+export interface LintError {
+    file: string;
+    message: string;
+}
+export interface LintSummary {
+    warnings: number;
+    errors: number;
+    /** One entry per rule that ran, including rules that found nothing. */
+    byRule: Record<string, number>;
+}
+export interface LintResult {
+    version: string;
+    files: string[];
+    summary: LintSummary;
+    findings: Finding[];
+    errors: LintError[];
+}
+export interface RuleOptions {
+    /** Per-database composite index limit used by `quota-headroom`. */
+    quota: number;
+    /** Fraction of `quota` above which `quota-headroom` warns. */
+    quotaThreshold: number;
+}
+export interface RuleContext {
+    file: string;
+    document: IndexDocument;
+    indexes: readonly AnalysedIndex[];
+    options: RuleOptions;
+}
+export interface Rule {
+    readonly id: RuleId;
+    /** One line, used by `--help`. */
+    readonly description: string;
+    check(context: RuleContext): Finding[];
+}
+export type OutputFormat = 'text' | 'json' | 'github';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * The shapes indexwright reads and produces.
+ *
+ * The input types mirror `firestore.indexes.json` loosely on purpose: unknown keys are carried
+ * through rather than rejected, so a field added by a future Firebase release does not break
+ * linting (SPEC §9).
+ */
+export const RULE_IDS = [
+    'scope-mismatch',
+    'field-order-variant',
+    'explicit-name-field',
+    'quota-headroom',
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsDH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,gBAAgB;IAChB,qBAAqB;IACrB,qBAAqB;IACrB,gBAAgB;CACR,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,OAAO,EAAE,MAAsB,CAAC"}

package/dist/version.js

@@ -0,0 +1,11 @@
+import { readFileSync } from 'node:fs';
+/**
+ * Read from package.json rather than duplicated in source, so a release cannot ship a `version`
+ * field in the JSON output that disagrees with the package it came from.
+ */
+function readVersion() {
+    const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return typeof manifest.version === 'string' ? manifest.version : '0.0.0';
+}
+export const VERSION = readVersion();
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;GAGG;AACH,SAAS,WAAW;IAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CACzC,CAAC;IAC3B,OAAO,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AAC3E,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAW,WAAW,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "indexwright",
+  "version": "0.1.0",
+  "description": "Linter for Firestore composite index declarations (firestore.indexes.json)",
+  "keywords": [
+    "firestore",
+    "firebase",
+    "index",
+    "composite-index",
+    "linter",
+    "static-analysis"
+  ],
+  "homepage": "https://github.com/uny/indexwright#readme",
+  "bugs": "https://github.com/uny/indexwright/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uny/indexwright.git"
+  },
+  "license": "Apache-2.0",
+  "author": "Yuki Nagai",
+  "type": "module",
+  "bin": {
+    "indexwright": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "SPEC.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc --build --force",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test \"test/*.test.js\"",
+    "verify-package": "npm run build && node scripts/verify-package.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}