chore(internals): add new rules for class inheritance and aria attribute management

- Introduced `no-deep-class-inheritance` rule to limit class inheritance depth, ensuring better maintainability.
- Added `no-host-managed-aria-attributes` rule to prevent misuse of ARIA attributes that should be managed through ElementInternals.
- Implemented `no-single-consumer-internal-base` rule to disallow internal base classes with fewer than two consumers, promoting better design practices.
- Updated ESLint configurations to include the new rules and their respective error handling.

Signed-off-by: Cory Rylan <crylan@nvidia.com>

Author: coryrylan

projects/internals/eslint/src/configs/lit.js

@@ -16,6 +16,8 @@ import requireElementDefinitions from '../local/require-element-definitions.js';
 import requireTestCompleteness from '../local/require-test-completeness.js';
 import requireComposedEvents from '../local/require-composed-events.js';
 import noMissingBundleRegistration from '../local/no-missing-bundle-registration.js';
+import noHostManagedAriaAttributes from '../local/no-host-managed-aria-attributes.js';
+import noSingleConsumerInternalBase from '../local/no-single-consumer-internal-base.js';
 
 const source = ['src/**/*.ts', 'src/**/*.tsx', 'src/**/*.d.ts'];
 const tests = [
@@ -64,7 +66,9 @@ export const litConfig = [
           'require-element-definitions': requireElementDefinitions,
           'require-test-completeness': requireTestCompleteness,
           'require-composed-events': requireComposedEvents,
-          'no-missing-bundle-registration': noMissingBundleRegistration
+          'no-missing-bundle-registration': noMissingBundleRegistration,
+          'no-host-managed-aria-attributes': noHostManagedAriaAttributes,
+          'no-single-consumer-internal-base': noSingleConsumerInternalBase
         }
       }
     },
