@jeremybarbet/oxlint-plugin 0.3.0 → 0.4.0

package/README.md

@@ -35,8 +35,9 @@ pass as every other lint rule — rather than as a batch report from a separate
 Not reported:
 
 - Exports tagged `/** @public */` or `/** @beta */`, the same opt-out knip honours.
-- Exports consumed inside their own file. Those are over-exposed, not dead — the fix is dropping the
-  `export` keyword, not deleting the declaration. Most exported return types look like this.
+- Exports consumed inside their own file. Those are over-exposed, not dead: the fix is dropping the
+  `export` keyword, not deleting the declaration. Most exported return types look like this, and
+  `no-unnecessary-export` below is the rule that reports them.
 - Anything matching `**/*.config.*`, always. A config file is loaded by path by the tool that owns
   it, so its default export is an entry point by definition.
 
@@ -57,6 +58,38 @@ Not reported:
 `ignoreDefaultExports` is the narrow version of `ignoreExports`: listing `app/**` there would also
 silence the named exports in those files, so a route that grew a dead helper would go unreported.
 
+### `no-unnecessary-export`
+
+Reports a binding that is exported but only ever used inside its own declaring file. The
+complement of `no-unused-modules`, which deliberately leaves this case alone because the two want
+opposite fixes:
+
+| Rule | Condition | Fix |
+| --- | --- | --- |
+| `no-unused-modules` | Nothing references the export, anywhere. | Delete the declaration. |
+| `no-unnecessary-export` | Only the declaring file references it. | Drop the `export` keyword. |
+
+The two never both fire on one name. Together they mean an export is either imported somewhere or
+reported.
+
+Type-only exports are skipped by default: an exported interface used only as a local return type is
+the ordinary shape of a typed codebase, not over-exposure. `@public` / `@beta` opt out, same as
+`no-unused-modules`.
+
+Reported, never autofixed. The verdict comes from a static crawl that cannot see a runtime-resolved
+import, so the fix is offered as an editor suggestion and `--fix` leaves the file alone. Only a lone
+`export const x = …` gets one: a specifier list drops an entry rather than the keyword, and a
+destructured or multi-declarator export may still have an imported sibling.
+
+| Option | Default | |
+| --- | --- | --- |
+| `includeTypes` | `false` | Also report type-only exports. |
+| `ignoreExports` | `[]` | Globs whose exports are never reported. |
+
+```ts
+'op/no-unnecessary-export': 'error',
+```
+
 ### `no-unused-class-members`
 
 Reports public class members that nothing outside the declaring file references.
@@ -101,10 +134,10 @@ nested type cannot silently break Apollo's cache-control computation. Ships an a
 
 ## Project discovery
 
-`no-unused-modules` and `no-unused-class-members` need a whole-project view, so they crawl and parse
-the project once per process and answer per-file from the result. (Oxlint's plugin API is per-file
-with no end-of-run hook, so this is the same approach `eslint-plugin-import` takes.) It costs roughly
-120ms on an 830-file repo.
+`no-unused-modules`, `no-unnecessary-export` and `no-unused-class-members` need a whole-project
+view, so they crawl and parse the project once per process and answer per-file from the result.
+(Oxlint's plugin API is per-file with no end-of-run hook, so this is the same approach
+`eslint-plugin-import` takes.) It costs roughly 120ms on an 830-file repo.
 
 Discovery is zero-config: everything under the oxlint working directory that looks like source,
 skipping `node_modules`, `dist`, `build`, `coverage`, `android`, `ios` and dotfile directories.

package/dist/index.d.mts

