0.19: feat: Allow to customize generated package name (disneystreaming#1950) (disneystreaming#1967)

* feat: Allow to customize generated package name (disneystreaming#1950)

* feat: Allow to customize generated package name

* Add change log and documentation

* Update changelog

* Use information about previous mappings when calculating current mappings

* Add remapping example to bootstrapped

* Add cross-module reference test

* Add missing header

* Address review comments

---------

Co-authored-by: ghostbuster91 <ghostbuster91@users.noreply.github.com>

* Add changelog entry

* Fix compilation issues after port

* apply scalafix

* trigger CI

* feat: Add allowedNamespaces to smithy4sCodegen metadata; deprecate build-tool namespace settings

Adds `allowedNamespaces` to the `smithy4sCodegen` Smithy metadata key as the
counterpart to the existing `excludedNamespaces` field. When the build-tool
`allowedNamespaces` / `excludedNamespaces` settings are also set, the two
sources are unioned.

Deprecates the build-tool surface (sbt `smithy4sAllowedNamespaces` /
`smithy4sExcludedNamespaces`, mill equivalents, and CLI `--allowed-ns` /
`--excluded-ns`) in favor of the Smithy-metadata-based form so namespace
filtering can live with the model rather than the build.

* Apply scalafix

* fix: Make multimodule-package-prefix scripted test work under sbt 2

Two pre-existing issues left over from porting PR disneystreaming#1950 to the 0.19 series
were preventing this scripted test from running on the sbt 2 / Scala 3
plugin:

- Missing `excludeDependencies` block in `project/plugins.sbt` for the
  `_2.13` variants that conflict with `_3` under sbt 2 (other scripted
  tests have this same workaround).
- Path-based `$ exists` / `$ absent` assertions were hardcoded to sbt 1's
  `target/scala-2.13/src_managed/...` layout. Replaced them with sbt
  tasks that use `Compile / sourceManaged`, which resolves correctly
  under both sbt 1 and sbt 2.

---------

Co-authored-by: ghostbuster91 <ghostbuster91@users.noreply.github.com>

Author: ghostbuster91

CHANGELOG.md

@@ -5,6 +5,13 @@ When adding entries, please treat them as if they could end up in a release any
 
 Thank you!
 
+# 0.19.5 
+
+- Port of [#1950](https://github.com/disneystreaming/smithy4s/pull/1950) to 0.19 series
+  codegen: Add `smithy4sCodegen` metadata key for render-time package remapping. Supports `packagePrefix` (prepend a prefix to all generated packages), `packageMappings` (per-namespace overrides), and `excludedNamespaces` (skip namespaces from codegen). See [Package Remapping](https://disneystreaming.github.io/smithy4s/docs/codegen/customisation/package-remapping) for details.
+- codegen: Add `allowedNamespaces` field to the `smithy4sCodegen` Smithy metadata key — restricts codegen to the listed namespace patterns. When the build-tool `allowedNamespaces` / `excludedNamespaces` settings are also set, the two sources are unioned.
+- codegen: Deprecate the build-tool `allowedNamespaces` / `excludedNamespaces` settings (sbt `smithy4sAllowedNamespaces` / `smithy4sExcludedNamespaces`, the equivalent mill targets, and the CLI `--allowed-ns` / `--excluded-ns` flags) in favor of the `smithy4sCodegen` Smithy metadata key.
+
 # 0.19.4
 
 - Add documentation for `UrlForm` serialization in [#1929](https://github.com/disneystreaming/smithy4s/pull/1929)
@@ -119,6 +126,10 @@ Prevents using it as an implicit conversion in Scala 2
 
 The handwritten Java `TraitService` implementations for all smithy4s meta traits in the protocol module have been removed and are now generated by smithy4s itself. This should not affect users who are not programmatically using those traits directly. (see [#1901](https://github.com/disneystreaming/smithy4s/pull/1901))
 
+# 0.18.53
+
+* codegen: Add `smithy4sCodegen` metadata key for render-time package remapping. Supports `packagePrefix` (prepend a prefix to all generated packages), `packageMappings` (per-namespace overrides), and `excludedNamespaces` (skip namespaces from codegen). See [Package Remapping](https://disneystreaming.github.io/smithy4s/docs/codegen/customisation/package-remapping) for details.
+
 # 0.18.50
 
 * Add effectful `make` overloads to `UnaryClientCompiler` and `UnaryClientEndpoint` accepting `Response => F[Boolean]`

build.sbt

@@ -1138,7 +1138,9 @@ lazy val bootstrapped = projectMatrix
       "weather",
       "smithy4s.example.product",
       "smithy4s.example.reservedNameOverride",
-      "smithy4s.example.bincompat"
+      "smithy4s.example.bincompat",
+      "pkg.remapping",
+      "pkg.remapping.nested"
     ),
     smithySpecs := IO.listFiles(
       (ThisBuild / baseDirectory).value / "sampleSpecs"

modules/bootstrapped/src/generated/smithy4s/example/packageremapping/PackageRemappingExample.scala

@@ -0,0 +1,23 @@
+package smithy4s.example.packageremapping
+
+import smithy4s.Hints
+import smithy4s.Schema
+import smithy4s.ShapeId
+import smithy4s.ShapeTag
+import smithy4s.example.packageremapping.nested.NestedString
+import smithy4s.schema.Schema.struct
+
+final case class PackageRemappingExample(value: NestedString)
+
+object PackageRemappingExample extends ShapeTag.Companion[PackageRemappingExample] {
+  val id: ShapeId = ShapeId("pkg.remapping", "PackageRemappingExample")
+
+  val hints: Hints = Hints.empty
+
+  // constructor using the original order from the spec
+  private def make(value: NestedString): PackageRemappingExample = PackageRemappingExample(value)
+
+  implicit val schema: Schema[PackageRemappingExample] = struct[PackageRemappingExample](
+    NestedString.schema.required[PackageRemappingExample]("value", _.value),
+  )(make).withId(id).addHints(hints)
+}

modules/bootstrapped/src/generated/smithy4s/example/packageremapping/nested/NestedString.scala

@@ -0,0 +1,15 @@
+package smithy4s.example.packageremapping.nested
+
+import smithy4s.Hints
+import smithy4s.Newtype
+import smithy4s.Schema
+import smithy4s.ShapeId
+import smithy4s.schema.Schema.bijection
+import smithy4s.schema.Schema.string
+
+object NestedString extends Newtype[String] {
+  val id: ShapeId = ShapeId("pkg.remapping.nested", "NestedString")
+  val hints: Hints = Hints.empty
+  val underlyingSchema: Schema[String] = string.withId(id).addHints(hints)
+  implicit val schema: Schema[NestedString] = bijection(underlyingSchema, asBijection)
+}

modules/bootstrapped/src/generated/smithy4s/example/packageremapping/nested/package.scala

@@ -0,0 +1,7 @@
+package smithy4s.example.packageremapping
+
+package object nested {
+
+  type NestedString = smithy4s.example.packageremapping.nested.NestedString.Type
+
+}

modules/codegen-cli/src/smithy4s/codegen/cli/CodegenCommand.scala

@@ -79,7 +79,7 @@ object CodegenCommand {
     Opts
       .option[List[String]](
         "allowed-ns",
-        "Comma-delimited list of namespaces that should not be processed. If unset, all namespaces are processed (except stdlib ones)"
+        "Comma-delimited list of namespaces that should not be processed. If unset, all namespaces are processed (except stdlib ones). DEPRECATED: use the `smithy4sCodegen` Smithy metadata key with `allowedNamespaces` instead."
       )
       .map(_.toSet)
       .orNone
@@ -88,7 +88,7 @@ object CodegenCommand {
     Opts
       .option[List[String]](
         "excluded-ns",
-        "Comma-delimited list of namespaces that should not be processed. If unset, all namespaces are processed (except stdlib ones)"
+        "Comma-delimited list of namespaces that should not be processed. If unset, all namespaces are processed (except stdlib ones). DEPRECATED: use the `smithy4sCodegen` Smithy metadata key with `excludedNamespaces` instead."
       )
       .map(_.toSet)
       .orNone

modules/codegen-plugin/src/sbt-test/codegen-plugin/multimodule-package-prefix/a/src/main/smithy/first.smithy

@@ -0,0 +1,9 @@
+$version: "2.0"
+
+metadata smithy4sCodegen = {
+    packagePrefix: "gen"
+}
+
+namespace com.example.first
+
+string MyString

modules/codegen-plugin/src/sbt-test/codegen-plugin/multimodule-package-prefix/b/src/main/scala/BTest.scala

@@ -0,0 +1,26 @@
+/*
+ *  Copyright 2021-2026 Disney Streaming
+ *
+ *  Licensed under the Tomorrow Open Source Technology License, Version 1.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     https://disneystreaming.github.io/TOST-1.0.txt
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package example
+
+import com.example.second.Second
+import gen.com.example.first.MyString
+
+object BTest {
+  def main(args: Array[String]): Unit = {
+    println(Second(MyString("hello")))
+  }
+}

modules/codegen-plugin/src/sbt-test/codegen-plugin/multimodule-package-prefix/b/src/main/smithy/second.smithy

@@ -0,0 +1,10 @@
+$version: "2.0"
+
+namespace com.example.second
+
+use com.example.first#MyString
+
+structure Second {
+    @required
+    value: MyString
+}

modules/codegen-plugin/src/sbt-test/codegen-plugin/multimodule-package-prefix/build.sbt

@@ -0,0 +1,56 @@
+ThisBuild / scalaVersion := "2.13.18"
+
+// Module A generates code for `com.example.first` under a custom package prefix
+// (`gen`). It carries a smithy4sGenerated manifest entry listing
+// the namespace as already-generated AND its `renderedPackages` mapping
+// (com.example.first -> gen.com.example.first), so downstream modules can both
+// skip regenerating that namespace and resolve cross-namespace references to
+// the right Scala package.
+lazy val a = (project in file("a"))
+  .enablePlugins(Smithy4sCodegenPlugin)
+  .settings(
+    libraryDependencies += "com.disneystreaming.smithy4s" %% "smithy4s-core" % smithy4sVersion.value,
+    TaskKey[Unit]("checkLayout") := {
+      val src = (Compile / sourceManaged).value / "smithy4s"
+      val prefixed = src / "gen" / "com" / "example" / "first" / "MyString.scala"
+      val unprefixed = src / "com" / "example" / "first" / "MyString.scala"
+      assert(
+        prefixed.exists,
+        s"Expected $prefixed to exist"
+      )
+      assert(
+        !unprefixed.exists,
+        s"Expected $unprefixed to be absent"
+      )
+    }
+  )
+
+// Module B references `com.example.first#MyString` from its own
+// `com.example.second` shapes. It must NOT regenerate `com.example.first`, and
+// the Scala code it generates for `Second` must import the upstream-rendered
+// `gen.com.example.first.MyString` (otherwise compilation would fail).
+lazy val b = (project in file("b"))
+  .enablePlugins(Smithy4sCodegenPlugin)
+  .dependsOn(a)
+  .settings(
+    TaskKey[Unit]("checkLayout") := {
+      val src = (Compile / sourceManaged).value / "smithy4s"
+      val ownNs = src / "com" / "example" / "second" / "Second.scala"
+      val upstreamUnprefixed =
+        src / "com" / "example" / "first" / "MyString.scala"
+      val upstreamPrefixed =
+        src / "gen" / "com" / "example" / "first" / "MyString.scala"
+      assert(
+        ownNs.exists,
+        s"Expected $ownNs to exist"
+      )
+      assert(
+        !upstreamUnprefixed.exists,
+        s"Expected $upstreamUnprefixed to be absent (upstream namespace must not be regenerated)"
+      )
+      assert(
+        !upstreamPrefixed.exists,
+        s"Expected $upstreamPrefixed to be absent (upstream namespace must not be regenerated)"
+      )
+    }
+  )