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

package/docs/2025-04-03-translation-key-normalization-design.md

@@ -0,0 +1,94 @@
+# Translation Key Normalization
+
+## Status
+
+ESLint rule and migration script ready. Tested on `plugin-chess`.
+
+## Problem
+
+1,326 translation keys across 56 plugins use inconsistent space-separated naming with no enforced suffix convention. 135 keys lack a type suffix entirely. This makes it hard to grep, autocomplete, or validate keys.
+
+## Convention
+
+**Format:** `segment.kebab-case.suffix`
+
+```
+settings.debug.label
+add-comment.label
+object-name.placeholder
+add-section.before-dialog.title
+typename.label_other
+```
+
+### Rules
+
+- Every key ends with a **type suffix**: `label | message | placeholder | title | description | heading | alt | button`.
+- Plural suffixes append after the type suffix: `typename.label_zero`, `lobby.participants_other`.
+- Dots separate hierarchical segments; segments use kebab-case.
+- `plugin name` keys become `plugin.label`.
+
+## Tools
+
+### 1. ESLint Rule (ongoing enforcement)
+
+`packages/common/eslint-plugin-rules/rules/translation-key-format.js`
+
+Registered in `.oxlintrc.json` as `@dxos/eslint-plugin-rules/translation-key-format` (currently `warn`).
+
+**Checks:**
+
+- `useDotsNotSpaces` — flags space-separated keys, suggests dot.kebab-case, auto-fixable.
+- `missingSuffix` — flags keys missing a valid type suffix (not auto-fixable, needs human decision).
+
+**Catches violations in:**
+
+- `t('key')` calls in source files.
+- Property keys in `translations.ts` files (string literal keys with string literal values).
+
+**Auto-fix:** `moon run plugin-name:lint -- --fix` rewrites both definitions and usages.
+
+**Promote to error** once migration is complete to prevent regressions.
+
+### 2. Checker Script (bulk analysis)
+
+`scripts/check-translations.mts` — run via `npx tsx scripts/check-translations.mts`.
+
+Reports:
+
+| Check                                  | Current Count |
+| -------------------------------------- | ------------- |
+| Missing keys (used but undefined)      | 68            |
+| Unused keys (defined but unreferenced) | 444           |
+| Incomplete plurals                     | 8             |
+| Missing suffix                         | 135           |
+| Non-hierarchical (space-separated)     | 1,326         |
+
+Use this for bulk analysis, migration planning, and tracking progress.
+
+## Migration Plan
+
+### Step 1: Fix known edge cases in normalizer
+
+- `plugin name` → `plugin.label` (special case).
+- Keys ending in nouns (`key`, `name`, `count`, `period`) that aren't valid suffixes need a suffix appended.
+
+### Step 2: Migrate incrementally with `--fix`
+
+Per plugin: `moon run plugin-name:lint -- --fix`, then verify with `moon run plugin-name:lint`.
+
+Start with small plugins (`plugin-chess`, `plugin-template`), then batch the rest.
+
+### Step 3: Validate
+
+- Re-run checker script to confirm counts decrease.
+- Build + test the migrated plugins.
+
+### Step 4: Promote to error
+
+Change `.oxlintrc.json` from `"warn"` to `"error"` once all plugins are clean.
+
+## Out of Scope
+
+- Moving to JSON files.
+- Cleaning up unused keys (separate effort using checker output).
+- UI packages / `osTranslations` namespace (phase 2).

package/docs/README.md

@@ -1,7 +1,5 @@
 # @dxos/eslint-plugin-rules
 
