code_sunset 0.1.0

data/lib/code_sunset/feature_usage_series.rb

@@ -0,0 +1,59 @@
+module CodeSunset
+  class FeatureUsageSeries
+    DEFAULT_WINDOW_DAYS = 30
+
+    def initialize(feature:, filters: {})
+      @feature = feature
+      @filters = filters.to_h.symbolize_keys
+    end
+
+    def call
+      date_range = normalized_range
+      analytics = CodeSunset::AnalyticsFilters.new(filters)
+
+      series = if analytics.raw_dimension_filters?
+        effective_range = analytics.retain_range(date_range)
+        feature.events.apply_filters(analytics.raw_filters).where(occurred_at: effective_range).group("DATE(occurred_at)").count
+      else
+        rollup_series = feature.daily_rollups.apply_filters(analytics.rollup_filters).where(day: date_range.first.to_date..date_range.last.to_date).group(:day).sum(:hits_count)
+        raw_series_fallback(rollup_series, date_range, analytics)
+      end
+
+      fill_gaps(series, date_range)
+    end
+
+    private
+
+    attr_reader :feature, :filters
+
+    def normalized_range
+      from = parse_time(filters[:from]) || DEFAULT_WINDOW_DAYS.days.ago.beginning_of_day
+      to = parse_time(filters[:to]) || Time.current.end_of_day
+      from.beginning_of_day..to.end_of_day
+    end
+
+    def raw_series_fallback(rollup_series, date_range, analytics)
+      return rollup_series if rollup_series.present?
+
+      feature.events
+        .apply_filters(analytics.rollup_filters)
+        .where(occurred_at: date_range)
+        .group("DATE(occurred_at)")
+        .count
+    end
+
+    def parse_time(value)
+      return if value.blank?
+
+      Time.zone.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    def fill_gaps(series, date_range)
+      (date_range.first.to_date..date_range.last.to_date).each_with_object({}) do |day, memo|
+        memo[day] = series[day] || series[day.to_s] || 0
+      end
+    end
+  end
+end

data/lib/code_sunset/identity_hash.rb

@@ -0,0 +1,9 @@
+module CodeSunset
+  class IdentityHash
+    class << self
+      def digest(value)
+        Digest::SHA256.hexdigest(value.to_s)
+      end
+    end
+  end
+end

data/lib/code_sunset/instrumentation.rb

@@ -0,0 +1,17 @@
+module CodeSunset
+  class Instrumentation
+    EVENT_NAME = "code_sunset.hit".freeze
+
+    class << self
+      def hit(feature_key, **attrs)
+        payload = CodeSunset::EventPayload.build(feature_key, attrs)
+        return unless payload
+
+        ActiveSupport::Notifications.instrument(EVENT_NAME, payload)
+      rescue StandardError => error
+        CodeSunset.log_error("instrumentation", error)
+        nil
+      end
+    end
+  end
+end

data/lib/code_sunset/job_context.rb

@@ -0,0 +1,17 @@
+module CodeSunset
+  module JobContext
+    extend ActiveSupport::Concern
+
+    included do
+      around_perform :with_code_sunset_job_context
+    end
+
+    private
+
+    def with_code_sunset_job_context
+      CodeSunset.with_context(job_class: self.class.name, source: "job") do
+        yield
+      end
+    end
+  end
+end

data/lib/code_sunset/removal_candidate_query.rb

@@ -0,0 +1,17 @@
+module CodeSunset
+  class RemovalCandidateQuery
+    def initialize(filters = {})
+      @filters = filters
+    end
+
+    def call
+      CodeSunset::FeatureQuery.new(filters).call.select do |snapshot|
+        %w[candidate_for_removal safe_to_remove].include?(snapshot.status)
+      end.sort_by { |snapshot| [-snapshot.score.to_f, snapshot.feature.key] }
+    end
+
+    private
+
+    attr_reader :filters
+  end
+end

data/lib/code_sunset/removal_prompt_builder.rb

