github.com/bazelbuild/bazel-gazelle@v0.36.1-0.20240520142334-61b277ba6fed/language/update.go (about)

     1  /* Copyright 2019 The Bazel Authors. All rights reserved.
     2  
     3  Licensed under the Apache License, Version 2.0 (the "License");
     4  you may not use this file except in compliance with the License.
     5  You may obtain a copy of the License at
     6  
     7     http://www.apache.org/licenses/LICENSE-2.0
     8  
     9  Unless required by applicable law or agreed to in writing, software
    10  distributed under the License is distributed on an "AS IS" BASIS,
    11  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  See the License for the specific language governing permissions and
    13  limitations under the License.
    14  */
    15  
    16  package language
    17  
    18  import (
    19  	"github.com/bazelbuild/bazel-gazelle/config"
    20  	"github.com/bazelbuild/bazel-gazelle/repo"
    21  	"github.com/bazelbuild/bazel-gazelle/rule"
    22  )
    23  
    24  // RepoUpdater may be implemented by languages that support updating
    25  // repository rules that provide named libraries.
    26  //
    27  // EXPERIMENTAL: this may change or be removed.
    28  type RepoUpdater interface {
    29  	UpdateRepos(args UpdateReposArgs) UpdateReposResult
    30  }
    31  
    32  // UpdateReposArgs contains arguments for RepoUpdater.UpdateRepos.
    33  // Arguments are passed in a struct value so that new fields may be added
    34  // in the future without breaking existing implementations.
    35  //
    36  // EXPERIMENTAL: this may change or be removed.
    37  type UpdateReposArgs struct {
    38  	// Config is the configuration for the main workspace.
    39  	Config *config.Config
    40  
    41  	// Imports is a list of libraries to update. UpdateRepos should return
    42  	// repository rules that provide these libraries. It may also return
    43  	// repository rules providing transitive dependencies.
    44  	Imports []string
    45  
    46  	// Cache stores information fetched from the network and ensures that
    47  	// the same request isn't made multiple times.
    48  	Cache *repo.RemoteCache
    49  }
    50  
    51  // UpdateReposResult contains return values for RepoUpdater.UpdateRepos.
    52  // Results are returned through a struct so that new (optional) fields may be
    53  // added without breaking existing implementations.
    54  //
    55  // EXPERIMENTAL: this may change or be removed.
    56  type UpdateReposResult struct {
    57  	// Gen is a list of repository rules that provide libraries named by
    58  	// UpdateImportArgs.Imports. These will be merged with existing rules or
    59  	// added to WORKSPACE. This list may be shorter or longer than the list
    60  	// of imports, since a single repository may provide multiple imports,
    61  	// and additional repositories may be needed for transitive dependencies.
    62  	Gen []*rule.Rule
    63  
    64  	// Error is any fatal error that occurred. Non-fatal errors should be logged.
    65  	Error error
    66  }
    67  
    68  // RepoImporter may be implemented by languages that support importing
    69  // repository rules from another build system.
    70  //
    71  // EXPERIMENTAL: this may change or be removed.
    72  type RepoImporter interface {
    73  	// CanImport returns whether a given configuration file may be imported
    74  	// with this extension. Only one extension may import any given file.
    75  	// ImportRepos will not be called unless this returns true.
    76  	CanImport(path string) bool
    77  
    78  	// ImportRepos generates a list of repository rules by reading a
    79  	// configuration file from another build system.
    80  	ImportRepos(args ImportReposArgs) ImportReposResult
    81  }
    82  
    83  // ImportReposArgs contains arguments for RepoImporter.ImportRepos.
    84  // Arguments are passed in a struct value so that new fields may be added
    85  // in the future without breaking existing implementations.
    86  //
    87  // EXPERIMENTAL: this may change or be removed.
    88  type ImportReposArgs struct {
    89  	// Config is the configuration for the main workspace.
    90  	Config *config.Config
    91  
    92  	// Path is the name of the configuration file to import.
    93  	Path string
    94  
    95  	// Prune indicates whether repository rules that are no longer needed
    96  	// should be deleted. This means the Empty list in the result should be
    97  	// filled in.
    98  	Prune bool
    99  
   100  	// Cache stores information fetched from the network and ensures that
   101  	// the same request isn't made multiple times.
   102  	Cache *repo.RemoteCache
   103  }
   104  
   105  // ImportReposResult contains return values for RepoImporter.ImportRepos.
   106  // Results are returned through a struct so that new (optional) fields may
   107  // be added without breaking existing implementations.
   108  //
   109  // EXPERIMENTAL: this may change or be removed.
   110  type ImportReposResult struct {
   111  	// Gen is a list of imported repository rules.
   112  	Gen []*rule.Rule
   113  
   114  	// Empty is a list of repository rules that may be deleted. This should only
   115  	// be set if ImportReposArgs.Prune is true.
   116  	Empty []*rule.Rule
   117  
   118  	// Error is any fatal error that occurred. Non-fatal errors should be logged.
   119  	Error error
   120  }