oxlint-plugin-effect 0.8.2 → 0.9.0

package/README.md

@@ -25,23 +25,26 @@ If the project uses JSON configuration, copy the exported rule map into `rules`;
 
 ## Recommended Rules
 
-| Rule                          | Contract                                                                                  |
-| ----------------------------- | ----------------------------------------------------------------------------------------- |
-| `effect/noAs`                 | Bans TypeScript `as` assertions; use `satisfies`                                          |
-| `effect/noAsyncFunction`      | Bans async functions and await expressions                                                |
-| `effect/noTryCatch`           | Bans every try/catch/finally statement                                                    |
-| `effect/noTestLifecycleHooks` | Bans `beforeEach`, `afterEach`, `beforeAll`, and `afterAll`; use Effect scopes instead    |
-| `effect/noThrowStatement`     | Bans every throw statement                                                                |
-| `effect/noNewPromise`         | Bans new Promise, Promise calls, and Promise static APIs                                  |
-| `effect/noNewError`           | Allows native Error values only as direct arguments to Effect.die, Cause.die, or Exit.die |
-| `effect/noNullish`            | Bans null and undefined; use Option or a domain enum for richer state                     |
-| `effect/noTernary`            | Bans conditional expressions while allowing ordinary if statements                        |
-| `effect/noDynamicImports`     | Allows import() only behind a named lazy-loading boundary; bans require()                 |
-| `effect/noEffectDo`           | Bans Effect.Do                                                                            |
-| `effect/noEffectBind`         | Bans Effect.bind                                                                          |
-| `effect/preferEffectFn`       | Requires `Effect.fn` for a generator operation that adds a span                           |
-| `effect/noGlobals`            | Bans ambient capabilities with direct Effect replacements; allows `process.std*.isTTY`    |
-| `effect/noNodeBuiltinImport`  | Bans fully replaced Node modules and replaced operations from partial modules             |
+| Rule                               | Contract                                                                                  |
+| ---------------------------------- | ----------------------------------------------------------------------------------------- |
+| `effect/noAs`                      | Bans TypeScript `as` assertions; use `satisfies`                                          |
+| `effect/noAsyncFunction`           | Bans async functions and await expressions                                                |
+| `effect/noTryCatch`                | Bans every try/catch/finally statement                                                    |
+| `effect/noTestLifecycleHooks`      | Bans `beforeEach`, `afterEach`, `beforeAll`, and `afterAll`; use Effect scopes instead    |
+| `effect/noThrowStatement`          | Bans every throw statement                                                                |
+| `effect/noNewPromise`              | Bans new Promise, Promise calls, and Promise static APIs                                  |
+| `effect/noNewError`                | Allows native Error values only as direct arguments to Effect.die, Cause.die, or Exit.die |
+| `effect/noNullish`                 | Bans null and undefined; use Option or a domain enum for richer state                     |
+| `effect/noTernary`                 | Bans conditional expressions while allowing ordinary if statements                        |
+| `effect/noDynamicImports`          | Allows import() only behind a named lazy-loading boundary; bans require()                 |
+| `effect/noEffectDo`                | Bans Effect.Do                                                                            |
+| `effect/noEffectBind`              | Bans Effect.bind                                                                          |
+| `effect/preferCatchTag`            | Replaces manual `_tag` predicates in `Effect.catchIf` with tagged recovery                |
+| `effect/preferEffectFn`            | Requires `Effect.fn` for a generator operation that adds a span                           |
+| `effect/preferMatchTagsExhaustive` | Requires exhaustive `Match` for return-only `_tag` switches                               |
+| `effect/preferPredicateIsTagged`   | Replaces combined `_tag` comparisons with a named `Predicate` refinement                  |
+| `effect/noGlobals`                 | Bans ambient capabilities with direct Effect replacements; allows `process.std*.isTTY`    |
+| `effect/noNodeBuiltinImport`       | Bans fully replaced Node modules and replaced operations from partial modules             |
 
 ## Anti-Slop Rules
 
@@ -63,7 +66,7 @@ The recommended preset also includes these rules from
 
 See `THIRD_PARTY_NOTICES.md` for the source revision and license.
 
