base

Documentation

Overview

Package base contains code shared by other CLI subpackages.

Package base contains code shared by other CLI subpackages.

Index

• Constants
• func CheckForBogusConfig(entryPath string) error
• func CollectErrorMessages(err error, in []string) (out []string)
• func ExpandDirectories(paths []string) ([]string, error)
• func GenerateConfigs(ctx context.Context, inputFile string, meta, flags *lucicfg.Meta, ...) (*lucicfg.State, error)
• func MissingFlagError(flag string) error
• func NewCLIError(msg string, args ...any) error
• func PathLoader(path string) (starlark.StringDict, string, error)
• func Validate(ctx context.Context, params ValidateParams, ...) ([]*buildifier.Finding, []*lucicfg.ValidationResult, error)
• type CommandLineError
• type ConfigServiceConnFactory
• type LegacyConfigServiceClientFactory
• type Parameters
• type RewriterFactory
  • func GetRewriterFactory(configPath string) (rewriterFactory *RewriterFactory, err error)
  • func GuessRewriterFactoryFunc(paths []string) (*RewriterFactory, error)
  • func (f *RewriterFactory) GetRewriter(path string) (*build.Rewriter, error)
• type Subcommand
  • func (c *Subcommand) AddGeneratorFlags()
  • func (c *Subcommand) CheckArgs(args []string, minPosCount, maxPosCount int) bool
  • func (c *Subcommand) DefaultMeta() lucicfg.Meta
  • func (c *Subcommand) Done(result any, err error) int
  • func (c *Subcommand) Init(params Parameters)
  • func (c *Subcommand) LegacyConfigServiceClient(ctx context.Context) (*http.Client, error)
  • func (c *Subcommand) MakeConfigServiceConn(ctx context.Context, host string) (*grpc.ClientConn, error)
  • func (c *Subcommand) ModifyContext(ctx context.Context) context.Context
• type ValidateParams

Constants

const ConfigName = ".lucicfgfmtrc"

ConfigName is the file name we will be used for lucicfg formatting

Functions

func CheckForBogusConfig

func CheckForBogusConfig(entryPath string) error

CheckForBogusConfig will look for any config files contained in a subdirectory of entryPath (recursively).

Because we intend for there to be at most one config file per workspace, and for that config file to be located at the root of the workspace, any such extra config files would be errors. Due to the 'stateless' nature of fmt and lint, we search down the directory hierarchy here to try to detect such misconfiguration, but in the future when these subcommands become stateful (like validate currently is), we may remove this check.

func CollectErrorMessages

func CollectErrorMessages(err error, in []string) (out []string)

CollectErrorMessages traverses err (which can be a MultiError, recursively), and appends all error messages there to 'in', returning the resulting slice.

They are eventually used in JSON output and printed to stderr.

func ExpandDirectories

func ExpandDirectories(paths []string) ([]string, error)

ExpandDirectories recursively traverses directories in `paths` discovering *.star files in them.

If `paths` is empty, expands `.`.

Returns the overall list of absolute paths to discovered files.

func GenerateConfigs

func GenerateConfigs(ctx context.Context, inputFile string, meta, flags *lucicfg.Meta, vars map[string]string) (*lucicfg.State, error)

GenerateConfigs executes the Starlark script and assembles final values for meta config.

It is a common part of subcommands that generate configs.

'meta' is initial Meta config with default parameters, it will be mutated in-place to contain the final parameters (based on lucicfg.config(...) calls in Starlark and the config populated via CLI flags, passed as 'flags'). 'flags' are also mutated in-place to rebase ConfigDir onto cwd.

'vars' are a collection of k=v pairs passed via CLI flags as `-var k=v`. They are used to pre-set lucicfg.var(..., exposed_as=<k>) variables.

func MissingFlagError

func MissingFlagError(flag string) error

MissingFlagError is CommandLineError about a missing flag.

func NewCLIError

func NewCLIError(msg string, args ...any) error

NewCLIError returns new CommandLineError.

func PathLoader

func PathLoader(path string) (starlark.StringDict, string, error)

PathLoader is an interpreter.Loader that loads files using file system paths.

func Validate

func Validate(ctx context.Context, params ValidateParams, getRewriterForPath func(path string) (*build.Rewriter, error)) ([]*buildifier.Finding, []*lucicfg.ValidationResult, error)

Validate validates both input source code and generated config files.

It is a common part of subcommands that validate configs.

Source code is checked using buildifier linters and formatters, if enabled. This is controlled by LintChecks meta args.

Generated config files are split into 0 or more config sets and sent to the LUCI Config remote service for validation, if enabled. This is controlled by ConfigServiceHost meta arg.

Dumps all validation errors to the stderr. In addition to detailed validation results, also returns a multi-error with all blocking errors.

Types

type CommandLineError

type CommandLineError struct {
	// contains filtered or unexported fields
}

CommandLineError is used to tag errors related to command line arguments.

Subcommand.Done(..., err) will print the usage string if it finds such error.

type ConfigServiceConnFactory

