### Apply Patch for go-tree-sitter

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/treesitter/README.md

Downstream consumers that materialize github.com/smacker/go-tree-sitter through their own go_deps must reapply the ABI 15 patch. This example shows how to use go_deps_dev.module_override to apply the patch.

```python
go_deps_dev = use_extension("@gazelle//:extensions.bzl", "go_deps", dev_dependency = True)
go_deps_dev.module_override(
    patch_strip = 1,
    patches = ["@aspect_treesitter_grammars//patches:go-tree-sitter-abi15.patch"],
    path = "github.com/smacker/go-tree-sitter",
)
```

--------------------------------

### Scoping Producers and Collectors

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

This example demonstrates how to use `ctx.properties.is_local` and `ctx.data` to scope producers to anchors and collect them. Producers scope their Symbol ID to the nearest anchor, and collectors at the anchor import the scoped ID.

```python
def prepare(ctx):
    if ctx.properties.is_local("collect_root"):
        ctx.data["collect_root"] = ctx.rel
    ...

def declare(ctx):
    rootdir = ctx.data.get("collect_root")
    # producers scope their Symbol id to the nearest anchor ...
    #   aspect.Symbol(id = path.join(rootdir, "widget"), provider = "demo")
    # ... and a collector at the anchor (rootdir == ctx.rel) imports the scoped id
    #   aspect.Import(id = path.join(ctx.rel, "widget"), provider = "demo", multiple = True)
```

--------------------------------

### Tagging a prebuilt release

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/prebuilt/README.md

Create a semver tag prefixed with 'prebuilt-' to trigger the release workflow for prebuilt binaries. Pre-release tags create GitHub pre-releases.

```bash
git tag prebuilt-v1.2.3
git push origin prebuilt-v1.2.3
```

--------------------------------

### Run Gazelle and check BUILD files

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/prebuilt/README.md

Commands to update BUILD files using `bazel run //:gazelle` and to check for stale BUILD files in CI using `bazel run //:gazelle.check`.

```sh
bazel run //:gazelle        # update BUILD files
bazel run //:gazelle.check  # CI: fail if BUILD files are stale
```

--------------------------------

### Add aspect_gazelle_prebuilt to MODULE.bazel

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/prebuilt/README.md

Declare aspect_gazelle_prebuilt as a dependency in your MODULE.bazel file. Specify the version needed for your project.

```starlark
# MODULE.bazel
bazel_dep(name = "aspect_gazelle_prebuilt", version = "...")
```

--------------------------------

### path.join

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Joins one or more path components intelligently.

```APIDOC
## path.join(parts...)

### Description
Joins one or more path components intelligently.

### Method
Utility function

### Parameters
#### Path Parameters
- **parts** (string...) - Required - One or more path components to join.
```

--------------------------------

### Load and Define Bzl Library

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/runner/tests/cli-update-mode-diff/expectedStdout.txt

Loads the bzl_library macro from bazel_skylib and defines a library named 'foo' using a source file 'foo.bzl'. This snippet is typically found in a BUILD.bazel file.

```bazel
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")

bzl_library(
    name = "foo",
    srcs = ["foo.bzl"],
    visibility = ["//visibility:public"],
)
```

--------------------------------

### Configure .bazelrc for LLVM Toolchain and Linking

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/js/README.md

Configure your .bazelrc file to use the hermetic LLVM C/C++ toolchain for building the Rust parser and linking via cgo. This includes environment variables to prevent default toolchain detection and a linkopt to work around a Go stdlib + lld PIE-link incompatibility.

```bazelrc
# Use the hermetic LLVM C/C++ toolchain (provided by @aspect_gazelle_js) to
# build the Rust parser and link it via cgo.
common --repo_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1
common --repo_env=BAZEL_NO_APPLE_CPP_TOOLCHAIN=1
common --linkopt=-no-pie

# Stub libgcc_s; rules_rust tool binaries otherwise link against a non-hermetic
# system libgcc_s that the LLVM sysroot lacks ("unable to find library -lgcc_s").
common --@llvm//config:experimental_stub_libgcc_s=True
```

--------------------------------

