Enforce module family import boundaries

2026-07-17 13:58:50 +00:00
parent 3d3cc0c08e
commit 2df7084d5d
4 changed files with 180 additions and 79 deletions
--- a/internal/modules/import_boundaries_test.go
+++ b/internal/modules/import_boundaries_test.go
@@ -41,69 +41,145 @@ func TestImportBoundaryFixtureIsRejected(t *testing.T) {
 	fixture := filepath.Join(repositoryRoot, "internal", "modules", "generic", "testdata", "importboundaries", "imports_dnd.go")
 	err := checkImportBoundaries(repositoryRoot, fixture)
 	if err == nil {
-		t.Fatal("fixture import was accepted, want generic-to-D&D violation")
+		t.Fatal("fixture import was accepted, want generic-to-concrete violation")
 	}
-	if !strings.Contains(err.Error(), "generic packages must not import D&D packages") {
-		t.Fatalf("fixture error = %q, want generic-to-D&D violation", err)
+	if !strings.Contains(err.Error(), "generic family must not import concrete family") {
+		t.Fatalf("fixture error = %q, want generic-to-concrete violation", err)
 	}
 }

 func TestImportBoundaryRules(t *testing.T) {
 	tests := []struct {
-		name       string
-		filename   string
-		importPath string
-		wantError  bool
+		name          string
+		filename      string
+		sourcePackage string
+		importPath    string
+		wantError     bool
 	}{
 		{
-			name:       "D&D implementation cannot import Seriatim",
-			filename:   "internal/modules/dnd/extract/example/extractor.go",
-			importPath: moduleImportPrefix + "seriatim/input/transcript",
-			wantError:  true,
+			name:          "concrete implementation cannot import peer concrete family",
+			filename:      "internal/modules/dnd/extract/example/extractor.go",
+			sourcePackage: "example",
+			importPath:    moduleImportPrefix + "seriatim/input/transcript",
+			wantError:     true,
 		},
 		{
-			name:       "Seriatim implementation cannot import D&D",
-			filename:   "internal/modules/seriatim/input/example/adapter.go",
-			importPath: moduleImportPrefix + "dnd/shared",
-			wantError:  true,
+			name:          "future concrete family cannot import current concrete family",
+			filename:      "internal/modules/almanac/extract/example/extractor.go",
+			sourcePackage: "example",
+			importPath:    moduleImportPrefix + "dnd/shared",
+			wantError:     true,
 		},
 		{
-			name:       "generic implementation cannot import D&D",
-			filename:   "internal/modules/generic/merge/example/merger.go",
-			importPath: moduleImportPrefix + "dnd/shared",
-			wantError:  true,
+			name:          "current concrete family cannot import future concrete family",
+			filename:      "internal/modules/seriatim/input/example/adapter.go",
+			sourcePackage: "example",
+			importPath:    moduleImportPrefix + "almanac/shared",
+			wantError:     true,
 		},
 		{
-			name:       "domain root cannot import child",
-			filename:   "internal/modules/dnd/types.go",
-			importPath: moduleImportPrefix + "dnd/extract/spells",
-			wantError:  true,
+			name:          "generic implementation cannot import current concrete family",
+			filename:      "internal/modules/generic/merge/example/merger.go",
+			sourcePackage: "example",
+			importPath:    moduleImportPrefix + "dnd/shared",
+			wantError:     true,
 		},
 		{
-			name:       "D&D implementation may import generic implementation",
-			filename:   "internal/modules/dnd/extract/example/extractor.go",
-			importPath: moduleImportPrefix + "generic/normalize/noop",
+			name:          "generic implementation cannot import future concrete family",
+			filename:      "internal/modules/generic/merge/example/merger.go",
+			sourcePackage: "example",
+			importPath:    moduleImportPrefix + "almanac/shared",
+			wantError:     true,
 		},
 		{
-			name:       "domain registrar may compose child packages",
-			filename:   "internal/modules/dnd/register/register.go",
-			importPath: moduleImportPrefix + "dnd/extract/spells",
+			name:          "concrete implementation cannot import generic implementation",
+			filename:      "internal/modules/dnd/extract/example/extractor.go",
+			sourcePackage: "example",
+			importPath:    moduleImportPrefix + "generic/normalize/noop",
+			wantError:     true,
 		},
 		{
-			name:       "CLI may compose registrars",
-			filename:   "internal/cli/catalog.go",
-			importPath: moduleImportPrefix + "dnd/register",
+			name:          "concrete white-box test follows production rules",
+			filename:      "internal/modules/dnd/extract/example/extractor_test.go",
+			sourcePackage: "example",
+			importPath:    moduleImportPrefix + "generic/normalize/noop",
+			wantError:     true,
 		},
 		{
-			name:       "external integration test may compose domains",
-			filename:   "internal/modules/integration/example_test.go",
-			importPath: moduleImportPrefix + "dnd/extract/spells",
+			name:          "concrete registrar may compose generic implementation",
+			filename:      "internal/modules/almanac/register/register.go",
+			sourcePackage: "register",
+			importPath:    moduleImportPrefix + "generic/normalize/noop",
+		},
+		{
+			name:          "family root cannot import child implementation",
+			filename:      "internal/modules/almanac/types.go",
+			sourcePackage: "almanac",
+			importPath:    moduleImportPrefix + "almanac/extract/events",
+			wantError:     true,
+		},
+		{
+			name:          "family root cannot import registrar",
+			filename:      "internal/modules/almanac/types.go",
+			sourcePackage: "almanac",
+			importPath:    moduleImportPrefix + "almanac/register",
+			wantError:     true,
+		},
+		{
+			name:          "child may import family root",
+			filename:      "internal/modules/almanac/extract/events/extractor.go",
+			sourcePackage: "events",
+			importPath:    moduleImportPrefix + "almanac",
+		},
+		{
+			name:          "child may import same-family sibling",
+			filename:      "internal/modules/almanac/extract/events/extractor.go",
+			sourcePackage: "events",
+			importPath:    moduleImportPrefix + "almanac/shared",
+		},
+		{
+			name:          "concrete registrar may compose own child",
+			filename:      "internal/modules/almanac/register/register.go",
+			sourcePackage: "register",
+			importPath:    moduleImportPrefix + "almanac/extract/events",
+		},
+		{
+			name:          "generic registrar may compose generic child",
+			filename:      "internal/modules/generic/register/register.go",
+			sourcePackage: "register",
+			importPath:    moduleImportPrefix + "generic/output/json",
+		},
+		{
+			name:          "application composition root may compose registrars",
+			filename:      "internal/cli/catalog.go",
+			sourcePackage: "cli",
+			importPath:    moduleImportPrefix + "almanac/register",
+		},
+		{
+			name:          "black-box integration test may compose families",
+			filename:      "internal/modules/integration/example_test.go",
+			sourcePackage: "integration_test",
+			importPath:    moduleImportPrefix + "almanac/extract/events",
+		},
+		{
+			name:          "white-box integration test is not exempt",
+			filename:      "internal/modules/integration/example_test.go",
+			sourcePackage: "integration",
+			importPath:    moduleImportPrefix + "almanac/extract/events",
+			wantError:     true,
+		},
+		{
+			name:          "integration production file is not exempt",
+			filename:      "internal/modules/integration/example.go",
+			sourcePackage: "integration",
+			importPath:    moduleImportPrefix + "almanac/extract/events",
+			wantError:     true,
 		},
 	}

 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			err := validateImport(tt.filename, tt.importPath)
+			err := validateImport(tt.filename, tt.sourcePackage, tt.importPath)
 			if tt.wantError && err == nil {
 				t.Fatal("validateImport() error = nil, want boundary violation")
 			}
@@ -129,68 +205,77 @@ func checkImportBoundaries(repositoryRoot string, filename string) error {
 		if err != nil {
 			return fmt.Errorf("parse import in %s: %w", relative, err)
 		}
-		if err := validateImport(relative, importPath); err != nil {
+		if err := validateImport(relative, parsed.Name.Name, importPath); err != nil {
 			return fmt.Errorf("%s imports %s: %w", relative, importPath, err)
 		}
 	}
 	return nil
 }

-func validateImport(filename string, importPath string) error {
-	if isExternalIntegrationTest(filename) {
+func validateImport(filename string, sourcePackage string, importPath string) error {
+	if isBlackBoxIntegrationTest(filename, sourcePackage) {
 		return nil
 	}
-	sourceDomain, sourceRoot := domainForFile(filename)
-	targetDomain, targetChild := domainForImport(importPath)
-	if sourceDomain == "" || targetDomain == "" {
+	targetFamily, targetChild := moduleFamilyForImport(importPath)
+	if targetFamily == "" {
 		return nil
 	}
-	if sourceRoot && sourceDomain == targetDomain && targetChild {
-		return fmt.Errorf("domain root packages must not import child implementations")
+	if isIntegrationFile(filename) {
+		return fmt.Errorf("module integration composition is allowed only in black-box tests")
 	}
-	if sourceDomain == "generic" && targetDomain == "dnd" {
-		return fmt.Errorf("generic packages must not import D&D packages")
+	sourceFamily, sourceRoot, sourceRegistrar := moduleFamilyForFile(filename)
+	if sourceFamily == "" {
+		return nil
 	}
-	if sourceDomain == "dnd" && targetDomain == "seriatim" {
-		return fmt.Errorf("D&D packages must not import Seriatim packages")
+	if sourceRoot && sourceFamily == targetFamily && targetChild {
+		return fmt.Errorf("family root must not import child packages")
 	}
-	if sourceDomain == "seriatim" && targetDomain == "dnd" {
-		return fmt.Errorf("Seriatim packages must not import D&D packages")
+	if sourceFamily == targetFamily {
+		return nil
 	}
-	return nil
+	if sourceFamily == "generic" {
+		return fmt.Errorf("generic family must not import concrete family %q", targetFamily)
+	}
+	if targetFamily == "generic" {
+		if sourceRegistrar {
+			return nil
+		}
+		return fmt.Errorf("concrete family %q may import generic implementations only from its registrar", sourceFamily)
+	}
+	return fmt.Errorf("concrete family %q must not import concrete family %q", sourceFamily, targetFamily)
 }

-func domainForFile(filename string) (domain string, root bool) {
+func moduleFamilyForFile(filename string) (family string, root bool, registrar bool) {
 	const prefix = "internal/modules/"
 	if !strings.HasPrefix(filename, prefix) {
-		return "", false
+		return "", false, false
 	}
 	remainder := strings.TrimPrefix(filename, prefix)
 	parts := strings.Split(remainder, "/")
-	if len(parts) < 2 || !isDomain(parts[0]) {
-		return "", false
+	if len(parts) < 2 || parts[0] == "integration" {
+		return "", false, false
 	}
-	return parts[0], len(parts) == 2
+	return parts[0], len(parts) == 2, len(parts) > 2 && parts[1] == "register"
 }

-func domainForImport(importPath string) (domain string, child bool) {
+func moduleFamilyForImport(importPath string) (family string, child bool) {
 	if !strings.HasPrefix(importPath, moduleImportPrefix) {
 		return "", false
 	}
 	remainder := strings.TrimPrefix(importPath, moduleImportPrefix)
 	parts := strings.Split(remainder, "/")
-	if len(parts) == 0 || !isDomain(parts[0]) {
+	if len(parts) == 0 || parts[0] == "" || parts[0] == "integration" {
 		return "", false
 	}
 	return parts[0], len(parts) > 1
 }

-func isDomain(name string) bool {
-	return name == "dnd" || name == "generic" || name == "seriatim"
+func isIntegrationFile(filename string) bool {
+	return strings.HasPrefix(filename, "internal/modules/integration/")
 }

-func isExternalIntegrationTest(filename string) bool {
-	return strings.HasPrefix(filename, "internal/modules/integration/") && strings.HasSuffix(filename, "_test.go")
+func isBlackBoxIntegrationTest(filename string, sourcePackage string) bool {
+	return isIntegrationFile(filename) && strings.HasSuffix(filename, "_test.go") && sourcePackage == "integration_test"
 }

 func testRepositoryRoot(t *testing.T) string {