@cratis/eslint-plugin-components 3.4.0 → 3.5.1

package/README.md

@@ -9,6 +9,7 @@ Cratis base config, [`@cratis/eslint-config`](https://www.npmjs.com/package/@cra
 | `no-primereact-dialog` | Disallows importing `Dialog` from `primereact/dialog`. Use `CommandDialog` from `@cratis/components/CommandDialog`, or `Dialog` from `@cratis/components/Dialogs` — the wrappers add Arc command binding, overlay/focus fixes, and theming. |
 | `onbeforeexecute-must-return` | Requires an `onBeforeExecute` callback to return the command values. `onBeforeExecute` is a transformer — a body that can complete without returning executes the command with `undefined` (silent data loss). |
 | `no-hooks-in-view-model` | Disallows React hooks (including generated Arc proxies' `.use()`) inside a view model class. View models must be plain, hook-free classes that receive injected abstractions. |
+| `no-raw-command-form-marker` | Disallows identifying a CommandForm field or column by a hand-written `displayName` string, in either direction. Use `markAsCommandFormField`/`markAsCommandFormColumn` and `isCommandFormField`/`isCommandFormColumn` from `@cratis/components/CommandForm` — they go through a marker a build transform cannot rewrite. |
 
 The two import rules cover `import` and re-`export … from` forms.
 
@@ -44,7 +45,7 @@ export default [
 }],
 ```
 
-`onbeforeexecute-must-return` and `no-hooks-in-view-model` take no options.
+`onbeforeexecute-must-return`, `no-hooks-in-view-model` and `no-raw-command-form-marker` take no options.
 
 ## Rules
 
@@ -96,3 +97,38 @@ A class is treated as a view model when it is registered via `withViewModel(...)
 with `@injectable`, or named `*ViewModel`. Both bare hooks (`useState`, `useIdentity`, …) and
 proxy member hooks (`.use()`, `.useSuspense()`, `.useChangeStream()`) are flagged. Hooks
 inside a nested non–view-model class are not.
+
+### `no-raw-command-form-marker`
+
+`CommandForm`, `CommandDialog` and `CommandStepper` decide which children are fields by
+inspecting the child's component type. Historically that test was a single string
+comparison against `displayName` — and `displayName` is React's public, writable
+*diagnostic* name, a routine target for build tooling. Storybook's
+`reactDocgen: 'react-docgen-typescript'` setting rewrites it by default.
+
+When it is rewritten, the child stops being recognized as a field: it renders with no
+container, so no label, no bound value and no change handler. There is no error and no
+warning, and every gate stays green.
+
+The helpers go through an `isCommandFormField` / `isCommandFormColumn` marker that a rename
+does not touch, while still setting and honoring the legacy `displayName` — so they are strictly
+more permissive than the literal, never less. `@cratis/arc.react` marks and reads the same two
+properties, and that shared shape is what carries the contract across the two packages.
+
+```ts
+// ❌ a build transform that rewrites displayName silently unbinds this field
+MyField.displayName = 'CommandFormField';
+if (component.displayName === 'CommandFormField') { wrap(component); }
+
+// ✅ marker first, legacy displayName still set and still honoured
+import { markAsCommandFormField, isCommandFormField } from '@cratis/components/CommandForm';
+
+markAsCommandFormField(MyField);
+if (isCommandFormField(component)) { wrap(component); }
+```
+
+Flagged in both directions: assignment (`C.displayName = '…'`, including computed and
+object-literal forms) and comparison (`===`, `!==`, either operand order). Referring to the
+exported `CommandFormFieldDisplayName` / `CommandFormColumnDisplayName` constants is not
+flagged, so the declarations themselves and any deliberate legacy-path code stay clean.
+Prefer `asCommandFormField` from `@cratis/arc.react` where it applies — it marks for you.

package/index.js

@@ -3,6 +3,7 @@ import { noPrimereactDialog } from './lib/noPrimereactDialog.js';
 import { noRootBarrelImport } from './lib/noRootBarrelImport.js';
 import { onbeforeexecuteMustReturn } from './lib/onbeforeexecuteMustReturn.js';
 import { noHooksInViewModel } from './lib/noHooksInViewModel.js';
+import { noRawCommandFormMarker } from './lib/noRawCommandFormMarker.js';
 
 const { version } = createRequire(import.meta.url)('./package.json');
 
@@ -17,6 +18,7 @@ const plugin = {
         'no-root-barrel-import': noRootBarrelImport,
         'onbeforeexecute-must-return': onbeforeexecuteMustReturn,
         'no-hooks-in-view-model': noHooksInViewModel,
+        'no-raw-command-form-marker': noRawCommandFormMarker,
     },
     configs: {},
 };
@@ -37,6 +39,7 @@ Object.assign(plugin.configs, {
                 '@cratis/components/no-root-barrel-import': 'error',
                 '@cratis/components/onbeforeexecute-must-return': 'error',
                 '@cratis/components/no-hooks-in-view-model': 'error',
+                '@cratis/components/no-raw-command-form-marker': 'error',
             },
         },
     ],
