sasso 0.2.7-x86_64-linux → 0.14.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91cbaf5bd897cbece2019bbdb57335b0323b24ed6a0ad40ac57ab212397f3722
-  data.tar.gz: 870cd5783a4e90c0c4076e9ac08bda84ca22b2e0749408e329ba77478f8e0d15
+  metadata.gz: 8ba6180eeb0f5ef43f24cb0c5e8427d5bd2a59e0b7ec04083a83ee94a0c3591c
+  data.tar.gz: 7b45deeed303e21be6a1880ac89f8481a067dedfc5713b886f251758eb509fd8
 SHA512:
-  metadata.gz: 04a6e6b4568373e90f5dff566759063e6fc5a8f4307525b59ff005a62bb9de5228d65300f7c912ff4831a8954a3cb5a10feb0019b2966b7d791591f8e29abbb1
-  data.tar.gz: 2a44fb96b4f1d89ac68ba19b1805894949848467955978b66e877d16a03a8658985ef14af031daf819979a645e681900ce6f170c3ced20cfb35533c0c9ace32f
+  metadata.gz: f1164925ed900845d4866ef5f89d2e77e9ce81407940476c48f3ad4686e7436928638a74ed7c453d63bbd91b74627c8395d324174cd679b6b513a8e332216bbb
+  data.tar.gz: dd0936aff5384157373441ebabfef00ee6f2de04eb84a4ad7b16fd723e42f395eea5410c799a5e56931867f6e7a54a2a31e6af00bb3291f923474ea2ff2e3d1c

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/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/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: x86_64-linux
 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: rake
@@ -63,7 +63,6 @@ files:
 - LICENSE-MIT
 - README.md
 - lib/sasso.rb
-- lib/sasso/3.1/sasso.so
 - lib/sasso/3.2/sasso.so
 - lib/sasso/3.3/sasso.so
 - lib/sasso/3.4/sasso.so
@@ -85,7 +84,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
   - - "<"
     - !ruby/object:Gem::Version
       version: 3.5.dev