trmnl_preview 0.25.0 → 0.27.0

data/lib/trmnlp/cli.rb

@@ -117,6 +117,8 @@ module TRMNLP
       puts VERSION
       # Keep the version first when stdout is a pipe and stderr is not.
       $stdout.flush
+      # On stderr, so a script that reads the version still gets the number alone.
+      warn "Running in Docker (#{ENV.fetch('TRMNLP_IMAGE', 'image unknown')})" if self.class.in_container?
       check_for_update(fresh: true)
     end
   end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Recipe review flags a plain https:// link in a custom field's description. An
+      # embedded link is shorter, opens in a new tab and is plainly clickable. Review
+      # skips a link without https://, which is how an example stays unlinked.
+      class CustomFieldLinksEmbedded < Check
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/11395668-recipe-best-practices#h_d981e5e6c6'
+        DESCRIPTION_KEY = /\Adescription(?:-[\w-]+)?\z/
+        ANCHOR = %r{<a\b[^>]*>.*?</a>}im
+        PLAIN_LINK = %r{https://[^\s<>"']*[^\s<>"'.,;:!?)]}
+
+        def issues
+          source.custom_field_definitions.flat_map do |field|
+            field.select { |key, _| key.match?(DESCRIPTION_KEY) }.flat_map do |key, text|
+              text.to_s.gsub(ANCHOR, '').scan(PLAIN_LINK).uniq.map { issue_for(field['keyname'], key, it) }
+            end
+          end
+        end
+
+        private
+
+        def issue_for(keyname, key, url)
+          { message: "Custom field '#{keyname}' #{key} has a plain link, #{url}. Embed it as " \
+                     "<a href=\"#{url}\" class=\"underline\">, or remove https:// if it is only an example.",
+            learn_more: LEARN_MORE }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # TRMNL refuses to import a settings.yml, view or transform over 100 KB, so `trmnlp push` fails.
+      class FilesUnderUploadLimit < Check
+        MAX_BYTES = 100 * 1024
+
+        def issues
+          source.upload_files.filter_map do |path|
+            next if path.size <= MAX_BYTES
+
+            { message: "src/#{path.basename} is #{path.size} bytes; TRMNL refuses to import a file over 100 KB." }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -12,14 +12,22 @@ module TRMNLP
       class FrameworkClassesExist < Check
         FAMILY_PATTERN = /\A(?:value|label|title|description|text|content)--/
         DATA_PATH = File.expand_path('../../../../db/data/framework_classes.yml', __dir__)
+        LEARN_MORE = 'https://trmnl.com/framework/docs/element_sizes'
+        # Smallest to largest. Each family has its own subset, and the same name is a different size in each.
+        # No family has `medium`, but it is the name people reach for between small and large.
+        SIZES = %w[xxsmall xsmall small base medium large xlarge xxlarge xxxlarge mega giga tera peta].freeze
 
         # Release number => the family classes its plugins.css defines, from that release until the next one listed.
         CLASSES_BY_RELEASE = YAML.load_file(DATA_PATH).transform_keys { Gem::Version.new(it) }.sort.freeze
 
         def issues
-          (used_classes - release_classes).map do |name|
-            { message: "'#{name}' is not a class in Framework v#{source.framework_version}, so it has no effect. " \
-                       'Check the name in the Framework docs.' }
+          classes = release_classes
+          (used_classes - classes).map do |name|
+            missing = "'#{name}' is not a class in Framework v#{source.framework_version}, so it has no effect."
+            sizes = sizes_of(name, classes)
+            next { message: "#{missing} Check the name in the Framework docs." } if sizes.empty?
+
+            { message: "#{missing} Its sizes are #{sizes.join(', ')}.", learn_more: LEARN_MORE }
           end
         end
 
@@ -36,6 +44,14 @@ module TRMNLP
           version = Gem::Version.new(source.framework_version.number)
           CLASSES_BY_RELEASE.select { |release, _| release <= version }.last.last
         end
+
+        # The family's sizes in this release, when the class names a size; empty otherwise.
+        def sizes_of(name, classes)
+          family, size = name.split('--', 2)
+          return [] unless SIZES.include?(size)
+
+          SIZES.map { "#{family}--#{it}" } & classes
+        end
       end
     end
   end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require_relative '../check'
+require_relative 'framework_classes_exist'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports a Framework class behind screen prefixes that the plugin's release does not
+      # define for it, such as `xl:value--large` or `dark:value--large`. The class matches no
+      # rule, so it does nothing. Classes the release lacks entirely are left to FrameworkClassesExist.
+      class FrameworkPrefixesExist < Check
+        PREFIXED_PATTERN = /\A(?<prefix>.+):(?<name>(?:value|label|title|description|text|content)--.+)\z/
+        DATA_PATH = File.expand_path('../../../../db/data/framework_prefixes.yml', __dir__)
+        LEARN_MORE = 'https://trmnl.com/framework/docs/responsive'
+
+        # Release number => the prefixes its plugins.css defines and the classes each covers,
+        # from that release until the next one listed.
+        VARIANTS_BY_RELEASE = YAML.load_file(DATA_PATH).transform_keys { Gem::Version.new(it) }.sort.freeze
+
+        def issues
+          prefixed_classes.filter_map do |full_name, prefix, name|
+            next unless release_classes.include?(name)
+
+            next if covers?(prefix, name)
+
+            { message: "'#{full_name}' has no effect: #{reason(prefix, name)}", learn_more: LEARN_MORE }
+          end
+        end
+
+        private
+
+        # A Liquid tag splits into several words, so any word with a brace or percent sign is skipped.
+        def prefixed_classes
+          source.html_fragments.values.flat_map { it.css('[class]').flat_map { it['class'].split } }
+                .grep_v(/[{}%]/)
+                .uniq
+                .filter_map { |full_name| (match = full_name.match(PREFIXED_PATTERN)) && [full_name, *match.captures] }
+        end
+
+        def reason(prefix, name)
+          version = "Framework v#{source.framework_version}"
+          return "#{name} has no '#{prefix}:' variant in #{version}." if families_by_prefix.key?(prefix)
+
+          reordered = families_by_prefix.keys.find do |known|
+            known.split(':').sort == prefix.split(':').sort && covers?(known, name)
+          end
+          return "#{version} has no '#{prefix}:' prefix. Write it as '#{reordered}:#{name}'." if reordered
+
+          "#{version} has no '#{prefix}:' prefix."
+        end
+
+        # A family is covered as `all` its classes, all `except` some, or `only` some.
+        def covers?(prefix, name)
+          coverage = families_by_prefix.dig(prefix, name.split('--').first)
+          case coverage
+          when 'all' then true
+          when Hash then coverage.key?('except') ? !coverage['except'].include?(name) : coverage['only'].include?(name)
+          else false
+          end
+        end
+
+        def families_by_prefix
+          @families_by_prefix ||= in_release(VARIANTS_BY_RELEASE).each_with_object({}) do |variant, prefixes|
+            variant['prefixes'].each { prefixes[it] = variant['families'] }
+          end
+        end
+
+        def release_classes = @release_classes ||= in_release(FrameworkClassesExist::CLASSES_BY_RELEASE)
+
+        def in_release(lists)
+          version = Gem::Version.new(source.framework_version.number)
+          lists.select { |release, _| release <= version }.last.last
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Recipe review asks a webhook recipe to show each install its own
+      # webhook URL, so the user can copy it into the service that pushes data.
+      class WebhookUrlShown < Check
+        MESSAGE = 'Add a custom field with field_type copyable_webhook_url, so people who install this webhook ' \
+                  'recipe can copy their webhook URL. TRMNL fills it in with the URL of each install.'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10513740-custom-plugin-form-builder#h_431c22552a'
+
+        private
+
+        def pass?
+          source.settings['strategy'] != 'webhook' ||
+            source.custom_field_definitions.any? { it['field_type'] == 'copyable_webhook_url' }
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/diagnostic.rb

@@ -7,7 +7,8 @@ module TRMNLP
     class Diagnostic
       SETTINGS_KEYS = {
         'title_casing' => 'name', 'title_length' => 'name',
-        'description_length' => 'description', 'recipe_overview_length' => 'recipe_overview'
+        'description_length' => 'description', 'recipe_overview_length' => 'recipe_overview',
+        'webhook_url_shown' => 'strategy'
       }.freeze
       MARKUP_PATTERNS = {
         'no_async_functions' => /async function/i,
@@ -41,9 +42,10 @@ module TRMNLP
         return source.locations(MARKUP_PATTERNS[rule_id]) if MARKUP_PATTERNS.key?(rule_id)
 
         case rule_id
-        when 'arbitrary_values_in_range', 'framework_classes_exist' then class_locations
+        when 'arbitrary_values_in_range', 'framework_classes_exist', 'framework_prefixes_exist' then class_locations
         when 'layouts_have_content' then empty_view_locations
         when 'form_fields_valid' then form_field_locations
+        when 'custom_field_links_embedded' then custom_field_description_locations
         when 'custom_fields_used' then project_field_locations
         when 'no_custom_filters', 'no_unknown_filters' then filter_locations
         when 'title_bar_outside_layout', 'no_nested_layouts'
@@ -83,6 +85,12 @@ module TRMNLP
         end
       end
 
+      def custom_field_description_locations
+        keyname, key = finding[:message].match(/\ACustom field '([^']*)' (\S+) has/)&.captures
+        index = source.custom_field_definitions.index { it['keyname'].to_s == keyname }
+        index ? source.yaml_location('src/settings.yml', 'custom_fields', index, key) : []
+      end
+
       def project_field_locations
         key = finding[:message][/Custom field '([^']+)'/, 1]
         return [] unless key

