Add descriptions for dep-tree check (#117)

* Add descriptions for dep-tree check

* Add schema.json

* Update README with new check information

Author: gabotechs

README.md

@@ -299,6 +299,9 @@ check:
 
 ### Example configuration file
 
+A `schema.json` file is provided in https://github.com/gabotechs/dep-tree/blob/main/schema.json which can be
+used in IDEs for providing autocompletion on `.dep-tree.yml` files.
+
 Dep Tree by default will read the configuration file in `.dep-tree.yml`, which is expected to be a file
 that contains the following settings:
 
@@ -360,6 +363,13 @@ check:
     'src/products/**':
       - 'src/products/**'
       - 'src/helpers/**'
+    # additionally, instead of providing a simple list of allowed dependencies, you
+    # can also provide the reason for this restriction to exist, that way, when if the
+    # check fails, an informative error is displayed through stderr.
+    'src/users/**':
+      to:
+        - 'src/helpers/**'
+      reason: The Users domain is only allowed to import helper code, nothing else
 
   # map from glob pattern to array of glob patterns that determines forbidden
   # dependencies. If a file that matches a key glob pattern depends on another
@@ -370,6 +380,14 @@ check:
     # as they are supposed to belong to different domains.
     'src/products/**':
       - 'src/users/**'
+    # additionally, instead of providing a simple list of forbidden dependencies, you
+    # can also provide the reason for each individual restriction to exist. If one of
+    # these rules is broken, the reason will be displayed through stderr
+    'src/users/**':
+      - to: 'src/products/**'
+        reason: The Users domain should not import anything from the Products domain
+      - to: 'src/orders/**'
+        reason: The Users domain should not import anything from the Orders domain
 
   # typically, in a project, there is a set of files that are always good to depend
   # on, because they are supposed to be common helpers, or parts that are actually

internal/check/check.go

@@ -26,22 +26,38 @@ func Check[T any](
 	if err != nil {
 		return err
 	}
+
 	// 2. Check for rule violations in the graph.
-	failures := make([]string, 0)
+	sb := strings.Builder{}
 	for _, node := range g.AllNodes() {
 		for _, dep := range g.FromId(node.Id) {
 			from, to := cfg.rel(node.Id), cfg.rel(dep.Id)
-			pass, err := cfg.Check(from, to)
+			pass, reason, err := cfg.Check(from, to)
 			if err != nil {
 				return err
 			} else if !pass {
-				failures = append(failures, from+" -> "+to)
+				sb.WriteString("- ")
+				sb.WriteString(from)
+				sb.WriteString(" -> ")
+				sb.WriteString(to)
+				if reason != "" {
+					for _, line := range strings.Split(reason, "\n") {
+						sb.WriteString("\n  ")
+						sb.WriteString(line)
+					}
+				}
+				sb.WriteString("\n")
 			}
 		}
 	}
 	// 3. Check for cycles.
 	cycles := g.RemoveElementaryCycles()
 	if !cfg.AllowCircularDependencies {
+		if len(cycles) > 0 {
+			sb.WriteString("\n")
+			sb.WriteString("detected circular dependencies:")
+			sb.WriteString("\n")
+		}
 		for _, cycle := range cycles {
 			formattedCycleStack := make([]string, len(cycle.Stack))
 			for i, el := range cycle.Stack {
@@ -52,64 +68,66 @@ func Check[T any](
 				}
 			}
 
-			msg := "detected circular dependency: " + strings.Join(formattedCycleStack, " -> ")
-			failures = append(failures, msg)
+			sb.WriteString("- ")
+			sb.WriteString(strings.Join(formattedCycleStack, " -> "))
+			sb.WriteString("\n")
 		}
 	}
-	if len(failures) > 0 {
-		return errors.New("Check failed, the following dependencies are not allowed:\n" + strings.Join(failures, "\n"))
+	errorMsg := sb.String()
+	if len(errorMsg) > 0 {
+		return errors.New("Check failed, the following dependencies are not allowed:\n" + errorMsg)
 	}
 	return nil
 }
 
-func (c *Config) whiteListCheck(from, to string) (bool, error) {
-	for k, v := range c.WhiteList {
+func (c *Config) whiteListCheck(from, to string) (bool, string, error) {
+	for k, rule := range c.WhiteList {
 		doesMatch, err := utils.GlobstarMatch(k, from)
 		if err != nil {
-			return false, err
+			return false, "", err
 		}
 		if doesMatch {
-			for _, dest := range v {
+			for _, dest := range rule.To {
 				shouldPass, err := utils.GlobstarMatch(dest, to)
 				if err != nil {
-					return false, err
+					return false, "", err
 				}
 				if shouldPass {
-					return true, nil
+					return true, "", nil
 				}
 			}
-			return false, nil
+			return false, rule.Reason, nil
 		}
 	}
-	return true, nil
+	return true, "", nil
 }
 
-func (c *Config) blackListCheck(from, to string) (bool, error) {
+func (c *Config) blackListCheck(from, to string) (bool, string, error) {
 	for k, v := range c.BlackList {
 		doesMatch, err := utils.GlobstarMatch(k, from)
 		if err != nil {
-			return false, err
+			return false, "", err
 		}
 		if doesMatch {
-			for _, dest := range v {
-				shouldReject, err := utils.GlobstarMatch(dest, to)
+			for _, rule := range v {
+				shouldReject, err := utils.GlobstarMatch(rule.To, to)
 				if err != nil {
-					return false, err
+					return false, "", err
 				}
 				if shouldReject {
-					return false, nil
+					return false, rule.Reason, nil
 				}
 			}
 		}
 	}
 
-	return true, nil
+	return true, "", nil
 }
 
-func (c *Config) Check(from, to string) (bool, error) {
-	pass, err := c.blackListCheck(from, to)
+func (c *Config) Check(from, to string) (bool, string, error) {
+	pass, reason, err := c.blackListCheck(from, to)
 	if err != nil || !pass {
-		return pass, err
+		return pass, reason, err
 	}
 	return c.whiteListCheck(from, to)
 }

internal/check/check_test.go

@@ -10,10 +10,10 @@ import (
 
 func TestCheck(t *testing.T) {
 	tests := []struct {
-		Name     string
-		Spec     [][]int
-		Config   *Config
-		Failures []string
+		Name    string
+		Spec    [][]int
+		Config  *Config
+		Failure string
 	}{
 		{
 			Name: "Simple",
@@ -26,18 +26,48 @@ func TestCheck(t *testing.T) {
 			},
 			Config: &Config{
 				Entrypoints: []string{"0"},
-				WhiteList: map[string][]string{
+				WhiteList: map[string]WhiteListEntries{
 					"4": {},
 				},
-				BlackList: map[string][]string{
-					"0": {"3"},
+				BlackList: map[string][]BlackListEntry{
+					"0": {{To: "3"}},
 				},
 			},
-			Failures: []string{
-				"0 -> 3",
-				"4 -> 3",
-				"detected circular dependency: 4 -> 3 -> 4",
+			Failure: `
+Check failed, the following dependencies are not allowed:
+- 0 -> 3
+- 4 -> 3
+
+detected circular dependencies:
+- 4 -> 3 -> 4`,
+		},
+		{
+			Name: "With description",
+			Spec: [][]int{
+				0: {1, 2, 3},
+				1: {2, 4},
+				2: {3, 4},
+				3: {4},
+				4: {3},
 			},
+			Config: &Config{
+				Entrypoints: []string{"0"},
+				WhiteList: map[string]WhiteListEntries{
+					"4": {Reason: "4 Should not be importing anything"},
+				},
+				BlackList: map[string][]BlackListEntry{
+					"0": {{To: "3", Reason: "0 should not import 3"}},
+				},
+			},
+			Failure: `
+Check failed, the following dependencies are not allowed:
+- 0 -> 3
+  0 should not import 3
+- 4 -> 3
+  4 Should not be importing anything
+
+detected circular dependencies:
+- 4 -> 3 -> 4`,
 		},
 	}
 
@@ -51,11 +81,11 @@ func TestCheck(t *testing.T) {
 				tt.Config,
 				nil,
 			)
-			if tt.Failures != nil {
-				msg := err.Error()
-				failures := strings.Split(msg, "\n")
-				failures = failures[1:]
-				a.Equal(tt.Failures, failures)
+			if tt.Failure != "" {
+				a.Equal(
+					strings.TrimSpace(tt.Failure),
+					strings.TrimSpace(err.Error()),
+				)
 			}
 		})
 	}

internal/check/config.go

@@ -2,11 +2,11 @@ package check
 
 type Config struct {
 	Path                      string
-	Entrypoints               []string            `yaml:"entrypoints"`
-	AllowCircularDependencies bool                `yaml:"allowCircularDependencies"`
-	Aliases                   map[string][]string `yaml:"aliases"`
-	WhiteList                 map[string][]string `yaml:"allow"`
-	BlackList                 map[string][]string `yaml:"deny"`
+	Entrypoints               []string                    `yaml:"entrypoints"`
+	AllowCircularDependencies bool                        `yaml:"allowCircularDependencies"`
+	Aliases                   map[string][]string         `yaml:"aliases"`
+	WhiteList                 map[string]WhiteListEntries `yaml:"allow"`
+	BlackList                 map[string][]BlackListEntry `yaml:"deny"`
 }
 
 func (c *Config) Init(path string) {
@@ -15,21 +15,85 @@ func (c *Config) Init(path string) {
 }
 
 func (c *Config) expandAliases() {
-	lists := []map[string][]string{
-		c.WhiteList,
-		c.BlackList,
+	for k, entries := range c.WhiteList {
+		newV := make([]string, 0)
+		for _, entry := range entries.To {
+			if aliases, ok := c.Aliases[entry]; ok {
+				newV = append(newV, aliases...)
+			} else {
+				newV = append(newV, entry)
+			}
+		}
+		c.WhiteList[k] = WhiteListEntries{
+			To:     newV,
+			Reason: entries.Reason,
+		}
 	}
-	for _, list := range lists {
-		for k, v := range list {
-			newV := make([]string, 0)
-			for _, entry := range v {
-				if alias, ok := c.Aliases[entry]; ok {
-					newV = append(newV, alias...)
-				} else {
-					newV = append(newV, entry)
+
+	for k, entries := range c.BlackList {
+		newV := make([]BlackListEntry, 0)
+		for _, entry := range entries {
+			if aliases, ok := c.Aliases[entry.To]; ok {
+				for _, alias := range aliases {
+					newV = append(newV, BlackListEntry{
+						To:     alias,
+						Reason: entry.Reason,
+					})
 				}
+			} else {
+				newV = append(newV, entry)
 			}
-			list[k] = newV
 		}
+		c.BlackList[k] = newV
+	}
+}
+
+type BlackListEntry struct {
+	To     string `yaml:"to"`
+	Reason string `yaml:"reason"`
+}
+
+func (v *BlackListEntry) UnmarshalYAML(unmarshal func(interface{}) error) error {
+	var str string
+	if err := unmarshal(&str); err == nil {
+		v.To = str
+		return nil
+	}
+	temp := struct {
+		To     string `yaml:"to"`
+		Reason string `yaml:"reason"`
+	}{}
+
+	err := unmarshal(&temp)
+	if err != nil {
+		return err
+	}
+	v.To = temp.To
+	v.Reason = temp.Reason
+	return nil
+}
+
+type WhiteListEntries struct {
+	To     []string `yaml:"to"`
+	Reason string   `yaml:"reason"`
+}
+
+func (v *WhiteListEntries) UnmarshalYAML(unmarshal func(interface{}) error) error {
+	var strList []string
+	if err := unmarshal(&strList); err == nil {
+		v.To = strList
+		return nil
+	}
+
+	temp := struct {
+		To     []string `yaml:"to"`
+		Reason string   `yaml:"reason"`
+	}{}
+	err := unmarshal(&temp)
+	if err != nil {
+		return err
 	}
+	v.To = temp.To
+	v.Reason = temp.Reason
+	return nil
 }