From 2b316560e348a251366cc87736238087834f7ce3 Mon Sep 17 00:00:00 2001
From: Marco Kaufmann <marco.kaufmann@sonarsource.com>
Date: Wed, 10 May 2023 19:14:59 +0200
Subject: [PATCH] Create rule S6627: Users should not use internal APIs

---
 rules/S6627/kotlin/metadata.json |  3 +-
 rules/S6627/kotlin/rule.adoc     | 47 +++++++++++++++++---------------
 2 files changed, 27 insertions(+), 23 deletions(-)

diff --git a/rules/S6627/kotlin/metadata.json b/rules/S6627/kotlin/metadata.json
index 6a5a985b285..25cff2beb9d 100644
--- a/rules/S6627/kotlin/metadata.json
+++ b/rules/S6627/kotlin/metadata.json
@@ -1,5 +1,5 @@
 {
-  "title": "FIXME",
+  "title": "Users should not use internal APIs",
   "type": "CODE_SMELL",
   "status": "ready",
   "remediation": {
@@ -7,6 +7,7 @@
     "constantCost": "5min"
   },
   "tags": [
+    "Gradle"
   ],
   "defaultSeverity": "Major",
   "ruleSpecification": "RSPEC-6627",
diff --git a/rules/S6627/kotlin/rule.adoc b/rules/S6627/kotlin/rule.adoc
index 50a6ef739e3..f22aa7c6dba 100644
--- a/rules/S6627/kotlin/rule.adoc
+++ b/rules/S6627/kotlin/rule.adoc
@@ -1,43 +1,46 @@
-FIXME: add a description
+== Why is this an issue?
 
-// If you want to factorize the description uncomment the following line and create the file.
-//include::../description.adoc[]
+The public API of a framework, plugin, or library is the way its provider intended it to be used.
+API stability and compatibility (within the same major version number) of a library are guaranteed only for its public API.
 
-== Why is this an issue?
+Internal APIs are mere implementation details and are prone to breaking changes as the implementation of the library changes.
+No guarantees are being made about them. Therefore, users should not use internal APIs, even when visible.
+
+=== What is the potential impact?
 
-FIXME: remove the unused optional headers (that are commented out)
+==== Code Stability
 
-//=== What is the potential impact?
+If not fixed, your code might break when the library is upgraded to a new version, even if only the minor version number or the patch number changes.
 
 == How to fix it
-//== How to fix it in FRAMEWORK NAME
+
+Replace internal API usage with the public API designed for your use case.
+This may imply a refactoring of the affected code if no one-to-one replacement is available in the public API.
+If a specific functionality is required, copying the required parts of the implementation into your code may even be better than using the internal API.
 
 === Code examples
 
 ==== Noncompliant code example
 
-[source,text,diff-id=1,diff-type=noncompliant]
+[source,kotlin,diff-id=1,diff-type=noncompliant]
 ----
-FIXME
+if (org.gradle.internal.os.OperatingSystem.current().isWindows) { // Noncompliant, OperatingSystem is part of Gradle internal API
+    // ...
+}
 ----
 
 ==== Compliant solution
 
-[source,text,diff-id=1,diff-type=compliant]
+[source,kotlin,diff-id=1,diff-type=compliant]
 ----
-FIXME
+if (System.getProperty("os.name").toLowerCase().contains("windows")) { // Compliant
+    // ...
+}
 ----
 
-//=== How does this work?
-
-//=== Pitfalls
-
-//=== Going the extra mile
+== Resources
 
+=== Documentation
 
-//== Resources
-//=== Documentation
-//=== Articles & blog posts
-//=== Conference presentations
-//=== Standards
-//=== Benchmarks
+* https://docs.gradle.org/current/userguide/authoring_maintainable_build_scripts.html#sec:avoiding_gradle_internal_apis[Gradle Documentation - Avoid using internal Gradle APIs]
+* https://github.com/liutikas/gradle-best-practices#dont-use-internal-apis[Best Practices when using Gradle - Don't use internal APIs (Liutikas)]