ace-lint 0.25.0 → 0.27.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b28e15301bd4cac4a828be1dbe5a7c13bb09dc8014d0f0d803fcd53fe0e7e88
-  data.tar.gz: 8f8fe4b4948fd41aa12af6588a4a6e90a1a6eaa357208aaab54f997ebfbd69f1
+  metadata.gz: 8d08aca270559c7f2cb97ffab6f7d0cc28fab077a58b51763d7d9ac0e223a22b
+  data.tar.gz: 305b0142f0f4b89104559f0079f98f3286e41fd8876ec236c24e3bce838f5df7
 SHA512:
-  metadata.gz: 24cf2c6f78e9df0663cab9c9f073d4e1ab07d9206146b38d8c579b7874d285f07423b5d38602b6dafa683b957866f2f04a79be91dccac8cbcf6c67054c9fe0a5
-  data.tar.gz: e72a57f50f8fa8ef5a9ed5593134c4c72aa29119c66023596d50b573edd6bf44ca88cbfa5c7fba76f6f0b967476cd2ff3050b3548fbc09a4cac1a9d53bd44e48
+  metadata.gz: 033a583ec905b507983508780c806a13bbb054ac6423c3c7619279c84aebf85bb60db054b53ad7d7f4f887b9a4f004006de67d1edf90952aeaa706bedeacc5ef
+  data.tar.gz: b444718179323bb8e2c1b6617605a54349e22e170c02b81add84b76c282c036ccad901edba5aa0386b85515a95d29ea63331c13d50fb0da5f9d7b77b6e9b1fc8

data/.ace-defaults/lint/config.yml

@@ -1,5 +1,6 @@
 # ace-lint general configuration
 # Place this in .ace/lint/config.yml in your project
 
-# General ace-lint settings (currently using defaults)
-# Future: enable/disable specific linters, custom rules, etc.
+lint:
+  # Default model for --auto-fix-with-agent when --model is not provided
+  doctor_agent_model: "gemini:flash-latest@yolo"

data/CHANGELOG.md