@@ -134,6 +138,8 @@ export const litConfig = [
       'local/require-internal-host': ['error'],
       'local/require-element-definitions': ['error'],
       'local/require-composed-events': ['error'],
+      'local/no-host-managed-aria-attributes': ['error'],
+      'local/no-single-consumer-internal-base': ['error'],
       'local/no-missing-bundle-registration': [
         'error',
         {

projects/internals/eslint/src/configs/typescript.js

@@ -3,6 +3,7 @@ import tseslint from 'typescript-eslint';
 import importPlugin from 'eslint-plugin-import';
 import jsdoc from 'eslint-plugin-jsdoc';
 import deadCode from '../local/dead-code.js';
+import noDeepClassInheritance from '../local/no-deep-class-inheritance.js';
 import exampleMetadata from '../local/example-metadata.js';
 import exampleNaming from '../local/example-naming.js';
 import exampleTemplateSize from '../local/example-template-size.js';
@@ -48,6 +49,7 @@ const config = {
     'local-typescript': {
       rules: {
         'no-dead-code': deadCode,
+        'no-deep-class-inheritance': noDeepClassInheritance,
         'example-metadata': exampleMetadata,
         'example-naming': exampleNaming,
         'example-template-size': exampleTemplateSize,
@@ -106,6 +108,10 @@ const config = {
     'jsdoc/check-tag-names': 'error',
     'jsdoc/informative-docs': 'error',
     'local-typescript/no-dead-code': ['warn'], // todo, this should be migrated to the internal playground template config
+    'local-typescript/no-deep-class-inheritance': [
+      'error',
+      { maxDepth: 2, allowedRoots: ['HTMLElement', 'LitElement', 'FormControlMixin', 'BaseButton'] }
+    ],
     'local-typescript/require-listener-cleanup': 'error',
     'local-typescript/require-observer-cleanup': 'error',
     'local-typescript/require-timer-cleanup': 'error',

projects/internals/eslint/src/local/no-deep-class-inheritance.js

@@ -0,0 +1,114 @@
+const DEFAULT_MAX_DEPTH = 2;
+const DEFAULT_ALLOWED_ROOTS = ['HTMLElement', 'LitElement'];
+
+/**
+ * ESLint rule that limits class inheritance depth. The rule counts superclass
+ * hops until it reaches a configured allowed root class so local wrappers around
+ * platform/framework bases stay possible without allowing hierarchy creep.
+ *
+ * @type {import('eslint').Rule.RuleModule}
+ */
+export default {
+  meta: {
+    type: 'problem',
+    name: 'no-deep-class-inheritance',
+    docs: {
+      description: 'Disallows class inheritance chains deeper than the configured maximum.',
+      category: 'Best Practice',
+      recommended: true
+    },
+    schema: [
+      {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          maxDepth: {
+            type: 'integer',
+            minimum: 1
+          },
+          allowedRoots: {
+            type: 'array',
+            items: { type: 'string' },
+            uniqueItems: true
+          }
+        }
+      }
+    ],
+    messages: {
+      'too-deep':
+        '`{{className}}` has inheritance depth {{depth}} (`{{chain}}`). Maximum allowed depth is {{maxDepth}}.'
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const allowedRoots = new Set(options.allowedRoots ?? DEFAULT_ALLOWED_ROOTS);
+
+    return {
+      ClassDeclaration(node) {
+        if (!node.superClass) {
+          return;
+        }
+
+        const services = context.sourceCode.parserServices;
+        if (!services?.program || !services.esTreeNodeToTSNodeMap) {
+          return;
+        }
+
+        const superClass = services.esTreeNodeToTSNodeMap.get(node.superClass);
+        const chain = getInheritanceChain(superClass, services.program.getTypeChecker(), allowedRoots);
+
+        if (chain.length <= maxDepth) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: 'too-deep',
+          data: {
+            className: node.id?.name ?? '<anonymous>',
+            depth: String(chain.length),
+            maxDepth: String(maxDepth),
+            chain: `${node.id?.name ?? '<anonymous>'} -> ${chain.join(' -> ')}`
+          }
+        });
+      }
+    };
+  }
+};
+
+function getInheritanceChain(superClass, checker, allowedRoots) {
+  const chain = [];
+  const visited = new Set();
+  let expression = superClass;
+
+  while (expression) {
+    const symbol = checker.getTypeAtLocation(expression).symbol;
+    const className = symbol?.getName() ?? expression.getText();
+
+    chain.push(className);
+
+    if (allowedRoots.has(className)) {
+      break;
+    }
+
+    const declaration = getClassDeclaration(symbol);
+    if (!declaration || visited.has(declaration)) {
+      break;
+    }
+
+    visited.add(declaration);
+    expression = getExtendsExpression(declaration);
+  }
+
+  return chain;
+}
+
+function getClassDeclaration(symbol) {
+  return symbol?.declarations?.find(declaration => Array.isArray(declaration.members)) ?? null;
+}
+
+function getExtendsExpression(classDeclaration) {
+  const heritageClause = classDeclaration.heritageClauses?.find(clause => clause.getText().startsWith('extends '));
+  return heritageClause?.types?.[0]?.expression ?? null;
+}

projects/internals/eslint/src/local/no-deep-class-inheritance.test.js

@@ -0,0 +1,137 @@
+import { beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { RuleTester } from 'eslint';
+import tseslint from 'typescript-eslint';
+import noDeepClassInheritance from './no-deep-class-inheritance.js';
+
+let tester;
+
+beforeEach(() => {
+  tester = new RuleTester({
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        projectService: { allowDefaultProject: ['*.ts'] },
+        tsconfigRootDir: import.meta.dirname
+      }
+    }
+  });
+});
+
+test('defines rule metadata', () => {
+  assert.equal(noDeepClassInheritance.meta.type, 'problem');
+  assert.equal(noDeepClassInheritance.meta.name, 'no-deep-class-inheritance');
+  assert.ok(noDeepClassInheritance.meta.messages['too-deep']);
+});
+
+test('valid: allows direct and depth-2 class inheritance', () => {
+  tester.run('no-deep-class-inheritance', noDeepClassInheritance, {
+    valid: [
+      {
+        filename: 'direct-lit.ts',
+        code: `
+          declare class LitElement {}
+
+          class Badge extends LitElement {}
+        `
+      },
+      {
+        filename: 'depth-two.ts',
+        code: `
+          declare class LitElement {}
+
+          class BaseButton extends LitElement {}
+          class SortButton extends BaseButton {}
+        `
+      },
+      {
+        filename: 'event-target-root.ts',
+        code: `
+          class VideoGroup extends EventTarget {}
+          class ManagedVideoGroup extends VideoGroup {}
+        `
+      }
+    ],
+    invalid: []
+  });
+});
+
+test('valid: supports custom maxDepth and allowedRoots options', () => {
+  tester.run('no-deep-class-inheritance', noDeepClassInheritance, {
+    valid: [
+      {
+        filename: 'custom-max-depth.ts',
+        options: [{ maxDepth: 3 }],
+        code: `
+          declare class LitElement {}
+
+          class BaseButton extends LitElement {}
+          class SortButton extends BaseButton {}
+          class ToolbarSortButton extends SortButton {}
+        `
+      },
+      {
+        filename: 'custom-root.ts',
+        options: [{ allowedRoots: ['BaseElement'] }],
+        code: `
+          class BaseElement {}
+          class Control extends BaseElement {}
+          class Color extends Control {}
+        `
+      }
+    ],
+    invalid: []
+  });
+});
+
+test('invalid: reports classes deeper than maxDepth', () => {
+  tester.run('no-deep-class-inheritance', noDeepClassInheritance, {
+    valid: [],
+    invalid: [
+      {
+        filename: 'too-deep.ts',
+        code: `
+          declare class LitElement {}
+
+          class BaseButton extends LitElement {}
+          class SortButton extends BaseButton {}
+          class ToolbarSortButton extends SortButton {}
+        `,
+        errors: [
+          {
+            messageId: 'too-deep',
+            data: {
+              className: 'ToolbarSortButton',
+              depth: '3',
+              maxDepth: '2',
+              chain: 'ToolbarSortButton -> SortButton -> BaseButton -> LitElement'
+            }
+          }
+        ]
+      },
+      {
+        filename: 'custom-max-depth-invalid.ts',
+        options: [{ maxDepth: 1, allowedRoots: ['BaseElement'] }],
+        code: `
+          class BaseElement {}
+
+          class Control extends BaseElement {}
+          class Radio extends Control {}
+        `,
+        errors: [
+          {
+            messageId: 'too-deep',
+            data: {
+              className: 'Radio',
+              depth: '2',
+              maxDepth: '1',
+              chain: 'Radio -> Control -> BaseElement'
+            }
+          }
+        ]
+      }
+    ]
+  });
+});

projects/internals/eslint/src/local/no-host-managed-aria-attributes.js

@@ -0,0 +1,86 @@
+const MANAGED_ATTRIBUTES = {
+  'aria-current': 'stateCurrent',
+  'aria-disabled': 'stateDisabled',
+  'aria-expanded': 'stateExpanded',
+  'aria-label': 'ElementInternals.ariaLabel',
+  'aria-pressed': 'statePressed',
+  'aria-selected': 'stateSelected',
+  role: 'ElementInternals.role'
+};
+
+/**
+ * Prevent setting host ARIA state attributes that should be managed through
+ * ElementInternals and the shared state/type controllers.
+ *
+ * @type {import('eslint').Rule.RuleModule}
+ */
+export default {
+  meta: {
+    type: 'problem',
+    name: 'no-host-managed-aria-attributes',
+    docs: {
+      description: 'Prevent host ARIA state attributes that should be managed with ElementInternals.',
+      category: 'Best Practice',
+      recommended: true
+    },
+    schema: [],
+    messages: {
+      'managed-attribute':
+        'Use {{controller}} instead of setting "{{attribute}}" on the custom element host with {{method}}().'
+    }
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isHostAttributeMutation(node)) {
+          return;
+        }
+
+        const attribute = getStaticString(node.arguments[0])?.toLowerCase();
+        const controller = MANAGED_ATTRIBUTES[attribute];
+
+        if (!controller) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: 'managed-attribute',
+          data: {
+            attribute,
+            controller,
+            method: node.callee.property.name
+          }
+        });
+      }
+    };
+  }
+};
+
+function isHostAttributeMutation(node) {
+  if (node.callee.type !== 'MemberExpression' || node.callee.computed) {
+    return false;
+  }
+
+  if (node.callee.object.type !== 'ThisExpression') {
+    return false;
+  }
+
+  return ['setAttribute', 'removeAttribute', 'toggleAttribute'].includes(node.callee.property.name);
+}
+
+function getStaticString(node) {
+  if (!node) {
+    return null;
+  }
+
+  if (node.type === 'Literal' && typeof node.value === 'string') {
+    return node.value;
+  }
+
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis[0]?.value.cooked ?? null;
+  }
+
+  return null;
+}