ace-bundle 0.40.0

data/lib/ace/bundle/organisms/pr_bundle_loader.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "ace/git"
+
+module Ace
+  module Bundle
+    module Organisms
+      # Loads PR diff content into bundle
+      #
+      # Responsible for:
+      # - Normalizing PR references (string, array, hash formats)
+      # - Fetching diffs via Ace::Git::Molecules::PrMetadataFetcher
+      # - Integrating results into bundle sections
+      # - Error handling and surfacing
+      #
+      # @example Basic usage
+      #   loader = PrBundleLoader.new(timeout: 60)
+      #   loader.process(bundle, ["123", "owner/repo#456"])
+      #
+      class PrBundleLoader
+        # @param options [Hash] Configuration options
+        # @option options [Integer] :timeout Timeout for gh commands (default from ace-git config)
+        # @option options [Boolean] :debug Enable debug output
+        def initialize(options = {})
+          @timeout = options[:timeout] || Ace::Git.network_timeout
+          @debug = options[:debug] || false
+        end
+
+        # Process PR references and add diffs to bundle
+        #
+        # @param bundle [Models::BundleData] Bundle to populate
+        # @param pr_refs [Array<String>, String, Hash, nil] PR reference(s)
+        # @return [Boolean] true if at least one diff was successfully fetched
+        def process(bundle, pr_refs)
+          normalized = normalize_pr_refs(pr_refs)
+          return false if normalized.empty?
+
+          processed_diffs = fetch_all_diffs(bundle, normalized)
+          successful_diffs = processed_diffs.select { |d| d[:success] }
+
+          if successful_diffs.empty?
+            surface_errors_to_content(bundle)
+            return false
+          end
+
+          add_diffs_to_bundle(bundle, processed_diffs)
+          true
+        end
+
+        private
+
+        # Normalize PR refs to array, deduplicate, and remove empty/nil values
+        # Handles both string refs and hash refs (for future extensibility)
+        #
+        # @param pr_refs [String, Array, Hash, nil] PR reference(s)
+        # @return [Array<String>] Normalized, deduplicated PR refs
+        def normalize_pr_refs(pr_refs)
+          refs = pr_refs.is_a?(Array) ? pr_refs.flatten : [pr_refs]
+          refs.map do |ref|
+            case ref
+            when String then ref.strip
+            when Hash then ref[:number]&.to_s || ref["number"]&.to_s
+            else ref&.to_s
+            end
+          end.compact.reject(&:empty?).uniq
+        end
+
+        # Fetch diffs for all PR refs, recording errors in bundle metadata
+        #
+        # @param bundle [Models::BundleData] Bundle for error recording
+        # @param pr_refs [Array<String>] Normalized PR refs
+        # @return [Array<Hash>] Processed diff results
+        def fetch_all_diffs(bundle, pr_refs)
+          pr_refs.map do |pr_ref|
+            fetch_single_diff(bundle, pr_ref)
+          end.compact
+        end
+
+        # Fetch diff for a single PR reference
+        #
+        # @param bundle [Models::BundleData] Bundle for error recording
+        # @param pr_ref [String] Single PR reference
+        # @return [Hash, nil] Diff result or nil on skip
+        def fetch_single_diff(bundle, pr_ref)
+          result = Ace::Git::Molecules::PrMetadataFetcher.fetch_diff(pr_ref, timeout: @timeout)
+
+          if result[:success]
+            {
+              range: result[:source],
+              output: result[:diff],
+              success: true,
+              source: :pr
+            }
+          else
+            record_error(bundle, "PR fetch failed for '#{pr_ref}': #{result[:error]}")
+            {range: pr_range_identifier(pr_ref), output: "Error: #{result[:error]}", success: false, error: result[:error], source: :pr}
+          end
+        rescue Ace::Git::Error => e
+          # Catches all ace-git errors: GitError, GhNotInstalledError, GhAuthenticationError,
+          # PrNotFoundError, TimeoutError (all inherit from Ace::Git::Error)
+          record_error(bundle, "PR fetch failed for '#{pr_ref}': #{e.message}")
+          {range: pr_range_identifier(pr_ref), output: "Error: #{e.message}", success: false, error: e.message, source: :pr}
+        rescue ArgumentError => e
+          record_error(bundle, "Invalid PR identifier '#{pr_ref}': #{e.message}")
+          nil
+        end
+
+        # Record error in bundle metadata
+        #
+        # @param bundle [Models::BundleData] Bundle to update
+        # @param message [String] Error message
+        def record_error(bundle, message)
+          bundle.metadata[:errors] ||= []
+          bundle.metadata[:errors] << message
+        end
+
+        # Generate standardized PR range identifier for error responses
+        # @param pr_ref [String] PR reference
+        # @return [String] Range identifier in "pr:ref" format
+        def pr_range_identifier(pr_ref)
+          "pr:#{pr_ref}"
+        end
+
+        # Surface errors to content for callers who don't inspect metadata
+        #
+        # @param bundle [Models::BundleData] Bundle to update
+        def surface_errors_to_content(bundle)
+          return unless bundle.metadata[:errors]&.any?
+
+          error_notice = bundle.metadata[:errors].map { |e| "- #{e}" }.join("\n")
+          bundle.content = "**PR Fetch Errors:**\n#{error_notice}\n\n" + (bundle.content || "")
+        end
+
+        # Add processed diffs to bundle's diffs section
+        #
+        # @param bundle [Models::BundleData] Bundle to update
+        # @param processed_diffs [Array<Hash>] Diff results to add
+        def add_diffs_to_bundle(bundle, processed_diffs)
+          bundle.sections ||= {}
+          bundle.sections["diffs"] ||= {title: "Diffs", _processed_diffs: []}
+          bundle.sections["diffs"][:_processed_diffs] ||= []
+          bundle.sections["diffs"][:_processed_diffs].concat(processed_diffs)
+        end
+      end
+    end
+  end
+end