@@ -12,6 +12,7 @@ declare const _default: {
     };
     rules: {
         'no-export-all': import("./types.mts").Rule;
+        'no-unnecessary-export': import("./types.mts").Rule;
         'no-unused-class-members': import("./types.mts").Rule;
         'no-unused-modules': import("./types.mts").Rule;
         'no-unused-styles': import("./types.mts").Rule;

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import noExportAll from "./rules/no-export-all.mjs";
+import noUnnecessaryExport from "./rules/no-unnecessary-export.mjs";
 import noUnusedClassMembers from "./rules/no-unused-class-members.mjs";
 import noUnusedModules from "./rules/no-unused-modules.mjs";
 import noUnusedStyles from "./rules/no-unused-styles.mjs";
@@ -15,6 +16,7 @@ export default {
     meta: { name: 'op' },
     rules: {
         'no-export-all': noExportAll,
+        'no-unnecessary-export': noUnnecessaryExport,
         'no-unused-class-members': noUnusedClassMembers,
         'no-unused-modules': noUnusedModules,
         'no-unused-styles': noUnusedStyles,

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,2BAA2B,CAAC;AACpD,OAAO,oBAAoB,MAAM,qCAAqC,CAAC;AACvE,OAAO,eAAe,MAAM,+BAA+B,CAAC;AAC5D,OAAO,cAAc,MAAM,8BAA8B,CAAC;AAC1D,OAAO,mBAAmB,MAAM,mCAAmC,CAAC;AAEpE;;;;;;;GAOG;AACH,eAAe;IACb,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;IACpB,KAAK,EAAE;QACL,eAAe,EAAE,WAAW;QAC5B,yBAAyB,EAAE,oBAAoB;QAC/C,mBAAmB,EAAE,eAAe;QACpC,kBAAkB,EAAE,cAAc;QAClC,uBAAuB,EAAE,mBAAmB;KAC7C;CACF,CAAC"}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,2BAA2B,CAAC;AACpD,OAAO,mBAAmB,MAAM,mCAAmC,CAAC;AACpE,OAAO,oBAAoB,MAAM,qCAAqC,CAAC;AACvE,OAAO,eAAe,MAAM,+BAA+B,CAAC;AAC5D,OAAO,cAAc,MAAM,8BAA8B,CAAC;AAC1D,OAAO,mBAAmB,MAAM,mCAAmC,CAAC;AAEpE;;;;;;;GAOG;AACH,eAAe;IACb,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;IACpB,KAAK,EAAE;QACL,eAAe,EAAE,WAAW;QAC5B,uBAAuB,EAAE,mBAAmB;QAC5C,yBAAyB,EAAE,oBAAoB;QAC/C,mBAAmB,EAAE,eAAe;QACpC,kBAAkB,EAAE,cAAc;QAClC,uBAAuB,EAAE,mBAAmB;KAC7C;CACF,CAAC"}

package/dist/rules/no-unnecessary-export.d.mts

@@ -0,0 +1,3 @@
+import { type Rule } from '../types.mts';
+declare const rule: Rule;
+export default rule;

package/dist/rules/no-unnecessary-export.mjs

@@ -0,0 +1,127 @@
+import { relative } from 'node:path';
+import { matchesGlob } from "../glob.mjs";
+import { getProjectIndex, readProjectSettings } from "../project-index.mjs";
+import {} from "../types.mjs";
+/**
+ * The complement of `no-unused-modules`: that rule treats an export its own file consumes as used,
+ * which leaves an over-exposed binding unreported. Nothing imports it, so the `export` should go.
+ */
+/** Always applied, on top of whatever a project configures. Mirrors `no-unused-modules`. */
+const ALWAYS_IGNORED_EXPORTS = ['**/*.config.*'];
+/** Declarations that emit no runtime binding, so exporting one is not the over-exposure this rule means. */
+const TYPE_DECLARATIONS = new Set(['TSInterfaceDeclaration', 'TSTypeAliasDeclaration']);
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow exporting a binding only its own file uses',
+        },
+        messages: {
+            unnecessary: "'{{name}}' is only used in this file. Drop the `export` keyword.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    includeTypes: { type: 'boolean' },
+                    ignoreExports: { type: 'array', items: { type: 'string' } },
+                },
+                additionalProperties: false,
+            },
+        ],
+        hasSuggestions: true,
+    },
+    create(context) {
+        const raw = (context.options?.[0] ?? {});
+        const includeTypes = raw.includeTypes ?? false;
+        const ignoreExports = [...ALWAYS_IGNORED_EXPORTS, ...(raw.ignoreExports ?? [])];
+        const index = getProjectIndex(context.cwd, readProjectSettings(context));
+        const self = context.filename;
+        const file = index.files.get(self);
+        if (!file) {
+            return {};
+        }
+        const relativePath = relative(index.root, self).split('\\').join('/');
+        if (matchesGlob(relativePath, ignoreExports)) {
+            return {};
+        }
+        const importers = index.importedFrom.get(self);
+        // A namespace import (`import * as x`) reaches every export, so none of them can be called local.
+        if (importers?.has('*')) {
+            return {};
+        }
+        const isLocalOnly = (name) => {
+            if (importers?.has(name) || file.intentionalExports.has(name)) {
+                return false;
+            }
+            // The inversion. Without a local reference the export is dead, which is `no-unused-modules`'
+            // finding, not this one, and the two must never both fire on a name.
+            return file.localReferences.has(name);
+        };
+        /**
+         * The span covering the `export` keyword, or null when removing it is not the right fix. A
+         * specifier list drops one entry instead, and a destructured export may have an imported sibling.
+         */
+        const exportKeywordRange = (node, declaration) => {
+            if ((node.specifiers ?? []).length > 0) {
+                return null;
+            }
+            const declarations = (declaration.declarations ?? []);
+            const single = declaration.id?.type === 'Identifier' ||
+                (declarations.length === 1 && declarations[0]?.id?.type === 'Identifier');
+            return single ? [node.range[0], declaration.range[0]] : null;
+        };
+        const report = (node, name, range) => {
+            if (!isLocalOnly(name)) {
+                return;
+            }
+            context.report({
+                node,
+                messageId: 'unnecessary',
+                data: { name },
+                ...(range && {
+                    suggest: [
+                        {
+                            desc: 'Remove the `export` keyword.',
+                            fix: fixer => fixer.removeRange(range),
+                        },
+                    ],
+                }),
+            });
+        };
+        return {
+            /**
+             * `export default` is out of scope: its export name is `default`, a reserved word no
+             * identifier can match, so it never has a local reference to begin with.
+             */
+            ExportNamedDeclaration(node) {
+                if (node.source || (!includeTypes && node.exportKind === 'type')) {
+                    return;
+                }
+                for (const specifier of (node.specifiers ?? [])) {
+                    const name = specifier.exported?.name;
+                    if (!name || name === 'default' || (!includeTypes && specifier.exportKind === 'type')) {
+                        continue;
+                    }
+                    report(specifier.exported, name, null);
+                }
+                const declaration = node.declaration;
+                if (!declaration || (!includeTypes && TYPE_DECLARATIONS.has(declaration.type))) {
+                    return;
+                }
+                const range = exportKeywordRange(node, declaration);
+                if (declaration.id?.name) {
+                    report(declaration.id, declaration.id.name, range);
+                    return;
+                }
+                for (const declarator of (declaration.declarations ?? [])) {
+                    if (declarator.id?.type === 'Identifier') {
+                        report(declarator.id, declarator.id.name, range);
+                    }
+                }
+            },
+        };
+    },
+};
+export default rule;
+//# sourceMappingURL=no-unnecessary-export.mjs.map

package/dist/rules/no-unnecessary-export.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-unnecessary-export.mjs","sourceRoot":"","sources":["../../src/rules/no-unnecessary-export.mts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@jeremybarbet/oxlint-plugin",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared oxlint JS plugin: dead-code rules that oxlint, tsc and knip each miss, plus a few house rules.",
   "author": "Jérémy Barbet <jeremgraph@gmail.com> (https://github.com/jeremybarbet)",
   "repository": "https://github.com/jeremybarbet/oxlint-plugin",
   "homepage": "https://github.com/jeremybarbet/oxlint-plugin#readme",
   "license": "MIT",
-  "packageManager": "yarn@4.13.0",
+  "packageManager": "yarn@4.18.0",
   "engines": {
     "node": ">=22"
   },