specproof 0.1.0

data/lib/specproof/skills.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+require "tmpdir"
+
+module SpecProof
+  # Exports the packaged workflow skills into a client directory.
+  module Skills
+    SKILL_NAMES = %w[specproof-specify specproof-test-gaps].freeze
+    SOURCE_ROOT = File.expand_path("../../skills", __dir__).freeze
+
+    module_function
+
+    # Copies the packaged skills into an explicit client skills directory.
+    # `source_root` is an internal seam for tests; production callers use the
+    # packaged assets rooted next to this library.
+    def export(to:, source_root: SOURCE_ROOT)
+      destination = normalized_destination(to)
+      assets = packaged_assets(source_root)
+      planned = preflight(destination, assets)
+
+      exported = []
+      unchanged = []
+
+      planned.each do |asset|
+        target = asset.fetch(:target)
+        asset.fetch(:files).each do |file|
+          output = File.join(target, file.fetch(:relative))
+          if file.fetch(:unchanged)
+            unchanged << output
+            next
+          end
+
+          FileUtils.mkdir_p(File.dirname(output))
+          write_file(output, file.fetch(:content))
+          exported << output
+        end
+      end
+
+      {
+        destination: destination,
+        exported: exported.sort,
+        unchanged: unchanged.sort
+      }
+    end
+
+    def normalized_destination(to)
+      unless to.is_a?(String) && !to.strip.empty?
+        raise configuration_error("An explicit non-empty skill destination is required.", "missing_skills_destination")
+      end
+
+      File.expand_path(to)
+    end
+    private_class_method :normalized_destination
+
+    def packaged_assets(source_root)
+      root = File.expand_path(source_root)
+      unless File.directory?(root)
+        raise configuration_error("Packaged skills directory is missing: #{root}", "invalid_skills_package")
+      end
+
+      entries = Dir.children(root).sort
+      unless entries == SKILL_NAMES.sort
+        raise configuration_error("Packaged skills must contain exactly #{SKILL_NAMES.join(" and ")}.",
+                                  "invalid_skills_package")
+      end
+
+      SKILL_NAMES.map do |name|
+        skill_root = File.join(root, name)
+        reject_symlink_path!(skill_root, "skill asset")
+        unless File.directory?(skill_root)
+          raise configuration_error("Skill asset must be a directory: #{skill_root}", "invalid_skills_package")
+        end
+
+        files = Dir.glob(File.join(skill_root, "**", "*"), File::FNM_DOTMATCH).sort.filter_map do |path|
+          next if %w[. ..].include?(File.basename(path))
+
+          reject_symlink_path!(path, "skill asset")
+          stat = File.lstat(path)
+          next if stat.directory?
+          unless stat.file?
+            raise configuration_error("Skill asset must contain only regular files and directories: #{path}",
+                                      "invalid_skills_package")
+          end
+
+          relative = path.delete_prefix("#{skill_root}/")
+          { relative: relative, content: File.binread(path) }
+        end
+
+        unless files.any? { |file| file.fetch(:relative) == "SKILL.md" }
+          raise configuration_error("Skill asset is missing SKILL.md: #{skill_root}", "invalid_skills_package")
+        end
+
+        { name: name, files: files }
+      end
+    rescue Errno::ENOENT => e
+      raise configuration_error("Packaged skill asset is incomplete: #{e.message}", "invalid_skills_package")
+    end
+    private_class_method :packaged_assets
+
+    def preflight(destination, assets)
+      reject_symlink_path!(destination, "destination")
+      if File.exist?(destination) && !File.directory?(destination)
+        raise configuration_error("Skill destination must be a directory: #{destination}", "unsafe_skills_destination")
+      end
+
+      assets.map do |asset|
+        target = File.join(destination, asset.fetch(:name))
+        reject_symlink_path!(target, "destination")
+        if File.exist?(target) && !File.directory?(target)
+          raise configuration_error("Skill destination entry must be a directory: #{target}",
+                                    "unsafe_skills_destination")
+        end
+
+        unchanged = true
+        asset.fetch(:files).each do |file|
+          output = File.join(target, file.fetch(:relative))
+          reject_symlink_path!(output, "destination")
+          next unless File.exist?(output)
+
+          unless File.file?(output)
+            raise configuration_error("Skill destination file has an incompatible type: #{output}",
+                                      "unsafe_skills_destination")
+          end
+
+          unless File.binread(output) == file.fetch(:content)
+            raise configuration_error("Skill destination contains different content: #{output}",
+                                      "skills_destination_conflict")
+          end
+        end
+
+        if File.directory?(target)
+          Dir.glob(File.join(target, "**", "*"), File::FNM_DOTMATCH).each do |path|
+            next if %w[. ..].include?(File.basename(path))
+
+            reject_symlink_path!(path, "destination")
+          end
+        end
+
+        files = asset.fetch(:files).map do |file|
+          output = File.join(target, file.fetch(:relative))
+          unchanged = File.file?(output)
+          file.merge(unchanged: unchanged)
+        end
+        { target: target, files: files }
+      end
+    end
+    private_class_method :preflight
+
+    def reject_symlink_path!(path, description)
+      expanded = File.expand_path(path)
+      current = File::SEPARATOR
+      expanded.split(File::SEPARATOR).reject(&:empty?).each do |part|
+        current = File.join(current, part)
+        next unless File.exist?(current) || File.symlink?(current)
+
+        stat = File.lstat(current)
+        if stat.symlink?
+          raise configuration_error("Skill #{description} cannot include symlinks: #{current}",
+                                    "unsafe_skills_destination")
+        end
+        if current != expanded && !stat.directory?
+          raise configuration_error("Skill #{description} path has a non-directory parent: #{current}",
+                                    "unsafe_skills_destination")
+        end
+      end
+    rescue Errno::ENOENT
+      nil
+    end
+    private_class_method :reject_symlink_path!
+
+    def write_file(path, content)
+      directory = File.dirname(path)
+      Tempfile.create([".specproof-skill-", ".tmp"], directory, binmode: true) do |temporary|
+        temporary.write(content)
+        temporary.flush
+        File.rename(temporary.path, path)
+      end
+    end
+    private_class_method :write_file
+
+    def configuration_error(message, code)
+      ConfigurationError.new(message, code: code, path: nil, source: nil)
+    end
+    private_class_method :configuration_error
+  end
+end

