@dxos/eslint-plugin-rules 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/rules/effect-subpath-imports.js

@@ -4,9 +4,23 @@
 
 import { createRequire } from 'node:module';
 
-
 const EXCLUDED_EFFECT_PACKAGES = ['@effect/vitest'];
 
+/**
+ * Map of Effect base-package exports that come from a subpath (not a direct segment).
+ * Used when resolving imports like `import { pipe } from 'effect'` → effect/Function.
+ */
+const EFFECT_EXPORT_TO_SUBPATH = {
+  pipe: 'Function',
+  flow: 'Function',
+};
+
+/**
+ * Subpaths that allow named imports (e.g. `import { pipe, flow } from 'effect/Function'`).
+ * Other subpaths still require namespace imports.
+ */
+const NAMED_IMPORT_ALLOWED_SUBPATHS = new Set(['Function']);
+
 /**
  * ESLint rule to transform combined imports from 'effect' and '@effect/*'
  * into subpath imports except for the EXCLUDED_EFFECT_PACKAGES.
@@ -33,7 +47,9 @@ export default {
     const exportsCache = new Map(); // packageName -> Set<segment>
 
     const loadExportsForPackage = (pkgName) => {
-      if (exportsCache.has(pkgName)) return exportsCache.get(pkgName);
+      if (exportsCache.has(pkgName)) {
+        return exportsCache.get(pkgName);
+      }
       try {
         const pkgJson = requireForFile(`${pkgName}/package.json`);
         const ex = pkgJson && pkgJson.exports;
@@ -41,8 +57,12 @@ export default {
         if (ex && typeof ex === 'object') {
           for (const key of Object.keys(ex)) {
             // Keys like './Schema', './SchemaAST', './Function' (skip '.' and './package.json').
-            if (key === '.' || key === './package.json') continue;
-            if (key.startsWith('./')) segments.add(key.slice(2));
+            if (key === '.' || key === './package.json') {
+              continue;
+            }
+            if (key.startsWith('./')) {
+              segments.add(key.slice(2));
+            }
           }
         }
         exportsCache.set(pkgName, segments);
@@ -59,6 +79,17 @@ export default {
       return exported.has(segment);
     };
 
+    const resolveExportToSegment = (pkgName, exportName) => {
+      if (isValidSubpath(pkgName, exportName)) {
+        return exportName;
+      }
+      if (pkgName === 'effect' && EFFECT_EXPORT_TO_SUBPATH[exportName]) {
+        const segment = EFFECT_EXPORT_TO_SUBPATH[exportName];
+        return isValidSubpath(pkgName, segment) ? segment : null;
+      }
+      return null;
+    };
+
     const isEffectPackage = (source) => {
       return source === 'effect' || source.startsWith('effect/') || source.startsWith('@effect/');
     };
@@ -66,7 +97,7 @@ export default {
     const shouldSkipEffectPackage = (basePackage) => {
       return EXCLUDED_EFFECT_PACKAGES.includes(basePackage);
     };
-    
+
     /**
      * Get the base package name from a source string.
      * @param {string} source - The source string to get the base package name from.
@@ -87,15 +118,21 @@ export default {
     return {
       ImportDeclaration: (node) => {
         const source = String(node.source.value);
-        if (!isEffectPackage(source)) return;
+        if (!isEffectPackage(source)) {
+          return;
+        }
         const basePackage = getBasePackage(source);
-        if (shouldSkipEffectPackage(basePackage)) return;
+        if (shouldSkipEffectPackage(basePackage)) {
+          return;
+        }
 
-        // If it's a subpath import (e.g., 'effect/Schema'), enforce namespace import only.
+        // If it's a subpath import (e.g., 'effect/Schema'), enforce namespace import except for allowed subpaths.
         if (source.startsWith(basePackage + '/')) {
+          const segment = source.slice(basePackage.length + 1);
+          const allowsNamed = NAMED_IMPORT_ALLOWED_SUBPATHS.has(segment);
           const isNamespaceOnly =
             node.specifiers.length === 1 && node.specifiers[0].type === 'ImportNamespaceSpecifier';
-          if (!isNamespaceOnly) {
+          if (!allowsNamed && !isNamespaceOnly) {
             context.report({
               node,
               message: 'Use namespace import for Effect subpaths',
@@ -123,24 +160,39 @@ export default {
         const typeImports = [];
         const regularImports = [];
         for (const specifier of node.specifiers) {
-          if (specifier.type !== 'ImportSpecifier') continue;
+          if (specifier.type !== 'ImportSpecifier') {
+            continue;
+          }
           const entry = { imported: specifier.imported.name, local: specifier.local.name };
-          if (specifier.importKind === 'type') typeImports.push(entry);
-          else regularImports.push(entry);
+          if (specifier.importKind === 'type') {
+            typeImports.push(entry);
+          } else {
+            regularImports.push(entry);
+          }
         }
 
-        // Partition into resolvable vs unresolved specifiers.
+        // Partition into resolvable vs unresolved specifiers (resolved entries include segment for fix).
         const resolvedType = [];
         const unresolvedType = [];
         const resolvedRegular = [];
         const unresolvedRegular = [];
 
-        typeImports.forEach((s) =>
-          isValidSubpath(packageName, s.imported) ? resolvedType.push(s) : unresolvedType.push(s),
-        );
-        regularImports.forEach((s) =>
-          isValidSubpath(packageName, s.imported) ? resolvedRegular.push(s) : unresolvedRegular.push(s),
-        );
+        typeImports.forEach((spec) => {
+          const segment = resolveExportToSegment(packageName, spec.imported);
+          if (segment) {
+            resolvedType.push({ ...spec, segment });
+          } else {
+            unresolvedType.push(spec);
+          }
+        });
+        regularImports.forEach((spec) => {
+          const segment = resolveExportToSegment(packageName, spec.imported);
+          if (segment) {
+            resolvedRegular.push({ ...spec, segment });
+          } else {
+            unresolvedRegular.push(spec);
+          }
+        });
 
         const unresolved = [...unresolvedType, ...unresolvedRegular].map(({ imported }) => imported);
 
@@ -160,27 +212,59 @@ export default {
               return null;
             }
 
-            // Prefer regular (value) imports over type imports on duplicates.
-            const seenResolved = new Set(); // key: `${alias}|${segment}`
-
-            // First, emit value imports and record keys.
-            resolvedRegular.forEach(({ imported, local }) => {
-              const alias = imported !== local ? local : imported;
-              const key = `${alias}|${imported}`;
-              if (seenResolved.has(key)) return;
-              seenResolved.add(key);
-              imports.push(`import * as ${alias} from '${packageName}/${imported}';`);
+            // Group resolved imports by segment.
+            const bySegment = new Map(); // segment -> { regular: [...], type: [...] }
+            resolvedRegular.forEach((entry) => {
+              const seg = entry.segment;
+              let group = bySegment.get(seg);
+              if (!group) {
+                group = { regular: [], type: [] };
+                bySegment.set(seg, group);
+              }
+              group.regular.push(entry);
             });
-
-            // Then, emit type imports only if a value import for the same alias/segment was not emitted.
-            resolvedType.forEach(({ imported, local }) => {
-              const alias = imported !== local ? local : imported;
-              const key = `${alias}|${imported}`;
-              if (seenResolved.has(key)) return; // skip type if value exists
-              seenResolved.add(key);
-              imports.push(`import type * as ${alias} from '${packageName}/${imported}';`);
+            resolvedType.forEach((entry) => {
+              const seg = entry.segment;
+              let group = bySegment.get(seg);
+              if (!group) {
+                group = { regular: [], type: [] };
+                bySegment.set(seg, group);
+              }
+              group.type.push(entry);
             });
 
+            for (const [segment, group] of bySegment) {
+              const useNamed = NAMED_IMPORT_ALLOWED_SUBPATHS.has(segment);
+              const merged = [...group.regular];
+              for (const t of group.type) {
+                if (!group.regular.some((r) => r.local === t.local)) {
+                  merged.push(t);
+                }
+              }
+              if (useNamed && merged.length > 0) {
+                const specParts = merged.map(({ imported, local }) =>
+                  imported !== local ? `${imported} as ${local}` : imported,
+                );
+                imports.push(`import { ${specParts.join(', ')} } from '${packageName}/${segment}';`);
+              } else {
+                const seen = new Set();
+                for (const { imported, local } of merged) {
+                  const alias = imported !== local ? local : imported;
+                  if (seen.has(alias)) {
+                    continue;
+                  }
+                  seen.add(alias);
+                  const isTypeOnly =
+                    group.type.some((t) => t.imported === imported) &&
+                    !group.regular.some((r) => r.imported === imported);
+                  const importStr = isTypeOnly
+                    ? `import type * as ${alias} from '${packageName}/${segment}';`
+                    : `import * as ${alias} from '${packageName}/${segment}';`;
+                  imports.push(importStr);
+                }
+              }
+            }
+
             // If there are unresolved, keep them in a single base import.
             if (unresolvedType.length || unresolvedRegular.length) {
               // Prefer value over type for the same local alias when both are present.
@@ -192,7 +276,9 @@ export default {
               });
               unresolvedType.forEach((s) => {
                 const entry = byLocal.get(s.local) ?? {};
-                if (!entry.value) entry.type = s; // only keep type if no value for same local
+                if (!entry.value) {
+                  entry.type = s;
+                } // only keep type if no value for same local
                 byLocal.set(s.local, entry);
               });
 
@@ -208,14 +294,18 @@ export default {
                   specParts.push(part);
                 }
               }
-              if (specParts.length) imports.push(`import { ${specParts.join(', ')} } from '${packageName}';`);
+              if (specParts.length) {
+                imports.push(`import { ${specParts.join(', ')} } from '${packageName}';`);
+              }
             }
 
             // Get the original import's indentation.
             const importIndent = sourceCode.text.slice(node.range[0] - node.loc.start.column, node.range[0]);
 
             // Join imports with newline and proper indentation.
-            if (imports.length === 0) return null; // nothing to change
+            if (imports.length === 0) {
+              return null;
+            } // nothing to change
             const newImports = imports.join('\n' + importIndent);
 
             return fixer.replaceText(node, newImports);

package/rules/import-as-namespace.js

@@ -0,0 +1,271 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DIRECTIVE_TEXT = '@import-as-namespace';
+const DIRECTIVE_LINE_REGEX = /^\s*\/\/\s*@import-as-namespace\s*$/m;
+const PASCAL_CASE_REGEX = /^[A-Z][a-zA-Z0-9]*$/;
+const TS_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+/**
+ * ESLint rule to enforce namespace imports for modules annotated with `// @import-as-namespace`.
+ *
+ * When a module contains the `// @import-as-namespace` directive comment, this rule enforces:
+ * - The module filename is PascalCase (e.g. `LanguageModel.ts`).
+ * - All imports of the module use namespace form: `import * as LanguageModel from './LanguageModel'`.
+ * - The namespace name matches the filename (without extension), or has a `Module` suffix.
+ * - Re-exports use namespace form: `export * as LanguageModel from './LanguageModel'`.
+ *
+ * The `Module` suffix is allowed as an escape hatch when the expected namespace name conflicts
+ * with a local declaration in the importing file (e.g., `import * as ObjModule from './Obj'`
+ * when the file also exports its own `Obj` interface).
+ *
+ * @example
+ * // In LanguageModel.ts:
+ * // @import-as-namespace
+ * export const foo = 1;
+ *
+ * // ❌ Bad (in another file):
+ * import { foo } from './LanguageModel';
+ * export { foo } from './LanguageModel';
+ * export * from './LanguageModel';
+ *
+ * // ✅ Good:
+ * import * as LanguageModel from './LanguageModel';
+ * import * as LanguageModelModule from './LanguageModel';  // Also allowed when needed
+ * export * as LanguageModel from './LanguageModel';
+ */
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'enforce namespace imports for modules marked with @import-as-namespace',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      filenameMustBePascalCase:
+        'Module marked with @import-as-namespace must have a PascalCase filename. Got: "{{filename}}".',
+      mustUseNamespaceImport:
+        'Module "{{source}}" is marked @import-as-namespace. Use: `import * as {{namespace}} from \'{{source}}\'`.',
+      namespaceMustMatchFilename: 'Namespace import name "{{actual}}" must match filename "{{expected}}".',
+      mustUseNamespaceReexport:
+        'Module "{{source}}" is marked @import-as-namespace. Use: `export * as {{namespace}} from \'{{source}}\'`.',
+    },
+  },
+  create: (context) => {
+    const directiveCache = new Map();
+
+    const fileHasDirective = (filePath) => {
+      if (directiveCache.has(filePath)) {
+        return directiveCache.get(filePath);
+      }
+      try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const result = DIRECTIVE_LINE_REGEX.test(content);
+        directiveCache.set(filePath, result);
+        return result;
+      } catch {
+        directiveCache.set(filePath, false);
+        return false;
+      }
+    };
+
+    const resolveRelativeImport = (source, currentFile) => {
+      if (!source.startsWith('.')) {
+        return null;
+      }
+      const dir = path.dirname(currentFile);
+      const resolved = path.resolve(dir, source);
+      for (const ext of TS_EXTENSIONS) {
+        const filePath = resolved + ext;
+        if (fs.existsSync(filePath)) {
+          return filePath;
+        }
+      }
+      for (const ext of TS_EXTENSIONS) {
+        const filePath = path.join(resolved, 'index' + ext);
+        if (fs.existsSync(filePath)) {
+          return filePath;
+        }
+      }
+      return null;
+    };
+
+    const namespaceFromSource = (source) => {
+      const parts = source.split('/');
+      const last = parts[parts.length - 1];
+      return last.replace(/\.\w+$/, '');
+    };
+
+    const buildImportFix = (fixer, node, source, expectedNamespace, context) => {
+      const fixes = [];
+      const importKeyword = node.importKind === 'type' ? 'import type' : 'import';
+      fixes.push(fixer.replaceText(node, `${importKeyword} * as ${expectedNamespace} from '${source}';`));
+
+      try {
+        const declaredVars = context.sourceCode.getDeclaredVariables(node);
+        for (const variable of declaredVars) {
+          for (const ref of variable.references) {
+            if (ref.identifier.range[0] >= node.range[0] && ref.identifier.range[1] <= node.range[1]) {
+              continue;
+            }
+            fixes.push(fixer.replaceText(ref.identifier, `${expectedNamespace}.${variable.name}`));
+          }
+        }
+      } catch {
+        // Scope analysis unavailable; fix import declaration only.
+      }
+
+      return fixes;
+    };
+
+    return {
+      Program: (node) => {
+        const comments = context.sourceCode.getAllComments();
+        const hasDirective = comments.some(
+          (comment) => comment.type === 'Line' && comment.value.trim() === DIRECTIVE_TEXT,
+        );
+        if (!hasDirective) {
+          return;
+        }
+        const filename = path.basename(context.getFilename());
+        const stem = filename.replace(/\.\w+$/, '');
+        if (!PASCAL_CASE_REGEX.test(stem)) {
+          context.report({
+            node,
+            messageId: 'filenameMustBePascalCase',
+            data: { filename },
+          });
+        }
+      },
+
+      ImportDeclaration: (node) => {
+        const source = String(node.source.value);
+        if (!source.startsWith('.')) {
+          return;
+        }
+        if (!node.specifiers || node.specifiers.length === 0) {
+          return;
+        }
+
+        const currentFile = context.getFilename();
+        const resolved = resolveRelativeImport(source, currentFile);
+        if (!resolved) {
+          return;
+        }
+        if (!fileHasDirective(resolved)) {
+          return;
+        }
+
+        const expectedNamespace = namespaceFromSource(source);
+
+        const isNamespaceImport =
+          node.specifiers.length === 1 && node.specifiers[0].type === 'ImportNamespaceSpecifier';
+
+        if (!isNamespaceImport) {
+          context.report({
+            node,
+            messageId: 'mustUseNamespaceImport',
+            data: { source, namespace: expectedNamespace },
+            fix: (fixer) => buildImportFix(fixer, node, source, expectedNamespace, context),
+          });
+          return;
+        }
+
+        const actual = node.specifiers[0].local.name;
+        const allowedNames = [expectedNamespace, expectedNamespace + 'Module'];
+        if (!allowedNames.includes(actual)) {
+          context.report({
+            node,
+            messageId: 'namespaceMustMatchFilename',
+            data: { actual, expected: expectedNamespace },
+            fix: (fixer) => {
+              const importKeyword = node.importKind === 'type' ? 'import type' : 'import';
+              return fixer.replaceText(node, `${importKeyword} * as ${expectedNamespace} from '${source}';`);
+            },
+          });
+        }
+      },
+
+      ExportNamedDeclaration: (node) => {
+        if (!node.source) {
+          return;
+        }
+        const source = String(node.source.value);
+        if (!source.startsWith('.')) {
+          return;
+        }
+
+        const currentFile = context.getFilename();
+        const resolved = resolveRelativeImport(source, currentFile);
+        if (!resolved) {
+          return;
+        }
+        if (!fileHasDirective(resolved)) {
+          return;
+        }
+
+        const expectedNamespace = namespaceFromSource(source);
+        const exportKeyword = node.exportKind === 'type' ? 'export type' : 'export';
+        context.report({
+          node,
+          messageId: 'mustUseNamespaceReexport',
+          data: { source, namespace: expectedNamespace },
+          fix: (fixer) => {
+            return fixer.replaceText(node, `${exportKeyword} * as ${expectedNamespace} from '${source}';`);
+          },
+        });
+      },
+
+      ExportAllDeclaration: (node) => {
+        if (!node.source) {
+          return;
+        }
+        const source = String(node.source.value);
+        if (!source.startsWith('.')) {
+          return;
+        }
+
+        const currentFile = context.getFilename();
+        const resolved = resolveRelativeImport(source, currentFile);
+        if (!resolved) {
+          return;
+        }
+        if (!fileHasDirective(resolved)) {
+          return;
+        }
+
+        const expectedNamespace = namespaceFromSource(source);
+
+        if (node.exported) {
+          const actual = node.exported.name;
+          const allowedNames = [expectedNamespace, expectedNamespace + 'Module'];
+          if (!allowedNames.includes(actual)) {
+            context.report({
+              node,
+              messageId: 'namespaceMustMatchFilename',
+              data: { actual, expected: expectedNamespace },
+              fix: (fixer) => {
+                return fixer.replaceText(node, `export * as ${expectedNamespace} from '${source}';`);
+              },
+            });
+          }
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: 'mustUseNamespaceReexport',
+          data: { source, namespace: expectedNamespace },
+          fix: (fixer) => {
+            return fixer.replaceText(node, `export * as ${expectedNamespace} from '${source}';`);
+          },
+        });
+      },
+    };
+  },
+};

