@cratis/eslint-plugin-arc 0.0.1

package/README.md

@@ -0,0 +1,42 @@
+# @cratis/eslint-plugin-arc
+
+ESLint rules for projects that consume Cratis Arc. Compose these on top of the Cratis
+base config, [`@cratis/eslint-config`](https://www.npmjs.com/package/@cratis/eslint-config).
+
+| Rule / processor | What it does |
+|---|---|
+| `skip-generated-proxies` (processor) | Skips Arc-generated proxy files wholesale. They carry a `// @generated by Cratis` header (and a `**DO NOT EDIT**` banner), cannot be edited, and are regenerated by the build — so any finding on them is un-actionable. Keyed on the header because proxies sit intermixed with hand-written `.ts`. |
+| `no-hooks-in-view-model` | Disallows React hook calls inside MVVM view models (classes named `*ViewModel`). A view model must be a plain, React-free class; inject Cratis abstractions instead of calling hooks. |
+
+## Install
+
+```sh
+yarn add -D @cratis/eslint-plugin-arc @cratis/eslint-config eslint
+```
+
+## Use
+
+```js
+// eslint.config.mjs
+import cratis from '@cratis/eslint-config';
+import arc from '@cratis/eslint-plugin-arc';
+
+export default [
+    ...cratis.configs.consumer,
+    ...arc.configs.recommended,
+    // …your project rules
+];
+```
+
+### `no-hooks-in-view-model` options
+
+```js
+'@cratis/arc/no-hooks-in-view-model': ['error', {
+    classSuffix: 'ViewModel',          // class-name suffix that marks a view model
+    hookPattern: '^use[A-Z]',          // bare-identifier calls treated as hooks
+    additionalHooks: ['injectQuery'],  // extra call names to forbid
+}]
+```
+
+Only bare-identifier calls (`useState(...)`) are flagged — member calls like
+`this.useDefaults()` are not, so view-model methods that merely start with `use` are safe.

package/index.js

@@ -0,0 +1,43 @@
+import { createRequire } from 'node:module';
+import { noHooksInViewModel } from './lib/noHooksInViewModel.js';
+import { isGeneratedProxy, skipGeneratedProxies } from './lib/skipGeneratedProxies.js';
+
+const { version } = createRequire(import.meta.url)('./package.json');
+
+// A single flat-config plugin object — meta + rules + processors + self-referencing
+// configs — per the ESLint flat-config plugin convention. The default export IS the
+// plugin, so consumers get `arc.meta`, `arc.rules`, `arc.processors`, and `arc.configs`
+// directly. Composes on top of @cratis/eslint-config.
+const plugin = {
+    meta: { name: '@cratis/eslint-plugin-arc', version },
+    rules: { 'no-hooks-in-view-model': noHooksInViewModel },
+    processors: { 'skip-generated-proxies': skipGeneratedProxies },
+    configs: {},
+};
+
+// configs reference the plugin itself, so they are assigned after it exists.
+//
+//   import cratis from '@cratis/eslint-config';
+//   import arc from '@cratis/eslint-plugin-arc';
+//   export default [...cratis.configs.consumer, ...arc.configs.recommended];
+Object.assign(plugin.configs, {
+    recommended: [
+        {
+            name: '@cratis/arc/skip-generated-proxies',
+            files: ['**/*.ts'],
+            processor: plugin.processors['skip-generated-proxies'],
+        },
+        {
+            name: '@cratis/arc/recommended',
+            files: ['**/*.ts', '**/*.tsx'],
+            plugins: { '@cratis/arc': plugin },
+            rules: {
+                '@cratis/arc/no-hooks-in-view-model': 'error',
+            },
+        },
+    ],
+});
+
+export default plugin;
+export const { configs, rules, processors, meta } = plugin;
+export { noHooksInViewModel, skipGeneratedProxies, isGeneratedProxy };

package/lib/noHooksInViewModel.js

@@ -0,0 +1,70 @@
+const DEFAULT_HOOK_PATTERN = /^use[A-Z]/;
+
+// Flags React hook calls made inside an MVVM view model. In Cratis MVVM a view model is
+// a plain, React-free class — constructed and unit-tested without React — and everything
+// it needs from the React world (identity, navigation, query/command hooks) is injected
+// as a Cratis abstraction, never obtained by calling a hook. A hook called from a class
+// named `*ViewModel` is therefore always a mistake, and one that is otherwise invisible
+// until the component misbehaves at runtime.
+//
+// Only bare-identifier calls (`useState(...)`) are flagged, never member calls
+// (`this.useDefaults()`, `service.useCache()`), so a view-model method that merely starts
+// with `use` is not a false positive. Scope is the nearest enclosing class, so a hook in
+// a non-view-model class nested inside a view model is left alone.
+export const noHooksInViewModel = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow React hook calls inside MVVM view models (classes named *ViewModel).',
+            recommended: true,
+            url: 'https://github.com/Cratis/Arc/blob/main/Source/JavaScript/Arc.ESLint/README.md',
+        },
+        schema: [{
+            type: 'object',
+            properties: {
+                classSuffix: { type: 'string' },
+                hookPattern: { type: 'string' },
+                additionalHooks: { type: 'array', items: { type: 'string' } },
+            },
+            additionalProperties: false,
+        }],
+        messages: {
+            noHook: "Do not call the React hook '{{hook}}' inside view model '{{viewModel}}'. A view model must be a plain, React-free class — inject the Cratis abstraction instead of calling a hook.",
+        },
+    },
+    create(context) {
+        const options = context.options[0] ?? {};
+        const classSuffix = options.classSuffix ?? 'ViewModel';
+        const hookPattern = options.hookPattern ? new RegExp(options.hookPattern) : DEFAULT_HOOK_PATTERN;
+        const additionalHooks = new Set(options.additionalHooks ?? []);
+
+        // Stack of enclosing classes; each entry is the view-model name, or null when the
+        // class is not a view model. The top of the stack is the nearest enclosing class.
+        const enclosingClasses = [];
+
+        const enterClass = node => {
+            const name = node.id && node.id.name;
+            enclosingClasses.push(name && name.endsWith(classSuffix) ? name : null);
+        };
+        const exitClass = () => enclosingClasses.pop();
+        const nearestViewModel = () => (enclosingClasses.length ? enclosingClasses[enclosingClasses.length - 1] : null);
+
+        return {
+            ClassDeclaration: enterClass,
+            'ClassDeclaration:exit': exitClass,
+            ClassExpression: enterClass,
+            'ClassExpression:exit': exitClass,
+            CallExpression(node) {
+                const viewModel = nearestViewModel();
+                if (!viewModel) return;
+                if (node.callee.type !== 'Identifier') return;
+                const hook = node.callee.name;
+                if (hookPattern.test(hook) || additionalHooks.has(hook)) {
+                    context.report({ node, messageId: 'noHook', data: { hook, viewModel } });
+                }
+            },
+        };
+    },
+};
+
+export default noHooksInViewModel;

