ace-lint 0.25.0

data/lib/ace/lint/atoms/base_runner.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Ace
+  module Lint
+    module Atoms
+      # Base class for Ruby linter runners
+      # Provides shared parsing logic for RuboCop-style JSON output
+      class BaseRunner
+        # Thread-safe availability cache (shared across all subclasses)
+        @availability_mutex = Mutex.new
+        @availability_cache = {}
+
+        class << self
+          # Check if the linter is available (cached per process, thread-safe)
+          # @return [Boolean] True if linter command is available
+          def available?
+            BaseRunner.instance_variable_get(:@availability_mutex).synchronize do
+              cache = BaseRunner.instance_variable_get(:@availability_cache)
+              cmd = command_name
+              cache[cmd] ||= system_has_command?(cmd)
+            end
+          end
+
+          # Reset availability cache for this linter (for testing purposes)
+          # @internal
+          def reset_availability_cache!
+            BaseRunner.instance_variable_get(:@availability_mutex).synchronize do
+              cache = BaseRunner.instance_variable_get(:@availability_cache)
+              cache.delete(command_name)
+            end
+          end
+
+          # Command name to check for availability (subclass override)
+          # @return [String] Command name
+          def command_name
+            raise NotImplementedError, "Subclass must implement command_name"
+          end
+
+          # Execute the linter command
+          # Subclasses must implement: tool_name, build_command, unavailable_result
+          # @param file_paths [String, Array<String>] Path(s) to lint
+          # @param fix [Boolean] Apply autofix
+          # @param config_path [String, nil] Explicit config path
+          # @return [Hash] Result with :success, :errors, :warnings
+          def run(file_paths, fix: false, config_path: nil)
+            paths = Array(file_paths)
+            return unavailable_result unless available?
+
+            cmd = build_command(paths, fix: fix, config_path: config_path)
+            stdout, stderr, status = Open3.capture3(*cmd)
+
+            if status.success?
+              parse_success_output(stdout)
+            else
+              parse_error_output(stdout, stderr, exit_status: status.exitstatus)
+            end
+          rescue => e
+            {
+              success: false,
+              errors: [{message: "#{tool_name} execution failed for #{Array(file_paths).join(", ")}: #{e.message}"}],
+              warnings: []
+            }
+          end
+
+          # Parse successful output (no issues)
+          # @param stdout [String] Linter output
+          # @return [Hash] Parsed result
+          def parse_success_output(stdout)
+            if stdout.strip.empty? || stdout.include?("no offenses")
+              return {success: true, errors: [], warnings: []}
+            end
+
+            parse_json_output(stdout)
+          rescue JSON::ParserError
+            {success: true, errors: [], warnings: []}
+          end
+
+          # Parse error output (issues found)
+          # @param stdout [String] Linter stdout
+          # @param stderr [String] Linter stderr
+          # @param exit_status [Integer] Process exit status
+          # @return [Hash] Parsed result
+          def parse_error_output(stdout, stderr, exit_status:)
+            unless stdout.strip.empty?
+              begin
+                return parse_json_output(stdout, exit_status: exit_status)
+              rescue JSON::ParserError
+                return parse_text_output(stderr, exit_status: exit_status)
+              end
+            end
+
+            parse_text_output(stderr, exit_status: exit_status)
+          end
+
+          # Parse JSON output from linter (RuboCop-style format)
+          # @param output [String] JSON string
+          # @param exit_status [Integer, nil] Process exit status
+          # @return [Hash] Parsed result
+          # @raise [JSON::ParserError] if output is not valid JSON
+          def parse_json_output(output, exit_status: nil)
+            data = JSON.parse(output)
+            errors = []
+            warnings = []
+
+            # RuboCop JSON format: {files: [{path, offenses: [...]}]}
+            if data.is_a?(Hash) && data.key?("files")
+              data["files"].each do |file_data|
+                file_path = file_data["path"] || "unknown"
+                offenses = file_data["offenses"] || []
+
+                offenses.each do |offense|
+                  item = build_offense_item(offense, file_path)
+                  if offense["severity"] == "error" || offense["severity"] == "fatal"
+                    errors << item
+                  else
+                    warnings << item
+                  end
+                end
+              end
+            # Fallback: direct array format
+            elsif data.is_a?(Array)
+              data.each do |offense|
+                item = build_offense_item(offense)
+                if offense["severity"] == "error" || offense["severity"] == "fatal"
+                  errors << item
+                else
+                  warnings << item
+                end
+              end
+            end
+
+            success = exit_status ? exit_status.zero? : errors.empty?
+
+            {
+              success: success,
+              errors: errors,
+              warnings: warnings
+            }
+          end
+
+          # Parse text output (fallback for non-JSON output)
+          # @param output [String] Text output
+          # @param exit_status [Integer, nil] Process exit status
+          # @return [Hash] Parsed result
+          def parse_text_output(output, exit_status: nil)
+            errors = []
+            warnings = []
+
+            output.each_line do |line|
+              # Format: file:line:column: severity: message
+              next unless line.match?(/^.+:\d+:\d+:/)
+
+              parts = line.split(":", 5)
+              next if parts.size < 5
+
+              item = {
+                file: parts[0],
+                line: parts[1].to_i,
+                column: parts[2].to_i,
+                message: parts[4].strip
+              }
+
+              if error_severity?(parts[3], line)
+                errors << item
+              else
+                warnings << item
+              end
+            end
+
+            success = exit_status ? exit_status.zero? : errors.empty?
+
+            # Add fallback error if non-zero exit but no offenses parsed
+            if !success && errors.empty? && warnings.empty? && !output.strip.empty?
+              errors << {message: "#{tool_name} failed: #{output.strip.lines.first&.strip || output.strip}"}
+            end
+
+            {
+              success: success,
+              errors: errors,
+              warnings: warnings
+            }
+          end
+
+          # Build offense item from linter offense
+          # @param offense [Hash] Offense data
+          # @param file_path [String] File path
+          # @return [Hash] Offense item
+          def build_offense_item(offense, file_path = nil)
+            path = file_path || offense.dig("location", "path") || "unknown"
+            location = offense["location"] || {}
+
+            {
+              file: path,
+              line: location["line"] || 0,
+              column: location["column"] || 0,
+              message: "#{offense["cop_name"]}: #{offense["message"]}"
+            }
+          end
+
+          protected
+
+          # Check if a command is available on the system
+          # @param cmd [String] Command name
+          # @return [Boolean] True if command exists
+          def system_has_command?(cmd)
+            # Cross-platform: use system with redirect to null
+            system("#{cmd} --version > /dev/null 2>&1")
+          end
+
+          # Check if severity indicates an error
+          # @param severity_field [String] The severity field from text output
+          # @param line [String] Full line for context
+          # @return [Boolean] True if error severity
+          def error_severity?(severity_field, line)
+            severity = severity_field.strip.upcase
+            # RuboCop: E/F = error, C/W = warning
+            severity == "E" || severity == "F" || line.include?("error") || line.include?("Error")
+          end
+
+          # Subclass interface methods - must be implemented
+          def tool_name
+            raise NotImplementedError, "Subclass must implement tool_name"
+          end
+
+          def build_command(_paths, fix:, config_path:)
+            raise NotImplementedError, "Subclass must implement build_command"
+          end
+
+          def unavailable_result
+            raise NotImplementedError, "Subclass must implement unavailable_result"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lint/atoms/comment_validator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lint
+    module Atoms
+      # Validates presence of required YAML comments in frontmatter
+      # Used for SKILL.md files that require documentation comments
+      class CommentValidator
+        class << self
+          # Validate that required comments are present in the raw content
+          # @param content [String] Raw file content (with frontmatter)
+          # @param required_comments [Array<String>] Comment prefixes to check for
+          # @return [Array<String>] List of missing comment patterns
+          def validate(content, required_comments:)
+            return [] if required_comments.nil? || required_comments.empty?
+            return required_comments if content.nil? || content.empty?
+
+            # Extract frontmatter section (between --- markers)
+            frontmatter = extract_frontmatter_raw(content)
+            return required_comments if frontmatter.nil?
+
+            missing = []
+
+            required_comments.each do |comment_pattern|
+              # Check if the comment pattern exists in frontmatter
+              # The pattern is like "# context:" - we check if it appears in the YAML section
+              unless frontmatter.include?(comment_pattern)
+                missing << comment_pattern
+              end
+            end
+
+            missing
+          end
+
+          # Find the line number where a comment should be added
+          # @param content [String] Raw file content
+          # @return [Integer] Line number for error reporting (typically line 1-2)
+          def frontmatter_start_line
+            1
+          end
+
+          private
+
+          # Extract raw frontmatter content including comments
+          # @param content [String] Full file content
+          # @return [String, nil] Raw frontmatter text or nil if not found
+          def extract_frontmatter_raw(content)
+            return nil unless content.start_with?("---\n", "---\r\n")
+
+            # Find the ending delimiter
+            start_index = content.index("\n") + 1
+            end_match = content.match(/\n---\n|\n---\r\n/, start_index)
+
+            return nil unless end_match
+
+            # Return the raw frontmatter including comments
+            content[0...end_match.end(0)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lint/atoms/config_locator.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ace
+  module Lint
+    module Atoms
+      # Locates configuration files for validators with precedence rules
+      # Precedence: explicit path > .ace/lint/ > native config > gem defaults
+      # Results are cached to avoid repeated filesystem I/O (thread-safe)
+      class ConfigLocator
+        # Native config file names for each tool
+        NATIVE_CONFIGS = {
+          standardrb: [".standard.yml"],
+          rubocop: [".rubocop.yml"]
+        }.freeze
+
+        # Default config paths within gem defaults directory
+        GEM_DEFAULT_CONFIGS = {
+          standardrb: nil, # StandardRB uses its own defaults
+          rubocop: ".rubocop.yml"
+        }.freeze
+
+        # Thread-safe class-level cache for config lookup results
+        @config_cache = {}
+        @cache_mutex = Mutex.new
+
+        # Locate config file for a validator
+        # @param tool [String, Symbol] Validator name (e.g., :standardrb, :rubocop)
+        # @param project_root [String] Project root directory
+        # @param explicit_path [String, nil] Explicit config path from user config
+        # @return [Hash] { path: String|nil, source: Symbol }
+        #   source: :explicit, :ace_config, :native, :gem_defaults, :none
+        def self.locate(tool, project_root:, explicit_path: nil)
+          tool_sym = tool.to_s.downcase.to_sym
+
+          # 1. Explicit path takes highest precedence (not cached)
+          if explicit_path && !explicit_path.empty?
+            full_path = resolve_path(explicit_path, project_root)
+            return {path: full_path, source: :explicit, exists: File.exist?(full_path)}
+          end
+
+          # Build cache key (exclude explicit_path from caching as it may vary)
+          cache_key = "#{tool_sym}:#{project_root}"
+
+          # Thread-safe cache lookup and population
+          @cache_mutex.synchronize do
+            # Return cached result if available
+            return @config_cache[cache_key].dup if @config_cache.key?(cache_key)
+
+            # 2. Check .ace/lint/ directory
+            ace_config = find_ace_config(tool_sym, project_root)
+            if ace_config
+              @config_cache[cache_key] = ace_config
+              return ace_config.dup
+            end
+
+            # 3. Check for native config in project root
+            native_config = find_native_config(tool_sym, project_root)
+            if native_config
+              @config_cache[cache_key] = native_config
+              return native_config.dup
+            end
+
+            # 4. Fall back to gem defaults
+            gem_config = find_gem_default_config(tool_sym)
+            if gem_config
+              @config_cache[cache_key] = gem_config
+              return gem_config.dup
+            end
+
+            result = {path: nil, source: :none, exists: false}
+            @config_cache[cache_key] = result
+            result
+          end
+        end
+
+        # Resolve a potentially relative path
+        # @param path [String] Path to resolve
+        # @param base [String] Base directory for relative paths
+        # @return [String] Resolved absolute path
+        def self.resolve_path(path, base)
+          return path if Pathname.new(path).absolute?
+
+          File.expand_path(path, base)
+        end
+
+        # Find config in .ace/lint/ directory
+        # @param tool [Symbol] Validator name
+        # @param project_root [String] Project root directory
+        # @return [Hash, nil] Config info or nil if not found
+        def self.find_ace_config(tool, project_root)
+          ace_lint_dir = File.join(project_root, ".ace", "lint")
+          return nil unless File.directory?(ace_lint_dir)
+
+          # Try tool-specific config names
+          config_names = native_config_names(tool)
+          config_names.each do |name|
+            path = File.join(ace_lint_dir, name)
+            return {path: path, source: :ace_config, exists: true} if File.exist?(path)
+          end
+
+          nil
+        end
+        private_class_method :find_ace_config
+
+        # Find native config in project root
+        # @param tool [Symbol] Validator name
+        # @param project_root [String] Project root directory
+        # @return [Hash, nil] Config info or nil if not found
+        def self.find_native_config(tool, project_root)
+          config_names = native_config_names(tool)
+          config_names.each do |name|
+            path = File.join(project_root, name)
+            return {path: path, source: :native, exists: true} if File.exist?(path)
+          end
+
+          nil
+        end
+        private_class_method :find_native_config
+
+        # Find gem default config
+        # @param tool [Symbol] Validator name
+        # @return [Hash, nil] Config info or nil if not found
+        def self.find_gem_default_config(tool)
+          config_file = GEM_DEFAULT_CONFIGS[tool]
+          return nil unless config_file
+
+          # Try Gem.loaded_specs first (installed gem)
+          gem_root = ::Gem.loaded_specs["ace-lint"]&.gem_dir
+
+          # Fallback for development environments (e.g., mono-repo)
+          gem_root ||= File.expand_path("../../..", __dir__) if __dir__
+
+          return nil unless gem_root
+
+          path = File.join(gem_root, ".ace-defaults", "lint", config_file)
+          return {path: path, source: :gem_defaults, exists: true} if File.exist?(path)
+
+          nil
+        end
+        private_class_method :find_gem_default_config
+
+        # Get native config file names for a tool
+        # @param tool [Symbol] Validator name
+        # @return [Array<String>] List of possible config file names
+        def self.native_config_names(tool)
+          NATIVE_CONFIGS[tool] || []
+        end
+        private_class_method :native_config_names
+
+        # Reset config cache (for testing)
+        # @return [void]
+        def self.reset_cache!
+          @cache_mutex.synchronize do
+            @config_cache = {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lint/atoms/frontmatter_extractor.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lint
+    module Atoms
+      # Pure function to extract frontmatter from markdown
+      class FrontmatterExtractor
+        # Extract frontmatter and content from markdown
+        # @param content [String] Markdown content with potential frontmatter
+        # @return [Hash] Result with :frontmatter, :body, :has_frontmatter
+        def self.extract(content)
+          return empty_result if content.nil? || content.empty?
+
+          # Check if content starts with frontmatter delimiter
+          unless content.start_with?("---\n", "---\r\n")
+            return {
+              frontmatter: nil,
+              body: content,
+              has_frontmatter: false
+            }
+          end
+
+          # Find the ending delimiter
+          # Start search after the first "---\n"
+          start_index = content.index("\n") + 1
+          end_match = content.match(/\n---\n|\n---\r\n/, start_index)
+
+          unless end_match
+            return {
+              frontmatter: nil,
+              body: content,
+              has_frontmatter: false,
+              error: "Missing closing '---' delimiter for frontmatter"
+            }
+          end
+
+          end_index = end_match.begin(0)
+
+          # Extract frontmatter YAML (between the delimiters)
+          frontmatter_content = content[4...end_index]
+
+          # Extract body content (after the closing delimiter)
+          body_start = end_match.end(0)
+          body_content = content[body_start..] || ""
+
+          {
+            frontmatter: frontmatter_content,
+            body: body_content,
+            has_frontmatter: true
+          }
+        end
+
+        # Check if content has frontmatter
+        # @param content [String] Markdown content
+        # @return [Boolean] True if frontmatter detected
+        def self.has_frontmatter?(content)
+          return false if content.nil? || content.empty?
+
+          content.start_with?("---\n", "---\r\n") &&
+            (content.include?("\n---\n") || content.include?("\n---\r\n"))
+        end
+
+        def self.empty_result
+          {
+            frontmatter: nil,
+            body: "",
+            has_frontmatter: false,
+            error: "Empty content"
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ace/lint/atoms/kramdown_parser.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module Ace
+  module Lint
+    module Atoms
+      # Pure function to parse markdown with kramdown
+      class KramdownParser
+        # Parse markdown content with kramdown
+        # @param content [String] Markdown content
+        # @param options [Hash] Kramdown options
+        # @return [Hash] Result with :success, :document, :errors, :warnings
+        def self.parse(content, options: {})
+          # Minimal defaults - let kramdown use its defaults
+          # Users can override via .ace/lint/config.yml
+          default_options = {
+            input: "GFM" # Use GitHub Flavored Markdown
+          }
+
+          merged_options = default_options.merge(options)
+
+          begin
+            document = Kramdown::Document.new(content, merged_options)
+
+            # Kramdown collects warnings during parsing (as strings)
+            # All warnings are informational, not errors
+            warnings = document.warnings || []
+
+            {
+              success: true, # Kramdown warnings don't indicate parsing failure
+              document: document,
+              errors: [],
+              warnings: warnings
+            }
+          rescue => e
+            {
+              success: false,
+              document: nil,
+              errors: ["Kramdown parsing error: #{e.message}"],
+              warnings: []
+            }
+          end
+        end
+
+        # Format markdown content with kramdown
+        # @param content [String] Markdown content
+        # @param options [Hash] Kramdown options
+        # @return [Hash] Result with :success, :formatted_content, :errors
+        def self.format(content, options: {})
+          parse_result = parse(content, options: options)
+
+          return {success: false, formatted_content: nil, errors: parse_result[:errors]} unless parse_result[:success]
+
+          begin
+            # Convert back to markdown
+            formatted = parse_result[:document].to_kramdown
+
+            {
+              success: true,
+              formatted_content: formatted,
+              errors: []
+            }
+          rescue => e
+            {
+              success: false,
+              formatted_content: nil,
+              errors: ["Kramdown formatting error: #{e.message}"]
+            }
+          end
+        end
+
+        # Kramdown warnings are already formatted strings
+        def self.format_kramdown_message(warning)
+          warning.to_s
+        end
+      end
+    end
+  end
+end