@reinteractive/rails-insight 1.0.1

package/src/tools/handlers/get-deep-analysis.js

@@ -0,0 +1,294 @@
+import { z } from 'zod'
+import {
+  noIndex,
+  respond,
+  toTableName,
+  pathToClassName,
+  SIGNIFICANT_CATEGORIES,
+  DROP_GEMS,
+  NOTABLE_ABSENT_CANDIDATES,
+} from './helpers.js'
+
+/**
+ * Register the get_deep_analysis tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_deep_analysis',
+    'Get 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, testing, design_patterns, test_conventions, factory_registry, coverage_snapshot',
+    {
+      category: z.string().describe('The category to analyze'),
+      name: z
+        .string()
+        .optional()
+        .describe(
+          'Entity name for categories that accept it (e.g. model name, component name)',
+        ),
+      depth: z
+        .number()
+        .optional()
+        .describe('Depth for related queries (default: 2)'),
+    },
+    async ({ category, name, depth = 2 }) => {
+      if (!state.index) return noIndex()
+      const index = state.index
+      const extractions = index.extractions || {}
+
+      switch (category) {
+        case 'authentication':
+          return respond(extractions.auth || {})
+
+        case 'authorization':
+          return respond(extractions.authorization || {})
+
+        case 'jobs':
+          return respond(extractions.jobs || {})
+
+        case 'email':
+          return respond(extractions.email || {})
+
+        case 'storage':
+          return respond(extractions.storage || {})
+
+        case 'caching':
+          return respond(extractions.caching || {})
+
+        case 'realtime':
+          return respond(extractions.realtime || {})
+
+        case 'api_patterns':
+          return respond(extractions.api || {})
+
+        case 'dependencies': {
+          const gemfile = extractions.gemfile || {}
+          const allGems = Array.isArray(gemfile.gems) ? gemfile.gems : []
+          const gemNames = new Set(allGems.map((g) => g.name))
+          const significant = {}
+          for (const gem of allGems) {
+            if (!SIGNIFICANT_CATEGORIES.has(gem.category)) continue
+            if (DROP_GEMS.has(gem.name)) continue
+            if (!significant[gem.category]) significant[gem.category] = {}
+            significant[gem.category][gem.name] =
+              gem.resolved || gem.version || 'unknown'
+          }
+          if (significant.testing) {
+            const testingEntries = Object.entries(significant.testing).slice(
+              0,
+              3,
+            )
+            significant.testing = Object.fromEntries(testingEntries)
+          }
+          const notableAbsent = NOTABLE_ABSENT_CANDIDATES.filter(
+            (g) => !gemNames.has(g),
+          )
+          return respond({
+            ...significant,
+            total_gem_count: allGems.length,
+            notable_absent: notableAbsent,
+            ruby_version: gemfile.rubyVersion || null,
+          })
+        }
+
+        case 'components': {
+          const components = extractions.components || {}
+          if (name) {
+            const comp = components[name]
+            if (!comp)
+              return respond({
+                error: `Component '${name}' not found`,
+                available: Object.keys(components),
+              })
+            return respond(comp)
+          }
+          return respond(
+            Object.entries(components).map(([n, c]) => ({
+              name: n,
+              tier: c.tier,
+              slot_count: (c.slots || []).length,
+              has_preview: c.has_preview || false,
+              file: c.file,
+            })),
+          )
+        }
+
+        case 'stimulus': {
+          const stimulusControllers = extractions.stimulus_controllers || []
+          if (name) {
+            const sc = stimulusControllers.find(
+              (s) => s.identifier === name || s.class === name,
+            )
+            if (!sc)
+              return respond({
+                error: `Stimulus controller '${name}' not found`,
+              })
+            return respond(sc)
+          }
+          return respond(stimulusControllers)
+        }
+
+        case 'views':
+          return respond(extractions.views || {})
+
+        case 'convention_drift':
+          return respond({
+            drift: index.drift || [],
+            total: (index.drift || []).length,
+          })
+
+        case 'manifest': {
+          const manifest = index.manifest || {}
+          if (name) {
+            const entries = manifest.byCategory?.[name] || []
+            return respond({
+              category: name,
+              count: entries.length,
+              files: entries.map((e) => e.path),
+            })
+          }
+          return respond({
+            total_files: manifest.total_files,
+            categories: manifest.stats,
+          })
+        }
+
+        case 'detected_stack':
+          return respond(index.versions || {})
+
+        case 'related': {
+          if (!name)
+            return respond({
+              error: 'name parameter required for related category',
+            })
+          const allRels = index.relationships || []
+          const rankings = index.rankings || {}
+          const visited = new Set([name])
+          let frontier = [name]
+          const connected = []
+          for (let d = 0; d < depth && frontier.length > 0; d++) {
+            const nextFrontier = []
+            for (const current of frontier) {
+              for (const rel of allRels) {
+                let neighbor = null,
+                  direction = null
+                if (rel.from === current && !visited.has(rel.to)) {
+                  neighbor = rel.to
+                  direction = 'outgoing'
+                } else if (rel.to === current && !visited.has(rel.from)) {
+                  neighbor = rel.from
+                  direction = 'incoming'
+                }
+                if (neighbor) {
+                  visited.add(neighbor)
+                  nextFrontier.push(neighbor)
+                  connected.push({
+                    entity: neighbor,
+                    relationship: rel.type,
+                    direction,
+                    distance: d + 1,
+                    rank: rankings[neighbor] || 0,
+                  })
+                }
+              }
+            }
+            frontier = nextFrontier
+          }
+          connected.sort((a, b) => a.distance - b.distance || b.rank - a.rank)
+          return respond({
+            source: name,
+            depth,
+            connected,
+            total: connected.length,
+          })
+        }
+
+        case 'model_list': {
+          const models = extractions.models || {}
+          return respond(
+            Object.entries(models).map(([n, m]) => ({
+              name: n,
+              superclass: m.superclass || 'ApplicationRecord',
+              association_count: (m.associations || []).length,
+              scope_count: (m.scopes || []).length,
+              has_secure_password: m.has_secure_password || false,
+              file: m.file,
+            })),
+          )
+        }
+
+        case 'controller_list': {
+          const controllers = extractions.controllers || {}
+          return respond(
+            Object.entries(controllers).map(([n, c]) => ({
+              name: n,
+              superclass: c.superclass || 'ApplicationController',
+              action_count: (c.actions || []).length,
+              namespace: c.namespace || null,
+              file: c.file,
+            })),
+          )
+        }
+
+        case 'component_list': {
+          const components = extractions.components || {}
+          return respond(
+            Object.entries(components).map(([n, c]) => ({
+              name: n,
+              tier: c.tier,
+              slot_count: (c.slots || []).length,
+              has_preview: c.has_preview || false,
+              file: c.file,
+            })),
+          )
+        }
+
+        case 'testing':
+          return respond(extractions.tier2?.testing || {})
+
+        case 'design_patterns':
+          return respond(extractions.tier2?.design_patterns || {})
+
+        case 'test_conventions':
+          return respond(extractions.test_conventions || {})
+
+        case 'factory_registry':
+          return respond(extractions.factory_registry || {})
+
+        case 'coverage_snapshot':
+          return respond(extractions.coverage_snapshot || {})
+
+        default:
+          return respond({
+            error: `Unknown category: ${category}`,
+            available: [
+              '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',
+              'testing',
+              'design_patterns',
+              'test_conventions',
+              'factory_registry',
+              'coverage_snapshot',
+            ],
+          })
+      }
+    },
+  )
+}

package/src/tools/handlers/get-domain-clusters.js

@@ -0,0 +1,113 @@
+import { z } from 'zod'
+import { noIndex, respond, pathToClassName } from './helpers.js'
+import { WELL_COVERED_THRESHOLD } from '../../core/constants.js'
+
+/**
+ * Register the get_domain_clusters tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_domain_clusters',
+    'Returns domain-clustered file groups for parallel test generation. Files in the same cluster share associations and factories. Files in different clusters can be worked on simultaneously without conflict.',
+    {
+      max_cluster_size: z
+        .number()
+        .optional()
+        .describe('Maximum files per cluster (default: 8)'),
+      include_covered: z
+        .boolean()
+        .optional()
+        .describe('Include files that already have coverage (default: false)'),
+    },
+    async ({ max_cluster_size = 8, include_covered = false }) => {
+      if (!state.index) return noIndex()
+      const extractions = state.index.extractions || {}
+      const models = extractions.models || {}
+      const coverageSnapshot = extractions.coverage_snapshot || {}
+      const factoryRegistry = extractions.factory_registry || {}
+      const relationships = state.index.relationships || []
+
+      const clusters = []
+      const assigned = new Set()
+
+      const sortedModels = Object.entries(models)
+        .filter(([, m]) => m.type !== 'concern' && !m.abstract)
+        .sort(
+          (a, b) =>
+            (b[1].associations?.length || 0) - (a[1].associations?.length || 0),
+        )
+
+      for (const [name, model] of sortedModels) {
+        if (assigned.has(name)) continue
+
+        if (!include_covered) {
+          const fileCov = coverageSnapshot.per_file?.[model.file]
+          if (fileCov && fileCov.line_coverage >= WELL_COVERED_THRESHOLD)
+            continue
+        }
+
+        const cluster = {
+          anchor: name,
+          models: [name],
+          files: model.file ? [model.file] : [],
+          factories_available: [],
+          shared_associations: [],
+        }
+        assigned.add(name)
+
+        const relatedModels = (model.associations || [])
+          .map((a) => pathToClassName(a.name))
+          .filter((n) => models[n] && !assigned.has(n))
+
+        for (const related of relatedModels) {
+          if (cluster.models.length >= max_cluster_size) break
+
+          if (!include_covered) {
+            const relModel = models[related]
+            const fileCov = relModel?.file
+              ? coverageSnapshot.per_file?.[relModel.file]
+              : null
+            if (fileCov && fileCov.line_coverage >= WELL_COVERED_THRESHOLD)
+              continue
+          }
+
+          cluster.models.push(related)
+          assigned.add(related)
+          if (models[related]?.file) cluster.files.push(models[related].file)
+          cluster.shared_associations.push({
+            from: name,
+            to: related,
+            type:
+              (model.associations || []).find(
+                (a) => pathToClassName(a.name) === related,
+              )?.type || 'association',
+          })
+        }
+
+        for (const modelName of cluster.models) {
+          const factoryName = modelName.replace(/([A-Z])/g, (m, l, i) =>
+            i === 0 ? l.toLowerCase() : `_${l.toLowerCase()}`,
+          )
+          if (factoryRegistry.factories?.[factoryName]) {
+            cluster.factories_available.push(factoryName)
+          }
+        }
+
+        clusters.push(cluster)
+      }
+
+      return respond({
+        clusters,
+        total_clusters: clusters.length,
+        unassigned_models: Object.keys(models).filter(
+          (n) =>
+            !assigned.has(n) &&
+            models[n].type !== 'concern' &&
+            !models[n].abstract,
+        ).length,
+      })
+    },
+  )
+}

package/src/tools/handlers/get-factory-registry.js

@@ -0,0 +1,43 @@
+import { z } from 'zod'
+import { noIndex, respond } from './helpers.js'
+
+/**
+ * Register the get_factory_registry tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_factory_registry',
+    'Returns parsed FactoryBot factory definitions including attributes, traits, sequences, and associations. Use to understand what test data factories are available.',
+    {
+      model: z
+        .string()
+        .optional()
+        .describe('Filter to a specific model/factory name'),
+    },
+    async ({ model }) => {
+      if (!state.index) return noIndex()
+      const registry = state.index.extractions?.factory_registry || {}
+
+      if (model) {
+        const factory =
+          registry.factories?.[model] ||
+          registry.factories?.[
+            model.replace(/([A-Z])/g, (m, l, i) =>
+              i === 0 ? l.toLowerCase() : `_${l.toLowerCase()}`,
+            )
+          ]
+        if (!factory) {
+          return respond({
+            error: `Factory for '${model}' not found`,
+            available: Object.keys(registry.factories || {}),
+          })
+        }
+        return respond(factory)
+      }
+
+      return respond(registry)
+    },
+  )
+}

package/src/tools/handlers/get-full-index.js

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+import { formatOutput } from '../../core/formatter.js'
+import { noIndex, respond } from './helpers.js'
+import { DEFAULT_FULL_INDEX_BUDGET } from '../../core/constants.js'
+
+/**
+ * Register the get_full_index tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_full_index',
+    'Complete index JSON trimmed to fit a specified token budget.',
+    {
+      token_budget: z
+        .number()
+        .optional()
+        .default(DEFAULT_FULL_INDEX_BUDGET)
+        .describe('Maximum token budget (default: 12000)'),
+    },
+    async ({ token_budget = DEFAULT_FULL_INDEX_BUDGET }) => {
+      if (!state.index) return noIndex()
+      const trimmed = formatOutput(state.index, token_budget)
+      return respond(trimmed)
+    },
+  )
+}

package/src/tools/handlers/get-model.js

@@ -0,0 +1,108 @@
+import { z } from 'zod'
+import { noIndex, respond, toTableName, pathToClassName } from './helpers.js'
+
+/**
+ * Register the get_model tool.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} state - Mutable state with { index, provider, verbose }
+ */
+export function register(server, state) {
+  server.tool(
+    'get_model',
+    'Deep extraction for a specific model: associations, validations, scopes with queries, enums with values, callbacks, public methods, database columns.',
+    { name: z.string().describe('Model class name (e.g. "User")') },
+    async ({ name }) => {
+      if (!state.index) return noIndex()
+      const models = state.index.extractions?.models || {}
+      const model = models[name]
+      if (!model) {
+        return respond({
+          error: `Model '${name}' not found`,
+          available: Object.keys(models),
+        })
+      }
+
+      // Enrich with schema columns
+      const schema = state.index.extractions?.schema || {}
+      const tables = schema.tables || []
+      const tableName = model.table_name || toTableName(name)
+      const tableData = tables.find((t) => t.name === tableName)
+      const columns = tableData
+        ? tableData.columns.map((c) => ({
+            name: c.name,
+            type: c.type,
+            constraints: c.constraints || null,
+            ...(tableData.indexes?.some(
+              (i) => i.columns.includes(c.name) && i.unique,
+            )
+              ? { unique_index: true }
+              : {}),
+          }))
+        : null
+
+      // FK relationships from schema
+      const schemaFks = schema.foreign_keys || []
+      const foreign_keys = schemaFks
+        .filter((fk) => fk.from_table === tableName)
+        .map((fk) => ({
+          column: fk.column,
+          references: { table: fk.to_table, column: fk.primary_key || 'id' },
+        }))
+
+      // Indexes for this table
+      const indexes = (tableData?.indexes || []).map((i) => ({
+        columns: i.columns,
+        unique: i.unique || false,
+        name: i.name || null,
+      }))
+
+      // Inverse associations
+      const allModels = state.index.extractions?.models || {}
+      const nameLower = name.toLowerCase()
+      const inverse_associations = Object.entries(allModels)
+        .filter(([mName]) => mName !== name)
+        .flatMap(([mName, m]) =>
+          (m.associations || [])
+            .filter((a) => {
+              const assocName = a.name?.toLowerCase?.() || ''
+              return (
+                assocName === nameLower ||
+                assocName === nameLower + 's' ||
+                assocName === nameLower + 'es' ||
+                (a.options &&
+                  String(a.options)
+                    .toLowerCase()
+                    .includes(`class_name.*${nameLower}`))
+              )
+            })
+            .map((a) => ({
+              model: mName,
+              type: a.type,
+              name: a.name,
+              options: a.options || null,
+            })),
+        )
+
+      // Auth relevance disambiguation
+      let auth_relevance = undefined
+      const authzData = state.index.extractions?.authorization || {}
+      if (
+        /^role$/i.test(name) &&
+        authzData.roles?.model &&
+        authzData.roles.model !== name
+      ) {
+        auth_relevance = `none — this is a domain model for job positions, not related to access control. Authorization roles are defined as an enum on the ${authzData.roles.model} model.`
+      }
+
+      return respond({
+        ...model,
+        columns,
+        indexes: indexes.length > 0 ? indexes : null,
+        foreign_keys: foreign_keys.length > 0 ? foreign_keys : null,
+        inverse_associations:
+          inverse_associations.length > 0 ? inverse_associations : null,
+        ...(auth_relevance ? { auth_relevance } : {}),
+      })
+    },
+  )
+}