@dxos/eslint-plugin-rules 0.8.3 → 0.8.4-main.1068cf700f

package/index.js

@@ -2,10 +2,47 @@
 // Copyright 2022 DXOS.org
 //
 
-module.exports = {
+import comment from './rules/comment.js';
+import effectSubpathImports from './rules/effect-subpath-imports.js';
+import header from './rules/header.js';
+import noEffectRunPromise from './rules/no-effect-run-promise.js';
+import noEmptyPromiseCatch from './rules/no-empty-promise-catch.js';
+import fs from 'node:fs';
+
+const pkg = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+
+const plugin = {
+  meta: {
+    name: pkg.name,
+    version: pkg.version,
+    namespace: 'example',
+  },
   rules: {
-    comment: require('./rules/comment'),
-    header: require('./rules/header'),
-    'no-empty-promise-catch': require('./rules/no-empty-promise-catch'),
+    comment,
+    'effect-subpath-imports': effectSubpathImports,
+    header,
+    'no-effect-run-promise': noEffectRunPromise,
+    'no-empty-promise-catch': noEmptyPromiseCatch,
+  },
+  configs: {
+    recommended: {
+      plugins: {
+        'dxos-plugin': null,
+      },
+      rules: {
+        'dxos-plugin/effect-subpath-imports': 'error',
+        'dxos-plugin/header': 'error',
+        'dxos-plugin/no-effect-run-promise': 'error',
+        'dxos-plugin/no-empty-promise-catch': 'error',
+        // TODO(dmaretskyi): Turned off due to large number of errors and no auto-fix.
+        // 'dxos-plugin/comment': 'error',
+      },
+    },
   },
 };
+
+Object.assign(plugin.configs.recommended.plugins, {
+  'dxos-plugin': plugin,
+});
+
+export default plugin;

package/moon.yml

@@ -0,0 +1,2 @@
+layer: library
+language: typescript

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@dxos/eslint-plugin-rules",
-  "version": "0.8.3",
+  "version": "0.8.4-main.1068cf700f",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "info@dxos.org",
   "sideEffects": true,
-  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  },
   "publishConfig": {
     "access": "public"
   }

package/rules/comment.js

@@ -10,7 +10,8 @@
 // Requires
 // ------------------------------------------------------------------------------
 
-const HEADER_PATTERN = require('./header').pattern;
+import header from './header.js';
+const HEADER_PATTERN = header.pattern;
 
 // ------------------------------------------------------------------------------
 // Helpers
