Skip to content

Experimental: add starlarklibrary gazelle extension#410

Open
pcj wants to merge 18 commits into
masterfrom
stardoc
Open

Experimental: add starlarklibrary gazelle extension#410
pcj wants to merge 18 commits into
masterfrom
stardoc

Conversation

@pcj
Copy link
Copy Markdown
Member

@pcj pcj commented Nov 30, 2025

Experimental new gazelle extension for collecting the .bzl files of an external resource. Not proto related, it could be upstreamed to gazelle itself if useful.

Currently in use at bazel-contrib/bcr-frontend

pcj added 9 commits November 29, 2025 22:55
Lets MODULE.bazel point starlark_repository at a workspace-local path
instead of an http_archive. Useful when the source already lives on
disk — e.g. a git submodule — and we want to skip the network fetch
entirely. The bcr-frontend project hits this with ~449 overlay-bzl
modules that all derive from the same bazel-central-registry archive;
emitting one `.archive(urls=...)` per module trips GitHub's 429 rate
limit on cold caches.

Changes
- extensions/starlark_repository.bzl: new `local` tag class with attrs
  {name, path, build_directives, build_file_generation, languages,
  cfgs, imports, imports_out (default "imports.csv"), deleted_files,
  reresolve_known_proto_imports, importpath}. The extension impl maps
  user-facing `path` to the underlying `local_path` attr and dispatches
  to the same starlark_repository repo rule used by `.archive`.
- rules/proto/proto_repository.bzl: in `_proto_repository_impl`'s
  local_path branch, resolve workspace-relative paths against the main
  workspace root (via Label("@@//:MODULE.bazel").dirname) before
  passing them to ctx.watch_tree() and fetch_repo's --path arg. Bare
  strings were otherwise interpreted relative to the external repo's
  own dir, where the directory doesn't exist.
- rules/proto/proto_repository.bzl: in _generate_proto_repository_info,
  return empty string when imports_out is unset, so a future caller
  with no imports_out can't trip `exports_files([""])`.

Usage:

    starlark_repository = use_extension(
        "@build_stack_rules_proto//extensions:starlark_repository.bzl",
        "starlark_repository",
    )
    starlark_repository.local(
        name = "bzl.colordiff---1.0.22",
        path = "data/bazel-central-registry/modules/colordiff/1.0.22/overlay",
        build_directives = ["gazelle:starlarkrepository_root"],
        build_file_generation = "clean",
        languages = ["starlarkrepository"],
    )
    use_repo(starlark_repository, "bzl.colordiff---1.0.22")
… targets (#423)

Adds a new "preserve" build_file_generation mode that runs cmd/preserve_packages
between fetch_repo and gazelle. The tool mirrors fetch_repo -clean semantics
(deletes WORKSPACE / MODULE.bazel / etc.) but renames BUILD and BUILD.bazel to
BUILD.package and BUILD.bazel.package so the upstream package layout is
preserved as opaque files rather than discarded.

The starlarkrepository gazelle extension grows a parallel pair of kinds
alongside starlark_module / starlark_module_library:

  - starlark_package: one per BUILD*.package, src points at the preserved file.
    Name is the dot-sanitized filename (BUILD.package -> BUILD_package) to
    avoid clashing with starlark_module names derived from .bzl files.
  - starlark_package_library: emitted at the configured root, named
    "starlark_packages" (not "packages", which would clash with packages.bzl).
    Its `packages` attr is populated in Resolve via the RuleIndex.

starlark_repository.archive/.local default build_file_generation to "preserve"
so users get the new behavior automatically; they can still override.
pcj added a commit to bazel-contrib/bcr-frontend that referenced this pull request May 19, 2026
* feat: packageinfo parsing

* feat: packages tab + cross-registry targets view

Surface BUILD-file extraction in the SPA: each module-version gets a
"Packages" tab with a sticky rule-kind sidebar, per-package target
list with a stacked color breakdown bar, and per-target detail page
showing the reproduced BUILD call (syntax-highlighted) plus a GitHub
source link. New top-level `/targets` view enumerates every loaded
callable in the registry and lists usages grouped by module-version;
each callable symbol's docs page links out to it via a Usages button.

- new packagecompiler flag --bzl_file (transitive load context) +
  --port for local constellate testing
- registry-wide packages.pb.gz + per-version packageinfo.pb.gz
  (hashed, deployed under modules/<m>/<v>/) wired through
  releasecompiler and release.bzl
- ModuleSource.packages proto field decorated client-side, with a
  fallback fetch of per-version packageinfo.pb.gz for older versions
- ruleUsageIndex built from loaded callables; trie-routed at
  /targets/@<repo>/<pkg>/<file>.bzl/<symbol>, with parsed-but-empty
  URLs rendering a "no usages" blankslate instead of 404
- packages tab: 2-pane PageLayout with a treeview sidebar grouping
  every target by rule kind (colored dot, kind→/targets link, count);
  per-package row replaces "N targets" with a horizontal flex bar
  whose width scales with package size and whose segments are
  colored by ruleKindStyle (smallest→largest left-to-right)
- next/prev shortcut ([ / ]) cycles packages when on a
  /packages/<pkg> URL
- targets cycle key uses _list to avoid colliding with a target
  literally named "list"

* stackb/rules_proto: upgrade to stackb/rules_proto#410

* bazel run //:format
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant