jekyll_flexible_include 2.0.15 → 2.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef5ec6b930c61453fe741a89ea81e1da2d9303d910a23a9520f12c47a10b802b
-  data.tar.gz: 629a43513ddb0a6203024eeccbb52e8442d01612f5d10e2fc5451f4a9c739e52
+  metadata.gz: d8f07914cb71b0dc833f7735175ef18ccde8357e7fcf14014d954cae6e40c5bc
+  data.tar.gz: e077293b1be82f05dedfd02e6326c6c64d4a87895fc4d6f90cc7d532d50df857
 SHA512:
-  metadata.gz: d16333226e03cab0849b10d1b3c022c24f03d50d4e27c1459fc0e831f0bab64d080832dac3d3671dc9e1727e60e90a15864b4f74b6860d4045404f9058e5580b
-  data.tar.gz: ca350963ac6320ad1a1384ab8b2e3eea2c3e6043c12c0b872b95bfb05e942bc070a64a8b5631a642eaea4bd72f11fc7286b25e93a90643a6d54954a5b5b103ef
+  metadata.gz: 2a476f8c116c18590acd67e5be96fb1d10889394f3c278cec7bb43d211be7a8f8dcacc158953c4e9bea3de29b6d32668e8d5500ae24a8a0bd405d091219ac6ff
+  data.tar.gz: 5bd8341a6eb53a35a520791a32d79ec587169650f56d36c3d4b4aa965f6247867037253d83c677cbdae913d79b19d6a18a901a63013cc49fbc526358583bb238

data/.rubocop.yml

@@ -1,6 +1,9 @@
 require:
-  - rubocop-rspec
   # - rubocop-jekyll
+  - rubocop-md
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
 
 # inherit_gem:
 #   rubocop-jekyll: .rubocop.yml
@@ -20,8 +23,14 @@ Gemspec/DeprecatedAttributeAssignment:
 Gemspec/RequireMFA:
   Enabled: false
 
+Layout/InitialIndentation:
+  Exclude:
+    - README.md
+
 Layout/HashAlignment:
-  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+  Exclude:
+    - jekyll_flexible_include_plugin.gemspec
 
 Layout/LineLength:
   Max: 150
@@ -29,6 +38,10 @@ Layout/LineLength:
 Layout/MultilineMethodCallIndentation:
   Enabled: false
 
+Lint/RedundantCopDisableDirective:
+  Exclude:
+    - jekyll_flexible_include_plugin.gemspec
+
 Metrics/AbcSize:
   Max: 45
 
@@ -42,10 +55,10 @@ Metrics/ClassLength:
     - spec/**/*
 
 Metrics/CyclomaticComplexity:
-  Max: 10
+  Max: 20
 
 Metrics/MethodLength:
-  Max: 30
+  Max: 40
 
 Metrics/PerceivedComplexity:
   Max: 15
@@ -63,6 +76,9 @@ RSpec/MultipleExpectations:
 Style/CommandLiteral:
   Enabled: false
 
+Style/CommentedKeyword:
+  Enabled: false
+
 Style/Documentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 2.0.18 / 2023-03-24
+  * The following are now parsed property:
+    `die_on_file_error`, `die_on_path_denied`, `die_on_run_error`, `die_on_path_denied`, and `die_on_other_error`.
+
+## 2.0.17 / 2023-03-22
+  * Added `repo` and `git_ref` parameters, so files can be retrieved from git repositories at a given commit or tag.
+
+## 2.0.16 / 2023-02-19
+  * Replaced hard-coded CSS in `denied` method with `flexible_error` class in
+    `demo/assets/css/style.css`.
+  * Added `-e` and `-x` options to `demo/_bin/debug`.
+  * Added configuration section `flexible_include` with supported parameters
+    `die_on_file_error`, `die_on_path_denied`, `die_on_run_error`,
+    `die_on_path_denied` and `die_on_other_error`.
+  * Fixed `undefined method 'path'` that occurred when `FLEXIBLE_INCLUDE_PATHS` was specified.
+
 ## 2.0.15 / 2023-02-18
   * Replaced dependency `key-value-parser` with `jekyll_plugin_support`.
   * Added `demo` website.

data/README.md

