@t09tanaka/test-gates 0.1.0 → 0.2.0

package/dist/cli.js

@@ -15,6 +15,54 @@ var OPTIONS_BY_COMMAND = {
   selfcheck: ["--dir", "--all", "--first"],
   lcov: ["--dir", "--file"]
 };
+function consume(parsed, argv, index, allowed) {
+  const arg = argv[index];
+  const next = index + 1;
+  if (arg === "--") {
+    if (parsed.command !== "mutation" && parsed.command !== "selfcheck") {
+      throw new UsageError('"--" is only accepted by the mutation and selfcheck commands');
+    }
+    parsed.rest.push(...argv.slice(next));
+    return argv.length;
+  }
+  if (arg === "--help" || arg === "-h") {
+    parsed.help = true;
+    return next;
+  }
+  if (arg === "--version" || arg === "-v") {
+    parsed.version = true;
+    return next;
+  }
+  const equals = arg.indexOf("=");
+  const name = equals !== -1 ? arg.slice(0, equals) : arg;
+  if (allowed?.includes(name)) {
+    if (VALUE_OPTIONS.includes(name)) {
+      const value = equals !== -1 ? arg.slice(equals + 1) : argv[next];
+      if (value === void 0 || value === "") {
+        throw new UsageError(`${name} needs a value`);
+      }
+      const key = name.slice(2);
+      parsed[key] = value;
+      return equals !== -1 ? next : next + 1;
+    }
+    if (equals !== -1) {
+      throw new UsageError(`${name} does not take a value`);
+    }
+    const mode = name === "--all" ? "all" : "first";
+    if (parsed.mode !== null && parsed.mode !== mode) {
+      throw new UsageError("--all and --first cannot be combined");
+    }
+    parsed.mode = mode;
+    return next;
+  }
+  if (parsed.command === "mutation") {
+    parsed.rest.push(arg);
+    return next;
+  }
+  throw new UsageError(
+    parsed.command ? `unknown argument for ${parsed.command}: ${arg}` : `unknown argument: ${arg}`
+  );
+}
 function parseArgs(argv) {
   const parsed = {
     command: null,
@@ -37,58 +85,7 @@ function parseArgs(argv) {
   }
   const allowed = parsed.command ? OPTIONS_BY_COMMAND[parsed.command] : void 0;
   while (index < argv.length) {
-    const arg = argv[index];
-    index += 1;
-    if (arg === "--") {
-      if (parsed.command !== "mutation" && parsed.command !== "selfcheck") {
-        throw new UsageError('"--" is only accepted by the mutation and selfcheck commands');
-      }
-      parsed.rest.push(...argv.slice(index));
-      break;
-    }
-    if (arg === "--help" || arg === "-h") {
-      parsed.help = true;
-      continue;
-    }
-    if (arg === "--version" || arg === "-v") {
-      parsed.version = true;
-      continue;
-    }
-    const equals = arg.indexOf("=");
-    const name = equals !== -1 ? arg.slice(0, equals) : arg;
-    if (allowed?.includes(name)) {
-      if (VALUE_OPTIONS.includes(name)) {
-        let value;
-        if (equals !== -1) {
-          value = arg.slice(equals + 1);
-        } else {
-          value = argv[index];
-          index += 1;
-        }
-        if (value === void 0 || value === "") {
-          throw new UsageError(`${name} needs a value`);
-        }
-        const key = name.slice(2);
-        parsed[key] = value;
-        continue;
-      }
-      if (equals !== -1) {
-        throw new UsageError(`${name} does not take a value`);
-      }
-      const mode = name === "--all" ? "all" : "first";
-      if (parsed.mode !== null && parsed.mode !== mode) {
-        throw new UsageError("--all and --first cannot be combined");
-      }
-      parsed.mode = mode;
-      continue;
-    }
-    if (parsed.command === "mutation") {
-      parsed.rest.push(arg);
-      continue;
-    }
-    throw new UsageError(
-      parsed.command ? `unknown argument for ${parsed.command}: ${arg}` : `unknown argument: ${arg}`
-    );
+    index = consume(parsed, argv, index, allowed);
   }
   if (parsed.command === "selfcheck" && parsed.rest.length === 0 && argv.includes("--")) {
     throw new UsageError('"--" must be followed by the gate command');
@@ -128,17 +125,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}`
     }))
   );
 }
@@ -221,6 +218,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 };
 }
@@ -280,6 +280,83 @@ 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;
+}
+function findImporters(gatePath, others, aliases) {
+  const target = gatePath.replace(SCRIPT_EXTENSION, "");
+  const asDirectory = target.replace(/\/index$/, "");
+  return others.filter(
+    (other) => other.path !== gatePath && parseImports(other.source).some((imported) => {
+      if (imported.typeOnly) {
+        return false;
+      }
+      const resolved = resolveSpecifier(imported.module, other.path, aliases);
+      return resolved === target || resolved === asDirectory;
+    })
+  ).map((other) => other.path);
+}
 
 // src/core/scan.ts
 var IGNORE_DIRECTIVE = /\b(istanbul|c8|v8)\s+ignore\b/;
@@ -297,7 +374,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));
 }
@@ -334,6 +411,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)) {
@@ -360,34 +438,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 = [];
@@ -405,7 +480,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];
@@ -466,6 +541,21 @@ function looksLikeSpec(gatePath, settings) {
   return extension !== null && suffixesFor(extension, settings).some((suffix) => gatePath.endsWith(suffix));
 }
 
+// src/core/vitest-coverage.ts
+function vitestCoverageWarning(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/fs.ts
 import fs from "fs";
 import path from "path";
@@ -660,7 +750,9 @@ function resolveSettings(raw) {
       "gateCommand",
       "selfcheck",
       "stryker",
-      "lcov"
+      "lcov",
+      "imports",
+      "mutation"
     ],
     "settings"
   );
@@ -761,6 +853,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 {
@@ -782,6 +910,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 ?? null,
     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}]`)
@@ -957,9 +1088,43 @@ function checkGates(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(
+        fs3.readFileSync(path3.join(current, "node_modules", "vitest", "package.json"), "utf8")
+      );
+      return typeof pkg.version === "string" ? pkg.version : null;
+    } catch {
+      const parent = path3.dirname(current);
+      if (parent === current) {
+        return null;
+      }
+      current = parent;
+    }
+  }
+}
+function checkWarnings(manifest) {
+  const config = VITEST_GATE_CONFIGS.find((name) => fs3.existsSync(path3.join(manifest.dir, name)));
+  if (!config) {
+    return [];
+  }
+  const warning = vitestCoverageWarning({
+    vitestVersion: installedVitestVersion(manifest.dir),
+    configSource: readText(manifest.dir, config)
+  });
+  return warning === null ? [] : [`${config}: ${warning}`];
+}
 function runCheck(dir, io2) {
   const manifest = readManifest(dir);
   const violations = checkGates(manifest);
+  for (const warning of checkWarnings(manifest)) {
+    io2.err(`test-gates check: warning: ${warning}`);
+  }
   if (violations.length > 0) {
     printViolations(io2, "check", violations);
     return 1;
@@ -1170,6 +1335,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}`;
@@ -1177,13 +1363,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 ?? {})) {
@@ -1193,7 +1381,9 @@ function judgeMutationReport(input) {
     const gatePath = normalizePath2(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({
@@ -1257,38 +1447,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;
@@ -1296,6 +1501,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;
@@ -1305,24 +1515,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,
@@ -1338,7 +1531,14 @@ function judgeMutationReport(input) {
       message: "no mutants were evaluated (the mutation test ran on nothing)"
     });
   }
-  return { violations, survivors, summary };
+  const maxTimeouts = input.maxTimeouts ?? null;
+  if (maxTimeouts !== null && 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}` : "";
@@ -1372,6 +1572,7 @@ function runMutationResult(dir, reportOverride, io2) {
   const verdict = judgeMutationReport({
     gates: manifest.gates,
     report,
+    maxTimeouts: manifest.settings.maxTimeouts,
     readSource: (gatePath) => {
       try {
         return fs5.readFileSync(path5.join(manifest.dir, gatePath), "utf8");
@@ -1412,6 +1613,24 @@ function runMutationResult(dir, reportOverride, io2) {
     }
     io2.err("");
   }
+  const maxTimeouts = manifest.settings.maxTimeouts;
+  if (maxTimeouts !== null && verdict.unexpectedTimeouts.length > maxTimeouts) {
+    io2.err(
+      `test-gates mutation: ${verdict.unexpectedTimeouts.length} mutant(s) timed out (settings.mutation.maxTimeouts: ${maxTimeouts})`
+    );
+    for (const mutant of verdict.unexpectedTimeouts) {
+      io2.err(`  - ${formatSurvivor(mutant)}`);
+    }
+    io2.err("");
+    io2.err("A timeout counts as detected, but on a loaded machine a mutant that would survive");
+    io2.err("can time out instead. Run again with less load (-- --concurrency 1). Only for a");
+    io2.err("mutant that can never finish (a loop that no longer ends), add it to");
+    io2.err('"expectedTimeouts" of the gate in test-gates.json and fill in "reason":');
+    for (const mutant of verdict.unexpectedTimeouts) {
+      io2.err(`    ${mutant.file}: ${JSON.stringify(mutant.allowance)}`);
+    }
+    io2.err("");
+  }
   if (verdict.violations.length > 0) {
     printViolations(io2, "mutation", verdict.violations);
   }
@@ -1521,6 +1740,18 @@ function runSelfcheck(dir, mode, commandOverride, io2) {
     } else {
       failed += 1;
       io2.err(`  \u2717 ${gate.path}: ${reason}`);
+      if (result.status === 0) {
+        const importers = findImporters(
+          gate.path,
+          manifest.gates.filter((other) => existsExact(manifest.dir, other.path)).map((other) => ({ path: other.path, source: readText(manifest.dir, other.path) })),
+          manifest.settings.importAliases
+        );
+        if (importers.length > 0) {
+          io2.err(
+            `      hint: ${importers.join(", ")} import(s) this gate, so their specs cover it without its own spec. Mock the import in those specs and assert the call (toHaveBeenCalledWith), so that each spec only covers its own gate`
+          );
+        }
+      }
       const tail = output.trimEnd().split("\n").slice(-25).join("\n");
       if (tail !== "") {
         io2.err(tail.replace(/^/gm, "      "));