Merge pull request gradle#26585 Fix public API definitions

This PR updates the definition of the Gradle Public API to match the existing state of the project.
It also fixes other places in the project that normally must be synced to the public API definition.

I took the state of the public API definition and used it in a Bash script to find any packages that do not actually exist in the project anymore. This is done by running a ripgrep search for strings like `package org.gradle.env`.

<details>
  <summary>Stale package detection script</summary>

Note that you need [`ripgrep`](https://github.com/BurntSushi/ripgrep) installed to run this script.

```bash
#!/bin/bash

packages=(
    "org.gradle"
    "org.gradle.api"
    "org.gradle.authentication"
    "org.gradle.build"
    "org.gradle.buildinit"
    "org.gradle.caching"
    "org.gradle.concurrent"
    "org.gradle.deployment"
    "org.gradle.env"
    "org.gradle.external.javadoc"
    "org.gradle.ide"
    "org.gradle.includedbuild"
    "org.gradle.ivy"
    "org.gradle.jvm"
    "org.gradle.language"
    "org.gradle.maven"
    "org.gradle.nativeplatform"
    "org.gradle.normalization"
    "org.gradle.platform"
    "org.gradle.play"
    "org.gradle.plugin.devel"
    "org.gradle.plugin.repository"
    "org.gradle.plugin.use"
    "org.gradle.plugin.management"
    "org.gradle.plugins"
    "org.gradle.process"
    "org.gradle.testfixtures"
    "org.gradle.testing.jacoco"
    "org.gradle.tooling"
    "org.gradle.swiftpm"
    "org.gradle.model"
    "org.gradle.testkit"
    "org.gradle.testing"
    "org.gradle.vcs"
    "org.gradle.work"
    "org.gradle.workers"
    "org.gradle.util"
)

for package_name in "${packages[@]}"; do
    echo ""
    printf '%s\n' "Searching for '$package_name'"

    # Shows unique directories that contains files having a match for the package name
    rg --only-matching --with-filename "package $package_name" | \
        awk -F':' '{ print $1 }' | xargs -I {} dirname {} | sort -u | \
        rg 'src/main' | rg -v '/internal' | \
        awk 'NR==1 {prev=$0; next} {if (index($0, prev) != 1) print prev; prev=$0} END {print prev}'
done
```
</details>

These are the results that I got:
https://gist.github.com/alllex/f87a45f8a841bd3541845951043b8c69

They suggest that the following packages are not really part of the public API anymore. Either there are no classes at all in those packages, or they are not production classes (e.g. integration tests).

- `org.gradle.env`
- `org.gradle.includedbuild`
- `org.gradle.play`
- `org.gradle.plugin.repository`

### Reviewing cheatsheet

Before merging the PR, comments starting with
- ❌ ❓**must** be fixed
- 🤔 💅 **should** be fixed
- 💭 **may** be fixed
- 🎉 celebrate happy things

Co-authored-by: Alex Semin <[email protected]>

build-logic-commons/basics/src/main/kotlin/gradlebuild/basics/PublicApi.kt

@@ -7,6 +7,7 @@ package gradlebuild.basics
  * A type is part of the Gradle public API if and only if its FQCN matches {@link #includes} and does not match {@link #excludes}.
  */
 // NOTE: If you update this, please also change .idea/scopes/Gradle_public_API.xml
+// and also change `avoiding_gradle_internal_apis` section in `src/docs/userguide/authoring-builds/authoring_maintainable_build_scripts.adoc`
 object PublicApi {
     val includes = listOf(
         "org/gradle/*",
@@ -17,20 +18,16 @@ object PublicApi {
         "org/gradle/caching/**",
         "org/gradle/concurrent/**",
         "org/gradle/deployment/**",
-        "org/gradle/env/**",
         "org/gradle/external/javadoc/**",
         "org/gradle/ide/**",
-        "org/gradle/includedbuild/**",
         "org/gradle/ivy/**",
         "org/gradle/jvm/**",
         "org/gradle/language/**",
         "org/gradle/maven/**",
         "org/gradle/nativeplatform/**",
         "org/gradle/normalization/**",
         "org/gradle/platform/**",
-        "org/gradle/play/**",
         "org/gradle/plugin/devel/**",
-        "org/gradle/plugin/repository/*",
         "org/gradle/plugin/use/*",
         "org/gradle/plugin/management/*",
         "org/gradle/plugins/**",

subprojects/docs/src/docs/userguide/authoring-builds/authoring_maintainable_build_scripts.adoc

@@ -69,42 +69,53 @@ include::sample[dir="snippets/bestPractices/conditionalLogic-do/groovy", files="
 
 Use of Gradle internal APIs in plugins and build scripts has the potential to break builds when either Gradle or plugins change.
 
-The following packages are listed in the link:https://github.com/gradle/gradle/blob/180b9d3fa84b91768364c603380e82947437eda1/buildSrc/subprojects/configuration/src/main/kotlin/org/gradle/gradlebuild/public-api.kt[Gradle public API definition], with the exception of any subpackage with `internal` in the name:
+The following packages are listed in the
+link:https://github.com/gradle/gradle/blob/6961503e70aa634653e71413224831fd3fa3ec2d/build-logic/basics/src/main/kotlin/gradlebuild/basics/PublicApi.kt[Gradle public API definition]
+and the
+link:https://github.com/gradle/gradle/blob/6961503e70aa634653e71413224831fd3fa3ec2d/build-logic/basics/src/main/kotlin/gradlebuild/basics/PublicKotlinDslApi.kt[Kotlin DSL API definition], except any subpackage with `internal` in the name.
 
+// If these list is modified due changes in the public API definitions, update the permalinks too
+.Gradle API packages
 ----
-org/gradle/*
-org/gradle/api/**
-org/gradle/authentication/**
-org/gradle/buildinit/**
-org/gradle/caching/**
-org/gradle/concurrent/**
-org/gradle/deployment/**
-org/gradle/external/javadoc/**
-org/gradle/ide/**
-org/gradle/includedbuild/**
-org/gradle/ivy/**
-org/gradle/jvm/**
-org/gradle/language/**
-org/gradle/maven/**
-org/gradle/nativeplatform/**
-org/gradle/normalization/**
-org/gradle/platform/**
-org/gradle/play/**
-org/gradle/plugin/devel/**
-org/gradle/plugin/repository/*
-org/gradle/plugin/use/*
-org/gradle/plugin/management/*
-org/gradle/plugins/**
-org/gradle/process/**
-org/gradle/testfixtures/**
-org/gradle/testing/jacoco/**
-org/gradle/tooling/**
-org/gradle/swiftpm/**
-org/gradle/model/**
-org/gradle/testkit/**
-org/gradle/testing/**
-org/gradle/vcs/**
-org/gradle/workers/**
+org.gradle
+org.gradle.api.*
+org.gradle.authentication.*
+org.gradle.build.*
+org.gradle.buildinit.*
+org.gradle.caching.*
+org.gradle.concurrent.*
+org.gradle.deployment.*
+org.gradle.external.javadoc.*
+org.gradle.ide.*
+org.gradle.ivy.*
+org.gradle.jvm.*
+org.gradle.language.*
+org.gradle.maven.*
+org.gradle.nativeplatform.*
+org.gradle.normalization.*
+org.gradle.platform.*
+org.gradle.plugin.devel.*
+org.gradle.plugin.use
+org.gradle.plugin.management
+org.gradle.plugins.*
+org.gradle.process.*
+org.gradle.testfixtures.*
+org.gradle.testing.jacoco.*
+org.gradle.tooling.*
+org.gradle.swiftpm.*
+org.gradle.model.*
+org.gradle.testkit.*
+org.gradle.testing.*
+org.gradle.vcs.*
+org.gradle.work.*
+org.gradle.workers.*
+org.gradle.util.*
+----
+
+.Kotlin DSL API packages
+----
+org.gradle.kotlin.dsl
+org.gradle.kotlin.dsl.precompile
 ----
 
 === Alternatives for oft-used internal APIs