bundler-codegraph 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 010d01ceb078418222249056f60188101bde16ea45c8717f45759d6f80602402
+  data.tar.gz: bcc8de402d3b5826cfddf3fa8e7eadcc52d17caea29b3c60de5d0e6855f022a3
+SHA512:
+  metadata.gz: ebf29e721f8fff41d7c6e9a7cc95f90b048c47d04c1ce8b16f6f79cfde6016aaee73b4060ccc56427a6b725d15fed5325db393cf4d355ac0f3171e7a3f67d23d
+  data.tar.gz: a65f3f6497ed2ae73ea39469ac327b24dda381d9047b93621812cff3619d332a4a60139305effdd13a9ed63494b33c31a0116cca88c6f22562e710d828be2e86

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# CHANGELOG
+
+## 0.1.0 (2026-09-25)
+
+First release!
+
+* Index every gem of the bundle at the end of `bundle install`: `after-install` queues each gem, `after-install-all` indexes the queue, so indexing never holds up an install worker; each gem indexed prints a line
+* Add the `bundle codegraph-index [--force]` command to catch up on an already installed bundle; `--help` prints its usage; it exits non-zero on an unknown argument, a missing `codegraph` binary, or any gem failing to index
+* Serialize indexing through an advisory file lock, so concurrent `bundle install` runs do not run several indexers at once; the lock lives in a private per-user directory, so another user of a shared `/tmp` cannot hold it, and both the hook and `bundle codegraph-index` warn when that directory cannot be trusted
+* Stop `codegraph` (TERM, then KILL) before cleaning up when `bundle install` is interrupted, even when the signal reaches Ruby alone
+* Skip gems carrying no Ruby source, and have the hook skip gems already holding an index (`.codegraph/codegraph.db`)
+* Sync existing indexes from `bundle codegraph-index`, which completes one a killed run left partial
+* Remove the `.codegraph/` directory of a failed or interrupted run, and restore the previous index when a `--force` rebuild fails or is killed
+* Turn the plugin into a no-op when the `codegraph` binary is missing, rather than failing the install
+* Run `codegraph` with its stdin on `/dev/null`, so a prompt it would show can never hang `bundle install`
+* Find Ruby sources under a path holding glob metacharacters (`[`, `{`) instead of skipping every gem as `no Ruby source`
+* Leave `bundler` and the project's own gemspec out of both the hook and `bundle codegraph-index`
+* Warn about each gem `codegraph` fails on, and keep its error output in a per-gem log file; the hook says it skips that gem, and does not retry it until a new version of it is installed, `bundle codegraph-index` runs, or the temporary directory is purged; an interrupted run, or a `codegraph` killed by a signal, is not recorded as a failure
+* Add the `BUNDLER_CODEGRAPH`, `BUNDLER_CODEGRAPH_EXCLUDE` and `BUNDLER_CODEGRAPH_BIN` environment variables

data/LICENSE