### Consume Common Module via Go Modules

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/common/README.md

This snippet shows how to consume the common module using go.mod and rules_go's go_deps extension in your MODULE.bazel file. Ensure you are not depending on it via bazel_dep.

```starlark
# In the consumer's MODULE.bazel
go_deps = use_extension("@gazelle//:extensions.bzl", "go_deps")
go_deps.from_file(go_mod = "//:go.mod")
use_repo(go_deps, "com_github_aspect_build_aspect_gazelle_common", ...)
```

```go.mod
require github.com/aspect-build/aspect-gazelle/common <version>
```

--------------------------------

### Basic aspect_gazelle rule

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/prebuilt/README.md

Load and use the aspect_gazelle macro in your BUILD.bazel file to generate BUILD files for specified languages. This is the primary way to integrate Gazelle into your build.

```starlark
# BUILD.bazel
load("@aspect_gazelle_prebuilt//:def.bzl", "aspect_gazelle")

aspect_gazelle(languages = ["js"])
```

--------------------------------

### path.ext

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Returns the extension of the file portion of the path.

```APIDOC
## path.ext(p)

### Description
Returns the extension of the file portion of the path.

### Method
Utility function

### Parameters
#### Path Parameters
- **p** (string) - Required - The path to get the extension from.
```

--------------------------------

### Aspect AstQuery Factory Method

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Use this factory method to create an AstQuery for analyzing source code Abstract Syntax Trees. It accepts a tree-sitter query, an optional grammar, a file path filter, and a content filter to gate the parsing and querying process.

```python
aspect.AstQuery(query, grammar, filter, content_filter)
```

--------------------------------

### Declare Source Files by Glob Patterns

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Matches source files using glob patterns, excluding specific files. Globs are slower than exact path or extension matchers.

```python
# Every .ts source except specs, declaration files, and generated code.
aspect.SourceGlobs(["src/**/*.ts"], exclude = ["**/*.spec.ts", "**/*.d.ts", "src/gen/**"])
```

--------------------------------

### Reading Inherited Plugin Data

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Plugin data is stored in `ctx.data` and can be read with fallback options. Writes are restricted to the 'prepare' stage.

```python
ctx.data[key] = value      # write (prepare stage only)
ctx.data.get(key, default) # read with a fallback
ctx.data[key]              # read (errors if unset)
key in ctx.data            # membership
```

--------------------------------

### Create sh_library targets for .bash and .sh files

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

This snippet demonstrates how to register an Orion extension to generate sh_library targets for shell scripts. It uses aspect.orion_extension to define the extension's behavior, including identifying source files and declaring targets.

```starlark
"Create sh_library targets for .bash and .sh files"

aspect.orion_extension(
    id = "rules_sh",
    prepare = lambda cfg: aspect.PrepareResult(
        sources = aspect.SourceExtensions(".bash", ".sh"),
    ),
    declare = lambda ctx: ctx.targets.add(
        kind = "sh_library",
        name = "shell",
        attrs = {
            "srcs": [s.path for s in ctx.sources],
        },
    ),
)

```

--------------------------------

### aspect.RawQuery

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Creates a RawQuery object to read file content as-is. It takes a glob pattern to match file names and an optional content pattern to gate the query.

```APIDOC
## aspect.RawQuery(filter, content_filter)

### Description
Factory method for a `RawQuery`. This query reads the file content as-is without any parsing or filtering.

### Method
Factory method

### Parameters
#### Path Parameters
- **filter** (string) - Required - A glob pattern to match file names.
- **content_filter** (string) - Optional - A content pattern gating whether the query runs.

### Response
#### Success Response
Returns a `RawQuery` object.

#### Response Example
```json
{
  "query_type": "RawQuery",
  "filter": "*.txt",
  "content_filter": "some_pattern"
}
```
```

--------------------------------

### Define Gazelle Target with Prebuilt

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/README.md

Define a gazelle target in your BUILD file using the aspect_gazelle macro from the prebuilt module. Specify languages and extensions as needed. The `with_check = True` option creates a gazelle.check target to ensure BUILD files are up-to-date.

