dialecto-rails 0.1.0

data/lib/dialecto_rails/usages/keys.rb

@@ -0,0 +1,206 @@
+require "prism"
+require_relative "record"
+
+module DialectoRails
+  module Usages
+    # Reads the key argument of a translate call (spec-0023 §6.3): what text it can name, which literals carry
+    # that text, and why it can't be resolved when it can't.
+    #
+    #   :static     one key (`text`), with its literal if the literal can be rewritten
+    #   :set        an exact list of `keys` (a ternary, an `||`, an array, an interpolation over a literal list)
+    #   :pattern    literal parts around unknown ones (`items`), with the head literal
+    #   :unresolved nothing to read (`reason`)
+    #   :param      the key is one of a wrapper's parameters (`index`), only when `params` is given
+    #
+    # `items` hold `{lit:}`, `{wild: true}` and, for a wrapper, `{param: index}`.
+    module Keys
+      Analysis = Struct.new(:kind, :text, :items, :keys, :literals, :reason, :index, keyword_init: true)
+
+      MAX_KEYS = 5_000
+      TRANSPARENT = %i[to_s to_sym to_str].freeze
+
+      module_function
+
+      # `env`: local name → literal values (a block parameter over a literal list). `params`: local name →
+      # positional index, when scouting a wrapper's body.
+      def analyze(node, env: {}, params: nil, role: :key)
+        case node
+        when Prism::StringNode then static_string(node, role)
+        when Prism::SymbolNode then static_symbol(node, role)
+        when Prism::InterpolatedStringNode, Prism::InterpolatedSymbolNode then interpolated(node, env, params, role)
+        when Prism::ParenthesesNode then parenthesized(node, env, params, role)
+        when Prism::ArrayNode then choices(node.elements, env, params, role)
+        when Prism::OrNode then choices([node.left, node.right], env, params, role)
+        when Prism::IfNode then choices(branches(node), env, params, role)
+        when Prism::LocalVariableReadNode
+          if params&.key?(node.name)
+            Analysis.new(kind: :param, index: params[node.name], items: [{param: params[node.name]}])
+          else
+            unresolved(:variable)
+          end
+        when Prism::InstanceVariableReadNode, Prism::ClassVariableReadNode, Prism::GlobalVariableReadNode
+          unresolved(:variable)
+        when Prism::ConstantReadNode, Prism::ConstantPathNode then unresolved(:constant)
+        when Prism::CallNode
+          return unresolved(:variable) if node.variable_call?
+          return concatenated(node, env, params, role) if concatenation?(node)
+
+          transparent?(node) ? analyze(node.receiver, env: env, params: params, role: role) : unresolved(:method_call)
+        else unresolved(:variable)
+        end
+      end
+
+      def unresolved(reason) = Analysis.new(kind: :unresolved, reason: reason, items: [{wild: true}], literals: [])
+
+      def transparent?(node)
+        node.receiver && TRANSPARENT.include?(node.name) && node.arguments.nil? &&
+          (node.receiver.is_a?(Prism::LocalVariableReadNode))
+      end
+
+      # `"users." + role`: a string literal on the left of `+` with one argument. It names the same keys as
+      # `"users.#{role}"`, so it locks the same family. It carries no head literal: the contract's head span
+      # ends where an interpolation begins, so a group rename that reaches this call is refused, not rewritten.
+      def concatenation?(node)
+        node.name == :+ && node.receiver.is_a?(Prism::StringNode) && node.block.nil? &&
+          node.arguments&.arguments&.length == 1
+      end
+
+      def concatenated(node, env, params, role)
+        rest = analyze(node.arguments.arguments.first, env: env, params: params, role: role)
+        tail = rest.kind == :param ? {param: rest.index} : {wild: true}
+        Analysis.new(kind: :pattern, items: [{lit: node.receiver.unescaped}, tail], literals: [],
+          reason: :interpolation)
+      end
+
+      def parenthesized(node, env, params, role)
+        body = node.body
+        statements = body.is_a?(Prism::StatementsNode) ? body.body : []
+        statements.length == 1 ? analyze(statements.first, env: env, params: params, role: role) : unresolved(:variable)
+      end
+
+      def branches(node)
+        out = []
+        out.concat(node.statements&.body.to_a.last(1))
+        tail = node.subsequent
+        case tail
+        when Prism::ElseNode then out.concat(tail.statements&.body.to_a.last(1))
+        when Prism::IfNode then out.concat(branches(tail))
+        end
+        out
+      end
+
+      # `cond ? "a" : "b"`, `"a" || "b"`, `[:a, :b]`: each literal branch is a use.
+      def choices(nodes, env, params, role)
+        analyses = nodes.map { |branch| analyze(branch, env: env, params: params, role: role) }
+        return unresolved(:variable) if analyses.empty? || analyses.any? { |item| item.kind != :static }
+
+        keys = analyses.map(&:text).uniq.sort
+        items = common_items(keys)
+        Analysis.new(kind: :set, keys: keys, items: items, literals: analyses.flat_map(&:literals))
+      end
+
+      # The segments every key shares at the start and at the end; whatever lies between is wild.
+      def common_items(keys)
+        return [{lit: keys.first}] if keys.length == 1
+
+        split = keys.map { |key| key.split(".", -1) }
+        head = split.first.zip(*split.drop(1)).take_while { |segments| segments.uniq.length == 1 }.length
+        tail_limit = split.map(&:length).min - head
+        tail = 0
+        tail += 1 while tail < tail_limit && split.map { |segments| segments[-1 - tail] }.uniq.length == 1
+        items = []
+        items << {lit: split.first.first(head).join(".") + "."} if head.positive?
+        items << {wild: true}
+        items << {lit: "." + split.first.last(tail).join(".")} if tail.positive?
+        items
+      end
+
+      def static_string(node, role)
+        opening = node.opening_loc&.slice
+        text = node.unescaped
+        literal = nil
+        if ['"', "'"].include?(opening) && node.content_loc.slice == text
+          literal = Literal.new(text_start: node.content_loc.start_offset, text_end: node.content_loc.end_offset,
+            delim: opening, role: role, anchor_end: node.location.end_offset)
+        end
+        Analysis.new(kind: :static, text: text, items: [{lit: text}], literals: [literal].compact)
+      end
+
+      def static_symbol(node, role)
+        opening = node.opening_loc&.slice
+        text = node.unescaped
+        literal = nil
+        if [":", ':"', ":'"].include?(opening) && node.value_loc && node.value_loc.slice == text
+          literal = Literal.new(text_start: node.value_loc.start_offset, text_end: node.value_loc.end_offset,
+            delim: opening, role: role, anchor_end: node.location.end_offset)
+        end
+        Analysis.new(kind: :static, text: text, items: [{lit: text}], literals: [literal].compact)
+      end
+
+      def interpolated(node, env, params, role)
+        parts = node.parts
+        if node.opening_loc.nil? && parts.all?(Prism::StringNode)
+          return unresolved(:concatenated_literal)
+        end
+
+        items = []
+        values = []
+        parts.each do |part|
+          case part
+          when Prism::StringNode
+            items << {lit: part.unescaped}
+            values << [part.unescaped]
+          when Prism::EmbeddedStatementsNode
+            resolved = embedded(part, env, params)
+            if resolved.is_a?(Array)
+              items << {wild: true}
+              values << resolved
+            elsif resolved.is_a?(Integer)
+              items << {param: resolved}
+              values << nil
+            else
+              items << {wild: true}
+              values << nil
+            end
+          else
+            items << {wild: true}
+            values << nil
+          end
+        end
+
+        literal = head_literal(node, role)
+        if values.none?(&:nil?)
+          keys = values.inject([""]) { |acc, options| acc.product(options).map(&:join) }.uniq.sort
+          if keys.length <= MAX_KEYS
+            return Analysis.new(kind: :set, keys: keys, items: items, literals: [literal].compact, reason: :interpolation)
+          end
+        end
+        Analysis.new(kind: :pattern, items: items, literals: [literal].compact, reason: :interpolation)
+      end
+
+      # An embedded `#{...}`: the literal values a loop variable stands for (Array), a wrapper parameter's
+      # index (Integer), or nil.
+      def embedded(part, env, params)
+        statements = part.statements&.body
+        return nil unless statements&.length == 1
+
+        node = statements.first
+        node = node.receiver if node.is_a?(Prism::CallNode) && transparent?(node)
+        return nil unless node.is_a?(Prism::LocalVariableReadNode)
+        return env[node.name] if env.key?(node.name)
+
+        params&.fetch(node.name, nil)
+      end
+
+      def head_literal(node, role)
+        first = node.parts.first
+        opening = node.opening_loc&.slice
+        return nil unless first.is_a?(Prism::StringNode) && [%("), ':"'].include?(opening)
+        return nil unless first.location.slice == first.unescaped
+
+        Literal.new(text_start: first.location.start_offset, text_end: first.location.end_offset,
+          delim: opening, role: role, head: true, anchor_end: node.location.end_offset)
+      end
+    end
+  end
+end

data/lib/dialecto_rails/usages/known_wrappers.rb

@@ -0,0 +1,31 @@
+module DialectoRails
+  module Usages
+    # Translate wrappers that come from a gem (an app that depends on spree never has `Spree.t`'s definition in its
+    # tree), switched on by the gems in `Gemfile.lock` (spec-0023 §6.3). A project adds its own with the `wrappers`
+    # setting; a declared wrapper takes the key as its first argument and puts `scope` in front of it.
+    module KnownWrappers
+      SPREE = [{call: "Spree.t", scope: "spree"}, {call: "Spree.translate", scope: "spree"}].freeze
+
+      BY_GEM = {
+        "spree_core" => SPREE,
+        "solidus_core" => SPREE
+      }.freeze
+
+      # The declared entries as the scan uses them (`receiver:`, `name:`, `scope:`), from the project's `wrappers`
+      # setting and the table for the locked gems. An entry that isn't `Const.method` is dropped.
+      def self.declared(configured, gem_names)
+        entries = Array(configured) + gem_names.flat_map { |name| BY_GEM.fetch(name, []) }
+        entries.filter_map { |entry| parse(entry) }.uniq
+      end
+
+      def self.parse(entry)
+        entry = entry.to_h.transform_keys(&:to_sym)
+        match = entry[:call].to_s.strip.match(/\A(?:::)?((?:[A-Z]\w*::)*[A-Z]\w*)\.([a-z_]\w*[?!]?)\z/)
+        return nil unless match
+
+        scope = Array(entry[:scope]).map(&:to_s).reject(&:empty?).join(".")
+        {receiver: match[1], name: match[2], scope: scope.empty? ? nil : scope}
+      end
+    end
+  end
+end

data/lib/dialecto_rails/usages/lazy_scope.rb

@@ -0,0 +1,52 @@
+module DialectoRails
+  module Usages
+    # Where a lazy key (`t(".title")`) is read from decides what it means (spec-0023 §6.4): Rails resolves it
+    # from the rendering view, or from a controller's or mailer's action, so the scan derives that context
+    # from the file and the class around the call.
+    module LazyScope
+      VIEW_ROOT = %r{(?:\A|/)app/views/(.+)\z}
+      ACTIONS = %w[index show new create edit update destroy].freeze
+
+      module_function
+
+      # `{base:, from:}` for a file under `app/views/`, or nil. `users/_row.html.erb` is `users.row`, a partial.
+      def view(path)
+        relative = path[VIEW_ROOT, 1]
+        return nil unless relative
+
+        *directories, file = relative.split("/")
+        name = file.split(".").first.to_s
+        partial = name.start_with?("_")
+        name = name.delete_prefix("_")
+        {base: (directories + [name]).join(".").delete_prefix("."), from: partial ? "partial" : "view"}
+      end
+
+      # :controller, :mailer or nil, from a class's own name and its superclass's.
+      def kind(class_name, superclass_name)
+        names = [class_name, superclass_name].compact
+        return :controller if names.any? { |name| name.end_with?("Controller") }
+        return :mailer if names.any? { |name| name.end_with?("Mailer") }
+
+        nil
+      end
+
+      # `Admin::UsersController` → `admin.users`; `UserMailer` → `user_mailer`.
+      def path(constant_path, kind)
+        segments = constant_path.split("::").map { |segment| underscore(segment) }
+        segments[-1] = segments[-1].delete_suffix("_controller") if kind == :controller
+        segments.join(".")
+      end
+
+      def underscore(name)
+        name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+
+      def action?(kind, method_name, visibility)
+        return false unless method_name
+        return ACTIONS.include?(method_name) if kind == :controller
+
+        kind == :mailer && visibility == :public
+      end
+    end
+  end
+end

data/lib/dialecto_rails/usages/parse_check.rb

@@ -0,0 +1,75 @@
+require "prism"
+require_relative "scanner"
+require_relative "templates"
+
+module DialectoRails
+  module Usages
+    # `dialecto-rails parse-check`: do these files still parse with the gem's own readers? Ruby goes through Prism;
+    # ERB and HAML through the same extractors the usage scan uses, and the Ruby they yield through Prism, with the
+    # constructs a template may hold outside a method tolerated as the scan tolerates them. A rewritten call site
+    # must keep every file readable, so the rename check runs this over the bytes it would commit.
+    class ParseCheck
+      Failure = Struct.new(:path, :line, :message, keyword_init: true)
+
+      RUBY_NAMES = %w[Rakefile Gemfile].freeze
+
+      # `{checked: n, skipped: n, failures: [Failure]}`; a file of a kind the scan doesn't read is skipped.
+      def self.call(files) = new(files).call
+
+      def initialize(files)
+        @files = files
+      end
+
+      def call
+        result = {checked: 0, skipped: 0, failures: []}
+        @files.each do |path, bytes|
+          failure = check(path, bytes.dup.force_encoding(Encoding::UTF_8), result)
+          result[:failures] << failure if failure
+        end
+        result
+      end
+
+      private
+
+      def check(path, bytes, result)
+        lang = language(path)
+        return skip(result) unless lang
+
+        ruby = reduce(lang, bytes)
+        return skip(result) if ruby.nil?
+
+        result[:checked] += 1
+        errors = Prism.parse(ruby, version: "latest").errors
+        errors = errors.reject { |error| Scanner::TEMPLATE_TOLERATED.include?(error.message) } unless lang == :ruby
+        return if errors.empty?
+
+        Failure.new(path: path, line: errors.first.location.start_line, message: errors.first.message)
+      rescue => e
+        # A parser's message may quote the source; only the class and our own line-number messages are kept.
+        message = e.is_a?(Templates::Unreadable) ? e.message : "#{e.class.name} while reading the file"
+        Failure.new(path: path, line: nil, message: message)
+      end
+
+      def skip(result)
+        result[:skipped] += 1
+        nil
+      end
+
+      def reduce(lang, bytes)
+        case lang
+        when :ruby then bytes
+        when :erb then Templates.erb(bytes)
+        when :haml then Templates.haml(bytes)
+        end
+      end
+
+      def language(path)
+        extension = File.extname(path).downcase
+        return :ruby if Scanner::RUBY_EXTENSIONS.include?(extension) || RUBY_NAMES.include?(File.basename(path))
+        return :erb if extension == ".erb"
+
+        :haml if extension == ".haml"
+      end
+    end
+  end
+end

data/lib/dialecto_rails/usages/read_by_name.json

@@ -0,0 +1,28 @@
+{
+  "namespaces": [
+    { "prefix": "activerecord.", "reader": "Rails reads this key by its name, for model names, attributes and errors" },
+    { "prefix": "activemodel.", "reader": "Rails reads this key by its name, for model names, attributes and errors" },
+    { "prefix": "attributes.", "reader": "Rails reads this key by its name, for attribute names" },
+    { "prefix": "errors.", "reader": "Rails reads this key by its name, for validation messages" },
+    { "prefix": "helpers.", "reader": "Rails reads this key by its name, for form helpers" },
+    { "prefix": "date.", "reader": "Rails reads this key by its name, for dates" },
+    { "prefix": "time.", "reader": "Rails reads this key by its name, for times" },
+    { "prefix": "datetime.", "reader": "Rails reads this key by its name, for dates and times" },
+    { "prefix": "number.", "reader": "Rails reads this key by its name, for numbers" },
+    { "prefix": "support.", "reader": "Rails reads this key by its name, for lists and array formatting" },
+    { "prefix": "i18n.", "reader": "Rails reads this key by its name, for the i18n library" }
+  ],
+  "gems": {
+    "activeadmin": ["active_admin."],
+    "administrate": ["administrate."],
+    "devise": ["devise."],
+    "devise-i18n": ["devise."],
+    "doorkeeper": ["doorkeeper."],
+    "kaminari": ["views.", "helpers.page_entries_info."],
+    "pundit": ["pundit."],
+    "rails_admin": ["admin."],
+    "responders": ["flash."],
+    "simple_form": ["simple_form."],
+    "will_paginate": ["will_paginate."]
+  }
+}

data/lib/dialecto_rails/usages/record.rb

@@ -0,0 +1,91 @@
+module DialectoRails
+  module Usages
+    # A literal in the source that carries part of a key: where its text sits (absolute UTF-8 byte
+    # offsets), what delimits it, and where an anchor that contains it must reach (`anchor_end`).
+    Literal = Struct.new(:text_start, :text_end, :delim, :role, :head, :anchor_end, keyword_init: true) do
+      def head? = head == true
+    end
+
+    # Pattern parts (spec-0018 §3): `{lit: String}` and `{wild: true}`, adjacent ones merged.
+    module Parts
+      module_function
+
+      def build(items)
+        merged = []
+        items.each do |item|
+          if item[:wild]
+            merged << {wild: true} unless merged.last&.key?(:wild)
+          elsif !item[:lit].to_s.empty?
+            if merged.last&.key?(:lit)
+              merged[-1] = {lit: merged.last[:lit] + item[:lit]}
+            else
+              merged << {lit: item[:lit]}
+            end
+          end
+        end
+        collapse(merged)
+      end
+
+      # `*` `.` `*` can only read what `*` reads: an unknown scope in front of an unknown key.
+      def collapse(parts)
+        index = 0
+        while index <= parts.length - 3
+          if parts[index][:wild] && parts[index + 1] == {lit: "."} && parts[index + 2][:wild]
+            parts.slice!(index + 1, 2)
+          else
+            index += 1
+          end
+        end
+        parts
+      end
+
+      def pattern(parts) = parts.map { |part| part[:lit] || "*" }.join
+
+      def json(parts) = parts.map { |part| part[:wild] ? {"wild" => true} : {"lit" => part[:lit]} }
+    end
+
+    # Byte offset → 1-based line, for one file.
+    class LineIndex
+      def initialize(bytes)
+        @newlines = []
+        offset = -1
+        @newlines << offset while (offset = bytes.byteindex("\n", offset + 1))
+      end
+
+      def line(offset) = @newlines.bsearch_index { |position| position >= offset } || @newlines.length
+
+      def line_of(offset) = line(offset) + 1
+    end
+
+    # The key-bearing literals of one record, turned into the contract's `spans` and the anchor around them.
+    class Anchor
+      MAX_BYTES = 2_000
+
+      attr_reader :start, :finish, :literals
+
+      def initialize(start:, call_end:, literals:, extra_end: nil)
+        @start = start
+        @literals = literals.sort_by(&:text_start)
+        ends = @literals.map(&:anchor_end)
+        ends << extra_end if extra_end
+        @finish = ends.empty? ? call_end : ends.max
+      end
+
+      def too_long? = finish - start > MAX_BYTES
+
+      def index_of(literal) = literals.index { |candidate| candidate.equal?(literal) }
+
+      def spans
+        literals.map do |literal|
+          span = {"start" => literal.text_start - start, "end" => literal.text_end - start, "delim" => literal.delim,
+                  "role" => literal.role.to_s, "lang" => "ruby"}
+          if literal.head?
+            span["head"] = true
+            span["closed"] = false
+          end
+          span
+        end
+      end
+    end
+  end
+end