impacted 0.0.1

package/README.md

@@ -0,0 +1,150 @@
+# impacted
+
+Find test files impacted by code changes using static dependency analysis.
+
+[![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
+
+## Installation
+
+```bash
+npm install 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
+node --test $(git diff --name-only main | npx impacted)
+
+# Vitest
+vitest $(git diff --name-only main | npx impacted)
+
+# Jest
+jest $(git diff --name-only main | npx impacted)
+```
+
+### GitHub Action
+
+```yaml
+- uses: sozua/impacted@v1
+  id: impacted
+  with:
+    pattern: '**/*.test.js'
+
+- name: Run impacted tests
+  if: steps.impacted.outputs.has-impacted == 'true'
+  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
+
+| 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
+
+```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',
+});
+```
+
+#### 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
+
+- **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.
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+MIT

package/bin/impacted.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import { findImpacted } from '../src/index.js';
+
+const args = process.argv.slice(2);
+
+// Parse -p/--pattern flag
+let pattern = '**/*.test.js';
+const patternIndex = args.findIndex((arg) => arg === '-p' || arg === '--pattern');
+if (patternIndex !== -1 && args[patternIndex + 1]) {
+  pattern = args[patternIndex + 1];
+}
+
+// Read changed files from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+
+process.stdin.on('readable', () => {
+  let chunk;
+  while ((chunk = process.stdin.read()) !== null) {
+    input += chunk;
+  }
+});
+
+process.stdin.on('end', async () => {
+  const changedFiles = input
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  if (changedFiles.length === 0) {
+    process.exit(0);
+  }
+
+  const impacted = await findImpacted({
+    changedFiles,
+    testFiles: pattern,
+  });
+
+  for (const file of impacted) {
+    console.log(file);
+  }
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "impacted",
+  "version": "0.0.1",
+  "description": "Find test files impacted by code changes using static dependency analysis",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "impacted": "./bin/impacted.js"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "test",
+    "testing",
+    "affected",
+    "impacted",
+    "dependency",
+    "graph",
+    "ci",
+    "predictive",
+    "test-selection"
+  ],
+  "author": "sozua",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sozua/impacted.git"
+  },
+  "homepage": "https://github.com/sozua/impacted#readme",
+  "bugs": {
+    "url": "https://github.com/sozua/impacted/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "acorn": "^8.14.0",
+    "acorn-walk": "^8.3.4",
+    "fast-glob": "^3.3.3"
+  }
+}

package/src/cache.js

@@ -0,0 +1,136 @@
+import { readFileSync, writeFileSync, statSync } from 'node:fs';
+
+/**
+ * Cache for import extraction results with mtime-based invalidation
+ */
+export class ImportCache {
+  /**
+   * @param {Object} options
+   * @param {string} [options.cacheFile] - Path to persist cache (optional)
+   */
+  constructor(options = {}) {
+    this.cacheFile = options.cacheFile;
+    this.data = new Map();
+    this.hits = 0;
+    this.misses = 0;
+
+    if (this.cacheFile) {
+      this._load();
+    }
+  }
+
+  /**
+   * Get cached imports for a file, or null if not cached/stale
+   * @param {string} filePath - Absolute file path
+   * @returns {string[] | null}
+   */
+  get(filePath) {
+    const entry = this.data.get(filePath);
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+
+    // Check if file has been modified
+    let mtime;
+    try {
+      mtime = statSync(filePath).mtimeMs;
+    } catch {
+      // File doesn't exist anymore, invalidate
+      this.data.delete(filePath);
+      this.misses++;
+      return null;
+    }
+
+    if (entry.mtime !== mtime) {
+      this.data.delete(filePath);
+      this.misses++;
+      return null;
+    }
+
+    this.hits++;
+    return entry.imports;
+  }
+
+  /**
+   * Store imports for a file
+   * @param {string} filePath - Absolute file path
+   * @param {string[]} imports - Extracted import specifiers
+   */
+  set(filePath, imports) {
+    let mtime;
+    try {
+      mtime = statSync(filePath).mtimeMs;
+    } catch {
+      // Can't stat file, don't cache
+      return;
+    }
+
+    this.data.set(filePath, { mtime, imports });
+  }
+
+  /**
+   * Get cache statistics
+   * @returns {{ hits: number, misses: number, size: number }}
+   */
+  stats() {
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      size: this.data.size,
+    };
+  }
+
+  /**
+   * Persist cache to disk
+   */
+  save() {
+    if (!this.cacheFile) return;
+
+    const serialized = {};
+    for (const [key, value] of this.data) {
+      serialized[key] = value;
+    }
+
+    try {
+      writeFileSync(this.cacheFile, JSON.stringify(serialized), 'utf8');
+    } catch {
+      // Ignore write errors (e.g., read-only filesystem)
+    }
+  }
+
+  /**
+   * Clear all cached data
+   */
+  clear() {
+    this.data.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  /**
+   * Load cache from disk
+   * @private
+   */
+  _load() {
+    try {
+      const content = readFileSync(this.cacheFile, 'utf8');
+      const parsed = JSON.parse(content);
+      for (const [key, value] of Object.entries(parsed)) {
+        this.data.set(key, value);
+      }
+    } catch {
+      // No cache file or invalid, start fresh
+    }
+  }
+}
+
+/**
+ * Create a cache instance
+ * @param {Object} [options]
+ * @param {string} [options.cacheFile] - Path to persist cache
+ * @returns {ImportCache}
+ */
+export function createCache(options) {
+  return new ImportCache(options);
+}

package/src/graph.js

@@ -0,0 +1,171 @@
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
+import { parseImports } from './parser.js';
+import { resolveSpecifier } from './resolver.js';
+
+const SUPPORTED_EXTENSIONS = ['.js', '.mjs', '.cjs', '.jsx'];
+
+/** @typedef {import('./cache.js').ImportCache} ImportCache */
+
+/**
+ * Check if a file has a supported extension
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isSupportedFile(filePath) {
+  return SUPPORTED_EXTENSIONS.includes(extname(filePath));
+}
+
+/**
+ * Extract imports from a file
+ * @param {string} filePath - Absolute path to the file
+ * @returns {string[]} Array of import specifiers
+ */
+export function extractImports(filePath) {
+  let source;
+  try {
+    source = readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+  return parseImports(source);
+}
+
+const DEFAULT_EXCLUDE_PATHS = ['node_modules', 'dist'];
+
+/**
+ * Check if a file path matches any excluded path pattern
+ * @param {string} filePath
+ * @param {string[]} excludePaths
+ * @returns {boolean}
+ */
+function isExcluded(filePath, excludePaths) {
+  return excludePaths.some((pattern) => filePath.includes(pattern));
+}
+
+/**
+ * Build a dependency graph starting from entry files
+ * @param {string[]} entryFiles - Array of absolute file paths
+ * @param {Object} options
+ * @param {string[]} [options.excludePaths=['node_modules', 'dist']] - Paths to exclude from graph
+ * @param {ImportCache} [options.cache] - Optional cache for import extraction
+ * @returns {Map<string, Set<string>>} Map of file -> dependencies
+ */
+export function buildDependencyGraph(entryFiles, options = {}) {
+  const { excludePaths = DEFAULT_EXCLUDE_PATHS, cache } = options;
+
+  const graph = new Map();
+  const visited = new Set();
+  const pending = [...entryFiles];
+
+  for (let i = 0; i < pending.length; i++) {
+    const file = pending[i];
+
+    if (visited.has(file)) continue;
+    visited.add(file);
+
+    if (isExcluded(file, excludePaths)) {
+      continue;
+    }
+
+    if (!isSupportedFile(file)) {
+      continue;
+    }
+
+    // Try cache first
+    let imports = cache?.get(file);
+    if (imports === null || imports === undefined) {
+      imports = extractImports(file);
+      cache?.set(file, imports);
+    }
+
+    const dependencies = new Set();
+
+    for (const specifier of imports) {
+      const resolved = resolveSpecifier(specifier, file);
+      if (!resolved || isExcluded(resolved, excludePaths)) continue;
+
+      dependencies.add(resolved);
+      if (!visited.has(resolved)) {
+        pending.push(resolved);
+      }
+    }
+
+    graph.set(file, dependencies);
+  }
+
+  return graph;
+}
+
+/**
+ * Invert the graph: file -> files that depend on it
+ * @param {Map<string, Set<string>>} graph
+ * @returns {Map<string, Set<string>>}
+ */
+export function invertGraph(graph) {
+  const inverted = new Map();
+
+  for (const [file, deps] of graph) {
+    for (const dep of deps) {
+      if (!inverted.has(dep)) {
+        inverted.set(dep, new Set());
+      }
+      inverted.get(dep).add(file);
+    }
+  }
+
+  return inverted;
+}
+
+/**
+ * Find all files impacted by changes to the given files
+ * @param {string[]} changedFiles - Changed file paths (absolute)
+ * @param {string[]} testFiles - Test file paths (absolute)
+ * @param {Map<string, Set<string>>} graph - Dependency graph
+ * @returns {string[]} Impacted test files
+ */
+export function findImpactedTests(changedFiles, testFiles, graph) {
+  const inverted = invertGraph(graph);
+  const impacted = new Set();
+  const visited = new Set();
+  const pending = [...changedFiles];
+  const testSet = new Set(testFiles);
+
+  for (let i = 0; i < pending.length; i++) {
+    const file = pending[i];
+
+    if (visited.has(file)) continue;
+    visited.add(file);
+
+    // If this file is a test file, it's impacted
+    if (testSet.has(file)) {
+      impacted.add(file);
+    }
+
+    // Add all files that depend on this file
+    const dependents = inverted.get(file);
+    if (dependents) {
+      for (const dependent of dependents) {
+        if (!visited.has(dependent)) {
+          pending.push(dependent);
+        }
+      }
+    }
+  }
+
+  return [...impacted];
+}
+
+/**
+ * Main entry: find test files impacted by changed files
+ * @param {string[]} changedFiles - Changed files (absolute paths)
+ * @param {string[]} testFiles - All test files (absolute paths)
+ * @param {Object} options
+ * @param {string[]} [options.excludePaths=['node_modules', 'dist']] - Paths to exclude from graph
+ * @param {ImportCache} [options.cache] - Optional cache for import extraction
+ * @returns {string[]} Impacted test files
+ */
+export function getImpactedTests(changedFiles, testFiles, options = {}) {
+  const graph = buildDependencyGraph(testFiles, options);
+  return findImpactedTests(changedFiles, testFiles, graph);
+}

package/src/index.js

@@ -0,0 +1,91 @@
+import { resolve } from 'node:path';
+import fg from 'fast-glob';
+import { getImpactedTests } from './graph.js';
+import { createCache, ImportCache } from './cache.js';
+
+/**
+ * Find test files impacted by code changes
+ *
+ * @param {Object} options
+ * @param {string[]} options.changedFiles - Files that changed (relative or absolute)
+ * @param {string|string[]} options.testFiles - Test file glob pattern(s) or explicit file list
+ * @param {string} [options.cwd=process.cwd()] - Working directory
+ * @param {string[]} [options.excludePaths=['node_modules', 'dist']] - Paths to exclude from graph
+ * @param {ImportCache} [options.cache] - Cache instance for import extraction
+ * @param {string} [options.cacheFile] - Path to persist cache (creates cache automatically)
+ * @returns {Promise<string[]>} Impacted test file paths (absolute)
+ *
+ * @example
+ * import { findImpacted } from 'impacted';
+ *
+ * const tests = await findImpacted({
+ *   changedFiles: ['src/utils.js'],
+ *   testFiles: 'test/** /*.test.js',
+ * });
+ *
+ * @example
+ * // With persistent caching
+ * const tests = await findImpacted({
+ *   changedFiles: ['src/utils.js'],
+ *   testFiles: 'test/** /*.test.js',
+ *   cacheFile: '.impacted-cache.json',
+ * });
+ */
+export async function findImpacted(options) {
+  const {
+    changedFiles,
+    testFiles,
+    cwd = process.cwd(),
+    excludePaths,
+    cache: providedCache,
+    cacheFile,
+  } = options;
+
+  if (!changedFiles || changedFiles.length === 0) {
+    return [];
+  }
+
+  // Resolve changed files to absolute paths
+  const absoluteChangedFiles = changedFiles.map((f) => resolve(cwd, f));
+
+  // Resolve test files - either glob or explicit list
+  let absoluteTestFiles;
+  if (typeof testFiles === 'string' || (Array.isArray(testFiles) && testFiles.some((t) => t.includes('*')))) {
+    // It's a glob pattern
+    const patterns = Array.isArray(testFiles) ? testFiles : [testFiles];
+    absoluteTestFiles = await fg(patterns, { cwd, absolute: true });
+  } else if (Array.isArray(testFiles)) {
+    // Explicit file list
+    absoluteTestFiles = testFiles.map((f) => resolve(cwd, f));
+  } else {
+    return [];
+  }
+
+  if (absoluteTestFiles.length === 0) {
+    return [];
+  }
+
+  // Set up cache
+  let cache = providedCache;
+  if (!cache && cacheFile) {
+    cache = createCache({ cacheFile: resolve(cwd, cacheFile) });
+  }
+
+  const result = getImpactedTests(absoluteChangedFiles, absoluteTestFiles, {
+    excludePaths,
+    cache,
+  });
+
+  // Persist cache if using cacheFile option
+  if (!providedCache && cacheFile && cache) {
+    cache.save();
+  }
+
+  return result;
+}
+
+// Re-export lower-level APIs for advanced usage
+export { buildDependencyGraph, findImpactedTests, invertGraph } from './graph.js';
+export { parseImports } from './parser.js';
+export { resolveSpecifier } from './resolver.js';
+export { createCache, ImportCache } from './cache.js';

package/src/parser.js

@@ -0,0 +1,75 @@
+import * as acorn from 'acorn';
+import * as walk from 'acorn-walk';
+
+/**
+ * Extract all import/require specifiers from source code
+ * Handles ESM (import/export) and CJS (require) patterns
+ * @param {string} source - The source code
+ * @returns {string[]} Array of import specifiers
+ */
+export function parseImports(source) {
+  const imports = [];
+
+  let ast;
+  try {
+    ast = acorn.parse(source, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      allowHashBang: true,
+      allowReturnOutsideFunction: true,
+      allowAwaitOutsideFunction: true,
+    });
+  } catch {
+    // If module mode fails, try script mode for pure CJS files
+    try {
+      ast = acorn.parse(source, {
+        ecmaVersion: 'latest',
+        sourceType: 'script',
+        allowHashBang: true,
+        allowReturnOutsideFunction: true,
+      });
+    } catch {
+      return [];
+    }
+  }
+
+  walk.simple(ast, {
+    // require('specifier')
+    CallExpression(node) {
+      if (
+        node.callee.name === 'require' &&
+        node.arguments.length > 0 &&
+        node.arguments[0].type === 'Literal' &&
+        typeof node.arguments[0].value === 'string'
+      ) {
+        imports.push(node.arguments[0].value);
+      }
+    },
+    // import('specifier') - dynamic import
+    ImportExpression(node) {
+      if (node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        imports.push(node.source.value);
+      }
+    },
+    // import x from 'specifier'
+    ImportDeclaration(node) {
+      if (node.source.type === 'Literal' && typeof node.source.value === 'string') {
+        imports.push(node.source.value);
+      }
+    },
+    // export * from 'specifier'
+    ExportAllDeclaration(node) {
+      if (node.source?.type === 'Literal' && typeof node.source.value === 'string') {
+        imports.push(node.source.value);
+      }
+    },
+    // export { x } from 'specifier'
+    ExportNamedDeclaration(node) {
+      if (node.source?.type === 'Literal' && typeof node.source.value === 'string') {
+        imports.push(node.source.value);
+      }
+    },
+  });
+
+  return imports;
+}

package/src/resolver.js

@@ -0,0 +1,116 @@
+import { createRequire } from 'node:module';
+import { builtinModules } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * Find the nearest package.json from a given path
+ * @param {string} startPath
+ * @returns {{ path: string, pkg: object } | null}
+ */
+function findPackageJson(startPath) {
+  let dir = dirname(startPath);
+  const root = resolve('/');
+
+  while (dir !== root) {
+    const pkgPath = join(dir, 'package.json');
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      return { path: pkgPath, pkg, dir };
+    } catch {
+      dir = dirname(dir);
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve subpath imports (#imports) from package.json imports field
+ * @param {string} specifier - The import specifier starting with #
+ * @param {string} parentPath - Absolute path to the parent file
+ * @returns {string|null}
+ */
+function resolveSubpathImport(specifier, parentPath) {
+  const pkgInfo = findPackageJson(parentPath);
+  if (!pkgInfo || !pkgInfo.pkg.imports) {
+    return null;
+  }
+
+  const { imports } = pkgInfo.pkg;
+
+  // Direct match
+  if (imports[specifier]) {
+    const target = resolveImportTarget(imports[specifier]);
+    if (target) {
+      return resolve(pkgInfo.dir, target);
+    }
+  }
+
+  // Pattern match (e.g., "#utils/*" -> "./src/utils/*")
+  for (const [pattern, target] of Object.entries(imports)) {
+    if (pattern.includes('*')) {
+      const prefix = pattern.slice(0, pattern.indexOf('*'));
+      const suffix = pattern.slice(pattern.indexOf('*') + 1);
+
+      if (specifier.startsWith(prefix) && specifier.endsWith(suffix)) {
+        const matched = specifier.slice(prefix.length, specifier.length - suffix.length || undefined);
+        const resolvedTarget = resolveImportTarget(target);
+        if (resolvedTarget) {
+          const finalPath = resolvedTarget.replace('*', matched);
+          return resolve(pkgInfo.dir, finalPath);
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve an import target (handles conditional exports)
+ * @param {string|object} target
+ * @returns {string|null}
+ */
+function resolveImportTarget(target) {
+  if (typeof target === 'string') {
+    return target;
+  }
+
+  if (typeof target === 'object' && target !== null) {
+    // Priority: import > node > default > require
+    const conditions = ['import', 'node', 'default', 'require'];
+    for (const condition of conditions) {
+      if (target[condition]) {
+        return resolveImportTarget(target[condition]);
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve a specifier to an absolute file path
+ * Handles: CJS require, ESM import, subpath imports (#)
+ * @param {string} specifier - The import/require specifier
+ * @param {string} parentPath - Absolute path to the parent file
+ * @returns {string|null} Resolved absolute path or null if resolution fails
+ */
+export function resolveSpecifier(specifier, parentPath) {
+  // Skip built-in modules
+  if (specifier.startsWith('node:') || builtinModules.includes(specifier)) {
+    return null;
+  }
+
+  // Handle subpath imports (#imports)
+  if (specifier.startsWith('#')) {
+    return resolveSubpathImport(specifier, parentPath);
+  }
+
+  try {
+    const require = createRequire(parentPath);
+    return require.resolve(specifier);
+  } catch {
+    return null;
+  }
+}