@reasonabletech/config-vitest 0.1.0

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@reasonabletech/config-vitest",
+  "version": "0.1.0",
+  "description": "Shared Vitest configuration",
+  "keywords": [
+    "reasonabletech",
+    "config",
+    "typescript",
+    "vitest",
+    "testing",
+    "test-config",
+    "coverage",
+    "vite"
+  ],
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./node": {
+      "types": "./dist/src/node.d.ts",
+      "import": "./dist/src/node.js",
+      "default": "./dist/src/node.js"
+    },
+    "./react": {
+      "types": "./dist/src/react.d.ts",
+      "import": "./dist/src/react.js",
+      "default": "./dist/src/react.js"
+    },
+    "./workspace": {
+      "types": "./dist/src/workspace.d.ts",
+      "import": "./dist/src/workspace.js",
+      "default": "./dist/src/workspace.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/**/*",
+    "src"
+  ],
+  "dependencies": {
+    "@vitejs/plugin-react": "5.1.4",
+    "vite": "7.3.1",
+    "vitest": "4.0.18"
+  },
+  "devDependencies": {
+    "@types/node": "25.3.1",
+    "@vitest/coverage-v8": "4.0.18",
+    "eslint": "10.0.2",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18",
+    "@reasonabletech/config-eslint": "0.1.0",
+    "@reasonabletech/config-typescript": "0.1.0"
+  },
+  "peerDependencies": {
+    "vite": ">=7.3.1 <8",
+    "vitest": ">=4.0.18 <5"
+  },
+  "license": "MIT",
+  "author": "Reasonable Tech Company",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ReasonableTech/core-utils.git",
+    "directory": "packages/config-vitest"
+  },
+  "bugs": {
+    "url": "https://github.com/ReasonableTech/core-utils/issues"
+  },
+  "homepage": "https://github.com/ReasonableTech/core-utils/tree/main/packages/config-vitest",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "clean": "rm -rf dist .turbo node_modules tsconfig.tsbuildinfo",
+    "dev": "tsc --watch",
+    "docs:coverage": "tsx ../../../scripts/analysis/check-doc-coverage.ts --html",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run tests/e2e",
+    "test:integration": "vitest run tests/integration",
+    "test:ui": "vitest --ui",
+    "test:unit": "vitest run tests/unit",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc --noEmit",
+    "verify:release": "pnpm typecheck && pnpm lint:check && pnpm test && pnpm build"
+  }
+}

package/src/global-setup.ts