@@ -0,0 +1,331 @@
+require "find"
+require "pathname"
+
+module CodeSunset
+  RemovalPromptArtifact = Struct.new(
+    :prompt_markdown,
+    :evidence_markdown,
+    :summary,
+    :search_matches,
+    :signals,
+    :warnings,
+    keyword_init: true
+  )
+
+  class RemovalPromptBuilder
+    SearchMatch = Struct.new(:path, :line_number, :line_preview, keyword_init: true)
+
+    SEARCH_DIRECTORIES = %w[app config lib db test spec].freeze
+    EXCLUDED_DIRECTORY_NAMES = %w[log tmp storage node_modules .git].freeze
+    EXCLUDED_PATH_FRAGMENTS = ["vendor/bundle"].freeze
+    MATCH_LIMIT = 20
+    RECENT_EVENT_LIMIT = 5
+    PREVIEW_LIMIT = 180
+
+    def initialize(feature:, snapshot:, filters:, top_orgs:, top_users:, request_paths:, job_usage:, recent_events:, recent_events_total_count:, usage_series:, root: Rails.root)
+      @feature = feature
+      @snapshot = snapshot
+      @filters = filters.to_h.symbolize_keys
+      @top_orgs = Array(top_orgs)
+      @top_users = Array(top_users)
+      @request_paths = Array(request_paths)
+      @job_usage = Array(job_usage)
+      @recent_events = Array(recent_events)
+      @recent_events_total_count = recent_events_total_count.to_i
+      @usage_series = usage_series.to_h
+      @root = Pathname.new(root.to_s)
+    end
+
+    def call
+      search_matches = build_search_matches
+      warnings = build_warnings(search_matches)
+      signals = build_signals(search_matches)
+
+      RemovalPromptArtifact.new(
+        prompt_markdown: build_prompt(signals, warnings, search_matches),
+        evidence_markdown: build_evidence(signals, warnings, search_matches),
+        summary: build_summary,
+        search_matches: search_matches,
+        signals: signals,
+        warnings: warnings
+      )
+    end
+
+    private
+
+    attr_reader :feature, :snapshot, :filters, :top_orgs, :top_users, :request_paths, :job_usage, :recent_events, :recent_events_total_count, :usage_series, :root
+
+    def build_prompt(signals, warnings, search_matches)
+      lines = []
+      lines << "# Removal Prompt: #{feature.key}"
+      lines << ""
+      lines << "You are helping remove the Rails feature `#{feature.key}` conservatively."
+      lines << ""
+      lines << "## Objective"
+      lines << "Assess whether `#{feature.key}` can be retired and identify the safest way to remove the feature and associated code."
+      lines << ""
+      lines << "## Working Rules"
+      lines << "- Treat runtime evidence as the source of truth for recent usage."
+      lines << "- Inspect the code references below before changing anything."
+      lines << "- Prefer staged disablement or guarded rollout steps before hard deletion when risk is non-trivial."
+      lines << "- If the evidence is insufficient for deletion, say so clearly and recommend the next safest step."
+      lines << ""
+      lines << "## Runtime Evidence"
+      lines << "- Status: #{signals[:status]}"
+      lines << "- Removal score: #{signals[:score]}"
+      lines << "- Last seen: #{signals[:last_seen]}"
+      lines << "- Activity: #{signals[:hits_7d]} hits in 7d, #{signals[:hits_30d]} hits in 30d"
+      lines << "- Reach: #{signals[:unique_orgs_count]} orgs, #{signals[:unique_users_count]} users in 30d"
+      lines << "- Paid usage: #{signals[:paid_hits_30d]}"
+      lines << "- Filters applied: #{signals[:filter_context]}"
+      lines << "- Repo matches found: #{search_matches.count}"
+      lines << ""
+      lines << "## What To Do"
+      lines << "1. Verify whether this feature still appears necessary based on the runtime evidence."
+      lines << "2. Review the matching code references and identify controllers, jobs, services, views, routes, tests, configs, and docs tied to `#{feature.key}`."
+      lines << "3. Propose the safest removal approach, including any staged disablement, cleanup ordering, and rollback considerations."
+      lines << "4. List the exact files likely to change."
+      lines << "5. Call out risks, unknowns, and what would block safe removal."
+      lines << "6. Provide a verification plan covering tests, runtime checks, and post-removal monitoring."
+      lines << ""
+      lines << "## Expected Output"
+      lines << "- A short assessment of whether the feature is removable now"
+      lines << "- A conservative removal plan"
+      lines << "- The exact files to inspect or change"
+      lines << "- Risks and unknowns"
+      lines << "- Verification steps"
+      lines << ""
+      lines << "## Notes"
+      lines << "- Recent event detail and raw-only filters may be limited by retained raw event history."
+      lines << "- Use the evidence pack below as the starting point, then inspect the codebase directly as needed."
+      if warnings.any?
+        lines << ""
+        lines << "## Warnings"
+        warnings.each { |warning| lines << "- #{warning}" }
+      end
+      lines.join("\n")
+    end
+
+    def build_evidence(signals, warnings, search_matches)
+      lines = []
+      lines << "# Evidence Pack: #{feature.key}"
+      lines << ""
+      lines << "## Summary"
+      lines << summary_line(build_summary)
+      lines << ""
+      lines << "## Feature Metadata"
+      lines << summary_line("Owner: #{feature.owner.presence || "Unassigned"}")
+      lines << summary_line("Description: #{feature.description.presence || "No description provided."}")
+      lines << summary_line("Sunset after days: #{feature.sunset_after_days}")
+      lines << summary_line("Remove after days unused: #{feature.remove_after_days_unused}")
+      lines << ""
+      lines << "## Runtime Signals"
+      lines << summary_line("Status: #{signals[:status]}")
+      lines << summary_line("Removal score: #{signals[:score]}")
+      lines << summary_line("Last seen: #{signals[:last_seen]}")
+      lines << summary_line("Hits: #{signals[:hits_7d]} in 7d, #{signals[:hits_30d]} in 30d")
+      lines << summary_line("Reach: #{signals[:unique_orgs_count]} orgs, #{signals[:unique_users_count]} users in 30d")
+      lines << summary_line("Paid usage in 30d: #{signals[:paid_hits_30d]}")
+      lines << summary_line("Filters applied: #{signals[:filter_context]}")
+      lines << summary_line("Trend points captured: #{signals[:usage_points]}")
+      lines << ""
+      lines << "## Score Breakdown"
+      score_breakdown.each do |label, detail|
+        lines << summary_line("#{label}: #{detail}")
+      end
+      lines << ""
+      lines << "## Top Orgs"
+      lines.concat(list_or_empty(top_orgs))
+      lines << ""
+      lines << "## Top Users"
+      lines.concat(list_or_empty(top_users))
+      lines << ""
+      lines << "## Request Paths"
+      lines.concat(list_or_empty(request_paths))
+      lines << ""
+      lines << "## Job Classes"
+      lines.concat(list_or_empty(job_usage))
+      lines << ""
+      lines << "## Recent Event Window"
+      lines << summary_line(recent_event_window_note)
+      lines.concat(recent_event_lines)
+      lines << ""
+      lines << "## Exact Host-App Matches"
+      if search_matches.any?
+        search_matches.each do |match|
+          lines << summary_line("`#{match.path}:#{match.line_number}` — #{match.line_preview}")
+        end
+      else
+        lines << summary_line("No exact feature-key references were found under #{SEARCH_DIRECTORIES.join(', ')}.")
+      end
+      if warnings.any?
+        lines << ""
+        lines << "## Warnings"
+        warnings.each { |warning| lines << summary_line(warning) }
+      end
+      lines.join("\n")
+    end
+
+    def build_summary
+      case snapshot&.status
+      when "safe_to_remove"
+        "This feature looks like a low-risk removal candidate based on inactivity and the current removal score."
+      when "candidate_for_removal"
+        "This feature appears close to removable, but the remaining references and recent signals should be reviewed before code is deleted."
+      when "cooling_down"
+        "This feature is trending toward removal, but recent usage still suggests a staged approach."
+      else
+        "This feature still shows active or uncertain usage and should be treated as a higher-risk removal candidate."
+      end
+    end
+
+    def build_signals(search_matches)
+      {
+        status: snapshot&.status.to_s.tr("_", " ").titleize.presence || "Unknown",
+        score: format("%.1f/100", snapshot&.score.to_f),
+        last_seen: if snapshot&.last_seen_at.present?
+          snapshot.last_seen_at.in_time_zone.strftime("%Y-%m-%d %H:%M:%S %Z")
+        else
+          "Never observed"
+        end,
+        hits_7d: snapshot&.hits_7d.to_i,
+        hits_30d: snapshot&.hits_30d.to_i,
+        unique_orgs_count: snapshot&.unique_orgs_count.to_i,
+        unique_users_count: snapshot&.unique_users_count.to_i,
+        paid_hits_30d: snapshot&.paid_hits_30d.to_i,
+        usage_points: usage_series.size,
+        filter_context: filter_context,
+        search_match_count: search_matches.count
+      }
+    end
+
+    def build_warnings(search_matches)
+      warnings = []
+      warnings << analytics.raw_filter_notice if analytics.raw_filter_notice.present?
+      warnings << "Paid-org traffic still exists in the last 30 days." if snapshot&.paid_hits_30d.to_i.positive?
+      warnings << "The feature still has hits in the last 7 days." if snapshot&.hits_7d.to_i.positive?
+      warnings << "No recent runtime events matched the selected filters." if recent_events_total_count.zero?
+      warnings << "No exact feature-key references were found in the host app." if search_matches.empty?
+      warnings
+    end
+
+    def score_breakdown
+      return {} unless snapshot
+
+      calculator = CodeSunset::ScoreCalculator.new(feature: feature, snapshot: snapshot)
+      calculator.breakdown.transform_values do |component|
+        "#{format('%.1f', component[:score])}/#{format('%.0f', component[:max])} from #{component[:detail]}"
+      end.transform_keys do |key|
+        key.to_s.tr("_", " ").titleize
+      end
+    end
+
+    def list_or_empty(entries)
+      return [summary_line("None in the current window.")] if entries.empty?
+
+      entries.map do |identifier, hits|
+        summary_line("`#{identifier}` — #{hits.to_i} hits")
+      end
+    end
+
+    def recent_event_window_note
+      "Showing #{[recent_events.size, RECENT_EVENT_LIMIT].min} of #{recent_events_total_count} recent events that matched the current filters."
+    end
+
+    def recent_event_lines
+      return [summary_line("No recent events matched the selected filters.")] if recent_events.empty?
+
+      recent_events.first(RECENT_EVENT_LIMIT).map do |event|
+        summary_line("#{event.occurred_at.in_time_zone.strftime('%Y-%m-%d %H:%M:%S %Z')} — #{event.request_path.presence || event.job_class.presence || event.source}")
+      end
+    end
+
+    def build_search_matches
+      matches = []
+
+      searchable_files.each do |path|
+        File.foreach(path, encoding: "UTF-8", invalid: :replace, undef: :replace, replace: "").with_index(1) do |line, line_number|
+          next unless line.include?(feature.key)
+
+          matches << SearchMatch.new(
+            path: relative_path(path),
+            line_number: line_number,
+            line_preview: compact_preview(line)
+          )
+          return matches if matches.size >= MATCH_LIMIT
+        end
+      rescue StandardError
+        next
+      end
+
+      matches
+    end
+
+    def searchable_files
+      files = []
+
+      SEARCH_DIRECTORIES.each do |entry|
+        directory = root.join(entry)
+        next unless directory.exist?
+
+        Find.find(directory.to_s) do |path|
+          if File.directory?(path)
+            basename = File.basename(path)
+            if EXCLUDED_DIRECTORY_NAMES.include?(basename) || excluded_path_fragment?(path)
+              Find.prune
+            else
+              next
+            end
+          end
+
+          next unless File.file?(path)
+          next if excluded_path_fragment?(path)
+          next unless text_file?(path)
+
+          files << path
+        end
+      end
+
+      files.sort
+    end
+
+    def excluded_path_fragment?(path)
+      EXCLUDED_PATH_FRAGMENTS.any? { |fragment| path.include?(fragment) }
+    end
+
+    def text_file?(path)
+      sample = File.binread(path, 1024)
+      !sample.include?("\x00")
+    rescue StandardError
+      false
+    end
+
+    def compact_preview(line)
+      compact = line.to_s.strip.gsub(/\s+/, " ")
+      return compact if compact.length <= PREVIEW_LIMIT
+
+      "#{compact[0, PREVIEW_LIMIT - 1]}…"
+    end
+
+    def relative_path(path)
+      Pathname.new(path).relative_path_from(root).to_s
+    end
+
+    def filter_context
+      visible_filters = filters.except(:page)
+      return "None" if visible_filters.blank?
+
+      visible_filters.map do |key, value|
+        "#{key}=#{value}"
+      end.join(", ")
+    end
+
+    def analytics
+      @analytics ||= CodeSunset::AnalyticsFilters.new(filters)
+    end
+
+    def summary_line(text)
+      "- #{text}"
+    end
+  end
+end

