SONARPY-3693 Create rule S8413: Router prefixes should be defined during APIRouter initialization (#818)

GitOrigin-RevId: 07c251b366702d7644da925adba3b0783a7d904a

Author: Seppli11

python-checks/src/main/java/org/sonar/python/checks/OpenSourceCheckList.java

@@ -374,6 +374,7 @@ public Stream<Class<?>> getChecks() {
       ReturnAndYieldInOneFunctionCheck.class,
       ReturnYieldOutsideFunctionCheck.class,
       RobustCipherAlgorithmCheck.class,
+      RouterPrefixInIncludeRouterCheck.class,
       S3BucketBlockPublicAccessCheck.class,
       S3BucketGrantedAccessCheck.class,
       S3BucketHTTPCommunicationCheck.class,

python-checks/src/main/java/org/sonar/python/checks/RouterPrefixInIncludeRouterCheck.java

@@ -0,0 +1,109 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2025 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonar.python.checks;
+
+import java.util.Optional;
+import java.util.stream.Stream;
+import org.sonar.check.Rule;
+import org.sonar.plugins.python.api.PythonSubscriptionCheck;
+import org.sonar.plugins.python.api.SubscriptionContext;
+import org.sonar.plugins.python.api.symbols.v2.SymbolV2;
+import org.sonar.plugins.python.api.symbols.v2.UsageV2;
+import org.sonar.plugins.python.api.tree.CallExpression;
+import org.sonar.plugins.python.api.tree.Expression;
+import org.sonar.plugins.python.api.tree.Name;
+import org.sonar.plugins.python.api.tree.RegularArgument;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.plugins.python.api.types.v2.matchers.TypeMatcher;
+import org.sonar.plugins.python.api.types.v2.matchers.TypeMatchers;
+import org.sonar.python.checks.utils.Expressions;
+import org.sonar.python.tree.TreeUtils;
+
+@Rule(key = "S8413")
+public class RouterPrefixInIncludeRouterCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE =
+    "Define the prefix in the \"APIRouter\" constructor instead of in \"include_router()\".";
+
+  private static final TypeMatcher INCLUDE_ROUTER_MATCHER = TypeMatchers.any(
+    TypeMatchers.isType("fastapi.applications.FastAPI.include_router"),
+    TypeMatchers.isType("fastapi.routing.APIRouter.include_router")
+  );
+
+  private static final TypeMatcher API_ROUTER_MATCHER = TypeMatchers.isType("fastapi.routing.APIRouter");
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.CALL_EXPR, RouterPrefixInIncludeRouterCheck::checkIncludeRouterCall);
+  }
+
+  private static void checkIncludeRouterCall(SubscriptionContext ctx) {
+    CallExpression callExpr = (CallExpression) ctx.syntaxNode();
+
+    if (!INCLUDE_ROUTER_MATCHER.isTrueFor(callExpr.callee(), ctx)) {
+      return;
+    }
+
+    RegularArgument prefixArg = TreeUtils.argumentByKeyword("prefix", callExpr.arguments());
+    if (prefixArg == null) {
+      return;
+    }
+
+    Optional<RegularArgument> routerArg = TreeUtils.nthArgumentOrKeywordOptional(0, "router", callExpr.arguments());
+    if (routerArg.isEmpty()) {
+      return;
+    }
+
+    Expression routerExpr = routerArg.get().expression();
+    if (!(routerExpr instanceof Name routerName)) {
+      return;
+    }
+
+    SymbolV2 routerSymbol = routerName.symbolV2();
+    if (routerSymbol == null) {
+      return;
+    }
+
+    if (isRouterWithoutPrefixInConstructor(routerSymbol, ctx)) {
+      var keyword = prefixArg.keywordArgument();
+      if (keyword != null) {
+        ctx.addIssue(keyword, MESSAGE);
+      }
+    }
+  }
+
+  private static boolean isRouterWithoutPrefixInConstructor(SymbolV2 routerSymbol, SubscriptionContext ctx) {
+    return routerSymbol.usages().stream()
+      .filter(UsageV2::isBindingUsage)
+      .map(UsageV2::tree)
+      .flatMap(RouterPrefixInIncludeRouterCheck::getBindingCallExpression)
+      .filter(call -> API_ROUTER_MATCHER.isTrueFor(call.callee(), ctx))
+      .anyMatch(RouterPrefixInIncludeRouterCheck::callHasNoPrefixArgument);
+  }
+
+  private static Stream<CallExpression> getBindingCallExpression(Tree bindingTree) {
+    if (!(bindingTree instanceof Name name)) {
+      return Stream.empty();
+    }
+    return Expressions.singleAssignedNonNameValue(name).stream()
+      .flatMap(TreeUtils.toStreamInstanceOfMapper(CallExpression.class));
+  }
+
+  private static boolean callHasNoPrefixArgument(CallExpression call) {
+    return TreeUtils.argumentByKeyword("prefix", call.arguments()) == null;
+  }
+}

python-checks/src/main/java/org/sonar/python/checks/utils/Expressions.java