@@ -0,0 +1,19 @@
+The MIT License (MIT)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,278 @@
+# bundler-codegraph
+
+[![GitHub license](https://img.shields.io/github/license/jbox-web/bundler-codegraph.svg)](https://github.com/jbox-web/bundler-codegraph/blob/master/LICENSE)
+[![CI](https://github.com/jbox-web/bundler-codegraph/workflows/CI/badge.svg)](https://github.com/jbox-web/bundler-codegraph/actions)
+[![Maintainability](https://qlty.sh/gh/jbox-web/projects/bundler-codegraph/maintainability.svg)](https://qlty.sh/gh/jbox-web/projects/bundler-codegraph)
+[![Code Coverage](https://qlty.sh/gh/jbox-web/projects/bundler-codegraph/coverage.svg)](https://qlty.sh/gh/jbox-web/projects/bundler-codegraph)
+
+A Bundler plugin that builds a [CodeGraph][codegraph] index inside every gem it
+installs.
+
+## Why
+
+Answering *"what does this gem actually do here?"* normally means a grep/read
+loop through `.bundle/ruby/*/gems/<gem>/`: guess a filename, read it, follow a
+constant into another file, read that one too. Every hop is a round-trip, the
+whole file lands in the context window when three methods were needed, and
+nothing in that loop can follow a dynamically dispatched call.
+
+[CodeGraph][codegraph] turns a directory into a local SQLite knowledge graph of
+symbols, edges and files. Querying it returns the relevant symbols' verbatim
+source *and* the call paths between them, in a single round-trip:
+
+```bash
+codegraph explore --path .bundle/ruby/4.0.0/gems/rack-3.2.6 "Rack::Session::Cookie"
+```
+
+The MCP tool takes the same value as `projectPath`, so an agent gets the same
+answer without shelling out.
+
+The catch: the index has to already exist when the question comes up. Running
+`codegraph init` by hand on a few hundred gem directories, and again after every
+`bundle update`, is not a plan. That is the whole point of this plugin — the
+index is a side effect of `bundle install`, and nobody has to think about it.
+
+## Install
+
+### 1. The `codegraph` binary
+
+It must be on `PATH`. Through [mise][mise] and the [jbox-web aqua
+registry][aqua-registry]:
+
+```toml
+# mise.toml
+[settings]
+aqua.registries = ["https://github.com/jbox-web/aqua-registry"]
+
+[tools]
+"aqua:colbymchenry/codegraph" = "1.5.0"
+```
+
+Or straight from npm:
+
+```bash
+npm install -g @colbymchenry/codegraph
+```
+
+If the binary is missing the plugin turns itself into a no-op rather than
+failing the install, so this step can be skipped on machines that do not need
+the indexes.
+
+### 2. The plugin
+
+Add it to the `Gemfile` of the project whose dependencies you want indexed:
+
+```ruby
+plugin 'bundler-codegraph'
+```
+
+That pulls the released gem from RubyGems.org. To follow unreleased changes,
+point it at the repository instead:
+
+```ruby
+plugin 'bundler-codegraph', git: 'https://github.com/jbox-web/bundler-codegraph.git', branch: 'master'
+```
+
+A `plugin` declaration takes the same options as a `gem` one — Bundler's plugin
+DSL delegates straight to it — so `github:`, `tag:`, `ref:` and `path:` all
+work. Use `path:` when hacking on the plugin itself, since it picks changes up
+without a commit:
+
+```ruby
+plugin 'bundler-codegraph', path: '/path/to/bundler-codegraph'
+```
+
+Bundler installs it into `.bundle/plugin/` on the next `bundle install`.
+
+**Every update of the plugin goes through an uninstall.** Bundler reinstalls a
+plugin whenever its path changes — a new release, a new commit fetched by
+`bundle update` on a `git:` source, a moved `path:` checkout, a switch from one
+source to another — but registers the new copy without removing the old one,
+and refuses the `codegraph-index` command the old copy still holds:
+
+```
+Failed to install plugin `bundler-codegraph`, due to Bundler::Plugin::Index::CommandConflict (Command(s) `codegraph-index` declared by bundler-codegraph are already registered.)
+```
+
+That is Bundler's doing (checked on 4.0.17), and it hits any plugin that
+declares a command. Uninstall first, then install again:
+
+```bash
+bundle plugin uninstall bundler-codegraph && bundle install
+```
+
+There is no `bundle plugin update`: this is also how a `git:` clone, pinned to
+the commit resolved at install time, moves forward.
+
+## Usage
+
+Nothing to run: every gem of the bundle is indexed at the end of each
+`bundle install`.
+
+A bundle that is already in place needs one catch-up pass:
+
+```bash
+bundle codegraph-index          # index every gem that has none, sync the others
+bundle codegraph-index --force  # rebuild all of them
+```
+
+Without `--force`, an index already in place goes through `codegraph sync`,
+which also completes an index a killed run left partial.
+
+The command exits non-zero on an unknown argument, when the `codegraph` binary
+cannot be found (checked before walking the bundle), and — after trying every
+gem — when any of them failed to index, so a script or a CI job can tell.
+`bundle codegraph-index --help` (or `bundle help codegraph-index`) prints its
+usage.
+
+Both walk the *resolved* bundle (`Bundler.definition.specs`, minus `bundler`
+itself and minus the project's own gemspec — a gem project declaring `gemspec`
+is not one of its dependencies), not the contents of `.bundle/ruby/*/gems/`.
+Stale checkouts and older versions of a gem sitting next to the one in
+`Gemfile.lock` are left alone, so an unindexed directory down there is expected
+rather than a missed gem. Gems installed from a Git source live in
+`.bundle/ruby/*/bundler/gems/`, and `path:` sources are indexed where they sit.
+codegraph drops a `.gitignore` inside `.codegraph/` that ignores everything but
+itself, so the database never shows up in Git; that `.gitignore` itself still
+does, as an untracked file — add `.codegraph` to the `.gitignore` of any `path:`
+source tracked by Git to keep its status clean.
+
+## Using the index from an agent
+
+Indexing every gem is only worth it if the agent actually reaches for those
+indexes. Two things are needed.
+
+**Wire up the MCP server.** `codegraph install` configures it for Claude Code,
+Cursor, Codex CLI, opencode and Hermes Agent (`--target`, `--location`, or
+`--print-config <agent>` to just see the snippet). It runs over stdio as
+`codegraph serve --mcp` and exposes `codegraph_explore` — relevant symbols'
+verbatim source plus the call paths between them — and `codegraph_node`, for one
+symbol's caller/callee trail or a line-numbered file read.
+
+Both take a `projectPath`, and the server resolves the nearest `.codegraph/` at
+or above it. **That is what makes this plugin useful**: an index dropped inside a
+gem directory is queryable from any project, without registering each gem as a
+project of its own.
+
+**Tell the agent to use them.** Nothing here changes an agent's default habit of
+grepping through vendored sources, so the rule has to be written down. Something
+along these lines, in the consuming project's `CLAUDE.md` / `AGENTS.md`:
+
+```markdown
+## Dependencies
+
+Every gem of the bundle carries its own CodeGraph index. For a question about a
+dependency's code, query that gem's index rather than reading its files:
+
+- `codegraph_explore` with `projectPath` set to the gem directory, e.g.
+  `.bundle/ruby/4.0.0/gems/rack-3.2.6`
+- or `codegraph explore -p <gem directory> "<symbol or question>"`
+
+Take the version from `Gemfile.lock`: several versions of a gem can sit side by
+side on disk, and only the resolved one is indexed. If a gem has no
+`.codegraph/` directory, run `bundle codegraph-index` at the project root and
+retry.
+```
+
+## How it works
+
+`plugins.rb` registers two hooks and a command with Bundler, and is the only
+file in the repository that touches Bundler's plugin API.
+
+**The install hooks.** Bundler emits `GEM_AFTER_INSTALL` once per gem, from the
+install worker that handled it — on Bundler 4 (checked on 4.0.17) for every gem
+of the bundle on every `bundle install`, whether it was just installed or
+already there. The plugin checks the install succeeded and only queues the gem:
+indexing from the worker would hold it for as long as `codegraph` runs and stall
+the rest of the install. Once everything is installed Bundler emits
+`GEM_AFTER_INSTALL_ALL`, and the plugin runs `codegraph init <gem path>` on each
+queued gem, one at a time, which drops a `.codegraph/` directory next to the
+gem's sources. A `bundle install` that fails never emits that second hook, so
+the gems it did install stay unindexed until `bundle codegraph-index` runs.
+Each gem it indexes prints a `bundler-codegraph: indexed <gem>` line, so a cold
+install that spends minutes in `codegraph` after Bundler is done does not look
+hung. Three properties of that indexing pass are deliberate:
+
+- *It never raises.* Every outcome — binary missing, no Ruby source, index
+  already there, `codegraph` exiting non-zero — comes back as a status symbol
+  and is swallowed. An exception raised from a Bundler hook aborts the entire
+  `bundle install`, and a failed index is never a good enough reason to break
+  someone's install. A gem `codegraph` fails on still gets a one-line warning,
+  pointing at its error output, kept in
+  `bundler-codegraph-<uid>/<gem directory>-<digest>.log` (`rack-3.2.6-…log`) under
+  `Dir.tmpdir` until a later run succeeds. The hook does not retry that gem on
+  the next `bundle install` — it would pay the same failure every time — and
+  says so in a `skipped` line, until a new version lands in a new directory,
+  `bundle codegraph-index` retries it, or the system purges its temporary
+  directory (macOS does on its own, Linux usually at boot). A `path:` source
+  keeps its directory: after fixing it, run `bundle codegraph-index`. An interrupted run
+  (codegraph is stopped before the cleanup, killed if it ignores TERM), a `codegraph` killed by a signal
+  (the OOM killer) or one that could not even start is not a failure: no log is
+  kept, and the gem is tried again next time.
+- *It never leaves a partial index.* An index is a `.codegraph/codegraph.db`,
+  and `codegraph init` creates `.codegraph/` before it starts indexing, so a run
+  that fails or is interrupted (Ctrl-C included) has its `.codegraph/` removed
+  rather than left for the next run to mistake for a complete index; a bare
+  `.codegraph/` without its database is such a leftover, and is rebuilt.
+  `--force` sets the previous index aside and puts it back when the rebuild
+  fails — or on the next run, when the rebuild was killed outright.
+- *It serializes.* `codegraph` is itself multi-threaded and already saturates
+  several cores, so the queue is indexed one gem at a time, and an advisory
+  `flock` keeps two `bundle install` (or a `bundle install` and a `bundle
+  codegraph-index`) running side by side from indexing at once. The lock file
+  sits in a private per-user directory, `bundler-codegraph-<uid>` under
+  `Dir.tmpdir`, created `0700` (and closed again if it is yours but was left
+  open); when that path is not a directory owned by you — someone planted it
+  in a shared `/tmp` — indexing runs unserialized and without error logs
+  rather than trusting it, and both the hook and `bundle codegraph-index` say
+  so.
+
+**The `codegraph-index` command.** The catch-up pass for whatever the hooks
+missed — a failed `bundle install`, an index deleted by hand — and it reports a
+per-gem status so it is obvious what was skipped and why. It is also the repair
+pass: it runs `codegraph sync` on every index already there, which completes
+one a killed `bundle install` left partial — something the hook cannot see,
+since it skips existing indexes to keep `bundle install` fast — and it retries
+the gems the hook stopped retrying after a failure.
+
+## Configuration
+
+| Variable | Effect |
+| --- | --- |
+| `BUNDLER_CODEGRAPH` | `0`, `off`, `false` or `no` disables the plugin entirely |
+| `BUNDLER_CODEGRAPH_EXCLUDE` | Comma-separated glob patterns matched against gem names, e.g. `tzinfo-data,rails-*` |
+| `BUNDLER_CODEGRAPH_BIN` | Absolute path to the `codegraph` binary when it is not on `PATH` |
+
+There is no *include* list on purpose: restricting a run to a handful of gems is
+rare enough that negative globs do the job, and an include list would silently
+shrink the coverage a later `bundle install` is expected to produce.
+
+## Cost
+
+Expect an index to weigh roughly **four times the gem's source**: rack 3.2.6 is
+528 kB on disk and produces a 2.1 MB index, built in under a second. Scaled to a
+real application — a ~400-gem bundle — that is a few minutes for the initial
+catch-up pass and somewhere around 600 MB next to the gems. Gems holding no Ruby
+source at all are skipped, and the hook skips gems that already carry an index
+(`.codegraph/codegraph.db`), so the steady-state cost after the first pass is
+only whatever `bundle update` brings in. `bundle codegraph-index` syncs those
+existing indexes instead, at a fraction of a second each on a healthy one.
+
+An index lands next to its gem, wherever Bundler installed it. With a
+project-local `BUNDLE_PATH` (`bundle config set --local path .bundle`, as the
+examples above assume) that is the project's `.bundle/`. Without one, gems —
+and so their indexes — live in the Ruby installation's shared `GEM_HOME`, used
+by every project on that Ruby: the 600 MB land there, an index built for one
+project serves the others, and `bundle codegraph-index --force` in one project
+rebuilds them for all. Set `BUNDLE_PATH` to keep the indexes per project.
+
+`.bundle/` is usually already git-ignored; `path:` sources are not, hence the
+`.gitignore` note above.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+[codegraph]: https://github.com/colbymchenry/codegraph
+[mise]: https://mise.jdx.dev
+[aqua-registry]: https://github.com/jbox-web/aqua-registry

data/lib/bundler/codegraph/backfill.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Codegraph
+
+    # Indexes a whole set of gem specs, one at a time: the queue
+    # `after_install_all` drains at the end of `bundle install`, or the whole
+    # resolved bundle for `bundle codegraph-index`.
+    class Backfill
+
+      attr_reader :specs, :reporter, :indexer_options
+
+      # @param specs [Enumerable] objects responding to `name` and `full_gem_path`
+      # @param reporter [#call, nil] called after each gem with its name, its
+      #   status and `Indexer#log_hint`
+      # @param indexer_options [Hash] handed to every `Indexer` as is (`config:`,
+      #   `force:`, `sync:`, `skip_failed:`), with a single `Config` for them all
+      def initialize(specs, reporter: nil, **indexer_options)
+        @specs           = specs
+        @reporter        = reporter
+        @indexer_options = { config: Config.new }.merge(indexer_options)
+      end
+
+      # @return [Hash{Symbol => Integer}] number of gems per resulting status
+      def call
+        specs.each_with_object(Hash.new(0)) do |spec, results|
+          name, status, log_hint = index(spec)
+          results[status] += 1
+          reporter&.call(name, status, log_hint)
+        end
+      end
+
+      private
+
+      # A spec that cannot even be read counts as a failure of its own, rather
+      # than cutting the pass short for every gem after it.
+      def index(spec)
+        indexer = Indexer.new(spec.full_gem_path, name: spec.name, **indexer_options)
+        [spec.name, indexer.call, indexer.log_hint]
+      rescue StandardError
+        [spec.respond_to?(:name) ? spec.name : spec.to_s, :failed, '']
+      end
+    end
+  end
+end

data/lib/bundler/codegraph/command.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Codegraph
+
+    # `bundle codegraph-index [--force]`
+    #
+    # Indexes every gem of the current bundle, and runs `codegraph sync` on the
+    # indexes already there — which also completes one a killed run left
+    # partial. Loaded only from `plugins.rb`, so the rest of the gem stays
+    # testable without Bundler's plugin API.
+    class Command < Bundler::Plugin::API
+
+      FORCE_FLAG = '--force'
+
+      # Labels for the statuses worth reporting; anything else is silent noise.
+      STATUS_LABELS = {
+        indexed:         'indexed',
+        synced:          'synchronized',
+        already_indexed: 'already indexed',
+        excluded:        'excluded',
+        no_ruby:         'no Ruby source',
+        missing:         'not installed',
+        unavailable:     'codegraph not found',
+        disabled:        'disabled',
+        failed:          'failed',
+      }.freeze
+
+      HELP_FLAGS = %w[--help -h].freeze
+
+      USAGE = <<~USAGE
+        Usage: bundle codegraph-index [--force]
+
+        Indexes every gem of the bundle with codegraph, and syncs the indexes already there.
+
+          --force  rebuild every index from scratch
+      USAGE
+
+      # Exits non-zero (through a `Bundler::BundlerError`) on an unknown
+      # argument, when the binary is missing — before walking the bundle, rather
+      # than reporting every gem as `codegraph not found` — and once every gem
+      # was tried when any of them failed, so a script can tell. `--help` is
+      # what `bundle help codegraph-index` passes.
+      def exec(_command_name, args)
+        return Bundler.ui.info(USAGE) if args.intersect?(HELP_FLAGS)
+
+        force  = force?(args)
+        config = Config.new
+        ensure_executable(config)
+        Codegraph.warn_untrusted_runtime_dir(Bundler.ui, config)
+
+        results = Backfill.new(gem_specs, config: config, force: force, sync: true, reporter: method(:report)).call
+        Bundler.ui.info("\n#{summary(results)}")
+        ensure_no_failure(results)
+      end
+
+      private
+
+      def force?(args)
+        unknown = args - [FORCE_FLAG]
+        raise Bundler::InvalidOption, "Unknown option: #{unknown.join(' ')}" unless unknown.empty?
+
+        args.include?(FORCE_FLAG)
+      end
+
+      def ensure_executable(config)
+        return if config.disabled? || config.executable
+
+        raise Bundler::PluginError, "codegraph not found (#{config.binary})"
+      end
+
+      def ensure_no_failure(results)
+        failed = results[:failed]
+        return if failed.zero?
+
+        raise Bundler::PluginError, "#{failed} gem#{'s' if failed > 1} failed to index"
+      end
+
+      def gem_specs
+        root = Bundler.root
+        Bundler.definition.specs.select { |spec| Codegraph.dependency?(spec, root) }
+      end
+
+      def report(name, status, log_hint)
+        Bundler.ui.info("#{name}: #{STATUS_LABELS.fetch(status, status)}#{log_hint}")
+      end
+
+      def summary(results)
+        results.map { |status, count| "#{count} #{STATUS_LABELS.fetch(status, status)}" }.join(', ')
+      end
+    end
+  end
+end

data/lib/bundler/codegraph/config.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Codegraph
+
+    # Runtime configuration, driven entirely by environment variables so that a
+    # single `bundle install` can be run with indexing off without editing a file.
+    class Config
+
+      ENV_ENABLED = 'BUNDLER_CODEGRAPH'
+      ENV_EXCLUDE = 'BUNDLER_CODEGRAPH_EXCLUDE'
+      ENV_BINARY  = 'BUNDLER_CODEGRAPH_BIN'
+
+      DEFAULT_BINARY  = 'codegraph'
+      DISABLED_VALUES = %w[0 off false no].freeze
+
+      attr_reader :env, :exclude_patterns, :binary
+
+      # @param env [Hash] environment to read the configuration from
+      def initialize(env: ENV)
+        @env                 = env
+        @disabled            = DISABLED_VALUES.include?(env[ENV_ENABLED].to_s.strip.downcase)
+        @exclude_patterns    = env[ENV_EXCLUDE].to_s.split(',').map(&:strip).reject(&:empty?)
+        @binary              = env[ENV_BINARY].to_s.empty? ? DEFAULT_BINARY : env[ENV_BINARY]
+        @executable          = nil
+        @executable_resolved = false
+      end
+
+      # Resolved lazily, once: the `PATH` lookup only runs when something
+      # actually needs the binary.
+      #
+      # @return [String, nil] path of the codegraph executable, nil when not found
+      def executable
+        return @executable if @executable_resolved
+
+        @executable_resolved = true
+        @executable = which(binary)
+      end
+
+      def disabled?
+        @disabled
+      end
+
+      # @param gem_name [String] name of the gem about to be indexed
+      # @return [Boolean] true when the gem matches one of the exclusion globs
+      def excluded?(gem_name)
+        exclude_patterns.any? { |pattern| File.fnmatch?(pattern, gem_name.to_s) }
+      end
+
+      private
+
+      # A name holding a separator is a path: used as is, never looked up on
+      # PATH. An empty PATH entry stands for the current directory, as in POSIX
+      # — `File.join('', name)` would make it the filesystem root.
+      def which(name)
+        return (runnable?(name) ? name : nil) if name.include?(File::SEPARATOR)
+
+        env.fetch('PATH', '').split(File::PATH_SEPARATOR, -1).each do |dir|
+          candidate = File.join(dir.empty? ? '.' : dir, name)
+          return candidate if runnable?(candidate)
+        end
+
+        nil
+      end
+
+      def runnable?(candidate)
+        File.file?(candidate) && File.executable?(candidate)
+      end
+    end
+  end
+end

data/lib/bundler/codegraph/error_log.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+
+module Bundler
+  module Codegraph
+
+    # codegraph's error output for one gem, kept in the runtime directory for
+    # as long as the last run on that gem failed.
+    #
+    # The log starts with the directory it is about, is written under a
+    # temporary name while codegraph runs, and only takes its own name once the
+    # run failed: a log naming a directory means codegraph failed on it and
+    # nothing retried it since — never that a run is still going. A new version
+    # of the gem is a new directory.
+    class ErrorLog
+
+      # Named after the gem directory and a digest of its full path
+      # (`rack-3.2.6-<digest>.log`): two directories of the same name — the
+      # same version in two projects' `.bundle/`, two `path:` sources called
+      # `admin` — keep a log each, instead of erasing each other's on every run.
+      #
+      # @param gem_path [String] directory codegraph runs on
+      # @return [String, nil] nil when the runtime directory cannot be trusted
+      def self.path(gem_path)
+        dir = RuntimeDir.path
+        dir && File.join(dir, "#{File.basename(gem_path)}-#{::Digest::SHA256.hexdigest(gem_path)[0, 12]}.log")
+      end
+
+      attr_reader :path, :gem_path
+
+      # @param gem_path [String] directory codegraph runs on
+      def initialize(gem_path)
+        @path     = self.class.path(gem_path)
+        @gem_path = gem_path
+        @kept     = false
+        @logged   = false
+      end
+
+      # Whether the last `capture` kept a log — the only log a failure message
+      # may point at: one found on disk could predate this attempt, or belong
+      # to another process working on another version of the gem.
+      def kept?
+        @kept
+      end
+
+      # Where to find codegraph's error output, as a suffix for a failure
+      # message; empty unless this attempt kept a log.
+      #
+      # @return [String]
+      def hint
+        kept? ? ", see #{path}" : ''
+      end
+
+      def failed_before?
+        return false unless path && File.exist?(path)
+
+        File.foreach(path).first&.chomp == gem_path
+      end
+
+      def discard
+        FileUtils.rm_f(path) if path
+      end
+
+      # Yields the stream codegraph's stderr should go to, and keeps the log
+      # only when the block returns a failure. An exception — `Interrupt`
+      # included — drops it too: codegraph did not fail, it was stopped, and a
+      # kept log would stop the hook from ever retrying the gem.
+      #
+      # Only an explicit `false` is a codegraph failure: `nil` means it could
+      # not even be started. A log that cannot be opened (full disk) must not
+      # cost the index either, so codegraph then runs without one.
+      #
+      # @return the block's value
+      def capture(&)
+        @kept = false
+        return yield(File::NULL) unless path
+
+        succeeded = write(&)
+        @kept = succeeded == false && @logged && publish
+        succeeded
+      ensure
+        FileUtils.rm_f(partial_path) if path
+      end
+
+      private
+
+      def partial_path
+        "#{path}.part"
+      end
+
+      # The header goes in first. A log that cannot be opened or written (full
+      # disk) falls back to running codegraph without one — and is never
+      # published, empty, as the log of a failure; an error raised by the block
+      # itself propagates, rather than running codegraph twice.
+      def write
+        @logged = false
+        File.open(partial_path, 'w', 0o600) do |file|
+          file.puts(gem_path)
+          file.flush
+          @logged = true
+          return yield file
+        end
+      rescue SystemCallError
+        raise if @logged
+
+        yield File::NULL
+      end
+
+      def publish
+        File.rename(partial_path, path)
+        true
+      rescue SystemCallError
+        false
+      end
+    end
+  end
+end

data/lib/bundler/codegraph/indexer.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Bundler
+  module Codegraph
+
+    # Builds a CodeGraph index for a single gem directory.
+    #
+    # Never raises: every failure mode is reported as a status symbol, because
+    # this runs from a Bundler hook where an exception would abort the whole
+    # `bundle install`.
+    class Indexer
+
+      INDEX_DIRNAME  = '.codegraph'
+      DATABASE_NAME  = 'codegraph.db'
+      BACKUP_DIRNAME = '.codegraph.bundler-codegraph-backup'
+
+      attr_reader :path, :name, :config, :force, :sync, :skip_failed
+
+      # @param path [String] absolute path of the directory to index
+      # @param name [String] gem name, used for the exclusion patterns
+      # @param config [Config]
+      # @param force [Boolean] drop and rebuild an existing index
+      # @param sync [Boolean] run `codegraph sync` on an existing index instead
+      #   of skipping it, which also completes an index a killed run left behind
+      # @param skip_failed [Boolean] skip a directory codegraph already failed
+      #   on, as long as its error log is there
+      # rubocop:disable-next Metrics/ParameterLists
+      def initialize(path, name:, config: Config.new, force: false, sync: false, skip_failed: false)
+        @path        = path.to_s
+        @name        = name.to_s
+        @config      = config
+        @force       = force
+        @sync        = sync
+        @skip_failed = skip_failed
+        @error_log   = nil
+      end
+
+      # @return [Symbol] :indexed, :synced, :failed, :disabled, :excluded,
+      #   :missing, :failed_before, :no_ruby, :already_indexed or :unavailable
+      def call
+        skipped = skip_reason
+        return skipped if skipped
+
+        Lock.synchronize do
+          error_log.discard
+          run
+        end
+      rescue StandardError
+        :failed
+      end
+
+      # Where to find codegraph's error output after `call`, as a suffix for a
+      # failure message (see `ErrorLog#hint`).
+      #
+      # @return [String]
+      def log_hint
+        @error_log ? @error_log.hint : ''
+      end
+
+      # Same criterion as codegraph itself: a `.codegraph/` directory without
+      # its database is a leftover, not an index.
+      def indexed?
+        File.exist?(File.join(index_path, DATABASE_NAME))
+      end
+
+      private
+
+      # Ordered cheapest-first: configuration, then single stats, then the PATH
+      # lookup (done once per Config), and the walk of the gem's tree last.
+      def skip_reason
+        config_skip_reason || filesystem_skip_reason
+      end
+
+      def config_skip_reason
+        return :disabled if config.disabled?
+        return :excluded if config.excluded?(name)
+
+        nil
+      end
+
+      def filesystem_skip_reason
+        return :missing         unless Dir.exist?(path)
+        return :already_indexed if keep_index?
+        return :unavailable     unless executable
+        return :failed_before   if skip_failed && error_log.failed_before?
+        return :no_ruby         unless ruby_sources?
+
+        nil
+      end
+
+      # An index this run leaves alone: present, neither forced nor synced, and
+      # not sitting next to the backup a killed `--force` rebuild left behind.
+      def keep_index?
+        indexed? && !force && !sync && !Dir.exist?(backup_path)
+      end
+
+      # Stops at the first hit instead of materializing the whole file list.
+      # The path goes through `base:`, never into the pattern: a checkout under
+      # a directory named `client [2026]` would otherwise match nothing.
+      def ruby_sources?
+        Dir.glob('**/*.rb', base: path) { |_file| return true }
+        false
+      end
+
+      def executable
+        config.executable
+      end
+
+      # Checks for an index again: another process may have built it while this
+      # one waited for the lock.
+      #
+      # A backup only outlives a `--force` rebuild that never reached its
+      # `ensure` (SIGKILL, OOM): whatever `.codegraph/` holds then is that
+      # unfinished rebuild, and the backup is the index to keep.
+      def run
+        restore_backup
+        return build unless indexed?
+        return rebuild if force
+
+        sync ? refresh : :already_indexed
+      end
+
+      # `codegraph init` creates `.codegraph/` before it starts indexing, so a
+      # failed or interrupted run leaves a partial index behind that the next
+      # run would take for a complete one. Whatever is there when the build does
+      # not succeed is therefore removed, a stale leftover included.
+      def build
+        FileUtils.rm_rf(index_path)
+        succeeded = codegraph('init')
+        succeeded ? :indexed : :failed
+      ensure
+        FileUtils.rm_rf(index_path) unless succeeded
+      end
+
+      # The previous index is set aside rather than deleted, and put back when
+      # the rebuild does not succeed.
+      def rebuild
+        FileUtils.rm_rf(backup_path)
+        File.rename(index_path, backup_path)
+        status = build
+      ensure
+        status == :indexed ? FileUtils.rm_rf(backup_path) : restore_backup
+      end
+
+      def restore_backup
+        return unless Dir.exist?(backup_path)
+
+        FileUtils.rm_rf(index_path)
+        File.rename(backup_path, index_path)
+      end
+
+      def refresh
+        codegraph('sync') ? :synced : :failed
+      end
+
+      # stdin is closed off too: codegraph prompts on it in some setups (live
+      # watching disabled, a Git checkout), and with its output going to
+      # /dev/null the question would be invisible and `bundle install` would
+      # hang on it. At EOF the prompt is cancelled and codegraph moves on.
+      # stderr goes to the gem's `ErrorLog`, kept only when the run fails.
+      def codegraph(command)
+        error_log.capture { |stderr| Subprocess.run([executable, command, path], stderr) }
+      end
+
+      # The log of an earlier run is discarded once this one holds the lock
+      # (see `call`) — never earlier, where it could be another process's log
+      # still being written — so a log that exists afterwards always holds codegraph's
+      # output from this run — never a stale one, when this run failed before
+      # codegraph even ran.
+      def error_log
+        @error_log ||= ErrorLog.new(path)
+      end
+
+      def index_path
+        File.join(path, INDEX_DIRNAME)
+      end
+
+      def backup_path
+        File.join(path, BACKUP_DIRNAME)
+      end
+    end
+  end
+end

data/lib/bundler/codegraph/lock.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+
+module Bundler
+  module Codegraph
+
+    # Serializes indexing across processes.
+    #
+    # `codegraph` already saturates several cores on its own. Within one
+    # `bundle install` the queue is drained one gem at a time; this advisory
+    # file lock covers several `bundle install` (or a `bundle codegraph-index`)
+    # running side by side.
+    module Lock
+
+      LOCK_FILENAME = 'bundler-codegraph.lock'
+
+      # @return [String, nil] nil when the runtime directory cannot be trusted
+      def self.path
+        dir = RuntimeDir.path
+        dir && File.join(dir, LOCK_FILENAME)
+      end
+
+      # Runs the block while holding the exclusive lock. An untrusted runtime
+      # directory, or a filesystem without working advisory locks, degrades to
+      # running unserialized rather than failing.
+      #
+      # Only opening and locking may fall back: an error raised by the block
+      # itself propagates, rather than running the block a second time, unlocked.
+      def self.synchronize(&)
+        lock_path = path
+        lock_path ? with_lock(lock_path, &) : yield
+      end
+
+      def self.with_lock(lock_path)
+        locked = false
+        File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |file|
+          file.flock(File::LOCK_EX)
+          locked = true
+          return yield
+        end
+      rescue SystemCallError, NotImplementedError
+        raise if locked
+
+        yield
+      end
+      private_class_method :with_lock
+    end
+  end
+end

data/lib/bundler/codegraph/runtime_dir.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+
+module Bundler
+  module Codegraph
+
+    # A private directory for the plugin's runtime files, one per user under
+    # `Dir.tmpdir`.
+    #
+    # On Linux `Dir.tmpdir` is the shared `/tmp`, where a fixed file name lets
+    # another user create it first — and then either hold the lock forever or
+    # leave it unopenable. The directory is created 0700 and only trusted when
+    # it is a real directory (not a symlink), owned by the current user and
+    # closed to everyone else; callers degrade gracefully when it is not.
+    module RuntimeDir
+
+      # @return [String] where the directory lives, trusted or not
+      def self.candidate
+        File.join(Dir.tmpdir, "bundler-codegraph-#{Process.uid}")
+      end
+
+      # @return [String, nil] the directory, nil when it cannot be trusted
+      def self.path
+        dir = candidate
+        create(dir)
+        trusted?(dir) ? dir : nil
+      rescue SystemCallError
+        nil
+      end
+
+      # A directory already there and ours — a real directory, not a symlink
+      # — is closed to others if it was left open (a umask, another tool):
+      # otherwise it would stay untrusted, and the lock and logs off, for good.
+      def self.create(dir)
+        Dir.mkdir(dir, 0o700)
+      rescue Errno::EEXIST
+        stat = File.lstat(dir)
+        File.chmod(0o700, dir) if stat.directory? && stat.uid == Process.uid
+      end
+      private_class_method :create
+
+      # Owned by `Process.uid`, the same id the directory is named after —
+      # `File::Stat#owned?` compares with the effective uid instead.
+      def self.trusted?(dir)
+        stat = File.lstat(dir)
+        stat.directory? && stat.uid == Process.uid && stat.mode.nobits?(0o077)
+      end
+      private_class_method :trusted?
+    end
+  end
+end

data/lib/bundler/codegraph/subprocess.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Codegraph
+
+    # Runs codegraph as a child process, stdin and stdout closed off.
+    #
+    # `Kernel#system` would leave the child running when this process alone
+    # is interrupted (SIGTERM to Ruby, not its process group): the cleanup that
+    # follows — removing a partial index, releasing the lock — would then happen
+    # under a live codegraph. The child is stopped and reaped first.
+    module Subprocess
+
+      # How long a child gets to exit on TERM before it is killed.
+      STOP_TIMEOUT = 5
+
+      # @param argv [Array<String>] command line
+      # @param stderr [IO, String] where the child's error output goes
+      # @return [Boolean, nil] like `system`, except that a child killed by a
+      #   signal (the OOM killer) gives nil, as one that cannot be started: it
+      #   did not fail, it was stopped
+      def self.run(argv, stderr)
+        pid = Process.spawn(*argv, in: File::NULL, out: File::NULL, err: stderr)
+        status = Process.wait2(pid).last
+        pid = nil
+        status.success? || (status.signaled? ? nil : false)
+      rescue SystemCallError
+        nil
+      ensure
+        stop(pid) if pid
+      end
+
+      # TERM first, KILL once STOP_TIMEOUT is over: a child that ignores TERM
+      # must not hang `bundle install` in an `ensure`. A child already reaped
+      # (the interrupt landed right after `wait2`) is never signalled, as its
+      # pid may have been reused.
+      def self.stop(pid)
+        return if reaped?(pid)
+
+        Process.kill('TERM', pid)
+        return if exited_within?(pid, STOP_TIMEOUT)
+
+        Process.kill('KILL', pid)
+        Process.wait(pid)
+      rescue SystemCallError
+        nil
+      end
+      private_class_method :stop
+
+      def self.reaped?(pid)
+        !Process.wait(pid, Process::WNOHANG).nil?
+      rescue Errno::ECHILD
+        true
+      end
+      private_class_method :reaped?
+
+      def self.exited_within?(pid, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        until Process.wait(pid, Process::WNOHANG)
+          return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+          sleep 0.05
+        end
+        true
+      end
+      private_class_method :exited_within?
+    end
+  end
+end

data/lib/bundler/codegraph/version.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Codegraph
+
+    def self.gem_version
+      Gem::Version.new VERSION::STRING
+    end
+
+    module VERSION
+      MAJOR = 0
+      MINOR = 1
+      TINY  = 0
+      PRE   = nil
+
+      STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')
+    end
+  end
+end

data/lib/bundler/codegraph.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative 'codegraph/version'
+require_relative 'codegraph/config'
+require_relative 'codegraph/runtime_dir'
+require_relative 'codegraph/error_log'
+require_relative 'codegraph/lock'
+require_relative 'codegraph/subprocess'
+require_relative 'codegraph/indexer'
+require_relative 'codegraph/backfill'
+
+module Bundler
+
+  # Bundler plugin building a CodeGraph index inside every gem it installs, so
+  # that an agent can query a dependency's source through `codegraph explore
+  # --path <gem>` instead of reading its files by hand.
+  module Codegraph
+
+    # Specs queued by `after_install`, drained by `after_install_all`. A
+    # `Thread::Queue` because Bundler fires `after-install` from each of its
+    # parallel install workers.
+    @pending = Queue.new
+
+    class << self
+      attr_reader :pending
+    end
+
+    # Entry point wired to Bundler's `after-install` hook, which fires from the
+    # install workers themselves. Indexing there would hold a worker for as long
+    # as `codegraph` runs, and stall the rest of the install behind it: the gem
+    # is only queued, and `after_install_all` indexes the queue once installing
+    # is over.
+    #
+    # Swallows everything: the hook also fires for failed installs, and a broken
+    # index must never be the reason a `bundle install` aborts.
+    #
+    # @param spec_install [Bundler::ParallelInstaller::SpecInstallation]
+    # @param root [Pathname, String, nil] root of the project being installed,
+    #   `Bundler.root` by default — resolved in the body, where the rescue
+    #   covers it, never as a keyword default, which is evaluated outside it
+    # @return [nil]
+    def self.after_install(spec_install, root: nil)
+      return unless spec_install.respond_to?(:installed?) && spec_install.installed?
+
+      spec = spec_install.spec
+      pending << spec if dependency?(spec, root || Bundler.root)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # Entry point wired to Bundler's `after-install-all` hook, fired once every
+    # gem is installed — and not at all when the install fails, in which case
+    # `bundle codegraph-index` picks up whatever was left unindexed.
+    #
+    # Swallows everything, for the same reason as `after_install`, but warns
+    # about each gem that failed to index, pointing at codegraph's error output.
+    #
+    # @param config [Config, nil] read from the environment by default
+    # @param shell [#warn, nil] Bundler's UI by default; both are resolved in
+    #   the body, where the rescue covers them
+    # @return [Hash{Symbol => Integer}, nil] number of gems per resulting status
+    def self.after_install_all(config: nil, shell: nil)
+      config ||= Config.new
+      shell  ||= Bundler.ui
+      specs = []
+      specs << pending.pop until pending.empty?
+      warn_untrusted_runtime_dir(shell, config) unless specs.empty?
+      # Bundler fires `after-install` for every gem on every `bundle install`:
+      # a gem codegraph fails on is not retried each time, only once it changes
+      # or when `bundle codegraph-index` runs.
+      Backfill.new(specs, config: config, skip_failed: true, reporter: reporter_for(shell)).call
+    rescue StandardError
+      nil
+    end
+
+    # One line per gem actually indexed — a cold install can spend minutes in
+    # codegraph after Bundler is done — one per gem skipped after an earlier
+    # failure, so it is never left unindexed without a word, and a warning
+    # per new failure. Printing may fail (`bundle install | head` closes the
+    # pipe); that must not cost the rest of the queue.
+    def self.reporter_for(shell)
+      lambda do |name, status, log_hint|
+        report(shell, name, status, log_hint)
+      rescue StandardError
+        nil
+      end
+    end
+    private_class_method :reporter_for
+
+    def self.report(shell, name, status, log_hint)
+      case status
+      when :indexed then shell.info("bundler-codegraph: indexed #{name}")
+      when :failed_before
+        shell.info("bundler-codegraph: skipped #{name}, codegraph failed on it before; " \
+                   '`bundle codegraph-index` retries it')
+      when :failed then shell.warn("bundler-codegraph: indexing #{name} failed#{log_hint}")
+      end
+    end
+    private_class_method :report
+
+    # Without a trusted runtime directory the lock and the error logs are both
+    # off; say so once rather than let it pass unnoticed — as long as there is
+    # any indexing to run at all.
+    def self.warn_untrusted_runtime_dir(shell, config)
+      return if config.disabled? || !config.executable || RuntimeDir.path
+
+      shell.warn("bundler-codegraph: #{RuntimeDir.candidate} is not a private directory, " \
+                 'so indexing runs unserialized and without error logs')
+    end
+
+    # Whether a spec of the bundle is a dependency worth indexing. `bundler`
+    # itself lives in the Ruby installation, outside the bundle. A project
+    # declaring `gemspec` gets its own spec back as a `path:` source rooted at
+    # the project directory, which is the project, not a dependency: it is
+    # told by its `Bundler::Source::Gemspec` source, since the Gemfile need not
+    # sit at the root (Appraisal's `gemfiles/*.gemfile` use `gemspec path:
+    # '../'`), and by its path for specs that carry no source.
+    #
+    # @param spec [#name, #full_gem_path]
+    # @param root [Pathname, String] root of the project
+    def self.dependency?(spec, root)
+      return false if spec.name == 'bundler' || own_gemspec?(spec)
+
+      File.expand_path(spec.full_gem_path) != File.expand_path(root.to_s)
+    end
+
+    def self.own_gemspec?(spec)
+      defined?(Bundler::Source::Gemspec) && spec.respond_to?(:source) && spec.source.is_a?(Bundler::Source::Gemspec)
+    end
+    private_class_method :own_gemspec?
+  end
+end

data/plugins.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'lib/bundler/codegraph'
+require_relative 'lib/bundler/codegraph/command'
+
+# Fired once per gem, from each parallel install worker: only queues the gem.
+Bundler::Plugin::API.hook(Bundler::Plugin::Events::GEM_AFTER_INSTALL) do |spec_install|
+  Bundler::Codegraph.after_install(spec_install)
+end
+
+# Fired once, after every gem is installed: indexes the queue.
+Bundler::Plugin::API.hook(Bundler::Plugin::Events::GEM_AFTER_INSTALL_ALL) do |_dependencies|
+  Bundler::Codegraph.after_install_all
+end
+
+Bundler::Plugin::API.command('codegraph-index', Bundler::Codegraph::Command)

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: bundler-codegraph
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicolas Rodriguez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A Bundler plugin running `codegraph init` on each installed gem.
+email:
+- nico@nicoladmin.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/bundler/codegraph.rb
+- lib/bundler/codegraph/backfill.rb
+- lib/bundler/codegraph/command.rb
+- lib/bundler/codegraph/config.rb
+- lib/bundler/codegraph/error_log.rb
+- lib/bundler/codegraph/indexer.rb
+- lib/bundler/codegraph/lock.rb
+- lib/bundler/codegraph/runtime_dir.rb
+- lib/bundler/codegraph/subprocess.rb
+- lib/bundler/codegraph/version.rb
+- plugins.rb
+homepage: https://github.com/jbox-web/bundler-codegraph
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Build a CodeGraph index for every gem Bundler installs.
+test_files: []