carve-lang 0.1.10 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d4e85e4ab93621b11f1502ca546d64cc0d46e513e4074e6e4014cec8f5aee04
-  data.tar.gz: 3100558ccb654d5c2441358ce8a13ba363db7937e0e979be3944780322b62561
+  metadata.gz: cd1a19b5989abf287804723f52ff9b4f6ab7098be2d7a6f893caffa7e9ca4f26
+  data.tar.gz: 1c503d1890015fd5f129d8464405a6f66a594517026abbf588474fec96ad8e5e
 SHA512:
-  metadata.gz: db44ca3900ce90483edd037944efa79adf6c55a921afe8b00b00a31ba687d6f0f5fce97efba6ec3fb67e69f3c931544bd6b0e09169d62e9a8549b99e0836c693
-  data.tar.gz: 28dbc892917d7fb9074005e71cff53fe603bc25ca4d3a54add3042be7813aa4bed7e2db0eea5b950b1a5e2c416de9d9588c38ac7f8985cb90aa126f482d17c86
+  metadata.gz: 80e49b48040288e254718b55f452a0f0d8a3beab8246a7e50f4f8fb3db50d65597453389a0fcbbdb1610a54f99f51c2659da63b7a60482f700c82fe522b92642
+  data.tar.gz: 03e5140ca7a00cc0e71c5ca0db95cfabfd223cb15d77cfb456373f8538948c6ba6b12e882d0f81843d466b369a4b13fc64ae9cdd19e1fd59ed22ef9b2deac857

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.11] - 2026-10-23
+
+### Improvements
+
+- `Carve.lint(source, extensions:)` exposes the engine's linter: findings carry
+  the rule id, message, 1-based line and column, and character offsets. With
+  `root:` and `source_path:` it lints included files and reports each finding's
+  file and `includedBy` chain (#223).
+
 ## [0.1.10] - 2026-10-23
 
 ### Breaking
@@ -527,7 +536,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.10...HEAD
+[Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.11...HEAD
+[0.1.11]: https://github.com/markup-carve/carve-rb/compare/v0.1.10...v0.1.11
 [0.1.10]: https://github.com/markup-carve/carve-rb/compare/v0.1.9...v0.1.10
 [0.1.9]: https://github.com/markup-carve/carve-rb/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/markup-carve/carve-rb/compare/v0.1.7...v0.1.8

data/README.md

@@ -140,6 +140,21 @@ Other render methods leave directives literal. See the
 [include reference](docs/reference.md#file-includes) for budgets, AST expansion,
 targets, and containment behavior.
 
+## Lint
+
+`Carve.lint(source)` reports constructs that render but lose what the author
+wrote, such as an unattached attribute or a link to a missing id:
+
+```ruby
+Carve.lint("é [x](#nope)\n").map { |f| [f[:rule], f[:line], f[:column]] }
+# => [["broken-fragment-link", 1, 3]]
+```
+
+Columns and the `:start`/`:end` offsets count characters, not bytes. Pass
+`root:` and `source_path:` to lint included files too; each such finding names
+its file and the `:includedBy` chain. See the
+[lint reference](docs/reference.md#linting).
+
 ## Security
 
 Use `safe: true` and a restrictive profile for untrusted documents. Custom

data/ext/carve/Cargo.lock

@@ -54,7 +54,7 @@ dependencies = [
 
 [[package]]
 name = "carve-rb"
-version = "0.1.10"
+version = "0.1.11"
 dependencies = [
  "carve-lang",
  "magnus",

data/ext/carve/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "carve-rb"
-version = "0.1.10"
+version = "0.1.11"
 edition = "2021"
 rust-version = "1.75"
 publish = false

data/ext/carve/src/lib.rs

@@ -297,28 +297,16 @@ fn parse_include_target(ruby: &Ruby, name: &str) -> Result<IncludeTarget, Error>
     }
 }
 
-#[allow(clippy::too_many_arguments)]
-fn render_with_includes_json(
+/// Canonicalize an include root and the document's own path, and refuse a
+/// document outside the root. Both must be absolute: a relative one would root
+/// containment at the process working directory.
+fn contained_include_paths(
     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);
+    root: &str,
+    source_path: &str,
+) -> Result<(PathBuf, PathBuf), Error> {
+    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(),
@@ -343,6 +331,42 @@ fn render_with_includes_json(
             "include source_path must be a file inside the include root".to_string(),
         ));
     }
+    Ok((root_real, source_real))
+}
+
+/// A path as a reader sees it: relative to the include root.
+fn root_relative(root_real: &Path, value: &str) -> String {
+    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()
+    }
+}
+
+#[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_real, source_real) = contained_include_paths(ruby, &root, &source_path)?;
 
     let resolver = carve_rs::FileSystemResolver::new(&root_real).map_err(|_| {
         Error::new(
@@ -443,16 +467,7 @@ fn render_with_includes_json(
     } 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 safe_path = |value: &str| root_relative(&root_real, value);
     let warnings = prepared
         .warnings
         .iter()
@@ -495,6 +510,122 @@ fn render_with_includes_json(
     .to_string())
 }
 
+/// Byte offset -> codepoint offset over `source`.
+///
+/// `LintWarning` reports `start`/`end` in bytes so a Rust caller can slice its
+/// `&str`; a Ruby String indexes by character, so a byte offset would mis-slice
+/// every document with a non-ASCII character before the finding. A byte inside a
+/// character maps to that character, and the final slot is the total.
+fn codepoint_table(source: &str) -> Vec<usize> {
+    let mut table = Vec::with_capacity(source.len() + 1);
+    let mut count = 0usize;
+    for ch in source.chars() {
+        for _ in 0..ch.len_utf8() {
+            table.push(count);
+        }
+        count += 1;
+    }
+    table.push(count);
+    table
+}
+
+#[allow(clippy::too_many_arguments)]
+fn lint_json(
+    ruby: &Ruby,
+    source: String,
+    names: RArray,
+    root: Option<String>,
+    source_path: Option<String>,
+    max_depth: Option<usize>,
+    max_bytes: Option<usize>,
+    max_resolver_calls: Option<usize>,
+    max_warnings: Option<usize>,
+) -> Result<String, Error> {
+    let boxed = boxed_extensions(ruby, names)?;
+    let mut options = Options::new();
+    for extension in &boxed {
+        options = options.with_extension(extension.as_ref());
+    }
+    // The document's own findings come first in `lint_carve_with_options`, and
+    // they are the only ones whose offsets index `source`. Linting it alone
+    // first tells the two apart without guessing from a finding's fields.
+    let own = carve_rs::lint_carve_with_options(&source, &options);
+    let own_count = own.len();
+    let (warnings, root_real) = match (root, source_path) {
+        (None, None) => (own, None),
+        (Some(root), Some(source_path)) => {
+            let (root_real, source_real) = contained_include_paths(ruby, &root, &source_path)?;
+            let resolver = carve_rs::FileSystemResolver::new(&root_real).map_err(|_| {
+                Error::new(
+                    ruby.exception_arg_error(),
+                    "include root is not usable".to_string(),
+                )
+            })?;
+            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 options = options.with_lint_includes(include_options);
+            (
+                carve_rs::lint_carve_with_options(&source, &options),
+                Some(root_real),
+            )
+        }
+        _ => {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "lint needs both root: and source_path: to follow includes".to_string(),
+            ))
+        }
+    };
+    let table = codepoint_table(&source);
+    let total = table.len() - 1;
+    let to_codepoint = |byte: usize| table.get(byte).copied().unwrap_or(total);
+    let path = |value: &str| match &root_real {
+        Some(root_real) => root_relative(root_real, value),
+        None => value.to_string(),
+    };
+    let findings = warnings
+        .iter()
+        .enumerate()
+        .map(|(index, warning)| {
+            let own = index < own_count;
+            serde_json::json!({
+                "rule": warning.rule,
+                "message": warning.message,
+                "line": warning.line,
+                "column": warning.column,
+                "start": own.then(|| to_codepoint(warning.start)),
+                "end": own.then(|| to_codepoint(warning.end)),
+                "file": warning.file.as_deref().map(&path),
+                "includedBy": warning
+                    .included_by
+                    .iter()
+                    .map(|site| {
+                        serde_json::json!({
+                            "file": path(&site.file),
+                            "line": site.line,
+                            "column": site.column,
+                        })
+                    })
+                    .collect::<Vec<_>>(),
+            })
+        })
+        .collect::<Vec<_>>();
+    Ok(serde_json::Value::Array(findings).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(
@@ -1024,6 +1155,20 @@ guarded!(
     ) -> String =>? render_with_includes_json
 );
 
+guarded!(
+    g_lint_json(
+        ruby: &Ruby,
+        source: Source,
+        names: RArray,
+        root: Option<String>,
+        source_path: Option<String>,
+        max_depth: Option<usize>,
+        max_bytes: Option<usize>,
+        max_resolver_calls: Option<usize>,
+        max_warnings: Option<usize>
+    ) -> String =>? lint_json
+);
+
 /// Entry point invoked by Ruby when the extension is loaded.
 ///
 /// `name = "carve"` makes the macro emit the `Init_carve` symbol that matches
@@ -1073,5 +1218,6 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     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))?;
+    module.define_singleton_method("_lint_json", function!(g_lint_json, 8))?;
     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.10"
+  VERSION = "0.1.11"
 end

data/lib/carve.rb

@@ -150,6 +150,55 @@ module Carve
       )
     end
 
