ace-docs 0.31.0

data/lib/ace/docs/organisms/validator.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Ace
+  module Docs
+    module Organisms
+      # Validates documents against their declared rules
+      class Validator
+        def initialize(registry)
+          @registry = registry
+        end
+
+        # Validate a document against rules
+        # @param document [Document] Document to validate
+        # @param syntax [Boolean] Run syntax validation
+        # @param semantic [Boolean] Run semantic validation
+        # @return [Hash] Validation results
+        def validate_document(document, syntax: true, semantic: false)
+          errors = []
+          warnings = []
+
+          # Check frontmatter validity
+          if !document.managed?
+            errors << "Missing required frontmatter fields"
+          end
+
+          # Check max lines rule
+          if document.max_lines
+            line_count = document.content.lines.count
+            if line_count > document.max_lines
+              errors << "Exceeds max lines: #{line_count}/#{document.max_lines}"
+            end
+          end
+
+          # Check required sections
+          if document.required_sections.any?
+            missing_sections = check_sections(document)
+            if missing_sections.any?
+              errors << "Missing required sections: #{missing_sections.join(", ")}"
+            end
+          end
+
+          # Syntax validation (would delegate to external linters)
+          if syntax
+            syntax_results = validate_syntax(document)
+            errors.concat(syntax_results[:errors])
+            warnings.concat(syntax_results[:warnings])
+          end
+
+          # Semantic validation (would use LLM)
+          if semantic
+            semantic_results = validate_semantic(document)
+            errors.concat(semantic_results[:errors])
+            warnings.concat(semantic_results[:warnings])
+          end
+
+          {
+            valid: errors.empty?,
+            errors: errors,
+            warnings: warnings
+          }
+        end
+
+        private
+
+        def check_sections(document)
+          required = document.required_sections
+          content = document.content.downcase
+
+          missing = []
+          required.each do |section|
+            # Check for section as a header
+            unless content.include?("# #{section.downcase}") ||
+                content.include?("## #{section.downcase}")
+              missing << section
+            end
+          end
+
+          missing
+        end
+
+        def validate_syntax(document)
+          # TODO: Integrate with markdownlint or similar
+          {errors: [], warnings: []}
+        end
+
+        def validate_semantic(document)
+          # Build semantic validation prompt
+          keywords = document.context_keywords.any? ? document.context_keywords.join(", ") : "(none specified)"
+
+          prompt = <<~PROMPT
+            Validate this documentation for semantic accuracy and relevance.
+
+            Document Type: #{document.doc_type}
+            Purpose: #{document.purpose}
+            Keywords: #{keywords}
+
+            Content:
+            #{document.content}
+
+            Check for:
+            - Content matches stated purpose
+            - Information is accurate and up-to-date
+            - No contradictions or inconsistencies
+            - Appropriate depth for document type
+
+            Respond with:
+            VALID or INVALID on first line
+            Then list any issues as bullet points starting with "-"
+          PROMPT
+
+          # Call LLM using Ruby API
+          begin
+            response = call_llm_for_validation(prompt)
+            stdout = response[:text]
+          rescue => e
+            # Handle all errors (including when Ace::LLM is not loaded)
+            error_msg = if e.message.include?("not found") || e.message.include?("No model specified") || e.message.include?("uninitialized constant")
+              "Semantic validation unavailable (ace-llm configuration issue). Check ace-llm setup."
+            else
+              "Semantic validation error: #{e.message}"
+            end
+            return {errors: [error_msg], warnings: []}
+          end
+
+          # Parse LLM response
+          errors = []
+          warnings = []
+
+          if stdout.match?(/INVALID/i)
+            # Extract issues from response
+            # Skip the first line (VALID/INVALID) and collect issue lines
+            lines = stdout.strip.split("\n")
+            lines.each_with_index do |line, idx|
+              next if idx == 0 # Skip VALID/INVALID line
+              next if line.strip.empty?
+
+              if line.start_with?("-")
+                errors << line.sub(/^-\s*/, "").strip
+              end
+            end
+
+            # If no issues were extracted but marked INVALID, add generic error
+            if errors.empty?
+              errors << "Content validation failed - semantic issues detected"
+            end
+          end
+
+          {errors: errors, warnings: warnings}
+        end
+
+        # Call LLM for validation (protected for testing)
+        # @param prompt [String] The validation prompt
+        # @return [Hash] Response with :text key
+        def call_llm_for_validation(prompt)
+          Ace::LLM::QueryInterface.query(
+            "gflash",
+            prompt,
+            temperature: 0.3
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/prompts/compact_diff_prompt.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Ace
+  module Docs
+    module Prompts
+      # Builds prompts for LLM diff compaction
+      class CompactDiffPrompt
+        # Build a prompt for compacting a diff
+        # @param diff [String] The git diff to compact
+        # @param documents [Array<Document>] Documents being analyzed
+        # @return [String] Complete prompt for LLM
+        def self.build(diff, documents = [])
+          document_list = format_document_list(documents)
+
+          <<~PROMPT
+            # Task: Compact Git Diff for Documentation Updates
+
+            You are analyzing code changes to help update documentation. Your task is to compact the following git diff by removing noise while preserving all relevant details that might affect documentation.
+
+            ## Documents Being Updated
+            #{document_list}
+
+            ## Instructions
+
+            1. **REMOVE** (noise that doesn't affect documentation):
+               - Test file changes (test/, spec/, *_test.rb, *.test.*)
+               - Formatting-only changes (whitespace, indentation)
+               - Comment-only changes that don't alter functionality
+               - Version bumps in lock files (Gemfile.lock, package-lock.json)
+               - Generated files and build artifacts
+               - Minor refactors that don't change behavior
+
+            2. **KEEP** (relevant changes that affect documentation):
+               - New features, classes, methods, or commands
+               - Changed interfaces, parameters, or return values
+               - New or modified configuration options
+               - Architecture or structural changes
+               - Behavioral changes
+               - New dependencies or tools
+               - Error handling changes
+               - Performance improvements worth documenting
+               - Deprecations or removals
+
+            3. **ORGANIZE** the output by impact level:
+               - HIGH: New features, removed features, breaking changes
+               - MEDIUM: Interface changes, new options, behavioral changes
+               - LOW: Performance improvements, minor enhancements
+
+            ## Output Format
+
+            Provide a markdown report with:
+            - Summary section with key changes
+            - Sections organized by impact (HIGH/MEDIUM/LOW)
+            - For each change, include:
+              * Component/gem name
+              * Brief description
+              * Relevant files
+              * Which documents might need updates
+
+            ## Git Diff to Analyze
+
+            ```diff
+            #{diff}
+            ```
+
+            ## Response
+
+            Please provide the compacted analysis in markdown format.
+          PROMPT
+        end
+
+        # Build a prompt for analyzing changes without documents
+        # @param diff [String] The git diff to analyze
+        # @param since [String] Time period for the diff
+        # @return [String] Complete prompt for LLM
+        def self.build_general(diff, since: "recent changes")
+          <<~PROMPT
+            # Task: Analyze and Compact Git Diff
+
+            Analyze the following git diff from #{since} and provide a compacted summary suitable for documentation updates.
+
+            ## Instructions
+
+            1. Remove noise (tests, formatting, lock files)
+            2. Focus on changes that affect documentation
+            3. Organize by impact level (HIGH/MEDIUM/LOW)
+            4. Provide actionable insights for documentation updates
+
+            ## Git Diff
+
+            ```diff
+            #{diff}
+            ```
+
+            ## Response
+
+            Provide a structured markdown analysis with:
+            - Executive summary
+            - Significant changes by impact level
+            - Files and components affected
+            - Suggested documentation updates
+          PROMPT
+        end
+
+        private_class_method def self.format_document_list(documents)
+          return "No specific documents targeted" if documents.empty?
+
+          list = documents.map do |doc|
+            path = doc.respond_to?(:relative_path) ? doc.relative_path : doc.path
+            type = doc.respond_to?(:doc_type) ? " (#{doc.doc_type})" : ""
+            "- #{path}#{type}"
+          end
+
+          list.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/prompts/consistency_prompt.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+# Try to load ace-bundle for better document embedding
+begin
+  require "ace/bundle"
+rescue LoadError
+  # Will work without ace-bundle but with less optimal formatting
+end
+
+module Ace
+  module Docs
+    module Prompts
+      # Builds prompts for cross-document consistency analysis
+      class ConsistencyPrompt
+        # Build the complete prompt for consistency analysis
+        # @param documents [Hash] hash of { path => content } for documents to analyze
+        # @param options [Hash] analysis options
+        # @param session_dir [String, nil] session directory for saving context.md
+        # @return [Hash] { system: String, user: String } prompts
+        def build(documents, options = {}, session_dir: nil)
+          # Use ace-bundle if available for better document separation
+          user_content = if defined?(Ace::Bundle) && session_dir
+            build_with_context(documents, options, session_dir)
+          else
+            user_prompt(documents, options)
+          end
+
+          {
+            system: system_prompt,
+            user: user_content
+          }
+        end
+
+        private
+
+        # Generate the system prompt with analysis instructions
+        def system_prompt
+          <<~PROMPT
+            You are a documentation consistency analyzer. Analyze the provided documents for consistency issues.
+
+            ## Analysis Types
+
+            1. **TERMINOLOGY CONFLICTS**: Inconsistent word usage
+               - Different words for the same concept (e.g., "gem" vs "package" in Ruby context)
+               - Spelling variations (US vs UK: "analyze" vs "analyse", "color" vs "colour")
+               - Case inconsistencies (e.g., "GitHub" vs "github" vs "Github")
+               - Technical term variations (e.g., "LLM" vs "large language model")
+
+            2. **DUPLICATE CONTENT**: Similar or identical content blocks
+               - Identify content that appears in multiple documents with >70% similarity
+               - Flag redundant explanations of the same concept
+               - Note which document should be the authoritative source
+
+            3. **VERSION INCONSISTENCIES**: Mismatched version numbers
+               - Different version numbers for the same tool/library
+               - Outdated references in some documents
+               - Inconsistent release information
+
+            4. **CONSOLIDATION OPPORTUNITIES**: Content that could be merged
+               - Multiple documents explaining the same workflow
+               - Scattered information that belongs together
+               - Overlapping guides that could be combined
+
+            ## Response Format
+
+            Return ONLY valid JSON in this exact structure:
+
+            ```json
+            {
+              "terminology_conflicts": [
+                {
+                  "terms": ["term1", "term2"],
+                  "occurrences": {
+                    "term1": [
+                      {"file": "path/to/file1.md", "count": 5, "examples": ["line excerpt 1", "line excerpt 2"]},
+                      {"file": "path/to/file2.md", "count": 3, "examples": ["line excerpt"]}
+                    ],
+                    "term2": [
+                      {"file": "path/to/file3.md", "count": 8, "examples": ["line excerpt"]}
+                    ]
+                  },
+                  "recommendation": "Standardize to 'term1' (Ruby ecosystem convention)"
+                }
+              ],
+              "duplicate_content": [
+                {
+                  "description": "Installation instructions",
+                  "similarity_percentage": 85,
+                  "locations": [
+                    {"file": "README.md", "lines": "45-67", "excerpt": "first 50 chars..."},
+                    {"file": "docs/getting-started.md", "lines": "12-34", "excerpt": "first 50 chars..."}
+                  ],
+                  "recommendation": "Keep in getting-started.md, reference from README"
+                }
+              ],
+              "version_inconsistencies": [
+                {
+                  "item": "ace-docs version",
+                  "versions_found": [
+                    {"version": "0.4.5", "file": "README.md", "line": 12},
+                    {"version": "0.4.6", "file": "CHANGELOG.md", "line": 5},
+                    {"version": "0.4.4", "file": "docs/api.md", "line": 23}
+                  ],
+                  "recommendation": "Update all to 0.4.6 (latest in CHANGELOG)"
+                }
+              ],
+              "consolidation_opportunities": [
+                {
+                  "topic": "Workflow instructions for updating documents",
+                  "documents": [
+                    {"file": "docs/update-workflow.md", "coverage": "comprehensive"},
+                    {"file": "docs/quick-update.md", "coverage": "basic steps"},
+                    {"file": "README.md", "coverage": "brief mention in section 'Updating Documents'"}
+                  ],
+                  "recommendation": "Consolidate into single workflow document with quick-start section"
+                }
+              ]
+            }
+            ```
+
+            ## Analysis Guidelines
+
+            - For terminology: Consider context (Ruby gems vs npm packages)
+            - For duplicates: Use the similarity threshold provided (default 70%)
+            - For versions: Check semantic versioning and identify the most recent
+            - For consolidation: Consider user journey and information architecture
+            - Always provide actionable, specific recommendations
+            - Include file paths and line numbers when possible
+            - Provide brief excerpts to illustrate the issues
+          PROMPT
+        end
+
+        # Generate the user prompt with document content and parameters
+        def user_prompt(documents, options)
+          threshold = options[:threshold] || 70
+          focus_areas = build_focus_areas(options)
+
+          <<~PROMPT
+            Analyze these #{documents.count} documents for consistency issues:
+
+            ## Documents to Analyze
+
+            #{format_documents(documents)}
+
+            ## Analysis Parameters
+
+            - Similarity threshold for duplicates: #{threshold}%
+            - Focus areas: #{focus_areas.join(", ")}
+            #{"- Pattern filter: #{options[:pattern]}" if options[:pattern]}
+
+            ## Instructions
+
+            1. Scan all documents for the four types of consistency issues
+            2. Apply the similarity threshold of #{threshold}% for duplicate detection
+            3. Provide specific, actionable recommendations for each issue
+            4. Include file paths and line references where applicable
+            5. Return results in the exact JSON format specified
+
+            Analyze the documents now and return the JSON results.
+          PROMPT
+        end
+
+        # Format documents for inclusion in the prompt
+        def format_documents(documents)
+          documents.map do |path, content|
+            # Extract frontmatter if present
+            frontmatter = extract_frontmatter(content)
+
+            # Truncate very long documents
+            truncated_content = truncate_content(content)
+
+            <<~DOC
+              ### File: #{path}
+              #{"Frontmatter: #{frontmatter.to_json}\n" if frontmatter}
+              ```
+              #{truncated_content}
+              ```
+            DOC
+          end.join("\n")
+        end
+
+        # Extract YAML frontmatter from content
+        def extract_frontmatter(content)
+          return nil unless content.start_with?("---\n")
+
+          parts = content.split(/^---\s*$/, 3)
+          return nil unless parts.size >= 2
+
+          begin
+            require "yaml"
+            YAML.safe_load(parts[1])
+          rescue
+            nil
+          end
+        end
+
+        # Truncate content if it's too long
+        def truncate_content(content, max_lines = 500)
+          lines = content.lines
+          return content if lines.size <= max_lines
+
+          truncated = lines.first(max_lines).join
+          truncated + "\n... (truncated, #{lines.size - max_lines} lines omitted) ..."
+        end
+
+        # Build focus areas based on options
+        def build_focus_areas(options)
+          areas = []
+
+          if options[:all] || (!options[:terminology] && !options[:duplicates] && !options[:versions])
+            areas = ["terminology conflicts", "duplicate content", "version inconsistencies", "consolidation opportunities"]
+          else
+            areas << "terminology conflicts" if options[:terminology]
+            areas << "duplicate content" if options[:duplicates]
+            areas << "version inconsistencies" if options[:versions]
+          end
+
+          areas.empty? ? ["all issue types"] : areas
+        end
+
+        # Build user prompt with ace-bundle for better document separation
+        def build_with_context(documents, options, session_dir)
+          # Use the actual document paths directly (no copying needed)
+          doc_files = documents.keys.map { |path| File.expand_path(path) }
+
+          # Create context.md with frontmatter and instructions
+          threshold = options[:threshold] || 70
+          focus_areas = build_focus_areas(options)
+
+          # Build context configuration
+          context_config = {
+            "params" => {"format" => "markdown-xml"},
+            "embed_document_source" => true,
+            "files" => doc_files
+          }
+
+          # Create frontmatter
+          frontmatter = {"context" => context_config}
+
+          # Build instructions
+          instructions = <<~INSTRUCTIONS
+            # Cross-Document Consistency Analysis
+
+            Analyze these #{documents.count} documents for consistency issues.
+
+            ## Analysis Parameters
+
+            - Similarity threshold for duplicates: #{threshold}%
+            - Focus areas: #{focus_areas.join(", ")}
+            #{"- Pattern filter: #{options[:pattern]}" if options[:pattern]}
+
+            ## Instructions
+
+            1. Scan all documents for the four types of consistency issues
+            2. Apply the similarity threshold of #{threshold}% for duplicate detection
+            3. Provide specific, actionable recommendations for each issue
+            4. Include file paths and line references where applicable
+            5. Return results in the exact JSON format specified
+
+            ## Documents
+
+            The following documents are embedded below using XML tags:
+          INSTRUCTIONS
+
+          # Create context.md
+          context_md_content = "#{YAML.dump(frontmatter).strip}\n---\n\n#{instructions}"
+          context_md_path = File.join(session_dir, "context.md")
+          File.write(context_md_path, context_md_content)
+
+          # Load via ace-bundle to get XML-embedded documents
+          begin
+            result = Ace::Bundle.load_file(context_md_path)
+            result.content
+          rescue => e
+            warn "ace-bundle embedding failed: #{e.message}, falling back to direct format" if Ace::Docs.debug?
+            # Fallback to regular prompt if ace-bundle fails
+            user_prompt(documents, options)
+          end
+        end
+      end
+    end
+  end
+end