package/lib/skipGeneratedProxies.js

@@ -0,0 +1,38 @@
+// An ESLint flat-config processor that skips Cratis-generated proxy files wholesale.
+//
+// Arc's ProxyGenerator emits a `// @generated by Cratis …` line as line 1 (see
+// GeneratedFileMetadata.cs) followed by a `**DO NOT EDIT** - This file is an
+// automatically generated file.` banner (the Handlebars templates). These files cannot
+// be edited — they are regenerated by `dotnet build -c Release` — so every lint finding
+// on them is un-actionable, and an autofix would rewrite a file the next build reverts.
+//
+// Generated `.ts` proxies are co-located with hand-written `.ts` (view models, helpers)
+// with no path or naming distinction, so the header is the only reliable signal — hence
+// a content-sniffing processor rather than an `ignores` glob. `preprocess` returns `[]`
+// (no lintable blocks) for a generated file and the file unchanged for everything else.
+// The pass-through preserves the original filename, so import resolution is unaffected,
+// and `supportsAutofix` keeps `--fix` working on the hand-written files that flow through.
+
+const GENERATED_HEADER = '// @generated by Cratis';
+const DO_NOT_EDIT_BANNER = '**DO NOT EDIT** - This file is an automatically generated file.';
+
+export const isGeneratedProxy = text => {
+    if (typeof text !== 'string') return false;
+    if (text.startsWith(GENERATED_HEADER)) return true;
+    // Fallback for any generator variant that omits the @generated line: the DO NOT EDIT
+    // banner the templates emit within the first handful of lines.
+    return text.split('\n', 4).join('\n').includes(DO_NOT_EDIT_BANNER);
+};
+
+export const skipGeneratedProxies = {
+    meta: { name: '@cratis/arc/skip-generated-proxies' },
+    preprocess(text) {
+        return isGeneratedProxy(text) ? [] : [text];
+    },
+    postprocess(messages) {
+        return messages.flat();
+    },
+    supportsAutofix: true,
+};
+
+export default skipGeneratedProxies;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@cratis/eslint-plugin-arc",
+  "version": "0.0.1",
+  "description": "Cratis Arc ESLint rules: skip generated proxies and keep MVVM view models React-free. Compose on top of @cratis/eslint-config.",
+  "author": "Cratis",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cratis/Arc.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "cratis",
+    "arc",
+    "mvvm"
+  ],
+  "files": [
+    "index.js",
+    "lib",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./index.js"
+  },
+  "scripts": {
+    "test": "yarn g:test",
+    "ci": "yarn g:test"
+  },
+  "peerDependencies": {
+    "eslint": ">=9"
+  }
+}