1## Purpose
2
3`import-boss` enforces optional import restrictions between packages. This is
4useful to manage the dependency graph within a large repository, such as
5[kubernetes](https://github.com/kubernetes/kubernetes).
6
7## How does it work?
8
9When a package is verified, `import-boss` looks for a file called
10`.import-restrictions` in the same directory and all parent directories, up to
11the module root (defined by the presence of a go.mod file). These files
12contain rules which are evaluated against each dependency of the package in
13question.
14
15Evaluation starts with the rules file closest to the package. If that file
16makes a determination to allow or forbid the import, evaluation is done. If
17the import does not match any rule, the next-closest rules file is consulted,
18and so forth. If the rules files are exhausted and no determination has been
19made, the import will be flagged as an error.
20
21### What are rules files?
22
23A rules file is a JSON or YAML document with two top-level keys, both optional:
24* `Rules`
25* `InverseRules`
26
27### What are Rules?
28
29A `rule` defines a policy to be enforced on packages which are depended on by
30the package in question. It consists of three parts:
31 - A `SelectorRegexp`, to select the import paths that the rule applies to.
32 - A list of `AllowedPrefixes`
33 - A list of `ForbiddenPrefixes`
34
35An import is allowed if it matches at least one allowed prefix and does not
36match any forbidden prefixes.
37
38Rules also have a boolean `Transitive` option. When this option is true, the
39rule is applied to transitive imports.
40
41Example:
42
43```json
44{
45 "Rules": [
46 {
47 "SelectorRegexp": "example[.]com",
48 "AllowedPrefixes": [
49 "example.com/project/package",
50 "example.com/other/package"
51 ],
52 "ForbiddenPrefixes": [
53 "example.com/legacy/package"
54 ]
55 },
56 {
57 "SelectorRegexp": "^unsafe$",
58 "AllowedPrefixes": [],
59 "ForbiddenPrefixes": [ "" ],
60 "Transitive": true
61 }
62 ]
63}
64```
65
66The `SelectorRegexp` specifies that this rule applies only to imports which
67match that regex.
68
69Note: an empty list (`[]`) matches nothing, and an empty string (`""`) is a
70prefix of everything.
71
72### What are InverseRules?
73
74In contrast to rules, which are defined in terms of "things this package
75depends on", inverse rules are defined in terms of "things which import this
76package". This allows for fine-grained import restrictions for "semi-private
77packages" which are more sophisticated than Go's `internal` convention.
78
79If inverse rules are found, then all known imports of the package are checked
80against each such rule, in the same fashion as regular rules. Note that this
81can only handle known imports, which is defined as any package which is also
82being considered by this `import-boss` run. For most repositories, `./...` will
83suffice.
84
85Example:
86
87```yaml
88inverseRules:
89 - selectorRegexp: example[.]com
90 allowedPrefixes:
91 - example.com/this-same-repo
92 - example.com/close-friend/legacy
93 forbiddenPrefixes:
94 - example.com/other-project
95 - selectorRegexp: example[.]com
96 transitive: true
97 forbiddenPrefixes:
98 - example.com/other-team
99```
100
101## How do I run import-boss?
102
103For most scenarios, simply running `import-boss ./...` will work. For projects
104which use Go workspaces, this can even span multiple modules.
View as plain text