spurline-core 0.3.0

data/lib/spurline/audit/secret_filter.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+require "set"
+
+module Spurline
+  module Audit
+    # Stateless redaction utility for tool-call argument payloads.
+    module SecretFilter
+      SENSITIVE_PATTERNS = %w[
+        key token secret password credential passphrase
+        api_key api_secret access_token refresh_token
+        auth bearer jwt private_key
+      ].freeze
+
+      class << self
+        # Returns a filtered copy of arguments with sensitive values redacted.
+        # Never mutates the original object.
+        def filter(arguments, tool_name:, registry: nil)
+          return nil if arguments.nil?
+
+          sensitive_fields = sensitive_parameters_for(tool_name, registry)
+          filter_value(arguments, sensitive_fields)
+        end
+
+        # Returns true when any sensitive key is present in arguments.
+        def contains_secrets?(arguments, tool_name:, registry: nil)
+          return false if arguments.nil?
+
+          sensitive_fields = sensitive_parameters_for(tool_name, registry)
+          contains_secrets_in_value?(arguments, sensitive_fields)
+        end
+
+        private
+
+        def filter_value(value, sensitive_fields)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), out|
+              key_name = key.to_s
+              if sensitive_key?(key_name, sensitive_fields)
+                out[key] = redacted_placeholder(key_name)
+              else
+                out[key] = filter_value(nested, sensitive_fields)
+              end
+            end
+          when Array
+            value.map { |nested| filter_value(nested, sensitive_fields) }
+          else
+            value
+          end
+        end
+
+        def contains_secrets_in_value?(value, sensitive_fields)
+          case value
+          when Hash
+            value.any? do |key, nested|
+              sensitive_key?(key.to_s, sensitive_fields) ||
+                contains_secrets_in_value?(nested, sensitive_fields)
+            end
+          when Array
+            value.any? { |nested| contains_secrets_in_value?(nested, sensitive_fields) }
+          else
+            false
+          end
+        end
+
+        def sensitive_key?(name, sensitive_fields)
+          normalized = normalize_key(name)
+          return true if sensitive_fields.include?(normalized)
+
+          tokens = normalized.split("_")
+          SENSITIVE_PATTERNS.any? do |pattern|
+            pattern_tokens = pattern.split("_")
+            if pattern_tokens.length == 1
+              tokens.include?(pattern)
+            else
+              tokens.each_cons(pattern_tokens.length).any? { |slice| slice == pattern_tokens }
+            end
+          end
+        end
+
+        def sensitive_parameters_for(tool_name, registry)
+          tool = resolve_tool(tool_name, registry)
+          return Set.new unless tool&.respond_to?(:sensitive_parameters)
+
+          raw = tool.sensitive_parameters || Set.new
+          Set.new(raw.map { |name| normalize_key(name) })
+        rescue StandardError
+          Set.new
+        end
+
+        def resolve_tool(tool_name, registry)
+          return nil unless registry && tool_name
+
+          if registry.respond_to?(:registered?) && !registry.registered?(tool_name)
+            return nil
+          end
+
+          tool = registry.fetch(tool_name)
+          return tool.class unless tool.is_a?(Class)
+
+          tool
+        rescue StandardError
+          nil
+        end
+
+        def normalize_key(name)
+          name.to_s
+            .gsub(/([a-z0-9])([A-Z])/, '\1_\2')
+            .strip
+            .downcase
+            .gsub(/[^a-z0-9]+/, "_")
+            .gsub(/\A_+|_+\z/, "")
+        end
+
+        def redacted_placeholder(field_name)
+          "[REDACTED:#{field_name}]"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/base.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Spurline
+  # Framework internals. Developers never interact with this class directly.
+  # Includes all DSL modules and provides registry access.
+  #
+  # Default adapters are registered here so `use_model :claude_sonnet` works
+  # out of the box without manual registration.
+  class Base
+    include Spurline::DSL::Model
+    include Spurline::DSL::Persona
+    include Spurline::DSL::Tools
+    include Spurline::DSL::Memory
+    include Spurline::DSL::Guardrails
+    include Spurline::DSL::Hooks
+    include Spurline::DSL::SuspendUntil
+
+    # Default model-to-adapter mapping.
+    DEFAULT_ADAPTERS = {
+      claude_sonnet: { adapter: Spurline::Adapters::Claude, model: "claude-sonnet-4-20250514" },
+      claude_opus: { adapter: Spurline::Adapters::Claude, model: "claude-opus-4-20250514" },
+      claude_haiku: { adapter: Spurline::Adapters::Claude, model: "claude-haiku-4-5-20251001" },
+      openai_gpt4o: { adapter: Spurline::Adapters::OpenAI, model: "gpt-4o" },
+      openai_gpt4o_mini: { adapter: Spurline::Adapters::OpenAI, model: "gpt-4o-mini" },
+      openai_o3_mini: { adapter: Spurline::Adapters::OpenAI, model: "o3-mini" },
+      stub: { adapter: Spurline::Adapters::StubAdapter },
+    }.freeze
+
+    class << self
+      def deterministic_sequence(*tool_names)
+        if tool_names.empty?
+          raise Spurline::ConfigurationError,
+            "deterministic_sequence requires at least one tool name."
+        end
+
+        @deterministic_sequence_config = tool_names.map do |item|
+          item.is_a?(Hash) ? item : item.to_sym
+        end
+      end
+
+      def deterministic_sequence_config
+        own = instance_variable_defined?(:@deterministic_sequence_config) ? @deterministic_sequence_config : nil
+        if own
+          own
+        elsif superclass.respond_to?(:deterministic_sequence_config)
+          superclass.deterministic_sequence_config
+        else
+          nil
+        end
+      end
+
+      def tool_registry
+        @tool_registry ||= Spurline::Tools::Registry.new
+        Spurline::Spur.flush_pending_registrations!(@tool_registry)
+        @tool_registry
+      end
+
+      def toolkit_registry
+        @toolkit_registry ||= Spurline::Tools::ToolkitRegistry.new(tool_registry: tool_registry)
+      end
+
+      def adapter_registry
+        @adapter_registry ||= begin
+          registry = Spurline::Adapters::Registry.new
+          register_default_adapters!(registry)
+          registry
+        end
+        Spurline::Spur.flush_pending_adapter_registrations!(@adapter_registry)
+        @adapter_registry
+      end
+
+      def session_store
+        @session_store ||= resolve_session_store(Spurline.config.session_store)
+      end
+
+      def session_store=(store)
+        @session_store = resolve_session_store(store)
+      end
+
+      def inherited(subclass)
+        super
+        # Share registries with subclasses
+        subclass.instance_variable_set(:@tool_registry, tool_registry)
+        subclass.instance_variable_set(:@toolkit_registry, toolkit_registry)
+        subclass.instance_variable_set(:@adapter_registry, adapter_registry)
+        subclass.instance_variable_set(:@session_store, @session_store)
+        if instance_variable_defined?(:@deterministic_sequence_config)
+          subclass.instance_variable_set(
+            :@deterministic_sequence_config,
+            @deterministic_sequence_config&.dup
+          )
+        end
+      end
+
+      private
+
+      def resolve_session_store(store)
+        case store
+        when nil, :memory
+          Spurline::Session::Store::Memory.new
+        when :sqlite
+          Spurline::Session::Store::SQLite.new(path: Spurline.config.session_store_path)
+        when :postgres
+          url = Spurline.config.session_store_postgres_url
+          unless url && !url.strip.empty?
+            raise Spurline::ConfigurationError,
+              "session_store_postgres_url must be set when using :postgres session store. " \
+              "Set it via Spurline.configure { |c| c.session_store_postgres_url = \"postgresql://...\" }."
+          end
+          Spurline::Session::Store::Postgres.new(url: url)
+        else
+          return store if store.respond_to?(:save) &&
+            store.respond_to?(:load) &&
+            store.respond_to?(:delete) &&
+            store.respond_to?(:exists?)
+
+          raise Spurline::ConfigurationError,
+            "Invalid session_store: #{store.inspect}. " \
+            "Use :memory, :sqlite, :postgres, or an object implementing save/load/delete/exists?."
+        end
+      end
+
+      def register_default_adapters!(registry)
+        DEFAULT_ADAPTERS.each do |name, config|
+          registry.register(name, config[:adapter])
+        end
+      end
+    end
+  end
+end

