ai-deslop 0.2.1 → 0.2.2

package/README.md

@@ -13,117 +13,43 @@ npm install --save-dev ai-deslop
 
 Ships compiled JavaScript — works with any oxlint JS-plugin runtime (Bun, Deno, or Node.js).
 
-## Usage
-
-Register the plugin in `oxlint.config.ts` and enable every rule as an error via the exported `recommended` config:
-
-```ts
-import { defineConfig } from "oxlint";
-import { configs as deslopConfigs } from "ai-deslop";
-
-export default defineConfig({
-  jsPlugins: ["ai-deslop"],
-  options: {
-    ...deslopConfigs.recommended.options,
-  },
-  rules: {
-    ...deslopConfigs.recommended.rules,
-  },
-});
-```
-
-The `recommended` config also enables standard type-aware rules (`typescript/no-deprecated`, `typescript/no-floating-promises`), so it sets `options.typeAware`. Type-aware linting requires the `oxlint-tsgolint` package to be installed.
-
-Or with `.oxlintrc.json` (list the rules explicitly):
-
-```json
-{
-  "jsPlugins": ["ai-deslop"],
-  "options": {
-    "typeAware": true
-  },
-  "rules": {
-    "deslop/no-array-filter-map": "error",
-    "deslop/no-reduce-accumulator-copy": "error",
-    "deslop/no-chained-type-assertions": "error",
-    "deslop/no-conditional-empty-object-spread": "error",
-    "deslop/no-known-value-widening": "error",
-    "deslop/no-module-mocking": "error",
-    "deslop/no-object-parameters": "error",
-    "deslop/no-reflect-apply": "error",
-    "deslop/no-reflect-get": "error",
-    "deslop/no-runtime-typeof": "error",
-    "deslop/no-shape-in-symbol-names": "error",
-    "deslop/no-unknown-parameters": "error",
-    "deslop/no-unknown-returns": "error",
-    "deslop/no-unknown-type-aliases": "error",
-    "deslop/no-unsafe-dictionary-type": "error",
-    "deslop/no-widen-then-assert": "error",
-    "deslop/require-safety-comment-for-type-assertion": "error",
-    "deslop/no-call-only-assertions": "error",
-    "deslop/no-pass-through-type-alias": "error",
-    "typescript/no-deprecated": "error",
-    "typescript/no-floating-promises": "error"
-  }
-}
-```
-
 ## Rules
 
