analytics_ops 0.2.0 → 0.3.0

data/lib/analytics_ops/cli/options.rb

@@ -6,22 +6,33 @@ module AnalyticsOps
     class Options
       DEFAULTS = {
         config: "config/analytics_ops.yml",
+        config_explicit: false,
         profile: "production",
+        profile_explicit: false,
         format: "human",
         log_level: "warn",
+        log_level_explicit: false,
         transport: :grpc,
+        transport_explicit: false,
+        timeout_explicit: false,
         yes: false,
-        noninteractive: false
+        noninteractive: false,
+        compare: false,
+        dimensions: [].freeze,
+        metrics: [].freeze,
+        filters: [].freeze,
+        all_rows: false
       }.freeze
       SETUP_OPTIONS = %i[property service_account].freeze
       PROPERTY_ID = /\A\d{1,50}\z/
       PROFILE = /\A[A-Za-z][A-Za-z0-9_]{0,63}\z/
+      CONNECTION = /\A[A-Za-z][A-Za-z0-9_-]{0,63}\z/
 
       attr_reader :values
 
       def initialize(arguments)
         @arguments = arguments
-        @values = DEFAULTS.dup
+        @values = DEFAULTS.transform_values { |value| value.is_a?(Array) ? value.dup : value }
         @explicit_format = nil
       end
 
@@ -38,15 +49,25 @@ module AnalyticsOps
           add_file_options(options)
           add_format_options(options)
           add_setup_options(options)
+          add_report_options(options)
           add_client_options(options)
           add_execution_options(options)
         end
       end
 
       def add_file_options(options)
-        options.on("-c", "--config PATH", "Configuration path") { |path| @values[:config] = path }
-        options.on("-p", "--profile NAME", "Configuration profile") { |name| @values[:profile] = name }
-        options.on("-o", "--output PATH", "Write a generated plan to PATH") { |path| @values[:output] = path }
+        options.on("-c", "--config PATH", "Configuration path") do |path|
+          @values[:config] = path
+          @values[:config_explicit] = true
+        end
+        options.on("-p", "--profile NAME", "Configuration profile") do |name|
+          @values[:profile] = name
+          @values[:profile_explicit] = true
+        end
+        options.on("--connection NAME", "Saved Google connection") { |name| @values[:connection] = name }
+        options.on("-o", "--output PATH", "Write a plan or bounded CSV export to PATH") do |path|
+          @values[:output] = path
+        end
       end
 
       def add_format_options(options)
@@ -73,12 +94,46 @@ module AnalyticsOps
         end
       end
 
+      def add_report_options(options)
+        options.on("--last DAYS", Integer, "Use the previous number of complete days") do |days|
+          @values[:last_days] = days
+        end
+        options.on("--from DATE", "Report start date (YYYY-MM-DD)") { |date| @values[:start_date] = date }
+        options.on("--to DATE", "Report end date (YYYY-MM-DD)") { |date| @values[:end_date] = date }
+        options.on("--compare", "Also include the equally long preceding period") { @values[:compare] = true }
+        options.on("--dimension NAME", "Dimension for `report custom` (repeatable)") do |name|
+          @values.fetch(:dimensions) << name
+        end
+        options.on("--metric NAME", "Metric for `report custom` (repeatable)") do |name|
+          @values.fetch(:metrics) << name
+        end
+        options.on("--where FIELD=VALUE", "Exact dimension filter for `report custom` (repeatable)") do |value|
+          @values.fetch(:filters) << value
+        end
+        options.on("--limit ROWS", Integer, "Maximum rows in one report request") { |value| @values[:limit] = value }
+        options.on("--all", "Export every available row, within --max-rows") { @values[:all_rows] = true }
+        options.on("--max-rows ROWS", Integer, "Hard limit for --all (default 1000000)") do |value|
+          @values[:max_rows] = value
+        end
+        options.on("--page-size ROWS", Integer, "Rows per --all API request (default 100000)") do |value|
+          @values[:page_size] = value
+        end
+        options.on("--kind KIND", %w[dimension metric], "Limit `fields` to one field kind") do |value|
+          @values[:field_kind] = value
+        end
+        options.on("--concurrency COUNT", Integer, "Portfolio requests at once (1-8; default 4)") do |value|
+          @values[:concurrency] = value
+        end
+      end
+
       def add_client_options(options)
         options.on("--log-level LEVEL", CLI::LOG_LEVELS, CLI::LOG_LEVELS.join(", ")) do |level|
           @values[:log_level] = level
+          @values[:log_level_explicit] = true
         end
         options.on("--transport TRANSPORT", %w[grpc rest], "grpc or rest") do |transport|
           @values[:transport] = transport.to_sym
+          @values[:transport_explicit] = true
         end
         options.on("--timeout SECONDS", Float, "Google API timeout") do |seconds|
           unless seconds.finite? && seconds.positive?
@@ -86,6 +141,7 @@ module AnalyticsOps
           end
 
           @values[:timeout] = seconds
+          @values[:timeout_explicit] = true
         end
       end
 
@@ -97,7 +153,16 @@ module AnalyticsOps
       def validate!(command)
         validate_arguments!(command)
         validate_scoped_options!(command)
+        validate_local_options!(command)
+        validate_connection!
+        validate_report_period!(command)
         validate_setup! if command == "setup"
+        validate_apply! if command == "apply"
+        validate_mcp! if command == "mcp"
+        validate_custom_report!(command)
+        validate_export!(command)
+        validate_field_options!(command)
+        validate_portfolio_options!(command)
         validate_format!(command)
       end
 
@@ -108,16 +173,212 @@ module AnalyticsOps
       end
 
       def validate_scoped_options!(command)
-        raise OptionParser::InvalidArgument, "--output is only valid with plan" if @values[:output] && command != "plan"
+        validate_plan_scope!(command)
+        validate_selection_scope!(command)
+        validate_execution_scope!(command)
+        validate_setup_scope!(command)
+      end
+
+      def validate_local_options!(command)
+        if %w[connections schema].include?(command) && @values.fetch(:config_explicit)
+          raise OptionParser::InvalidArgument, "--config is not valid with #{command}"
+        end
+        return unless %w[connections profiles schema use].include?(command)
+        return unless @values.fetch(:log_level_explicit) ||
+                      @values.fetch(:transport_explicit) ||
+                      @values.fetch(:timeout_explicit)
+
+        raise OptionParser::InvalidArgument,
+              "--log-level, --transport, and --timeout are not valid with #{command}"
+      end
+
+      def validate_plan_scope!(command)
+        if @values[:output] && !%w[plan report].include?(command)
+          raise OptionParser::InvalidArgument, "--output is only valid with plan or report --all"
+        end
         raise OptionParser::InvalidArgument, "--yes is only valid with apply" if @values[:yes] && command != "apply"
-        if @values[:noninteractive] && !%w[apply setup].include?(command)
-          raise OptionParser::InvalidArgument, "--non-interactive is only valid with apply or setup"
+      end
+
+      def validate_selection_scope!(command)
+        if @values[:connection] && %w[connections portfolio profiles schema].include?(command)
+          raise OptionParser::InvalidArgument, "--connection is not valid with #{command}"
         end
+        return unless @values[:profile_explicit] && %w[connections portfolio profiles schema use].include?(command)
+
+        raise OptionParser::InvalidArgument, "--profile is not valid with #{command}"
+      end
+
+      def validate_execution_scope!(command)
+        return unless @values[:noninteractive] && !%w[apply setup].include?(command)
+
+        raise OptionParser::InvalidArgument, "--non-interactive is only valid with apply or setup"
+      end
+
+      def validate_setup_scope!(command)
         return if SETUP_OPTIONS.none? { |name| @values[name] } || command == "setup"
 
         raise OptionParser::InvalidArgument, "--property and --service-account are setup-only"
       end
 
