@systemfsoftware/stryker-plugins 0.6.0 → 0.8.0

package/README.md

@@ -1,18 +1,13 @@
 # @systemfsoftware/stryker-plugins
 
-[Stryker](https://stryker-mutator.io) mutation-testing plugins for [Effect](https://effect.website).
+![version](https://img.shields.io/npm/v/@systemfsoftware/stryker-plugins)
+![license](https://img.shields.io/npm/l/@systemfsoftware/stryker-plugins)
 
-## `effect-schema-ignorer`
+> Stop Effect `Schema` declarations from dragging your Stryker score below 100%.
 
-A Stryker **Ignore** plugin (`effect-schema-declarations`) that skips the _equivalent_ mutants on Effect `Schema` declarations — mutations that change source without changing behaviour, so no test can ever kill them. It recognizes and ignores:
+A brand description, a `_tag`, a `title` — mutate any of them and the source changes but the behaviour does not, so no test can ever kill the mutant. Those unkillable mutants sit in your report forever, indistinguishable from real coverage gaps. This [Stryker](https://stryker-mutator.io) Ignore plugin removes them, so the score that remains is behaviour.
 
-- brand descriptions in `Symbol.for('…')`,
-- `Schema.TaggedClass` / `Schema.TaggedError` `_tag` identifiers,
-- the field schemas of those declarations.
-
-Schema declarations are **data, not behaviour** (Constitution Article III §4) — mutating them produces unkillable equivalent mutants that drag a mutation score below 100% for no real coverage gap. This plugin removes that noise so the score reflects logic.
-
-## Usage
+## Install
 
 ```bash
 pnpm add -D @systemfsoftware/stryker-plugins
@@ -31,5 +26,35 @@ In `stryker.config.json`:
 }
 ```
 
+Mutants it recognizes are reported as `Ignored`, each carrying the reason it was safe to skip.
+
 > [!NOTE]
 > `@stryker-mutator/api` is a peer dependency — your Stryker install provides it. `effect` is a direct dependency (the plugin decodes AST nodes with `Schema`).
+
+## What it ignores
+
+| Declaration                                               | Example                                                             |
+| --------------------------------------------------------- | ------------------------------------------------------------------- |
+| Brand descriptions                                        | `Symbol.for('UserId')`                                              |
+| `TaggedClass` / `TaggedError` tags                        | `S.TaggedClass<A>()('Placed', {…})`                                 |
+| The field schemas of those declarations                   | the `{…}` above                                                     |
+| `optionalWith` defaults                                   | `S.optionalWith(S.Number, { default: () => 0 })`                    |
+| Documentation annotations                                 | `identifier`, `description`, `title`, `documentation`, `examples`   |
+| An `annotations({…})` object that is _only_ documentation | `S.annotations({ title: 'Amount' })`                                |
+| A `TemplateLiteral` head a piped `pattern` already forces | `S.TemplateLiteral('usr', S.String).pipe(S.pattern(/^usr[a-z]*$/))` |
+
+## Where the line is
+
+Every ignore is proven redundant, never merely assumed — anything a test could observe keeps its mutants.
+
+`arbitrary`, `pretty`, `equivalence`, `message`, `jsonSchema` and `parseIssueTitle` are **not** documentation: each changes what the schema does, so a survivor there is a test gap to close. That is why the two `annotations` rules differ — a `title` is ignored wherever it appears, but the enclosing object is ignored only when every entry documents, since emptying an object holding an `arbitrary` would silently change what your property tests generate.
+
+The `TemplateLiteral` head is ignored only where the piped pattern makes it unobservable: the head must be the first span with no regex metacharacters, and the pattern must be an unflagged regex literal opening `^` + that head, with no quantifier making its final character optional. A head with no pattern keeps its mutants, and so do `/^usr?…/`, `/^usr…/i`, `/^usr…/m`, and every span past the first.
+
+## Contributing
+
+Development setup and workflow: [AGENTS.md](AGENTS.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/effect-schema-ignorer-C8RpAXcS.mjs

@@ -0,0 +1,154 @@
+import { PluginKind, declareValuePlugin } from "@stryker-mutator/api/plugin";
+import { Schema } from "effect";
+//#region src/effect-schema-ignorer/ast-node.schema.ts
+const Identifier = Schema.Struct({
+	type: Schema.Literal("Identifier"),
+	name: Schema.String
+});
+const StringLiteral = Schema.Struct({
+	type: Schema.Literal("StringLiteral"),
+	value: Schema.String
+});
+const RegExpLiteral = Schema.Struct({
+	type: Schema.Literal("RegExpLiteral"),
+	pattern: Schema.String,
+	flags: Schema.String
+});
+const ObjectExpression = Schema.Struct({ type: Schema.Literal("ObjectExpression") });
+const ArrowFunctionExpression = Schema.Struct({ type: Schema.Literal("ArrowFunctionExpression") });
+const UnknownNode = Schema.Struct({ type: Schema.String });
+const MemberExpression = Schema.suspend(() => Schema.Struct({
+	type: Schema.Literal("MemberExpression"),
+	object: Schema.suspend(() => AstNode),
+	property: Schema.suspend(() => AstNode)
+}));
+const CallExpression = Schema.suspend(() => Schema.Struct({
+	type: Schema.Literal("CallExpression"),
+	callee: Schema.suspend(() => AstNode),
+	arguments: Schema.Array(Schema.suspend(() => AstNode))
+}));
+const AstNode = Schema.suspend(() => Schema.Union(Identifier, StringLiteral, RegExpLiteral, ObjectExpression, ArrowFunctionExpression, MemberExpression, CallExpression, UnknownNode));
+//#endregion
+//#region src/effect-schema-ignorer/schema-declaration-ignore.ts
+const SYMBOL_DESCRIPTION_IGNORED = "Symbol.for() brand description is identity-only data, not behaviour";
+const TAGGED_TAG_IGNORED = "TaggedClass/TaggedError _tag is a declaration discriminant, not behaviour";
+const TAGGED_FIELDS_IGNORED = "TaggedClass/TaggedError field schema is a declaration, not behaviour";
+const OPTIONAL_DEFAULT_IGNORED = "optionalWith default value is config, not behaviour";
+const ANNOTATION_OBJECT_IGNORED = "annotations object holding only documentation is a declaration, not behaviour";
+const ANNOTATION_TEXT_IGNORED = "annotation documentation value is declaration data, not behaviour";
+const TEMPLATE_HEAD_IGNORED = "TemplateLiteral head re-stated by an anchored pattern filter is a declaration of the encoded type, not behaviour";
+/**
+* The Effect `Schema` annotations that describe a schema without changing what
+* it does. `arbitrary`, `pretty`, `equivalence`, `message`, `jsonSchema` and
+* `parseIssueTitle` are absent by design: each one alters observable behaviour,
+* so a surviving mutant of one is a test gap to close, never an equivalent
+* mutant to ignore.
+*/
+const DocumentationKey = Schema.Literal("identifier", "description", "title", "documentation", "examples");
+const DocumentationProperty = Schema.Struct({
+	type: Schema.Literal("ObjectProperty"),
+	computed: Schema.Literal(false),
+	key: Schema.Union(Schema.Struct({
+		type: Schema.Literal("Identifier"),
+		name: DocumentationKey
+	}), Schema.Struct({
+		type: Schema.Literal("StringLiteral"),
+		value: DocumentationKey
+	})),
+	value: Schema.Unknown
+});
+/**
+* An object literal whose every entry documents. One behaviour-bearing entry -
+* an `arbitrary` beside a `title` - fails the schema, so the object keeps its
+* mutants: emptying it would delete a generator, which a test can observe.
+*/
+const DocumentationObject = Schema.Struct({
+	type: Schema.Literal("ObjectExpression"),
+	properties: Schema.NonEmptyArray(DocumentationProperty)
+});
+const TAGGED_FACTORIES = ["TaggedClass", "TaggedError"];
+const isIdentifier = Schema.is(Identifier);
+const isStringLiteral = Schema.is(StringLiteral);
+const isObjectExpression = Schema.is(ObjectExpression);
+const isArrowFunctionExpression = Schema.is(ArrowFunctionExpression);
+const isMemberExpression = Schema.is(MemberExpression);
+const isCallExpression = Schema.is(CallExpression);
+const isDocumentationProperty = Schema.is(DocumentationProperty);
+const isDocumentationObject = Schema.is(DocumentationObject);
+const isRegExpLiteral = Schema.is(RegExpLiteral);
+const isNamedMember = (node, object, property) => isMemberExpression(node) && isIdentifier(node.object) && node.object.name === object && isIdentifier(node.property) && node.property.name === property;
+const isSymbolForCallee = (callee) => isNamedMember(callee, "Symbol", "for");
+const isTaggedFactoryReference = (reference) => isMemberExpression(reference) && isIdentifier(reference.property) && TAGGED_FACTORIES.includes(reference.property.name);
+const isTaggedFactoryCallee = (callee) => isCallExpression(callee) && isTaggedFactoryReference(callee.callee);
+const isArgumentOf = (node, parent, index, calleeMatches) => isCallExpression(parent) && calleeMatches(parent.callee) && parent.arguments[index] === node;
+const isOptionalWithCallee = (callee) => isNamedMember(callee, "S", "optionalWith");
+const isAnnotationsCallee = (callee) => isMemberExpression(callee) && isIdentifier(callee.property) && callee.property.name === "annotations";
+/**
+* A head whose every character stands for itself inside a regex. `a.b` is
+* excluded because `^a.b` would also admit `axb`, which the head refuses.
+*/
+const REGEX_INERT_HEAD = /^[A-Za-z0-9_]+$/;
+/** `?`, `*` and `{` make the character before them optional, so `^usr?` never forces the `r`. */
+const OPTIONAL_QUANTIFIERS = [
+	"?",
+	"*",
+	"{"
+];
+const isNamedMethodCallee = (callee, method) => isMemberExpression(callee) && isIdentifier(callee.property) && callee.property.name === method;
+/**
+* Whether an unflagged, `^`-anchored regex admits only strings opening with
+* `head`. Flags are refused outright: `i` would admit another casing and `m`
+* would let `^` match a line start, and the head rejects both — so it decides.
+*/
+const forcesPrefix = (regex, head) => isRegExpLiteral(regex) && regex.flags === "" && regex.pattern.startsWith(`^${head}`) && !OPTIONAL_QUANTIFIERS.includes(regex.pattern.charAt(head.length + 1));
+const patternForcesPrefix = (argument, head) => isCallExpression(argument) && isNamedMethodCallee(argument.callee, "pattern") && argument.arguments.some((regex) => forcesPrefix(regex, head));
+/**
+* The head of a `TemplateLiteral` piped straight into a `pattern` that already
+* forces that same prefix. Effect rejects refinements as spans, so a prefixed
+* wire format can only earn its `` `${head}${string}` `` type this way, and the
+* prefix ends up stated twice by construction. Emptying the head then changes
+* nothing observable: the filter still refuses every input the head would have
+* refused, and Effect derives the arbitrary from the filter's regex rather than
+* the head. Only the encoded *type* moves, which no test can see.
+*
+* Restricted to argument 0: a trailing span sits past the anchor, so an
+* anchored prefix proves nothing about it and its mutants stay.
+*/
+const templateHeadRule = {
+	matches: (node, parent, grandparent, ancestor) => isStringLiteral(node) && REGEX_INERT_HEAD.test(node.value) && isArgumentOf(node, parent, 0, (callee) => isNamedMethodCallee(callee, "TemplateLiteral")) && isMemberExpression(grandparent) && grandparent.object === parent && isIdentifier(grandparent.property) && grandparent.property.name === "pipe" && isCallExpression(ancestor) && ancestor.callee === grandparent && ancestor.arguments.some((argument) => patternForcesPrefix(argument, node.value)),
+	reason: TEMPLATE_HEAD_IGNORED
+};
+const argumentRule = (is, argumentIndex, calleeMatches, reason) => ({
+	matches: (node, parent) => is(node) && isArgumentOf(node, parent, argumentIndex, calleeMatches),
+	reason
+});
+/**
+* A documentation-keyed entry of an `annotations` call. Unlike the object rule
+* this does not care what sits beside it: `title` is documentation whether or
+* not an `arbitrary` shares the object, because replacing the title cannot
+* change what the schema does. Emptying the whole object could, which is why
+* that rule is the stricter of the two.
+*/
+const documentationValueRule = {
+	matches: (node, parent, grandparent, ancestor) => isDocumentationProperty(parent) && parent.value === node && isArgumentOf(grandparent, ancestor, 0, isAnnotationsCallee),
+	reason: ANNOTATION_TEXT_IGNORED
+};
+const RULES = [
+	argumentRule(isStringLiteral, 0, isSymbolForCallee, SYMBOL_DESCRIPTION_IGNORED),
+	argumentRule(isStringLiteral, 0, isTaggedFactoryCallee, TAGGED_TAG_IGNORED),
+	argumentRule(isObjectExpression, 1, isTaggedFactoryCallee, TAGGED_FIELDS_IGNORED),
+	argumentRule(isArrowFunctionExpression, 1, isOptionalWithCallee, OPTIONAL_DEFAULT_IGNORED),
+	argumentRule(isDocumentationObject, 0, isAnnotationsCallee, ANNOTATION_OBJECT_IGNORED),
+	documentationValueRule,
+	templateHeadRule
+];
+const decideSchemaDeclarationIgnore = (node, parent, grandparent, ancestor) => RULES.find((rule) => rule.matches(node, parent, grandparent, ancestor))?.reason;
+//#endregion
+//#region src/effect-schema-ignorer/index.ts
+const strykerPlugins = [declareValuePlugin(PluginKind.Ignore, "effect-schema-declarations", { shouldIgnore(path) {
+	const parent = path.parentPath;
+	const grandparent = parent?.parentPath;
+	return decideSchemaDeclarationIgnore(path.node, parent?.node, grandparent?.node, grandparent?.parentPath?.node);
+} })];
+//#endregion
+export { strykerPlugins as t };

package/dist/effect-schema-ignorer.mjs

@@ -1,2 +1,2 @@
-import { t as strykerPlugins } from "./effect-schema-ignorer-D-acEaX8.mjs";
+import { t as strykerPlugins } from "./effect-schema-ignorer-C8RpAXcS.mjs";
 export { strykerPlugins };

package/dist/index.mjs

@@ -1,5 +1,53 @@
-import { t as strykerPlugins$1 } from "./effect-schema-ignorer-D-acEaX8.mjs";
+import { t as strykerPlugins$2 } from "./effect-schema-ignorer-C8RpAXcS.mjs";
+import { PluginKind, declareValuePlugin } from "@stryker-mutator/api/plugin";
+import { Schema } from "effect";
+//#region src/in-source-test-ignorer/ast-node.schema.ts
+const Identifier = Schema.Struct({
+	type: Schema.Literal("Identifier"),
+	name: Schema.String
+});
+const AstLike = Schema.Struct({ type: Schema.String });
+const MetaProperty = Schema.Struct({
+	type: Schema.Literal("MetaProperty"),
+	meta: Identifier,
+	property: Identifier
+});
+const ImportMetaMember = Schema.Struct({
+	type: Schema.Literal("MemberExpression"),
+	object: MetaProperty,
+	property: Identifier
+});
+const BinaryExpression = Schema.Struct({
+	type: Schema.Literal("BinaryExpression"),
+	left: AstLike,
+	right: AstLike
+});
+const IfStatement = Schema.Struct({
+	type: Schema.Literal("IfStatement"),
+	test: AstLike
+});
+//#endregion
+//#region src/in-source-test-ignorer/in-source-test-ignore.ts
+const IN_SOURCE_TEST_IGNORED = "inside an `if (import.meta.vitest)` block — test code, not production behaviour";
+const isImportMetaMember = Schema.is(ImportMetaMember);
+const isBinaryExpression = Schema.is(BinaryExpression);
+const isIfStatement = Schema.is(IfStatement);
+const isImportMetaVitest = (node) => isImportMetaMember(node) && node.object.meta.name === "import" && node.object.property.name === "meta" && node.property.name === "vitest";
+const guardsOnImportMetaVitest = (test) => isImportMetaVitest(test) || isBinaryExpression(test) && (isImportMetaVitest(test.left) || isImportMetaVitest(test.right));
+const isInSourceTestGuard = (node) => isIfStatement(node) && guardsOnImportMetaVitest(node.test);
+const decideInSourceTestIgnore = (ancestors) => {
+	for (const ancestor of ancestors) if (isInSourceTestGuard(ancestor)) return IN_SOURCE_TEST_IGNORED;
+};
+//#endregion
+//#region src/in-source-test-ignorer/index.ts
+function* ancestorsOf(path) {
+	for (let current = path.parentPath; current; current = current.parentPath) yield current.node;
+}
+const strykerPlugins$1 = [declareValuePlugin(PluginKind.Ignore, "in-source-vitest-block", { shouldIgnore(path) {
+	return decideInSourceTestIgnore(ancestorsOf(path));
+} })];
+//#endregion
 //#region src/mod.ts
-const strykerPlugins = [...strykerPlugins$1];
+const strykerPlugins = [...strykerPlugins$2, ...strykerPlugins$1];
 //#endregion
 export { strykerPlugins };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@systemfsoftware/stryker-plugins",
   "license": "MIT",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "author": "Ryan Lee <drdgvhbh@gmail.com>",
   "repository": {
     "type": "git",
@@ -53,8 +53,8 @@
     "vitest": "^4",
     "@systemfsoftware/arethetypeswrong-cli": "^1.0.7",
     "@systemfsoftware/effect-schema-law": "^0.5.0",
-    "@systemfsoftware/effect-schema-vite": "^1.3.0",
     "@systemfsoftware/oxlint-config": "^0.1.0",
+    "@systemfsoftware/effect-schema-vite": "^1.4.0",
     "@systemfsoftware/stryker-js-core": "^1.1.6",
     "@systemfsoftware/tsconfig": "^1.2.6",
     "@systemfsoftware/vitest-config": "^0.1.0",

package/dist/effect-schema-ignorer-D-acEaX8.mjs

@@ -1,78 +0,0 @@
-import { PluginKind, declareValuePlugin } from "@stryker-mutator/api/plugin";
-import { Schema } from "effect";
-//#region src/effect-schema-ignorer/ast-node.schema.ts
-const Identifier = Schema.Struct({
-	type: Schema.Literal("Identifier"),
-	name: Schema.String
-});
-const StringLiteral = Schema.Struct({
-	type: Schema.Literal("StringLiteral"),
-	value: Schema.String
-});
-const ObjectExpression = Schema.Struct({ type: Schema.Literal("ObjectExpression") });
-const ArrowFunctionExpression = Schema.Struct({ type: Schema.Literal("ArrowFunctionExpression") });
-const UnknownNode = Schema.Struct({ type: Schema.String });
-const MemberExpression = Schema.suspend(() => Schema.Struct({
-	type: Schema.Literal("MemberExpression"),
-	object: Schema.suspend(() => AstNode),
-	property: Schema.suspend(() => AstNode)
-}));
-const CallExpression = Schema.suspend(() => Schema.Struct({
-	type: Schema.Literal("CallExpression"),
-	callee: Schema.suspend(() => AstNode),
-	arguments: Schema.Array(Schema.suspend(() => AstNode))
-}));
-const AstNode = Schema.suspend(() => Schema.Union(Identifier, StringLiteral, ObjectExpression, ArrowFunctionExpression, MemberExpression, CallExpression, UnknownNode));
-//#endregion
-//#region src/effect-schema-ignorer/schema-declaration-ignore.ts
-const SYMBOL_DESCRIPTION_IGNORED = "Symbol.for() brand description is identity-only data, not behaviour";
-const TAGGED_TAG_IGNORED = "TaggedClass/TaggedError _tag is a declaration discriminant, not behaviour";
-const TAGGED_FIELDS_IGNORED = "TaggedClass/TaggedError field schema is a declaration, not behaviour";
-const OPTIONAL_DEFAULT_IGNORED = "optionalWith default value is config, not behaviour";
-const TAGGED_FACTORIES = ["TaggedClass", "TaggedError"];
-const isIdentifier = Schema.is(Identifier);
-const isStringLiteral = Schema.is(StringLiteral);
-const isObjectExpression = Schema.is(ObjectExpression);
-const isArrowFunctionExpression = Schema.is(ArrowFunctionExpression);
-const isMemberExpression = Schema.is(MemberExpression);
-const isCallExpression = Schema.is(CallExpression);
-const isNamedMember = (node, object, property) => isMemberExpression(node) && isIdentifier(node.object) && node.object.name === object && isIdentifier(node.property) && node.property.name === property;
-const isSymbolForCallee = (callee) => isNamedMember(callee, "Symbol", "for");
-const isTaggedFactoryReference = (reference) => isMemberExpression(reference) && isIdentifier(reference.property) && TAGGED_FACTORIES.includes(reference.property.name);
-const isTaggedFactoryCallee = (callee) => isCallExpression(callee) && isTaggedFactoryReference(callee.callee);
-const isArgumentOf = (node, parent, index, calleeMatches) => isCallExpression(parent) && calleeMatches(parent.callee) && parent.arguments[index] === node;
-const isOptionalWithCallee = (callee) => isNamedMember(callee, "S", "optionalWith");
-const RULES = [
-	{
-		is: isStringLiteral,
-		argumentIndex: 0,
-		calleeMatches: isSymbolForCallee,
-		reason: SYMBOL_DESCRIPTION_IGNORED
-	},
-	{
-		is: isStringLiteral,
-		argumentIndex: 0,
-		calleeMatches: isTaggedFactoryCallee,
-		reason: TAGGED_TAG_IGNORED
-	},
-	{
-		is: isObjectExpression,
-		argumentIndex: 1,
-		calleeMatches: isTaggedFactoryCallee,
-		reason: TAGGED_FIELDS_IGNORED
-	},
-	{
-		is: isArrowFunctionExpression,
-		argumentIndex: 1,
-		calleeMatches: isOptionalWithCallee,
-		reason: OPTIONAL_DEFAULT_IGNORED
-	}
-];
-const decideSchemaDeclarationIgnore = (node, parent) => RULES.find((rule) => rule.is(node) && isArgumentOf(node, parent, rule.argumentIndex, rule.calleeMatches))?.reason;
-//#endregion
-//#region src/effect-schema-ignorer/index.ts
-const strykerPlugins = [declareValuePlugin(PluginKind.Ignore, "effect-schema-declarations", { shouldIgnore(path) {
-	return decideSchemaDeclarationIgnore(path.node, path.parentPath?.node);
-} })];
-//#endregion
-export { strykerPlugins as t };