trmnl_preview 0.14.2 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dabcf8ddd9b11d8ce8fc76e389820c7cd4f2d3b48db7aa7848896f9dfb6ec59
-  data.tar.gz: 467322fc910fdfed1ed5c37bb9773a7256d3d8f1f44683e2c9e4f3882b4ab7df
+  metadata.gz: de41fcea181f5a6a71aba1dcd87b4faa4c3d886df1f6581c3008a0f91e597bba
+  data.tar.gz: e9f1c5bb500da483e282ec826f812915b17dbfbbe5704e2b2be2c36de802e4cb
 SHA512:
-  metadata.gz: 75747b93b8aa45ac964b1ae87ef0dd50134c836bf5bc4bef19e47f166132b1dfca6edf8744f967702be6ffdc4c80c7b9b725646443053708f2d74df37a8537e9
-  data.tar.gz: b6fa8f755ab31f3dae9a3c2773ced039f646c7363288ae27512d0e3a95e72143093ca2869cb26a402084dd1b66c6c2dfc29a022ef8fed84bbb6e18fa5ffed347
+  metadata.gz: 5cba8a2ebb0798770ac545866b2c6e882e857db554fc2bcfa41d7c1046e53aaf3a2d0f798b32c634e5f00c4353cbb6fdeb14a4e407e3770d6bc016c90e0717c2
+  data.tar.gz: d3941f34861a81f2a21f9d1907620fb7d90f2f7f5d0fcb2dda3bac43ce683fa5eaafc5825853358635025125904037cb1305a038be841522d020b1239f3b2b07

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 
 # Changelog
 
+## 0.15.0
+
+- `trmnlp lint` names where each finding is: a rule ID such as `[no_opacity]`, then the file, line and column with the source line. Before, it printed only the message, so you had to search every view and Shared for the cause. `trmnlp lint --format json` writes the same report as one JSON object (`version`, `passed`, `issues`) for CI. Exit statuses are unchanged, and the values of unused custom fields in `.trmnlp.yml` are never printed. (#153)
+- The inline-style check counts real CSS declarations in `style` attributes, still with a limit of six. It counted eight property names anywhere in the markup, so `font-size` in an HTML comment or a `<style>` block failed while seven `style="color:red"` passed. Comments, scripts, text and `<style>` blocks no longer count, and declarations inside Liquid `{% if %}` branches all count. (#152)
+
 ## 0.14.2
 
 - A failed transform prints its stderr once. The `transform failed:` line repeated the whole stack trace that the `transform stderr:` line had just printed; it now names only the exit code. The preview page still shows the full error. (#148)

data/README.md

@@ -99,6 +99,26 @@ 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.
 
+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
+locations; checks for a missing chart setting show the related Highcharts usage.
+Unused project custom-field values are omitted from excerpts because they can
+contain credentials.
+
+For CI integrations, use `trmnlp lint --format json`. It writes one JSON object
+with `version: 1`, `passed` and an `issues` array. Each issue has `rule_id`,
+`severity`, `message`, `locations` and, when available, `learn_more`. Each location
+has `path`, `line`, `column` and `snippet`. A clean report has `passed: true` and
+`issues: []`. All existing checks retain severity `error` and the same exit status:
+zero when clean, nonzero when findings exist. `--quiet` suppresses either format.
+
+The inline-style check counts CSS declarations in actual HTML `style` attributes,
+with a limit of six across the view templates and Shared. All property names count,
+including custom properties. HTML/Liquid comments, script strings, text,
+`data-*` attributes and `<style>` blocks are excluded from this inline check.
+Liquid in declaration values is counted without rendering the plugin, every branch included.
+
 ## Building Static Files
 
 `trmnlp build` renders every view to a static file under `_build/` — handy for exporting a snapshot or feeding the output into another pipeline. Run it from inside a plugin project:

data/lib/trmnlp/cli.rb

@@ -72,6 +72,8 @@ module TRMNLP
     end
 
     desc 'lint', 'Check plugin code against TRMNL best practices'
+    method_option :format, type: :string, default: 'text', enum: %w[text json],
+                           desc: 'Report format (text or json)'
     def lint
       # Exit non-zero when issues are found so CI pipelines can gate on it.
       exit(1) unless Commands::Lint.run(options)

data/lib/trmnlp/commands/lint.rb

@@ -2,12 +2,18 @@
 
 require_relative 'base'
 require_relative '../lint'
+require_relative '../lint/diagnostic'
+require 'json'
 
 module TRMNLP
   module Commands
     # Runs the markup best-practice checks and reports their findings.
     class Lint < Base
-      Options = Data.define(:dir, :quiet)
+      Options = Data.define(:dir, :quiet, :format) do
+        def initialize(dir:, quiet:, format: 'text')
+          super(dir:, quiet:, format: format || 'text')
+        end
+      end
 
       def call
         context.validate!
@@ -18,7 +24,10 @@ module TRMNLP
       private
 
       def issues
-        @issues ||= TRMNLP::Lint::CHECKS.flat_map { |check| check.new(source).issues }.uniq
+        @issues ||= TRMNLP::Lint::CHECKS.flat_map do |type|
+          check = type.new(source)
+          check.issues.map { |finding| TRMNLP::Lint::Diagnostic.new(check, source, finding).to_h }
+        end.uniq
       end
 
       def source
@@ -26,6 +35,8 @@ module TRMNLP
       end
 
       def report
+        return reporter.info(JSON.generate(version: 1, passed: issues.empty?, issues:)) if options.format == 'json'
+
         return reporter.info(reporter.green('✓ All checks passed!')) if issues.empty?
 
         reporter.info(reporter.yellow("#{issues.size} issue#{'s' if issues.size > 1} found:\n"))
@@ -34,7 +45,11 @@ module TRMNLP
       end
 
       def report_issue(issue, index)
-        reporter.info("  #{index + 1}. #{issue[:message]}")
+        reporter.info("  #{index + 1}. [#{issue[:rule_id]}] #{issue[:message]}")
+        issue[:locations].each do |location|
+          reporter.info("     #{location[:path]}:#{location[:line]}:#{location[:column]}")
+          reporter.info("       #{location[:snippet]}") unless location[:snippet].to_s.empty?
+        end
         reporter.info("     Learn more: #{issue[:learn_more]}") if issue[:learn_more]
       end
     end

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

@@ -19,9 +19,14 @@ module TRMNLP
         UNREACHABLE = [SocketError, Net::OpenTimeout, Net::ReadTimeout,
                        Errno::ECONNREFUSED, Errno::EHOSTUNREACH, OpenSSL::SSL::SSLError].freeze
 
+        attr_reader :unreachable_urls
+
         private
 
-        def pass? = static_image_urls.all? { |url| reachable?(url) }
+        def pass?
+          @unreachable_urls = static_image_urls.reject { |url| reachable?(url) }
+          unreachable_urls.empty?
+        end
 
         def static_image_urls
           source.all_markup

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

@@ -1,25 +1,32 @@
 # frozen_string_literal: true
 
 require_relative '../check'
+require 'crass'
+require 'nokogiri'
 
 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 = Nokogiri::HTML.fragment(markup_without_liquid_comments).css('[style]').sum do |element|
+            # Count Liquid output as a CSS value and drop Liquid tags, so every
+            # branch's declarations count without evaluating the template.
+            css = element['style'].gsub(/\{\{.*?\}\}/m, 'var(--trmnlp-liquid)').gsub(/\{%.*?%\}/m, '')
+            Crass.parse_properties(css).count { |token| token[:node] == :property }
+          end
           count <= MAX_INLINE_STYLES
         end
+
+        def markup_without_liquid_comments
+          source.all_markup.gsub(/\{%-?\s*comment\s*-?%\}.*?\{%-?\s*endcomment\s*-?%\}/m, '')
+        end
       end
     end
   end

data/lib/trmnlp/lint/diagnostic.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module Lint
+    # Adds reporting metadata without changing a check's existing #issues API.
+    # Rule IDs are the snake_case check names and are part of the report contract.
+    class Diagnostic
+      SETTINGS_KEYS = {
+        'title_casing' => 'name', 'title_length' => 'name',
+        'description_length' => 'description', 'recipe_overview_length' => 'recipe_overview'
+      }.freeze
+      MARKUP_PATTERNS = {
+        'no_async_functions' => /async function/i,
+        'no_opacity' => Checks::NoOpacity::PATTERN,
+        'no_size_classes' => Checks::NoSizeClasses::PATTERN,
+        'waits_for_dom_load' => Regexp.new(Regexp.union(Checks::WaitsForDomLoad::FORBIDDEN).source, Regexp::IGNORECASE),
+        'limited_inline_styles' => /\sstyle\s*=/i,
+        'highcharts_animations_disabled' => /highcharts/i,
+        'highcharts_elements_unique' => /highcharts/i
+      }.freeze
+
+      def initialize(check, source, finding)
+        @check = check
+        @source = source
+        @finding = finding
+      end
+
+      def to_h
+        finding.merge(rule_id:, severity: 'error', locations: locations.uniq)
+      end
+
+      private
+
+      attr_reader :check, :source, :finding
+
+      def rule_id
+        check.class.name.split('::').last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+
+      def locations
+        return source.yaml_location('src/settings.yml', SETTINGS_KEYS[rule_id]) if SETTINGS_KEYS.key?(rule_id)
+        return source.locations(MARKUP_PATTERNS[rule_id]) if MARKUP_PATTERNS.key?(rule_id)
+
+        case rule_id
+        when 'arbitrary_values_in_range' then class_locations
+        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 'image_links_reachable' then source.locations(Regexp.union(check.unreachable_urls))
+        else []
+        end
+      end
+
+      def class_locations
+        css_class = finding[:message][/\A'([^']+)'/, 1]
+        css_class ? source.locations(Regexp.new(Regexp.escape(css_class))) : []
+      end
+
+      def empty_view_locations
+        return [] if source.shared_markup.length >= Checks::LayoutsHaveContent::MIN_CONTENT_LENGTH
+
+        source.view_markup.filter_map do |view, markup|
+          if markup.length < Checks::LayoutsHaveContent::MIN_CONTENT_LENGTH
+            { path: "src/#{view}.liquid", line: 1, column: 1, snippet: markup }
+          end
+        end
+      end
+
+      def form_field_locations
+        warning = finding[:message].split(' — ', 2).last
+        source.custom_field_definitions.each_with_index.flat_map do |field, index|
+          if FormField.validate(field).include?(warning)
+            source.yaml_location('src/settings.yml', 'custom_fields', index)
+          else
+            []
+          end
+        end
+      end
+
+      def project_field_locations
+        key = finding[:message][/Custom field '([^']+)'/, 1]
+        return [] unless key
+
+        # Project custom-field values can contain credentials. Show the key,
+        # but never echo its value into terminal output or CI artifacts.
+        source.yaml_location('.trmnlp.yml', 'custom_fields', key).map do |location|
+          location.merge(snippet: "#{key}: [value omitted]")
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/source.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'yaml'
+
 module TRMNLP
   module Lint
     # The plugin data every lint check examines: markup per view, shared
@@ -44,10 +46,55 @@ module TRMNLP
         end
       end
 
+      # Keep the original whitespace here: stripped templates cannot provide
+      # accurate line/column numbers. All paths in reports are project-relative.
+      def markup_files
+        @markup_files ||= (VIEWS + ['shared']).to_h do |view|
+          ["src/#{view}.liquid", raw_read(paths.template(view))]
+        end
+      end
+
+      def locations(pattern, files: markup_files)
+        files.flat_map do |path, contents|
+          contents.to_enum(:scan, pattern).map do
+            offset = Regexp.last_match.begin(0)
+            prefix = contents[0...offset]
+            line = prefix.count("\n") + 1
+            { path:, line:, column: offset - (prefix.rindex("\n") || -1),
+              snippet: contents.lines[line - 1].to_s.chomp[0, 240] }
+          end
+        end.uniq
+      end
+
+      def yaml_location(file, *keys)
+        path = file == '.trmnlp.yml' ? paths.trmnlp_config : paths.plugin_config
+        contents = raw_read(path)
+        node = Psych.parse_stream(contents).children.first&.root
+        keys.each do |key|
+          node = if key.is_a?(Integer) && node.is_a?(Psych::Nodes::Sequence)
+                   node.children[key]
+                 else
+                   mapping_value(node, key)
+                 end
+        end
+        return [] unless node
+
+        [{ path: file, line: node.start_line + 1, column: node.start_column + 1,
+           snippet: contents.lines[node.start_line].to_s.chomp[0, 240] }]
+      end
+
       private
 
       attr_reader :config, :paths
 
+      def raw_read(path) = path.exist? ? path.read : ''
+
+      def mapping_value(node, key)
+        return unless node.is_a?(Psych::Nodes::Mapping)
+
+        node.children.each_slice(2).to_a.rfind { |name, _| name.value == key.to_s }&.last
+      end
+
       def read(path) = path.exist? ? path.read.strip : ''
     end
   end

data/lib/trmnlp/version.rb

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

data/trmnl_preview.gemspec

@@ -47,6 +47,8 @@ Gem::Specification.new do |spec|
 
   # HTML rendering
   spec.add_dependency 'activesupport', '~> 8.0'
+  spec.add_dependency 'crass', '~> 1.0'
+  spec.add_dependency 'nokogiri', '~> 1.18'
   spec.add_dependency 'trmnl-liquid', '~> 0.8.2'
 
   # PNG rendering

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.14.2
+  version: 0.15.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -65,6 +65,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: crass
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.18'
 - !ruby/object:Gem::Dependency
   name: trmnl-liquid
   requirement: !ruby/object:Gem::Requirement
@@ -320,6 +348,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/diagnostic.rb
 - lib/trmnlp/lint/source.rb
 - lib/trmnlp/oauth.rb
 - lib/trmnlp/oauth/client.rb