-The preset intentionally allows `Effect.as`, `Option.as`, `Effect.never`, `Effect.async`, ordinary `if` and `switch` statements, and runtime runners at explicit application boundaries.
+The preset intentionally allows `Effect.as`, `Option.as`, `Effect.never`, `Effect.async`, simple `_tag` guards, partial or stateful `switch` statements, and runtime runners at explicit application boundaries.
 
 ## Platform Boundaries
 

package/dist/presets/recommended.d.ts

@@ -29,7 +29,10 @@ declare const recommended: {
   readonly "effect/noUnknownTypeAliases": "error";
   readonly "effect/noUnsafeDictionaryType": "error";
   readonly "effect/noWidenThenAssert": "error";
+  readonly "effect/preferCatchTag": "error";
   readonly "effect/preferEffectFn": "error";
+  readonly "effect/preferMatchTagsExhaustive": "error";
+  readonly "effect/preferPredicateIsTagged": "error";
 };
 //#endregion
 export { recommended };

package/dist/presets/recommended.js

@@ -29,7 +29,10 @@ const recommended = {
 	"effect/noUnknownTypeAliases": "error",
 	"effect/noUnsafeDictionaryType": "error",
 	"effect/noWidenThenAssert": "error",
-	"effect/preferEffectFn": "error"
+	"effect/preferCatchTag": "error",
+	"effect/preferEffectFn": "error",
+	"effect/preferMatchTagsExhaustive": "error",
+	"effect/preferPredicateIsTagged": "error"
 };
 //#endregion
 export { recommended };

package/dist/rules/_tagged-control-flow.js

@@ -0,0 +1,79 @@
+//#region src/rules/_tagged-control-flow.ts
+const expressionKey = (node) => {
+	if (node.type === "Identifier") return node.name;
+	if (node.type === "ThisExpression") return "this";
+	if (node.type !== "MemberExpression" || node.computed || node.property.type !== "Identifier") return null;
+	const object = expressionKey(node.object);
+	if (object === null) return null;
+	return `${object}.${node.property.name}`;
+};
+const stringLiteral = (node) => {
+	if (node.type !== "Literal") return null;
+	if (typeof node.value !== "string") return null;
+	return node.value;
+};
+const taggedSubject = (node) => {
+	if (node.type !== "MemberExpression" || node.computed || node.property.type !== "Identifier" || node.property.name !== "_tag") return null;
+	return expressionKey(node.object);
+};
+const tagComparison = (node) => {
+	if (node.type !== "BinaryExpression" || node.operator !== "===") return null;
+	const leftSubject = taggedSubject(node.left);
+	const rightTag = stringLiteral(node.right);
+	if (leftSubject !== null && rightTag !== null) return {
+		subject: leftSubject,
+		tag: rightTag
+	};
+	const rightSubject = taggedSubject(node.right);
+	const leftTag = stringLiteral(node.left);
+	if (rightSubject === null || leftTag === null) return null;
+	return {
+		subject: rightSubject,
+		tag: leftTag
+	};
+};
+const tagComparisonsInOr = (node) => {
+	if (node.type === "LogicalExpression" && node.operator === "||") {
+		const left = tagComparisonsInOr(node.left);
+		const right = tagComparisonsInOr(node.right);
+		if (left === null || right === null) return null;
+		return [...left, ...right];
+	}
+	const comparison = tagComparison(node);
+	if (comparison === null) return null;
+	return [comparison];
+};
+const hasOneTaggedSubject = (comparisons) => {
+	const first = comparisons[0];
+	if (first === void 0 || comparisons.length < 2) return false;
+	return comparisons.every((comparison) => comparison.subject === first.subject);
+};
+const isEffectCall = (node, operation) => node.callee.type !== "Super" && node.callee.type === "MemberExpression" && !node.callee.computed && node.callee.object.type === "Identifier" && node.callee.object.name === "Effect" && node.callee.property.type === "Identifier" && node.callee.property.name === operation;
+const isFunction = (node) => node?.type === "ArrowFunctionExpression" || node?.type === "FunctionExpression";
+const effectCallbackLocation = (node, operation) => {
+	let current = node.parent;
+	while (current !== void 0 && current !== null) {
+		if (isFunction(current)) {
+			const call = current.parent;
+			if (call?.type !== "CallExpression" || !isEffectCall(call, operation)) return null;
+			const index = call.arguments.indexOf(current);
+			if (index < 0) return null;
+			return {
+				argumentCount: call.arguments.length,
+				index
+			};
+		}
+		current = current.parent;
+	}
+	return null;
+};
+const isInsideCatchAllHandler = (node) => {
+	const location = effectCallbackLocation(node, "catchAll");
+	if (location === null) return false;
+	let handlerIndex = 1;
+	if (location.argumentCount === 1) handlerIndex = 0;
+	return location.index === handlerIndex;
+};
+const taggedSwitchSubject = (node) => taggedSubject(node.discriminant);
+//#endregion
+export { effectCallbackLocation, hasOneTaggedSubject, isEffectCall, isInsideCatchAllHandler, tagComparisonsInOr, taggedSwitchSubject };

