carve-lang 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fa1a68f65aa5ecd3b0ca6554071fa31a2db0b9f57789a65ee5e2f3d8af8b77f
-  data.tar.gz: 2d9cec2f07553546dcecaac2f603db42b559512dafa0d183e5a5c297561b4e25
+  metadata.gz: e1129dd70ab09658be69bfbbf0158a02d599d9e814fb5e3f015be6d1a6cc5621
+  data.tar.gz: bc87753903ba603238e2c766b20c8384259dc8f44e87da90af4ef3f6d26ac613
 SHA512:
-  metadata.gz: bd2a0359ee4083b50daf8da92144cdcb02f72a3edc7d67b79d52b3e37ced9a73443b229170e7758e610db406bee5065a3e9c449da4494601c963b087c44e4b06
-  data.tar.gz: 81355dccbf314c449d49fc64ffc41344d193ad28c51e1707249e7128b1dae2689cbef4f553460e2e20a0bf8afca42cdf52849709753a84dab55e8d8f20397743
+  metadata.gz: f4f5180ccfda64b312e035b7302db7de20b52293466dd1719715d7ab9fcdfa06ba61b23e993d042df746ced604219bdb78cd5931e09a6dd25388ee9fffcac102
+  data.tar.gz: c1276c1504398c7be637fc9e6699b42217e0a3845f49e7647348650701abdc25148fe2138c49643171154d8834c184ef711b294bd3f3215db29de509299e127c

