@t09tanaka/test-gates 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -92,17 +92,17 @@ function allowanceProblems(entry) {
   }
   return problems;
 }
-function validateEquivalentMutants(gatePath, value) {
+function validateEquivalentMutants(gatePath, value, field = "equivalentMutants") {
   if (value === void 0) {
     return [];
   }
   if (!Array.isArray(value)) {
-    return [{ file: MANIFEST_FILE, message: `${gatePath}: equivalentMutants must be an array` }];
+    return [{ file: MANIFEST_FILE, message: `${gatePath}: ${field} must be an array` }];
   }
   return value.flatMap(
     (entry, index) => allowanceProblems(entry).map((problem) => ({
       file: MANIFEST_FILE,
-      message: `${gatePath}: equivalentMutants[${index}]${problem}`
+      message: `${gatePath}: ${field}[${index}]${problem}`
     }))
   );
 }
@@ -185,6 +185,9 @@ function parseManifest(text) {
   }
   for (const gate of gates) {
     violations.push(...validateEquivalentMutants(gate.path, gate.equivalentMutants));
+    violations.push(
+      ...validateEquivalentMutants(gate.path, gate.expectedTimeouts, "expectedTimeouts")
+    );
   }
   return { gates, candidates, settings: raw.settings, violations };
 }
@@ -233,8 +236,13 @@ var DEFAULT_FORBIDDEN_SOURCE = [
   {
     pattern: `^\\s*(['"])use (client|server)\\1`,
     reason: "'use client' / 'use server' directive (not a pure module)"
+  },
+  {
+    pattern: "\\bprocess\\??\\.env\\b",
+    reason: "reads process.env (not a pure module). Take the value as an argument"
   }
 ];
+var DEFAULT_MAX_TIMEOUTS = 0;
 var SettingsError = class extends Error {
 };
 function isRecord2(value) {
@@ -334,7 +342,9 @@ function resolveSettings(raw) {
       "gateCommand",
       "selfcheck",
       "stryker",
-      "lcov"
+      "lcov",
+      "imports",
+      "mutation"
     ],
     "settings"
   );
@@ -435,6 +445,42 @@ function resolveSettings(raw) {
       "settings.selfcheck.failurePattern"
     );
   }