```starlark
load("@aspect_gazelle_prebuilt//:def.bzl", "aspect_gazelle")

aspect_gazelle(
    name = "gazelle",
    languages = ["js", "python", ...],
    extensions = ["//tools/gazelle:my_rule.star", ...],
    # Also create a `gazelle.check` target that fails if BUILD files are stale.
    with_check = True,
)
```

--------------------------------

### Accessing Extension Properties

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Plugins can access extension properties set in BUILD files using `ctx.properties`. The `is_local` method helps determine if a property was set in the current directory.

```python
ctx.properties.is_local(name)
```

--------------------------------

### Enable BUILD file checking in CI

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/prebuilt/README.md

Configure aspect_gazelle with `with_check = True` to create a `.check` target. This target verifies BUILD file staleness without making changes, suitable for CI environments.

```starlark
aspect_gazelle(
    languages = ["js"],
    with_check = True,
)
```

--------------------------------

### path.base

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Returns the basename (i.e., the file portion) of a path, including the extension.

```APIDOC
## path.base(p)

### Description
Returns the basename (i.e., the file portion) of a path, including the extension.

### Method
Utility function

### Parameters
#### Path Parameters
- **p** (string) - Required - The path to get the basename from.
```

--------------------------------

### Aspect RegexQuery Factory Method

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Use this factory method to create a RegexQuery for pattern matching within source files. It takes a regular expression, an optional file path filter, and a content filter to determine which files to process.

```python
aspect.RegexQuery(expression, filter, content_filter)
```

--------------------------------

### Configure aspect_gazelle with Go dependencies

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/prebuilt/README.md

When using rules_go, declare upstream @gazelle for go_deps and pass repo_config to aspect_gazelle. This ensures Go dependencies are correctly mapped and resolved.

```starlark
# MODULE.bazel
bazel_dep(name = "aspect_gazelle_prebuilt", version = "...") # for BUILD generation
bazel_dep(name = "gazelle", version = "0.51.3")  # for go_deps

go_deps = use_extension("@gazelle//:extensions.bzl", "go_deps")
go_deps.from_file(go_mod = "//:go.mod")
use_repo(
    go_deps,
    "bazel_gazelle_go_repository_config",  # required for aspect_gazelle(repo_config = ...)
    "com_github_some_module",              # add your Go dep repos here
)
```

```starlark
# BUILD.bazel
load("@aspect_gazelle_prebuilt//:def.bzl", "aspect_gazelle")

aspect_gazelle(
    name = "gazelle",
    languages = ["go", "proto"],
    repo_config = "@bazel_gazelle_go_repository_config//:WORKSPACE",
)
```

--------------------------------

### Declare LLVM Dependency in MODULE.bazel

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/js/README.md

Declare the LLVM dependency in your MODULE.bazel file to ensure the @llvm//config: flag resolves correctly. This is necessary for bzlmod to expose the repository by its apparent name.

```starlark
bazel_dep(name = "llvm", version = "0.8.3")  # match the version @aspect_gazelle_js pins
```

--------------------------------

### path.dirname

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Returns the dirname of a path.

```APIDOC
## path.dirname(p)

### Description
Returns the dirname of a path.

### Method
Utility function

### Parameters
#### Path Parameters
- **p** (string) - Required - The path to get the dirname from.
```

--------------------------------

### Check for File Existence

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Checks if a specific file exists in the current directory. The name can be a relative path.

```python
def prepare(ctx):
    if ctx.has_file("tsconfig.json"):
        ctx.data["ts_root"] = ctx.rel
    ...
```

--------------------------------

### Enable or Disable Orion Plugin

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Use this directive in a BUILD file to enable or disable a specific Orion plugin. The last directive encountered wins, and settings are inherited by subpackages.

```starlark
# gazelle:{plugin_id} enabled|disabled
```

--------------------------------

### Register Orion Extension with aspect.orion_extension

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Registers a configure extension for generating targets in BUILD files. This function takes an ID, optional properties, and callback functions for different stages of the extension lifecycle.

