sasspile 0.9.14

A pure Rust SCSS compiler — functional style, type-safe pipeline
Documentation

⛔ 禁止参照 dart-sass:dart-sass 依赖 GC(垃圾回收),其嵌套结构依赖 GC 保。sasspile 是纯 Rust 项目,无 GC,所有权语义完全不同。任何实现必须基于 Rust 所有权模型和 sass-spec 规范,不得参照 dart-sass 的实现。

sasspile

Crates.io Docs.rs License CI

纯 Rust 函数式 SCSS 编译器,使用 Rust 1.97 + Edition 2024 构建。

v0.9.8 — tokio-internal-async (对内异步对外同步) + 死代码清理 (Reactor 14→9 字段, 删 6 死类型) + Parser 回归 Iterator — sass-spec 基线 7592/12133 (62%), ep_full 121/121 (100%).

sasspile 是一个从零实现的 SCSS 编译器,采用 Rust 所有权管线。通过类型状态机(Type-State Pattern)确保编译阶段类型安全,使用 move 语义实现零 clone 的数据流。

Reactor::from_file(&path)?
    .with_load_paths(load_paths)
    .lex()?
    .parse()?
    .evaluate()?
    .serialize(OutputStyle::Expanded)
    .finish()

特性

  • 类型状态机管线: Reactor<StateRaw> → StateLexed → StateParsed → StateEvaluated → StateSerialized
  • Reactor 架构: 单类型 + 泛型状态参数编码管线阶段 + ReactorTrace OTel 集成 + tokio runtime (IO 层异步)
  • 纯函数式风格: Iterator + fold + 不可变数据
  • 零依赖核心: 纯 Rust 实现,无外部 C 库(color crate 仅用于参考)
  • sass-spec 兼容: 7365/12131 (62%) 全量通过(内联 hrx_support 模块,非隔离模式 + 路径前缀),core_functions/color 已跳过(需 --ignored 手动触发)
  • Bootstrap 5.3.8: 全量编译通过 ✅
  • Element Plus: 121/121 (100%) 通过 ✅(file_resolver.rs 拆分 + module_helpers 统一后无回归)
  • tracing 调试: 内建 span + event 追踪链路 + OpenTelemetry stdout exporter(--features otel)
  • AI 开发技能: 内置 skill.md 综合开发指南

快速开始

添加依赖:

[dependencies]
sasspile = "0.4"

最小示例:

use sasspile::{compile_expanded, compile_compressed};

fn main() -> Result<(), sasspile::SassError> {
    // 展开式输出
    let css = compile_expanded("a { color: red; }")?;
    println!("{}", css);
    // => "a {\n  color: red;\n}\n"

    // 压缩式输出
    let css = compile_compressed("a { color: red; }")?;
    println!("{}", css);
    // => "a{color:red;}"

    Ok(())
}

使用示例

use sasspile::compile_expanded;

let scss = r#"
$primary: #3498db;

.btn {
    background: $primary;
    color: white;

    &:hover {
        background: darken($primary, 10%);
    }

    @media (max-width: 768px) {
        width: 100%;
    }
}
"#;

let css = compile_expanded(scss)?;
println!("{}", css);

支持的功能

变量与作用域

  • 全局变量与局部变量
  • 变量插值 #{$var}

嵌套规则

  • 选择器嵌套
  • 属性嵌套(font: { size: 14px; weight: bold; })
  • 父选择器引用 &

运算

  • 数学运算(+, -, *, /, %)
  • 颜色运算
  • 字符串拼接

颜色函数(完整)

构造:rgb/rgba/hsl/hsla/hwb

操作:adjust-color/change-color/scale-color/mix/darken/lighten/adjust-hue/saturate/desaturate/grayscale/complement/invert/opacify/fade-in/transparentize/fade-out

CSS Color 4:color.to-space/color.to-gamut/color.channel/color.adjust/color.change/color.scale(支持 Lab/Lch/Oklab/Oklch/DisplayP3/sRGB/XYZ 等现代色彩空间)