@@ -0,0 +1,58 @@
+import { spawnSync } from "node:child_process";
+import { findRepoRoot, readPackageName } from "./workspace.js";
+
+/**
+ * Builds the pnpm + turbo CLI arguments needed to build all upstream
+ * workspace dependencies of the given package.
+ * @param packageName - The package name (e.g. `@reasonabletech/utils`)
+ * @returns An array of CLI arguments for `spawnSync("pnpm", ...)`
+ */
+export function getTurboBuildArgs(packageName: string): readonly string[] {
+  return [
+    "-w",
+    "turbo",
+    "run",
+    "build",
+    `--filter=${packageName}^...`,
+  ] as const;
+}
+
+/**
+ * Vitest global setup that builds workspace dependencies before tests run.
+ *
+ * Skipped when `RT_VITEST_SKIP_DEP_BUILD=true` is set or when
+ * a parent build is already in progress (re-entrancy guard).
+ */
+export default function globalSetup(): void {
+  if (process.env.RT_VITEST_SKIP_DEP_BUILD === "true") {
+    return;
+  }
+
+  if (process.env.RT_VITEST_DEP_BUILD_RUNNING === "true") {
+    return;
+  }
+
+  const packageDir = process.cwd();
+  const packageName = readPackageName(packageDir);
+  if (packageName === null) {
+    return;
+  }
+
+  const repoRoot = findRepoRoot(packageDir);
+  const args = getTurboBuildArgs(packageName);
+
+  const result = spawnSync("pnpm", args, {
+    cwd: repoRoot,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      RT_VITEST_DEP_BUILD_RUNNING: "true",
+    },
+  });
+
+  if (result.status !== 0) {
+    throw new Error(
+      `Failed to build workspace dependencies (exit code: ${result.status ?? "unknown"})`,
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,280 @@
+/**
+ * Base Vitest configuration for all packages
+ * @module @reasonabletech/config-vitest
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { defaultClientConditions, defaultServerConditions } from "vite";
+import { defineConfig } from "vitest/config";
+import type { InlineConfig } from "vitest/node";
+import { readPackageName } from "./workspace.js";
+
+/** Recursively makes all properties of T readonly */
+export type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends ReadonlyArray<infer U>
+    ? ReadonlyArray<DeepReadonly<U>>
+    : T[P] extends Array<infer U>
+      ? ReadonlyArray<DeepReadonly<U>>
+      : T[P] extends object
+        ? DeepReadonly<T[P]>
+        : T[P];
+};
+
+/**
+ * Immutable configuration object accepted by {@link createVitestConfig} and
+ * related helpers.
+ */
+export type VitestConfig = DeepReadonly<{
+  test?: InlineConfig;
+  resolve?: {
+    conditions?: string[];
+    alias?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}>;
+
+// Empty readonly config for default parameters
+const EMPTY_CONFIG = {} as const satisfies VitestConfig;
+
+/**
+ * Base configuration options that apply to all test environments
+ */
+export const baseConfig = {
+  test: {
+    testTimeout: 10000, // 10 seconds default timeout
+    hookTimeout: 10000, // 10 seconds for setup/teardown hooks
+    coverage: {
+      provider: "v8" as const,
+      reporter: ["text", "html", "lcov", "json"],
+      reportsDirectory: "./generated/test-coverage",
+      exclude: [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/tests/**",
+        "**/*.d.ts",
+        "**/*.config.{js,ts,mjs,mts}",
+        "**/coverage/**",
+        "**/examples/**",
+        "**/src/index.ts",
+        "**/src/*/index.ts",
+        "**/src/types/**",
+        "tsup.config.ts",
+        "vitest.config.mts",
+        "tailwind.config.mjs",
+        "**/vitest.setup.ts",
+      ],
+      thresholds:
+        process.env.VITEST_COVERAGE_THRESHOLDS_DISABLED === "true"
+          ? {
+              lines: 0,
+              functions: 0,
+              branches: 0,
+              statements: 0,
+            }
+          : {
+              lines: 100,
+              functions: 100,
+              branches: 100,
+              statements: 100,
+            },
+    },
+  },
+};
+
+/**
+ * Generates resolve aliases that map a package's own name back to its source
+ * directory. This allows test files to `import { foo } from "@reasonabletech/my-pkg"`
+ * and have Vite resolve it to the local `src/` tree instead of requiring a prior
+ * build step.
+ *
+ * Placed before user-supplied aliases so consumers can override if needed.
+ * @param projectDir - Absolute path to the project directory
+ * @returns A record mapping the package name to its `src/` directory
+ */
+function generateSelfPackageAliases(
+  projectDir: string,
+): Record<string, string> {
+  const packageName = readPackageName(projectDir);
+  if (packageName === null) {
+    return {};
+  }
+  return {
+    [packageName]: `${projectDir}/src`,
+  };
+}
+
+/**
+ * Auto-detects setup files in a project directory
+ * @param projectDir - The project directory path
+ * @returns Array of detected setup file paths
+ */
+function autoDetectSetupFiles(projectDir?: string): string[] {
+  if (projectDir === undefined || projectDir === "") {
+    return [];
+  }
+
+  const vitestSetupPath = join(projectDir, "vitest.setup.ts");
+  if (existsSync(vitestSetupPath)) {
+    return ["./vitest.setup.ts"];
+  }
+
+  const testsSetupPath = join(projectDir, "tests/setup.ts");
+  if (existsSync(testsSetupPath)) {
+    return ["./tests/setup.ts"];
+  }
+
+  return [];
+}
+
+/**
+ * Auto-detects test include patterns based on project structure
+ * @returns Array of include patterns
+ */
+function autoDetectIncludePatterns(): string[] {
+  return ["tests/**/*.test.{ts,tsx,js,jsx}"];
+}
+
+/** @overload */
+/**
+ * Creates a merged configuration from the base and any custom options.
+ * @param projectDirOrConfig - Either the absolute project directory (use `import.meta.dirname`) or a prebuilt config.
+ * @param customConfig - Additional configuration to merge when a project directory is provided.
+ * @returns A merged Vitest configuration tailored for the caller.
+ */
+export function createVitestConfig(
+  projectDirOrConfig?: string | VitestConfig,
+  customConfig?: VitestConfig,
+): ReturnType<typeof defineConfig> {
+  // Handle overloaded parameters
+  let projectDir: string | undefined;
+  let config: VitestConfig;
+
+  if (typeof projectDirOrConfig === "string") {
+    projectDir = projectDirOrConfig;
+    config = customConfig ?? EMPTY_CONFIG;
+  } else {
+    projectDir = undefined;
+    config = projectDirOrConfig ?? EMPTY_CONFIG;
+  }
+
+  // Auto-detect configuration if not explicitly provided
+  const autoSetupFiles =
+    config.test?.setupFiles !== undefined && config.test.setupFiles.length > 0
+      ? []
+      : autoDetectSetupFiles(projectDir);
+  const autoIncludePatterns =
+    config.test?.include !== undefined && config.test.include.length > 0
+      ? []
+      : autoDetectIncludePatterns();
+
+  return defineConfig({
+    ...baseConfig,
+    ...config,
+    test: {
+      ...baseConfig.test,
+      // Auto-detect setupFiles if not explicitly provided
+      ...(autoSetupFiles.length > 0 && { setupFiles: autoSetupFiles }),
+      // Auto-detect include patterns if not explicitly provided
+      ...(autoIncludePatterns.length > 0 && { include: autoIncludePatterns }),
+      ...config.test,
+      coverage: {
+        ...baseConfig.test.coverage,
+        ...config.test?.coverage,
+      },
+    },
+    resolve: {
+      // Prefer "source" condition in package.json exports, allowing
+      // Vitest to resolve workspace dependencies directly to TypeScript source
+      // files without requiring a prior build step.
+      //
+      // Since Vite 6, resolve.conditions REPLACES the defaults instead of
+      // extending them. We must include defaultClientConditions to preserve
+      // standard conditions like "module", "browser", "development|production".
+      conditions: ["source", ...defaultClientConditions],
+      alias: {
+        // Work around packages whose "module" entry is bundler-oriented but not
+        // directly Node.js ESM-resolvable in Vitest (e.g. extensionless internal
+        // specifiers). Prefer the Node/CJS build for tests.
+        "@opentelemetry/api": "@opentelemetry/api/build/src/index.js",
+        // Auto-generate self-package alias (e.g. "@reasonabletech/utils" → "./src")
+        ...(projectDir !== undefined &&
+          projectDir !== "" &&
+          generateSelfPackageAliases(projectDir)),
+        // Standard "@" → src alias
+        ...(projectDir !== undefined &&
+          projectDir !== "" && { "@": `${projectDir}/src` }),
+        // Consumer-provided aliases override everything above
+        ...config.resolve?.alias,
+      },
+      ...config.resolve,
+    },
+    // Vitest runs in Vite's SSR mode. Since Vite 6, ssr.resolve.conditions is
+    // independent from resolve.conditions and defaults to defaultServerConditions.
+    // We must explicitly include "source" in ssr.resolve.conditions so
+    // workspace dependencies resolve to TypeScript source during test execution.
+    // Additionally, ssr.resolve.externalConditions passes "source" to
+    // Node.js when it natively resolves externalized packages.
+    //
+    // Note: We intentionally omit the "module" export condition for SSR tests.
+    // Some third-party packages expose a "module" build that is bundler-friendly
+    // but not directly Node.js ESM-resolvable (for example: extensionless internal
+    // specifiers). For tests, preferring Node-compatible ("node"/"default") entry
+    // points avoids runtime import failures.
+    ssr: {
+      resolve: {
+        conditions: [
+          "source",
+          ...defaultServerConditions.filter(
+            (condition) => condition !== "module",
+          ),
+        ],
+        externalConditions: ["source"],
+      },
+    },
+  });
+}
+
+/** @overload */
+/**
+ * Creates a configuration with extended timeouts for long-running tests.
+ * @param projectDirOrConfig - Either the absolute project directory or an existing configuration to extend.
+ * @param customConfig - Additional configuration to merge when a project directory is supplied.
+ * @returns A Vitest configuration suited for long-running suites.
+ */
+export function createLongRunningTestConfig(
+  projectDirOrConfig?: string | VitestConfig,
+  customConfig?: VitestConfig,
+): ReturnType<typeof defineConfig> {
+  // Handle overloaded parameters
+  let projectDir: string | undefined;
+  let config: VitestConfig;
+
+  if (typeof projectDirOrConfig === "string") {
+    projectDir = projectDirOrConfig;
+    config = customConfig ?? EMPTY_CONFIG;
+  } else {
+    projectDir = undefined;
+    config = projectDirOrConfig ?? EMPTY_CONFIG;
+  }
+
+  const longRunningConfig: VitestConfig = {
+    ...config,
+    test: {
+      testTimeout: 30000, // 30 seconds for long-running tests
+      hookTimeout: 30000, // 30 seconds for setup/teardown hooks
+      ...config.test,
+    },
+  };
+
+  if (projectDir !== undefined) {
+    return createVitestConfig(projectDir, longRunningConfig);
+  }
+  return createVitestConfig(longRunningConfig);
+}
+
+// Re-export for convenience
+export { createReactConfig, createReactConfigWithPlugins } from "./react.js";
+
+export default createVitestConfig;

package/src/node.ts

@@ -0,0 +1,74 @@
+/**
+ * Node.js-specific Vitest configuration
+ * @module @reasonabletech/config-vitest/node
+ */
+
+import type { InlineConfig } from "vitest/node";
+import type { UserConfig } from "vite";
+import { createVitestConfig, type DeepReadonly } from "./index.js";
+
+/** Immutable Vitest configuration type combining Vite UserConfig with Vitest InlineConfig */
+export type VitestConfig = DeepReadonly<UserConfig> & {
+  readonly test?: DeepReadonly<InlineConfig>;
+};
+
+// Empty readonly config for default parameters
+const EMPTY_CONFIG = {} as const satisfies VitestConfig;
+
+/**
+ * Node.js-specific configuration options
+ */
+export const nodeConfig = {
+  test: {
+    environment: "node" as const,
+    include: ["tests/**/*.test.ts"],
+  },
+} as const satisfies VitestConfig;
+
+/**
+ * Creates a Vitest configuration for Node.js-based packages.
+ * @param projectDirOrConfig - Either the absolute project directory (use `import.meta.dirname`) or a prebuilt config.
+ * @param customConfig - Additional configuration to merge when a project directory is provided.
+ * @returns A Vitest configuration optimized for Node.js environments
+ */
+export function createNodeConfig(
+  projectDirOrConfig?: string | VitestConfig,
+  customConfig?: VitestConfig,
+): ReturnType<typeof createVitestConfig> {
+  // Handle overloaded parameters
+  let projectDir: string | undefined;
+  let config: VitestConfig;
+
+  if (typeof projectDirOrConfig === "string") {
+    projectDir = projectDirOrConfig;
+    config = customConfig ?? EMPTY_CONFIG;
+  } else {
+    projectDir = undefined;
+    config = projectDirOrConfig ?? EMPTY_CONFIG;
+  }
+
+  // Merge node-specific settings with consumer config
+  const mergedConfig = {
+    ...nodeConfig,
+    ...config,
+    test: {
+      ...nodeConfig.test,
+      ...config.test,
+    },
+  };
+
+  // Delegate to createVitestConfig which handles aliasing and base config.
+  // When projectDir is present, pass both args so createVitestConfig generates aliases.
+  // When absent, pass the merged config as the sole argument.
+  if (projectDir !== undefined) {
+    return createVitestConfig(
+      projectDir,
+      mergedConfig as Parameters<typeof createVitestConfig>[1],
+    );
+  }
+  return createVitestConfig(
+    mergedConfig as Parameters<typeof createVitestConfig>[0],
+  );
+}
+
+export default createNodeConfig;