@d-es-ign/stryker-js-instrumenter 9.6.0

package/src/transformers/babel-transformer.ts

@@ -0,0 +1,217 @@
+import babel, { type NodePath, type types } from '@babel/core';
+
+// @ts-expect-error The babel types don't define "File" yet
+import { File } from '@babel/core';
+
+import {
+  isImportDeclaration,
+  isTypeNode,
+  locationIncluded,
+  locationOverlaps,
+  placeHeaderIfNeeded,
+} from '../util/syntax-helpers.js';
+import { ScriptFormat } from '../syntax/index.js';
+import {
+  allMutantPlacers,
+  MutantPlacer,
+  throwPlacementError,
+} from '../mutant-placers/index.js';
+import { Mutable, Mutant } from '../mutant.js';
+import { allMutators } from '../mutators/index.js';
+
+import { DirectiveBookkeeper } from './directive-bookkeeper.js';
+import { IgnorerBookkeeper } from './ignorer-bookkeeper.js';
+
+import { AstTransformer } from './index.js';
+
+const { traverse } = babel;
+
+interface MutantsPlacement<TNode extends types.Node> {
+  appliedMutants: Map<Mutant, TNode>;
+  placer: MutantPlacer<TNode>;
+}
+
+type PlacementMap = Map<types.Node, MutantsPlacement<types.Node>>;
+
+export const transformBabel: AstTransformer<ScriptFormat> = (
+  { root, originFileName, rawContent, offset },
+  mutantCollector,
+  { options, mutateDescription, logger },
+  mutators = allMutators,
+  mutantPlacers = allMutantPlacers,
+) => {
+  // Wrap the AST in a `new File`, so `nodePath.buildCodeFrameError` works
+  // https://github.com/babel/babel/issues/11889
+  const file = new File(
+    { filename: originFileName },
+    { code: rawContent, ast: root },
+  );
+
+  // Create a placementMap for the mutation switching bookkeeping
+  const placementMap: PlacementMap = new Map();
+
+  // Create the bookkeeper responsible for the // Stryker ... directives
+  const directiveBookkeeper = new DirectiveBookkeeper(
+    logger,
+    mutators,
+    originFileName,
+  );
+
+  // The ignorer bookkeeper is responsible for keeping track of the ignored node and the reason why it is ignored
+  const ignorerBookkeeper = new IgnorerBookkeeper(options.ignorers);
+
+  // Now start the actual traversing of the AST
+  //
+  // On the way down:
+  // * Treat the tree as immutable.
+  // * Identify the nodes that can be used to place mutants on in the placement map.
+  // * Generate the mutants on each node.
+  //    * When a node generated mutants, do a short walk back up and register them in the placement map
+  //    * Call the `applied` method using the placement node, that way the mutant will capture the AST with mutation all the way to the placement node
+  //
+  // On the way up:
+  // * If this node has mutants in the placementMap, place them in the AST.
+  //
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+  traverse(file.ast, {
+    enter(path) {
+      directiveBookkeeper.processStrykerDirectives(path.node);
+      if (shouldSkip(path)) {
+        path.skip();
+      } else {
+        ignorerBookkeeper.enterNode(path);
+        addToPlacementMapIfPossible(path);
+        if (shouldMutate(path)) {
+          const mutantsToPlace = collectMutants(path);
+          if (mutantsToPlace.length) {
+            registerInPlacementMap(path, mutantsToPlace);
+          }
+        }
+      }
+    },
+    exit(path) {
+      placeMutantsIfNeeded(path);
+      ignorerBookkeeper.leaveNode(path);
+    },
+  });
+
+  placeHeaderIfNeeded(mutantCollector, originFileName, options, root);
+
+  /**
+   *  If mutants were collected, be sure to register them in the placement map.
+   */
+  function registerInPlacementMap(path: NodePath, mutantsToPlace: Mutant[]) {
+    const placementPath = path.find((ancestor) =>
+      placementMap.has(ancestor.node),
+    );
+    if (placementPath) {
+      const { appliedMutants } = placementMap.get(placementPath.node)!;
+      mutantsToPlace.forEach((mutant) =>
+        appliedMutants.set(mutant, mutant.applied(placementPath.node)),
+      );
+    } else {
+      throw new Error(
+        `Mutants cannot be placed. This shouldn't happen! Unplaced mutants: ${JSON.stringify(mutantsToPlace, null, 2)}`,
+      );
+    }
+  }
+
+  /**
+   * If this node can be used to place mutants on, add to the placement map
+   */
+  function addToPlacementMapIfPossible(path: NodePath) {
+    const placer = mutantPlacers.find((p) => p.canPlace(path));
+    if (placer) {
+      placementMap.set(path.node, { appliedMutants: new Map(), placer });
+    }
+  }
+
+  /**
+   * Don't traverse import declarations, decorators and nodes that don't have overlap with the selected mutation ranges
+   */
+  function shouldSkip(path: NodePath) {
+    return (
+      isTypeNode(path) ||
+      isImportDeclaration(path) ||
+      path.isDecorator() ||
+      !mutateDescription ||
+      (Array.isArray(mutateDescription) &&
+        mutateDescription.every(
+          (range) => !locationOverlaps(range, path.node.loc!),
+        ))
+    );
+  }
+
+  function shouldMutate(path: NodePath) {
+    return (
+      mutateDescription === true ||
+      (Array.isArray(mutateDescription) &&
+        mutateDescription.some((range) =>
+          locationIncluded(range, path.node.loc!),
+        ))
+    );
+  }
+
+  /**
+   * Place mutants that are assigned to the current node path (on exit)
+   */
+  function placeMutantsIfNeeded(path: NodePath) {
+    const mutantsPlacement = placementMap.get(path.node);
+    if (mutantsPlacement?.appliedMutants.size) {
+      try {
+        mutantsPlacement.placer.place(path, mutantsPlacement.appliedMutants);
+        path.skip();
+      } catch (error) {
+        throwPlacementError(
+          error as Error,
+          path,
+          mutantsPlacement.placer,
+          [...mutantsPlacement.appliedMutants.keys()],
+          originFileName,
+        );
+      }
+    }
+  }
+
+  /**
+   * Collect the mutants for the current node and return the non-ignored.
+   */
+  function collectMutants(path: NodePath) {
+    return [...mutate(path)]
+      .map((mutable) =>
+        mutantCollector.collect(originFileName, path.node, mutable, offset),
+      )
+      .filter((mutant) => !mutant.ignoreReason);
+  }
+
+  /**
+   * Generate mutants for the current node.
+   */
+  function* mutate(node: NodePath): Iterable<Mutable> {
+    for (const mutator of mutators) {
+      for (const replacement of mutator.mutate(node)) {
+        yield {
+          replacement,
+          mutatorName: mutator.name,
+          ignoreReason:
+            directiveBookkeeper.findIgnoreReason(
+              node.node.loc!.start.line,
+              mutator.name,
+            ) ??
+            findExcludedMutatorIgnoreReason(mutator.name) ??
+            ignorerBookkeeper.currentIgnoreMessage,
+        };
+      }
+    }
+
+    function findExcludedMutatorIgnoreReason(
+      mutatorName: string,
+    ): string | undefined {
+      if (options.excludedMutations.includes(mutatorName)) {
+        return `Ignored because of excluded mutation "${mutatorName}"`;
+      } else {
+        return undefined;
+      }
+    }
+  }
+};

