@autotests/playwright-impact 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# test-impact-core
+
+Select only impacted Playwright specs from changed POM and utility methods.
+
+`test-impact-core` is built for Playwright teams using Page Object Model who want faster feedback and shorter CI cycles without running the full test suite on every commit.
+
+It solves a common problem: broad reruns after small UI/POM changes. Instead of running everything, it computes the smallest reliable spec set to execute.
+
+## Install
+
+```bash
+// npm
+npm i @autotests/test-impact-core
+
+// pnpm
+pnpm add @autotests/test-impact-core
+```
+
+## Why
+
+- Large Playwright projects grow quickly, and full-suite runs become expensive.
+- POM-heavy repositories often change in narrow areas but still trigger wide test execution.
+- Running all specs for each PR slows CI, delays triage, and increases infrastructure cost.
+- `test-impact-core` changes this by selecting only specs impacted by changed files and changed method behavior.
+
+## 30-Second Setup (Minimum Required Configuration)
+
+Only these fields are required. Everything else has defaults.
+
+- `repoRoot`: absolute path to repository root.
+- `profile.testsRootRelative`: where Playwright specs live.
+- `profile.changedSpecPrefix`: prefix used to detect directly changed spec files.
+- `profile.isRelevantPomPath(filePath)`: rule that marks which source files are considered POM/utility inputs for impact analysis.
+
+Public API entry point: `analyzeImpactedSpecs`.
+
+## Typical CI Usage
+
+Typical workflow in CI:
+
+1. Compare feature branch changes against `main` (via `baseRef`).
+2. Compute impacted specs.
+3. Exit early when `hasAnythingToRun` is false.
+4. Run only `selectedSpecsRelative` in Playwright.
+
+This pattern reduces pipeline time while keeping selection practical and explainable.
+
+## How It Works (High Level)
+
+1. Read changed files from Git.
+2. Mark directly changed spec files.
+3. Detect semantic impact in changed POM/utility methods.
+4. Map impacted methods to fixture usage in specs.
+5. Apply selection policy and return final spec set.
+
+## Before/After Example (Text)
+
+Before:
+- A change in one shared POM/utility file often leads teams to run a large suite or the full project.
+
+After with `test-impact-core`:
+- The same change results in a narrowed list of impacted specs only.
+- Directly changed specs are still always included.
+- CI runs faster, and failures are easier to link to the actual code change.
+
+## Configuration
+
+### Required
+
+- `repoRoot`: absolute path to repository root.
+- `profile`: project configuration object.
+- `profile.testsRootRelative`: tests root relative path.
+- `profile.changedSpecPrefix`: prefix for direct changed spec detection.
+- `profile.isRelevantPomPath(filePath)`: function that returns true for relevant POM/utility files.
+
+### Optional (Advanced)
+
+Most teams can skip these initially.
+
+- `analysisRootsRelative`: roots for class/method graph scan. Default: `['src/pages', 'src/utils']`.
+- `fixturesTypesRelative`: fixture map file path. Default: `src/fixtures/types.ts`.
+- `baseRef`: git ref for comparison (example: `origin/main`).
+- `includeUntrackedSpecs` (default `true`): include untracked `*.spec.ts`/`*.spec.tsx` as direct changed specs.
+- `includeWorkingTreeWithBase` (default `true`): when `baseRef` is set, union committed diff (`base...HEAD`) with current working tree diff (`HEAD`).
+- `fileExtensions` (default `['.ts', '.tsx']`): file extensions to analyze.
+- `selectionBias` (default `'fail-open'`): uncertain call-site behavior.
+
+## Result Fields (Most Used)
+
+- `selectedSpecsRelative`: relative paths for your test runner CLI.
+- `hasAnythingToRun`: quick boolean for early exit.
+- `selectionReasons`: reason code per selected spec.
+
+## Advanced Diagnostics
+
+- `warnings`: compatibility or uncertainty warnings.
+- `coverageStats.uncertainCallSites`: count of uncertain call sites encountered.
+- `coverageStats.statusFallbackHits`: count of git status fallbacks (`C/T/U/unknown`).
+- `changedEntriesBySource`: diagnostics for diff sources (`base...HEAD`, working tree, untracked).
+
+### Reason Codes
+
+- `direct-changed-spec`: spec was directly changed in git/untracked set.
+- `matched-precise`: spec has precise impacted fixture method usage.
+- `matched-uncertain-fail-open`: uncertain match retained by fail-open policy.
+- `retained-no-bindings`: spec kept because no fixture bindings were found in callback params.
+
+### Selection Policy (`selectionBias`)
+
+- Default: `fail-open` for pragmatic safety.
+- Alternative: `fail-closed` to drop uncertain matches.
+
+## Notes
+
+- This library is intentionally pragmatic and defaults to `selectionBias: 'fail-open'`.
+- For maximum safety, use `fail-open` in CI and monitor `warnings`/`uncertainCallSites`.
+- Use deterministic input (`baseRef`, clean profile predicates) for deterministic output.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@autotests/playwright-impact",
+  "version": "0.1.0",
+  "description": "Core impacted-test selection library for changed POM/method analysis",
+  "license": "ISC",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "types": "src/index.d.ts",
+  "files": [
+    "src",
+    "tests",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "peerDependencies": {
+    "typescript": ">=5 <6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.9",
+    "typescript": "^5.9.2"
+  }
+}

package/src/analyze-impacted-specs.js

@@ -0,0 +1,294 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  SUPPORTED_FILE_EXTENSIONS,
+  listFilesRecursive,
+  getChangedEntries,
+  readChangeContents,
+  getUntrackedSpecPaths,
+} = require('./modules/file-and-git-helpers');
+const { buildInheritanceGraph, collectImpactedClasses, getFixtureKeysForClasses } = require('./modules/class-impact-helpers');
+const { parseFixtureMappings } = require('./modules/fixture-map-helpers');
+const { collectChangedMethodsByClass, buildImpactedMethodsByClass } = require('./modules/method-impact-helpers');
+const { selectSpecFiles } = require('./modules/spec-selection-helpers');
+const { filterSpecsByImpactedMethods } = require('./modules/method-filter-helpers');
+const { selectSpecsByChangedImports } = require('./modules/import-impact-helpers');
+const { evaluateGlobalWatch, getDefaultGlobalWatchPatterns } = require('./modules/global-watch-helpers');
+
+const DIRECT_CHANGED_SPEC_STATUSES = new Set(['A', 'M', 'R']);
+const DEFAULT_SELECTION_BIAS = 'fail-open';
+const DEFAULT_GLOBAL_WATCH_MODE = 'force-all-in-project';
+
+const getStatusSummary = (entries) => {
+  const summary = { A: 0, M: 0, D: 0, R: 0 };
+  for (const entry of entries) {
+    if (summary[entry.status] !== undefined) summary[entry.status] += 1;
+  }
+  return summary;
+};
+
+const validateProfile = (profile) => {
+  if (!profile || typeof profile !== 'object') throw new Error('Missing required profile configuration');
+  if (!profile.testsRootRelative) throw new Error('Missing profile.testsRootRelative');
+  if (!profile.changedSpecPrefix) throw new Error('Missing profile.changedSpecPrefix');
+  if (typeof profile.isRelevantPomPath !== 'function') throw new Error('Missing profile.isRelevantPomPath(filePath) function');
+};
+
+const normalizeFileExtensions = (fileExtensions) => {
+  const source = Array.isArray(fileExtensions) && fileExtensions.length > 0 ? fileExtensions : Array.from(SUPPORTED_FILE_EXTENSIONS);
+  const normalized = source
+    .map((ext) => String(ext || '').trim().toLowerCase())
+    .filter((ext) => ext.startsWith('.'));
+  return normalized.length > 0 ? Array.from(new Set(normalized)) : Array.from(SUPPORTED_FILE_EXTENSIONS);
+};
+
+/**
+ * Analyze changed sources and return the deterministic list of impacted spec files.
+ * Pipeline:
+ * 1) collect and normalize changed entries from git/untracked sources
+ * 2) seed semantic impact from changed POM classes/methods
+ * 3) Stage A preselect specs by impacted fixture keys
+ * 4) Stage B precise/uncertain method matching with selection bias policy
+ */
+const analyzeImpactedSpecs = ({
+  repoRoot,
+  baseRef = null,
+  profile,
+  includeUntrackedSpecs = true,
+  includeWorkingTreeWithBase = true,
+  fileExtensions = ['.ts', '.tsx'],
+  selectionBias = DEFAULT_SELECTION_BIAS,
+}) => {
+  validateProfile(profile);
+  if (!repoRoot) throw new Error('Missing required repoRoot');
+
+  const effectiveExtensions = normalizeFileExtensions(fileExtensions);
+  const testsRoot = path.join(repoRoot, profile.testsRootRelative);
+  const analysisRootsRelative = profile.analysisRootsRelative || ['src/pages', 'src/utils'];
+  const fixturesTypesRelative = profile.fixturesTypesRelative || 'src/fixtures/types.ts';
+  const globalWatchMode = profile.globalWatchMode || DEFAULT_GLOBAL_WATCH_MODE;
+  const globalWatchPatterns = Array.isArray(profile.globalWatchPatterns) && profile.globalWatchPatterns.length > 0
+    ? profile.globalWatchPatterns
+    : getDefaultGlobalWatchPatterns();
+
+  // Stage 0: gather changed files and keep only profile-relevant subsets.
+  const changedEntriesResult = getChangedEntries({
+    repoRoot,
+    baseRef,
+    includeWorkingTreeWithBase,
+    profile,
+    fileExtensions: effectiveExtensions,
+  });
+  const changedEntries = changedEntriesResult.entries;
+  const changedPomEntries = changedEntries.filter((entry) => {
+    const candidates = [entry.effectivePath, entry.oldPath, entry.newPath].filter(Boolean);
+    return candidates.some((filePath) => profile.isRelevantPomPath(filePath));
+  });
+  const changedSpecEntries = changedEntries.filter((entry) => {
+    const targetPath = String(entry.effectivePath || '').trim();
+    return targetPath.startsWith(profile.changedSpecPrefix) && effectiveExtensions.some((ext) => targetPath.endsWith(`.spec${ext}`));
+  });
+  const globalWatch = globalWatchMode === 'disabled'
+    ? { matchedPaths: [], resolvedFiles: [] }
+    : evaluateGlobalWatch({
+      repoRoot,
+      changedEntries,
+      patterns: globalWatchPatterns,
+      listFilesRecursive,
+    });
+
+  const changedSpecFiles = changedSpecEntries
+    .filter((entry) => DIRECT_CHANGED_SPEC_STATUSES.has(entry.status))
+    .map((entry) => entry.effectivePath)
+    .filter(Boolean);
+  const untrackedSpecFiles = includeUntrackedSpecs
+    ? getUntrackedSpecPaths({ repoRoot, changedSpecPrefix: profile.changedSpecPrefix, fileExtensions: effectiveExtensions })
+    : [];
+  const directChangedSpecFiles = Array.from(new Set([...changedSpecFiles, ...untrackedSpecFiles])).sort((a, b) => a.localeCompare(b));
+
+  if (globalWatchMode !== 'disabled' && globalWatch.matchedPaths.length > 0) {
+    const selectedSpecs = listFilesRecursive(testsRoot)
+      .filter((filePath) => effectiveExtensions.some((ext) => filePath.endsWith(`.spec${ext}`)))
+      .sort((a, b) => a.localeCompare(b));
+    const selectionReasons = new Map(selectedSpecs.map((specPath) => [specPath, 'global-watch-force-all']));
+
+    return {
+      selectedSpecs,
+      selectedSpecsRelative: selectedSpecs.map((specPath) => path.relative(repoRoot, specPath)),
+      changedPomEntries,
+      directChangedSpecFiles,
+      statusSummary: getStatusSummary(changedPomEntries),
+      impactedClasses: new Set(),
+      impactedMethodsByClass: new Map(),
+      fixtureKeys: new Set(),
+      stageASelectedCount: selectedSpecs.length,
+      semanticStats: { changedPomEntriesByStatus: { A: 0, M: 0, D: 0, R: 0 }, semanticChangedMethodsCount: 0, topLevelRuntimeChangedFiles: 0 },
+      propagationStats: { impactedMethodsTotal: 0 },
+      droppedByMethodFilter: 0,
+      retainedWithoutMethodFilter: 0,
+      selectionReasons,
+      hasAnythingToRun: selectedSpecs.length > 0,
+      warnings: changedEntriesResult.warnings,
+      coverageStats: { uncertainCallSites: 0, statusFallbackHits: changedEntriesResult.statusFallbackHits },
+      changedEntriesBySource: changedEntriesResult.changedEntriesBySource,
+      forcedAllSpecs: true,
+      forcedAllSpecsReason: 'global-watch-force-all',
+      globalWatchMatches: globalWatch.matchedPaths,
+      globalWatchResolvedFiles: globalWatch.resolvedFiles,
+    };
+  }
+
+  // Fast exit when neither changed POM files nor direct changed specs are present.
+  if (changedPomEntries.length === 0 && directChangedSpecFiles.length === 0) {
+    return {
+      selectedSpecs: [],
+      selectedSpecsRelative: [],
+      changedPomEntries,
+      directChangedSpecFiles,
+      statusSummary: getStatusSummary(changedPomEntries),
+      impactedClasses: new Set(),
+      impactedMethodsByClass: new Map(),
+      fixtureKeys: new Set(),
+      stageASelectedCount: 0,
+      semanticStats: { changedPomEntriesByStatus: { A: 0, M: 0, D: 0, R: 0 }, semanticChangedMethodsCount: 0, topLevelRuntimeChangedFiles: 0 },
+      propagationStats: { impactedMethodsTotal: 0 },
+      droppedByMethodFilter: 0,
+      retainedWithoutMethodFilter: 0,
+      selectionReasons: new Map(),
+      hasAnythingToRun: false,
+      warnings: changedEntriesResult.warnings,
+      coverageStats: { uncertainCallSites: 0, statusFallbackHits: changedEntriesResult.statusFallbackHits },
+      changedEntriesBySource: changedEntriesResult.changedEntriesBySource,
+      forcedAllSpecs: false,
+      forcedAllSpecsReason: null,
+      globalWatchMatches: globalWatch.matchedPaths,
+      globalWatchResolvedFiles: globalWatch.resolvedFiles,
+    };
+  }
+
+  let impactedClasses = new Set();
+  let impactedMethodsByClass = new Map();
+  let fixtureKeys = new Set();
+  let fixtureKeyToClass = new Map();
+  let selectedSpecs = [];
+  let stageASelectedCount = 0;
+  let semanticStats = {
+    changedPomEntriesByStatus: { A: 0, M: 0, D: 0, R: 0 },
+    semanticChangedMethodsCount: 0,
+    topLevelRuntimeChangedFiles: 0,
+  };
+  let propagationStats = { impactedMethodsTotal: 0 };
+  let propagationWarnings = [];
+  let importMatchedSpecs = [];
+
+  const pageFiles = analysisRootsRelative
+    .flatMap((relativePath) => listFilesRecursive(path.join(repoRoot, relativePath)))
+    .filter((filePath) => effectiveExtensions.includes(path.extname(filePath).toLowerCase()));
+  const { parentsByChild, childrenByParent } = buildInheritanceGraph(pageFiles, fs.readFileSync);
+
+  if (changedPomEntries.length > 0) {
+    importMatchedSpecs = selectSpecsByChangedImports({
+      repoRoot,
+      testsRootAbs: testsRoot,
+      changedPomEntries,
+      listFilesRecursive,
+      fileExtensions: effectiveExtensions,
+    });
+  }
+
+  // Stage 1: semantic seed and callgraph propagation from changed POM entries.
+  if (changedPomEntries.length > 0) {
+    const changedMethodsResult = collectChangedMethodsByClass({
+      changedPomEntries,
+      baseRef,
+      readChangeContents: (entry, entryBaseRef) => readChangeContents({ repoRoot, entry, baseRef: entryBaseRef }),
+    });
+
+    semanticStats = changedMethodsResult.stats;
+    const hasSemanticPomImpact = semanticStats.semanticChangedMethodsCount > 0 || semanticStats.topLevelRuntimeChangedFiles > 0;
+
+    if (hasSemanticPomImpact) {
+      impactedClasses = collectImpactedClasses({
+        changedPomEntries,
+        childrenByParent,
+        baseRef,
+        readChangeContents: (entry, entryBaseRef) => readChangeContents({ repoRoot, entry, baseRef: entryBaseRef }),
+      });
+
+      const impactedMethodsResult = buildImpactedMethodsByClass({
+        impactedClasses,
+        changedMethodsByClass: changedMethodsResult.changedMethodsByClass,
+        parentsByChild,
+        pageFiles,
+      });
+
+      impactedMethodsByClass = impactedMethodsResult.impactedMethodsByClass;
+      propagationStats = impactedMethodsResult.stats;
+      propagationWarnings = impactedMethodsResult.warnings || [];
+
+      const fixtureMappings = parseFixtureMappings({ typesPath: path.join(repoRoot, fixturesTypesRelative) });
+      fixtureKeyToClass = fixtureMappings.fixtureKeyToClass;
+      const classesForFixtureSelection = impactedMethodsByClass.size > 0 ? new Set(impactedMethodsByClass.keys()) : impactedClasses;
+      fixtureKeys = getFixtureKeysForClasses(classesForFixtureSelection, fixtureMappings.classToFixtureKeys);
+
+      // Stage A: fixture-key prefilter to avoid scanning unrelated specs in Stage B.
+      if (fixtureKeys.size > 0) {
+        selectedSpecs = selectSpecFiles({ testsRootAbs: testsRoot, fixtureKeys, listFilesRecursive, fileExtensions: effectiveExtensions });
+        stageASelectedCount = selectedSpecs.length;
+      }
+    }
+  }
+
+  // Directly changed specs are always added after Stage A prefilter.
+  const directChangedSpecsAbs = directChangedSpecFiles.map((filePath) => path.join(repoRoot, filePath));
+  const selectedSet = new Set([...selectedSpecs, ...directChangedSpecsAbs, ...importMatchedSpecs]);
+  selectedSpecs = Array.from(selectedSet).sort((a, b) => a.localeCompare(b));
+  stageASelectedCount = selectedSpecs.length;
+
+  // Stage B: method-level filtering with fail-open/fail-closed handling for uncertain call sites.
+  const methodFilterResult = filterSpecsByImpactedMethods({
+    selectedSpecs,
+    directChangedSpecsAbs,
+    alwaysIncludeSpecsAbs: importMatchedSpecs,
+    fixtureKeyToClass,
+    fixtureKeys,
+    impactedMethodsByClass,
+    selectionBias,
+  });
+
+  selectedSpecs = methodFilterResult.filteredSpecs;
+
+  return {
+    selectedSpecs,
+    selectedSpecsRelative: selectedSpecs.map((specPath) => path.relative(repoRoot, specPath)),
+    changedPomEntries,
+    directChangedSpecFiles,
+    statusSummary: getStatusSummary(changedPomEntries),
+    impactedClasses,
+    impactedMethodsByClass,
+    fixtureKeys,
+    stageASelectedCount,
+    semanticStats,
+    propagationStats,
+    droppedByMethodFilter: methodFilterResult.droppedByMethodFilter,
+    retainedWithoutMethodFilter: methodFilterResult.retainedWithoutMethodFilter,
+    selectionReasons: methodFilterResult.selectionReasons,
+    hasAnythingToRun: selectedSpecs.length > 0,
+    warnings: [...changedEntriesResult.warnings, ...propagationWarnings, ...methodFilterResult.warnings],
+    coverageStats: {
+      uncertainCallSites: methodFilterResult.uncertainCallSites,
+      statusFallbackHits: changedEntriesResult.statusFallbackHits,
+    },
+    changedEntriesBySource: changedEntriesResult.changedEntriesBySource,
+    forcedAllSpecs: false,
+    forcedAllSpecsReason: null,
+    globalWatchMatches: globalWatch.matchedPaths,
+    globalWatchResolvedFiles: globalWatch.resolvedFiles,
+  };
+};
+
+module.exports = {
+  analyzeImpactedSpecs,
+};

