react-doctor 0.2.14-dev.7b4ddf7 → 0.2.14-dev.8921575

package/dist/index.d.ts

@@ -5,13 +5,35 @@ import * as Cause from "effect/Cause";
 //#region src/types/config.d.ts
 type FailOnLevel = "error" | "warning" | "none";
 interface ReactDoctorIgnoreOverride {
+  /** Glob patterns the override applies to (e.g. `["src/legacy/**"]`). */
   files: string[];
+  /**
+   * Rule keys to suppress for the matched files. Omit (or leave empty) to
+   * suppress every rule for those files.
+   */
   rules?: string[];
 }
 interface ReactDoctorIgnoreConfig {
+  /**
+   * Fully-qualified rule keys (`"<plugin>/<rule>"`) whose diagnostics are
+   * dropped AFTER linting. The rule still runs; its findings are filtered
+   * out. To stop a rule from running at all, set it to `"off"` in the
+   * top-level `rules` map instead. Prefer `react-doctor rules disable
+   * <rule>` to edit this safely.
+   */
   rules?: string[];
+  /**
+   * Glob patterns whose files are excluded from scanning entirely (matched
+   * against paths relative to the scanned directory).
+   */
   files?: string[];
+  /** Per-path rule suppressions — narrower than the top-level `rules`/`files`. */
   overrides?: ReactDoctorIgnoreOverride[];
+  /**
+   * Behavioral tags whose rules are disabled BEFORE linting, skipping a
+   * whole family at once (e.g. `["design", "test-noise", "migration-hint"]`).
+   * Prefer `react-doctor rules ignore-tag <tag>` to edit this safely.
+   */
   tags?: string[];
 }
 /**
@@ -20,9 +42,9 @@ interface ReactDoctorIgnoreConfig {
  * locally but excluded from PR comments, the score, or the CI gate:
  *
  * - `cli` — local terminal output from `react-doctor` (`printDiagnostics`).
- * - `prComment` — output captured by the GitHub Action for the sticky
- *   PR comment. Enabled when the CLI is run with `--pr-comment` (the
- *   action sets this automatically when `github-token` is provided).
+ * - `prComment` — diagnostics destined for a sticky pull-request
+ *   summary comment. Selected by running the CLI with `--pr-comment`
+ *   (sets `outputSurface: "prComment"`).
  * - `score` — diagnostics shipped to the React Doctor score API
  *   (or counted toward local score calculations).
  * - `ciFailure` — diagnostics that count toward the `--fail-on` exit
@@ -53,6 +75,14 @@ type RuleSeverityOverride = "error" | "warn" | "off";
  * `rules` and `categories` fields on `ReactDoctorConfig`. Per-rule
  * wins over per-category when both match the same diagnostic.
  */
