gazelle

package
v1.509.25 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 28, 2024 License: Apache-2.0 Imports: 31 Imported by: 0

README

JavaScript/TypeScript BUILD file generation

This package automates the creation and maintenance of BUILD files for JavaScript and TypeScript, using rules_js and rules_ts. It is a Gazelle Language implementation.

Usage

This feature is included in the Aspect CLI, accessed with the configure command. It's also possible to build into your own Gazelle binary.

Rules

Generated targets include:

  • ts_project targets for source, tests, and custom targets and their ts/js/npm dependencies
  • npm_package targets for projects within a pnpm workspace
  • npm_link_all_packages for linking npm packages
Directives

See Aspect CLI Directives for a list of supported directives.

Documentation

Index

Constants

View Source 
const (
	// Directive_TypeScriptExtension represents the directive that controls whether
	// this TypeScript generation is enabled or not. Sub-packages inherit this value.
	// Can be either "enabled" or "disabled". Defaults to "enabled".
	Directive_TypeScriptExtension = "js"
	// En/disable ts_proto_library generation
	Directive_TypeScriptProtoExtension = "js_proto"
	// En/disable ts_config generation
	Directive_TypeScriptConfigExtension = "js_tsconfig"
	// Directive_GenerationMode represents the directive that controls the BUILD generation
	// mode. See below for the GenerationModeType constants.
	Directive_GenerationMode = "js_generation_mode"
	// The pnpm-lock.yaml file.
	Directive_Lockfile = "js_pnpm_lockfile"
	// Directive_IgnoreImports represents the directive that controls the
	// ignored dependencies from the generated targets.
	// Sub-packages extend this value.
	// Ignored imports may be file path globs.
	Directive_IgnoreImports = "js_ignore_imports"
	// Directive_Resolve represents a gazelle:resolve state which supports globs.
	Directive_Resolve = "js_resolve"
	// Directive_ValidateImportStatements represents the directive that controls
	// whether the TypeScript import statements should be validated.
	Directive_ValidateImportStatements = "js_validate_import_statements"
	// Directive_LibraryNamingConvention represents the directive that controls the
	// ts_project naming convention. It interpolates {dirname} with the
	// Bazel package name. E.g. if the Bazel package name is `foo`, setting this
	// to `{dirname}_my_lib` would render to `foo_my_lib`.
	Directive_LibraryNamingConvention = "js_project_naming_convention"
	// The target name for npm_package() rules. See npm_translate_lock(npm_package_target_name)
	Directive_NpmPackageNameConvention = "js_npm_package_target_name"
	// Directive_TestsNamingConvention represents the directive that controls the ts_project test
	// naming convention. See js_project_naming_convention for more info on
	// the package name interpolation.
	Directive_TestsNamingConvention = "js_tests_naming_convention"
	// The glob for the main library files, excludes files matching Directive_TestFiles.
	Directive_LibraryFiles = "js_files"
	// The glob for test files.
	Directive_TestFiles = "js_test_files"
	// Add a glob to a custom library type
	Directive_CustomTargetFiles = "js_custom_files"
	// Add a glob to a custom library type
	Directive_CustomTargetTestFiles = "js_custom_test_files"
)

Directives. Keep in sync with documentation in /docs/cli/help/directives.md

View Source 
const (
	DefaultNpmLinkAllTargetName = "node_modules"
	TargetNameDirectoryVar      = "{dirname}"
	DefaultLibraryName          = TargetNameDirectoryVar
	DefaultTestsName            = TargetNameDirectoryVar + "_tests"
	NpmPackageContentName       = TargetNameDirectoryVar + "_lib"

	// The default name for ts_proto_library rules, where {proto_library} is the name of the proto target
	ProtoNameVar            = "{proto_library}"
	DefaultProtoLibraryName = ProtoNameVar + "_ts"

	// The suffix added to the end of a target being wrapped in a package.
	PackageSrcSuffix = "_lib"

	// The default should align with the rules_js default npm_translate_lock(npm_package_target_name)
	DefaultNpmPackageTargetName = TargetNameDirectoryVar
)
View Source 
const (
	// The filename (with any of the TS extensions) imported when importing a directory.
	IndexFileName = "index"

	NpmPackageFilename = "package.json"

	DefaultRootTargetName = "root"

	MaxWorkerCount = 12
)
View Source 
const (
	TsProjectKind         = "ts_project"
	TsProtoLibraryKind    = "ts_proto_library"
	JsLibraryKind         = "js_library"
	TsConfigKind          = "ts_config"
	NpmPackageKind        = "npm_package"
	NpmLinkAllKind        = "npm_link_all_packages"
	RulesJsRepositoryName = "aspect_rules_js"
	RulesTsRepositoryName = "aspect_rules_ts"
	NpmRepositoryName     = "npm"
)
View Source 
const (
	Resolution_Error      = -1
	Resolution_None       = 0
	Resolution_NotFound   = 1
	Resolution_Package    = 2
	Resolution_Label      = 3
	Resolution_NativeNode = 4
	Resolution_Override   = 5
)
View Source 
const LanguageName = "js"

