@t09tanaka/test-gates 0.0.0-stage → 0.2.0

package/dist/vitest.d.cts

@@ -0,0 +1,26 @@
+interface VitestGatesOptions {
+    /** Directory of test-gates.json: `__dirname`, or `import.meta.url` of the config file. */
+    rootDir?: string;
+    /** `test` options of Vitest. `include` and `coverage.include/thresholds/enabled` are owned by the helper. */
+    test?: Record<string, unknown> & {
+        coverage?: Record<string, unknown>;
+    };
+    /**
+     * Coverage provider. Default `v8`. `istanbul` (needs `@vitest/coverage-istanbul`) also counts
+     * the skipped side of an `if` without `else` on Vitest 3, and an unused default parameter on
+     * every version; see the README for the measurements. Same as `test.coverage.provider`.
+     */
+    coverageProvider?: 'v8' | 'istanbul';
+    /** Any other Vite option: resolve.alias, esbuild, plugins, … */
+    [option: string]: unknown;
+}
+/**
+ * Vitest config for the gate run: only the specs of the gates, only the gates measured, every
+ * gate at 100% on all four metrics (`thresholds.perFile`).
+ *
+ * Glob or path keys are deliberately not used in `thresholds`: Vitest passes when such a key
+ * matches no file. Pass the result to `defineConfig`.
+ */
+declare function createVitestGatesConfig(options?: VitestGatesOptions): Record<string, unknown>;
+
+export { type VitestGatesOptions, createVitestGatesConfig };

package/dist/vitest.d.ts

@@ -0,0 +1,26 @@
+interface VitestGatesOptions {
+    /** Directory of test-gates.json: `__dirname`, or `import.meta.url` of the config file. */
+    rootDir?: string;
+    /** `test` options of Vitest. `include` and `coverage.include/thresholds/enabled` are owned by the helper. */
+    test?: Record<string, unknown> & {
+        coverage?: Record<string, unknown>;
+    };
+    /**
+     * Coverage provider. Default `v8`. `istanbul` (needs `@vitest/coverage-istanbul`) also counts
+     * the skipped side of an `if` without `else` on Vitest 3, and an unused default parameter on
+     * every version; see the README for the measurements. Same as `test.coverage.provider`.
+     */
+    coverageProvider?: 'v8' | 'istanbul';
+    /** Any other Vite option: resolve.alias, esbuild, plugins, … */
+    [option: string]: unknown;
+}
+/**
+ * Vitest config for the gate run: only the specs of the gates, only the gates measured, every
+ * gate at 100% on all four metrics (`thresholds.perFile`).
+ *
+ * Glob or path keys are deliberately not used in `thresholds`: Vitest passes when such a key
+ * matches no file. Pass the result to `defineConfig`.
+ */
+declare function createVitestGatesConfig(options?: VitestGatesOptions): Record<string, unknown>;
+
+export { type VitestGatesOptions, createVitestGatesConfig };

package/dist/vitest.js

@@ -0,0 +1,43 @@
+import {
+  FULL_COVERAGE,
+  resolveRootDir
+} from "./chunk-4HAJIKDZ.js";
+import {
+  NO_SPEC_PATTERN,
+  gateSpecs,
+  loadGates
+} from "./chunk-XEKQKLKY.js";
+
+// src/vitest.ts
+function createVitestGatesConfig(options = {}) {
+  const { rootDir: rootDirOption, coverageProvider, test = {}, ...overrides } = options;
+  const rootDir = resolveRootDir(rootDirOption);
+  const manifest = loadGates(rootDir);
+  const { coverage = {}, ...testOverrides } = test;
+  const specs = gateSpecs(manifest);
+  return {
+    ...overrides,
+    root: rootDir,
+    test: {
+      environment: "node",
+      ...testOverrides,
+      include: specs.length > 0 ? specs : [NO_SPEC_PATTERN],
+      // `test-gates selfcheck` leaves out the only spec of a single-gate project; the run must
+      // then fail on the coverage threshold, not on "no test files found".
+      passWithNoTests: true,
+      coverage: {
+        provider: "v8",
+        reporter: ["text"],
+        reportsDirectory: "coverage/gates",
+        ...coverage,
+        ...coverageProvider === void 0 ? {} : { provider: coverageProvider },
+        enabled: true,
+        include: manifest.gates.map((gate) => gate.path),
+        thresholds: { perFile: true, ...FULL_COVERAGE }
+      }
+    }
+  };
+}
+export {
+  createVitestGatesConfig
+};

