@systemfsoftware/stryker-js-instrumenter 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,246 @@
+import { BaseContext, Injector, PluginKind } from "@systemfsoftware/stryker-js-plugin-api/plugin";
+import { FileDescription, Mutant, MutateDescription, Position } from "@systemfsoftware/stryker-js-plugin-api/core";
+import { types } from "@babel/core";
+import { I } from "@systemfsoftware/stryker-js-util";
+import { Ignorer } from "@systemfsoftware/stryker-js-plugin-api/ignore";
+import { Logger } from "@systemfsoftware/stryker-js-plugin-api/logging";
+//#region src/instrumenter-tokens.d.ts
+declare const instrumenterTokens: Readonly<{
+  readonly createParser: 'instrumenterCreateParser';
+  readonly print: 'instrumenterPrint';
+  readonly transform: 'instrumenterTransform';
+}>;
+//#endregion
+//#region src/syntax/index.d.ts
+declare enum AstFormat {
+  Html = "html",
+  JS = "js",
+  TS = "ts",
+  Tsx = "tsx",
+  Svelte = "svelte"
+}
+interface AstByFormat {
+  [AstFormat.Html]: HtmlAst;
+  [AstFormat.JS]: JSAst;
+  [AstFormat.TS]: TSAst;
+  [AstFormat.Tsx]: TsxAst;
+  [AstFormat.Svelte]: SvelteAst;
+}
+type Ast = HtmlAst | JSAst | SvelteAst | TSAst | TsxAst;
+type ScriptAst = JSAst | TSAst | TsxAst;
+interface BaseAst {
+  originFileName: string;
+  rawContent: string;
+  root: Ast['root'];
+  offset?: Position;
+}
+/**
+ * Represents an Html AST.
+ */
+interface HtmlAst extends BaseAst {
+  format: AstFormat.Html;
+  root: HtmlRootNode;
+}
+/**
+ * Represents a TS AST
+ */
+interface JSAst extends BaseAst {
+  format: AstFormat.JS;
+  root: types.File;
+}
+/**
+ * Represents a TS AST
+ */
+interface TSAst extends BaseAst {
+  format: AstFormat.TS;
+  root: types.File;
+}
+/**
+ * Represents a TS AST
+ */
+interface TsxAst extends BaseAst {
+  format: AstFormat.Tsx;
+  root: types.File;
+}
+/**
+ * Represents a Svelte AST
+ */
+interface SvelteAst extends BaseAst {
+  format: AstFormat.Svelte;
+  root: SvelteRootNode;
+}
+/**
+ * Represents the root node of an HTML AST
+ * We've taken a shortcut here, instead of representing the entire AST, we're only representing the script tags.
+ * We might need to expand this in the future if we would ever want to support mutating the actual HTML (rather than only the JS/TS)
+ */
+interface HtmlRootNode {
+  scripts: ScriptAst[];
+}
+interface SvelteRootNode {
+  moduleScript?: TemplateScript;
+  additionalScripts: TemplateScript[];
+}
+/**
+ * Represents a svelte script or binding expression
+ * We've taken a shortcut here, instead of representing the entire AST, we're only representing the script tags and expression bindings.
+ */
+interface TemplateScript {
+  ast: ScriptAst;
+  range: Range;
+  isExpression: boolean;
+}
+interface Range {
+  start: number;
+  end: number;
+}
+//#endregion
+//#region src/parsers/parser-options.d.ts
+interface ParserOptions {
+  plugins: unknown[] | null;
+}
+//#endregion
+//#region src/parsers/create-parser.d.ts
+declare function createParser(parserOptions: ParserOptions): {
+  <T extends AstFormat>(code: string, fileName: string, formatOverride: T): Promise<AstByFormat[T]>;
+  (code: string, fileName: string, formatOverride?: AstFormat): Promise<Ast>;
+};
+//#endregion
+//#region src/printers/index.d.ts
+declare function print(file: Ast): string;
+//#endregion
+//#region src/mutant.d.ts
+interface Mutable {
+  mutatorName: string;
+  ignoreReason?: string | undefined;
+  replacement: types.Node;
+}
+declare class Mutant$1 implements Mutable {
+  readonly id: string;
+  readonly fileName: string;
+  readonly original: types.Node;
+  readonly offset: Position;
+  readonly replacementCode: string;
+  readonly replacement: types.Node;
+  readonly mutatorName: string;
+  readonly ignoreReason: string | undefined;
+  constructor(id: string, fileName: string, original: types.Node, specs: Mutable, offset?: Position);
+  toApiMutant(): Mutant;
+  /**
+   * Applies the mutant in (a copy of) the AST, without changing provided AST.
+   * Can the tree itself (in which case the replacement is returned),
+   * or can be nested in the given tree.
+   *
+   * Returns a plain node rather than the argument's own type: whether the
+   * replacement fits a given position is the placer's claim, and the placer
+   * checks it with a Babel predicate. A generic return would have to assert it
+   * here, where nothing can check it.
+   * @param originalTree The original node, which will be treated as readonly
+   */
+  applied(originalTree: types.Node): types.Node;
+}
+//#endregion
+//#region src/transformers/mutant-collector.d.ts
+declare class MutantCollector {
+  private readonly _mutants;
+  get mutants(): readonly Mutant$1[];
+  /**
+   * 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)
+   */
+  collect(fileName: string, original: types.Node, mutable: Mutable, offset?: Position): Mutant$1;
+  hasPlacedMutants(fileName: string): boolean;
+}
+//#endregion
+//#region src/mutators/mutator-options.d.ts
+interface MutatorOptions {
+  excludedMutations: string[];
+  noHeader?: boolean;
+}
+//#endregion
+//#region src/transformers/transformer-options.d.ts
+interface TransformerOptions extends MutatorOptions {
+  ignorers: Ignorer[];
+}
+//#endregion
+//#region src/transformers/transformer.d.ts
+/**
+ * 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
+ */
+declare function transform(ast: Ast, mutantCollector: I<MutantCollector>, transformerContext: Omit<TransformerContext, 'transform'>): void;
+type AstTransformer<T extends AstFormat> = (ast: AstByFormat[T], mutantCollector: I<MutantCollector>, context: TransformerContext) => void;
+interface TransformerContext {
+  transform: AstTransformer<AstFormat>;
+  options: TransformerOptions;
+  mutateDescription: MutateDescription;
+  logger: Logger;
+}
+//#endregion
+//#region src/create-instrumenter.d.ts
+interface InstrumenterContext extends BaseContext {
+  [instrumenterTokens.createParser]: typeof createParser;
+  [instrumenterTokens.print]: typeof print;
+  [instrumenterTokens.transform]: typeof transform;
+}
+declare function createInstrumenter(injector: Injector<BaseContext>): Instrumenter;
+declare namespace createInstrumenter {
+  var inject: ["$injector"];
+}
+//#endregion
+//#region src/file.d.ts
+interface File extends FileDescription {
+  name: string;
+  content: string;
+}
+//#endregion
+//#region src/disable-type-checks.d.ts
+/**
+ * Disables TypeScript type checking for a single file by inserting `// @ts-nocheck` commands.
+ * It also does this for *.js files, as they can be type checked by typescript as well.
+ * Other file types are silently ignored
+ *
+ * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#-ts-nocheck-in-typescript-files
+ */
+declare function disableTypeChecks(file: File, options: ParserOptions): Promise<File>;
+//#endregion
+//#region src/frameworks/index.d.ts
+declare const strykerPlugins: import("@systemfsoftware/stryker-js-plugin-api/plugin").ClassPlugin<PluginKind.Ignore, []>[];
+declare const frameworkPluginsFileUrl: string;
+//#endregion
+//#region src/instrument-result.d.ts
+interface InstrumentResult {
+  files: readonly File[];
+  mutants: readonly Mutant[];
+}
+//#endregion
+//#region src/instrumenter-options.d.ts
+interface InstrumenterOptions extends ParserOptions, TransformerOptions {}
+//#endregion
+//#region src/instrumenter.d.ts
+/**
+ * The instrumenter is responsible for
+ * * Generating mutants based on source files
+ * * Instrumenting the source code with the mutants placed in `mutant switches`.
+ * * Adding mutant coverage expressions in the source code.
+ * @see https://github.com/stryker-mutator/stryker-js/issues/1514
+ */
+declare class Instrumenter {
+  private readonly logger;
+  private readonly _createParser;
+  private readonly _print;
+  private readonly _transform;
+  static inject: ["logger", "instrumenterCreateParser", "instrumenterPrint", "instrumenterTransform"];
+  constructor(logger: Logger, _createParser?: typeof createParser, _print?: typeof print, _transform?: typeof transform);
+  instrument(files: readonly File[], options: InstrumenterOptions): Promise<InstrumentResult>;
+}
+//#endregion
+export { File, InstrumentResult, Instrumenter, InstrumenterContext, InstrumenterOptions, type ParserOptions, createInstrumenter, disableTypeChecks, frameworkPluginsFileUrl, strykerPlugins };