Adds docs for resolvers (#2084)

* Clean up parsing repositories for publishing

* Add documentation for resolvers

Author: romanowski

modules/cli/src/main/scala/scala/cli/commands/publish/RepoParams.scala

@@ -68,17 +68,12 @@ object RepoParams {
         }
         RepoParams.gitHubRepoFor(org, name)
       case repoStr =>
-        val repo0 = RepositoryParser.repositoryOpt(repoStr)
-          .collect {
-            case m: MavenRepository =>
-              m
-          }
-          .getOrElse {
-            val url =
-              if (repoStr.contains("://")) repoStr
-              else os.Path(repoStr, os.pwd).toNIO.toUri.toASCIIString
-            MavenRepository(url)
-          }
+        val repo0 = RepositoryParser.repositoryOpt(repoStr).getOrElse {
+          val url =
+            if (repoStr.contains("://")) repoStr
+            else os.Path(repoStr, os.pwd).toNIO.toUri.toASCIIString
+          MavenRepository(url)
+        }
 
         RepoParams(
           PublishRepository.Simple(repo0),

modules/cli/src/main/scala/scala/cli/commands/publish/RepositoryParser.scala

@@ -3,14 +3,14 @@ package scala.cli.commands.publish
 // from coursier.internal.SharedRepositoryParser
 // delete when coursier.internal.SharedRepositoryParser.repositoryOpt is available for us
 
-import coursier.Repositories
 import coursier.core.Repository
 import coursier.ivy.IvyRepository
 import coursier.maven.MavenRepository
+import coursier.{LocalRepositories, Repositories}
 
 object RepositoryParser {
 
-  def repositoryOpt(s: String): Option[Repository] =
+  def repositoryOpt(s: String): Option[MavenRepository] =
     if (s == "central")
       Some(Repositories.central)
     else if (s.startsWith("sonatype:"))
@@ -23,16 +23,10 @@ object RepositoryParser {
 
       Some(Repositories.bintray(id))
     }
-    else if (s.startsWith("bintray-ivy:"))
-      Some(Repositories.bintrayIvy(s.stripPrefix("bintray-ivy:")))
-    else if (s.startsWith("typesafe:ivy-"))
-      Some(Repositories.typesafeIvy(s.stripPrefix("typesafe:ivy-")))
     else if (s.startsWith("typesafe:"))
       Some(Repositories.typesafe(s.stripPrefix("typesafe:")))
     else if (s.startsWith("sbt-maven:"))
       Some(Repositories.sbtMaven(s.stripPrefix("sbt-maven:")))
-    else if (s.startsWith("sbt-plugin:"))
-      Some(Repositories.sbtPlugin(s.stripPrefix("sbt-plugin:")))
     else if (s == "scala-integration" || s == "scala-nightlies")
       Some(Repositories.scalaIntegration)
     else if (s == "jitpack")
@@ -53,24 +47,4 @@ object RepositoryParser {
       Some(Repositories.apache(s.stripPrefix("apache:")))
     else
       None
-
-  def repository(s: String): Either[String, Repository] =
-    repositoryOpt(s) match {
-      case Some(repo) => Right(repo)
-      case None =>
-        if (s.startsWith("ivy:")) {
-          val s0     = s.stripPrefix("ivy:")
-          val sepIdx = s0.indexOf('|')
-          if (sepIdx < 0)
-            IvyRepository.parse(s0)
-          else {
-            val mainPart     = s0.substring(0, sepIdx)
-            val metadataPart = s0.substring(sepIdx + 1)
-            IvyRepository.parse(mainPart, Some(metadataPart))
-          }
-        }
-        else
-          Right(MavenRepository(s))
-    }
-
 }

modules/cli/src/main/scala/scala/cli/commands/shared/SharedDependencyOptions.scala

@@ -4,6 +4,7 @@ import caseapp.*
 import com.github.plokhotnyuk.jsoniter_scala.core.*
 import com.github.plokhotnyuk.jsoniter_scala.macros.*
 
+import scala.build.preprocessing.directives.Repository
 import scala.cli.commands.tags
 
 // format: off
@@ -17,7 +18,7 @@ final case class SharedDependencyOptions(
   @Group(HelpGroup.Dependency.toString)
   @Tag(tags.should)
   @Tag(tags.inShortHelp)
-  @HelpMessage("Add repositories")
+  @HelpMessage(Repository.usageMsg)
   @Name("repo")
   @Name("r")
     repository: List[String] = Nil,

modules/directives/src/main/scala/scala/build/preprocessing/directives/Repository.scala

@@ -9,14 +9,15 @@ import scala.cli.commands.SpecificationLevel
 @DirectiveGroupName("Repository")
 @DirectiveExamples("//> using repository jitpack")
 @DirectiveExamples("//> using repository sonatype:snapshots")
+@DirectiveExamples("//> using repository m2Local")
 @DirectiveExamples(
   "//> using repository https://maven-central.storage-download.googleapis.com/maven2"
 )
 @DirectiveUsage(
   "//> using repository _repository_",
   "`//> using repository `_repository_"
 )
-@DirectiveDescription("Add a repository for dependency resolution")
+@DirectiveDescription(Repository.usageMsg)
 @DirectiveLevel(SpecificationLevel.SHOULD)
 // format: off
 final case class Repository(
@@ -36,4 +37,9 @@ final case class Repository(
 
 object Repository {
   val handler: DirectiveHandler[Repository] = DirectiveHandler.derive
+
+  val usageMsg =
+    """Add repositories for dependency resolution.
+      |
+      |Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository""".stripMargin
 }

website/docs/guides/dependencies.md

@@ -37,6 +37,41 @@ For example:
 org.postgresql:postgresql:42.2.8
 ```
 
+### Repositories
+
+Sometimes dependencies are published into non-standard repositories, like nightly builds published to Sonatype Snapshots. Scala CLI can use additional maven and ivy repositories with the `repository` directive or `--repository` command line options:
+
+```scala
+//> using repository sonatype:snapshots
+```
+
+or
+
+```bash ignore
+scala-cli --repository "https://maven-central.storage-download.googleapis.com/maven2"
+```
+
+Both directive and command line option accept predefined repository definitions (see below) or a URL of the root of Maven repository.
+
+Repositories can also be resolved from the `COURSIER_REPOSITORIES` environment variable, but this is not recommended (more in [Coursier documentation](https://get-coursier.io/docs/other-repositories)).
+
+#### Predefined repositories
+
+
+| predefined repository | kind | description  |
+| ---------- | ---- | --- |
+| central | Maven [(root)](https://repo1.maven.org/maven2) | Used by default, default repository for most Scala libraries |
+| sonatype:snapshots | Maven [(root)](https://oss.sonatype.org/content/repositories/snapshots) | Repositories where most Scala libraries publish its snapshots / nightly builds. Used when `X.nightly` is used as Scala version e.g. `3.1.nightly`. |
+| ivy2local | Ivy | Local ivy repository, used to publish things locally (e.g. by `publishLocal`). Localized in `<ivy-home>/local`, usually `<user-home>/.ivy/local`.    |
+| m2Local | Maven | Local maven repository, localized in `<user-home>/.m2/repository` |
+
+Scala CLI delegates parsing of predefined repositories to Coursier and full details can be obtains from Coursier source code ([here](https://github.com/coursier/coursier/blob/2444eebcc151e0f6927e269137e8737c1f31cbe2/modules/coursier/jvm/src/main/scala/coursier/LocalRepositories.scala) and [here](https://github.com/coursier/coursier/blob/2444eebcc151e0f6927e269137e8737c1f31cbe2/modules/coursier/shared/src/main/scala/coursier/internal/SharedRepositoryParser.scala))
+
+
+
+
+
+
 ### Excluding Transitive Dependencies
 
 To exclude a transitive dependency from a Scala CLI project use the `exclude` parameter:
@@ -98,7 +133,7 @@ It is possible to declare dependencies limited to the test scope with the `using
 `````
 
 More details can be found in
-the [`using` directives guide](./using-directives.md#directives-with-a-test-scope-equivalent).
+the [`using` directives guide](./using-directives#directives-with-a-test-scope-equivalent).
 
 ## Specifying dependencies from the command line
 
@@ -121,11 +156,11 @@ scala-cli compile Sample.sc \
 ```
 
 Note that `--dependency` is only meant as a convenience. You should favor adding dependencies in the sources themselves
-via [using directives](/docs/guides/configuration.md#special-imports). However, the `--dependency` CLI option takes
+via [using directives](./configuration#special-imports). However, the `--dependency` CLI option takes
 precedence over `using` directives, so it can be used to override a `using` directive, such as when you want to work
 with a different dependency version.
 
-You can also add repositories on the command-line, via `--repository`:
+You can also add repositories on the command-line, via `--repository` or `//> using repos`
 
 ```bash ignore
 scala-cli compile Sample.sc \

website/docs/reference/cli-options.md

@@ -257,7 +257,9 @@ Add dependencies
 
 Aliases: `-r`, `--repo`
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 ### `--compiler-plugin`
 

website/docs/reference/directives.md

@@ -235,7 +235,9 @@ Enable Python support
 
 ### Repository
 
-Add a repository for dependency resolution
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 `//> using repository `_repository_
 
@@ -244,6 +246,8 @@ Add a repository for dependency resolution
 
 `//> using repository sonatype:snapshots`
 
+`//> using repository m2Local`
+
 `//> using repository https://maven-central.storage-download.googleapis.com/maven2`
 
 ### Resource directories

website/docs/reference/scala-command/cli-options.md

@@ -226,7 +226,9 @@ Aliases: `-r`, `--repo`
 
 `SHOULD have` per Scala Runner specification
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 ### `--compiler-plugin`
 

website/docs/reference/scala-command/directives.md

@@ -180,7 +180,9 @@ Set the default platform to Scala.js or Scala Native
 
 ### Repository
 
-Add a repository for dependency resolution
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 `//> using repository `_repository_
 
@@ -189,6 +191,8 @@ Add a repository for dependency resolution
 
 `//> using repository sonatype:snapshots`
 
+`//> using repository m2Local`
+
 `//> using repository https://maven-central.storage-download.googleapis.com/maven2`
 
 ### Resource directories

website/docs/reference/scala-command/runner-specification.md

@@ -186,7 +186,9 @@ Embed resources into the Scala Native binary (can be read with the Java resource
 
 **--repository**
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 Aliases: `-r` ,`--repo`
 
@@ -900,7 +902,9 @@ Embed resources into the Scala Native binary (can be read with the Java resource
 
 **--repository**
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 Aliases: `-r` ,`--repo`
 
@@ -1431,7 +1435,9 @@ Embed resources into the Scala Native binary (can be read with the Java resource
 
 **--repository**
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 Aliases: `-r` ,`--repo`
 
@@ -1988,7 +1994,9 @@ Embed resources into the Scala Native binary (can be read with the Java resource
 
 **--repository**
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 Aliases: `-r` ,`--repo`
 
@@ -2564,7 +2572,9 @@ Embed resources into the Scala Native binary (can be read with the Java resource
 
 **--repository**
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 Aliases: `-r` ,`--repo`
 
@@ -3116,7 +3126,9 @@ Embed resources into the Scala Native binary (can be read with the Java resource
 
 **--repository**
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 Aliases: `-r` ,`--repo`
 
@@ -3705,7 +3717,9 @@ Embed resources into the Scala Native binary (can be read with the Java resource
 
 **--repository**
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 Aliases: `-r` ,`--repo`
 
@@ -4339,7 +4353,9 @@ Embed resources into the Scala Native binary (can be read with the Java resource
 
 **--repository**
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 Aliases: `-r` ,`--repo`
 
@@ -5186,7 +5202,9 @@ Embed resources into the Scala Native binary (can be read with the Java resource
 
 **--repository**
 
-Add repositories
+Add repositories for dependency resolution.
+
+Accepts predefined repositories supported by Coursier (like `sonatype:snapshots` or `m2Local`) or a URL of the root of Maven repository
 
 Aliases: `-r` ,`--repo`