trmnl_preview 0.7.2 → 0.8.0

data/lib/trmnlp/framework_version.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module TRMNLP
+  # Represents a TRMNL design-system framework version, so plugins can
+  # pin (or float to "latest") the CSS/JS bundle they render against,
+  # both in production and locally.
+  class FrameworkVersion
+    include Comparable
+
+    DEFAULT_ASSET_HOST = 'https://trmnl.com'
+    DATA_PATH = File.expand_path('../../db/data/framework_versions.yml', __dir__)
+
+    attr_reader :number
+
+    def self.config = @config ||= YAML.load_file(DATA_PATH).freeze
+
+    def self.version_numbers = config.fetch('versions').map { |v| v['number'] }.freeze
+
+    def self.latest = new(config.fetch('latest'))
+
+    # Suitable for showing in a `select` form field. Pinnable versions are
+    # ordered newest-first by semantic version — never by manifest order.
+    def self.options
+      newest_first = version_numbers.sort_by { |number| Gem::Version.new(number) }.reverse
+      [{ "Always track latest (currently v#{latest.number})" => 'latest' }] +
+        newest_first.map { |number| { "v#{number}" => number } }
+    end
+
+    def initialize(number, asset_host: DEFAULT_ASSET_HOST)
+      @asset_host = asset_host
+
+      if number.nil? || number == 'latest'
+        @number = self.class.config.fetch('latest')
+        @pinned = false
+      elsif self.class.version_numbers.include?(number)
+        @number = number
+        @pinned = true
+      else
+        raise ArgumentError, "unknown framework version: #{number}"
+      end
+    end
+
+    def pinned? = @pinned
+
+    def css_url = "#{@asset_host}/css/#{path_segment}/plugins.css"
+
+    def js_url = "#{@asset_host}/js/#{path_segment}/plugins.js"
+
+    def ==(other) = other.is_a?(self.class) && number == other.number
+
+    def <=>(other)
+      return nil unless other.is_a?(self.class)
+
+      Gem::Version.new(number) <=> Gem::Version.new(other.number)
+    end
+
+    def as_json(*) = number
+
+    def to_s = number
+
+    private
+
+    # When pinned, requests assets at /css/<version>/plugins.css to lock
+    # behavior; otherwise hit /css/latest/ for live updates.
+    def path_segment = pinned? ? @number : 'latest'
+  end
+end

data/lib/trmnlp/image_quantizer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'mini_magick'
+require 'tempfile'
+require 'fileutils'
+
+module TRMNLP
+  class ImageQuantizer
+    MIN_DEPTH = 1
+    MAX_DEPTH = 8
+
+    def initialize(depth:)
+      @depth = clamp(depth)
+    end
+
+    def call(path)
+      tmp = Tempfile.new(['mono', '.png'])
+      tmp.close
+      quantize(path, tmp.path)
+      FileUtils.mv(tmp.path, path, force: true)
+    end
+
+    private
+
+    def quantize(src, dst)
+      MiniMagick.convert do |m|
+        m << src
+        m.colorspace 'Gray'
+        m.dither 'FloydSteinberg'
+        apply_depth(m)
+        m.depth @depth
+        m.define "png:bit-depth=#{@depth}"
+        m.strip
+        m << dst
+      end
+    end
+
+    def apply_depth(m)
+      if @depth == 1
+        # NOTE: 1-bit only has black/white, so a halftone remap simulates gray
+        # via dithering patterns. Skipping this collapses photos to pure
+        # silhouettes.
+        m.remap 'pattern:gray50'
+        m.posterize 2
+        m.colors 2
+        m.type 'Bilevel'
+      else
+        levels = 2**@depth
+        m.posterize levels
+        m.colors levels
+      end
+    end
+
+    def clamp(depth)
+      [[depth.to_i, MIN_DEPTH].max, MAX_DEPTH].min
+    end
+  end
+end

