@ethlete/eslint-plugin 1.0.0-next.18 → 1.0.0-next.20

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.0.0-next.20
+
+### Patch Changes
+
+- [`085c95e`](https://github.com/ethlete-io/ethdk/commit/085c95ebe1ecb8489b00b042066997a7a9dc8e5e) Thanks [@TomTomB](https://github.com/TomTomB)! - `require-form-submit` accepts `[etForm]` and `[formRoot]` as a form's submit handling.
+
+- [`4350d8e`](https://github.com/ethlete-io/ethdk/commit/4350d8e1eca00447ba130ec5a0ce43a64cfc4496) Thanks [@TomTomB](https://github.com/TomTomB)! - `no-trivial-wrapper-method` no longer flags `focus`, `blur` or `reset` on a component or directive - Angular resolves those by name on the instance.
+
+## 1.0.0-next.19
+
+### Minor Changes
+
+- [#3055](https://github.com/ethlete-io/ethdk/pull/3055) [`2fcb8e3`](https://github.com/ethlete-io/ethdk/commit/2fcb8e3799169956571534b75fdc152acc983877) Thanks [@github-actions](https://github.com/apps/github-actions)! - Add `require-form-submit` (a form handles its own submission, a submit control reaches a form) plus the opt-in `no-cdk-import` and `no-legacy-query-import`, which name each legacy symbol's successor in the message.
+
 ## 1.0.0-next.18
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/eslint-plugin",
-  "version": "1.0.0-next.18",
+  "version": "1.0.0-next.20",
   "license": "MIT",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/configs/recommended.js

@@ -422,6 +422,8 @@ const recommendedTemplate = {
     // (warn + suggestion-only: the rewrite is only safe when the input has a booleanAttribute transform,
     // which a template rule cannot verify)
     'ethlete/prefer-static-boolean-properties': 'warn',
+    // A form must handle its own submission, and a type="submit" control must reach a form
+    'ethlete/require-form-submit': 'error',
   },
 };
 

package/src/index.js

@@ -55,6 +55,9 @@ const preferPresentTenseOutput = require('./rules/prefer-present-tense-output');
 const preferStaticBooleanProperties = require('./rules/prefer-static-boolean-properties');
 const noImpureTopLevelProvider = require('./rules/no-impure-top-level-provider');
 const noLegacyPrepareWithoutInjector = require('./rules/no-legacy-prepare-without-injector');
+const requireFormSubmit = require('./rules/require-form-submit');
+const noCdkImport = require('./rules/no-cdk-import');
+const noLegacyQueryImport = require('./rules/no-legacy-query-import');
 const { recommendedTs, recommendedTemplate, recommendedSpec } = require('./configs/recommended');
 
 /** @type {import('eslint').ESLint.Plugin} */
@@ -118,6 +121,9 @@ const plugin = {
     'prefer-present-tense-output': preferPresentTenseOutput,
     'prefer-static-boolean-properties': preferStaticBooleanProperties,
     'no-impure-top-level-provider': noImpureTopLevelProvider,
+    'require-form-submit': requireFormSubmit,
+    'no-cdk-import': noCdkImport,
+    'no-legacy-query-import': noLegacyQueryImport,
   },
 };
 

package/src/rules/no-cdk-import.js

@@ -0,0 +1,154 @@
+// @ts-check
+'use strict';
+
+const { createRequire } = require('node:module');
+const path = require('node:path');
+const fs = require('node:fs');
+
+/**
+ * Disallows importing from `@ethlete/cdk`, the maintenance-mode predecessor of `@ethlete/components`,
+ * and names the successor of each imported symbol in the message.
+ *
+ *   import { ButtonComponent } from '@ethlete/cdk';
+ *   → `ButtonComponent` is legacy @ethlete/cdk. Use `ButtonComponent` from @ethlete/components
+ *     (https://…/components/button): a real button system - variant, size and color inputs plus
+ *     theming instead of CSS-only classes.
+ *
+ * The successors come from `migration-map.json`, which ships inside the `@ethlete/cdk` package - so
+ * the advice is always the installed version's, and this rule holds no copy of it. Without the map on
+ * disk the rule still reports, pointing at the migration guide instead of a specific symbol.
+ *
+ * Off by default: it is only useful once an app has decided to leave the cdk behind.
+ */
+
+const CDK_PACKAGE = '@ethlete/cdk';
+const MIGRATION_MAP = '@ethlete/cdk/migration-map.json';
+const DEFAULT_DOCS_BASE_URL = 'https://ethlete-sdk-docs.web.app';
+
+/** @type {Map<string, Record<string, { kind: string, to?: string, package?: string, docs?: string, note?: string }> | null>} */
+const mapCache = new Map();
+
+/**
+ * @param {string | undefined} mapPath
+ * @param {string} cwd
+ */
+const loadMigrationMap = (mapPath, cwd) => {
+  const cacheKey = mapPath ? path.resolve(cwd, mapPath) : MIGRATION_MAP;
+
+  if (mapCache.has(cacheKey)) return mapCache.get(cacheKey) ?? null;
+
+  let map;
+
+  try {
+    map = mapPath
+      ? JSON.parse(fs.readFileSync(cacheKey, 'utf8'))
+      : createRequire(path.join(cwd, 'noop.js'))(MIGRATION_MAP);
+  } catch {
+    map = null;
+  }
+
+  mapCache.set(cacheKey, map);
+
+  return map;
+};
+
+/** @param {any} specifier */
+const importedName = (specifier) => {
+  if (specifier.type !== 'ImportSpecifier') return null;
+
+  return specifier.imported.name ?? specifier.imported.value ?? null;
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noCdkImport = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow importing from the maintenance-mode @ethlete/cdk; name the @ethlete/components successor.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          /** Where to read the migration map from, when `@ethlete/cdk` is not resolvable from the linted project. */
+          migrationMapPath: { type: 'string' },
+          /** Base URL the migration map's doc paths are appended to. */
+          docsBaseUrl: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      successor: '`{{ name }}` is legacy {{ cdk }}. Use `{{ to }}` from {{ package }} instead ({{ docs }}).{{ note }}',
+      noSuccessor: '`{{ name }}` is legacy {{ cdk }} and has no successor{{ note }} - see {{ docs }}.',
+      unmapped: '`{{ name }}` is legacy {{ cdk }}. Move it to @ethlete/components - see {{ docs }}.',
+      module: 'Do not depend on the legacy {{ cdk }} - move to @ethlete/components, see {{ docs }}.',
+    },
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const docsBaseUrl = (options.docsBaseUrl ?? DEFAULT_DOCS_BASE_URL).replace(/\/$/, '');
+    const migrationDocs = `${docsBaseUrl}/cdk/migration`;
+    const map = loadMigrationMap(options.migrationMapPath, context.cwd);
+
+    /** @param {string} name */
+    const entryFor = (name) => map?.[name] ?? null;
+
+    return {
+      ImportDeclaration(node) {
+        const declaration = /** @type {any} */ (node);
+        const source = declaration.source.value;
+
+        if (typeof source !== 'string' || (source !== CDK_PACKAGE && !source.startsWith(`${CDK_PACKAGE}/`))) return;
+
+        const named = declaration.specifiers.filter(/** @param {any} s */ (s) => importedName(s));
+
+        if (!named.length) {
+          context.report({ node, messageId: 'module', data: { cdk: CDK_PACKAGE, docs: migrationDocs } });
+
+          return;
+        }
+
+        for (const specifier of named) {
+          const name = /** @type {string} */ (importedName(specifier));
+          const entry = entryFor(name);
+
+          if (!entry) {
+            context.report({
+              node: specifier,
+              messageId: 'unmapped',
+              data: { name, cdk: CDK_PACKAGE, docs: migrationDocs },
+            });
+
+            continue;
+          }
+
+          if (!entry.to) {
+            context.report({
+              node: specifier,
+              messageId: 'noSuccessor',
+              data: { name, cdk: CDK_PACKAGE, note: entry.note ? ` (${entry.note})` : '', docs: migrationDocs },
+            });
+
+            continue;
+          }
+
+          context.report({
+            node: specifier,
+            messageId: 'successor',
+            data: {
+              name,
+              cdk: CDK_PACKAGE,
+              to: entry.to,
+              package: entry.package ?? '@ethlete/components',
+              docs: entry.docs ? `${docsBaseUrl}${entry.docs}` : migrationDocs,
+              note: entry.note ? ` ${entry.note}.` : '',
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+module.exports = noCdkImport;

package/src/rules/no-legacy-query-import.js

@@ -0,0 +1,136 @@
+// @ts-check
+'use strict';
+
+/**
+ * Disallows importing the legacy (v2) query system from `@ethlete/query`, and names the current-system
+ * API in the message.
+ *
+ *   import { V2QueryClient, filterSuccess } from '@ethlete/query';
+ *   → `V2QueryClient` is the legacy (v2) query system. Use `createQueryClient` instead (…/query/queries).
+ *   → `filterSuccess` … Use `query.response()` instead - the query is already signals (…/query/queries).
+ *
+ * Two things are matched: every `V2`/`AnyV2`-prefixed export - the prefix the library gives the legacy
+ * system's half of a colliding name - and the legacy APIs that never collided, which carry their
+ * successor from the migration guide. `createLegacyQueryCreator` is deliberately **not** matched: it is
+ * the sanctioned interop seam a migration leans on until its call sites are converted.
+ *
+ * Off by default, and deliberately not type-aware: it names successors rather than repeating the
+ * `@deprecated` tag every legacy export already carries. For the whole deprecated surface (including
+ * the types this rule leaves alone), enable `@typescript-eslint/no-deprecated` alongside it.
+ */
+
+const QUERY_PACKAGE = '@ethlete/query';
+const DEFAULT_DOCS_BASE_URL = 'https://ethlete-sdk-docs.web.app';
+
+/**
+ * The legacy APIs whose names never collided with the current system, and what the migration guide
+ * (`/query/legacy#migrating-to-the-current-system`) maps each one to.
+ *
+ * @type {Record<string, { to: string, docs: string }>}
+ */
+const LEGACY_SYMBOLS = {
+  def: { to: 'the type parameter of a current creator - `createGetQuery(client)<TArgs>(route)`', docs: '/query/http' },
+  BasicAuthProvider: { to: 'no equivalent - the current system authenticates through `createBearerAuthProvider`', docs: '/query/auth' }, // prettier-ignore
+  CustomHeaderAuthProvider: { to: '`headers` on `createQueryClient`, which re-reads a function form per request', docs: '/query/queries#the-query-client' }, // prettier-ignore
+  EntityStore: { to: 'nothing directly - caching dedupes by request, and shared state derives from signals', docs: '/query/caching' }, // prettier-ignore
+  InfinityQuery: { to: '`createPagedQueryStack`', docs: '/query/stacks#paged-queries' },
+  InfinityQueryDirective: { to: '`createPagedQueryStack`', docs: '/query/stacks#paged-queries' },
+  InfinityQueryTriggerDirective: { to: '`createPagedQueryStack`', docs: '/query/stacks#paged-queries' },
+  createInfinityQueryConfig: { to: '`createPagedQueryStack`', docs: '/query/stacks#paged-queries' },
+  QueryDirective: { to: "the query's own signals, read directly in the template", docs: '/query/migrating-from-v2#templates-read-signals-not-directives' }, // prettier-ignore
+  filterSuccess: { to: '`query.response()`, or `query.response.asObservable()` where a stream is needed', docs: '/query/queries#the-query-object' }, // prettier-ignore
+  filterFailure: { to: '`query.error()`, or `query.error.asObservable()` where a stream is needed', docs: '/query/queries#the-query-object' }, // prettier-ignore
+  switchQueryState: { to: "the query's own signals - each one is an `ObservableSignal`", docs: '/query/queries#the-query-object' }, // prettier-ignore
+  takeUntilResponse: { to: "the query's own signals - each one is an `ObservableSignal`", docs: '/query/queries#the-query-object' }, // prettier-ignore
+  toQuerySignal: { to: 'the query object itself - it is already signals', docs: '/query/queries#the-query-object' },
+  queryStateSignal: { to: 'the query object itself - it is already signals', docs: '/query/queries#the-query-object' }, // prettier-ignore
+  queryStateResponseSignal: { to: '`query.response()`', docs: '/query/queries#the-query-object' },
+  queryStateErrorSignal: { to: '`query.error()`', docs: '/query/queries#the-query-object' },
+  queryStateLoadingSignal: { to: '`query.loading()`', docs: '/query/queries#the-query-object' },
+  validateWithV2Query: { to: '`validateWithQuery`', docs: '/query/errors#validating-against-the-server-as-the-user-types' }, // prettier-ignore
+  provideQueryClientForDevtools: { to: '`provideQueryDevtools()` from `@ethlete/query-devtools`, which registers every client at once', docs: '/query-devtools/' }, // prettier-ignore
+};
+
+/** The current-system counterparts of the names the legacy system had to give up its half of. */
+const V2_SUCCESSORS = {
+  V2QueryClient: { to: '`createQueryClient`', docs: '/query/queries#the-query-client' },
+  V2QueryClientConfig: { to: 'the config of `createQueryClient`', docs: '/query/queries#the-query-client' },
+  V2QueryCreator: { to: '`createGetQuery` and its siblings', docs: '/query/http' },
+  AnyV2QueryCreator: { to: '`createGetQuery` and its siblings', docs: '/query/http' },
+  V2BearerAuthProvider: { to: '`createBearerAuthProvider` plus the secure creator templates', docs: '/query/auth' },
+};
+
+/** @param {any} specifier */
+const importedName = (specifier) => {
+  if (specifier.type !== 'ImportSpecifier') return null;
+
+  return specifier.imported.name ?? specifier.imported.value ?? null;
+};
+
+/** @param {string} name */
+const isV2Symbol = (name) => /^(V2|AnyV2)[A-Z]/.test(name);
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noLegacyQueryImport = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow importing the legacy (v2) query system; name the current-system API instead.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          /** Base URL the guide paths in the messages are appended to. */
+          docsBaseUrl: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      successor: '`{{ name }}` is the legacy (v2) query system. Use {{ to }} instead ({{ docs }}).',
+      legacySystem:
+        '`{{ name }}` is the legacy (v2) query system. Migrate to the current one - see {{ docs }}, and run `nx g @ethlete/query:migrate-to-query-v3` for the mechanical parts.',
+    },
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const docsBaseUrl = (options.docsBaseUrl ?? DEFAULT_DOCS_BASE_URL).replace(/\/$/, '');
+
+    return {
+      ImportDeclaration(node) {
+        const declaration = /** @type {any} */ (node);
+
+        if (declaration.source.value !== QUERY_PACKAGE) return;
+
+        for (const specifier of declaration.specifiers) {
+          const name = importedName(specifier);
+
+          if (!name) continue;
+
+          const successor = V2_SUCCESSORS[name] ?? LEGACY_SYMBOLS[name];
+
+          if (successor) {
+            context.report({
+              node: specifier,
+              messageId: 'successor',
+              data: { name, to: successor.to, docs: `${docsBaseUrl}${successor.docs}` },
+            });
+
+            continue;
+          }
+
+          if (!isV2Symbol(name)) continue;
+
+          context.report({
+            node: specifier,
+            messageId: 'legacySystem',
+            data: { name, docs: `${docsBaseUrl}/query/migrating-from-v2` },
+          });
+        }
+      },
+    };
+  },
+};
+
+module.exports = noLegacyQueryImport;

package/src/rules/no-trivial-wrapper-method.js

@@ -16,14 +16,41 @@
  * GOOD:
  *   // Call this.value.set(val) directly at the call sites.
  *   // If the method wraps something non-trivially (transforms args, adds logic), it is fine.
+ *   // `focus`/`blur`/`reset` on a @Component/@Directive are exempt - see CONTRACT_METHOD_NAMES.
  */
 
+/**
+ * Imperative members Angular and the DOM look up **by name on the instance**. A component that
+ * wraps a control in a host directive has to re-expose them itself: signal forms resolves a custom
+ * control to the wrapper component, not to its host directives, so a `focus()` that only forwards
+ * is the whole contract - there is no call site to inline it into.
+ */
+const CONTRACT_METHOD_NAMES = new Set(['focus', 'blur', 'reset']);
+
 /**
  * Returns true when the param is a plain identifier (no default, no destructuring, no rest).
  * @param {import('@typescript-eslint/types').TSESTree.Parameter} param
  */
 const isSimpleParam = (param) => param.type === 'Identifier';
 
+/**
+ * Whether the class holding this method is an Angular component or directive.
+ * @param {import('eslint').Rule.Node} methodNode MethodDefinition node
+ */
+const isInAngularClass = (methodNode) => {
+  const classNode = methodNode.parent?.parent;
+  const decorators = classNode && 'decorators' in classNode ? classNode.decorators : null;
+
+  if (!decorators) return false;
+
+  return decorators.some((decorator) => {
+    const expression = decorator.expression;
+    const callee = expression.type === 'CallExpression' ? expression.callee : expression;
+
+    return callee.type === 'Identifier' && (callee.name === 'Component' || callee.name === 'Directive');
+  });
+};
+
 /**
  * Returns the single CallExpression in the method body when the method is a
  * trivial all-args-forwarding wrapper, or null otherwise.
@@ -97,6 +124,8 @@ const noTrivialWrapperMethod = {
         const methodName = node.key.type === 'Identifier' ? node.key.name : null;
         if (!methodName) return;
 
+        if (CONTRACT_METHOD_NAMES.has(methodName) && isInAngularClass(node)) return;
+
         const callee = callExpr.callee;
         const targetName =
           callee.type === 'MemberExpression'

package/src/rules/require-form-submit.js

@@ -0,0 +1,95 @@
+// @ts-check
+'use strict';
+
+/**
+ * Checks the two ends of the same wire: that a `<form>` handles its own submission, and that a
+ * submit control reaches a form at all.
+ *
+ *   <form (ngSubmit)="save()">          ✔
+ *   <form [etForm]="form">              ✔ signal forms - the directive submits the field tree
+ *   <form>                              ✘ pressing Enter in a field does nothing, or reloads the page
+ *
+ *   <form …><button type="submit">      ✔
+ *   <button type="submit" form="edit">  ✔ associated by id, outside the form's subtree
+ *   <button type="submit">              ✘ submits nothing
+ *
+ * A form declaring native submission (`action`, `ngNoForm`, `method="dialog"`) is left alone - it is
+ * handled by the platform rather than by a handler.
+ */
+
+/** @param {any} node @param {string} name */
+const attribute = (node, name) => node.attributes?.find(/** @param {any} a */ (a) => a.name === name);
+
+/** @param {any} node @param {string} name */
+const hasBinding = (node, name) =>
+  node.inputs?.some(/** @param {any} i */ (i) => i.name === name) ||
+  node.attributes?.some(/** @param {any} a */ (a) => a.name === name);
+
+/** @param {any} node */
+const handlesSubmit = (node) =>
+  node.outputs?.some(/** @param {any} o */ (o) => o.name === 'submit' || o.name === 'ngSubmit') ||
+  hasBinding(node, 'etForm') ||
+  hasBinding(node, 'formRoot');
+
+/** @param {any} node */
+const submitsNatively = (node) =>
+  hasBinding(node, 'action') || hasBinding(node, 'ngNoForm') || attribute(node, 'method')?.value === 'dialog';
+
+/** @param {any} node */
+const isSubmitControl = (node) =>
+  (node.name === 'button' || node.name === 'input') && attribute(node, 'type')?.value === 'submit';
+
+/** @type {import('eslint').Rule.RuleModule} */
+const requireFormSubmit = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require a `<form>` to handle its own submission, and a submit control to reach a form.',
+    },
+    schema: [],
+    messages: {
+      missingSubmitHandler:
+        'This `<form>` handles no submission - pressing Enter in a field either does nothing or reloads the page. Bind `[etForm]` (signal forms), `(ngSubmit)` (reactive forms) or `(submit)`, or use a plain element if this is not a form.',
+      submitOutsideForm:
+        'A `type="submit"` control outside a `<form>` submits nothing. Put it inside the form, or associate it with one by id: `form="the-form-id"`.',
+    },
+  },
+  create(context) {
+    const parserServices = /** @type {any} */ (context.sourceCode.parserServices);
+
+    if (!parserServices?.convertNodeSourceSpanToLoc) return {};
+
+    let formDepth = 0;
+
+    /** @param {any} node */
+    const report = (node, messageId) =>
+      context.report({
+        loc: parserServices.convertNodeSourceSpanToLoc(node.startSourceSpan ?? node.sourceSpan),
+        messageId,
+      });
+
+    return {
+      /** @param {any} node */
+      Element(node) {
+        if (node.name === 'form') {
+          formDepth++;
+
+          if (!handlesSubmit(node) && !submitsNatively(node)) report(node, 'missingSubmitHandler');
+
+          return;
+        }
+
+        if (formDepth > 0 || !isSubmitControl(node) || hasBinding(node, 'form')) return;
+
+        report(node, 'submitOutsideForm');
+      },
+
+      /** @param {any} node */
+      'Element:exit'(node) {
+        if (node.name === 'form') formDepth--;
+      },
+    };
+  },
+};
+
+module.exports = requireFormSubmit;