sasso 0.2.7 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa5247a26666129d493b49655b25a696b6d3edb691ca67778ebaf5d7959ddc40
-  data.tar.gz: df82268c67577ff6fd41c7bc82291f614b603988f25c753ca3d82cdad4cf4a6c
+  metadata.gz: 48e0d49603b5fa0b739a8f52c44b52b6dffdf7ead5561fab036584829f0c5b57
+  data.tar.gz: 5dc5d4d1d8dab9d7202465f73a989e9e4cb6aed5b25811d5d090b3e100edf575
 SHA512:
-  metadata.gz: ba8e537045e3e0b587d706065d7872e0ee08ec06b89ecb25e7c5c6af6ebfebb8d73b0febab955b132c8997f2a2f2b41c20aadd374bb03dc36dd15c0a7ae89d90
-  data.tar.gz: ad75f75e99813a3bf68e76431ab4c38cfb36dec4b8104b46d9ce4f4524cda03603c3c893f0d3ebd40a70d1470a6a56b2ecd110aa9bfefae07450d9e08722cef7
+  metadata.gz: 5a5fc9a1351d5b31b705c9763ca0c5bf4981d5c56782f949099a1228e14be24fc8aef56866c3cad7624655883dda2383eb792376b864aab3d359cd56eba5cc47
+  data.tar.gz: f6b9ae0fd2f91181439c7bfda2002aeb4845a6219ab41055cffe8a5ac41a02d54d3ed30d0fad54fe2e6311b55c7ab77ff4fd0151b3a1f41a0e13f90a498375e0

data/CHANGELOG.md

@@ -3,11 +3,112 @@
 All notable changes to the **sasso** Ruby gem are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-The gem version floats independently of the `sasso` compiler crate; each release
-notes the exact core crate version it pins.
+Since 0.14.0 the gem version tracks the `sasso` compiler crate it bundles; each
+release notes the exact core crate version it pins. Releases up to 0.2.7 versioned
+the gem independently of the crate.
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-09-17
+
+_The gem version now tracks the core compiler's. It jumps 0.2.7 → 0.14.0 to meet
+`sasso` 0.14.0, adopting seven core releases at once (0.7.0 through 0.14.0)._
+
+_**Why align.** The gem version floated independently, so "sasso 0.2.7" said
+nothing about which compiler it carried: the three framework gems each had to
+document the mapping, and a bug report needed both numbers to be actionable.
+From here, a gem release adopting core X.Y.Z **is** gem X.Y.Z. A gem-only fix
+takes the next patch, so the gem may sit ahead of the crate within a minor —
+the new `Sasso::CORE_VERSION` always reports what is actually linked._
+
+_The Ruby API is backward compatible; the CSS the compiler emits is not, in the
+ways listed below._
+
+### Removed
+
+- **Ruby 3.1 support** (`required_ruby_version` is now `>= 3.2.0`). It left
+  security maintenance in March 2025, and is off the precompiled-gem matrix.
+
+### Changed (output — dart-sass 1.101.4 → 1.104.1 alignment)
+
+The gem's Ruby API is unchanged, but the CSS it emits moved with the core. If
+you byte-compare output — snapshot tests, asset digests, build caches — expect
+diffs. The CSS is equivalent; only its spelling changed.
+
+- **Global `whiteness()` / `blackness()` are no longer built-ins** (core 0.9.0):
+  they are `sass:color`-only, so the bare call is now an unknown function and
+  passes through as plain CSS instead of being evaluated. `whiteness(#f00)` goes
+  from `0%` to `whiteness(#f00)`, and `1 + whiteness(#f00)` to `1whiteness(#f00)`
+  — both byte-identical to dart-sass 1.104.1, and both **silent**: no error, no
+  warning. This is the change in this release to grep your stylesheets for. Use
+  `color.whiteness()` / `color.blackness()` via `@use "sass:color"`.
+- A legacy color with any fractional channel writes its rgb triple as
+  **percentages**: `rgb(127.5, 0, 127.5)` becomes `rgb(50%, 0%, 50%)` (0.9.0).
+- **Compressed hsl/hwb route through rgb** like every other legacy space, so
+  `darken(#336699, 10%)` compresses to `rgb(15%,30%,45%)` rather than
+  `hsl(210,50%,30%)` (0.9.0).
+- **A negative zero keeps its sign**: `0 * -1`, `-0` and `math.div(0, -1)`
+  serialize as `-0`. The sign is the IEEE sign bit, so `0 - 0` stays `0` (0.10.0).
+- **Colors convert their degenerate channels**: a `NaN` channel becomes `0`, and
+  a polar hue converts every non-finite value (0.10.0).
+- **`rec2020` uses the pure 2.4 gamma transfer function**, replacing the BT.2020
+  piecewise curve (0.9.0).
+- **Plain-CSS `if()` emits in CSS serialization format**, not `meta.inspect`
+  format: lists lose their parens, `null` serializes to nothing (0.9.0).
+- **A comment before `@use` is emitted exactly once**; a repeat edge into an
+  already-loaded module no longer re-emits it (0.10.0).
+- Extensive **`@extend`, module-system and selector line-break fidelity** fixes
+  (0.7.0, 0.8.0) — the work that took all 20 projects in the core's real-world
+  corpus to byte-identical with dart-sass.
+
+### Changed (source maps)
+
+- **A declaration whose value is a bare `$name` maps back to the variable's
+  definition**, transitively through `$b: $a` chains, module members and
+  mixin/function parameters (0.9.0). The segment used to be omitted, which also
+  renumbered every following delta-encoded segment — so a recorded `mappings`
+  string changes.
+
+### Changed (diagnostics)
+
+- **Function arity errors follow dart's wording**: only positional arguments
+  count, and the word "positional" appears once any named argument is in play
+  (0.10.0).
+- **An error inside a loaded file is attributed to that file**, with one stack
+  frame per loader, for `@use`, `@forward` and `@import` chains alike (0.7.0).
+
+### Added
+
+- **`charset:`** (dart-sass `charset`) — `false` omits the `@charset "UTF-8";`
+  prefix, or the U+FEFF BOM when compressed, that non-ASCII output carries.
+- **`quiet:`** — print no `@warn`/`@debug`/deprecation diagnostics. They have
+  always gone to `$stderr`; there was previously no way off.
+- **`quiet_deps:`** (dart-sass `quietDeps`) — drop deprecation warnings raised
+  inside dependencies (files resolved through a load path), while the entry
+  stylesheet's own still print. `@warn` is untouched either way.
+- **`on_warn:`** — a callable receiving each diagnostic as a Hash of the new
+  `Sasso::WARNING_KEYS`, which replaces the stderr printing rather than
+  duplicating it. `:formatted` carries the full dart-style block, so the
+  compiler's own rendering can go straight into an application logger.
+  Mutually exclusive with `quiet:`. A compile that warns and then fails delivers
+  its warnings before raising `Sasso::CompileError`, the way dart-sass hands them
+  to its logger before throwing.
+- **`Sasso::CORE_VERSION`** — the bundled compiler crate's version, read from
+  the linked binary so it cannot drift from what is loaded.
+
+### Documentation
+
+- The README documents **`source_map:` and `CompileResult` for the first time**;
+  they shipped in gem 0.2.0 and never reached it. `sig/sasso.rbs` gains them too,
+  alongside the new options.
+- The **Performance table is remeasured**: this working tree (core 0.14.0)
+  against `sass-embedded` 1.104.1 and `sassc` 2.4.0. The ~180-rule case is ~10%
+  faster. The cold-start row is **corrected upward**, from a claimed 1.1 ms to a
+  measured 3.2 ms — that figure reproduced on neither the old gem nor the new, so
+  it predates this release; the margin over `sass-embedded` is 12.7×, not 35×.
+- `benchmark/Gemfile` takes **`SASSO_PATH`** to benchmark a working tree instead
+  of the published gem, which is what the README's table now reports.
+
 ## [0.2.7] - 2026-06-25
 
 ### Changed

data/Cargo.lock

@@ -239,14 +239,14 @@ dependencies = [
  "magnus",
  "rb-sys",
  "rb-sys-env",
- "sasso 0.6.3",
+ "sasso 0.14.0",
 ]
 
 [[package]]
 name = "sasso"
-version = "0.6.3"
+version = "0.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4bcc15ed0914f0ad1a1ed01b1aa236511eada9f911d5ab80cdd17dcf233d9a95"
+checksum = "f6ae98548b2e9447aca2340b1c082c82d06721586708b808c52e2f908499c2f8"
 
 [[package]]
 name = "seq-macro"

data/README.md

@@ -6,7 +6,7 @@ In-process **SCSS / Sass → CSS** compilation for Ruby, backed by [**sasso**](h
 
 > This gem is the Ruby binding. The compiler core lives in the separate
 > [`momiji-rs/sasso`](https://github.com/momiji-rs/sasso) repo (crate on
-> crates.io); this gem pins it exactly and releases on its own cadence.
+> crates.io); this gem pins it exactly and carries its version number.
 
 ## Install
 
@@ -52,6 +52,78 @@ Sasso.compile("app/assets/stylesheets/application.scss",
 | `load_paths:` | `[]` | directories searched for `@use`/`@forward`/`@import` |
 | `url:` | `nil` | filename shown in diagnostics (enables the rich dart-style error block) |
 | `alert_ascii:` | `false` | ASCII-only diagnostics |
+| `charset:` | `true` | prefix non-ASCII output with `@charset "UTF-8";` (a BOM when compressed) |
+| `source_map:` | `false` | return a `Sasso::CompileResult` instead of a String |
+| `source_map_include_sources:` | `false` | embed each source's text in the map's `sourcesContent` |
+| `quiet:` | `false` | print no `@warn`/`@debug`/deprecation diagnostics |
+| `quiet_deps:` | `false` | drop deprecation warnings raised inside dependencies |
+| `on_warn:` | `nil` | a callable receiving each diagnostic; replaces the stderr printing |
+
+### Source maps
+
+With `source_map: true` the return value is a `Sasso::CompileResult` — `#css` is
+the same String you would get otherwise, and `#source_map` is a parsed Source Map
+v3 Hash. Pass `url:` so the map can name the entry stylesheet.
+
+```ruby
+r = Sasso.compile_string(scss, source_map: true, url: "application.scss")
+r.css                     # => "a {\n  color: red;\n}"
+r.source_map["version"]   # => 3
+r.source_map["sources"]   # => ["application.scss"]
+```
+
+### Diagnostics
+
+`@warn`, `@debug` and deprecation warnings print to `$stderr` by default, the
+same dart-style block the `sasso` CLI and dart-sass print. Two ways to change
+that:
+
+```ruby
+# Silence them entirely:
+Sasso.compile_string(scss, quiet: true)
+
+# Silence only what dependencies deprecate (dart-sass `quietDeps`) — files
+# resolved through a load path. The entry stylesheet's own still print.
+Sasso.compile_string(scss, load_paths: ["vendor/stylesheets"], quiet_deps: true)
+
+# Or take delivery yourself, which suppresses the printing:
+Sasso.compile_string(scss, url: "in.scss", on_warn: ->(d) {
+  next if d[:deprecation_id] == "color-functions"
+
+  Rails.logger.warn(d[:formatted])   # the block the compiler would have printed
+})
+```
+
+Each diagnostic is a Hash of `Sasso::WARNING_KEYS`: `:kind` (`:warn`/`:debug`),
+`:deprecation`, `:deprecation_id`, `:message`, `:formatted`, `:url`, `:line` and
+`:path`. `:url` is dart's display form of the file; `:path` identifies it (the
+importer's canonical path), which is what distinguishes a dependency from the
+entry stylesheet. `quiet:` and `on_warn:` are mutually exclusive.
+
+Two things to know about what `on_warn:` receives:
+
+- A compile that warns and then **fails** delivers its warnings first and raises
+  `Sasso::CompileError` after, so a diagnostic is never lost to the error — the
+  callable is the only thing reporting them once it has taken over. If the
+  callable itself raises, the `CompileError` still wins and carries that
+  exception as its `#cause`.
+- Like dart-sass, the compiler **caps a repeated deprecation at five per id** and
+  then emits one summary diagnostic — `"N repetitive deprecation warnings
+  omitted."` — with no `:deprecation_id`, no `:url` and `:line` of `0`. Code that
+  keys on the id or formats `"#{d[:url]}:#{d[:line]}"` should expect it. There is
+  no verbose mode that lifts the cap; the compiler core does not offer one.
+
+### Versions
+
+Since 0.14.0 the gem version tracks the core compiler crate it bundles: gem
+0.14.0 pins crate 0.14.0. A gem-only fix takes the next patch, so `Sasso::VERSION`
+may sit ahead of the crate within a minor — `Sasso::CORE_VERSION` reads the
+version out of the linked binary and is the authority on what is loaded.
+
+```ruby
+Sasso::VERSION       # => "0.14.0"  the gem
+Sasso::CORE_VERSION  # => "0.14.0"  the compiler actually linked in
+```
 
 ### Errors
 
@@ -92,20 +164,20 @@ IPC, no Dart VM), it avoids the per-call protocol roundtrip of `sass-embedded`
 and the process-spawn cost paid by any out-of-process compiler.
 
 Compiling the same SCSS (variables, nesting, `@for`, math) on an Apple M2 Max,
-Ruby 3.4.1:
+Ruby 3.4.1, against `sass-embedded` 1.104.1 and `sassc` 2.4.0:
 
 | | `sasso` (this gem) | `sass-embedded` (dart-sass) | `sassc` (libsass) |
 | --- | --: | --: | --: |
