spec_ai 0.1.0

data/lib/spec_ai/snapshot_plan.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module SpecAi
+  class SnapshotPlan
+    def self.build(snapshot)
+      new(snapshot).plan
+    end
+
+    def initialize(snapshot)
+      @snapshot = snapshot
+    end
+
+    def plan
+      scenarios = []
+      scenarios << happy_path
+      scenarios.concat(validation_scenarios)
+      scenarios.concat(association_scenarios)
+      scenarios.concat(devise_scenarios)
+      scenarios = scenarios.compact.uniq { |scenario| scenario["name"] }
+      return if scenarios.empty?
+
+      TestPlan.new(
+        "target" => @snapshot.target.class_name,
+        "test_type" => "model",
+        "scenarios" => scenarios
+      )
+    end
+
+    private
+
+    def happy_path
+      scenario(
+        name: "is valid with complete attributes",
+        category: "happy_path",
+        expected_behavior: "valid"
+      )
+    end
+
+    def validation_scenarios
+      Array(@snapshot.model[:validations]).flat_map do |item|
+        attributes = Array(item[:attributes] || item["attributes"]).map(&:to_s)
+        validators = Array(item[:validators] || item["validators"]).map(&:to_s)
+        attributes.filter_map { |attribute| attribute if usable_attribute?(attribute) }.flat_map do |attribute|
+          scenarios_for(attribute, validators)
+        end
+      end
+    end
+
+    def scenarios_for(attribute, validators)
+      list = []
+      if validators.include?("presence")
+        list << scenario(
+          name: "requires #{attribute}",
+          category: "validation",
+          expected_behavior: "invalid",
+          attribute: attribute,
+          value: "nil",
+          setup: ["#{attribute} is nil"]
+        )
+        if SpecAi.configuration.include_edge_cases
+          list << scenario(
+            name: "rejects blank #{attribute}",
+            category: "edge_case",
+            expected_behavior: "invalid",
+            attribute: attribute,
+            value: "",
+            setup: ["#{attribute} is blank"]
+          )
+        end
+      end
+      if validators.include?("uniqueness")
+        list << scenario(
+          name: "requires a unique #{attribute}",
+          category: "validation",
+          expected_behavior: "invalid",
+          attribute: attribute,
+          value: unique_value(attribute),
+          setup: ["another record already has this #{attribute}"]
+        )
+      end
+      if validators.include?("format")
+        list << scenario(
+          name: "rejects an invalid #{attribute} format",
+          category: "validation",
+          expected_behavior: "invalid",
+          attribute: attribute,
+          value: format_value(attribute),
+          setup: ["#{attribute} is malformed"]
+        )
+      end
+      if validators.include?("length")
+        list << scenario(
+          name: "rejects a too-short #{attribute}",
+          category: "validation",
+          expected_behavior: "invalid",
+          attribute: attribute,
+          value: "short",
+          setup: ["#{attribute} is too short"]
+        )
+      end
+      if validators.include?("confirmation")
+        list << scenario(
+          name: "requires #{attribute} confirmation to match",
+          category: "validation",
+          expected_behavior: "invalid",
+          attribute: "#{attribute}_confirmation",
+          value: "mismatch",
+          setup: ["#{attribute}_confirmation does not match"]
+        )
+      end
+      list
+    end
+
+    def association_scenarios
+      Array(@snapshot.model[:associations]).filter_map do |item|
+        name = (item[:name] || item["name"]).to_s
+        macro = (item[:macro] || item["macro"]).to_s
+        next if name.empty? || macro.empty?
+
+        scenario(
+          name: "#{macro.tr('_', ' ')} #{name}",
+          category: "association",
+          expected_behavior: "has_association",
+          association: name,
+          association_macro: macro
+        )
+      end
+    end
+
+    def devise_scenarios
+      return [] unless @snapshot.model[:source].to_s.match?(/\bdevise\b/)
+
+      list = []
+      if usable_attribute?("password") && Array(@snapshot.model[:validations]).none? { |item| Array(item[:attributes] || item["attributes"]).map(&:to_s).include?("password") }
+        list.concat(scenarios_for("password", %w[presence length]))
+      end
+      list
+    end
+
+    def usable_attribute?(name)
+      @snapshot.known_attributes.include?(name.to_s)
+    end
+
+    def unique_value(attribute)
+      attribute == "email" ? "duplicate@example.com" : "duplicate"
+    end
+
+    def format_value(attribute)
+      attribute == "email" ? "not-an-email" : "invalid"
+    end
+
+    def scenario(name:, category:, expected_behavior:, attribute: nil, value: nil, association: nil, association_macro: nil, setup: [])
+      {
+        "name" => name,
+        "category" => category,
+        "priority" => "high",
+        "setup" => setup,
+        "expected_behavior" => expected_behavior,
+        "attribute" => attribute,
+        "value" => value,
+        "association" => association,
+        "association_macro" => association_macro
+      }
+    end
+  end
+end