```starlark
aspect.orion_extension(
    id = "my_extension",
    properties = {
        "my_property": aspect.Property(default = "default_value"),
    },
    prepare = my_prepare_function,
    analyze = my_analyze_function,
    declare = my_declare_function,
)
```

--------------------------------

### Defining a Property

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Properties are defined using `aspect.Property(type, default)`. Specify the property's type and an optional default value.

```python
aspect.Property(type, default)
```

--------------------------------

### aspect.YamlQuery

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Creates a YamlQuery object to query YAML documents using YQ filter expressions. It filters files by glob pattern and gates the query with a content pattern.

```APIDOC
## aspect.YamlQuery(query, filter, content_filter)

### Description
Factory method for a `YamlQuery`. This query runs a YQ filter expression on YAML documents.

### Method
Factory method

### Parameters
#### Path Parameters
- **query** (string) - Required - A YQ filter expression to run on the YAML document.
- **filter** (string) - Required - A glob pattern to match file names to query.
- **content_filter** (string) - Optional - A content pattern gating whether the query runs.

### Response
#### Success Response
Returns a `YamlQuery` object. The query result is a list of each matching YAML node.

#### Response Example
```json
{
  "query_type": "YamlQuery",
  "query": ".some.key",
  "filter": "*.yaml",
  "content_filter": "some_pattern"
}
```
```

--------------------------------

### Register Rule Kind with aspect.register_rule_kind

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Registers a new rule kind for generation by a configure extension. Ensure the rule kind is not already provided by another enabled Gazelle language to avoid conflicts.

```starlark
aspect.register_rule_kind(
    name = "my_rule_kind",
    From = "@my_repo//my_rules:defs.bzl",
    NonEmptyAttrs = {"srcs", "deps"},
    MergeableAttrs = {"data"},
    ResolveAttrs = {"deps"},
)
```

--------------------------------

### aspect.TomlQuery

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Creates a TomlQuery object to query TOML documents using YQ filter expressions. It filters files by glob pattern and gates the query with a content pattern.

```APIDOC
## aspect.TomlQuery(query, filter, content_filter)

### Description
Factory method for a `TomlQuery`. This query runs a filter expression on TOML documents.

### Method
Factory method

### Parameters
#### Path Parameters
- **query** (string) - Required - A filter expression to run on the TOML document.
- **filter** (string) - Required - A glob pattern to match file names to query.
- **content_filter** (string) - Optional - A content pattern gating whether the query runs.

### Response
#### Success Response
Returns a `TomlQuery` object. The query result is a list of each matching node.

#### Response Example
```json
{
  "query_type": "TomlQuery",
  "query": ".some.key",
  "filter": "*.toml",
  "content_filter": "some_pattern"
}
```
```

--------------------------------

### aspect.JsonQuery

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Creates a JsonQuery object to query JSON documents using JQ filter expressions. It filters files by glob pattern and gates the query with a content pattern.

```APIDOC
## aspect.JsonQuery(query, filter, content_filter)

### Description
Factory method for a `JsonQuery`. This query runs a JQ filter expression on JSON documents.

### Method
Factory method

### Parameters
#### Path Parameters
- **query** (string) - Required - A JQ filter expression to run on the JSON document.
- **filter** (string) - Required - A glob pattern to match file names to query.
- **content_filter** (string) - Optional - A content pattern gating whether the query runs.

### Response
#### Success Response
Returns a `JsonQuery` object. The query result is a list of each matching JSON node.

#### Response Example
```json
{
  "query_type": "JsonQuery",
  "query": ".some.field",
  "filter": "*.json",
  "content_filter": "some_pattern"
}
```
```

--------------------------------

### Set Orion Plugin Property

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/language/orion/README.md

Use this directive to set a property value for an Orion plugin, as defined by the plugin's Properties(). Values are inherited by subpackages.

```starlark
# gazelle:{property_name} {value}
```

--------------------------------

### Disable Gitignore Support in Gazelle

Source: https://github.com/aspect-build/aspect-gazelle/blob/main/README.md

Opt out of `.gitignore` support when Gazelle generates BUILD files. This is done by passing `--gitignore=false` to gazelle.

```sh
bazel run //:gazelle -- --gitignore=false
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.