@reinteractive/rails-insight 1.0.1

package/src/core/context-loader.js

@@ -0,0 +1,227 @@
+/**
+ * Layer 1: Project Context Loader
+ *
+ * Parses the project's claude.md (or similar instruction file) to extract
+ * declared conventions, stack, and project context. This information is
+ * compared against actual codebase scan results by the drift detector.
+ *
+ * @module context-loader
+ */
+
+/**
+ * @typedef {Object} ProjectContext
+ * @property {boolean} found - Whether a claude.md file was found
+ * @property {string|null} raw - Raw file contents
+ * @property {Object} declared - Extracted declarations
+ * @property {string[]} declared.stack - Declared technology stack items
+ * @property {string[]} declared.conventions - Declared coding conventions
+ * @property {string[]} declared.patterns - Declared design patterns
+ * @property {string[]} declared.gems - Explicitly mentioned gems
+ * @property {string[]} declared.testing - Declared testing approach
+ * @property {string[]} declared.deployment - Declared deployment approach
+ * @property {string|null} declared.rubyVersion - Declared Ruby version
+ * @property {string|null} declared.railsVersion - Declared Rails version
+ * @property {string[]} warnings - Any parsing warnings
+ */
+
+const SECTION_HEADINGS = /^#{1,3}\s+(.+)/
+const BULLET_ITEM = /^\s*[-*]\s+(.+)/
+const NUMBERED_ITEM = /^\s*\d+[.)]\s+(.+)/
+
+const STACK_KEYWORDS =
+  /\b(rails|ruby|postgres|postgresql|mysql|sqlite|redis|sidekiq|puma|nginx|docker|kamal|heroku|aws|gcp|elasticsearch|memcached|mongodb|solid.?queue|solid.?cache|solid.?cable|turbo|stimulus|hotwire|webpacker|propshaft|sprockets|import.?maps|tailwind|bootstrap|esbuild|rollup|vite)\b/i
+
+const GEM_PATTERN =
+  /\b(devise|pundit|cancancan|paper_trail|friendly_id|acts_as_tenant|activeadmin|administrate|avo|ransack|pagy|kaminari|searchkick|pg_search|pay|stripe|rspec|minitest|factory_bot|faker|capybara|rubocop|brakeman|bullet|rack-mini-profiler|faraday|httparty|aasm|statesman|noticed|flipper|discard|paranoia|wicked_pdf|prawn|grover|whenever|sidekiq-cron|action_text|noticed|good_job)\b/i
+
+const VERSION_PATTERN = /\bruby\s+(\d+\.\d+(?:\.\d+)?)\b/i
+const RAILS_VERSION_PATTERN = /\brails\s+(\d+\.\d+(?:\.\d+)?)\b/i
+
+const CONVENTION_KEYWORDS =
+  /\b(convention|pattern|approach|practice|standard|guideline|rule|must|should|always|never|prefer|avoid|use|don't use)\b/i
+
+const TESTING_KEYWORDS =
+  /\b(rspec|minitest|test|testing|spec|factory|fixture|capybara|system test|integration test|unit test|coverage)\b/i
+
+const DEPLOY_KEYWORDS =
+  /\b(deploy|kamal|capistrano|heroku|docker|kubernetes|ci|cd|pipeline|staging|production|github actions?)\b/i
+
+const PATTERN_KEYWORDS =
+  /\b(service object|form object|query object|decorator|presenter|interactor|concern|module|mixin|observer|callback|middleware|serializer|policy|ability)\b/i
+
+/**
+ * Load and parse project context from a claude.md file.
+ *
+ * @param {import('../providers/interface.js').FileProvider} provider - File access provider
+ * @param {string} [claudeMdPath='claude.md'] - Relative path to the context file
+ * @returns {ProjectContext} Parsed project context
+ */
+export function loadProjectContext(provider, claudeMdPath = 'claude.md') {
+  const raw = provider.readFile(claudeMdPath)
+
+  if (raw === null) {
+    return {
+      found: false,
+      raw: null,
+      declared: emptyDeclared(),
+      warnings: [`No context file found at ${claudeMdPath}`],
+    }
+  }
+
+  const warnings = []
+  const declared = emptyDeclared()
+  const lines = raw.split('\n')
+
+  let currentSection = ''
+
+  for (const line of lines) {
+    const headingMatch = line.match(SECTION_HEADINGS)
+    if (headingMatch) {
+      currentSection = headingMatch[1].toLowerCase().trim()
+      continue
+    }
+
+    const content = extractLineContent(line)
+    if (!content) continue
+
+    // Extract stack items
+    const stackMatches = content.match(new RegExp(STACK_KEYWORDS.source, 'gi'))
+    if (stackMatches) {
+      for (const m of stackMatches) {
+        const normalized = m.toLowerCase()
+        if (!declared.stack.includes(normalized)) {
+          declared.stack.push(normalized)
+        }
+      }
+    }
+
+    // Extract gem mentions
+    const gemMatches = content.match(new RegExp(GEM_PATTERN.source, 'gi'))
+    if (gemMatches) {
+      for (const m of gemMatches) {
+        const normalized = m.toLowerCase()
+        if (!declared.gems.includes(normalized)) {
+          declared.gems.push(normalized)
+        }
+      }
+    }
+
+    // Extract versions
+    const rubyVer = content.match(VERSION_PATTERN)
+    if (rubyVer && !declared.rubyVersion) {
+      declared.rubyVersion = rubyVer[1]
+    }
+
+    const railsVer = content.match(RAILS_VERSION_PATTERN)
+    if (railsVer && !declared.railsVersion) {
+      declared.railsVersion = railsVer[1]
+    }
+
+    // Classify lines by section context and keywords
+    if (isTestingContext(currentSection, content)) {
+      addUnique(declared.testing, content)
+    }
+
+    if (isDeployContext(currentSection, content)) {
+      addUnique(declared.deployment, content)
+    }
+
+    if (isConventionContext(currentSection, content)) {
+      addUnique(declared.conventions, content)
+    }
+
+    if (PATTERN_KEYWORDS.test(content)) {
+      addUnique(declared.patterns, content)
+    }
+  }
+
+  return { found: true, raw, declared, warnings }
+}
+
+/**
+ * @returns {Object} Empty declared structure
+ */
+function emptyDeclared() {
+  return {
+    stack: [],
+    conventions: [],
+    patterns: [],
+    gems: [],
+    testing: [],
+    deployment: [],
+    rubyVersion: null,
+    railsVersion: null,
+  }
+}
+
+/**
+ * Extract meaningful content from a line (bullet, numbered, or plain text).
+ * @param {string} line
+ * @returns {string|null}
+ */
+function extractLineContent(line) {
+  const trimmed = line.trim()
+  if (!trimmed || trimmed.startsWith('#')) return null
+
+  const bullet = trimmed.match(BULLET_ITEM)
+  if (bullet) return bullet[1].trim()
+
+  const numbered = trimmed.match(NUMBERED_ITEM)
+  if (numbered) return numbered[1].trim()
+
+  return trimmed
+}
+
+/**
+ * @param {string} section
+ * @param {string} content
+ * @returns {boolean}
+ */
+function isTestingContext(section, content) {
+  return (
+    section.includes('test') ||
+    section.includes('spec') ||
+    section.includes('quality') ||
+    TESTING_KEYWORDS.test(content)
+  )
+}
+
+/**
+ * @param {string} section
+ * @param {string} content
+ * @returns {boolean}
+ */
+function isDeployContext(section, content) {
+  return (
+    section.includes('deploy') ||
+    section.includes('infrastructure') ||
+    section.includes('hosting') ||
+    DEPLOY_KEYWORDS.test(content)
+  )
+}
+
+/**
+ * @param {string} section
+ * @param {string} content
+ * @returns {boolean}
+ */
+function isConventionContext(section, content) {
+  return (
+    section.includes('convention') ||
+    section.includes('standard') ||
+    section.includes('guideline') ||
+    section.includes('rule') ||
+    section.includes('style') ||
+    CONVENTION_KEYWORDS.test(content)
+  )
+}
+
+/**
+ * @param {string[]} arr
+ * @param {string} item
+ */
+function addUnique(arr, item) {
+  if (!arr.includes(item)) {
+    arr.push(item)
+  }
+}

package/src/core/drift-detector.js

@@ -0,0 +1,168 @@
+/**
+ * Convention Drift Detector
+ * Compares declared conventions (from claude.md / context) against
+ * detected patterns from extractions to flag mismatches.
+ */
+
+/**
+ * Detect convention drift between declared and actual state.
+ * @param {object} declared - From context loader (claude.md parsed data)
+ * @param {object} versions - From version detector
+ * @param {object} extractions - All extraction results
+ * @returns {Array<{category: string, declared: string, actual: string, severity: string}>}
+ */
+export function detectDrift(declared = {}, versions = {}, extractions = {}) {
+  const drift = []
+
+  detectEnumSyntaxDrift(drift, versions, extractions)
+  detectTestingDrift(drift, declared, extractions)
+  detectViewsDrift(drift, declared, extractions)
+  detectStimulusDrift(drift, declared, extractions)
+  detectAuthDrift(drift, declared, extractions)
+
+  return drift
+}
+
+/**
+ * Check for legacy enum syntax in Rails 7+ apps.
+ */
+function detectEnumSyntaxDrift(drift, versions, extractions) {
+  const railsVersion = versions.rails ? parseFloat(versions.rails) : 0
+  if (railsVersion < 7.0) return
+
+  if (extractions.models) {
+    let legacyCount = 0
+    for (const model of Object.values(extractions.models)) {
+      if (model.enums) {
+        for (const e of Object.values(model.enums)) {
+          // Legacy hash syntax: enum status: { ... }
+          if (e.syntax === 'legacy') legacyCount++
+        }
+      }
+    }
+    if (legacyCount > 0) {
+      drift.push({
+        category: 'enum_syntax',
+        declared: `Rails ${versions.rails} (modern enum syntax expected)`,
+        actual: `${legacyCount} model(s) use legacy hash syntax`,
+        severity: 'low',
+      })
+    }
+  }
+}
+
+/**
+ * Check for testing convention drift.
+ */
+function detectTestingDrift(drift, declared, extractions) {
+  if (!declared.conventions) return
+
+  const testConventions = declared.conventions.filter((c) =>
+    /test|spec|rspec/i.test(c),
+  )
+
+  if (
+    testConventions.length > 0 &&
+    extractions.tier2 &&
+    extractions.tier2.testing
+  ) {
+    const framework = extractions.tier2.testing.framework
+    for (const conv of testConventions) {
+      if (/rspec/i.test(conv) && framework === 'minitest') {
+        drift.push({
+          category: 'testing',
+          declared: conv,
+          actual: 'Project uses minitest, not rspec',
+          severity: 'medium',
+        })
+      }
+      if (/minitest/i.test(conv) && framework === 'rspec') {
+        drift.push({
+          category: 'testing',
+          declared: conv,
+          actual: 'Project uses rspec, not minitest',
+          severity: 'medium',
+        })
+      }
+    }
+  }
+}
+
+/**
+ * Check for views convention drift.
+ */
+function detectViewsDrift(drift, declared, extractions) {
+  if (!declared.conventions) return
+
+  const viewConventions = declared.conventions.filter((c) =>
+    /partial|erb|haml|slim/i.test(c),
+  )
+
+  for (const conv of viewConventions) {
+    if (/no.*partial/i.test(conv) && extractions.views) {
+      const partialCount = extractions.views.partial_renders || 0
+      if (partialCount > 0) {
+        drift.push({
+          category: 'views',
+          declared: conv,
+          actual: `${partialCount} partials found`,
+          severity: 'low',
+        })
+      }
+    }
+  }
+}
+
+/**
+ * Check for Stimulus convention drift.
+ */
+function detectStimulusDrift(drift, declared, extractions) {
+  if (!declared.conventions) return
+
+  const stimConventions = declared.conventions.filter((c) =>
+    /stimulus|controller/i.test(c),
+  )
+
+  if (stimConventions.length === 0) return
+
+  for (const conv of stimConventions) {
+    if (/flat/i.test(conv) && extractions.stimulus_controllers) {
+      const nested = extractions.stimulus_controllers.some(
+        (sc) => sc.identifier && sc.identifier.includes('--'),
+      )
+      if (nested) {
+        drift.push({
+          category: 'stimulus',
+          declared: conv,
+          actual: 'Nested Stimulus controller directories detected',
+          severity: 'low',
+        })
+      }
+    }
+  }
+}
+
+/**
+ * Check for auth convention drift.
+ */
+function detectAuthDrift(drift, declared, extractions) {
+  if (!declared.stack) return
+
+  const stackAuth = Array.isArray(declared.stack)
+    ? declared.stack.filter((s) => /devise|auth/i.test(s))
+    : []
+
+  if (stackAuth.length > 0 && extractions.auth) {
+    if (
+      stackAuth.some((s) => /devise/i.test(s)) &&
+      extractions.auth.primary_strategy !== 'devise'
+    ) {
+      drift.push({
+        category: 'auth',
+        declared: 'Devise in stack',
+        actual: `Primary auth strategy: ${extractions.auth.primary_strategy || 'none'}`,
+        severity: 'medium',
+      })
+    }
+  }
+}

package/src/core/formatter.js

@@ -0,0 +1,197 @@
+/**
+ * Token-Budgeted Formatter
+ * Uses binary search to find maximal content within a token budget.
+ */
+
+import { estimateTokens } from '../utils/token-counter.js'
+
+/** Default token budget */
+const DEFAULT_BUDGET = 12000
+
+/**
+ * Format index output to fit within a token budget.
+ * @param {object} fullIndex - Complete index object
+ * @param {number} [tokenBudget] - Target token budget
+ * @returns {object} Trimmed index
+ */
+export function formatOutput(fullIndex, tokenBudget = DEFAULT_BUDGET) {
+  if (!fullIndex || typeof fullIndex !== 'object') return {}
+
+  const fullJson = JSON.stringify(fullIndex)
+  const fullTokens = estimateTokens(fullJson)
+
+  // If it fits, return as-is
+  if (fullTokens <= tokenBudget) return fullIndex
+
+  // Priority-ordered sections to include
+  const sections = [
+    'version',
+    'generated_at',
+    'versions',
+    'statistics',
+    'context',
+    'manifest',
+    'drift',
+    'rankings',
+    'relationships',
+    'extractions',
+  ]
+
+  // Build output by adding sections in priority order
+  const result = {}
+  let currentTokens = 2 // for {}
+
+  for (const section of sections) {
+    if (!(section in fullIndex)) continue
+
+    const value = fullIndex[section]
+    const sectionJson = JSON.stringify({ [section]: value })
+    const sectionTokens = estimateTokens(sectionJson)
+
+    if (currentTokens + sectionTokens <= tokenBudget) {
+      result[section] = value
+      currentTokens += sectionTokens
+    } else {
+      // Try to fit a trimmed version of the section
+      const trimmed = trimSection(section, value, tokenBudget - currentTokens)
+      if (trimmed !== null) {
+        result[section] = trimmed
+        currentTokens += estimateTokens(JSON.stringify({ [section]: trimmed }))
+      }
+      // Continue to try remaining sections
+    }
+  }
+
+  // Add any remaining top-level keys not in priority list
+  for (const key of Object.keys(fullIndex)) {
+    if (key in result) continue
+    const val = fullIndex[key]
+    const kJson = JSON.stringify({ [key]: val })
+    const kTokens = estimateTokens(kJson)
+    if (currentTokens + kTokens <= tokenBudget) {
+      result[key] = val
+      currentTokens += kTokens
+    }
+  }
+
+  return result
+}
+
+/**
+ * Trim a section to fit within available tokens.
+ * @param {string} sectionName
+ * @param {*} value
+ * @param {number} availableTokens
+ * @returns {*} Trimmed value or null
+ */
+function trimSection(sectionName, value, availableTokens) {
+  if (availableTokens <= 10) return null
+
+  if (sectionName === 'extractions' && typeof value === 'object') {
+    return trimExtractions(value, availableTokens)
+  }
+
+  if (Array.isArray(value)) {
+    const trimmed = trimArray(value, availableTokens)
+    return trimmed.length > 0 ? trimmed : null
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    return trimObject(value, availableTokens)
+  }
+
+  return null
+}
+
+/**
+ * Trim extractions to fit available tokens using binary search.
+ * Higher priority sections are kept first.
+ */
+function trimExtractions(extractions, availableTokens) {
+  const priorityOrder = [
+    'gemfile',
+    'schema',
+    'models',
+    'controllers',
+    'routes',
+    'auth',
+    'config',
+    'jobs',
+    'email',
+    'storage',
+    'caching',
+    'realtime',
+    'api',
+    'views',
+    'components',
+    'stimulus',
+    'authorization',
+    'tier2',
+    'tier3',
+  ]
+
+  const keys = Object.keys(extractions)
+  const ordered = [
+    ...priorityOrder.filter((k) => keys.includes(k)),
+    ...keys.filter((k) => !priorityOrder.includes(k)),
+  ]
+
+  const result = {}
+  let usedTokens = 2
+
+  for (const key of ordered) {
+    const json = JSON.stringify({ [key]: extractions[key] })
+    const tokens = estimateTokens(json)
+    if (usedTokens + tokens <= availableTokens) {
+      result[key] = extractions[key]
+      usedTokens += tokens
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : null
+}
+
+/**
+ * Binary search to find maximal array slice within budget.
+ */
+function trimArray(arr, availableTokens) {
+  if (!arr.length) return arr
+
+  let lo = 0
+  let hi = arr.length
+  let best = 0
+
+  while (lo <= hi) {
+    const mid = Math.floor((lo + hi) / 2)
+    const slice = arr.slice(0, mid)
+    const tokens = estimateTokens(JSON.stringify(slice))
+    if (tokens <= availableTokens) {
+      best = mid
+      lo = mid + 1
+    } else {
+      hi = mid - 1
+    }
+  }
+
+  return arr.slice(0, best)
+}
+
+/**
+ * Trim an object to fit available tokens by including keys greedily.
+ */
+function trimObject(obj, availableTokens) {
+  const keys = Object.keys(obj)
+  const result = {}
+  let used = 2 // {}
+
+  for (const key of keys) {
+    const entryJson = JSON.stringify({ [key]: obj[key] })
+    const entryTokens = estimateTokens(entryJson)
+    if (used + entryTokens <= availableTokens) {
+      result[key] = obj[key]
+      used += entryTokens
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : null
+}