scryer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e14bfb1c3912e5ce4773838e90a19b9f5acd3814cf8f216052ca91784473863b
+  data.tar.gz: 9f70388a0d3537da003c1c621117df0c3bf953e0a3aaea63e8b56ea4dc3c8d1f
+SHA512:
+  metadata.gz: 387810bd90bd1031be8c6b0b8debf3ee0ef91dfa982dfdf03afb331be07d7d41379b6e4e33fc340465c7da1e7f9d28a5eb186b2ec630826d54fb9522953085ec
+  data.tar.gz: d2adf3bb70c181e2c874354c963828fb06e6dcd69dec7417b69fe064653da1df1b9a7cc82a14e4b7dd5fe4623876978dfb4a28469ae63d87df6c54d544334455

data/README.md

@@ -0,0 +1,367 @@
+# Scryer
+
+A static code analyzer for Rails apps, built on Ruby's own `Ripper` (stdlib — no Rails or
+`bundle install` needed to run the scan itself). Reports three things:
+
+- **Security findings**: SQL injection via string interpolation, unpermitted mass assignment,
+  command injection, hardcoded API keys/secrets, unsafe deserialization (`Marshal.load`/
+  `YAML.load`/`JSON.load`), unescaped-HTML XSS risk (`.html_safe`/`raw`), CSRF protection gaps,
+  weak password hashing, and open redirects.
+- **Duplicate code**: near-duplicate methods across the codebase, via token-normalized similarity
+  (renamed variables/changed literals still count as "the same shape").
+- **Performance heuristics**: likely N+1 queries, missing pagination on index actions,
+  inefficient per-record save loops, and unbounded full-table iteration.
+
+Several more things live alongside the static scan, each documented in its own section below:
+
+- **Skipping rules** ([Skipping rules](#skipping-rules)): silence a specific rule by `rule_id`
+  (config-wide via `c.skip_rules`, or one-off via `--skip`) without editing or deleting it.
+- A **runtime query watcher** ([Runtime query watcher](#runtime-query-watcher)) that instruments a
+  *running* app to catch N+1 queries and unused eager loading as they actually happen — the same
+  broad goal as [Bullet](https://github.com/flyerhzm/bullet), built independently on a different
+  mechanism.
+- A **dependency audit** ([Dependency audit](#dependency-audit)) that checks `Gemfile.lock` against
+  [OSV.dev](https://osv.dev) for known-vulnerable gem versions and insecure sources — the same
+  broad goal as [bundler-audit](https://github.com/rubysec/bundler-audit), built independently on a
+  different data source.
+- **AI-assisted fix suggestions** ([AI-assisted fix suggestions](#ai-assisted-fix-suggestions)),
+  optional, provider-agnostic: rewrites each finding's `suggested_fix` against its actual code
+  using an LLM you configure — any LLM, not a specific vendor.
+
+Every finding includes a `suggested_fix` — human-reviewable text explaining the issue with an
+example. **Nothing is auto-applied.** A security or performance fix needs a human's judgment
+about the surrounding code; this gem's job is to point at the issue and explain it clearly, not
+to rewrite your files. This holds whether `suggested_fix` came from a rule's static template or
+from the optional AI enrichment below — either way, it's text for a human to read and act on.
+
+## A note on how this gem was actually verified
+
+Unlike most hand-written Rails work, this gem's core scanning engine was genuinely executed
+during development — `Ripper` needs no Rails or bundler to run, so every rule here was tested
+against real vulnerable-code and clean/fixed-code fixtures, not just written and hoped for. Where
+a rule produced a false positive during that testing (an actual one did — `BCrypt::Password.create`
+initially tripped the mass-assignment rule meant for `Model.create(params)`), it was caught and
+fixed before being considered done. That's a meaningfully higher bar of confidence than most of
+this account's Rails-app work, which can't be executed in the sandbox it was built in.
+
+That said: this is a heuristic tool, not full data-flow/taint analysis (that's what a mature tool
+like Brakeman spends years building). Expect some false positives and false negatives — that's
+normal for this class of tool, not a bug. An already-guarded call can still get flagged since
+rules don't trace surrounding conditionals — always review a finding in its surrounding context
+before acting on it.
+
+## Install
+
+Scryer is a development-time analysis tool, not something a running production process needs —
+scope it to the `:development` group so a production deploy (typically `bundle install --without
+development`, or `BUNDLE_WITHOUT=development` in CI) never installs it at all:
+
+```ruby
+# Gemfile
+group :development do
+  gem "scryer"
+end
+```
+
+```bash
+bundle install
+bin/rails generate scryer:install
+```
+
+This drops a commented `config/initializers/scryer.rb` into your app — see
+[Generators](#generators) below for exactly what it does and what each setting controls. Scryer
+is entirely local: there is nothing to point at a server and nothing to authenticate, so the
+generator's only job is letting you override the defaults (project name, which directories get
+scanned, the branch label).
+
+## Running a scan
+
+```bash
+bin/rails scryer:report   # writes tmp/scryer_report.{json,html}
+```
+
+By default this writes both `tmp/scryer_report.json` and `tmp/scryer_report.html`. Both format
+and output path are configurable via task args — any mix of `json`, `html`, `csv` plus at most one
+path (quote the whole thing so your shell doesn't eat the brackets/commas, e.g.
+`bin/rails 'scryer:report[json,doc/security_report.json]'`). Rake splits bracket args on every
+comma, so each format is its own item in the list rather than one comma-joined string
+(`scryer:report[json,html]` is two args, not `"json,html"` as one). At most one non-format token
+is accepted per call; giving two raises an error rather than guessing which one you meant.
+
+Outside a Rails app (or in CI, or anywhere you don't want a rake task), the gem also ships a
+`scryer` executable — same idea as `brakeman -o report.json`, with `-o` repeatable and format
+inferred per-file from its extension:
+
+```bash
+scryer                                    # scans ., writes tmp/scryer_report.{json,html}
+scryer -o report.json                     # just one file, exact path, format from extension
+scryer -o report.json -o report.html      # as many outputs as you like, one -o each
+scryer -p /path/to/app -o /tmp/out.html   # -p sets the root to scan (default: cwd)
+scryer --help                             # full option list (--project-name, --branch, --version, ...)
+```
+
+It exits `0` when the scan is clean and `1` when there's at least one security finding, so
+`scryer -o report.json` can gate a CI job the same way `brakeman -o report.json` does. A `2` exit
+means a usage error (bad flag, unrecognized output extension) rather than anything about the scan
+itself.
+
+Or use the scanning engine directly as a library:
+
+```ruby
+require "scryer"
+result = Scryer::Scanner.new(root: "/path/to/app").call
+puts result.security_findings.size
+```
+
+Open `tmp/scryer_report.html` in a browser — it's a single self-contained file (inline CSS, no
+external assets, works offline) with an overview, a summary of counts by severity, the full list
+of checks that ran, a breakdown of warnings by type, every finding in detail, and duplicate-code
+groups — laid out similarly to a Brakeman report. `tmp/scryer_report.json` has the same data in
+machine-readable form, for feeding into your own dashboard or CI gate. A third format, `.csv`
+(`scryer -o report.csv` / `rails 'scryer:report[csv]'`), is a flat one-row-per-finding table
+(security + performance findings, plus dependency findings if `--include-deps`/`deps` was used) —
+handy for dropping into a spreadsheet or importing into a ticketing tool. It skips duplicate-code
+groups, which don't reduce to a single actionable row.
+
+## What gets scanned
+
+By default: `app/`, `lib/`, `config/`, `db/` (relative to the app root) — configurable via
+`c.dirs` in the initializer. `vendor/`, `node_modules/`, `tmp/`, `log/`, `.git/`, `spec/`, `test/`
+are always skipped.
+
+## Branch reporting
+
+By default the `git_branch` recorded in the report comes from `git rev-parse --abbrev-ref HEAD` in
+the app root. Set `c.branch` in the initializer to override this — useful in CI, where checkouts
+often land in a detached-HEAD state and there's no real branch name to detect:
+
+```ruby
+Scryer.configure do |c|
+  c.branch = ENV["CI_COMMIT_BRANCH"]
+end
+```
+
+This only changes the label shown in the report; it does not check out a different branch or
+restrict which branch can be scanned.
+
+## Skipping rules
+
+Every rule is heuristic, so an occasional false positive on your specific codebase is expected
+(see "A note on how this gem was actually verified" above) — `skip_rules` silences one by
+`rule_id` without editing or deleting the rule itself, so it still runs (and could still catch a
+real issue) on every other codebase that uses this gem:
+
+```ruby
+# config/initializers/scryer.rb
+Scryer.configure do |c|
+  c.skip_rules = ["mass_assignment"]   # rule_id, from the finding's `rule_id` field
+end
+```
+
+The `scryer` executable's `--skip RULE_ID` flag (repeatable) adds to this list for a single run
+without touching the initializer — useful for a one-off "does this go away without rule X" check:
+
+```bash
+scryer --skip mass_assignment --skip weak_crypto
+```
+
+## Runtime query watcher
+
+Everything above is a one-shot static scan — it reads source, never boots Rails, and can't see
+what actually happens at request time. `Scryer::QueryWatcher` is different: it's an opt-in
+runtime instrumentation that watches a *running* app for two of the problems
+[Bullet](https://github.com/flyerhzm/bullet) is best known for catching — a collection query
+followed by one repeat query per row ("N+1"), and an `.includes`/`.preload`/`.eager_load`
+association that gets fetched but never actually read ("unused eager loading"). It was built
+independently of Bullet, on a different mechanism (SQL-shape correlation via
+`ActiveSupport::Notifications`, plus a `Module#prepend` on `ActiveRecord::QueryMethods`'s eager-load
+methods and `Association#reader` — not Bullet's own per-request association bookkeeping); no
+Bullet source was read or copied to build it.
+
+Enable it from an initializer (typically gated to development/test, though nothing stops you from
+running it in production if you want the noise):
+
+```ruby
+# config/initializers/scryer.rb
+if Rails.env.development? || Rails.env.test?
+  require "scryer/query_watcher"
+  Scryer::QueryWatcher.enable!
+  Rails.application.config.middleware.use Scryer::QueryWatcher::Middleware
+end
+```
+
+The middleware opens one tracking scope per request and logs (via `Rails.logger` by default —
+override with `Scryer::QueryWatcher.enable!(logger: ...)`) anything it finds when the request
+ends. Outside a request — a Sidekiq job, a rake task, a console session — wrap the code yourself:
+
+```ruby
+findings = Scryer::QueryWatcher.watch { SomeJob.new.perform }
+```
+
+`enable!(n_plus_one_threshold: 2)` controls how many repeats of the same query shape from the same
+call site count as N+1 (default: the second occurrence already means one collection load produced
+more than one query). Each finding is a `Scryer::QueryWatcher::Finding` with `kind`
+(`n_plus_one_query_runtime` or `unused_eager_load`), `message`, `call_site`, `count`, and
+`suggested_fix` — the same shape as everything else in this gem, so it's straightforward to feed
+into your own logging/alerting instead of (or alongside) the built-in logger call.
+
+This is genuinely runtime-only: with no queries running, it finds nothing, and it never appears in
+the static `tmp/scryer_report.html` output. Think of it as this gem's answer to "what actually
+happened during this request", where the rest of Scryer answers "what does this code look like".
+
+## Dependency audit
+
+`Scryer::DependencyAudit` checks `Gemfile.lock` for the same broad concerns
+[bundler-audit](https://github.com/rubysec/bundler-audit) targets — known-vulnerable gem versions
+and insecure dependency sources — built independently on a different data source and a different
+lockfile parser: rather than bundler-audit's local clone of the `ruby-advisory-db` git repo, this
+queries [OSV.dev](https://osv.dev) (Google's Open Source Vulnerabilities database) live, one
+lookup per gem+version, over a small stdlib-only thread pool; `Gemfile.lock` is read with a small
+hand-rolled parser (see `DependencyAudit.parse_lockfile`) instead of depending on the `bundler`
+library, so it works the same whether or not this happens to run under Bundler. No bundler-audit
+source was read or copied to build this.
+
+```bash
+bin/rails scryer:audit_dependencies   # inside a Rails app
+```
+
+This is the one part of Scryer that needs a live network connection (to reach OSV.dev) — so
+unlike the static scan, it's not part of the default `scryer`/`scryer:report` run; call it
+explicitly, the same way `bundle-audit check` is a separate command from your test suite. It exits
+non-zero if anything is found, so it can gate CI.
+
+Two checks run, and either can be called on its own as a library:
+
+```ruby
+Scryer::DependencyAudit.insecure_sources(Rails.root.to_s)  # offline — no network needed
+Scryer::DependencyAudit.vulnerable_gems(Rails.root.to_s)   # needs network (OSV.dev)
+```
+
+- **Insecure sources**: flags any `GIT`/`PATH` block in `Gemfile.lock` whose `remote:` is
+  unencrypted (`git://` or plain `http://`) — the same supply-chain concern bundler-audit's
+  insecure-source check targets.
+- **Vulnerable gems**: for every RubyGems-sourced gem (git/path-sourced gems are skipped — their
+  version string doesn't necessarily correspond to the same code as the published gem of that
+  name, so checking them against RubyGems advisories could misattribute or miss vulnerabilities),
+  queries OSV.dev for known vulnerabilities affecting that exact version. Each finding carries the
+  advisory id, title, a severity bucketed from OSV's own severity level, a link to the advisory,
+  and the fixed version(s) to upgrade to.
+
+**From the `scryer` executable** (outside a Rails app, or in CI): `scryer --audit-deps` runs the
+same two checks standalone, same output/exit-code behavior as the rake task. `scryer --include-deps`
+folds them into the normal `-o` report instead — one HTML/JSON/CSV file covering static findings
+*and* dependency findings together. And for a single gem, without touching `Gemfile.lock` at all:
+
+```bash
+scryer --check-gem rack            # every advisory ever filed against rack, any version
+scryer --check-gem rack:2.0.8      # only advisories affecting exactly this version
+```
+
+This is the same OSV.dev client `vulnerable_gems` uses, exposed as a one-off lookup — useful for
+"is this gem I'm about to add actually fine" before it's even in your `Gemfile.lock`.
+
+## AI-assisted fix suggestions
+
+Every rule already ships a generic, human-reviewable `suggested_fix` — that's always there and
+needs nothing configured. `Scryer::AiFixSuggester` optionally rewrites that text per finding using
+an LLM, so the suggestion is written against the finding's actual offending line instead of a
+generic template.
+
+**Provider-agnostic by design — bring any LLM.** Scryer doesn't depend on or assume any specific
+vendor's API or SDK (consistent with the zero-runtime-dependency design described in the gemspec).
+Configure `c.ai_client` to any object, or even a bare `Proc`/lambda, that responds to `#call(prompt)`
+(or `#complete(prompt)`) and returns the model's reply as a `String`:
+
+```ruby
+# config/initializers/scryer.rb
+Scryer.configure do |c|
+  # Simplest form: any callable. Wire up whatever SDK/gem you already use —
+  # Scryer never requires one itself.
+  c.ai_client = ->(prompt) { MyLlmClient.chat(prompt) }
+end
+```
+
+This is entirely opt-in: `c.ai_client` is `nil` by default, and with no client configured
+`AiFixSuggester` makes zero network calls and every finding keeps its original `suggested_fix`.
+
+### `Scryer::AiClient` — a ready-made HTTP adapter
+
+For the common case of a JSON/HTTP chat endpoint, `Scryer::AiClient` saves writing the request
+plumbing by hand. It takes the two pieces of vendor-specific shape as plain `Proc`s and handles the
+HTTP call itself (stdlib `Net::HTTP`, no gem):
+
+```ruby
+# Claude (Messages API)
+Scryer.configure do |c|
+  c.ai_client = Scryer::AiClient.new(
+    url: "https://api.anthropic.com/v1/messages",
+    headers: { "x-api-key" => ENV.fetch("ANTHROPIC_API_KEY"), "anthropic-version" => "2023-06-01" },
+    build_request: ->(prompt) { { model: "claude-opus-5", max_tokens: 1024, messages: [{ role: "user", content: prompt }] } },
+    parse_response: ->(json) { json.dig("content", 0, "text") }
+  )
+end
+```
+
+```ruby
+# Any OpenAI-compatible chat completions endpoint (OpenAI itself, a local
+# Ollama/vLLM server, Azure OpenAI, ...) — same adapter, different shape.
+Scryer.configure do |c|
+  c.ai_client = Scryer::AiClient.new(
+    url: "https://api.openai.com/v1/chat/completions",
+    headers: { "Authorization" => "Bearer #{ENV.fetch('OPENAI_API_KEY')}" },
+    build_request: ->(prompt) { { model: "gpt-4o-mini", messages: [{ role: "user", content: prompt }] } },
+    parse_response: ->(json) { json.dig("choices", 0, "message", "content") }
+  )
+end
+```
+
+Neither example pins Scryer to that vendor — `build_request`/`parse_response` are just data telling
+`AiClient` how to shape one HTTP call; point it at any endpoint that takes a JSON body and returns
+a JSON body.
+
+### What happens with it configured
+
+`bin/rails scryer:report` and the `scryer` executable both check `Scryer.configuration.ai_client`
+after scanning and, if set, call `Scryer::AiFixSuggester.enhance_result!(result)` before rendering
+— one LLM call per security/performance finding, run across a small thread pool (same pattern as
+the dependency audit's OSV.dev lookups) rather than one at a time. A client that raises, times out,
+or returns nothing usable just leaves that finding's original `suggested_fix` in place — a failed
+enrichment never fails the scan.
+
+```ruby
+Scryer::AiFixSuggester.enhance!(finding)          # one Finding, in place
+Scryer::AiFixSuggester.enhance_result!(result)    # every finding on a Scanner::Result, in place
+```
+
+**This sends code snippets to whatever endpoint you configure.** `code_snippet`, `message`, and the
+file path are included in the prompt — the same privacy consideration as any third-party service:
+don't point this at an endpoint you don't trust with your source, and be mindful this is a second
+place (besides the HTML report itself) where finding detail leaves your machine.
+
+## Generators
+
+Scryer ships one generator: `scryer:install`. Run `bin/rails generate scryer:install --help`
+in a host app for the full description (also in
+[lib/generators/scryer/USAGE](lib/generators/scryer/USAGE)); short version:
+
+- **What it creates**: a single file, `config/initializers/scryer.rb`, templated from
+  [lib/generators/scryer/templates/scryer_initializer.rb](lib/generators/scryer/templates/scryer_initializer.rb).
+  Nothing else — no routes, no migrations, no controllers/views.
+- **What it doesn't do**: the rake tasks (`scryer:report`) are registered by
+  [Scryer::Railtie](lib/scryer/railtie.rb) as soon as the gem is in your `Gemfile`, whether or
+  not you ever run this generator. The generator exists purely to give you an editable config file.
+- **Settings it exposes**: `c.project_name` (report header label), `c.dirs` (which top-level
+  directories get scanned), `c.branch` (override the git branch label — see
+  [Branch reporting](#branch-reporting)). All are optional; the commented-out initializer works
+  as-is with just `bundle install` + the generator.
+- **Re-running it**: standard Thor/Rails::Generators behavior — if
+  `config/initializers/scryer.rb` already exists, you'll be prompted to overwrite, skip, or diff
+  rather than have it silently clobbered.
+
+## Extending it
+
+Every rule is a small class extending `Scryer::Rule` — see `lib/scryer/rules/*.rb`
+(security) and `lib/scryer/performance_rules/*.rb` (performance) for the pattern. A new
+rule file dropped into either directory is picked up automatically (rules self-register via
+`Rule.inherited` — no manual wiring needed). `Scryer::Ast` has the tree-walking
+helpers used throughout.

data/exe/scryer

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "scryer"
+require "scryer/cli"
+
+exit Scryer::CLI.new(ARGV).run

data/lib/generators/scryer/USAGE

@@ -0,0 +1,66 @@
+Description:
+    Installs Scryer into a Rails application by creating a commented
+    config/initializers/scryer.rb initializer.
+
+    Scryer itself needs no configuration to run — the initializer only
+    exists so you can override defaults. It does not create migrations,
+    routes, controllers, or views: this generator's only side effect is
+    the one file it creates. The rake tasks (`scryer:report`) are made
+    available automatically by Scryer's Railtie the moment the gem is
+    in your Gemfile, with or without running this generator.
+
+    What you get in config/initializers/scryer.rb, and what each option
+    controls:
+
+      c.project_name  - Label shown in the report header. Defaults to the
+                         app's directory name if left unset.
+
+      c.dirs          - Which top-level directories (relative to Rails.root)
+                         get scanned. Defaults to %w[app lib config db].
+                         vendor/, node_modules/, tmp/, log/, .git/, spec/,
+                         and test/ are always skipped regardless of this
+                         setting.
+
+      c.branch        - Overrides the git branch name recorded in the
+                         report. Only useful in CI, where checkouts often
+                         land in a detached-HEAD state and
+                         `git rev-parse --abbrev-ref HEAD` returns nothing
+                         useful. Leave unset to use the actual checked-out
+                         branch.
+
+    Two more things ship in this gem but aren't controlled by the
+    initializer — see the README for both:
+
+      - Scryer::QueryWatcher: an opt-in runtime instrumentation for N+1
+        queries and unused eager loading (README: "Runtime query watcher").
+      - `bin/rails scryer:audit_dependencies`: a Gemfile.lock vulnerability
+        + insecure-source audit against OSV.dev (README: "Dependency audit").
+
+Example:
+    bin/rails generate scryer:install
+
+    This creates:
+        config/initializers/scryer.rb
+
+    After running it:
+        bin/rails scryer:report
+
+    writes tmp/scryer_report.json and tmp/scryer_report.html — open the
+    .html file in a browser to review findings (security, performance,
+    duplicate code), grouped and summarized similarly to a Brakeman report.
+
+    Format and output path are both configurable via task args — any mix of
+    json/html, plus the 'deps' token to fold a dependency audit in, plus at
+    most one path (quote the whole thing so your shell doesn't eat the
+    brackets/commas):
+
+        bin/rails 'scryer:report[json]'                    # just JSON, under tmp/
+        bin/rails 'scryer:report[json,doc/security.json]'  # JSON to an exact file
+        bin/rails 'scryer:report[json,html]'                # both, under tmp/
+        bin/rails 'scryer:report[json,html,reports]'        # both, under reports/
+        bin/rails 'scryer:report[html,deps]'                # HTML + a dependency audit section
+
+    Re-running `bin/rails generate scryer:install` after the initializer
+    already exists follows normal Thor/Rails::Generators behavior: it will
+    prompt to overwrite, skip, or diff the existing file rather than
+    silently clobbering your edits.

data/lib/generators/scryer/install_generator.rb

@@ -0,0 +1,29 @@
+require "rails/generators"
+
+module Scryer
+  module Generators
+    # `rails generate scryer:install` — drops a commented initializer
+    # into the host app. Doesn't touch anything else; the rake tasks are
+    # already loaded automatically by the Railtie. See
+    # lib/generators/scryer/USAGE for the detailed description shown by
+    # `bin/rails generate scryer:install --help`.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a config/initializers/scryer.rb initializer for static code analysis (security, duplicate code, performance heuristics)."
+
+      def create_initializer
+        template "scryer_initializer.rb", "config/initializers/scryer.rb"
+      end
+
+      def show_readme
+        say ""
+        say "Scryer installed. Next steps:", :green
+        say "  1. (Optional) Edit config/initializers/scryer.rb to set project_name, dirs, or branch."
+        say "  2. Run `bin/rails scryer:report` to scan this app and write tmp/scryer_report.{json,html}."
+        say "     Add a dependency audit or a custom path with task args, e.g. `bin/rails 'scryer:report[html,deps]'`."
+        say "  3. Open tmp/scryer_report.html in a browser to review findings — see README.md for what each section means."
+      end
+    end
+  end
+end

data/lib/generators/scryer/templates/scryer_initializer.rb

@@ -0,0 +1,28 @@
+# Configuration for the scryer gem (static code analysis: security,
+# duplicate code, performance heuristics). Run `bin/rails scryer:report`
+# to scan this app and generate tmp/scryer_report.{json,html} locally.
+
+Scryer.configure do |c|
+  c.project_name = "my-rails-app"
+
+  # Which top-level directories to scan (relative to Rails.root). Defaults
+  # to app/, lib/, config/, db/ — uncomment to customize:
+  # c.dirs = %w[app lib config db]
+
+  # The branch recorded in the report as this scan's git_branch, overriding
+  # whatever `git rev-parse --abbrev-ref HEAD` finds locally (useful in CI
+  # where checkouts often land in detached-HEAD state). Leave blank to use
+  # the actual checked-out branch:
+  # c.branch = ENV["CI_COMMIT_BRANCH"]
+end
+
+# Runtime query watcher (N+1 / unused eager loading — see README's "Runtime
+# query watcher"). Off by default; uncomment to enable in this environment.
+# Unlike the static scan above, this instruments a *running* app, so it's
+# typically only turned on for development/test:
+#
+# if Rails.env.development? || Rails.env.test?
+#   require "scryer/query_watcher"
+#   Scryer::QueryWatcher.enable!
+#   Rails.application.config.middleware.use Scryer::QueryWatcher::Middleware
+# end

data/lib/scryer/ai_client.rb

@@ -0,0 +1,53 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Scryer
+  # A small, provider-agnostic HTTP adapter for wiring *any* LLM into
+  # AiFixSuggester — Claude, OpenAI, a self-hosted Ollama/vLLM server, or
+  # anything else that takes a JSON request and returns a JSON response over
+  # HTTP. Scryer ships no vendor SDKs (see the gemspec's zero-runtime-
+  # dependency design); this adapter is configured with just the two pieces
+  # of vendor-specific shape it needs, both plain Procs:
+  #
+  #   - build_request:   prompt (String) -> request body (Hash)
+  #   - parse_response:  parsed JSON response (Hash) -> the model's reply (String)
+  #
+  # Everything else (the HTTP call, headers, timeouts) is generic. See the
+  # README's "AI-assisted fix suggestions" section for ready-made
+  # build_request/parse_response pairs for a couple of common APIs.
+  #
+  # AiFixSuggester itself doesn't require this class at all — any object
+  # (or bare Proc/lambda) responding to #call(prompt) and returning a String
+  # works as Scryer.configuration.ai_client. This class just saves writing
+  # the HTTP plumbing by hand for the common case of a JSON chat endpoint.
+  class AiClient
+    def initialize(url:, build_request:, parse_response:, headers: {}, open_timeout: 5, read_timeout: 30)
+      @uri = URI(url)
+      @headers = { "Content-Type" => "application/json" }.merge(headers)
+      @build_request = build_request
+      @parse_response = parse_response
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # Returns the model's reply as a String, or nil if the request failed or
+    # the response couldn't be parsed. Never raises — AiFixSuggester treats
+    # a nil/blank reply the same as "no client configured" and leaves the
+    # finding's original suggested_fix untouched.
+    def call(prompt)
+      body = JSON.generate(@build_request.call(prompt))
+
+      response = Net::HTTP.start(@uri.host, @uri.port, use_ssl: @uri.scheme == "https",
+                                                        open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
+        http.post(@uri.request_uri, body, @headers)
+      end
+
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      @parse_response.call(JSON.parse(response.body))
+    rescue StandardError
+      nil
+    end
+  end
+end