data/lib/specproof/sources/rbs.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../../specproof"
+require_relative "rbs_projector"
+
+module SpecProof
+  module Sources
+    # Reads the deliberately small, explicit RBS subset used for scalar input facts.
+    module RBS
+      VERSION = "4.2.0"
+
+      class << self
+        def load(paths:, targets:, declarations: {})
+          canonical_paths = normalize_paths(paths)
+          targets = normalize_targets(targets)
+          rbs = load_dependency
+          verify_version!(rbs)
+
+          buffers = canonical_paths.map { |path| parse(path, rbs) }
+          environment = resolve_environment(buffers, rbs)
+          facts = targets.flat_map do |target|
+            RBSProjector.new(target, environment, canonical_paths, rbs,
+                             declaration: declarations[target]).facts
+          end
+          facts.sort_by { |fact| [fact.target, fact.input.to_s] }.freeze
+        end
+
+        private
+
+        def normalize_paths(paths)
+          values = Array(paths)
+          if values.empty?
+            raise ConfigurationError.new("provide at least one RBS signature file", code: "paths_required")
+          end
+
+          canonical = values.map do |entry|
+            input_path = nil
+            input_path = File.path(entry)
+            path = File.realpath(input_path)
+            unless File.file?(path)
+              raise ConfigurationError.new(
+                "RBS signature path is not a regular file: #{path}", code: "file_error", path: path
+              )
+            end
+            path
+          rescue Errno::ENOENT => e
+            raise ConfigurationError.new(e.message, code: "file_not_found",
+                                                    path: e.respond_to?(:path) ? e.path : input_path)
+          rescue SystemCallError => e
+            raise ConfigurationError.new(e.message, code: "file_error",
+                                                    path: e.respond_to?(:path) ? e.path : input_path)
+          rescue TypeError, ArgumentError => e
+            raise ConfigurationError.new(e.message, code: "file_error", path: input_path)
+          end
+          if canonical.uniq.length != canonical.length
+            raise ConfigurationError.new("RBS signature paths must be unique", code: "duplicate_path")
+          end
+
+          canonical.sort.freeze
+        end
+
+        def normalize_targets(targets)
+          values = Array(targets)
+          raise ConfigurationError.new("provide at least one RBS target", code: "targets_required") if values.empty?
+
+          values.each do |target|
+            next if valid_target?(target)
+
+            message = "target must use ClassName#instance_method or " \
+                      "ClassName.singleton_method syntax: #{target.inspect}"
+            raise ConfigurationError.new(message, code: "invalid_target")
+          end
+          if values.uniq.length != values.length
+            raise ConfigurationError.new("RBS targets must be unique", code: "duplicate_target")
+          end
+
+          values.sort.freeze
+        end
+
+        def valid_target?(target)
+          return false unless target.is_a?(String)
+
+          TargetName.parse(target)
+          true
+        rescue ConfigurationError
+          false
+        end
+
+        def load_dependency
+          require "rbs"
+          ::RBS
+        rescue LoadError => e
+          raise ConfigurationError.new("RBS support requires the optional rbs gem (4.2.0): #{e.message}",
+                                       code: "rbs_dependency_missing")
+        end
+
+        def verify_version!(rbs)
+          return if rbs::VERSION == VERSION
+
+          raise ConfigurationError.new("RBS #{VERSION} is required; found #{rbs::VERSION}",
+                                       code: "unsupported_rbs_version")
+        end
+
+        def parse(path, rbs)
+          content = File.read(path, encoding: "UTF-8")
+          unless content.valid_encoding?
+            raise ConfigurationError.new("RBS signature file must be valid UTF-8", code: "rbs_parse_error", path: path)
+          end
+
+          buffer = rbs::Buffer.new(name: Pathname(path), content: content)
+          buffer, directives, declarations = rbs::Parser.parse_signature(buffer)
+          [buffer, directives, declarations].freeze
+        rescue rbs::ParsingError => e
+          source = Source.new(path: path, line: e.location.start_line, kind: "rbs") if e.location
+          raise ConfigurationError.new(e.message, code: "rbs_parse_error", path: path, source: source)
+        rescue Errno::ENOENT, Errno::EACCES => e
+          raise ConfigurationError.new(e.message, code: "file_error", path: path)
+        end
+
+        def resolve_environment(buffers, rbs)
+          environment = rbs::Environment.from_loader(rbs::EnvironmentLoader.new)
+          buffers.each do |buffer, directives, declarations|
+            environment.add_source(rbs::Source::RBS.new(buffer, directives, declarations))
+          end
+          environment.resolve_type_names
+        rescue rbs::BaseError => e
+          location = e.respond_to?(:location) ? e.location : nil
+          buffer = location&.buffer
+          path = buffer.name.to_s if buffer
+          source = Source.new(path: path, line: location.start_line, kind: "rbs") if location && path
+          raise ConfigurationError.new(e.message, code: "rbs_parse_error", path: path, source: source)
+        end
+      end
+    end
+  end
+end