Variables

View Source 
var DefaultSourceGlobs = []*TargetGroup{
	&TargetGroup{
		name:           DefaultLibraryName,
		customSources:  []string{},
		defaultSources: []string{fmt.Sprintf("**/*.{%s}", strings.Join(typescriptFileExtensionsArray, ","))},
		testonly:       false,
	},
	&TargetGroup{
		name:           DefaultTestsName,
		customSources:  []string{},
		defaultSources: []string{fmt.Sprintf("**/*.{spec,test}.{%s}", strings.Join(typescriptFileExtensionsArray, ","))},
		testonly:       true,
	},
}

Functions

func NewConfigurer added in v1.505.0 

func NewConfigurer(lang *typeScriptLang) config.Configurer

func NewLanguage 

func NewLanguage() language.Language

NewLanguage initializes a new TypeScript that satisfies the language.Language interface. This is the entrypoint for the extension initialization.

func NewResolver added in v1.505.0 

func NewResolver(lang *typeScriptLang) resolve.Resolver

Types

type Configurer 

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

Configurer satisfies the config.Configurer interface. It's the language-specific configuration extension.

func (*Configurer) CheckFlags 

func (ts *Configurer) CheckFlags(fs *flag.FlagSet, c *config.Config) error

CheckFlags validates the configuration after command line flags are parsed. This is called once with the root configuration when Gazelle starts. CheckFlags may set default values in flags or make implied changes.

func (*Configurer) Configure added in v1.505.0 

func (ts *Configurer) Configure(c *config.Config, rel string, f *rule.File)

Configure modifies the configuration using directives and other information extracted from a build file. Configure is called in each directory.

c is the configuration for the current directory. It starts out as a copy of the configuration for the parent directory.

rel is the slash-separated relative path from the repository root to the current directory. It is "" for the root directory itself.

f is the build file for the current directory or nil if there is no existing build file.

func (*Configurer) KnownDirectives 

func (ts *Configurer) KnownDirectives() []string

KnownDirectives returns a list of directive keys that this Configurer can interpret. Gazelle prints errors for directives that are not recoginized by any Configurer.

func (*Configurer) RegisterFlags 

func (ts *Configurer) RegisterFlags(fs *flag.FlagSet, cmd string, c *config.Config)

RegisterFlags registers command-line flags used by the extension. This method is called once with the root configuration when Gazelle starts. RegisterFlags may set an initial values in Config.Exts. When flags are set, they should modify these values.

type GenerationModeType 

type GenerationModeType string

GenerationModeType represents one of the generation modes. 

const (
	GenerationModeNone GenerationModeType = "none"
	// GenerationModeDirectory defines the mode in which a coarse-grained target will
	// be generated for each sub-directory.
	GenerationModeDirectory GenerationModeType = "directory"
)

Generation modes

type ImportStatement 

type ImportStatement struct {
	resolve.ImportSpec

	// Alternative paths this statement may resolve to
	Alt []string

	// The path of the file containing the import
	SourcePath string

	// The path as written in the import statement
	ImportPath string
}

ImportStatement represents an ImportSpec imported from a source file. Imports can be of any form (es6, cjs, amd, ...). Imports may be relative ot the source, absolute, workspace, named modules etc.

type JsGazelleConfig 

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

JsGazelleConfig represents a config extension for a specific Bazel package.

func (*JsGazelleConfig) AddExcludedPattern 

func (c *JsGazelleConfig) AddExcludedPattern(pattern string)

AddExcludedPattern adds a glob pattern parsed from the standard gazelle:exclude directive.

func (*JsGazelleConfig) AddIgnoredImport 

func (c *JsGazelleConfig) AddIgnoredImport(impGlob string)

