@dxos/eslint-plugin-rules 0.8.4-main.c85a9c8dae → 0.8.4-main.dd46787728

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/index.js

@@ -2,13 +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'));
 
@@ -20,11 +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: {
@@ -34,6 +41,7 @@ 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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/eslint-plugin-rules",
-  "version": "0.8.4-main.c85a9c8dae",
+  "version": "0.8.4-main.dd46787728",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "repository": {

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