data/lib/code_sunset/score_calculator.rb

@@ -0,0 +1,83 @@
+module CodeSunset
+  class ScoreCalculator
+    def initialize(feature:, snapshot:)
+      @feature = feature
+      @snapshot = snapshot
+    end
+
+    def score
+      return 0.0 unless snapshot
+
+      breakdown.values.sum { |component| component[:score] }.round(2)
+    end
+
+    def breakdown
+      return {} unless snapshot
+
+      {
+        recency: recency_breakdown,
+        volume: volume_breakdown,
+        orgs: org_breakdown,
+        paid_usage: paid_usage_breakdown
+      }
+    end
+
+    private
+
+    attr_reader :feature, :snapshot
+
+    def days_unused
+      @days_unused ||= if snapshot.last_seen_at.present?
+        (Time.current.to_date - snapshot.last_seen_at.to_date).to_i
+      else
+        (Time.current.to_date - (feature.created_at || Time.current).to_date).to_i
+      end
+    end
+
+    def recency_breakdown
+      score = ([days_unused, 120].min / 120.0 * 45).round(2)
+
+      {
+        score: score,
+        max: 45.0,
+        detail: "#{days_unused} days unused"
+      }
+    end
+
+    def volume_breakdown
+      recent_hits = [snapshot.hits_30d.to_i, 100].min
+      score = ((1 - (recent_hits / 100.0)) * 25).round(2)
+
+      {
+        score: score,
+        max: 25.0,
+        detail: "#{snapshot.hits_30d.to_i} hits in last 30d"
+      }
+    end
+
+    def org_breakdown
+      orgs = [snapshot.unique_orgs_count.to_i, 20].min
+      score = ((1 - (orgs / 20.0)) * 20).round(2)
+
+      {
+        score: score,
+        max: 20.0,
+        detail: "#{snapshot.unique_orgs_count.to_i} orgs in last 30d"
+      }
+    end
+
+    def paid_usage_breakdown
+      score = snapshot.paid_hits_30d.to_i.zero? ? 10.0 : 0.0
+
+      {
+        score: score,
+        max: 10.0,
+        detail: if snapshot.paid_hits_30d.to_i.zero?
+          "no paid hits in last 30d"
+        else
+          "#{snapshot.paid_hits_30d.to_i} paid hits in last 30d"
+        end
+      }
+    end
+  end
+end

