trmnl_preview 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4db6e3e57f6772dd1af033e4ccb533ee516344b66d859b63185d23129a724ef5
-  data.tar.gz: 8415b8724cf0535880ab4c4e0a6ca42771363f7adae620fcca0bd290468a0d0c
+  metadata.gz: d1b736ce74a0385dda5b989fe604d0256d0b1522b1955855aa0eac945ec3dd0b
+  data.tar.gz: f4b4321d72bd9129a025f07d21707f0584e965a5bfe072db3ecc95c2fbf04921
 SHA512:
-  metadata.gz: b440d6525409a971f262d09d7914d7be562dfadf617d1463c03b92519e848bd29b20e9e53fb30e7a1cf964919723e7e3e64364b573609ab7fbc2d215acdd97af
-  data.tar.gz: 96ce3caffe6bd63267aad0f6f9aa53a4471ddd6f308447e31040aed8968e77d3a4d82048ff44c4b80ccfbf4678284099f846c4d68f821effebd8bc53454637e2
+  metadata.gz: 3997799add0b42fd60ffd8f6c7d9d3c99696152fe32316e8925cfe1a24eed73f410a7efc86a432a46697d1fbd7fa0fa44c7d8c63727c48c0ff48778035e993f5
+  data.tar.gz: 12cf46d3ae00fda1f1e82eb80c5ed2bbe2598208ad84de9ecdc878afcb96b51f27e4ed62630195cdb1a0fc60a8d5b6cbc1d6be2f1ef4833aefdc0c370cd1634d

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 
 # Changelog
 
+## 0.21.0
+
+- The `bin/trmnlp` script that `trmnlp init` writes pulls a newer `trmnl/trmnlp` image once a day, so a Docker user stays on the latest release. Before, it ran whatever image was pulled first. The README shows how to install the script as `trmnlp` with Docker alone.
+- The `bin/trmnlp` script that `trmnlp init` writes runs every command in Docker as the gem would. It asked for a terminal it did not have on CI and in scripts (`the input device is not a TTY`), and published port 4567 for every command, so `lint` and `test` failed while `serve` ran and `serve --port` could not be reached. On Linux it runs as you, so snapshots and `_build` are not root's. A plugin's OAuth tokens and saved data are kept between runs, and `CI` and `TRMNL_API_KEY` reach trmnlp. Saved as `trmnlp` on the `PATH`, it no longer starts itself without end. An existing plugin gets the new script from `trmnlp init <its folder>`, answering `y` for `bin/trmnlp` only.
+- The README asks for Ruby >= 4.0 to install the gem, as the gem does. It said 3.4.
+- `trmnlp lint` reports a filter that neither Liquid nor trmnl-liquid defines (`no_unknown_filters`), such as a typo or a LiquidJS filter like `push`. TRMNL outputs the value unfiltered, and `serve` and `build` drew it the same way, so nothing showed the mistake.
+- The Docker image includes geckodriver, so it draws screens on arm64 Linux such as a Raspberry Pi. Selenium downloaded it on every run that draws a screen (`test`, `build`, `serve`), which took about half a second and failed with no network, and on arm64 without x86 emulation it could not download one at all (`Unable to obtain geckodriver`).
+- Every command checks RubyGems for a newer stable release, once a day, and suggests a Gem or Bundler update command on stderr; `trmnlp version` always asks. `--quiet` or `TRMNLP_NO_UPDATE_NOTIFIER=1` skips it, and network failures leave output and exit status unchanged.
+- `have_no_overflow(except: '.forecast')` and `screen.overflowing(except:)` leave out a box that hides content on purpose, and everything inside it.
+
 ## 0.20.0
 
 - `trmnlp lint` skips the rules listed under `ignored_lint_rules` in `.trmnlp.yml`, in text and JSON output alike. An unknown rule ID is an error that lists the known ones.

data/README.md