package/src/transformers/directive-bookkeeper.ts

@@ -0,0 +1,173 @@
+import type { types } from '@babel/core';
+import { notEmpty } from '@stryker-mutator/util';
+
+import { Logger } from '@stryker-mutator/api/logging';
+
+import { NodeMutator } from '../mutators/node-mutator.js';
+
+const WILDCARD = 'all';
+const DEFAULT_REASON = 'Ignored using a comment';
+
+type IgnoreReason = string | undefined;
+
+interface Rule {
+  findIgnoreReason(mutatorName: string, line: number): IgnoreReason;
+}
+
+class IgnoreRule implements Rule {
+  constructor(
+    public mutatorNames: string[],
+    public line: number | undefined,
+    public ignoreReason: IgnoreReason,
+    public previousRule: Rule,
+  ) {}
+
+  private matches(mutatorName: string, line: number): boolean {
+    const lineMatches = () => this.line === undefined || this.line === line;
+    const mutatorMatches = () =>
+      this.mutatorNames.includes(mutatorName) ||
+      this.mutatorNames.includes(WILDCARD);
+    return lineMatches() && mutatorMatches();
+  }
+
+  public findIgnoreReason(mutatorName: string, line: number): IgnoreReason {
+    if (this.matches(mutatorName, line)) {
+      return this.ignoreReason;
+    }
+    return this.previousRule.findIgnoreReason(mutatorName, line);
+  }
+}
+
+class RestoreRule extends IgnoreRule {
+  constructor(
+    mutatorNames: string[],
+    line: number | undefined,
+    previousRule: Rule,
+  ) {
+    super(mutatorNames, line, undefined, previousRule);
+  }
+}
+
+const rootRule: Rule = {
+  findIgnoreReason() {
+    return undefined;
+  },
+};
+
+/**
+ * Responsible for the bookkeeping of "// Stryker" directives like "disable" and "restore".
+ */
+export class DirectiveBookkeeper {
+  // https://regex101.com/r/nWLLLm/1
+  private readonly strykerCommentDirectiveRegex =
+    /^\s?Stryker (disable|restore)(?: (next-line))? ([a-zA-Z, ]+)(?::(.+)?)?/;
+
+  private currentIgnoreRule = rootRule;
+  private readonly allMutatorNames: string[];
+
+  constructor(
+    private readonly logger: Logger,
+    private readonly allMutators: NodeMutator[],
+    private readonly originFileName: string,
+  ) {
+    this.allMutatorNames = this.allMutators.map((x) => x.name.toLowerCase());
+  }
+
+  public processStrykerDirectives({ loc, leadingComments }: types.Node): void {
+    leadingComments
+      ?.map((comment) => ({
+        comment,
+        matchResult: this.strykerCommentDirectiveRegex.exec(comment.value) as
+          | [
+              fullMatch: string,
+              directiveType: string,
+              scope: string | undefined,
+              mutators: string,
+              reason: string | undefined,
+            ]
+          | null,
+      }))
+      .filter(({ matchResult }) => notEmpty(matchResult))
+      .forEach(({ comment, matchResult }) => {
+        const [, directiveType, scope, mutators, optionalReason] = matchResult!;
+        let mutatorNames = mutators.split(',').map((mutator) => mutator.trim());
+        this.warnAboutUnusedDirective(
+          mutatorNames,
+          directiveType,
+          scope,
+          comment,
+        );
+        mutatorNames = mutatorNames.map((mutator) => mutator.toLowerCase());
+        const reason = (optionalReason ?? DEFAULT_REASON).trim();
+        switch (directiveType) {
+          case 'disable':
+            switch (scope) {
+              case 'next-line':
+                this.currentIgnoreRule = new IgnoreRule(
+                  mutatorNames,
+                  loc!.start.line,
+                  reason,
+                  this.currentIgnoreRule,
+                );
+                break;
+              default:
+                this.currentIgnoreRule = new IgnoreRule(
+                  mutatorNames,
+                  undefined,
+                  reason,
+                  this.currentIgnoreRule,
+                );
+                break;
+            }
+            break;
+          case 'restore':
+            switch (scope) {
+              case 'next-line':
+                this.currentIgnoreRule = new RestoreRule(
+                  mutatorNames,
+                  loc!.start.line,
+                  this.currentIgnoreRule,
+                );
+                break;
+              default:
+                this.currentIgnoreRule = new RestoreRule(
+                  mutatorNames,
+                  undefined,
+                  this.currentIgnoreRule,
+                );
+                break;
+            }
+            break;
+        }
+      });
+  }
+
+  public findIgnoreReason(
+    line: number,
+    mutatorName: string,
+  ): string | undefined {
+    mutatorName = mutatorName.toLowerCase();
+    return this.currentIgnoreRule.findIgnoreReason(mutatorName, line);
+  }
+
+  private warnAboutUnusedDirective(
+    mutators: string[],
+    directiveType: string,
+    scope: string | undefined,
+    comment: types.Comment,
+  ) {
+    for (const mutator of mutators) {
+      if (mutator === WILDCARD) continue;
+      if (!this.allMutatorNames.includes(mutator.toLowerCase())) {
+        this.logger.warn(
+          // Scope can be global and therefore undefined
+          `Unused 'Stryker ${
+            scope ? directiveType + ' ' + scope : directiveType
+          }' directive. Mutator with name '${mutator}' not found. Directive found at: ${this.originFileName}:${comment.loc!.start.line}:${
+            comment.loc!.start.column
+          }.`,
+        );
+      }
+    }
+  }
+}

