@cratis/eslint-plugin-components 3.6.1 → 4.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cratis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,20 +3,37 @@
 ESLint rules for projects that consume Cratis Components. Compose these on top of the
 Cratis base config, [`@cratis/eslint-config`](https://www.npmjs.com/package/@cratis/eslint-config).
 
-| Rule | What it does |
-|---|---|
-| `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. |
-| `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.
+| Rule                          | What it does                                                                                                                                                                                                                                                                                                                                                         |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.                                                                                                                         |
+| `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:
+
 ```sh
-yarn add -D @cratis/eslint-plugin-components @cratis/eslint-config eslint
+TOOLING_RANGE='^4.0.0' # Shell-safe equivalent of >=4 <5.
+
+# Choose the application package manager:
+npm install --save-dev "@cratis/eslint-plugin-components@$TOOLING_RANGE" \
+  @cratis/eslint-config eslint
+pnpm add --save-dev "@cratis/eslint-plugin-components@$TOOLING_RANGE" \
+  @cratis/eslint-config eslint
+yarn add --dev "@cratis/eslint-plugin-components@$TOOLING_RANGE" \
+  @cratis/eslint-config eslint
 ```
 
 ## Use
@@ -38,7 +55,7 @@ export default [
 ```js
 '@cratis/components/no-root-barrel-import': ['error', {
     packageName: '@cratis/components',  // barrel to forbid
-    allow: [],                          // exact specifiers to permit
+    allow: [],                          // exact specifiers to permit wholesale
 }],
 '@cratis/components/no-primereact-dialog': ['error', {
     source: 'primereact/dialog',        // module to forbid
@@ -47,24 +64,112 @@ export default [
 
 `onbeforeexecute-must-return`, `no-hooks-in-view-model` and `no-raw-command-form-marker` take no options.
 
+`no-react-in-kernel` is a repository-owned architecture guard and is not enabled by the consumer preset. Components configures it with the canonical inventory in `lib/kernelBoundary.js`; an explicit `kernelPaths` array may be supplied when testing or applying the rule to another owned tree.
+
+## Repository kernel boundary
+
+`no-react-in-kernel` applies only when the linted filename is one of the explicitly declared `kernelPaths`. It reports static imports and re-exports, TypeScript import assignments, dynamic imports, CommonJS `require(...)`, package subpaths, and browser DOM global references. Near-miss package names and files outside the inventory are left alone. The repository decision and exact included/excluded modules are documented in `Documentation/decisions/0003-kernel-boundary.md`.
+
+## Considered and rejected: a hardcoded-owned-label rule
+
+During the issue #174 localization pass, a static rule flagging a hardcoded English literal that
+bypasses `CratisComponentsProvider` messages (e.g. a `title`/`aria-label` string sitting next to an
+already-localized prop) was considered and rejected. Every rule above is a syntactic, structural
+pattern an AST visitor resolves unambiguously (an import specifier, a known display-name
+constant, a callback's control-flow shape). Detecting an _owned-label bypass_ instead requires
+understanding which of a component's many string literals are user-facing chrome versus CSS class
+names, `data-*` values, decorative glyphs, or genuinely correct per-instance defaults — a semantic
+judgment call, not a syntactic one. A rule broad enough to catch a real bypass (any string literal
+passed to `title`/`aria-label`/`placeholder`/a `Tooltip`'s `content`) flags the large fraction of
+those call sites that are already correct, and an allowlist narrow enough to avoid that noise stops
+catching new bypasses the moment a new component or prop name is introduced — the allowlist would
+need updating in lockstep with every future component, which defeats the purpose of a ratchet.
+Render-time sentinel-provider specs (see
+`Source/Common/for_CratisComponentsProvider/when_every_owned_label_is_overridden.tsx`) are the
+reliable gate instead: they render each audited surface under a provider whose messages are all
+unmistakable sentinel strings and assert the rendered label is the sentinel, never the English
+default — a real behavioral check that a static rule cannot approximate without the same false-positive
+cost. Revisit a lint rule if a narrower, high-confidence pattern emerges (for example, once every
+owned-label prop follows one consistent naming and JSDoc convention).
+
 ## Rules
 
+### `no-root-barrel-import`
+
+Components 4 removes every component-family namespace from the package root. The rule keeps a fixed map from each Components 3 namespace to its Components 4 subpath, plus the exact setup allowlist that remains at the root:
+
+- `CratisComponentsProvider`, `useCratisComponentsConfig`, `cratisDefaults`, and `mergeCratisComponentsConfig`;
+- `CratisComponentsConfig`, `CratisComponentsProviderProps`, and `CratisComponentsMessages`;
+- `CratisPaginatorMessages`, `CratisDatePickerMessages`, `CratisDropdownMessages`, `CratisDialogMessages`, `CratisStepperMessages`, `CratisNotificationsMessages`, `CratisDataTableMessages`, and `CratisColumnFilterMessages`.
+
+```ts
+// ✅ approved setup symbols stay at the root
+import { CratisComponentsProvider } from '@cratis/components';
+
+// ❌ a component namespace imported from the root barrel
+import { Canvas } from '@cratis/components';
+
+// ✅ the same namespace, imported from its subpath
+import * as Canvas from '@cratis/components/Canvas';
+
+// ❌ whole-package forms are ambiguous and reported without an autofix
+import Components = require('@cratis/components');
+const lazyComponents = await import('@cratis/components');
+```
+
+A single-namespace violation is autofixed to the namespace form shown above, preserving an alias (`Canvas as C`) and `import type` (`import type { Canvas } from '@cratis/components'` becomes `import type * as Canvas from '@cratis/components/Canvas'`, and a per-specifier `type` modifier is honored the same way). The historical `CommandStepper` namespace is mapped to `@cratis/components/CommandDialog`, because that root namespace exposed the complete CommandDialog module rather than only the narrower standalone stepper entry. A mixed import naming both a setup symbol and a namespace is split — the setup symbol stays imported from the root, the namespace moves:
+
+```ts
+// Before
+import { CratisComponentsProvider, Canvas } from '@cratis/components';
+
+// After (autofixed)
+import { CratisComponentsProvider } from '@cratis/components';
+import * as Canvas from '@cratis/components/Canvas';
+```
+
+The rule never guesses. Each of these is flagged with guidance but **not** autofixed:
+
+- A namespace import of the whole package (`import * as Everything from '@cratis/components'`)
+  — which subpath each later member access belongs to cannot be inferred from the import alone.
+- A default import (`import Everything from '@cratis/components'`) — the package has no
+  default export.
+- A side-effect-only import (`import '@cratis/components'`) — there is no binding to infer a
+  subpath from.
+- A named import of a symbol that is neither an approved setup symbol nor a known namespace
+  (for example a member that only exists _inside_ a namespace, not at the root) — the whole
+  statement is left unfixed rather than partially migrated.
+- 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.
+
+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'`
+re-export the same way it autofixes the matching import — this rule flags every re-export
+form with guidance but never autofixes any of them; see
+[`@cratis/components.migrator`](https://www.npmjs.com/package/@cratis/components.migrator).
+
 ### `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.
+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`.
+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
+relies on the fallback.
 
 ```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
+// ❌ replacement is discarded — the runtime falls back to `values` and warns
+<CommandDialog onBeforeExecute={values => { const updated = { ...values, id: Guid.create() }; }} />
+// ❌ bare return — same guarded fallback
 <CommandDialog onBeforeExecute={values => { return; }} />
 ```
 
@@ -83,7 +188,9 @@ service) instead of calling a hook.
 ```ts
 // ❌ generated Arc proxy hook inside a view model
 class AuthorsViewModel {
-    load() { const [authors] = AllAuthors.use(); }   // flagged
+    load() {
+        const [authors] = AllAuthors.use();
+    } // flagged
 }
 
 // ✅ inject the abstraction; call hooks only in the component
@@ -103,7 +210,7 @@ inside a nested non–view-model class are not.
 `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
+_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
@@ -118,13 +225,20 @@ properties, and that shared shape is what carries the contract across the two pa
 ```ts
 // ❌ a build transform that rewrites displayName silently unbinds this field
 MyField.displayName = 'CommandFormField';
-if (component.displayName === 'CommandFormField') { wrap(component); }
+if (component.displayName === 'CommandFormField') {
+    wrap(component);
+}
 
 // ✅ marker first, legacy displayName still set and still honoured
-import { markAsCommandFormField, isCommandFormField } from '@cratis/components/CommandForm';
+import {
+    markAsCommandFormField,
+    isCommandFormField,
+} from '@cratis/components/CommandForm';
 
 markAsCommandFormField(MyField);
-if (isCommandFormField(component)) { wrap(component); }
+if (isCommandFormField(component)) {
+    wrap(component);
+}
 ```
 
 Flagged in both directions: assignment (`C.displayName = '…'`, including computed and

package/index.js

@@ -4,6 +4,7 @@ import { noRootBarrelImport } from './lib/noRootBarrelImport.js';
 import { onbeforeexecuteMustReturn } from './lib/onbeforeexecuteMustReturn.js';
 import { noHooksInViewModel } from './lib/noHooksInViewModel.js';
 import { noRawCommandFormMarker } from './lib/noRawCommandFormMarker.js';
+import { noReactInKernel } from './lib/noReactInKernel.js';
 
 const { version } = createRequire(import.meta.url)('./package.json');
 
@@ -19,6 +20,7 @@ const plugin = {
         'onbeforeexecute-must-return': onbeforeexecuteMustReturn,
         'no-hooks-in-view-model': noHooksInViewModel,
         'no-raw-command-form-marker': noRawCommandFormMarker,
+        'no-react-in-kernel': noReactInKernel,
     },
     configs: {},
 };
@@ -32,7 +34,7 @@ Object.assign(plugin.configs, {
     recommended: [
         {
             name: '@cratis/components/recommended',
-            files: ['**/*.ts', '**/*.tsx'],
+            files: ['**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}'],
             plugins: { '@cratis/components': plugin },
             rules: {
                 '@cratis/components/no-primereact-dialog': 'error',
@@ -47,4 +49,4 @@ Object.assign(plugin.configs, {
 
 export default plugin;
 export const { configs, rules, meta } = plugin;
-export { noPrimereactDialog, noRootBarrelImport, onbeforeexecuteMustReturn, noHooksInViewModel, noRawCommandFormMarker };
+export { noPrimereactDialog, noRootBarrelImport, onbeforeexecuteMustReturn, noHooksInViewModel, noRawCommandFormMarker, noReactInKernel };

package/lib/kernelBoundary.js

@@ -0,0 +1,139 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import path from 'node:path';
+
+/**
+ * Repository-owned source modules whose contracts are deliberately independent of React and the browser DOM.
+ *
+ * This is the canonical kernel inventory. The root ESLint config, the no-react-in-kernel rule, and the
+ * emitted package-graph gate all consume this exact list.
+ */
+export const kernelSourcePaths = Object.freeze([
+    'Source/PivotViewer/constants.ts',
+    'Source/PivotViewer/engine/layout.ts',
+    'Source/PivotViewer/engine/requestCorrelator.ts',
+    'Source/PivotViewer/engine/store.ts',
+    'Source/PivotViewer/engine/types.ts',
+    'Source/Canvas/canvasGesture.ts',
+    'Source/Canvas/canvasTransformActivity.ts',
+    'Source/Canvas/panMomentum.ts',
+    'Source/Canvas/pinchGesture.ts',
+    'Source/Canvas/shapes/Region/regionContainment.ts',
+    'Source/Filter/types.ts',
+    'Source/Filter/utils.ts',
+    'Source/DataTables/DataTableFilterMatcherRegistry.ts',
+    'Source/DataTables/DataTableFilterMeta.ts',
+    'Source/DataTables/paginatorRange.ts',
+    'Source/DataTables/selectionKeys.ts',
+    'Source/CommandDialog/applyBeforeExecute.ts',
+    'Source/CommandForm/commandFormMarkers.ts',
+    'Source/CommandForm/fields/chipValues.ts',
+    'Source/CommandForm/fields/fieldValueFromEvent.ts',
+    'Source/SchemaEditor/schemaHelpers.ts',
+    'Source/Chat/isTopicUnnamed.ts',
+    'Source/Chat/shouldRequestTopicName.ts',
+    'Source/Chat/topicsByActivity.ts',
+    'Source/Chat/Kit/findOwnReaction.ts',
+    'Source/Chat/Kit/reactionsExcludingUser.ts',
+    'Source/Chat/Kit/Mentions/MentionCandidate.ts',
+    'Source/Chat/Kit/Mentions/MentionQuery.ts',
+    'Source/Chat/Kit/Mentions/activeMentionQuery.ts',
+    'Source/Chat/Kit/Mentions/applyMention.ts',
+    'Source/Chat/Kit/Mentions/extractMentions.ts',
+    'Source/Chat/Kit/Mentions/findMentionRanges.ts',
+    'Source/Chat/Kit/Mentions/matchCandidates.ts',
+    'Source/Chat/Kit/Mentions/mentionSegments.ts',
+]);
+
+/** React package roots forbidden from kernel source and emitted closures. */
+const reactKernelPackages = Object.freeze([
+    'react',
+    'react-dom',
+    'react-aria-components',
+]);
+
+/** Browser DOM globals forbidden from kernel source and emitted runtime closures. */
+export const browserDomGlobals = Object.freeze([
+    'CSSStyleDeclaration',
+    'ClipboardEvent',
+    'CustomEvent',
+    'DOMRect',
+    'Document',
+    'DragEvent',
+    'Element',
+    'Event',
+    'EventTarget',
+    'FocusEvent',
+    'HTMLButtonElement',
+    'HTMLCanvasElement',
+    'HTMLDivElement',
+    'HTMLElement',
+    'HTMLFormElement',
+    'HTMLInputElement',
+    'HTMLTextAreaElement',
+    'InputEvent',
+    'IntersectionObserver',
+    'KeyboardEvent',
+    'MessageEvent',
+    'MouseEvent',
+    'MutationObserver',
+    'Node',
+    'PointerEvent',
+    'ResizeObserver',
+    'TouchEvent',
+    'WheelEvent',
+    'Window',
+    'Worker',
+    'cancelAnimationFrame',
+    'document',
+    'getComputedStyle',
+    'history',
+    'localStorage',
+    'location',
+    'matchMedia',
+    'navigator',
+    'performance',
+    'requestAnimationFrame',
+    'sessionStorage',
+    'self',
+    'window',
+]);
+
+/** True when a package specifier is React, React DOM, React Aria Components, or one of their subpaths. */
+export const isKernelReactSpecifier = (specifier) =>
+    reactKernelPackages.some(
+        (packageName) =>
+            specifier === packageName || specifier.startsWith(`${packageName}/`),
+    );
+
+const normalized = (value) => value.split(path.sep).join('/').replace(/^\.\//u, '');
+
+/** True when an ESLint filename identifies one of the declared repository kernel modules. */
+export function isKernelSourcePath(filename, paths = kernelSourcePaths, cwd = process.cwd()) {
+    if (!filename || filename === '<input>' || filename === '<text>') return false;
+
+    const normalizedFilename = normalized(filename);
+    const normalizedCwd = normalized(cwd).replace(/\/$/u, '');
+    const relative = normalizedFilename.startsWith(`${normalizedCwd}/`)
+        ? normalizedFilename.slice(normalizedCwd.length + 1)
+        : normalizedFilename;
+
+    return paths.some((candidate) => {
+        const normalizedCandidate = normalized(candidate);
+        return (
+            relative === normalizedCandidate ||
+            normalizedFilename.endsWith(`/${normalizedCandidate}`)
+        );
+    });
+}
+
+/** Maps a declared TypeScript module under `Source/` to its emitted `dist/esm` path. */
+export function kernelEmittedPath(sourcePath, extension) {
+    if (extension !== '.js' && extension !== '.d.ts') {
+        throw new Error(`Unsupported kernel emitted extension '${extension}'.`);
+    }
+    return normalized(sourcePath)
+        .replace(/^Source\//u, '')
+        .replace(/\.(?:tsx?|mts|cts)$/u, extension);
+}

package/lib/noReactInKernel.js

@@ -0,0 +1,116 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    browserDomGlobals,
+    isKernelReactSpecifier,
+    isKernelSourcePath,
+    kernelSourcePaths,
+} from './kernelBoundary.js';
+
+/**
+ * Keeps the repository's explicitly declared computation kernel independent of React and browser DOM APIs.
+ * The filename check is intentional: this is an owned architectural boundary, not a consumer-wide ban.
+ */
+export const noReactInKernel = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Disallow React package edges and browser DOM globals in explicitly declared Components kernel modules.',
+            recommended: false,
+            url: 'https://github.com/Cratis/Components/blob/main/Documentation/decisions/0003-kernel-boundary.md',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    kernelPaths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            forbiddenDependency:
+                "Kernel module '{{file}}' must not depend on '{{specifier}}'. Keep React, React DOM, and React Aria Components outside the repository-owned kernel.",
+            forbiddenBrowserGlobal:
+                "Kernel module '{{file}}' must not use browser DOM global '{{name}}'. Pass data through a React/DOM adapter outside the kernel instead.",
+        },
+    },
+    create(context) {
+        const kernelPaths = context.options[0]?.kernelPaths ?? kernelSourcePaths;
+        const filename = context.filename;
+        if (!isKernelSourcePath(filename, kernelPaths, context.cwd ?? process.cwd())) {
+            return {};
+        }
+
+        const file = kernelPaths.find((candidate) =>
+            isKernelSourcePath(filename, [candidate], context.cwd ?? process.cwd()),
+        );
+        const reportedGlobals = new Set();
+
+        const reportSpecifier = (node) => {
+            if (!node || typeof node.value !== 'string') return;
+            if (!isKernelReactSpecifier(node.value)) return;
+            context.report({
+                node,
+                messageId: 'forbiddenDependency',
+                data: { file, specifier: node.value },
+            });
+        };
+
+        return {
+            ImportDeclaration(node) {
+                reportSpecifier(node.source);
+            },
+            ExportNamedDeclaration(node) {
+                reportSpecifier(node.source);
+            },
+            ExportAllDeclaration(node) {
+                reportSpecifier(node.source);
+            },
+            TSImportEqualsDeclaration(node) {
+                const reference = node.moduleReference;
+                if (reference?.type === 'TSExternalModuleReference') {
+                    reportSpecifier(reference.expression);
+                }
+            },
+            ImportExpression(node) {
+                reportSpecifier(node.source);
+            },
+            CallExpression(node) {
+                if (node.callee.type !== 'Identifier' || node.callee.name !== 'require') {
+                    return;
+                }
+                const [argument] = node.arguments;
+                if (!argument || argument.type === 'SpreadElement') return;
+                reportSpecifier(argument);
+            },
+            'Program:exit'() {
+                const forbidden = new Set(browserDomGlobals);
+                const scopes = context.sourceCode.scopeManager?.scopes ?? [];
+                for (const scope of scopes) {
+                    for (const reference of scope.references) {
+                        const identifier = reference.identifier;
+                        if (!forbidden.has(identifier.name)) continue;
+                        if (reference.resolved?.defs?.length > 0) continue;
+                        const key = `${identifier.range?.[0] ?? identifier.loc.start.line}:${identifier.name}`;
+                        if (reportedGlobals.has(key)) continue;
+                        reportedGlobals.add(key);
+                        context.report({
+                            node: identifier,
+                            messageId: 'forbiddenBrowserGlobal',
+                            data: { file, name: identifier.name },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+
+export default noReactInKernel;

package/lib/noRootBarrelImport.js

@@ -1,48 +1,279 @@
+import {
+    namespaceSubpaths,
+    approvedRootSymbols,
+    removedRootSymbols,
+} from './rootNamespaceMap.js';
+
 const DEFAULTS = { packageName: '@cratis/components', allow: [] };
 
-// Disallow importing from the Cratis Components root barrel. The package exposes
-// purpose-built subpath exports (`@cratis/components/CommandDialog`,
-// `@cratis/components/DataPage`, `@cratis/components/Toolbar`, …); importing the root
-// pulls the whole optional-peer-heavy surface and hides intent. Covers `import` and
-// re-`export … from` forms.
+// Disallow importing a component namespace from the Cratis Components root barrel. The
+// package exposes purpose-built subpath exports (`@cratis/components/CommandDialog`,
+// `@cratis/components/DataPage`, `@cratis/components/Toolbar`, …); Components 4 removes
+// component namespaces from the setup-only root. The small,
+// approved setup surface (`CratisComponentsProvider` and friends) remains importable from
+// the root. Covers static imports/re-exports, TypeScript import assignments, dynamic imports,
+// and CommonJS require calls. Only named static imports are autofixed, and only when every
+// specifier in the statement is unambiguous.
 export const noRootBarrelImport = {
     meta: {
         type: 'suggestion',
+        fixable: 'code',
         docs: {
-            description: 'Disallow importing from the @cratis/components root barrel; use a subpath export.',
+            description:
+                'Disallow importing a component namespace from the @cratis/components root barrel; use a subpath export. Approved setup symbols (e.g. CratisComponentsProvider) remain allowed at the root.',
             recommended: true,
             url: 'https://github.com/Cratis/Components/blob/main/ESLint/README.md',
         },
-        schema: [{
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-                allow: { type: 'array', items: { type: 'string' } },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    packageName: { type: 'string' },
+                    allow: { type: 'array', items: { type: 'string' } },
+                },
+                additionalProperties: false,
             },
-            additionalProperties: false,
-        }],
+        ],
         messages: {
-            useSubpath: "Import from a '{{packageName}}' subpath (e.g. '{{packageName}}/CommandDialog'), not the package root barrel.",
+            useNamespaceSubpath:
+                "Import '{{name}}' from '{{packageName}}/{{subpath}}' as a namespace instead of the package root barrel: import * as {{name}} from '{{packageName}}/{{subpath}}'.",
+            useNamespaceSubpathExport:
+                "Re-export '{{name}}' from '{{packageName}}/{{subpath}}' instead of the package root barrel: export * as {{name}} from '{{packageName}}/{{subpath}}'. This is not autofixed — verify downstream default-export expectations.",
+            removedCompatibilitySymbol:
+                "'{{name}}' was a Components 3 PrimeReact compatibility export and has no Components 4 subpath. Migrate renderer slots to typed Cratis parts and remove this import manually.",
+            removedCompatibilitySymbolExport:
+                "'{{name}}' was a Components 3 PrimeReact compatibility export and has no Components 4 subpath. Migrate renderer slots to typed Cratis parts and remove this re-export manually.",
+            unknownSymbol:
+                "'{{name}}' is not a recognized '{{packageName}}' root export (neither an approved setup symbol nor a known namespace). Import it from its specific subpath instead of the package root.",
+            unknownSymbolExport:
+                "'{{name}}' is not a recognized '{{packageName}}' root export (neither an approved setup symbol nor a known namespace). Re-export it from its specific subpath instead of the package root.",
+            ambiguousImport:
+                "This import of '{{packageName}}' cannot be safely auto-migrated off the root barrel — move each symbol to its subpath import manually. See ESLint/README.md.",
+            ambiguousExport:
+                "This wildcard re-export of '{{packageName}}' cannot be safely auto-migrated off the root barrel — replace it with explicit subpath re-exports.",
         },
     },
     create(context) {
         const options = { ...DEFAULTS, ...(context.options[0] ?? {}) };
+        const packageName = options.packageName;
         const allow = new Set(options.allow);
 
-        const check = node => {
-            const source = node.source;
-            if (!source || typeof source.value !== 'string') return;
-            if (source.value === options.packageName && !allow.has(source.value)) {
-                context.report({ node: source, messageId: 'useSubpath', data: { packageName: options.packageName } });
-            }
-        };
+        const isRootSpecifier = (source) =>
+            !!source &&
+            typeof source.value === 'string' &&
+            source.value === packageName &&
+            !allow.has(source.value);
 
         return {
-            ImportDeclaration: check,
-            ExportNamedDeclaration: check,
-            ExportAllDeclaration: check,
+            ImportDeclaration(node) {
+                if (!isRootSpecifier(node.source)) return;
+                checkImport(context, node, packageName);
+            },
+            TSImportEqualsDeclaration(node) {
+                const reference = node.moduleReference;
+                if (
+                    reference?.type !== 'TSExternalModuleReference' ||
+                    !isRootSpecifier(reference.expression)
+                )
+                    return;
+                context.report({
+                    node: reference.expression,
+                    messageId: 'ambiguousImport',
+                    data: { packageName },
+                });
+            },
+            ImportExpression(node) {
+                if (!isRootSpecifier(node.source)) return;
+                context.report({
+                    node: node.source,
+                    messageId: 'ambiguousImport',
+                    data: { packageName },
+                });
+            },
+            CallExpression(node) {
+                if (node.callee.type !== 'Identifier' || node.callee.name !== 'require')
+                    return;
+                const [argument] = node.arguments;
+                if (!argument || argument.type === 'SpreadElement') return;
+                if (!isRootSpecifier(argument)) return;
+                context.report({
+                    node: argument,
+                    messageId: 'ambiguousImport',
+                    data: { packageName },
+                });
+            },
+            ExportNamedDeclaration(node) {
+                if (!isRootSpecifier(node.source)) return;
+                checkNamedExport(context, node, packageName);
+            },
+            ExportAllDeclaration(node) {
+                if (!isRootSpecifier(node.source)) return;
+                context.report({
+                    node: node.source,
+                    messageId: 'ambiguousExport',
+                    data: { packageName },
+                });
+            },
         };
     },
 };
 
+function checkImport(context, node, packageName) {
+    // No specifiers at all: `import '@cratis/components';` — nothing to infer a subpath
+    // from.
+    if (node.specifiers.length === 0) {
+        context.report({
+            node: node.source,
+            messageId: 'ambiguousImport',
+            data: { packageName },
+        });
+        return;
+    }
+
+    // `import Default from '...'` and/or `import * as Namespace from '...'`.
+    const hasDefault = node.specifiers.some((s) => s.type === 'ImportDefaultSpecifier');
+    const hasNamespace = node.specifiers.some(
+        (s) => s.type === 'ImportNamespaceSpecifier',
+    );
+    if (hasDefault || hasNamespace) {
+        context.report({
+            node: node.source,
+            messageId: 'ambiguousImport',
+            data: { packageName },
+        });
+        return;
+    }
+
+    const named = node.specifiers.filter((s) => s.type === 'ImportSpecifier');
+    const kept = [];
+    const namespaced = [];
+    let hasUnknown = false;
+
+    for (const specifier of named) {
+        const importedName = specifier.imported.name ?? specifier.imported.value;
+
+        if (approvedRootSymbols.has(importedName)) {
+            kept.push(specifier);
+            continue;
+        }
+        if (Object.hasOwn(namespaceSubpaths, importedName)) {
+            namespaced.push({ specifier, subpath: namespaceSubpaths[importedName] });
+            continue;
+        }
+        if (removedRootSymbols.has(importedName)) {
+            hasUnknown = true;
+            context.report({
+                node: specifier,
+                messageId: 'removedCompatibilitySymbol',
+                data: { name: importedName },
+            });
+            continue;
+        }
+
+        hasUnknown = true;
+        context.report({
+            node: specifier,
+            messageId: 'unknownSymbol',
+            data: { name: importedName, packageName },
+        });
+    }
+
+    if (namespaced.length === 0) return; // nothing to move (all approved, or all unknown-and-already-reported).
+
+    // Never guess: an unrecognized specifier means no autofix for the whole statement,
+    // even for the specifiers this rule does recognize.
+    const fix = hasUnknown
+        ? undefined
+        : (fixer) => [
+              fixer.replaceText(
+                  node,
+                  buildReplacementText({
+                      packageName,
+                      declTypeOnly: node.importKind === 'type',
+                      kept,
+                      namespaced,
+                  }),
+              ),
+          ];
+
+    for (const { specifier, subpath } of namespaced) {
+        const importedName = specifier.imported.name ?? specifier.imported.value;
+        context.report({
+            node: specifier,
+            messageId: 'useNamespaceSubpath',
+            data: { name: importedName, packageName, subpath },
+            fix,
+        });
+    }
+}
+
+function checkNamedExport(context, node, packageName) {
+    if (!node.specifiers || node.specifiers.length === 0) {
+        // `export {} from '@cratis/components';` — nothing to report.
+        return;
+    }
+
+    for (const specifier of node.specifiers) {
+        const localNode = specifier.local ?? specifier;
+        const exportedName = localNode.name ?? localNode.value;
+
+        if (approvedRootSymbols.has(exportedName)) continue;
+        if (Object.hasOwn(namespaceSubpaths, exportedName)) {
+            context.report({
+                node: specifier,
+                messageId: 'useNamespaceSubpathExport',
+                data: {
+                    name: exportedName,
+                    packageName,
+                    subpath: namespaceSubpaths[exportedName],
+                },
+            });
+            continue;
+        }
+        if (removedRootSymbols.has(exportedName)) {
+            context.report({
+                node: specifier,
+                messageId: 'removedCompatibilitySymbolExport',
+                data: { name: exportedName },
+            });
+            continue;
+        }
+
+        context.report({
+            node: specifier,
+            messageId: 'unknownSymbolExport',
+            data: { name: exportedName, packageName },
+        });
+    }
+}
+
+function specifierText(specifier, prefix = '') {
+    const importedName = specifier.imported.name ?? specifier.imported.value;
+    const localName = specifier.local.name;
+    const typeOnly = specifier.importKind === 'type';
+    const alias = localName === importedName ? '' : ` as ${localName}`;
+    return `${prefix}${typeOnly ? 'type ' : ''}${importedName}${alias}`;
+}
+
+function buildReplacementText({ packageName, declTypeOnly, kept, namespaced }) {
+    const lines = [];
+
+    if (kept.length > 0) {
+        const specifiers = kept.map((specifier) => specifierText(specifier)).join(', ');
+        lines.push(
+            `import ${declTypeOnly ? 'type ' : ''}{ ${specifiers} } from '${packageName}';`,
+        );
+    }
+
+    for (const { specifier, subpath } of namespaced) {
+        const localName = specifier.local.name;
+        const typeOnly = declTypeOnly || specifier.importKind === 'type';
+        lines.push(
+            `import ${typeOnly ? 'type ' : ''}* as ${localName} from '${packageName}/${subpath}';`,
+        );
+    }
+
+    return lines.join('\n');
+}
+
 export default noRootBarrelImport;

package/lib/onbeforeexecuteMustReturn.js

@@ -3,7 +3,11 @@
 // 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') {
+    if (
+        node.type === 'FunctionDeclaration' ||
+        node.type === 'FunctionExpression' ||
+        node.type === 'ArrowFunctionExpression'
+    ) {
         return;
     }
     if (node.type === 'ReturnStatement') {
@@ -35,22 +39,28 @@ const isOnBeforeExecuteCallback = (node) => {
     const parent = node.parent;
     if (!parent) return false;
 
-    if (parent.type === 'JSXExpressionContainer' &&
+    if (
+        parent.type === 'JSXExpressionContainer' &&
         parent.parent?.type === 'JSXAttribute' &&
-        parent.parent.name?.name === 'onBeforeExecute') {
+        parent.parent.name?.name === 'onBeforeExecute'
+    ) {
         return true;
     }
 
-    if ((parent.type === 'Property' || parent.type === 'PropertyDefinition') &&
+    if (
+        (parent.type === 'Property' || parent.type === 'PropertyDefinition') &&
         parent.value === node &&
-        keyNameOf(parent.key) === 'onBeforeExecute') {
+        keyNameOf(parent.key) === 'onBeforeExecute'
+    ) {
         return true;
     }
 
-    if (parent.type === 'VariableDeclarator' &&
+    if (
+        parent.type === 'VariableDeclarator' &&
         parent.init === node &&
         parent.id?.type === 'Identifier' &&
-        parent.id.name === 'onBeforeExecute') {
+        parent.id.name === 'onBeforeExecute'
+    ) {
         return true;
     }
 
@@ -58,30 +68,40 @@ const isOnBeforeExecuteCallback = (node) => {
 };
 
 // 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.
+// transformer, not a side-effect hook. A runtime guard (`applyBeforeExecute`) prevents a
+// missing return from executing with `undefined`: it falls back to the current object and logs
+// a warning. In-place mutations may remain because the callback received that same object, but
+// a replacement object is discarded and the callback still violates its contract. This lint
+// backstop keeps JavaScript and loosely typed call sites from relying on that fallback. 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.',
+            description:
+                'Require an onBeforeExecute callback to return the command values; on a missing return the runtime falls back to the current object and warns, so replacement values are discarded.',
             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).',
+            missingReturn:
+                'onBeforeExecute is a transformer and must return the command values. This callback can complete without returning, so the runtime falls back to the current object and logs a warning; any replacement value is discarded. Return the values (mutated or not).',
+            emptyReturn:
+                'onBeforeExecute must return the command values, not `return;`. The runtime falls back to the current object and logs a warning; any replacement value is discarded. 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;
+            if (
+                node.type === 'ArrowFunctionExpression' &&
+                node.body.type !== 'BlockStatement'
+            )
+                return;
 
             const returns = [];
             collectOwnReturns(node.body, returns);

package/lib/rootNamespaceMap.js

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Single source of truth for `no-root-barrel-import`'s namespace-aware behavior: every
+ * component namespace removed from the Components 3 root, and the small setup surface
+ * that remains supported at the Components 4 root.
+ *
+ * Mirrors `Source/index.ts` and the `exports` map in `Source/package.json`. When a
+ * namespace subpath is added, renamed, or removed there, update `namespaceSubpaths` here
+ * (and the matching copy in `Migrator/lib/namespaceMap.js`) in the same change. Neither
+ * file imports the other: this plugin and the codemods package ship and publish
+ * independently, so the map is intentionally duplicated rather than shared across a
+ * workspace boundary.
+ */
+
+/**
+ * Every retained namespace removed from the Components 3 root, mapped to the Components 4
+ * subpath it belongs to: importing `Canvas` from the root should instead be
+ * `import * as Canvas from '@cratis/components/Canvas'`. `Types` is the one case where the
+ * namespace name and its subpath differ in casing (`./types`, lowercase).
+ */
+export const namespaceSubpaths = {
+    Canvas: 'Canvas',
+    Chat: 'Chat',
+    CommandDialog: 'CommandDialog',
+    // The former root CommandStepper namespace aliased the entire CommandDialog module.
+    // Preserve that module identity; the narrower ./CommandStepper subpath does not.
+    CommandStepper: 'CommandDialog',
+    CommandForm: 'CommandForm',
+    Common: 'Common',
+    DataPage: 'DataPage',
+    DataTables: 'DataTables',
+    Dialogs: 'Dialogs',
+    Display: 'Display',
+    Dropdown: 'Dropdown',
+    Filter: 'Filter',
+    Notifications: 'Notifications',
+    ObjectContentEditor: 'ObjectContentEditor',
+    ObjectNavigationalBar: 'ObjectNavigationalBar',
+    PivotViewer: 'PivotViewer',
+    SchemaEditor: 'SchemaEditor',
+    TimeMachine: 'TimeMachine',
+    Toolbar: 'Toolbar',
+    Types: 'types',
+};
+
+/** Components 3 renderer-compatibility exports removed without a Components 4 subpath. */
+export const removedRootSymbols = new Set([
+    'Compatibility',
+    'assertPrimeReact11PassThroughCompatibility',
+    'components3PrimeReact11PassThroughContract',
+    'primeReact11PassThroughSentinelAttribute',
+    'primeReact11PassThroughSentinelPreset',
+    'PrimeReact11PassThroughComponent',
+]);
+
+/**
+ * The primary setup surface `Source/index.ts` re-exports directly from the root so a
+ * consumer that only wants provider setup does not need to know about the `Common`
+ * subpath. Importing one of these from the package root is allowed.
+ */
+export const approvedRootSymbols = new Set([
+    'CratisComponentsProvider',
+    'useCratisComponentsConfig',
+    'cratisDefaults',
+    'mergeCratisComponentsConfig',
+    'CratisComponentsConfig',
+    'CratisComponentsProviderProps',
+    'CratisComponentsMessages',
+    'CratisPaginatorMessages',
+    'CratisDatePickerMessages',
+    'CratisDropdownMessages',
+    'CratisDialogMessages',
+    'CratisStepperMessages',
+    'CratisNotificationsMessages',
+    'CratisDataTableMessages',
+    'CratisColumnFilterMessages',
+]);

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@cratis/eslint-plugin-components",
-    "version": "3.6.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.",
+    "version": "4.1.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, 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",
     "type": "module",
@@ -22,7 +22,8 @@
     "files": [
         "index.js",
         "lib",
-        "README.md"
+        "README.md",
+        "LICENSE"
     ],
     "exports": {
         "./package.json": "./package.json",
@@ -30,9 +31,10 @@
     },
     "scripts": {
         "test": "yarn g:test",
+        "verify-package": "node ./test/verify-packed-package.mjs",
         "ci": "yarn g:test"
     },
     "peerDependencies": {
         "eslint": ">=9"
     }
-}
+}