ace-support-items 0.15.3

data/lib/ace/support/items/atoms/item_id_formatter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../models/item_id"
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Splits and reconstructs 6-char b36ts IDs with type markers.
+        #
+        # A raw 6-char b36ts ID "8ppq7w" becomes "8pp.t.q7w" with type marker "t".
+        # Subtasks append a single character: "8pp.t.q7w.a"
+        #
+        # @example Split a raw ID
+        #   ItemIdFormatter.split("8ppq7w", type_marker: "t")
+        #   # => ItemId(prefix: "8pp", type_marker: "t", suffix: "q7w")
+        #
+        # @example Reconstruct from formatted ID
+        #   ItemIdFormatter.reconstruct("8pp.t.q7w")
+        #   # => "8ppq7w"
+        class ItemIdFormatter
+          # Split a 6-char b36ts ID into prefix.marker.suffix format
+          # @param raw_b36ts [String] 6-character b36ts ID
+          # @param type_marker [String] Type marker (e.g., "t" for task, "i" for idea)
+          # @return [Models::ItemId] Parsed item ID
+          # @raise [ArgumentError] If raw_b36ts is not exactly 6 characters
+          def self.split(raw_b36ts, type_marker:)
+            raise ArgumentError, "Expected 6-char b36ts ID, got #{raw_b36ts.inspect}" unless raw_b36ts.is_a?(String) && raw_b36ts.length == 6
+
+            Models::ItemId.new(
+              raw_b36ts: raw_b36ts,
+              prefix: raw_b36ts[0..2],
+              type_marker: type_marker,
+              suffix: raw_b36ts[3..5],
+              subtask_char: nil
+            )
+          end
+
+          # Create an ItemId with a subtask character
+          # @param raw_b36ts [String] 6-character b36ts ID
+          # @param type_marker [String] Type marker
+          # @param subtask_char [String] Single subtask character (e.g., "a")
+          # @return [Models::ItemId] Parsed item ID with subtask
+          def self.split_subtask(raw_b36ts, type_marker:, subtask_char:)
+            item_id = split(raw_b36ts, type_marker: type_marker)
+            Models::ItemId.new(
+              raw_b36ts: item_id.raw_b36ts,
+              prefix: item_id.prefix,
+              type_marker: item_id.type_marker,
+              suffix: item_id.suffix,
+              subtask_char: subtask_char
+            )
+          end
+
+          # Reconstruct a raw 6-char b36ts ID from a formatted ID string
+          # @param formatted_id [String] Formatted ID (e.g., "8pp.t.q7w" or "8pp.t.q7w.a")
+          # @return [String] Raw 6-char b36ts ID (e.g., "8ppq7w")
+          # @raise [ArgumentError] If format is invalid
+          def self.reconstruct(formatted_id)
+            match = formatted_id.match(/^([0-9a-z]{3})\.([a-z])\.([0-9a-z]{3})(?:\.([0-9a-z]))?$/)
+            raise ArgumentError, "Invalid formatted ID: #{formatted_id.inspect}" unless match
+
+            "#{match[1]}#{match[3]}"
+          end
+
+          # Build a folder name from formatted ID and slug
+          # @param formatted_id [String] e.g., "8pp.t.q7w"
+          # @param slug [String] e.g., "fix-login"
+          # @return [String] e.g., "8pp.t.q7w-fix-login"
+          def self.folder_name(formatted_id, slug)
+            if slug.nil? || slug.empty?
+              formatted_id
+            else
+              "#{formatted_id}-#{slug}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/item_id_parser.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "../models/item_id"
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Parses various reference forms into an ItemId model.
+        #
+        # Supported formats:
+        #   - Full:    "8pp.t.q7w"    → prefix=8pp, marker=t, suffix=q7w
+        #   - Short:   "t.q7w"        → prefix=nil, marker=t, suffix=q7w
+        #   - Suffix:  "q7w"          → prefix=nil, marker=nil, suffix=q7w
+        #   - Subtask: "8pp.t.q7w.a"  → prefix=8pp, marker=t, suffix=q7w, subtask=a
+        #   - Raw:     "8ppq7w"       → prefix=8pp, marker=nil, suffix=q7w (6-char raw b36ts)
+        class ItemIdParser
+          # Full format: prefix.marker.suffix (e.g., "8pp.t.q7w")
+          FULL_PATTERN = /^([0-9a-z]{3})\.([a-z])\.([0-9a-z]{3})$/
+
+          # Full with subtask: prefix.marker.suffix.subtask (e.g., "8pp.t.q7w.a")
+          SUBTASK_PATTERN = /^([0-9a-z]{3})\.([a-z])\.([0-9a-z]{3})\.([0-9a-z])$/
+
+          # Short format: marker.suffix (e.g., "t.q7w")
+          SHORT_PATTERN = /^([a-z])\.([0-9a-z]{3})$/
+
+          # Suffix-only: 3 chars (e.g., "q7w")
+          SUFFIX_PATTERN = /^[0-9a-z]{3}$/
+
+          # Raw 6-char b36ts (e.g., "8ppq7w")
+          RAW_PATTERN = /^[0-9a-z]{6}$/
+
+          # Parse a reference string into an ItemId
+          # @param ref [String] Reference in any supported format
+          # @param default_marker [String, nil] Default type marker for ambiguous refs
+          # @return [ItemId, nil] Parsed item ID or nil if unparseable
+          def self.parse(ref, default_marker: nil)
+            return nil if ref.nil? || ref.empty?
+
+            ref = ref.strip.downcase
+
+            # Try each pattern in order of specificity
+            if (match = ref.match(SUBTASK_PATTERN))
+              Models::ItemId.new(
+                raw_b36ts: "#{match[1]}#{match[3]}",
+                prefix: match[1],
+                type_marker: match[2],
+                suffix: match[3],
+                subtask_char: match[4]
+              )
+            elsif (match = ref.match(FULL_PATTERN))
+              Models::ItemId.new(
+                raw_b36ts: "#{match[1]}#{match[3]}",
+                prefix: match[1],
+                type_marker: match[2],
+                suffix: match[3],
+                subtask_char: nil
+              )
+            elsif (match = ref.match(SHORT_PATTERN))
+              Models::ItemId.new(
+                raw_b36ts: nil,
+                prefix: nil,
+                type_marker: match[1],
+                suffix: match[2],
+                subtask_char: nil
+              )
+            elsif ref.match?(SUFFIX_PATTERN)
+              Models::ItemId.new(
+                raw_b36ts: nil,
+                prefix: nil,
+                type_marker: default_marker,
+                suffix: ref,
+                subtask_char: nil
+              )
+            elsif ref.match?(RAW_PATTERN)
+              Models::ItemId.new(
+                raw_b36ts: ref,
+                prefix: ref[0..2],
+                type_marker: default_marker,
+                suffix: ref[3..5],
+                subtask_char: nil
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/item_statistics.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Pure counting logic for item collections.
+        # Groups items by a field and computes completion rates.
+        class ItemStatistics
+          # @param items [Array] Items responding to a field method
+          # @param field [Symbol] Field to group by (e.g., :status, :priority, :type)
+          # @return [Hash] { total:, by_field: { "value" => count } }
+          def self.count_by(items, field)
+            result = {total: items.size, by_field: {}}
+            items.each do |item|
+              value = item.public_send(field).to_s
+              result[:by_field][value] ||= 0
+              result[:by_field][value] += 1
+            end
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/position_generator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Generates B36TS position values for pinning items in sort order.
+        # Position values are 6-char B36TS strings that sort lexicographically = chronologically.
+        module PositionGenerator
+          # Increment/decrement in seconds for before/after positioning.
+          # ~2 seconds precision in B36TS, so 4 seconds ensures a distinct value.
+          OFFSET_SECONDS = 4
+
+          # Generate a very early position (sorts before all normal timestamps).
+          # Uses a fixed early time to ensure it sorts first.
+          # @return [String] 6-char B36TS position
+          def self.first
+            require "ace/b36ts"
+            # Year 2020, Jan 1 — well before any real item creation
+            early_time = Time.utc(2020, 1, 1)
+            Ace::B36ts.encode(early_time)
+          end
+
+          # Generate a position at current time (sorts after all existing items).
+          # @return [String] 6-char B36TS position
+          def self.last
+            require "ace/b36ts"
+            Ace::B36ts.encode(Time.now.utc)
+          end
+
+          # Generate a position just after the given position.
+          # @param pos [String] Existing 6-char B36TS position
+          # @return [String] 6-char B36TS position slightly after pos
+          def self.after(pos)
+            require "ace/b36ts"
+            time = Ace::B36ts.decode(pos)
+            Ace::B36ts.encode(time + OFFSET_SECONDS)
+          end
+
+          # Generate a position just before the given position.
+          # @param pos [String] Existing 6-char B36TS position
+          # @return [String] 6-char B36TS position slightly before pos
+          def self.before(pos)
+            require "ace/b36ts"
+            time = Ace::B36ts.decode(pos)
+            Ace::B36ts.encode(time - OFFSET_SECONDS)
+          end
+
+          # Generate a position between two existing positions.
+          # @param a [String] Lower 6-char B36TS position
+          # @param b [String] Upper 6-char B36TS position
+          # @return [String] 6-char B36TS position between a and b
+          def self.between(a, b)
+            require "ace/b36ts"
+            time_a = Ace::B36ts.decode(a)
+            time_b = Ace::B36ts.decode(b)
+            midpoint = Time.at((time_a.to_f + time_b.to_f) / 2).utc
+            Ace::B36ts.encode(midpoint)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/relative_time_formatter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Formats a Time into a human-readable relative string like "2h ago".
+        # Pure function — no I/O, fully testable with injected reference time.
+        class RelativeTimeFormatter
+          SECONDS_PER_MINUTE = 60
+          MINUTES_PER_HOUR = 60
+          HOURS_PER_DAY = 24
+          DAYS_PER_WEEK = 7
+          DAYS_PER_MONTH = 30
+          MONTHS_PER_YEAR = 12
+
+          # @param time [Time] The timestamp to format
+          # @param reference [Time] The "now" reference point (default: Time.now)
+          # @return [String] e.g. "just now", "5m ago", "2h ago", "3d ago", "2w ago", "1mo ago", "1y ago"
+          def self.format(time, reference: Time.now)
+            return "unknown" if time.nil?
+            return "unknown" unless time.is_a?(Time)
+
+            seconds = (reference - time).to_i
+            return "just now" if seconds < SECONDS_PER_MINUTE
+
+            minutes = seconds / SECONDS_PER_MINUTE
+            return "#{minutes}m ago" if minutes < MINUTES_PER_HOUR
+
+            hours = minutes / MINUTES_PER_HOUR
+            return "#{hours}h ago" if hours < HOURS_PER_DAY
+
+            days = hours / HOURS_PER_DAY
+            return "#{days}d ago" if days < DAYS_PER_WEEK
+
+            return "#{days / DAYS_PER_WEEK}w ago" if days < DAYS_PER_MONTH
+
+            months = days / DAYS_PER_MONTH
+            return "#{months}mo ago" if months < MONTHS_PER_YEAR
+
+            years = months / MONTHS_PER_YEAR
+            "#{years}y ago"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/slug_sanitizer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # SlugSanitizer provides strict kebab-case slug sanitization for filesystem safety.
+        # Ensures consistent slug handling across the codebase.
+        #
+        # Features:
+        # - Removes path traversal characters (dots, slashes, backslashes)
+        # - Enforces lowercase, numbers, and hyphens only
+        # - Collapses multiple hyphens and trims leading/trailing hyphens
+        # - Returns empty string for entirely invalid input (caller should handle fallback)
+        class SlugSanitizer
+          MAX_LENGTH = 55
+
+          # Sanitize a slug string to strict kebab-case.
+          #
+          # @param slug [String, nil] The slug to sanitize
+          # @param max_length [Integer] Maximum length for the slug (default: MAX_LENGTH)
+          # @return [String] Sanitized slug (empty string if input is nil or entirely invalid)
+          #
+          # @example
+          #   SlugSanitizer.sanitize("My Topic-Slug")
+          #   # => "my-topic-slug"
+          #
+          #   SlugSanitizer.sanitize("../../etc/passwd")
+          #   # => "etc-passwd"
+          #
+          #   SlugSanitizer.sanitize("../")
+          #   # => "" (empty - caller should use fallback)
+          def self.sanitize(slug, max_length: MAX_LENGTH)
+            return "" if slug.nil? || slug.empty?
+
+            # Remove any characters that could enable path traversal: dots, slashes, backslashes
+            # Then validate against allowed pattern (lowercase, numbers, hyphens only)
+            cleaned = slug.to_s.gsub(/[.\\\/]/, "").strip
+            # Further sanitize to only allowed characters (lowercase letters, numbers, hyphens)
+            result = cleaned.downcase.gsub(/[^a-z0-9-]/, "-").squeeze("-").gsub(/^-|-$/, "")
+            truncate_at_word_boundary(result, max_length)
+          end
+
+          # Truncate at word boundary (last hyphen before max_length) to avoid mid-word cuts.
+          #
+          # @param result [String] The sanitized slug
+          # @param max_length [Integer] Maximum allowed length
+          # @return [String] Truncated slug
+          def self.truncate_at_word_boundary(result, max_length)
+            return result if result.length <= max_length
+
+            truncated = result[0...max_length]
+            # Find last hyphen to avoid cutting mid-word
+            last_hyphen = truncated.rindex("-")
+            if last_hyphen && last_hyphen > 0
+              truncated[0...last_hyphen]
+            else
+              truncated
+            end
+          end
+
+          private_class_method :truncate_at_word_boundary
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/sort_score_calculator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Pure function computing sort scores for smart auto-sort.
+        # Score formula: priority_weight × 100 + age_days (capped)
+        # with status-based modifiers for in-progress boost and blocked penalty.
+        module SortScoreCalculator
+          DEFAULT_PRIORITY_WEIGHTS = {
+            "critical" => 4,
+            "high" => 3,
+            "medium" => 2,
+            "low" => 1
+          }.freeze
+
+          # Compute a sort score for an item.
+          # @param priority_weight [Numeric] Weight for the item's priority level
+          # @param age_days [Numeric] Days since creation
+          # @param status [String, nil] Item status for boost/penalty
+          # @param in_progress_boost [Numeric] Added to score for in-progress items
+          # @param blocked_factor [Numeric] Score multiplied by this for blocked items
+          # @param age_cap [Numeric] Maximum age_days value used in calculation
+          # @return [Float] Computed sort score
+          def self.compute(priority_weight:, age_days:, status: nil,
+            in_progress_boost: 1000, blocked_factor: 0.1, age_cap: 90)
+            capped_age = [age_days.to_f, age_cap.to_f].min
+            score = priority_weight.to_f * 100 + capped_age
+
+            case status
+            when "in-progress"
+              score + in_progress_boost
+            when "blocked"
+              score * blocked_factor
+            else
+              score
+            end
+          end
+
+          # Look up the priority weight for a named priority.
+          # @param priority [String, nil] Priority name (critical, high, medium, low)
+          # @param weights [Hash] Custom weight mapping
+          # @return [Numeric] Weight value (defaults to 0 for unknown priorities)
+          def self.priority_weight(priority, weights: DEFAULT_PRIORITY_WEIGHTS)
+            return 0 unless priority
+
+            weights[priority.to_s.downcase] || 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/special_folder_detector.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Detects and normalizes "special" folder names used for item organization.
+        # Special folders use a configurable prefix convention (default: "_").
+        # Short names (without prefix) are auto-expanded: "archive" => "_archive".
+        class SpecialFolderDetector
+          # Default prefix for special folders (single source of truth)
+          DEFAULT_PREFIX = "_"
+
+          # Virtual filters — not physical folders, used for list filtering
+          VIRTUAL_FILTERS = {"next" => :next, "all" => :all}.freeze
+
+          # Aliases that mean "move back to root" (no special folder).
+          # "next" is the primary label; "root" and "/" are convenience aliases.
+          MOVE_TO_ROOT_ALIASES = %w[next root /].freeze
+
+          # Check if a name means "move to root" (out of any special folder).
+          # @param name [String] The name to check
+          # @return [Boolean] True if the name is a move-to-root alias
+          def self.move_to_root?(name)
+            return false if name.nil? || name.empty?
+
+            MOVE_TO_ROOT_ALIASES.include?(name.downcase)
+          end
+
+          # Check if a name is a virtual filter
+          # @param name [String] The name to check
+          # @return [Symbol, nil] :next, :all, or nil
+          def self.virtual_filter?(name)
+            return nil if name.nil? || name.empty?
+
+            VIRTUAL_FILTERS[name.downcase]
+          end
+
+          # Detect if a folder name is a special folder
+          # @param folder_name [String] The folder name to check
+          # @param prefix [String] The prefix that marks special folders
+          # @return [Boolean] True if it's a special folder
+          def self.special?(folder_name, prefix: DEFAULT_PREFIX)
+            return false if folder_name.nil? || folder_name.empty?
+
+            folder_name.start_with?(prefix)
+          end
+
+          # Normalize a folder name to its canonical form
+          # Short names are expanded: "archive" => "_archive"
+          # Already-prefixed names are returned as-is
+          # Virtual filters are returned as-is (not expanded)
+          # @param folder_name [String] The folder name to normalize
+          # @param prefix [String] The prefix to prepend for expansion
+          # @return [String] Canonical folder name
+          def self.normalize(folder_name, prefix: DEFAULT_PREFIX)
+            return folder_name if folder_name.nil? || folder_name.empty?
+            return folder_name if folder_name.start_with?(prefix)
+            return folder_name if VIRTUAL_FILTERS.key?(folder_name.downcase)
+            return folder_name if folder_name.include?(File::SEPARATOR) || folder_name.include?("..")
+
+            "#{prefix}#{folder_name}"
+          end
+
+          # Strip the special folder prefix to get the short display name
+          # @param folder_name [String] The folder name (e.g. "_archive")
+          # @param prefix [String] The prefix to strip
+          # @return [String] Short name (e.g. "archive")
+          def self.short_name(folder_name, prefix: DEFAULT_PREFIX)
+            return folder_name if folder_name.nil? || folder_name.empty?
+
+            folder_name.delete_prefix(prefix)
+          end
+
+          # Extract the special folder from a path (if any)
+          # Returns the first path component that is a special folder
+          # @param path [String] File path to inspect
+          # @param root [String] Root path to make path relative
+          # @param prefix [String] The prefix that marks special folders
+          # @return [String, nil] Special folder name or nil
+          def self.detect_in_path(path, root: nil, prefix: DEFAULT_PREFIX)
+            check_path = if root
+              begin
+                Pathname.new(path).relative_path_from(Pathname.new(root)).to_s
+              rescue ArgumentError
+                path
+              end
+            else
+              path
+            end
+
+            parts = check_path.split(File::SEPARATOR).reject(&:empty?)
+            parts.find { |part| special?(part, prefix: prefix) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/stats_line_formatter.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "ansi_colors"
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Generic stats line builder for item lists.
+        # Produces a summary like: "Tasks: ○ 3 | ▶ 1 | ✓ 5 • 3 of 660"
+        class StatsLineFormatter
+          # @param label [String] e.g. "Tasks", "Ideas", "Retros"
+          # @param stats [Hash] Output of ItemStatistics.count_by (by :status)
+          # @param status_order [Array<String>] Ordered status keys to display
+          # @param status_icons [Hash<String,String>] Status → icon mapping
+          # @param folder_stats [Hash, nil] Output of ItemStatistics.count_by (by :special_folder)
+          # @param total_count [Integer, nil] Total items before folder filtering (enables "X of Y" display)
+          # @param global_folder_stats [Hash, nil] Folder name → count hash from full scan (always shown)
+          # @return [String] e.g. "Tasks: ○ 3 | ▶ 1 | ✓ 5 • 3 of 660"
+          def self.format(label:, stats:, status_order:, status_icons:, folder_stats: nil, total_count: nil, global_folder_stats: nil)
+            parts = []
+            status_order.each do |status|
+              count = stats[:by_field][status] || 0
+              next if count == 0
+
+              icon = status_icons[status] || status
+              parts << "#{icon} #{count}"
+            end
+
+            # Catch any statuses not in status_order (unknown/unexpected)
+            stats[:by_field].each do |status, count|
+              next if count == 0 || status_order.include?(status)
+
+              icon = status_icons[status] || status
+              parts << "#{icon} #{count}"
+            end
+
+            line = "#{label}: #{parts.join(" | ")}"
+
+            shown = stats[:total]
+            total = total_count || shown
+
+            if shown < total
+              # Filtered view: show ratio
+              line += " \u2022 #{shown} of #{total}"
+            else
+              # Full view: show total
+              line += " \u2022 #{shown} total"
+              # Inline folder breakdown from current results (only when unfiltered
+              # and global_folder_stats not provided — global takes precedence)
+              if !global_folder_stats && folder_stats && folder_stats[:by_field].size > 1
+                folder_parts = folder_stats[:by_field]
+                  .sort_by { |_, count| -count }
+                  .map { |folder, count| "#{folder_label(folder)} #{count}" }
+                suffix = " \u2014 #{folder_parts.join(" | ")}"
+                line += AnsiColors.colorize(suffix, AnsiColors::DIM)
+              end
+            end
+
+            # Global folder breakdown (always shown when provided and multi-folder)
+            if global_folder_stats && global_folder_stats.size > 1
+              global_parts = global_folder_stats
+                .sort_by { |_, count| -count }
+                .map { |folder, count| "#{folder_label(folder)} #{count}" }
+              suffix = " \u2014 #{global_parts.join(" | ")}"
+              line += AnsiColors.colorize(suffix, AnsiColors::DIM)
+            end
+
+            line
+          end
+
+          # Map special_folder values to display labels.
+          # nil (root items) renders as "next".
+          def self.folder_label(folder)
+            return "next" if folder.nil? || folder.empty? || folder == ""
+
+            SpecialFolderDetector.short_name(folder)
+          end
+
+          private_class_method :folder_label
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/title_extractor.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Extracts the first H1 heading from markdown body content.
+        class TitleExtractor
+          # Extract title from the first `# H1` heading in body content
+          # @param body [String] Markdown body content
+          # @return [String, nil] Extracted title or nil if none found
+          def self.extract(body)
+            return nil if body.nil? || body.empty?
+
+            match = body.match(/^#\s+(.+)$/)
+            match ? match[1].strip : nil
+          end
+        end
+      end
+    end
+  end
+end