package/dist/rules/index.d.ts

@@ -22,11 +22,14 @@ import { noUnknownParameters } from "./no-unknown-parameters.js";
 import { noUnknownTypeAliases } from "./no-unknown-type-aliases.js";
 import { noUnsafeDictionaryType } from "./no-unsafe-dictionary-type.js";
 import { noWidenThenAssert } from "./no-widen-then-assert.js";
+import { preferCatchTag } from "./prefer-catch-tag.js";
 import { preferEffectFn } from "./prefer-effect-fn.js";
+import { preferMatchTagsExhaustive } from "./prefer-match-tags-exhaustive.js";
+import { preferPredicateIsTagged } from "./prefer-predicate-is-tagged.js";
 
 //#region src/rules/index.d.ts
 declare namespace index_d_exports {
-  export { noAs, noAsyncFunction, noChainedTypeAssertions, noConditionalEmptyObjectSpread, noDynamicImports, noEffectBind, noEffectDo, noGlobals, noKnownValueWidening, noNewError, noNewPromise, noNodeBuiltinImport, noNullish, noObjectParameters, noRuntimeTypeof, noShapeInSymbolNames, noTernary, noTestLifecycleHooks, noThrowStatement, noTryCatch, noUnknownParameters, noUnknownTypeAliases, noUnsafeDictionaryType, noWidenThenAssert, preferEffectFn };
+  export { noAs, noAsyncFunction, noChainedTypeAssertions, noConditionalEmptyObjectSpread, noDynamicImports, noEffectBind, noEffectDo, noGlobals, noKnownValueWidening, noNewError, noNewPromise, noNodeBuiltinImport, noNullish, noObjectParameters, noRuntimeTypeof, noShapeInSymbolNames, noTernary, noTestLifecycleHooks, noThrowStatement, noTryCatch, noUnknownParameters, noUnknownTypeAliases, noUnsafeDictionaryType, noWidenThenAssert, preferCatchTag, preferEffectFn, preferMatchTagsExhaustive, preferPredicateIsTagged };
 }
 //#endregion
 export { index_d_exports };

package/dist/rules/index.js

@@ -23,7 +23,10 @@ import { noUnknownParameters } from "./no-unknown-parameters.js";
 import { noUnknownTypeAliases } from "./no-unknown-type-aliases.js";
 import { noUnsafeDictionaryType } from "./no-unsafe-dictionary-type.js";
 import { noWidenThenAssert } from "./no-widen-then-assert.js";
+import { preferCatchTag } from "./prefer-catch-tag.js";
 import { preferEffectFn } from "./prefer-effect-fn.js";