package/package.json

@@ -1,6 +1,140 @@
 {
   "name": "@t09tanaka/test-gates",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Test gates for the code that must not be wrong: per-file 100% coverage as the floor, mutation testing with a per-mutant allow list as the real check.",
+  "author": "t09tanaka",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t09tanaka/test-gates.git"
+  },
+  "homepage": "https://github.com/t09tanaka/test-gates#readme",
+  "bugs": {
+    "url": "https://github.com/t09tanaka/test-gates/issues"
+  },
+  "keywords": [
+    "test",
+    "coverage",
+    "mutation-testing",
+    "stryker",
+    "jest",
+    "vitest",
+    "lcov",
+    "quality-gate",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "test-gates": "dist/cli.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./jest": {
+      "import": {
+        "types": "./dist/jest.d.ts",
+        "default": "./dist/jest.js"
+      },
+      "require": {
+        "types": "./dist/jest.d.cts",
+        "default": "./dist/jest.cjs"
+      }
+    },
+    "./vitest": {
+      "import": {
+        "types": "./dist/vitest.d.ts",
+        "default": "./dist/vitest.js"
+      },
+      "require": {
+        "types": "./dist/vitest.d.cts",
+        "default": "./dist/vitest.cjs"
+      }
+    },
+    "./stryker": {
+      "import": {
+        "types": "./dist/stryker.d.ts",
+        "default": "./dist/stryker.js"
+      },
+      "require": {
+        "types": "./dist/stryker.d.cts",
+        "default": "./dist/stryker.cjs"
+      }
+    },
+    "./schema.json": "./schema/test-gates.schema.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test",
+    "lint:fix": "eslint src test --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:gates": "node dist/cli.js check && vitest run --config vitest.gates.config.ts",
+    "test:gates:selfcheck": "node dist/cli.js selfcheck",
+    "test:gates:mutation": "node dist/cli.js mutation",
+    "prepublishOnly": "npm run lint && npm run format:check && npm run typecheck && npm test && npm run test:gates && npm run test:gates:selfcheck"
+  },
+  "peerDependencies": {
+    "@stryker-mutator/core": ">=9",
+    "jest": ">=29",
+    "vitest": ">=3",
+    "@vitest/coverage-istanbul": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "@stryker-mutator/core": {
+      "optional": true
+    },
+    "jest": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    },
+    "@vitest/coverage-istanbul": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
+    "@types/node": "^22.20.5",
+    "@vitest/coverage-istanbul": "^3.2.7",
+    "@vitest/coverage-v8": "^3.2.7",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "prettier": "^3.9.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^3.2.7"
+  }
+}

package/schema/test-gates.schema.json

