active-query-explorer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2ef157353a28e6c13fa4d6a3e3bb51936219ca8824de578a276c1339dbb37b8
+  data.tar.gz: 2b83cff84f6190b827da21c5ab071492ddfe6715689a997b9e2d77a27d7a6824
+SHA512:
+  metadata.gz: 58bf29b6f5a7c150f70e5d51d688fef495749f8227c8cadcfb2723baecc59fb67cc3fc731631440ccb55bbae7638172e9eaccea863e172e6999cec271cfdf6d3
+  data.tar.gz: 92458577f9d13b22250b8ffe96b427d1e89f80562cfb0cc0061d3090243146a62950a5ee2aee2668c55a0cd2f95dec086972d2d031559f721f1544ce7364b288

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-19
+
+### Added
+- Initial release of ActiveQueryExplorer gem
+- Mountable Rails engine for browsing and executing ActiveQuery query objects
+- Web GUI for discovering all registered ActiveQuery objects
+- Display of query metadata (arguments, types, defaults)
+- Execute queries with parameters from the browser
+- Plain text format endpoint for AI-consumable query catalog
+- Support for Rails 6.1+ and Ruby 3.2+
+
+[Unreleased]: https://github.com/matiasasis/active-query-explorer/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/matiasasis/active-query-explorer/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Matias Asis
+
+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,244 @@
+# Active Query Explorer
+
+A mountable Rails engine that provides a web UI for browsing, searching, and executing [Active Query](https://github.com/matiasasis/active-query) objects registered in your application.
+
+## Overview
+
+Active Query Explorer discovers all classes registered in `ActiveQuery::Base.registry`, groups them by namespace, and presents them in an interactive interface. Developers can browse query definitions, inspect parameters (names, types, defaults, optionality), and execute queries directly from the browser.
+
+It is designed for Rails applications that use the `active-query` gem to define query objects. If your app has query classes inheriting from `ActiveQuery::Base`, this engine makes them discoverable and runnable without writing any additional code.
+
+## Installation
+
+Add to your Gemfile. The gem is not yet published to RubyGems, so reference it via Git or a local path:
+
+```ruby
+# Via Git
+gem "active-query-explorer", git: "https://github.com/matiasasis/active-query-explorer.git"
+
+# Or via local path during development
+gem "active-query-explorer", path: "../active-query-explorer"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+**Requirements:** Ruby >= 3.2, Rails >= 6.1 and < 9.0, `active-query` >= 0.1.3.
+
+## Mounting the Engine
+
+Add to your `config/routes.rb`:
+
+```ruby
+mount ActiveQueryExplorer::Engine => "/queries", as: "active_query_explorer"
+```
+
+After starting your Rails server, visit `http://localhost:3000/queries` to access the UI.
+
+The engine is isolated-namespaced (`ActiveQueryExplorer`), so it will not conflict with your application's routes or controllers.
+
+## Usage
+
+### Web UI
+
+The HTML interface at your mount path provides:
+
+- **Sidebar** -- Query classes grouped by namespace, with collapsible sections and count badges. Clicking a class scrolls to its detail card.
+- **Search** -- Full-text filtering across class names, query names, descriptions, and parameter names. Focus with `Cmd+K` / `Ctrl+K`.
+- **Filters** -- Namespace dropdown, parameter presence toggle (all / with params / without params).
+- **Query cards** -- Expandable cards showing each query's description, parameters (name, type, required/optional, default value), and source file location.
+- **Inline execution** -- Form fields rendered per-parameter with type labels. Submit to execute the query and see results with timing metadata.
+
+### Example Flow
+
+1. Visit `/queries`
+2. Browse or search for a query (e.g., `Billing::InvoiceQuery#overdue`)
+3. Expand the query card to see its parameters
+4. Fill in parameter values and click Execute
+5. View the returned result set inline
+
+## API / Formats
+
+The index endpoint supports three response formats:
+
+### HTML (default)
+
+```
+GET /queries
+```
+
+The interactive UI described above.
+
+### JSON
+
+```
+GET /queries.json
+```
+
+Returns the full query catalog as structured JSON -- an array of namespace groups, each containing query objects with their class names, source locations, and query definitions (name, description, parameters).
+
+Useful for building custom tooling or dashboards.
+
+### Text
+
+```
+GET /queries.text
+```
+
+Returns an AI-consumable plain text catalog. Each query is rendered as a structured block:
+
+```
+=== QUERY START ===
+name: Billing::InvoiceQuery#overdue
+namespace: Billing
+description: Find overdue invoices
+returns: unknown
+side_effects: unknown
+idempotent: unknown
+safety: unknown
+
+inputs:
+  - name: days
+    type: Integer
+    required: true
+    default: none
+=== QUERY END ===
+```
+
+Useful for including query definitions in LLM context or generating documentation.
+
+### Execute Endpoint
+
+```
+POST /queries/execute
+Content-Type: application/json
+
+{
+  "query_class": "Billing::InvoiceQuery",
+  "query_name": "overdue",
+  "args": { "days": 30 }
+}
+```
+
+Returns `{ "result": <serialized_data> }` on success, or `{ "error": "message" }` on failure. CSRF token is required (the UI handles this automatically).
+
+## Configuration
+
+Create an initializer (e.g., `config/initializers/active_query_explorer.rb`):
+
+```ruby
+ActiveQueryExplorer.result_limit = 200          # Max records returned (default: 100)
+ActiveQueryExplorer.query_paths = %w[queries]    # Subdirectories under app/ to eager-load (default: ["queries", "query_objects"])
+```
+
+### Swappable Services
+
+The discovery, execution, and serialization layers can be replaced:
+
+```ruby
+ActiveQueryExplorer.discovery_class = MyCustomDiscovery
+ActiveQueryExplorer.executor_class = MyCustomExecutor
+ActiveQueryExplorer.serializer_class = MyCustomSerializer
+```
+
+Each must implement the same interface as the default classes (see Architecture below).
+
+## Architecture
+
+```
+lib/
+  active_query_explorer.rb          # Module entry point, configuration accessors
+  active_query_explorer/
+    engine.rb                       # Rails engine definition, eager-loading initializer
+    query_discovery.rb              # Reads ActiveQuery::Base.registry, groups by namespace
+    query_executor.rb               # Coerces args, whitelists params, calls query methods
+    result_serializer.rb            # Serializes AR relations, records, scalars, enumerables
+    query_text_formatter.rb         # Generates plain text query catalog
+    version.rb                      # VERSION = "0.1.0"
+
+app/
+  controllers/active_query_explorer/
+    queries_controller.rb           # index (html/json/text) + execute (json)
+  views/active_query_explorer/queries/
+    index.html.erb                  # Full UI (HTML + CSS + JS, self-contained)
+
+config/
+  routes.rb                         # Engine routes
+```
+
+### Discovery Flow
+
+1. On Rails boot, the engine's `eager_load_queries` initializer loads all Ruby files from `app/queries/`, `app/query_objects/`, and their Packwerk equivalents (`packs/*/app/queries/`, `packs/*/app/query_objects/`).
+2. When the index action is hit, `QueryDiscovery#grouped_queries` reads `ActiveQuery::Base.registry`, filters to Class entries, extracts each class's `.queries` definitions, and groups them by namespace (derived from the class name).
+3. Each query definition includes its name, description, and parameter definitions (`args_def`).
+
+### Execution Flow
+
+1. Controller validates `query_class` and `query_name` against `VALID_QUERY_NAME` regex (`/\A[a-zA-Z_]\w*\z/`).
+2. `QueryDiscovery` resolves the class and query definition.
+3. `QueryExecutor` whitelists arguments against `args_def` keys, coerces types via `ActiveQuery::TypeRegistry.coerce`, and calls the query method via `public_send`.
+4. `ResultSerializer` converts the result (AR relation, record, scalar, or enumerable) to JSON-safe output, applying `result_limit`.
+
+## Adding Query Objects
+
+Query objects are discovered automatically. To add a new one:
+
+1. Create a class that inherits from `ActiveQuery::Base` in `app/queries/` (or `app/query_objects/`):
+
+```ruby
+# app/queries/billing/invoice_query.rb
+class Billing::InvoiceQuery < ActiveQuery::Base
+  query :overdue,
+        description: "Find invoices past due date",
+        args_def: {
+          days: { type: Integer, optional: false },
+          status: { type: String, optional: true, default: "pending" }
+        }
+
+  def self.overdue(args = {})
+    Invoice.where("due_date < ?", args[:days].days.ago)
+            .where(status: args[:status])
+  end
+end
+```
+
+2. The class registers itself in `ActiveQuery::Base.registry` (handled by the `active-query` gem).
+3. Restart your Rails server (or, in development, the class will be loaded on the next request if eager loading is configured).
+4. Visit the explorer UI -- your query appears grouped under its namespace.
+
+**Packwerk support:** If your app uses Packwerk, place query objects in `packs/<pack_name>/app/queries/` and they will be discovered automatically.
+
+## Development
+
+### Setup
+
+```bash
+git clone <repo-url>
+cd active-query-explorer
+bundle install
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+Tests use an in-memory SQLite database. The test suite covers configuration, discovery, execution, serialization, the controller (including input validation and error handling), and the text formatter.
+
+CI runs on Ruby 3.2, 3.3, and 3.4 via GitHub Actions.
+
+## Known Gaps
+
+- **Authentication/authorization:** The engine does not include any access control. You must restrict access yourself (e.g., via a routing constraint or middleware). Since the execute endpoint runs arbitrary registered queries, this is important in production.
+- **Not published to RubyGems:** Must be referenced via Git or path in your Gemfile.
+- **Query interface assumptions:** The engine assumes query classes respond to `.queries` returning an array with `:name`, `:description`, and `:args_def` keys. This is dictated by the `active-query` gem's API -- refer to its documentation for the definitive contract.
+- **Text format metadata:** The `returns`, `side_effects`, `idempotent`, and `safety` fields in the text format are always `unknown` -- the `active-query` gem does not currently expose this metadata.
+- **Result limit is global:** `result_limit` applies to all queries uniformly; there is no per-query override.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/active-query-explorer.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/active_query_explorer/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "active-query-explorer"
+  spec.version = ActiveQueryExplorer::VERSION
+  spec.authors = ["Matias Asis"]
+  spec.email = ["matiasis.90@gmail.com"]
+  spec.summary = "A mountable Rails engine for browsing and executing ActiveQuery query objects."
+  spec.description = "ActiveQuery Explorer provides a web GUI (similar to GraphiQL) that discovers all registered ActiveQuery objects, displays their metadata, and allows executing them with parameters."
+  spec.homepage = "https://github.com/matiasasis/active-query-explorer"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/matiasasis/active-query-explorer"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/matiasasis/active-query-explorer/issues"
+  spec.metadata["changelog_uri"] = "https://github.com/matiasasis/active-query-explorer/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile]) ||
+        f.match?(/\.gem\z/)
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "active-query", "~> 0.1", ">= 0.1.3"
+  spec.add_dependency "actionpack", ">= 6.1", "< 9.0"
+  spec.add_dependency "railties", ">= 6.1", "< 9.0"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.9"
+  spec.add_development_dependency "activerecord", ">= 6.1", "< 9.0"
+  spec.add_development_dependency "sqlite3", '>= 1.5.1', '< 3.0'
+end