@@ -44,4 +47,4 @@ Object.assign(plugin.configs, {
 
 export default plugin;
 export const { configs, rules, meta } = plugin;
-export { noPrimereactDialog, noRootBarrelImport, onbeforeexecuteMustReturn, noHooksInViewModel };
+export { noPrimereactDialog, noRootBarrelImport, onbeforeexecuteMustReturn, noHooksInViewModel, noRawCommandFormMarker };

package/lib/noRawCommandFormMarker.js

@@ -0,0 +1,89 @@
+// The identifiers a CommandForm child is recognized by, and the helpers that own each one.
+const MARKERS = {
+    CommandFormField: { mark: 'markAsCommandFormField', predicate: 'isCommandFormField' },
+    CommandFormColumn: { mark: 'markAsCommandFormColumn', predicate: 'isCommandFormColumn' },
+};
+
+const EQUALITY = new Set(['===', '!==', '==', '!=']);
+
+// True for `x.displayName` and `x['displayName']`.
+const isDisplayNameMember = node =>
+    node?.type === 'MemberExpression' &&
+    (node.computed
+        ? node.property?.type === 'Literal' && node.property.value === 'displayName'
+        : node.property?.type === 'Identifier' && node.property.name === 'displayName');
+
+const markerFor = node =>
+    node?.type === 'Literal' && typeof node.value === 'string'
+        ? MARKERS[node.value]
+        : undefined;
+
+// Disallow hand-writing the `displayName` strings that identify a CommandForm field or
+// column, in either direction — stamping one onto a component, or comparing against one to
+// decide what a child is.
+//
+// `displayName` is React's public, writable diagnostic name and a routine target for build
+// tooling: Storybook's `reactDocgen: 'react-docgen-typescript'` setting rewrites it by
+// default. A component identified only by that string stops being recognized the moment
+// anything renames it, and it fails silently — the field simply renders with no container,
+// so no label, no bound value and no change handler, with no error and no warning.
+//
+// The helpers in '@cratis/components/CommandForm' set and read an `isCommandFormField` /
+// `isCommandFormColumn` marker that a rename does not touch, and keep the legacy `displayName`
+// alongside it for compatibility, so going through them is both safer and strictly more
+// permissive than the literal. `@cratis/arc.react` marks and reads the same two properties;
+// that shared shape is what carries the contract between the packages.
+export const noRawCommandFormMarker = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow identifying CommandForm fields and columns by a raw displayName string; use the marker helpers.',
+            recommended: true,
+            url: 'https://github.com/Cratis/Components/blob/main/ESLint/README.md',
+        },
+        schema: [],
+        messages: {
+            useMarkHelper:
+                "Do not stamp displayName = '{{name}}' by hand — a build transform that rewrites displayName silently unbinds this component. Use {{helper}}() from '@cratis/components/CommandForm'.",
+            usePredicate:
+                "Do not identify a CommandForm child by comparing displayName to '{{name}}' — a component whose displayName was rewritten is missed. Use {{helper}}() from '@cratis/components/CommandForm'.",
+        },
+    },
+    create(context) {
+        const report = (node, messageId, helper, name) =>
+            context.report({ node, messageId, data: { helper, name } });
+
+        return {
+            // C.displayName = 'CommandFormField'
+            AssignmentExpression(node) {
+                if (node.operator !== '=' || !isDisplayNameMember(node.left)) return;
+                const marker = markerFor(node.right);
+                if (marker) report(node, 'useMarkHelper', marker.mark, node.right.value);
+            },
+
+            // { displayName: 'CommandFormField' } — e.g. via Object.assign
+            Property(node) {
+                const key = node.computed ? undefined : node.key;
+                const named =
+                    (key?.type === 'Identifier' && key.name === 'displayName') ||
+                    (key?.type === 'Literal' && key.value === 'displayName');
+                if (!named) return;
+                const marker = markerFor(node.value);
+                if (marker) report(node, 'useMarkHelper', marker.mark, node.value.value);
+            },
+
+            // child.displayName === 'CommandFormField' (either operand order)
+            BinaryExpression(node) {
+                if (!EQUALITY.has(node.operator)) return;
+                const [member, literal] = isDisplayNameMember(node.left)
+                    ? [node.left, node.right]
+                    : [node.right, node.left];
+                if (!isDisplayNameMember(member)) return;
+                const marker = markerFor(literal);
+                if (marker) report(node, 'usePredicate', marker.predicate, literal.value);
+            },
+        };
+    },
+};
+
+export default noRawCommandFormMarker;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@cratis/eslint-plugin-components",
-    "version": "3.4.0",
-    "description": "Cratis Components ESLint rules: import from subpaths not the root barrel, use the Cratis dialog wrappers instead of primereact/dialog, require onBeforeExecute callbacks to return their values, and keep React hooks out of view models. Compose on top of @cratis/eslint-config.",
+    "version": "3.5.1",
+    "description": "Cratis Components ESLint rules: import from subpaths not the root barrel, use the Cratis dialog wrappers instead of primereact/dialog, require onBeforeExecute callbacks to return their values, keep React hooks out of view models, and identify CommandForm fields by a tamper-resistant marker rather than a raw displayName string. Compose on top of @cratis/eslint-config.",
     "author": "Cratis",
     "license": "MIT",
     "type": "module",