data/lib/trmnlp/lint/check.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module Lint
+    # Base class for a single best-practice check. A subclass declares a
+    # MESSAGE constant (and optionally LEARN_MORE) and implements #pass?.
+    # Checks that surface a variable number of findings override #issues.
+    class Check
+      def initialize(source)
+        @source = source
+      end
+
+      def issues
+        pass? ? [] : [issue]
+      end
+
+      private
+
+      attr_reader :source
+
+      def pass?
+        raise NotImplementedError
+      end
+
+      def issue
+        learn_more = self.class.const_defined?(:LEARN_MORE) ? self.class::LEARN_MORE : nil
+        { message: self.class::MESSAGE, learn_more: }.compact
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/custom_fields_used.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports custom fields declared in .trmnlp.yml that never appear in the
+      # polling settings or the markup — one finding per unused field.
+      class CustomFieldsUsed < Check
+        SETTINGS_KEYS = %w[polling_url polling_headers polling_body].freeze
+
+        def issues
+          source.custom_field_values.keys.reject { |keyname| used?(keyname) }.map do |keyname|
+            { message: "Custom field '#{keyname}' is not used in form fields or markup." }
+          end
+        end
+
+        private
+
+        def used?(keyname)
+          pattern = /#{Regexp.escape(keyname)}/
+          searchable_settings.match?(pattern) || source.all_markup.match?(pattern)
+        end
+
+        def searchable_settings
+          @searchable_settings ||= SETTINGS_KEYS.filter_map { |key| source.settings[key] }.join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/form_fields_valid.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+require_relative '../../form_field'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Validates settings.yml custom_fields against the FormField schema —
+      # the same source serve/build use for their startup warnings.
+      class FormFieldsValid < Check
+        def issues
+          FormField.validate_all(source.custom_field_definitions).map do |warning|
+            { message: "settings.yml custom_fields — #{warning}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/highcharts_animations_disabled.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class HighchartsAnimationsDisabled < Check
+        MESSAGE = 'Highcharts should have animations disabled.'
+        LEARN_MORE = 'https://trmnl.com/framework/chart'
+
+        private
+
+        def pass?
+          markup = source.all_markup
+          return true unless markup.downcase.include?('highcharts')
+
+          markup.match?(/animation:\s{0,6}false/)
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/highcharts_elements_unique.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class HighchartsElementsUnique < Check
+        MESSAGE = 'To avoid variable shadowing across charts in multiple layouts, ' \
+                  'use the append_random filter for your Highcharts elements.'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10347358-custom-plugin-filters'
+
+        private
+
+        def pass?
+          markup = source.all_markup
+          return true unless markup.downcase.include?('highcharts')
+
+          markup.match?(/append_random/)
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/image_links_reachable.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Flags static <img> URLs that answer with a non-success status. A
+      # network failure (offline, DNS, timeout) is NOT a plugin defect, so
+      # those are skipped rather than reported as one.
+      class ImageLinksReachable < Check
+        MESSAGE = 'One or more <img> tags has a static "src" URL that does not ' \
+                  'respond to HTTP GET requests with a success code.'
+        TIMEOUT = 5
+        UNREACHABLE = [SocketError, Net::OpenTimeout, Net::ReadTimeout,
+                       Errno::ECONNREFUSED, Errno::EHOSTUNREACH, OpenSSL::SSL::SSLError].freeze
+
+        private
+
+        def pass? = static_image_urls.all? { |url| reachable?(url) }
+
+        def static_image_urls
+          source.view_markup.values
+                .flat_map { |html| html.scan(/<img[^>]+src\s*=\s*["']([^"']+)["']/i).flatten }
+                .map(&:strip)
+                .reject { |src| src.empty? || src.include?('{{') || src.start_with?('data:') }
+        end
+
+        def reachable?(url)
+          return false unless url.match?(%r{\Ahttps?://})
+
+          response = fetch(URI.parse(url))
+          response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPRedirection)
+        rescue *UNREACHABLE
+          true
+        rescue StandardError
+          false
+        end
+
+        def fetch(uri)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
+                                              open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+            http.get(uri.request_uri)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/layouts_have_content.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class LayoutsHaveContent < Check
+        MIN_CONTENT_LENGTH = 10
+        MESSAGE = 'Some markup layouts are empty, please provide basic treatment.'
+
+        private
+
+        # A view passes when either its own markup or the shared markup
+        # carries real content — mirrors the hosted behaviour.
+        def pass?
+          source.view_markup.values.all? do |markup|
+            [markup.length, source.shared_markup.length].max >= MIN_CONTENT_LENGTH
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/limited_inline_styles.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class LimitedInlineStyles < Check
+        MAX_INLINE_STYLES = 6
+        PROPERTIES = %w[
+          justify-content padding margin background-color
+          border-radius text-align object-fit font-size
+        ].freeze
+        MESSAGE = 'Markup uses too many inline styles, add more native Framework classes.'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/11395668-recipe-best-practices#h_3a3eab0712'
+
+        private
+
+        def pass?
+          count = PROPERTIES.sum { |property| source.all_markup.scan(property).size }
+          count <= MAX_INLINE_STYLES
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/no_async_functions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class NoAsyncFunctions < Check
+        MESSAGE = 'Async JavaScript functions are not allowed due to browser ' \
+                  'timeout settings for generating screenshots.'
+
+        private
+
+        def pass? = !source.all_markup.downcase.include?('async function')
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/no_opacity.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class NoOpacity < Check
+        MESSAGE = 'Opacity should not be used, use the "--gray--##" Framework classes instead.'
+        LEARN_MORE = 'https://trmnl.com/framework/docs/text_color'
+        PATTERN = /opacity:\s*[\d.]+/
+
+        private
+
+        def pass? = !source.all_markup.match?(PATTERN)
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/no_size_classes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class NoSizeClasses < Check
+        PATTERN = /\b(view(--|__)(full|half_horizontal|half_vertical|quadrant))\b("|')>/
+        MESSAGE = "We already apply the 'full', 'half_horizontal', 'half_vertical', and " \
+                  "'quadrant' classes to each view, please remove them."
+
+        private
+
+        def pass? = !source.all_markup.match?(PATTERN)
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/title_casing.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class TitleCasing < Check
+        MESSAGE = 'Title should begin with a capital letter.'
+
+        private
+
+        def pass?
+          name = source.plugin_name
+          name.empty? || name[0] == name[0].upcase
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/title_length.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class TitleLength < Check
+        MAX_LENGTH = 50
+        MESSAGE = "Title should be <= #{MAX_LENGTH} characters long.".freeze
+
+        private
+
+        def pass? = source.plugin_name.length <= MAX_LENGTH
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/waits_for_dom_load.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class WaitsForDomLoad < Check
+        MESSAGE = 'JavaScript should listen for the DOMContentLoaded event, not window.onLoad()'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/9510536-private-plugins#h_db7030f8b8'
+        FORBIDDEN = ['window.onload', 'window.addeventlistener("load")',
+                     "window.addeventlistener('load')"].freeze
+
+        private
+
+        def pass?
+          markup = source.all_markup.downcase
+          FORBIDDEN.none? { |token| markup.include?(token) }
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/source.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module Lint
+    # The plugin data every lint check examines: markup per view, shared
+    # markup, the combined markup string, and the raw settings.yml. Built
+    # once and shared across all checks. Settings come straight from
+    # Config::Plugin (a single parse); checks read the raw `{{ }}` templates,
+    # which Config::Plugin's semantic readers render away.
+    class Source
+      VIEWS = %w[full half_horizontal half_vertical quadrant].freeze
+
+      def initialize(config:, paths:)
+        @config = config
+        @paths = paths
+      end
+
+      def plugin_name = settings['name'].to_s
+      def settings = config.plugin.settings
+      def custom_field_values = config.project.custom_fields
+      def custom_field_definitions = config.plugin.custom_field_definitions
+
+      def view_markup
+        @view_markup ||= VIEWS.to_h { |view| [view, read(paths.template(view))] }
+      end
+
+      def shared_markup
+        @shared_markup ||= read(paths.shared_template)
+      end
+
+      def all_markup
+        @all_markup ||= view_markup.values.join + shared_markup
+      end
+
+      private
+
+      attr_reader :config, :paths
+
+      def read(path) = path.exist? ? path.read.strip : ''
+    end
+  end
+end

data/lib/trmnlp/lint.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'lint/check'
+require_relative 'lint/source'
+require_relative 'lint/checks/title_casing'
+require_relative 'lint/checks/title_length'
+require_relative 'lint/checks/layouts_have_content'
+require_relative 'lint/checks/no_async_functions'
+require_relative 'lint/checks/waits_for_dom_load'
+require_relative 'lint/checks/limited_inline_styles'
+require_relative 'lint/checks/no_size_classes'
+require_relative 'lint/checks/no_opacity'
+require_relative 'lint/checks/highcharts_animations_disabled'
+require_relative 'lint/checks/highcharts_elements_unique'
+require_relative 'lint/checks/image_links_reachable'
+require_relative 'lint/checks/custom_fields_used'
+require_relative 'lint/checks/form_fields_valid'
+
+module TRMNLP
+  # Markup best-practice checks behind `trmnlp lint`.
+  module Lint
+    # Every check the lint command runs, in report order.
+    CHECKS = [
+      Checks::TitleCasing,
+      Checks::TitleLength,
+      Checks::LayoutsHaveContent,
+      Checks::NoAsyncFunctions,
+      Checks::WaitsForDomLoad,
+      Checks::LimitedInlineStyles,
+      Checks::NoSizeClasses,
+      Checks::NoOpacity,
+      Checks::HighchartsAnimationsDisabled,
+      Checks::HighchartsElementsUnique,
+      Checks::ImageLinksReachable,
+      Checks::CustomFieldsUsed,
+      Checks::FormFieldsValid
+    ].freeze
+  end
+end

data/lib/trmnlp/paths.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'xdg'
+
+module TRMNLP
+  class Paths
+    attr_reader :root_dir
+
+    def initialize(root_dir)
+      @root_dir = Pathname.new(root_dir)
+      @xdg = XDG.new
+    end
+
+    # --- trmnlp library ---
+
+    def gem_dir = Pathname.new(__dir__).join('..', '..').expand_path
+
+    def templates_dir = gem_dir.join('templates')
+
+    # --- directories ---
+
+    def src_dir = root_dir.join('src')
+
+    def build_dir = root_dir.join('_build')
+    def create_build_dir = build_dir.mkpath
+
+    def app_config_dir = xdg.config_home.join('trmnlp')
+
+    def cache_dir = xdg.cache_home.join('trmnl')
+    def create_cache_dir = cache_dir.mkpath
+
+    def valid? = trmnlp_config.exist?
+
+    # --- files ---
+
+    def trmnlp_config = root_dir.join('.trmnlp.yml')
+
+    def plugin_config = src_dir.join('settings.yml')
+
+    def template(view) = src_dir.join("#{view}.liquid")
+
+    def shared_template = template('shared')
+
+    def app_config = app_config_dir.join('config.yml')
+
+    def user_data = cache_dir.join('data.json')
+
+    def render_template = Pathname.new(__dir__).join('..', '..', 'web', 'views', 'render_html.erb')
+
+    def src_files = src_dir.glob('*').select(&:file?)
+
+    # File extension → transform language identifier.
+    TRANSFORM_EXTENSIONS = {
+      '.py' => 'python',
+      '.rb' => 'ruby',
+      '.php' => 'php',
+      '.js' => 'node'
+    }.freeze
+
+    # Locate src/transform.{py,rb,php,js}. Returns [Pathname, language]
+    # or [nil, nil] if no transform file exists.
+    def transform_file
+      TRANSFORM_EXTENSIONS.each do |ext, language|
+        candidate = src_dir.join("transform#{ext}")
+        return [candidate, language] if candidate.exist?
+      end
+      [nil, nil]
+    end
+
+    # --- utilities ---
+
+    def expand(path) = Pathname.new(path).expand_path(root_dir)
+
+    private
+
+    attr_reader :xdg
+  end
+end