Dependency rules define what kind of dependencies you wish to block or allow in your software. If you want to know why dependency rules are important, you can find more information from this article. 

This straightforward rule tells that there should be no references from actual implementation to any test code. The other way around is perfectly fine though.

In real-world use your code paths and rule needs might be much more complex. This article helps you understand the full syntax of Softagram dependency rules and construct your own set of rules that you can place in the root of your git repository in the .softagram.json file.

If you have any issues working with the rules, please ping us in the chat - we are happy to help!

A more complex example with aliases, multiple source/target elements and different types of rules would be here:

This example defines that 1) production code in middleware and apps folders must not use any code in the tests folder and 2) only test code can have dependencies to apps folder. There is also a 3) GrepRule for defining that certain kinds of test code related imports can be only present in test folder. Source and target paths are simplified by using Aliases so that we avoid repeating the same long paths in multiple rules.

Example of dependency rule:

Every Softagram dependency rule has four mandatory fields:

and Optional settings, described farther below in this article.

Next we walk through all the fields; Dependency Rule Types,  the Source/Target elements, DependencyOperators and lastly Optional settings that are common for all Rule Types.

Softagram has tree rule types, DepRule is used to detect unwanted dependencies based on the Softagram dependency analysis. RexExpDepRule to use regular Expression to create more complex rules. GrepRule can be used for more complex cases, as it is not based on detected dependencies but pattern matching.

DepRule element can be used to set up simple element path based rules.  Example of DepRule:

The specification of the rule:

Source and Target paths are defined in section Element Paths
DependencyOperators are defined in section Dependency Operators
SettingsMap have only general settings defined in section Optional Settings
​

GrepRule is a bit different from the dependency rules. It can be used to perform grep statements and validate software based on the location of the grep matches. GrepRule supports "MustBeLocatedOnlyAt" and "MustNotBeLocatedAt" operators. When need to specify the whitelisting patterns, use MustBeLocatedOnlyAt operator. If blacklisting approach is needed, MustNotBeLocatedAt works for that purpose.

​Currently GrepRule is restricted to Java, C#, Python, JavaScript, TypeScript, C/C++, JSON, VBProj, CSProj and Kotlin code files.
​
For example, the example GrepRule below checks if the test code is located in correctly named directories:
​

With this rule in place, putting #include.*gtest.h in any file under any other directory than /test/ would trigger a dependency violation that is shown and alerted by Softagram. Thus effectively helping to avoid using test libraries in implementation code.

Using simply "src" as the location parameter, as above, to make something forbidden in all directories and files that contain src in the name. In case you need to make it forbidden everywhere, use empty list: []. This is good if you want to keep track of illegal words such as statements that configure hard coded secrets into source code.

When you want to define the source or target element as a regex that matches to multiple similar paths, use the RegExpDepRule as a Dependency Type

For each dependency A -> B, UserRegExp is matched against A and  UsedRegExp is matched against B. Also DepTypeRegExp is applied against dep type (e.g. “import”, "inc", "function_ref", "inherits"). Note that DepTypeRegExp can be left as empty string which matches to all dependency types. 

 Example:    

With these dependencies:

Dependencies 1 and 3 are not matched, but dependency 2 is matched.

 Example: #2   

This matches with all of the three dependencies above.

SettingsMap have  general settings defined in section Optional Settings and ReqExprDepRule specific settings.

ignore_patterns_if_both_equal: Regular expression that will be matched to both user path and used path and if both matches, the dependency will be ignored.

ignore_if_originating_from_src_to_siblings: By setting this as "true", it places additional constraint for the dependency matcher to ignore all dependencies where the user path contains src directory and the used path is located under the same src directory or in one of its siblings.

grouping:  in case of capturing groups are used in regular expression, it is possible to assign names for the groups, e.g. here the first group of the left (user) expression is named as pkg1, and the first group of the right (used) expression gets name pkg2.  

conditions:  Currently it supports == and != operators. It allows specifying constraints based on the state of the named variable parts. Below it requires pkg1 to have in-equal values of test and src. 

Source and target element paths follow the same syntax. Element path is a slash-delimited path of the element. We talk about element paths instead of file or folder paths, because in Softagram also classes and functions have paths. E.g. /ProjectX/main-repo/src/MyClass.java/MyClass/myFunction

You can use direct element path, multiple paths or aliases in the rule definitions.

Example of a short full path: /ProjectX/main-repo/src/file.h. Full path is always starting with a slash and the project name. Project name is the name of Softagram project! 

Three dots (...) in the beginning of the path looks the partial path everywhere, as in path ".../src/file.h". 

It is also possible to specify some directory as a named variable part using curly braces:   "/Project/repo1/{some-directory}/src"

If both source and target path refer to identically named variable part, the value of that variable part are required to be identical.(Update?)

To apply the same rule to multiple source or target paths, you can use a list of element paths instead of a single path, example below with "DepRule" and one source and 2 target paths:

To avoid repeating long element paths again and again, you can also define aliases for your most common paths that are used in multiple dependency rules.

After defining an alias like this, you can simply use "MyFile" as the source or target path instead of the full element path.

DependencyOperators between the source and target paths, e.g. "-!->", specifies the matching type. 

These are the operators:

The following general optional keys, also called a SettingsMap, can be set to any rule definition: 

We recommend always adding a description that tells why the rule exists, as it will be shown up in code-review when someone breaks the rule. You add the description with following format inside the SettingsMap:

DepRule and GrepRule may have severity in the settings map. It defines the directives that can adjust the severity of the rule match. These directives are applied so that for any dependency, the last matching directive is effective. Severity directive has four parts: 

Example: severity directives for an example rule:

In this case the first directive sets all matches of the rule to be warning while some exception cases are set to be ignored. By switching the order of the directives it is possible to turn around how the matching works. In this case opposite order would indicate all matches to be warning, as there is empty string used as the element path. The empty string indicates to match all elements.

Rule severity can be any of critical (default, displayed in red), warning (displayed in yellow), info (displayed in blue), or ignored.

Softagram offers two ways to add new dependency rules for your project:

We recommend using the .softagram.json  approach, as this allows you to keep your dependency rules in version control, making it easier to maintain. However, when you want to quickly test a new rule without making changes to your git repository, you can use the settings in Softagram web UI. If you define any rules in the Softagram web UI, any rules defined in .softagram.json are dismissed. They'll become active again when you empty up the dependency rules in web UI.
​