feat: per-module scoring via diagnose({ projects }), CLI --project paths, and config projects

packages/api/src/diagnose.ts

@@ -3,13 +3,16 @@ import * as Layer from "effect/Layer";
 import {
   buildSkippedChecks,
   Config,
+  DEFAULT_PROJECT_SCAN_CONCURRENCY,
   DEFAULT_SHOW_WARNINGS,
   DeadCode,
   Files,
   Git,
   layerOtlp,
   Linter,
   LintPartialFailures,
+  mapWithConcurrency,
+  mergeReactDoctorConfigs,
   Progress,
   Project,
   Reporter,
@@ -41,15 +44,15 @@ import type {
 // stack is built once here rather than duplicated per variant.
 const buildDiagnoseLayer = (
   config: ReactDoctorConfig | null,
-  configOverride?: { readonly resolvedDirectory: string },
+  configOverrideTarget?: Pick<ResolvedScanTarget, "resolvedDirectory" | "configSourceDirectory">,
 ) => {
   const configLayer =
-    configOverride === undefined
+    configOverrideTarget === undefined
       ? Config.layerNode
       : Config.layerOf({
           config,
-          resolvedDirectory: configOverride.resolvedDirectory,
-          configSourceDirectory: null,
+          resolvedDirectory: configOverrideTarget.resolvedDirectory,
+          configSourceDirectory: configOverrideTarget.configSourceDirectory,
         });
   return Layer.mergeAll(
     Project.layerNode,
@@ -113,9 +116,9 @@ const outputToDiagnoseResult = (
   };
 };
 
-export const diagnose = async (
+const diagnoseDirectory = async (
   directory: string,
-  options: DiagnoseOptions = {},
+  options: DiagnoseOptions,
 ): Promise<DiagnoseResult> => {
   const startTime = globalThis.performance.now();
   const scanTarget = await resolveScanTarget(directory);
@@ -149,21 +152,40 @@ const findWorstScore = (projectResults: ProjectResult[]): ScoreResult | null =>
 const diagnoseProject = async (
   projectDefinition: ProjectDefinition,
   baseOptions: DiagnoseOptions,
+  batchConfig: ReactDoctorConfig | undefined,
 ): Promise<ProjectResult> => {
   const startTime = globalThis.performance.now();
 
   try {
     const scanTarget = await resolveScanTarget(projectDefinition.directory);
-    const { directory: _, config: configOverride, ...perProjectOptions } = projectDefinition;
-    const mergedOptions: DiagnoseOptions = { ...baseOptions, ...perProjectOptions };
+    const { directory: _, config: projectConfig, ...perProjectOptions } = projectDefinition;
 
-    const program = buildInspectProgram(scanTarget, mergedOptions, configOverride);
+    // Config layers, least to most specific: on-disk `doctor.config.*` ←
+    // batch `config` ← per-project `config`. With no overrides the merge is
+    // the identity and the orchestrator loads from disk (`Config.layerNode`).
+    const didOverrideConfig = batchConfig !== undefined || projectConfig !== undefined;
+    const effectiveConfig = mergeReactDoctorConfigs(
+      mergeReactDoctorConfigs(scanTarget.userConfig, batchConfig),
+      projectConfig,
+    );
 
-    const effectiveConfig = configOverride ?? scanTarget.userConfig;
+    const program = buildInspectProgram(
+      scanTarget,
+      { ...baseOptions, ...perProjectOptions },
+      effectiveConfig ?? undefined,
+    );
+    // `plugins` is override-wins in the merge: when a caller layer supplies
+    // it, relative entries resolve against the scan root (caller configs
+    // have no file location); otherwise the on-disk config's directory.
+    const didOverridePlugins =
+      batchConfig?.plugins !== undefined || projectConfig?.plugins !== undefined;
     const layer = buildDiagnoseLayer(
       effectiveConfig,
-      configOverride !== undefined
-        ? { resolvedDirectory: scanTarget.resolvedDirectory }
+      didOverrideConfig
+        ? {
+            resolvedDirectory: scanTarget.resolvedDirectory,
+            configSourceDirectory: didOverridePlugins ? null : scanTarget.configSourceDirectory,
+          }
         : undefined,
     );
 
@@ -185,76 +207,52 @@ const diagnoseProject = async (
   }
 };
 
-/**
- * Scan multiple projects in parallel and return per-project scores,
- * diagnostics, and an aggregate score (worst-of across all projects).
- *
- * Each project runs its own independent `runInspect` pipeline — the
- * same pipeline `diagnose()` uses — so per-project config overrides,
- * dead-code analysis, and scoring all work identically to a single
- * `diagnose()` call.
- *
- * Projects that fail (e.g. missing `package.json`, no React dependency)
- * are included in the result with `ok: false` rather than aborting the
- * entire batch, so callers always receive partial results.
- *
- * ```ts
- * const result = await diagnoseProjects({
- *   projects: [
- *     { directory: "packages/app" },
- *     { directory: "packages/shared", deadCode: false },
- *     { directory: "packages/admin", config: {
- *       rules: { "react-doctor/no-array-index-as-key": "off" },
- *     }},
- *   ],
- *   concurrency: 4,
- * });
- *
- * for (const project of result.projects) {
- *   if (project.ok) {
- *     console.log(project.directory, project.score);
- *   } else {
- *     console.error(project.directory, project.error);
- *   }
- * }
- * ```
- */
-export const diagnoseProjects = async (
+const diagnoseProjectBatch = async (
   input: DiagnoseProjectsInput,
 ): Promise<DiagnoseProjectsResult> => {
   const startTime = globalThis.performance.now();
-  const { projects, concurrency: rawConcurrency, ...baseOptions } = input;
-  const concurrency = Math.max(1, rawConcurrency ?? projects.length);
-
-  const projectResults: ProjectResult[] = [];
-  const pendingProjects = [...projects];
-
-  const runBatch = async (): Promise<void> => {
-    const batch: Promise<ProjectResult>[] = [];
-
-    while (pendingProjects.length > 0 && batch.length < concurrency) {
-      const projectDefinition = pendingProjects.shift()!;
-      batch.push(diagnoseProject(projectDefinition, baseOptions));
-    }
-
-    const batchResults = await Promise.all(batch);
-    projectResults.push(...batchResults);
+  const { projects, concurrency, config: batchConfig, ...baseOptions } = input;
 
-    if (pendingProjects.length > 0) {
-      await runBatch();
-    }
-  };
-
-  await runBatch();
-
-  const allDiagnostics = projectResults.flatMap((projectResult) =>
-    projectResult.ok ? projectResult.diagnostics : [],
+  // `diagnoseProject` never rejects (failures come back as `ok: false`),
+  // so the pool always drains every project.
+  const projectResults = await mapWithConcurrency(
+    projects,
+    concurrency ?? DEFAULT_PROJECT_SCAN_CONCURRENCY,
+    (projectDefinition) => diagnoseProject(projectDefinition, baseOptions, batchConfig),
   );
 
   return {
     projects: projectResults,
-    diagnostics: allDiagnostics,
+    diagnostics: projectResults.flatMap((projectResult) =>
+      projectResult.ok ? projectResult.diagnostics : [],
+    ),
     score: findWorstScore(projectResults),
     elapsedMilliseconds: globalThis.performance.now() - startTime,
   };
 };
+
+interface Diagnose {
+  /** Scan a single project directory and return diagnostics + score. */
+  (directory: string, options?: DiagnoseOptions): Promise<DiagnoseResult>;
+  /**
+   * Scan multiple projects in parallel — each through the same pipeline as
+   * the single-directory form — and return per-project results plus an
+   * aggregate worst-of score. A failing project (e.g. no `package.json`)
+   * comes back with `ok: false` instead of aborting the batch. Per-project
+   * `config` layers on the batch `config`, which layers on each project's
+   * on-disk config (see `mergeReactDoctorConfigs`).
+   */
+  (input: DiagnoseProjectsInput): Promise<DiagnoseProjectsResult>;
+}
+
+// HACK: the cast is required to assign the overload implementation (whose
+// return type is the union of both signatures) to the overloaded interface
+// — TypeScript can't verify that narrowing on the first argument selects
+// the matching return type.
+export const diagnose = (async (
+  directoryOrInput: string | DiagnoseProjectsInput,
+  options: DiagnoseOptions = {},
+): Promise<DiagnoseResult | DiagnoseProjectsResult> =>
+  typeof directoryOrInput === "string"
+    ? diagnoseDirectory(directoryOrInput, options)
+    : diagnoseProjectBatch(directoryOrInput)) as Diagnose;

packages/api/src/index.ts

@@ -1,4 +1,4 @@
-export { diagnose, diagnoseProjects } from "./diagnose.js";
+export { diagnose } from "./diagnose.js";
 export { defineConfig } from "@react-doctor/core";
 
 export type {

packages/api/tests/diagnose.test.ts

@@ -4,7 +4,6 @@ import * as path from "node:path";
 import { afterAll, describe, expect, it } from "vite-plus/test";
 import {
   diagnose,
-  diagnoseProjects,
   NoReactDependencyError,
   NotADirectoryError,
   ProjectNotFoundError,
@@ -79,9 +78,9 @@ describe("diagnose", () => {
   });
 });
 
-describe("diagnoseProjects", () => {
+describe("diagnose({ projects })", () => {
   it("returns per-project results for multiple directories", async () => {
-    const result = await diagnoseProjects({
+    const result = await diagnose({
       projects: [
         { directory: path.join(FIXTURES_DIRECTORY, "basic-react") },
         { directory: path.join(FIXTURES_DIRECTORY, "nextjs-app") },
@@ -109,7 +108,7 @@ describe("diagnoseProjects", () => {
   });
 
   it("flattens diagnostics across all succeeded projects", async () => {
-    const result = await diagnoseProjects({
+    const result = await diagnose({
       projects: [
         { directory: path.join(FIXTURES_DIRECTORY, "basic-react") },
         { directory: path.join(FIXTURES_DIRECTORY, "nextjs-app") },
@@ -126,7 +125,7 @@ describe("diagnoseProjects", () => {
   });
 
   it("supports per-project scan option overrides", async () => {
-    const result = await diagnoseProjects({
+    const result = await diagnose({
       projects: [
         { directory: path.join(FIXTURES_DIRECTORY, "basic-react"), deadCode: false },
         { directory: path.join(FIXTURES_DIRECTORY, "nextjs-app"), deadCode: false },
@@ -143,7 +142,7 @@ describe("diagnoseProjects", () => {
   });
 
   it("respects concurrency: 1 for sequential execution", async () => {
-    const result = await diagnoseProjects({
+    const result = await diagnose({
       projects: [
         { directory: path.join(FIXTURES_DIRECTORY, "basic-react") },
         { directory: path.join(FIXTURES_DIRECTORY, "nextjs-app") },
@@ -158,7 +157,7 @@ describe("diagnoseProjects", () => {
   });
 
   it("handles a single project identically to diagnose()", async () => {
-    const multiResult = await diagnoseProjects({
+    const multiResult = await diagnose({
       projects: [{ directory: path.join(FIXTURES_DIRECTORY, "basic-react") }],
       deadCode: false,
       lint: false,
@@ -177,7 +176,7 @@ describe("diagnoseProjects", () => {
   });
 
   it("collects failing projects with ok: false without aborting the batch", async () => {
-    const result = await diagnoseProjects({
+    const result = await diagnose({
       projects: [
         { directory: path.join(FIXTURES_DIRECTORY, "basic-react") },
         { directory: noReactTempDirectory },
@@ -197,7 +196,7 @@ describe("diagnoseProjects", () => {
   });
 
   it("returns empty results for an empty projects array", async () => {
-    const result = await diagnoseProjects({ projects: [], deadCode: false, lint: false });
+    const result = await diagnose({ projects: [], deadCode: false, lint: false });
 
     expect(result.projects).toHaveLength(0);
     expect(result.diagnostics).toHaveLength(0);
@@ -206,7 +205,7 @@ describe("diagnoseProjects", () => {
   });
 
   it("clamps concurrency: 0 to 1 without hanging", async () => {
-    const result = await diagnoseProjects({
+    const result = await diagnose({
       projects: [{ directory: path.join(FIXTURES_DIRECTORY, "basic-react") }],
       deadCode: false,
       lint: false,
@@ -217,7 +216,7 @@ describe("diagnoseProjects", () => {
   });
 
   it("accepts per-project ReactDoctorConfig override", async () => {
-    const result = await diagnoseProjects({
+    const result = await diagnose({
       projects: [
         {
           directory: path.join(FIXTURES_DIRECTORY, "basic-react"),
@@ -231,4 +230,24 @@ describe("diagnoseProjects", () => {
     expect(result.projects).toHaveLength(1);
     expect(result.projects[0].ok).toBe(true);
   });
+
+  it("layers per-project configs on top of a batch-level config", async () => {
+    const result = await diagnose({
+      projects: [
+        { directory: path.join(FIXTURES_DIRECTORY, "basic-react") },
+        {
+          directory: path.join(FIXTURES_DIRECTORY, "nextjs-app"),
+          config: { rules: { "react-doctor/no-prop-drilling": "off" } },
+        },
+      ],
+      config: { ignore: { tags: ["design"] } },
+      deadCode: false,
+      lint: false,
+    });
+
+    expect(result.projects).toHaveLength(2);
+    for (const projectResult of result.projects) {
+      expect(projectResult.ok).toBe(true);
+    }
+  });
 });

packages/core/src/constants.ts

@@ -134,6 +134,13 @@ export const MIN_SCAN_CONCURRENCY = 1;
 
 export const MAX_SCAN_CONCURRENCY = 16;
 
+// Default worker count for a `diagnose({ projects })` batch. Each project
+// scan already fans out its own oxlint workers (bounded by the constants
+// above), so batch concurrency multiplies process count — a small bound
+// keeps an 80-module monorepo from spawning hundreds of subprocesses by
+// default. Callers opt into more via `DiagnoseProjectsInput.concurrency`.
+export const DEFAULT_PROJECT_SCAN_CONCURRENCY = 4;
+
 export const DEFAULT_BRANCH_CANDIDATES = ["main", "master"];
 
 // JSON-format oxlint / eslint configs react-doctor can fold into the

packages/core/src/index.ts

@@ -87,6 +87,7 @@ export * from "./utils/has-published-fix-recipe.js";
 export * from "./utils/list-source-files.js";
 export * from "./utils/map-with-concurrency.js";
 export * from "./utils/match-glob-pattern.js";
+export * from "./utils/merge-react-doctor-configs.js";
 export * from "./utils/redact-sensitive-text.js";
 export * from "./utils/resolve-github-actions-score-metadata.js";
 export * from "./utils/resolve-scan-concurrency.js";

packages/core/src/types/config.ts

@@ -278,6 +278,22 @@ export interface ReactDoctorConfig {
    * requested directory).
    */
   rootDir?: string;
+  /**
+   * Projects to scan and score separately — the config-file equivalent of
+   * the CLI `--project` flag, for repos that always want per-module scoring
+   * (e.g. a monorepo dashboard tracking each module's score daily) without
+   * passing the flag on every run.
+   *
+   * Entries resolve exactly like `--project` values: workspace package
+   * names (or directory basenames) first, then directory paths relative to
+   * the scanned root. `"*"` selects every discovered workspace project.
+   * Invalid entries fail the run with the same error as the flag.
+   *
+   * Precedence: an explicit `--project` flag overrides this list. Only the
+   * config at the invocation root is consulted — `projects` inside a
+   * module's own config is ignored (modules can't redirect the scan).
+   */
+  projects?: string[];
   textComponents?: string[];
   /**
    * Names of components that safely route string-only children through a