SONARPY-2392 Update custom rule examples

docs/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT No Attribution
+
+Copyright 2023, SonarSource SA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/pom.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.sonarsource.python</groupId>
+    <artifactId>python</artifactId>
+    <version>4.25-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>docs</artifactId>
+  <packaging>pom</packaging>
+
+  <name>SonarQube Python :: Documentation</name>
+
+  <modules>
+    <module>python-custom-rules-example</module>
+  </modules>
+
+</project>

docs/python-custom-rules-example/pom.xml

@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.sonarsource.python</groupId>
+    <artifactId>docs</artifactId>
+    <version>4.25-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>python-custom-rules-example</artifactId>
+  <packaging>sonar-plugin</packaging>
+
+  <name>SonarQube Python :: Documentation :: Custom Rules Example</name>
+  <description>Python custom rule examples for SonarQube</description>
+
+  <properties>
+    <sonar.python.version>4.24.0.18631</sonar.python.version>
+  </properties>
+  <dependencies>
+    <dependency>
+      <groupId>org.sonarsource.api.plugin</groupId>
+      <artifactId>sonar-plugin-api</artifactId>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.sonarsource.analyzer-commons</groupId>
+      <artifactId>sonar-analyzer-commons</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.sonarsource.sonarqube</groupId>
+      <artifactId>sonar-plugin-api-impl</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.sonarsource.python</groupId>
+      <artifactId>sonar-python-plugin</artifactId>
+      <type>sonar-plugin</type>
+      <version>${project.version}</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.sonarsource.python</groupId>
+      <artifactId>python-checks-testkit</artifactId>
+      <version>${project.version}</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.sonarsource.sonar-packaging-maven-plugin</groupId>
+        <artifactId>sonar-packaging-maven-plugin</artifactId>
+        <extensions>true</extensions>
+        <configuration>
+          <pluginClass>org.sonar.samples.python.CustomPythonRulesPlugin</pluginClass>
+          <requirePlugins>python:${project.version}</requirePlugins>
+          <pluginApiMinVersion>${pluginApiMinVersion}</pluginApiMinVersion>
+          <requiredForLanguages>py,ipynb</requiredForLanguages>
+        </configuration>
+      </plugin>
+
+      <plugin>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.7.0</version>
+        <configuration>
+          <source>17</source>
+          <target>17</target>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>com.mycila</groupId>
+        <artifactId>license-maven-plugin</artifactId>
+        <configuration>
+          <licenseSets>
+            <licenseSet>
+              <header>${project.basedir}/src/main/resources/license-header.txt</header>
+            </licenseSet>
+          </licenseSets>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>

