chore: add eslint rule no-property-overload to disallow property shadowing in interfaces/classes

Author: MattDevy

specification/eslint.config.js

@@ -95,6 +95,7 @@ export default defineConfig({
         }
       }
     ],
-    'es-spec-validator/no-all-string-literal-unions': 'error'
+    'es-spec-validator/no-all-string-literal-unions': 'error',
+    'es-spec-validator/no-property-overload': 'error'
   }
 })

validator/README.md

@@ -17,7 +17,8 @@ It is configured [in the specification directory](../specification/eslint.config
 | `no-inline-unions`                    | Inline union types (e.g., `field: A \| B`) are not allowed in properties/fields. Define a named type alias instead to improve code generation for statically-typed languages.              |
 | `prefer-tagged-variants`              | Union of class types should use tagged variants (`@variants internal` or `@variants container`) instead of inline unions for better deserialization support in statically-typed languages. |
 | `no-duplicate-type-names`             | All types must be unique across class and enum definitions.                                                                                                                                |
-| `no-all-string-literal-unions         | Unions consisting entirely of string literals (e.g., `"green" \| "yellow" \| "red"`) are not allowed, use enums instead.                                                                   |                                                                                                                         |
+| `no-all-string-literal-unions`        | Unions consisting entirely of string literals (e.g., `"green" \| "yellow" \| "red"`) are not allowed, use enums instead.                                                                   |
+| `no-property-overload`                | Properties that shadow or overload properties from a base interface or class are not allowed. All property names must be unique across the inheritance chain.                              |                                                                                                                         |
 
 ## Usage
 

validator/eslint-plugin-es-spec.js

@@ -27,6 +27,7 @@ import noInlineUnions from './rules/no-inline-unions.js'
 import preferTaggedVariants from './rules/prefer-tagged-variants.js'
 import noDuplicateTypeNames from './rules/no-duplicate-type-names.js'
 import noAllStringLiteralUnions from './rules/no-all-string-literal-unions.js'
+import noPropertyOverload from './rules/no-property-overload.js'
 
 export default {
   rules: {
@@ -40,6 +41,7 @@ export default {
     'no-inline-unions': noInlineUnions,
     'prefer-tagged-variants': preferTaggedVariants,
     'no-duplicate-type-names': noDuplicateTypeNames,
-    'no-all-string-literal-unions': noAllStringLiteralUnions
+    'no-all-string-literal-unions': noAllStringLiteralUnions,
+    'no-property-overload': noPropertyOverload
   }
 }

validator/rules/no-property-overload.js

@@ -0,0 +1,116 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { ESLintUtils, TSESTree } from '@typescript-eslint/utils'
+
+const IMPLEMENTS_KEYWORD = 119;
+const EXTENDS_KEYWORD = 96;
+
+export const noPropertyOverload = ESLintUtils.RuleCreator.withoutDocs({
+    name: "no-property-overload",
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Disallow properties that shadow or overload properties from a base interface or class.",
+            requiresTypeChecking: true,
+        },
+        messages: {
+            propertyOverload: "Property '{{propertyName}}' on {{typeName}} '{{declarationName}}' overloads a property from a base type."
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+
+    create(context) {
+        const services = ESLintUtils.getParserServices(context);
+        if (!services.program) {
+            return {};
+        }
+
+        const typeChecker = services.program.getTypeChecker();
+        const esTreeNodeToTSNodeMap = services.esTreeNodeToTSNodeMap;
+
+        const getPropertyName = (node) => node.name ?? node.value ?? null;
+
+        function collectAllProperties(type, inheritedPropertyNames, visited = new Set()) {
+            if (visited.has(type)) return;
+            visited.add(type);
+
+            type.getProperties().forEach(prop => inheritedPropertyNames.add(prop.name));
+
+            type.symbol?.declarations?.forEach(declaration => {
+                declaration.heritageClauses?.forEach(clause => {
+                    if (clause.token === IMPLEMENTS_KEYWORD || clause.token === EXTENDS_KEYWORD) {
+                        clause.types.forEach(typeNode => {
+                            const relatedType = typeChecker.getTypeAtLocation(typeNode);
+                            collectAllProperties(relatedType, inheritedPropertyNames, visited);
+                        });
+                    }
+                });
+            });
+
+            (type.getBaseTypes() || []).forEach(baseType => {
+                collectAllProperties(baseType, inheritedPropertyNames, visited);
+            });
+        }
+
+        return {
+            'TSInterfaceDeclaration, ClassDeclaration'(node) {
+                const isInterface = node.type === 'TSInterfaceDeclaration';
+                const hasInheritance = isInterface
+                    ? node.extends?.length > 0
+                    : node.superClass || node.implements?.length > 0;
+
+                if (!hasInheritance) return;
+
+                const tsNode = esTreeNodeToTSNodeMap.get(node);
+                const currentType = typeChecker.getTypeAtLocation(tsNode);
+                const baseTypes = currentType.getBaseTypes() || [];
+
+                const inheritedPropertyNames = new Set();
+                baseTypes.forEach(baseType => {
+                    collectAllProperties(baseType, inheritedPropertyNames, new Set());
+                });
+
+                const typeName = isInterface ? 'interface' : 'class';
+
+                node.body.body.forEach(propNode => {
+                    if (propNode.type !== 'TSPropertySignature' && propNode.type !== 'PropertyDefinition') {
+                        return;
+                    }
+
+                    const localPropName = getPropertyName(propNode.key);
+                    if (!localPropName || !inheritedPropertyNames.has(localPropName)) return;
+
+                    context.report({
+                        node: propNode.key,
+                        messageId: "propertyOverload",
+                        data: {
+                            propertyName: localPropName,
+                            typeName,
+                            declarationName: node.id.name,
+                        },
+                    });
+                });
+            }
+        };
+    }
+});
+
+export default noPropertyOverload;