@@ -34,46 +34,78 @@ In addition, filenames that require environment expansion because they contain a
 defined when <code>jekyll build</code> executes.
 
 
+A file from a git repository can also be included.
+Files can be retrieved from at a given commit or tag.
+Two new options are provided for this purpose:
+  - `repo` - directory where git repo resides; environment variables are expanded; defaults to current directory.
+  - `git_ref` - Git ref of commit or tag to be examined for the file; defaults to `HEAD`.
+
+
+### Configuration
+Configuration parameters can be added to a section in `_config.yml` called `flexible_include`, like this:
+
+```yaml
+flexible_include:
+  die_on_file_error: true
+  die_on_path_denied: true
+  die_on_run_error: true
+  die_on_other_error: true
+```
+
+The default values for all of these parameters is `false`,
+except for `die_on_other_error`, which defaults to `true`.
+
+ - If `die_on_file_error` is enabled, then an attempt to include a file that fails will cause Jekyll to die with an error message.
+
+ - If `die_on_path_denied` is enabled (see [Restricting Directory Access](#restricting-directory-access)), then an attempt to include a file that should be blocked will cause Jekyll to die with an error message.
+
+ - If `die_on_run_error` is enabled, then an attempt to run a process that fails will cause Jekyll to die with an error message.
+
+ - If `die_on_other_error` is enabled, then any other exception will cause Jekyll to die with an error message.
+
+
 ### Syntax
-The following are equivalent:
+The following are all equivalent, however, the first two are recommended:
 ```html
+{% flexible_include file="path" [ OPTIONS ] %}
+{% flexible_include file='path' [ OPTIONS ] %}
 {% flexible_include path [ OPTIONS ] %}
 {% flexible_include 'path' [ OPTIONS ] %}
 {% flexible_include "path" [ OPTIONS ] %}
 ```
 
-By default, the included file will escape characters <code>&lt;</code>,
-<code>{</code> and <code>}</code> unless the <code>do_not_escape</code> keyword option is specified.
 Note that the [square brackets] merely indicate optional parameters
 and are not intended to be written literally.
 
 
 ### Options
-  * `do_not_escape` includes the content without HTML escaping it.
+  * `do_not_escape` keyword option caused the content to be included without HTML escaping it.
+    By default, the included file will escape characters <code>&lt;</code>,
+    <code>{</code> and <code>}</code> unless the <code>do_not_escape</code> keyword option is specified.
 
   * `highlight='regex pattern here'` wraps content matching the regex pattern within a
     `<span class='bg_yellow'></span>` tag.
     Note that the pattern can simply consist of the exact text that you want to highlight.
 
-  * `pre` causes the included file to be wrapped inside a &lt;pre>&lt;/pre> tag,
-    no label is generated.
+  * `pre` is a keyword option that causes the included file to be wrapped inside a
+    &lt;pre>&lt;/pre> tag; no label is generated.
     The &lt;pre>&lt;/pre> tag has an `data-lt-active="false"` attribute, so
     [LanguageTool](https://forum.languagetool.org/t/avoid-spell-check-on-certain-html-inputs-manually/3944)
     will not attempt to check the spelling or grammar of the contents.
 
 The following options imply `pre`:
-  * `dark` applies the `dark` class to the generated &lt;pre>&lt;/pre> tag.
+  * `dark` keyword option applies the `dark` class to the generated &lt;pre>&lt;/pre> tag.
     You can define the `dark` and `darkLabel` classes as desired.
     [This CSS is a good starting point.](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#pre_css)
 
-  * `download` uses the name of the file as a label,
+  * `download` keyword option uses the name of the file as a label,
     and displays it above the &lt;pre>&lt;/pre> tag.
     Clicking the label causes the file to be downloaded.
 
-  * `copy_button` draws an icon at the top right of the &lt;pre>&lt;/pre>
+  * `copyButton` keyword option draws an icon at the top right of the &lt;pre>&lt;/pre>
     tag that causes the included contents to be copied to the clipboard.
 
-  * `label` specifies that an automatically generated label be placed above the contents.
+  * `label` keyword option specifies that an automatically generated label be placed above the contents.
     There is no need to specify this option if `download` or `copy_button` options are provided.
 
   * `label="blah blah"` specifies a label for the contents; this value overrides the default label.
@@ -130,7 +162,7 @@ and a red error message will be logged on the console that says something like:
 
 ## Installation
 1. Add the following to `Gemfile`, inside the `jekyll_plugins` group:
-   ```
+   ```ruby
    group :jekyll_plugins do
      gem 'jekyll_flexible_include', '~> 2.0.15'
    end
@@ -172,13 +204,13 @@ and a red error message will be logged on the console that says something like:
    {% flexible_include 'folder/within/jekyll/site/bar.js' %}
    {% flexible_include '/etc/passwd' %}
    {% flexible_include '~/.ssh/config' %}
-   {% flexible_include '!jekyll' %}
+   {% flexible_include '!jekyll help' %}
    {% flexible_include '$HOME/.bash_aliases' %}
    ```
 
 2. Include a JSON file (without escaping characters).
    ```
-   {% flexible_include '~/folder/under/home/directory/foo.html' do_not_escape %}
+   {% flexible_include do_not_escape file='~/folder/under/home/directory/foo.html' %}
    ```
 
 ## Additional Information
@@ -210,7 +242,7 @@ Following is a workaround.
 ## Known Issues
 If the plugin does not work:
 
-1. Ensure `_config.yml` doesn't have `safe: true`.
+1. Ensure `_config.yml` doesn't have `safe: true` set.
    That prevents all plugins from working.
 
 2. If you have version older than v2.x.x,
@@ -246,19 +278,36 @@ jekyll_flexible_include (2.0.4)
 ```
 
 
-## Demo
+## Demo Website
 A test/demo website is provided in the `demo` directory.
 You can run it under a debugger, or let it run free.
 
-### Free Range Demo Website
-To let it run freely, without a debugger, use the `-r` option:
-  ```shell
-  $ demo/bin/debug -r
-  ```
+The `demo/_bin/debug` script can set various parameters for the demo.
+View the help information with the `-h` option:
+```shell
+$ demo/_bin/debug -h
+
+debug - Run the demo Jekyll website.
+
+By default the demo Jekyll website runs without restriction under ruby-debug-ide and debase.
+View it at http://localhost:4444
+
+Options:
+  -e  Restrict the allowable directories to read from to the following regexes:
+        jekyll_flexible_include_plugin/.*
+        /dev/.*
+        /proc/.*
+        /run/.*
+
+  -h  Show this error message
+
+  -r  Run freely, without a debugger
+
+  -x  Disable the ability to execute arbitrary commands
+```
 
-View the generated website at [`http://localhost:4444`](http://localhost:4444)
 
-### Demo Website Debugging
+### Debugging the Demo
 To run under a debugger, for example Visual Studio Code:
  1. Set breakpoints.
 
@@ -269,7 +318,7 @@ To run under a debugger, for example Visual Studio Code:
 
   3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch configuration called `Attach rdebug-ide`.
 
-  4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+  4. View the generated website at [`http://localhost:4444`](http://localhost:4444).
 
 
 ### Build and Push to RubyGems

data/jekyll_flexible_include_plugin.gemspec

@@ -36,4 +36,5 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.version = JekyllFlexibleIncludePluginVersion::VERSION
 
   spec.add_dependency 'jekyll_plugin_support', '~> 0.5.1'
+  spec.add_dependency 'rugged'
 end

data/lib/flexible_include/version.rb

@@ -1,3 +1,3 @@
 module JekyllFlexibleIncludePluginVersion
-  VERSION = '2.0.15'.freeze
+  VERSION = '2.0.18'.freeze
 end

data/lib/flexible_include.rb

@@ -58,29 +58,21 @@ module FlexibleClassMethods
   end
 end
 
-class FlexibleError < StandardError; end
+FlexibleIncludeError = Class.new(Liquid::Error)
 
-class FlexibleInclude < JekyllSupport::JekyllTag
+class FlexibleInclude < JekyllSupport::JekyllTag # rubocop: disable Metrics/ClassLength
   include JekyllFlexibleIncludePluginVersion
 
-  class << self
-    include FlexibleClassMethods
-  end
-
-  FlexibleIncludeError = Class.new(Liquid::Error)
-
-  def render_impl
-    self.class.security_check
-    parse_args
+  def render_impl # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    setup
     path = JekyllPluginHelper.expand_env(@filename)
-
     case path
     when /\A\// # Absolute path
-      return denied("Access to #{path} denied by FLEXIBLE_INCLUDE_PATHS value.") unless self.class.access_allowed(path)
+      return denied("Access to <code>#{path}</code> denied by <code>FLEXIBLE_INCLUDE_PATHS</code> value.") unless self.class.access_allowed(path)
 
       @logger.debug { "Absolute path=#{path}, @filename=#{@filename}" }
     when /\A~/ # Relative path to user's home directory
-      return denied("Access to #{path} denied by FLEXIBLE_INCLUDE_PATHS value.") unless self.class.access_allowed(path)
+      return denied("Access to <code>#{path}</code> denied by <code>FLEXIBLE_INCLUDE_PATHS</code> value.") unless self.class.access_allowed(path)
 
       @logger.debug { "User home start @filename=#{@filename}, path=#{path}" }
       @filename = @filename.delete_prefix '~/'
@@ -99,19 +91,49 @@ class FlexibleInclude < JekyllSupport::JekyllTag
       @logger.debug { "Relative end @filename=#{@filename}, path=#{path}" }
     end
     render_completion(path, contents)
-    # rescue StandardError => e
-    #   raise FlexibleIncludeError, e.message.red, [] # Suppress stack trace
+  rescue Errno::EACCES => e
+    msg = format_error_message e.message
+    @logger.error msg
+    raise FlexibleIncludeError, msg, [] if @die_on_file_error
+
+    "<span class='flexible_error'>FlexibleIncludeError: #{msg}</span>"
+  rescue Errno::ENOENT => e
+    msg = format_error_message e.message
+    @logger.error msg
+    raise FlexibleIncludeError, msg, [] if @die_on_path_denied
+
+    "<span class='flexible_error'>FlexibleIncludeError: #{msg}</span>"
+  rescue FlexibleIncludeError => e
+    @logger.error e.message
+    raise e
+  rescue StandardError => e
+    msg = format_error_message e.message
+    @logger.error msg
+    raise FlexibleIncludeError, msg, [] if @die_on_other_error
+
+    "<span class='flexible_error'>FlexibleIncludeError: #{msg}</span>"
   end
 
   private
 
+  class << self
+    include FlexibleClassMethods
+  end
+
   def denied(msg)
-    @logger.error("#{@helper.page.path} - #{msg}")
-    "<p style='color: white; background-color: red; padding: 2pt 1em 2pt 1em;'>#{msg}</p>"
+    msg_no_html = remove_html_tags(msg)
+    @logger.error("#{@page['path']} - #{msg_no_html}")
+    raise FlexibleIncludeError, "#{@page['path']} - #{msg_no_html.red}", [] if @die_on_path_denied
+
+    "<p class='flexible_error'>#{msg}</p>"
+  end
+
+  def format_error_message(message)
+    "#{message} on line #{@line_number} (after front matter) of #{@page['path']}}"
   end
 
   def highlight(content, pattern)
-    content.gsub(Regexp::new(pattern), "<span class='bg_yellow'>\\0</span>")
+    content.gsub(Regexp.new(pattern), "<span class='bg_yellow'>\\0</span>")
   end
 
   def parse_args
@@ -138,18 +160,19 @@ class FlexibleInclude < JekyllSupport::JekyllTag
     @logger.debug("@filename=#{@filename}")
   end
 
-  def read_file(file)
-    File.read(file)
-  end
-
+  # Not used, delete
   def realpath_prefixed_with?(path, dir)
     File.exist?(path) && File.realpath(path).start_with?(dir)
-  rescue StandardError
-    false
+  rescue StandardError => _e
+    raise FlexibleIncludeError, remove_html_tags(e.message).red, [] if @die_on_file_error
+  end
+
+  def remove_html_tags(string)
+    string.gsub(/<[^>]*>/, '')
   end
 
   def render_completion(path, contents)
-    contents ||= read_file(path)
+    contents ||= File.read(path)
     contents.strip! if @strip
     contents2 = @do_not_escape ? contents : FlexibleClassMethods.escape_html(contents)
     contents2 = highlight(contents2, @highlight_pattern) if @highlight_pattern
@@ -158,8 +181,40 @@ class FlexibleInclude < JekyllSupport::JekyllTag
   end
 
   def run(cmd)
-    @logger.debug { "Executing @filename=#{cmd}" }
+    if cmd.empty?
+      msg = format_error_message 'FlexibleIncludeError: Empty command string'
+      @do_not_escape = true
+      return "<span class='flexible_error'>#{msg}</span>" unless @die_on_other_error
+
+      raise FlexibleIncludeError, msg, []
+    end
+
+    @logger.debug { "Executing #{cmd}" }
     %x[#{cmd}].chomp
+  rescue FlexibleIncludeError => e
+    raise e
+  rescue StandardError => e
+    msg = format_error_message "#{e.class}: #{e.message.strip}"
+    @logger.error msg
+    @do_not_escape = true
+    return "<span class='flexible_error'>#{msg}</span>" unless @die_on_run_error
+
+    e.set_backtrace []
+    raise e
+  end
+
+  def setup
+    self.class.security_check
+
+    config = @config[JekyllFlexibleIncludeName::PLUGIN_NAME]
+    if config
+      @die_on_file_error  = config['die_on_file_error'] == true
+      @die_on_other_error = config['die_on_other_error'] == true
+      @die_on_path_denied = config['die_on_path_denied'] == true
+      @die_on_run_error   = config['die_on_run_error'] == true
+    end
+
+    parse_args
   end
 
   PREFIX = "<button class='copyBtn' data-clipboard-target=".freeze

data/lib/git_util.rb

@@ -0,0 +1,41 @@
+require 'rugged'
+
+class GitFileReader
+  def initialize(repo_dir = '.')
+    @repo = Rugged::Repository.new repo_dir
+  end
+
+  def blob_at(ref, path)
+    commit = @repo.rev_parse ref # Rugged::Commit
+    @repo.blob_at(commit.oid, path) # Rugged::Blob
+  end
+
+  def commit_for_ref(ref)
+    reference = @repo.ref ref # Rugged::Reference
+    abort "Error: #{ref} is an invalid ref" if reference.nil?
+
+    reference_direct = reference.type == :symbolic ? reference.target : reference
+    @commit = reference_direct.target # Rugged::Commit
+    self
+  end
+
+  # @return content of desired file
+  def contents(filename)
+    abort('Error: @commit is undefined; invoke commit_for_ref before invoking contents') if @commit.nil?
+
+    tree = @commit.tree # Rugged::Tree
+    entry = tree.get_entry filename # hash
+    abort("Error: #{filename} is not present in commit #{commit.oid}") if entry.nil?
+
+    sha = entry[:oid] # String
+    object = @repo.read sha # Rugged::ObdObject; this is a blob
+    object.data # String
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  puts GitFileReader.new('.').blob_at('HEAD~2', 'README.md').content
+  # puts GitFileReader.new('.').commit_for_ref('HEAD^').contents('README.md')
+  # puts GitFileReader.new('.').commit_for_ref('HEAD').contents('README.md')
+  # puts GitFileReader.new('.').commit_for_ref('refs/heads/master').contents('README.md')
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_flexible_include
 version: !ruby/object:Gem::Version
-  version: 2.0.15
+  version: 2.0.18
 platform: ruby
 authors:
 - Mike Slinn
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-19 00:00:00.000000000 Z
+date: 2023-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll_plugin_support
@@ -26,6 +26,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.5.1
+- !ruby/object:Gem::Dependency
+  name: rugged
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   Jekyll's built-in include tag only supports including files within the _includes folder.
   This plugin supports 4 types of includes: absolute filenames,
@@ -45,7 +59,8 @@ files:
 - jekyll_flexible_include_plugin.gemspec
 - lib/flexible_include.rb
 - lib/flexible_include/version.rb
-- spec/glob_spec.rb
+- lib/git_util.rb
+- spec/flexible_include_spec.rb
 - spec/spec_helper.rb
 - spec/status_persistence.txt
 homepage: https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#flexibleInclude
@@ -81,7 +96,7 @@ specification_version: 4
 summary: Jekyll plugin supports various ways to include content into the generated
   site.
 test_files:
-- spec/glob_spec.rb
+- spec/flexible_include_spec.rb
 - spec/spec_helper.rb
 - spec/status_persistence.txt
 ...