package/src/format-analyze-result.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Format selection reasons as log-friendly lines for CLI output.
+ * The output is deterministic and can be truncated with maxLines.
+ */
+const formatSelectionReasonsForLog = ({ selectedSpecs, selectionReasons, repoRoot, maxLines = 40 }) => {
+  if (!selectionReasons || typeof selectionReasons.get !== 'function' || selectedSpecs.length === 0) return '';
+
+  const lines = [];
+  for (const specPath of selectedSpecs) {
+    const reason = selectionReasons.get(specPath);
+    if (!reason) continue;
+    lines.push(`       - ${path.relative(repoRoot, specPath)}: ${reason}`);
+  }
+
+  if (lines.length === 0) return '';
+  if (lines.length <= maxLines) return lines.join('\n');
+
+  const visible = lines.slice(0, maxLines);
+  const hidden = lines.length - maxLines;
+  return `${visible.join('\n')}\n       - ... ${hidden} more selected specs with reasons`;
+};
+
+module.exports = {
+  formatSelectionReasonsForLog,
+};

package/src/index.d.ts

@@ -0,0 +1,74 @@
+export type ChangedEntryStatus = 'A' | 'M' | 'D' | 'R';
+
+export type ChangedEntry = {
+  status: ChangedEntryStatus;
+  oldPath: string | null;
+  newPath: string | null;
+  effectivePath: string;
+  rawStatus?: string;
+};
+
+export type AnalyzeProfile = {
+  testsRootRelative: string;
+  changedSpecPrefix: string;
+  isRelevantPomPath: (filePath: string) => boolean;
+  analysisRootsRelative?: string[];
+  fixturesTypesRelative?: string;
+  globalWatchPatterns?: string[];
+  globalWatchMode?: 'force-all-in-project' | 'disabled';
+};
+
+export type AnalyzeOptions = {
+  repoRoot: string;
+  baseRef?: string | null;
+  profile: AnalyzeProfile;
+  includeUntrackedSpecs?: boolean;
+  includeWorkingTreeWithBase?: boolean;
+  fileExtensions?: string[];
+  selectionBias?: 'fail-open' | 'balanced' | 'fail-closed';
+};
+
+export type AnalyzeResult = {
+  selectedSpecs: string[];
+  selectedSpecsRelative: string[];
+  changedPomEntries: ChangedEntry[];
+  directChangedSpecFiles: string[];
+  statusSummary: { A: number; M: number; D: number; R: number };
+  impactedClasses: Set<string>;
+  impactedMethodsByClass: Map<string, Set<string>>;
+  fixtureKeys: Set<string>;
+  stageASelectedCount: number;
+  semanticStats: {
+    changedPomEntriesByStatus: { A: number; M: number; D: number; R: number };
+    semanticChangedMethodsCount: number;
+    topLevelRuntimeChangedFiles: number;
+  };
+  propagationStats: { impactedMethodsTotal: number };
+  droppedByMethodFilter: number;
+  retainedWithoutMethodFilter: number;
+  selectionReasons: Map<string, string>;
+  hasAnythingToRun: boolean;
+  warnings: string[];
+  coverageStats: {
+    uncertainCallSites: number;
+    statusFallbackHits: number;
+  };
+  changedEntriesBySource: {
+    fromBaseHead: number;
+    fromWorkingTree: number;
+    fromUntracked: number;
+  };
+  forcedAllSpecs: boolean;
+  forcedAllSpecsReason: string | null;
+  globalWatchMatches: string[];
+  globalWatchResolvedFiles: string[];
+};
+
+export function analyzeImpactedSpecs(options: AnalyzeOptions): AnalyzeResult;
+
+export function formatSelectionReasonsForLog(args: {
+  selectedSpecs: string[];
+  selectionReasons: Map<string, string>;
+  repoRoot: string;
+  maxLines?: number;
+}): string;

