feat(source-layout): enforce schema-level architecture contracts with package-info markers

Author: bsayli

src/main/java/io/github/blueprintplatform/codegen/adapter/out/framework/springboot/java/source/SourceLayoutAdapter.java

@@ -6,6 +6,8 @@
 import io.github.blueprintplatform.codegen.domain.model.value.pkg.PackageName;
 import io.github.blueprintplatform.codegen.domain.port.out.artifact.GeneratedDirectory;
 import io.github.blueprintplatform.codegen.domain.port.out.artifact.GeneratedResource;
+import io.github.blueprintplatform.codegen.domain.port.out.artifact.GeneratedTextResource;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
@@ -49,6 +51,14 @@ public class SourceLayoutAdapter implements SourceLayoutPort {
           Path.of("domain", "model"),
           Path.of("domain", "service"));
 
+  private static final List<String> HEX_TOP_LEVEL_FAMILIES =
+      List.of("adapter", "application", "domain", "bootstrap");
+
+  private static final List<String> STANDARD_TOP_LEVEL_FAMILIES =
+      List.of("controller", "service", "repository", "domain", "config");
+
+  private static final String PACKAGE_INFO_FILE = "package-info.java";
+
   @Override
   public ArtifactKey artifactKey() {
     return ArtifactKey.SOURCE_LAYOUT;
@@ -65,12 +75,29 @@ public Iterable<? extends GeneratedResource> generate(ProjectBlueprint blueprint
     addDirectories(resources, COMMON_DIRS);
     addDirectories(resources, List.of(mainBasePackageDir, testBasePackageDir));
 
-    var segments = blueprint.getArchitecture().layout().isHexagonal() ? HEX_DIRS : STANDARD_DIRS;
+    var isHex = blueprint.getArchitecture().layout().isHexagonal();
+
+    var segments = isHex ? HEX_DIRS : STANDARD_DIRS;
     addDirectoriesUnder(resources, mainBasePackageDir, segments);
 
+    addTopLevelPackageInfoMarkers(resources, mainBasePackageDir, packageName, isHex);
+
     return List.copyOf(resources);
   }
 
+  private void addTopLevelPackageInfoMarkers(
+      List<GeneratedResource> out,
+      Path mainBasePackageDir,
+      PackageName basePackage,
+      boolean isHex) {
+    var families = isHex ? HEX_TOP_LEVEL_FAMILIES : STANDARD_TOP_LEVEL_FAMILIES;
+    for (var family : families) {
+      var relativePath = mainBasePackageDir.resolve(family).resolve(PACKAGE_INFO_FILE);
+      var content = "package " + basePackage.value() + "." + family + ";\n";
+      out.add(new GeneratedTextResource(relativePath, content, StandardCharsets.UTF_8));
+    }
+  }
+
   private Path resolveBasePackageDir(Path javaRoot, PackageName packageName) {
     var pkgPath = Path.of(packageName.value().replace('.', '/'));
     return javaRoot.resolve(pkgPath);

src/main/resources/templates/springboot/java/governance/standard/strict/StandardUnknownFamilyTest.java.ftl

@@ -34,6 +34,8 @@ import org.junit.jupiter.api.Assertions;
  * Contract note:
  * - If this test fails, at least one bounded context contains code that does not conform
  *   to the generated STANDARD package contract (likely a rename-based escape).
+ * - If this test fails due to no detected bounded context, it indicates guardrails are effectively disabled
+ *   (e.g. canonical family renamed, root structure altered, or no controller exists while strict guardrails are enabled).
  */
 @AnalyzeClasses(
         packages = BASE_PACKAGE,
@@ -54,7 +56,12 @@ class StandardUnknownFamilyTest {
         var contexts = detectControllerContexts(classes);
 
         if (contexts.isEmpty()) {
-            return;
+            Assertions.fail(
+                    "No STANDARD bounded context was detected under scope '" + BASE_PACKAGE + "'. "
+                            + "Expected at least one context containing '" + CONTROLLER + "'. "
+                            + "This may indicate that the root package or canonical family names were changed "
+                            + "(or that no controller exists while strict guardrails are enabled)."
+            );
         }
 
         var violationsByContext = new TreeMap<String, Set<String>>();

src/test/java/io/github/blueprintplatform/codegen/adapter/out/framework/springboot/java/source/SourceLayoutAdapterTest.java

@@ -4,7 +4,6 @@
 
 import io.github.blueprintplatform.codegen.application.port.out.artifact.ArtifactKey;
 import io.github.blueprintplatform.codegen.domain.model.ProjectBlueprint;
-import io.github.blueprintplatform.codegen.domain.model.value.architecture.ArchitectureGovernance;
 import io.github.blueprintplatform.codegen.domain.model.value.architecture.ArchitectureSpec;
 import io.github.blueprintplatform.codegen.domain.model.value.dependency.Dependencies;
 import io.github.blueprintplatform.codegen.domain.model.value.identity.ArtifactId;
@@ -26,6 +25,7 @@
 import io.github.blueprintplatform.codegen.domain.model.value.tech.stack.TechStack;
 import io.github.blueprintplatform.codegen.domain.port.out.artifact.GeneratedDirectory;
 import io.github.blueprintplatform.codegen.domain.port.out.artifact.GeneratedResource;
+import io.github.blueprintplatform.codegen.domain.port.out.artifact.GeneratedTextResource;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
@@ -54,57 +54,55 @@ private static ProjectBlueprint blueprint(ProjectLayout layout) {
             new TechStack(Framework.SPRING_BOOT, BuildTool.MAVEN, Language.JAVA),
             new SpringBootJvmTarget(JavaVersion.JAVA_21, SpringBootVersion.V3_5));
 
-    ArchitectureSpec architecture =
-        new ArchitectureSpec(layout, ArchitectureGovernance.none(), SampleCodeOptions.none());
+    ArchitectureSpec architecture = new ArchitectureSpec(layout, null, SampleCodeOptions.none());
 
     Dependencies dependencies = Dependencies.of(List.of());
 
     return ProjectBlueprint.of(metadata, platform, architecture, dependencies);
   }
 
-  private static List<Path> toRelativePaths(Iterable<? extends GeneratedResource> resources) {
+  private static List<Path> directoriesOf(Iterable<? extends GeneratedResource> resources) {
     List<Path> result = new ArrayList<>();
     StreamSupport.stream(resources.spliterator(), false)
-        .forEach(
-            r -> {
-              assertThat(r).isInstanceOf(GeneratedDirectory.class);
-              result.add(r.relativePath());
-            });
+        .filter(r -> r instanceof GeneratedDirectory)
+        .forEach(r -> result.add(r.relativePath()));
+    return result;
+  }
+
+  private static List<Path> textFilesOf(Iterable<? extends GeneratedResource> resources) {
+    List<Path> result = new ArrayList<>();
+    StreamSupport.stream(resources.spliterator(), false)
+        .filter(r -> r instanceof GeneratedTextResource)
+        .forEach(r -> result.add(r.relativePath()));
     return result;
   }
 
   @Test
   @DisplayName("artifactKey() should return SOURCE_LAYOUT")
   void artifactKey_shouldReturnSourceLayout() {
     SourceLayoutAdapter adapter = new SourceLayoutAdapter();
-
     assertThat(adapter.artifactKey()).isEqualTo(ArtifactKey.SOURCE_LAYOUT);
   }
 
   @Test
-  @DisplayName(
-      "generate() with STANDARD layout should create base/package directories and layered sub-packages")
-  void generate_standardLayout_shouldCreateLayeredSubPackages() {
+  @DisplayName("generate() with STANDARD layout should create directories and package-info markers")
+  void generate_standardLayout_shouldCreateLayeredSubPackagesAndMarkers() {
     SourceLayoutAdapter adapter = new SourceLayoutAdapter();
     ProjectBlueprint blueprint = blueprint(ProjectLayout.STANDARD);
 
     Iterable<? extends GeneratedResource> resources = adapter.generate(blueprint);
-    List<Path> paths = toRelativePaths(resources);
 
     Path mainBase = Path.of("src", "main", "java").resolve(BASE_PACKAGE_PATH);
     Path testBase = Path.of("src", "test", "java").resolve(BASE_PACKAGE_PATH);
 
-    List<Path> expected =
+    List<Path> expectedDirs =
         List.of(
-            // common dirs
             Path.of("src", "main", "java"),
             Path.of("src", "test", "java"),
             Path.of("src", "main", "resources"),
             Path.of("src", "test", "resources"),
-            // base package dirs
             mainBase,
             testBase,
-            // standard layered sub-packages (under main base package only)
             mainBase.resolve("controller"),
             mainBase.resolve(Path.of("controller", "dto")),
             mainBase.resolve("service"),
@@ -114,33 +112,38 @@ void generate_standardLayout_shouldCreateLayeredSubPackages() {
             mainBase.resolve(Path.of("domain", "model")),
             mainBase.resolve(Path.of("domain", "service")));
 
-    assertThat(paths).containsExactlyInAnyOrderElementsOf(expected).hasSize(expected.size());
+    List<Path> expectedMarkers =
+        List.of(
+            mainBase.resolve(Path.of("controller", "package-info.java")),
+            mainBase.resolve(Path.of("service", "package-info.java")),
+            mainBase.resolve(Path.of("repository", "package-info.java")),
+            mainBase.resolve(Path.of("domain", "package-info.java")),
+            mainBase.resolve(Path.of("config", "package-info.java")));
+
+    assertThat(directoriesOf(resources)).containsExactlyInAnyOrderElementsOf(expectedDirs);
+    assertThat(textFilesOf(resources)).containsExactlyInAnyOrderElementsOf(expectedMarkers);
   }
 
   @Test
   @DisplayName(
-      "generate() with HEXAGONAL layout should create base/package directories and hexagonal sub-packages")
-  void generate_hexagonalLayout_shouldCreateHexagonalSubPackages() {
+      "generate() with HEXAGONAL layout should create directories and package-info markers")
+  void generate_hexagonalLayout_shouldCreateHexagonalSubPackagesAndMarkers() {
     SourceLayoutAdapter adapter = new SourceLayoutAdapter();
     ProjectBlueprint blueprint = blueprint(ProjectLayout.HEXAGONAL);
 
     Iterable<? extends GeneratedResource> resources = adapter.generate(blueprint);
-    List<Path> paths = toRelativePaths(resources);
 
     Path mainBase = Path.of("src", "main", "java").resolve(BASE_PACKAGE_PATH);
     Path testBase = Path.of("src", "test", "java").resolve(BASE_PACKAGE_PATH);
 
-    List<Path> expected =
+    List<Path> expectedDirs =
         List.of(
-            // common dirs
             Path.of("src", "main", "java"),
             Path.of("src", "test", "java"),
             Path.of("src", "main", "resources"),
             Path.of("src", "test", "resources"),
-            // base package dirs
             mainBase,
             testBase,
-            // hexagonal sub-packages (under main base package only)
             mainBase.resolve("adapter"),
             mainBase.resolve(Path.of("adapter", "in")),
             mainBase.resolve(Path.of("adapter", "out")),
@@ -157,6 +160,14 @@ void generate_hexagonalLayout_shouldCreateHexagonalSubPackages() {
             mainBase.resolve(Path.of("domain", "port", "out")),
             mainBase.resolve(Path.of("domain", "service")));
 
-    assertThat(paths).containsExactlyInAnyOrderElementsOf(expected).hasSize(expected.size());
+    List<Path> expectedMarkers =
+        List.of(
+            mainBase.resolve(Path.of("adapter", "package-info.java")),
+            mainBase.resolve(Path.of("application", "package-info.java")),
+            mainBase.resolve(Path.of("domain", "package-info.java")),
+            mainBase.resolve(Path.of("bootstrap", "package-info.java")));
+
+    assertThat(directoriesOf(resources)).containsExactlyInAnyOrderElementsOf(expectedDirs);
+    assertThat(textFilesOf(resources)).containsExactlyInAnyOrderElementsOf(expectedMarkers);
   }
 }

src/test/java/io/github/blueprintplatform/codegen/architecture/archunit/DependencyDirectionArchitectureTest.java

@@ -19,8 +19,6 @@ class DependencyDirectionArchitectureTest {
   private static final String APPLICATION_ROOT = BASE_PACKAGE + ".application..";
   private static final String APPLICATION_PORTS = BASE_PACKAGE + ".application.port..";
   private static final String ADAPTER_ROOT = BASE_PACKAGE + ".adapter..";
-  private static final String BOOTSTRAP_ROOT = BASE_PACKAGE + ".bootstrap..";
-
   @ArchTest
   static final ArchRule application_implementation_must_not_depend_on_adapters =
       noClasses()
@@ -32,7 +30,6 @@ class DependencyDirectionArchitectureTest {
           .dependOnClassesThat()
           .resideInAnyPackage(ADAPTER_ROOT)
           .allowEmptyShould(true);
-
   @ArchTest
   static final ArchRule adapters_must_not_depend_on_application_implementation =
       noClasses()
@@ -41,7 +38,7 @@ class DependencyDirectionArchitectureTest {
           .should()
           .dependOnClassesThat(applicationImplementation())
           .allowEmptyShould(true);
-
+  private static final String BOOTSTRAP_ROOT = BASE_PACKAGE + ".bootstrap..";
   @ArchTest
   static final ArchRule bootstrap_must_not_be_depended_on =
       noClasses()