@commonplaces/oxlint-plugin 0.6.2 → 0.7.0

package/README.md

@@ -1,7 +1,7 @@
 # @commonplaces/oxlint-plugin
 
-107 custom Oxlint rules for strict Effect TypeScript, Alchemy and general code
-checks. Version 0.6.1 supports **Oxlint 1.87.0, 1.88.0 or 1.89.0** and **Node 22.14 or newer**.
+108 custom Oxlint rules for strict Effect TypeScript, Alchemy and general code
+checks. Version 0.7.0 supports **Oxlint 1.87.0, 1.88.0 or 1.89.0** and **Node 22.14 or newer**.
 Oxlint's JavaScript plugin API is experimental, so upgrade it only after running
 the rule tests. The development tools use 1.89.0; consuming projects may use any supported version.
 All three exact versions are checked with independently installed archives. ESLint is not a supported host.
@@ -12,14 +12,14 @@ Effect setup below after dependency installation.
 
 ## Install
 
-Install version 0.6.1 and save its exact version:
+Install version 0.7.0 and save its exact version:
 
 ```sh
-npm install --save-dev --save-exact @commonplaces/oxlint-plugin@0.6.1 \
+npm install --save-dev --save-exact @commonplaces/oxlint-plugin@0.7.0 \
   @effect/tsgo@0.55.0 oxlint@1.89.0 oxlint-tsgolint@7.0.2004 typescript@7.0.2
 ```
 
-Version 0.6.1 supports exactly Oxlint 1.87.0, 1.88.0 or 1.89.0. Older releases
+Version 0.7.0 supports exactly Oxlint 1.87.0, 1.88.0 or 1.89.0. Older releases
 keep their earlier host lists. Consumer adoption is a separate step.
 
 The manifest and lockfile retain the resolved version. Historical GitHub release
@@ -433,6 +433,23 @@ are bounded directory prefixes; this is not a TypeScript, bundler, conditional
 export or symlink resolver. Same-owner asset queries are allowed; `file:` imports
 are unsupported and rejected. Invalid or contradictory options fail closed.
 
+### HTTP response-body error classification
+
+The `effect` and `strict` groups enable `strict-effect/http-client-error-classification`.
+Effect's HTTP `DecodeError` includes connection failures while reading a response
+body. Do not map every `DecodeError` to a payload/integrity failure while mapping
+`TransportError` to unavailability. Use the transport recovery path by default;
+distinguish deliberate size limits or other payload failures with a tagged cause.
+Keep malformed JSON/schema errors separate and test failure after response headers.
+
+The rule checks native `Match.tags`/`tagsExhaustive` tables containing
+`DecodeError`, `TransportError` and `StatusCodeError`. It rejects unconditional
+results using different error constructors, following immutable local aliases,
+simple return helpers and `Effect.fail`/`succeed`. Imported aliases and shadowing
+are respected. It does not prove conditional branches, opaque helpers, computed
+tables or other dispatch styles: behavioural tests still own their semantics.
+There are no project-specific names, configuration options or automatic fixes.
+
 ### Subprocess pipe capture
 
 The `effect` group enables `strict-effect/subprocess-pipe-capture`. It follows

package/dist/http-client-error-classification.d.ts

@@ -0,0 +1 @@
+export declare const httpClientErrorClassification: import("@oxlint/plugins").Rule;

package/dist/http-client-error-classification.js