@@ -29,6 +29,7 @@
 import javax.annotation.Nullable;
 import org.sonar.plugins.python.api.symbols.Symbol;
 import org.sonar.plugins.python.api.symbols.Usage;
+import org.sonar.plugins.python.api.tree.AnnotatedAssignment;
 import org.sonar.plugins.python.api.tree.Argument;
 import org.sonar.plugins.python.api.tree.AssignmentStatement;
 import org.sonar.plugins.python.api.tree.CallExpression;
@@ -152,6 +153,8 @@ public static Expression singleAssignedValue(Name name, Set<Name> visited) {
           parent.parent().is(Kind.ASSIGNMENT_STMT)) {
 
           result = ((AssignmentStatement) parent.parent()).assignedValue();
+        } else if (parent instanceof AnnotatedAssignment annotatedAssignment) {
+          result = annotatedAssignment.assignedValue();
         } else {
           return null;
         }

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S8413.html

@@ -0,0 +1,56 @@
+<p>An issue is raised when a router prefix is defined in the <code>include_router()</code> call instead of in the <code>APIRouter()</code>
+initialization.</p>
+<h2>Why is this an issue?</h2>
+<p>In FastAPI applications, routers help organize endpoints into logical groups. Each router can have a URL prefix that gets prepended to all its
+routes.</p>
+<p>When you define the prefix in the <code>include_router()</code> call, the router’s URL structure is separated from its definition. This means
+developers need to search through the application setup code to understand where the router’s endpoints will be accessible.</p>
+<p>Modern FastAPI versions support defining the prefix directly in the <code>APIRouter()</code> constructor. This approach keeps the router’s
+configuration self-contained and makes the code easier to understand at a glance.</p>
+<p>By defining the prefix at initialization time, you create a single source of truth for the router’s configuration. Anyone reading the router file
+immediately knows its URL structure without having to trace through the application setup.</p>
+<h3>What is the potential impact?</h3>
+<p>This pattern reduces code maintainability and readability. In larger applications with multiple routers, it becomes increasingly difficult to
+understand the application’s URL structure without examining the main application file.</p>
+<p>When routers are defined in separate modules (a common practice), developers working on a specific router module cannot see its full URL path
+without switching to a different file. This cognitive overhead slows down development and increases the likelihood of mistakes when adding or
+modifying routes.</p>
+<h2>How to fix it</h2>
+<p>Move the <code>prefix</code> parameter from the <code>include_router()</code> call to the <code>APIRouter()</code> initialization. This makes the
+router’s URL structure immediately visible in its definition.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+from fastapi import APIRouter, FastAPI
+
+router = APIRouter()  # Noncompliant
+
+@router.get("/users")
+def list_users():
+    return ["user1", "user2"]
+
+app = FastAPI()
+app.include_router(router, prefix="/api/v1")
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+from fastapi import APIRouter, FastAPI
+
+router = APIRouter(prefix="/api/v1")
+
+@router.get("/users")
+def list_users():
+    return ["user1", "user2"]
+
+app = FastAPI()
+app.include_router(router)
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> FastAPI - APIRouter - <a href="https://fastapi.tiangolo.com/tutorial/bigger-applications/">Official FastAPI documentation on using APIRouter
+  for larger applications</a> </li>
+  <li> FastAPI - APIRouter Reference - <a href="https://fastapi.tiangolo.com/reference/apirouter/">API reference for the APIRouter class and its
+  parameters</a> </li>
+</ul>
+

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S8413.json

@@ -0,0 +1,25 @@
+{
+  "title": "Router prefixes should be defined during \"APIRouter\" initialization",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "2min"
+  },
+  "tags": [
+    "fastapi",
+    "convention",
+    "readability"
+  ],
+  "defaultSeverity": "Blocker",
+  "ruleSpecification": "RSPEC-8413",
+  "sqKey": "S8413",
+  "scope": "Main",
+  "quickfix": "unknown",
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "BLOCKER"
+    },
+    "attribute": "CLEAR"
+  }
+}

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/Sonar_way_profile.json

@@ -323,6 +323,7 @@
     "S8409",
     "S8410",
     "S8411",
-    "S8412"
+    "S8412",
+    "S8413"
   ]
 }

python-checks/src/test/java/org/sonar/python/checks/RouterPrefixInIncludeRouterCheckTest.java

@@ -0,0 +1,29 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2025 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonar.python.checks;
+
+import org.junit.jupiter.api.Test;
+import org.sonar.python.checks.utils.PythonCheckVerifier;
+
+class RouterPrefixInIncludeRouterCheckTest {
+  @Test
+  void test() {
+    PythonCheckVerifier.verify(
+      "src/test/resources/checks/routerPrefixInIncludeRouter.py",
+      new RouterPrefixInIncludeRouterCheck());
+  }
+}

python-checks/src/test/java/org/sonar/python/checks/utils/ExpressionsTest.java