data/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.7] - 2026-10-07
+
+### Changed
+
+- The engine is the published `carve-lang` 0.1.8 crate, up from 0.1.7. It closes
+  every row `resources/spec-drift.txt` declared: the gem renders all 2225 corpus
+  documents spec main declares byte-identically, where 0.1.7 rendered 30 of them
+  by a superseded rule. The ledger is empty again, which is the only state a tag
+  may ship.
+- **Breaking for a `Carve.to_html` consumer:** a heading cross-reference, a
+  numbered caption or equation reference, and a collapsed reference falling back
+  to heading text compare their target case exactly. `</#target>` against a
+  `# Target` heading no longer resolves and stays literal text; link-definition
+  labels, footnote labels and include fragment selectors already matched case
+  exactly. `carve fmt --migrate` in carve-rs repairs unambiguous case-only misses
+  (markup-carve/carve#2732, markup-carve/carve-rs#2320).
+- **Breaking for a `Carve.to_html` consumer:** a glossary reference matches its
+  term exactly and links to the matched entry, and two terms differing only in
+  case take two ids (markup-carve/carve#2739).
+- A render that blanks a denied destination scheme reports one
+  `destination-denied` loss, so a checked render of a `javascript:` destination
+  refuses where it used to pass. The emitted `href=""` does not move
+  (markup-carve/carve#2679).
+
+### Added
+
+- `Carve::EnginePanic`, a `StandardError` subclass raised when the engine
+  panics, so a host rendering untrusted input can rescue one and keep serving.
+  The message carries the panic text and its location in the engine source, and
+  the usual panic report still reaches stderr (#170).
+
+### Fixed
+
+- An engine panic arrives as a rescuable Ruby exception rather than `fatal`.
+  magnus catches the unwind but raises it as `fatal`, which no host can stop,
+  not even with `rescue Exception`, so any panic ended the process. The binding
+  now converts a caught panic itself (#170).
+- A line holding a single `|` followed by an attribute block, such as `|{.r}`,
+  renders as paragraph text. Under the 0.1.7 engine it panicked inside the table
+  check, and a panic crossing the FFI boundary reached Ruby as `fatal`, which
+  `rescue` cannot catch, so five bytes of input terminated the host process
+  (markup-carve/carve-rs#2341).
+
 ## [0.1.6] - 2026-09-29
 
 ### Changed
@@ -401,7 +444,8 @@ are not listed, because no release ever shipped them.
   Arrays (every AST node type is covered), enabling custom renderers such as
   [carve-hexapdf](https://github.com/markup-carve/carve-hexapdf).
 
-[Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.6...HEAD
+[Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.7...HEAD
+[0.1.7]: https://github.com/markup-carve/carve-rb/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/markup-carve/carve-rb/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/markup-carve/carve-rb/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/markup-carve/carve-rb/compare/v0.1.3...v0.1.4

data/README.md

@@ -45,6 +45,29 @@ Carve.to_html(
 `Carve::EXTENSIONS` reports the names accepted by the bundled engine. Unknown
 names raise `ArgumentError`.
 
+## Errors
+
+An invalid argument raises `ArgumentError`, and a render the engine refuses -
+input past a profile's `max_length`, or a denied construct - also raises
+`ArgumentError` with the engine's reason.
+
+If the engine panics, the call raises `Carve::EnginePanic`, a `StandardError`
+subclass carrying the panic message and its location in the engine source. A
+panic means the engine reached a state it believed impossible, so the document
+is not renderable, but the process survives and a host can serve an error
+instead of losing the worker:
+
+``` ruby
+begin
+  Carve.to_html(untrusted_source)
+rescue Carve::EnginePanic => e
+  logger.error("carve engine panic: #{e.message}")
+  "<p>This document could not be rendered.</p>"
+end
+```
+
+Report any input that raises it: a panic is an engine defect, not a rejection.
+
 ## Migration and AST access
 
 `Carve.from_html` and `Carve.from_markdown` return canonical Carve with

data/ext/carve/Cargo.lock

@@ -37,22 +37,24 @@ checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 
 [[package]]
 name = "carve-lang"
-version = "0.1.7"
+version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bade620457149d669d9e7b89c3952fa5c44fcbefac2d4de78b75f64792ef1774"
+checksum = "0889683244be278df2ff8e1cd88e9f932036a424bb8d838546636b7f11e93903"
 dependencies = [
  "html5ever",
  "markup5ever_rcdom",
+ "memchr",
  "pulldown-cmark",
  "regex",
  "serde",
  "serde_json",
+ "smallvec",
  "unicode-normalization",
 ]
 
 [[package]]
 name = "carve-rb"
-version = "0.1.6"
+version = "0.1.7"
 dependencies = [
  "carve-lang",
  "magnus",

data/ext/carve/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "carve-rb"
-version = "0.1.6"
+version = "0.1.7"
 edition = "2021"
 rust-version = "1.75"
 publish = false
@@ -22,4 +22,4 @@ serde_json = "1"
 # The Carve engine. Imported under the Rust crate alias `carve_rs` so the
 # binding's own crate name (`carve-rb`) does not collide with the engine's
 # package name (`carve`) in the Cargo lockfile.
-carve_rs = { package = "carve-lang", version = "=0.1.7" }
+carve_rs = { package = "carve-lang", version = "=0.1.8" }

data/ext/carve/src/lib.rs

@@ -27,8 +27,12 @@
 use carve_rs::extensions::registry;
 use carve_rs::{CarveExtension, Mode, Options, Profile, StaticRenderers};
 use magnus::value::{InnerValue, Opaque};
-use magnus::{function, prelude::*, Error, RArray, RHash, Ruby, Value};
+use magnus::{function, prelude::*, Error, ExceptionClass, RArray, RHash, Ruby, Value};
+use std::any::Any;
+use std::cell::RefCell;
+use std::panic::{self, AssertUnwindSafe};
 use std::path::{Path, PathBuf};
+use std::sync::Once;
 
 /// HTML-escape a string for the renderer-failure fallback path.
 ///
@@ -732,6 +736,192 @@ fn stamp_needs_review(source: String, current_version: Option<String>) -> bool {
     carve_rs::needs_review(&source, &current)
 }
 
+/// Panic deliberately inside the extension, so a test can observe the FFI
+/// panic contract rather than assuming it.
+///
+/// Nothing but a test calls this. It exists because no Carve input panics the
+/// pinned engine: the one that did (`|{.r}`) is fixed, and a test that cannot
+/// reach a panic cannot tell a working safety net from a missing one.
+fn panic_probe() -> String {
+    panic!("deliberate panic from the Carve extension panic probe");
+}
+
+// ---------------------------------------------------------------------------
+// FFI panic safety
+// ---------------------------------------------------------------------------
+//
+// magnus wraps every exposed call in catch_unwind, but `Error::from_panic`
+// raises the caught panic as Ruby's `fatal`, and Ruby does not let a host stop
+// a `fatal` -- not with `rescue Exception`, not with anything. So the unwind
+// that was supposed to protect the host still ends the process, and magnus
+// offers no way to choose a different class.
+//
+// Everything Ruby can reach therefore runs inside `guard`, which catches the
+// unwind FIRST and raises `Carve::EnginePanic` (a StandardError) instead. The
+// `panic = "unwind"` compile flag is still what makes any of this possible,
+// which is why `scripts/check-panic-unwind.sh` stays.
+
+thread_local! {
+    /// Where the most recent panic on this thread came from.
+    ///
+    /// The payload `catch_unwind` hands back carries the message but not the
+    /// location, and the location is the half that identifies the engine bug.
+    static PANIC_LOCATION: RefCell<Option<String>> = const { RefCell::new(None) };
+}
+
+/// Record panic locations without taking over panic reporting.
+///
+/// The previous hook still runs, so the `thread '<unnamed>' panicked at ...`
+/// line and any `RUST_BACKTRACE` output a developer relies on are unchanged.
+fn install_panic_hook() {
+    static ONCE: Once = Once::new();
+    ONCE.call_once(|| {
+        let previous = panic::take_hook();
+        panic::set_hook(Box::new(move |info| {
+            let location = info
+                .location()
+                .map(|l| format!("{}:{}:{}", l.file(), l.line(), l.column()));
+            PANIC_LOCATION.with(|slot| *slot.borrow_mut() = location);
+            previous(info);
+        }));
+    });
+}
+
+/// `Carve::EnginePanic`, or `RuntimeError` if the class cannot be looked up.
+///
+/// The fallback is still rescuable, which is the property that matters; losing
+/// the specific class is better than losing the process.
+fn engine_panic_class(ruby: &Ruby) -> ExceptionClass {
+    ruby.define_module("Carve")
+        .ok()
+        .and_then(|module| module.const_get::<_, ExceptionClass>("EnginePanic").ok())
+        .unwrap_or_else(|| ruby.exception_runtime_error())
+}
+
+/// Turn a caught unwind payload into a rescuable Ruby exception.
+fn engine_panic_error(payload: Box<dyn Any + Send>) -> Error {
+    let message = if let Some(m) = payload.downcast_ref::<&'static str>() {
+        (*m).to_string()
+    } else if let Some(m) = payload.downcast_ref::<String>() {
+        m.clone()
+    } else {
+        "panic".to_string()
+    };
+    let message = match PANIC_LOCATION.with(|slot| slot.borrow_mut().take()) {
+        Some(at) => format!("the Carve engine panicked at {at}: {message}"),
+        None => format!("the Carve engine panicked: {message}"),
+    };
+
+    // Unchecked for the same reason magnus does it in `Error::from_panic`: this
+    // only runs while a Ruby thread is calling into the extension.
+    let ruby = unsafe { Ruby::get_unchecked() };
+    Error::new(engine_panic_class(&ruby), message)
+}
+
+/// Run an exposed call with the panic net in front of magnus's.
+fn guard<T>(f: impl FnOnce() -> Result<T, Error>) -> Result<T, Error> {
+    match panic::catch_unwind(AssertUnwindSafe(f)) {
+        Ok(result) => result,
+        Err(payload) => Err(engine_panic_error(payload)),
+    }
+}
+
+/// Declare the guarded wrapper Ruby is given for an implementation function.
+///
+/// `=>` wraps an infallible implementation, `=>?` one that already returns
+/// `Result`. Registering a bare implementation instead of its wrapper would
+/// leave that one call raising `fatal` again, so `test/panic_unwind_test.rb`
+/// reads the `function!` registrations below and fails on any name that is not
+/// a `g_` wrapper.
+macro_rules! guarded {
+    ($wrapper:ident ( $($arg:ident : $ty:ty),* ) -> $ret:ty => $inner:ident) => {
+        #[allow(clippy::too_many_arguments)]
+        fn $wrapper($($arg: $ty),*) -> Result<$ret, Error> {
+            guard(|| Ok($inner($($arg),*)))
+        }
+    };
+    ($wrapper:ident ( $($arg:ident : $ty:ty),* ) -> $ret:ty =>? $inner:ident) => {
+        #[allow(clippy::too_many_arguments)]
+        fn $wrapper($($arg: $ty),*) -> Result<$ret, Error> {
+            guard(|| $inner($($arg),*))
+        }
+    };
+}
+
+guarded!(g_to_html(source: String) -> String => to_html);
+guarded!(g_to_markdown(source: String) -> String => to_markdown);
+guarded!(g_to_plain_text(source: String) -> String => to_plain_text);
+guarded!(g_to_ansi(source: String) -> String => to_ansi);
+guarded!(g_to_carve(source: String) -> String => to_carve);
+guarded!(g_from_markdown_json(source: String) -> String => from_markdown_json);
+guarded!(g_to_ast_json(source: String) -> String => to_ast_json);
+guarded!(g_extension_names() -> Vec<String> => extension_names);
+guarded!(g_panic_probe() -> String => panic_probe);
+guarded!(
+    g_stamp_needs_review(source: String, current_version: Option<String>) -> bool
+        => stamp_needs_review
+);
+guarded!(
+    g_from_html_json(ruby: &Ruby, source: String, mode: String) -> String =>? from_html_json
+);
+guarded!(g_read_stamp(ruby: &Ruby, source: String) -> Value =>? read_stamp);
+guarded!(
+    g_to_html_with_extensions(ruby: &Ruby, source: String, names: RArray) -> String
+        =>? to_html_with_extensions
+);
+guarded!(
+    g_to_html_full(
+        ruby: &Ruby,
+        source: String,
+        names: RArray,
+        mode: String,
+        renderers: RHash
+    ) -> String =>? to_html_full
+);
+guarded!(
+    g_to_html_full_with_symbols(
+        ruby: &Ruby,
+        source: String,
+        names: RArray,
+        mode: String,
+        renderers: RHash,
+        symbols: RHash
+    ) -> String =>? to_html_full_with_symbols
+);
+guarded!(
+    g_to_html_safe(
+        ruby: &Ruby,
+        source: String,
+        names: RArray,
+        mode: String,
+        renderers: RHash,
+        symbols: RHash,
+        safe: bool,
+        profile: Option<String>,
+        sections: bool
+    ) -> String =>? to_html_safe
+);
+guarded!(
+    g_render_with_includes_json(
+        ruby: &Ruby,
+        source: String,
+        root: String,
+        source_path: String,
+        target: String,
+        names: RArray,
+        mode: String,
+        renderers: RHash,
+        symbols: RHash,
+        safe: bool,
+        profile: Option<String>,
+        sections: bool,
+        max_depth: Option<usize>,
+        max_bytes: Option<usize>,
+        max_resolver_calls: Option<usize>,
+        max_warnings: Option<usize>
+    ) -> String =>? render_with_includes_json
+);
+
 /// Entry point invoked by Ruby when the extension is loaded.
 ///
 /// `name = "carve"` makes the macro emit the `Init_carve` symbol that matches
@@ -739,35 +929,43 @@ fn stamp_needs_review(source: String, current_version: Option<String>) -> bool {
 /// package is named `carve-rb`.
 #[magnus::init(name = "carve")]
 fn init(ruby: &Ruby) -> Result<(), Error> {
+    install_panic_hook();
+
     let module = ruby.define_module("Carve")?;
+    // Raised when the engine panics. A StandardError subclass on purpose:
+    // magnus would otherwise surface the panic as `fatal`, which no host can
+    // rescue, so an embedder taking untrusted input had no defense at all
+    // (markup-carve/carve-rb#170).
+    module.define_error("EnginePanic", ruby.exception_standard_error())?;
     // Native primitives. The pure-Ruby wrapper in lib/carve.rb defines the
     // public `Carve.to_html(source, extensions:, mode:, renderers:)` on top of
     // these. `_to_html` is the no-extension fast path; the wrapper owns the
     // bare `to_html` name.
-    module.define_singleton_method("_to_html", function!(to_html, 1))?;
-    module.define_singleton_method("to_markdown", function!(to_markdown, 1))?;
-    module.define_singleton_method("to_plain_text", function!(to_plain_text, 1))?;
-    module.define_singleton_method("to_ansi", function!(to_ansi, 1))?;
-    module.define_singleton_method("to_carve", function!(to_carve, 1))?;
+    module.define_singleton_method("_to_html", function!(g_to_html, 1))?;
+    module.define_singleton_method("to_markdown", function!(g_to_markdown, 1))?;
+    module.define_singleton_method("to_plain_text", function!(g_to_plain_text, 1))?;
+    module.define_singleton_method("to_ansi", function!(g_to_ansi, 1))?;
+    module.define_singleton_method("to_carve", function!(g_to_carve, 1))?;
     module.define_singleton_method(
         "_render_with_includes_json",
-        function!(render_with_includes_json, 15),
+        function!(g_render_with_includes_json, 15),
     )?;
-    module.define_singleton_method("_from_html_json", function!(from_html_json, 2))?;
-    module.define_singleton_method("_from_markdown_json", function!(from_markdown_json, 1))?;
-    module.define_singleton_method("_to_ast_json", function!(to_ast_json, 1))?;
+    module.define_singleton_method("_from_html_json", function!(g_from_html_json, 2))?;
+    module.define_singleton_method("_from_markdown_json", function!(g_from_markdown_json, 1))?;
+    module.define_singleton_method("_to_ast_json", function!(g_to_ast_json, 1))?;
     module.define_singleton_method(
         "to_html_with_extensions",
-        function!(to_html_with_extensions, 2),
+        function!(g_to_html_with_extensions, 2),
     )?;
-    module.define_singleton_method("to_html_full", function!(to_html_full, 4))?;
+    module.define_singleton_method("to_html_full", function!(g_to_html_full, 4))?;
     module.define_singleton_method(
         "to_html_full_with_symbols",
-        function!(to_html_full_with_symbols, 5),
+        function!(g_to_html_full_with_symbols, 5),
     )?;
-    module.define_singleton_method("_to_html_safe", function!(to_html_safe, 8))?;
-    module.define_singleton_method("_extension_names", function!(extension_names, 0))?;
-    module.define_singleton_method("_read_stamp", function!(read_stamp, 1))?;
-    module.define_singleton_method("_stamp_needs_review", function!(stamp_needs_review, 2))?;
+    module.define_singleton_method("_to_html_safe", function!(g_to_html_safe, 8))?;
+    module.define_singleton_method("_extension_names", function!(g_extension_names, 0))?;
+    module.define_singleton_method("_read_stamp", function!(g_read_stamp, 1))?;
+    module.define_singleton_method("_stamp_needs_review", function!(g_stamp_needs_review, 2))?;
+    module.define_singleton_method("_panic_probe", function!(g_panic_probe, 0))?;
     Ok(())
 }

data/lib/carve/version.rb

@@ -8,5 +8,5 @@ module Carve
   # compares it against ext/carve/Cargo.toml and against the newest cut
   # CHANGELOG section on every run, and .github/workflows/release.yml refuses to
   # publish a gem whose version is not the tag being released.
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: carve-lang
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys