@nkzw/eslint-plugin-fbtee 5.0.0 → 6.0.0

package/README.md

@@ -392,6 +392,10 @@ export default [
 
 Use `fbtee.configs.strict.rules` to also check for untranslated text.
 
+## Migration to fbtee 6
+
+`fbt()` now returns strings for text-only messages and real React Fragments for rich messages. Its return type is `string | ReactElement`; use `fbs()` for string-only props, attributes, and storage. The `FbtResult` runtime class and its custom serialization methods are removed. See the [React result migration guide](docs/react-results.md) for compatibility details, tests, and production benchmarks.
+
 ## Migration from fbtee 4
 
 fbtee 5 combines `@nkzw/fbtee-cli` and `@nkzw/oxc-transform-fbtee` into `@nkzw/fbtee-compiler`:

package/docs/rules/prefer-fbs.md

@@ -0,0 +1,36 @@
+# Prefer the string API over coercing React translations (@nkzw/fbtee/prefer-fbs)
+
+Use `fbs()` when translated text is required. `fbt()` may return a React element, which `String()` silently converts to `[object Object]`. This rule is enabled in the recommended and strict configurations and does not require type information.
+
+## Rule details
+
+Examples of incorrect code:
+
+```tsx
+String(fbt('Hello', 'Greeting'));
+String(fbt.c('Save'));
+String(<fbt desc="Greeting">Hello</fbt>);
+```
+
+Use the string API directly:
+
+```tsx
+fbs('Hello', 'Greeting');
+fbs.c('Save');
+fbs(['Hello ', fbs.param('name', name)], 'Greeting');
+```
+
+The rule recognizes the conventional `fbt` binding, aliases imported from `fbtee` or `fbtee/server`, and common-string calls. Parentheses and TypeScript assertions do not hide a direct call. A locally shadowed `String` function is ignored.
+
+There is no automatic fix: migrating a call can require adding an `fbs` import, updating nested helpers, and reviewing parameter values. `fbs.param()` accepts strings; do not blindly rename helpers that receive numbers or React nodes.
+
+## Scope
+
+This is a direct-expression check. It deliberately does not trace variables, returned values, or translator aliases created through assignments:
+
+```tsx
+const message = fbt('Hello', 'Greeting');
+String(message);
+```
+
+It also does not analyze template interpolation, `.toString()`, or JSON serialization. Review those separately during migration. This rule does not change runtime behavior or add runtime overhead.

package/lib/index.d.mts

@@ -1,10 +1,10 @@
-//#region src/index.d.ts
 declare const _default: {
   configs: {
     recommended: {
       rules: {
         '@nkzw/fbtee/no-empty-strings': number;
         '@nkzw/fbtee/no-unhelpful-desc': number;
+        '@nkzw/fbtee/prefer-fbs': number;
       };
     };
     strict: {
@@ -12,6 +12,7 @@ declare const _default: {
         '@nkzw/fbtee/no-empty-strings': number;
         '@nkzw/fbtee/no-unhelpful-desc': number;
         '@nkzw/fbtee/no-untranslated-strings': number;
+        '@nkzw/fbtee/prefer-fbs': number;
       };
     };
   };
@@ -31,7 +32,9 @@ declare const _default: {
     }], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
       name: string;
     };
+    'prefer-fbs': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferFbs", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+      name: string;
+    };
   };
 };
-//#endregion
 export { _default as default };

package/lib/index.mjs

@@ -1,9 +1,8 @@
-import { ESLintUtils } from "@typescript-eslint/utils";
-//#region package.json
+import { ASTUtils, ESLintUtils } from "@typescript-eslint/utils";
+// package.json
 var name = "@nkzw/eslint-plugin-fbtee";
