lcp 0.1.0

data/lib/lcp_ruby/i18n_check/registry_walker.rb

@@ -0,0 +1,621 @@
+require_relative "offense"
+require_relative "configuration"
+require_relative "key_deriver"
+
+module LcpRuby
+  module I18nCheck
+    # Boot-time registry walker — the single pass that backs
+    # `lcp_ruby:i18n_check`.
+    #
+    # Iterates every labeled element in `LcpRuby.loader.*_definitions`
+    # through the iteration façade on each Definition class
+    # (`each_section`, `each_field`, …). For each element:
+    #
+    #   1. Computes the canonical i18n key chain via `KeyDeriver`.
+    #   2. Checks `I18n.exists?(key, locale, fallback: false)` for every
+    #      configured locale.
+    #   3. Emits an `Offense`:
+    #        - `:literal_in_dsl` when the author overrode the humanized
+    #          default AND the locale entry is missing
+    #        - `:missing_translation` otherwise (or always for
+    #          `missing_only` Tier-1 kinds without a DSL literal —
+    #          workflow states, menu entries, transitions)
+    #      Severity for missing-translation downgrades to `:info` when
+    #      `I18n.fallbacks` covers every missing locale.
+    #
+    # YAML-loaded definitions surface as `source: nil` from the façade.
+    # The walker falls back to `definition.source_path` (line nil) so
+    # they still emit with file context, just without per-row precision.
+    # Definitions with NO source at all (engine-internal definitions
+    # registered programmatically) are skipped — see Decision 4.
+    #
+    # See `docs/design/i18n_consistency_check.md` for the full
+    # specification.
+    class RegistryWalker
+      # Line-precise opt-out marker. The pattern (and the mandatory non-empty
+      # reason after the colon) mirrors `lcp_ruby:i18n_lint` and the
+      # `LcpRuby/NoHardcodedI18nString` cop. Recognized only when the
+      # offense carries both file and line — YAML-loaded definitions
+      # (line: nil) opt out via `config.exclude` globs instead.
+      EXEMPT_RE = /#\s*i18n-exempt:\s*(?<reason>\S.*)/.freeze
+
+      def initialize(config: Configuration.new, key_deriver: KeyDeriver.new, loader: nil)
+        @config      = config
+        @key_deriver = key_deriver
+        @loader      = loader || (defined?(LcpRuby) && LcpRuby.respond_to?(:loader) ? LcpRuby.loader : nil)
+        raise ArgumentError, "RegistryWalker requires a loader" unless @loader
+        @file_cache  = {}
+      end
+
+      def run
+        offenses = []
+        @loader.presenter_definitions.each_value  { |p| offenses.concat(walk_presenter(p)) }
+        @loader.model_definitions.each_value      { |m| offenses.concat(walk_model(m)) }
+        @loader.workflow_definitions.each_value   { |w| offenses.concat(walk_workflow(w)) }
+        @loader.view_group_definitions.each_value { |v| offenses.concat(walk_view_group(v)) }
+        if @loader.respond_to?(:page_definitions)
+          @loader.page_definitions.each_value { |p| offenses.concat(walk_page(p)) }
+        end
+        offenses.concat(walk_menu(@loader.menu_definition)) if @loader.respond_to?(:menu_defined?) && @loader.menu_defined?
+        dedup_tier2(offenses.compact)
+      end
+
+      private
+
+      # Dedup Tier 2 offenses by `(file, line, kind, value)`. The loader
+      # merges `inherits_from:` parent → child metadata before registering
+      # in `presenter_definitions`, so a parent's `column :x, label: "Y"`
+      # surfaces in every inheriting child carrying the same source-loc
+      # of the parent's DSL line. Without dedup, an N-child inheritance
+      # chain reports the same offense N times.
+      #
+      # Tier 1 offenses are NOT deduped — each presenter has its own
+      # `lcp_ruby.presenters.<name>.sections.<key>` namespace, so
+      # `section "Activities"` shared across N presenters is N legitimate
+      # missing-translation reports, not one. The `keys` array (nil for
+      # Tier 2, populated for Tier 1) is the discriminator.
+      #
+      # YAML-loaded duplicates (`line: nil`) collapse only when `(file,
+      # kind, value)` match — different YAML files report independently.
+      def dedup_tier2(offenses)
+        seen = {}
+        offenses.each_with_object([]) do |o, out|
+          if o.keys.nil?
+            key = [ o.file, o.line, o.kind, o.value ]
+            next if seen[key]
+            seen[key] = true
+          end
+          out << o
+        end
+      end
+
+      # ─── Per-Definition walkers ──────────────────────────────────────
+
+      def walk_presenter(presenter)
+        out = []
+        fb = fallback_source(presenter)
+
+        # `model:` feeds the i18n key template (`lcp_ruby.models.%{model}.other`);
+        # `name:` feeds `expected_humanize_for(:presenter_label, name:)` which
+        # mirrors the runtime fallback (`name.humanize` —
+        # presenter_definition.rb:23, NOT the model's humanize). Both keys
+        # are required; the template ignores `name:`, the override-detection
+        # ignores `model:`.
+        out << check(
+          kind: :presenter_label,
+          value: presenter.label,
+          args: { model: presenter.model, name: presenter.name },
+          source: presenter.source_location_for(:label) || fb
+        )
+
+        presenter.each_view_description do |label:, view:, source:|
+          out << check(
+            kind: :presenter_description,
+            value: label,
+            args: { name: presenter.name, view: view },
+            source: source || fb
+          )
+        end
+
+        presenter.each_section do |label:, section_key:, source:|
+          out << check(
+            kind: :presenter_section,
+            value: label,
+            args: { name: presenter.name, section_key: section_key },
+            source: source || fb
+          )
+        end
+
+        presenter.each_form_submit_label do |label:, action:, source:|
+          out << check(
+            kind: :presenter_form_submit,
+            value: label,
+            args: { name: presenter.name, action: action },
+            source: source || fb
+          )
+        end
+
+        presenter.each_column              { |label:, source:, **|       out << check_tier2(:presenter_column_label, label, source || fb) }
+        presenter.each_form_field_override { |label:, source:, **|       out << check_tier2(:presenter_field_label_override, label, source || fb) }
+        presenter.each_filter              { |label:, source:, **|       out << check_tier2(:presenter_filter_label, label, source || fb) }
+        presenter.each_saved_filter        { |label:, source:, **|       out << check_tier2(:presenter_saved_filter_label, label, source || fb) }
+        presenter.each_tab                 { |label:, source:, **|       out << check_tier2(:presenter_tab_label, label, source || fb) }
+        presenter.each_step                { |label:, source:, **|       out << check_tier2(:presenter_step_label, label, source || fb) }
+
+        presenter.each_custom_action do |label:, action:, source:|
+          out << check(
+            kind: :custom_action_label,
+            value: label,
+            args: { action: action },
+            source: source || fb
+          )
+        end
+
+        out.compact
+      end
+
+      def walk_model(model)
+        out = []
+        fb = fallback_source(model)
+
+        out << check(
+          kind: :model_label_singular,
+          value: model.label,
+          args: { name: model.name },
+          source: model.source_location_for(:label) || fb
+        )
+        out << check(
+          kind: :model_label_plural,
+          value: model.label_plural,
+          args: { name: model.name },
+          source: model.source_location_for(:label_plural) || fb
+        )
+
+        model.each_field do |label:, field:, source:|
+          out << check(
+            kind: :model_field,
+            value: label,
+            args: { model: model.name, field: field },
+            source: source || fb
+          )
+        end
+
+        model.each_enum_value do |label:, field:, value:, source:|
+          out << check(
+            kind: :model_enum_value,
+            value: label,
+            args: { model: model.name, field: field, value: value },
+            source: source || fb
+          )
+        end
+
+        out.compact
+      end
+
+      def walk_workflow(workflow)
+        out = []
+        fb = fallback_source(workflow)
+
+        workflow.each_state do |state:, source:|
+          out << check(
+            kind: :workflow_state,
+            value: nil,
+            args: { workflow: workflow.name, state: state },
+            source: source || fb,
+            missing_only: true
+          )
+        end
+
+        workflow.each_state_description do |description:, source:, **|
+          out << check_tier2(:workflow_state_description, description, source || fb)
+        end
+
+        workflow.each_transition do |label:, transition:, source:|
+          out << check(
+            kind: :workflow_transition,
+            value: label,
+            args: { workflow: workflow.name, transition: transition },
+            source: source || fb,
+            missing_only: true
+          )
+        end
+
+        out.compact
+      end
+
+      def walk_view_group(view_group)
+        out = []
+        fb = fallback_source(view_group)
+        view_group.each_view_label do |label:, source:, **|
+          out << check_tier2(:view_group_view_label, label, source || fb)
+        end
+        out.compact
+      end
+
+      # Maps the yielded MenuDefinition kind onto the KeyDeriver kind
+      # used for tier-1 lookup. Adding a third lintable menu literal is
+      # one entry here plus one in `walk_item` on the MenuDefinition
+      # side — both kinds share the same slug derivation, only the
+      # i18n sub-namespace differs.
+      MENU_KIND_TO_CHECK = {
+        label: :menu_entry,
+        aria_label: :menu_aria_label
+      }.freeze
+
+      def walk_menu(menu)
+        return [] if menu.nil?
+        out = []
+        fb = fallback_source(menu)
+        menu.each_entry do |kind:, value:, source:|
+          check_kind = MENU_KIND_TO_CHECK[kind]
+          next unless check_kind
+          next if value.nil?
+          slug = @key_deriver.parameterize_menu_label(value)
+          out << check(
+            kind: check_kind,
+            value: value,
+            args: { label_slug: slug },
+            source: source || fb,
+            missing_only: true
+          )
+        end
+        out.compact
+      end
+
+      # Pages have no `title:` literal — their schema declares only
+      # `title_key:` (Tier 1 by design). We check that the configured
+      # title_key resolves in every locale; pages without a title_key
+      # opt out of translation (humanize fallback is rendered directly).
+      def walk_page(page)
+        out = []
+        fb = fallback_source(page)
+
+        if page.respond_to?(:title_key) && page.title_key.present?
+          keys = [ page.title_key.to_s ]
+          missing = locales_missing_keys(keys)
+          unless missing.empty?
+            severity = severity_for(:missing_translation, missing)
+            unless severity == :off
+              out << Offense.new(
+                file: fb && fb["file"], line: fb && fb["line"],
+                kind: :missing_translation,
+                severity: severity,
+                method: nil,
+                content: nil, value: nil,
+                suggested_fix: suggested_fix(:missing_translation, keys, missing, nil),
+                keys: keys, missing_in: missing
+              )
+            end
+          end
+        end
+
+        # Literals on chart widgets are not walked: no auto-derived key
+        # namespace exists for page widgets yet (platform-wide follow-up).
+        zones = page.respond_to?(:zones) ? Array(page.zones) : []
+        zones.each do |zone|
+          next unless zone.respond_to?(:widget?) && zone.widget?
+          widget = zone.respond_to?(:widget) ? zone.widget : nil
+          next unless widget.is_a?(Hash) && widget["type"] == "chart"
+          out.concat(walk_chart_widget(page, zone, widget, fb))
+        end
+
+        out.compact
+      end
+
+      CHART_TEXT_KEY_FIELDS = %w[label_key xtitle_key ytitle_key empty_key].freeze
+
+      def walk_chart_widget(_page, _zone, widget, fb)
+        out = []
+
+        CHART_TEXT_KEY_FIELDS.each do |field|
+          key_value = widget[field]
+          next if key_value.blank?
+          out << chart_widget_key_offense(key_value, fb)
+        end
+
+        series = widget["series"]
+        if series.is_a?(Array)
+          series.each do |s|
+            next unless s.is_a?(Hash)
+            key_value = s["name_key"]
+            next if key_value.blank?
+            out << chart_widget_key_offense(key_value, fb)
+          end
+        end
+
+        out.compact
+      end
+
+      def chart_widget_key_offense(key_value, fb)
+        keys = [ key_value.to_s ]
+        missing = locales_missing_keys(keys)
+        return nil if missing.empty?
+        severity = severity_for(:missing_translation, missing)
+        return nil if severity == :off
+        Offense.new(
+          file: fb && fb["file"], line: fb && fb["line"],
+          kind: :missing_translation,
+          severity: severity,
+          method: nil,
+          content: nil, value: nil,
+          suggested_fix: suggested_fix(:missing_translation, keys, missing, nil),
+          keys: keys, missing_in: missing
+        )
+      end
+
+      # Returns a source-location stub for a definition based on its
+      # `source_path` (the `.rb` / `.yml` file the loader read). Used
+      # as a fallback when the façade yields `source: nil` — typically
+      # for YAML-loaded definitions where there's no `caller_locations`
+      # capture site, or for implicit field labels (humanize fallback,
+      # no DSL `label:`). Line is nil because YAML doesn't get walked
+      # at row-precision in this design — file context is enough to
+      # locate the issue.
+      def fallback_source(definition)
+        return nil unless definition.respond_to?(:source_path)
+        path = definition.source_path
+        return nil if path.nil? || path.to_s.empty?
+        { "file" => path.to_s, "line" => nil }
+      end
+
+      # Returns true iff the offense at `source[file]`:`source[line]`
+      # carries an `# i18n-exempt: <reason>` comment. Read source files
+      # lazily and cache so a 1000-offense report only does one open per
+      # file. Returns false (no exemption) when:
+      #   * source is nil
+      #   * source has no concrete line (YAML-loaded — use config.exclude
+      #     glob to opt out at the file level instead)
+      #   * the file can't be read (deleted between scan and check, etc.)
+      def exempt_at?(source)
+        return false unless source
+        file = source["file"]
+        line = source["line"]
+        return false if file.nil? || line.nil?
+
+        lines = file_lines(file)
+        return false unless lines
+        line_text = lines[line - 1]
+        return false unless line_text
+        line_text.match?(EXEMPT_RE)
+      end
+
+      def file_lines(file)
+        @file_cache.fetch(file) do
+          @file_cache[file] = begin
+            File.readlines(file)
+          rescue Errno::ENOENT, Errno::EACCES
+            nil
+          end
+        end
+      end
+
+      # ─── Check helpers ──────────────────────────────────────────────
+
+      # Tier 1 check. `missing_only: true` skips the literal-in-dsl branch
+      # and only emits :missing_translation offenses (used for kinds whose
+      # runtime fallback IS the literal itself — menu_entry, workflow_state,
+      # workflow_transition).
+      def check(kind:, value:, args:, source:, missing_only: false)
+        # Source nil after `source || fallback_source(definition)` means
+        # the definition has no DSL site AND no source_path — typically
+        # an engine-bundled definition that the loader registers
+        # programmatically. Per the design's host-only principle, the
+        # lint should not flag those.
+        return nil if source.nil?
+
+        keys = @key_deriver.derive(kind: kind, **args)
+        return nil if keys.nil?             # Tier 2 — caller should use check_tier2
+
+        missing = locales_missing_keys(keys)
+
+        if missing_only
+          return nil if missing.empty?
+          return nil if exempt_at?(source)
+          return offense_for_missing(source: source, keys: keys, missing: missing)
+        end
+
+        return nil if value.nil? || value.is_a?(Symbol)
+        return nil unless value.is_a?(String)
+        return nil if value.strip.empty?  # `label ""` is a malformed config, not a literal worth flagging
+
+        overrode = author_overrode_default?(value, kind, args)
+
+        # `resolved_label` semantics: a literal that pairs with all-locales-
+        # present is the runtime default fallback, not a violation. Only
+        # flag pure duplicates when the host opts in AND the literal is
+        # actually a meaningful override (drift risk only matters when
+        # the literal differs from the humanize default — otherwise the
+        # locale entry is what gets used and there's nothing to drift).
+        return nil if missing.empty? && (!@config.flag_pure_duplicates || !overrode)
+
+        return nil if exempt_at?(source)
+
+        kind_emitted = overrode ? :literal_in_dsl : :missing_translation
+        severity = severity_for(kind_emitted, missing)
+        return nil if severity == :off
+        Offense.new(
+          file: source && source["file"],
+          line: source && source["line"],
+          kind: kind_emitted,
+          severity: severity,
+          method: nil,
+          content: value,
+          value: value,
+          suggested_fix: suggested_fix(kind_emitted, keys, missing, value),
+          keys: keys,
+          missing_in: missing
+        )
+      end
+
+      # Tier 2 check — UI surfaces where the runtime renders the literal
+      # directly with no `I18n.t` lookup. Emits `:direct_render_label`
+      # offenses; severity routed via `severity_per_kind[:direct_render_label]`.
+      def check_tier2(kind, value, source)
+        return nil if value.nil? || value.is_a?(Symbol)
+        return nil unless value.is_a?(String)
+        return nil if source.nil?            # engine-internal, see check()
+        return nil if @key_deriver.identifier_like?(value)
+        return nil if exempt_at?(source)
+        # `literal_as_default_locale` semantics: Tier 2 surfaces render
+        # the literal directly in every locale (no per-key i18n). When
+        # the host has only the default locale configured, the literal
+        # is intentional in that locale and there are no other locales
+        # to break — silence the report. Multi-locale apps still see
+        # Tier 2 reports because non-default locales would render the
+        # literal too (broken UX in those locales).
+        return nil if tier2_silenced_by_default_locale?
+        severity = @config.severity_for(:direct_render_label)
+        return nil if severity == :off
+
+        Offense.new(
+          file: source && source["file"],
+          line: source && source["line"],
+          kind: :direct_render_label,
+          severity: severity,
+          method: nil,
+          content: value,
+          value: value,
+          suggested_fix: tier2_suggested_fix(kind),
+          keys: nil,
+          missing_in: []
+        )
+      end
+
+      def offense_for_missing(source:, keys:, missing:)
+        severity = severity_for(:missing_translation, missing)
+        return nil if severity == :off
+        Offense.new(
+          file: source && source["file"],
+          line: source && source["line"],
+          kind: :missing_translation,
+          severity: severity,
+          method: nil,
+          content: nil,
+          value: nil,
+          suggested_fix: suggested_fix(:missing_translation, keys, missing, nil),
+          keys: keys,
+          missing_in: missing
+        )
+      end
+
+      # ─── Locale + fallback resolution ───────────────────────────────
+
+      # Returns the configured locales for which `keys` does not resolve.
+      # When `literal_as_default_locale` is set, the default locale is
+      # stripped from the result — the lint treats DSL literals (or
+      # humanize-default fallbacks for missing_only kinds) as the implicit
+      # default-locale value, mirroring what the runtime renders via the
+      # `default:` argument of `I18n.t`. Single-locale apps then never
+      # see "missing in en" reports for entries whose literal IS the
+      # English value; multi-locale apps still see "missing in cs" until
+      # they populate cs.yml. See `CLAUDE.md` § "i18n Principle".
+      def locales_missing_keys(keys)
+        missing = @config.locales.reject { |locale| key_resolves?(keys, locale) }
+        return missing unless @config.literal_as_default_locale
+        return missing unless defined?(I18n) && I18n.respond_to?(:default_locale)
+        missing - [ I18n.default_locale.to_sym ]
+      end
+
+      # Silence Tier 2 reports when the host has only the default locale
+      # configured AND `literal_as_default_locale` is on — the literal is
+      # the intended value in that single locale, no other locales would
+      # render it broken. Memoized: the decision is pure-config, doesn't
+      # change between offense calls.
+      def tier2_silenced_by_default_locale?
+        return @tier2_silenced if defined?(@tier2_silenced)
+        @tier2_silenced = compute_tier2_silenced
+      end
+
+      def compute_tier2_silenced
+        return false unless @config.literal_as_default_locale
+        return false unless defined?(I18n) && I18n.respond_to?(:default_locale)
+        @config.locales == [ I18n.default_locale.to_sym ]
+      end
+
+      def key_resolves?(keys, locale)
+        Array(keys).any? { |k| I18n.exists?(k, locale, fallback: false) }
+      end
+
+      # Severity routing per design §B `severity_for(kind, keys, missing)`.
+      # `:literal_in_dsl` always uses the configured severity. `:missing_translation`
+      # downgrades to `:info` when there is nothing missing, or when every
+      # missing locale is covered by a fallback chain.
+      def severity_for(kind, missing)
+        return @config.severity_for(:literal_in_dsl) if kind == :literal_in_dsl
+        return :info if missing.empty?
+        return :info if all_covered_by_fallback?(missing)
+        @config.severity_for(:missing_translation)
+      end
+
+      def all_covered_by_fallback?(missing)
+        return false unless fallbacks_available?
+
+        missing.all? do |locale|
+          chain = (I18n.fallbacks[locale] || []) - [ locale ]
+          chain.any? { |fb| !missing.include?(fb) }
+        end
+      end
+
+      def fallbacks_available?
+        return @fallbacks_available if defined?(@fallbacks_available)
+        @fallbacks_available = defined?(I18n) && I18n.respond_to?(:fallbacks) && !I18n.fallbacks.nil?
+      end
+
+      # ─── Override detection ─────────────────────────────────────────
+
+      def author_overrode_default?(value, kind, args)
+        return false unless value.is_a?(String)
+        expected = @key_deriver.expected_humanize_for(kind, args)
+        return true if expected.nil?  # no fallback known — treat as override
+        value != expected
+      end
+
+      # ─── Suggested fix messaging ────────────────────────────────────
+
+      def suggested_fix(kind, keys, missing, value)
+        primary = Array(keys).first
+        case kind
+        when :literal_in_dsl
+          if missing.any?
+            "Move literal to locale file(s): add `#{primary}:` to " \
+              "config/locales/{#{missing.map(&:to_s).join(',')}}.yml " \
+              "(or use `label_key:` if the schema declares one)"
+          else
+            "Remove literal `#{value}` — every locale already has #{primary}"
+          end
+        when :missing_translation
+          locales_str = missing.map(&:to_s).join(",")
+          "Add `#{primary}:` to config/locales/{#{locales_str}}.yml " \
+            "(missing in: #{locales_str})"
+        end
+      end
+
+      def tier2_suggested_fix(kind)
+        case kind
+        when :presenter_column_label, :presenter_field_label_override
+          "Remove `label:` so the underlying field key applies, " \
+            "or extend the runtime to consume a per-presenter column-label key"
+        when :presenter_filter_label
+          "Remove `label:` so the underlying parameter/scope label applies"
+        when :presenter_saved_filter_label
+          "Move literal to a locale file and extend the runtime to consume " \
+            "`lcp_ruby.saved_filters.<...>`"
+        when :presenter_tab_label, :presenter_step_label
+          "Move literal to a locale file and extend the runtime to consume " \
+            "the corresponding tab/step key"
+        when :view_group_view_label
+          "Remove `label:` from the view definition (the underlying " \
+            "presenter's resolved_label applies) or extend the runtime to " \
+            "consume `lcp_ruby.view_groups.<vg>.views.<page>`"
+        when :workflow_state_description
+          "Remove `description:` from the state, or extend the runtime to " \
+            "consume `lcp_ruby.workflows.<wf>.states.<state>.description`"
+        when :type_label, :nested_fields_add_label
+          "Move literal to a locale file and extend runtime to consume the key"
+        else
+          "Move literal to a locale file"
+        end
+      end
+    end
+  end
+end