sovra

library0.2.0jsnpmunverified

Sovra is a high-performance, Rust-based utility for monorepos designed to identify affected test files by analyzing code changes and their import graphs. It leverages Oxc for its underlying dependency resolution, ensuring fast execution. The library provides a Node.js API to determine which tests should be run in a given CI pipeline, significantly speeding up large repository workflows. It ships with comprehensive TypeScript support, including path aliases, and offers configurable resolver options that align with `oxc-resolver`. Currently at version 0.2.0, it is in active development, focusing on performance and accuracy for JavaScript and TypeScript projects. Its primary differentiator is its Rust-powered speed and its direct integration for test selection based on file changes.

testing devops

npm install sovra

github ↗package ↗

INSTALL

IMPORT

SIG · SOVRA

sovra

testingjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getAffected

✓ import { getAffected } from 'sovra';

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

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

OxcResolverOptions

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

✗ import { OxcResolverOptions } from 'oxc-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

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

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

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

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);

Debug

Known issues

gotchaSovra 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.

affects: >=0.1.0

gotchaAs 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.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Dynamic import/require not supported for analysis.

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')

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'

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.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

globrequiredUsed in common usage patterns for finding test files in a project.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/oblador/sovra ↗

packagehttps://www.npmjs.com/package/sovra ↗