docs/python-custom-rules-example/src/main/java/org/sonar/samples/python/CustomPythonRuleRepository.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2011-2024 SonarSource SA - mailto:info AT sonarsource DOT com
+ * This code is released under [MIT No Attribution](https://opensource.org/licenses/MIT-0) license.
+ */
+package org.sonar.samples.python;
+
+import java.util.ArrayList;
+import java.util.List;
+import org.sonar.api.SonarRuntime;
+import org.sonar.api.server.rule.RulesDefinition;
+import org.sonar.plugins.python.api.PythonCustomRuleRepository;
+import org.sonarsource.analyzer.commons.RuleMetadataLoader;
+
+public class CustomPythonRuleRepository implements RulesDefinition, PythonCustomRuleRepository {
+  public static final String RESOURCE_BASE_PATH = "/org/sonar/l10n/python/rules/python";
+  public static final String REPOSITORY_KEY = "python-custom-rules-example";
+  public static final String REPOSITORY_NAME = "MyCompany Custom Repository";
+
+  private final SonarRuntime runtime;
+
+  public CustomPythonRuleRepository(SonarRuntime runtime) {
+    this.runtime = runtime;
+  }
+
+  @Override
+  public void define(Context context) {
+    NewRepository repository = context.createRepository(REPOSITORY_KEY, "py").setName(REPOSITORY_NAME);
+    RuleMetadataLoader ruleMetadataLoader = new RuleMetadataLoader(RESOURCE_BASE_PATH, runtime);
+    ruleMetadataLoader.addRulesByAnnotatedClass(repository, new ArrayList<>(RulesList.getChecks()));
+    repository.done();
+  }
+
+  @Override
+  public String repositoryKey() {
+    return REPOSITORY_KEY;
+  }
+
+  @Override
+  public List<Class<?>> checkClasses() {
+    return new ArrayList<>(RulesList.getChecks());
+  }
+}

docs/python-custom-rules-example/src/main/java/org/sonar/samples/python/CustomPythonRulesPlugin.java

@@ -0,0 +1,16 @@
+/*
+ * Copyright (C) 2011-2024 SonarSource SA - mailto:info AT sonarsource DOT com
+ * This code is released under [MIT No Attribution](https://opensource.org/licenses/MIT-0) license.
+ */
+package org.sonar.samples.python;
+
+import org.sonar.api.Plugin;
+
+public class CustomPythonRulesPlugin implements Plugin {
+
+  @Override
+  public void define(Context context) {
+    context.addExtension(CustomPythonRuleRepository.class);
+  }
+
+}

docs/python-custom-rules-example/src/main/java/org/sonar/samples/python/RulesList.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (C) 2011-2024 SonarSource SA - mailto:info AT sonarsource DOT com
+ * This code is released under [MIT No Attribution](https://opensource.org/licenses/MIT-0) license.
+ */
+package org.sonar.samples.python;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.stream.Stream;
+import org.sonar.plugins.python.api.PythonCheck;
+import org.sonar.samples.python.checks.CustomPythonSubscriptionCheck;
+import org.sonar.samples.python.checks.CustomPythonVisitorCheck;
+
+public final class RulesList {
+
+  private RulesList() {
+  }
+
+  public static List<Class<? extends PythonCheck>> getChecks() {
+    return new ArrayList<>(Stream.concat(
+      getPythonChecks().stream(),
+      getPythonTestChecks().stream()
+    ).toList());
+  }
+
+  /**
+   * These rules are going to target MAIN code only
+   */
+  public static List<Class<? extends PythonCheck>> getPythonChecks() {
+    return new ArrayList<>(List.of(
+      CustomPythonSubscriptionCheck.class
+    ));
+  }
+
+  /**
+   * These rules are going to target TEST code only
+   */
+  public static List<Class<? extends PythonCheck>> getPythonTestChecks() {
+    return new ArrayList<>(List.of(
+      CustomPythonVisitorCheck.class
+    ));
+  }
+}

docs/python-custom-rules-example/src/main/java/org/sonar/samples/python/checks/CustomPythonSubscriptionCheck.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright (C) 2011-2024 SonarSource SA - mailto:info AT sonarsource DOT com
+ * This code is released under [MIT No Attribution](https://opensource.org/licenses/MIT-0) license.
+ */
+package org.sonar.samples.python.checks;
+
+import org.sonar.check.Rule;
+import org.sonar.plugins.python.api.PythonSubscriptionCheck;
+import org.sonar.plugins.python.api.tree.ForStatement;
+import org.sonar.plugins.python.api.tree.Tree;
+
+@Rule(key = CustomPythonSubscriptionCheck.RULE_KEY)
+public class CustomPythonSubscriptionCheck extends PythonSubscriptionCheck {
+
+  public static final String RULE_KEY = "subscription";
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.FOR_STMT, ctx -> ctx.addIssue(((ForStatement) ctx.syntaxNode()).forKeyword(), "For statement."));
+  }
+}

docs/python-custom-rules-example/src/main/java/org/sonar/samples/python/checks/CustomPythonVisitorCheck.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright (C) 2011-2024 SonarSource SA - mailto:info AT sonarsource DOT com
+ * This code is released under [MIT No Attribution](https://opensource.org/licenses/MIT-0) license.
+ */
+package org.sonar.samples.python.checks;
+
+import org.sonar.check.Rule;
+import org.sonar.plugins.python.api.PythonVisitorCheck;
+import org.sonar.plugins.python.api.tree.FunctionDef;
+
+@Rule(key = CustomPythonVisitorCheck.RULE_KEY)
+public class CustomPythonVisitorCheck extends PythonVisitorCheck {
+
+  public static final String RULE_KEY = "visitor";
+
+  @Override
+  public void visitFunctionDef(FunctionDef pyFunctionDefTree) {
+    addIssue(pyFunctionDefTree.name(), "Function def.");
+    super.visitFunctionDef(pyFunctionDefTree);
+  }
+
+}

docs/python-custom-rules-example/src/main/java/org/sonar/samples/python/checks/package-info.java

@@ -0,0 +1,9 @@
+/*
+ * Copyright (C) 2011-2024 SonarSource SA - mailto:info AT sonarsource DOT com
+ * This code is released under [MIT No Attribution](https://opensource.org/licenses/MIT-0) license.
+ */
+@ParametersAreNonnullByDefault
+package org.sonar.samples.python.checks;
+
+import javax.annotation.ParametersAreNonnullByDefault;
+

docs/python-custom-rules-example/src/main/java/org/sonar/samples/python/package-info.java

@@ -0,0 +1,9 @@
+/*
+ * Copyright (C) 2011-2024 SonarSource SA - mailto:info AT sonarsource DOT com
+ * This code is released under [MIT No Attribution](https://opensource.org/licenses/MIT-0) license.
+ */
+@ParametersAreNonnullByDefault
+package org.sonar.samples.python;
+
+import javax.annotation.ParametersAreNonnullByDefault;
+

docs/python-custom-rules-example/src/main/resources/license-header.txt

@@ -0,0 +1,2 @@
+Copyright (C) ${license.years} ${license.owner} - ${license.mailto}
+This code is released under [MIT No Attribution](https://opensource.org/licenses/MIT-0) license.

docs/python-custom-rules-example/src/main/resources/org/sonar/l10n/python/rules/python/subscription.html

@@ -0,0 +1,9 @@
+<p>raises an issue on a <code>For statement.</code></p>
+<h2>Noncompliant Code Example</h2>
+<pre>
+TO DO 
+</pre>
+<h2>Compliant Solution</h2>
+<pre>
+TO DO 
+</pre>

docs/python-custom-rules-example/src/main/resources/org/sonar/l10n/python/rules/python/subscription.json

@@ -0,0 +1,21 @@
+{
+  "title": "Python subscription visitor check",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "10min"
+  },
+  "tags": [
+    "custom-python"
+  ],
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "LOW",
+      "RELIABILITY": "LOW",
+      "SECURITY": "LOW"
+    },
+    "attribute": "CLEAR"
+  },
+  "defaultSeverity": "Minor"
+}

docs/python-custom-rules-example/src/main/resources/org/sonar/l10n/python/rules/python/visitor.html

@@ -0,0 +1,9 @@
+<p>raises an issue on a <code>For statement.</code> with a visitor on which you can control the visit.</p>
+<h2>Noncompliant Code Example</h2>
+<pre>
+TO DO 
+</pre>
+<h2>Compliant Solution</h2>
+<pre>
+TO DO 
+</pre>

docs/python-custom-rules-example/src/main/resources/org/sonar/l10n/python/rules/python/visitor.json

@@ -0,0 +1,21 @@
+{
+  "title": "Python visitor check",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "custom-python"
+  ],
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "LOW",
+      "RELIABILITY": "LOW",
+      "SECURITY": "LOW"
+    },
+    "attribute": "CLEAR"
+  },
+  "defaultSeverity": "Minor"
+}