+    # Report constructs that parse and render, but not the way the author
+    # meant: an attribute that attaches to nothing, an unclosed fence, a
+    # fragment link with no target.
+    #
+    #   Carve.lint("Text.\n\n{#gone}\n")
+    #   # => [{rule: "unattached-block-attribute", message: "...", line: 3,
+    #   #      column: 1, start: 7, end: 14, file: nil, includedBy: []}]
+    #
+    # Returns an Array of Hashes, empty for a clean document:
+    #
+    # * +:rule+ - the engine's stable rule id, the same in every Carve engine.
+    # * +:message+ - what degrades, in prose.
+    # * +:line+, +:column+ - 1-based; the column counts characters, not bytes.
+    # * +:start+, +:end+ - 0-based character offsets into +source+, end
+    #   exclusive, so <tt>source[f[:start]...f[:end]]</tt> is the offending text.
+    #   +nil+ on a finding the include pass adds (below), whose offsets would
+    #   index another text.
+    # * +:file+, +:includedBy+ - see below; +nil+ and +[]+ without includes.
+    #
+    # The engine reports no severity: every finding is a warning.
+    #
+    # Pass the same +extensions:+ you render with, since they change which
+    # constructs are elements and which rules apply.
+    #
+    # ==== Following includes
+    #
+    # With +root:+ and +source_path:+ (absolute, as for .to_html_with_includes)
+    # the pass also lints every included Carve file and reports include
+    # directives that stay literal (a missing target, a cycle, a budget). Such a
+    # finding names its +:file+ relative to the root and its +:includedBy+ chain,
+    # top-level first, as +{file:, line:, column:}+. The budgets
+    # (+max_depth:+ and the rest) mean what they mean for rendering.
+    def lint(source, extensions: nil, root: nil, source_path: nil, max_depth: nil,
+             max_bytes: nil, max_resolver_calls: nil, max_warnings: nil)
+      JSON.parse(
+        _lint_json(
+          source.to_s,
+          Array(extensions).map(&:to_s),
+          root&.to_s,
+          source_path&.to_s,
+          max_depth,
+          max_bytes,
+          max_resolver_calls,
+          max_warnings,
+        ),
+        symbolize_names: true,
+      )
+    end
+
     # Format +source+ into canonical Carve. A writer refusal returns the source
     # as authored. +align_tables:+ pads table cells into aligned columns.
     def to_carve(source, align_tables: false)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carve-lang
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.11
 platform: ruby
 authors:
 - markup-carve