@reinteractive/rails-insight 1.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-2026 reinteractive
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# RailsInsight
+
+[![npm version](https://img.shields.io/npm/v/@reinteractive/railsinsight.svg)](https://www.npmjs.com/package/@reinteractive/railsinsight)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+
+A Rails-aware codebase indexer that runs as an MCP (Model Context Protocol) server, giving AI coding agents deep structural understanding of your Rails application — models, associations, routes, schema, authentication, jobs, components, and 56 total file categories — without reading every file.
+
+## Why RailsInsight?
+
+Generic code-analysis tools treat Ruby files as plain text. RailsInsight understands **Rails conventions**: `has_many :through`, `before_action` filters, Devise modules, Pundit policies, Turbo Stream broadcasts, Solid Queue jobs, and more. It builds a directed weighted graph of your entire app and exposes it through MCP tools so your AI agent can reason about impact, dependencies, and architecture — without consuming your entire codebase in tokens.
+
+## Installation
+
+```bash
+npx @reinteractive/railsinsight
+```
+
+Or install globally:
+
+```bash
+npm install -g @reinteractive/railsinsight
+```
+
+## Quick Start
+
+Run from your Rails project root:
+
+```bash
+npx @reinteractive/railsinsight
+```
+
+This starts a local MCP server over stdio. The indexer scans your project structure, extracts Rails conventions, builds a relationship graph, and exposes everything through MCP tools.
+
+To point at a different Rails app:
+
+```bash
+npx @reinteractive/railsinsight --project-root /path/to/your/rails/app
+```
+
+### CLI Options
+
+| Flag                    | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `--project-root <path>` | Path to the Rails project (defaults to cwd)      |
+| `--claude-md <path>`    | Path to a `claude.md` / `CLAUDE.md` context file |
+| `--mode local\|remote`  | Transport mode (default: `local`)                |
+| `--port <number>`       | Port for remote mode (default: `3000`)           |
+| `--verbose`             | Enable verbose logging to stderr                 |
+| `--help`                | Show help                                        |
+
+## Claude Code Integration
+
+Add to your Claude Code MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "railsinsight": {
+      "command": "npx",
+      "args": ["@reinteractive/railsinsight"]
+    }
+  }
+}
+```
+
+## Cursor / VS Code Integration
+
+In your `.cursor/mcp.json` or VS Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "railsinsight": {
+      "command": "npx",
+      "args": ["@reinteractive/railsinsight"]
+    }
+  }
+}
+```
+
+The server uses the workspace directory as the project root automatically, so no path argument is needed for normal project-local use.
+
+## Available Tools
+
+All 17 tools are available with no tier restrictions.
+
+### Core Tools
+
+| Tool                | Description                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `index_project`     | Re-index the Rails project. In local mode, re-scans the project root. Accepts `force` (boolean) to bypass cache. Returns statistics and duration.                                                                                                                                                                                                                                                                  |
+| `get_overview`      | Project summary: Rails/Ruby versions, database, auth strategy, key models and controllers, frontend stack, file counts. Call this first.                                                                                                                                                                                                                                                                           |
+| `get_full_index`    | Complete index JSON trimmed to fit a specified token budget (default: 12,000 tokens).                                                                                                                                                                                                                                                                                                                              |
+| `get_model`         | Deep extraction for a specific model: associations, validations, scopes with queries, enums with values, callbacks, public methods, database columns. Requires `name`.                                                                                                                                                                                                                                             |
+| `get_controller`    | Deep extraction for a specific controller: actions with routes, filters, rate limiting, strong params, rescue handlers. Requires `name`.                                                                                                                                                                                                                                                                           |
+| `get_routes`        | Complete route map with namespaces, nested resources, member/collection routes.                                                                                                                                                                                                                                                                                                                                    |
+| `get_schema`        | Database schema with tables, columns, indexes, foreign keys, and model-to-table mapping.                                                                                                                                                                                                                                                                                                                           |
+| `get_subgraph`      | Skill-scoped relationship subgraph with ranked files. Skills: `authentication`, `database`, `frontend`, `api`, `jobs`, `email`.                                                                                                                                                                                                                                                                                    |
+| `search_patterns`   | Search across all extractions for a specific Rails pattern type (e.g. `has_many_through`, `before_action`, `turbo_broadcast`).                                                                                                                                                                                                                                                                                     |
+| `get_deep_analysis` | Deep analysis for a specific category. Categories: `authentication`, `authorization`, `jobs`, `email`, `storage`, `caching`, `realtime`, `api_patterns`, `dependencies`, `components`, `stimulus`, `views`, `convention_drift`, `manifest`, `detected_stack`, `related`, `model_list`, `controller_list`, `component_list`. Accepts optional `name` (entity name) and `depth` (BFS hops for `related`, default 2). |
+
+### Test Intelligence Tools
+
+| Tool                       | Description                                                                                                                                                                                                                  |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_coverage_gaps`        | Prioritised list of files needing test coverage, with structural context and per-method coverage data from SimpleCov. Accepts optional `category`, `min_gap`, and `limit`.                                                   |
+| `get_test_conventions`     | Detected test patterns and conventions: spec style (request vs controller), let style, auth helper, factories, shared examples, custom matchers, and pattern reference files.                                                |
+| `get_domain_clusters`      | Domain-clustered file groups for parallel test generation. Files in the same cluster share associations and factories; different clusters can be worked on simultaneously. Accepts `max_cluster_size` and `include_covered`. |
+| `get_factory_registry`     | Parsed FactoryBot factory definitions including attributes, traits, sequences, and associations. Accepts optional `model` to filter by factory name.                                                                         |
+| `get_well_tested_examples` | High-quality existing spec files suitable as pattern references for test generation agents. Selected by structural complexity per spec category. Accepts `category` and `limit`.                                             |
+
+### Blast Radius Tools
+
+| Tool                 | Description                                                                                                                                                                                                                                           |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_blast_radius`   | Analyse the impact of code changes. Accepts explicit file paths or auto-detects from git diff. Returns impacted entities classified by risk level (CRITICAL/HIGH/MEDIUM/LOW) with affected tests. Accepts `files`, `base_ref`, `staged`, `max_depth`. |
+| `get_review_context` | Build a token-budget-aware review summary for changed files. Combines blast radius analysis with relevant code context for AI-assisted code review. Accepts `files`, `base_ref`, `staged`, `token_budget`.                                            |
+
+## What It Detects
+
+RailsInsight classifies files across **56 categories** using pure path-based analysis:
+
+| #   | Category       | #   | Category         | #   | Category           |
+| --- | -------------- | --- | ---------------- | --- | ------------------ |
+| 1   | Models         | 20  | Code Quality     | 39  | Rich Text          |
+| 2   | Controllers    | 21  | Deployment       | 40  | Notifications      |
+| 3   | Routes         | 22  | Search           | 41  | Feature Flags      |
+| 4   | Schema         | 23  | Payments         | 42  | Audit              |
+| 5   | Components     | 24  | Multi-tenancy    | 43  | Soft Delete        |
+| 6   | Stimulus       | 25  | Admin            | 44  | Pagination         |
+| 7   | Views          | 26  | Design Patterns  | 45  | Friendly URLs      |
+| 8   | Authentication | 27  | State Machines   | 46  | Tagging            |
+| 9   | Authorization  | 28  | i18n             | 47  | SEO                |
+| 10  | Jobs           | 29  | PDF              | 48  | Geolocation        |
+| 11  | Email          | 30  | CSV              | 49  | SMS / Push         |
+| 12  | Storage        | 31  | Webhooks         | 50  | Activity Tracking  |
+| 13  | Caching        | 32  | Scheduled Tasks  | 51  | Data Import/Export |
+| 14  | Realtime       | 33  | Middleware       | 52  | Event Sourcing     |
+| 15  | API            | 34  | Engines          | 53  | dry-rb             |
+| 16  | Gemfile        | 35  | Credentials      | 54  | Markdown           |
+| 17  | Config         | 36  | HTTP Client      | 55  | Rate Limiting      |
+| 18  | Security       | 37  | Performance      | 56  | GraphQL            |
+| 19  | Testing        | 38  | Database Tooling |     |                    |
+
+Beyond classification, deep extractors analyze file content to extract:
+
+- **Models**: Associations, validations, scopes, enums, callbacks, concerns, Devise modules, broadcasts
+- **Controllers**: Actions, before/after/around filters, strong params, rescue handlers, caching
+- **Routes**: Resources, namespaces, nesting, member/collection routes, constraints, mounts
+- **Schema**: Tables, columns with types, indexes (unique/composite), foreign keys
+- **Components**: ViewComponent params, slots, Stimulus connections, sidecar files, previews
+- **Auth**: Devise strategy, modules per model, custom controllers, OAuth providers
+- **Authorization**: Pundit/CanCanCan policies, roles, permission structures
+- **Jobs**: Queue names, retry strategies, callbacks, scheduling, Sidekiq/GoodJob config
+- **Email**: Mailer actions, layouts, delivery config, Action Mailbox routing
+- **Storage**: Active Storage services, model attachments, variants, direct upload config
+- **Caching**: Cache store, fragment caching, Russian doll patterns, counter caches
+- **Realtime**: ActionCable channels, Turbo Stream broadcasts, CableReady operations
+- **API**: Versioning strategy, serializers, pagination, rate limiting, authentication
+
+## Rails Version Support
+
+| Rails Version | Support Level                                             |
+| ------------- | --------------------------------------------------------- |
+| 8.0 – 8.1+    | Full support (Solid Queue, Solid Cache, Kamal, Propshaft) |
+| 7.0 – 7.2     | Full support (Hotwire, import maps, Turbo)                |
+| 6.0 – 6.1     | Full support (Webpacker, Sprockets, legacy enum syntax)   |
+| < 6.0         | Basic structural scanning only                            |
+
+## How It Works
+
+RailsInsight processes your Rails project through a 6-layer pipeline:
+
+1. **Context Loader** — Parses `claude.md` / `CLAUDE.md` for declared conventions and project context
+2. **Version Detector** — Identifies Rails/Ruby versions, database adapter, asset pipeline, frontend stack, and all gems from `Gemfile.lock`
+3. **Structural Scanner** — Classifies every file into 1 of 56 categories using path patterns (zero file reads)
+4. **Deep Extractors** — 19 specialized extractors parse file content for models, controllers, routes, schema, components, Stimulus controllers, auth, authorization, jobs, email, storage, caching, realtime, API patterns, views, config, and tier 2/3 patterns
+5. **Relationship Graph** — Builds a directed weighted graph with 22 edge types (model→association, controller→model, route→controller, etc.) and computes Personalized PageRank to rank entities by importance
+6. **Convention Drift Detector** — Compares declared conventions (from `claude.md`) against actual extracted patterns, reporting mismatches with severity levels
+
+The entire index is built in a single pass, typically under 2 seconds for large projects, and the result is served through MCP tools with token-budget-aware formatting.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Running Tests
+
+```bash
+npm test                   # Run all tests
+npm run test:watch         # Watch mode
+npm run test:core          # Core layer tests only
+npm run test:extractors    # Extractor tests
+npm run test:patterns      # Rails pattern tests
+npm run test:coverage      # Run with coverage
+```
+
+## Limitations
+
+RailsInsight uses regex-based extraction rather than a full Ruby AST parser. This handles the vast majority of real-world Rails code, but may miss unconventional patterns such as:
+
+- Multi-line method calls split across 3+ lines
+- Metaprogrammed associations or validations
+- Dynamic class definitions
+
+If you encounter a pattern that isn't detected, please [open an issue](https://github.com/reinteractive/rails-insight/issues).
+
+## License
+
+ISC — see [LICENSE](LICENSE) for details.

