# sass-tracing-tools

**Repository Path**: pauljoihn21/sass-tracing-tools

## Basic Information

- **Project Name**: sass-tracing-tools
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sass-tracing-tools

SCSS spec HRX 审计工具，基于 Rust + tracing + OpenTelemetry。

从 [sass-spec](https://github.com/sass/sass-spec) 的 HRX 文件中提取完整的测试用例图谱，识别多层嵌套虚拟目录结构，输出机器可读的 JSON 审计报告，为后续 SCSS 编译器实现提供准确的测试数据基准。

## 审计数据概览

| 指标 | 数值 |
|------|------|
| HRX 文件总数 | 1,306 |
| 测试用例总数 | 12,167 |
| Success 用例 | 9,915 |
| Error 用例 | 2,252 |
| SCSS 语法 | 11,774 |
| Sass 语法 | 393 |
| 最大嵌套深度 | 6 层 |

### 按功能域分布

| 域 | HRX 数 | 用例数 | 最大深度 |
|----|--------|--------|----------|
| core_functions | 874 | 8,647 | 6 |
| values | 94 | 1,227 | 5 |
| css | 145 | 967 | 6 |
| directives | 157 | 896 | 5 |
| expressions | 19 | 250 | 5 |
| callable | 3 | 101 | 4 |
| operators | 5 | 37 | 5 |
| parser | 4 | 22 | 3 |
| variables | 5 | 20 | 3 |

### 按嵌套深度分布

| 深度 | 用例数 |
|------|--------|
| 0（根级） | 213 |
| 1 | 3,235 |
| 2 | 5,825 |
| 3 | 2,161 |
| 4 | 599 |
| 5 | 122 |
| 6 | 12 |

## 架构

```
Scanner (walkdir)     文件遍历，排除 libsass/non_conformant
    │
    ▼
Parser (状态机)       HRX 格式解析，识别 <===> path 头 + <===> 目录分隔段
    │
    ▼
VFS Builder           从扁平路径构建虚拟目录树，计算嵌套深度
    │
    ▼
Test Discoverer       遍历 VFS 每个 dir，识别 input/output/error/warning
    │
    ▼
Reporter              生成 JSON 审计报告 + diff + summary
```

## 项目结构

```
src/
├── lib.rs          # 库入口
├── models.rs       # 数据类型: TestCase, HrxAudit, AuditReport
├── parser.rs       # HRX 状态机解析器
├── vfs.rs          # 虚拟目录树构建
├── discoverer.rs   # 测试用例发现
├── scanner.rs      # walkdir 文件遍历
├── report.rs       # 审计编排 + JSON 报告
└── main.rs         # CLI 入口
tests/
├── parser_test.rs      # 8 个解析/VFS 测试
└── discoverer_test.rs  # 3 个测试发现测试
```

## 用法

### 审计模式

```bash
# 全量审计 → JSON 文件
cargo run -- audit --spec-root sass-spec/spec/ --output spec_map.json

# 只输出汇总（不含 audits 细节）
cargo run -- audit --spec-root sass-spec/spec/ --summary-only

# 自定义排除目录
cargo run -- audit --spec-root sass-spec/spec/ --exclude libsass non_conformant
```

### 单文件检查

```bash
cargo run -- inspect --file sass-spec/spec/directives/extend/bogus.hrx
```

输出该 HRX 的完整 VFS 结构、测试用例列表、嵌套深度。

### 差异对比

```bash
# 对比两份审计报告
cargo run -- diff --spec-root sass-spec/spec/ --old-report old_spec_map.json
```

## 可观测性

### Tracing

所有处理管道使用 tracing span 记录上下文与调用链：

```bash
# 默认 info 级别
RUST_LOG=info cargo run -- audit --spec-root sass-spec/spec/

# trace 级别：完整 span 链
RUST_LOG=trace cargo run -- audit --spec-root sass-spec/spec/ 2>&1 | tee trace.log
```

Span 层次：

```
hrx_audit{stage=audit spec_root=...}
├── scan_files{stage=scan}
├── parse_hrx{stage=parse hrx_id=...}
├── discover_tests{stage=discover hrx_id=...}
└── (汇总)
```

### JSON 输出

审计结果为标准 JSON，可直接被后续工具消费：

```json
{
  "spec_root": "sass-spec/spec/",
  "total_hrx_files": 1306,
  "total_test_cases": 12167,
  "by_domain": { ... },
  "by_depth": { "0": 213, "1": 3235, ... },
  "by_type": { "success": 9915, "error": 2252 },
  "by_syntax": { "scss": 11774, "sass": 393 },
  "audits": [ ... ]
}
```

## 技术栈

- Rust edition 2024, toolchain 1.97
- tracing + tracing-subscriber — 结构化日志 + span 链
- opentelemetry 0.32 + opentelemetry-stdout — metrics JSON 输出
- clap 4 — CLI 框架
- serde + serde_json — 序列化
- walkdir 2 — 目录遍历

## 设计决策

| 决策 | 选择 | 理由 |
|------|------|------|
| HRX 解析 | 手写状态机 | 格式简单，调试友好 |
| VFS 表示 | 树形结构 | 保留目录顺序，便于递归遍历 |
| Tracing 导出 | 控制台 FmtLayer | 无需外部依赖，直接看 span 链 |
| 审计结果 | JSON 文件 | 机器可读，可被后续工具消费 |
| 排除目录 | libsass/ + non_conformant/ | 遗留测试不作为规范参考 |
| 测试放置 | tests/ 目录 | 禁止内联测试 |

## 开发

```bash
# 运行测试
cargo test

# 运行审计
cargo run -- audit --spec-root sass-spec/spec/ --output spec_map.json --summary-only

# verbose 模式
cargo run -- audit --spec-root sass-spec/spec/ --verbose
```