-var version = "5.0.0";
-//#endregion
-//#region src/utils.tsx
+var version = "6.0.0";
+// src/utils.tsx
 const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/nkzw-tech/fbtee/blob/main/packages/eslint-plugin-fbtee/docs/rules/${name}.md`);
 function resolveMemberExpressions(object, property) {
 	if (object.type === "JSXMemberExpression") return `${resolveMemberExpressions(object.object, object.property)}.${property.name}`;
@@ -81,8 +80,7 @@ function isFbtNode(node) {
 	}
 	return false;
 }
-//#endregion
-//#region src/rules/no-empty-strings.tsx
+// src/rules/no-empty-strings.tsx
 var no_empty_strings_default = createRule({
 	create(context) {
 		return {
@@ -143,8 +141,7 @@ function validateChildren(node) {
 function isEmptyString(node) {
 	return resolveNodeValue(node)?.trim() === "";
 }
-//#endregion
-//#region src/rules/no-unhelpful-desc.tsx
+// src/rules/no-unhelpful-desc.tsx
 var no_unhelpful_desc_default = createRule({
 	create(context) {
 		return {
@@ -213,8 +210,7 @@ var no_unhelpful_desc_default = createRule({
 	},
 	name: "no-unhelpful-desc"
 });
-//#endregion
-//#region src/rules/no-untranslated-strings.tsx
+// src/rules/no-untranslated-strings.tsx
 const attributes = /* @__PURE__ */ new Set([
 	"title",
 	"placeholder",
@@ -292,18 +288,61 @@ var no_untranslated_strings_default = createRule({
 	},
 	name: "no-untranslated-strings"
 });
-//#endregion
-//#region src/index.tsx
+// src/rules/prefer-fbs.tsx
+function unwrap(node) {
+	while (node.type === "TSAsExpression" || node.type === "TSTypeAssertion" || node.type === "TSNonNullExpression" || node.type === "TSSatisfiesExpression" || node.type === "ChainExpression") node = node.expression;
+	return node;
+}
+var prefer_fbs_default = createRule({
+	create(context) {
+		function isFbt(node) {
+			if (node.type !== "Identifier") return false;
+			const variable = ASTUtils.findVariable(context.sourceCode.getScope(node), node.name);
+			const imported = variable?.defs.find((definition) => definition.type === "ImportBinding");
+			if (imported) return imported.parent.type === "ImportDeclaration" && (imported.parent.source.value === "fbtee" || imported.parent.source.value === "fbtee/server") && (imported.node.type === "ImportDefaultSpecifier" || imported.node.type === "ImportSpecifier" && (imported.node.imported.type === "Identifier" ? imported.node.imported.name : imported.node.imported.value) === "fbt");
+			return node.name === "fbt" && !variable?.defs.some((definition) => definition.type === "FunctionName");
+		}
+		return { CallExpression(node) {
+			if (node.callee.type !== "Identifier" || node.callee.name !== "String") return;
+			if (ASTUtils.findVariable(context.sourceCode.getScope(node), "String")?.defs.length || !node.arguments[0]) return;
+			const argument = unwrap(node.arguments[0]);
+			if (argument.type === "JSXElement" && argument.openingElement.name.type === "JSXIdentifier" && argument.openingElement.name.name === "fbt") {
+				context.report({
+					messageId: "preferFbs",
+					node
+				});
+				return;
+			}
+			if (argument.type !== "CallExpression") return;
+			const callee = unwrap(argument.callee);
+			if (isFbt(callee) || callee.type === "MemberExpression" && isFbt(unwrap(callee.object)) && (!callee.computed && callee.property.type === "Identifier" && callee.property.name === "c" || callee.computed && callee.property.type === "Literal" && callee.property.value === "c")) context.report({
+				messageId: "preferFbs",
+				node
+			});
+		} };
+	},
+	defaultOptions: [],
+	meta: {
+		docs: { description: "Require fbs() instead of String(fbt(...)) for translated text." },
+		messages: { preferFbs: "Use fbs() or fbs.c() instead of String() on an fbt result. Rich fbt results stringify to \"[object Object]\"." },
+		schema: [],
+		type: "problem"
+	},
+	name: "prefer-fbs"
+});
+// src/index.tsx
 var src_default = {
 	configs: {
 		recommended: { rules: {
 			"@nkzw/fbtee/no-empty-strings": 2,
-			"@nkzw/fbtee/no-unhelpful-desc": 2
+			"@nkzw/fbtee/no-unhelpful-desc": 2,
+			"@nkzw/fbtee/prefer-fbs": 2
 		} },
 		strict: { rules: {
 			"@nkzw/fbtee/no-empty-strings": 2,
 			"@nkzw/fbtee/no-unhelpful-desc": 2,
-			"@nkzw/fbtee/no-untranslated-strings": 2
+			"@nkzw/fbtee/no-untranslated-strings": 2,
+			"@nkzw/fbtee/prefer-fbs": 2
 		} }
 	},
 	meta: {
@@ -313,8 +352,8 @@ var src_default = {
 	rules: {
 		"no-empty-strings": no_empty_strings_default,
 		"no-unhelpful-desc": no_unhelpful_desc_default,
-		"no-untranslated-strings": no_untranslated_strings_default
+		"no-untranslated-strings": no_untranslated_strings_default,
+		"prefer-fbs": prefer_fbs_default
 	}
 };
-//#endregion
 export { src_default as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/eslint-plugin-fbtee",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "",
   "keywords": [],
   "license": "MIT",
@@ -15,10 +15,10 @@
     "import": "./lib/index.mjs"
   },
   "dependencies": {
-    "@typescript-eslint/utils": "^8.64.0"
+    "@typescript-eslint/utils": "^8.72.2"
   },
   "devDependencies": {
-    "@typescript-eslint/rule-tester": "^8.64.0"
+    "@typescript-eslint/rule-tester": "^8.72.2"
   },
   "scripts": {
     "build": "tsdown src/index.tsx -d lib --target=node22 --format=esm --clean --dts"

package/src/__tests__/prefer-fbs-test.tsx

@@ -0,0 +1,58 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import plugin from '../index.tsx';
+import rule from '../rules/prefer-fbs.tsx';
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parserOptions: {
+      ecmaFeatures: { jsx: true },
+    },
+  },
+});
+
+ruleTester.run('prefer-fbs', rule, {
+  invalid: [
+    "String(fbt('Hello', 'Greeting'));",
+    "String(fbt.c('Save'));",
+    "String(fbt['c']('Save'));",
+    "String((fbt('Hello', 'Greeting')));",
+    "String(fbt('Hello', 'Greeting') as unknown);",
+    "String(fbt('Hello', 'Greeting')!);",
+    "String(fbt('Hello', 'Greeting') satisfies unknown);",
+    "String(fbt?.('Hello', 'Greeting'));",
+    "String(fbt(['Hello ', fbt.param('name', <b>Alice</b>)], 'Greeting'));",
+    'String(<fbt desc="Greeting">Hello</fbt>);',
+    "import { fbt } from 'fbtee'; String(fbt('Hello', 'Greeting'));",
+    "import { fbt as translate } from 'fbtee'; String(translate('Hello', 'Greeting'));",
+    "import { fbt as translate } from 'fbtee/server'; String(translate.c('Save'));",
+    "import translate from 'fbtee'; String(translate('Hello', 'Greeting'));",
+    "const { fbt } = useFbt(); String(fbt('Hello', 'Greeting'));",
+    "function message(fbt) { return String(fbt('Hello', 'Greeting')); }",
+  ].map((code) => ({ code, errors: [{ messageId: 'preferFbs' as const }], output: null })),
+  valid: [
+    "fbs('Hello', 'Greeting');",
+    "fbs.c('Save');",
+    "String(fbs('Hello', 'Greeting'));",
+    "String(fbs.c('Save'));",
+    'String(<fbs desc="Greeting">Hello</fbs>);',
+    "String(fbt.param('name', 'Alice'));",
+    "String(fbt._('Hello'));",
+    "String(other('Hello'));",
+    "import { fbs as fbt } from 'fbtee'; String(fbt('Hello', 'Greeting'));",
+    "import { fbt } from 'other'; String(fbt('Hello', 'Greeting'));",
+    "import fbt = require('other'); String(fbt('Hello'));",
+    "function fbt(text) { return text; } String(fbt('Hello'));",
+    "function example(String) { return String(fbt('Hello', 'Greeting')); }",
+    "const String = value => value; String(fbt('Hello', 'Greeting'));",
+    "import { fbt as translate } from 'fbtee'; function example(translate) { return String(translate('Hello')); }",
+    "const result = fbt('Hello', 'Greeting'); String(result);",
+    "const translate = fbt; String(translate('Hello', 'Greeting'));",
+    'String();',
+  ],
+});
+
+test('prefer-fbs is enabled in the recommended and strict configs', () => {
+  expect(plugin.rules['prefer-fbs']).toBe(rule);
+  expect(plugin.configs.recommended.rules['@nkzw/fbtee/prefer-fbs']).toBe(2);
+  expect(plugin.configs.strict.rules['@nkzw/fbtee/prefer-fbs']).toBe(2);
+});

package/src/index.tsx

@@ -2,6 +2,7 @@ import packageJson from '../package.json' with { type: 'json' };
 import noEmptyStringsRule from './rules/no-empty-strings.tsx';
 import noUnhelpfulDesc from './rules/no-unhelpful-desc.tsx';
 import noUntranslatedStrings from './rules/no-untranslated-strings.tsx';
+import preferFbs from './rules/prefer-fbs.tsx';
 
 export default {
   configs: {
@@ -9,6 +10,7 @@ export default {
       rules: {
         '@nkzw/fbtee/no-empty-strings': 2,
         '@nkzw/fbtee/no-unhelpful-desc': 2,
+        '@nkzw/fbtee/prefer-fbs': 2,
       },
     },
     strict: {
@@ -16,6 +18,7 @@ export default {
         '@nkzw/fbtee/no-empty-strings': 2,
         '@nkzw/fbtee/no-unhelpful-desc': 2,
         '@nkzw/fbtee/no-untranslated-strings': 2,
+        '@nkzw/fbtee/prefer-fbs': 2,
       },
     },
   },
@@ -27,5 +30,6 @@ export default {
     'no-empty-strings': noEmptyStringsRule,
     'no-unhelpful-desc': noUnhelpfulDesc,
     'no-untranslated-strings': noUntranslatedStrings,
+    'prefer-fbs': preferFbs,
   },
 };

package/src/rules/prefer-fbs.tsx

@@ -0,0 +1,94 @@
+import { ASTUtils, TSESTree } from '@typescript-eslint/utils';
+import { createRule } from '../utils.tsx';
+
+function unwrap(node: TSESTree.Node): TSESTree.Node {
+  while (
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSTypeAssertion' ||
+    node.type === 'TSNonNullExpression' ||
+    node.type === 'TSSatisfiesExpression' ||
+    node.type === 'ChainExpression'
+  ) {
+    node = node.expression;
+  }
+  return node;
+}
+
+export default createRule<[], 'preferFbs'>({
+  create(context) {
+    function isFbt(node: TSESTree.Node): boolean {
+      if (node.type !== 'Identifier') {
+        return false;
+      }
+      const variable = ASTUtils.findVariable(context.sourceCode.getScope(node), node.name);
+      const imported = variable?.defs.find((definition) => definition.type === 'ImportBinding');
+      if (imported) {
+        return (
+          imported.parent.type === 'ImportDeclaration' &&
+          (imported.parent.source.value === 'fbtee' ||
+            imported.parent.source.value === 'fbtee/server') &&
+          (imported.node.type === 'ImportDefaultSpecifier' ||
+            (imported.node.type === 'ImportSpecifier' &&
+              (imported.node.imported.type === 'Identifier'
+                ? imported.node.imported.name
+                : imported.node.imported.value) === 'fbt'))
+        );
+      }
+      return (
+        node.name === 'fbt' &&
+        !variable?.defs.some((definition) => definition.type === 'FunctionName')
+      );
+    }
+
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== 'Identifier' || node.callee.name !== 'String') {
+          return;
+        }
+        const string = ASTUtils.findVariable(context.sourceCode.getScope(node), 'String');
+        if (string?.defs.length || !node.arguments[0]) {
+          return;
+        }
+        const argument = unwrap(node.arguments[0]);
+        if (
+          argument.type === 'JSXElement' &&
+          argument.openingElement.name.type === 'JSXIdentifier' &&
+          argument.openingElement.name.name === 'fbt'
+        ) {
+          context.report({ messageId: 'preferFbs', node });
+          return;
+        }
+        if (argument.type !== 'CallExpression') {
+          return;
+        }
+        const callee = unwrap(argument.callee);
+        if (
+          isFbt(callee) ||
+          (callee.type === 'MemberExpression' &&
+            isFbt(unwrap(callee.object)) &&
+            ((!callee.computed &&
+              callee.property.type === 'Identifier' &&
+              callee.property.name === 'c') ||
+              (callee.computed &&
+                callee.property.type === 'Literal' &&
+                callee.property.value === 'c')))
+        ) {
+          context.report({ messageId: 'preferFbs', node });
+        }
+      },
+    };
+  },
+  defaultOptions: [],
+  meta: {
+    docs: {
+      description: 'Require fbs() instead of String(fbt(...)) for translated text.',
+    },
+    messages: {
+      preferFbs:
+        'Use fbs() or fbs.c() instead of String() on an fbt result. Rich fbt results stringify to "[object Object]".',
+    },
+    schema: [],
+    type: 'problem',
+  },
+  name: 'prefer-fbs',
+});