Sovra Test Decider

Common errors

• Error: Dynamic import/require not supported for analysis.

  cause Attempting to use `sovra` to analyze files containing import or require statements with dynamic paths (e.g., `require(variable)` or `import(`template-string/${var}`).
  fix Modify the source code to use only static import paths that can be resolved at build time. Sovra's Rust-based analysis requires fixed import declarations.

• TypeError: Cannot read properties of undefined (reading 'files') or (reading 'errors')

  cause Incorrectly accessing properties from the result of `getAffected` without handling potential `undefined` or null results, or if the function threw an unexpected error.
  fix Ensure you check `affected.files` and `affected.errors` for existence before attempting to access them, as shown in the quickstart example. Always wrap calls to `getAffected` in a `try...catch` block if not awaiting a Promise directly.

• Error: Cannot find module 'glob' or 'node:child_process'

  cause The `glob` package or `node:child_process` (when used with `execSync`) are used in common examples but are not direct dependencies of `sovra` itself.
  fix Install `glob` as a development dependency (`npm install -D glob` or `yarn add -D glob`). `node:child_process` is a built-in Node.js module and does not require installation; ensure your Node.js version is compatible and correctly referenced.

Warnings

• gotcha Sovra cannot analyze imports that use variables or expressions, as these can only be resolved at runtime. This includes patterns like `require(process.env.SOME_VAR)` or `import(`./file.${platform}.mjs`).
  Fix: Refactor your codebase to use static import paths that can be resolved during static analysis. Avoid dynamic import or require patterns where possible for files that need to be tracked by Sovra.
• gotcha As of version 0.2.0, Sovra is in early development. While stable for its current feature set, future minor versions might introduce breaking changes to the API surface as the project matures.
  Fix: Monitor the project's GitHub repository and release notes for upcoming breaking changes. Consider pinning to exact patch versions or reviewing changes when updating minor versions in production environments.

Install

• npm install sovra npm
• yarn add sovra yarn
• pnpm add sovra pnpm

Imports

• getAffected
  wrong:

  import getAffected from 'sovra';
  const getAffected = require('sovra');

  correct:

  import { getAffected } from 'sovra';

  Sovra primarily exports named functions for its API. Prefer ESM imports for type safety and modern JavaScript environments.
• OxcResolverOptions
  wrong:

  import { OxcResolverOptions } from 'oxc-resolver';

  correct:

  import { type OxcResolverOptions } from 'sovra/resolver';

  While `sovra` uses `oxc-resolver` internally, its types for `OxcResolverOptions` are re-exported or provided as part of `sovra`'s own type definitions, often accessible via a specific subpath or implicitly.
• CommonJS require
  wrong:

  const sovra = require('sovra');
  const getAffected = sovra.getAffected;

  correct:

  const { getAffected } = require('sovra');

  For CommonJS environments, destructuring directly from `require('sovra')` is the correct approach as `getAffected` is a named export.

Quickstart

Demonstrates how to use `getAffected` to find test files impacted by recent Git changes, leveraging `glob` for file discovery and `tsconfig.json` for path resolution.

import { getAffected } from "sovra";
import { execSync } from "node:child_process";
import { glob } from "glob";

async function runAffectedTests() {
  const testFiles = await glob("src/**/*.spec.{ts,tsx}");
  const changedFiles = execSync("git diff --name-only main", { encoding: "utf8" })
    .trim()
    .split("\n")
    .filter(Boolean);

  if (testFiles.length === 0 || changedFiles.length === 0) {
    console.log("No test files or changed files found.");
    return;
  }

  const resolverOptions = {
    tsconfig: {
      configFile: "tsconfig.json"
    }
  };

  const affected = await getAffected(testFiles, changedFiles, resolverOptions);

  if (affected.errors && affected.errors.length > 0) {
    console.error("Errors determining affected files:", ...affected.errors);
  } else if (affected.files && affected.files.length > 0) {
    console.log("Affected test files:", affected.files);
    // Example: Run these tests with your test runner
    // execSync(`pnpm jest ${affected.files.join(' ')}`, { stdio: 'inherit' });
  } else {
    console.log("No tests affected by the changes.");
  }
}

runAffectedTests().catch(console.error);