package/src/transformers/html-transformer.ts

@@ -0,0 +1,13 @@
+import { AstFormat } from '../syntax/index.js';
+
+import { AstTransformer } from './index.js';
+
+export const transformHtml: AstTransformer<AstFormat.Html> = (
+  { root },
+  mutantCollector,
+  context,
+) => {
+  root.scripts.forEach((ast) => {
+    context.transform(ast, mutantCollector, context);
+  });
+};

package/src/transformers/ignorer-bookkeeper.ts

@@ -0,0 +1,41 @@
+import type { types, NodePath as BabelNodePath } from '@babel/core';
+
+import type { Ignorer } from '@stryker-mutator/api/ignore';
+
+declare module '@stryker-mutator/api/ignore' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface NodePath extends BabelNodePath {}
+}
+
+/**
+ * Responsible for keeping track of the active ignore message and node using the configured ignore-plugins.
+ */
+export class IgnorerBookkeeper {
+  private readonly ignorers;
+  private activeIgnored?: { node: types.Node; message: string };
+
+  public get currentIgnoreMessage(): string | undefined {
+    return this.activeIgnored?.message;
+  }
+
+  constructor(ignorers: Ignorer[]) {
+    this.ignorers = ignorers;
+  }
+
+  public enterNode(path: BabelNodePath): void {
+    if (!this.activeIgnored) {
+      this.ignorers.forEach((ignorer) => {
+        const message = ignorer.shouldIgnore(path);
+        if (message) {
+          this.activeIgnored = { node: path.node, message };
+        }
+      });
+    }
+  }
+
+  public leaveNode(path: BabelNodePath): void {
+    if (this.activeIgnored?.node === path.node) {
+      this.activeIgnored = undefined;
+    }
+  }
+}

