glancer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4248cad39bdfcfd7cb3907a83c81170f49bf15b76c0af226d6333622479dd72
+  data.tar.gz: cd8b5588e4032750fa0f5be8eae5de5ded28a713a1223b948d4fd94b258ce012
+SHA512:
+  metadata.gz: 4cb913d4829f562ceaa8ebc9ff808c22037b540c0ecf75991cfb6f785434fc0fd8588d73d6a65e54a09f96d002a7e0359bc0e8884ba112a75fac215832b32340
+  data.tar.gz: 4b5f94c281b5161e83bbbbf48296d321344302ee53811bf0b8b4184cce385f831552fca3827ee26dae34897dd501ff8de74ad33f6714e8d7e3ed1b6c135779d7

data/.github/workflows/ci.yml

@@ -0,0 +1,96 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  # ── Lint ────────────────────────────────────────────────────────────────────
+  lint:
+    name: RuboCop
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop --format github
+
+  # ── Test ────────────────────────────────────────────────────────────────────
+  test:
+    name: RSpec / Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    needs: lint
+    permissions:
+      contents: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.3", "3.4", "4.0"]
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run RSpec with coverage
+        run: bundle exec rspec
+        env:
+          COVERAGE: "true"
+          CI: "true"
+
+      - name: Upload coverage report (Ruby 3.3 only)
+        if: matrix.ruby == '3.3'
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: coverage-report
+          path: coverage/
+          retention-days: 7
+
+      - name: Check minimum coverage
+        if: matrix.ruby == '3.3'
+        run: |
+          COVERED=$(ruby -e "
+            require 'json'
+            data = JSON.parse(File.read('coverage/.last_run.json'))
+            pct = data.dig('result', 'line') || data.dig('result', 'covered_percent') || 0
+            puts pct.round(2)
+          ")
+          echo "Coverage: ${COVERED}%"
+          ruby -e "exit(1) if ${COVERED}.to_f < 80" || {
+            echo "::warning::Coverage ${COVERED}% is below the 80% threshold."
+          }
+
+      - name: Extract coverage percentage for badge
+        if: matrix.ruby == '3.3'
+        id: coverage
+        run: |
+          PCT=$(ruby -e "
+            require 'json'
+            data = JSON.parse(File.read('coverage/coverage.json'))
+            puts data.dig('metrics', 'covered_percent').round(2)
+          ")
+          echo "pct=${PCT}%" >> "$GITHUB_OUTPUT"
+
+      - name: Generate coverage badge
+        if: matrix.ruby == '3.3' && github.ref == 'refs/heads/main'
+        uses: ernanej/badge-generator@main
+        with:
+          name: ${{ steps.coverage.outputs.pct }}
+          prefix: coverage
+          path: .github/badges/coverage.svg
+          github_token: ${{ secrets.GITHUB_TOKEN }}

data/.rubocop.yml

@@ -0,0 +1,54 @@
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: disable
+  SuggestExtensions: false
+  Exclude:
+    - ".ruby-lsp/**/*"
+    - "vendor/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Internal Rails engine — no public API to document
+Style/Documentation:
+  Enabled: false
+
+# @@store in Workflow::Cache is intentional
+Style/ClassVars:
+  Enabled: false
+
+# Complex pipeline and configuration methods legitimately exceed 10 lines
+Metrics/MethodLength:
+  Max: 80
+
+Layout/ExtraSpacing:
+  AllowForAlignment: true
+
+Metrics/AbcSize:
+  Max: 55
+
+Metrics/ClassLength:
+  Max: 300
+
+Metrics/ModuleLength:
+  Max: 200
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+# Rake tasks and generator templates are necessarily long blocks
+Metrics/BlockLength:
+  Max: 80
+  Exclude:
+    - "lib/tasks/**/*.rake"
+    - "lib/generators/**/*.rb"
+    - "spec/**/*.rb"
+
+Layout/LineLength:
+  Max: 140

data/CHANGELOG.md

@@ -0,0 +1,88 @@
+# 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]
+
+## [1.0.0] — 2026-05-24
+
+### Added
+
+- **SQL editing**: users can edit the generated SQL directly in the chat UI before
+  executing it. Edits are persisted with a `user_edited_sql` flag and surfaced with
+  a visible badge.
+- **Pipeline status labels**: animated step-by-step labels (embedding → retrieval →
+  SQL generation → validation → execution → response) while the pipeline is running.
+- **Accordion results**: running a new query collapses the previous results panel;
+  panels can be toggled independently.
+- **Copy buttons**: one-click copy for both the raw SQL and the full assistant response.
+- **Large-result alert**: a warning banner when a query returns ≥ 500 rows or has no
+  `LIMIT` clause.
+- **Audio input**: microphone button powered by the Web Speech API; transcribed text
+  is appended to the question field.
+- **Desktop sidebar toggle**: chevron button to collapse/expand the chat list on large
+  screens; state is persisted in `localStorage`.
+- **Blazer integration**: "Open in Blazer" button auto-detected when the `blazer` gem
+  is present; configurable via `config.blazer_path`.
+- **`:silent` log verbosity level**: suppresses all log output including `warn` and
+  `error` — intended for test environments.
+- **100 % test coverage**: 552 RSpec examples covering every workflow path, edge case,
+  and rescue branch.
+- **CI badge**: automatically generated coverage SVG committed to the `badge-generator`
+  branch on every push to `main`.
+
+### Changed
+
+- LLM humanization prompt rewritten to never describe the query as "executed" — it now
+  explains the logic and why it answers the question.
+- Improved self-correction: the executor retries up to 3 times, passing the database
+  error back to the LLM on each attempt.
+- Immediate user-message rendering: the user's bubble appears in the chat instantly
+  (before the server responds) via a temporary DOM node that is replaced by the
+  Turbo Stream response.
+
+### Fixed
+
+- Info panel never showed content because the controller was passing `message_for_info:`
+  but the partial expected `message_info:`.
+
+## [0.1.0] — 2026-05-14
+
+### Added
+
+- **RAG pipeline**: embed → retrieve → generate SQL → execute → humanize, with automatic
+  retry (up to 3 attempts) on SQL errors using LLM self-correction.
+- **Multi-provider LLM support** via [ruby_llm](https://github.com/crmne/ruby_llm):
+  Gemini, OpenAI, and OpenRouter. Each role (SQL generation, chat responses, embeddings)
+  can use a different provider and model.
+- **Indexers** for `db/schema.rb`, `app/models/**/*.rb`, and a custom Markdown context
+  file. Rake tasks: `glancer:index:all`, `glancer:index:schema`, `glancer:index:models`,
+  `glancer:index:context`.
+- **Cosine similarity retrieval** with per-source-type relevance weights (schema 1.3×,
+  context 1.2×, models 1.1×) and a configurable minimum score threshold.
+- **Chunk overlap** to prevent context loss at document boundaries.
+- **SQL safety layer**: `SQLSanitizer` (blocks destructive statements),
+  `SQLValidator` (verifies table references against indexed schema), and
+  mandatory read-only transaction with automatic rollback.
+- **Audit trail**: every executed query is stored in `glancer_audits` with a unique
+  `run_id` UUID injected as an SQL comment (`/*glancer,run_id:UUID*/`).
+- **In-memory response cache** (`workflow_cache_ttl`) to avoid redundant LLM calls for
+  repeated identical questions.
+- **Chat UI**: Stimulus + Turbo Streams interface with dark mode, typewriter effect,
+  CSV export, SQL re-run, pipeline status labels, accordion results, copy-to-clipboard,
+  and audio input (Web Speech API).
+- **Settings page** at `/glancer/settings` for runtime custom instructions.
+- **Schema viewer** at `/glancer/db-schema` showing indexed tables and columns.
+- **Install generator**: `rails generate glancer:install` scaffolds the initializer,
+  context file, and mounts the engine.
+- Configurable `statement_timeout` enforced via adapter-native mechanisms
+  (PostgreSQL `SET statement_timeout`, MySQL `SET max_execution_time`).
+- `config.history_limit` to control how many prior turns are included in the prompt.
+- `config.read_only_db` to route queries to a replica connection string.
+
+[Unreleased]: https://github.com/ErnaneJ/glancer/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/ErnaneJ/glancer/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/ErnaneJ/glancer/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Glancer is a **Ruby on Rails engine (gem)** that adds natural language database querying to any Rails app via RAG (Retrieval-Augmented Generation) and LLMs. It indexes the host app's schema, models, and custom context into a vector store, then answers user questions with generated and executed SQL, returning humanized responses through a chat UI.
+
+## Commands
+
+```bash
+# Development
+bundle exec rake spec rubocop    # Default CI: tests + linting (both must pass)
+bundle exec rake spec            # RSpec only
+bundle exec rake rubocop         # RuboCop only
+
+# Rake tasks (run in host app after mounting)
+rails glancer:index:all          # Rebuild all embeddings (prompts confirmation)
+rails glancer:index:schema       # Index db/schema.rb only
+rails glancer:index:models       # Index app/models only
+rails glancer:index:context      # Index custom context Markdown file
+rails glancer:version            # Print gem version
+```
+
+## Architecture
+
+### RAG Query Pipeline
+
+The core workflow runs in `lib/glancer/workflow.rb` and follows this sequence per user message:
+
+```
+1. Embed question → cosine similarity search over glancer_embeddings
+   - Weights: schema 1.3x, context 1.2x, models 1.1x
+   - Filters: min_score (default 0.6), top-k (default 5)
+
+2. Build prompt (PromptBuilder) with retrieved chunks + last 6 messages
+   - LLM receives adapter type for syntax-specific SQL generation
+   - Language directive: respond in the same language as the question
+
+3. LLM generates SELECT-only SQL
+   - SQLExtractor: parses ```sql blocks from raw LLM output
+   - SQLSanitizer: blocks DELETE/UPDATE/INSERT/DROP/TRUNCATE/ALTER/CREATE/REPLACE
+   - SQLValidator: verifies referenced tables exist in indexed schema
+
+4. Execute inside a transaction that always rolls back (read-only safety)
+   - Injects /*glancer,run_id:UUID*/ comment for audit trail
+   - Creates Glancer::Audit record
+   - Auto-retry up to 3 times via LLM error correction
+
+5. LLM humanizes results; response cached in-memory (TTL configurable)
+```
+
+### Database Tables
+
+| Table | Purpose |
+|-------|---------|
+| `glancer_chats` | Conversation containers |
+| `glancer_messages` | User/assistant turns; stores `sql`, `successful` flag, optional `user_message_id` FK linking reply to source |
+| `glancer_embeddings` | Vector store: `content`, `embedding` (JSONB on PG / JSON elsewhere), `source_type`, `source_path` |
+| `glancer_audits` | Immutable query log: `question`, `sql`, `adapter`, `run_id` (unique UUID) |
+
+### Indexers (`lib/glancer/indexer/`)
+
+- **SchemaIndexer**: Splits `db/schema.rb` into per-table chunks by `create_table` blocks
+- **ModelIndexer**: Reads `app/models/**/*.rb`, chunks at 1000 chars
+- **ContextIndexer**: Reads custom Markdown from `config_file_path`; skips files whose first line is `--glancer-ignore`
+
+Embeddings are regenerated on each `glancer:index:*` call (full re-index, not incremental).
+
+### Configuration (`lib/glancer/configuration.rb`)
+
+Singleton via `Glancer.configure { |config| }`. All setters validate on assignment (raise `ArgumentError` on invalid). Key non-obvious settings:
+
+```ruby
+config.adapter          # Auto-detected from ActiveRecord if nil
+config.read_only_db     # Optional replica URL; connection opened per transaction, reset after
+config.k                # Number of top embeddings retrieved (default 10)
+config.min_score        # Cosine similarity floor 0.0–1.0 (default 0.6)
+config.workflow_cache_ttl  # In-memory result cache TTL (NOT shared across processes)
+```
+
+### Frontend (`app/assets/`)
+
+Stimulus JS + Turbo Streams with Tailwind CSS (CDN, dark mode default). Controllers:
+- **MessageController**: form submit, typewriter effect (12ms/char), CSV export (client-side DOM traversal), SQL re-run
+- **ChatController**: chat CRUD, copy-to-clipboard
+
+Both controllers respond to `.html` and `.turbo_stream` formats. CSV generation happens entirely in the browser by traversing the rendered `<table>` DOM — there is no backend CSV endpoint.
+
+### Routes
+
+```ruby
+resources :chats, only: [:index, :show, :create, :destroy] do
+  resources :messages, only: [:create]
+end
+get  "/messages/:id/info"       # Side-panel with SQL + sources
+post "/messages/:id/run_sql"    # Re-execute saved SQL without regenerating
+root to: "chats#index"
+```
+
+## Non-Obvious Constraints
+
+- **Transactions always roll back** — even on successful reads. This is intentional for read-only safety; do not add `raise ActiveRecord::Rollback` — it's already unconditional.
+- **SQL audit comment is mandatory** — every executed query has `/*glancer,run_id:UUID*/` injected by Executor; removing this breaks audit tracking.
+- **In-memory cache is process-local** — `Glancer::Workflow::Cache` uses a class-level `@@store` hash. It will not invalidate across Puma workers or restarts.
+- **Vector search is O(n) pure Ruby** — no pgvector or native DB indexing. Large embedding tables will degrade retrieval performance noticeably.
+- **ModelIndexer hard-codes 1000-char chunk size** — there is no configuration option for this.
+- **Prompt language detection is LLM-instructed, not programmatic** — the system prompt tells the LLM to match input language; no ICU/language detection library is used.
+- **`user_message_id` is a self-referential FK on `glancer_messages`** — assistant messages point to the user message that triggered them; this is used for threading in the UI info panel.
+
+## Gem Development Notes
+
+The gemspec (`glancer.gemspec`) includes only `.rb`, `.erb`, `.md`, `.yml`, `.rake` files. Assets follow normal Rails engine conventions with `config.assets.precompile` declared in the engine initializer.
+
+To test changes against a host Rails app, use a `Gemfile` path reference: `gem 'glancer', path: '../glancer'`.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+ernane.junior25@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations