@dxos/eslint-plugin-rules 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

package/LICENSE

@@ -1,8 +1,105 @@
-MIT License 
-Copyright (c) 2022 DXOS
+# Functional Source License, Version 1.1, ALv2 Future License
 
-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:
+## Abbreviation
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+FSL-1.1-Apache-2.0
 
-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.
+## Notice
+
+Copyright 2026 DXOS
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -16,4 +16,4 @@ pnpm i @dxos/eslint-plugin-rules
 
 Your ideas, issues, and code are most welcome. Please take a look at our [community code of conduct](https://github.com/dxos/dxos/blob/main/CODE_OF_CONDUCT.md), the [issue guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-issues), and the [PR contribution guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-prs).
 
-License: [MIT](./LICENSE) Copyright 2022 © DXOS
+License: [FSL-1.1-Apache-2.0](./LICENSE) Copyright 2022 © DXOS

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,12 +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'));
 
@@ -19,10 +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: {
@@ -32,6 +41,8 @@ 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.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dxos/eslint-plugin-rules",
-  "version": "0.8.4-main.ef1bc66f44",
+  "version": "0.8.4-main.effb148878",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "repository": {
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "info@dxos.org",
   "sideEffects": true,
   "type": "module",

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

@@ -47,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;
@@ -55,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);
@@ -74,7 +80,9 @@ export default {
     };
 
     const resolveExportToSegment = (pkgName, exportName) => {
-      if (isValidSubpath(pkgName, exportName)) return 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;
@@ -110,9 +118,13 @@ 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 except for allowed subpaths.
         if (source.startsWith(basePackage + '/')) {
@@ -148,10 +160,15 @@ 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 (resolved entries include segment for fix).
@@ -162,13 +179,19 @@ export default {
 
         typeImports.forEach((spec) => {
           const segment = resolveExportToSegment(packageName, spec.imported);
-          if (segment) resolvedType.push({ ...spec, segment });
-          else unresolvedType.push(spec);
+          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);
+          if (segment) {
+            resolvedRegular.push({ ...spec, segment });
+          } else {
+            unresolvedRegular.push(spec);
+          }
         });
 
         const unresolved = [...unresolvedType, ...unresolvedRegular].map(({ imported }) => imported);
@@ -214,7 +237,9 @@ export default {
               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 (!group.regular.some((r) => r.local === t.local)) {
+                  merged.push(t);
+                }
               }
               if (useNamed && merged.length > 0) {
                 const specParts = merged.map(({ imported, local }) =>
@@ -225,7 +250,9 @@ export default {
                 const seen = new Set();
                 for (const { imported, local } of merged) {
                   const alias = imported !== local ? local : imported;
-                  if (seen.has(alias)) continue;
+                  if (seen.has(alias)) {
+                    continue;
+                  }
                   seen.add(alias);
                   const isTypeOnly =
                     group.type.some((t) => t.imported === imported) &&
@@ -249,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);
               });
 
@@ -265,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/translation-key-format.js

@@ -0,0 +1,443 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+'use strict';
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+/**
+ * Valid type suffixes for translation keys.
+ */
+const VALID_SUFFIXES = [
+  'label',
+  'message',
+  'placeholder',
+  'title',
+  'description',
+  'heading',
+  'alt',
+  'button',
+  'name',
+  'value',
+  'icon',
+  'menu',
+];
+
+/**
+ * Plural suffixes appended by i18next.
+ */
+const PLURAL_SUFFIXES = ['_zero', '_one', '_other'];
+
+/**
+ * Strip i18next plural suffix from a key.
+ */
+const stripPluralSuffix = (key) => {
+  for (const suffix of PLURAL_SUFFIXES) {
+    if (key.endsWith(suffix)) {
+      return key.slice(0, -suffix.length);
+    }
+  }
+  return key;
+};
+
+/**
+ * Get the plural suffix if present.
+ */
+const getPluralSuffix = (key) => {
+  for (const suffix of PLURAL_SUFFIXES) {
+    if (key.endsWith(suffix)) {
+      return suffix;
+    }
+  }
+  return '';
+};
+
+/**
+ * Check if a key has a valid type suffix (after stripping plural suffix).
+ * Only dot-separated suffixes are considered valid (e.g., 'foo.label').
+ */
+const hasValidSuffix = (key) => {
+  const base = stripPluralSuffix(key);
+  return VALID_SUFFIXES.some((suffix) => {
+    return base === suffix || base.endsWith(`.${suffix}`);
+  });
+};
+
+/**
+ * Check if a key has a suffix joined by hyphen instead of dot (e.g., 'plugin-name').
+ * Returns the corrected key if fixable, null otherwise.
+ */
+const fixHyphenatedSuffix = (key) => {
+  const pluralSuffix = getPluralSuffix(key);
+  const base = stripPluralSuffix(key);
+  for (const suffix of VALID_SUFFIXES) {
+    if (base.endsWith(`-${suffix}`) && base.length > suffix.length + 1) {
+      const prefix = base.slice(0, -(suffix.length + 1));
+      return `${prefix}.${suffix}${pluralSuffix}`;
+    }
+  }
+  return null;
+};
+
+/**
+ * Check if a key uses dot.kebab-case format (no spaces).
+ */
+const isDotNotation = (key) => {
+  const base = stripPluralSuffix(key);
+  return !base.includes(' ');
+};
+
+/**
+ * Convert a space-separated key to dot.kebab-case format.
+ */
+const toDotNotation = (key) => {
+  const pluralSuffix = getPluralSuffix(key);
+  const base = stripPluralSuffix(key);
+  const words = base.split(' ');
+
+  if (words.length <= 1) {
+    return key;
+  }
+
+  const lastWord = words[words.length - 1];
+  const isLastWordSuffix = VALID_SUFFIXES.includes(lastWord);
+
+  if (isLastWordSuffix) {
+    const pathWords = words.slice(0, -1);
+    const kebab = pathWords.join('-');
+    return `${kebab}.${lastWord}${pluralSuffix}`;
+  }
+
+  // No valid suffix — kebab-case everything.
+  const kebab = words.join('-');
+  return `${kebab}${pluralSuffix}`;
+};
+
+// --- Key validation: resolve meta.id and load translations ---
+
+/** Cache: pluginDir → { metaId, keys } */
+const pluginCache = new Map();
+
+/**
+ * Walk up from a file path to find the package root (directory containing src/translations.ts).
+ */
+const findPackageDir = (filePath) => {
+  let dir = dirname(filePath);
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(join(dir, 'src/translations.ts'))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return null;
+};
+
+/**
+ * Resolve the namespace identifier for a package.
+ * Plugins use meta.id from src/meta.ts.
+ * UI packages use translationKey from src/translations.ts.
+ */
+const resolveNamespace = (packageDir) => {
+  // Try plugin pattern: src/meta.ts with id field.
+  const metaPath = join(packageDir, 'src/meta.ts');
+  if (existsSync(metaPath)) {
+    const content = readFileSync(metaPath, 'utf-8');
+    const match = content.match(/id:\s*['"]([^'"]+)['"]/);
+    if (match) {
+      return { namespace: match[1], source: 'meta.id' };
+    }
+  }
+
+  // Try UI package pattern: export const translationKey = '...'.
+  const translationsPath = join(packageDir, 'src/translations.ts');
+  if (existsSync(translationsPath)) {
+    const content = readFileSync(translationsPath, 'utf-8');
+    const match = content.match(/export\s+const\s+translationKey\s*=\s*['"]([^'"]+)['"]/);
+    if (match) {
+      return { namespace: match[1], source: 'translationKey' };
+    }
+  }
+
+  return null;
+};
+
+/**
+ * Extract translation keys for the primary namespace from a translations.ts file.
+ * Handles both [meta.id]: { ... } and [translationKey]: { ... } patterns.
+ */
+const readTranslationKeys = (packageDir, nsSource) => {
+  const keys = new Set();
+  const translationsPath = join(packageDir, 'src/translations.ts');
+  if (!existsSync(translationsPath)) {
+    return keys;
+  }
+
+  const content = readFileSync(translationsPath, 'utf-8');
+  const lines = content.split('\n');
+  let inBlock = false;
+  let braceDepth = 0;
+
+  // Match the namespace block header based on the source pattern.
+  const blockPattern = nsSource === 'meta.id' ? /\[meta\.id\]\s*:\s*\{/ : /\[translationKey\]\s*:\s*\{/;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (!inBlock && trimmed.match(blockPattern)) {
+      inBlock = true;
+      braceDepth = 1;
+      continue;
+    }
+
+    if (inBlock) {
+      for (const ch of trimmed) {
+        if (ch === '{') {
+          braceDepth++;
+        }
+        if (ch === '}') {
+          braceDepth--;
+        }
+      }
+
+      const keyMatch = trimmed.match(/^['"]([^'"]+)['"]\s*:/);
+      if (keyMatch && braceDepth >= 1) {
+        keys.add(keyMatch[1]);
+      }
+
+      if (braceDepth <= 0) {
+        inBlock = false;
+      }
+    }
+  }
+
+  return keys;
+};
+
+/**
+ * Get package info (namespace + valid keys) for a file, with caching.
+ */
+const getPackageInfo = (filePath) => {
+  const packageDir = findPackageDir(filePath);
+  if (!packageDir) {
+    return null;
+  }
+
+  if (pluginCache.has(packageDir)) {
+    return pluginCache.get(packageDir);
+  }
+
+  const nsInfo = resolveNamespace(packageDir);
+  if (!nsInfo) {
+    pluginCache.set(packageDir, null);
+    return null;
+  }
+
+  const keys = readTranslationKeys(packageDir, nsInfo.source);
+  const info = { namespace: nsInfo.namespace, nsSource: nsInfo.source, keys };
+  pluginCache.set(packageDir, info);
+  return info;
+};
+
+export default {
+  meta: {
+    type: 'suggestion',
+    fixable: 'code',
+    docs: {
+      description:
+        'Enforce translation key format: dot.kebab-case with required type suffix. Validates keys exist in translations.',
+    },
+    messages: {
+      missingSuffix: 'Invalid translation key: "{{key}}"',
+      useDotsNotSpaces: 'Translation key "{{key}}" should use dot.kebab-case format. Suggested: "{{suggested}}".',
+      undefinedKey: 'Translation key "{{key}}" is not defined in translations for namespace "{{namespace}}".',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          suffixes: {
+            type: 'array',
+            items: { type: 'string' },
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+
+  create(context) {
+    const options = context.options[0] || {};
+    const suffixes = options.suffixes || VALID_SUFFIXES;
+    const filename =
+      context.filename || (context.getFilename && context.getFilename()) || context.physicalFilename || '';
+
+    // Check source text once to determine if this is a translation-aware file.
+    const sourceText = (context.sourceCode || context.getSourceCode()).text;
+    const usesTranslation = sourceText.includes('useTranslation');
+    const usesStaticNamespace =
+      sourceText.includes('useTranslation(meta.id)') || sourceText.includes('useTranslation(translationKey)');
+
+    // Resolve package info for this file (works for both plugins and UI packages).
+    const packageInfo = getPackageInfo(filename);
+
+    /**
+     * Check a string literal node that represents a translation key.
+     * @param {boolean} isDefinition - true for keys in translations.ts definitions.
+     */
+    const checkKeyFormat = (node, key, isDefinition = false) => {
+      // Check 1: Must use dot notation (no spaces).
+      if (!isDotNotation(key)) {
+        const suggested = toDotNotation(key);
+        context.report({
+          node,
+          messageId: 'useDotsNotSpaces',
+          data: { key, suggested },
+          fix: (fixer) => fixer.replaceText(node, `'${suggested}'`),
+        });
+        return;
+      }
+
+      // Check 2: Suffix joined by hyphen instead of dot (e.g., 'plugin-name' → 'plugin.name').
+      const fixedKey = fixHyphenatedSuffix(key);
+      if (fixedKey) {
+        context.report({
+          node,
+          messageId: 'useDotsNotSpaces',
+          data: { key, suggested: fixedKey },
+          fix: (fixer) => fixer.replaceText(node, `'${fixedKey}'`),
+        });
+        return;
+      }
+
+      // Check 3: Must end with a valid suffix (definitions only).
+      if (isDefinition && !hasValidSuffix(key)) {
+        context.report({
+          node,
+          messageId: 'missingSuffix',
+          data: { key, suffixes: suffixes.join(', ') },
+        });
+      }
+    };
+
+    /**
+     * Check that a key exists in the package's translations.
+     */
+    const checkKeyExists = (node, key, hasNsOverride) => {
+      // Only check if we resolved the package and the file uses a static namespace.
+      if (!packageInfo || !usesStaticNamespace || hasNsOverride) {
+        return;
+      }
+
+      // Check exact key, then check plural variants (i18next resolves 'foo.label' with { count } to 'foo.label_one'/'foo.label_other').
+      const hasPluralVariant = PLURAL_SUFFIXES.some((suffix) => packageInfo.keys.has(key + suffix));
+      if (!packageInfo.keys.has(key) && !hasPluralVariant) {
+        context.report({
+          node,
+          messageId: 'undefinedKey',
+          data: { key, namespace: packageInfo.namespace },
+        });
+      }
+    };
+
+    return {
+      // t('some key') or t('some key', { ns: ... }).
+      // Only fires in files that use useTranslation.
+      CallExpression(node) {
+        if (
+          !usesTranslation ||
+          node.callee.type !== 'Identifier' ||
+          node.callee.name !== 't' ||
+          node.arguments.length < 1 ||
+          node.arguments[0].type !== 'Literal' ||
+          typeof node.arguments[0].value !== 'string'
+        ) {
+          return;
+        }
+
+        const key = node.arguments[0].value;
+
+        // Check format.
+        checkKeyFormat(node.arguments[0], key);
+
+        // Check if there's an ns override in the second argument.
+        let hasNsOverride = false;
+        if (node.arguments.length >= 2 && node.arguments[1].type === 'ObjectExpression') {
+          hasNsOverride = node.arguments[1].properties.some(
+            (prop) =>
+              prop.key &&
+              ((prop.key.type === 'Identifier' && prop.key.name === 'ns') ||
+                (prop.key.type === 'Literal' && prop.key.value === 'ns')),
+          );
+        }
+
+        // Check existence.
+        checkKeyExists(node.arguments[0], key, hasNsOverride);
+      },
+
+      // Label tuples: ['key', { ns: meta.id, ... }]
+      // Matches ArrayExpression with a string literal first element and an object with an `ns` property.
+      ArrayExpression(node) {
+        if (
+          node.elements.length >= 2 &&
+          node.elements[0] &&
+          node.elements[0].type === 'Literal' &&
+          typeof node.elements[0].value === 'string' &&
+          node.elements[1] &&
+          node.elements[1].type === 'ObjectExpression' &&
+          node.elements[1].properties.some(
+            (prop) =>
+              prop.key &&
+              ((prop.key.type === 'Identifier' && prop.key.name === 'ns') ||
+                (prop.key.type === 'Literal' && prop.key.value === 'ns')),
+          )
+        ) {
+          const key = node.elements[0].value;
+
+          // Check format.
+          checkKeyFormat(node.elements[0], key);
+
+          // Check existence (determine if ns points to the package's own namespace).
+          const nsProp = node.elements[1].properties.find(
+            (prop) =>
+              prop.key &&
+              ((prop.key.type === 'Identifier' && prop.key.name === 'ns') ||
+                (prop.key.type === 'Literal' && prop.key.value === 'ns')),
+          );
+          const isOwnNamespace =
+            nsProp &&
+            nsProp.value &&
+            ((nsProp.value.type === 'MemberExpression' &&
+              nsProp.value.object.type === 'Identifier' &&
+              nsProp.value.object.name === 'meta' &&
+              nsProp.value.property.type === 'Identifier' &&
+              nsProp.value.property.name === 'id') ||
+              (nsProp.value.type === 'Identifier' && nsProp.value.name === 'translationKey'));
+          checkKeyExists(node.elements[0], key, !isOwnNamespace);
+        }
+      },
+
+      // Property keys in translations.ts files.
+      // Guard: only check files whose source contains the translations export pattern.
+      Property(node) {
+        if (!sourceText.includes('satisfies Resource[]')) {
+          return;
+        }
+
+        if (
+          node.key.type === 'Literal' &&
+          typeof node.key.value === 'string' &&
+          node.value.type === 'Literal' &&
+          typeof node.value.value === 'string'
+        ) {
+          checkKeyFormat(node.key, node.key.value, true);
+        }
+      },
+    };
+  },
+};