allow to explicitly include typescript libraries

If you only want to generate ScalablyTyped facades for a few js dependencies, you currently have to maintain an ignore list in the build.sbt file.

In order to make this more explicit and easier to maintain, this PR introduces a new option `stExplicitInclude`, which allows to explicitly select the libraries, you want to process. All others are automatically ignored.

Usage:
```
// is None per default
stExplicitInclude := Some(List("packageA", "packageB"))
```

fixes ScalablyTyped#601

cli/src/main/scala/org/scalablytyped/converter/cli/Main.scala

@@ -37,6 +37,7 @@ object Main {
     enableScalaJsDefined     = Selection.All,
     flavour                  = Flavour.Normal,
     ignored                  = SortedSet("typescript"),
+    explicitlyIncluded       = None,
     stdLibs                  = SortedSet("es6"),
     expandTypeMappings       = EnabledTypeMappingExpansion.DefaultSelection,
     versions                 = Versions(Versions.Scala3, Versions.ScalaJs1),
@@ -155,6 +156,9 @@ object Main {
       opt[Seq[String]]("ignoredLibs")
         .action((x, c) => c.mapConversion(_.copy(ignored = x.toSet.sorted)))
         .text(s"Libraries you want to ignore"),
+      opt[Seq[String]]("explicitlyIncludedLibs")
+        .action((x, c) => c.mapConversion(_.copy(explicitlyIncluded = Some(x.toSet.sorted))))
+        .text(s"Libraries you want to explicitly include"),
       opt[String]("privateWithin")
         .action((x, c) => c.mapConversion(_.copy(privateWithin = Some(Name(x)))))
         .text(s"Libraries you want to ignore"),
@@ -263,6 +267,7 @@ object Main {
                 resolve                 = bootstrapped.libraryResolver,
                 ignored                 = conversion.ignoredLibs,
                 ignoredModulePrefixes   = conversion.ignoredModulePrefixes,
+                explicitlyIncluded      = conversion.explicitlyIncludedLibs,
                 pedantic                = false,
                 parser                  = PersistingParser(parseCachePath, bootstrapped.inputFolders, logger.void),
                 expandTypeMappings      = conversion.expandTypeMappings,

docs/conversion-options.md

@@ -40,6 +40,28 @@ project.settings(
 )
 ```
 
+### `stExplicitInclude`
+With many js dependencies, you might want to not automatically generate code for every depenendency, that you then need to ignore.
+You can explicitly list the packages or modules that should be processed instead:
+
+```scala
+project.settings(
+  stExplicitInclude := Some(List(
+    "is-object",
+    "is-number",
+  ))
+)
+```
+
+Be aware, that `stIgnore` takes precedence if you use it together with `stExplicitInclude`.
+
+Switch back to default behavior of processing every dependency:
+```scala
+project.settings(
+  stExplicitInclude := None
+)
+```
+
 ### `stIncludeDev`
 
 By default the plugin only includes dependencies defined with `npmDependencies`. 

importer-portable/src/main/scala/org/scalablytyped/converter/internal/importer/ConversionOptions.scala

@@ -17,13 +17,17 @@ case class ConversionOptions(
     stdLibs:                  SortedSet[String],
     expandTypeMappings:       Selection[TsIdentLibrary],
     ignored:                  SortedSet[String],
+    explicitlyIncluded:       Option[SortedSet[String]],
     versions:                 Versions,
     organization:             String,
     enableReactTreeShaking:   Selection[Name],
     enableLongApplyMethod:    Boolean,
     privateWithin:            Option[Name],
     useDeprecatedModuleNames: Boolean,
 ) {
+  val explicitlyIncludedLibs: Option[Set[TsIdentLibrary]] =
+    explicitlyIncluded.map(_.map(TsIdentLibrary.apply))
+
   val ignoredLibs: Set[TsIdentLibrary] =
     ignored.map(TsIdentLibrary.apply)
 

importer-portable/src/main/scala/org/scalablytyped/converter/internal/importer/Phase1ReadTypescript.scala

@@ -21,6 +21,7 @@ class Phase1ReadTypescript(
     calculateLibraryVersion: CalculateLibraryVersion,
     ignored:                 Set[TsIdentLibrary],
     ignoredModulePrefixes:   Set[List[String]],
+    explicitlyIncluded:      Option[Set[TsIdentLibrary]],
     pedantic:                Boolean,
     parser:                  InFile => Either[String, TsParsedFile],
     expandTypeMappings:      Selection[TsIdentLibrary],
@@ -47,7 +48,7 @@ class Phase1ReadTypescript(
   ): PhaseRes[LibTsSource, LibTs] = {
     source match {
       case source if ignored(source.libName) || isCircular => PhaseRes.Ignore()
-      case source =>
+      case source if explicitlyIncluded.forall(_(source.libName)) =>
         val includedFiles: IArray[InFile] =
           source match {
             case LibTsSource.StdLibSource(_, files, _) =>

importer/src/main/scala/org/scalablytyped/converter/internal/importer/Ci.scala

@@ -105,6 +105,7 @@ object Ci {
                 enableScalaJsDefined = Selection.All,
                 flavour              = flavour,
                 ignored              = Libraries.ignored.map(_.value),
+                explicitlyIncluded   = None,
                 stdLibs              = SortedSet("esnext.full"),
                 expandTypeMappings   = EnabledTypeMappingExpansion.DefaultSelection,
                 versions = Versions(
@@ -264,6 +265,7 @@ class Ci(config: Ci.Config, paths: Ci.Paths, pool: ForkJoinPool, ec: ExecutionCo
             resolve                 = bootstrapped.libraryResolver,
             ignored                 = config.conversion.ignoredLibs,
             ignoredModulePrefixes   = config.conversion.ignoredModulePrefixes,
+            explicitlyIncluded      = config.conversion.explicitlyIncludedLibs,
             pedantic                = config.pedantic,
             parser                  = PersistingParser(paths.parseCache, IArray(externalsFolder, dtFolder), logger.void),
             expandTypeMappings      = config.conversion.expandTypeMappings,

importer/src/test/scala/org/scalablytyped/converter/internal/importer/ImporterHarness.scala

@@ -87,6 +87,7 @@ trait ImporterHarness extends AnyFunSuite {
             calculateLibraryVersion = new DTVersions(DTLastChangedIndex.No, includeGitPart = false),
             ignored                 = ignored,
             ignoredModulePrefixes   = Set.empty,
+            explicitlyIncluded      = None,
             pedantic                = pedantic,
             parser                  = parser.parseFile,
             expandTypeMappings      = EnabledTypeMappingExpansion.DefaultSelection,

sbt-converter/src/main/scala/org/scalablytyped/converter/internal/ImportTypings.scala

@@ -83,6 +83,7 @@ object ImportTypings {
           calculateLibraryVersion = CalculateLibraryVersion.PackageJsonOnly,
           ignored                 = input.conversion.ignoredLibs,
           ignoredModulePrefixes   = input.conversion.ignoredModulePrefixes,
+          explicitlyIncluded      = input.conversion.explicitlyIncludedLibs,
           pedantic                = false,
           parser                  = cachedParser,
           expandTypeMappings      = input.conversion.expandTypeMappings,

sbt-converter/src/main/scala/org/scalablytyped/converter/internal/ImportTypingsGenSources.scala

@@ -69,6 +69,7 @@ object ImportTypingsGenSources {
           calculateLibraryVersion = CalculateLibraryVersion.PackageJsonOnly,
           ignored                 = input.conversion.ignoredLibs,
           ignoredModulePrefixes   = input.conversion.ignoredModulePrefixes,
+          explicitlyIncluded      = input.conversion.explicitlyIncludedLibs,
           pedantic                = false,
           parser                  = cachedParser,
           expandTypeMappings      = input.conversion.expandTypeMappings,
@@ -182,6 +183,7 @@ object ImportTypingsGenSources {
       stdLibs                  = SortedSet("es5", "dom"),
       expandTypeMappings       = EnabledTypeMappingExpansion.DefaultSelection,
       ignored                  = SortedSet(),
+      explicitlyIncluded       = None,
       versions                 = Versions(Versions.Scala213, Versions.ScalaJs1),
       organization             = "org.scalablytyped",
       enableReactTreeShaking   = Selection.None,

sbt-converter/src/main/scala/org/scalablytyped/converter/plugin/ScalablyTypedPluginBase.scala

@@ -30,6 +30,7 @@ object ScalablyTypedPluginBase extends AutoPlugin {
     val stConversionOptions = settingKey[ConversionOptions]("All conversion options")
     val stDir               = settingKey[File]("Directory used for caches, built artifacts and so on")
     val stIgnore            = settingKey[List[String]]("completely ignore libraries or modules")
+    val stExplicitInclude   = settingKey[Option[List[String]]]("explicitly select libraries or modules")
     val stFlavour           = settingKey[Flavour]("The type of react binding to use")
     val stEnableScalaJsDefined = settingKey[Selection[String]](
       "Whether to generate @ScalaJSDefined traits when possible",
@@ -67,6 +68,7 @@ object ScalablyTypedPluginBase extends AutoPlugin {
       },
       stFlavour := converter.Flavour.Normal,
       stIgnore := List("typescript"),
+      stExplicitInclude := None,
       stOutputPackage := Name.typings.unescaped,
       stStdlib := List("es6", "dom"),
       stTypescriptVersion := "4.3",
@@ -97,6 +99,7 @@ object ScalablyTypedPluginBase extends AutoPlugin {
           stdLibs                  = SortedSet.empty ++ stStdlib.value,
           expandTypeMappings       = stInternalExpandTypeMappings.value.map(TsIdentLibrary.apply),
           ignored                  = stIgnore.value.to[Set].sorted,
+          explicitlyIncluded       = stExplicitInclude.value.map(_.to[Set].sorted),
           versions                 = versions,
           organization             = organization,
           enableReactTreeShaking   = stReactEnableTreeShaking.value.map(name => ImportName(TsIdentLibrary(name))),