Create rule S7197: Circular file imports should be resolved (#4645)

* Create rule S7197

* Create rule S7197: Circular file imports should be resolved

* Comments

---------

Co-authored-by: kaufco <[email protected]>
Co-authored-by: Marco Kaufmann <[email protected]>
Co-authored-by: zglicz <[email protected]>

rules/S7197/javascript/metadata.json

@@ -0,0 +1,25 @@
+{
+  "title": "Circular file imports should be resolved",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "0min"
+  },
+  "tags": [
+    "architecture",
+    "design"
+  ],
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-7197",
+  "sqKey": "S7197",
+  "scope": "All",
+  "defaultQualityProfiles": ["Sonar way"],
+  "quickfix": "infeasible",
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "HIGH"
+    },
+    "attribute": "MODULAR"
+  }
+}

rules/S7197/javascript/rule.adoc

@@ -0,0 +1,100 @@
+This rule reports circular dependencies between source files, including indirect cycles spanning multiple files caused by circular imports.
+
+== Why is this an issue?
+
+Circular dependencies occur when two or more source files import each other, either directly or indirectly.
+This creates a dependency structure that lacks a clear hierarchy, making the codebase harder to understand and maintain.
+Additionally, the order in which circular imports are resolved is not guaranteed, which can lead to unpredictable behavior and runtime errors.
+
+=== What is the potential impact?
+
+Circular dependencies increase the complexity of the code architecture, reducing readability, extensibility, and maintainability.
+As the project grows, these dependencies can spread, further complicating the architecture and increasing technical debt.
+Over time, resolving these dependencies becomes increasingly difficult.
+
+== How to fix it
+
+1. **Refactor shared functionality**: If multiple files share similar functionality, consider moving that functionality to a separate module that both can import. This allows each file to depend on the shared module rather than on each other.
+
+2. **Use dependency inversion:** Instead of directly importing modules that create circular dependencies, use dependency inversion by passing necessary functions or objects as parameters. This breaks the circular reference and makes the code more modular and testable.
+
+3. **Split responsibilities**: Evaluate whether each file is handling too many responsibilities. If so, break them down into smaller, more focused modules. This reduces circular dependencies and ensures that your code is easier to manage and extend.
+
+=== Code examples
+
+==== Noncompliant code example
+
+The following code contains a circular dependency: `order.js` → `customer.js` → `order.js`, and `order.js` → `product.js` → `order.js`.
+Both cycles are connected through `order.js`, forming a tangle of two cycles.
+
+[source,javascript,diff-id=1,diff-type=noncompliant]
+----
+// order.js
+import { Customer } from './customer.js';
+import { Product } from './product.js';
+
+export class Order {
+    constructor() {
+        this.customer = new Customer();
+        this.products = [];
+    }
+}
+
+// customer.js
+import { Order } from './order.js';
+
+export class Customer {
+    constructor() {
+        this.orders = [];
+    }
+}
+
+// product.js
+import { Order } from './order.js';
+
+export class Product {
+    constructor() {
+        this.orders = [];
+    }
+}
+----
+
+==== Compliant solution
+
+The issue can be resolved by refactoring the structure.
+Two service functions can replace the dependencies `customer.js` → `order.js` and `product.js` → `order.js`.
+
+[source,javascript,diff-id=1,diff-type=compliant]
+----
+// order.js
+import { Customer } from './customer.js';
+import { Product } from './product.js';
+
+export class Order {
+    constructor() {
+        this.customer = new Customer();
+        this.products = [];
+    }
+}
+
+// customer.js
+export class Customer { }
+
+// product.js
+export class Product { }
+
+// orderService.js
+export function getOrdersByCustomer(customer) {
+    // Implementation to get orders by customer
+}
+
+export function getOrdersByProduct(product) {
+    // Implementation to get orders by product
+}
+----
+
+== Resources
+
+- Wikipedia - https://en.wikipedia.org/wiki/Acyclic_dependencies_principle[Acyclic dependencies principle]
+- STAN - https://stan4j.com/advanced/adp/[Acyclic dependencies principle]
+- RSPEC - https://sonarsource.github.io/rspec/#/rspec/S7091/java[S7091: Circular dependencies between classes across package boundaries should be resolved]

rules/S7197/metadata.json

@@ -0,0 +1,2 @@
+{
+}