+import { preferMatchTagsExhaustive } from "./prefer-match-tags-exhaustive.js";
+import { preferPredicateIsTagged } from "./prefer-predicate-is-tagged.js";
 //#region src/rules/index.ts
 var rules_exports = /* @__PURE__ */ __exportAll({
 	noAs: () => noAs,
@@ -50,7 +53,10 @@ var rules_exports = /* @__PURE__ */ __exportAll({
 	noUnknownTypeAliases: () => noUnknownTypeAliases,
 	noUnsafeDictionaryType: () => noUnsafeDictionaryType,
 	noWidenThenAssert: () => noWidenThenAssert,
-	preferEffectFn: () => preferEffectFn
+	preferCatchTag: () => preferCatchTag,
+	preferEffectFn: () => preferEffectFn,
+	preferMatchTagsExhaustive: () => preferMatchTagsExhaustive,
+	preferPredicateIsTagged: () => preferPredicateIsTagged
 });
 //#endregion
 export { rules_exports };

package/dist/rules/prefer-catch-tag.d.ts

@@ -0,0 +1,6 @@
+import * as _$_oxlint_plugins0 from "@oxlint/plugins";
+
+//#region src/rules/prefer-catch-tag.d.ts
+declare const preferCatchTag: _$_oxlint_plugins0.CreateRule;
+//#endregion
+export { preferCatchTag };

package/dist/rules/prefer-catch-tag.js

@@ -0,0 +1,48 @@
+import { make } from "../vendor/effect-oxlint/Diagnostic.js";
+import { RuleContext } from "../vendor/effect-oxlint/RuleContext.js";
+import { define, meta } from "../vendor/effect-oxlint/Rule.js";
+import "../vendor/effect-oxlint/index.js";
+import { isEffectCall, tagComparisonsInOr } from "./_tagged-control-flow.js";
+import * as Effect from "effect/Effect";
+//#region src/rules/prefer-catch-tag.ts
+const returnedExpression = (fn) => {
+	if (fn.body === null) return null;
+	if (fn.body.type !== "BlockStatement") return fn.body;
+	if (fn.body.body.length !== 1) return null;
+	const statement = fn.body.body[0];
+	if (statement?.type !== "ReturnStatement" || statement.argument === null) return null;
+	return statement.argument;
+};
+const hasManualTagPredicate = (argument) => {
+	if (argument?.type !== "ArrowFunctionExpression" && argument?.type !== "FunctionExpression") return false;
+	const parameter = argument.params[0];
+	if (parameter?.type !== "Identifier") return false;
+	const expression = returnedExpression(argument);
+	if (expression === null) return false;
+	const comparisons = tagComparisonsInOr(expression);
+	if (comparisons === null || comparisons.length === 0) return false;
+	return comparisons.every((comparison) => comparison.subject === parameter.name);
+};
+const preferCatchTag = define({
+	name: "prefer-catch-tag",
+	meta: meta({
+		type: "suggestion",
+		description: "Use Effect.catchTag or Effect.catchTags for tagged failures."
+	}),
+	create: function* () {
+		const context = yield* RuleContext;
+		return { CallExpression: (node) => {
+			if (!isEffectCall(node, "catchIf")) return Effect.void;
+			let predicateIndex = 1;
+			if (node.arguments.length === 2) predicateIndex = 0;
+			const predicate = node.arguments[predicateIndex];
+			if (!hasManualTagPredicate(predicate)) return Effect.void;
+			return context.report(make({
+				node,
+				message: "Use Effect.catchTag for one tagged failure or Effect.catchTags for multiple tagged failures."
+			}));
+		} };
+	}
+});
+//#endregion
+export { preferCatchTag };

package/dist/rules/prefer-match-tags-exhaustive.d.ts

@@ -0,0 +1,6 @@
+import * as _$_oxlint_plugins0 from "@oxlint/plugins";
+
+//#region src/rules/prefer-match-tags-exhaustive.d.ts
+declare const preferMatchTagsExhaustive: _$_oxlint_plugins0.CreateRule;
+//#endregion
+export { preferMatchTagsExhaustive };

package/dist/rules/prefer-match-tags-exhaustive.js

@@ -0,0 +1,46 @@
+import { make } from "../vendor/effect-oxlint/Diagnostic.js";
+import { RuleContext } from "../vendor/effect-oxlint/RuleContext.js";
+import { define, meta } from "../vendor/effect-oxlint/Rule.js";
+import "../vendor/effect-oxlint/index.js";
+import { isInsideCatchAllHandler, taggedSwitchSubject } from "./_tagged-control-flow.js";
+import * as Effect from "effect/Effect";
+//#region src/rules/prefer-match-tags-exhaustive.ts
+const statementReturns = (statement) => {
+	if (statement.type === "ReturnStatement") return true;
+	if (statement.type !== "BlockStatement") return false;
+	const last = statement.body.at(-1);
+	if (last === void 0) return false;
+	return statementReturns(last);
+};
+const caseReturns = (switchCase) => {
+	const last = switchCase.consequent.at(-1);
+	if (last === void 0) return false;
+	return statementReturns(last);
+};
+const isCompleteTransformationShape = (node) => {
+	if (node.cases.length < 2 || taggedSwitchSubject(node) === null) return false;
+	for (const switchCase of node.cases) {
+		if (switchCase.test === null || switchCase.test.type !== "Literal") return false;
+		if (typeof switchCase.test.value !== "string" || !caseReturns(switchCase)) return false;
+	}
+	return true;
+};
+const preferMatchTagsExhaustive = define({
+	name: "prefer-match-tags-exhaustive",
+	meta: meta({
+		type: "suggestion",
+		description: "Use Match.tagsExhaustive for a complete tagged-union transformation."
+	}),
+	create: function* () {
+		const context = yield* RuleContext;
+		return { SwitchStatement: (node) => {
+			if (!isCompleteTransformationShape(node) || isInsideCatchAllHandler(node)) return Effect.void;
+			return context.report(make({
+				node,
+				message: "Use Match.type with Match.tagsExhaustive so a new tagged variant requires a new case."
+			}));
+		} };
+	}
+});
+//#endregion
+export { preferMatchTagsExhaustive };

package/dist/rules/prefer-predicate-is-tagged.d.ts

@@ -0,0 +1,6 @@
+import * as _$_oxlint_plugins0 from "@oxlint/plugins";
+
+//#region src/rules/prefer-predicate-is-tagged.d.ts
+declare const preferPredicateIsTagged: _$_oxlint_plugins0.CreateRule;
+//#endregion
+export { preferPredicateIsTagged };

package/dist/rules/prefer-predicate-is-tagged.js

@@ -0,0 +1,37 @@
+import { make } from "../vendor/effect-oxlint/Diagnostic.js";
+import { RuleContext } from "../vendor/effect-oxlint/RuleContext.js";
+import { define, meta } from "../vendor/effect-oxlint/Rule.js";
+import "../vendor/effect-oxlint/index.js";
+import { effectCallbackLocation, hasOneTaggedSubject, tagComparisonsInOr } from "./_tagged-control-flow.js";
+import * as Effect from "effect/Effect";
+//#region src/rules/prefer-predicate-is-tagged.ts
+const isCatchIfPredicate = (node) => {
+	const location = effectCallbackLocation(node, "catchIf");
+	if (location === null) return false;
+	let predicateIndex = 1;
+	if (location.argumentCount === 2) predicateIndex = 0;
+	return location.index === predicateIndex;
+};
+const preferPredicateIsTagged = define({
+	name: "prefer-predicate-is-tagged",
+	meta: meta({
+		type: "suggestion",
+		description: "Use Predicate.isTagged for combined tagged-value narrowing."
+	}),
+	create: function* () {
+		const context = yield* RuleContext;
+		return { LogicalExpression: (node) => {
+			if (node.operator !== "||") return Effect.void;
+			if (node.parent?.type === "LogicalExpression" && node.parent.operator === "||") return Effect.void;
+			if (isCatchIfPredicate(node)) return Effect.void;
+			const comparisons = tagComparisonsInOr(node);
+			if (comparisons === null || !hasOneTaggedSubject(comparisons)) return Effect.void;
+			return context.report(make({
+				node,
+				message: "Use a named Predicate refinement composed from Predicate.isTagged for multiple tags."
+			}));
+		} };
+	}
+});
+//#endregion
+export { preferPredicateIsTagged };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxlint-plugin-effect",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "oxlint plugin with Effect-specific lint rules",
   "license": "MIT",
   "repository": {