@nxds/eslint-plugin 0.5.0 → 0.7.0

package/README.md

@@ -32,6 +32,22 @@ Enforces `.claude/rules/extract-inline-handlers.md`: inline JSX handler props (`
 
 Enforces `.claude/rules/code-comments.md`: JSDoc blocks must not carry `@default` or `@example` tags. The docs read prop defaults from code and usage from `docs` stories, so a tag is a second copy that can drift. Line comments and plain block comments are not checked. Wired in the root `eslint.config.js` for `packages/react/src` and `packages/vue/src`.
 
+### `@nxds/no-react-19-only`
+
+Reports React 19-only APIs in `packages/react`, the source `packages/react-18` is generated from. The generator adds `forwardRef` and changes nothing else, so a React 19-only call would compile there and then break on React 18. It reports:
+
+| Pattern                                                                                                   | Use instead                                             |
+| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `use`, `useActionState`, `useOptimistic`, `useEffectEvent`, `Activity`, `captureOwnerStack` from `react`  | An API React 18.3 has                                   |
+| `useFormStatus`, `requestFormReset`, `preload*`, `preinit*`, `preconnect`, `prefetchDNS` from `react-dom` | An API React 18.3 has                                   |
+| `<SomeContext value={…}>`                                                                                 | `<SomeContext.Provider value={…}>`                      |
+| A ref callback that returns a cleanup                                                                     | The node in state, with setup and teardown in an effect |
+| `useDeferredValue(value, initialValue)`                                                                   | One argument                                            |
+| A function passed to `action` or `formAction`                                                             | `onSubmit` or `onClick`                                 |
+| `<title>` outside an `<svg>`, `<meta>`, `<link>`, `<style precedence>`                                    | Metadata the app's framework renders                    |
+
+Wired in the root `eslint.config.js` for `packages/react/src` only. It is not in `nxdsComponentConfig`, because a React 19 app may use these APIs.
+
 ## Source of truth
 
 The token-layer rules are self-contained: the canonical step set is `src/canonical-step-set.json`. The component rules map 1:1 to the `.claude/rules/*.md` cited above — the rule code plus those docs are the spec. Every rule has RuleTester coverage in `__tests__/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxds/eslint-plugin",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "ESLint rules that enforce nxds conventions in copied components.",
   "keywords": [

package/src/index.js

@@ -3,6 +3,7 @@ import { createRequire } from 'node:module';
 import canonicalSpacingSteps from './rules/canonical-spacing-steps.js';
 import noJsdocDataTags from './rules/no-jsdoc-data-tags.js';
 import noMultiStatementJsxHandler from './rules/no-multi-statement-jsx-handler.js';
+import noReact19Only from './rules/no-react-19-only.js';
 import noRenderPropTypes from './rules/no-render-prop-types.js';
 import nxClassConventions from './rules/nx-class-conventions.js';
 
@@ -18,6 +19,7 @@ const plugin = {
     'no-render-prop-types': noRenderPropTypes,
     'no-multi-statement-jsx-handler': noMultiStatementJsxHandler,
     'no-jsdoc-data-tags': noJsdocDataTags,
+    'no-react-19-only': noReact19Only,
   },
 };
 

package/src/rules/no-react-19-only.js

@@ -0,0 +1,280 @@
+// `packages/react-18` is generated from `packages/react` by wrapping each
+// component in `forwardRef`, and nothing else changes. So `packages/react`
+// must not use anything React 18 lacks: the generated copy would compile and
+// then break at runtime. This rule reports the React 19-only APIs and
+// behaviours an nxds component could reach for.
+
+const REACT_ONLY_19 = new Set([
+  'use',
+  'useActionState',
+  'useOptimistic',
+  'useEffectEvent',
+  'Activity',
+  'captureOwnerStack',
+  'cache',
+  'cacheSignal',
+]);
+
+const REACT_DOM_ONLY_19 = new Set([
+  'useFormStatus',
+  'requestFormReset',
+  'preload',
+  'preloadModule',
+  'preinit',
+  'preinitModule',
+  'preconnect',
+  'prefetchDNS',
+]);
+
+const ONLY_19_BY_SOURCE = {
+  react: REACT_ONLY_19,
+  'react-dom': REACT_DOM_ONLY_19,
+};
+
+const FUNCTION_TYPES = new Set([
+  'ArrowFunctionExpression',
+  'FunctionExpression',
+  'FunctionDeclaration',
+]);
+
+function isFunction(node) {
+  return node != null && FUNCTION_TYPES.has(node.type);
+}
+
+/** Whether `fn` returns a function from its own body, not a nested one. */
+function returnsFunction(fn) {
+  if (
+    fn.type === 'ArrowFunctionExpression' &&
+    fn.body.type !== 'BlockStatement'
+  ) {
+    return isFunction(fn.body);
+  }
+  let found = false;
+  const visit = (node) => {
+    if (found || node == null || typeof node.type !== 'string') return;
+    if (node.type === 'ReturnStatement') {
+      if (isFunction(node.argument)) found = true;
+      return;
+    }
+    if (isFunction(node)) return;
+    for (const [key, value] of Object.entries(node)) {
+      if (key === 'parent') continue;
+      if (Array.isArray(value)) value.forEach(visit);
+      else if (value && typeof value === 'object') visit(value);
+    }
+  };
+  visit(fn.body);
+  return found;
+}
+
+/** The name a call's callee ends in: `useCallback` for `React.useCallback`. */
+function calleeName(call) {
+  const { callee } = call;
+  if (callee.type === 'Identifier') return callee.name;
+  if (
+    callee.type === 'MemberExpression' &&
+    callee.property.type === 'Identifier'
+  ) {
+    return callee.property.name;
+  }
+  return null;
+}
+
+/** The function an identifier names, when it is declared in reach. */
+function functionNamed(context, identifier) {
+  const scope = context.sourceCode.getScope(identifier);
+  let variable = null;
+  for (let current = scope; current && !variable; current = current.upper) {
+    variable = current.set.get(identifier.name) ?? null;
+  }
+  const definition = variable?.defs[0];
+  if (!definition) return null;
+  if (definition.node.type === 'FunctionDeclaration') return definition.node;
+  if (definition.node.type !== 'VariableDeclarator') return null;
+  const init = definition.node.init;
+  if (isFunction(init)) return init;
+  if (init?.type === 'CallExpression' && calleeName(init) === 'useCallback') {
+    return isFunction(init.arguments[0]) ? init.arguments[0] : null;
+  }
+  return null;
+}
+
+function expressionFunction(context, expression) {
+  if (isFunction(expression)) return expression;
+  if (expression.type === 'Identifier')
+    return functionNamed(context, expression);
+  return null;
+}
+
+function attributeExpression(attribute) {
+  const { value } = attribute;
+  return value?.type === 'JSXExpressionContainer' ? value.expression : null;
+}
+
+function hasAncestorElement(node, name) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (
+      current.type === 'JSXElement' &&
+      current.openingElement.name.type === 'JSXIdentifier' &&
+      current.openingElement.name.name === name
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow React 19-only APIs in source that packages/react-18 is generated from.',
+    },
+    schema: [],
+    messages: {
+      api: '`{{name}}` is React 19 only, so the generated packages/react-18 breaks. Use an API React 18.3 has.',
+      contextProvider:
+        'Rendering a context as a provider is React 19 only. Render `<{{name}}.Provider value={…}>`.',
+      refCleanup:
+        'A ref callback that returns a cleanup is React 18-incompatible: React 18 ignores the cleanup and calls the ref with `null`. Keep the node in state and set up and tear down in an effect.',
+      deferredInitialValue:
+        "`useDeferredValue`'s initial value is React 19 only. Pass one argument.",
+      formAction:
+        'A function `{{name}}` is React 19 only. Handle the form in `onSubmit` or the button in `onClick`.',
+      documentMetadata:
+        '`<{{name}}>` is hoisted into the document head by React 19 only. React 18 renders it in place.',
+    },
+  },
+  create(context) {
+    // Local names bound to the `react` / `react-dom` namespace or default import.
+    const namespaces = new Map();
+    const contexts = new Set();
+
+    function reportMember(node, source, name) {
+      if (ONLY_19_BY_SOURCE[source]?.has(name)) {
+        context.report({ node, messageId: 'api', data: { name } });
+      }
+    }
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (!(source in ONLY_19_BY_SOURCE)) return;
+        for (const specifier of node.specifiers) {
+          if (specifier.type === 'ImportSpecifier') {
+            const imported =
+              specifier.imported.name ?? specifier.imported.value;
+            reportMember(specifier, source, imported);
+          } else {
+            namespaces.set(specifier.local.name, source);
+          }
+        }
+      },
+
+      MemberExpression(node) {
+        if (
+          node.object.type !== 'Identifier' ||
+          node.property.type !== 'Identifier'
+        ) {
+          return;
+        }
+        const source = namespaces.get(node.object.name);
+        if (source) reportMember(node.property, source, node.property.name);
+      },
+
+      JSXMemberExpression(node) {
+        if (node.object.type !== 'JSXIdentifier') return;
+        const source = namespaces.get(node.object.name);
+        if (source) reportMember(node.property, source, node.property.name);
+      },
+
+      VariableDeclarator(node) {
+        if (
+          node.id.type === 'Identifier' &&
+          node.init?.type === 'CallExpression' &&
+          calleeName(node.init) === 'createContext'
+        ) {
+          contexts.add(node.id.name);
+        }
+      },
+
+      CallExpression(node) {
+        if (
+          calleeName(node) === 'useDeferredValue' &&
+          node.arguments.length > 1
+        ) {
+          context.report({ node, messageId: 'deferredInitialValue' });
+        }
+      },
+
+      JSXOpeningElement(node) {
+        if (node.name.type !== 'JSXIdentifier') return;
+        const { name } = node.name;
+        const attributes = node.attributes.filter(
+          (attribute) => attribute.type === 'JSXAttribute'
+        );
+
+        const isContext = contexts.has(name) || /^[A-Z]\w*Context$/.test(name);
+        if (
+          isContext &&
+          attributes.some((attribute) => attribute.name.name === 'value')
+        ) {
+          context.report({
+            node,
+            messageId: 'contextProvider',
+            data: { name },
+          });
+        }
+
+        if (name === 'meta' || name === 'link') {
+          context.report({
+            node,
+            messageId: 'documentMetadata',
+            data: { name },
+          });
+        }
+        if (name === 'title' && !hasAncestorElement(node.parent, 'svg')) {
+          context.report({
+            node,
+            messageId: 'documentMetadata',
+            data: { name },
+          });
+        }
+        if (
+          name === 'style' &&
+          attributes.some((attribute) => attribute.name.name === 'precedence')
+        ) {
+          context.report({
+            node,
+            messageId: 'documentMetadata',
+            data: { name },
+          });
+        }
+
+        for (const attribute of attributes) {
+          const attributeName = attribute.name.name;
+          const expression = attributeExpression(attribute);
+          if (!expression) continue;
+
+          if (attributeName === 'ref') {
+            const fn = expressionFunction(context, expression);
+            if (fn && returnsFunction(fn)) {
+              context.report({ node: attribute, messageId: 'refCleanup' });
+            }
+          }
+          if (
+            (attributeName === 'action' || attributeName === 'formAction') &&
+            expressionFunction(context, expression)
+          ) {
+            context.report({
+              node: attribute,
+              messageId: 'formAction',
+              data: { name: attributeName },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/src/rules/no-render-prop-types.js

@@ -2,7 +2,9 @@
 // should not be typed as render callbacks (`(...) => ReactNode`), component
 // references (`ComponentType<...>`, `FC<...>`), or unions thereof. Event
 // handler props (`onClick`, `onSubmit`, ...) return data, not JSX, and are
-// exempt.
+// exempt. So is a prop whose JSDoc carries `@thirdPartyShape <reason>`: a
+// third-party API mandates its shape. It is a plain tag, not an
+// `eslint-disable`, so copied source lints clean in apps without this plugin.
 //
 // Known scope gaps — these patterns sneak through the AST visitors below and
 // must be caught by code review:
@@ -14,6 +16,8 @@
 //   only).
 
 const EVENT_HANDLER = /^on[A-Z]/;
+// The tag counts only with a reason after it.
+const THIRD_PARTY_TAG = /@thirdPartyShape[ \t]+[^\s*]/;
 
 const REACT_NODE_NAMES = new Set([
   'ReactNode',
@@ -113,6 +117,10 @@ export default {
       if (EVENT_HANDLER.test(name)) {
         return;
       }
+      const comments = context.sourceCode.getCommentsBefore(node);
+      if (comments.some((comment) => THIRD_PARTY_TAG.test(comment.value))) {
+        return;
+      }
       const ann = node.typeAnnotation?.typeAnnotation;
       if (!ann) {
         return;

package/src/rules/nx-class-conventions.js

@@ -129,14 +129,14 @@ function isDocsSpecimenPage(filename) {
 const RAW_TYPOGRAPHY_EXCEPTIONS = [
   {
     filename:
-      /(?:^|[/\\])packages[/\\]react[/\\]src[/\\]components[/\\]avatar[/\\]avatar\.tsx$/,
+      /(?:^|[/\\])packages[/\\]react(?:-18)?[/\\]src[/\\]components[/\\]avatar[/\\]avatar\.tsx$/,
     className:
       'nx:flex nx:size-full nx:items-center nx:justify-center nx:rounded-[inherit] nx:bg-muted nx:text-foreground nx:font-medium nx:leading-none',
     messageIds: new Set(['rawFontWeight', 'rawLineHeight']),
   },
   {
     filename:
-      /(?:^|[/\\])packages[/\\]react[/\\]src[/\\]components[/\\]chart[/\\]chart\.tsx$/,
+      /(?:^|[/\\])packages[/\\]react(?:-18)?[/\\]src[/\\]components[/\\]chart[/\\]chart\.tsx$/,
     className: 'nx:text-foreground nx:font-mono nx:font-medium nx:tabular-nums',
     messageIds: new Set(['rawFontWeight']),
   },