@@ -6,6 +6,84 @@ The format is based on [Keep a Changelog][1], and this project adheres to [Seman
 
 ## [Unreleased]
 
+## [0.27.3] - 2026-03-26
+
+### Fixed
+- Corrected `--auto-fix --dry-run` file-count reporting to count unique lint result file paths instead of parsing formatted issue strings.
+
+### Changed
+- Extracted deterministic and agent-assisted auto-fix orchestration from the lint CLI command into `Organisms::AutoFixOrchestrator`.
+- Centralized `ace-llm` test load-path setup in `test_helper` for agent-fix command tests.
+
+### Technical
+- Documented the frontmatter-prefix reconstruction contract in `MarkdownSurgicalFixer`.
+- Marked internal structural-change guardrail helpers in `KramdownFormatter` as private class methods.
+
+## [0.27.2] - 2026-03-26
+
+### Fixed
+- Made `--auto-fix-with-agent` apply concrete file edits from model output and fail fast when no editable changes are returned.
+- Prevented stale pre-agent lint errors from being carried into post-agent validation results.
+- Hardened markdown formatting guardrails to treat any HTML attribute-count change (increase or decrease) as structural risk.
+
+### Changed
+- Added an explicit warning before agent-assisted fixes that full file contents are sent to the selected model.
+- Added payload-size limits for agent-fix prompt file content to avoid oversized requests.
+- Refactored markdown fence-state handling to use a shared fence-aware line iterator across linter and fixer paths.
+
+### Technical
+- Added non-dry-run command tests for agent fix mode success and no-edit failure behavior.
+- Added formatter coverage for HTML attribute-removal structural change detection.
+
+## [0.27.1] - 2026-03-26
+
+### Fixed
+- Preserved markdown link destinations containing nested parentheses during typography-safe surgical fixes.
+- Hardened agent prompt construction for `--auto-fix-with-agent` by using dynamic code fences that remain valid when file content already contains fenced blocks.
+
+### Changed
+- Updated `--auto-fix --dry-run` preview wording to avoid implying every issue is deterministically fixable.
+- Aligned `--auto-fix` exit behavior with normal lint semantics: warning-only results now exit successfully while error results still fail.
+
+### Technical
+- Optimized `run_auto_fix` to skip redundant fix-mode passes for non-fixable file types while preserving final lint validation.
+
+## [0.27.0] - 2026-03-26
+
+### Added
+- Added deterministic repair flags to `ace-lint`: `--auto-fix`, `--auto-fix-with-agent`, `--dry-run` (`-n`), and `--model`.
+- Added agent-assisted lint repair flow that builds a structured prompt with remaining violations and full file content for affected files.
+- Added command-level coverage for auto-fix dry-run, alias parity, warning precedence, and exit semantics.
+
+### Fixed
+- Fixed auto-fix exit behavior to return non-zero when violations remain after deterministic repair.
+- Fixed help and docs drift by aligning CLI docs/examples and E2E fix-mode guidance with the new auto-fix contract.
+
+### Changed
+- Changed `--fix` semantics to an alias of `--auto-fix` (deterministic fix then re-lint).
+- Changed auto-fix modes to ignore `--format` with an explicit warning.
+- Added `lint.doctor_agent_model` default configuration for agent-assisted repair model selection.
+
+### Technical
+- Expanded task specification verification checklist evidence for the auto-fix and agent-assisted workflow implementation.
+
+## [0.26.0] - 2026-03-26
+
+### Added
+- Added `MarkdownSurgicalFixer` for markdown-family `--fix` operations that apply targeted line edits without full document reserialization.
+- Added structural guardrails for markdown `--format` to skip unsafe kramdown rewrites when frontmatter, code-block, table, or HTML-attribute drift is detected.
+
+### Fixed
+- Fixed markdown style checks to ignore heading/list spacing checks inside fenced code blocks.
+- Added trailing whitespace detection for markdown style validation.
+
+### Changed
+- Changed markdown-family `--fix` behavior (`markdown`, `skill`, `workflow`, `agent`) to surgical edits, with `--fix --format` executing surgical fix first then guarded format.
+- Updated CLI/help and usage docs to describe surgical `--fix` semantics and guarded `--format` behavior.
+
+### Technical
+- Expanded ace-lint tests for surgical fixer behavior, formatter guardrails, and orchestrator ordering.
+
 ## [0.25.0] - 2026-03-23
 
 ### Fixed

data/README.md

@@ -3,7 +3,7 @@
 
   Ruby-native linting for markdown, YAML, and Ruby with no Node.js or Python runtime required.
 
-  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
   <br><br>
 
   <a href="https://rubygems.org/gems/ace-lint"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-lint.svg" /></a>
@@ -24,13 +24,15 @@
 
 1. Run lint checks across markdown, YAML, Ruby, and frontmatter validators in one pass.
 2. Apply safe auto-fixes with `--fix` for markdown and Ruby style issues.
+   For markdown-family files, `--fix` is surgical (line-level) and does not reserialize structure.
+   Use `--format` when you explicitly want a guarded kramdown rewrite.
 3. Report results with colorized pass/fail output, using configuration cascade from CLI flags through project and user defaults.
 
 ## Use Cases
 
 **Validate markdown, YAML, and Ruby in one pass** - run [`ace-lint`](docs/usage.md) for doc and code lint checks without mixing Node/Python tooling into Ruby projects. Use `/as-lint-run` for the full agent-driven lint workflow.
 
-**Apply low-risk formatting fixes before review** - use `--fix` to automatically clean markdown and Ruby style issues prior to manual review. Run `/as-lint-fix-issue-from` to fix specific issues identified in lint reports.
+**Apply low-risk formatting fixes before review** - use `--fix` to automatically clean markdown and Ruby style issues prior to manual review. For markdown, fixes are surgical to preserve frontmatter/code blocks/tables/HTML. Run `/as-lint-fix-issue-from` to fix specific issues identified in lint reports.
 
 **Standardize lint behavior across teams and repos** - rely on user/project/default cascade settings from [ace-support-config](../ace-support-config) for consistent validator sets and output modes.
 

data/lib/ace/lint/cli/commands/lint.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 require "ace/support/cli"
+require_relative "../../atoms/type_detector"
 require_relative "../../atoms/validator_registry"
 require_relative "../../organisms/lint_orchestrator"
+require_relative "../../organisms/auto_fix_orchestrator"
 require_relative "../../organisms/result_reporter"
 require_relative "../../organisms/report_generator"
 require_relative "../../organisms/lint_doctor"
@@ -18,6 +20,12 @@ module Ace
         class Lint < Ace::Support::Cli::Command
           include Ace::Support::Cli::Base
 
+          AGENT_FIX_FILE_BLOCK_START = "<<ACE_FILE:".freeze
+          AGENT_FIX_FILE_BLOCK_END = "<<ACE_END_FILE>>".freeze
+          AGENT_FIX_NO_CHANGES = "<<ACE_NO_CHANGES>>".freeze
+          AGENT_FIX_MAX_FILE_BYTES = 200_000
+          AGENT_FIX_MAX_TOTAL_BYTES = 1_000_000
+
           desc <<~DESC.strip
             Lint markdown, YAML, Ruby, and frontmatter files
 
@@ -42,8 +50,11 @@ module Ace
           # Examples shown in help output
           example [
             "README.md                    # Auto-detect type from extension",
-            "--fix README.md              # Auto-fix and format",
-            "docs/**/*.md --format        # Format with kramdown",
+            "--auto-fix README.md         # Deterministic auto-fix then re-lint",
+            "--fix README.md              # Alias for --auto-fix",
+            "--auto-fix --dry-run README.md  # Preview fixes without writing",
+            "--auto-fix-with-agent README.md # Auto-fix then agent for remaining issues",
+            "docs/**/*.md --format        # Format with guarded kramdown",
             "**/*.rb --validators standardrb,rubocop  # Multiple validators",
             "--doctor                     # Diagnose lint configuration",
             "--doctor-verbose             # Diagnose with all details"
@@ -54,8 +65,13 @@ module Ace
           argument :files, required: false, type: :array, desc: "Files to lint"
 
           # Method options (maintaining parity with Thor implementation)
-          option :fix, type: :boolean, aliases: %w[-f], desc: "Auto-fix/format files"
-          option :format, type: :boolean, desc: "Format files with kramdown"
+          option :auto_fix, type: :boolean, aliases: %w[-f --fix], desc: "Deterministic auto-fix, then re-lint"
+          option :auto_fix_with_agent, type: :boolean,
+            desc: "Run --auto-fix, then launch agent for remaining issues"
+          option :dry_run, type: :boolean, aliases: %w[-n],
+            desc: "Preview auto-fixes without modifying files"
+          option :model, type: :string, desc: "Provider:model for agent-assisted fix"
+          option :format, type: :boolean, desc: "Format markdown with guarded kramdown"
           option :type, type: :string, aliases: %w[-t], desc: "File type (markdown, yaml, ruby, frontmatter)"
           option :line_width, type: :integer, desc: "Line width for formatting (default: 120)"
           option :validators, type: :string, desc: "Comma-separated list of validators (e.g., standardrb,rubocop)"
@@ -116,7 +132,22 @@ module Ace
             lint_options = prepare_options(clean_options)
 
             # Lint files
-            results = orchestrator.lint_files(expanded_paths, options: lint_options)
+            if auto_fix_mode?(clean_options)
+              warn_format_ignored_if_needed(clean_options)
+              auto_fix_orchestrator = build_auto_fix_orchestrator(
+                orchestrator,
+                lint_options: lint_options,
+                options: clean_options
+              )
+              if clean_options[:dry_run]
+                auto_fix_orchestrator.run_dry_run(expanded_paths)
+                return
+              end
+
+              results = auto_fix_orchestrator.run(expanded_paths)
+            else
+              results = orchestrator.lint_files(expanded_paths, options: lint_options)
+            end
 
             # Generate report unless --no-report flag is set
             report_dir = nil
@@ -138,8 +169,16 @@ module Ace
             verbose = !clean_options[:quiet]
             Organisms::ResultReporter.report(results, verbose: verbose, report_dir: report_dir, report_files: report_files)
 
-            # Raise on lint failures
-            if results.any?(&:failed?)
+            # Raise on remaining issues
+            if auto_fix_mode?(clean_options)
+              remaining_errors = results.sum(&:error_count)
+              if remaining_errors.positive?
+                raise Ace::Support::Cli::Error.new(
+                  "#{remaining_errors} error violation(s) remain after auto-fix",
+                  exit_code: 1
+                )
+              end
+            elsif results.any?(&:failed?)
               failed_count = results.count(&:failed?)
               exit_code = Organisms::ResultReporter.exit_code(results)
               raise Ace::Support::Cli::Error.new("#{failed_count} file(s) had lint errors", exit_code: exit_code)
@@ -289,7 +328,7 @@ module Ace
             prepared[:type] = options[:type].to_sym if options[:type]
 
             # Fix/format options
-            prepared[:fix] = options[:fix] if options[:fix]
+            prepared[:fix] = true if auto_fix_mode?(options)
             prepared[:format] = options[:format] if options[:format]
 
             # Validators option (comma-separated list)
@@ -311,6 +350,30 @@ module Ace
           def parse_validators(validators_str)
             validators_str.split(",").map { |v| v.strip.downcase.to_sym }
           end
+
+          def auto_fix_mode?(options)
+            options[:auto_fix] || options[:auto_fix_with_agent]
+          end
+
+          def warn_format_ignored_if_needed(options)
+            return unless options[:format]
+
+            warn "[ace-lint] Warning: --format is ignored when using --auto-fix or --auto-fix-with-agent"
+          end
+
+          def build_auto_fix_orchestrator(orchestrator, lint_options:, options:)
+            Organisms::AutoFixOrchestrator.new(
+              orchestrator: orchestrator,
+              lint_options: lint_options,
+              with_agent: options[:auto_fix_with_agent],
+              model: options[:model],
+              file_block_start: AGENT_FIX_FILE_BLOCK_START,
+              file_block_end: AGENT_FIX_FILE_BLOCK_END,
+              no_changes_marker: AGENT_FIX_NO_CHANGES,
+              max_file_bytes: AGENT_FIX_MAX_FILE_BYTES,
+              max_total_bytes: AGENT_FIX_MAX_TOTAL_BYTES
+            )
+          end
         end
       end
     end

data/lib/ace/lint/molecules/kramdown_formatter.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "../atoms/kramdown_parser"
+require_relative "../atoms/frontmatter_extractor"
+require_relative "markdown_linter"
 
 module Ace
   module Lint
@@ -10,21 +12,35 @@ module Ace
         # Format markdown file in place
         # @param file_path [String] Path to markdown file
         # @param options [Hash] Kramdown options
-        # @return [Hash] Result with :success, :formatted, :errors
-        def self.format_file(file_path, options: {})
+        # @param guardrails [Boolean] Enable structural safety checks before write
+        # @return [Hash] Result with :success, :formatted, :errors, :warnings
+        def self.format_file(file_path, options: {}, guardrails: false)
           content = File.read(file_path)
           result = format_content(content, options: options)
 
-          if result[:success] && result[:formatted_content]
-            File.write(file_path, result[:formatted_content])
-            {success: true, formatted: true, errors: []}
-          else
-            {success: false, formatted: false, errors: result[:errors]}
+          return {success: false, formatted: false, errors: result[:errors], warnings: []} unless result[:success]
+
+          formatted_content = result[:formatted_content]
+          return {success: true, formatted: false, errors: [], warnings: []} if formatted_content == content
+
+          if guardrails
+            structural_changes = detect_structural_changes(content, formatted_content)
+            if structural_changes.any?
+              return {
+                success: true,
+                formatted: false,
+                errors: [],
+                warnings: ["Skipped formatting due to structural change risk: #{structural_changes.join(", ")}"]
+              }
+            end
           end
+
+          File.write(file_path, formatted_content)
+          {success: true, formatted: true, errors: [], warnings: []}
         rescue Errno::ENOENT
-          {success: false, formatted: false, errors: ["File not found: #{file_path}"]}
+          {success: false, formatted: false, errors: ["File not found: #{file_path}"], warnings: []}
         rescue => e
-          {success: false, formatted: false, errors: ["Error formatting file: #{e.message}"]}
+          {success: false, formatted: false, errors: ["Error formatting file: #{e.message}"], warnings: []}
         end
 
         # Format markdown content
@@ -60,6 +76,57 @@ module Ace
 
           result[:formatted_content] != content
         end
+
+        def self.detect_structural_changes(original, formatted)
+          changes = []
+          changes << "frontmatter" if frontmatter_changed?(original, formatted)
+          changes << "code blocks" if fence_count_changed?(original, formatted)
+          changes << "tables" if table_row_count_changed?(original, formatted)
+          changes << "html attributes" if html_attributes_changed?(original, formatted)
+          changes
+        end
+
+        def self.frontmatter_changed?(original, formatted)
+          original_frontmatter = Atoms::FrontmatterExtractor.extract(original)
+          formatted_frontmatter = Atoms::FrontmatterExtractor.extract(formatted)
+
+          original_frontmatter[:has_frontmatter] != formatted_frontmatter[:has_frontmatter] ||
+            original_frontmatter[:frontmatter].to_s != formatted_frontmatter[:frontmatter].to_s
+        end
+
+        def self.fence_count_changed?(original, formatted)
+          fence_count(original) != fence_count(formatted)
+        end
+
+        def self.fence_count(content)
+          content.lines.count { |line| line.match?(MarkdownLinter::FENCE_PATTERN) }
+        end
+
+        def self.table_row_count_changed?(original, formatted)
+          table_row_count(original) != table_row_count(formatted)
+        end
+
+        def self.table_row_count(content)
+          content.lines.count { |line| line.match?(/^\s*\|.*\|\s*$/) }
+        end
+
+        def self.html_attributes_changed?(original, formatted)
+          html_attribute_count(formatted) != html_attribute_count(original)
+        end
+
+        def self.html_attribute_count(content)
+          content.scan(/<([A-Za-z][A-Za-z0-9:-]*)([^>]*)>/).sum do |_tag_name, attributes|
+            attributes.scan(/\s+[A-Za-z_:][\w:.-]*(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?/).size
+          end
+        end
+
+        private_class_method :frontmatter_changed?,
+          :fence_count_changed?,
+          :fence_count,
+          :table_row_count_changed?,
+          :table_row_count,
+          :html_attributes_changed?,
+          :html_attribute_count
       end
     end
   end