@@ -100,6 +100,17 @@ trmnlp push                    # upload
 
 `trmnlp lint` exits non-zero when it finds issues, so you can gate CI on it. Run `trmnlp help` for all flags.
 
+Every command also checks RubyGems for a newer stable `trmnl_preview` release
+and, when one is available, suggests `gem update trmnl_preview`, or
+`bundle update trmnl_preview` when run through Bundler. An exact Gemfile pin must
+be changed before Bundler can update it. Notices go to stderr, keeping lint JSON
+output and exit status unchanged. The answer is cached for a day, so most runs
+make no request; `trmnlp version` always asks RubyGems. `--quiet` or
+`TRMNLP_NO_UPDATE_NOTIFIER=1` skips the check. Connection and read timeouts are
+two seconds each; current versions and an unavailable registry stay silent. The
+check never installs an update or changes your Gemfile or lockfile. Inside Docker there is no
+check: the `bin/trmnlp` script pulls a newer image once a day instead.
+
 Lint findings include a stable snake_case rule ID, severity and source locations.
 Locations use project-relative paths and one-based line/column numbers, followed
 by a source excerpt (up to 240 characters). Aggregate checks show their contributing
@@ -123,6 +134,8 @@ Liquid in declaration values is counted without rendering the plugin, every bran
 Filters from `custom_filters` in `.trmnlp.yml` exist only in trmnlp. TRMNL does not load them
 and outputs the value unfiltered, so `no_custom_filters` reports each place the markup uses one.
 Filters that trmnl-liquid also provides are not reported.
+A filter that neither Liquid nor trmnl-liquid defines, such as a typo or one from another
+Liquid (Jekyll, LiquidJS), is also output unfiltered on TRMNL, so `no_unknown_filters` reports it.
 
 To accept a rule's findings, list its rule ID under `ignored_lint_rules` in `.trmnlp.yml`.
 `trmnlp lint` then skips that check in both formats, so the CLI and CI agree. An unknown
@@ -214,13 +227,13 @@ The `bin/trmnlp` script is provided as a convenience. It will use the local Ruby
 
 You can modify the `bin/trmnlp` script to set up environment variables (plugin secrets, etc.) before running the server.
 
-**Gem or Docker?** Install the gem if you already have Ruby >= 3.4 — it has the fastest startup. Use Docker for zero local setup.
+**Gem or Docker?** Install the gem if you already have Ruby >= 4.0 — it has the fastest startup. Use Docker for zero local setup.
 
 ### Installing via RubyGems
 
 Prerequisites:
 
-- Ruby >= 3.4
+- Ruby >= 4.0
 - For PNG rendering (optional):
   - Firefox
   - ImageMagick
@@ -232,6 +245,20 @@ trmnlp serve
 
 ### Installing via Docker
 
+To type `trmnlp` as with the gem, copy the script from the image onto your `PATH`:
+
+```sh
+mkdir -p ~/.local/bin
+docker run --rm --entrypoint cat trmnl/trmnlp /app/templates/init/bin/trmnlp > ~/.local/bin/trmnlp
+chmod +x ~/.local/bin/trmnlp
+```
+
+It runs each command in the image and pulls a newer image once a day. To stay on one release,
+set `IMAGE` in the script to a tag such as `trmnl/trmnlp:v0.20.0`. `trmnlp init` puts the same
+script in each plugin as `bin/trmnlp`.
+
+Or run the image yourself:
+
 ```sh
 docker run \
     --pull always \

data/lib/trmnlp/cli.rb

@@ -4,6 +4,8 @@ require 'thor'
 
 require_relative '../trmnlp'
 require_relative '../trmnlp/commands'
+require_relative 'paths'
+require_relative 'update_check'
 
 module TRMNLP
   class CLI < Thor
@@ -22,6 +24,23 @@ module TRMNLP
     def self.in_container? = File.exist?('/.dockerenv') || File.exist?('/run/.containerenv')
     def self.default_bind = in_container? ? '0.0.0.0' : '127.0.0.1'
 
+    no_commands do
+      # Thor routes every command through here, so the update notice covers
+      # them all without each command having to remember it. `version` runs
+      # its own fresh check after printing, and help has nothing to update.
+      def invoke_command(command, *)
+        check_for_update unless %w[help version].include?(command.name)
+        super
+      end
+
+      def check_for_update(fresh: false)
+        # In a container `gem update` does not apply; bin/trmnlp pulls a newer image instead.
+        return if options[:quiet] || UpdateCheck.disabled? || self.class.in_container?
+
+        UpdateCheck.new(Paths.new(options[:dir]).update_check).call(fresh:)
+      end
+    end
+
     desc 'build', 'Generate static HTML files'
     method_option :png, type: :boolean, default: false, desc: 'Also render a PNG per view'
     method_option :width, type: :numeric, desc: 'PNG width in pixels (with --png)'
@@ -96,6 +115,9 @@ module TRMNLP
     desc 'version', 'Show version'
     def version
       puts VERSION
+      # Keep the version first when stdout is a pipe and stderr is not.
+      $stdout.flush
+      check_for_update(fresh: true)
     end
   end
 end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'trmnl/liquid'
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports markup that uses a filter neither Liquid nor trmnl-liquid defines, such
+      # as a typo or a filter from another Liquid (Jekyll, LiquidJS). TRMNL does not fail
+      # on one: it outputs the value unfiltered. custom_filters are no_custom_filters' to report.
+      class NoUnknownFilters < Check
+        def issues
+          unknown_filter_names.map do |name|
+            { message: "Filter '#{name}' is not a Liquid or TRMNL filter. TRMNL outputs the value unfiltered; " \
+                       'check the name, or use a built-in filter or the transform instead.' }
+          end
+        end
+
+        private
+
+        def unknown_filter_names
+          used_filter_names - environment.filter_method_names - source.local_only_filter_names
+        end
+
+        def used_filter_names = source.markup_files.values.flat_map { filter_names(it) }.uniq
+
+        # Liquid's own parse, so a pipe in a string or a raw block is not taken for a filter.
+        def filter_names(markup)
+          names = []
+          template = ::Liquid::Template.parse(markup, environment:)
+          ::Liquid::ParseTreeVisitor.for(template.root)
+                                    .add_callback_for(::Liquid::Variable) { names.concat(it.filters.map(&:first)) }
+                                    .visit
+          names
+        rescue ::Liquid::SyntaxError
+          [] # A template that does not parse fails to render, which says so.
+        end
+
+        # trmnl-liquid's template tag keeps its body as a String, which ParseTreeVisitor cannot walk.
+        def environment = @environment ||= TRMNL::Liquid.new { it.register_tag 'template', ::Liquid::Block }
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/diagnostic.rb

@@ -44,7 +44,7 @@ module TRMNLP
         when 'layouts_have_content' then empty_view_locations
         when 'form_fields_valid' then form_field_locations
         when 'custom_fields_used' then project_field_locations
-        when 'no_custom_filters' then custom_filter_locations
+        when 'no_custom_filters', 'no_unknown_filters' then filter_locations
         when 'image_links_reachable' then source.locations(Regexp.union(check.unreachable_urls))
         else []
         end
@@ -55,7 +55,7 @@ module TRMNLP
         css_class ? source.locations(Regexp.new(Regexp.escape(css_class))) : []
       end
 
-      def custom_filter_locations
+      def filter_locations
         source.locations(Checks::NoCustomFilters.usage_pattern(finding[:message][/Filter '([^']+)'/, 1]))
       end
 

data/lib/trmnlp/lint.rb

@@ -19,6 +19,7 @@ require_relative 'lint/checks/image_links_reachable'
 require_relative 'lint/checks/custom_fields_used'
 require_relative 'lint/checks/form_fields_valid'
 require_relative 'lint/checks/no_custom_filters'
+require_relative 'lint/checks/no_unknown_filters'
 
 module TRMNLP
   # Markup best-practice checks behind `trmnlp lint`.
@@ -41,7 +42,8 @@ module TRMNLP
       Checks::ImageLinksReachable,
       Checks::CustomFieldsUsed,
       Checks::FormFieldsValid,
-      Checks::NoCustomFilters
+      Checks::NoCustomFilters,
+      Checks::NoUnknownFilters
     ].freeze
 
     def self.rule_id(check_type) = check_type.name.split('::').last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase

data/lib/trmnlp/paths.rb

@@ -55,6 +55,9 @@ module TRMNLP
 
     def transform_output = cache_dir.join('transform_output', "#{project_key}.json")
 
+    # One file for every project: the published gem version is not per project.
+    def update_check = cache_dir.join('update_check.json')
+
     def render_template = Pathname.new(__dir__).join('..', '..', 'web', 'views', 'render_html.erb')
 
     def src_files = src_dir.glob('*').select(&:file?)

data/lib/trmnlp/testing/rspec.rb

@@ -46,10 +46,10 @@ module TRMNLP
   end
 end
 
-RSpec::Matchers.define :have_no_overflow do
-  match { |screen| screen.overflowing.empty? }
+RSpec::Matchers.define :have_no_overflow do |except: nil|
+  match { |screen| screen.overflowing(except:).empty? }
   failure_message do |screen|
-    "expected nothing to overflow on #{screen.inspect}, but: #{screen.overflowing.join(', ')}"
+    "expected nothing to overflow on #{screen.inspect}, but: #{screen.overflowing(except:).join(', ')}"
   end
 end
 

data/lib/trmnlp/testing/screen.rb

@@ -15,6 +15,7 @@ module TRMNLP
 
       # Every element drawn past the screen's edge, and every box that cuts a child box or a glyph's ink.
       OVERFLOW_SCRIPT = <<~JS
+        const except = arguments[0];
         const screen = document.documentElement.getBoundingClientRect();
         const describe = (el) => el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') +
           (el.classList.length ? '.' + [...el.classList].join('.') : '');
@@ -78,7 +79,7 @@ module TRMNLP
         };
         return [...document.querySelectorAll('.view *')].filter((el) => {
           const box = el.getBoundingClientRect();
-          if (!drawn(box) || insideTruncation(el)) return false;
+          if (!drawn(box) || insideTruncation(el) || (except && el.closest(except))) return false;
           const outside = box.right > screen.right + 1 || box.bottom > screen.bottom + 1 || box.left < -1 || box.top < -1;
           const style = getComputedStyle(el);
           const overflows = el.scrollWidth > el.clientWidth + 1 || el.scrollHeight > el.clientHeight + 1;
@@ -123,7 +124,7 @@ module TRMNLP
 
       def evaluate(expression) = @browser.on(self) { it.execute_script("return (#{expression});") }
 
-      def overflowing = @browser.on(self) { it.execute_script(OVERFLOW_SCRIPT) }
+      def overflowing(except: nil) = @browser.on(self) { it.execute_script(OVERFLOW_SCRIPT, except) }
 
       # Script errors, unhandled rejections, console.error lines and files that failed to load.
       def problems = evaluate('window.__trmnlpProblems || []')

data/lib/trmnlp/update_check.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require_relative 'reporter'
+require_relative 'version'
+
+module TRMNLP
+  # Tells the user when RubyGems has a newer trmnl_preview. The answer is
+  # cached for a day so routine commands do not wait on the network; a
+  # failed lookup is cached too, so an offline run stalls at most once a day.
+  class UpdateCheck
+    ENDPOINT = 'https://rubygems.org/api/v1/gems/trmnl_preview.json'
+    TIMEOUT = 2
+    CACHE_TTL = 24 * 60 * 60
+    DISABLE_ENV_KEY = 'TRMNLP_NO_UPDATE_NOTIFIER'
+
+    def self.disabled? = !ENV[DISABLE_ENV_KEY].to_s.empty?
+
+    def initialize(cache_path, reporter: Reporter.new(stream: $stderr))
+      @cache_path = Pathname.new(cache_path)
+      @reporter = reporter
+    end
+
+    # Reports a newer stable release. fresh: asks RubyGems now instead of
+    # trusting a cached answer from the last day.
+    def call(fresh: false)
+      latest = fresh ? refresh : cached
+      return unless latest && latest > Gem::Version.new(VERSION)
+
+      reporter.info("trmnl_preview #{latest} is available (installed: #{VERSION}).")
+      reporter.info(update_guidance)
+    end
+
+    private
+
+    attr_reader :cache_path, :reporter
+
+    def cached
+      cache = read_cache
+      return version_from(cache['version']) if cache && Time.now.to_i - cache['checked_at'] < CACHE_TTL
+
+      refresh
+    end
+
+    def refresh
+      latest = fetch_latest
+      write_cache(latest)
+      latest
+    end
+
+    def read_cache
+      data = JSON.parse(cache_path.read)
+      data if data.is_a?(Hash) && data['checked_at'].is_a?(Integer)
+    rescue SystemCallError, JSON::ParserError
+      nil
+    end
+
+    def write_cache(latest)
+      cache_path.dirname.mkpath
+      cache_path.write(JSON.generate(checked_at: Time.now.to_i, version: latest&.to_s))
+    rescue SystemCallError
+      nil
+    end
+
+    def fetch_latest
+      response = Faraday.get(ENDPOINT) do |request|
+        request.options.open_timeout = TIMEOUT
+        request.options.timeout = TIMEOUT
+      end
+      parse_version(response.body) if response.success?
+    rescue Faraday::Error, JSON::ParserError, ArgumentError
+      nil
+    end
+
+    def parse_version(body)
+      data = JSON.parse(body)
+      version_from(data['version']) if data.is_a?(Hash)
+    end
+
+    def version_from(value)
+      return unless value.is_a?(String) && !value.empty? && Gem::Version.correct?(value)
+
+      version = Gem::Version.new(value)
+      version unless version.prerelease?
+    end
+
+    def update_guidance
+      return 'Update with: gem update trmnl_preview' if ENV['BUNDLE_GEMFILE'].to_s.empty?
+
+      'Update the trmnl_preview constraint in your Gemfile if needed, then run: bundle update trmnl_preview'
+    end
+  end
+end

data/lib/trmnlp/version.rb

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

data/templates/init/bin/trmnlp

@@ -4,10 +4,23 @@
 # Use this opportunity to set up environment variables, install dependencies, etc.
 #
 
-if command -v trmnlp &> /dev/null
+# Saved on the PATH as `trmnlp`, this script is what `command -v trmnlp` finds: not a gem.
+GEM="$(command -v trmnlp)"
+if [ -n "$GEM" ] && ! [ "$GEM" -ef "$0" ]
 then
-    trmnlp "$@"
-    exit
+    exec "$GEM" "$@"
+fi
+
+if ! command -v docker &> /dev/null
+then
+    echo "Install the trmnl_preview gem:
+
+  gem install trmnl_preview
+
+Or install Docker:
+
+    https://docs.docker.com/get-docker/"
+    exit 1
 fi
 
 # Determine XDG config directory on host OS
@@ -17,28 +30,64 @@ else
     CONFIG_DIR="$HOME/.config/trmnlp"
 fi
 
-if [ ! -d "$CONFIG_DIR" ]; then
-    mkdir -p "$CONFIG_DIR"
+# What trmnlp caches is kept as well: a plugin's OAuth tokens, its saved data and transform state.
+CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/trmnl"
+
+mkdir -p "$CONFIG_DIR" "$CACHE_DIR"
+
+# Add a tag to stay on one release: trmnl/trmnlp:v0.20.0
+IMAGE=trmnl/trmnlp
+
+# A newer release is pulled once a day. With no network, the image already here runs.
+PULLED_AT="$CACHE_DIR/image_pulled"
+if [ -z "$(find "$PULLED_AT" -mtime -1 2> /dev/null)" ]; then
+    docker pull --quiet "$IMAGE" > /dev/null 2>&1
+    touch "$PULLED_AT"
 fi
 
-if command -v docker &> /dev/null
+# On Linux the container's root is the host's root, and the files trmnlp writes (snapshots, _build,
+# a pulled plugin) would be root's. So trmnlp runs as you, with a home of its own to write in.
+# Docker Desktop and rootless Docker hand the files to you already.
+CONTAINER_HOME=/root
+SECURITY="$(docker info --format '{{.SecurityOptions}}' 2> /dev/null)"
+if [ "$(uname)" = Linux ] && [ "$(id -u)" != 0 ] && [ -n "$SECURITY" ] && [[ "$SECURITY" != *rootless* ]]
 then
-    docker run \
-        -it \
-        --rm \
-        --publish 4567:4567 \
-        --volume "$(pwd):/plugin" \
-        --volume "$CONFIG_DIR:/root/.config/trmnlp" \
-        trmnl/trmnlp "$@"
-    exit
+    CONTAINER_HOME=/tmp/home
+    # .config and .cache are made for you as well: Docker would make them root's to mount the
+    # folders below into them, and Firefox hangs when it cannot write there.
+    ARGS=(
+        --user "$(id -u):$(id -g)"
+        --env HOME=/tmp/home
+        --tmpfs "/tmp/home:exec,uid=$(id -u),gid=$(id -g)"
+        --tmpfs "/tmp/home/.config:uid=$(id -u),gid=$(id -g)"
+        --tmpfs "/tmp/home/.cache:exec,uid=$(id -u),gid=$(id -g)"
+    )
 fi
 
-echo "Install the trmnl_preview gem:
-
-  gem install trmnl_preview
-
-Or install Docker:
+# A terminal only when there is one: CI and scripts have none.
+if [ -t 0 ] && [ -t 1 ]; then
+    ARGS+=(--tty)
+fi
 
-    https://docs.docker.com/get-docker/"
+# Only serve listens, so every other command can run next to it.
+if [ "$1" = serve ]; then
+    PORT=4567
+    for ARG in "$@"; do
+        case "$PREVIOUS" in -p | --port) PORT="$ARG" ;; esac
+        case "$ARG" in --port=*) PORT="${ARG#--port=}" ;; esac
+        PREVIOUS="$ARG"
+    done
+    ARGS+=(--publish "$PORT:$PORT")
+fi
 
-exit 1
+exec docker run \
+    --rm \
+    --init \
+    --interactive \
+    "${ARGS[@]}" \
+    --env CI \
+    --env TRMNL_API_KEY \
+    --volume "$CONFIG_DIR:$CONTAINER_HOME/.config/trmnlp" \
+    --volume "$CACHE_DIR:$CONTAINER_HOME/.cache/trmnl" \
+    --volume "$(pwd):/plugin" \
+    "$IMAGE" "$@"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -433,6 +433,7 @@ files:
 - lib/trmnlp/lint/checks/no_custom_filters.rb
 - lib/trmnlp/lint/checks/no_opacity.rb
 - lib/trmnlp/lint/checks/no_size_classes.rb
+- lib/trmnlp/lint/checks/no_unknown_filters.rb
 - lib/trmnlp/lint/checks/recipe_overview_length.rb
 - lib/trmnlp/lint/checks/title_casing.rb
 - lib/trmnlp/lint/checks/title_length.rb
@@ -483,6 +484,7 @@ files:
 - lib/trmnlp/transform_client.rb
 - lib/trmnlp/transform_pipeline.rb
 - lib/trmnlp/transform_state.rb
+- lib/trmnlp/update_check.rb
 - lib/trmnlp/user_data_assembler.rb
 - lib/trmnlp/version.rb
 - lib/trmnlp/watcher.rb