Adds a dependency to the list of ignored dependencies for a given package. Adding an ignored dependency to a package also makes it ignored on a subpackage.

func (*JsGazelleConfig) AddResolve 

func (c *JsGazelleConfig) AddResolve(imprt string, label *label.Label)

func (*JsGazelleConfig) AddTargetGlob added in v1.505.0 

func (c *JsGazelleConfig) AddTargetGlob(target, fileGlob string, isTestOnly bool)

AddTargetGlob sets the glob used to find source files for the specified target

func (*JsGazelleConfig) GenerationEnabled 

func (c *JsGazelleConfig) GenerationEnabled() bool

GenerationEnabled returns whether the extension is enabled or not.

func (*JsGazelleConfig) GenerationMode 

func (c *JsGazelleConfig) GenerationMode() GenerationModeType

GenerationMode returns whether coarse-grained targets should be generated or not.

func (*JsGazelleConfig) GetResolution 

func (c *JsGazelleConfig) GetResolution(imprt string) *label.Label

func (*JsGazelleConfig) GetSourceTarget added in v1.505.0 

func (c *JsGazelleConfig) GetSourceTarget(filePath string) *TargetGroup

Determine if and which target the passed file belongs in.

func (*JsGazelleConfig) GetSourceTargets added in v1.505.0 

func (c *JsGazelleConfig) GetSourceTargets() []*TargetGroup

Return a list of all source groups for this config, including primary library + tests. The list is the source of truth for the order of groups

func (*JsGazelleConfig) GetTsConfigGenerationEnabled added in v1.508.0 

func (c *JsGazelleConfig) GetTsConfigGenerationEnabled() bool

If ts_config extension is enabled.

func (*JsGazelleConfig) IsFileExcluded 

func (c *JsGazelleConfig) IsFileExcluded(fileRelPath string) bool

Determine if the file path is ignored based on the current configuration.

func (*JsGazelleConfig) IsImportIgnored 

func (c *JsGazelleConfig) IsImportIgnored(impt string) bool

Checks if a import is ignored in the given package or in one of the parent packages up to the workspace root.

func (*JsGazelleConfig) MapTargetName added in v1.505.0 

func (c *JsGazelleConfig) MapTargetName(name string) string

func (*JsGazelleConfig) NewChild 

func (c *JsGazelleConfig) NewChild(childPath string) *JsGazelleConfig

NewChild creates a new child JsGazelleConfig. It inherits desired values from the current JsGazelleConfig and sets itself as the parent to the child.

func (*JsGazelleConfig) PnpmLockfile 

func (c *JsGazelleConfig) PnpmLockfile() string

func (*JsGazelleConfig) ProtoGenerationEnabled added in v1.507.2 

func (c *JsGazelleConfig) ProtoGenerationEnabled() bool

If ts_proto_library extension is enabled.

func (*JsGazelleConfig) RenderNpmPackageTargetName added in v1.508.19 

func (c *JsGazelleConfig) RenderNpmPackageTargetName(packageName string) string

func (*JsGazelleConfig) RenderNpmSourceLibraryName 

func (c *JsGazelleConfig) RenderNpmSourceLibraryName(npmPackageName string) string

The library name when wrapped within an npm package.

func (*JsGazelleConfig) RenderSourceTargetName added in v1.508.19 

func (c *JsGazelleConfig) RenderSourceTargetName(groupName, packageName string, isNpmPackage bool) string

Returns the ts_project target name by performing all substitutions.

func (*JsGazelleConfig) RenderTsConfigName added in v1.508.0 

func (c *JsGazelleConfig) RenderTsConfigName(tsconfigName string) string

func (*JsGazelleConfig) RenderTsProtoLibraryName added in v1.507.2 

func (c *JsGazelleConfig) RenderTsProtoLibraryName(protoLibraryName string) string

func (*JsGazelleConfig) SetGenerationEnabled 

func (c *JsGazelleConfig) SetGenerationEnabled(enabled bool)

SetGenerationEnabled sets whether the extension is enabled or not.

func (*JsGazelleConfig) SetGenerationMode 

func (c *JsGazelleConfig) SetGenerationMode(generationMode GenerationModeType)

SetGenerationMode sets whether coarse-grained targets should be generated or not.

func (*JsGazelleConfig) SetLibraryNamingConvention 

func (c *JsGazelleConfig) SetLibraryNamingConvention(libraryNamingConvention string)