package/rules/no-bare-dot-imports.js

@@ -0,0 +1,55 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * ESLint rule to prevent bare "." or ".." imports.
+ * These imports are ambiguous as they don't explicitly show which file is being imported.
+ *
+ * @example
+ * // ❌ Bad
+ * import { foo } from '.';
+ * import { bar } from '..';
+ *
+ * // ✅ Good
+ * import { foo } from './index';
+ * import { bar } from '../index';
+ */
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow bare "." or ".." in import paths',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      bareDotImport: 'Use explicit path instead of bare "{{source}}". Consider "{{suggestion}}" instead.',
+    },
+  },
+  create: (context) => {
+    return {
+      ImportDeclaration: (node) => {
+        const source = node.source.value;
+
+        // Check if the import is exactly "." or ".."
+        if (source === '.' || source === '..') {
+          context.report({
+            node: node.source,
+            messageId: 'bareDotImport',
+            data: {
+              source,
+              suggestion: source === '.' ? './index' : '../index',
+            },
+            fix: (fixer) => {
+              const newSource = source === '.' ? './index' : '../index';
+              return fixer.replaceText(node.source, `'${newSource}'`);
+            },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/no-effect-run-promise.js

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+'use strict';
+
+/**
+ * ESLint rule to prevent usage of Effect.runPromise and Effect.runPromiseExit,
+ * and suggest runAndForwardErrors instead.
+ * @example
+ * // bad
+ * await Effect.runPromise(myEffect);
+ * await Effect.runPromiseExit(myEffect);
+ *
+ * // good
+ * await runAndForwardErrors(myEffect);
+ */
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow Effect.runPromise; suggest runAndForwardErrors instead.',
+      recommended: true,
+    },
+    messages: {
+      noRunPromise: 'Use runAndForwardErrors from @dxos/effect instead of Effect.runPromise.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        // Check if this is Effect.runPromise or Effect.runPromiseExit
+        const isEffectMethod =
+          node.callee.type === 'MemberExpression' &&
+          node.callee.object.type === 'Identifier' &&
+          node.callee.object.name === 'Effect' &&
+          node.callee.property.type === 'Identifier';
+
+        if (isEffectMethod) {
+          const methodName = node.callee.property.name;
+          if (methodName === 'runPromise') {
+            context.report({
+              node,
+              messageId: 'noRunPromise',
+            });
+          }
+        }
+      },
+    };
+  },
+};