@echoes-of-order/eslint-config 1.121.0

package/rules/analyze-relation-usage.js

@@ -0,0 +1,687 @@
+/**
+ * @fileoverview ESLint rule to analyze relation usage through static code analysis
+ * @description Traces data flow from repository calls to DTO usage to identify missing relations
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const analyzeRelationUsageRule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Analyze data flow to identify potentially missing TypeORM relations",
+      category: "TypeORM",
+      recommended: true,
+    },
+    fixable: null,
+    schema: [
+      {
+        type: "object",
+        properties: {
+          traceMethods: {
+            type: "array",
+            items: { type: "string" },
+            description: "Method patterns to trace (e.g., '*ForDto', '*ToApi')",
+          },
+          dtoPatterns: {
+            type: "array",
+            items: { type: "string" },
+            description: "DTO class name patterns to analyze",
+          },
+          entityDirectory: {
+            type: "string",
+            description: "Path to entity directory for external entity analysis",
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      potentialMissingRelation: "Method '{{methodName}}' may need relation '{{relationName}}' - used in DTO '{{dtoName}}' but not loaded in repository call",
+      suggestRelationLoad: "Consider adding relations: [{{suggestedRelations}}] to repository call in '{{methodName}}'",
+      invalidRelation: "Relation '{{relationName}}' does not exist in Entity '{{entityName}}'. Available relations: [{{availableRelations}}]",
+      entityNotFound: "Entity '{{entityName}}' not found for relation validation",
+    },
+  },
+
+  create(context) {
+    const options = context.options[0] || {};
+    const traceMethods = options.traceMethods || ["*ForDto", "*ToApi", "getAll", "getBy*"];
+    const dtoPatterns = options.dtoPatterns || ["*Dto"];
+    const entityDirectory = options.entityDirectory || path.join(context.getCwd(), 'src/entity');
+
+    // Data structures for analysis
+    const serviceMethodCalls = new Map(); // method -> repository calls
+    const dtoPropertyAccess = new Map(); // DTO class -> accessed properties
+    const entityRelations = new Map(); // Entity -> relations (static cache)
+    const dataFlow = new Map(); // method -> DTOs used
+    const repositoryMethods = new Map(); // methodName -> entityName
+    let currentMethod = null; // Track current method being analyzed
+    const visitedNodes = new Set();
+
+    /**
+     * Load entity relations from external files
+     */
+    function loadEntityRelations(entityName) {
+      if (entityRelations.has(entityName)) {
+        return entityRelations.get(entityName);
+      }
+
+      const relations = [];
+
+      /**
+       * Recursively search for entity file in all subdirectories
+       */
+      function findEntityFile(directory) {
+        try {
+          if (!fs.existsSync(directory)) {
+            return null;
+          }
+
+          const items = fs.readdirSync(directory);
+
+          // First, check if the entity file exists directly in this directory
+          const directFile = path.join(directory, `${entityName}.ts`);
+          if (fs.existsSync(directFile)) {
+            return directFile;
+          }
+
+          // Then, recursively search subdirectories
+          for (const item of items) {
+            const itemPath = path.join(directory, item);
+            const stat = fs.statSync(itemPath);
+
+            if (stat.isDirectory()) {
+              const found = findEntityFile(itemPath);
+              if (found) {
+                return found;
+              }
+            }
+          }
+
+          return null;
+        } catch (error) {
+          return null;
+        }
+      }
+
+      const entityPath = findEntityFile(entityDirectory);
+
+      if (entityPath) {
+        try {
+          const content = fs.readFileSync(entityPath, 'utf8');
+
+          // Parse relations using line-by-line approach for reliability
+          // TypeORM decorators are often on the line before the property declaration
+          const lines = content.split('\n');
+          for (let i = 0; i < lines.length - 1; i++) {
+            const line = lines[i].trim();
+            const nextLine = lines[i + 1].trim();
+
+            // Check if current line has a relation decorator
+            if (line.match(/@(?:OneToMany|ManyToOne|OneToOne|ManyToMany)/)) {
+              // Check if next line has a property declaration
+              const propertyMatch = nextLine.match(/(\w+)\s*:/);
+              if (propertyMatch) {
+                const relationName = propertyMatch[1];
+                if (!relations.includes(relationName)) {
+                  relations.push(relationName);
+                }
+              }
+            }
+          }
+        } catch (error) {
+          // Error reading file, continue
+        }
+      } else {
+        // Debug: Log when entity file is not found
+        console.log(`[analyze-relation-usage] Entity file not found for: ${entityName} in ${entityDirectory}`);
+      }
+
+      entityRelations.set(entityName, relations);
+      return relations;
+    }
+
+    /**
+     * Check if method name matches trace patterns
+     */
+    function shouldTraceMethod(methodName) {
+      return traceMethods.some(pattern => {
+        const regex = new RegExp(pattern.replace(/\*/g, ".*"));
+        return regex.test(methodName);
+      });
+    }
+
+    /**
+     * Check if class name matches DTO patterns
+     */
+    function isDtoClass(className) {
+      return dtoPatterns.some(pattern => {
+        const regex = new RegExp(pattern.replace(/\*/g, ".*"));
+        return regex.test(className);
+      });
+    }
+
+    /**
+     * Extract entity name from repository call - robust version
+     */
+    function getEntityFromRepositoryCall(node) {
+      // Case 1: Direct getRepository call with entity argument
+      // this.dataSource.getRepository(EntityClass)
+      if (
+        node.callee?.property?.name === "getRepository" &&
+        node.arguments?.[0]?.name
+      ) {
+        return node.arguments[0].name;
+      }
+
+      // Case 2: Method call on repository object
+      // raceRepository.findOne() or this.getRepository().findOne()
+      if (node.callee?.object?.type === "CallExpression") {
+        const repositoryCall = node.callee.object;
+
+        // Direct getRepository call with entity argument
+        if (repositoryCall.callee?.property?.name === "getRepository" &&
+            repositoryCall.arguments?.[0]?.name) {
+          return repositoryCall.arguments[0].name;
+        }
+
+        // Method call like this.getRepository() - trace back to method definition
+        if (repositoryCall.callee?.property?.name === "getRepository") {
+          return findEntityFromMethodDefinition(repositoryCall);
+        }
+      }
+
+      // Case 3: Repository variable name pattern
+      // raceRepository.findOne() -> PlayableRaceEntity
+      if (node.callee?.object?.name) {
+        const objectName = node.callee.object.name;
+        if (objectName.includes("Repository")) {
+          return findEntityFromRepositoryVariable(node, objectName);
+        }
+      }
+
+      // Case 4: Variable declaration context
+      // const raceRepository = this.dataSource.getRepository(PlayableRaceEntity);
+      return findEntityFromVariableDeclaration(node);
+    }
+
+    /**
+     * Find entity from method definition (e.g., getRepository method)
+     */
+    function findEntityFromMethodDefinition(repositoryCall) {
+      // Walk up the AST to find the method definition
+      let currentNode = repositoryCall;
+      while (currentNode && currentNode.parent) {
+        currentNode = currentNode.parent;
+
+        // Found a method definition
+        if (currentNode.type === "MethodDefinition") {
+          const methodName = currentNode.key?.name;
+
+          // Look for getRepository method
+          if (methodName === "getRepository") {
+            const methodBody = currentNode.value?.body;
+            if (methodBody?.body) {
+              // Look for return statement with getRepository call
+              for (const statement of methodBody.body) {
+                if (statement.type === "ReturnStatement" &&
+                    statement.argument?.type === "CallExpression" &&
+                    statement.argument.callee?.property?.name === "getRepository" &&
+                    statement.argument.arguments?.[0]?.name) {
+                  return statement.argument.arguments[0].name;
+                }
+              }
+            }
+          }
+        }
+
+        // Also check if we're in a service class and look for patterns
+        if (currentNode.type === "ClassDeclaration") {
+          const className = currentNode.id?.name;
+          if (className && className.includes("Service")) {
+            // Look for common patterns in service classes
+            const serviceBody = currentNode.body?.body;
+            if (serviceBody) {
+              for (const member of serviceBody) {
+                if (member.type === "MethodDefinition" &&
+                    member.key?.name === "getRepository") {
+                  const methodBody = member.value?.body;
+                  if (methodBody?.body) {
+                    for (const statement of methodBody.body) {
+                      if (statement.type === "ReturnStatement" &&
+                          statement.argument?.type === "CallExpression" &&
+                          statement.argument.callee?.property?.name === "getRepository" &&
+                          statement.argument.arguments?.[0]?.name) {
+                        return statement.argument.arguments[0].name;
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+
+      return null;
+    }
+
+    /**
+     * Find entity from repository variable name
+     */
+    function findEntityFromRepositoryVariable(node, objectName) {
+      // Walk up to find where this variable was declared
+      let currentNode = node;
+      while (currentNode && currentNode.parent) {
+        currentNode = currentNode.parent;
+
+        // Check variable declarations
+        if (currentNode.type === "VariableDeclarator" &&
+            currentNode.id?.name === objectName) {
+          // Check if it's assigned from getRepository
+          if (currentNode.init?.type === "CallExpression" &&
+              currentNode.init.callee?.property?.name === "getRepository" &&
+              currentNode.init.arguments?.[0]?.name) {
+            return currentNode.init.arguments[0].name;
+          }
+        }
+
+        // Check method calls that might assign the repository
+        if (currentNode.type === "CallExpression" &&
+            currentNode.callee?.property?.name === "getRepository" &&
+            currentNode.arguments?.[0]?.name) {
+          // Check if this call is assigned to our repository variable
+          const parent = currentNode.parent;
+          if (parent?.type === "VariableDeclarator" &&
+              parent.id?.name === objectName) {
+            return currentNode.arguments[0].name;
+          }
+        }
+      }
+
+      return null;
+    }
+
+    /**
+     * Find entity from variable declaration context
+     */
+    function findEntityFromVariableDeclaration(node) {
+      let currentNode = node;
+      while (currentNode && currentNode.parent) {
+        currentNode = currentNode.parent;
+
+        if (currentNode.type === "VariableDeclarator" && currentNode.id?.name) {
+          const varName = currentNode.id.name;
+          if (varName.includes("Repository")) {
+            // Check if it's assigned from getRepository
+            if (currentNode.init?.type === "CallExpression" &&
+                currentNode.init.callee?.property?.name === "getRepository" &&
+                currentNode.init.arguments?.[0]?.name) {
+              return currentNode.init.arguments[0].name;
+            }
+          }
+        }
+      }
+
+      return null;
+    }
+
+    /**
+     * Extract relations from repository find options
+     */
+    function getRelationsFromFindOptions(node) {
+      const optionsArg = node.arguments?.[0];
+      if (!optionsArg || optionsArg.type !== "ObjectExpression") {
+        return [];
+      }
+
+      const relationsProperty = optionsArg.properties?.find(
+        prop => prop.key?.name === "relations"
+      );
+
+      if (!relationsProperty || relationsProperty.value?.type !== "ArrayExpression") {
+        return [];
+      }
+
+      const relations = relationsProperty.value.elements
+        ?.filter(el => el?.type === "Literal" && typeof el.value === "string")
+        ?.map(el => el.value) || [];
+
+      // For nested relations like "raceAbilities.ability", we need to validate
+      // that the base relation exists and the nested relation exists in the related entity
+      return relations;
+    }
+
+    /**
+     * Validate nested relations (e.g., "raceAbilities.ability")
+     */
+    function validateNestedRelation(entityName, relationPath) {
+      const parts = relationPath.split('.');
+      if (parts.length === 1) {
+        // Simple relation - already validated by main logic
+        return true;
+      }
+
+      const [baseRelation, ...nestedParts] = parts;
+
+      // First, check if base relation exists in the main entity
+      const entityRelations = loadEntityRelations(entityName);
+      if (!entityRelations.includes(baseRelation)) {
+        return false;
+      }
+
+      // Find the related entity for the base relation
+      const relatedEntityName = findRelatedEntityName(entityName, baseRelation);
+      if (!relatedEntityName) {
+        return false;
+      }
+
+      // Recursively validate nested relations
+      const nestedRelation = nestedParts.join('.');
+      return validateNestedRelation(relatedEntityName, nestedRelation);
+    }
+
+    /**
+     * Find the related entity name for a given relation
+     */
+    function findRelatedEntityName(entityName, relationName) {
+      // Try to load the entity file and find the relation type
+      const entityPath = findEntityFile(entityName);
+      if (!entityPath) {
+        return null;
+      }
+
+      try {
+        const content = fs.readFileSync(entityPath, 'utf8');
+        const lines = content.split('\n');
+
+        for (let i = 0; i < lines.length - 1; i++) {
+          const line = lines[i].trim();
+          const nextLine = lines[i + 1].trim();
+
+          // Check if current line has a relation decorator and next line has our relation
+          if (line.match(/@(?:OneToMany|ManyToOne|OneToOne|ManyToMany)/) &&
+              nextLine.includes(relationName)) {
+
+            // Extract the entity type from the decorator
+            const entityMatch = line.match(/\(\(\) => (\w+)/);
+            if (entityMatch) {
+              return entityMatch[1];
+            }
+          }
+        }
+      } catch (error) {
+        // Error reading file, continue
+      }
+
+      return null;
+    }
+
+    /**
+     * Find entity file path
+     */
+    function findEntityFile(entityName) {
+      const entityDirectory = path.join(context.getCwd(), 'src/entity');
+
+      function searchDirectory(directory) {
+        try {
+          if (!fs.existsSync(directory)) {
+            return null;
+          }
+
+          const items = fs.readdirSync(directory);
+
+          // First, check if the entity file exists directly in this directory
+          const directFile = path.join(directory, `${entityName}.ts`);
+          if (fs.existsSync(directFile)) {
+            return directFile;
+          }
+
+          // Then, recursively search subdirectories
+          for (const item of items) {
+            const itemPath = path.join(directory, item);
+            const stat = fs.statSync(itemPath);
+
+            if (stat.isDirectory()) {
+              const found = searchDirectory(itemPath);
+              if (found) {
+                return found;
+              }
+            }
+          }
+
+          return null;
+        } catch (error) {
+          return null;
+        }
+      }
+
+      return searchDirectory(entityDirectory);
+    }
+
+    /**
+     * Analyze property access in DTO constructor/fromEntity method
+     */
+    function analyzeDtoPropertyAccess(node, dtoClassName) {
+      if (!isDtoClass(dtoClassName)) return;
+
+      const accessedProperties = new Set();
+
+      // Walk through method body to find property accesses
+      function walkNode(n) {
+        if (!n || typeof n !== "object" || visitedNodes.has(n)) {
+          return;
+        }
+
+        visitedNodes.add(n);
+        if (n.type === "MemberExpression" &&
+            (n.object?.name === "entity" || n.object?.name === "item")) {
+          if (n.property?.name) {
+            accessedProperties.add(n.property.name);
+          }
+        }
+
+        // Recursively walk child nodes
+        Object.values(n).forEach(child => {
+          if (child && typeof child === "object" && child.type) {
+            walkNode(child);
+          } else if (Array.isArray(child)) {
+            child.forEach(item => item && typeof item === "object" && item.type && walkNode(item));
+          }
+        });
+      }
+
+      walkNode(node);
+      dtoPropertyAccess.set(dtoClassName, accessedProperties);
+    }
+
+    /**
+     * Track method calls to DTOs
+     */
+    function trackDtoUsage(node, methodName) {
+      // Look for DTO.fromEntity() calls or new DTO() calls
+      if (node.type === "CallExpression") {
+        if (node.callee?.property?.name === "fromEntity" && node.callee?.object?.name) {
+          const dtoName = node.callee.object.name;
+          if (isDtoClass(dtoName)) {
+            if (!dataFlow.has(methodName)) {
+              dataFlow.set(methodName, new Set());
+            }
+            dataFlow.get(methodName).add(dtoName);
+          }
+        }
+
+        if (node.callee?.name && isDtoClass(node.callee.name)) {
+          if (!dataFlow.has(methodName)) {
+            dataFlow.set(methodName, new Set());
+          }
+          dataFlow.get(methodName).add(node.callee.name);
+        }
+      }
+    }
+
+    return {
+      // Collect entity relations from @Entity classes in current file
+      ClassDeclaration(node) {
+        if (node.decorators?.some(dec => dec.expression?.callee?.name === "Entity")) {
+          const className = node.id?.name;
+          const relations = [];
+
+          node.body?.body?.forEach(member => {
+            if (member.type === "PropertyDefinition" && member.decorators) {
+              const hasRelationDecorator = member.decorators.some(decorator => {
+                const decoratorName = decorator.expression?.callee?.name || decorator.expression?.name;
+                return ["OneToMany", "ManyToOne", "OneToOne", "ManyToMany"].includes(decoratorName);
+              });
+
+              if (hasRelationDecorator && member.key?.name) {
+                relations.push(member.key.name);
+              }
+            }
+          });
+
+          if (className && relations.length > 0) {
+            entityRelations.set(className, relations);
+          }
+        }
+      },
+
+      // Analyze DTO classes
+      MethodDefinition(node) {
+        const className = node.parent?.parent?.id?.name;
+        if (className && isDtoClass(className)) {
+          if (node.key?.name === "constructor" || node.key?.name === "fromEntity") {
+            analyzeDtoPropertyAccess(node.value?.body, className);
+          }
+        }
+
+        // Track service methods
+        const methodName = node.key?.name;
+        if (methodName && shouldTraceMethod(methodName)) {
+          currentMethod = methodName;
+        }
+      },
+
+      "MethodDefinition:exit"() {
+        currentMethod = null;
+      },
+
+      // Track repository calls in traced methods
+      CallExpression(node) {
+        // Check repository method calls
+        const methodName = node.callee?.property?.name;
+        if (["find", "findOne", "findOneBy", "findAndCount", "findOneOrFail"].includes(methodName)) {
+          const entityName = getEntityFromRepositoryCall(node);
+
+          if (entityName) {
+            const requestedRelations = getRelationsFromFindOptions(node);
+            // Load relations from external entity files if not in current file
+            const availableRelations = loadEntityRelations(entityName);
+
+            // Validate each requested relation against available relations
+            requestedRelations.forEach(relation => {
+              // Check if it's a nested relation (contains dots)
+              if (relation.includes('.')) {
+                // Validate nested relation
+                if (!validateNestedRelation(entityName, relation)) {
+                  context.report({
+                    node,
+                    messageId: "invalidRelation",
+                    data: {
+                      relationName: relation,
+                      entityName,
+                      availableRelations: availableRelations.join(", ") || "none",
+                    },
+                  });
+                }
+              } else {
+                // Simple relation validation
+                if (!availableRelations.includes(relation)) {
+                  context.report({
+                    node,
+                    messageId: "invalidRelation",
+                    data: {
+                      relationName: relation,
+                      entityName,
+                      availableRelations: availableRelations.join(", ") || "none",
+                    },
+                  });
+                }
+              }
+            });
+
+            // Store for further analysis
+            if (currentMethod) {
+              if (!serviceMethodCalls.has(currentMethod)) {
+                serviceMethodCalls.set(currentMethod, []);
+              }
+
+              serviceMethodCalls.get(currentMethod).push({
+                node,
+                entityName,
+                relations: requestedRelations,
+              });
+            }
+          }
+        }
+
+        // Track DTO usage
+        if (currentMethod) {
+          trackDtoUsage(node, currentMethod);
+        }
+      },
+
+      // Perform final analysis when processing is complete
+      "Program:exit"() {
+        serviceMethodCalls.forEach((repositoryCalls, methodName) => {
+          const usedDtos = dataFlow.get(methodName) || new Set();
+
+          usedDtos.forEach(dtoName => {
+            const dtoProperties = dtoPropertyAccess.get(dtoName) || new Set();
+
+            repositoryCalls.forEach(repoCall => {
+              const entityName = repoCall.entityName;
+              const loadedRelations = repoCall.relations;
+              const entityRelationsList = loadEntityRelations(entityName);
+
+              // Find accessed properties that are relations but not loaded
+              const accessedRelations = [...dtoProperties].filter(prop =>
+                entityRelationsList.includes(prop)
+              );
+
+              const missingRelations = accessedRelations.filter(rel =>
+                !loadedRelations.includes(rel)
+              );
+
+              if (missingRelations.length > 0) {
+                context.report({
+                  node: repoCall.node,
+                  messageId: "suggestRelationLoad",
+                  data: {
+                    methodName,
+                    suggestedRelations: missingRelations.join('", "'),
+                  },
+                });
+              }
+            });
+          });
+        });
+
+        // Clear state for next file
+        visitedNodes.clear();
+      },
+
+      Program() {
+        // Reset state at the start of each file
+        visitedNodes.clear();
+        serviceMethodCalls.clear();
+        dataFlow.clear();
+        currentMethod = null;
+      },
+    };
+  }
+};
+
+export default analyzeRelationUsageRule;