data/lib/spec_ai/target.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SpecAi
+  class Target
+    attr_reader :input, :class_name, :model_path, :spec_path, :table_name, :factory_name
+
+    def initialize(input, app_root: SpecAi.configuration.app_root)
+      @input = input.to_s.strip
+      @app_root = app_root
+      resolve!
+    end
+
+    def source_path
+      model_path
+    end
+
+    def name
+      class_name
+    end
+
+    private
+
+    def resolve!
+      if looks_like_path?
+        relative = @input.sub(%r{\A#{Regexp.escape(@app_root)}/?}, "")
+        relative = relative.sub(%r{\A(?:\./)+}, "")
+        @class_name = class_name_from_path(relative)
+      else
+        @class_name = @input.sub(/\.rb\z/, "")
+      end
+
+      @model_path = Inflector.model_path(@class_name)
+      @spec_path = Inflector.spec_path(@class_name)
+      @table_name = Inflector.table_name(@class_name)
+      @factory_name = Inflector.factory_name(@class_name)
+
+      sandbox = Sandbox.new(@app_root)
+      return if sandbox.exist?(@model_path)
+
+      raise TargetNotFound, "could not find model file #{@model_path} for #{@input}"
+    end
+
+    def looks_like_path?
+      @input.include?("/") || @input.end_with?(".rb")
+    end
+
+    def class_name_from_path(relative)
+      cleaned = relative.sub(%r{\Aapp/models/}, "").sub(%r{\Aspec/models/}, "").sub(/_spec\.rb\z/, "").sub(/\.rb\z/, "")
+      Inflector.camelize(cleaned)
+    end
+  end
+end

data/lib/spec_ai/test_plan.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+module SpecAi
+  class TestPlan
+    SCHEMA = {
+      "type" => "object",
+      "properties" => {
+        "target" => { "type" => "string" },
+        "test_type" => { "type" => "string", "enum" => %w[model] },
+        "scenarios" => {
+          "type" => "array",
+          "minItems" => 1,
+          "items" => {
+            "type" => "object",
+            "properties" => {
+              "name" => { "type" => "string" },
+              "category" => {
+                "type" => "string",
+                "enum" => %w[happy_path validation association edge_case error_handling]
+              },
+              "priority" => { "type" => "string", "enum" => %w[high medium low] },
+              "setup" => { "type" => "array", "items" => { "type" => "string" } },
+              "expected_behavior" => { "type" => "string" },
+              "attribute" => { "type" => "string" },
+              "value" => { "type" => "string" },
+              "association" => { "type" => "string" },
+              "association_macro" => { "type" => "string" }
+            },
+            "required" => %w[name category priority expected_behavior]
+          }
+        }
+      },
+      "required" => %w[target test_type scenarios]
+    }.freeze
+
+    Scenario = Struct.new(
+      :name, :category, :priority, :setup, :expected_behavior,
+      :attribute, :value, :association, :association_macro,
+      keyword_init: true
+    )
+
+    attr_reader :target, :test_type, :scenarios
+
+    def self.from(data)
+      new(data)
+    end
+
+    def self.from_task(task)
+      from(payload_from_task(task))
+    end
+
+    def self.unreadable(raw)
+      cfg = SpecAi.configuration
+      <<~MSG.strip
+        #{cfg.provider} / #{cfg.model} did not return a valid test plan.
+
+        Reply: #{preview(raw)}
+
+        Check the API key for this provider, or switch provider/model in config/spec_ai.yml.
+        Re-run with --verbose to see the full LLM output.
+      MSG
+    end
+
+    def self.preview(raw)
+      text = raw.to_s.strip.gsub(/\s+/, " ")
+      return "(empty reply)" if text.empty?
+
+      text.length > 180 ? "#{text[0, 177]}..." : text
+    end
+
+    def self.payload_from_task(task)
+      if task.respond_to?(:structured_output)
+        data = task.structured_output
+        return data if usable_payload?(data)
+      end
+      if task.respond_to?(:result)
+        data = task.result
+        return data if usable_payload?(data)
+      end
+      task.respond_to?(:raw_result) ? task.raw_result : nil
+    end
+
+    def self.usable_payload?(data)
+      return false if data.nil?
+      return data.any? if data.is_a?(Hash)
+      return !data.strip.empty? if data.is_a?(String)
+      return data.any? if data.is_a?(Array)
+
+      true
+    end
+
+    def initialize(data)
+      hash = normalize(data)
+      @target = hash.fetch("target")
+      @test_type = hash["test_type"] || "model"
+      @scenarios = Array(hash["scenarios"]).map { |scenario| build_scenario(scenario) }
+      raise InvalidPlan, "test plan must include at least one scenario" if @scenarios.empty?
+    end
+
+    def to_h
+      {
+        "target" => target,
+        "test_type" => test_type,
+        "scenarios" => scenarios.map { |scenario| scenario.to_h.transform_keys(&:to_s) }
+      }
+    end
+
+    def without_existing(example_names)
+      names = Array(example_names).map { |name| name.to_s.downcase }
+      kept = scenarios.reject { |scenario| names.include?(scenario.name.to_s.downcase) }
+      return self if kept.size == scenarios.size
+      return nil if kept.empty?
+
+      duplicate = to_h.merge("scenarios" => kept.map { |scenario| scenario.to_h.transform_keys(&:to_s) })
+      self.class.new(duplicate)
+    end
+
+    def ground(snapshot)
+      kept = scenarios.select { |scenario| grounded?(scenario, snapshot) }
+      return self if kept.size == scenarios.size
+      return nil if kept.empty?
+
+      self.class.new(to_h.merge("scenarios" => kept.map { |scenario| scenario.to_h.transform_keys(&:to_s) }))
+    end
+
+    def self.merge(primary, extra)
+      return extra if primary.nil?
+      return primary if extra.nil?
+
+      names = primary.scenarios.map { |scenario| scenario.name.to_s.downcase }
+      added = extra.scenarios.reject { |scenario| names.include?(scenario.name.to_s.downcase) }
+      return primary if added.empty?
+
+      scenarios = primary.to_h["scenarios"] + added.map { |scenario| scenario.to_h.transform_keys(&:to_s) }
+      new(primary.to_h.merge("scenarios" => scenarios))
+    end
+
+    def self.stabilize(plan, snapshot)
+      base = SnapshotPlan.build(snapshot)
+      grounded = plan&.ground(snapshot)
+      merge(base, grounded) || grounded || base
+    end
+
+    private
+
+    def normalize(data)
+      original = data
+      data = unwrap(data)
+      raise InvalidPlan, self.class.unreadable(original) unless data.is_a?(Hash)
+
+      stringify(data)
+    rescue JSON::ParserError
+      raise InvalidPlan, self.class.unreadable(original)
+    end
+
+    def unwrap(data)
+      return data if data.is_a?(Hash)
+
+      if data.is_a?(Array)
+        match = data.find { |item| item.is_a?(Hash) && (item.key?("scenarios") || item.key?(:scenarios)) }
+        return match if match
+        return data.first if data.first.is_a?(Hash)
+      end
+
+      return unwrap_json(data) if data.is_a?(String)
+
+      data
+    end
+
+    def unwrap_json(raw)
+      text = raw.to_s.strip
+      fenced = text[/```(?:json)?\s*(\{.*?\})\s*```/m, 1]
+      text = fenced if fenced
+      parse_json_object(text)
+    end
+
+    def parse_json_object(text)
+      text = text.to_s.strip
+      return JSON.parse(text) if text.start_with?("{")
+
+      start = text.index("{")
+      raise JSON::ParserError, "no JSON object found" unless start
+
+      JSON.parse(extract_balanced_object(text, start))
+    end
+
+    def extract_balanced_object(text, start)
+      depth = 0
+      in_string = false
+      escape = false
+
+      text[start..].each_char.with_index do |char, index|
+        if in_string
+          if escape
+            escape = false
+          elsif char == "\\"
+            escape = true
+          elsif char == '"'
+            in_string = false
+          end
+          next
+        end
+
+        in_string = true if char == '"'
+        depth += 1 if char == "{"
+        depth -= 1 if char == "}"
+        return text[start, index + 1] if depth.zero?
+      end
+
+      raise JSON::ParserError, "unbalanced JSON object"
+    end
+
+    def stringify(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), memo| memo[key.to_s] = stringify(item) }
+      when Array
+        value.map { |item| stringify(item) }
+      else
+        value
+      end
+    end
+
+    def build_scenario(raw)
+      raw = stringify(raw)
+      Scenario.new(
+        name: raw.fetch("name"),
+        category: raw.fetch("category"),
+        priority: raw["priority"] || "medium",
+        setup: Array(raw["setup"]),
+        expected_behavior: raw.fetch("expected_behavior"),
+        attribute: raw["attribute"],
+        value: raw["value"],
+        association: raw["association"],
+        association_macro: raw["association_macro"]
+      )
+    rescue KeyError => error
+      raise InvalidPlan, "scenario is missing #{error.key}"
+    end
+
+    DEVISE_EMAIL = /\A[^@\s]+@[^@\s]+\z/.freeze
+
+    def grounded?(scenario, snapshot)
+      return false if invented_association?(scenario, snapshot)
+      return false if invented_attribute?(scenario, snapshot)
+      return false if unfounded_invalid?(scenario, snapshot)
+
+      true
+    end
+
+    def invented_association?(scenario, snapshot)
+      return false unless scenario.category == "association"
+
+      name = scenario.association.to_s
+      name.empty? || !snapshot.association_names.include?(name) || haystack(scenario).match?(/no associations?\b/i)
+    end
+
+    def invented_attribute?(scenario, snapshot)
+      return false unless %w[validation edge_case].include?(scenario.category.to_s)
+
+      attribute = scenario.attribute.to_s
+      !attribute.empty? && !snapshot.known_attributes.include?(attribute)
+    end
+
+    def unfounded_invalid?(scenario, snapshot)
+      return false unless invalid_expectation?(scenario)
+
+      text = haystack(scenario)
+      value = scenario.value.to_s
+      attribute = inferred_attribute(scenario, snapshot)
+
+      return false if text.match?(/unique|uniqueness|duplicate/i)
+      return true if text.match?(/no associations?\b/i)
+      return true if missing_confirmation?(snapshot, attribute, text, value)
+      return true if whitespace_email?(snapshot, attribute, text, value)
+      return true if whitespace_password?(attribute, text)
+      return true if devise_allows_email?(snapshot, attribute, text, value)
+      return true if invented_constraint?(snapshot, attribute, text)
+
+      false
+    end
+
+    def inferred_attribute(scenario, snapshot)
+      return scenario.attribute.to_s unless scenario.attribute.to_s.empty?
+
+      text = haystack(scenario)
+      snapshot.known_attributes.find { |name| text.match?(/\b#{Regexp.escape(name)}\b/i) }.to_s
+    end
+
+    COMPLEXITY_RE = /special[_\s-]*character|uppercase|lowercase|(?<![a-z])digit|symbol|complexity|strong[_\s-]*password|without[_\s-]*special/i
+
+    def invented_constraint?(snapshot, attribute, text)
+      return false if attribute.to_s.empty?
+
+      validators = snapshot.validators_for(attribute)
+      return true if text.match?(COMPLEXITY_RE) && !validators.include?("format")
+      return true if attribute == "password" && snapshot.devise? &&
+                     text.match?(/format|pattern|regex/i) && !validators.include?("format")
+
+      false
+    end
+
+    def invalid_expectation?(scenario)
+      expected = scenario.expected_behavior.to_s
+      expected.match?(/invalid|not[_ ]valid/i)
+    end
+
+    def missing_confirmation?(snapshot, attribute, text, value)
+      return false unless snapshot.devise?
+      confirmation = attribute.end_with?("_confirmation") || text.match?(/password confirmation|password_confirmation/i)
+      return false unless confirmation
+      return false if text.match?(/mismatch|does not match|different/i)
+
+      value.empty? || value == "nil" || text.match?(/without|missing|blank|empty/i)
+    end
+
+    def whitespace_email?(snapshot, attribute, text, value)
+      return false unless snapshot.devise?
+      return false unless attribute == "email" || text.match?(/\bemail\b/i)
+
+      text.match?(/leading whitespace|trailing whitespace|whitespace in email/i) || value.match?(/\A\s|\s\z/)
+    end
+
+    def whitespace_password?(attribute, text)
+      (attribute == "password" || text.match?(/\bpassword\b/i)) &&
+        text.match?(/leading whitespace|trailing whitespace|whitespace in password/i)
+    end
+
+    def devise_allows_email?(snapshot, attribute, text, value)
+      return false unless snapshot.devise?
+      return false unless attribute == "email" || text.match?(/\bemail\b/i)
+      return false if value.empty? || value == "nil"
+      return false if text.match?(/unique|uniqueness|duplicate/i)
+
+      value.match?(DEVISE_EMAIL)
+    end
+
+    def haystack(scenario)
+      [scenario.name, scenario.expected_behavior, scenario.attribute, scenario.value, *Array(scenario.setup)].join(" ")
+    end
+  end
+end

data/lib/spec_ai/tools/list_related_files.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rcrewai"
+
+module SpecAi
+  module Tools
+    class ListRelatedFiles < RCrewAI::Tools::Base
+      tool_name "list_related_files"
+      description "List model, spec, factory, and schema paths related to a Rails model"
+      param :class_name, type: :string, required: true, description: "Model class name, e.g. User"
+
+      def initialize(sandbox: SpecAi::Sandbox.new)
+        @sandbox = sandbox
+        super()
+      end
+
+      def execute(class_name:)
+        target = Target.new(class_name, app_root: @sandbox.root)
+        snapshot = Context::Builder.new(target, sandbox: @sandbox).build
+        lines = [
+          target.model_path,
+          target.spec_path,
+          snapshot.schema[:path],
+          snapshot.factories[:path]
+        ]
+        snapshot.related.each { |item| lines << item[:path] }
+        lines.compact.uniq.join("\n")
+      rescue SpecAi::Error => error
+        "ERROR: #{error.message}"
+      end
+    end
+  end
+end

data/lib/spec_ai/tools/read_app_file.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rcrewai"
+
+module SpecAi
+  module Tools
+    class ReadAppFile < RCrewAI::Tools::Base
+      tool_name "read_app_file"
+      description "Read a file inside the Rails app (app/, spec/, db/, config/, test/)"
+      param :path, type: :string, required: true, description: "Relative path from the application root"
+
+      def initialize(sandbox: SpecAi::Sandbox.new)
+        @sandbox = sandbox
+        super()
+      end
+
+      def execute(path:)
+        @sandbox.read(path)
+      rescue SpecAi::Error => error
+        "ERROR: #{error.message}"
+      end
+    end
+  end
+end

data/lib/spec_ai/tools/read_existing_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rcrewai"
+
+module SpecAi
+  module Tools
+    class ReadExistingSpec < RCrewAI::Tools::Base
+      tool_name "read_existing_spec"
+      description "Read the existing RSpec file for a model if it exists"
+      param :class_name, type: :string, required: true, description: "Model class name, e.g. User"
+
+      def initialize(sandbox: SpecAi::Sandbox.new)
+        @sandbox = sandbox
+        super()
+      end
+
+      def execute(class_name:)
+        target = Target.new(class_name, app_root: @sandbox.root)
+        result = Analyzers::ExistingSpecs.new(target, sandbox: @sandbox).analyze
+        return "No existing spec at #{result[:path]}" unless result[:present]
+
+        "#{result[:path]}\n#{result[:excerpt]}"
+      rescue SpecAi::Error => error
+        "ERROR: #{error.message}"
+      end
+    end
+  end
+end

data/lib/spec_ai/tools/read_factory.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rcrewai"
+
+module SpecAi
+  module Tools
+    class ReadFactory < RCrewAI::Tools::Base
+      tool_name "read_factory"
+      description "Read a FactoryBot factory for a model"
+      param :class_name, type: :string, required: true, description: "Model class name, e.g. User"
+
+      def initialize(sandbox: SpecAi::Sandbox.new)
+        @sandbox = sandbox
+        super()
+      end
+
+      def execute(class_name:)
+        target = Target.new(class_name, app_root: @sandbox.root)
+        result = Analyzers::Factories.new(target, sandbox: @sandbox).analyze
+        return "No factory found for #{class_name}" unless result[:present]
+
+        "#{result[:path]} (factory :#{result[:name]})\n#{result[:excerpt]}"
+      rescue SpecAi::Error => error
+        "ERROR: #{error.message}"
+      end
+    end
+  end
+end