-| Warm — small component (256 B) | **13.5 µs** | 129 µs (**9.5×**) | 1151 µs (85×) |
-| Warm — ~180 rules (5.5 KB) | **237 µs** | 915 µs (**3.8×**) | 10178 µs (43×) |
-| Cold start (`require` + first compile) | **1.1 ms** | 38.5 ms (**35×**) | 35.6 ms (32×) |
+| Warm — small component (256 B) | **13.3 µs** | 125 µs (**9.4×**) | 1148 µs (87×) |
+| Warm — ~180 rules (5.5 KB) | **215 µs** | 906 µs (**4.2×**) | 10234 µs (48×) |
+| Cold start (`require` + first compile) | **3.2 ms** | 40.6 ms (**12.7×**) | 37.0 ms (12×) |
 
 Parenthesised values are how much slower the other gem is than `sasso`.
 
 - **Per-request compiling** (e.g. a Sinatra route): in-process latency is ~13 µs
-  vs ~129 µs for `sass-embedded`'s pipe roundtrip to its Dart subprocess.
+  vs ~125 µs for `sass-embedded`'s pipe roundtrip to its Dart subprocess.
 - **One-shot builds** (e.g. `rails assets:precompile`): the dominant cost is the
-  ~38 ms Dart subprocess spawn, which `sasso` does not pay (~1 ms cold).
+  ~41 ms Dart subprocess spawn, which `sasso` does not pay (~3 ms cold).
 
 The engine is also heavily perf-tuned (a scoped bump arena, reference-counted
 values). Numbers are representative of one machine; run your own with your

data/ext/sasso/Cargo.toml

@@ -1,7 +1,7 @@
 # The Ruby native-extension wrapper: a cdylib around `sasso::compile`, shipped
 # inside the `sasso` gem (NOT published to crates.io). Depends on the PUBLISHED
-# core crate via an exact pin — bump it deliberately to adopt a new core release
-# (the gem version floats independently; see lib/sasso/version.rb).
+# core crate via an exact pin — bump it deliberately to adopt a new core release,
+# and move the gem version to match (see lib/sasso/version.rb).
 [package]
 # Must equal the rake-compiler ExtensionTask name (rb_sys looks the package up
 # by this name). The core compiler is depended on under a RENAMED key
@@ -29,7 +29,7 @@ rb-sys = "0.9"
 # The published core compiler, pinned exactly to the API surface this binding
 # targets. Renamed to `sasso_core` so this package can be named `sasso` (a
 # package may not depend on a crate of its own name without a rename).
-sasso_core = { package = "sasso", version = "=0.6.3" }
+sasso_core = { package = "sasso", version = "=0.14.0" }
 
 [build-dependencies]
 rb-sys-env = "0.1"

data/ext/sasso/src/lib.rs

@@ -1,82 +1,117 @@
 //! Magnus binding around `sasso::compile`. Exposes a flat native ABI
-//! `Sasso::Native._compile(...)`; the ergonomic keyword API lives in
+//! `Sasso::Native._compile(source, opts)`; the ergonomic keyword API lives in
 //! `lib/sasso.rb`. The core crate is `unsafe`-free; this thin FFI layer is the
 //! `unsafe` boundary (magnus hides it — we write no explicit `unsafe`).
 //!
+//! Options travel in ONE hash rather than as positional arguments, so adopting
+//! a new compiler option costs a key here instead of an ABI arity change on
+//! both sides. `Sasso::Native` is a private ABI: `lib/sasso.rb` is its only
+//! caller and validates every value before it arrives.
+//!
 //! Importer policy (v1): a built-in Rust `FsImporter` driven by `load_paths`.
 //! A Ruby-callback importer is deferred (GC-pinning + GVL re-entrancy hazards).
 
-use magnus::{function, prelude::*, Error, ExceptionClass, RArray, RModule, Ruby};
+use magnus::{function, prelude::*, value::ReprValue, Error, RArray, RHash, Ruby, TryConvert};
 use sasso_core as sasso; // the core crate, renamed in Cargo.toml to free the `sasso` package name
+use std::cell::RefCell;
 use std::path::PathBuf;
+use std::rc::Rc;
 
-/// `Sasso::CompileError` (defined in lib/sasso.rb, loaded before this ext) for
-/// a rescuable raise; falls back to `RuntimeError` if the lookup ever fails.
-fn compile_error(ruby: &Ruby, msg: String) -> Error {
-    let klass = ruby
-        .class_object()
-        .const_get::<_, RModule>("Sasso")
-        .and_then(|m| m.const_get::<_, ExceptionClass>("CompileError"))
-        .unwrap_or_else(|_| ruby.exception_runtime_error());
-    Error::new(klass, msg)
+/// Read one option out of the hash. A missing key and an explicit `nil` read
+/// the same, so the Ruby wrapper can pass a key through unconditionally.
+fn opt<T: TryConvert>(ruby: &Ruby, opts: RHash, key: &str) -> Result<Option<T>, Error> {
+    match opts.get(ruby.sym_new(key)) {
+        Some(v) if !v.is_nil() => Ok(Some(T::try_convert(v)?)),
+        _ => Ok(None),
+    }
 }
 
-/// Flat native ABI. Args are pre-validated/normalized by the Ruby wrapper.
-/// Never panics across FFI — every failure is a raised Ruby exception.
-fn native_compile(
-    ruby: &Ruby,
-    source: String,
-    style: String,
-    syntax: String,
-    load_paths: RArray,
-    url: Option<String>,
-    unicode: bool,
-) -> Result<String, Error> {
-    let mut opts = sasso::Options::default()
-        .with_style(if style == "compressed" {
-            sasso::OutputStyle::Compressed
-        } else {
-            sasso::OutputStyle::Expanded
-        })
-        .with_syntax(match syntax.as_str() {
-            "sass" => sasso::Syntax::Sass,
-            "css" => sasso::Syntax::Css,
-            _ => sasso::Syntax::Scss,
-        })
-        .with_unicode(unicode);
+/// Read a boolean option, falling back to the core crate's own default.
+fn flag(ruby: &Ruby, opts: RHash, key: &str, default: bool) -> Result<bool, Error> {
+    Ok(opt::<bool>(ruby, opts, key)?.unwrap_or(default))
+}
 
-    // `url` is load-bearing: it ENABLES the byte-exact dart diagnostic block.
-    if let Some(ref u) = url {
-        opts = opts.with_url(u);
+/// Read `load_paths` as filesystem paths.
+fn load_paths(ruby: &Ruby, opts: RHash) -> Result<Vec<PathBuf>, Error> {
+    match opt::<RArray>(ruby, opts, "load_paths")? {
+        Some(a) => Ok(a
+            .to_vec::<String>()?
+            .into_iter()
+            .map(PathBuf::from)
+            .collect()),
+        None => Ok(Vec::new()),
     }
+}
 
-    let paths: Vec<PathBuf> = load_paths
-        .to_vec::<String>()?
-        .into_iter()
-        .map(PathBuf::from)
-        .collect();
-    // Bind the importer for the whole `compile` call (Options borrows it).
-    let importer = sasso::FsImporter::new(paths.clone());
-    if !paths.is_empty() {
-        opts = opts.with_importer(&importer);
+/// One `@warn` / `@debug` / deprecation diagnostic, copied out of the borrowed
+/// `WarnEvent` so it outlives the compile that produced it.
+///
+/// The handler runs DURING the compile, and calling back into Ruby from there
+/// would re-enter the VM mid-compile; instead every event is recorded here and
+/// handed to Ruby once `compile` has returned. That trades memory for safety: a
+/// compile raising N warnings holds N of these until it finishes, where the
+/// default stderr path streams them out and retains nothing. The core caps
+/// repeated deprecations at five per id, so in practice only `@warn`/`@debug` in
+/// a loop can grow the buffer without bound.
+struct Warning {
+    kind: &'static str,
+    deprecation: bool,
+    deprecation_id: String,
+    message: String,
+    formatted: String,
+    url: String,
+    line: usize,
+    path: String,
+}
+
+impl Warning {
+    fn record(event: &sasso::WarnEvent<'_>) -> Self {
+        Warning {
+            kind: match event.kind {
+                sasso::WarnKind::Debug => "debug",
+                sasso::WarnKind::Warn => "warn",
+            },
+            deprecation: event.deprecation,
+            deprecation_id: event.deprecation_id.to_owned(),
+            message: event.message.to_owned(),
+            formatted: event.formatted.to_owned(),
+            url: event.url.to_owned(),
+            line: event.line,
+            path: event.path.to_owned(),
+        }
     }
 
-    sasso::compile(&source, &opts).map_err(|e| compile_error(ruby, e.to_string()))
+    fn into_hash(self, ruby: &Ruby) -> Result<RHash, Error> {
+        let h = ruby.hash_new();
+        h.aset(ruby.sym_new("kind"), ruby.sym_new(self.kind))?;
+        h.aset(ruby.sym_new("deprecation"), self.deprecation)?;
+        h.aset(ruby.sym_new("deprecation_id"), self.deprecation_id)?;
+        h.aset(ruby.sym_new("message"), self.message)?;
+        h.aset(ruby.sym_new("formatted"), self.formatted)?;
+        h.aset(ruby.sym_new("url"), self.url)?;
+        h.aset(ruby.sym_new("line"), self.line)?;
+        h.aset(ruby.sym_new("path"), self.path)?;
+        Ok(h)
+    }
 }
 
-/// Source-map variant: returns `[css, source_map_json]` (a Ruby Array via the
-/// Rust tuple). `include_sources` populates the map's `sourcesContent`.
-fn native_compile_with_map(
-    ruby: &Ruby,
-    source: String,
-    style: String,
-    syntax: String,
-    load_paths: RArray,
-    url: Option<String>,
-    unicode: bool,
-    include_sources: bool,
-) -> Result<(String, String), Error> {
-    let mut opts = sasso::Options::default()
+/// Flat native ABI:
+/// `_compile(source, opts) -> [css, source_map_json, warnings, error]`.
+///
+/// A compile failure RETURNS its message in `error` rather than raising here,
+/// so the recorded warnings come back with it: `lib/sasso.rb` delivers them to
+/// `on_warn:` and then raises `Sasso::CompileError`. dart-sass's logger sees the
+/// warnings a failing compile raised too, and swallowing them would be worse
+/// than not forwarding them — under `on_warn:` nothing else prints them.
+/// Never panics across FFI — every other failure is a raised Ruby exception.
+fn native_compile(ruby: &Ruby, source: String, opts: RHash) -> Result<RArray, Error> {
+    let style = opt::<String>(ruby, opts, "style")?.unwrap_or_default();
+    let syntax = opt::<String>(ruby, opts, "syntax")?.unwrap_or_default();
+    let url = opt::<String>(ruby, opts, "url")?;
+    let paths = load_paths(ruby, opts)?;
+    let want_map = flag(ruby, opts, "source_map", false)?;
+
+    let mut copts = sasso::Options::default()
         .with_style(if style == "compressed" {
             sasso::OutputStyle::Compressed
         } else {
@@ -87,33 +122,97 @@ fn native_compile_with_map(
             "css" => sasso::Syntax::Css,
             _ => sasso::Syntax::Scss,
         })
-        .with_unicode(unicode)
-        .with_source_map_include_sources(include_sources);
+        .with_unicode(flag(ruby, opts, "unicode", true)?)
+        .with_source_map_include_sources(flag(ruby, opts, "source_map_include_sources", false)?)
+        .with_charset(flag(ruby, opts, "charset", true)?);
 
+    // `url` is load-bearing: it ENABLES the byte-exact dart diagnostic block.
     if let Some(ref u) = url {
-        opts = opts.with_url(u);
+        copts = copts.with_url(u);
+    }
+
+    // Bind the importer for the whole `compile` call (Options borrows it).
+    let has_paths = !paths.is_empty();
+    let importer = sasso::FsImporter::new(paths);
+    if has_paths {
+        copts = copts.with_importer(&importer);
     }
 
-    let paths: Vec<PathBuf> = load_paths
-        .to_vec::<String>()?
-        .into_iter()
-        .map(PathBuf::from)
-        .collect();
-    let importer = sasso::FsImporter::new(paths.clone());
-    if !paths.is_empty() {
-        opts = opts.with_importer(&importer);
+    // dart-sass `quietDeps`: classified by how a file was RESOLVED, so the set
+    // has to come from the importer that resolved it. Harmless with no load
+    // paths — nothing can be a dependency, so the set stays empty.
+    if flag(ruby, opts, "quiet_deps", false)? {
+        copts = copts.with_quiet_deps(importer.dependencies());
     }
 
-    let result =
-        sasso::compile_with_source_map(&source, &opts).map_err(|e| compile_error(ruby, e.to_string()))?;
-    Ok((result.css, result.source_map.to_json()))
+    // "stderr" leaves `Options::warn` unset, which is what makes the core print
+    // its own dart-style block — the default path installs no handler and pays
+    // nothing, not even the sink's allocation. Only "capture" allocates.
+    let mut captured: Option<Rc<RefCell<Vec<Warning>>>> = None;
+    match opt::<String>(ruby, opts, "warnings")?
+        .unwrap_or_default()
+        .as_str()
+    {
+        "silence" => copts = copts.with_warn_handler(Rc::new(|_| {})),
+        "capture" => {
+            let sink: Rc<RefCell<Vec<Warning>>> = Rc::new(RefCell::new(Vec::new()));
+            let handler = Rc::clone(&sink);
+            copts = copts.with_warn_handler(Rc::new(move |event: &sasso::WarnEvent<'_>| {
+                handler.borrow_mut().push(Warning::record(event));
+            }));
+            captured = Some(sink);
+        }
+        _ => {}
+    }
+
+    // One shape for both entry points: the map is None when it was not asked for.
+    let compiled = if want_map {
+        sasso::compile_with_source_map(&source, &copts)
+            .map(|result| (result.css, Some(result.source_map.to_json())))
+    } else {
+        sasso::compile(&source, &copts).map(|css| (css, None))
+    };
+
+    let out = ruby.ary_new_capa(4);
+    let error = match compiled {
+        Ok((css, map_json)) => {
+            out.push(css)?;
+            out.push(map_json)?;
+            None
+        }
+        // Report the failure as a value; `lib/sasso.rb` raises it, AFTER the
+        // warnings below have been delivered.
+        Err(e) => {
+            out.push(ruby.qnil())?;
+            out.push(ruby.qnil())?;
+            Some(e.to_string())
+        }
+    };
+
+    // Only ever non-empty under "capture".
+    let recorded = captured.map(|sink| sink.take()).unwrap_or_default();
+    let warnings = ruby.ary_new_capa(recorded.len());
+    for warning in recorded {
+        warnings.push(warning.into_hash(ruby)?)?;
+    }
+    out.push(warnings)?;
+    out.push(error)?;
+
+    Ok(out)
+}
+
+/// The bundled core compiler's version, read from the crate this extension is
+/// actually linked against. The core exposes `VERSION` (since 0.9.1) precisely
+/// so a binding cannot report a version that has drifted from its own pin.
+fn core_version() -> &'static str {
+    sasso::VERSION
 }
 
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("Sasso")?;
     let native = module.define_module("Native")?;
-    native.define_module_function("_compile", function!(native_compile, 6))?;
-    native.define_module_function("_compile_with_map", function!(native_compile_with_map, 7))?;
+    native.define_module_function("_compile", function!(native_compile, 2))?;
+    native.define_module_function("_core_version", function!(core_version, 0))?;
     Ok(())
 }

data/lib/sasso/version.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 module Sasso
-  # The gem version floats INDEPENDENTLY of the core `sasso` crate version; the
-  # native extension pins the crate exactly (ext/sasso/Cargo.toml: sasso = "=…").
-  VERSION = "0.2.7"
+  # Tracks the core `sasso` crate this gem bundles: a release adopting core
+  # X.Y.Z is gem X.Y.Z, and the native extension pins that crate exactly
+  # (ext/sasso/Cargo.toml). A gem-only fix takes the next patch, so the gem may
+  # sit ahead of the crate within a minor — `Sasso::CORE_VERSION` reads the
+  # version out of the linked binary and is the authority on what is loaded.
+  VERSION = "0.14.0"
 end

data/lib/sasso.rb

@@ -31,9 +31,21 @@ rescue LoadError
 end
 
 module Sasso
+  # The bundled compiler crate's version, read from the linked binary rather
+  # than written down here, so it cannot drift from what is actually loaded.
+  # VERSION tracks it as of 0.14.0, but a gem-only patch moves ahead of it.
+  CORE_VERSION = Sasso::Native._core_version.freeze
+
   STYLES   = %i[expanded compressed].freeze
   SYNTAXES = %i[scss sass css].freeze
 
+  # The keys of a diagnostic Hash handed to `on_warn:`. `:kind` is :warn or
+  # :debug; `:formatted` is the full dart-style block (header, snippet, stack
+  # trace) the compiler would otherwise have printed to stderr; `:url` is dart's
+  # display form of the source file and `:path` identifies it (the importer's
+  # canonical path), which is what tells a dependency from the entry stylesheet.
+  WARNING_KEYS = %i[kind deprecation deprecation_id message formatted url line path].freeze
+
   module_function
 
   # Compile a SCSS/Sass source String to a CSS String.
@@ -44,20 +56,50 @@ module Sasso
   #   load_paths:  dirs searched for @use/@forward/@import (built-in importer)
   #   url:         filename shown in diagnostics; ENABLES the dart-exact error block
   #   alert_ascii: true => ASCII-only diagnostics (maps to the compiler's no-unicode)
+  #   charset:     false => omit the @charset/BOM prefix on non-ASCII output
+  #   quiet:       true => print no @warn/@debug/deprecation diagnostics at all
+  #   quiet_deps:  true => drop deprecation warnings raised inside dependencies
+  #   on_warn:     a callable receiving each diagnostic as a Hash (see WARNING_KEYS);
+  #                taking delivery this way replaces the default stderr printing
   #
+  # Diagnostics go to $stderr by default, as the `sasso` CLI and dart-sass do.
   # Raises Sasso::CompileError on a compile failure; ArgumentError on bad options.
   def compile_string(source, style: :expanded, syntax: :scss, indented: false,
                      load_paths: [], url: nil, alert_ascii: false,
-                     source_map: false, source_map_include_sources: false)
+                     source_map: false, source_map_include_sources: false,
+                     charset: true, quiet: false, quiet_deps: false, on_warn: nil)
     syntax = :sass if indented
     validate!(style, STYLES, :style)
     validate!(syntax, SYNTAXES, :syntax)
-    paths = Array(load_paths).map(&:to_s)
-    src = String(source)
-    return Sasso::Native._compile(src, style.to_s, syntax.to_s, paths, url && url.to_s, !alert_ascii) unless source_map
+    # A positional Hash, not keyword arguments: `_compile` is a C function and
+    # has no keyword parameters, so the braces say what actually crosses the ABI.
+    css, map_json, diagnostics, error = Sasso::Native._compile(String(source), {
+                                                       style: style.to_s,
+                                                       syntax: syntax.to_s,
+                                                       load_paths: Array(load_paths).map(&:to_s),
+                                                       url: url && url.to_s,
+                                                       unicode: !alert_ascii,
+                                                       source_map: source_map,
+                                                       source_map_include_sources: source_map_include_sources,
+                                                       charset: charset,
+                                                       quiet_deps: quiet_deps,
+                                                       warnings: warnings_mode(quiet, on_warn),
+                                                     })
+    # Deliver first, raise second: a compile can warn and then fail, and those
+    # warnings are the caller's only copy once `on_warn:` has taken over from
+    # the compiler's own printing. The native side hands the failure back as a
+    # String for exactly this reason.
+    # The `ensure` is what makes the compile failure win when the callable
+    # itself raises: a logger that is down should not mask the Sass error, which
+    # is the actual news. Ruby records the callable's exception as the
+    # CompileError's #cause, so neither is lost.
+    begin
+      diagnostics.each { |d| on_warn.call(d) } if on_warn
+    ensure
+      raise CompileError, error if error
+    end
+    return css unless source_map
 
-    css, map_json = Sasso::Native._compile_with_map(src, style.to_s, syntax.to_s, paths,
-                                                    url && url.to_s, !alert_ascii, source_map_include_sources)
     CompileResult.new(css, JSON.parse(map_json))
   end
 
@@ -87,4 +129,22 @@ module Sasso
           "invalid #{name}: #{value.inspect} (expected one of #{allowed.inspect})"
   end
   private_class_method :validate!
+
+  # Which diagnostic mode the native side installs. "stderr" leaves the
+  # compiler's own handler in place — the default costs nothing, and the block
+  # prints as it is raised rather than after the compile. The other two modes
+  # install a handler, which is what suppresses that printing.
+  def warnings_mode(quiet, on_warn)
+    if on_warn
+      raise ArgumentError, "quiet: and on_warn: are mutually exclusive" if quiet
+      raise ArgumentError, "on_warn: must respond to #call" unless on_warn.respond_to?(:call)
+
+      "capture"
+    elsif quiet
+      "silence"
+    else
+      "stderr"
+    end
+  end
+  private_class_method :warnings_mode
 end

data/sig/sasso.rbs

@@ -1,15 +1,42 @@
 module Sasso
   VERSION: String
+  CORE_VERSION: String
   STYLES: Array[Symbol]
   SYNTAXES: Array[Symbol]
+  WARNING_KEYS: Array[Symbol]
+
+  # One @warn / @debug / deprecation diagnostic, as handed to `on_warn:`.
+  type warning = {
+    kind: Symbol,
+    deprecation: bool,
+    deprecation_id: String,
+    message: String,
+    formatted: String,
+    url: String,
+    line: Integer,
+    path: String,
+  }
 
   class Error < StandardError
   end
   class CompileError < Error
   end
 
+  # `Struct.new(:css, :source_map)`. The constructor is spelled out because an
+  # RBS class without one inherits `Object`'s zero-argument `new`, which would
+  # reject the two-argument call the implementation makes.
+  class CompileResult < Struct[untyped]
+    attr_reader css: String
+    attr_reader source_map: Hash[String, untyped]
+
+    def initialize: (String css, Hash[String, untyped] source_map) -> void
+  end
+
   def self.compile_string: (String source, ?style: Symbol, ?syntax: Symbol,
                             ?indented: bool, ?load_paths: Array[untyped],
-                            ?url: String?, ?alert_ascii: bool) -> String
-  def self.compile: (untyped path, **untyped opts) -> String
+                            ?url: String?, ?alert_ascii: bool,
+                            ?source_map: bool, ?source_map_include_sources: bool,
+                            ?charset: bool, ?quiet: bool, ?quiet_deps: bool,
+                            ?on_warn: (^(warning) -> void)?) -> (String | CompileResult)
+  def self.compile: (untyped path, **untyped opts) -> (String | CompileResult)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sasso
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.14.0
 platform: ruby
 authors:
 - momiji-rs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-25 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -102,7 +102,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="