+  const importsSection = section(settings.imports, ["mode", "allow"], "settings.imports");
+  if (importsSection.mode !== void 0 && importsSection.mode !== "blocklist" && importsSection.mode !== "allowlist") {
+    throw new SettingsError('settings.imports.mode: must be "blocklist" or "allowlist"');
+  }
+  const importAllowRaw = importsSection.allow ?? [];
+  if (!Array.isArray(importAllowRaw)) {
+    throw new SettingsError("settings.imports.allow: must be an array");
+  }
+  const importAllow = importAllowRaw.map((item, index) => {
+    const at = `settings.imports.allow[${index}]`;
+    if (typeof item === "string" && item !== "") {
+      return { module: item };
+    }
+    if (isRecord2(item) && typeof item.pattern === "string" && item.pattern !== "") {
+      rejectUnknownKeys(item, ["pattern", "flags"], at);
+      if (item.flags !== void 0 && typeof item.flags !== "string") {
+        throw new SettingsError(`${at}.flags: must be a string`);
+      }
+      return { regex: compile(item.pattern, item.flags, at) };
+    }
+    if (isRecord2(item) && typeof item.module === "string" && item.module !== "") {
+      rejectUnknownKeys(item, ["module", "names"], at);
+      const names = stringArray(item.names, `${at}.names`);
+      if (names.length === 0) {
+        throw new SettingsError(`${at}.names: must list at least one name`);
+      }
+      return { module: item.module, names };
+    }
+    throw new SettingsError(
+      `${at}: must be a package name, { pattern, flags? } or { module, names }`
+    );
+  });
+  const mutation = section(settings.mutation, ["maxTimeouts"], "settings.mutation");
+  if (mutation.maxTimeouts !== void 0 && !(Number.isInteger(mutation.maxTimeouts) && mutation.maxTimeouts >= 0)) {
+    throw new SettingsError("settings.mutation.maxTimeouts: must be an integer >= 0");
+  }
   const stryker = section(settings.stryker, ["configFile", "reportFile"], "settings.stryker");
   const lcov = section(settings.lcov, ["file", "summaryExclude"], "settings.lcov");
   return {
@@ -456,6 +502,9 @@ function resolveSettings(raw) {
     selfcheckFailurePattern,
     strykerConfigFile: optionalString(stryker.configFile, "settings.stryker.configFile"),
     strykerReportFile: optionalString(stryker.reportFile, "settings.stryker.reportFile") ?? DEFAULT_REPORT_FILE,
+    importMode: importsSection.mode ?? "blocklist",
+    importAllow,
+    maxTimeouts: mutation.maxTimeouts ?? DEFAULT_MAX_TIMEOUTS,
     lcovFile: optionalString(lcov.file, "settings.lcov.file"),
     lcovSummaryExclude: lcov.summaryExclude === void 0 ? [] : stringArray(lcov.summaryExclude, "settings.lcov.summaryExclude").map(
       (pattern, index) => compile(pattern, void 0, `settings.lcov.summaryExclude[${index}]`)
@@ -650,6 +699,70 @@ function parseImports(source) {
   }
   return found.sort((a, b) => a.line - b.line);
 }
+var COMPUTED_CALL_IMPORT = /(?<![.\w$])(?:require|import)\s*\(\s*(?!['"`\s)])/g;
+function findUncheckableImports(source) {
+  return [...source.matchAll(COMPUTED_CALL_IMPORT)].map((match) => lineAt(source, match.index));
+}
+
+// src/core/import-policy.ts
+var SCRIPT_EXTENSION = /\.[cm]?[jt]sx?$/;
+function isProjectImport(specifier, aliases) {
+  return specifier.startsWith(".") || aliases.some((alias) => specifier.startsWith(alias.prefix));
+}
+function resolveSpecifier(specifier, fromFile, aliases) {
+  let joined = null;
+  if (specifier.startsWith(".")) {
+    const slash = fromFile.lastIndexOf("/");
+    joined = slash === -1 ? specifier : `${fromFile.slice(0, slash)}/${specifier}`;
+  } else {
+    const alias = aliases.find((candidate) => specifier.startsWith(candidate.prefix));
+    if (alias) {
+      joined = alias.target + specifier.slice(alias.prefix.length);
+    }
+  }
+  if (joined === null) {
+    return null;
+  }
+  const segments = [];
+  for (const segment of joined.split("/")) {
+    if (segment === "..") {
+      segments.pop();
+    } else if (segment !== "." && segment !== "") {
+      segments.push(segment);
+    }
+  }
+  return segments.join("/").replace(SCRIPT_EXTENSION, "");
+}
+function matches(rule, specifier) {
+  if (rule.regex) {
+    return rule.regex.test(specifier);
+  }
+  return specifier === rule.module || specifier.startsWith(`${rule.module}/`);
+}
+function judgePackageImport(ref, allow) {
+  const rules = allow.filter((rule) => matches(rule, ref.module));
+  if (rules.length === 0) {
+    return `runtime import of "${ref.module}" is not in settings.imports.allow (allowlist mode allows relative imports, import aliases and listed packages only)`;
+  }
+  if (rules.some((rule) => rule.names === void 0)) {
+    return null;
+  }
+  const allowedNames = rules.flatMap((rule) => rule.names);
+  if (ref.whole) {
+    return `only ${allowedNames.join(", ")} may be imported from "${ref.module}", as named imports (settings.imports.allow)`;
+  }
+  const extra = ref.names.filter((name) => !allowedNames.includes(name));
+  return extra.length === 0 ? null : `runtime import of ${extra.join(", ")} from "${ref.module}" is not in settings.imports.allow (allowed: ${allowedNames.join(", ")})`;
+}
+function judgeProjectImport(target, impurePaths, gateExtensions) {
+  const candidates = [target, ...gateExtensions.map((extension) => target + extension)];
+  for (const rule of impurePaths) {
+    if (candidates.some((candidate) => rule.regex.test(candidate))) {
+      return rule.reason;
+    }
+  }
+  return null;
+}
 
 // src/core/scan.ts
 var IGNORE_DIRECTIVE = /\b(istanbul|c8|v8)\s+ignore\b/;
@@ -667,7 +780,7 @@ var DISABLED_TESTS = [
   }
 ];
 var MODULE_MOCK = /\b(?:jest|vi)\s*\.\s*(?:mock|doMock|unstable_mockModule|setMock)\s*\(\s*(?:import\s*\(\s*)?(['"`])([^'"`\n]+)\1/g;
-var SCRIPT_EXTENSION = /\.[cm]?[jt]sx?$/;
+var SCRIPT_EXTENSION2 = /\.[cm]?[jt]sx?$/;
 function eachLine(source, visit) {
   source.split("\n").forEach((line, index) => visit(line, index + 1));
 }
@@ -704,6 +817,7 @@ function scanGateSource(gatePath, source, settings) {
     if (imported.typeOnly) {
       continue;
     }
+    const before = violations.length;
     if (!settings.allowedImports.some((regex) => regex.test(imported.module))) {
       for (const rule of settings.impureImports) {
         if (rule.regex.test(imported.module)) {
@@ -730,34 +844,31 @@ function scanGateSource(gatePath, source, settings) {
         });
       }
     }
-  }
-  return violations.sort((a, b) => a.line - b.line);
-}
-function resolveSpecifier(specifier, fromFile, aliases) {
-  let joined = null;
-  if (specifier.startsWith(".")) {
-    const directory = fromFile.includes("/") ? fromFile.slice(0, fromFile.lastIndexOf("/")) : "";
-    joined = directory === "" ? specifier : `${directory}/${specifier}`;
-  } else {
-    for (const alias of aliases) {
-      if (specifier.startsWith(alias.prefix)) {
-        joined = alias.target + specifier.slice(alias.prefix.length);
-        break;
+    if (settings.importMode === "allowlist" && violations.length === before) {
+      const reason = isProjectImport(imported.module, settings.importAliases) ? judgeProjectImport(
+        resolveSpecifier(imported.module, gatePath, settings.importAliases),
+        settings.impurePaths,
+        settings.gateExtensions
+      ) : judgePackageImport(imported, settings.importAllow);
+      if (reason !== null) {
+        violations.push({
+          file: gatePath,
+          line: imported.line,
+          message: isProjectImport(imported.module, settings.importAliases) ? `runtime import of "${imported.module}" (${reason})` : reason
+        });
       }
     }
   }
-  if (joined === null) {
-    return null;
-  }
-  const segments = [];
-  for (const segment of joined.split("/")) {
-    if (segment === "..") {
-      segments.pop();
-    } else if (segment !== "." && segment !== "") {
-      segments.push(segment);
+  if (settings.importMode === "allowlist") {
+    for (const line of findUncheckableImports(source)) {
+      violations.push({
+        file: gatePath,
+        line,
+        message: "require() / import() with a computed specifier cannot be checked (allowlist mode)"
+      });
     }
   }
-  return segments.join("/").replace(SCRIPT_EXTENSION, "");
+  return violations.sort((a, b) => a.line - b.line);
 }
 function scanSpecSource(gatePath, specPath, source, settings) {
   const violations = [];
@@ -775,7 +886,7 @@ function scanSpecSource(gatePath, specPath, source, settings) {
       }
     }
   });
-  const gateModule = gatePath.replace(SCRIPT_EXTENSION, "");
+  const gateModule = gatePath.replace(SCRIPT_EXTENSION2, "");
   const gateDirectory = gateModule.replace(/\/index$/, "");
   for (const match of source.matchAll(MODULE_MOCK)) {
     const specifier = match[2];
@@ -812,6 +923,21 @@ function scanStrykerConfig(configPath, source) {
   return violations;
 }
 
+// src/core/vitest-coverage.ts
+function vitestCoverageViolation(input) {
+  if (input.vitestVersion === null || input.vitestVersion === "") {
+    return null;
+  }
+  const major = Number(input.vitestVersion.split(".")[0]);
+  if (!Number.isInteger(major) || major >= 4) {
+    return null;
+  }
+  if (/\bistanbul\b/.test(input.configSource) || /\bexperimentalAstAwareRemapping\s*:\s*true\b/.test(input.configSource)) {
+    return null;
+  }
+  return `Vitest ${input.vitestVersion} with the v8 coverage provider does not count the skipped side of an "if" without "else", so a gate can show 100% branches with that side untested. Use coverageProvider: 'istanbul' (needs @vitest/coverage-istanbul), set coverage.experimentalAstAwareRemapping: true, or move to Vitest 4`;
+}
+
 // src/commands/check.ts
 var STRYKER_CONFIG_NAMES = [
   "stryker.gates.config.mjs",
@@ -902,8 +1028,40 @@ function checkGates(manifest) {
       violations.push(...scanStrykerConfig(strykerConfig, readText(dir, strykerConfig)));
     }
   }
+  violations.push(...checkVitestCoverage(manifest));
   return violations;
 }
+var VITEST_GATE_CONFIGS = ["ts", "mts", "cts", "js", "mjs", "cjs"].map(
+  (extension) => `vitest.gates.config.${extension}`
+);
+function installedVitestVersion(startDir) {
+  let current = startDir;
+  for (; ; ) {
+    try {
+      const pkg = JSON.parse(
+        import_node_fs3.default.readFileSync(import_node_path3.default.join(current, "node_modules", "vitest", "package.json"), "utf8")
+      );
+      return typeof pkg.version === "string" ? pkg.version : null;
+    } catch {
+      const parent = import_node_path3.default.dirname(current);
+      if (parent === current) {
+        return null;
+      }
+      current = parent;
+    }
+  }
+}
+function checkVitestCoverage(manifest) {
+  const config = VITEST_GATE_CONFIGS.find((name) => import_node_fs3.default.existsSync(import_node_path3.default.join(manifest.dir, name)));
+  if (!config) {
+    return [];
+  }
+  const message = vitestCoverageViolation({
+    vitestVersion: installedVitestVersion(manifest.dir),
+    configSource: readText(manifest.dir, config)
+  });
+  return message === null ? [] : [{ file: config, message }];
+}
 
 // src/core/mutation-result.ts
 var DETECTED = /* @__PURE__ */ new Set(["Killed", "Timeout"]);
@@ -938,6 +1096,27 @@ function sliceByLocation(source, location) {
 function keyOf(mutator, original, replacement) {
   return JSON.stringify([mutator, normalizeCode(original), normalizeCode(replacement)]);
 }
+function describeMutant(file, entry) {
+  const { mutant } = entry;
+  return {
+    file,
+    line: mutant.location.start.line,
+    column: mutant.location.start.column,
+    status: mutant.status,
+    mutator: mutant.mutatorName,
+    original: normalizeCode(entry.original),
+    replacement: normalizeCode(entry.replacement),
+    occurrence: entry.occurrence,
+    sameKeyCount: entry.sameKeyCount,
+    allowance: {
+      mutator: mutant.mutatorName,
+      original: normalizeCode(entry.original),
+      replacement: normalizeCode(entry.replacement),
+      ...entry.sameKeyCount > 1 ? { occurrence: entry.occurrence } : {},
+      reason: ""
+    }
+  };
+}
 function describeAllowance(entry) {
   const occurrence = entry.occurrence === void 0 ? "" : ` / occurrence ${entry.occurrence}`;
   return `${entry.mutator} / ${normalizeCode(entry.original)} \u2192 ${normalizeCode(entry.replacement)}${occurrence}`;
@@ -945,13 +1124,15 @@ function describeAllowance(entry) {
 function judgeMutationReport(input) {
   const violations = [];
   const survivors = [];
+  const unexpectedTimeouts = [];
   const summary = {
     total: 0,
     detected: 0,
     timeout: 0,
     allowed: 0,
     notEvaluable: 0,
-    unallowed: 0
+    unallowed: 0,
+    expectedTimeout: 0
   };
   const files = /* @__PURE__ */ new Map();
   for (const [file, result] of Object.entries(input.report.files ?? {})) {
@@ -961,7 +1142,9 @@ function judgeMutationReport(input) {
     const gatePath = normalizePath(gate.path);
     const shapeViolations = validateEquivalentMutants(gate.path, gate.equivalentMutants);
     violations.push(...shapeViolations);
-    const allowances = Array.isArray(gate.equivalentMutants) ? gate.equivalentMutants : [];
+    violations.push(
+      ...validateEquivalentMutants(gate.path, gate.expectedTimeouts, "expectedTimeouts")
+    );
     const result = files.get(gatePath);
     if (!result || !Array.isArray(result.mutants) || result.mutants.length === 0) {
       violations.push({
@@ -1025,38 +1208,53 @@ function judgeMutationReport(input) {
     if (!locationsValid) {
       continue;
     }
-    const allowed = /* @__PURE__ */ new Set();
-    allowances.forEach((allowance, index) => {
-      if (!isUsableEquivalentMutant(allowance)) {
-        return;
+    const claim = (field, entries, noun, accept) => {
+      const claimed = /* @__PURE__ */ new Set();
+      if (!Array.isArray(entries)) {
+        return claimed;
       }
-      const at = `${gate.path}: equivalentMutants[${index}] (${describeAllowance(allowance)})`;
-      const group = byKey.get(keyOf(allowance.mutator, allowance.original, allowance.replacement)) ?? [];
-      if (allowance.occurrence === void 0 && group.length > 1) {
-        violations.push({
-          file: MANIFEST_FILE,
-          message: `${at}: matches ${group.length} mutants in the file. Add "occurrence" (1-based) to pick one`
-        });
-        return;
-      }
-      const target = group[(allowance.occurrence ?? 1) - 1];
-      if (!target || !SURVIVED.has(target.mutant.status)) {
-        const why = target ? `the mutant is now ${target.mutant.status}` : "no such mutant in this run";
-        violations.push({
-          file: MANIFEST_FILE,
-          message: `${at}: stale allowance (${why}). Remove it`
-        });
-        return;
-      }
-      if (allowed.has(target)) {
-        violations.push({
-          file: MANIFEST_FILE,
-          message: `${at}: another allowance already covers this mutant`
-        });
-        return;
-      }
-      allowed.add(target);
-    });
+      entries.forEach((entry, index) => {
+        if (!isUsableEquivalentMutant(entry)) {
+          return;
+        }
+        const at = `${gate.path}: ${field}[${index}] (${describeAllowance(entry)})`;
+        const group = byKey.get(keyOf(entry.mutator, entry.original, entry.replacement)) ?? [];
+        if (entry.occurrence === void 0 && group.length > 1) {
+          violations.push({
+            file: MANIFEST_FILE,
+            message: `${at}: matches ${group.length} mutants in the file. Add "occurrence" (1-based) to pick one`
+          });
+          return;
+        }
+        const target = group[(entry.occurrence ?? 1) - 1];
+        const refusal = target ? accept(target.mutant.status) : `stale ${noun} (no such mutant in this run). Remove it`;
+        if (!target || refusal !== null) {
+          violations.push({ file: MANIFEST_FILE, message: `${at}: ${refusal}` });
+          return;
+        }
+        if (claimed.has(target)) {
+          violations.push({
+            file: MANIFEST_FILE,
+            message: `${at}: another ${noun} already covers this mutant`
+          });
+          return;
+        }
+        claimed.add(target);
+      });
+      return claimed;
+    };
+    const allowed = claim(
+      "equivalentMutants",
+      gate.equivalentMutants,
+      "allowance",
+      (status) => SURVIVED.has(status) ? null : `stale allowance (the mutant is now ${status}). Remove it`
+    );
+    const expected = claim(
+      "expectedTimeouts",
+      gate.expectedTimeouts,
+      "entry",
+      (status) => SURVIVED.has(status) ? `the mutant ${status === "NoCoverage" ? "has no coverage" : "survived"} instead of timing out. Detect it with a test` : null
+    );
     for (const entry of located) {
       const { mutant } = entry;
       summary.total += 1;
@@ -1064,6 +1262,11 @@ function judgeMutationReport(input) {
         summary.detected += 1;
         if (mutant.status === "Timeout") {
           summary.timeout += 1;
+          if (expected.has(entry)) {
+            summary.expectedTimeout += 1;
+          } else {
+            unexpectedTimeouts.push(describeMutant(gate.path, entry));
+          }
         }
       } else if (NOT_EVALUABLE.has(mutant.status)) {
         summary.notEvaluable += 1;
@@ -1073,24 +1276,7 @@ function judgeMutationReport(input) {
           continue;
         }
         summary.unallowed += 1;
-        survivors.push({
-          file: gate.path,
-          line: mutant.location.start.line,
-          column: mutant.location.start.column,
-          status: mutant.status,
-          mutator: mutant.mutatorName,
-          original: normalizeCode(entry.original),
-          replacement: normalizeCode(entry.replacement),
-          occurrence: entry.occurrence,
-          sameKeyCount: entry.sameKeyCount,
-          allowance: {
-            mutator: mutant.mutatorName,
-            original: normalizeCode(entry.original),
-            replacement: normalizeCode(entry.replacement),
-            ...entry.sameKeyCount > 1 ? { occurrence: entry.occurrence } : {},
-            reason: ""
-          }
-        });
+        survivors.push(describeMutant(gate.path, entry));
       } else {
         violations.push({
           file: gate.path,
@@ -1106,7 +1292,14 @@ function judgeMutationReport(input) {
       message: "no mutants were evaluated (the mutation test ran on nothing)"
     });
   }
-  return { violations, survivors, summary };
+  const maxTimeouts = input.maxTimeouts ?? 0;
+  if (unexpectedTimeouts.length > maxTimeouts) {
+    violations.push({
+      file: MANIFEST_FILE,
+      message: `${unexpectedTimeouts.length} mutant(s) timed out outside expectedTimeouts; settings.mutation.maxTimeouts allows ${maxTimeouts}`
+    });
+  }
+  return { violations, survivors, unexpectedTimeouts, summary };
 }
 function formatSurvivor(survivor) {
   const occurrence = survivor.sameKeyCount > 1 ? ` / occurrence ${survivor.occurrence} of ${survivor.sameKeyCount}` : "";

package/dist/index.d.cts

@@ -12,6 +12,11 @@ interface Gate {
     decides: string;
     impact: string;
     equivalentMutants?: EquivalentMutant[];
+    /**
+     * Mutants that always time out (a loop that never ends). Same key as `equivalentMutants`.
+     * They are not counted against `settings.mutation.maxTimeouts`.
+     */
+    expectedTimeouts?: EquivalentMutant[];
 }
 interface Candidate {
     path: string;
@@ -75,6 +80,21 @@ interface Settings {
         file?: string;
         summaryExclude?: string[];
     };
+    /** Since 0.2.0. */
+    imports?: {
+        mode?: 'blocklist' | 'allowlist';
+        allow?: (string | {
+            pattern: string;
+            flags?: string;
+        } | {
+            module: string;
+            names: string[];
+        })[];
+    };
+    /** Since 0.2.0. */
+    mutation?: {
+        maxTimeouts?: number;
+    };
 }
 interface Manifest {
     $schema?: string;
@@ -108,6 +128,14 @@ interface ResolvedSettings {
     strykerReportFile: string;
     lcovFile: string | null;
     lcovSummaryExclude: RegExp[];
+    importMode: 'blocklist' | 'allowlist';
+    importAllow: {
+        module?: string;
+        regex?: RegExp;
+        names?: string[];
+    }[];
+    /** Timeouts tolerated outside `expectedTimeouts`. */
+    maxTimeouts: number;
 }
 /** One finding. Printed as `file:line: message`. */
 interface Violation {
@@ -244,10 +272,17 @@ interface MutationSummary {
     notEvaluable: number;
     /** Survived / NoCoverage mutants with no allowance. */
     unallowed: number;
+    /** The part of `timeout` that `expectedTimeouts` entries cover. */
+    expectedTimeout: number;
 }
 interface MutationVerdict {
     violations: Violation[];
     survivors: UnallowedSurvivor[];
+    /**
+     * Timed-out mutants that no `expectedTimeouts` entry covers. When there are more of them
+     * than `maxTimeouts`, `violations` says so.
+     */
+    unexpectedTimeouts: UnallowedSurvivor[];
     summary: MutationSummary;
 }
 /** Whitespace is not part of the key, so reformatting a gate does not invalidate an allowance. */
@@ -275,6 +310,11 @@ declare function judgeMutationReport(input: {
     gates: Gate[];
     report: MutationReport;
     readSource: (gatePath: string) => string | undefined;
+    /**
+     * `settings.mutation.maxTimeouts`: how many timeouts outside `expectedTimeouts` are
+     * tolerated. Absent means 0.
+     */
+    maxTimeouts?: number;
 }): MutationVerdict;
 /** `file:line:column / mutator / original → replacement / occurrence n of m`. */
 declare function formatSurvivor(survivor: UnallowedSurvivor): string;

package/dist/index.d.ts

@@ -12,6 +12,11 @@ interface Gate {
     decides: string;
     impact: string;
     equivalentMutants?: EquivalentMutant[];
+    /**
+     * Mutants that always time out (a loop that never ends). Same key as `equivalentMutants`.
+     * They are not counted against `settings.mutation.maxTimeouts`.
+     */
+    expectedTimeouts?: EquivalentMutant[];
 }
 interface Candidate {
     path: string;
@@ -75,6 +80,21 @@ interface Settings {
         file?: string;
         summaryExclude?: string[];
     };
+    /** Since 0.2.0. */
+    imports?: {
+        mode?: 'blocklist' | 'allowlist';
+        allow?: (string | {
+            pattern: string;
+            flags?: string;
+        } | {
+            module: string;
+            names: string[];
+        })[];
+    };
+    /** Since 0.2.0. */
+    mutation?: {
+        maxTimeouts?: number;
+    };
 }
 interface Manifest {
     $schema?: string;
@@ -108,6 +128,14 @@ interface ResolvedSettings {
     strykerReportFile: string;
     lcovFile: string | null;
     lcovSummaryExclude: RegExp[];
+    importMode: 'blocklist' | 'allowlist';
+    importAllow: {
+        module?: string;
+        regex?: RegExp;
+        names?: string[];
+    }[];
+    /** Timeouts tolerated outside `expectedTimeouts`. */
+    maxTimeouts: number;
 }
 /** One finding. Printed as `file:line: message`. */
 interface Violation {
@@ -244,10 +272,17 @@ interface MutationSummary {
     notEvaluable: number;
     /** Survived / NoCoverage mutants with no allowance. */
     unallowed: number;
+    /** The part of `timeout` that `expectedTimeouts` entries cover. */
+    expectedTimeout: number;
 }
 interface MutationVerdict {
     violations: Violation[];
     survivors: UnallowedSurvivor[];
+    /**
+     * Timed-out mutants that no `expectedTimeouts` entry covers. When there are more of them
+     * than `maxTimeouts`, `violations` says so.
+     */
+    unexpectedTimeouts: UnallowedSurvivor[];
     summary: MutationSummary;
 }
 /** Whitespace is not part of the key, so reformatting a gate does not invalidate an allowance. */
@@ -275,6 +310,11 @@ declare function judgeMutationReport(input: {
     gates: Gate[];
     report: MutationReport;
     readSource: (gatePath: string) => string | undefined;
+    /**
+     * `settings.mutation.maxTimeouts`: how many timeouts outside `expectedTimeouts` are
+     * tolerated. Absent means 0.
+     */
+    maxTimeouts?: number;
 }): MutationVerdict;
 /** `file:line:column / mutator / original → replacement / occurrence n of m`. */
 declare function formatSurvivor(survivor: UnallowedSurvivor): string;