package/src/transformers/index.ts

@@ -0,0 +1,6 @@
+import { MutantCollector } from './mutant-collector.js';
+import { TransformerOptions } from './transformer-options.js';
+
+export type { TransformerOptions };
+export { MutantCollector };
+export * from './transformer.js';

package/src/transformers/mutant-collector.ts

@@ -0,0 +1,44 @@
+import type { types } from '@babel/core';
+import { Position } from '@stryker-mutator/api/core';
+
+import { Mutant, Mutable } from '../mutant.js';
+
+export class MutantCollector {
+  private readonly _mutants: Mutant[] = [];
+
+  public get mutants(): readonly Mutant[] {
+    return this._mutants;
+  }
+
+  /**
+   * Adds mutants to the internal mutant list.
+   * @param fileName file name that houses the mutant
+   * @param original The node to mutate
+   * @param mutables the named node mutation to be added
+   * @param contextPath the context where these mutants are found and should be placed as close by as possible
+   * @param offset offset of mutant nodes
+   * @returns The mutant (for testability)
+   */
+  public collect(
+    fileName: string,
+    original: types.Node,
+    mutable: Mutable,
+    offset: Position = { line: 0, column: 0 },
+  ): Mutant {
+    const mutant = new Mutant(
+      this._mutants.length.toString(),
+      fileName,
+      original,
+      mutable,
+      offset,
+    );
+    this._mutants.push(mutant);
+    return mutant;
+  }
+
+  public hasPlacedMutants(fileName: string): boolean {
+    return this.mutants.some(
+      (mutant) => mutant.fileName === fileName && !mutant.ignoreReason,
+    );
+  }
+}

package/src/transformers/svelte-transformer.ts

