@cratis/eslint-plugin-components 4.14.0 → 4.14.2

package/README.md

@@ -7,22 +7,17 @@ Cratis base config, [`@cratis/eslint-config`](https://www.npmjs.com/package/@cra
 | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `no-root-barrel-import`       | Disallows importing a removed Components 3 component namespace from the Components 4 setup-only root. Use the exact component subpath (`@cratis/components/CommandDialog`, `@cratis/components/DataPage`, `@cratis/components/Toolbar`, …). Package-wide provider/configuration symbols remain allowed at the root; an unambiguous namespace violation is autofixed. |
 | `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. The runtime guards a missing return by keeping the current object and warning, but a replacement value is discarded and the callback violates the transformer contract.                                                                                                                         |
+| `onbeforeexecute-must-return` | Requires `onBeforeExecute` on imported Components command dialogs/steppers or Arc `CommandForm` to return command values. It does not flag Arc `CommandScope`, whose callback is void.                                                                                                                         |
 | `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.                                            |
 | `no-react-in-kernel`          | Repository architecture rule that rejects React, React DOM, React Aria Components, and browser DOM globals in the explicit Components kernel inventory. It is intentionally not part of the consumer `recommended` config.                                                                                                                                           |
 
 Both import rules cover static `import` and re-`export … from` forms. The root-barrel rule also reports TypeScript `import = require(...)`, dynamic `import(...)`, and CommonJS `require(...)` of the package root; ambiguous forms are never autofixed.
 
-> **Publication status:** The install examples target the owner-authorized 4.0.0 npm release. When
-> reading this README from repository source before that release, verify availability with
-> `npm view @cratis/eslint-plugin-components@4.0.0 version`; source contributors use the workspace
-> commands in this checkout instead.
-
 ## Install
 
-Use the independently released Components 4 tooling train bounded to `>=4 <5`. Never use
-`latest`; plugin patches can release independently from Components Core:
+The plugin is released at the same version as `@cratis/components`. Install the Components 4
+tooling train bounded to `>=4 <5` so a future major cannot arrive unannounced. Never use `latest`:
 
 ```sh
 TOOLING_RANGE='^4.0.0' # Shell-safe equivalent of >=4 <5.
@@ -100,7 +95,8 @@ Components 4 removes every component-family namespace from the package root. The
 
 - `CratisComponentsProvider`, `useCratisComponentsConfig`, `cratisDefaults`, and `mergeCratisComponentsConfig`;
 - `CratisComponentsConfig`, `CratisComponentsProviderProps`, and `CratisComponentsMessages`;
-- `CratisPaginatorMessages`, `CratisDatePickerMessages`, `CratisDropdownMessages`, `CratisDialogMessages`, `CratisStepperMessages`, `CratisNotificationsMessages`, `CratisDataTableMessages`, and `CratisColumnFilterMessages`.
+- `CratisPaginatorMessages`, `CratisDatePickerMessages`, `CratisDropdownMessages`, `CratisDialogMessages`, `CratisStepperMessages`, `CratisNotificationsMessages`, `CratisDataTableMessages`, and `CratisColumnFilterMessages`;
+- `CratisComponentsIcons`, `CratisIconResolver`, and `useCratisIcon`.
 
 ```ts
 // ✅ approved setup symbols stay at the root
@@ -142,8 +138,10 @@ The rule never guesses. Each of these is flagged with guidance but **not** autof
 - The Components 3.6 `Compatibility` namespace and direct pass-through exports — reported
   as known removals with typed-parts guidance and never autofixed because Components 4 has
   no compatibility subpath.
-- Any `export … from '@cratis/components'` re-export form — flagged with the same subpath
-  guidance, but re-exports are never autofixed.
+- Any `export … from '@cratis/components'` re-export of a namespace, removed compatibility
+  export, or unknown symbol, and any wildcard re-export — flagged with the same subpath
+  guidance, but re-exports are never autofixed. Re-exporting an approved setup symbol is
+  allowed.
 
 A companion, standalone codemod applies the equivalent rewrite across a whole project in one
 pass, and additionally autofixes a named `export { Canvas } from '@cratis/components'`
@@ -153,10 +151,12 @@ form with guidance but never autofixes any of them; see
 
 ### `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 does not run the command with `undefined` — a runtime
-guard (`applyBeforeExecute`) falls back to the current object and logs a `console.warn`.
+`onBeforeExecute` on `CommandDialog`, `StepperCommandDialog`, `CommandStepper`, and Arc's
+`CommandForm` is a **transformer**: it receives the current command values and must **return** them (mutated or
+not). In the Components wrappers, a callback that returns nothing does not run the command with
+`undefined` — a runtime guard (`applyBeforeExecute`) falls back to the current object and logs a
+`console.warn`. Arc's standalone `CommandForm` (22.16.0) uses the returned value directly, with no
+such fallback.
 In-place mutations may therefore remain, but a replacement object is discarded and the call
 still violates the transformer contract. TypeScript catches this at fully typed call sites;
 this rule is the static backstop for JavaScript and loosely typed consumers, so behavior never
@@ -173,10 +173,7 @@ relies on the fallback.
 <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.
+The rule checks JSX callbacks only when the component resolves through an import from `@cratis/components/CommandDialog` (`CommandDialog`, `StepperCommandDialog`, `CommandStepper`), `@cratis/components/CommandStepper` (`CommandStepper`), or `@cratis/arc.react/commands` (`CommandForm`). Aliases and namespace imports are supported. Unknown components, object properties, and standalone variables are not flagged because their callback contract cannot be inferred. In particular, Arc `CommandScope` has a void-returning `onBeforeExecute` side-effect hook, not a transformer, so it is not flagged. This rule is 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`
 

package/lib/onbeforeexecuteMustReturn.js

@@ -32,39 +32,22 @@ const keyNameOf = (key) => {
     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;
+const transformerExports = new Map([
+    [
+        '@cratis/components/CommandDialog',
+        new Set(['CommandDialog', 'StepperCommandDialog', 'CommandStepper']),
+    ],
+    ['@cratis/components/CommandStepper', new Set(['CommandStepper'])],
+    ['@cratis/arc.react/commands', new Set(['CommandForm'])],
+]);
 
-    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;
+const importBinding = (scope, name) => {
+    for (let current = scope; current; current = current.upper) {
+        const variable = current.set.get(name);
+        if (variable)
+            return variable.defs.find(definition => definition.type === 'ImportBinding')?.node;
     }
-
-    return false;
+    return undefined;
 };
 
 // Require an `onBeforeExecute` callback to return the command values on every path. It is a
@@ -94,8 +77,34 @@ export const onbeforeexecuteMustReturn = {
         },
     },
     create(context) {
+        const imports = new Map();
+        const isTransformer = (node) => {
+            const attribute = node.parent?.parent;
+            if (
+                node.parent?.type !== 'JSXExpressionContainer' ||
+                attribute?.type !== 'JSXAttribute' ||
+                attribute.name?.name !== 'onBeforeExecute'
+            ) return false;
+            const opening = attribute.parent;
+            if (opening?.type !== 'JSXOpeningElement') return false;
+            const tag = opening.name;
+            const identifier = tag.type === 'JSXIdentifier'
+                ? tag
+                : tag.type === 'JSXMemberExpression' &&
+                    tag.object.type === 'JSXIdentifier' &&
+                    tag.property.type === 'JSXIdentifier'
+                    ? tag.object
+                    : undefined;
+            if (!identifier) return false;
+            const specifier = importBinding(context.sourceCode.getScope(node), identifier.name);
+            const imported = imports.get(specifier);
+            if (!imported) return false;
+            return tag.type === 'JSXIdentifier'
+                ? imported.kind === 'named'
+                : imported.kind === 'namespace' && imported.exports.has(tag.property.name);
+        };
         const check = (node) => {
-            if (!isOnBeforeExecuteCallback(node)) return;
+            if (!isTransformer(node)) return;
             // An expression-bodied arrow (`values => values`) always returns a value.
             if (
                 node.type === 'ArrowFunctionExpression' &&
@@ -118,6 +127,21 @@ export const onbeforeexecuteMustReturn = {
         };
 
         return {
+            ImportDeclaration(node) {
+                const exports = transformerExports.get(node.source.value);
+                if (!exports || node.importKind === 'type') return;
+                for (const specifier of node.specifiers) {
+                    if (specifier.type === 'ImportNamespaceSpecifier') {
+                        imports.set(specifier, { kind: 'namespace', exports });
+                    } else if (
+                        specifier.type === 'ImportSpecifier' &&
+                        specifier.importKind !== 'type' &&
+                        exports.has(keyNameOf(specifier.imported))
+                    ) {
+                        imports.set(specifier, { kind: 'named' });
+                    }
+                }
+            },
             ArrowFunctionExpression: check,
             FunctionExpression: check,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/eslint-plugin-components",
-    "version": "4.14.0",
+    "version": "4.14.2",
     "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, protect the repository-owned React-free kernel, 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",