lcp 0.1.0

data/lib/lcp_ruby/i18n_check/reporter.rb

@@ -0,0 +1,96 @@
+require "json"
+
+module LcpRuby
+  module I18nCheck
+    # Renders a list of `Offense` records to one of three formats and returns
+    # a process exit code (0 unless any :error-severity offense is present).
+    #
+    # The JSON output is a versioned, stable contract:
+    #   { "version": 1, "offenses": [...], "summary": {...} }
+    # IDE / CI clients should gate on `version` before consuming `offenses`.
+    class Reporter
+      FORMATS = %i[text github json].freeze
+      JSON_SCHEMA_VERSION = 1
+
+      class UnknownFormatError < ArgumentError; end
+
+      def report(offenses, format: :text, io: $stdout)
+        format = format.to_sym
+        unless FORMATS.include?(format)
+          raise UnknownFormatError, "unknown format #{format.inspect}; expected one of #{FORMATS.inspect}"
+        end
+        send("format_#{format}", offenses, io)
+        summary_exit_code(offenses)
+      end
+
+      private
+
+      def format_text(offenses, io)
+        if offenses.empty?
+          io.puts "lcp_ruby:i18n_check — 0 offense(s)"
+          return
+        end
+
+        offenses.group_by(&:file).sort_by { |file, _| file.to_s }.each do |file, group|
+          io.puts(file || "(unknown source)")
+          group.sort_by { |o| [ o.line.to_i, o.kind.to_s ] }.each do |o|
+            line_prefix = o.line ? "  #{o.line}: " : "  "
+            io.puts "#{line_prefix}[#{o.kind}/#{o.severity}] #{format_text_line(o)}"
+          end
+        end
+        io.puts "—"
+        io.puts "Total: #{offenses.size} offense(s) " \
+                "(#{offenses.count(&:error?)} err, " \
+                "#{offenses.count(&:warning?)} warn, " \
+                "#{offenses.count(&:info?)} info)"
+      end
+
+      def format_text_line(offense)
+        line = offense.content.to_s.strip
+        line << " — #{offense.suggested_fix}" if offense.suggested_fix
+        line
+      end
+
+      def format_github(offenses, io)
+        offenses.each do |o|
+          level = o.error? ? "error" : "warning" # GitHub annotations: error/warning/notice
+          io.puts "::#{level} file=#{escape_gha_property(o.file)},line=#{o.line}::" \
+                  "#{escape_gha_data("[#{o.kind}] #{o.suggested_fix || o.content}")}"
+        end
+      end
+
+      # GitHub Actions workflow-command escaping. Property values (the
+      # `file=...,line=...` segment) treat `,` and `:` as delimiters, so
+      # we must percent-encode them in addition to newlines. The message
+      # body (after `::`) only needs newline escaping. Reference:
+      # https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions
+      def escape_gha_property(value)
+        value.to_s
+             .gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+             .gsub(":", "%3A").gsub(",", "%2C")
+      end
+
+      def escape_gha_data(value)
+        value.to_s.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+      end
+
+      def format_json(offenses, io)
+        payload = {
+          version: JSON_SCHEMA_VERSION,
+          offenses: offenses.map(&:to_h_v1),
+          summary: {
+            error: offenses.count(&:error?),
+            warning: offenses.count(&:warning?),
+            info: offenses.count(&:info?),
+            total: offenses.size
+          }
+        }
+        io.puts JSON.pretty_generate(payload)
+      end
+
+      def summary_exit_code(offenses)
+        offenses.any?(&:error?) ? 1 : 0
+      end
+    end
+  end
+end

data/lib/lcp_ruby/i18n_check/runner.rb

@@ -0,0 +1,46 @@
+require_relative "configuration"
+require_relative "key_deriver"
+require_relative "registry_walker"
+require_relative "reporter"
+
+module LcpRuby
+  module I18nCheck
+    # Glues `RegistryWalker` and `Reporter` together for the rake task.
+    #
+    # The lint is a single boot-time pass: walk the loaded metadata
+    # registry and check that every labeled element resolves in every
+    # configured locale via `I18n.exists?`. No AST scan, no separate
+    # YAML walker — see Phase 9 in `docs/design/i18n_consistency_check.md`
+    # for the simplification rationale.
+    #
+    # Resolves the output format with precedence:
+    #   explicit `format:` arg → ENV["LCP_I18N_FORMAT"] → config default.
+    #
+    # `run` returns a process exit code (0 = clean / only warnings,
+    # 1 = at least one error-severity offense). The rake task forwards it
+    # to `exit`.
+    class Runner
+      def initialize(config: Configuration.new, root: Dir.pwd, loader: nil)
+        @config = config
+        @root   = root
+        @loader = loader
+      end
+
+      def run(format: nil, io: $stdout)
+        resolved_format = (format || ENV["LCP_I18N_FORMAT"] || @config.format).to_sym
+        offenses = registry_walker.run
+        Reporter.new.report(offenses, format: resolved_format, io: io)
+      end
+
+      private
+
+      def registry_walker
+        @registry_walker ||= RegistryWalker.new(
+          config: @config,
+          key_deriver: KeyDeriver.new,
+          loader: @loader
+        )
+      end
+    end
+  end
+end

data/lib/lcp_ruby/i18n_check.rb

@@ -0,0 +1,15 @@
+module LcpRuby
+  # Boot-time empirical i18n lint for host-app metadata. Walks
+  # `LcpRuby.loader.*_definitions` and asserts that every labeled
+  # element resolves in every configured locale via `I18n.exists?`.
+  # See `docs/reference/i18n_check.md` for usage.
+  module I18nCheck
+    autoload :Configuration,  "lcp_ruby/i18n_check/configuration"
+    autoload :Heuristics,     "lcp_ruby/i18n_check/heuristics"
+    autoload :Offense,        "lcp_ruby/i18n_check/offense"
+    autoload :Reporter,       "lcp_ruby/i18n_check/reporter"
+    autoload :KeyDeriver,     "lcp_ruby/i18n_check/key_deriver"
+    autoload :RegistryWalker, "lcp_ruby/i18n_check/registry_walker"
+    autoload :Runner,         "lcp_ruby/i18n_check/runner"
+  end
+end

data/lib/lcp_ruby/i18n_lint.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module LcpRuby
+  # Walks ERB templates and Stimulus JavaScript controllers for hardcoded
+  # user-visible strings. Complements the RuboCop cop for Ruby
+  # (LcpRuby/NoHardcodedI18nString) which handles .rb files via AST.
+  #
+  # Pure file walk — no Rails environment boot. Invoked by the
+  # `lcp_ruby:i18n_lint` rake task and exercised directly by specs.
+  #
+  # Allow-list: append `<%# i18n-exempt: <reason> %>` or `// i18n-exempt: <reason>`
+  # on the same line as a flagged pattern to suppress that occurrence.
+  class I18nLint
+    ROOT = File.expand_path("../..", __dir__)
+
+    INCLUDE_GLOBS = [
+      "app/views/**/*.erb",
+      "app/assets/javascripts/**/*.js"
+    ].freeze
+
+    EXCLUDE_FRAGMENTS = [
+      "spec/dummy/",
+      "spec/fixtures/",
+      "examples/",
+      "lib/generators/lcp_ruby/templates/"
+    ].freeze
+
+    ERB_RULES = {
+      hardcoded_title: /<title>[^<][^<]*<\/title>/,
+      pluralize_literal_noun: /pluralize\(\s*[^,)]+,\s*["'][A-Za-z]/,
+      hardcoded_placeholder_attr: /\bplaceholder=["'][A-Z]/,
+      hardcoded_title_attr: /\btitle=["'][A-Z]/,
+      hardcoded_data_confirm: /\bdata-confirm=["'][A-Z]/
+    }.freeze
+
+    JS_RULES = {
+      alert_literal: /\balert\(\s*["'][A-Z]/,
+      confirm_literal: /\bconfirm\(\s*["'][A-Z]/,
+      prompt_literal: /\bprompt\(\s*["'][A-Z]/,
+      text_content_literal: /\.textContent\s*=\s*["'][A-Z]/,
+      title_literal: /\.title\s*=\s*["'][A-Z]/,
+      placeholder_literal: /\.placeholder\s*=\s*["'][A-Z]/,
+      set_attribute_literal: /setAttribute\(\s*['"](?:title|aria-label|placeholder)['"]\s*,\s*["'][A-Z]/,
+      new_error_literal: /\bnew\s+Error\(\s*["'][A-Z]/,
+      throw_error_literal: /\bthrow\s+new\s+Error\(\s*["'][A-Z]/
+    }.freeze
+
+    # ERB exemption marker: `<%# i18n-exempt: ... %>`
+    ERB_EXEMPT_RE = /<%#\s*i18n-exempt:/.freeze
+
+    # JS exemption marker: `// i18n-exempt: ...`
+    JS_EXEMPT_RE = %r{//\s*i18n-exempt:}.freeze
+
+    def run
+      offenses = []
+      files.each do |path|
+        next if excluded?(path)
+        next if path.end_with?(".js.erb") # compile-time template is exempt by design
+        rules = path.end_with?(".erb") ? ERB_RULES : JS_RULES
+        exempt_re = path.end_with?(".erb") ? ERB_EXEMPT_RE : JS_EXEMPT_RE
+        offenses.concat(scan_file(path, rules, exempt_re))
+      end
+      offenses
+    end
+
+    # Per-rule post-filters to reduce false positives (spec §"Per-pattern
+    # classifier refinements"). Public so specs can exercise the individual
+    # classifiers without spinning up a full rake invocation.
+    def skip_false_positive?(rule_name, line)
+      case rule_name
+      when :pluralize_literal_noun
+        pluralize_second_arg_is_translation?(line)
+      when :title_literal
+        # Skip assignments like `x.title = data.title` / `el.title = record.title`
+        line.match?(/\.title\s*=\s*[A-Za-z_][A-Za-z0-9_.]*(\[|\s*;|\s*$)/)
+      when :new_error_literal, :throw_error_literal
+        # Skip re-throws `new Error(err.message)` / `new Error(e)`
+        line.match?(/new\s+Error\(\s*[a-z_][A-Za-z0-9_]*(?:\.\w+)?\s*\)/)
+      else
+        false
+      end
+    end
+
+    # Returns true when the second argument of `pluralize(...)` on this line
+    # starts with a `t(` or `I18n.t(` call (i.e. the noun is already a
+    # translation, not a hardcoded literal).
+    #
+    # Uses a depth-counting scan so commas inside nested parens in the first
+    # argument (e.g. `pluralize(a > 1 ? 2 : 1, t("..."))`) are handled
+    # correctly — a plain regex breaks on that shape.
+    def pluralize_second_arg_is_translation?(line)
+      idx = line.index("pluralize(")
+      return false unless idx
+
+      depth = 0
+      i = idx + "pluralize(".length
+      while i < line.length
+        c = line[i]
+        case c
+        when "(" then depth += 1
+        when ")"
+          return false if depth.zero? # closed before we found a comma
+          depth -= 1
+        when ","
+          if depth.zero?
+            rest = line[(i + 1)..].lstrip
+            return rest.start_with?("t(", "I18n.t(")
+          end
+        end
+        i += 1
+      end
+      false
+    end
+
+    private
+
+    def files
+      INCLUDE_GLOBS.flat_map { |glob| Dir.glob(File.join(ROOT, glob)) }
+    end
+
+    def excluded?(path)
+      EXCLUDE_FRAGMENTS.any? { |frag| path.include?(frag) }
+    end
+
+    def scan_file(path, rules, exempt_re)
+      offenses = []
+      File.readlines(path).each_with_index do |line, idx|
+        next if line.match?(exempt_re)
+
+        rules.each do |rule_name, re|
+          next unless line.match?(re)
+          next if skip_false_positive?(rule_name, line)
+
+          offenses << {
+            file: path.sub(ROOT + "/", ""),
+            line: idx + 1,
+            rule: rule_name,
+            content: line.strip
+          }
+        end
+      end
+      offenses
+    end
+  end
+end

data/lib/lcp_ruby/import/auto_mapper.rb

@@ -0,0 +1,98 @@
+module LcpRuby
+  module Import
+    # Automatically maps source CSV/XLSX column headers to target model field names.
+    class AutoMapper
+      # @param source_headers [Array<String>] column headers from the source file
+      # @param target_fields [Array<Hash>] field entries from FieldTreeBuilder (name, label, type)
+      # @return [Hash] { "Source Column" => "field_name", ... } for matched columns
+      def self.auto_map(source_headers, target_fields)
+        new(source_headers, target_fields).map
+      end
+
+      def initialize(source_headers, target_fields)
+        @source_headers = source_headers
+        @target_fields = target_fields
+        @used_fields = Set.new
+      end
+
+      def map
+        result = {}
+
+        # Build reverse lookup indexes
+        by_name = {}
+        by_label = {}
+
+        # Sentinel value to mark suffix collisions between nested fields.
+        nested_collision = Object.new
+
+        @target_fields.each do |field|
+          name = field["name"].to_s
+          label = field["label"].to_s
+          by_name[name.downcase] = name
+          by_label[label.downcase] = name unless label.empty?
+
+          # Nested fields: also index by suffix so "Starting Salary" can match
+          # "hire_detail.starting_salary". Direct fields take priority.
+          next unless name.include?(".")
+
+          suffix_key = name.split(".", 2).last.downcase
+          if by_name.key?(suffix_key)
+            existing = by_name[suffix_key]
+            # Another nested field owns it → collision, remove both.
+            # Direct field or collision sentinel → leave as is (direct always wins).
+            if existing.is_a?(String) && existing.include?(".")
+              by_name[suffix_key] = nested_collision
+            end
+          else
+            by_name[suffix_key] = name
+          end
+
+          short_label = label.sub(/^.+→\s*/i, "").strip.downcase
+          unless short_label.empty?
+            if by_label.key?(short_label)
+              existing = by_label[short_label]
+              if existing.is_a?(String) && existing.include?(".")
+                by_label[short_label] = nested_collision
+              end
+            else
+              by_label[short_label] = name
+            end
+          end
+        end
+
+        # Clean up collision sentinels
+        by_name.reject! { |_k, v| v.equal?(nested_collision) }
+        by_label.reject! { |_k, v| v.equal?(nested_collision) }
+
+        @source_headers.each do |header|
+          next if header.nil? || header.strip.empty?
+          normalized = header.strip.downcase
+
+          # Strategy 1: exact field name match (case-insensitive)
+          if by_name[normalized] && !@used_fields.include?(by_name[normalized])
+            result[header] = by_name[normalized]
+            @used_fields.add(by_name[normalized])
+            next
+          end
+
+          # Strategy 2: humanized label match
+          if by_label[normalized] && !@used_fields.include?(by_label[normalized])
+            result[header] = by_label[normalized]
+            @used_fields.add(by_label[normalized])
+            next
+          end
+
+          # Strategy 3: underscore/humanize normalization
+          underscored = normalized.gsub(/\s+/, "_").gsub(/[^a-z0-9_]/, "")
+          if by_name[underscored] && !@used_fields.include?(by_name[underscored])
+            result[header] = by_name[underscored]
+            @used_fields.add(by_name[underscored])
+            next
+          end
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/lcp_ruby/import/field_tree_builder.rb

@@ -0,0 +1,178 @@
+module LcpRuby
+  module Import
+    # Builds the field metadata tree for import target fields.
+    # Returns writable fields (unlike Export::FieldTreeBuilder which returns readable fields).
+    class FieldTreeBuilder
+      def self.build(model_definition:, evaluator:, presenter:, current_user:)
+        new(model_definition:, evaluator:, presenter:, current_user:).build
+      end
+
+      def initialize(model_definition:, evaluator:, presenter:, current_user:)
+        @model_definition = model_definition
+        @evaluator = evaluator
+        @presenter = presenter
+        @current_user = current_user
+      end
+
+      def build
+        writable = @evaluator.writable_fields
+        fields = []
+        custom_fields = []
+
+        @model_definition.fields.each do |field_def|
+          next unless writable.include?(field_def.name)
+          next if skip_field?(field_def)
+
+          entry = build_field_entry(field_def)
+
+          if field_def.name.start_with?("cf_")
+            custom_fields << entry
+          else
+            fields << entry
+          end
+        end
+
+        # Add FK fields for writable belongs_to associations
+        @model_definition.associations.each do |assoc|
+          next unless assoc.type == "belongs_to" && assoc.foreign_key
+          next unless writable.include?(assoc.foreign_key) || @evaluator.field_writable?(assoc.foreign_key)
+
+          fields << build_association_entry(assoc)
+        end
+
+        # Add fields from has_one associations with nested_attributes
+        nested_whitelist = @presenter&.import_nested_associations
+
+        @model_definition.associations.each do |assoc|
+          next unless assoc.type == "has_one" && assoc.nested_attributes && !assoc.through?
+          next if nested_whitelist && !nested_whitelist.include?(assoc.name)
+
+          target_model_def = begin
+            LcpRuby.loader.model_definition(assoc.target_model)
+          rescue LcpRuby::MetadataError
+            next
+          end
+
+          target_perm = LcpRuby.loader.permission_definition(assoc.target_model)
+          target_evaluator = Authorization::PermissionEvaluator.new(
+            target_perm, @current_user, assoc.target_model
+          )
+
+          nested_fields = target_model_def.fields
+            .reject { |f| skip_field?(f) }
+            .select { |f| target_evaluator.field_writable?(f.name) }
+            .reject { |f| assoc.foreign_key && f.name == assoc.foreign_key }
+            .reject { |f| assoc.as && f.name == "#{assoc.as}_type" }
+            .map do |f|
+              entry = build_field_entry(f)
+              entry["name"] = "#{assoc.name}.#{f.name}"
+              assoc_label = I18n.t("lcp_ruby.models.#{assoc.target_model}.one", default: assoc.name.humanize)
+              nested_label = f.resolved_label(model_name: assoc.target_model).presence || f.name.humanize
+              entry["label"] = "#{assoc_label} → #{nested_label}"
+              entry["nested_association"] = assoc.name
+              entry
+            end
+
+          fields.concat(nested_fields) if nested_fields.any?
+        end
+
+        # Add dynamic custom fields from registry
+        if @model_definition.custom_fields_enabled? && CustomFields::Registry.available?
+          cf_writable = writable.include?("custom_data") || writable == "all"
+          CustomFields::Registry.for_model(@model_definition.name).each do |cf_def|
+            next unless cf_writable || writable.include?(cf_def.field_name)
+
+            custom_fields << {
+              "name" => cf_def.field_name,
+              "type" => cf_def.custom_type,
+              "label" => synthetic_label(cf_def.field_name) ||
+                         cf_def.label.presence ||
+                         cf_def.field_name.humanize
+            }
+          end
+        end
+
+        result = { "fields" => fields }
+        result["custom_fields"] = custom_fields if custom_fields.any?
+        result
+      end
+
+      private
+
+      def skip_field?(field_def)
+        return true if field_def.computed?
+        return true if field_def.respond_to?(:virtual?) && field_def.virtual?
+        return true if field_def.respond_to?(:external?) && field_def.external?
+        return true if field_def.type == "attachment" # attachments not importable via CSV
+        return true if %w[created_at updated_at created_by_id updated_by_id].include?(field_def.name)
+        false
+      end
+
+      def build_field_entry(field_def)
+        entry = {
+          "name" => field_def.name,
+          "type" => field_def.type,
+          "label" => field_label(field_def)
+        }
+        entry["required"] = true if field_def.validations.any? { |v| v.type == "presence" }
+        entry["enum_values"] = field_def.enum_value_names if field_def.enum?
+        entry
+      end
+
+      def build_association_entry(assoc)
+        entry = {
+          "name" => assoc.foreign_key,
+          "type" => LcpRuby::AssociationFkType.field_type(assoc),
+          "label" => association_label(assoc)
+        }
+
+        # Provide lookup fields for the target model
+        target_model_def = LcpRuby.loader.model_definition(assoc.target_model)
+        if target_model_def
+          lookup_fields = target_model_def.fields
+            .reject { |f| f.computed? || f.type == "attachment" || f.type == "json" }
+            .select { |f| %w[string integer email].include?(f.resolved_base_type) }
+            .map { |f| { "name" => f.name, "label" => field_label(f) } }
+
+          # Always include id as first option — the importer's
+          # row_processor resolves to the join column on write-back, so
+          # id-based lookup works even for primary_key: associations.
+          lookup_fields.unshift({ "name" => "id", "label" => "ID" }) unless lookup_fields.any? { |f| f["name"] == "id" }
+
+          entry["association"] = {
+            "model" => assoc.target_model,
+            "lookup_fields" => lookup_fields
+          }
+
+          # For primary_key: associations, surface the join column so
+          # the import UI can annotate "stored as: <vema_code>".
+          entry["association"]["join_column"] = assoc.primary_key if assoc.primary_key.present?
+        end
+
+        entry
+      rescue LcpRuby::MetadataError
+        entry
+      end
+
+      def field_label(field_def)
+        field_def.resolved_label(model_name: @model_definition.name).presence || field_def.name.humanize
+      end
+
+      def association_label(assoc)
+        synthetic_label(assoc.foreign_key) ||
+          I18n.t("lcp_ruby.models.#{assoc.target_model}.one", default: assoc.name.humanize)
+      end
+
+      # Resolves model-scoped → global i18n for fields without a
+      # FieldDefinition (custom fields, association FK columns). Returns
+      # nil when no translation is registered, so callers can chain their
+      # own domain-specific fallbacks (YAML label, humanize, model name).
+      def synthetic_label(field_name)
+        I18n.t(
+          "lcp_ruby.models.#{@model_definition.name}.fields.#{field_name}",
+          default: I18n.t("lcp_ruby.fields.#{field_name}", default: nil)
+        ).presence
+      end
+    end
+  end
+end