@cratis/eslint-plugin-components 2.4.1 → 2.5.1

package/README.md

@@ -7,8 +7,10 @@ Cratis base config, [`@cratis/eslint-config`](https://www.npmjs.com/package/@cra
 |---|---|
 | `no-root-barrel-import` | Disallows importing from the `@cratis/components` root barrel. Use a subpath export (`@cratis/components/CommandDialog`, `@cratis/components/DataPage`, `@cratis/components/Toolbar`, …) — the root pulls the whole optional-peer-heavy surface and hides intent. |
 | `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. |
 
-Both cover `import` and re-`export … from` forms.
+The two import rules cover `import` and re-`export … from` forms.
 
 ## Install
 
@@ -41,3 +43,56 @@ export default [
     source: 'primereact/dialog',        // module to forbid
 }],
 ```
+
+`onbeforeexecute-must-return` and `no-hooks-in-view-model` take no options.
+
+## Rules
+
+### `onbeforeexecute-must-return`
+
+`onBeforeExecute` (on `CommandDialog`, `StepperCommandDialog`, `CommandScope`, …) is a
+**transformer**: it receives the current command values and must **return** them (mutated or
+not). A callback that returns nothing runs the command with `undefined` — every field is
+wiped at submit time. TypeScript catches this at fully-typed call sites; this rule is the
+backstop for JavaScript and loosely-typed consumers.
+
+```tsx
+// ✅ returns the values
+<CommandDialog onBeforeExecute={values => { values.id = Guid.create(); return values; }} />
+<CommandDialog onBeforeExecute={values => values} />
+
+// ❌ side-effect only — command executes with undefined
+<CommandDialog onBeforeExecute={values => { values.id = Guid.create(); }} />
+// ❌ bare return
+<CommandDialog onBeforeExecute={values => { return; }} />
+```
+
+It flags JSX attribute (`onBeforeExecute={…}`), object property (`{ onBeforeExecute: … }`),
+and variable (`const onBeforeExecute = …`) forms. It is a lint backstop, not a full
+control-flow analysis: a callback that returns a value on some branches but can still fall
+through is not flagged.
+
+### `no-hooks-in-view-model`
+
+A view model is plain TypeScript — it must never call React hooks. `react-hooks/rules-of-hooks`
+does not reliably flag hooks called from **class methods**, so this rule fills the gap for
+Cratis MVVM view models. Inject an abstraction (`IIdentityProvider`, `IMessenger`, a query
+service) instead of calling a hook.
+
+```ts
+// ❌ generated Arc proxy hook inside a view model
+class AuthorsViewModel {
+    load() { const [authors] = AllAuthors.use(); }   // flagged
+}
+
+// ✅ inject the abstraction; call hooks only in the component
+@injectable
+class AuthorsViewModel {
+    constructor(private readonly identity: IIdentityProvider) {}
+}
+```
+
+A class is treated as a view model when it is registered via `withViewModel(...)`, decorated
+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.

package/index.js

@@ -1,6 +1,8 @@
 import { createRequire } from 'node:module';
 import { noPrimereactDialog } from './lib/noPrimereactDialog.js';
 import { noRootBarrelImport } from './lib/noRootBarrelImport.js';
+import { onbeforeexecuteMustReturn } from './lib/onbeforeexecuteMustReturn.js';
+import { noHooksInViewModel } from './lib/noHooksInViewModel.js';
 
 const { version } = createRequire(import.meta.url)('./package.json');
 
@@ -13,6 +15,8 @@ const plugin = {
     rules: {
         'no-primereact-dialog': noPrimereactDialog,
         'no-root-barrel-import': noRootBarrelImport,
+        'onbeforeexecute-must-return': onbeforeexecuteMustReturn,
+        'no-hooks-in-view-model': noHooksInViewModel,
     },
     configs: {},
 };
@@ -31,6 +35,8 @@ Object.assign(plugin.configs, {
             rules: {
                 '@cratis/components/no-primereact-dialog': 'error',
                 '@cratis/components/no-root-barrel-import': 'error',
+                '@cratis/components/onbeforeexecute-must-return': 'error',
+                '@cratis/components/no-hooks-in-view-model': 'error',
             },
         },
     ],
@@ -38,4 +44,4 @@ Object.assign(plugin.configs, {
 
 export default plugin;
 export const { configs, rules, meta } = plugin;
-export { noPrimereactDialog, noRootBarrelImport };
+export { noPrimereactDialog, noRootBarrelImport, onbeforeexecuteMustReturn, noHooksInViewModel };

package/lib/noHooksInViewModel.js

@@ -0,0 +1,122 @@
+const HOOK_IDENTIFIER = /^use[A-Z0-9]/;
+// Matches a `.use(...)` / `.useSuspense(...)` / `.useChangeStream(...)` member call — the
+// shape of a generated Arc query/command proxy hook — as well as bare `useX()` hooks.
+const HOOK_MEMBER = /^use([A-Z0-9]|$)/;
+
+const decoratorName = (decorator) => {
+    const expression = decorator.expression;
+    if (!expression) return undefined;
+    if (expression.type === 'Identifier') return expression.name;
+    if (expression.type === 'CallExpression' && expression.callee?.type === 'Identifier') {
+        return expression.callee.name;
+    }
+    return undefined;
+};
+
+const hasInjectableDecorator = (classNode) => {
+    const decorators = classNode.decorators ?? [];
+    return decorators.some((decorator) => decoratorName(decorator) === 'injectable');
+};
+
+const isHookCall = (node) => {
+    const callee = node.callee;
+    if (!callee) return false;
+    if (callee.type === 'Identifier') return HOOK_IDENTIFIER.test(callee.name);
+    if (callee.type === 'MemberExpression' && callee.property?.type === 'Identifier' && !callee.computed) {
+        return HOOK_MEMBER.test(callee.property.name);
+    }
+    return false;
+};
+
+// Walk a class body for hook calls, without descending into a nested class (a different
+// subject) — but still descend through the view model's own methods and getters.
+const forEachHookCall = (node, visit) => {
+    if (!node || typeof node.type !== 'string') return;
+    if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') return;
+    if (node.type === 'CallExpression' && isHookCall(node)) {
+        visit(node);
+    }
+    for (const key of Object.keys(node)) {
+        if (key === 'parent') continue;
+        const child = node[key];
+        if (Array.isArray(child)) {
+            for (const item of child) forEachHookCall(item, visit);
+        } else {
+            forEachHookCall(child, visit);
+        }
+    }
+};
+
+// Forbid React hooks (including generated Arc proxies' `.use()`) inside a class that is a
+// view model — one registered via `withViewModel`, decorated with `@injectable`, or named
+// `*ViewModel`. `react-hooks/rules-of-hooks` does not reliably flag hooks called from class
+// methods; a view model must be plain, hook-free TypeScript and receive injected
+// abstractions instead.
+export const noHooksInViewModel = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow React hooks (including Arc proxy .use()) inside a view model class.',
+            recommended: true,
+            url: 'https://github.com/Cratis/Components/blob/main/ESLint/README.md',
+        },
+        schema: [],
+        messages: {
+            noHook: "Do not call the hook '{{name}}' inside a view model. View models must be plain, hook-free classes — inject the abstraction (IIdentityProvider, IMessenger, a query service) instead.",
+        },
+    },
+    create(context) {
+        const registeredViewModels = new Set();
+        const classNodes = [];
+
+        const nameOfCallee = (callee) => {
+            if (!callee) return undefined;
+            if (callee.type === 'Identifier') return callee.name;
+            if (callee.type === 'MemberExpression' && callee.property?.type === 'Identifier') {
+                return callee.property.name;
+            }
+            return undefined;
+        };
+
+        const hookName = (node) => {
+            const callee = node.callee;
+            if (callee.type === 'Identifier') return callee.name;
+            if (callee.type === 'MemberExpression' && callee.property?.type === 'Identifier') {
+                return `.${callee.property.name}`;
+            }
+            return 'hook';
+        };
+
+        const collectClass = (node) => {
+            classNodes.push(node);
+        };
+
+        return {
+            CallExpression(node) {
+                if (nameOfCallee(node.callee) !== 'withViewModel') return;
+                const first = node.arguments[0];
+                if (first?.type === 'Identifier') {
+                    registeredViewModels.add(first.name);
+                }
+            },
+            ClassDeclaration: collectClass,
+            ClassExpression: collectClass,
+            'Program:exit'() {
+                for (const classNode of classNodes) {
+                    const name = classNode.id?.name;
+                    const isViewModel =
+                        (name && /ViewModel$/.test(name)) ||
+                        hasInjectableDecorator(classNode) ||
+                        (name && registeredViewModels.has(name));
+                    if (!isViewModel) continue;
+
+                    forEachHookCall(classNode.body, (call) => {
+                        context.report({ node: call, messageId: 'noHook', data: { name: hookName(call) } });
+                    });
+                }
+            },
+        };
+    },
+};
+
+export default noHooksInViewModel;

