ace-docs 0.31.0

data/lib/ace/docs/atoms/terminology_extractor.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module Ace
+  module Docs
+    module Atoms
+      # Extracts and analyzes terminology from documents to find conflicts
+      class TerminologyExtractor
+        # Common words to exclude from terminology analysis
+        COMMON_WORDS = %w[
+          a an and are as at be but by for from has have i in is it of on or
+          that the this to was will with you your we our us their them they
+          can could should would may might must shall will do does did done
+          get got gets getting make makes made making take takes took taken
+          use uses used using go goes went gone going come comes came coming
+          see sees saw seen seeing know knows knew known knowing think thinks
+          thought thinking want wants wanted wanting need needs needed needing
+          give gives gave given giving find finds found finding tell tells told
+          telling work works worked working call calls called calling try tries
+          tried trying ask asks asked asking feel feels felt feeling become
+          becomes became becoming leave leaves left leaving put puts putting
+          keep keeps kept keeping let lets letting begin begins began beginning
+          seem seems seemed seeming help helps helped helping talk talks talked
+          talking turn turns turned turning start starts started starting show
+          shows showed shown showing hear hears heard hearing play plays played
+          playing run runs ran running move moves moved moving like likes liked
+          liking live lives lived living believe believes believed believing
+          bring brings brought bringing happen happens happened happening write
+          writes wrote written writing provide provides provided providing sit
+          sits sat sitting stand stands stood standing lose loses lost losing
+          pay pays paid paying meet meets met meeting include includes included
+          including continue continues continued continuing set sets setting
+          learn learns learned learning change changes changed changing lead
+          leads led leading understand understands understood understanding
+          watch watches watched watching follow follows followed following stop
+          stops stopped stopping create creates created creating speak speaks
+          spoke spoken speaking read reads reading allow allows allowed allowing
+          add adds added adding spend spends spent spending grow grows grew
+          grown growing open opens opened opening walk walks walked walking win
+          wins won winning offer offers offered offering remember remembers
+          remembered remembering love loves loved loving consider considers
+          considered considering appear appears appeared appearing buy buys
+          bought buying wait waits waited waiting serve serves served serving
+          die dies died dying send sends sent sending expect expects expected
+          expecting build builds built building stay stays stayed staying fall
+          falls fell fallen falling cut cuts cutting reach reaches reached
+          reaching kill kills killed killing remain remains remained remaining
+          suggest suggests suggested suggesting raise raises raised raising
+          pass passes passed passing sell sells sold selling require requires
+          required requiring report reports reported reporting decide decides
+          decided deciding pull pulls pulled pulling one two three four five
+          six seven eight nine ten first second third last next new old good
+          bad best worst more most less least very much many few some any all
+          no not yes other another each every either neither both such own same
+          different various certain several many most few little much enough
+          only just still already yet even also too quite rather almost nearly
+          always usually often sometimes rarely never again further then once
+          now here there where when why how what which who whom whose if unless
+          until while although though because since before after during within
+          without through across beyond behind below beneath beside between
+          above over under around among against along toward towards upon down
+          up out off away back forward backward forwards backwards inside
+          outside onto into about for from with without by at in on to as of
+        ].freeze
+
+        # Extract key terms from document content with frequency counts
+        # @param content [String] the document content
+        # @param doc_path [String] the document path for reference
+        # @return [Hash] terms with their frequencies and locations
+        def extract_terms(content, doc_path = nil)
+          terms = {}
+          lines = content.lines
+
+          lines.each_with_index do |line, index|
+            # Skip code blocks and front matter
+            next if line.strip.start_with?("```", "---")
+
+            # Extract words and normalize them
+            words = line.downcase.scan(/\b[a-z]+(?:-[a-z]+)*\b/)
+
+            words.each do |word|
+              # Skip common words and very short words
+              next if COMMON_WORDS.include?(word) || word.length < 3
+
+              # Track term frequency and locations
+              terms[word] ||= {count: 0, locations: [], variations: Set.new}
+              terms[word][:count] += 1
+              terms[word][:locations] << {file: doc_path, line: index + 1}
+
+              # Track original variations (case)
+              original = line[/\b#{Regexp.escape(word)}\b/i]
+              terms[word][:variations] << original if original
+            end
+          end
+
+          # Filter to meaningful terms (appears multiple times or has variations)
+          terms.select do |_term, data|
+            data[:count] > 1 || data[:variations].size > 1
+          end
+        end
+
+        # Find terminology conflicts across multiple documents
+        # @param documents [Hash] hash of { path => content }
+        # @return [Array] array of conflict hashes
+        def find_conflicts(documents)
+          all_terms = {}
+          conflicts = []
+
+          # Extract terms from each document
+          documents.each do |path, content|
+            doc_terms = extract_terms(content, path)
+
+            doc_terms.each do |term, data|
+              all_terms[term] ||= {}
+              all_terms[term][path] = data
+            end
+          end
+
+          # Find similar terms that might be conflicts
+          term_list = all_terms.keys
+
+          term_list.each_with_index do |term1, i|
+            term_list[(i + 1)..-1].each do |term2|
+              similarity = calculate_similarity(term1, term2)
+
+              # Check for potential conflicts (similar but not identical)
+              if similarity > 0.7 && similarity < 1.0
+                conflicts << build_conflict(term1, term2, all_terms)
+              elsif are_variants?(term1, term2)
+                conflicts << build_conflict(term1, term2, all_terms)
+              end
+            end
+          end
+
+          # Also find inconsistent usage of the same base term
+          find_inconsistent_usage(all_terms, conflicts)
+
+          conflicts.compact
+        end
+
+        # Filter out common words from a list of terms
+        # @param terms [Array] list of terms to filter
+        # @return [Array] filtered list without common words
+        def filter_common_words(terms)
+          terms.reject { |term| COMMON_WORDS.include?(term.downcase) }
+        end
+
+        private
+
+        # Calculate similarity between two terms (simple Levenshtein-like)
+        def calculate_similarity(term1, term2)
+          return 1.0 if term1 == term2
+
+          # Normalize comparison
+          t1 = term1.downcase
+          t2 = term2.downcase
+
+          # Check for plural/singular variants
+          return 0.95 if t1 == "#{t2}s" || t2 == "#{t1}s"
+          return 0.95 if t1 == "#{t2}es" || t2 == "#{t1}es"
+          return 0.95 if t1.end_with?("y") && t2 == t1[0...-1] + "ies"
+          return 0.95 if t2.end_with?("y") && t1 == t2[0...-1] + "ies"
+
+          # Check for common variations
+          return 0.9 if one_char_diff?(t1, t2)
+
+          # Otherwise, calculate based on common characters
+          common_chars = (t1.chars & t2.chars).size
+          max_length = [t1.length, t2.length].max.to_f
+          common_chars / max_length
+        end
+
+        # Check if two terms are known variants
+        def are_variants?(term1, term2)
+          variants = {
+            "analyze" => "analyse",
+            "organize" => "organise",
+            "recognize" => "recognise",
+            "realize" => "realise",
+            "color" => "colour",
+            "behavior" => "behaviour",
+            "center" => "centre",
+            "fiber" => "fibre",
+            "license" => "licence"
+          }
+
+          variants.any? do |us, uk|
+            (term1.include?(us) && term2.include?(uk)) ||
+              (term1.include?(uk) && term2.include?(us))
+          end
+        end
+
+        # Check if terms differ by only one character
+        def one_char_diff?(term1, term2)
+          return false if (term1.length - term2.length).abs > 1
+
+          if term1.length == term2.length
+            diff_count = 0
+            term1.chars.each_with_index do |char, i|
+              diff_count += 1 if char != term2[i]
+            end
+            diff_count == 1
+          else
+            # Check for single insertion/deletion
+            longer = (term1.length > term2.length) ? term1 : term2
+            shorter = (term1.length > term2.length) ? term2 : term1
+
+            longer.length.times do |i|
+              test = longer[0...i] + longer[(i + 1)..-1]
+              return true if test == shorter
+            end
+            false
+          end
+        end
+
+        # Build a conflict report entry
+        def build_conflict(term1, term2, all_terms)
+          docs1 = all_terms[term1]&.keys || []
+          docs2 = all_terms[term2]&.keys || []
+
+          return nil if docs1.empty? || docs2.empty?
+
+          {
+            type: "terminology",
+            terms: [term1, term2],
+            documents: {
+              term1 => docs1.map { |doc|
+                {
+                  file: doc,
+                  count: all_terms[term1][doc][:count]
+                }
+              },
+              term2 => docs2.map { |doc|
+                {
+                  file: doc,
+                  count: all_terms[term2][doc][:count]
+                }
+              }
+            },
+            recommendation: suggest_standardization(term1, term2, all_terms)
+          }
+        end
+
+        # Find inconsistent usage of the same base term
+        def find_inconsistent_usage(all_terms, conflicts)
+          all_terms.each do |term, docs|
+            next unless docs.size > 1
+
+            # Check if the same term has very different case variations
+            all_variations = docs.values.flat_map { |d| d[:variations].to_a }
+            unique_variations = all_variations.uniq
+
+            if unique_variations.size > 1 && significantly_different_cases?(unique_variations)
+              conflicts << {
+                type: "case_inconsistency",
+                term: term,
+                variations: unique_variations,
+                documents: docs.map { |path, data|
+                  {
+                    file: path,
+                    variations: data[:variations].to_a,
+                    count: data[:count]
+                  }
+                },
+                recommendation: "Standardize capitalization of '#{term}' across documents"
+              }
+            end
+          end
+        end
+
+        # Check if case variations are significantly different
+        def significantly_different_cases?(variations)
+          patterns = variations.map { |v| categorize_case(v) }.uniq
+          patterns.size > 1
+        end
+
+        # Categorize the case pattern of a word
+        def categorize_case(word)
+          return :lower if word == word.downcase
+          return :upper if word == word.upcase
+          return :title if word == word.capitalize
+          :mixed
+        end
+
+        # Suggest which term to standardize on
+        def suggest_standardization(term1, term2, all_terms)
+          # Prefer the more frequently used term
+          count1 = all_terms[term1]&.values&.sum { |d| d[:count] } || 0
+          count2 = all_terms[term2]&.values&.sum { |d| d[:count] } || 0
+
+          if count1 > count2 * 2
+            "Standardize to '#{term1}' (used #{count1} times vs #{count2})"
+          elsif count2 > count1 * 2
+            "Standardize to '#{term2}' (used #{count2} times vs #{count1})"
+          elsif are_variants?(term1, term2)
+            # Check for US vs UK spelling
+            if term1.include?("z") || term1.include?("or")
+              "Standardize to '#{term1}' (US spelling)"
+            else
+              "Standardize to '#{term2}' (UK spelling)"
+            end
+          else
+            "Consider standardizing to '#{(count1 >= count2) ? term1 : term2}'"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/atoms/time_range_calculator.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Ace
+  module Docs
+    module Atoms
+      # Pure function for time range calculations
+      class TimeRangeCalculator
+        class << self
+          # Calculate a git-compatible "since" string from a date
+          # @param date [Date, Time, String] The date to calculate from
+          # @return [String] Git-compatible since string (e.g., "2 weeks ago")
+          def calculate_since(date)
+            return date if date.is_a?(String) && date.match?(/^\d+\s+(days?|weeks?|months?)\s+ago$/)
+
+            parsed_date = parse_date(date)
+            days_ago = (Date.today - parsed_date.to_date).to_i
+
+            format_days_ago(days_ago)
+          end
+
+          # Parse a date from various formats
+          # @param date_string [String, Date, Time] Date in various formats
+          # @return [Date] Parsed date
+          def parse_date(date_string)
+            return date_string if date_string.is_a?(Date)
+            return date_string.to_date if date_string.is_a?(Time)
+
+            # Handle various string formats
+            case date_string
+            when /^today$/i
+              Date.today
+            when /^yesterday$/i
+              Date.today - 1
+            when /^(\d+)\s+days?\s+ago$/i
+              Date.today - Regexp.last_match(1).to_i
+            when /^(\d+)\s+weeks?\s+ago$/i
+              Date.today - (Regexp.last_match(1).to_i * 7)
+            when /^(\d+)\s+months?\s+ago$/i
+              Date.today << Regexp.last_match(1).to_i
+            when /^\d{4}-\d{2}-\d{2}$/
+              Date.parse(date_string)
+            else
+              # Try to parse with Date.parse as fallback
+              Date.parse(date_string)
+            end
+          rescue ArgumentError => e
+            raise ArgumentError, "Invalid date format: #{date_string}. Error: #{e.message}"
+          end
+
+          # Format a date for human-readable display
+          # @param date [Date, Time] Date to format
+          # @return [String] Human-readable date (e.g., "2 weeks ago", "3 days ago")
+          def format_human(date)
+            parsed_date = parse_date(date)
+            days_ago = (Date.today - parsed_date).to_i
+
+            format_days_ago(days_ago)
+          end
+
+          private
+
+          # Format days into human-readable time ago string
+          def format_days_ago(days)
+            case days
+            when 0
+              "today"
+            when 1
+              "yesterday"
+            when 2..6
+              "#{days} days ago"
+            when 7..13
+              "1 week ago"
+            when 14..20
+              "2 weeks ago"
+            when 21..29
+              "3 weeks ago"
+            when 30..59
+              "1 month ago"
+            when 60..89
+              "2 months ago"
+            when 90..179
+              "3 months ago"
+            when 180..364
+              "6 months ago"
+            else
+              "#{(days / 365.0).round} years ago"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/atoms/timestamp_parser.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Ace
+  module Docs
+    module Atoms
+      # Pure timestamp parsing and validation functions
+      # Supports ISO 8601 UTC and date-only formats
+      #
+      # Timezone Behavior:
+      #   - ISO 8601 UTC format (YYYY-MM-DDTHH:MM:SSZ) is the recommended format
+      #   - Date-only format (YYYY-MM-DD) remains timezone-agnostic
+      #
+      # Return Types:
+      #   - Date-only strings → Date objects
+      #   - ISO 8601 UTC strings → Time objects (in UTC)
+      #   This polymorphic return type preserves the precision of the input format.
+      module TimestampParser
+        # Regular expression patterns for timestamp validation
+        DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+        ISO8601_UTC_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/
+
+        # Parse a timestamp string to Date or Time object
+        # @param value [String, Date, Time] Timestamp to parse
+        # @return [Date, Time] Parsed timestamp
+        # @raise [ArgumentError] If format is invalid
+        def self.parse_timestamp(value)
+          raise ArgumentError, "Cannot parse nil timestamp" if value.nil?
+
+          # Return already parsed objects as-is
+          return value if value.is_a?(Date) || value.is_a?(Time)
+
+          # Must be a string at this point
+          raise ArgumentError, "Timestamp must be a String, Date, or Time" unless value.is_a?(String)
+
+          # Validate format before parsing
+          unless validate_format(value)
+            raise ArgumentError, "Invalid timestamp format. Use YYYY-MM-DDTHH:MM:SSZ (ISO 8601 UTC) or YYYY-MM-DD"
+          end
+
+          # Parse based on format
+          if value.match?(ISO8601_UTC_PATTERN)
+            parse_iso8601_utc(value)
+          elsif value.match?(DATE_ONLY_PATTERN)
+            parse_date(value)
+          else
+            raise ArgumentError, "Invalid timestamp format. Use YYYY-MM-DDTHH:MM:SSZ (ISO 8601 UTC) or YYYY-MM-DD"
+          end
+        rescue Date::Error, ArgumentError => e
+          # Improve error message for date parsing errors
+          raise ArgumentError, "Invalid timestamp: #{e.message}"
+        end
+
+        # Validate timestamp format
+        # @param value [String] Timestamp string to validate
+        # @return [Boolean] true if format is valid
+        def self.validate_format(value)
+          return false if value.nil? || !value.is_a?(String) || value.empty?
+
+          value.match?(DATE_ONLY_PATTERN) || value.match?(ISO8601_UTC_PATTERN)
+        end
+
+        # Format a Date or Time object to string
+        # @param time_obj [Date, Time] Object to format
+        # @return [String] Formatted timestamp in ISO 8601 UTC format (for Time) or date-only (for Date)
+        # @raise [ArgumentError] If object is not Date or Time
+        def self.format_timestamp(time_obj)
+          raise ArgumentError, "Cannot format nil timestamp" if time_obj.nil?
+
+          case time_obj
+          when Date
+            time_obj.strftime("%Y-%m-%d")
+          when Time
+            time_obj.utc.strftime("%Y-%m-%dT%H:%M:%SZ")  # ISO 8601 UTC format
+          else
+            raise ArgumentError, "Timestamp must be a Date or Time object"
+          end
+        end
+
+        private
+
+        # Parse date-only string
+        # @param date_str [String] Date string in YYYY-MM-DD format
+        # @return [Date] Parsed date
+        # @raise [ArgumentError] If date is invalid
+        def self.parse_date(date_str)
+          Date.parse(date_str)
+        rescue Date::Error => e
+          raise ArgumentError, "Invalid date: #{e.message}"
+        end
+
+        # Parse ISO 8601 UTC datetime string
+        # @param iso8601_str [String] ISO 8601 datetime string in YYYY-MM-DDTHH:MM:SSZ format
+        # @return [Time] Parsed time in UTC
+        # @raise [ArgumentError] If datetime is invalid
+        def self.parse_iso8601_utc(iso8601_str)
+          Time.parse(iso8601_str).utc  # Ensure UTC
+        rescue ArgumentError => e
+          raise ArgumentError, "Invalid ISO 8601 datetime: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/atoms/type_inferrer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Ace
+  module Docs
+    module Atoms
+      # Infers document type from file extension and patterns
+      # with configurable priority hierarchy
+      class TypeInferrer
+        # Map of file extensions to document types
+        EXTENSION_MAP = {
+          ".wf.md" => "workflow",
+          ".g.md" => "guide",
+          ".template.md" => "template",
+          ".api.md" => "api"
+        }.freeze
+
+        # Infer type from file extension
+        # @param path [String] File path
+        # @return [String, nil] Document type or nil
+        def self.from_extension(path)
+          EXTENSION_MAP.each do |ext, type|
+            return type if path.end_with?(ext)
+          end
+          nil
+        end
+
+        # Resolve document type using priority hierarchy:
+        # 1. Explicit frontmatter doc-type (highest priority)
+        # 2. Config pattern type
+        # 3. README basename inference
+        # 4. File extension inference (lowest priority)
+        #
+        # @param path [String] File path
+        # @param pattern_type [String, nil] Type from config pattern matching
+        # @param frontmatter_type [String, nil] Explicit doc-type from frontmatter
+        # @return [String, nil] Resolved document type
+        def self.resolve(path, pattern_type: nil, frontmatter_type: nil)
+          # Priority 1: Explicit frontmatter (overrides everything)
+          return frontmatter_type if frontmatter_type && !frontmatter_type.empty?
+
+          # Priority 2: Config pattern type
+          return pattern_type if pattern_type && !pattern_type.empty?
+
+          # Priority 3: Basename inference
+          if File.basename(path).casecmp("README.md").zero?
+            return "root_readme" if root_readme?(path)
+
+            return "readme"
+          end
+
+          # Priority 4: Extension-based inference
+          extension_type = from_extension(path)
+          return extension_type if extension_type
+
+          nil
+        end
+
+        def self.root_readme?(path)
+          normalized = path.to_s.sub(%r{\A\./}, "")
+          return true if normalized.casecmp("README.md").zero?
+
+          File.expand_path(path.to_s) == File.join(Dir.pwd, "README.md")
+        rescue
+          false
+        end
+        private_class_method :root_readme?
+      end
+    end
+  end
+end