data/lib/spurline/cartographer/CLAUDE.md

@@ -0,0 +1,12 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3734 | 10:05 PM | 🔵 | Cartographer repository analysis system verified as complete and production-ready | ~1142 |
+| #3733 | 10:04 PM | 🔵 | Cartographer repository analysis system verified complete and production-ready with all six analyzers | ~1347 |
+</claude-mem-context>

data/lib/spurline/cartographer/analyzer.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Cartographer
+    class Analyzer
+      attr_reader :repo_path, :findings
+
+      def initialize(repo_path:)
+        @repo_path = File.expand_path(repo_path)
+        @findings = {}
+      end
+
+      # Subclasses implement this. Returns a hash merged into RepoProfile.
+      def analyze
+        raise NotImplementedError, "#{self.class}#analyze must return a findings hash"
+      end
+
+      # Per-layer confidence score (0.0-1.0).
+      def confidence
+        1.0
+      end
+
+      private
+
+      def file_exists?(relative_path)
+        return false if excluded_relative_path?(relative_path)
+
+        File.exist?(File.join(repo_path, relative_path))
+      end
+
+      def read_file(relative_path)
+        return nil if excluded_relative_path?(relative_path)
+
+        path = File.join(repo_path, relative_path)
+        return nil unless File.file?(path)
+
+        File.read(path)
+      end
+
+      def glob(pattern)
+        Dir.glob(File.join(repo_path, pattern)).reject do |path|
+          excluded_relative_path?(relative_path(path))
+        end
+      end
+
+      def relative_path(path)
+        path.to_s.sub(%r{\A#{Regexp.escape(repo_path)}/?}, "")
+      end
+
+      def excluded_relative_path?(relative_path)
+        normalized = relative_path.to_s.sub(%r{\A\./}, "").sub(%r{\A/}, "")
+        return false if normalized.empty?
+
+        excluded_patterns.any? do |pattern|
+          token = pattern.to_s.sub(%r{\A\./}, "").sub(%r{\A/}, "").sub(%r{/$}, "")
+          if token.include?("/")
+            normalized == token || normalized.start_with?("#{token}/")
+          else
+            normalized.split("/").include?(token)
+          end
+        end
+      end
+
+      def excluded_patterns
+        Array(Spurline.config.cartographer_exclude_patterns)
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/spurline/cartographer/analyzers/CLAUDE.md

@@ -0,0 +1,12 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3734 | 10:05 PM | 🔵 | Cartographer repository analysis system verified as complete and production-ready | ~1142 |
+| #3733 | 10:04 PM | 🔵 | Cartographer repository analysis system verified complete and production-ready with all six analyzers | ~1347 |
+</claude-mem-context>

data/lib/spurline/cartographer/analyzers/ci_config.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Spurline
+  module Cartographer
+    module Analyzers
+      class CIConfig < Analyzer
+        def analyze
+          providers = []
+          commands = []
+
+          github_workflows = glob(".github/workflows/*.{yml,yaml}")
+          unless github_workflows.empty?
+            providers << :github_actions
+            github_workflows.each do |workflow_path|
+              commands.concat(extract_github_commands(workflow_path))
+            end
+          end
+
+          circle_config_path = File.join(repo_path, ".circleci", "config.yml")
+          if File.file?(circle_config_path)
+            providers << :circleci
+            commands.concat(extract_circleci_commands(circle_config_path))
+          end
+
+          gitlab_path = File.join(repo_path, ".gitlab-ci.yml")
+          if File.file?(gitlab_path)
+            providers << :gitlab_ci
+            commands.concat(extract_gitlab_commands(gitlab_path))
+          end
+
+          jenkinsfile_path = File.join(repo_path, "Jenkinsfile")
+          if File.file?(jenkinsfile_path)
+            providers << :jenkins
+            commands.concat(extract_jenkins_commands(jenkinsfile_path))
+          end
+
+          ci_hash = {}
+          ci_hash[:provider] = providers.first if providers.any?
+          ci_hash[:providers] = providers if providers.any?
+          ci_hash[:test_command] = pick_command(commands) { |cmd| test_command?(cmd) }
+          ci_hash[:lint_command] = pick_command(commands) { |cmd| lint_command?(cmd) }
+          ci_hash[:deploy_command] = pick_command(commands) { |cmd| deploy_command?(cmd) }
+          ci_hash.compact!
+
+          @findings = {
+            ci: ci_hash,
+            metadata: {
+              ci_config: {
+                command_count: commands.length,
+              },
+            },
+          }
+        end
+
+        def confidence
+          providers = findings.dig(:ci, :providers)
+          providers && !providers.empty? ? 1.0 : 0.5
+        end
+
+        private
+
+        def extract_github_commands(path)
+          payload = safe_yaml_load(path)
+          return [] unless payload.is_a?(Hash)
+
+          jobs = payload["jobs"]
+          return [] unless jobs.is_a?(Hash)
+
+          jobs.values.flat_map do |job|
+            next [] unless job.is_a?(Hash)
+
+            steps = job["steps"]
+            next [] unless steps.is_a?(Array)
+
+            steps.filter_map do |step|
+              next unless step.is_a?(Hash)
+
+              normalize_command(step["run"])
+            end
+          end
+        end
+
+        def extract_circleci_commands(path)
+          payload = safe_yaml_load(path)
+          return [] unless payload.is_a?(Hash)
+
+          jobs = payload["jobs"]
+          return [] unless jobs.is_a?(Hash)
+
+          jobs.values.flat_map do |job|
+            next [] unless job.is_a?(Hash)
+
+            steps = job["steps"]
+            next [] unless steps.is_a?(Array)
+
+            steps.filter_map do |step|
+              case step
+              when String
+                nil
+              when Hash
+                run = step["run"] || step[:run]
+                if run.is_a?(Hash)
+                  normalize_command(run["command"] || run[:command])
+                else
+                  normalize_command(run)
+                end
+              end
+            end
+          end
+        end
+
+        def extract_gitlab_commands(path)
+          payload = safe_yaml_load(path)
+          return [] unless payload.is_a?(Hash)
+
+          payload.values.flat_map do |job|
+            next [] unless job.is_a?(Hash)
+
+            scripts = job["script"] || job[:script]
+            case scripts
+            when Array
+              scripts.filter_map { |script| normalize_command(script) }
+            when String
+              [normalize_command(scripts)].compact
+            else
+              []
+            end
+          end
+        end
+
+        def extract_jenkins_commands(path)
+          content = File.read(path)
+          commands = content.scan(/\bsh\s+["']([^"']+)["']/).flatten
+          commands.filter_map { |command| normalize_command(command) }
+        rescue Errno::ENOENT
+          []
+        end
+
+        def safe_yaml_load(path)
+          YAML.safe_load(File.read(path), aliases: true)
+        rescue Psych::SyntaxError, Errno::ENOENT
+          nil
+        end
+
+        def pick_command(commands)
+          commands.find { |command| yield(command) }
+        end
+
+        def normalize_command(value)
+          return nil unless value
+
+          value.to_s.strip.gsub(/\s+/, " ")
+        end
+
+        def test_command?(command)
+          command.match?(/\b(rspec|minitest|pytest|go test|cargo test|npm test|yarn test|pnpm test|rake test|bundle exec rspec|bundle exec rake spec)\b/i)
+        end
+
+        def lint_command?(command)
+          command.match?(/\b(rubocop|eslint|prettier|standardrb|lint)\b/i)
+        end
+
+        def deploy_command?(command)
+          command.match?(/\b(deploy|kubectl|helm|terraform apply|cap\s)\b/i)
+        end
+      end
+    end
+  end
+end

data/lib/spurline/cartographer/analyzers/dotfiles.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Spurline
+  module Cartographer
+    module Analyzers
+      class Dotfiles < Analyzer
+        RUBOCOP_FILES = [".rubocop.yml"].freeze
+        ESLINT_FILES = %w[
+          .eslintrc
+          .eslintrc.json
+          .eslintrc.yml
+          .eslintrc.yaml
+          .eslintrc.js
+        ].freeze
+        PRETTIER_FILES = %w[
+          .prettierrc
+          .prettierrc.json
+          .prettierrc.yml
+          .prettierrc.yaml
+        ].freeze
+
+        def analyze
+          style_configs = {}
+          env_vars = parse_env_example
+
+          rubocop_file = RUBOCOP_FILES.find { |path| file_exists?(path) }
+          style_configs[:rubocop] = parse_yaml_keys(rubocop_file) if rubocop_file
+
+          eslint_file = ESLINT_FILES.find { |path| file_exists?(path) }
+          style_configs[:eslint] = parse_config_keys(eslint_file) if eslint_file
+
+          prettier_file = PRETTIER_FILES.find { |path| file_exists?(path) }
+          style_configs[:prettier] = parse_config_keys(prettier_file) if prettier_file
+
+          style_configs[:editorconfig] = parse_editorconfig_keys if file_exists?(".editorconfig")
+
+          runtime_versions = {}
+          nvmrc = read_file(".nvmrc")&.strip
+          runtime_versions[:node] = nvmrc if nvmrc && !nvmrc.empty?
+          runtime_versions.merge!(parse_tool_versions)
+
+          @findings = {
+            environment_vars_required: env_vars,
+            metadata: {
+              dotfiles: {
+                style_configs: style_configs,
+                runtime_versions: runtime_versions,
+              },
+            },
+          }
+        end
+
+        def confidence
+          has_dotfiles = findings.dig(:metadata, :dotfiles, :style_configs)&.any?
+          has_dotfiles ? 0.9 : 0.6
+        end
+
+        private
+
+        def parse_env_example
+          content = read_file(".env.example")
+          return [] unless content
+
+          content.each_line.filter_map do |line|
+            match = line.match(/^\s*([A-Z][A-Z0-9_]*)\s*=/)
+            match&.captures&.first
+          end.uniq.sort
+        end
+
+        def parse_editorconfig_keys
+          content = read_file(".editorconfig")
+          return [] unless content
+
+          content.each_line.filter_map do |line|
+            stripped = line.strip
+            next if stripped.empty? || stripped.start_with?("#", ";", "[")
+
+            stripped.split("=").first&.strip
+          end.uniq.sort
+        end
+
+        def parse_tool_versions
+          content = read_file(".tool-versions")
+          return {} unless content
+
+          content.each_line.each_with_object({}) do |line, hash|
+            stripped = line.strip
+            next if stripped.empty? || stripped.start_with?("#")
+
+            tool, version = stripped.split(/\s+/, 2)
+            next unless tool && version
+
+            hash[tool.to_sym] = version.strip
+          end
+        end
+
+        def parse_config_keys(relative_path)
+          return [] unless relative_path
+
+          if relative_path.end_with?(".json") || relative_path == ".eslintrc" || relative_path == ".prettierrc"
+            parse_json_keys(relative_path)
+          elsif relative_path.end_with?(".yml") || relative_path.end_with?(".yaml")
+            parse_yaml_keys(relative_path)
+          else
+            ["config_present"]
+          end
+        end
+
+        def parse_yaml_keys(relative_path)
+          return [] unless relative_path
+
+          payload = YAML.safe_load(read_file(relative_path), aliases: true)
+          return [] unless payload.is_a?(Hash)
+
+          payload.keys.map(&:to_s).sort
+        rescue Psych::SyntaxError, NoMethodError
+          []
+        end
+
+        def parse_json_keys(relative_path)
+          payload = JSON.parse(read_file(relative_path))
+          return [] unless payload.is_a?(Hash)
+
+          payload.keys.map(&:to_s).sort
+        rescue JSON::ParserError, NoMethodError
+          []
+        end
+      end
+    end
+  end
+end