+      def validate_connection!
+        return unless @values[:connection] && !CONNECTION.match?(@values.fetch(:connection))
+
+        raise OptionParser::InvalidArgument,
+              "--connection must start with a letter and use only letters, numbers, hyphens, or underscores"
+      end
+
+      def validate_report_period!(command)
+        requested = @values[:last_days] || @values[:start_date] || @values[:end_date] || @values[:compare]
+        return unless requested
+        unless %w[overview portfolio report health raw funnel].include?(command)
+          raise OptionParser::InvalidArgument,
+                "--last, --from, --to, and --compare are only valid with date-aware read commands"
+        end
+        if %w[raw funnel].include?(command) && @values.fetch(:compare)
+          raise OptionParser::InvalidArgument, "#{command} does not support --compare"
+        end
+
+        Reports::Period.resolve(
+          last_days: @values[:last_days],
+          start_date: @values[:start_date],
+          end_date: @values[:end_date],
+          compare: @values.fetch(:compare)
+        )
+      rescue InvalidRequestError => error
+        raise OptionParser::InvalidArgument, error.message
+      end
+
+      def validate_custom_report!(command)
+        return validate_raw_report_options! if command == "raw"
+
+        custom = command == "report" && @arguments.first == "custom"
+        selected = custom_report_options_selected?
+        require_custom_metrics! if custom
+        return unless selected
+
+        validate_custom_report_scope!(command)
+        require_custom_metrics!
+        validate_positive_bound!(:limit, Reports::Definition::MAX_STANDARD_LIMIT)
+        filters = parsed_custom_filters
+        @values[:custom_definition] = Reports::Definition.new(
+          name: "custom_report",
+          kind: "standard",
+          dimensions: @values.fetch(:dimensions),
+          metrics: @values.fetch(:metrics),
+          date_ranges: custom_report_date_ranges,
+          dimension_filter: combined_filter(filters),
+          limit: @values.fetch(:limit, 100)
+        )
+      rescue InvalidRequestError => error
+        raise OptionParser::InvalidArgument, error.message
+      end
+
+      def validate_raw_report_options!
+        if @values.fetch(:dimensions).any? || @values.fetch(:metrics).any? || @values.fetch(:filters).any?
+          raise OptionParser::InvalidArgument, "--dimension, --metric, and --where are not valid with raw"
+        end
+
+        validate_positive_bound!(:limit, 10_000)
+      end
+
+      def custom_report_options_selected?
+        @values.fetch(:dimensions).any? ||
+          @values.fetch(:metrics).any? ||
+          @values.fetch(:filters).any? ||
+          @values[:limit]
+      end
+
+      def validate_custom_report_scope!(command)
+        unless command == "report"
+          raise OptionParser::InvalidArgument, "custom report options are only valid with report"
+        end
+        return if @arguments.first == "custom"
+
+        raise OptionParser::InvalidArgument, "--dimension, --metric, --where, and --limit require `report custom`"
+      end
+
+      def require_custom_metrics!
+        return unless @values.fetch(:metrics).empty?
+
+        raise OptionParser::MissingArgument, "`report custom` requires at least one --metric"
+      end
+
+      def parsed_custom_filters
+        @values.fetch(:filters).map do |filter|
+          field, value = filter.to_s.split("=", 2)
+          unless field && value && !field.empty? && !value.empty?
+            raise OptionParser::InvalidArgument, "--where must use FIELD=VALUE"
+          end
+
+          { "field" => field, "match_type" => "exact", "value" => value }
+        end
+      end
+
+      def combined_filter(filters)
+        filters.length > 1 ? { "and" => filters } : filters.first
+      end
+
+      def custom_report_date_ranges
+        Reports::Period.resolve(
+          last_days: @values[:last_days],
+          start_date: @values[:start_date],
+          end_date: @values[:end_date],
+          compare: @values.fetch(:compare)
+        ) || Reports::Catalog::STANDARD_DATE_RANGE
+      end
+
+      def validate_export!(command)
+        validate_export_scope!(command)
+        validate_export_dependencies!(command)
+        validate_positive_bound!(:max_rows, Workspace::MAX_EXPORT_ROWS)
+        validate_positive_bound!(:page_size, Reports::Definition::MAX_STANDARD_LIMIT)
+      end
+
+      def validate_export_scope!(command)
+        requested = @values.fetch(:all_rows) || @values[:max_rows] || @values[:page_size]
+        return unless requested && command != "report"
+
+        raise OptionParser::InvalidArgument, "--all, --max-rows, and --page-size are report-only"
+      end
+
+      def validate_export_dependencies!(command)
+        if @values.fetch(:all_rows)
+          raise OptionParser::MissingArgument, "--all requires --output PATH" unless @values[:output]
+        elsif command == "report" && @values[:output]
+          raise OptionParser::InvalidArgument, "report --output requires --all"
+        end
+        return unless (@values[:max_rows] || @values[:page_size]) && !@values.fetch(:all_rows)
+
+        raise OptionParser::InvalidArgument, "--max-rows and --page-size require --all"
+      end
+
+      def validate_positive_bound!(name, maximum)
+        value = @values[name]
+        return unless value
+        return if value.is_a?(Integer) && value.between?(1, maximum)
+
+        raise OptionParser::InvalidArgument, "--#{name.to_s.tr("_", "-")} must be between 1 and #{maximum}"
+      end
+
+      def validate_field_options!(command)
+        return unless @values[:field_kind] && command != "fields"
+
+        raise OptionParser::InvalidArgument, "--kind is only valid with fields"
+      end
+
+      def validate_portfolio_options!(command)
+        if @values[:concurrency] && command != "portfolio"
+          raise OptionParser::InvalidArgument, "--concurrency is only valid with portfolio"
+        end
+        if @values[:concurrency] && !@values.fetch(:concurrency).between?(1, 8)
+          raise OptionParser::InvalidArgument, "--concurrency must be between 1 and 8"
+        end
+        return unless command == "portfolio" && @values.fetch(:format) == "csv"
+        return if @arguments.first == "report" && @arguments.length == 2
+
+        raise OptionParser::InvalidArgument, "CSV portfolio output requires `portfolio report NAME`"
+      end
+
       def validate_setup!
         validate_setup_property!
         raise OptionParser::InvalidArgument, "--profile is invalid" unless PROFILE.match?(@values.fetch(:profile))
@@ -147,8 +408,20 @@ module AnalyticsOps
         raise OptionParser::MissingArgument, "JSON setup requires --non-interactive --property ID"
       end
 
+      def validate_apply!
+        return unless @values.fetch(:format) == "json" && (!@values[:noninteractive] || !@values[:yes])
+
+        raise OptionParser::MissingArgument, "JSON apply requires --non-interactive --yes"
+      end
+
+      def validate_mcp!
+        return if @values.fetch(:format) == "human"
+
+        raise OptionParser::InvalidArgument, "mcp uses the MCP protocol and does not accept output formats"
+      end
+
       def validate_format!(command)
-        return unless @values.fetch(:format) == "csv" && !%w[report realtime].include?(command)
+        return unless @values.fetch(:format) == "csv" && !%w[report realtime portfolio raw funnel].include?(command)
 
         raise OptionParser::InvalidArgument, "CSV output is only valid for report results"
       end