package/lib/onbeforeexecuteMustReturn.js

@@ -0,0 +1,107 @@
+// Collect every `return` statement that belongs directly to `functionBody`, without
+// descending into nested functions (their returns are not this function's returns) or into
+// a return's own argument (which may itself contain a nested arrow).
+const collectOwnReturns = (node, returns) => {
+    if (!node || typeof node.type !== 'string') return;
+    if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {
+        return;
+    }
+    if (node.type === 'ReturnStatement') {
+        returns.push(node);
+        return;
+    }
+    for (const key of Object.keys(node)) {
+        if (key === 'parent') continue;
+        const child = node[key];
+        if (Array.isArray(child)) {
+            for (const item of child) collectOwnReturns(item, returns);
+        } else {
+            collectOwnReturns(child, returns);
+        }
+    }
+};
+
+const keyNameOf = (key) => {
+    if (!key) return undefined;
+    if (key.type === 'Identifier') return key.name;
+    if (key.type === 'Literal') return String(key.value);
+    return undefined;
+};
+
+// True when `node` is the function assigned to an `onBeforeExecute` binding — a JSX
+// attribute (`onBeforeExecute={...}`), an object property (`{ onBeforeExecute: ... }`), or a
+// variable (`const onBeforeExecute = ...`).
+const isOnBeforeExecuteCallback = (node) => {
+    const parent = node.parent;
+    if (!parent) return false;
+
+    if (parent.type === 'JSXExpressionContainer' &&
+        parent.parent?.type === 'JSXAttribute' &&
+        parent.parent.name?.name === 'onBeforeExecute') {
+        return true;
+    }
+
+    if ((parent.type === 'Property' || parent.type === 'PropertyDefinition') &&
+        parent.value === node &&
+        keyNameOf(parent.key) === 'onBeforeExecute') {
+        return true;
+    }
+
+    if (parent.type === 'VariableDeclarator' &&
+        parent.init === node &&
+        parent.id?.type === 'Identifier' &&
+        parent.id.name === 'onBeforeExecute') {
+        return true;
+    }
+
+    return false;
+};
+
+// Require an `onBeforeExecute` callback to return the command values on every path. It is a
+// transformer, not a side-effect hook: a body that can complete without returning executes
+// the command with `undefined` (silent data loss). A lint backstop for consumers whose call
+// sites are not fully typed — it flags a block-bodied callback that returns nothing, or a
+// bare `return;`. It does not do full path analysis, so a callback that returns a value on
+// some branches but can still fall through is not flagged.
+export const onbeforeexecuteMustReturn = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require an onBeforeExecute callback to return the command values; returning nothing executes the command with undefined.',
+            recommended: true,
+            url: 'https://github.com/Cratis/Components/blob/main/ESLint/README.md',
+        },
+        schema: [],
+        messages: {
+            missingReturn: 'onBeforeExecute is a transformer and must return the command values. This callback can complete without returning, which executes the command with undefined values. Return the values (mutated or not).',
+            emptyReturn: 'onBeforeExecute must return the command values, not `return;`. Return the values (mutated or not).',
+        },
+    },
+    create(context) {
+        const check = (node) => {
+            if (!isOnBeforeExecuteCallback(node)) return;
+            // An expression-bodied arrow (`values => values`) always returns a value.
+            if (node.type === 'ArrowFunctionExpression' && node.body.type !== 'BlockStatement') return;
+
+            const returns = [];
+            collectOwnReturns(node.body, returns);
+
+            const emptyReturn = returns.find((statement) => !statement.argument);
+            if (emptyReturn) {
+                context.report({ node: emptyReturn, messageId: 'emptyReturn' });
+                return;
+            }
+
+            if (returns.length === 0) {
+                context.report({ node, messageId: 'missingReturn' });
+            }
+        };
+
+        return {
+            ArrowFunctionExpression: check,
+            FunctionExpression: check,
+        };
+    },
+};
+
+export default onbeforeexecuteMustReturn;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@cratis/eslint-plugin-components",
-    "version": "2.4.1",
-    "description": "Cratis Components ESLint rules: import from subpaths, not the root barrel, and use the Cratis dialog wrappers instead of primereact/dialog. Compose on top of @cratis/eslint-config.",
+    "version": "2.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, and keep React hooks out of view models. Compose on top of @cratis/eslint-config.",
     "author": "Cratis",
     "license": "MIT",
     "type": "module",