@@ -0,0 +1,57 @@
+import { notEmpty } from '@stryker-mutator/util';
+
+import { types } from '@babel/core';
+
+import { AstFormat } from '../syntax/index.js';
+import { placeHeader } from '../util/syntax-helpers.js';
+
+import { AstTransformer } from './transformer.js';
+
+const moduleScriptStart = '<script context="module">\n';
+const moduleScript = `${moduleScriptStart}\n</script>\n`;
+
+export const transformSvelte: AstTransformer<AstFormat.Svelte> = (
+  svelte,
+  mutantCollector,
+  context,
+) => {
+  const { root, originFileName } = svelte;
+  [root.moduleScript, ...root.additionalScripts]
+    .filter(notEmpty)
+    .forEach((script) => {
+      context.transform(script.ast, mutantCollector, {
+        ...context,
+        options: {
+          ...context.options,
+          noHeader: true,
+        },
+      });
+    });
+
+  if (mutantCollector.hasPlacedMutants(originFileName)) {
+    // We need to place the instrumentation header inside the `<script context="module">` script
+    // If there already is a module script, place it there. If not, we need to add it.
+
+    if (!root.moduleScript) {
+      root.moduleScript = {
+        ast: {
+          format: AstFormat.JS,
+          root: types.file(types.program([])),
+          rawContent: '',
+          originFileName,
+        },
+        range: {
+          start: moduleScriptStart.length,
+          end: moduleScriptStart.length,
+        },
+        isExpression: false,
+      };
+      svelte.rawContent = `${moduleScript}${svelte.rawContent}`;
+      svelte.root.additionalScripts.forEach((script) => {
+        script.range.start += moduleScript.length;
+        script.range.end += moduleScript.length;
+      });
+    }
+    placeHeader(root.moduleScript.ast.root);
+  }
+};

package/src/transformers/transformer-options.ts

@@ -0,0 +1,7 @@
+import { Ignorer } from '@stryker-mutator/api/ignore';
+
+import { MutatorOptions } from '../mutators/index.js';
+
+export interface TransformerOptions extends MutatorOptions {
+  ignorers: Ignorer[];
+}

package/src/transformers/transformer.ts

@@ -0,0 +1,54 @@
+import { MutateDescription } from '@stryker-mutator/api/core';
+import { I } from '@stryker-mutator/util';
+import { Logger } from '@stryker-mutator/api/logging';
+
+import { Ast, AstByFormat, AstFormat } from '../syntax/index.js';
+
+import { TransformerOptions } from './transformer-options.js';
+import { transformBabel } from './babel-transformer.js';
+import { transformHtml } from './html-transformer.js';
+import { MutantCollector } from './mutant-collector.js';
+import { transformSvelte } from './svelte-transformer.js';
+
+/**
+ * Transform the AST by generating mutants and placing them in the AST.
+ * Supports all AST formats supported by Stryker.
+ * @param ast The Abstract Syntax Tree
+ * @param mutantCollector the mutant collector that will be used to register and administer mutants
+ * @param transformerContext the options used during transforming
+ */
+export function transform(
+  ast: Ast,
+  mutantCollector: I<MutantCollector>,
+  transformerContext: Omit<TransformerContext, 'transform'>,
+): void {
+  const context: TransformerContext = {
+    ...transformerContext,
+    transform,
+  };
+  switch (ast.format) {
+    case AstFormat.Html:
+      transformHtml(ast, mutantCollector, context);
+      break;
+    case AstFormat.JS:
+    case AstFormat.TS:
+    case AstFormat.Tsx:
+      transformBabel(ast, mutantCollector, context);
+      break;
+    case AstFormat.Svelte:
+      transformSvelte(ast, mutantCollector, context);
+  }
+}
+
+export type AstTransformer<T extends AstFormat> = (
+  ast: AstByFormat[T],
+  mutantCollector: I<MutantCollector>,
+  context: TransformerContext,
+) => void;
+
+export interface TransformerContext {
+  transform: AstTransformer<AstFormat>;
+  options: TransformerOptions;
+  mutateDescription: MutateDescription;
+  logger: Logger;
+}

package/src/util/binary-operator.ts

@@ -0,0 +1,23 @@
+export type BinaryOperator =
+  | '-'
+  | '!='
+  | '!=='
+  | '*'
+  | '**'
+  | '/'
+  | '&'
+  | '%'
+  | '^'
+  | '+'
+  | '<'
+  | '<<'
+  | '<='
+  | '=='
+  | '==='
+  | '>'
+  | '>='
+  | '>>'
+  | '>>>'
+  | '|'
+  | 'in'
+  | 'instanceof';

package/src/util/index.ts

@@ -0,0 +1,3 @@
+export * from './syntax-helpers.js';
+export * from './binary-operator.js';
+export * from './position-converter.js';