hanami-sasso 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dcf34040d859d4b988e52379a150972d7ecbe39a5220bf8a696bb5329a016572
+  data.tar.gz: 0c77072d4533a100af4aae20373b614360fa3feaf33821ab70dfae0b22461f1a
+SHA512:
+  metadata.gz: 484d10b56269d52e3fc5d80238a357863c792104b9e92d1a1fc1e7b430d1ce1bfd65c6d96eb5cedf7c8534e0d4f8105d597cbd4568d100267eb6d8a5950daca3
+  data.tar.gz: 4376f837b4f4a0b339b7e18e4e14eef024630b11c4c5d90c34c24bdab580830710e7786a2a84669d24be1c5127caa8f2d7cea54c8b3a7ca8b347a62c4be29ef6

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to **hanami-sasso** are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-14
+
+Initial release. Requires the `sasso` gem **>= 0.2.0**; targets **Hanami 2.1+**.
+
+### Added
+
+- `sasso:compile` / `sasso:watch` / `sasso:clobber` rake tasks that compile
+  configured Sass/SCSS entrypoints with the pure-Rust `sasso` compiler
+  in-process (no Node, no Dart, no subprocess) and write the CSS into `public/`.
+- Runs `sasso:compile` before Hanami's `assets:precompile` on deploy.
+- `HanamiSasso.configure` for builds / style / load_paths / source_dir /
+  build_dir / source_map (env-aware defaults: compressed + no map in production).