data/lib/trmnlp/lint/source.rb

@@ -45,6 +45,12 @@ module TRMNLP
         @all_markup ||= view_markup.values.join + shared_markup
       end
 
+      # The files TRMNL reads from a `trmnlp push` archive.
+      def upload_files
+        [paths.plugin_config, *(VIEWS + ['shared']).map { paths.template(it) }, paths.transform_file.first]
+          .compact.select(&:exist?)
+      end
+
       # The serverless transform (src/transform.{py,rb,php,js}), or '' without one.
       # It reads custom fields from its input, so a field may be used only there.
       def transform_code

data/lib/trmnlp/lint.rb

@@ -26,7 +26,11 @@ require_relative 'lint/checks/author_contact_method'
 require_relative 'lint/checks/title_bar_outside_layout'
 require_relative 'lint/checks/no_nested_layouts'
 require_relative 'lint/checks/framework_classes_exist'
+require_relative 'lint/checks/framework_prefixes_exist'
 require_relative 'lint/checks/no_external_qr_codes'
+require_relative 'lint/checks/custom_field_links_embedded'
+require_relative 'lint/checks/files_under_upload_limit'
+require_relative 'lint/checks/webhook_url_shown'
 
 module TRMNLP
   # Markup best-practice checks behind `trmnlp lint`.
