@codegraft/rules 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Joël Charles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @codegraft/rules
+
+Ready-made codemods — ESLint-rule-style transforms authored with [`@codegraft/codemod`](../codemod) and the `@codegraft/core` scope resolver.
+
+Each rule lives in its own module, is re-exported by name from the barrel, and the package is `"sideEffects": false` — so a consumer that imports one rule tree-shakes the rest. Every rule runs live via `forTarget` — directly, through `@codegraft/unplugin`, or `codegraft run`.
+
+## Rules
+
+### `removeUnusedImports`
+
+Removes imports whose local binding is never referenced, and rewrites value imports used only in type positions into type imports — the analogue of `eslint-plugin-unused-imports` plus the import half of `@typescript-eslint/consistent-type-imports`. Syntactic, single-file, and **confident-or-abstain**: it keeps anything it can't prove unused and never emits invalid code.
+
+Per binding, three outcomes:
+
+- **value-used** → kept as-is (a value import already serves type positions);
+- **type-used only** → rewritten as a type import — inline `import { type X }` next to a surviving value specifier, or a whole `import type …` when the entire statement becomes type-only (covers default and `* as ns` too);
+- **unused** → removed, including unused `import type …` and inline `{ type X }`; the whole statement goes when every binding is unused, otherwise the clause is rebuilt from the survivors.
+
+Safety, always erring towards code that still compiles:
+
+- never touches a side-effect import (`import 'x'`);
+- abstains on the whole file when the scope resolver can't model it (`with` / `eval` / a TS `namespace` / ambient `module`);
+- value-use detection is scope-aware (a use shadowed in an inner scope doesn't keep an outer import alive), and `typeof X` counts as a value use;
+- a type-only default/namespace that shares a statement with a surviving value binding is kept as a value import rather than split across two statements (safe, just not erasable).
+
+```ts
+import { removeUnusedImports } from '@codegraft/rules'
+
+const transform = await removeUnusedImports.forTarget('tsx')
+transform.transform("import { used, unused } from 'm'\nused()", {})
+// → "import { used } from 'm'\nused()"
+transform.transform("import { Foo } from 'm'\nlet v: Foo", {})
+// → "import type { Foo } from 'm'\nlet v: Foo"
+```
+
+It works on every JS-family grammar (JS / JSX / TS / TSX) and, through a `ZoneSplitter`, the `<script>` of a Vue SFC.
+
+The rule module is also a ready codemod (default export + `targets: ['javascript', 'typescript', 'tsx']`), so the CLI runs it directly — `.vue` `<script>` included, via the cli's built-in splitter:
+
+```bash
+codegraft run "src/**/*.{ts,tsx,vue}" --codemod @codegraft/rules/remove-unused-imports --in-place
+```
+
+See the root [README](../../README.md#ready-made-rules-codegraftrules) for how to wire a rule into a bundler or `codegraft run`.
+
+## Adding a rule
+
+1. Add `src/<rule-name>.ts` exporting a `defineCodemod(...)` result.
+2. Re-export it from `src/index.ts`.
+3. Add `src/<rule-name>.test.ts`, covering each grammar you support plus the `vueSplitter` path and the abstain cases.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { removeUnusedImports } from './remove-unused-imports.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// One rule per module, re-exported by name — combined with `"sideEffects": false`, a consumer
+// that imports a single rule tree-shakes the rest. Add new rules here the same way.
+export { removeUnusedImports } from './remove-unused-imports.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,oFAAoF;AACpF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/remove-unused-imports.d.ts

@@ -0,0 +1,12 @@
+import type { GrammarId } from '@codegraft/core';
+/**
+ * Remove imports with no reference, and rewrite a value import used only in type positions into a
+ * type import — the analogue of `eslint-plugin-unused-imports` plus the import half of
+ * `@typescript-eslint/consistent-type-imports`. Syntactic and single-file; confident-or-abstain, so
+ * a binding the scope resolver can't resolve is left untouched rather than deleted. Runs on every
+ * JS-family grammar and, through a `ZoneSplitter`, the `<script>` of a Vue SFC.
+ */
+export declare const removeUnusedImports: import("@codegraft/codemod").Codemod<Record<string, unknown>, GrammarId>;
+export default removeUnusedImports;
+export declare const targets: GrammarId[];
+//# sourceMappingURL=remove-unused-imports.d.ts.map

package/dist/remove-unused-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-unused-imports.d.ts","sourceRoot":"","sources":["../src/remove-unused-imports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG5D;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0EAgF9B,CAAA;AAEF,eAAe,mBAAmB,CAAA;AAIlC,eAAO,MAAM,OAAO,EAAE,SAAS,EAAwC,CAAA"}

package/dist/remove-unused-imports.js

@@ -0,0 +1,87 @@
+import { defineCodemod } from '@codegraft/codemod';
+/**
+ * Remove imports with no reference, and rewrite a value import used only in type positions into a
+ * type import — the analogue of `eslint-plugin-unused-imports` plus the import half of
+ * `@typescript-eslint/consistent-type-imports`. Syntactic and single-file; confident-or-abstain, so
+ * a binding the scope resolver can't resolve is left untouched rather than deleted. Runs on every
+ * JS-family grammar and, through a `ZoneSplitter`, the `<script>` of a Vue SFC.
+ */
+export const removeUnusedImports = defineCodemod((root) => {
+    // The resolver reports only value (`identifier`) references, so type-position uses are gathered
+    // separately: every `type_identifier`, plus the `identifier` head of a qualified type (`NS.x`).
+    const typeRefs = new Set();
+    root.find('type_identifier').forEach((ref) => typeRefs.add(ref.text));
+    root.find('nested_type_identifier').forEach((qualified) => {
+        const head = qualified.field('module');
+        if (head.type === 'identifier')
+            typeRefs.add(head.text);
+    });
+    root.find('import_statement').forEach((stmt) => {
+        const clause = stmt.children().filter((child) => child.type === 'import_clause').first();
+        if (clause.size() === 0)
+            return; // side-effect import (`import 'x'`): no binding to be unused
+        const isTypeStatement = stmt.node.allChildren.some((child) => child.type === 'type'); // `import type …`
+        const bindings = [];
+        clause.children().forEach((part) => {
+            if (part.type === 'identifier') {
+                bindings.push({ named: false, text: part.text, local: part, isType: isTypeStatement });
+            }
+            else if (part.type === 'namespace_import') {
+                bindings.push({ named: false, text: part.text, local: part.find('identifier').first(), isType: isTypeStatement });
+            }
+            else if (part.type === 'named_imports') {
+                part.find('import_specifier').forEach((spec) => {
+                    const alias = spec.field('alias');
+                    const name = spec.field('name');
+                    const inlineType = spec.node.allChildren.some((child) => child.type === 'type');
+                    const text = alias.size() ? `${name.text} as ${alias.text}` : name.text;
+                    bindings.push({ named: true, text, local: alias.size() ? alias : name, isType: isTypeStatement || inlineType });
+                });
+            }
+        });
+        // Keep each referenced binding, recording whether its only references are type-position ones.
+        const kept = [];
+        for (const binding of bindings) {
+            const references = binding.local.references();
+            if (!references)
+                return; // resolver abstains on this file — leave the statement untouched
+            const declaration = binding.local.node;
+            const valueUsed = !binding.isType &&
+                references.nodes().some((ref) => {
+                    // A qualified-type head (`NS.Thing`) lexes as a value identifier but is a type use.
+                    const parent = ref.parent;
+                    return ref !== declaration && !(parent?.type === 'nested_type_identifier' && parent.child('module') === ref);
+                });
+            if (!valueUsed && !typeRefs.has(binding.local.text))
+                continue; // unreferenced
+            kept.push({ ...binding, typeOnly: !valueUsed });
+        }
+        if (kept.length === 0) {
+            stmt.remove();
+            return;
+        }
+        // A type-only default or `* as ns` can't be marked inline, so a binding renders as a type only
+        // when the whole statement does (every binding type-only) or it's a named specifier. `asType`
+        // is the single source of truth for the no-op check and the rendering below.
+        const asTypeStatement = kept.every((binding) => binding.typeOnly);
+        const asType = (binding) => asTypeStatement || (binding.named && binding.typeOnly);
+        if (kept.length === bindings.length && kept.every((binding) => asType(binding) === binding.isType))
+            return;
+        const leading = [];
+        const specifiers = [];
+        for (const binding of kept) {
+            if (!binding.named)
+                leading.push(binding.text);
+            else
+                specifiers.push(asType(binding) && !asTypeStatement ? `type ${binding.text}` : binding.text);
+        }
+        if (specifiers.length)
+            leading.push(`{ ${specifiers.join(', ')} }`);
+        stmt.replaceWith(`${asTypeStatement ? 'import type' : 'import'} ${leading.join(', ')} from ${stmt.field('source').text}`);
+    });
+});
+export default removeUnusedImports;
+// Lets `codegraft run --codemod @codegraft/rules/remove-unused-imports` apply over `.js/.jsx/.ts/.tsx`
+// directly; the cli adds the Vue splitter, so `.vue` `<script>` works too without declaring it here.
+export const targets = ['javascript', 'typescript', 'tsx'];
+//# sourceMappingURL=remove-unused-imports.js.map

package/dist/remove-unused-imports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-unused-imports.js","sourceRoot":"","sources":["../src/remove-unused-imports.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@codegraft/rules",
+  "version": "0.1.0-beta.0",
+  "description": "Ready-made Codegraft codemods — ESLint-rule-style transforms (e.g. removeUnusedImports), one rule per module, tree-shakeable.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magne4000/codegraft.git",
+    "directory": "packages/rules"
+  },
+  "homepage": "https://github.com/magne4000/codegraft#readme",
+  "bugs": "https://github.com/magne4000/codegraft/issues",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./*": {
+      "import": "./dist/*.js",
+      "types": "./dist/*.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "dependencies": {
+    "@codegraft/codemod": "0.1.0-beta.0",
+    "@codegraft/core": "0.1.0-beta.0"
+  },
+  "devDependencies": {
+    "@codegraft/vue": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}