data/lib/ace/bundle/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ace
+  module Bundle
+    VERSION = "0.40.0"
+  end
+end

data/lib/ace/bundle.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "ace/support/config"
+require "ace/core"
+require "ace/git"
+require_relative "bundle/version"
+
+# Define error hierarchy before loading components (they reference these classes)
+module Ace
+  module Bundle
+    # Base error class for all ace-bundle errors
+    class Error < StandardError; end
+
+    # Raised when section validation fails
+    class SectionValidationError < Error; end
+
+    # Raised when preset loading fails
+    class PresetLoadError < Error; end
+  end
+end
+
+# Main API
+require_relative "bundle/organisms/bundle_loader"
+require_relative "bundle/molecules/preset_manager"
+require_relative "bundle/molecules/bundle_file_writer"
+
+# CLI and commands
+require_relative "bundle/cli"
+
+module Ace
+  module Bundle
+    # Mutex for thread-safe config initialization
+    @config_mutex = Mutex.new
+
+    class << self
+      # Load bundle using preset
+      # @param preset_name [String] Name of the preset to load
+      # @param options [Hash] Additional options
+      # @return [Models::BundleData] Loaded bundle data
+      def load_preset(preset_name, options = {})
+        loader = Organisms::BundleLoader.new(options)
+        loader.load_preset(preset_name)
+      end
+
+      # Load multiple presets and merge them
+      # @param preset_names [Array<String>] Names of presets to load
+      # @param options [Hash] Additional options
+      # @return [Models::BundleData] Merged bundle data
+      def load_multiple_presets(preset_names, options = {})
+        loader = Organisms::BundleLoader.new(options)
+        loader.load_multiple_presets(preset_names)
+      end
+
+      # Inspect configuration of presets/files without loading files or executing commands
+      # @param inputs [Array<String>] Names of presets or paths to files to inspect
+      # @param options [Hash] Additional options
+      # @return [Models::BundleData] Configuration as YAML
+      def inspect_config(inputs, options = {})
+        loader = Organisms::BundleLoader.new(options)
+        loader.inspect_config(inputs)
+      end
+
+      # List available presets
+      # @return [Array<Hash>] List of available presets
+      def list_presets
+        manager = Molecules::PresetManager.new
+        manager.list_presets
+      end
+
+      # Load bundle from file
+      # @param path [String] Path to bundle file
+      # @param options [Hash] Additional options
+      # @return [Models::BundleData] Loaded bundle data
+      def load_file(path, options = {})
+        loader = Organisms::BundleLoader.new(options)
+        loader.load_file(path)
+      end
+
+      # Load with auto-detection
+      # @param input [String] File path, inline YAML, or preset name
+      # @param options [Hash] Additional options
+      # @return [Models::BundleData] Loaded bundle data
+      def load_auto(input, options = {})
+        loader = Organisms::BundleLoader.new(options)
+        loader.load_auto(input)
+      end
+
+      # Load multiple inputs and merge them
+      # @param inputs [Array<String>] Array of inputs to load
+      # @param options [Hash] Additional options
+      # @return [Models::BundleData] Merged bundle data
+      def load_multiple(inputs, options = {})
+        loader = Organisms::BundleLoader.new(options)
+        loader.load_multiple(inputs)
+      end
+
+      # Load multiple inputs (presets and files) and merge them
+      # @param preset_names [Array<String>] Names of presets to load
+      # @param file_paths [Array<String>] Paths to configuration files
+      # @param options [Hash] Additional options
+      # @return [Models::BundleData] Merged bundle data
+      def load_multiple_inputs(preset_names, file_paths, options = {})
+        loader = Organisms::BundleLoader.new(options)
+        loader.load_multiple_inputs(preset_names, file_paths, options)
+      end
+
+      # Write bundle output to file with optional chunking
+      # @param bundle [Models::BundleData] Bundle to write
+      # @param output_path [String] Output file path
+      # @param options [Hash] Additional options
+      # @return [Hash] Write result with success status
+      def write_output(bundle, output_path, options = {})
+        writer = Molecules::BundleFileWriter.new(
+          cache_dir: cache_dir,
+          max_lines: max_lines
+        )
+        writer.write_with_chunking(bundle, output_path, options)
+      end
+
+      # Get configuration for ace-bundle
+      # Follows ADR-022: Configuration Default and Override Pattern
+      # Uses Ace::Support::Config.create() for configuration cascade resolution
+      # Thread-safe: uses mutex for initialization
+      # @return [Hash] merged configuration hash
+      # @example Get current configuration
+      #   config = Ace::Bundle.config
+      #   puts config["cache_dir"]  # => ".ace-local/bundle"
+      def config
+        # Fast path: return cached config if already initialized
+        return @config if defined?(@config) && @config
+
+        # Thread-safe initialization
+        @config_mutex.synchronize do
+          @config ||= load_config
+        end
+      end
+
+      # Reset configuration cache (mainly for testing)
+      # Thread-safe: uses mutex to prevent race conditions
+      def reset_config!
+        @config_mutex.synchronize do
+          @config = nil
+        end
+      end
+
+      # ---- Configuration Helper Methods (ADR-022 compliant) ----
+      # These read from config instead of using hardcoded constants
+
+      # Cache directory for bundle output files
+      # @return [String] Cache directory path (default: ".ace-local/bundle")
+      def cache_dir
+        config["cache_dir"] || ".ace-local/bundle"
+      end
+
+      # Maximum lines per chunk before splitting output into multiple files
+      # @return [Integer] Max lines per chunk (default: 2000)
+      def max_lines
+        config["max_lines"] || 2_000
+      end
+
+      # Line count threshold for auto-format output mode
+      # When no explicit --output mode is specified:
+      #   - Content below this threshold: displayed inline (stdout)
+      #   - Content at or above this threshold: saved to cache file
+      # @return [Integer] Auto-format threshold in lines (default: 500, range: 10-10000)
+      def auto_format_threshold
+        threshold = config["auto_format_threshold"]
+        # Ensure valid integer within reasonable bounds (10-10000 lines)
+        # - Below 10: too aggressive, would cache almost everything
+        # - Above 10000: defeats the purpose of auto-format
+        return 500 unless threshold.is_a?(Integer) && threshold.between?(10, 10_000)
+
+        threshold
+      end
+
+      # Compressor configuration section from global/project config
+      # @return [Hash] compressor config (default: {})
+      def compressor_config
+        config["compressor"] || {}
+      end
+
+      # Default compressor source scope from config
+      # @return [String] source scope (default: "off")
+      def compressor_source_scope
+        compressor_config["source_scope"] || "off"
+      end
+
+      # Default compressor mode from config
+      # @return [String] compressor mode (default: "exact")
+      def compressor_mode
+        compressor_config["mode"] || "exact"
+      end
+
+      private
+
+      # Load configuration using Ace::Support::Config cascade
+      # Resolves gem defaults from .ace-defaults/ and user overrides from .ace/
+      # @return [Hash] Merged and transformed configuration
+      def load_config
+        gem_root = Gem.loaded_specs["ace-bundle"]&.gem_dir ||
+          File.expand_path("../..", __dir__)
+
+        resolver = Ace::Support::Config.create(
+          config_dir: ".ace",
+          defaults_dir: ".ace-defaults",
+          gem_path: gem_root
+        )
+
+        # Resolve config for bundle namespace
+        config = resolver.resolve_namespace("bundle")
+
+        # Extract the bundle section for direct access
+        raw_config = config.data["bundle"] || config.data
+        normalize_keys(raw_config)
+      rescue Ace::Support::Config::YamlParseError => e
+        warn "ace-bundle: YAML syntax error in configuration"
+        warn "  #{e.message}"
+        # Fall back to gem defaults
+        load_gem_defaults_fallback
+      rescue => e
+        warn "ace-bundle: Failed to load configuration: #{e.message}"
+        # Fall back to gem defaults
+        load_gem_defaults_fallback
+      end
+
+      # Load gem defaults directly as fallback when cascade resolution fails
+      # @return [Hash] Defaults hash or empty hash if defaults also fail
+      def load_gem_defaults_fallback
+        gem_root = Gem.loaded_specs["ace-bundle"]&.gem_dir ||
+          File.expand_path("../..", __dir__)
+        defaults_path = File.join(gem_root, ".ace-defaults", "bundle", "config.yml")
+
+        return {} unless File.exist?(defaults_path)
+
+        data = YAML.safe_load_file(defaults_path, permitted_classes: [Date], aliases: true) || {}
+        normalize_keys(data["bundle"] || data)
+      rescue
+        {} # Only return empty hash if even defaults fail to load
+      end
+
+      # Normalize hash keys to strings for consistent access
+      # @param hash [Hash] Hash with potentially mixed string/symbol keys
+      # @return [Hash] Hash with string keys
+      def normalize_keys(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.transform_keys(&:to_s)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,190 @@
+--- !ruby/object:Gem::Specification
+name: ace-bundle
+version: !ruby/object:Gem::Version
+  version: 0.40.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-support-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: ace-support-config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: ace-support-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.24'
+- !ruby/object:Gem::Dependency
+  name: ace-support-fs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: ace-git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: ace-support-nav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: ace-compressor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+description: Assembles files, shell commands, and git diffs into a single bundled
+  file. Configured via presets or markdown frontmatter with protocol URL support (wfi://,
+  guide://, tmpl://, prompt://, task://). Output to stdout or cache, with optional
+  compression through ace-compressor.
+email:
+- mc@cs3b.com
+executables:
+- ace-bundle
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ace-defaults/bundle/config.yml"
+- ".ace-defaults/bundle/presets/base.md"
+- ".ace-defaults/bundle/presets/code-review.md"
+- ".ace-defaults/bundle/presets/development.md"
+- ".ace-defaults/bundle/presets/documentation-review.md"
+- ".ace-defaults/bundle/presets/mixed-content-example.md"
+- ".ace-defaults/bundle/presets/project-context.md"
+- ".ace-defaults/bundle/presets/project.md"
+- ".ace-defaults/bundle/presets/section-example-simple.md"
+- ".ace-defaults/bundle/presets/security-review.md"
+- ".ace-defaults/bundle/presets/simple-project.md"
+- ".ace-defaults/bundle/presets/team.md"
+- ".ace-defaults/nav/protocols/wfi-sources/ace-bundle.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- exe/ace-bundle
+- handbook/skills/as-bundle/SKILL.md
+- handbook/skills/as-onboard/SKILL.md
+- handbook/workflow-instructions/bundle.wf.md
+- handbook/workflow-instructions/onboard.wf.md
+- lib/ace/bundle.rb
+- lib/ace/bundle/atoms/boundary_finder.rb
+- lib/ace/bundle/atoms/bundle_normalizer.rb
+- lib/ace/bundle/atoms/content_checker.rb
+- lib/ace/bundle/atoms/line_counter.rb
+- lib/ace/bundle/atoms/preset_list_formatter.rb
+- lib/ace/bundle/atoms/preset_validator.rb
+- lib/ace/bundle/atoms/section_validator.rb
+- lib/ace/bundle/atoms/typo_detector.rb
+- lib/ace/bundle/cli.rb
+- lib/ace/bundle/cli/commands/load.rb
+- lib/ace/bundle/models/bundle_data.rb
+- lib/ace/bundle/molecules/bundle_chunker.rb
+- lib/ace/bundle/molecules/bundle_file_writer.rb
+- lib/ace/bundle/molecules/bundle_merger.rb
+- lib/ace/bundle/molecules/preset_manager.rb
+- lib/ace/bundle/molecules/section_compressor.rb
+- lib/ace/bundle/molecules/section_formatter.rb
+- lib/ace/bundle/molecules/section_processor.rb
+- lib/ace/bundle/organisms/bundle_loader.rb
+- lib/ace/bundle/organisms/pr_bundle_loader.rb
+- lib/ace/bundle/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-bundle/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Assemble multiple sources into a single bundled file, with optional compression
+test_files: []