type ConfigServiceConnFactory func(ctx context.Context, host string) (*grpc.ClientConn, error)

ConfigServiceConnFactory returns a gRPC connection that can be used to send request to LUCI Config service.

type LegacyConfigServiceClientFactory

type LegacyConfigServiceClientFactory func(ctx context.Context) (*http.Client, error)

LegacyConfigServiceClientFactory returns a HTTP client that is used to end request to LUCI Config service.

type Parameters

type Parameters struct {
	AuthOptions       auth.Options // mostly for client ID and client secret
	ConfigServiceHost string       // e.g. "config.luci.app"
}

Parameters can be used to customize CLI defaults.

type RewriterFactory

type RewriterFactory struct {
	// contains filtered or unexported fields
}

RewriterFactory is used to map from 'file to be formatted' to a Rewriter object, via its GetRewriter method.

This struct is obtained via the GetRewriterFactory function.

func GetRewriterFactory

func GetRewriterFactory(configPath string) (rewriterFactory *RewriterFactory, err error)

GetRewriterFactory will attempt to create a RewriterFactory object

If configPath is empty, or points to a file which doesn't exist, the returned factory will just produce GetDefaultRewriter() when asked about any path. We will return an error if the config file is invalid.

func GuessRewriterFactoryFunc

func GuessRewriterFactoryFunc(paths []string) (*RewriterFactory, error)

GuessRewriterFactoryFunc will find the common ancestor dir from all given paths and return a func that returns the rewriter factory.

Will look for a config file upwards(inclusive). If found, it will be used to determine rewriter properties. It will also look downwards(exclusive) to expose any misplaced config files.

func (*RewriterFactory) GetRewriter

func (f *RewriterFactory) GetRewriter(path string) (*build.Rewriter, error)

GetRewriter will return the Rewriter which is appropriate for formatting the file at `path`, using the previously loaded formatting configuration.

Note the method signature will pass in values that we need to evaluate the correct rewriter.

We will accept both relative and absolute paths.

type Subcommand

type Subcommand struct {
	subcommands.CommandRunBase

	Meta lucicfg.Meta        // meta config settable via CLI flags
	Vars stringmapflag.Value // all `-var k=v` flags
	// contains filtered or unexported fields
}

Subcommand is a base of all subcommands.

It defines some common flags, such as logging and JSON output parameters, and some common methods to report errors and dump JSON output.

It's Init() method should be called from within CommandRun to register base flags.

func (*Subcommand) AddGeneratorFlags

func (c *Subcommand) AddGeneratorFlags()

AddGeneratorFlags registers c.Meta and c.Vars in the FlagSet.

Used by subcommands that end up executing Starlark.

func (*Subcommand) CheckArgs

func (c *Subcommand) CheckArgs(args []string, minPosCount, maxPosCount int) bool

CheckArgs checks command line args.

It ensures all required positional and flag-like parameters are set. Setting maxPosCount to -1 indicates there is unbounded number of positional arguments allowed.

Returns true if they are, or false (and prints to stderr) if not.

func (*Subcommand) DefaultMeta

func (c *Subcommand) DefaultMeta() lucicfg.Meta

DefaultMeta returns Meta values to use by default if not overridden via flags or via lucicfg.config(...).

func (*Subcommand) Done

func (c *Subcommand) Done(result any, err error) int

Done is called as the last step of processing a subcommand.

It dumps the command result (or an error) to the JSON output file, prints the error message and generates the process exit code.

func (*Subcommand) Init

func (c *Subcommand) Init(params Parameters)

Init registers common flags.

func (*Subcommand) LegacyConfigServiceClient

func (c *Subcommand) LegacyConfigServiceClient(ctx context.Context) (*http.Client, error)

LegacyConfigServiceClient returns an authenticated client to call legacy LUCI Config service.

func (*Subcommand) MakeConfigServiceConn

func (c *Subcommand) MakeConfigServiceConn(ctx context.Context, host string) (*grpc.ClientConn, error)

MakeConfigServiceConn returns an authenticated grpc connection to call call LUCI Config service.

func (*Subcommand) ModifyContext

func (c *Subcommand) ModifyContext(ctx context.Context) context.Context

ModifyContext implements cli.ContextModificator.

type ValidateParams

type ValidateParams struct {
	Loader interpreter.Loader // represents the main package
	Source []string           // paths to lint, relative to the main package
	Output lucicfg.Output     // generated output files to validate
	Meta   lucicfg.Meta       // validation options (settable through Starlark)

	// LegacyConfigServiceClientFactory returns a HTTP client that is used to end
	// request to LUCI Config service.
	//
	// This is usually just subcommand.LegacyConfigServiceClient.
	LegacyConfigServiceClient LegacyConfigServiceClientFactory

	// ConfigServiceConn returns a gRPC connection that can be used to send
	// request to LUCI Config service.
	//
	// This is usually just subcommand.MakeConfigServiceConn.
	ConfigServiceConn ConfigServiceConnFactory
}

ValidateParams contains parameters for Validate call.