-### Generic (`deslop/*`)
-
-| Rule | Description |
+| Rule | Status | Description |
+| --- | --- | --- |
+| [`no-array-filter-map`](docs/deslop.md) | Recommended | Rejects adjacent eager array filter/map passes; allows lazy iterator pipelines. |
+| [`no-reduce-accumulator-copy`](docs/deslop.md) | Recommended | Rejects non-spread accumulator copies inside reducers. Enable native `oxc/no-accumulating-spread` alongside it. |
+| [`no-chained-type-assertions`](docs/deslop.md) | Recommended | Rejects nested `as` / angle-bracket assertions that fabricate evidence. |
+| [`no-conditional-empty-object-spread`](docs/deslop.md) | Recommended | Reports object spreads using a conditional `{}` branch to omit fields. |
+| [`no-known-value-widening`](docs/deslop.md) | Recommended | Rejects known expressions flowing into explicit `unknown`, `object`, or open dictionaries. |
+| [`no-module-mocking`](docs/deslop.md) | Recommended | Rejects Vitest and Jest module mocks. |
+| [`no-object-parameters`](docs/deslop.md) | Recommended | Rejects `object` on function inputs. |
+| [`no-reflect-apply`](docs/deslop.md) | Recommended | Rejects global `Reflect.apply`. |
+| [`no-reflect-get`](docs/deslop.md) | Recommended | Rejects global `Reflect.get`. |
+| [`no-runtime-typeof`](docs/deslop.md) | Recommended | Requires boundary parsing instead of ad hoc `typeof` narrowing. |
+| [`no-shape-in-symbol-names`](docs/deslop.md) | Recommended | Rejects `shape` in locally owned symbol names. |
+| [`no-unknown-parameters`](docs/deslop.md) | Recommended | Rejects `unknown` on function inputs. |
+| [`no-unknown-returns`](docs/deslop.md) | Recommended | Rejects return contracts resolving to `unknown`. |
+| [`no-unknown-type-aliases`](docs/deslop.md) | Recommended | Rejects aliases whose resolved type is `unknown`. |
+| [`no-unsafe-dictionary-type`](docs/deslop.md) | Recommended | Rejects dictionary values based on unsafe escape hatches. |
+| [`no-widen-then-assert`](docs/deslop.md) | Recommended | Rejects widening known evidence before narrowing assertions. |
+| [`require-safety-comment-for-type-assertion`](docs/deslop.md) | Recommended | Requires an invariant justification for non-const assertions. |
+| [`no-call-only-assertions`](docs/deslop.md) | Recommended | Flags tests whose assertions only check mock calls. |
+| [`no-pass-through-type-alias`](docs/deslop.md) | Recommended | Disallows aliases that only rename another type. |
+| [`no-duplicate-types`](docs/deslop.md#no-duplicate-types) | Opt-in | Reports exact duplicate object contracts. No fixer. |
+| [`canonical-class-names`](docs/tailwind.md) | Opt-in | Fixes non-canonical Tailwind CSS v4 class spellings. |
+
+| Standard rule | Status | Description |
+| --- | --- | --- |
+| `typescript/no-deprecated` | Recommended | Disallows using code marked `@deprecated`. Requires type-aware linting. |
+| `typescript/no-floating-promises` | Recommended | Disallows floating promises. Requires type-aware linting. |
+
+## Guides
+
+| Guide | Contents |
 | --- | --- |
-| `no-array-filter-map` | Rejects adjacent eager array filter/map passes; allows lazy iterator pipelines. |
-| `no-reduce-accumulator-copy` | Rejects non-spread accumulator copies inside reducers. Enable native `oxc/no-accumulating-spread` alongside it. |
-| `no-chained-type-assertions` | Rejects nested `as` / angle-bracket assertions that fabricate evidence (`as const` chains stay valid). |
-| `no-conditional-empty-object-spread` | Reports object spreads using a conditional `{}` branch to omit fields. |
-| `no-known-value-widening` | Rejects known expressions flowing into explicit `unknown` / `object` / open-dictionary targets. |
-| `no-module-mocking` | Rejects Vitest and Jest `mock` / `doMock` / `unstable_mockModule` calls. |
-| `no-object-parameters` | Rejects `object` (and aliases resolving to it) on function inputs. |
-| `no-reflect-apply` | Rejects global `Reflect.apply` in favor of typed function calls. |
-| `no-reflect-get` | Rejects global `Reflect.get` in favor of typed property access or boundary parsing. |
-| `no-runtime-typeof` | Requires boundary parsing instead of ad hoc `typeof` narrowing (`typeof x === "undefined"` probes stay allowed). |
-| `no-shape-in-symbol-names` | Rejects the case-insensitive substring `shape` in locally owned symbol names. |
-| `no-unknown-parameters` | Rejects `unknown` on function inputs (except the `cause` convention and type-predicate subjects). |
-| `no-unknown-returns` | Rejects function contracts resolving to `unknown` / `Promise<unknown>`. |
-| `no-unknown-type-aliases` | Rejects aliases whose resolved type is `unknown`. |
-| `no-unsafe-dictionary-type` | Rejects dictionary value contracts based on `unknown`, `any`, `object`, `{}`. |
-| `no-widen-then-assert` | Rejects flows that widen known evidence then assert it back to a narrower type. |
-| `require-safety-comment-for-type-assertion` | Requires a nearby invariant justification comment (default marker `SAFETY:`) for each non-const assertion. |
-| `no-call-only-assertions` | Flags tests whose every assertion only checks a mock was called (`toHaveBeenCalledWith` stays allowed). |
-| `no-pass-through-type-alias` | Disallows type aliases that only rename another type. |
-
-The rules use Oxlint's ESTree and lexical-scope APIs rather than a TypeScript type checker. They resolve same-file aliases but do not infer imported type definitions or cross-file call signatures.
-
-### Standard (`typescript/*`, in `recommended`)
-
-| Rule | Description |
-| --- | --- |
-| `typescript/no-deprecated` | Disallows using code marked `@deprecated`. Requires type-aware linting. |
-| `typescript/no-floating-promises` | Disallows floating Promises without handling. Requires type-aware linting. |
-
-### Opt-in (`deslop/canonical-class-names`, default off)
-
-Enforces canonical Tailwind CSS class spellings with `--fix` support (`mt-[16px]` → `mt-4`). Same source of truth as the Tailwind language server. Excluded from `recommended` because it requires a `cssPath` option — add it manually:
-
-```ts
-import { defineConfig } from "oxlint";
-import { configs as deslopConfigs } from "ai-deslop";
-
-export default defineConfig({
-  jsPlugins: ["ai-deslop"],
-  options: {
-    ...deslopConfigs.recommended.options,
-  },
-  rules: {
-    ...deslopConfigs.recommended.rules,
-    "deslop/canonical-class-names": ["warn", { cssPath: "./src/styles.css" }],
-  },
-});
-```
-
-Requires Tailwind CSS v4 (`tailwindcss` is an optional peer). Options: `cssPath` (required, absolute or relative to cwd), `rootFontSize` (default `16`), `attributes` (default `["class", "className"]`), `calleeFunctions` (default `["cn", "clsx", "cva", "twMerge", "tw", "classNames", "cx"]`). Only rewrites individual spellings — ordering/dedup belongs to the formatter. Strings with `${}` interpolations are skipped.
+| [Deslop rules](docs/deslop.md) | Recommended and opt-in deslop configuration, complete TypeScript/JSON examples, and `no-duplicate-types` options. |
+| [Tailwind canonical class names](docs/tailwind.md) | Tailwind v4 setup, complete TypeScript/JSON examples, and every supported option. |
 
 ## Credits
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { eslintCompatPlugin } from "@oxlint/plugins";
 /** Every `deslop/*` rule, plus selected standard rules, each set to `"error"`. Spread into the `rules` field of an oxlint config. */
 export declare const recommendedRules: Record<string, "error">;
-/** ESLint flat-config style configs. `recommended` enables every `deslop/*` rule as `"error"` (except opt-in rules like `canonical-class-names`), plus standard `typescript/*` rules. The `typescript/*` rules require type-aware linting (`options.typeAware`), so `recommended` sets it. */
+/** ESLint flat-config style configs. `recommended` enables every recommended `deslop/*` rule as `"error"` (excluding opt-in rules), plus standard `typescript/*` rules. The `typescript/*` rules require type-aware linting (`options.typeAware`), so `recommended` sets it. */
 export declare const configs: {
     recommended: {
         name: string;

package/dist/index.js

@@ -18,6 +18,7 @@ import { noWidenThenAssertRule } from "./rules/no-widen-then-assert.js";
 import { requireSafetyCommentForTypeAssertionRule } from "./rules/require-safety-comment-for-type-assertion.js";
 import { noCallOnlyAssertionsRule } from "./rules/no-call-only-assertions.js";
 import { noPassThroughTypeAliasRule } from "./rules/no-pass-through-type-alias.js";
+import { noDuplicateTypesRule } from "./rules/no-duplicate-types.js";
 import { canonicalClassNames } from "./tailwind/rule.js";
 /** Every `deslop/*` rule, plus selected standard rules, each set to `"error"`. Spread into the `rules` field of an oxlint config. */
 export const recommendedRules = {
@@ -43,7 +44,7 @@ export const recommendedRules = {
     "typescript/no-deprecated": "error",
     "typescript/no-floating-promises": "error",
 };
-/** ESLint flat-config style configs. `recommended` enables every `deslop/*` rule as `"error"` (except opt-in rules like `canonical-class-names`), plus standard `typescript/*` rules. The `typescript/*` rules require type-aware linting (`options.typeAware`), so `recommended` sets it. */
+/** ESLint flat-config style configs. `recommended` enables every recommended `deslop/*` rule as `"error"` (excluding opt-in rules), plus standard `typescript/*` rules. The `typescript/*` rules require type-aware linting (`options.typeAware`), so `recommended` sets it. */
 export const configs = {
     recommended: {
         name: "deslop/recommended",
@@ -74,6 +75,7 @@ const deslopPlugin = eslintCompatPlugin({
         "require-safety-comment-for-type-assertion": requireSafetyCommentForTypeAssertionRule,
         "no-call-only-assertions": noCallOnlyAssertionsRule,
         "no-pass-through-type-alias": noPassThroughTypeAliasRule,
+        "no-duplicate-types": noDuplicateTypesRule,
         // Opt-in: NOT in `recommendedRules`. Requires a `cssPath` option, so users add it manually.
         "canonical-class-names": canonicalClassNames,
     },

package/dist/rules/no-duplicate-types.d.ts

@@ -0,0 +1,2 @@
+/** Report exact structural duplicates without TypeScript assignability or fuzzy matching. */
+export declare const noDuplicateTypesRule: import("@oxlint/plugins").Rule;

package/dist/rules/no-duplicate-types.js

@@ -0,0 +1,143 @@
+import { defineRule } from "@oxlint/plugins";
+function propertyKey(node) {
+    const value = node;
+    if (value.type === "Identifier" && typeof value.name === "string")
+        return value.name;
+    if (typeof value.value === "string")
+        return JSON.stringify(value.value);
+    if (typeof value.value === "number")
+        return String(value.value);
+    return null;
+}
+function literalValue(node) {
+    const literal = node.literal;
+    if (typeof literal.value === "string")
+        return JSON.stringify(literal.value);
+    if (typeof literal.value === "number" || typeof literal.value === "boolean")
+        return String(literal.value);
+    if (typeof literal.value === "bigint")
+        return `${literal.value}n`;
+    if (literal.type === "UnaryExpression" && literal.operator === "-") {
+        if (typeof literal.argument?.value === "number")
+            return `-${literal.argument.value}`;
+        if (typeof literal.argument?.value === "bigint")
+            return `-${literal.argument.value}n`;
+    }
+    return null;
+}
+function canonicalTypeName(node) {
+    if (node.type === "Identifier")
+        return node.name;
+    if (node.type !== "TSQualifiedName")
+        return null;
+    const left = canonicalTypeName(node.left);
+    return left === null ? null : `${left}.${node.right.name}`;
+}
+function canonicalMembers(members, parameters) {
+    const result = [];
+    for (const member of members) {
+        if (member.type !== "TSPropertySignature" || member.computed || member.typeAnnotation === null)
+            return null;
+        const key = propertyKey(member.key);
+        const type = canonicalType(member.typeAnnotation.typeAnnotation, parameters);
+        if (key === null || type === null)
+            return null;
+        result.push(`prop(${key},${member.optional ? "?" : "!"},${member.readonly ? "ro" : "rw"},${type})`);
+    }
+    result.sort();
+    return `{${result.join(",")}}`;
+}
+function canonicalType(node, parameters) {
+    switch (node.type) {
+        case "TSAnyKeyword":
+        case "TSBigIntKeyword":
+        case "TSBooleanKeyword":
+        case "TSNeverKeyword":
+        case "TSNullKeyword":
+        case "TSNumberKeyword":
+        case "TSObjectKeyword":
+        case "TSStringKeyword":
+        case "TSSymbolKeyword":
+        case "TSUndefinedKeyword":
+        case "TSUnknownKeyword":
+        case "TSVoidKeyword":
+            return node.type;
+        case "TSLiteralType": {
+            const value = literalValue(node);
+            return value === null ? null : `literal(${value})`;
+        }
+        case "TSArrayType": {
+            const element = canonicalType(node.elementType, parameters);
+            return element === null ? null : `array(${element})`;
+        }
+        case "TSParenthesizedType": return canonicalType(node.typeAnnotation, parameters);
+        case "TSTypeOperator": {
+            const type = canonicalType(node.typeAnnotation, parameters);
+            return type === null ? null : `${node.operator}(${type})`;
+        }
+        case "TSUnionType":
+        case "TSIntersectionType": {
+            const types = node.types.map((type) => canonicalType(type, parameters));
+            if (types.some((type) => type === null))
+                return null;
+            return `${node.type === "TSUnionType" ? "union" : "intersection"}(${[...new Set(types)].sort().join(",")})`;
+        }
+        case "TSTypeLiteral": return canonicalMembers(node.members, parameters);
+        case "TSTypeReference": {
+            const name = canonicalTypeName(node.typeName);
+            if (name === null)
+                return null;
+            const arguments_ = node.typeArguments?.params.map((type) => canonicalType(type, parameters)) ?? [];
+            if (arguments_.some((type) => type === null))
+                return null;
+            return `ref(${parameters.get(name) ?? name}<${arguments_.join(",")}>)`;
+        }
+        default: return null;
+    }
+}
+function canonicalDeclaration(node) {
+    const parameters = new Map();
+    for (const [index, parameter] of (node.typeParameters?.params ?? []).entries()) {
+        parameters.set(parameter.name.name, `$${index}`);
+    }
+    if (node.type === "TSTypeAliasDeclaration")
+        return canonicalType(node.typeAnnotation, parameters);
+    if (node.extends.length > 0)
+        return null;
+    return canonicalMembers(node.body.body, parameters);
+}
+/** Report exact structural duplicates without TypeScript assignability or fuzzy matching. */
+export const noDuplicateTypesRule = defineRule({
+    meta: {
+        type: "suggestion",
+        docs: { description: "Report structurally identical TypeScript declarations" },
+        messages: { duplicate: "{{message}} First seen as {{firstName}} in {{firstFile}}." },
+        schema: [{ type: "object", properties: { message: { type: "string" }, minProperties: { type: "integer", minimum: 0 } }, additionalProperties: false }],
+    },
+    createOnce(context) {
+        const seen = new Map();
+        let options = {};
+        const report = (node, fingerprint) => {
+            const first = seen.get(fingerprint);
+            if (first === undefined) {
+                seen.set(fingerprint, { name: node.id.name, filename: context.filename });
+                return;
+            }
+            context.report({ node, messageId: "duplicate", data: { message: options.message ?? "This type is structurally identical to an existing declaration.", firstName: first.name, firstFile: first.filename } });
+        };
+        const inspect = (node) => {
+            const fingerprint = canonicalDeclaration(node);
+            if (fingerprint === null)
+                return;
+            const properties = node.type === "TSTypeAliasDeclaration" && node.typeAnnotation.type === "TSTypeLiteral" ? node.typeAnnotation.members.length : node.type === "TSInterfaceDeclaration" ? node.body.body.length : Infinity;
+            if (properties < (options.minProperties ?? 2))
+                return;
+            report(node, fingerprint);
+        };
+        return {
+            Program() { options = context.options[0] ?? {}; },
+            TSTypeAliasDeclaration: inspect,
+            TSInterfaceDeclaration: inspect,
+        };
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-deslop",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Opinionated Oxlint rules that reject low-evidence, low-signal, AI-slop code patterns.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,6 +19,7 @@
     "prepublishOnly": "npm run build",
     "check": "npm run build && oxlint src && tsc --noEmit",
     "lint": "oxlint src",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -37,7 +38,8 @@
   "devDependencies": {
     "@types/node": "26.2.0",
     "oxlint": "1.82.0",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "vitest": "^5.0.1"
   },
   "license": "MIT",
   "repository": {