@@ -0,0 +1,409 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/t09tanaka/test-gates/blob/main/schema/test-gates.schema.json",
+  "title": "test-gates.json",
+  "description": "The single source of truth for the test gates of one subproject (@t09tanaka/test-gates).",
+  "type": "object",
+  "required": ["gates"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "gates": {
+      "description": "Pure modules that hold an important decision. Each must reach 100% on all four coverage metrics and leave no surviving mutant outside its allow list.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/definitions/gate"
+      }
+    },
+    "candidates": {
+      "description": "Important logic that cannot be a gate yet. Nothing is enforced for these beyond their existence.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/candidate"
+      }
+    },
+    "settings": {
+      "$ref": "#/definitions/settings"
+    }
+  },
+  "definitions": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "gate": {
+      "type": "object",
+      "required": ["path", "decides", "impact"],
+      "additionalProperties": true,
+      "properties": {
+        "path": {
+          "description": "Path of the module, relative to the subproject, with forward slashes.",
+          "$ref": "#/definitions/nonEmptyString"
+        },
+        "decides": {
+          "description": "What this module decides.",
+          "$ref": "#/definitions/nonEmptyString"
+        },
+        "impact": {
+          "description": "What goes wrong for users or the business when the decision is wrong.",
+          "$ref": "#/definitions/nonEmptyString"
+        },
+        "equivalentMutants": {
+          "description": "Surviving mutants that are allowed because they cannot be observed from outside. One entry allows exactly one mutant.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/equivalentMutant"
+          }
+        },
+        "expectedTimeouts": {
+          "description": "Since 0.2.0. Mutants that can never finish (a loop that no longer ends) and therefore always time out. Same key as equivalentMutants. They are not counted against settings.mutation.maxTimeouts. An entry whose mutant survives, or does not exist, fails the run; one that is killed is accepted.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/equivalentMutant"
+          }
+        }
+      }
+    },
+    "equivalentMutant": {
+      "type": "object",
+      "required": ["mutator", "original", "replacement", "reason"],
+      "additionalProperties": false,
+      "properties": {
+        "mutator": {
+          "description": "Stryker mutator name, e.g. ConditionalExpression.",
+          "$ref": "#/definitions/nonEmptyString"
+        },
+        "original": {
+          "description": "The source text the mutant replaces. Whitespace differences are ignored.",
+          "$ref": "#/definitions/nonEmptyString"
+        },
+        "replacement": {
+          "description": "The text Stryker puts in its place. May be empty.",
+          "type": "string"
+        },
+        "reason": {
+          "description": "Why no input can make the mutant observable.",
+          "$ref": "#/definitions/nonEmptyString"
+        },
+        "occurrence": {
+          "description": "1-based index among the mutants of the file with the same mutator, original and replacement. Required when there is more than one.",
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "candidate": {
+      "type": "object",
+      "required": ["path", "decides", "blocker"],
+      "additionalProperties": true,
+      "properties": {
+        "path": {
+          "description": "File or directory, relative to the subproject.",
+          "$ref": "#/definitions/nonEmptyString"
+        },
+        "decides": {
+          "$ref": "#/definitions/nonEmptyString"
+        },
+        "blocker": {
+          "description": "What has to happen before this can become a gate.",
+          "$ref": "#/definitions/nonEmptyString"
+        }
+      }
+    },
+    "patternRule": {
+      "description": "A regular expression, either as a string or with flags and a reason.",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/nonEmptyString"
+        },
+        {
+          "type": "object",
+          "required": ["pattern"],
+          "additionalProperties": false,
+          "properties": {
+            "pattern": {
+              "$ref": "#/definitions/nonEmptyString"
+            },
+            "flags": {
+              "type": "string"
+            },
+            "reason": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "ruleList": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "defaults": {
+          "description": "Set to false to drop the built-in rules.",
+          "type": "boolean",
+          "default": true
+        },
+        "add": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/patternRule"
+          }
+        }
+      }
+    },
+    "settings": {
+      "description": "Per-project conventions. Everything is optional.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateExtensions": {
+          "description": "File extensions a gate may have.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^\\."
+          },
+          "default": [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"]
+        },
+        "spec": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "suffixes": {
+              "description": "Replaces the gate's extension to form the spec path. Default: \".spec<ext>\" and \".test<ext>\". An empty array means the project has no spec convention.",
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/nonEmptyString"
+              }
+            },
+            "rewrite": {
+              "description": "Regular expression replacements applied to the gate path before the suffix, for specs that live in another directory.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["from", "to"],
+                "additionalProperties": false,
+                "properties": {
+                  "from": {
+                    "$ref": "#/definitions/nonEmptyString"
+                  },
+                  "to": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "impureImports": {
+          "description": "Modules a gate must not import at runtime (regular expressions tested against the module specifier). `import type` is never checked.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "defaults": {
+              "type": "boolean",
+              "default": true
+            },
+            "add": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/patternRule"
+              }
+            },
+            "allow": {
+              "description": "Module specifiers exempt from every rule (regular expressions).",
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/nonEmptyString"
+              }
+            }
+          }
+        },
+        "impureNamedImports": {
+          "description": "Names a gate must not import from a module that is otherwise fine. Default: PrismaClient from @prisma/client.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "defaults": {
+              "type": "boolean",
+              "default": true
+            },
+            "add": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["module", "names"],
+                "additionalProperties": false,
+                "properties": {
+                  "module": {
+                    "$ref": "#/definitions/nonEmptyString"
+                  },
+                  "names": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "$ref": "#/definitions/nonEmptyString"
+                    }
+                  },
+                  "reason": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "impurePaths": {
+          "description": "Gate paths that are rejected (regular expressions). Default: components and declaration files.",
+          "$ref": "#/definitions/ruleList"
+        },
+        "forbiddenSource": {
+          "description": "Lines that must not appear in a gate (regular expressions, tested one line at a time). Default: 'use client' / 'use server'.",
+          "$ref": "#/definitions/ruleList"
+        },
+        "importAliases": {
+          "description": "Import aliases, used to recognise a spec that mocks the module under test.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["prefix", "target"],
+            "additionalProperties": false,
+            "properties": {
+              "prefix": {
+                "$ref": "#/definitions/nonEmptyString"
+              },
+              "target": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "gateCommand": {
+          "description": "The command `test-gates selfcheck` runs. Default: `jest --config jest.gates.config.*` or `vitest run --config vitest.gates.config.*`, whichever config exists.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/nonEmptyString"
+          }
+        },
+        "selfcheck": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": {
+              "description": "Run the negative control for every gate, or only for the first.",
+              "enum": ["all", "first"],
+              "default": "all"
+            },
+            "failurePattern": {
+              "description": "Regular expression the output of the failing gate run must match. `{gate}` stands for the gate path. Default: a coverage threshold message on a line that names the gate.",
+              "$ref": "#/definitions/nonEmptyString"
+            }
+          }
+        },
+        "stryker": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "configFile": {
+              "description": "Default: stryker.gates.config.mjs (.js / .cjs / .json).",
+              "$ref": "#/definitions/nonEmptyString"
+            },
+            "reportFile": {
+              "description": "Where the Stryker JSON report is written and read.",
+              "$ref": "#/definitions/nonEmptyString",
+              "default": "reports/mutation/mutation.json"
+            }
+          }
+        },
+        "lcov": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "file": {
+              "description": "Tracefile for `test-gates lcov` when --file is not given.",
+              "$ref": "#/definitions/nonEmptyString"
+            },
+            "summaryExclude": {
+              "description": "Paths left out of the reference total (regular expressions).",
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/nonEmptyString"
+              }
+            }
+          }
+        },
+        "imports": {
+          "description": "Since 0.2.0. How runtime imports of a gate are judged.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": {
+              "description": "blocklist (default): only the impureImports rules apply. allowlist: in addition, a runtime import must be relative, go through an import alias, or be listed in allow; a project import must not point at a file matched by impurePaths; a computed require() / import() is rejected.",
+              "enum": ["blocklist", "allowlist"],
+              "default": "blocklist"
+            },
+            "allow": {
+              "description": "Packages a gate may import in allowlist mode. A string is a package name (its subpaths included). { pattern } is a regular expression tested against the specifier. { module, names } allows only those named imports.",
+              "type": "array",
+              "items": {
+                "oneOf": [
+                  {
+                    "$ref": "#/definitions/nonEmptyString"
+                  },
+                  {
+                    "type": "object",
+                    "required": ["pattern"],
+                    "additionalProperties": false,
+                    "properties": {
+                      "pattern": {
+                        "$ref": "#/definitions/nonEmptyString"
+                      },
+                      "flags": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "required": ["module", "names"],
+                    "additionalProperties": false,
+                    "properties": {
+                      "module": {
+                        "$ref": "#/definitions/nonEmptyString"
+                      },
+                      "names": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "$ref": "#/definitions/nonEmptyString"
+                        }
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "mutation": {
+          "description": "Since 0.2.0.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "maxTimeouts": {
+              "description": "How many timed-out mutants outside expectedTimeouts are tolerated. Above it the run fails. Not set: no limit.",
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    }
+  }
+}