@@ -0,0 +1,93 @@
+import { defineRule } from "@oxlint/plugins";
+import { Array, Option } from "effect";
+import { constant, operation, referenceOf, valueOf } from "./native-reference.js";
+import { propertyName, variableInScope } from "./syntax.js";
+// Only prove unconditional constructor results. Conditional cause checks and
+// opaque helpers need behavioural tests; this rule does not infer their meaning.
+const constructedError = (context, input, visited = []) => {
+    if (Array.some(visited, (previous) => previous === input))
+        return Option.none();
+    const next = [...visited, input];
+    return valueOf(context, input).pipe(Option.flatMap((node) => {
+        if (node.type === "NewExpression")
+            return Option.some(node.callee);
+        if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") {
+            const body = node.body;
+            if (!body)
+                return Option.none();
+            if (body.type !== "BlockStatement")
+                return constructedError(context, body, next);
+            return Array.head(body.body).pipe(Option.filter(() => body.body.length === 1), Option.filter((statement) => statement.type === "ReturnStatement"), Option.flatMap((statement) => Option.fromNullishOr(statement.argument)), Option.flatMap((result) => constructedError(context, result, next)));
+        }
+        if (node.type !== "CallExpression")
+            return Option.none();
+        if (operation(context, node.callee, "effect/Effect", "fail") ||
+            operation(context, node.callee, "effect/Effect", "succeed"))
+            return Array.head(node.arguments).pipe(Option.flatMap((argument) => constructedError(context, argument, next)));
+        return constructedError(context, node.callee, next);
+    }));
+};
+const localClass = (context, node, visited = []) => {
+    if (Array.some(visited, (previous) => previous === node))
+        return Option.none();
+    if (node.type === "ClassExpression")
+        return Option.some(node);
+    if (node.type !== "Identifier")
+        return Option.none();
+    return variableInScope(context.sourceCode.getScope(node), node.name).pipe(Option.filter((variable) => Array.every(variable.references, (reference) => !reference.isWrite() || reference.init)), Option.flatMap((variable) => constant(variable).pipe(Option.flatMap((declaration) => Option.fromNullishOr(declaration.init)), Option.flatMap((initialiser) => localClass(context, initialiser, [...visited, node])), Option.orElse(() => Array.head(variable.defs).pipe(Option.filter(() => variable.defs.length === 1), Option.map((definition) => definition.node), Option.filter((definition) => definition.type === "ClassDeclaration"))))));
+};
+const differentConstructors = (context, left, right) => {
+    const imported = Option.all([referenceOf(context, left), referenceOf(context, right)]);
+    if (Option.isSome(imported)) {
+        const [a, b] = imported.value;
+        return (a.module !== b.module || !Option.makeEquivalence((x, y) => x === y)(a.name, b.name));
+    }
+    return Option.exists(Option.all([localClass(context, left), localClass(context, right)]), ([a, b]) => a !== b);
+};
+const handler = (table, name) => Array.findLast(table.properties, (property) => property.type === "Property" && Option.contains(propertyName(property.key), name)).pipe(Option.flatMap((property) => property.type === "Property" ? Option.some(property.value) : Option.none()));
+export const httpClientErrorClassification = defineRule({
+    meta: {
+        type: "problem",
+        schema: [],
+        messages: {
+            classification: "HTTP DecodeError also covers failed response-body reads. Use the TransportError recovery path unless you inspect a separately tagged payload failure; do not classify every DecodeError as a different domain error.",
+        },
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (!operation(context, node.callee, "effect/Match", "tags") &&
+                    !operation(context, node.callee, "effect/Match", "tagsExhaustive"))
+                    return;
+                const table = Array.head(node.arguments).pipe(Option.flatMap((argument) => valueOf(context, argument)), Option.filter((value) => value.type === "ObjectExpression"), 
+                // Do not guess which handler an unresolved spread/computed key replaces.
+                Option.filter((value) => Array.every(value.properties, (property) => property.type === "Property" &&
+                    (!property.computed || property.key.type === "Literal"))));
+                Option.match(table, {
+                    onNone: () => { },
+                    onSome: (table) => {
+                        // This distinctive native reason table avoids domain DecodeError
+                        // unions and does not depend on project-specific error names.
+                        if (Option.isNone(handler(table, "StatusCodeError")))
+                            return;
+                        const handlers = Option.all([
+                            handler(table, "DecodeError"),
+                            handler(table, "TransportError"),
+                        ]);
+                        Option.match(handlers, {
+                            onNone: () => { },
+                            onSome: ([decode, transport]) => {
+                                const errors = Option.all([
+                                    constructedError(context, decode),
+                                    constructedError(context, transport),
+                                ]);
+                                if (Option.exists(errors, ([left, right]) => differentConstructors(context, left, right)))
+                                    context.report({ node: decode, messageId: "classification" });
+                            },
+                        });
+                    },
+                });
+            },
+        };
+    },
+});

package/dist/index.js

@@ -44,6 +44,7 @@ export const effect = {
         "effect/require-service-operation-instrumentation": "error",
         "strict-effect/static-layers": "error",
         "strict-effect/subprocess-pipe-capture": "error",
+        "strict-effect/http-client-error-classification": "error",
         "strict-effect/no-runtime-type-assertions": "error",
         "strict-effect/no-unchecked-index": "error",
         "strict-effect/no-native-at": "error",

package/dist/strict-effect.js

@@ -1,4 +1,5 @@
 import { subprocessPipeCapture } from "./subprocess-pipe-capture.js";
+import { httpClientErrorClassification } from "./http-client-error-classification.js";
 import { noCopyingAccumulator } from "./accumulation.js";
 import { defineRule, eslintCompatPlugin } from "@oxlint/plugins";
 import * as Array from "effect/Array";
@@ -2549,6 +2550,7 @@ export default eslintCompatPlugin({
         "website-rpc-boundary": websiteRpcBoundary,
         "static-layers": staticLayers,
         "subprocess-pipe-capture": subprocessPipeCapture,
+        "http-client-error-classification": httpClientErrorClassification,
         "no-unchecked-index": noUncheckedIndex,
         "no-native-at": noNativeAt,
         "runtime-file-convention": runtimeFileConvention,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonplaces/oxlint-plugin",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Shared Oxlint rules for strict Effect TypeScript, Alchemy and repository code.",
   "license": "MIT",
   "author": "Cooper Corbett",