@@ -57,7 +61,11 @@ module TRMNLP
       Checks::TitleBarOutsideLayout,
       Checks::NoNestedLayouts,
       Checks::FrameworkClassesExist,
-      Checks::NoExternalQrCodes
+      Checks::FrameworkPrefixesExist,
+      Checks::NoExternalQrCodes,
+      Checks::CustomFieldLinksEmbedded,
+      Checks::FilesUnderUploadLimit,
+      Checks::WebhookUrlShown
     ].freeze
 
     def self.rule_id(check_type) = check_type.name.split('::').last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase

data/lib/trmnlp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TRMNLP
-  VERSION = '0.25.0'
+  VERSION = '0.27.0'
 end

data/templates/init/bin/trmnlp

@@ -7,9 +7,10 @@
 # Add a tag to stay on one release, v0.22.0 or later: trmnl/trmnlp:v0.22.0
 IMAGE=trmnl/trmnlp
 
-# Saved on the PATH as `trmnlp`, this script is what `command -v trmnlp` finds: not a gem.
+# Saved on the PATH as `trmnlp`, this script is what `command -v trmnlp` finds: not a gem. Nor is
+# another copy of it there (it names run_in_docker): that one would run its own image, not the one above.
 GEM="$(command -v trmnlp)"
-if [ -n "$GEM" ] && ! [ "$GEM" -ef "$0" ]
+if [ -n "$GEM" ] && ! [ "$GEM" -ef "$0" ] && ! grep -qs run_in_docker "$GEM"
 then
     exec "$GEM" "$@"
 fi

data/templates/run_in_docker

@@ -60,6 +60,7 @@ exec docker run \
     "${ARGS[@]}" \
     --env CI \
     --env TRMNL_API_KEY \
+    --env TRMNLP_IMAGE="$IMAGE" \
     --volume "$CONFIG_DIR:$CONTAINER_HOME/.config/trmnlp" \
     --volume "$CACHE_DIR:$CONTAINER_HOME/.cache/trmnl" \
     --volume "$(pwd):/plugin" \

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -361,6 +361,7 @@ files:
 - db/data/and_x_more.yml
 - db/data/form_fields.yml
 - db/data/framework_classes.yml
+- db/data/framework_prefixes.yml
 - db/data/framework_versions.yml
 - db/data/locales/cs.yml
 - db/data/locales/da.yml
@@ -424,10 +425,13 @@ files:
 - lib/trmnlp/lint/checks/arbitrary_values_in_range.rb
 - lib/trmnlp/lint/checks/author_contact_method.rb
 - lib/trmnlp/lint/checks/coordinates_use_lat_lon.rb
+- lib/trmnlp/lint/checks/custom_field_links_embedded.rb
 - lib/trmnlp/lint/checks/custom_fields_used.rb
 - lib/trmnlp/lint/checks/description_length.rb
+- lib/trmnlp/lint/checks/files_under_upload_limit.rb
 - lib/trmnlp/lint/checks/form_fields_valid.rb
 - lib/trmnlp/lint/checks/framework_classes_exist.rb
+- lib/trmnlp/lint/checks/framework_prefixes_exist.rb
 - lib/trmnlp/lint/checks/highcharts_animations_disabled.rb
 - lib/trmnlp/lint/checks/highcharts_elements_unique.rb
 - lib/trmnlp/lint/checks/image_links_reachable.rb
@@ -445,6 +449,7 @@ files:
 - lib/trmnlp/lint/checks/title_casing.rb
 - lib/trmnlp/lint/checks/title_length.rb
 - lib/trmnlp/lint/checks/waits_for_dom_load.rb
+- lib/trmnlp/lint/checks/webhook_url_shown.rb
 - lib/trmnlp/lint/checks/yes_no_selects_are_boolean.rb
 - lib/trmnlp/lint/diagnostic.rb
 - lib/trmnlp/lint/source.rb