-
-
 ## Dependency Graph
 
 ```mermaid
@@ -28,4 +26,4 @@ linkStyle default stroke:#333,stroke-width:1px
 ## Dependencies
 
 | Module | Direct |
-|---|---|
+| ------ | ------ |

package/index.js

@@ -2,11 +2,17 @@
 // Copyright 2022 DXOS.org
 //
 
+import fs from 'node:fs';
+
 import comment from './rules/comment.js';
+import consistentUpdateParam from './rules/consistent-update-param.js';
 import effectSubpathImports from './rules/effect-subpath-imports.js';
 import header from './rules/header.js';
+import importAsNamespace from './rules/import-as-namespace.js';
+import noBareDotImports from './rules/no-bare-dot-imports.js';
+import noEffectRunPromise from './rules/no-effect-run-promise.js';
 import noEmptyPromiseCatch from './rules/no-empty-promise-catch.js';
-import fs from 'node:fs';
+import translationKeyFormat from './rules/translation-key-format.js';
 
 const pkg = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
 
@@ -18,9 +24,14 @@ const plugin = {
   },
   rules: {
     comment,
+    'consistent-update-param': consistentUpdateParam,
     'effect-subpath-imports': effectSubpathImports,
     header,
+    'import-as-namespace': importAsNamespace,
+    'no-bare-dot-imports': noBareDotImports,
+    'no-effect-run-promise': noEffectRunPromise,
     'no-empty-promise-catch': noEmptyPromiseCatch,
+    'translation-key-format': translationKeyFormat,
   },
   configs: {
     recommended: {
@@ -30,6 +41,9 @@ const plugin = {
       rules: {
         'dxos-plugin/effect-subpath-imports': 'error',
         'dxos-plugin/header': 'error',
+        'dxos-plugin/import-as-namespace': 'error',
+        'dxos-plugin/no-bare-dot-imports': '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',

package/moon.yml

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

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@dxos/eslint-plugin-rules",
-  "version": "0.8.4-main.ae835ea",
+  "version": "0.8.4-main.bbf232bc24",
   "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,

package/rules/consistent-update-param.js

@@ -0,0 +1,143 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * ESLint rule to enforce that the callback parameter name in Obj.update(),
+ * Relation.update(), and Entity.update() matches the first argument name.
+ *
+ * @example
+ * // ❌ Bad
+ * Obj.update(trigger, (t) => { t.enabled = true; });
+ * Obj.update(trigger, (mutableTrigger) => { mutableTrigger.enabled = true; });
+ *
+ * // ✅ Good
+ * Obj.update(trigger, (trigger) => { trigger.enabled = true; });
+ */
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Enforce callback parameter name matches the first argument in Obj.update, Relation.update, and Entity.update.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      mismatchedName:
+        'Callback parameter "{{callbackParam}}" should be "{{firstArg}}" to match the first argument of {{caller}}.update().',
+    },
+  },
+  create(context) {
+    /** Yield all Identifier reference nodes for `name` inside `node`, respecting scope shadowing. */
+    function* collectReferences(node, name) {
+      if (!node || typeof node !== 'object' || !node.type) {
+        return;
+      }
+
+      if (
+        node.type === 'ArrowFunctionExpression' ||
+        node.type === 'FunctionExpression' ||
+        node.type === 'FunctionDeclaration'
+      ) {
+        if (node.params?.some((p) => p.type === 'Identifier' && p.name === name)) {
+          return;
+        }
+        yield* collectReferences(node.body, name);
+        return;
+      }
+
+      if (node.type === 'Identifier' && node.name === name) {
+        yield node;
+        return;
+      }
+
+      for (const key of Object.keys(node)) {
+        if (key === 'parent') {
+          continue;
+        }
+        if (node.type === 'MemberExpression' && key === 'property' && !node.computed) {
+          continue;
+        }
+        if (node.type === 'Property' && key === 'key' && !node.computed && !node.shorthand) {
+          continue;
+        }
+
+        const child = node[key];
+        if (Array.isArray(child)) {
+          for (const item of child) {
+            if (item && typeof item === 'object' && item.type) {
+              yield* collectReferences(item, name);
+            }
+          }
+        } else if (child && typeof child === 'object' && child.type) {
+          yield* collectReferences(child, name);
+        }
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        const { callee } = node;
+
+        if (
+          callee.type !== 'MemberExpression' ||
+          callee.object.type !== 'Identifier' ||
+          !['Obj', 'Relation', 'Entity'].includes(callee.object.name) ||
+          callee.property.type !== 'Identifier' ||
+          callee.property.name !== 'update'
+        ) {
+          return;
+        }
+
+        const args = node.arguments;
+        if (args.length < 2) {
+          return;
+        }
+
+        const firstArg = args[0];
+        const callback = args[1];
+
+        if (firstArg.type !== 'Identifier') {
+          return;
+        }
+        if (callback.type !== 'ArrowFunctionExpression' && callback.type !== 'FunctionExpression') {
+          return;
+        }
+        if (callback.params.length !== 1) {
+          return;
+        }
+
+        const param = callback.params[0];
+        if (param.type !== 'Identifier') {
+          return;
+        }
+        if (param.name === firstArg.name) {
+          return;
+        }
+
+        context.report({
+          node: param,
+          messageId: 'mismatchedName',
+          data: {
+            callbackParam: param.name,
+            firstArg: firstArg.name,
+            caller: callee.object.name,
+          },
+          fix(fixer) {
+            const oldName = param.name;
+            const newName = firstArg.name;
+
+            const fixes = [fixer.replaceTextRange([param.range[0], param.range[0] + oldName.length], newName)];
+            for (const ref of collectReferences(callback.body, oldName)) {
+              fixes.push(fixer.replaceTextRange([ref.range[0], ref.range[0] + oldName.length], newName));
+            }
+            return fixes;
+          },
+        });
+      },
+    };
+  },
+};

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);