impacted 0.0.1 → 0.0.4

package/README.md

@@ -1,63 +1,32 @@
 # impacted
 
-Find test files impacted by code changes using static dependency analysis.
+It takes a list of changed files, builds a dependency graph from your test files by statically analyzing their imports, and returns only the test files that depend on the changed files.
 
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![npm version](https://img.shields.io/npm/v/impacted)](https://www.npmjs.com/package/impacted)
-
-## About
-
-`impacted` analyzes your codebase's import graph to determine which test files are affected by a set of changed files. Run only the tests that matter instead of your entire test suite.
-
-This project is a userland implementation of [predictive test selection for Node.js test runner](https://github.com/nodejs/node/issues/54173).
-
-## Features
-
-- Static analysis of ESM and CommonJS (import, require, dynamic import, re-exports)
-- Supports Node.js subpath imports (`#imports`)
-- Transitive dependency tracking
-- Optional caching for faster repeated runs
-- CLI and programmatic API
-- GitHub Action for CI integration
+A userland implementation of [predictive test selection for Node.js test runner](https://github.com/nodejs/node/issues/54173).
 
-## Installation
-
-```bash
-npm install impacted
-```
+[![npm version](https://img.shields.io/npm/v/impacted)](https://www.npmjs.com/package/impacted)
 
 ## Usage
 
-### CLI
-
-Pipe changed files to `impacted`:
-
-```bash
-git diff --name-only HEAD~1 | npx impacted
-```
-
-With a custom test pattern:
-
 ```bash
-git diff --name-only main | npx impacted -p "src/**/*.spec.js"
-```
-
-Use with any test runner:
-
-```bash
-# Node.js test runner
+# Run only impacted tests
 node --test $(git diff --name-only main | npx impacted)
 
-# Vitest
+# Works with any test runner
 vitest $(git diff --name-only main | npx impacted)
-
-# Jest
 jest $(git diff --name-only main | npx impacted)
+
+# Custom test pattern
+git diff --name-only main | npx impacted -p "src/**/*.spec.js"
 ```
 
-### GitHub Action
+## GitHub Action
 
 ```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+
 - uses: sozua/impacted@v1
   id: impacted
   with:
@@ -68,78 +37,25 @@ jest $(git diff --name-only main | npx impacted)
   run: node --test ${{ steps.impacted.outputs.files }}
 ```
 
-#### Inputs
-
-| Input | Description | Default |
-|-------|-------------|---------|
-| `base` | Base ref to compare against | PR base or `HEAD~1` |
-| `head` | Head ref | `HEAD` |
-| `pattern` | Glob pattern for test files | `**/*.test.js` |
-| `working-directory` | Working directory | `.` |
-
-#### Outputs
+See [action.yml](https://github.com/sozua/impacted/blob/main/action.yml) for all inputs and outputs.
 
-| Output | Description |
-|--------|-------------|
-| `files` | Space-separated list of impacted test files |
-| `files-json` | JSON array of impacted test files |
-| `count` | Number of impacted test files |
-| `has-impacted` | Whether any tests are impacted (`true`/`false`) |
-
-### Programmatic API
+## Programmatic API
 
 ```javascript
 import { findImpacted } from 'impacted';
 
-const tests = await findImpacted({
-  changedFiles: ['src/utils.js', 'src/parser.js'],
-  testFiles: 'test/**/*.test.js',
-});
-
-console.log(tests);
-// ['/project/test/utils.test.js', '/project/test/parser.test.js']
-```
-
-#### With caching
-
-```javascript
 const tests = await findImpacted({
   changedFiles: ['src/utils.js'],
   testFiles: 'test/**/*.test.js',
-  cacheFile: '.impacted-cache.json',
+  cacheFile: '.impacted-cache.json', // optional
 });
 ```
 
-#### Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `changedFiles` | `string[]` | Files that changed (relative or absolute) |
-| `testFiles` | `string \| string[]` | Glob pattern(s) or explicit file list |
-| `cwd` | `string` | Working directory (default: `process.cwd()`) |
-| `excludePaths` | `string[]` | Paths to exclude (default: `['node_modules', 'dist']`) |
-| `cacheFile` | `string` | Path to persist cache between runs |
-
-## How it works
-
-1. Build a dependency graph starting from your test files
-2. Invert the graph to map each file to its dependents
-3. Walk the inverted graph from changed files to find impacted tests
-
-```
-src/utils.js (changed)
-    ↓ imported by
-src/parser.js
-    ↓ imported by
-test/parser.test.js (impacted)
-```
-
-## Known limitations
+## Limitations
 
-- **JavaScript only** - Supports `.js`, `.mjs`, `.cjs`, and `.jsx`. TypeScript files are not yet supported.
-- **Static analysis** - Cannot detect dynamic imports with variables (e.g., `require(getModuleName())`). Only string literals are resolved.
-- **Local files only** - Dependencies in `node_modules` are excluded from the graph. Changes to dependencies won't trigger impacted tests.
-- **No TypeScript path aliases** - Only Node.js subpath imports (`#imports` in package.json) are supported, not `tsconfig.json` paths.
+- JavaScript only (`.js`, `.mjs`, `.cjs`, `.jsx`) — no TypeScript yet
+- Static analysis only — dynamic `require(variable)` not supported
+- Local files only — `node_modules` changes won't trigger tests
 
 ## Requirements
 

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "impacted",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "Find test files impacted by code changes using static dependency analysis",
   "type": "module",
   "main": "./src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
   },
   "bin": {
     "impacted": "./bin/impacted.js"
@@ -15,7 +19,8 @@
     "bin"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "test:examples": "node --test examples/test.js"
   },
   "keywords": [
     "test",
@@ -44,6 +49,7 @@
   "dependencies": {
     "acorn": "^8.14.0",
     "acorn-walk": "^8.3.4",
-    "fast-glob": "^3.3.3"
+    "fast-glob": "^3.3.3",
+    "is-glob": "^4.0.3"
   }
 }

package/src/index.d.ts

@@ -0,0 +1,80 @@
+export interface FindImpactedOptions {
+  /** Files that changed (relative or absolute) */
+  changedFiles: string[];
+  /** Test file glob pattern(s) or explicit file list */
+  testFiles: string | string[];
+  /** Working directory (default: process.cwd()) */
+  cwd?: string;
+  /** Paths to exclude from graph (default: ['node_modules', 'dist']) */
+  excludePaths?: string[];
+  /** Cache instance for import extraction */
+  cache?: ImportCache;
+  /** Path to persist cache (creates cache automatically) */
+  cacheFile?: string;
+}
+
+export interface GraphOptions {
+  /** Paths to exclude from graph (default: ['node_modules', 'dist']) */
+  excludePaths?: string[];
+  /** Cache instance for import extraction */
+  cache?: ImportCache;
+}
+
+export interface CacheOptions {
+  /** Path to persist cache */
+  cacheFile?: string;
+}
+
+export interface CacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+}
+
+/** Find test files impacted by code changes */
+export function findImpacted(options: FindImpactedOptions): Promise<string[]>;
+
+/** Build a dependency graph starting from entry files */
+export function buildDependencyGraph(
+  entryFiles: string[],
+  options?: GraphOptions,
+): Map<string, Set<string>>;
+
+/** Find test files impacted by changed files given a dependency graph */
+export function findImpactedTests(
+  changedFiles: string[],
+  testFiles: string[],
+  graph: Map<string, Set<string>>,
+): string[];
+
+/** Invert a dependency graph (file → deps becomes dep → dependents) */
+export function invertGraph(
+  graph: Map<string, Set<string>>,
+): Map<string, Set<string>>;
+
+/** Extract import/require specifiers from source code */
+export function parseImports(source: string): string[];
+
+/** Resolve an import specifier to an absolute file path */
+export function resolveSpecifier(
+  specifier: string,
+  parentPath: string,
+): string | null;
+
+/** Create a cache instance */
+export function createCache(options?: CacheOptions): ImportCache;
+
+/** Cache for import extraction results with mtime-based invalidation */
+export class ImportCache {
+  constructor(options?: CacheOptions);
+  /** Get cached imports for a file, or null if not cached/stale */
+  get(filePath: string): string[] | null;
+  /** Store imports for a file */
+  set(filePath: string, imports: string[]): void;
+  /** Get cache statistics */
+  stats(): CacheStats;
+  /** Persist cache to disk */
+  save(): void;
+  /** Clear all cached data */
+  clear(): void;
+}

package/src/index.js

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 import fg from 'fast-glob';
+import isGlob from 'is-glob';
 import { getImpactedTests } from './graph.js';
 import { createCache, ImportCache } from './cache.js';
 
@@ -50,7 +51,7 @@ export async function findImpacted(options) {
 
   // Resolve test files - either glob or explicit list
   let absoluteTestFiles;
-  if (typeof testFiles === 'string' || (Array.isArray(testFiles) && testFiles.some((t) => t.includes('*')))) {
+  if (typeof testFiles === 'string' || (Array.isArray(testFiles) && testFiles.some((t) => isGlob(t)))) {
     // It's a glob pattern
     const patterns = Array.isArray(testFiles) ? testFiles : [testFiles];
     absoluteTestFiles = await fg(patterns, { cwd, absolute: true });