jekyll-carve 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28da599466525fea6bbc65a8c6143d8579241a20f1838d6ccb0f9d0317ac3405
-  data.tar.gz: f36f40e656e8d8ea3da71e207cbaeb61f7daf43b06f8ae7ef41f6d34dd9ad4f7
+  metadata.gz: 86256975160492f093658f4cde9291d34e1b343de95a42ec0e098d2ebb37a8c4
+  data.tar.gz: ec48c36fd313fe0fede2487ec12812c9684b5e4731fa3f6e60ad414fd9cdfd91
 SHA512:
-  metadata.gz: 869155a13081b84dcbd811b2a6474a8e1df7b282924c3b187226c0b16e782d8180f46dfd3b9fa9348c9ed631c0d8b37f33381c7e41849ec6571052c2619cd85b
-  data.tar.gz: 7fceaae2aee055d86faccc18445e2e5191dba2d9c3a74a73bd91ba1bffac31b531aa7fbcfce58da156379cb42f1f80214b9576a712d488f060e07cde018cd57b
+  metadata.gz: 5252c852e50fcc9240dbcbd47b734a8f1a269ff2d161966bde8d37cebf29219baf6778b08123a97791f098d82f7adec4196e3b02c8931e99e41f42d94e0694bb
+  data.tar.gz: 4981a39b6764c0c4b60399be7d4b3e0da50c701a8194a8e4369e87be52b2bbf59be62f93d80b85542400d74d20081540f324a0e96121c46783298145cc7eecf7

data/README.md

@@ -176,6 +176,45 @@ resolve against.
 > will publish them. Exclude them in `_config.yml`, or keep them outside the
 > source and point `include_root` at the tree above both.
 
+### `carve.lint` - reporting what renders but is lost
+
+Carve's linter reports constructs that parse and render, but not the way the
+author meant: a block attribute that attaches to nothing, a link to an id no
+heading has, an unclosed code fence. Turn it on to see them as build warnings:
+
+```yaml
+carve:
+  lint: true
+```
+
+```
+Carve lint: guide/intro.crv:7:1: unattached-block-attribute: This block attribute reaches no block: ...
+```
+
+Each warning names the page, the line and column in the file, and the rule id.
+The line counts the front matter, so it matches your editor; a Liquid tag that
+expands to several lines shifts the lines below it, since the linter reads the
+page after Liquid. Pages still render.
+
+To fail the build instead, use `strict`:
+
+```yaml
+carve:
+  lint: strict
+```
+
+Every page is linted and reported first, then `jekyll build` stops with an
+error before writing the site.
+
+The linter reads the same `carve.extensions` the pages render with. With
+`carve.includes` on it also lints each included Carve file, and a finding there
+names that file: `index.crv (parts/intro.crv:3:1): ...`. Include warnings such
+as `include-unresolved` are logged once, by the include pass, but count toward
+`strict`.
+
+`carve.lint` needs carve-lang 0.1.11 or later, the first engine that exposes the
+linter. That is why it is this gem's floor.
+
 ## Usage
 
 Create a page with a `.crv` extension. It MUST begin with Jekyll
@@ -197,6 +236,28 @@ This is /italic/ and *bold* text.
 Note Carve's inline syntax: `*...*` is **strong** (bold) and `/.../` is
 _emphasis_ (italic) - the opposite of Markdown.
 
