ace-docs 0.31.0

data/lib/ace/docs/cli/commands/status.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require "terminal-table"
+require "colorize"
+require_relative "../../organisms/document_registry"
+require_relative "scope_options"
+
+module Ace
+  module Docs
+    module CLI
+      module Commands
+        # ace-support-cli Command class for the status command
+        #
+        # This command shows document freshness and update status.
+        class Status < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include ScopeOptions
+
+          desc <<~DESC.strip
+            Show status of all managed documents
+
+            Display status information for all documents tracked by ace-docs,
+            including freshness, update status, and document metadata.
+
+            Configuration:
+              Global config:  ~/.ace/docs/config.yml
+              Project config: .ace/docs/config.yml
+              Example:        ace-docs/.ace-defaults/docs/config.yml
+
+            Output:
+              Table format with columns: path, type, status, last-updated
+              Exit codes: 0 (success), 1 (error)
+          DESC
+
+          example [
+            "                             # All tracked documents",
+            "--type handbook              # Filter by document type",
+            "--needs-update               # Show only documents needing update",
+            "--freshness stale            # Filter by freshness status",
+            "--freshness current          # Filter by freshness status",
+            "--package ace-docs           # Scope to one package",
+            "--glob 'ace-docs/**/*.md'    # Scope by glob"
+          ]
+
+          option :type, type: :string, desc: "Filter by document type"
+          option :needs_update, type: :boolean, desc: "Show only documents needing update"
+          option :freshness, type: :string, desc: "Filter by freshness status (current/stale/outdated)"
+          option :package, type: :array, desc: "Scope to package(s), e.g. --package ace-docs"
+          option :glob, type: :array, desc: "Scope by glob(s), e.g. --glob 'ace-docs/**/*.md'"
+
+          # Standard options
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(**options)
+            execute_status(options)
+          end
+
+          private
+
+          def execute_status(options)
+            registry = create_registry(options)
+            documents = filter_documents(registry, options)
+
+            if documents.empty?
+              warn "No managed documents found."
+              return
+            end
+
+            display_status(documents)
+            display_summary(documents, registry)
+          rescue => e
+            warn "Error showing status: #{e.message}"
+            warn e.backtrace.join("\n") if debug?(options)
+            raise Ace::Support::Cli::Error.new(e.message)
+          end
+
+          def create_registry(options)
+            project_root = options[:project_root]
+            scope_globs = normalized_scope_globs(options, project_root: project_root)
+
+            Ace::Docs::Organisms::DocumentRegistry.new(
+              project_root: project_root,
+              scope_globs: scope_globs
+            )
+          end
+
+          def filter_documents(registry, options)
+            documents = registry.all
+
+            # Filter by type if specified
+            if options[:type]
+              documents = documents.select { |doc| doc.doc_type == options[:type] }
+            end
+
+            # Filter by needs-update if specified
+            if options[:needs_update]
+              documents = documents.select(&:needs_update?)
+            end
+
+            # Filter by freshness if specified
+            if options[:freshness]
+              status = options[:freshness].to_sym
+              documents = documents.select { |doc| doc.freshness_status == status }
+            end
+
+            documents.sort_by(&:path)
+          end
+
+          def display_status(documents)
+            # Group documents by directory
+            grouped = documents.group_by { |doc| File.dirname(doc.relative_path || doc.path) }
+
+            puts "\nManaged Documents (#{documents.size} found)\n"
+
+            grouped.each do |group_name, group_docs|
+              puts "\n#{format_group_name(group_name)}:".cyan
+              display_group_table(group_docs)
+            end
+          end
+
+          def display_group_table(documents)
+            rows = documents.map do |doc|
+              [
+                status_icon(doc),
+                doc.display_name,
+                doc.doc_type || "-",
+                format_date(doc.last_updated),
+                freshness_indicator(doc)
+              ]
+            end
+
+            table = Terminal::Table.new do |t|
+              t.headings = ["", "Document", "Type", "Last Updated", "Status"]
+              t.rows = rows
+              t.style = {border_top: false, border_bottom: false}
+            end
+
+            puts table
+          end
+
+          def display_summary(documents, registry)
+            stats = registry.stats
+            needs_update = documents.count(&:needs_update?)
+
+            puts "\nSummary:"
+            puts "  Total: #{documents.size} documents"
+            puts "  Needing update: #{needs_update}".yellow if needs_update > 0
+
+            # Show by type
+            if stats[:by_type].any?
+              puts "  By type:"
+              stats[:by_type].each do |type, count|
+                puts "    #{type}: #{count}"
+              end
+            end
+
+            # Show by freshness
+            freshness_counts = documents.group_by(&:freshness_status).transform_values(&:size)
+            if freshness_counts.any?
+              puts "  By freshness:"
+              freshness_counts.each do |status, count|
+                color = case status
+                when :current then :green
+                when :stale then :yellow
+                when :outdated then :red
+                else :white
+                end
+                puts "    #{status}: #{count}".colorize(color)
+              end
+            end
+          end
+
+          def status_icon(doc)
+            case doc.freshness_status
+            when :current
+              "✓".green
+            when :stale
+              "⚠".yellow
+            when :outdated
+              "✗".red
+            else
+              "?".light_black
+            end
+          end
+
+          def format_date(date)
+            return "-" unless date
+
+            # Normalize Time to Date for age calculation
+            date_for_calc = date.is_a?(Time) ? date.to_date : date
+            days_ago = (Date.today - date_for_calc).to_i
+
+            # Display with time component when available (ISO 8601 for Time objects)
+            date_str = if date.respond_to?(:hour)
+              date.utc.strftime("%Y-%m-%dT%H:%M:%SZ")  # ISO 8601 UTC
+            else
+              date.strftime("%Y-%m-%d")  # Date-only
+            end
+
+            if days_ago == 0
+              "#{date_str} (today)".green
+            elsif days_ago == 1
+              "#{date_str} (1d ago)".green
+            elsif days_ago <= 7
+              "#{date_str} (#{days_ago}d ago)".yellow
+            else
+              "#{date_str} (#{days_ago}d ago)".red
+            end
+          end
+
+          def freshness_indicator(doc)
+            if doc.needs_update?
+              "needs update".red
+            elsif doc.freshness_status == :current
+              "current"
+            elsif doc.freshness_status == :stale
+              "getting stale".yellow
+            else
+              doc.freshness_status.to_s
+            end
+          end
+
+          def format_group_name(name)
+            # Format group names - keep original directory names intact
+            case name
+            when nil, ""
+              "Root"
+            else
+              # Just return the directory name as-is (don't capitalize)
+              name.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/cli/commands/update.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../../organisms/document_registry"
+require_relative "../../molecules/frontmatter_manager"
+require_relative "../../atoms/frontmatter_free_matcher"
+require_relative "scope_options"
+
+module Ace
+  module Docs
+    module CLI
+      module Commands
+        # ace-support-cli Command class for the update command
+        #
+        # This command handles updating document frontmatter.
+        class Update < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include ScopeOptions
+
+          # Exit codes
+          EXIT_SUCCESS = 0
+          EXIT_ERROR = 1
+
+          # Custom error classes
+          class UpdateError < StandardError; end
+          class FileNotFoundError < UpdateError; end
+          class MissingArgumentError < UpdateError; end
+
+          desc <<~DESC.strip
+            Update document frontmatter
+
+            Update frontmatter fields in a single document or all documents matching a preset.
+            Common updates include last-updated timestamps and status changes.
+
+            SYNTAX:
+              ace-docs update FILE [OPTIONS]
+              ace-docs update --preset PRESET [OPTIONS]
+
+            Configuration:
+              Global config:  ~/.ace/docs/config.yml
+              Project config: .ace/docs/config.yml
+
+            Output:
+              Updated fields written to file frontmatter
+              Exit codes: 0 (success), 1 (error)
+          DESC
+
+          example [
+            "README.md --set last-updated=today",
+            "docs/guide.md --set status=complete --set last-reviewed=2025-01-04",
+            "--set last-updated=today --preset handbook",
+            "file.md --set last-updated=2025-01-04",
+            "--package ace-docs --set last-checked=today",
+            "--glob 'ace-docs/docs/**/*.md' --set last-updated=today"
+          ]
+
+          argument :file, required: false, desc: "File to update (or use --preset)"
+
+          option :set, type: :hash, desc: "Fields to update (e.g., --set last-updated=today)"
+          option :preset, type: :string, desc: "Update all documents matching preset"
+          option :package, type: :array, desc: "Scope to package(s), e.g. --package ace-docs"
+          option :glob, type: :array, desc: "Scope by glob(s), e.g. --glob 'ace-docs/**/*.md'"
+
+          # Standard options
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(file: nil, **options)
+            # Handle --help/-h passed as file argument
+            if file == "--help" || file == "-h"
+              # ace-support-cli will handle help automatically, so we just ignore
+              return EXIT_SUCCESS
+            end
+
+            execute_update(file, options)
+          end
+
+          private
+
+          def execute_update(file, options)
+            documents = select_documents(file, options)
+
+            if documents.empty?
+              puts "No documents to update."
+              return EXIT_SUCCESS
+            end
+
+            updated_count = update_documents(documents, options)
+            puts "Updated frontmatter for #{updated_count} document(s)"
+
+            EXIT_SUCCESS
+          rescue => e
+            warn "Error updating documents: #{e.message}"
+            warn e.backtrace.join("\n") if debug?(options)
+            EXIT_ERROR
+          end
+
+          def select_documents(file, options)
+            scope_globs = normalized_scope_globs(options, project_root: options[:project_root])
+            registry = Ace::Docs::Organisms::DocumentRegistry.new(
+              project_root: options[:project_root],
+              scope_globs: scope_globs
+            )
+            scoped_docs = registry.all
+
+            if options[:preset]
+              scoped_docs.select { |d| d.context_preset == options[:preset] }
+            elsif file
+              # Try to find in registry first (existing doc with frontmatter)
+              doc = registry.find_by_path(file)
+
+              # If not in registry, check if file exists without frontmatter
+              if !doc && File.exist?(file)
+                unless path_in_scope?(file, scope_globs, project_root: options[:project_root] || Dir.pwd)
+                  raise FileNotFoundError, "File outside requested scope: #{file}"
+                end
+
+                # Create minimal Document object for file without frontmatter
+                require_relative "../../models/document"
+                doc = Ace::Docs::Models::Document.new(
+                  path: File.expand_path(file),
+                  frontmatter: {},  # Empty frontmatter - will be initialized
+                  content: File.read(file)
+                )
+              end
+
+              raise FileNotFoundError, "File not found: #{file}" unless doc
+              [doc]
+            elsif scope_options_present?(options)
+              scoped_docs
+            else
+              raise MissingArgumentError, "Please specify a file, --preset, --package, or --glob"
+            end
+          end
+
+          def update_documents(documents, options)
+            updated_count = 0
+            updates = options[:set] || {}
+            project_root = options[:project_root] || Dir.pwd
+
+            documents.each do |doc|
+              if frontmatter_free_document?(doc.path, project_root: project_root)
+                puts "Skipped: #{doc.path} (frontmatter-free document, metadata is inferred)"
+                next
+              end
+
+              # Initialize required fields if frontmatter is empty
+              working_updates = doc.frontmatter.empty? ? initialize_required_fields(doc, updates) : updates
+
+              if Ace::Docs::Molecules::FrontmatterManager.update_document(doc, working_updates)
+                updated_count += 1
+                puts "Updated: #{doc.display_name}"
+              end
+            end
+
+            updated_count
+          end
+
+          def initialize_required_fields(doc, updates)
+            required_updates = updates.dup
+
+            # Infer doc-type from file path/extension if not provided
+            required_updates["doc-type"] ||= infer_doc_type(doc.path)
+
+            # Require purpose to be provided
+            unless required_updates["purpose"]
+              raise MissingArgumentError, "Purpose required for new frontmatter. Use: --set purpose:'Document description'"
+            end
+
+            required_updates
+          end
+
+          def infer_doc_type(path)
+            case path
+            when /README\.md$/i then "readme"
+            when /\.wf\.md$/ then "workflow"
+            when /\.g\.md$/ then "guide"
+            when /\.template\.md$/ then "template"
+            when /docs\/.*\.md$/ then "context"
+            else "reference"
+            end
+          end
+
+          def frontmatter_free_document?(path, project_root:)
+            patterns = Ace::Docs.config["frontmatter_free"] || []
+            Ace::Docs::Atoms::FrontmatterFreeMatcher.match?(
+              path,
+              patterns: patterns,
+              project_root: project_root
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/cli/commands/validate.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require "colorize"
+require "open3"
+require_relative "../../organisms/document_registry"
+require_relative "../../organisms/validator"
+require_relative "scope_options"
+
+module Ace
+  module Docs
+    module CLI
+      module Commands
+        # ace-support-cli Command class for the validate command
+        #
+        # This command handles document validation.
+        class Validate < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include ScopeOptions
+
+          # Exit codes
+          EXIT_SUCCESS = 0
+          EXIT_ERROR = 1
+
+          desc <<~DESC.strip
+            Validate documents against rules
+
+            Validate documents against configured rules. Syntax validation uses linters,
+            semantic validation uses LLM analysis.
+
+            Configuration:
+              Validation rules configured via ace-lint
+              Global config:  ~/.ace/docs/config.yml
+              Project config: .ace/docs/config.yml
+
+            Output:
+              Validation report printed to stdout
+              Exit codes: 0 (pass), 1 (fail), 2 (error)
+          DESC
+
+          example [
+            "                             # Validate all documents",
+            "README.md                    # Validate specific file",
+            "docs/**/*.md                 # Validate by pattern",
+            "--syntax                     # Run syntax validation only",
+            "--semantic                   # Run semantic validation only",
+            "--all                        # Run all validation types",
+            "--package ace-docs           # Scope validation to one package",
+            "--glob 'ace-docs/**/*.md'    # Scope validation by glob"
+          ]
+
+          argument :pattern, required: false, desc: "File or pattern to validate"
+
+          option :syntax, type: :boolean, desc: "Run syntax validation using linters"
+          option :semantic, type: :boolean, desc: "Run semantic validation using LLM"
+          option :all, type: :boolean, desc: "Run all validation types"
+          option :package, type: :array, desc: "Scope to package(s), e.g. --package ace-docs"
+          option :glob, type: :array, desc: "Scope by glob(s), e.g. --glob 'ace-docs/**/*.md'"
+
+          # Standard options
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(pattern: nil, **options)
+            # Handle --help/-h passed as pattern argument
+            if pattern == "--help" || pattern == "-h"
+              # ace-support-cli will handle help automatically, so we just ignore
+              return EXIT_SUCCESS
+            end
+
+            execute_validate(pattern, options)
+          end
+
+          private
+
+          def execute_validate(pattern, options)
+            scope_globs = normalized_scope_globs(options, project_root: options[:project_root])
+            registry = Ace::Docs::Organisms::DocumentRegistry.new(
+              project_root: options[:project_root],
+              scope_globs: scope_globs
+            )
+            documents = select_documents(registry, pattern)
+
+            if documents.empty?
+              warn "No documents to validate."
+              return EXIT_SUCCESS
+            end
+
+            validator = Ace::Docs::Organisms::Validator.new(registry)
+            has_errors = false
+
+            documents.each do |doc|
+              puts "Validating: #{doc.display_name}"
+              results = validate_document(validator, doc, options)
+
+              if results[:valid]
+                puts "  ✓ Valid"
+              else
+                puts "  ✗ Invalid".red
+                has_errors = true
+                display_errors(results[:errors])
+              end
+
+              display_warnings(results[:warnings]) if results[:warnings]&.any?
+            end
+
+            has_errors ? EXIT_ERROR : EXIT_SUCCESS
+          rescue => e
+            warn "Error validating documents: #{e.message}"
+            warn e.backtrace.join("\n") if debug?(options)
+            EXIT_ERROR
+          end
+
+          def select_documents(registry, pattern)
+            if pattern
+              if File.exist?(pattern)
+                doc = registry.find_by_path(pattern)
+                doc ? [doc] : []
+              else
+                # Treat as glob pattern
+                registry.all.select do |doc|
+                  rel = doc.relative_path || doc.path
+                  File.fnmatch?(pattern, rel, File::FNM_PATHNAME | File::FNM_EXTGLOB) ||
+                    File.fnmatch?(pattern, doc.path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+                end
+              end
+            else
+              registry.all
+            end
+          end
+
+          def validate_document(validator, doc, options)
+            # Determine validation types
+            run_syntax = options[:syntax] || options[:all]
+            run_semantic = options[:semantic] || options[:all]
+            run_all = !options[:syntax] && !options[:semantic]
+
+            # If syntax validation is requested and ace-lint is configured, use it
+            if (run_syntax || run_all) && Ace::Docs.config["validation_enabled"]
+              validate_with_ace_lint(doc)
+            else
+              # Fall back to internal validation
+              validator.validate_document(
+                doc,
+                syntax: run_syntax || run_all,
+                semantic: run_semantic || run_all
+              )
+            end
+          end
+
+          def validate_with_ace_lint(doc)
+            ace_lint_path = Ace::Docs.config["ace_lint_path"] || "ace-lint"
+
+            # Check if ace-lint is available (using argv-style to avoid shell injection)
+            unless system("which", ace_lint_path, out: File::NULL, err: File::NULL)
+              # Fall back to internal validation
+              return {
+                valid: false,
+                errors: ["ace-lint not found. Install with: gem install ace-lint"],
+                warnings: []
+              }
+            end
+
+            # Run ace-lint on the document
+            stdout, stderr, status = Open3.capture3(ace_lint_path, doc.path)
+
+            if status.success?
+              {valid: true, errors: [], warnings: parse_lint_warnings(stdout)}
+            else
+              {valid: false, errors: parse_lint_errors(stdout, stderr), warnings: []}
+            end
+          rescue => e
+            {
+              valid: false,
+              errors: ["Lint validation failed: #{e.message}"],
+              warnings: []
+            }
+          end
+
+          def parse_lint_errors(stdout, stderr)
+            errors = []
+
+            # Parse stdout for errors
+            stdout.lines.each do |line|
+              if line.include?("error") || line.include?("ERROR")
+                errors << line.strip
+              end
+            end
+
+            # Add stderr if present
+            errors << stderr.strip unless stderr.strip.empty?
+
+            errors.empty? ? ["Validation failed"] : errors
+          end
+
+          def parse_lint_warnings(stdout)
+            warnings = []
+
+            stdout.lines.each do |line|
+              if line.include?("warning") || line.include?("WARNING")
+                warnings << line.strip
+              end
+            end
+
+            warnings
+          end
+
+          def display_errors(errors)
+            errors.each do |error|
+              puts "    - #{error}".red
+            end
+          end
+
+          def display_warnings(warnings)
+            warnings.each do |warning|
+              puts "    ⚠ #{warning}"
+            end
+          end
+        end
+      end
+    end
+  end
+end