@@ -88,7 +89,7 @@ const createRegExpForIgnorePatterns = (normalizedOptions) => {
 // Rule Definition
 // ------------------------------------------------------------------------------
 
-module.exports = {
+export default {
   meta: {
     type: 'layout',
 

package/rules/effect-subpath-imports.js

@@ -0,0 +1,284 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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.
+ * @example
+ * // before
+ * import { type Schema, SchemaAST } from 'effect';
+ *
+ * // after
+ * import type * as Schema from 'effect/Schema'
+ * import * as SchemaAST from 'effect/SchemaAST'
+ */
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'enforce subpath imports for Effect packages',
+    },
+    fixable: 'code',
+    schema: [],
+  },
+  create: (context) => {
+    // Resolver and caches are scoped to this lint run.
+    const requireForFile = createRequire(context.getFilename());
+    const exportsCache = new Map(); // packageName -> Set<segment>
+
+    const loadExportsForPackage = (pkgName) => {
+      if (exportsCache.has(pkgName)) return exportsCache.get(pkgName);
+      try {
+        const pkgJson = requireForFile(`${pkgName}/package.json`);
+        const ex = pkgJson && pkgJson.exports;
+        const segments = new Set();
+        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));
+          }
+        }
+        exportsCache.set(pkgName, segments);
+        return segments;
+      } catch {
+        const empty = new Set();
+        exportsCache.set(pkgName, empty);
+        return empty;
+      }
+    };
+
+    const isValidSubpath = (pkgName, segment) => {
+      const exported = loadExportsForPackage(pkgName);
+      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/');
+    };
+
+    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.
+     * @returns {string} The base package name.
+     * @example
+     * getBasePackage('effect/Schema') // 'effect'
+     * getBasePackage('@effect/ai/openai') // '@effect/ai'
+     */
+    const getBasePackage = (source) => {
+      if (source.startsWith('@')) {
+        const parts = source.split('/');
+        return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : source;
+      } else {
+        return source.split('/')[0];
+      }
+    };
+
+    return {
+      ImportDeclaration: (node) => {
+        const source = String(node.source.value);
+        if (!isEffectPackage(source)) return;
+        const basePackage = getBasePackage(source);
+        if (shouldSkipEffectPackage(basePackage)) return;
+
+        // 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 (!allowsNamed && !isNamespaceOnly) {
+            context.report({
+              node,
+              message: 'Use namespace import for Effect subpaths',
+            });
+          }
+          return;
+        }
+
+        // From here on, we only handle root package imports like 'effect'.
+        const packageName = basePackage;
+
+        // Only process imports with specifiers.
+        if (!node.specifiers || node.specifiers.length === 0) {
+          return;
+        }
+
+        // Only process named imports.
+        const hasNamedImports = node.specifiers.some((spec) => spec.type === 'ImportSpecifier');
+
+        if (!hasNamedImports) {
+          return;
+        }
+
+        // Group specifiers by type.
+        const typeImports = [];
+        const regularImports = [];
+        for (const specifier of node.specifiers) {
+          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);
+        }
+
+        // Partition into resolvable vs unresolved specifiers (resolved entries include segment for fix).
+        const resolvedType = [];
+        const unresolvedType = [];
+        const resolvedRegular = [];
+        const unresolvedRegular = [];
+
+        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);
+
+        // Report and autofix: fix resolvable ones; keep unresolved in a remaining combined import.
+        context.report({
+          node,
+          message:
+            unresolved.length > 0
+              ? `Use subpath imports for Effect packages; unresolved kept in base import: ${unresolved.join(', ')}`
+              : 'Use subpath imports for Effect packages',
+          fix: (fixer) => {
+            const sourceCode = context.getSourceCode();
+            const imports = [];
+
+            // Idempotency guard: if nothing is resolvable, do not rewrite.
+            if (resolvedType.length === 0 && resolvedRegular.length === 0) {
+              return null;
+            }
+
+            // 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);
+            });
+            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.
+              const byLocal = new Map(); // local -> { value?: {imported,local}, type?: {imported,local} }
+              unresolvedRegular.forEach((s) => {
+                const entry = byLocal.get(s.local) ?? {};
+                entry.value = s;
+                byLocal.set(s.local, entry);
+              });
+              unresolvedType.forEach((s) => {
+                const entry = byLocal.get(s.local) ?? {};
+                if (!entry.value) entry.type = s; // only keep type if no value for same local
+                byLocal.set(s.local, entry);
+              });
+
+              const specParts = [];
+              for (const entry of byLocal.values()) {
+                if (entry.value) {
+                  const { imported, local } = entry.value;
+                  const part = imported !== local ? `${imported} as ${local}` : `${imported}`;
+                  specParts.push(part);
+                } else if (entry.type) {
+                  const { imported, local } = entry.type;
+                  const part = imported !== local ? `type ${imported} as ${local}` : `type ${imported}`;
+                  specParts.push(part);
+                }
+              }
+              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
+            const newImports = imports.join('\n' + importIndent);
+
+            return fixer.replaceText(node, newImports);
+          },
+        });
+      },
+    };
+  },
+};

package/rules/header.js

@@ -5,7 +5,7 @@
 const REGEX = /Copyright [0-9]+ DXOS.org/;
 const TEMPLATE = ['//', `// Copyright ${new Date().getFullYear()} DXOS.org`, '//', ''].join('\n') + '\n';
 
-module.exports = {
+export default {
   pattern: REGEX,
   meta: {
     type: 'layout',
@@ -19,7 +19,7 @@ module.exports = {
   create: (context) => {
     return {
       Program: (node) => {
-        if (!context.getSource().match(REGEX)) {
+        if (!context.sourceCode.getText().match(REGEX)) {
           context.report({
             node,
             message: 'Missing copyright header',

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',
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/no-empty-promise-catch.js

@@ -9,7 +9,7 @@ const isCatchCallSite = (expression) =>
   expression.callee.type === 'MemberExpression' &&
   expression.callee.property.name === 'catch';
 
-module.exports = {
+export default {
   meta: {
     type: 'problem',
     fixable: 'code',

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": [
+    "**/*"
+  ],
+  "references": []
+}

package/.eslintrc.cjs

@@ -1,9 +0,0 @@
-module.exports = {
-  "extends": [
-    "../../../.eslintrc.js"
-  ],
-  "parserOptions": {
-    "project": "tsconfig.json",
-    "tsconfigRootDir": __dirname,
-  }
-}

package/project.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
-  "name": "eslint-rules",
-  "tags": [
-    "scope:common"
-  ],
-  "sourceRoot": "tools/eslint-plugin-rules",
-  "projectType": "library",
-  "targets": {
-    "lint": {}
-  }
-}