rosett-ai 1.3.3

data/lib/rosett_ai/thor/tasks/compile.rb

@@ -0,0 +1,415 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'thor'
+require 'terminal-table'
+require 'rainbow'
+require 'tty-spinner'
+require 'fileutils'
+require 'yaml'
+
+module RosettAi
+  module Thor
+    module Tasks
+      # Context for file compilation operations
+      CompileFileContext = Struct.new(:target_path, :content, :checksum, :filename)
+
+      # Thor task for compiling YAML configuration into markdown rule files
+      class Compile < ::Thor
+        default_task :generate
+
+        desc 'generate', 'Compile YAML configurations into markdown rule files'
+        long_desc <<~LONGDESC
+          Compiles behaviour and design YAML into engine-specific rule files.
+          By default, compiles for the configured default engine to ~/.claude/rules/.
+
+          Flags:
+            --verbose: Show detailed compilation output
+            --simulate: Dry run with diffs, no file writes
+            --vendor: Write compile.lock.yml lockfile
+            --engine NAME: Compile for specific engine
+            --strict: Treat warnings as errors
+            --locales: Compile locale files to gettext/Qt formats
+
+          Exit codes: 1 if validation fails in --strict mode
+
+          EXAMPLES
+
+            raictl compile
+            raictl compile --verbose --simulate
+            raictl compile --engine generic --strict
+            raictl compile --vendor
+            raictl compile --locales
+
+          Related commands: raictl behaviour validate, rai adopt
+        LONGDESC
+        method_option :verbose,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Show detailed output'
+        method_option :vendor,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Write compile.lock.yml lockfile'
+        method_option :simulate,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Dry run — show diffs without writing'
+        method_option :update,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Update existing rules (default behaviour)'
+        method_option :engine,
+                      type: :string,
+                      default: nil,
+                      desc: 'Engine name (e.g., claude, generic)'
+        method_option :target,
+                      type: :string,
+                      default: nil,
+                      desc: '[DEPRECATED] Use --engine instead'
+        method_option :strict,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Treat warnings as errors'
+        method_option :locales,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Compile locale files to gettext and Qt formats'
+
+        def generate
+          if options[:locales]
+            compile_locales
+            return
+          end
+
+          check_xdg_migration
+          compiler = build_compiler
+          categories = compiler.discover_categories
+
+          if categories.empty?
+            puts Rainbow(t('compile.no_categories')).yellow
+            return
+          end
+
+          log_categories(categories, compiler) if options[:verbose]
+
+          compiled = compiler.compile
+          check_conflict_warnings(compiler)
+          check_capabilities(resolve_engine_option)
+          results = process_compiled(compiler, compiled)
+          remove_orphans(compiler, compiled)
+          write_lockfile(compiler, compiled) if options[:vendor] && !options[:simulate]
+          print_summary(results)
+        end
+
+        private
+
+        def t(key, **)
+          ::I18n.t("rosett_ai.cli.#{key}", **)
+        end
+
+        def build_compiler
+          engine_name = resolve_engine_option
+          backend = RosettAi::Compiler::Backend.for(engine_name)
+          scope = detect_compile_scope
+          target = resolve_target_dir(backend) || default_target_dir(scope)
+          RosettAi::Compiler::CompilationPipeline.new(
+            source_dir: resolve_source_dir(scope),
+            target_dir: target,
+            schema_dir: RosettAi.root.join('conf', 'schemas'),
+            backend: backend,
+            scope: scope,
+            additional_source_dirs: additional_dirs(scope)
+          )
+        end
+
+        # Resolves the primary source directory for compilation.
+        #
+        # Global scope: XDG-compliant ~/.config/rosett-ai/conf (user behaviours)
+        # Project scope: .rosett-ai/conf (project behaviours, merged with global via additional_source_dirs)
+        # Internal (rosett-ai dev): rosett-ai repo's own conf/ (for development)
+        def resolve_source_dir(scope)
+          return RosettAi.root.join('conf') if RosettAi.context.rai_internal?
+
+          scope == :project ? RosettAi.conf_root.join('conf') : global_conf_dir
+        end
+
+        # Additional source dirs for the 3-tier lookup chain.
+        # Order matters: later dirs override earlier ones (CompilationPipeline
+        # appends @source_dir last). So packaged defaults go first, then XDG
+        # user config, so user rules override packaged defaults by filename.
+        def additional_dirs(scope)
+          dirs = []
+          packaged = RosettAi.paths.packaged_conf_dir
+          dirs << packaged if packaged.directory?
+          dirs << global_conf_dir if scope == :project || RosettAi.context.rai_internal?
+          dirs
+        end
+
+        def global_conf_dir
+          RosettAi.paths.rai_conf_dir
+        end
+
+        def detect_compile_scope
+          ctx = RosettAi.context
+          ctx.project? && !ctx.rai_internal? ? :project : :global
+        end
+
+        def check_xdg_migration
+          return if RosettAi.context.rai_internal?
+
+          migrator = RosettAi::Migration::XdgMigrator.new
+          return unless migrator.migration_needed?
+
+          puts Rainbow(migrator.warning_message).yellow
+          migrated = migrator.migrate!
+          migrated.each { |f| puts Rainbow("  Migrated: #{f}").green }
+          puts Rainbow("  Migration complete. #{migrated.size} file(s) moved.").green unless migrated.empty?
+        end
+
+        def check_conflict_warnings(compiler)
+          warnings = compiler.conflict_warnings
+          return if warnings.empty?
+
+          warnings.each do |warning|
+            puts Rainbow("  WARNING: #{warning}").yellow
+          end
+
+          return unless options[:strict]
+
+          raise RosettAi::CompileError,
+                "#{warnings.size} duplicate rule ID(s) detected in strict mode"
+        end
+
+        def check_capabilities(engine_name)
+          checker = RosettAi::Compiler::CapabilityChecker.new(engine_name)
+          summaries = checker.check_summarized(RosettAi.conf_root.join('conf'))
+          return if summaries.empty?
+
+          summaries.each do |summary|
+            puts Rainbow("  WARNING: #{summary[:message]}").yellow
+          end
+
+          return unless options[:strict]
+
+          total = summaries.sum { |summary| summary[:count] }
+          raise RosettAi::CompileError,
+                "#{total} capability warning(s) in strict mode"
+        end
+
+        def resolve_engine_option
+          engine = options[:engine]
+          target = options[:target]
+
+          if engine && target
+            raise RosettAi::CompileError,
+                  t('compile.engine_and_target_conflict')
+          end
+
+          if target
+            if options[:strict]
+              raise RosettAi::CompileError,
+                    t('compile.target_deprecated_strict')
+            end
+            RosettAi::Deprecation.warn_deprecated(
+              feature: '--target',
+              replacement: '--engine',
+              since: '1.0.0',
+              removal: '2.0.0'
+            )
+            return target
+          end
+
+          engine || RosettAi.rai_config.default_engine
+        end
+
+        def resolve_target_dir(backend)
+          dir = backend.profile.output_dir
+          dir ? Pathname.new(File.expand_path(dir)) : nil
+        end
+
+        def default_target_dir(scope)
+          return RosettAi.context.project_root.join('.claude', 'rules') if scope == :project
+
+          RosettAi.paths.rules_dir
+        end
+
+        # Resolves the target directory for a compiled output based on its
+        # declared scope. Falls back to the pipeline's target_dir when no
+        # scope is declared or the behaviour's scope matches the pipeline's.
+        #
+        # Scope routing:
+        #   global/personal → ~/.claude/rules/ (global rules dir)
+        #   project          → .claude/rules/  (project-local)
+        #   nil              → pipeline default (current behaviour)
+        def resolve_scoped_target_dir(compiler, info)
+          declared_scope = info[:scope]
+          return compiler.target_dir unless declared_scope
+
+          case declared_scope
+          when 'project'
+            if RosettAi.context.project?
+              RosettAi.context.project_root.join('.claude', 'rules')
+            else
+              compiler.target_dir
+            end
+          when 'global', 'personal'
+            RosettAi.paths.rules_dir
+          else
+            compiler.target_dir
+          end
+        end
+
+        def compile_locales
+          locale_compiler = RosettAi::Compiler::LocaleCompiler.new(
+            source_dir: RosettAi.root.join('locales'),
+            gettext_dir: RosettAi.root.join('locales', 'compiled', 'gettext'),
+            qt_dir: RosettAi.root.join('locales', 'compiled', 'qt')
+          )
+
+          if options[:simulate]
+            puts Rainbow(t('compile.locale_simulate')).yellow
+            log_verbose("Source: #{locale_compiler.source_dir}")
+            log_verbose("Gettext output: #{locale_compiler.gettext_dir}")
+            log_verbose("Qt output: #{locale_compiler.qt_dir}")
+            return
+          end
+
+          results = locale_compiler.compile
+          puts Rainbow(t('compile.locale_gettext_compiled', count: results[:gettext].size)).green
+          puts Rainbow(t('compile.locale_qt_compiled', count: results[:qt].size)).green
+        end
+
+        def log_categories(categories, compiler)
+          puts Rainbow(t('compile.discovered_categories')).bright
+          categories.each { |cat| puts "  #{Rainbow(cat).cyan}" }
+          compiler.skipped_project_categories.each do |cat|
+            puts "  #{Rainbow(cat).dark} (project scope only)"
+          end
+          puts
+        end
+
+        def process_compiled(compiler, compiled)
+          results = { created: [], updated: [], unchanged: [], skipped: [] }
+
+          compiled.each do |filename, info|
+            target_dir = resolve_scoped_target_dir(compiler, info)
+            target_path = target_dir.join(filename)
+            content = info[:content]
+            new_checksum = compiler.checksum(content)
+
+            ctx = CompileFileContext.new(
+              target_path: target_path, content: content, checksum: new_checksum, filename: filename
+            )
+            if options[:simulate]
+              handle_simulate(compiler, ctx, results)
+            else
+              handle_write(compiler, ctx, results)
+            end
+          end
+
+          results
+        end
+
+        def handle_simulate(compiler, ctx, results)
+          if File.exist?(ctx.target_path)
+            diff_output = compiler.diff(ctx.target_path, ctx.content)
+            if diff_output
+              puts Rainbow(t('compile.would_update', filename: ctx.filename)).yellow
+              puts diff_output if options[:verbose]
+              results[:updated] << ctx.filename
+            else
+              puts Rainbow(t('compile.unchanged', filename: ctx.filename)).green if options[:verbose]
+              results[:unchanged] << ctx.filename
+            end
+          else
+            puts Rainbow(t('compile.would_create', filename: ctx.filename)).cyan
+            results[:created] << ctx.filename
+          end
+        end
+
+        def handle_write(compiler, ctx, results)
+          FileUtils.mkdir_p(ctx.target_path.dirname)
+          action = determine_write_action(compiler, ctx)
+          perform_write_action(ctx, action, results)
+        end
+
+        def determine_write_action(compiler, ctx)
+          return :created unless File.exist?(ctx.target_path)
+
+          existing = compiler.checksum(File.read(ctx.target_path, encoding: 'utf-8'))
+          existing == ctx.checksum ? :unchanged : :updated
+        end
+
+        def perform_write_action(ctx, action, results)
+          target_path, content, filename, checksum_prefix = extract_ctx(ctx)
+          write_file(target_path, content) if [:updated, :created].include?(action)
+          log_verbose("#{format_action_label(action)}: #{filename} (#{checksum_prefix})")
+          results[action] << filename
+        end
+
+        def format_action_label(action)
+          { created: t('compile.created'), updated: t('compile.updated'),
+            unchanged: t('compile.unchanged', filename: '') }.fetch(action, action.to_s)
+        end
+
+        def extract_ctx(ctx)
+          [ctx.target_path, ctx.content, ctx.filename, ctx.checksum[0..7]]
+        end
+
+        def write_file(path, content)
+          File.open(path, 'w', 0o644) { |f| f.write(content) }
+        end
+
+        def remove_orphans(compiler, compiled)
+          # Guard: when compile produced no output (e.g. empty project conf/),
+          # every managed file in target_dir would appear orphaned. Removing
+          # them would silently destroy all compiled rules. See WP#712.
+          return if compiled.empty?
+
+          orphans = compiler.orphaned_files(compiled.keys)
+          orphans.each do |orphan|
+            basename = File.basename(orphan)
+            if options[:simulate]
+              puts Rainbow(t('compile.would_remove_orphan', filename: basename)).red
+            else
+              File.delete(orphan)
+              log_verbose(t('compile.removed_orphan', filename: basename))
+            end
+          end
+        end
+
+        def write_lockfile(compiler, compiled)
+          lockfile_path = RosettAi.conf_root.join('conf', 'compile.lock.yml')
+          data = compiler.lockfile_data(compiled)
+          File.open(lockfile_path, 'w', 0o644) { |f| f.write(data.to_yaml) }
+          log_verbose(t('compile.wrote_lockfile', path: lockfile_path))
+        end
+
+        def print_summary(results)
+          rows = []
+          rows << [t('compile.created'), results[:created].size] unless results[:created].empty?
+          rows << [t('compile.updated'), results[:updated].size] unless results[:updated].empty?
+          rows << [t('compile.unchanged', filename: ''), results[:unchanged].size] unless results[:unchanged].empty?
+
+          return if rows.empty?
+
+          puts
+          table = ::Terminal::Table.new(
+            title: Rainbow(t('compile.summary_title')).bright,
+            headings: [t('compile.action'), t('compile.count')],
+            rows: rows,
+            style: { border: :unicode_round }
+          )
+          puts table
+        end
+
+        def log_verbose(message)
+          puts "  #{message}" if options[:verbose]
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/thor/tasks/completion.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Thor
+    module Tasks
+      # Thor subcommand for generating shell completion scripts.
+      #
+      # Generates bash, zsh, and fish completion scripts from the Thor
+      # command registry. Scripts are output to stdout for piping or
+      # can be installed to the standard completion directory.
+      #
+      # @author hugo
+      # @author claude
+      class Completion < ::Thor
+        INSTALL_PATHS = {
+          'bash' => '/usr/share/bash-completion/completions/rai',
+          'zsh' => '/usr/share/zsh/vendor-completions/_rai',
+          'fish' => "#{Dir.home}/.config/fish/completions/raictl.fish"
+        }.freeze
+
+        desc 'bash', 'Generate bash completion script'
+        long_desc <<~LONGDESC
+          Generate a bash completion script and write to stdout.
+
+          Example: raictl completion bash > /usr/share/bash-completion/completions/rai
+
+          Related: completion zsh, completion fish, completion install
+        LONGDESC
+        def bash
+          output_completion('bash')
+        end
+
+        desc 'zsh', 'Generate zsh completion script'
+        long_desc <<~LONGDESC
+          Generate a zsh completion script and write to stdout.
+
+          Example: raictl completion zsh > /usr/share/zsh/vendor-completions/_rai
+
+          Related: completion bash, completion fish, completion install
+        LONGDESC
+        def zsh
+          output_completion('zsh')
+        end
+
+        desc 'fish', 'Generate fish completion script'
+        long_desc <<~LONGDESC
+          Generate a fish completion script and write to stdout.
+
+          Example: raictl completion fish > ~/.config/fish/completions/raictl.fish
+
+          Related: completion bash, completion zsh, completion install
+        LONGDESC
+        def fish
+          output_completion('fish')
+        end
+
+        desc 'install', 'Install completion script for the current shell'
+        long_desc <<~LONGDESC
+          Install the completion script to the standard system path.
+
+          The shell is auto-detected from $SHELL unless overridden
+          with --shell. Supported shells: bash, zsh, fish.
+
+          Install paths:
+            bash: /usr/share/bash-completion/completions/rai
+            zsh:  /usr/share/zsh/vendor-completions/_rai
+            fish: ~/.config/fish/completions/raictl.fish
+
+          EXAMPLES
+
+            raictl completion install
+            raictl completion install --shell zsh
+
+          Related: completion bash, completion zsh, completion fish
+        LONGDESC
+        method_option :shell, type: :string, default: nil,
+                              desc: 'Shell to install for (auto-detected from $SHELL)'
+        def install
+          shell = detect_shell
+          generator = RosettAi::Completion::Generator.new
+          script = generator.generate(shell)
+          path = INSTALL_PATHS.fetch(shell)
+
+          install_script(script, path, shell)
+        end
+
+        private
+
+        def output_completion(shell)
+          generator = RosettAi::Completion::Generator.new
+          puts generator.generate(shell)
+        end
+
+        def detect_shell
+          shell = options[:shell] || File.basename(ENV.fetch('SHELL', ''))
+          shell = shell.downcase
+
+          unless RosettAi::Completion::Generator::SUPPORTED_SHELLS.include?(shell)
+            raise RosettAi::Error,
+                  "Shell #{shell} is not supported — available: " \
+                  "#{RosettAi::Completion::Generator::SUPPORTED_SHELLS.join(', ')}"
+          end
+
+          shell
+        end
+
+        def install_script(script, path, shell)
+          dir = File.dirname(path)
+          FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+          File.write(path, script)
+          warn "Installed #{shell} completion to #{path}"
+        rescue Errno::EACCES
+          raise RosettAi::Error,
+                "Permission denied writing to #{path} — try: sudo rai completion install --shell #{shell}"
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/thor/tasks/comply.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'terminal-table'
+
+module RosettAi
+  module Thor
+    module Tasks
+      # CLI task for `rai comply` — compliance verification.
+      #
+      # Runs CRA, license, and SPDX header compliance checks.
+      # Produces TTY-aware or machine-readable (JSON) output.
+      # Exit codes: 0 = all pass, 1 = warnings only, 2 = any failure.
+      #
+      # @author hugo
+      # @author claude
+      class Comply < ::Thor
+        default_task :check
+
+        desc 'check', 'Run all compliance checks'
+        long_desc <<~LONGDESC
+          Runs compliance checks and produces a summary report.
+
+          By default, all checks are run: CRA requirements, license
+          compatibility, and SPDX header verification.
+
+          Use --cra, --license, or --headers to run specific checks.
+          Use --format json for machine-readable CI output.
+
+          Exit codes: 0 = all pass, 1 = warnings only, 2 = any failure.
+
+          EXAMPLES
+
+            raictl comply
+            raictl comply --cra
+            raictl comply --license --headers
+            raictl comply --format json
+        LONGDESC
+        method_option :cra, type: :boolean, default: false,
+                            desc: 'Run CRA-specific checks only'
+        method_option :license, type: :boolean, default: false,
+                                desc: 'Run license audit checks only'
+        method_option :headers, type: :boolean, default: false,
+                                desc: 'Run SPDX header checks only'
+        method_option :format, type: :string, enum: ['table', 'json'], default: 'table',
+                               desc: 'Output format'
+        def check
+          checks = selected_checks
+          results = RosettAi::Comply::Runner.new(
+            project_root: resolve_project_root,
+            checks: checks
+          ).run
+
+          reporter = RosettAi::Comply::Reporter.new(
+            results: results,
+            format: options[:format]
+          )
+          reporter.report
+
+          code = reporter.exit_code
+          exit code unless code.zero?
+        end
+
+        private
+
+        def selected_checks
+          active = []
+          active << :cra if options[:cra]
+          active << :license if options[:license]
+          active << :headers if options[:headers]
+          active.empty? ? nil : active
+        end
+
+        def resolve_project_root
+          Pathname.new(ENV.fetch('RAI_ORIGINAL_PWD', Dir.pwd))
+        end
+      end
+    end
+  end
+end