@@ -269,6 +269,7 @@ void singleAssignedValue() {
     assertThat(lastNameValue("x = 42; import x; x")).isNull();
     assertThat(lastNameValue("x = 42; x = 43; x")).isNull();
     assertThat(lastNameValue("x = 42; y")).isNull();
+    assertThat(lastNameValue("x: int = 42; x").getKind()).isEqualTo(Kind.NUMERIC_LITERAL);
   }
 
   private Expression lastNameValue(String code) {
@@ -290,6 +291,7 @@ void singleAssignedNonNameValue() {
     assertThat(lastNameNonNameValue("x = 42; import x; x")).isNull();
     assertThat(lastNameNonNameValue("x = 42; x = 43; x")).isNull();
     assertThat(lastNameNonNameValue("x = 42; y")).isNull();
+    assertThat(lastNameNonNameValue("x: int = 42; x").getKind()).isEqualTo(Kind.NUMERIC_LITERAL);
   }
 
   @Test

python-checks/src/test/resources/checks/routerPrefixInIncludeRouter.py

@@ -0,0 +1,125 @@
+from fastapi import APIRouter, FastAPI
+
+# --- Noncompliant Cases ---
+
+def noncompliant_basic():
+    """Basic case: prefix in include_router instead of APIRouter constructor"""
+    router = APIRouter()
+    app = FastAPI()
+    app.include_router(router, prefix="/api/v1")  # Noncompliant {{Define the prefix in the "APIRouter" constructor instead of in "include_router()".}}
+#                              ^^^^^^
+
+def noncompliant_router_to_router():
+    """Prefix when adding router to another router"""
+    parent = APIRouter()
+    child = APIRouter()
+    parent.include_router(child, prefix="/users")  # Noncompliant
+#                                ^^^^^^
+
+def noncompliant_keyword_argument():
+    """Using keyword argument for router parameter"""
+    router = APIRouter()
+    app = FastAPI()
+    app.include_router(router=router, prefix="/api")  # Noncompliant
+#                                     ^^^^^^
+
+def noncompliant_multiple_routers():
+    """Multiple routers with prefix in include_router"""
+    router1 = APIRouter()
+    router2 = APIRouter()
+    app = FastAPI()
+    app.include_router(router1, prefix="/v1")  # Noncompliant
+#                               ^^^^^^
+    app.include_router(router2, prefix="/v2")  # Noncompliant
+#                               ^^^^^^
+
+def noncompliant_prefix_with_tags():
+    """Prefix combined with other arguments"""
+    router = APIRouter()
+    app = FastAPI()
+    app.include_router(router, prefix="/api", tags=["api"])  # Noncompliant
+#                              ^^^^^^
+
+# --- Compliant Cases ---
+
+def compliant_prefix_in_constructor():
+    router = APIRouter(prefix="/api/v1")
+    app = FastAPI()
+    app.include_router(router)  # Compliant
+
+def compliant_no_prefix():
+    router = APIRouter()
+    app = FastAPI()
+    app.include_router(router)  # Compliant
+
+def compliant_both_prefixes():
+    """Prefix in both places - still compliant (user's choice to combine)"""
+    router = APIRouter(prefix="/api")
+    app = FastAPI()
+    app.include_router(router, prefix="/v1")  # Compliant
+
+def compliant_prefix_in_constructor_with_tags():
+    """Prefix in constructor, other args in include_router"""
+    router = APIRouter(prefix="/api")
+    app = FastAPI()
+    app.include_router(router, tags=["api"])  # Compliant
+
+def compliant_only_tags():
+    """Only tags, no prefix"""
+    router = APIRouter()
+    app = FastAPI()
+    app.include_router(router, tags=["api"])  # Compliant
+
+def fn_router_without_symbol():
+    """Router created inline - edge case"""
+    app = FastAPI()
+    app.include_router(APIRouter(), prefix="/api")  # FN 
+
+def fn_unknown_router_origin():
+    """Router comes from function call"""
+    app = FastAPI()
+    app.include_router(get_router(), prefix="/api")  # FN 
+
+def fn_router_from_import():
+    """Router imported from another module"""
+    from other_module import router
+    app = FastAPI()
+    app.include_router(router, prefix="/api")  # FN 
+
+# --- Edge Cases ---
+
+def edge_case_reassigned_router():
+    """Router reassigned to another variable"""
+    router = APIRouter()
+    r = router
+    app = FastAPI()
+    app.include_router(r, prefix="/api")  # Noncompliant
+
+def edge_case_conditional():
+    router = APIRouter()
+    app = FastAPI()
+    if True:
+        app.include_router(router, prefix="/api")  # Noncompliant
+#                                  ^^^^^^
+
+def edge_case_annotated_assignment():
+    router: APIRouter = APIRouter()
+    app = FastAPI()
+    app.include_router(router, prefix="/api")  # Noncompliant
+#                              ^^^^^^
+
+def edge_case_router_as_function_parameter():
+    def setup_routes(router: APIRouter):
+        app = FastAPI()
+        app.include_router(router, prefix="/api")  # potential FN 
+
+def edge_case_multiple_assignments():
+    router = APIRouter()
+    router = APIRouter(prefix="/api")  
+    app = FastAPI()
+    app.include_router(router, prefix="/v1")  # FN
+
+def edge_case_no_router():
+    router = APIRouter()
+    app = FastAPI()
+    app.include_router(prefix="/api", router)