rubocop-metz 0.5.2

data/lib/metz_scan/calibration/project_analyzer_evidence_runner/readiness_catalog.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "../../commands/scan/project_analyzer_runner"
+
+module MetzScan
+  module Calibration
+    module ProjectAnalyzerEvidenceRunner
+      class ReadinessCatalog
+        NOTES = {
+          "MetzProject/ServiceSoup" => {
+            "evidence" => "Medium design-pressure findings are calibrated; setup orchestration is downranked.",
+            "next" => "Monitor future calibration for setup noise or new service-call shapes.",
+            "not_next" => "Do not reopen promotion unless default-output evidence regresses."
+          },
+          "MetzProject/RepeatedBranching" => {
+            "evidence" => "Repeated branch tables are calibrated; generic subjects are lower-confidence.",
+            "next" => "Monitor generic-subject calibration and branch-subject readability.",
+            "not_next" => "Do not expand branch parsing without sparse fixture-backed evidence."
+          },
+          "MetzProject/DeepInheritanceTree" => {
+            "evidence" => "Useful inheritance spread evidence remains dependent on the optional project index.",
+            "next" => "Use opt-in calibration to watch grouped output and broad-root downranking.",
+            "not_next" => "Do not make default-output eligible while findings depend on optional indexing."
+          },
+          "MetzProject/PackageDependencyPressure" => {
+            "evidence" => "Expanded active fixtures show 47 findings: 5 medium package boundaries and " \
+                          "42 low shared dependencies; consolidated medium review splits into " \
+                          "3 useful prompts and 2 needs-context framework or extension surfaces.",
+            "next" => "Keep parked unless future generic work can separate cross-cutting logging pressure " \
+                      "from framework roots and public extension registries.",
+            "not_next" => "Do not implement classifier behavior, promote, retune thresholds, downrank " \
+                          "framework-root prompts, or add app-specific suppressions from this sample."
+          },
+          "MetzProject/NamespaceLeakPressure" => {
+            "evidence" => "Expanded active fixtures show 49 findings: 12 medium namespace-boundary prompts " \
+                          "and 37 low shared namespaces; consolidated medium review mixes useful domain " \
+                          "and security prompts with public extension or facade surfaces.",
+            "next" => "Keep parked unless future generic work separates namespace-boundary prompts from " \
+                      "public extension, facade, payment, reporting, and renderer APIs.",
+            "not_next" => "Do not implement classifier behavior, promote, add app-specific suppressions, " \
+                          "downrank payment namespaces, or retune thresholds from this narrow sample."
+          },
+          "MetzProject/ImplicitContextPressure" => {
+            "evidence" => "Expanded active fixtures show 12 findings dominated by mechanical framework state: " \
+                          "9 mechanical, 1 useful execution-identity prompt, and 2 needs-context identity prompts.",
+            "next" => "Keep candidate-only and use broader samples to separate boundary setup from ambient identity " \
+                      "design pressure.",
+            "not_next" => "Do not add suppressions, global-access forms, promotion, or default-output eligibility " \
+                          "from this sample."
+          },
+          "MetzProject/RepeatedQueryCriteria" => {
+            "evidence" => "Expanded active fixtures show 16 findings: 13 useful prompts and 3 mechanical lookups.",
+            "next" => "Keep separating membership-table lookups from business-named and lifecycle lookup concepts.",
+            "not_next" => "Do not add more query forms, dynamic receivers, association receivers, SQL strings, " \
+                          "joins, merges, Arel, single-key finders, bang finders, exists?, or take."
+          },
+          "MetzProject/SubclassOverridePressure" => {
+            "evidence" => "Expanded active fixtures show 148 findings: 93 low broad-root and " \
+                          "55 medium manual-review findings across abstract hook, cooperative, and " \
+                          "replacement override families.",
+            "next" => "Keep parked unless future generic work separates design-pressure hook contracts " \
+                      "from deliberate extension protocols and setup conventions.",
+            "not_next" => "Do not implement classifier behavior, promote, make default-output eligible, " \
+                          "suppress medium categories, or retune thresholds."
+          }
+        }.freeze
+
+        def initialize(analyzer_names: [], analyzers: Commands::Scan::ProjectAnalyzerRunner::ANALYZERS)
+          @analyzer_names = Array(analyzer_names)
+          @analyzers = analyzers
+        end
+
+        def to_a
+          selected_analyzers.filter_map { |analyzer| readiness_entry(analyzer) }
+        end
+
+        private
+
+        attr_reader :analyzer_names, :analyzers
+
+        def selected_analyzers
+          return analyzers if analyzer_names.empty?
+
+          analyzers.select { |analyzer| analyzer_names.include?(rule_id_for(analyzer)) }
+        end
+
+        def readiness_entry(analyzer)
+          note = NOTES[rule_id_for(analyzer)]
+          return unless note
+
+          analyzer_fields(analyzer).merge(note)
+        end
+
+        def analyzer_fields(analyzer)
+          status = analyzer::PROJECT_ANALYZER_STATUS
+          default_output = Commands::Scan::ProjectAnalyzerRunner.default_output_analyzer?(analyzer)
+
+          { "rule_id" => rule_id_for(analyzer), "status" => status, "default_output" => default_output,
+            "disposition" => disposition_for(status, default_output) }
+        end
+
+        def rule_id_for(analyzer)
+          analyzer::RULE_ID
+        end
+
+        def disposition_for(status, default_output)
+          "#{status_label(status)}; #{default_output_label(default_output)}."
+        end
+
+        def status_label(status)
+          return "Candidate-only" if status == "candidate"
+          return "Validated opt-in" if status == "validated"
+
+          status.to_s
+        end
+
+        def default_output_label(default_output)
+          default_output ? "default-output eligible" : "not default-output eligible"
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/calibration/project_analyzer_evidence_runner/summary.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require "open3"
+require "time"
+
+require_relative "../../project_index"
+require_relative "../../commands/scan/project_analyzer_metadata"
+require_relative "../../commands/scan/project_analyzer_offenses"
+require_relative "../../commands/scan/project_analyzer_runner"
+require_relative "readiness_catalog"
+
+module MetzScan
+  module Calibration
+    module ProjectAnalyzerEvidenceRunner
+      class Summary
+        def initialize(options)
+          @options = options
+        end
+
+        def to_h
+          target_runs = targets.map { |target| target_run_for(target).call }
+          SummaryPayload.new(summary_payload_options(target_runs)).to_h
+        end
+
+        private
+
+        attr_reader :options
+
+        def target_run_for(target)
+          TargetRun.new(target_run_options(target))
+        end
+
+        def target_run_options(target)
+          options.slice(:target_set, :default_output, :index_builder, :finding_runner).merge(target: target)
+        end
+
+        def summary_payload_options(target_runs)
+          { target_runs: target_runs, default_output: default_output, fixture_root: fixture_root,
+            analyzer_names: analyzer_names, targets_file: targets_file, baseline_file: baseline_file }
+        end
+
+        def targets = options.fetch(:targets)
+
+        def default_output = options.fetch(:default_output)
+
+        def fixture_root = options.fetch(:fixture_root)
+
+        def analyzer_names = options.fetch(:analyzer_names)
+
+        def targets_file = options.fetch(:targets_file)
+
+        def baseline_file = options[:baseline_file]
+      end
+
+      class TargetRun
+        def initialize(options)
+          @options = options
+        end
+
+        attr_reader :findings, :offenses
+
+        def call
+          @findings = project_findings
+          @offenses = Commands::Scan::ProjectAnalyzerOffenses.build(findings).offenses
+          self
+        end
+
+        def metadata
+          identity_metadata.merge(result_metadata)
+        end
+
+        private
+
+        attr_reader :options
+
+        def target = options.fetch(:target)
+
+        def target_set = options.fetch(:target_set)
+
+        def default_output = options.fetch(:default_output)
+
+        def finding_runner = options.fetch(:finding_runner)
+
+        def scan_paths
+          @scan_paths ||= target_set.scan_paths_for(target)
+        end
+
+        def index
+          @index ||= index_for(options.fetch(:index_builder))
+        end
+
+        def index_for(index_builder)
+          return NoScanIndex.new if scan_paths.empty?
+
+          index_builder.call(scan_paths)
+        end
+
+        def identity_metadata
+          { "name" => File.basename(target), "root" => target, "scan_paths" => scan_paths,
+            "git" => GitMetadata.new(target).to_h, "index" => IndexMetadata.new(index).to_h }
+        end
+
+        def result_metadata
+          { "project_analyzers" => project_analyzer_summary, "finding_count" => findings.size,
+            "offense_count" => offenses.size, "breakdowns" => breakdowns,
+            "notable_findings" => notable_findings }
+        end
+
+        def project_findings
+          return [] if scan_paths.empty?
+
+          finding_runner.call(scan_paths, index: index, default_output: default_output)
+        end
+
+        def project_analyzer_summary
+          Commands::Scan::ProjectAnalyzerMetadata.summary(findings, offenses)
+        end
+
+        def breakdowns
+          Commands::Scan::ProjectAnalyzerBreakdown.new(findings).to_h
+        end
+
+        def notable_findings
+          NotableFindings.new(findings, target_name: File.basename(target)).to_a
+        end
+      end
+
+      class SummaryPayload
+        def initialize(options)
+          @options = options
+        end
+
+        def to_h
+          summary = identity_fields.merge(target_fields).merge(project_fields)
+          baseline_file ? summary.merge("baseline_delta" => baseline_delta_for(summary)) : summary
+        end
+
+        private
+
+        attr_reader :options
+
+        def target_runs = options.fetch(:target_runs)
+
+        def default_output = options.fetch(:default_output)
+
+        def fixture_root = options.fetch(:fixture_root)
+
+        def analyzer_names = options.fetch(:analyzer_names)
+
+        def targets_file = options.fetch(:targets_file)
+
+        def baseline_file = options[:baseline_file]
+
+        def identity_fields
+          { "generated_at" => Time.now.utc.iso8601, "default_output" => default_output,
+            "fixture_root" => fixture_root, "analyzer_filter" => analyzer_names,
+            "targets_file" => targets_file }.compact
+        end
+
+        def target_fields
+          { "targets" => target_runs.map(&:metadata) }
+        end
+
+        def project_fields
+          { "project_analyzers" => project_analyzer_summary_with_readiness, "finding_count" => findings.size,
+            "offense_count" => offenses.size, "breakdowns" => breakdowns,
+            "notable_findings" => notable_findings }
+        end
+
+        def findings = target_runs.flat_map(&:findings)
+
+        def offenses = target_runs.flat_map(&:offenses)
+
+        def notable_findings = target_runs.flat_map { |target_run| target_run.metadata.fetch("notable_findings") }
+
+        def project_analyzer_summary
+          Commands::Scan::ProjectAnalyzerMetadata.summary(findings, offenses)
+        end
+
+        def project_analyzer_summary_with_readiness
+          project_analyzer_summary.merge("readiness" => readiness_entries)
+        end
+
+        def readiness_entries
+          ReadinessCatalog.new(analyzer_names: analyzer_names).to_a
+        end
+
+        def breakdowns
+          Commands::Scan::ProjectAnalyzerBreakdown.new(findings).to_h
+        end
+
+        def baseline_delta_for(summary)
+          BaselineDelta.new(summary: summary, baseline_file: baseline_file).to_h
+        end
+      end
+
+      class NotableFindings
+        INCLUDED_CONFIDENCES = %w[high medium].freeze
+        LIMIT = 20
+        private_constant :INCLUDED_CONFIDENCES, :LIMIT
+
+        def initialize(findings, target_name:)
+          @findings = findings
+          @target_name = target_name
+        end
+
+        def to_a
+          findings.select { |finding| notable?(finding) }
+                  .sort_by { |finding| sort_key(finding) }
+                  .first(LIMIT)
+                  .map { |finding| finding_metadata(finding) }
+        end
+
+        private
+
+        attr_reader :findings, :target_name
+
+        def notable?(finding)
+          INCLUDED_CONFIDENCES.include?(triage_metadata(finding)["confidence"])
+        end
+
+        def sort_key(finding)
+          Commands::Scan::ProjectAnalyzerTriagePriority.sort_key(triage_metadata(finding)) +
+            [finding.rule_id.to_s, finding.message.to_s]
+        end
+
+        def finding_metadata(finding)
+          triage_metadata(finding).merge(identity_metadata(finding), detail_metadata(finding)).compact
+        end
+
+        def identity_metadata(finding)
+          { "target" => target_name, "rule_id" => finding.rule_id, "message" => finding.message }
+        end
+
+        def detail_metadata(finding)
+          { "category" => category_for(finding), "metadata" => analyzer_metadata(finding),
+            "occurrence" => occurrence_metadata(finding) }
+        end
+
+        def triage_metadata(finding)
+          Commands::Scan::ProjectAnalyzerMetadata.triage_metadata(finding)
+        end
+
+        def analyzer_metadata(finding)
+          Commands::Scan::ProjectAnalyzerMetadata.analyzer_metadata(finding)
+        end
+
+        def category_for(finding)
+          Commands::Scan::ProjectAnalyzerMetadata.category_for(finding)
+        end
+
+        def occurrence_metadata(finding)
+          occurrence = Array(finding.report_occurrences).compact.first
+          return unless occurrence
+
+          { "path" => occurrence.path, "line" => occurrence_line(occurrence),
+            "context" => occurrence_context(occurrence) }.compact
+        end
+
+        def occurrence_line(occurrence)
+          return occurrence.report_line if occurrence.respond_to?(:report_line)
+          return occurrence.line if occurrence.respond_to?(:line)
+
+          nil
+        end
+
+        def occurrence_context(occurrence)
+          occurrence.context if occurrence.respond_to?(:context)
+        end
+      end
+
+      class NoScanIndex
+        def backend_name = :none
+
+        def available? = false
+
+        def reason = "no top-level app/ or lib/ scan paths under calibration target"
+
+        def indexed_files = []
+
+        def index_errors = []
+
+        def diagnostics = []
+      end
+
+      class IndexMetadata
+        def initialize(index)
+          @index = index
+        end
+
+        def to_h
+          availability_fields.merge(count_fields).compact
+        end
+
+        private
+
+        attr_reader :index
+
+        def availability_fields
+          { "backend" => index.backend_name.to_s, "available" => index.available?,
+            "reason" => index.reason }
+        end
+
+        def count_fields
+          { "indexed_file_count" => index.indexed_files.size, "index_error_count" => index.index_errors.size,
+            "diagnostic_count" => index.diagnostics.size }
+        end
+      end
+
+      class GitMetadata
+        def initialize(target)
+          @target = target
+        end
+
+        def to_h
+          { "branch" => git_capture("branch", "--show-current"),
+            "revision" => git_capture("rev-parse", "HEAD") }.compact
+        end
+
+        private
+
+        attr_reader :target
+
+        def git_capture(*)
+          stdout, _stderr, status = Open3.capture3("git", "-C", target, *)
+          return unless status.success?
+
+          stdout.strip.then { |value| value unless value.empty? }
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/calibration/project_analyzer_evidence_runner/target_set.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module MetzScan
+  module Calibration
+    module ProjectAnalyzerEvidenceRunner
+      class TargetSet
+        DEFAULT_SCAN_CHILDREN = %w[app lib].freeze
+
+        def initialize(paths:, default_apps_path:, targets_file: nil)
+          @paths = Array(paths)
+          @default_apps_path = default_apps_path
+          @targets_file = targets_file && File.expand_path(targets_file)
+          reject_mixed_target_inputs!
+        end
+
+        attr_reader :targets_file
+
+        def paths = raw_targets.map { |path| File.expand_path(path) }.uniq.sort
+
+        def ensure_present!
+          missing = paths.reject { |path| File.exist?(path) }
+          raise Error, "calibration target missing: #{missing.first}" unless missing.empty?
+
+          missing_scan_path = manifest_scan_paths.flatten.find { |path| !File.directory?(path) }
+          raise Error, "calibration scan path missing: #{missing_scan_path}" if missing_scan_path
+        end
+
+        def scan_paths_for(target)
+          manifest_paths = manifest_scan_paths_by_target[File.expand_path(target)]
+          return manifest_paths if manifest_paths
+
+          scan_paths = scan_children_for(target)
+          scan_paths = [target] if scan_paths.empty? && explicit_targets?
+          scan_paths.map { |path| File.expand_path(path) }
+        end
+
+        private
+
+        attr_reader :default_apps_path
+
+        def explicit_targets?
+          !@paths.empty?
+        end
+
+        def raw_targets
+          return manifest_target_roots if targets_file
+
+          @paths.empty? ? discovered_default_targets : @paths
+        end
+
+        def discovered_default_targets
+          return [default_apps_path] unless File.directory?(default_apps_path)
+
+          default_target_children.empty? ? [default_apps_path] : default_target_children
+        end
+
+        def default_target_children
+          Dir.children(default_apps_path)
+             .map { |child| File.join(default_apps_path, child) }
+             .select { |path| File.directory?(path) }
+        end
+
+        def scan_children_for(target)
+          DEFAULT_SCAN_CHILDREN.map { |child| File.join(target, child) }
+                               .select { |path| File.directory?(path) }
+        end
+
+        def reject_mixed_target_inputs!
+          return unless targets_file && explicit_targets?
+
+          raise Error, "cannot combine --targets-file with explicit PATH targets"
+        end
+
+        def manifest_target_roots
+          manifest_entries.map { |entry| entry.fetch("root") }
+        end
+
+        def manifest_scan_paths_by_target
+          return {} unless targets_file
+
+          @manifest_scan_paths_by_target ||= manifest_entries.to_h do |entry|
+            root = File.expand_path(entry.fetch("root"))
+            [root, Array(entry.fetch("scan_paths")).map { |path| File.expand_path(path, root) }]
+          end
+        end
+
+        def manifest_scan_paths
+          return [] unless targets_file
+
+          manifest_scan_paths_by_target.values
+        end
+
+        def manifest_entries
+          @manifest_entries ||= parse_manifest_entries
+        end
+
+        def parse_manifest_entries
+          target_entries.map { |entry| normalize_manifest_entry(entry) }
+        rescue Psych::Exception => e
+          raise Error, "invalid calibration targets file: #{e.message}"
+        end
+
+        def target_entries
+          manifest_document.fetch("targets").tap do |entries|
+            raise Error, "calibration targets file must contain a targets list" unless entries.is_a?(Array)
+          end
+        rescue KeyError
+          raise Error, "calibration targets file must contain a targets list"
+        end
+
+        def manifest_document
+          raise Error, "calibration targets file missing: #{targets_file}" unless File.file?(targets_file)
+
+          YAML.safe_load_file(targets_file, aliases: false) || {}
+        end
+
+        def normalize_manifest_entry(entry)
+          raise Error, "calibration target entry must be a mapping" unless entry.is_a?(Hash)
+
+          { "root" => manifest_entry_root(entry), "scan_paths" => manifest_entry_scan_paths(entry) }
+        end
+
+        def manifest_entry_root(entry)
+          entry.fetch("root") { raise Error, "calibration target entry missing root" }.to_s
+        end
+
+        def manifest_entry_scan_paths(entry)
+          scan_paths = entry.fetch("scan_paths") { raise Error, "calibration target entry missing scan_paths" }
+          raise Error, "calibration target scan_paths must be a list" unless scan_paths.is_a?(Array)
+          raise Error, "calibration target scan_paths must not be empty" if scan_paths.empty?
+
+          scan_paths.map(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/metz_scan/calibration/project_analyzer_evidence_runner.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "project_analyzer_evidence_runner/artifact_writer"
+require_relative "project_analyzer_evidence_runner/baseline_delta"
+require_relative "project_analyzer_evidence_runner/collaborators"
+require_relative "project_analyzer_evidence_runner/markdown_renderer"
+require_relative "project_analyzer_evidence_runner/summary"
+require_relative "project_analyzer_evidence_runner/target_set"
+
+module MetzScan
+  module Calibration
+    module ProjectAnalyzerEvidenceRunner
+      class Error < StandardError; end
+
+      DEFAULT_APPS_PATH = File.join("tmp", "project-analyzer-calibration", "apps").freeze
+      DEFAULT_RESULTS_PATH = File.join("tmp", "project-analyzer-calibration", "results").freeze
+
+      def self.default_apps_path = File.expand_path(DEFAULT_APPS_PATH)
+
+      def self.default_results_path = File.expand_path(DEFAULT_RESULTS_PATH)
+
+      def self.summarize(**options)
+        options = summarize_options(options)
+        targets = target_set(options[:paths], options[:targets_file])
+        resolved_summary_options = summary_options(targets, options)
+        targets.ensure_present!
+        Summary.new(resolved_summary_options).to_h
+      end
+
+      def self.write_artifacts(summary, output_dir: default_results_path, run_id: nil)
+        ArtifactWriter.new(summary: summary, output_dir: output_dir, run_id: run_id).call
+      end
+
+      def self.target_set(paths, targets_file)
+        TargetSet.new(paths: paths, default_apps_path: default_apps_path, targets_file: targets_file)
+      end
+
+      def self.summarize_options(options)
+        { paths: nil, default_output: false, analyzer_names: nil, targets_file: nil,
+          baseline_file: nil, index_builder: nil, finding_runner: nil }.merge(options)
+      end
+
+      def self.summary_options(targets, options)
+        analyzer_names = Array(options[:analyzer_names]).compact
+        analyzers = AnalyzerSelection.new(analyzer_names).call
+        base_summary_options(targets, options[:default_output], analyzer_names, options[:baseline_file])
+          .merge(collaborator_options(options, analyzers))
+      end
+
+      def self.collaborator_options(options, analyzers)
+        { index_builder: options[:index_builder] || ProjectIndex.method(:build),
+          finding_runner: options[:finding_runner] || FindingRunner.new(analyzers: analyzers) }
+      end
+
+      def self.base_summary_options(targets, default_output, analyzer_names, baseline_file)
+        { targets: targets.paths, target_set: targets,
+          default_output: default_output, fixture_root: default_apps_path,
+          analyzer_names: analyzer_names, targets_file: targets.targets_file, baseline_file: baseline_file }
+      end
+      private_class_method :target_set, :summary_options
+      private_class_method :base_summary_options
+    end
+  end
+end