颜色序列化:HSL 操作结果用 rgb(r%, g%, b%) 百分比格式输出(匹配 sass-spec)。CSS Color 4 转换使用 W3C 参考实现的有理数分数矩阵,色域映射支持 clip 和 local-minde 方法。

通道:red/green/blue/alpha/opacity/hue/saturation/lightness/whiteness/blackness/color-channel

Level 4:is-powerless/is-in-gamut/is-legacy/to-space/to-gamut/channel/space/same

字符串函数

str-length/str-index/str-slice/str-insert/str-split/to-upper-case/to-lower-case/unquote/quote/unique-id

列表函数

length/nth/append/join/index/separator/set-nth/is-bracketed/list-slash/zip

Map 函数

map-get/map-keys/map-values/map-has-key/map-merge/map-remove/map-set/map-deep-merge/map-deep-remove

数学函数

abs/ceil/floor/round/min/max/percentage/div/pow/sqrt/sin/cos/tan/asin/acos/atan/atan2/hypot/log/random/clamp/unit/is-unitless/compatible/comparable

命名参数支持:所有 math 函数支持命名参数调用(如 math.abs($number: 3)、math.clamp($min: 0, $number: 1, $max: 2)、math.pow($base: 2, $exponent: 3)、math.div($number1: 6, $number2: 3))。

选择器函数

selector-append/selector-nest/selector-parse/selector-simple-selectors/selector-unify/selector-extend/selector-replace/selector-is-super

Mixin 与函数

  • @mixin / @include / @content
  • @function / @return
  • @if / @else / @for / @each / @while
  • @import / @use / @forward
  • @extend / @at-root / @warn / @debug / @error

指令

  • @media 媒体查询
  • // 单行注释
  • /* */ 多行注释
  • !default / !important 标记

选择器

  • 通用选择器 *
  • 伪类 :hover, :focus, :nth-child(n)
  • 伪元素 ::before, ::after

测试

# 核心测试
cargo test --test compile_test    # 46 个
cargo test --test reactor_test    # 14 个
cargo test --test stage_test      # 8 个
cargo test --test ast_test        # 8 个
cargo test --test common_test     # 5 个
cargo test --test interp_test     # 15 个
cargo test --test default_config_test -- --test-threads=1  # 9 个

# 兼容性测试
cargo test --test bs_spec           # 15 Bootstrap 测试
cargo test --test ep_full           # 121 Element Plus 测试(约 38 秒)— 121/121 通过

# sass-spec 全量统计(约 44 秒)
RUST_LOG="sass_spec_full=info,sasspile=warn" cargo test --test sass_spec_full -- --nocapture

# OTel 追踪(输出 OpenTelemetry span)
RUST_LOG=info cargo test --features otel --test sass_spec_full -- --nocapture

全部通过:compile 46/46 + reactor 14/14 + stage 8/8 + ast 8/8 + common 5/5 + interp 15/15 + BS 15/15 + EP 121/121 + default 9/9 + sass-spec 7592/12133 (62%)

详见根目录 skill.md 获取完整开发指南。

架构设计

sasspile 使用类型状态机模式构建编译管线:

Reactor<StateRaw> { input }  ──lex()──►  Reactor<StateLexed> { tokens }
                                           │
                                           ▼
                                      Reactor<StateParsed> { ast }
                                           │
                                           ▼
                                    Reactor<StateEvaluated> { nodes }
                                           │
                                           ▼
                                   Reactor<StateSerialized> { css }

每个阶段通过类型转换确保:

  • 必须先解析后求值
  • 必须先求值后序列化
  • 编译错误在类型层面被阻止

文档

  • 架构指南: docs/ARCH.md — 模块职责、设计决策、性能考虑
  • API 文档: docs/API.md — 公开 API 参考
  • 开发技能: skill.md — 编译管线、内建函数、调试追踪
  • 设计文档: DESIGN.md — 项目设计思路

常用命令

# 开发任务(使用 just)
just test-all          # 运行全部测试
just clippy            # Clippy 检查
just bench             # 性能基准测试
just diag <subdir>     # sass-spec 诊断

# 或直接 cargo
cargo test --test compile_test
cargo clippy --all-targets
cargo bench

许可证

MIT