+## Highlighting Carve code blocks
+
+This plugin renders `.crv` pages. To highlight a ` ```carve ` block inside a
+Markdown page, add [rouge-carve](https://github.com/markup-carve/rouge-carve),
+which registers a Carve lexer with Rouge, Jekyll's default highlighter:
+
+```ruby
+# Gemfile
+group :jekyll_plugins do
+  gem "rouge-carve"
+end
+```
+
+Jekyll requires every gem in the `jekyll_plugins` group on its own. Without
+that group, list it in `_config.yml` instead:
+
+```yaml
+plugins:
+  - jekyll-carve
+  - rouge-carve
+```
+
 ## Important: Jekyll front matter vs. Carve frontmatter
 
 This is the one nuance to understand:

data/lib/jekyll/carve/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Carve
-    VERSION = "0.1.3"
+    VERSION = "0.1.4"
   end
 end

data/lib/jekyll-carve.rb

@@ -61,32 +61,46 @@ module Jekyll
       def convert(content)
         document = Rendering.current
         root = include_root
-        if root.nil? || document.nil? || document.path.to_s.empty?
-          return ::Carve.to_html(content.to_s,
-                                 extensions: carve_extensions,
-                                 symbols: carve_symbols)
-        end
-        # carve-lang added this entry point in 0.1.4; the floor stays lower for sites without includes.
-        unless ::Carve.respond_to?(:to_html_with_includes)
-          raise ArgumentError,
-                "carve.includes: the installed carve-lang (#{::Carve::VERSION}) has no " \
-                "to_html_with_includes; upgrade it to 0.1.4 or later, or set carve.includes: false"
-        end
+        include_page = !(root.nil? || document.nil? || document.path.to_s.empty?)
+        html = render(content.to_s, document, include_page ? root : nil)
+        lint(content.to_s, document, include_page ? root : nil) if lint_mode
+        html
+      end
 
-        begin
-          result = ::Carve.to_html_with_includes(content.to_s,
-                                                 root: root,
-                                                 source_path: document.path,
-                                                 extensions: carve_extensions,
-                                                 symbols: carve_symbols)
-        rescue ArgumentError => e
-          # A relative root, or a page outside it. Both are decided by the
-          # engine; what this adds is the key and the page to look at.
+      # How `carve.lint` is set: nil (off), :warn or :strict.
+      #
+      # `true` logs each finding as a build warning; `"strict"` also fails the
+      # build once every page has been linted.
+      def lint_mode
+        case (value = carve_config["lint"])
+        when nil, false then nil
+        when true then :warn
+        when "strict", :strict then :strict
+        else
           raise ArgumentError,
-                "carve.include_root: #{document.relative_path || document.path}: #{e.message}"
+                "carve.lint: expected true, false or \"strict\", got #{value.inspect}"
         end
-        report_includes(result, document, root)
-        result[:value]
+      end
+
+      # Lint findings counted under `carve.lint: strict` since the last reset.
+      def lint_findings
+        @lint_findings ||= 0
+      end
+
+      # Fail the build when strict lint counted a finding.
+      #
+      # Called from the `:site, :post_render` hook below, so every page is
+      # linted and reported before the build stops.
+      def check_lint!
+        return unless lint_mode == :strict && lint_findings.positive?
+
+        raise Jekyll::Errors::FatalException,
+              "carve.lint: #{lint_findings} lint finding(s) under strict mode; see the warnings above"
+      end
+
+      # Drop the strict-mode count, so each build is judged on its own.
+      def reset_lint
+        @lint_findings = 0
       end
 
       # The containment root configured under `carve.include_root`, or nil when
@@ -172,6 +186,71 @@ module Jekyll
 
       private
 
+      def render(content, document, root)
+        if root.nil?
+          return ::Carve.to_html(content,
+                                 extensions: carve_extensions,
+                                 symbols: carve_symbols)
+        end
+        # carve-lang added this entry point in 0.1.4; the floor stays lower for sites without includes.
+        unless ::Carve.respond_to?(:to_html_with_includes)
+          raise ArgumentError,
+                "carve.includes: the installed carve-lang (#{::Carve::VERSION}) has no " \
+                "to_html_with_includes; upgrade it to 0.1.4 or later, or set carve.includes: false"
+        end
+
+        begin
+          result = ::Carve.to_html_with_includes(content,
+                                                 root: root,
+                                                 source_path: document.path,
+                                                 extensions: carve_extensions,
+                                                 symbols: carve_symbols)
+        rescue ArgumentError => e
+          # A relative root, or a page outside it. Both are decided by the
+          # engine; what this adds is the key and the page to look at.
+          raise ArgumentError,
+                "carve.include_root: #{document.relative_path || document.path}: #{e.message}"
+        end
+        report_includes(result, document, root)
+        result[:value]
+      end
+
+      # Log each lint finding as a build warning, located in the source file.
+      #
+      # Runs after rendering, so a bad include root is reported by the render
+      # path with its own message. With includes on, the include-* findings
+      # repeat the include warnings `report_includes` already logged, so they
+      # are counted but not logged twice.
+      def lint(content, document, root)
+        page = document && (document.relative_path || document.path).to_s
+        page = "(no page)" if page.nil? || page.empty?
+        options = { extensions: carve_extensions }
+        options.update(root: root, source_path: document.path) if root
+        findings = ::Carve.lint(content, **options)
+        offset = front_matter_lines(document)
+        findings.each do |finding|
+          next if root && finding[:rule].start_with?("include-")
+
+          where = if finding[:file]
+                    "#{page} (#{finding[:file]}:#{finding[:line]}:#{finding[:column]})"
+                  else
+                    "#{page}:#{finding[:line] + offset}:#{finding[:column]}"
+                  end
+          Jekyll.logger.warn "Carve lint:", "#{where}: #{finding[:rule]}: #{finding[:message]}"
+        end
+        @lint_findings = lint_findings + findings.size if lint_mode == :strict
+      end
+
+      # Lines of YAML front matter above the body, so a finding names the line
+      # in the file. Jekyll strips the front matter before `convert` sees it.
+      def front_matter_lines(document)
+        path = document&.path.to_s
+        return 0 if path.empty? || !File.file?(path)
+
+        match = Jekyll::Document::YAML_FRONT_MATTER_REGEXP.match(File.read(path, encoding: "bom|utf-8"))
+        match ? match[0].count("\n") : 0
+      end
+
       # Surface what expansion degraded, and record what it read.
       def report_includes(result, document, root)
         page = document.relative_path || document.path
@@ -379,6 +458,17 @@ end
 # BEFORE `setup`, and `setup` is what builds the converter list.
 Jekyll::Hooks.register :site, :after_reset do |site|
   Array(site.converters).each do |converter|
-    converter.reset_symbols if converter.is_a?(Jekyll::Carve::Converter)
+    next unless converter.is_a?(Jekyll::Carve::Converter)
+
+    converter.reset_symbols
+    converter.reset_lint
+  end
+end
+
+# `carve.lint: strict` fails here, after every page was linted and before any
+# output is written.
+Jekyll::Hooks.register :site, :post_render do |site|
+  Array(site.converters).each do |converter|
+    converter.check_lint! if converter.is_a?(Jekyll::Carve::Converter)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-carve
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-08 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carve-lang
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.1.11
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.1.11
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0