feat: use array with module field for allowed and blocked config

Replace map-based Allowed/Blocked config types with ordered slices of
AllowedModule/BlockedModule structs, each with an explicit module field.
Rename match_type to match-type to follow YAML kebab-case conventions.

Author: ryancurrah

README.md

@@ -39,30 +39,30 @@ Results can be exported to different report formats. Which can be imported into
 # When this section is non-empty, any module not matched by an entry is blocked.
 # When omitted entirely, all modules are allowed except those in the blocked list.
 allowed:
-  # Exact match (default when match_type is omitted).
-  go.yaml.in/yaml/v4:
-  github.com/go-xmlfmt/xmlfmt:
+  # Exact match (default when match-type is omitted).
+  - module: go.yaml.in/yaml/v4
+  - module: github.com/go-xmlfmt/xmlfmt
 
   # version constrains which versions of the module are allowed.
   # Uses semver constraint syntax (e.g. ">= 1.0.0", "~1.2", "== 2.5.0").
-  github.com/confluentinc/confluent-kafka-go/v2:
+  - module: github.com/confluentinc/confluent-kafka-go/v2
     version: "== 2.5.0"
 
-  # match_type controls how the key is matched against module paths.
+  # match-type controls how the module is matched against module paths.
   # Options: exact (default), prefix, regex
-  github.com/kubernetes:
-    match_type: prefix
-  github.com/apache/arrow-go:
-    match_type: prefix
-  "github.com/somecompany/.*":
-    match_type: regex
+  - module: github.com/kubernetes
+    match-type: prefix
+  - module: github.com/apache/arrow-go
+    match-type: prefix
+  - module: "github.com/somecompany/.*"
+    match-type: regex
 
 # blocked defines modules that are not permitted as direct dependencies.
 blocked:
-  github.com/uudashr/go-module:
-    # match_type controls how the key is matched against module paths.
+  - module: github.com/uudashr/go-module
+    # match-type controls how the module is matched against module paths.
     # Options: exact (default), prefix, regex
-    match_type: exact
+    match-type: exact
 
     # recommendations lists alternative modules to suggest in the lint error.
     recommendations:
@@ -71,18 +71,18 @@ blocked:
     # reason is a human-readable explanation appended to the lint error.
     reason: "`mod` is the official go.mod parser library."
 
-  github.com/mitchellh/go-homedir:
+  - module: github.com/mitchellh/go-homedir
     # version constrains which versions of the module are blocked.
     # Uses semver constraint syntax. When omitted, all versions are blocked.
     version: "<= 1.1.0"
     reason: "old versions have a known bug."
 
-  "github.com/badcompany/.*":
-    match_type: regex
+  - module: "github.com/badcompany/.*"
+    match-type: regex
     reason: "No badcompany packages are permitted."
 