data/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 momiji-rs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+# hanami-sasso
+
+Compile **Sass/SCSS in [Hanami](https://hanamirb.org) 2.1+** with
+[**sasso**](https://github.com/momiji-rs/sasso-ruby) — a pure-Rust,
+zero-dependency, byte-for-byte [dart-sass](https://sass-lang.com) alternative.
+
+Hanami's assets pipeline is esbuild-based with no native Sass step. This gem adds
+`sasso:compile` / `sasso:watch` / `sasso:clobber` rake tasks that compile your
+Sass/SCSS **in-process** — no Node toolchain, no Dart VM, no subprocess — and
+write the CSS straight into `public/`.
+
+- **No Node for CSS.** Compile Sass with zero JavaScript tooling.
+- **In-process.** No process spawn per build — sasso is a native Ruby gem.
+- **Byte-for-byte dart-sass.** Same CSS as `dart-sass`, just faster.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "hanami-sasso"
+```
+
+```sh
+bundle install
+```
+
+Load the rake tasks from your `Rakefile` (after Hanami's, so the
+`assets:precompile` hook attaches):
+
+```ruby
+# Rakefile
+require "hanami/rake_tasks"
+require "hanami-sasso/rake_tasks"
+```
+
+Put your entrypoint (and partials) in `app/assets/css/` — e.g.
+`app/assets/css/app.scss`. Compile it:
+
+```sh
+bundle exec rake sasso:compile     # -> public/assets/css/app.css
+bundle exec rake sasso:watch       # recompile on change
+bundle exec rake sasso:clobber     # remove generated CSS
+```
+
+`sasso:compile` runs automatically before `assets:precompile`, so deploys
+regenerate the CSS. Link it from your layout:
+
+```erb
+<link rel="stylesheet" href="/assets/css/app.css">
+```
+
+## Configuration
+
+Configure in your `Rakefile` (or a `config/sasso.rb` you require) — all optional,
+defaults shown:
+
+```ruby
+HanamiSasso.configure do |c|
+  # { "<input under source_dir>" => "<output under build_dir>" }
+  c.builds     = { "app.scss" => "app.css" }
+  # nil = :compressed in production (HANAMI_ENV=production), :expanded else.
+  c.style      = nil
+  c.load_paths = []                      # extra @use/@import dirs
+  c.source_dir = "app/assets/css"
+  c.build_dir  = "public/assets/css"     # compiled straight into public/
+  c.source_map = nil                     # nil = sidecar .map outside production
+end
+```
+
+> **Prefer Hanami's esbuild pipeline?** Set `c.build_dir = "app/assets/css"` and
+> `import` the compiled `.css` from `app/assets/js/app.js`; esbuild will then
+> bundle and fingerprint it. The default compiles straight into `public/` so
+> CSS needs no Node at all.
+
+## Performance
+
+`sasso` compiles the same CSS as dart-sass, byte-for-byte, but much faster — and
+with no Node runtime. Benchmarked on an Apple M2 Max, all engines dart-sass
+1.101, against the Node frontend's default Sass engine (`sass`, dart2js):
+
+**In-process** (how this gem compiles — inside the Ruby process):
+
+| workload | hanami-sasso | Node `sass` (dart2js) |
+|----------|--------------|-----------------------|
+| ~360 rules  | **1.2 ms** | 8.0 ms (**6.4× slower**) |
+| ~3000 rules | **9.9 ms** | 71.5 ms (**7.2× slower**) |
+
+**Cold per-build** (one-shot compile incl. runtime startup):
+
+| workload | hanami-sasso | dart-sass (native) | Node `sass` (dart2js) |
+|----------|--------------|--------------------|-----------------------|
+| ~360 rules  | **3.0 ms** | 27.5 ms (9×) | 185 ms (**63× slower**) |
+| ~3000 rules | **10.9 ms** | 64.2 ms (6×) | 348 ms (**32× slower**) |
+
+Output is byte-identical to dart-sass, so this is pure speedup with no behavior
+change. (Synthetic workloads; ratios are the takeaway, absolute numbers are
+machine-specific.)
+
+## License
+
+MIT, matching the Sass ecosystem. (The core `sasso` compiler crate is dual
+MIT OR Apache-2.0.)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+  t.warning = false
+end
+
+task default: :test

data/hanami-sasso.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/hanami-sasso/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "hanami-sasso"
+  spec.version     = HanamiSasso::VERSION
+  spec.author      = "momiji-rs"
+  spec.summary     = "Compile Sass/SCSS in Hanami with the pure-Rust sasso compiler — no Node, no Dart"
+  spec.description = "A Hanami integration for sasso, a pure-Rust, zero-dependency, byte-for-byte " \
+                     "dart-sass alternative. Adds sasso:compile/watch/clobber rake tasks (and runs " \
+                     "before assets:precompile) that compile your Sass/SCSS in-process — no Node " \
+                     "toolchain, no Dart VM, no subprocess. For Hanami 2.1+."
+  spec.homepage    = "https://github.com/momiji-rs/hanami-sasso"
+  spec.license     = "MIT"
+
+  spec.metadata = {
+    "homepage_uri"          => spec.homepage,
+    "source_code_uri"       => spec.homepage,
+    "changelog_uri"         => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "rubygems_mfa_required" => "true",
+  }
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|script|spec|features)/}) || f.match(%r{^\.})
+  end
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 3.1.0"
+
+  # The gem's runtime code requires only the compiler (+ Rake for the tasks); it
+  # integrates with Hanami's `assets:precompile` when present but never loads the
+  # framework itself. Targets Hanami 2.1+.
+  spec.add_dependency "rake", ">= 13.0"
+  spec.add_dependency "sasso", ">= 0.2.0", "< 1"
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

data/lib/hanami-sasso/compiler.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "pathname"
+require "sasso"
+
+module HanamiSasso
+  # Compiles configured Sass/SCSS entrypoints to plain CSS files. Deliberately
+  # framework-free so it can be unit-tested with a plain temp `root:` — the rake
+  # tasks just wire the Hanami app root + configuration in.
+  #
+  #   HanamiSasso::Compiler.new(
+  #     root:       Dir.pwd,
+  #     builds:     { "app.scss" => "app.css" },
+  #     style:      :expanded,
+  #     load_paths: [],                  # extra dirs, in addition to the source dir
+  #     source_dir: "app/assets/css",
+  #     build_dir:  "public/assets/css",
+  #   ).build
+  class Compiler
+    Error = Class.new(StandardError)
+
+    ALLOWED_STYLES = %i[expanded compressed].freeze
+
+    attr_reader :root, :builds, :style, :load_paths, :source_dir, :build_dir, :source_map
+
+    def initialize(root:, builds:, style: :expanded, load_paths: [],
+                   source_dir: "app/assets/css",
+                   build_dir: "public/assets/css", source_map: false)
+      @root       = File.expand_path(root.to_s)
+      @builds     = normalize_builds(builds)
+      @style      = normalize_style(style)
+      @load_paths = Array(load_paths).map(&:to_s)
+      @source_dir = source_dir.to_s
+      @build_dir  = build_dir.to_s
+      @source_map = source_map ? true : false
+    end
+
+    # Compile every entrypoint; returns the list of written output paths.
+    def build
+      builds.map { |input, output| build_one(input, output) }
+    end
+
+    # Remove the generated CSS (and any sidecar maps) for every entrypoint.
+    def clobber
+      builds.filter_map do |_input, output|
+        dest = File.join(@root, @build_dir, output)
+        [dest, "#{dest}.map"].select { |f| File.file?(f) }.each { |f| FileUtils.rm_f(f) }
+        File.directory?(File.dirname(dest)) ? dest : nil
+      end
+    end
+
+    # Compile a single `input` (relative to source_dir) to `output` (relative to
+    # build_dir), returning the absolute path written.
+    def build_one(input, output)
+      src = File.join(@root, @source_dir, input)
+      raise Error, "hanami-sasso: input stylesheet not found: #{src}" unless File.file?(src)
+
+      dest = File.join(@root, @build_dir, output)
+      FileUtils.mkdir_p(File.dirname(dest))
+
+      # `Sasso.compile` already searches the entry file's own directory first
+      # (for sibling @use/@import); pass any extra include dirs after it.
+      if @source_map
+        result = ::Sasso.compile(src, style: @style, load_paths: @load_paths, source_map: true)
+        write_source_map(dest, result.source_map)
+        File.write(dest, result.css + source_map_footer(File.basename(dest)))
+      else
+        File.write(dest, ::Sasso.compile(src, style: @style, load_paths: @load_paths))
+      end
+      dest
+    end
+
+    # Recompile whenever a watched source file changes. Dependency-free poll loop
+    # (no `listen` gem): a cheap mtime scan of the source + load_path trees.
+    # Blocks. A compile error (including on the FIRST pass) is reported and the
+    # loop keeps running — the watcher must survive a mid-edit broken file.
+    def watch(interval: 1.0)
+      safe_build
+      snapshot = source_mtimes
+      loop do
+        sleep interval
+        current = source_mtimes
+        next if current == snapshot
+
+        snapshot = current
+        safe_build
+      end
+    end
+
+    private
+
+    def write_source_map(dest, source_map)
+      from_dir = File.dirname(dest)
+      source_map["file"] = File.basename(dest)
+      source_map["sources"] = Array(source_map["sources"]).map { |s| relative_source(s, from_dir) }
+      File.write("#{dest}.map", JSON.generate(source_map))
+    end
+
+    def source_map_footer(css_basename)
+      comment = "/*# sourceMappingURL=#{css_basename}.map */"
+      @style == :compressed ? "#{comment}\n" : "\n#{comment}\n"
+    end
+
+    def relative_source(url, from_dir)
+      Pathname.new(url).relative_path_from(Pathname.new(from_dir)).to_s
+    rescue ArgumentError
+      url
+    end
+
+    def safe_build
+      build
+    rescue ::Sasso::CompileError, Error => e
+      warn e.message
+    end
+
+    def source_mtimes
+      dirs = [File.join(@root, @source_dir), *@load_paths]
+      dirs.flat_map { |d| Dir.glob(File.join(d, "**", "*.{scss,sass}")) }
+          .uniq.sort.each_with_object({}) do |f, h|
+        h[f] = File.mtime(f).to_f
+      rescue Errno::ENOENT
+        # raced with a delete; skip
+      end
+    end
+
+    def normalize_builds(builds)
+      hash = builds.respond_to?(:to_h) ? builds.to_h : nil
+      if hash.nil? || hash.empty?
+        raise Error, 'hanami-sasso: builds must be a non-empty Hash of { "input.scss" => "output.css" }'
+      end
+
+      hash
+    end
+
+    def normalize_style(style)
+      sym = style.to_s.to_sym
+      unless ALLOWED_STYLES.include?(sym)
+        raise Error, "hanami-sasso: style must be one of #{ALLOWED_STYLES.inspect}, got #{style.inspect}"
+      end
+
+      sym
+    end
+  end
+end

data/lib/hanami-sasso/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module HanamiSasso
+  # Plugin configuration. Set it from your Rakefile (or a `config/sasso.rb` you
+  # require) with `HanamiSasso.configure { |c| ... }`. Defaults target a stock
+  # Hanami 2 layout and compile directly to `public/` (no Node, no esbuild).
+  class Configuration
+    attr_accessor :builds, :style, :load_paths, :source_dir, :build_dir, :source_map, :root
+
+    def initialize
+      # { "<input under source_dir>" => "<output under build_dir>" }
+      @builds      = { "app.scss" => "app.css" }
+      # nil = :compressed in production (HANAMI_ENV=production), :expanded else.
+      @style       = nil
+      # Extra @use/@import dirs; the entrypoint's own dir is always searched.
+      @load_paths  = []
+      @source_dir  = "app/assets/css"
+      # Compile straight into public/ so the CSS is served with no Node/esbuild
+      # step; link it with <link href="/assets/css/app.css">. Point this at
+      # "app/assets/css" instead if you'd rather feed Hanami's esbuild pipeline.
+      @build_dir   = "public/assets/css"
+      # nil = sidecar .map outside production, off in production; true/false force.
+      @source_map  = nil
+      # nil = the working dir when the task runs (the Hanami app root).
+      @root        = nil
+    end
+  end
+end

data/lib/hanami-sasso/rake_tasks.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rake"
+require "hanami-sasso"
+
+# Adds `sasso:compile` / `sasso:watch` / `sasso:clobber`, and runs `sasso:compile`
+# before Hanami's `assets:precompile` on deploy. Require this AFTER
+# `require "hanami/rake_tasks"` in your Rakefile so the precompile hook attaches:
+#
+#   # Rakefile
+#   require "hanami/rake_tasks"
+#   require "hanami-sasso/rake_tasks"
+#   HanamiSasso.configure { |c| c.builds = { "app.scss" => "app.css" } }  # optional
+
+namespace :sasso do
+  desc "Compile Sass/SCSS entrypoints with sasso"
+  task :compile do
+    HanamiSasso.compiler.build
+  end
+
+  desc "Watch sources and recompile on change"
+  task :watch do
+    HanamiSasso.compiler.watch
+  end
+
+  desc "Remove the generated CSS"
+  task :clobber do
+    HanamiSasso.compiler.clobber
+  end
+end
+
+# Compile before Hanami fingerprints/serves assets on deploy. No-op if the
+# Hanami assets tasks weren't loaded before this file.
+Rake::Task["assets:precompile"].enhance(["sasso:compile"]) if Rake::Task.task_defined?("assets:precompile")

data/lib/hanami-sasso/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module HanamiSasso
+  # The plugin version floats independently of the `sasso` compiler gem; the
+  # gemspec pins the compiler with a range.
+  VERSION = "0.1.0"
+end

data/lib/hanami-sasso.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "hanami-sasso/version"
+require "hanami-sasso/configuration"
+require "hanami-sasso/compiler"
+
+# Compile Sass/SCSS in a Hanami app with the pure-Rust `sasso` compiler — no
+# Node, no Dart, no subprocess. Provide the rake tasks by requiring
+# "hanami-sasso/rake_tasks" from your Rakefile.
+module HanamiSasso
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config)
+    end
+
+    def reset_configuration!
+      @config = Configuration.new
+    end
+
+    def production?
+      (ENV["HANAMI_ENV"] || ENV["RACK_ENV"] || "development").to_s == "production"
+    end
+
+    # Build a Compiler from the current configuration, resolving the env-aware
+    # defaults (style + source maps) to concrete values.
+    def compiler
+      c = config
+      Compiler.new(
+        root:       c.root || Dir.pwd,
+        builds:     c.builds,
+        style:      c.style || (production? ? :compressed : :expanded),
+        load_paths: c.load_paths,
+        source_dir: c.source_dir,
+        build_dir:  c.build_dir,
+        source_map: c.source_map.nil? ? !production? : c.source_map
+      )
+    end
+  end
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: hanami-sasso
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- momiji-rs
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: sasso
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A Hanami integration for sasso, a pure-Rust, zero-dependency, byte-for-byte
+  dart-sass alternative. Adds sasso:compile/watch/clobber rake tasks (and runs before
+  assets:precompile) that compile your Sass/SCSS in-process — no Node toolchain, no
+  Dart VM, no subprocess. For Hanami 2.1+.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- hanami-sasso.gemspec
+- lib/hanami-sasso.rb
+- lib/hanami-sasso/compiler.rb
+- lib/hanami-sasso/configuration.rb
+- lib/hanami-sasso/rake_tasks.rb
+- lib/hanami-sasso/version.rb
+homepage: https://github.com/momiji-rs/hanami-sasso
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/momiji-rs/hanami-sasso
+  source_code_uri: https://github.com/momiji-rs/hanami-sasso
+  changelog_uri: https://github.com/momiji-rs/hanami-sasso/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Compile Sass/SCSS in Hanami with the pure-Rust sasso compiler — no Node,
+  no Dart
+test_files: []