carve-lang 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '092afb8611f9491f14b1bdc5e74730dc30fd5efd269a3cf153246d8181e0e94c'
-  data.tar.gz: 57b9ce435040eb96ff5148a2ce15e0369bcb6f696bbf22422cb76ce42c60d1a9
+  metadata.gz: 8f7b8390c9d7d5e50b0f5272a47fad61194cfdb9f62a231a8087676aaa13feb5
+  data.tar.gz: b5dad730b6e6c6b7244cdd4b8080b4d23927f2c323055b0240c603e3c6230c6f
 SHA512:
-  metadata.gz: e8bfb7fea75aa1819fd2bde47740d428ba1c3846d004f5ca4e7fb11e89041750ecd7992ed3913fad42c4a627bbc5842e9e0adf66369f45c71499e34d623a3158
-  data.tar.gz: 18f13425d6701f44da146ee93c312acd0e8dec16a76fb55ab7995deadcf7931fbdd9fa8c666d19e7f153b7cd8b19d490cbe42e4389a0bfa9fe3be5183c65c64a
+  metadata.gz: f746efa34e732f4b0a855d60b61db5c8d13f767d4beeb4d0ec7d0a736daac5164b6c74941a30cba9472437e67734ed2d98d7837eac5a6ef4c7279169cc0b17e7
+  data.tar.gz: 587da609dfce7bab98b8333aba463ec784f5da814ec80b9624ed61c622e92c903586abeb33e3af3f33c2d387753a755cecaa82d3d9620b378b3533a337b900ad

