k8s.io/kubernetes@v1.31.0-alpha.0.0.20240520171757-56147500dadc/cmd/import-boss/README.md (about)

     1  ## Purpose
     2  
     3  `import-boss` enforces optional import restrictions between packages.  This is
     4  useful 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  
     9  When a package is verified, `import-boss` looks for a file called
    10  `.import-restrictions` in the same directory and all parent directories, up to
    11  the module root (defined by the presence of a go.mod file).  These files
    12  contain rules which are evaluated against each dependency of the package in
    13  question.
    14  
    15  Evaluation starts with the rules file closest to the package.  If that file
    16  makes a determination to allow or forbid the import, evaluation is done.  If
    17  the import does not match any rule, the next-closest rules file is consulted,
    18  and so forth.  If the rules files are exhausted and no determination has been
    19  made, the import will be flagged as an error.
    20  
    21  ### What are rules files?
    22  
    23  A 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  
    29  A `rule` defines a policy to be enforced on packages which are depended on by
    30  the 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  
    35  An import is allowed if it matches at least one allowed prefix and does not
    36  match any forbidden prefixes.
    37  
    38  Rules also have a boolean `Transitive` option. When this option is true, the
    39  rule is applied to transitive imports.
    40  
    41  Example:
    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  
    66  The `SelectorRegexp` specifies that this rule applies only to imports which
    67  match that regex.
    68  
    69  Note: an empty list (`[]`) matches nothing, and an empty string (`""`) is a
    70  prefix of everything.
    71  
    72  ### What are InverseRules?
    73  
    74  In contrast to rules, which are defined in terms of "things this package
    75  depends on", inverse rules are defined in terms of "things which import this
    76  package".  This allows for fine-grained import restrictions for "semi-private
    77  packages" which are more sophisticated than Go's `internal` convention.
    78  
    79  If inverse rules are found, then all known imports of the package are checked
    80  against each such rule, in the same fashion as regular rules.  Note that this
    81  can only handle known imports, which is defined as any package which is also
    82  being considered by this `import-boss` run.  For most repositories, `./...` will
    83  suffice.
    84  
    85  Example:
    86  
    87  ```yaml
    88  inverseRules:
    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  
   103  For most scenarios, simply running `import-boss ./...` will work.  For projects
   104  which use Go workspaces, this can even span multiple modules.