data/lib/specproof/sources/rbs_projector.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module SpecProof
+  module Sources
+    # Projects selected RBS methods into SpecProof's deliberately small scalar model.
+    class RBSProjector
+      def initialize(target, environment, paths, rbs, declaration: nil)
+        @target = target
+        @environment = environment
+        @paths = paths
+        @rbs = rbs
+        @declaration = declaration
+        @exclusions = declaration&.exclusions || {}
+      end
+
+      def facts
+        owner, method_name, kind = TargetName.parse(@target)
+        declarations = owner_declarations(owner, @environment, @paths)
+        method, visibility = select_method(@target, method_name.to_s, kind, declarations, @rbs)
+        validate_method!(@target, method, visibility, generic_owner?(owner, @environment), kind)
+        input_facts(@target, method, @rbs, @exclusions)
+      end
+
+      private
+
+      attr_reader :rbs
+
+      def owner_declarations(owner, environment, paths)
+        entries = environment.class_decls.select { |name, _entry| normalize_type_name(name) == owner }
+        entries.flat_map do |_name, entry|
+          owner_declarations = entry.each_decl.select do |declaration|
+            declaration.is_a?(rbs::AST::Declarations::Class) || declaration.is_a?(rbs::AST::Declarations::Module)
+          end
+          owner_declarations.select do |declaration|
+            supplied_declaration?(declaration, paths)
+          end
+        end
+      end
+
+      def generic_owner?(owner, environment)
+        environment.class_decls.any? do |name, entry|
+          normalize_type_name(name) == owner && entry.each_decl.any? do |declaration|
+            (declaration.is_a?(rbs::AST::Declarations::Class) ||
+              declaration.is_a?(rbs::AST::Declarations::Module)) && !declaration.type_params.empty?
+          end
+        end
+      end
+
+      def select_method(target, method_name, kind, declarations, rbs)
+        matches = matching_members(method_name, kind, declarations, rbs)
+        module_method = matching_module_method(method_name, declarations, rbs) if kind == :instance
+        unsupported_signature!(target, module_method, "module owners are not supported") if module_method
+        if matches[:unsupported_kind]
+          unsupported_signature!(target, matches[:unsupported_kind],
+                                 "singleton_instance method signatures are not supported")
+        end
+
+        if matches[:attribute]
+          unsupported_signature!(target, matches[:attribute], "generated attribute methods are not supported")
+        end
+        alias_member = matches[:"#{kind}_alias"]
+        unsupported_signature!(target, alias_member, "method aliases are not supported") if alias_member
+        methods = matches[kind]
+        if methods.empty?
+          if kind == :instance && !matches[:singleton].empty?
+            unsupported_signature!(target, matches[:singleton].first.first,
+                                   "singleton methods are not supported for instance targets")
+          end
+          raise ConfigurationError.new("RBS target was not found: #{target}", code: "rbs_target_not_found")
+        end
+        if methods.length > 1
+          unsupported_signature!(target, methods.first.first,
+                                 "method is declared more than once across class reopenings")
+        end
+
+        methods.first
+      end
+
+      def matching_members(method_name, kind, declarations, rbs)
+        matches = { instance: [], singleton: [], instance_alias: nil, singleton_alias: nil, attribute: nil,
+                    unsupported_kind: nil }
+        declarations.each do |declaration|
+          visibility = :public
+          declaration.members.each do |member|
+            case member
+            when rbs::AST::Members::Public then visibility = :public
+            when rbs::AST::Members::Private then visibility = :private
+            when rbs::AST::Members::MethodDefinition
+              add_matching_method(matches, member, visibility, method_name)
+            when rbs::AST::Members::Alias
+              if member.new_name.to_s == method_name
+                key = member.instance? ? :instance_alias : :singleton_alias
+                matches[key] = member
+              end
+            when rbs::AST::Members::Attribute
+              if member.kind == :singleton_instance && generated_attribute?(member, method_name, rbs)
+                matches[:unsupported_kind] = member
+              elsif member.kind == kind && generated_attribute?(member, method_name, rbs)
+                matches[:attribute] = member
+              end
+            end
+          end
+        end
+        matches
+      end
+
+      def add_matching_method(matches, member, visibility, method_name)
+        return unless member.name.to_s == method_name
+
+        case member.kind
+        when :instance then matches[:instance] << [member, visibility]
+        when :singleton then matches[:singleton] << [member, visibility]
+        when :singleton_instance then matches[:unsupported_kind] = member
+        end
+      end
+
+      def generated_attribute?(member, method_name, rbs)
+        reader = member.name.to_s == method_name && !member.is_a?(rbs::AST::Members::AttrWriter)
+        writer = method_name == "#{member.name}=" && !member.is_a?(rbs::AST::Members::AttrReader)
+        %i[instance singleton].include?(member.kind) && (reader || writer)
+      end
+
+      def matching_module_method(method_name, declarations, rbs)
+        declarations.grep(rbs::AST::Declarations::Module).lazy.flat_map(&:members).find do |member|
+          member.respond_to?(:name) && member.name.to_s == method_name
+        end
+      end
+
+      def validate_method!(target, method, visibility, generic_owner, kind)
+        method_kind = kind == :singleton ? "singleton" : "instance"
+        if (method.visibility || visibility) != :public
+          unsupported_signature!(target, method, "only directly declared public #{method_kind} methods are supported")
+        end
+        expected_kind = kind == :singleton ? :singleton : :instance
+        unsupported_signature!(target, method, "unsupported method kind") unless method.kind == expected_kind
+        if method.overloading? || method.overloads.length != 1
+          unsupported_signature!(target, method, "overloaded method signatures are not supported")
+        end
+        if method.overloads.any? { |overload| !overload.annotations.empty? }
+          unsupported_signature!(target, method, "method type extension annotations are not supported")
+        end
+        unsupported_signature!(target, method, "generic owner classes are not supported") if generic_owner
+
+        method_type = method.overloads.fetch(0).method_type
+        unsupported_signature!(target, method, "generic methods are not supported") if method_type.type_params.any?
+        function = method_type.type
+        return unless method_type.block || function.forwarding? || function.rest_positionals || function.rest_keywords
+
+        unsupported_signature!(target, method, "blocks, rest arguments, and forwarding are not supported")
+      end
+
+      def input_facts(target, method, rbs, exclusions)
+        function = method.overloads.fetch(0).method_type.type
+        params = function.required_positionals + function.optional_positionals + function.trailing_positionals
+        params.each do |param|
+          unless param.name && !param.name.to_s.empty?
+            unsupported_signature!(target, method, "every positional parameter must have an explicit name")
+          end
+        end
+        keyword_params = function.required_keywords.merge(function.optional_keywords)
+        duplicate_keywords = function.required_keywords.keys & function.optional_keywords.keys
+        unless duplicate_keywords.empty?
+          unsupported_signature!(target, method, "keyword parameter names must be unique")
+        end
+        names = params.map { |param| param.name.to_sym } + keyword_params.keys.map(&:to_sym)
+        unsupported_signature!(target, method, "target method must have at least one input") if names.empty?
+        unsupported_signature!(target, method, "parameter names must be unique") if names.uniq.length != names.length
+
+        named_params = params.map { |param| [param.name.to_sym, param] } +
+                       keyword_params.map { |name, param| [name.to_sym, param] }
+        validate_exclusions!(target, exclusions, names)
+        validate_declared_names!(target, method, @declaration, names)
+        named_params.map do |name, param|
+          next if exclusions.key?(name)
+
+          constraint = map_type(param.type, target, name, rbs)
+          InputTypeFact.new(target: target, input: name, constraint: constraint,
+                            source: source_for(param))
+        end.compact
+      end
+
+      def validate_exclusions!(target, exclusions, names)
+        unknown = exclusions.keys - names
+        return if unknown.empty?
+
+        name = unknown.min_by(&:to_s)
+        exclusion = exclusions.fetch(name)
+        source = exclusion.respond_to?(:source) ? exclusion.source : nil
+        raise ConfigurationError.new("excluded RBS input #{name.inspect} is not declared by RBS for #{target}",
+                                     code: "rbs_input_mismatch", source: source, path: source&.path)
+      end
+
+      def validate_declared_names!(target, method, declaration, names)
+        return unless declaration
+
+        unknown = declaration.inputs.keys - names
+        return if unknown.empty?
+
+        name = unknown.min_by(&:to_s)
+        input = declaration.inputs.fetch(name)
+        source = input.source
+        rbs_source = source_for(method)
+        location = rbs_source ? " at #{rbs_source.path}:#{rbs_source.line}" : ""
+        raise ConfigurationError.new("DSL input #{name.inspect} is not declared by RBS for #{target}#{location}",
+                                     code: "rbs_input_mismatch", source: source, path: source&.path)
+      end
+
+      def map_type(type, target, input, rbs)
+        case type
+        when rbs::Types::Union
+          TypeConstraints.union(type.types.map { |alternative| map_type(alternative, target, input, rbs) })
+        when rbs::Types::Optional
+          TypeConstraints.union([
+                                  map_type(type.type, target, input, rbs),
+                                  ScalarTypeConstraint.new(integer_any: false, values: [nil])
+                                ])
+        when rbs::Types::Bases::Bool
+          ScalarTypeConstraint.new(integer_any: false, values: [true, false])
+        when rbs::Types::Bases::Nil
+          ScalarTypeConstraint.new(integer_any: false, values: [nil])
+        when rbs::Types::Literal
+          value = type.literal
+          supported = value.nil? || value.equal?(true) || value.equal?(false) ||
+                      value.is_a?(Integer) || value.is_a?(Symbol) || Domains.supported_string?(value)
+          unsupported_type!(target, input, type) unless supported
+          ScalarTypeConstraint.new(integer_any: false, values: [value])
+        when rbs::Types::ClassInstance
+          if builtin_integer?(type) && type.args.empty?
+            ScalarTypeConstraint.new(integer_any: true, values: [])
+          else
+            unsupported_type!(target, input, type)
+          end
+        else
+          unsupported_type!(target, input, type)
+        end
+      end
+
+      def builtin_integer?(type)
+        name = type.name
+        name.name == :Integer && name.namespace.absolute? && name.namespace.path.empty?
+      end
+
+      def unsupported_type!(target, input, type)
+        raise ConfigurationError.new("unsupported RBS input type #{type}: #{target} / input #{input}",
+                                     code: "unsupported_rbs_type", source: source_for(type))
+      end
+
+      def unsupported_signature!(target, method, reason)
+        raise ConfigurationError.new("#{reason}: #{target}", code: "unsupported_rbs_signature",
+                                                             source: source_for(method))
+      end
+
+      def source_for(node)
+        location = node.respond_to?(:location) ? node.location : node
+        Source.new(path: location.buffer.name.to_s, line: location.start_line, kind: "rbs")
+      end
+
+      def supplied_declaration?(declaration, paths)
+        paths.include?(File.expand_path(declaration.location.buffer.name.to_s))
+      end
+
+      def normalize_type_name(name)
+        name.to_s.sub(/\A::/, "")
+      end
+    end
+    private_constant :RBSProjector
+  end
+end