data/lib/code_sunset/status_engine.rb

@@ -0,0 +1,38 @@
+module CodeSunset
+  class StatusEngine
+    def initialize(feature:, last_seen_at:, reference_time: Time.current)
+      @feature = feature
+      @last_seen_at = last_seen_at
+      @reference_time = reference_time
+    end
+
+    def status
+      return "safe_to_remove" if days_unused >= sunset_after_days
+      return "candidate_for_removal" if days_unused >= remove_after_days_unused
+      return "cooling_down" if days_unused >= cooling_down_days
+
+      "active"
+    end
+
+    private
+
+    attr_reader :feature, :last_seen_at, :reference_time
+
+    def days_unused
+      baseline = last_seen_at || feature.created_at || reference_time
+      (reference_time.to_date - baseline.to_date).to_i
+    end
+
+    def sunset_after_days
+      feature.sunset_after_days.presence || 90
+    end
+
+    def remove_after_days_unused
+      feature.remove_after_days_unused.presence || 60
+    end
+
+    def cooling_down_days
+      [14, (remove_after_days_unused / 2.0).ceil].max
+    end
+  end
+end

data/lib/code_sunset/subscriber.rb

@@ -0,0 +1,24 @@
+module CodeSunset
+  class Subscriber
+    class << self
+      def subscribe!
+        return @subscription if @subscription
+
+        @subscription = ActiveSupport::Notifications.subscribe(CodeSunset::Instrumentation::EVENT_NAME) do |_name, _start, _finish, _id, payload|
+          CodeSunset::EventIngestor.ingest(payload)
+        end
+      end
+
+      def unsubscribe!
+        return unless @subscription
+
+        ActiveSupport::Notifications.unsubscribe(@subscription)
+        @subscription = nil
+      end
+
+      def subscription
+        @subscription
+      end
+    end
+  end
+end

data/lib/code_sunset/version.rb

@@ -0,0 +1,3 @@
+module CodeSunset
+  VERSION = "0.1.0"
+end