SetLibraryNamingConvention sets the ts_project target naming convention.

func (*JsGazelleConfig) SetNpmPackageNamingConvention 

func (c *JsGazelleConfig) SetNpmPackageNamingConvention(testsNamingConvention string)

func (*JsGazelleConfig) SetPnpmLockfile 

func (c *JsGazelleConfig) SetPnpmLockfile(pnpmLockPath string)

Set the pnpm-workspace.yaml file path.

func (*JsGazelleConfig) SetProtoGenerationEnabled added in v1.507.2 

func (c *JsGazelleConfig) SetProtoGenerationEnabled(enabled bool)

func (*JsGazelleConfig) SetTestsNamingLibraryConvention 

func (c *JsGazelleConfig) SetTestsNamingLibraryConvention(testsNamingConvention string)

SetTestsNamingLibraryConvention sets the ts_project test target naming convention.

func (*JsGazelleConfig) SetTsConfigGenerationEnabled added in v1.508.0 

func (c *JsGazelleConfig) SetTsConfigGenerationEnabled(enabled bool)

func (*JsGazelleConfig) SetTsProtoLibraryNamingConvention added in v1.507.2 

func (c *JsGazelleConfig) SetTsProtoLibraryNamingConvention(tsProtoLibraryName string)

func (*JsGazelleConfig) SetValidateImportStatements 

func (c *JsGazelleConfig) SetValidateImportStatements(mode ValidationMode)

SetValidateImportStatements sets the ValidationMode for TypeScript import statements. It throws an error if this is set multiple times, i.e. if the directive is specified multiple times in the Bazel workspace.

func (*JsGazelleConfig) ValidateImportStatements 

func (c *JsGazelleConfig) ValidateImportStatements() ValidationMode

ValidateImportStatements returns whether the TypeScript import statements should be validated or not. If this option was not explicitly specified by the user, it defaults to true.

type LinkAllPackagesImports 

type LinkAllPackagesImports struct{}

Npm link-all rule import data

type NpmPackageImports 

type NpmPackageImports struct{}

NpmPackage rule import data

type ResolutionType 

type ResolutionType = int

type Resolver 

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

Resolver satisfies the resolve.Resolver interface. It resolves dependencies in rules generated by this extension.

func (*Resolver) Embeds added in v1.505.0 

func (ts *Resolver) Embeds(r *rule.Rule, from label.Label) []label.Label

Embeds returns a list of labels of rules that the given rule embeds. If a rule is embedded by another importable rule of the same language, only the embedding rule will be indexed. The embedding rule will inherit the imports of the embedded rule.

func (*Resolver) Imports added in v1.505.0 

func (ts *Resolver) Imports(c *config.Config, r *rule.Rule, f *rule.File) []resolve.ImportSpec

Determine what rule (r) outputs which can be imported. For TypeScript this is all the import-paths pointing to files within the rule.

func (*Resolver) Name added in v1.505.0 

func (*Resolver) Name() string

Name returns the name of the language. This is the prefix of the kinds of rules generated. E.g. ts_project

func (*Resolver) Resolve added in v1.505.0 

func (ts *Resolver) Resolve(
	c *config.Config,
	ix *resolve.RuleIndex,
	rc *repo.RemoteCache,
	r *rule.Rule,
	importData interface{},
	from label.Label,
)

Resolve translates imported libraries for a given rule into Bazel dependencies. Information about imported libraries is returned for each rule generated by language.GenerateRules in language.GenerateResult.Imports. Resolve generates a "deps" attribute (or the appropriate language-specific equivalent) for each import according to language-specific rules and heuristics.

type TargetGroup added in v1.505.0 

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

type TsProjectInfo added in v1.508.0 

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

TsProject rule import data

func (*TsProjectInfo) AddImport added in v1.508.0 

func (i *TsProjectInfo) AddImport(impt ImportStatement)

type ValidationMode added in v1.503.2 

type ValidationMode int

ValidationMode represents what should happen when validation errors are found. 

const (
	// ValidationError has gazelle produce an error when validation errors are found.
	ValidationError ValidationMode = iota
	// ValidationWarn has gazelle print warnings when validation errors are found.
	ValidationWarn
	// ValidationOff has gazelle swallow validation errors silently.
	ValidationOff
)

Source Files

View all Source files

Directories

Path Synopsis
tests
treesitter

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.