package/src/index.js

@@ -0,0 +1,10 @@
+'use strict';
+
+const { analyzeImpactedSpecs } = require('./analyze-impacted-specs');
+const { formatSelectionReasonsForLog } = require('./format-analyze-result');
+
+// Public library surface.
+module.exports = {
+  analyzeImpactedSpecs,
+  formatSelectionReasonsForLog,
+};

package/src/modules/class-impact-helpers.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const parseClassNames = (content) => {
+  if (!content) return new Set();
+  const names = new Set();
+  const re = /(?:export\s+)?class\s+([A-Za-z_]\w*)/g;
+  let match = re.exec(content);
+  while (match) {
+    names.add(match[1]);
+    match = re.exec(content);
+  }
+  return names;
+};
+
+/**
+ * Build simple inheritance lookup maps from source files.
+ * These maps are reused in class impact and method propagation stages.
+ */
+const buildInheritanceGraph = (pageFiles, readFile) => {
+  // Build parent/child lookup once so both Stage A and method propagation can resolve lineage.
+  const parentsByChild = new Map();
+  const childrenByParent = new Map();
+
+  for (const filePath of pageFiles) {
+    const content = readFile(filePath, 'utf8');
+    const re = /(?:export\s+)?class\s+([A-Za-z_]\w*)\s+extends\s+([A-Za-z_]\w*)/g;
+    let match = re.exec(content);
+    while (match) {
+      const child = match[1];
+      const parent = match[2];
+      parentsByChild.set(child, parent);
+      if (!childrenByParent.has(parent)) childrenByParent.set(parent, new Set());
+      childrenByParent.get(parent).add(child);
+      match = re.exec(content);
+    }
+  }
+
+  return { parentsByChild, childrenByParent };
+};
+
+/**
+ * Collect changed classes from base/head content and include all descendants.
+ * Descendant expansion prevents missing specs bound to inherited behavior.
+ */
+const collectImpactedClasses = ({ changedPomEntries, childrenByParent, baseRef, readChangeContents }) => {
+  // Seed impacted classes from both base and head versions, then include descendants.
+  // This keeps fixture preselection safe for renamed files and inheritance-heavy POM trees.
+  const impacted = new Set();
+
+  for (const entry of changedPomEntries) {
+    const { baseContent, headContent } = readChangeContents(entry, baseRef);
+    for (const className of parseClassNames(baseContent)) impacted.add(className);
+    for (const className of parseClassNames(headContent)) impacted.add(className);
+  }
+
+  const queue = [...impacted];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const children = childrenByParent.get(current) || new Set();
+    for (const child of children) {
+      if (impacted.has(child)) continue;
+      impacted.add(child);
+      queue.push(child);
+    }
+  }
+
+  return impacted;
+};
+
+/**
+ * Convert impacted classes to fixture keys used in Stage A spec preselection.
+ */
+const getFixtureKeysForClasses = (impactedClasses, classToFixtureKeys) => {
+  const keys = new Set();
+  for (const className of impactedClasses) {
+    const mappedKeys = classToFixtureKeys.get(className) || new Set();
+    for (const key of mappedKeys) keys.add(key);
+  }
+  return keys;
+};
+
+module.exports = {
+  buildInheritanceGraph,
+  collectImpactedClasses,
+  getFixtureKeysForClasses,
+};