carve-hexapdf 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9b8c7c6b8002f3587048d1711e0901a180e4f41a85778a2e4654f7daaeed9da
-  data.tar.gz: 6da20e9768485a0afe3aa2b71a73bb670a155a7adfb9e30d593bedead5db5632
+  metadata.gz: 45c5c94de95a03c35c6a7ea92a22aff7fec66c96ff2a5dc44cb36a43034426d8
+  data.tar.gz: 0e3560d71885dd7476d999ab910a2ea0ba9b111c7dccb678979c238e26e9d63c
 SHA512:
-  metadata.gz: 41deae43d68f4996a26a2e2ccae432550bb730877b82a164b5203fe3020e14e515e85d0261ff25a603c92bc7cc1957c2494c8ac7cf9b2c4174eed686f8b639c3
-  data.tar.gz: 3256a05ce59a8b4071df645e1df3690d3d9ee56c00d4f588f543330cf756c50e689c97aa39026db77e0caa1ac8f095b993fc57990dea20fecbb04d98fa838438
+  metadata.gz: 45f2c67a07e0036a07d862bb7cd42641bfae6a8123b668ab6b910bd67dd54a78d49f4dbe0e83a8f8f25e432207391c0b9377e13d9abf1c2f56eee95b5cf151b8
+  data.tar.gz: b18adba4f2de1b2d2678baa7adb7ac15ce5d8d581b7ca561e186e3c2b33c0bf387b2ba58b6a336669cf33642772cbdd1cbadb06142567a5a827e53f0908f02f6

data/CHANGELOG.md

