@t09tanaka/test-gates 0.0.0-stage → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,377 @@
+/** One allowed equivalent mutant. Matched by mutator + original + replacement, never by line number. */
+interface EquivalentMutant {
+    mutator: string;
+    original: string;
+    replacement: string;
+    reason: string;
+    /** 1-based index among the mutants of the file that share mutator + original + replacement. */
+    occurrence?: number;
+}
+interface Gate {
+    path: string;
+    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;
+    decides: string;
+    blocker: string;
+}
+/** A regular expression written in JSON. A bare string is shorthand for `{ pattern }`. */
+interface PatternRule {
+    pattern: string;
+    flags?: string;
+    reason?: string;
+}
+interface NamedImportRule {
+    module: string;
+    names: string[];
+    reason?: string;
+}
+interface ImportAlias {
+    prefix: string;
+    target: string;
+}
+interface SpecRewrite {
+    from: string;
+    to: string;
+}
+/** `settings` of test-gates.json. Everything is optional. */
+interface Settings {
+    gateExtensions?: string[];
+    spec?: {
+        suffixes?: string[];
+        rewrite?: SpecRewrite[];
+    };
+    impureImports?: {
+        defaults?: boolean;
+        add?: (string | PatternRule)[];
+        allow?: string[];
+    };
+    impureNamedImports?: {
+        defaults?: boolean;
+        add?: NamedImportRule[];
+    };
+    impurePaths?: {
+        defaults?: boolean;
+        add?: (string | PatternRule)[];
+    };
+    forbiddenSource?: {
+        defaults?: boolean;
+        add?: (string | PatternRule)[];
+    };
+    importAliases?: ImportAlias[];
+    gateCommand?: string[];
+    selfcheck?: {
+        mode?: 'all' | 'first';
+        failurePattern?: string;
+    };
+    stryker?: {
+        configFile?: string;
+        reportFile?: string;
+    };
+    lcov?: {
+        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;
+    gates: Gate[];
+    candidates: Candidate[];
+    settings?: Settings;
+}
+interface CompiledRule {
+    regex: RegExp;
+    reason: string;
+}
+/** Settings with defaults applied and every pattern compiled. */
+interface ResolvedSettings {
+    gateExtensions: string[];
+    /** `null` means "derive `.spec<ext>` and `.test<ext>` from the gate's extension". */
+    specSuffixes: string[] | null;
+    specRewrite: {
+        regex: RegExp;
+        to: string;
+    }[];
+    impureImports: CompiledRule[];
+    allowedImports: RegExp[];
+    impureNamedImports: Required<NamedImportRule>[];
+    impurePaths: CompiledRule[];
+    forbiddenSource: CompiledRule[];
+    importAliases: ImportAlias[];
+    gateCommand: string[] | null;
+    selfcheckMode: 'all' | 'first';
+    selfcheckFailurePattern: string | null;
+    strykerConfigFile: string | null;
+    strykerReportFile: string;
+    lcovFile: string | null;
+    lcovSummaryExclude: RegExp[];
+    importMode: 'blocklist' | 'allowlist';
+    importAllow: {
+        module?: string;
+        regex?: RegExp;
+        names?: string[];
+    }[];
+    /** `null`: no limit. */
+    maxTimeouts: number | null;
+}
+/** One finding. Printed as `file:line: message`. */
+interface Violation {
+    file: string;
+    line?: number;
+    message: string;
+}
+
+interface ResolvedGate extends Gate {
+    /** Where the spec may live, in order of preference (relative to the subproject). */
+    specCandidates: string[];
+    /**
+     * The spec that exists. When none exists this is the first candidate, so that a config built
+     * from it fails on the missing coverage instead of silently dropping the gate. `null` only
+     * when the project has no spec convention (`settings.spec.suffixes: []`).
+     */
+    spec: string | null;
+    /** Every candidate that exists. More than one is ambiguous and `test-gates check` rejects it. */
+    existingSpecs: string[];
+}
+interface LoadedManifest {
+    /** Absolute path of the subproject. */
+    dir: string;
+    gates: ResolvedGate[];
+    candidates: Candidate[];
+    settings: ResolvedSettings;
+    /** Problems inside the manifest entries (`test-gates check` reports them). */
+    violations: Violation[];
+}
+/** Reads `<dir>/test-gates.json`. Throws ManifestError when it cannot be used at all. */
+declare function readManifest(dir: string): LoadedManifest;
+/**
+ * Reads and validates `<dir>/test-gates.json` for use in a config file.
+ * Throws when the manifest has any structural problem: a config derived from a broken list
+ * would gate the wrong set of files.
+ */
+declare function loadGates(dir?: string): LoadedManifest;
+/**
+ * Specs the gate run executes: the spec of every gate, minus the one `test-gates selfcheck`
+ * asks to leave out through TEST_GATES_EXCLUDE_SPEC.
+ */
+declare function gateSpecs(manifest: LoadedManifest, env?: Record<string, string | undefined>): string[];
+
+/** Every static rule of the gates. Returns all violations, not just the first. */
+declare function checkGates(manifest: LoadedManifest): Violation[];
+
+declare const MANIFEST_FILE = "test-gates.json";
+/** The manifest cannot be used at all (exit code 2), as opposed to a violation inside it (exit code 1). */
+declare class ManifestError extends Error {
+}
+interface ParsedManifest {
+    /** Entries whose `path` is usable. Other problems of an entry are reported in `violations`. */
+    gates: Gate[];
+    candidates: Candidate[];
+    settings: unknown;
+    violations: Violation[];
+}
+/**
+ * Parses test-gates.json. Throws ManifestError when the file is not usable at all;
+ * returns per-entry problems as violations.
+ */
+declare function parseManifest(text: string): ParsedManifest;
+
+/** Where the Stryker JSON report is written and read when `settings.stryker.reportFile` is not set. */
+declare const DEFAULT_REPORT_FILE = "reports/mutation/mutation.json";
+declare const DEFAULT_GATE_EXTENSIONS: string[];
+/**
+ * Modules a pure module must not import at runtime. `import type` is never checked.
+ * `@prisma/client` is deliberately absent: `Prisma.Decimal` and enums are values a pure
+ * module may use. Only `PrismaClient` is banned, through DEFAULT_IMPURE_NAMED_IMPORTS.
+ */
+declare const DEFAULT_IMPURE_IMPORTS: PatternRule[];
+declare const DEFAULT_IMPURE_NAMED_IMPORTS: Required<NamedImportRule>[];
+/** Paths that cannot be gates. */
+declare const DEFAULT_IMPURE_PATHS: PatternRule[];
+/** Lines that must not appear in a gate. Each pattern is tested against one line at a time. */
+declare const DEFAULT_FORBIDDEN_SOURCE: PatternRule[];
+/**
+ * Applies defaults to `settings` of test-gates.json and compiles every pattern.
+ * Throws SettingsError on anything it does not understand: a typo in a setting must not
+ * silently fall back to a default.
+ */
+declare function resolveSettings(raw: unknown): ResolvedSettings;
+
+interface Position {
+    line: number;
+    column: number;
+}
+interface ReportLocation {
+    start: Position;
+    end: Position;
+}
+interface ReportMutant {
+    mutatorName: string;
+    replacement?: string;
+    status: string;
+    location: ReportLocation;
+}
+interface ReportFile {
+    source?: string;
+    mutants?: ReportMutant[];
+}
+/** The part of the mutation-testing-elements JSON report that the verdict depends on. */
+interface MutationReport {
+    files?: Record<string, ReportFile>;
+}
+/** A survivor that no allowance covers. `allowance` can be pasted into `equivalentMutants`. */
+interface UnallowedSurvivor {
+    file: string;
+    line: number;
+    column: number;
+    status: string;
+    mutator: string;
+    original: string;
+    replacement: string;
+    /** 1-based position among the mutants of the file with the same mutator/original/replacement. */
+    occurrence: number;
+    /** How many mutants of the file share that key. `occurrence` is required when this is > 1. */
+    sameKeyCount: number;
+    allowance: EquivalentMutant;
+}
+interface MutationSummary {
+    total: number;
+    /** Killed + Timeout. */
+    detected: number;
+    /**
+     * The Timeout part of `detected`. Shown on its own: under heavy load mutants time out that
+     * would otherwise survive, so a high number means the run may be hiding survivors.
+     */
+    timeout: number;
+    /** Survived / NoCoverage mutants matched by an allowance. */
+    allowed: number;
+    /** RuntimeError + CompileError: the mutated code is not a program, so nothing was evaluated. */
+    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. Informational unless
+     * `maxTimeouts` is set and exceeded, in which case `violations` says so.
+     */
+    unexpectedTimeouts: UnallowedSurvivor[];
+    summary: MutationSummary;
+}
+/** Whitespace is not part of the key, so reformatting a gate does not invalidate an allowance. */
+declare function normalizeCode(text: string): string;
+/**
+ * Cuts the text a report location points at. Lines and columns are 1-based and the end is
+ * exclusive. Returns null when the location is outside the source.
+ */
+declare function sliceByLocation(source: string, location: ReportLocation): string | null;
+/**
+ * Decides whether a Stryker run passes.
+ *
+ * Killed and Timeout mutants are detected. Survived and NoCoverage mutants must each be covered
+ * by one allowance of the gate (`equivalentMutants`), matched by mutator + original source text
+ * + replacement. RuntimeError and CompileError are counted but do not fail. Ignored, Pending
+ * and any unknown status fail: a mutant that was not evaluated proves nothing.
+ *
+ * An allowance fails the run when it matches no surviving mutant (stale), when it matches
+ * several mutants and has no `occurrence`, or when two allowances point at the same mutant.
+ *
+ * @param input.readSource Source of a gate on disk; `undefined` when it cannot be read. Used
+ *   when the report carries no source, and to reject a report made from an older file.
+ */
+declare function judgeMutationReport(input: {
+    gates: Gate[];
+    report: MutationReport;
+    readSource: (gatePath: string) => string | undefined;
+    /**
+     * `settings.mutation.maxTimeouts`: how many timeouts outside `expectedTimeouts` are
+     * tolerated. `null` or absent means no limit.
+     */
+    maxTimeouts?: number | null;
+}): MutationVerdict;
+/** `file:line:column / mutator / original → replacement / occurrence n of m`. */
+declare function formatSurvivor(survivor: UnallowedSurvivor): string;
+/** The real numbers, on one line. Deliberately not a percentage. */
+declare function formatSummary(summary: MutationSummary): string;
+
+interface LcovFile {
+    /** Instrumented lines. */
+    found: number;
+    /** Instrumented lines executed at least once. */
+    hit: number;
+    /** Instrumented lines never executed, ascending. Empty when the record has no DA entries. */
+    uncovered: number[];
+}
+/**
+ * Reads an lcov tracefile into per-file line coverage.
+ *
+ * When a file appears in several records (merged tracefiles), lines are united through their
+ * `DA:` entries, so a line counts as hit if any record hit it. A record without `DA:` entries
+ * contributes its `LF:` / `LH:` totals instead.
+ *
+ * @param rootDir When given, absolute `SF:` paths under it are made relative to it.
+ */
+declare function parseLcov(text: string, rootDir?: string): Map<string, LcovFile>;
+interface LcovGateResult {
+    path: string;
+    found: number;
+    hit: number;
+    ok: boolean;
+}
+interface LcovVerdict {
+    violations: Violation[];
+    results: LcovGateResult[];
+}
+/**
+ * Requires 100% line coverage for every gate. A gate with no record (never loaded by a test)
+ * or with no instrumented line fails: an absent measurement is not a pass.
+ */
+declare function judgeLcov(gatePaths: string[], coverage: Map<string, LcovFile>): LcovVerdict;
+
+/** Environment variable through which `test-gates selfcheck` tells the gate config which spec to leave out. */
+declare const EXCLUDE_ENV = "TEST_GATES_EXCLUDE_SPEC";
+/**
+ * Decides whether one negative control held: with the spec of `gatePath` left out, the gate
+ * command must fail, and it must fail because of the coverage threshold of that very file.
+ * A run that fails for another reason (a config that does not load) proves nothing.
+ *
+ * @param input.status Exit code of the gate command; null when it was killed or never started.
+ * @param input.failurePattern Replaces the built-in threshold detection. `{gate}` stands for
+ *   the gate path. Tested against the whole output.
+ * @returns Why the control did not hold, or null when it held.
+ */
+declare function judgeSelfcheck(input: {
+    status: number | null;
+    output: string;
+    gatePath: string;
+    failurePattern?: string | null;
+}): string | null;
+
+export { type Candidate, DEFAULT_FORBIDDEN_SOURCE, DEFAULT_GATE_EXTENSIONS, DEFAULT_IMPURE_IMPORTS, DEFAULT_IMPURE_NAMED_IMPORTS, DEFAULT_IMPURE_PATHS, DEFAULT_REPORT_FILE, EXCLUDE_ENV, type EquivalentMutant, type Gate, type LoadedManifest, MANIFEST_FILE, type Manifest, ManifestError, type MutationReport, type MutationSummary, type MutationVerdict, type ResolvedGate, type ResolvedSettings, type Settings, type UnallowedSurvivor, type Violation, checkGates, formatSummary, formatSurvivor, gateSpecs, judgeLcov, judgeMutationReport, judgeSelfcheck, loadGates, normalizeCode, parseLcov, parseManifest, readManifest, resolveSettings, sliceByLocation };