package/bin/railsinsight.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const options = {
+  'project-root': { type: 'string', short: 'p' },
+  'claude-md': { type: 'string' },
+  mode: { type: 'string', short: 'm', default: 'local' },
+  port: { type: 'string', default: '3000' },
+  verbose: { type: 'boolean', short: 'v', default: false },
+  help: { type: 'boolean', short: 'h', default: false },
+}
+
+const HELP_TEXT = `
+RailsInsight — Rails-Aware Codebase Indexer (MCP Server)
+
+Usage:
+  railsinsight --project-root <path> [options]
+
+Options:
+  -p, --project-root <path>   Path to Rails project root (required for local mode)
+  --claude-md <path>          Path to claude.md file (defaults to {project-root}/claude.md)
+  -m, --mode <mode>           Server mode: local or remote (default: local)
+  --port <number>             Port for remote mode (default: 3000)
+  -v, --verbose               Enable verbose logging to stderr
+  -h, --help                  Show this help message
+
+Examples:
+  railsinsight --project-root /path/to/rails/app
+  railsinsight -p . --verbose
+`
+
+/**
+ * Run the CLI with injectable dependencies for testing.
+ * @param {string[]} argv
+ * @param {Object} deps
+ * @returns {Promise<number>} Process exit code
+ */
+export async function main(argv = process.argv.slice(2), deps = {}) {
+  const writeStdout = deps.writeStdout || ((text) => process.stdout.write(text))
+  const writeStderr = deps.writeStderr || ((text) => process.stderr.write(text))
+  const parseArgsFn = deps.parseArgsFn || parseArgs
+  const existsSyncFn = deps.existsSyncFn || existsSync
+  const resolvePath = deps.resolvePath || resolve
+  const importServer = deps.importServer || (() => import('../src/server.js'))
+
+  let parsed
+  try {
+    parsed = parseArgsFn({ args: argv, options, allowPositionals: false })
+  } catch (err) {
+    writeStderr(`Error: ${err.message}\n`)
+    writeStderr('Run with --help for usage information.\n')
+    return 1
+  }
+
+  const { values } = parsed
+
+  if (values.help) {
+    writeStdout(HELP_TEXT)
+    return 0
+  }
+
+  const mode = values.mode || 'local'
+
+  if (mode === 'local') {
+    const projectRoot = resolvePath(values['project-root'] || '.')
+
+    if (!existsSyncFn(projectRoot)) {
+      writeStderr(`Error: Project root does not exist: ${projectRoot}\n`)
+      return 1
+    }
+
+    const claudeMdPath = values['claude-md'] || null
+    const verbose = values.verbose || false
+
+    const { startLocal } = await importServer()
+    await startLocal(projectRoot, { claudeMdPath, verbose, tier: 'pro' })
+    return 0
+  }
+
+  if (mode === 'remote') {
+    const port = parseInt(values.port || '3000', 10)
+    const verbose = values.verbose || false
+
+    const { startRemote } = await importServer()
+    try {
+      await startRemote({ port, verbose })
+    } catch (err) {
+      writeStderr(`Error: ${err.message}\n`)
+      return 1
+    }
+    return 0
+  }
+
+  writeStderr(`Error: Unknown mode "${mode}". Use "local" or "remote".\n`)
+  return 1
+}
+
+export function shouldRunAsCli(
+  argv1 = process.argv[1],
+  metaUrl = import.meta.url,
+) {
+  return Boolean(argv1) && metaUrl === pathToFileURL(argv1).href
+}
+
+export async function runCliIfInvoked(deps = {}) {
+  const argv1 = deps.argv1 ?? process.argv[1]
+  const metaUrl = deps.metaUrl ?? import.meta.url
+  const mainFn = deps.mainFn || main
+  const exitFn = deps.exitFn || ((code) => process.exit(code))
+
+  if (!shouldRunAsCli(argv1, metaUrl)) {
+    return false
+  }
+
+  const exitCode = await mainFn()
+  if (exitCode !== 0) {
+    exitFn(exitCode)
+  }
+
+  return true
+}
+
+if (await runCliIfInvoked()) {
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@reinteractive/rails-insight",
+  "version": "1.0.1",
+  "description": "Rails-aware codebase indexer — MCP server for AI agents",
+  "type": "module",
+  "bin": {
+    "railsinsight": "bin/railsinsight.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reinteractive/rails-insight.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/reinteractive/rails-insight#readme",
+  "bugs": {
+    "url": "https://github.com/reinteractive/rails-insight/issues"
+  },
+  "keywords": [
+    "rails",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "indexer",
+    "code-analysis",
+    "ruby",
+    "ruby-on-rails"
+  ],
+  "license": "ISC",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/railsinsight.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:patterns": "vitest run test/patterns/",
+    "test:extractors": "vitest run test/extractors/",
+    "test:core": "vitest run test/core/",
+    "test:contracts": "vitest run test/contracts/",
+    "test:golden": "vitest run test/golden/",
+    "test:edge": "vitest run test/edge-cases/",
+    "test:perf": "vitest run test/performance/",
+    "test:cross-version": "vitest run test/cross-version/",
+    "test:mcp": "vitest run test/mcp/",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}