@@ -5,7 +5,43 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## [0.1.2] - 2026-09-19
+
+### Fixed
+
+- **A substitution no longer vanishes from the page.** The inline renderer
+  dispatched on `critic_substitute` and read `new_text`; the engine publishes
+  `substitution`, whose halves are the inline arrays `old` and `new`
+  (markup-carve/carve-js#1827). The arm never fired, and the node has no
+  `children`, so the fallback rendered nothing at all. Both halves now reach the
+  page, struck for the replaced run and underlined for the replacement, matching
+  the reference ANSI and HTML renderers.
+  markup-carve/carve-hexapdf#39
+- **Inserted and deleted runs are decorated again.** The same mismatch on two
+  more arms: the dispatch read `critic_insert` and `critic_delete` where the
+  engine publishes `insert` and `delete`. Their text still reached the page
+  through the fallback, so what was lost was the underline and the
+  strikethrough, leaving an editorial mark indistinguishable from body text.
+  markup-carve/carve-hexapdf#41
+
+### Added
+
+- `Carve::Hexapdf.render_from_file(path)` renders the Carve document at `path`
+  with its `{{ path }}` includes expanded, contained to the file's own directory
+  by default and to `include_root:` when one is named. String input stays
+  literal. `on_includes:` hands the caller the warnings and the dependency
+  identities; without it the sanitized warnings go to stderr. `extensions:` and
+  `profile:` are accepted on that path and reach an included child.
+  markup-carve/carve-hexapdf#36
+
+### Changed
+
+- The development engine pin moves to carve-rb `main`, past
+  markup-carve/carve-rb#130, which exposes `Carve.parse_with_includes`, carries
+  the render options into a child, and publishes the substitution halves as
+  inline arrays. The supported consumer range is unchanged: no released
+  `carve-lang` carries the new halves yet, so a consumer resolving through that
+  range still sees a substitution render as nothing until carve-rb publishes.
 
 ## [0.1.1] - 2026-08-27
 

data/README.md

@@ -54,6 +54,50 @@ ast = Carve.parse("# From AST")
 pdf_bytes = Carve::Hexapdf.render_ast(ast)
 ```
 
+### Includes
+
+A Carve document can pull another file in with `{{ path }}`. A String has no
+identity of its own, so a directive in one stays literal; name the file instead
+and it expands:
+
+```ruby
+pdf_bytes = Carve::Hexapdf.render_from_file("report/index.crv")
+```
+
+`render_from_file` READS Carve from a path and hands back PDF bytes.
+`render_file` is its opposite pair: it takes Carve source and WRITES the PDF out,
+and a directive in that source stays literal.
+
+Containment defaults to the input file's own directory, so a sibling or a file
+below it resolves and nothing above it does. `include_root:` moves that root:
+
+```ruby
+Carve::Hexapdf.render_from_file("report/index.crv", include_root: "/srv/docs")
+```
+
+The root must be **absolute**. A relative one is refused rather than resolved,
+because resolving it lands on whatever directory the process happens to run in,
+which is not a root anyone chose. The named document has to sit inside the root.
+
+A target that cannot be read leaves the directive drawn as written, and the
+reason goes to stderr. The message does not say whether the file was missing or
+refused by containment: both report `include-unresolved`, so a document cannot
+be used to probe the filesystem. Pass `on_includes:` to take reporting over and
+get the dependency identities with it:
+
+```ruby
+Carve::Hexapdf.render_from_file(
+  "report/index.crv",
+  on_includes: lambda { |warnings:, dependencies:, suppressed_warnings:|
+    dependencies.each { |d| puts "#{d[:path]} #{d[:resolved] ? 'read' : d[:denial]}" }
+  }
+)
+```
+
+`extensions:` and `profile:` reach the engine on the include path, and a child
+file is parsed with the same ones as its parent. Without a root they raise,
+rather than being dropped: `Carve.parse` accepts neither.
+
 ### Options
 
 | Option | Default | Meaning |
@@ -217,43 +261,7 @@ always produces a PDF:
 
 ## Development
 
-```sh
-bundle install
-bundle exec rake test
-```
-
-### Which engine you are testing against
-
-`bundle install` here does **not** resolve `carve-lang` from RubyGems. `Gemfile`
-pins the engine to a carve-rb revision, so a development run measures one exact
-engine build rather than whatever the registry serves that day:
-
-```sh
-bundle exec ruby script/verify_engine_pin.rb
-# carve-lang 0.1.2 from carve-rb b7f3a91a... (Gemfile pins b7f3a91a4192)
-```
-
-CI runs that before the suite and refuses when the Gemfile, the resolved bundle
-and the loaded library disagree. To develop against a local carve-rb checkout,
-point `CARVE_RB_PATH` at it - it has to be set on purpose, so the surprising
-resolution is the one you asked for:
-
-```sh
-CARVE_RB_PATH=../carve-rb bundle install
-```
-
-An installed copy of this gem resolves differently, through the range
-`carve-hexapdf.gemspec` declares - today `>= 0.1.1, < 0.2.0`. The two are
-deliberately not the same engine, and the difference is not academic: this gem
-reads an AST whose node vocabulary was renamed once already inside 0.1.
-`test/engine_floor_test.rb` asks whether the engine under `bundle exec rake
-test` still publishes the vocabulary the renderer maps, and
-`script/consumer_engine_probe.rb` asks the same of an actual `gem install` -
-daily in `Engine drift`, and again before every release.
-
-There is no committed `Gemfile.lock`, and that is deliberate; the reasoning,
-including why a lockfile would be a weaker pin here and what it would cost the
-Ruby 3.1 job, is at the top of `Gemfile`.
+Contributor setup, testing, and maintenance notes are in the [development guide](docs/development.md).
 
 ## Licensing
 

data/lib/carve/hexapdf/renderer.rb

@@ -566,9 +566,14 @@ module Carve
         when "abbreviation"   then out << run(node[:abbr].to_s, ctx)
         when "cross_ref"      then out << run(node[:target].to_s, ctx)
         when "caption_number" then (out << run(node[:number].to_s, ctx) if node[:number])
-        when "critic_insert"  then emit_children(node, ctx.merge(underline: true), out)
-        when "critic_delete"  then emit_children(node, ctx.merge(strike: true), out)
-        when "critic_substitute" then out << run(node[:new_text].to_s, ctx.merge(underline: true))
+        when "insert" then emit_children(node, ctx.merge(underline: true), out)
+        when "delete" then emit_children(node, ctx.merge(strike: true), out)
+        # Both halves are inline arrays, and both reach the page: struck for the
+        # replaced run, underlined for the replacement, which is what the
+        # reference ANSI and HTML renderers show.
+        when "substitution"
+          emit_children({ children: node[:old] }, ctx.merge(strike: true), out)
+          emit_children({ children: node[:new] }, ctx.merge(underline: true), out)
         when "smart_punctuation" then out << run(smart_punctuation_text(node), ctx)
         # A character the author escaped. The backslash is authoring syntax, so
         # the page shows the character - but the node has no children, so
@@ -877,8 +882,8 @@ module Carve
       INLINE_TYPES = %w[
         text emphasis code link image span math raw_inline emoji autolink
         cross_ref caption_number mention tag citation_group inline_extension
-        abbreviation footnote soft_break hard_break critic_insert critic_delete
-        critic_substitute critic_comment
+        abbreviation footnote soft_break hard_break insert delete
+        substitution critic_comment
       ].freeze
     end
   end

data/lib/carve/hexapdf/version.rb

@@ -2,6 +2,6 @@
 
 module Carve
   module Hexapdf
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

data/lib/carve/hexapdf.rb

@@ -45,8 +45,31 @@ module Carve
       #                 +:bytes+ and optional +:width+/+:height+ (points) to
       #                 control the drawn size; anything else degrades the
       #                 construct to its monospace source.
-      def render(source, **opts)
-        render_ast(::Carve.parse(source), **opts)
+      def render(source, include_root: nil, source_path: nil, extensions: nil,
+                 profile: nil, on_includes: nil, **opts)
+        ast = parse_source(source, include_root: include_root, source_path: source_path,
+                           extensions: extensions, profile: profile,
+                           on_includes: on_includes)
+        render_ast(ast, **opts)
+      end
+
+      # Render the Carve document at +path+, with its <tt>{{ path }}</tt>
+      # includes expanded, and return the PDF bytes.
+      #
+      #   Carve::Hexapdf.render_from_file("report/index.crv")
+      #
+      # NOT to be confused with {render_file}, which takes Carve SOURCE and
+      # writes the PDF out. This one READS the Carve and hands the bytes back.
+      #
+      # Containment defaults to the input file's own directory, so a sibling or
+      # a file below it resolves and nothing above it does. +include_root:+
+      # widens or moves that root, and reaches the engine as the caller wrote
+      # it: the engine refuses a relative root, which is what keeps containment
+      # off whatever directory the process happens to run in.
+      def render_from_file(path, include_root: nil, **opts)
+        absolute = File.expand_path(path)
+        root = include_root || File.dirname(absolute)
+        render(File.read(absolute), include_root: root, source_path: absolute, **opts)
       end
 
       # Render an already-parsed Carve AST Hash (see +Carve.parse+) to PDF
@@ -62,10 +85,64 @@ module Carve
       end
 
       # Render Carve +source+ and write the PDF to +path+. Returns +path+.
+      #
+      # +source+ is a String with no identity of its own, so a directive stays
+      # literal unless the caller names both +include_root:+ and +source_path:+.
       def render_file(source, path, **opts)
         File.binwrite(path, render(source, **opts))
         path
       end
+
+      private
+
+      # The AST to draw: expanded when the caller named a root and a document.
+      #
+      # A String reaching this with neither is parsed as it stands, so a
+      # directive in it is text. That is the only thing a caller with no file
+      # can be given: a relative include has nothing to resolve against.
+      def parse_source(source, include_root:, source_path:, extensions:, profile:,
+                       on_includes:)
+        if include_root.nil? || source_path.nil?
+          unless extensions.nil? && profile.nil?
+            raise ArgumentError,
+                  "extensions: and profile: reach the engine on the include path only; " \
+                  "pass include_root: and source_path:, or drop them"
+          end
+
+          return ::Carve.parse(source)
+        end
+
+        result = ::Carve.parse_with_includes(source, root: include_root,
+                                                     source_path: source_path,
+                                                     extensions: extensions,
+                                                     profile: profile)
+        report_includes(result, on_includes)
+        result[:value]
+      end
+
+      # Hand the caller everything expansion found, or say what degraded.
+      #
+      # With +on_includes:+ the caller owns reporting and gets the dependency
+      # identities with it. Without it the sanitized warnings go to stderr,
+      # because a document that silently lost half its content is the failure
+      # this exists to prevent.
+      def report_includes(result, on_includes)
+        if on_includes
+          on_includes.call(warnings: Array(result[:warnings]),
+                           dependencies: Array(result[:dependencies]),
+                           suppressed_warnings: result[:suppressedWarnings].to_i)
+          return
+        end
+
+        Array(result[:warnings]).each do |warning|
+          where = warning[:file] ? "#{warning[:file]}: " : ""
+          $stderr.puts "carve-hexapdf: #{where}#{warning[:rule]}: #{warning[:message]}"
+        end
+        suppressed = result[:suppressedWarnings].to_i
+        return unless suppressed.positive?
+
+        $stderr.puts "carve-hexapdf: #{suppressed} further include warnings suppressed"
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: carve-hexapdf
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carve-lang