oxlint-plugin-arch 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Add `prefer-namespace-type-import` with a configurable named-type-import limit (default 3), module-specific namespace names, and scope-aware autofixes that qualify type references while reporting unsafe rewrites without a fix.
+
 - Options that took one regex string now also take a non-empty list, where any pattern may match: `pattern`, `allowPattern`, `allowNamePattern`, `denyTypePattern`, `hookPattern`, `rootPattern`, `factoryPattern`, `forbid`, and `require`. Single strings keep their behavior.
 - `no-type-declarations` `allowPattern` entries starting with `=` or `^=` match a type alias's value (`= ` plus its source text) instead of its name, so `'^= ReturnType<typeof '` keeps factory return types next to their factory. A name pattern that starts with `=` or `^=` is now read as a value pattern.
 - Fix `declaration-name` `pattern` with `g` or `y` flags rejecting every name after the first match.

package/README.md

@@ -6,7 +6,7 @@ Keep a codebase shaped the way you designed it: files in the right folders, expo
 
 - 🗂️ **Filename-aware.** Rules derive expected names from the file they run on (`user-action.create.ts` → `makeUserActionCreate`).
 - 🎛️ **Configurable.** No app names, folders, or libraries are baked in. Globs and policy live in your config.
-- 🛟 **Safe autofix.** Fixable rules only touch whitespace or comments, and never guess when a fix could change your code.
+- 🛟 **Safe autofix.** Layout and comment rules only touch whitespace or comments. Type-import fixes qualify scope-resolved references and skip unsafe rewrites.
 - ⚡ **Fast.** Built on Oxlint's JS plugin API and ESTree, with no extra parser.
 
 ---
@@ -65,7 +65,7 @@ export default defineConfig({
 | --- | --- |
 | [`minimal.oxlint.config.ts`](examples/minimal.oxlint.config.ts) | You want the smallest possible starting point. |
 | [`monorepo.oxlint.config.ts`](examples/monorepo.oxlint.config.ts) | ⭐ You are starting an `apps/server` + `apps/web` monorepo and want a strict, copy-ready setup. |
-| [`full.oxlint.config.ts`](examples/full.oxlint.config.ts) | You want to see every one of the 42 rules with its options. |
+| [`full.oxlint.config.ts`](examples/full.oxlint.config.ts) | You want to see every one of the 43 rules with its options. |
 
 > [!TIP]
 > `monorepo.oxlint.config.ts` already loads `oxlint-plugin-arch`, so you can copy it as-is and adjust globs and names. The other two load `../src/index.ts`; change that specifier to `oxlint-plugin-arch` when you copy them.
@@ -74,7 +74,7 @@ export default defineConfig({
 
 ## 🧩 Rules
 
-42 rules in 9 groups. 🔧 means the rule can autofix. Each rule file in [`src/rules/`](src/rules) explains its behavior in plain English, and the tests in [`src/tests/`](src/tests) show every option shape.
+43 rules in 9 groups. 🔧 means the rule can autofix. Each rule file in [`src/rules/`](src/rules) explains its behavior in plain English, and the tests in [`src/tests/`](src/tests) show every option shape.
 
 Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `require`, and the other `*Pattern` options) also take a non-empty list; any pattern in the list may match. Options that were already lists, such as `allowPatterns` and `allowCallees`, are unchanged.
 
@@ -117,6 +117,7 @@ Options that take one regex string (`pattern`, `allowPattern`, `forbid`, `requir
 | `no-type-declarations` | No type aliases or interfaces in matched files, so types live in one place. |
 | `no-runtime-in-types` | Type modules stay free of runtime code. Opt in to also ban runtime imports and re-exports. |
 | `no-imported-type-alias` | No exported aliases that only rename an imported type. |
+| `prefer-namespace-type-import` 🔧 | Long type-only named imports become a namespace import with qualified references. [Details ↓](#prefer-namespace-type-import) |
 
 ### 🧪 Schemas & APIs
 
@@ -200,6 +201,31 @@ Use `no-type-declarations` separately to control where named types may live. Wit
 
 </details>
 
+### `prefer-namespace-type-import`
+
+Prefers a namespace when a type-only import has **more than** `max` named specifiers. Both `import type { A, B }` and `import { type A, type B }` are checked; any runtime or default binding leaves the declaration alone.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `max` | `3` | Maximum named specifiers allowed (non-negative integer). Three passes; four fails. |
+| `names` | `{}` | Exact module-path-to-namespace-name map, such as `{ '#/types/room.types': 'RoomTypes' }`. Values must be ASCII binding identifiers, not reserved words. |
+
+The default name is the last path segment in PascalCase, stripping JS/TS extensions and adding `Types` unless already present: `#/types/room.types` → `RoomTypes`, `./harness.types.ts` → `HarnessTypes`, `@orbs/server/client` → `ClientTypes`. Other punctuation separates words; names starting with a digit get a `Module` prefix.
+
+```ts
+// Before
+import type { A, B as LocalB, C, D } from './room.types'
+export type Result = [A, LocalB, C, D]
+
+// After
+import type * as RoomTypes from './room.types'
+export type Result = [RoomTypes.A, RoomTypes.B, RoomTypes.C, RoomTypes.D]
+```
+
+The autofix updates scope-resolved type references, generics, indexed access, type-position `typeof`, interface heritage, and class implementations, including TSX. Shadowed local names are untouched. Exported type declarations are updated, but local export lists (`export type { A }`, `export { type A }`, or `export { A }`) are **report-only**; direct re-exports from another module are untouched.
+
+The diagnostic explains why an autofix was skipped: comments inside the import, an existing namespace import from the same module (no merging), a namespace name colliding with any binding/reference in the file or another proposed namespace, an unsupported imported name, or a reference outside the supported type syntax. Multiple qualifying imports from the same module are report-only too. Choose distinct `names` overrides to resolve collisions between different modules. Fixes preserve the module string, import attributes, semicolon, and comments outside the import.
+
 ### `no-type-declarations`
 
 Rejects type aliases and interfaces in matched files, so types live in one place.

package/dist/index.js

@@ -4023,9 +4023,142 @@ var paddingBetweenStatements = defineRule36({
   }
 });
 
-// src/rules/require-file-factory.ts
+// src/rules/prefer-namespace-type-import.ts
 import { defineRule as defineRule37 } from "@oxlint/plugins";
-var requireFileFactory = defineRule37({
+var bindingName = /^[A-Za-z_$][\w$]*$/;
+var reservedNames = new Set("await break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield implements interface let package private protected public static arguments eval".split(" "));
+function namespaceName(source, names) {
+  if (Object.hasOwn(names, source)) {
+    return names[source];
+  }
+  const stem = namingFileBasename(source).replace(/(?:\.d)?\.[cm]?[jt]sx?$/i, "");
+  const name = namingPascalCase(stem.replace(/[^A-Za-z0-9_$.-]/g, "-")) || "Module";
+  const prefixed = /^\d/.test(name) ? `Module${name}` : name;
+  return prefixed.endsWith("Types") ? prefixed : `${prefixed}Types`;
+}
+function isTypeOnlyNamedImport(node) {
+  return node.specifiers.length > 0 && node.specifiers.every((specifier) => specifier.type === "ImportSpecifier" && (node.importKind === "type" || specifier.importKind === "type"));
+}
+function safeReference(node) {
+  let current = node;
+  let parent = current.parent;
+  while (parent?.type === "TSQualifiedName" && parent.left === current || parent?.type === "MemberExpression" && !parent.computed && parent.object === current) {
+    current = parent;
+    parent = current.parent;
+  }
+  return parent?.type === "TSTypeReference" && parent.typeName === current || parent?.type === "TSTypeQuery" && parent.exprName === current || (parent?.type === "TSInterfaceHeritage" || parent?.type === "TSClassImplements") && parent.expression === current;
+}
+var preferNamespaceTypeImport = defineRule37({
+  meta: {
+    type: "suggestion",
+    fixable: "code",
+    schema: [{
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        max: { type: "integer", minimum: 0 },
+        names: { type: "object", additionalProperties: { type: "string", pattern: bindingName.source } }
+      }
+    }],
+    defaultOptions: [{ max: 3, names: {} }],
+    messages: {
+      namespace: "Use a type namespace '{{name}}' for {{count}} named imports (maximum {{max}}).{{reason}}"
+    }
+  },
+  createOnce(context) {
+    const imports = [];
+    return {
+      before() {
+        imports.length = 0;
+      },
+      ImportDeclaration(node) {
+        imports.push(node);
+      },
+      "Program:exit"() {
+        const { max, names } = optionsFirst(context);
+        const candidates = imports.filter((node) => isTypeOnlyNamedImport(node) && node.specifiers.length > max);
+        if (candidates.length === 0) {
+          return;
+        }
+        const sourceCode = context.sourceCode;
+        const occupied = new Set;
+        for (const scope of sourceCode.scopeManager.scopes) {
+          for (const variable of scope.variables) {
+            occupied.add(variable.name);
+          }
+          for (const reference of scope.references) {
+            occupied.add(reference.identifier.name);
+          }
+        }
+        const proposed = candidates.map((node) => namespaceName(node.source.value, names));
+        const comments = sourceCode.getAllComments();
+        const reports = [];
+        const edits = [];
+        for (const [index, node] of candidates.entries()) {
+          const name = proposed[index];
+          let reason = "";
+          const replacements = new Map;
+          if (!bindingName.test(name) || reservedNames.has(name)) {
+            reason = "invalid namespace binding";
+          } else if (imports.some((other) => other.source.value === node.source.value && other.specifiers.some((specifier) => specifier.type === "ImportNamespaceSpecifier"))) {
+            reason = "existing namespace import from this module";
+          } else if (occupied.has(name) || proposed.some((other, otherIndex) => otherIndex !== index && other === name)) {
+            reason = "namespace name collides with a binding, reference, or another proposed namespace";
+          } else if (comments.some((comment) => comment.range[0] >= node.range[0] && comment.range[1] <= node.range[1])) {
+            reason = "comment inside import";
+          } else {
+            const variables = sourceCode.getDeclaredVariables(node);
+            for (const specifier of node.specifiers) {
+              if (specifier.type !== "ImportSpecifier") {
+                continue;
+              }
+              const imported = specifier.imported.type === "Identifier" ? specifier.imported.name : specifier.imported.value;
+              const variable = variables.find((binding) => binding.identifiers.some((id) => id.range[0] === specifier.local.range[0]));
+              if (!bindingName.test(imported) || !variable || variable.defs.length !== 1) {
+                reason = "unsupported imported name or binding";
+                break;
+              }
+              for (const reference of variable.references) {
+                const identifier = reference.identifier;
+                if (identifier.parent.type === "ExportSpecifier") {
+                  reason = "local re-export";
+                  break;
+                }
+                if (!safeReference(identifier)) {
+                  reason = "unsupported reference syntax";
+                  break;
+                }
+                replacements.set(identifier, `${name}.${imported}`);
+              }
+              if (reason) {
+                break;
+              }
+            }
+          }
+          reports.push({ node, name, reason });
+          if (!reason) {
+            edits.push({ range: [node.range[0], node.source.range[0]], text: `import type * as ${name} from ` });
+            for (const [identifier, text] of replacements) {
+              edits.push({ range: identifier.range, text });
+            }
+          }
+        }
+        for (const { node, name, reason } of reports) {
+          context.report({
+            node,
+            messageId: "namespace",
+            data: { name, count: node.specifiers.length, max, reason: reason ? ` Autofix skipped: ${reason}.` : "" },
+            fix: reason ? undefined : (fixer) => edits.map((edit) => fixer.replaceTextRange(edit.range, edit.text))
+          });
+        }
+      }
+    };
+  }
+});
+
+// src/rules/require-file-factory.ts
+import { defineRule as defineRule38 } from "@oxlint/plugins";
+var requireFileFactory = defineRule38({
   meta: {
     type: "problem",
     schema: [{
@@ -4071,8 +4204,8 @@ var requireFileFactory = defineRule37({
 });
 
 // src/rules/require-object-params.ts
-import { defineRule as defineRule38 } from "@oxlint/plugins";
-var requireObjectParams = defineRule38({
+import { defineRule as defineRule39 } from "@oxlint/plugins";
+var requireObjectParams = defineRule39({
   meta: {
     type: "problem",
     schema: [{
@@ -4120,8 +4253,8 @@ var requireObjectParams = defineRule38({
 });
 
 // src/rules/require-orpc-output.ts
-import { defineRule as defineRule39 } from "@oxlint/plugins";
-var requireOrpcOutput = defineRule39({
+import { defineRule as defineRule40 } from "@oxlint/plugins";
+var requireOrpcOutput = defineRule40({
   meta: {
     type: "problem",
     schema: [{
@@ -4163,8 +4296,8 @@ var requireOrpcOutput = defineRule39({
 });
 
 // src/rules/require-paired-call.ts
-import { defineRule as defineRule40 } from "@oxlint/plugins";
-var requirePairedCall = defineRule40({
+import { defineRule as defineRule41 } from "@oxlint/plugins";
+var requirePairedCall = defineRule41({
   meta: {
     type: "problem",
     schema: [{
@@ -4239,8 +4372,8 @@ var requirePairedCall = defineRule40({
 });
 
 // src/rules/route-surface.ts
-import { defineRule as defineRule41 } from "@oxlint/plugins";
-var routeSurface = defineRule41({
+import { defineRule as defineRule42 } from "@oxlint/plugins";
+var routeSurface = defineRule42({
   meta: {
     type: "problem",
     schema: [{
@@ -4282,7 +4415,7 @@ var routeSurface = defineRule41({
 });
 
 // src/rules/test-title-pattern.ts
-import { defineRule as defineRule42 } from "@oxlint/plugins";
+import { defineRule as defineRule43 } from "@oxlint/plugins";
 var TEST_MODIFIERS = new Set(["only", "skip", "concurrent", "todo", "each"]);
 function isConfiguredName(name, callees) {
   if (!name) {
@@ -4322,7 +4455,7 @@ function regexMatches(regex, value) {
 function titlePatterns(pattern, flags) {
   return pattern === undefined ? [] : [pattern].flat().map((source) => ({ regex: new RegExp(source, flags), pattern: source }));
 }
-var testTitlePattern = defineRule42({
+var testTitlePattern = defineRule43({
   meta: {
     type: "suggestion",
     schema: [{
@@ -4433,6 +4566,7 @@ var src_default = eslintCompatPlugin({
     "only-export-components": onlyExportComponents,
     "only-export-constants": onlyExportConstants,
     "padding-between-statements": paddingBetweenStatements,
+    "prefer-namespace-type-import": preferNamespaceTypeImport,
     "require-file-factory": requireFileFactory,
     "require-object-params": requireObjectParams,
     "require-orpc-output": requireOrpcOutput,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxlint-plugin-arch",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Configurable architecture rules for Oxlint JavaScript plugins.",
   "type": "module",
   "main": "./dist/index.js",