+/**
+ * Closed set of severity buckets. Spelled out (rather than
+ * `Record<string, …>`) so an unknown/typo'd bucket key is a type error
+ * instead of a silent no-op.
+ */
+interface SeverityBuckets {
+  "compiler-cleanup"?: RuleSeverityOverride;
+}
 interface SurfaceControls {
   /**
    * Tag names whose diagnostics should be force-included on the surface,
@@ -66,9 +96,9 @@ interface SurfaceControls {
    * `["test-noise"]`) for a single channel without touching others.
    */
   excludeTags?: string[];
-  /** Category names (e.g. `"Architecture"`) to force-include. */
+  /** Category names (e.g. `"Maintainability"`) to force-include. */
   includeCategories?: string[];
-  /** Category names (e.g. `"Architecture"`) to exclude. */
+  /** Category names (e.g. `"Maintainability"`) to exclude. */
   excludeCategories?: string[];
   /**
    * Fully-qualified rule keys (`"<plugin>/<rule>"`, e.g.
@@ -85,12 +115,23 @@ interface ReactDoctorConfig {
   /**
    * Whether to run dead-code analysis (via `deslop-js`) alongside lint.
    * Reports unused files, unused exports, unused dependencies, and
-   * circular imports under the "Dead Code" category. Default: `true`.
+   * circular imports under the "Maintainability" category. Default: `true`.
    * Always skipped in `--diff` / `--staged` modes because reachability
    * is a whole-project property.
    */
   deadCode?: boolean;
   verbose?: boolean;
+  /**
+   * Whether to surface `"warning"`-severity diagnostics. Default: `true`
+   * — every warning reaches every surface (CLI, PR comment, score,
+   * `--fail-on`).
+   *
+   * Set to `false` to surface only `"error"`-severity findings. This is the
+   * master toggle and runs after per-rule / per-category severity
+   * overrides: a rule the user explicitly restamps to `"warn"` (via
+   * `rules` / `categories`) still shows even when `warnings` is `false`.
+   */
+  warnings?: boolean;
   diff?: boolean | string;
   failOn?: FailOnLevel;
   customRulesOnly?: boolean;
@@ -103,7 +144,7 @@ interface ReactDoctorConfig {
    * the redirect is stable no matter where the CLI / `diagnose()` is
    * run from. Absolute paths are used as-is.
    *
-   * Typical use: a monorepo root holds the only `react-doctor.config.json`
+   * Typical use: a monorepo root holds the only `doctor.config.*`
    * (so editor tooling and child commands all find it), but the React
    * app lives in `apps/web`. Setting `"rootDir": "apps/web"` makes
    * every invocation that loads this config scan that subproject
@@ -229,15 +270,12 @@ interface ReactDoctorConfig {
   rules?: Record<string, RuleSeverityOverride>;
   /**
    * Per-category severity map. Mirrors oxlint's top-level
-   * `categories` field, but keyed by React Doctor's display
-   * categories (`"Server"`, `"React Native"`, `"Architecture"`,
-   * `"Bundle Size"`, `"State & Effects"`, `"Security"`,
-   * `"Accessibility"`, `"Performance"`, `"Correctness"`,
-   * `"Next.js"`, `"Preact"`, `"TanStack Query"`,
-   * `"TanStack Start"`, …).
+   * `categories` field, but keyed by React Doctor's five user-facing
+   * buckets: `"Security"`, `"Bugs"`, `"Performance"`,
+   * `"Accessibility"`, `"Maintainability"`.
    *
    * ```json
-   * { "categories": { "React Native": "warn", "Server": "off" } }
+   * { "categories": { "Maintainability": "off", "Performance": "warn" } }
    * ```
    *
    * To silence a whole tag-defined rule family (e.g. `"design"`,
@@ -245,6 +283,20 @@ interface ReactDoctorConfig {
    * single category, use `ignore.tags` instead.
    */
   categories?: Record<string, RuleSeverityOverride>;
+  /**
+   * Per-bucket severity map. Buckets are curated rule families with a
+   * shared gating story (not categories). Today the only bucket is
+   * `"compiler-cleanup"`: the redundant-memoization rule
+   * (`react-compiler-no-manual-memoization`) that ships as a warning once
+   * React Compiler is detected. Set it to `"error"` to re-enable strictness.
+   *
+   * ```json
+   * { "buckets": { "compiler-cleanup": "error" } }
+   * ```
+   *
+   * A per-rule override in `rules` still wins over a bucket entry.
+   */
+  buckets?: SeverityBuckets;
   /**
    * User-defined oxlint plugins to load alongside the built-in
    * `react-doctor` plugin. Each entry is either:
@@ -288,6 +340,7 @@ interface Diagnostic {
   plugin: string;
   rule: string;
   severity: "error" | "warning";
+  title?: string;
   message: string;
   help: string;
   url?: string;
@@ -338,6 +391,22 @@ interface ProjectInfo {
    * — no `rn-*` rules load for the project at all.
    */
   hasReactNativeWorkspace: boolean;
+  /**
+   * The declared `expo` package version spec (e.g. `"~51.0.0"`), looked up
+   * in the project or any of its workspace packages, or `null` when `expo`
+   * isn't a dependency. Doubles as react-doctor's "is this an Expo project?"
+   * signal (`expoVersion !== null`) and its SDK-version source — the `expo`
+   * major tracks the Expo SDK release one-to-one — paralleling how
+   * `reactVersion` models the React runtime.
+   *
+   * Keyed off the dependency rather than `framework === "expo"` because
+   * `detectFramework` returns the first matching package, so a project
+   * declaring both `expo` and a web bundler (`vite` / `next`) classifies as
+   * the web framework yet is still an Expo project. Drives the `expo`
+   * capability in `buildCapabilities` (which gates every Expo-specific
+   * rule) and the ported expo-doctor checks.
+   */
+  expoVersion: string | null;
   /**
    * `true` when the project (or any of its workspace packages) declares
    * `react-native-reanimated`. Lets diagnostics surface reanimated's
@@ -349,9 +418,15 @@ interface ProjectInfo {
 }
 //#endregion
 //#region src/types/score.d.ts
+type RuleTier = "P0" | "P1" | "P2" | "P3";
+interface RulePriority {
+  readonly priority: number | null;
+  readonly tier: RuleTier;
+}
 interface ScoreResult {
   score: number;
   label: string;
+  readonly rules?: Readonly<Record<string, RulePriority>>;
 } //#endregion
 //#region src/types/diagnose.d.ts
 interface DiagnoseOptions {
@@ -365,6 +440,12 @@ interface DiagnoseOptions {
    * See that field's docs for the full contract.
    */
   respectInlineDisables?: boolean;
+  /**
+   * Per-call override for `ReactDoctorConfig.warnings`. See that field's
+   * docs — `"warning"`-severity diagnostics surface by default unless this
+   * (or the config) opts out via `false`.
+   */
+  warnings?: boolean;
 }
 interface DiagnoseResult {
   diagnostics: Diagnostic[];
@@ -385,7 +466,7 @@ interface DiagnoseResult {
  * Scan options (`deadCode`, `lint`, etc.) are flat on the entry and
  * layer on top of the global defaults — omitted fields fall through.
  * `config` is a full `ReactDoctorConfig` override that replaces the
- * on-disk `react-doctor.config.json` for this project's scan.
+ * on-disk `doctor.config.*` for this project's scan.
  */
 //#endregion
 //#region src/types/inspect.d.ts
@@ -404,6 +485,28 @@ interface InspectResult {
   skippedCheckReasons?: Record<string, string>;
   project: ProjectInfo;
   elapsedMilliseconds: number;
+  /**
+   * Number of files the scan reported. Distinct from
+   * `project.sourceFileCount` in diff / staged mode (where only changed
+   * files are scanned). Optional so non-orchestrator constructors keep
+   * working; the multi-project summary falls back to
+   * `project.sourceFileCount` when absent.
+   */
+  scannedFileCount?: number;
+  /**
+   * Absolute paths of every file the scan considered. Lets the
+   * multi-project summary count UNIQUE files across projects instead of
+   * summing per-project counts, which double-counts shared files when one
+   * workspace package's tree is nested inside another's.
+   */
+  scannedFilePaths?: ReadonlyArray<string>;
+  /**
+   * Wall-clock duration of the scan phase, in milliseconds. Distinct
+   * from `elapsedMilliseconds` (which spans the full `inspect()` call
+   * including score fetch + rendering). Used by the multi-project
+   * summary to report combined scan time.
+   */
+  scanElapsedMilliseconds?: number;
 }
 /**
  * Options accepted by `inspect()`. Mixes two concern groups; ordered
@@ -661,7 +764,7 @@ interface BuildJsonReportInput {
   totalElapsedMilliseconds: number;
 }
 declare const buildJsonReport: (input: BuildJsonReportInput) => JsonReport; //#endregion
-//#region src/can-oxlint-extend-config.d.ts
+//#region src/build-skipped-checks.d.ts
 //#endregion
 //#region src/get-diff-files.d.ts
 /**