-# Blocks 'replace' directives using local filesystem paths to prevent 
-# accidental commits of dev overrides. Sibling modules in multi-module 
+# Blocks 'replace' directives using local filesystem paths to prevent
+# accidental commits of dev overrides. Sibling modules in multi-module
 # repos are automatically detected and permitted.
 local_replace_directives: true
 ```
@@ -93,15 +93,16 @@ local_replace_directives: true
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `allowed` | map | *(none)* | Modules that are permitted. When non-empty, anything not matched is blocked. |
-| `blocked` | map | *(none)* | Modules that are explicitly blocked. |
+| `allowed` | list | *(none)* | Modules that are permitted. When non-empty, anything not matched is blocked. |
+| `blocked` | list | *(none)* | Modules that are explicitly blocked. |
 | `local_replace_directives` | bool | `false` | Block any module whose `replace` directive points to a local filesystem path. Multi-module repo aware: sibling modules whose replacement path contains a matching `go.mod` are not blocked. |
 
-#### `allowed` / `blocked` rule fields
+#### `allowed` / `blocked` entry fields
 
 | Field | Type | Description |
 |---|---|---|
-| `match_type` | `exact` \| `prefix` \| `regex` | How the rule key is matched against a module path. Defaults to `exact`. |
+| `module` | string | The module path to match against. |
+| `match-type` | `exact` \| `prefix` \| `regex` | How `module` is matched against dependency paths. Defaults to `exact`. |
 | `version` | semver constraint string | Restricts the rule to specific versions (e.g. `<= 1.2.0`, `>= 2.0.0`). When omitted, all versions match. |
 | `recommendations` | list of module paths | *(blocked only)* Alternative modules to suggest in the lint error. If the module being linted is itself in this list, the block is skipped. |
 | `reason` | string | *(blocked only)* Human-readable explanation appended to the lint error. |

allowed.go

@@ -6,19 +6,20 @@ import (
 	"github.com/Masterminds/semver/v3"
 )
 
-// Allowed is a map of modules or prefixes that are allowed to be used.
-type Allowed map[string]AllowedRule
+// Allowed is a list of modules that are allowed to be used.
+type Allowed []AllowedModule
 
-// AllowedRule defines the options for an allowed module.
-type AllowedRule struct {
-	MatchType MatchType           `yaml:"match_type"`
+// AllowedModule is a single entry in the allowed list.
+type AllowedModule struct {
+	Module    string              `yaml:"module"`
+	MatchType MatchType           `yaml:"match-type"`
 	Version   *semver.Constraints `yaml:"version"`
 	Matcher   Matcher             `yaml:"-"`
 }
 
 // CheckVersion returns true if the module version matches the allowed constraint,
 // or if no version constraint is specified.
-func (r *AllowedRule) CheckVersion(moduleVersion string) (bool, error) {
+func (r *AllowedModule) CheckVersion(moduleVersion string) (bool, error) {
 	if r.Version == nil {
 		return true, nil
 	}
@@ -32,18 +33,10 @@ func (r *AllowedRule) CheckVersion(moduleVersion string) (bool, error) {
 }
 
 // NotAllowedReason returns the reason why the module version is not allowed.
-func (r *AllowedRule) NotAllowedReason(moduleVersion string) string {
+func (r *AllowedModule) NotAllowedReason(moduleVersion string) string {
 	if r == nil || r.Version == nil {
 		return "the module is not in the allowed modules list."
 	}
 
 	return fmt.Sprintf("version `%s` does not meet the allowed version constraint `%s`.", moduleVersion, r.Version)
 }
-
-func (r *AllowedRule) ruleMatchType() MatchType {
-	return r.MatchType
-}
-
-func (r *AllowedRule) ruleMatcher() Matcher { //nolint:ireturn
-	return r.Matcher
-}

blocked.go

@@ -7,12 +7,13 @@ import (
 	"github.com/Masterminds/semver/v3"
 )
 
-// Blocked is a map of modules that are blocked and not to be used.
-type Blocked map[string]BlockedRule
+// Blocked is a list of modules that are blocked and not to be used.
+type Blocked []BlockedModule
 
-// BlockedRule represents a rule for a blocked module.
-type BlockedRule struct {
-	MatchType       MatchType           `yaml:"match_type"`
+// BlockedModule is a single entry in the blocked list.
+type BlockedModule struct {
+	Module          string              `yaml:"module"`
+	MatchType       MatchType           `yaml:"match-type"`
 	Recommendations []string            `yaml:"recommendations"`
 	Reason          string              `yaml:"reason"`
 	Version         *semver.Constraints `yaml:"version"`
@@ -21,7 +22,7 @@ type BlockedRule struct {
 
 // CheckVersion returns true if the module version matches the blocked constraint.
 // If no version constraint is specified, all versions are considered blocked.
-func (r *BlockedRule) CheckVersion(moduleVersion string) (bool, error) {
+func (r *BlockedModule) CheckVersion(moduleVersion string) (bool, error) {
 	if r.Version == nil {
 		return true, nil
 	}
@@ -35,7 +36,7 @@ func (r *BlockedRule) CheckVersion(moduleVersion string) (bool, error) {
 }
 
 // BlockReason returns the reason why the module or version is blocked.
-func (r *BlockedRule) BlockReason(currentModuleVersion string) string {
+func (r *BlockedModule) BlockReason(currentModuleVersion string) string {
 	var sb strings.Builder
 
 	if r.Version != nil {
@@ -74,7 +75,7 @@ func (r *BlockedRule) BlockReason(currentModuleVersion string) string {
 }
 
 // IsCurrentModuleARecommendation returns true if the current module is in the Recommendations list.
-func (r *BlockedRule) IsCurrentModuleARecommendation(currentModuleName string) bool {
+func (r *BlockedModule) IsCurrentModuleARecommendation(currentModuleName string) bool {
 	if r == nil {
 		return false
 	}
@@ -89,18 +90,10 @@ func (r *BlockedRule) IsCurrentModuleARecommendation(currentModuleName string) b
 }
 
 // HasRecommendations returns true if the blocked package has recommended modules.
-func (r *BlockedRule) HasRecommendations() bool {
+func (r *BlockedModule) HasRecommendations() bool {
 	if r == nil {
 		return false
 	}
 
 	return len(r.Recommendations) > 0
 }
-
-func (r *BlockedRule) ruleMatchType() MatchType {
-	return r.MatchType
-}
-
-func (r *BlockedRule) ruleMatcher() Matcher { //nolint:ireturn
-	return r.Matcher
-}

cmd/gomodguard/go.mod

@@ -8,7 +8,7 @@ require (
 	github.com/Masterminds/semver/v3 v3.4.0
 	github.com/mitchellh/go-homedir v1.1.0
 	github.com/phayes/checkstyle v0.0.0-20170904204023-bfd46e6a821d
-	github.com/ryancurrah/gomodguard/v2 v2.0.0
+	github.com/ryancurrah/gomodguard/v2 v2.0.1
 	github.com/stretchr/testify v1.11.1
 	go.yaml.in/yaml/v4 v4.0.0-rc.4
 )
@@ -20,4 +20,7 @@ require (
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
 
-retract v2.0.0
+retract (
+	v2.0.1
+	v2.0.0
+)

cmd/gomodguard/internal/cli/cli.go

@@ -6,7 +6,6 @@ import (
 	"flag"
 	"fmt"
 	"log"
-	"maps"
 	"os"
 	"path/filepath"
 	"runtime/debug"
@@ -114,8 +113,21 @@ func Run() int {
 		logger.Fatalf("error: %s", err)
 	}
 
-	logger.Printf("info: allowed modules, %+v", slices.Sorted(maps.Keys(config.Allowed)))
-	logger.Printf("info: blocked modules, %+v", slices.Sorted(maps.Keys(config.Blocked)))
+	allowedModuleNames := make([]string, len(config.Allowed))
+	for i, m := range config.Allowed {
+		allowedModuleNames[i] = m.Module
+	}
+
+	blockedModuleNames := make([]string, len(config.Blocked))
+	for i, m := range config.Blocked {
+		blockedModuleNames[i] = m.Module
+	}
+
+	slices.Sort(allowedModuleNames)
+	slices.Sort(blockedModuleNames)
+
+	logger.Printf("info: allowed modules, %+v", allowedModuleNames)
+	logger.Printf("info: blocked modules, %+v", blockedModuleNames)
 
 	results := processor.ProcessFiles(filteredFiles)
 

cmd/gomodguard/internal/cli/migrate.go

@@ -52,36 +52,48 @@ func MigrateConfig(filename string) int {
 	}
 
 	v2 := gomodguard.Configuration{
-		Allowed:                make(gomodguard.Allowed),
-		Blocked:                make(gomodguard.Blocked),
 		LocalReplaceDirectives: v1.Blocked.LocalReplaceDirectives,
 	}
 
 	for _, mod := range v1.Allowed.Modules {
-		v2.Allowed[mod] = gomodguard.AllowedRule{MatchType: gomodguard.ExactMatch}
+		v2.Allowed = append(v2.Allowed, gomodguard.AllowedModule{
+			Module:    mod,
+			MatchType: gomodguard.ExactMatch,
+		})
 	}
 
 	for _, pref := range v1.Allowed.Prefixes {
-		v2.Allowed[pref] = gomodguard.AllowedRule{MatchType: gomodguard.PrefixMatch}
+		v2.Allowed = append(v2.Allowed, gomodguard.AllowedModule{
+			Module:    pref,
+			MatchType: gomodguard.PrefixMatch,
+		})
 	}
 
 	for _, dom := range v1.Allowed.Domains {
-		v2.Allowed[dom] = gomodguard.AllowedRule{MatchType: gomodguard.PrefixMatch}
+		v2.Allowed = append(v2.Allowed, gomodguard.AllowedModule{
+			Module:    dom,
+			MatchType: gomodguard.PrefixMatch,
+		})
 	}
 
+	// Build a temporary map to merge modules and versions by module name.
+	blockedIndex := make(map[string]int)
+
 	for _, modMap := range v1.Blocked.Modules {
 		for modName, bm := range modMap {
-			rule := v2.Blocked[modName]
-			rule.MatchType = gomodguard.ExactMatch
-			rule.Recommendations = bm.Recommendations
-			rule.Reason = bm.Reason
-			v2.Blocked[modName] = rule
+			v2.Blocked = append(v2.Blocked, gomodguard.BlockedModule{
+				Module:          modName,
+				MatchType:       gomodguard.ExactMatch,
+				Recommendations: bm.Recommendations,
+				Reason:          bm.Reason,
+			})
+			blockedIndex[modName] = len(v2.Blocked) - 1
 		}
 	}
 
 	for _, versMap := range v1.Blocked.Versions {
 		for modName, bv := range versMap {
-			rule := v2.Blocked[modName]
+			var constraint *semver.Constraints
 
 			if bv.Version != "" {
 				c, err := semver.NewConstraint(bv.Version)
@@ -90,24 +102,28 @@ func MigrateConfig(filename string) int {
 					return 1
 				}
 
-				rule.Version = c
-			}
-
-			if bv.Reason != "" {
-				rule.Reason = bv.Reason
+				constraint = c
 			}
 
-			rule.MatchType = gomodguard.ExactMatch
-			v2.Blocked[modName] = rule
-		}
-	}
+			if idx, ok := blockedIndex[modName]; ok {
+				// Merge version info into existing entry.
+				entry := v2.Blocked[idx]
+				entry.Version = constraint
 
-	if len(v2.Allowed) == 0 {
-		v2.Allowed = nil
-	}
+				if bv.Reason != "" {
+					entry.Reason = bv.Reason
+				}
 
-	if len(v2.Blocked) == 0 {
-		v2.Blocked = nil
+				v2.Blocked[idx] = entry
+			} else {
+				v2.Blocked = append(v2.Blocked, gomodguard.BlockedModule{
+					Module:    modName,
+					MatchType: gomodguard.ExactMatch,
+					Version:   constraint,
+					Reason:    bv.Reason,
+				})
+			}
+		}
 	}
 
 	out, err := yaml.Marshal(v2)

cmd/gomodguard/internal/cli/processor_test.go

@@ -80,7 +80,7 @@ func TestProcessorYAMLConfig(t *testing.T) { //nolint:funlen
 		"allowed version - invalid constraint is caught at parse time": {
 			exampleDir:   examplesDir + "allowedversion",
 			wantParseErr: true,
-			invalidYAML:  "allowed:\n  github.com/Masterminds/semver/v3:\n    version: not-a-valid-constraint\n",
+			invalidYAML:  "allowed:\n  - module: github.com/Masterminds/semver/v3\n    version: not-a-valid-constraint\n",
 		},
 		"empty allow list - allows all modules": {
 			exampleDir: examplesDir + "emptyallowlist",

examples/alloptions/.gomodguard.yaml

@@ -1,19 +1,19 @@
 allowed:
-  gopkg.in/yaml.v3:
-  github.com/go-xmlfmt/xmlfmt:
-  github.com/Masterminds/semver/v3:
-  golang.org:
-    match_type: prefix
+  - module: gopkg.in/yaml.v3
+  - module: github.com/go-xmlfmt/xmlfmt
+  - module: github.com/Masterminds/semver/v3
+  - module: golang.org
+    match-type: prefix
 
 blocked:
-  github.com/uudashr/go-module:
+  - module: github.com/uudashr/go-module
     recommendations:
       - golang.org/x/mod
     reason: "`mod` is the official go.mod parser library."
-  github.com/gofrs/uuid:
+  - module: github.com/gofrs/uuid
     recommendations:
       - github.com/ryancurrah/gomodguard
     reason: "testing if module is not blocked when it is recommended."
-  github.com/mitchellh/go-homedir:
+  - module: github.com/mitchellh/go-homedir
     version: "<= 1.1.0"
     reason: "testing if blocked version constraint works."

examples/allowedversion/.gomodguard.yaml

@@ -1,3 +1,3 @@
 allowed:
-  github.com/Masterminds/semver/v3:
+  - module: github.com/Masterminds/semver/v3
     version: ">= 3.2.0"