carve-hexapdf 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9b8c7c6b8002f3587048d1711e0901a180e4f41a85778a2e4654f7daaeed9da
-  data.tar.gz: 6da20e9768485a0afe3aa2b71a73bb670a155a7adfb9e30d593bedead5db5632
+  metadata.gz: 20e7254d5697ad9d0e7b04769f516ce56b892d09c5407fe6b6cbd3e1ed8eed7e
+  data.tar.gz: 24af38395418395895e2eb639d8f6dd1e8ce3827135e532338fd670df2b8befb
 SHA512:
-  metadata.gz: 41deae43d68f4996a26a2e2ccae432550bb730877b82a164b5203fe3020e14e515e85d0261ff25a603c92bc7cc1957c2494c8ac7cf9b2c4174eed686f8b639c3
-  data.tar.gz: 3256a05ce59a8b4071df645e1df3690d3d9ee56c00d4f588f543330cf756c50e689c97aa39026db77e0caa1ac8f095b993fc57990dea20fecbb04d98fa838438
+  metadata.gz: 813e1c949beb5f2047b406fa06bc1580da7e5e163d6f67b95e15ca17d06fbc037585b8435f49e60c14cfba117f74d17d5184deeb5be7f6b023071759fd2b48eb
+  data.tar.gz: 7616495f87f40f73f2edbb423fea6c7d43b9443f930cb8372542225c682383913455879045f5ed7e5fc25bf0317e4a7976f77b8c39afe9ba4e9422c937f7703d

data/CHANGELOG.md

@@ -5,7 +5,79 @@ 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
+## [Unreleased]
+
+## [0.1.3] - 2026-10-08
+
+### Fixed
+
+- **A referenced footnote's body no longer vanishes from the page.**
+  `register_footnote` matched a reference to its definition through
+  `footnote_ref[:id]`; the engine renamed that field to `label`, so no
+  definition resolved and the note text never reached the endnote section. The
+  marker still numbered itself, so a page kept `[2]` and silently lost what it
+  pointed at. Both spellings are accepted now.
+  markup-carve/carve-hexapdf#47
+- **Cross-references reach the page.** The inline dispatcher had an arm for
+  `cross_ref` while the engine publishes `heading_ref`, so every `</#id>`
+  contributed nothing at all: `See </#Plan>.` drew `See .`. A resolved
+  reference is drawn as a link over the target heading's text, an unresolved
+  one back in its `</#id>` source spelling, which is how the HTML target
+  renders it. markup-carve/carve-hexapdf#48
+- **The example PDFs match the engine the gemspec supports.** They had been
+  generated by carve-lang 0.1.0, the version the floor excludes, and
+  `examples/generate.rb` would silently use a `carve-rb` checkout that merely
+  happened to sit beside this one. The sibling is opt-in through
+  `CARVE_RB_PATH` now, the same variable the `Gemfile` reads.
+  markup-carve/carve-hexapdf#49
+
+### Changed
+
+- Requires carve-rb v0.1.7 (carve-lang 0.1.7), up from an unreleased revision
+  32 commits and two releases behind it. A document containing a single `|`
+  followed by an attribute block used to abort the native extension with a
+  fatal `byte range starts at 1 but ends at 0`, killing the process rather than
+  raising, so a batch render died on five bytes of valid input; it now renders
+  as paragraph text. Cross-references, glossary terms and numbered captions
+  also compare case exactly on this engine.
+
+## [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

@@ -564,11 +564,32 @@ module Carve
           out << run("[#{number}]", ctx.merge(super: true)) if number
         when "citation_group" then out << run(node[:raw].to_s, ctx)
         when "abbreviation"   then out << run(node[:abbr].to_s, ctx)
-        when "cross_ref"      then out << run(node[:target].to_s, ctx)
+        # `heading_ref` is what `</#id>` publishes; `cross_ref` was its name
+        # before the rename and is still accepted, like the footnote arm above.
+        # Reading only `cross_ref` dropped every cross-reference from the page
+        # with no marker left behind: `See </#Plan>.` drew "See .".
+        #
+        # A resolved reference carries `href` and a `target` that is the target
+        # heading's TEXT, so it draws as a link over that text. An unresolved
+        # one carries no `href` and a `target` that is the selector as authored,
+        # which the HTML target renders as literal source - so it is drawn back
+        # in its source spelling rather than as a bare word that reads like
+        # prose.
+        when "heading_ref", "cross_ref"
+          if node[:href].to_s.empty?
+            out << run("</##{node[:target]}>", ctx)
+          else
+            out << run(node[:target].to_s, ctx.merge(link: node[:href].to_s))
+          end
         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
@@ -762,7 +783,12 @@ module Carve
           return @footnotes.last[:number]
         end
 
-        id = node[:id]
+        # `label` since carve-rb 0.1.4; `id` is the pre-rename spelling and is
+        # still accepted, the same way the node-type arms above accept both
+        # vocabularies. Reading only `id` silently dropped the body: the marker
+        # still numbered itself from `node[:number]`, so the page kept `[2]`
+        # and lost "2. Referenced note body." entirely.
+        id = node[:label] || node[:id]
         if id && @footnote_defs.key?(id)
           return @footnote_numbers[id] ||= begin
             @footnotes << { number: @footnotes.size + 1, blocks: @footnote_defs[id] }
@@ -877,8 +903,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.3"
   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.3
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carve-lang