data/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-09-19
+
+### Added
+
+- `Carve.to_html_with_includes` renders a file-backed document with its
+  `{{ path }}` directives expanded, contained to an absolute root the caller
+  names. It returns the rendered HTML alongside sanitized warnings and
+  root-relative dependencies, and forwards extension and include budget
+  settings to the engine. The binding canonicalizes the root and the source
+  path and requires the source to sit inside the root (#123, #125).
+- `Carve.parse_with_includes` publishes the expanded document as a tree, in the
+  shape `Carve.parse` returns, and the include path takes the same render
+  options the string entry points take. A consumer that draws from the tree
+  rather than from HTML, such as carve-hexapdf, was blocked without it. Its
+  nodes carry no `pos`: spec I4 leaves position remapping across an include out
+  of scope in every engine (#126, #127).
+
+### Changed
+
+- HTML and Markdown migration reports use schema version 2 with shared
+  preserved, normalized, degraded, and dropped fidelity plus confidence.
+  Markdown retains the existing `source_format` key as a compatibility alias
+  for the shared `sourceFormat` spelling and now emits a conservative
+  `fidelity-unverified` dropped/fallback finding on every import instead of
+  the previous empty diagnostics array (#117).
+- **Breaking:** A substitution node in the tree carries `old` and `new` as
+  arrays of inline nodes, where it carried the strings `oldText` and `newText`.
+  A caller reading that node walks the halves instead of reading them (#130,
+  markup-carve/carve-rs#1756).
+- The engine moves from carve-rs `42df4092` to released 0.1.6 (`d7837249`).
+  Beyond the substitution change, the range brings the include pass this
+  release exposes, mention and tag handling (a nameless mention or tag is
+  dropped and reported, an unspellable name is refused, attributes survive the
+  editor bridge), and writer and parser fixes: the Markdown and Carve writers
+  escape what would reopen a construct on the way back in, and parsing tightens
+  around braced inlines, forced closers, escaped markers, adjacent links, blank
+  table rows and a code span's closer. 1740 of 1740 corpus documents render
+  byte-identically, and `resources/spec-drift.txt` is empty.
+
 ## [0.1.3] - 2026-09-08
 
 ### Changed
@@ -324,7 +363,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.3...HEAD
+[Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.4...HEAD
+[0.1.4]: https://github.com/markup-carve/carve-rb/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/markup-carve/carve-rb/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/markup-carve/carve-rb/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/markup-carve/carve-rb/compare/v0.1.0...v0.1.1

data/README.md

@@ -37,15 +37,18 @@ time via `rb_sys`.
 require "carve"
 
 Carve.to_html("# Hello *world*")
+# => "<section id=\"Hello-world\">\n  <h1>Hello <strong>world</strong></h1>\n</section>"
 
 # Every core engine target is available from the binding.
 Carve.to_markdown(source)
 Carve.to_plain_text(source)
 Carve.to_ansi(source)
 Carve.to_carve(source)
+# Import reports use schema version 2, with fidelity and confidence per finding.
+# Markdown emits fidelity-unverified/dropped/fallback until its engine path
+# exposes construct-level fidelity.
 Carve.from_html('<p>Hello <strong>world</strong></p>')
 Carve.from_markdown('*em* and **strong**')
-# => "<section id=\"Hello-world\">\n  <h1>Hello <strong>world</strong></h1>\n</section>"
 
 # Carve syntax note: *...* is STRONG (bold), /.../ is EMPHASIS (italic).
 Carve.to_html("*bold* and /italic/")
@@ -77,6 +80,57 @@ this binding has always taken: `:math`, `:permalinks`, `:mermaid`, `:dot`,
 
 An unknown extension name raises `ArgumentError`.
 
+### File includes
+
+Includes are opt-in and require an absolute containment root plus the absolute
+path of the source document. The result carries the rendered value, warnings,
+and root-relative dependencies. Other render methods leave include directives
+literal.
+
+```ruby
+result = Carve.to_html_with_includes(
+  File.read("book.crv"),
+  root: File.expand_path("."),
+  source_path: File.expand_path("book.crv"),
+  max_depth: 16,
+)
+puts result[:value]
+```
+
+Every render option `Carve.to_html` takes is accepted here and reaches the
+included children too, so a document renders the same way whether or not it
+went through the include path: `extensions:`, `symbols:`, `profile:`, `mode:`,
+`renderers:`, `safe:` and `sections:`.
+
+`Carve.parse_with_includes` gives the expanded document as an AST instead, in
+the shape `Carve.parse` returns, for a host that walks the tree rather than
+rendering HTML:
+
+```ruby
+result = Carve.parse_with_includes(
+  File.read("book.crv"),
+  root: File.expand_path("."),
+  source_path: File.expand_path("book.crv"),
+)
+result[:value][:children]
+```
+
+Its nodes carry no `:pos`, unlike `Carve.parse`. Spec I4 leaves position
+remapping out of scope in every engine, so a span on an included node would name
+an offset in a document the caller never passed.
+
+`Carve.render_with_includes` takes the same arguments plus `target:`, one of
+`"html"`, `"markdown"`, `"plain"`, `"ansi"` or `"ast"`. There is no `"carve"`
+target: spec I15 excludes the Carve writer from expansion, because inlining a
+child into the formatter's output rewrites the author's document rather than
+formatting it.
+
+The budgets `max_depth:`, `max_bytes:`, `max_resolver_calls:` and
+`max_warnings:` pass through to the engine; omit one to keep its default. A
+target refused by the byte budget still reports `resolved: true`, because
+section 19 charges the budget for what the resolver handed back and a target is
+resolved before its size is known.
+
 ## Parsing to an AST
 
 `Carve.parse` returns the parsed document as a tree of Ruby Hashes and Arrays,
@@ -267,6 +321,9 @@ a document change.
 | `Carve.to_html(source, symbols: {...})` | Render with a `:name:` -> value symbol map (values are raw, see above). |
 | `Carve.to_html(source, safe: true, profile: :comment)` | Render untrusted input: escape `=html` raw blocks/spans, restrict constructs. |
 | `Carve.to_html(source, sections: false)` | Render headings flat, with the id on the `<h*>` instead of a `<section>` wrapper. |
+| `Carve.to_html_with_includes(source, root:, source_path:)` | Render contained file includes and return warnings and dependencies. |
+| `Carve.parse_with_includes(source, root:, source_path:)` | The same expansion, published as an AST instead of HTML. |
+| `Carve.render_with_includes(source, root:, source_path:, target:)` | The expansion over any render target: html, markdown, plain, ansi or ast. |
 | `Carve.read_stamp(source)` | Read a document's provenance marker: `{version:, generated_by:}` or `nil`. |
 | `Carve.needs_review?(source)` | Whether a document predates this engine's spec version (unstamped counts as yes). |
 | `Carve.to_html_with_extensions(source, names_array)` | Native primitive (Array of Strings). |

data/ext/carve/Cargo.lock

@@ -37,8 +37,8 @@ checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 
 [[package]]
 name = "carve-lang"
-version = "0.1.4"
-source = "git+https://github.com/markup-carve/carve-rs?rev=42df409227dc260cec336a6569f4f41c712cdc22#42df409227dc260cec336a6569f4f41c712cdc22"
+version = "0.1.6"
+source = "git+https://github.com/markup-carve/carve-rs?rev=d7837249c64b88879b04cd71b8b5555ff246e16f#d7837249c64b88879b04cd71b8b5555ff246e16f"
 dependencies = [
  "html5ever",
  "markup5ever_rcdom",
@@ -51,7 +51,7 @@ dependencies = [
 
 [[package]]
 name = "carve-rb"
-version = "0.1.3"
+version = "0.1.4"
 dependencies = [
  "carve-lang",
  "magnus",

data/ext/carve/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "carve-rb"
-version = "0.1.3"
+version = "0.1.4"
 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", git = "https://github.com/markup-carve/carve-rs", rev = "42df409227dc260cec336a6569f4f41c712cdc22" }
+carve_rs = { package = "carve-lang", git = "https://github.com/markup-carve/carve-rs", rev = "d7837249c64b88879b04cd71b8b5555ff246e16f" }

data/ext/carve/src/lib.rs

@@ -28,6 +28,7 @@ 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 std::path::{Path, PathBuf};
 
 /// HTML-escape a string for the renderer-failure fallback path.
 ///
@@ -215,6 +216,218 @@ fn to_carve(source: String) -> String {
     carve_rs::to_carve(&source)
 }
 
+/// Which renderer runs over the expanded document.
+///
+/// `carve` is absent on purpose: spec I15 excludes the Carve writer from
+/// expansion, because inlining a child into the formatter's output rewrites the
+/// author's document rather than formatting it.
+#[derive(Clone, Copy, PartialEq)]
+enum IncludeTarget {
+    Html,
+    Markdown,
+    Plain,
+    Ansi,
+    Ast,
+}
+
+fn parse_include_target(ruby: &Ruby, name: &str) -> Result<IncludeTarget, Error> {
+    match name {
+        "html" => Ok(IncludeTarget::Html),
+        "markdown" => Ok(IncludeTarget::Markdown),
+        "plain" => Ok(IncludeTarget::Plain),
+        "ansi" => Ok(IncludeTarget::Ansi),
+        "ast" => Ok(IncludeTarget::Ast),
+        other => Err(Error::new(
+            ruby.exception_arg_error(),
+            format!(
+                "Unknown Carve include target: {other:?} \
+                 (supported: \"html\", \"markdown\", \"plain\", \"ansi\", \"ast\")"
+            ),
+        )),
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn 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>,
+) -> Result<String, Error> {
+    let which = parse_include_target(ruby, &target)?;
+    let root_path = Path::new(&root);
+    let source_path = Path::new(&source_path);
+    if !root_path.is_absolute() || !source_path.is_absolute() {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "include root and source_path must be absolute".to_string(),
+        ));
+    }
+    let root_real = std::fs::canonicalize(root_path).map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            "include root is not a readable directory".to_string(),
+        )
+    })?;
+    let source_real = std::fs::canonicalize(source_path).map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            "include source_path is not a readable file".to_string(),
+        )
+    })?;
+    if !source_real.starts_with(&root_real) || !source_real.is_file() {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "include source_path must be a file inside the include root".to_string(),
+        ));
+    }
+
+    let resolver = carve_rs::FileSystemResolver::new(&root_real).map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            "include root is not usable".to_string(),
+        )
+    })?;
+    // The same options `to_html` builds. A document rendered through the
+    // include path renders the way it would without one: jekyll-carve passes a
+    // symbol map on every conversion, and carve-hexapdf asks for one profile
+    // and extension set across parent and child alike.
+    let parsed_mode = parse_mode(ruby, &mode)?;
+    let parsed_profile = match profile.as_deref() {
+        None => None,
+        Some(name) => Some(parse_profile(ruby, name)?),
+    };
+    let static_renderers = build_renderers(ruby, renderers)?;
+    let boxed = boxed_extensions(ruby, names)?;
+    let symbol_pairs = build_symbols(symbols)?;
+    let mut render_options = Options::new()
+        .with_mode(parsed_mode)
+        .with_renderers(static_renderers);
+    for extension in &boxed {
+        render_options = render_options.with_extension(extension.as_ref());
+    }
+    for (name, value) in &symbol_pairs {
+        render_options = render_options.with_symbol(name.clone(), value.clone());
+    }
+    if safe {
+        render_options = render_options.with_raw_html(false);
+    }
+    if let Some(preset) = parsed_profile {
+        render_options = render_options.with_profile(preset);
+    }
+    if !sections {
+        render_options = render_options.with_sections(false);
+    }
+    let mut include_options = carve_rs::IncludeOptions::new()
+        .with_resolver(&resolver)
+        .with_source_path(source_real.to_string_lossy());
+    if let Some(value) = max_depth {
+        include_options = include_options.with_max_depth(value);
+    }
+    if let Some(value) = max_bytes {
+        include_options = include_options.with_max_bytes(value);
+    }
+    if let Some(value) = max_resolver_calls {
+        include_options = include_options.with_max_resolver_calls(value);
+    }
+    if let Some(value) = max_warnings {
+        include_options = include_options.with_max_warnings(value);
+    }
+
+    let target_is_html = which == IncludeTarget::Html;
+    let prepared = carve_rs::prepare_doc_with_includes(
+        &source,
+        &render_options,
+        &include_options,
+        // Every target but HTML is inherently static, so it prepares under the
+        // interactive mode the other renderers assume.
+        if target_is_html {
+            render_options.mode
+        } else {
+            Mode::Interactive
+        },
+        target_is_html,
+    )
+    .map_err(|error| Error::new(ruby.exception_arg_error(), error.to_string()))?;
+    let rendered = match which {
+        IncludeTarget::Html => carve_rs::render_html_with_options(&prepared.doc, &render_options),
+        IncludeTarget::Markdown => {
+            carve_rs::render_markdown_with_options(&prepared.doc, &render_options)
+        }
+        IncludeTarget::Plain => {
+            carve_rs::render_plain_text_with_options(&prepared.doc, &render_options)
+        }
+        IncludeTarget::Ansi => carve_rs::render_ansi_with_options(&prepared.doc, &render_options),
+        // The AST is published as a tree, not as a string, so a caller does not
+        // parse JSON twice. Positions stay OFF, unlike `to_ast_json`: spec I4
+        // leaves position remapping out of scope in every engine, so a child's
+        // spans would point into a document the caller never passed.
+        IncludeTarget::Ast => Ok(carve_rs::to_json(&prepared.doc)),
+    }
+    .map_err(|error| Error::new(ruby.exception_runtime_error(), error.to_string()))?;
+    let value: serde_json::Value = if which == IncludeTarget::Ast {
+        serde_json::from_str(&rendered).map_err(|error| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("the engine's AST JSON did not parse: {error}"),
+            )
+        })?
+    } else {
+        serde_json::Value::String(rendered)
+    };
+    let safe_path = |value: &str| {
+        let path = PathBuf::from(value);
+        if path.is_absolute() {
+            path.strip_prefix(&root_real)
+                .map(|relative| relative.to_string_lossy().replace('\\', "/"))
+                .unwrap_or_else(|_| "[outside-root]".to_string())
+        } else {
+            value.to_string()
+        }
+    };
+    let warnings = prepared
+        .warnings
+        .iter()
+        .map(|warning| {
+            serde_json::json!({
+                "rule": warning.rule,
+                "message": warning.message,
+                "file": warning.file.as_deref().map(&safe_path),
+            })
+        })
+        .collect::<Vec<_>>();
+    let dependencies = prepared
+        .dependencies
+        .iter()
+        .map(|dependency| {
+            serde_json::json!({
+                "path": safe_path(&dependency.id),
+                "resolved": dependency.resolved,
+                "denial": dependency.denial.map(|denial| denial.as_str()),
+            })
+        })
+        .collect::<Vec<_>>();
+    Ok(serde_json::json!({
+        "value": value,
+        "warnings": warnings,
+        "dependencies": dependencies,
+        "suppressedWarnings": prepared.suppressed_warnings,
+    })
+    .to_string())
+}
+
 fn from_html_json(ruby: &Ruby, source: String, mode: String) -> Result<String, Error> {
     let mode = carve_rs::HtmlImportMode::from_name(&mode).ok_or_else(|| {
         Error::new(
@@ -222,7 +435,7 @@ fn from_html_json(ruby: &Ruby, source: String, mode: String) -> Result<String, E
             "mode must be safe, semantic, or roundtrip".to_string(),
         )
     })?;
-    let result = carve_rs::html_to_carve(
+    let result = carve_rs::migrate_html(
         &source,
         &carve_rs::HtmlImportOptions {
             mode,
@@ -239,31 +452,44 @@ fn from_html_json(ruby: &Ruby, source: String, mode: String) -> Result<String, E
         .report
         .diagnostics
         .iter()
-        .map(|diagnostic| {
-            let mut value = serde_json::json!({
-                "code": diagnostic.code.as_str(),
-                "message": diagnostic.message,
-                "severity": diagnostic.severity.as_str(),
-            });
-            if let Some(path) = &diagnostic.path {
-                value["path"] = serde_json::json!(path);
-            }
-            value
-        })
+        .map(migration_diagnostic_json)
         .collect::<Vec<_>>();
     Ok(serde_json::json!({
         "value": result.value,
         "report": {
-            "mode": result.report.mode.as_str(),
-            "adapter": result.report.adapter.as_str(),
+            "schemaVersion": result.report.schema_version,
+            "sourceFormat": result.report.source_format.as_str(),
+            "mode": result.report.mode.map(|value| value.as_str()),
+            "adapter": result.report.adapter.map(|value| value.as_str()),
             "diagnostics": diagnostics,
         }
     })
     .to_string())
 }
 
-fn from_markdown(source: String) -> String {
-    carve_rs::markdown_to_carve(&source)
+fn from_markdown_json(source: String) -> String {
+    let result = carve_rs::migrate_markdown(&source);
+    let diagnostics = result
+        .report
+        .diagnostics
+        .iter()
+        .map(migration_diagnostic_json)
+        .collect::<Vec<_>>();
+    serde_json::json!({"value": result.value, "report": {"schemaVersion": result.report.schema_version, "sourceFormat": result.report.source_format.as_str(), "diagnostics": diagnostics}}).to_string()
+}
+
+fn migration_diagnostic_json(diagnostic: &carve_rs::MigrationDiagnostic) -> serde_json::Value {
+    let mut value = serde_json::json!({
+        "code": diagnostic.code,
+        "message": diagnostic.message,
+        "severity": diagnostic.severity.as_str(),
+        "fidelity": diagnostic.fidelity.as_str(),
+        "confidence": diagnostic.confidence.as_str(),
+    });
+    if let Some(path) = &diagnostic.path {
+        value["path"] = serde_json::json!(path);
+    }
+    value
 }
 
 /// Parse Carve source and return its AST as a JSON string.
@@ -523,8 +749,12 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     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(
+        "_render_with_includes_json",
+        function!(render_with_includes_json, 15),
+    )?;
     module.define_singleton_method("_from_html_json", function!(from_html_json, 2))?;
-    module.define_singleton_method("_from_markdown", function!(from_markdown, 1))?;
+    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(
         "to_html_with_extensions",

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.3"
+  VERSION = "0.1.4"
 end

data/lib/carve.rb

@@ -42,6 +42,94 @@ module Carve
   RENDERER_KEYS = %i[mermaid chart graphviz math].freeze
 
   class << self
+    # Render +source+ to HTML with its <tt>{{ path }}</tt> includes expanded,
+    # contained to +root:+.
+    #
+    #   Carve.to_html_with_includes(File.read(page), root: "/srv/site",
+    #                               source_path: page, symbols: {smile: "\u{1F604}"})
+    #
+    # +root:+ and +source_path:+ are absolute, and the source file lives inside
+    # the root. A relative value raises ArgumentError rather than rooting
+    # containment at the process working directory, which is arbitrary with
+    # respect to the document.
+    #
+    # Returns +{value:, warnings:, dependencies:, suppressedWarnings:}+. Paths
+    # in +warnings+ and +dependencies+ are relative to the root, so a report can
+    # be shown to a reader as it stands.
+    #
+    # Every render option +to_html+ takes is accepted and reaches the included
+    # children too: an extension, a symbol map or a profile means the same thing
+    # in a child as in the parent.
+    def to_html_with_includes(source, root:, source_path:, extensions: nil, mode: nil,
+                              renderers: nil, symbols: nil, safe: false, profile: nil,
+                              sections: true, max_depth: nil, max_bytes: nil,
+                              max_resolver_calls: nil, max_warnings: nil)
+      render_with_includes(
+        source, target: "html", root: root, source_path: source_path,
+        extensions: extensions, mode: mode, renderers: renderers, symbols: symbols,
+        safe: safe, profile: profile, sections: sections, max_depth: max_depth,
+        max_bytes: max_bytes, max_resolver_calls: max_resolver_calls,
+        max_warnings: max_warnings
+      )
+    end
+
+    # The expanded document as an AST, in the shape +.parse+ returns.
+    #
+    #   Carve.parse_with_includes(File.read(page), root: root, source_path: page)
+    #   # => {value: {type: "document", ...}, warnings: [], dependencies: [...], ...}
+    #
+    # For a host that walks the tree rather than rendering HTML - carve-hexapdf
+    # draws its PDF from this shape.
+    #
+    # Nodes carry NO +:pos+, unlike +.parse+. Spec I4 leaves position remapping
+    # out of scope in every engine, so a span on an included node would name an
+    # offset in a document the caller never passed.
+    def parse_with_includes(source, root:, source_path:, extensions: nil, profile: nil,
+                            max_depth: nil, max_bytes: nil, max_resolver_calls: nil,
+                            max_warnings: nil)
+      render_with_includes(
+        source, target: "ast", root: root, source_path: source_path,
+        extensions: extensions, profile: profile, max_depth: max_depth,
+        max_bytes: max_bytes, max_resolver_calls: max_resolver_calls,
+        max_warnings: max_warnings
+      )
+    end
+
+    # The include pass over any render target: +"html"+, +"markdown"+,
+    # +"plain"+, +"ansi"+ or +"ast"+.
+    #
+    # There is no +"carve"+ target. Spec I15 excludes the Carve writer from
+    # expansion, because inlining a child into the formatter's output rewrites
+    # the author's document rather than formatting it.
+    def render_with_includes(source, root:, source_path:, target: "html", extensions: nil,
+                             mode: nil, renderers: nil, symbols: nil, safe: false,
+                             profile: nil, sections: true, max_depth: nil, max_bytes: nil,
+                             max_resolver_calls: nil, max_warnings: nil)
+      JSON.parse(
+        _render_with_includes_json(
+          source.to_s,
+          root.to_s,
+          source_path.to_s,
+          target.to_s,
+          Array(extensions).map(&:to_s),
+          (mode || :interactive).to_s,
+          renderers || {},
+          symbols || {},
+          !!safe,
+          profile&.to_s,
+          !!sections,
+          max_depth,
+          max_bytes,
+          max_resolver_calls,
+          max_warnings,
+        ),
+        symbolize_names: true,
+        # The engine bounds nesting itself, above Ruby JSON's default of 100, so
+        # a legal document would otherwise raise here. Same reason as .parse.
+        max_nesting: false,
+      )
+    end
+
     # Import HTML or Markdown into canonical Carve. Both methods return the
     # shared migration shape `{ value:, report: }`.
     def from_html(source, mode: :safe)
@@ -49,10 +137,10 @@ module Carve
     end
 
     def from_markdown(source)
-      {
-        value: _from_markdown(source),
-        report: { source_format: "markdown", diagnostics: [] }
-      }
+      result = JSON.parse(_from_markdown_json(source), symbolize_names: true)
+      # Keep the 0.1.x spelling while exposing the shared cross-language key.
+      result[:report][:source_format] = result[:report][:sourceFormat]
+      result
     end
 
     # Render Carve +source+ to an HTML string.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: carve-lang
 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-09-08 00:00:00.000000000 Z
+date: 2026-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys