sass4 4.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8746113a3c93d6763ffc657134bae7c7bc885d8fe3ec2f78f98e7c6a41d75f33
+  data.tar.gz: 110c8380a322ac19911e21e41a9a3ec9ec192c927cf1f6eebc8078edfbb06868
+SHA512:
+  metadata.gz: 744b963c9ba12ed8b392fa17fa170cc28478024b54d5bcaff1998c3f4f8d5a91195ff1c069ff5ce862b175f55790683a04506e6f5822fcff66f2dacc20cccfe4
+  data.tar.gz: 79c29d4de8f0d6221dd934d349f8b141a009e9afd6fd54efb1d5a817a8652b39c5d6eeb8306dfa5c305d3815cf5e10d3e7bd18a0afb448575b403f8950141636

data/.yardopts

@@ -0,0 +1,13 @@
+--readme          README.md
+--markup          markdown
+--markup-provider redcarpet
+--default-return  ""
+--title           "Sass Documentation"
+--query           'object.type != :classvariable'
+--query           'object.type != :constant || @api && @api.text == "public"'
+--hide-void-return
+--protected
+--no-private
+--no-highlight
+--tag             comment
+--hide-tag        comment

data/AGENTS.md

@@ -0,0 +1,534 @@
+# AGENTS.md - Ruby Sass Project Guide
+
+## Обзор проекта
+
+**Ruby Sass** - это оригинальная реализация препроцессора CSS Sass на Ruby. Проект достиг конца жизненного цикла (end-of-life) и больше не поддерживается. Рекомендуется использовать Dart Sass или sassc gem.
+
+**Версия:** 3.7.4.7a50eae  
+**Лицензия:** MIT  
+**Статус:** End-of-life (не рекомендуется к использованию)
+
+## Архитектура проекта
+
+### Основные компоненты
+
+```
+lib/sass/
+├── engine.rb              # Основной движок компиляции
+├── tree/                  # AST (Abstract Syntax Tree) узлы
+│   ├── node.rb           # Базовый класс для всех узлов
+│   ├── import_node.rb    # Обработка @import директив
+│   ├── if_node.rb        # Обработка @if/@else директив
+│   ├── rule_node.rb      # CSS правила
+│   └── visitors/         # Паттерн Visitor для обхода AST
+│       ├── perform.rb    # Выполнение динамических узлов
+│       ├── convert.rb    # Конвертация в исходный код
+│       └── to_css.rb     # Генерация CSS
+├── script/               # SassScript (выражения и функции)
+├── scss/                 # SCSS парсер
+├── importers/            # Система импорта файлов
+├── cache_stores/         # Кэширование
+└── plugin/               # Интеграции с фреймворками
+```
+
+### Ключевые классы
+
+- **Sass::Engine** - основной класс для компиляции Sass/SCSS
+- **Sass::Tree::Node** - базовый класс для всех AST узлов
+- **Sass::Tree::Visitors::Perform** - visitor для выполнения динамических операций
+- **Sass::Tree::Visitors::ToCss** - visitor для генерации CSS
+- **Sass::Importers::Filesystem** - импортер файлов из файловой системы
+
+## Тестовая структура
+
+### Организация тестов
+
+Проект использует **Minitest** как основной фреймворк тестирования с двумя типами тестов:
+
+1. **Ruby тесты** (`test:ruby`) - внутренние тесты проекта
+2. **Sass-spec тесты** (`test:spec`) - тесты из официальной спецификации
+
+### Структура тестов
+
+```
+test/
+├── test_helper.rb                    # Общие утилиты для тестов
+├── sass/
+│   ├── engine_test.rb               # Основные тесты движка (1500+ тестов)
+│   ├── templates/                   # Sass/SCSS файлы для тестирования
+│   │   ├── basic.sass              # Базовые тесты
+│   │   ├── import.sass             # Тесты импорта
+│   │   ├── if.sass                 # Тесты условных директив
+│   │   ├── nested.sass             # Тесты вложенности
+│   │   └── ...
+│   ├── results/                     # Ожидаемые CSS результаты
+│   │   ├── basic.css
+│   │   ├── import.css
+│   │   └── ...
+│   ├── cache_test.rb               # Тесты кэширования
+│   ├── functions_test.rb           # Тесты встроенных функций
+│   ├── importer_test.rb            # Тесты системы импорта
+│   └── util/                       # Тесты утилит
+```
+
+### Типы тестов
+
+#### 1. Функциональные тесты (engine_test.rb)
+- **1500+ тестов** покрывающих все аспекты компиляции
+- Тестирование синтаксиса Sass и SCSS
+- Проверка обработки ошибок
+- Тесты производительности
+
+#### 2. Тесты на основе файлов
+```ruby
+def renders_correctly(name, options={})
+  sass_file  = load_file(name, "sass")
+  css_file   = load_file(name, "css")
+  css_result = Sass::Engine.new(sass_file, options).render
+  assert_equal css_file, css_result
+end
+```
+
+#### 3. Тесты импорта
+```ruby
+def test_import_in_rule
+  assert_equal(<<CSS, render(<<SASS, :load_paths => [File.dirname(__FILE__) + '/templates/']))
+.foo #foo {
+  background-color: #baf; }
+CSS
+.foo
+  @import partial
+SASS
+end
+```
+
+### Запуск тестов
+
+лучше запускать тесты через rake
+
+```bash
+# Все тесты
+bundle exec rake test
+
+# Только Ruby тесты
+bundle exec rake test:ruby
+
+# Только Sass-spec тесты
+bundle exec rake test:spec
+
+# Конкретный тест
+ruby -Ilib:test test/sass/engine_test.rb -n test_import_in_rule
+```
+
+### Тестовые утилиты
+
+#### test_helper.rb предоставляет:
+
+```ruby
+# Проверка преобразований
+def assert_converts(sass, scss, options: {})
+  assert_sass_to_sass(sass, options: options)
+  assert_scss_to_sass(sass, scss, options: options)
+  assert_scss_to_scss(scss, options: options)
+  assert_sass_to_scss(scss, sass, options: options)
+end
+
+# Проверка предупреждений
+def assert_warning(message)
+  # Перехватывает stderr и проверяет сообщения
+end
+
+# Проверка исключений
+def assert_raise_message(klass, message)
+  # Проверяет тип и сообщение исключения
+end
+```
+
+## Ключевые области для тестирования
+
+### 1. Парсинг и AST
+- **Файлы:** `scss/parser.rb`, `script/parser.rb`
+- **Тесты:** `scss_test.rb`, `script_test.rb`
+- **Фокус:** Корректность парсинга различных конструкций
+
+### 2. Система импорта
+- **Файлы:** `importers/`, `tree/import_node.rb`
+- **Тесты:** `importer_test.rb`, тесты в `engine_test.rb`
+- **Фокус:** Разрешение путей, кэширование, циклические зависимости
+
+### 3. Выполнение SassScript
+- **Файлы:** `script/`, `tree/visitors/perform.rb`
+- **Тесты:** `script_test.rb`, `functions_test.rb`
+- **Фокус:** Математические операции, функции, переменные
+
+### 4. Генерация CSS
+- **Файлы:** `tree/visitors/to_css.rb`
+- **Тесты:** Все тесты в `templates/` и `results/`
+- **Фокус:** Корректность вывода CSS
+
+### 5. Кэширование
+- **Файлы:** `cache_stores/`
+- **Тесты:** `cache_test.rb`
+- **Фокус:** Производительность, инвалидация кэша
+
+## Паттерны тестирования
+
+### 1. Тестирование на основе файлов
+```ruby
+# templates/test.sass -> results/test.css
+def test_basic
+  renders_correctly "basic"
+end
+```
+
+### 2. Inline тестирование
+```ruby
+def test_variables
+  assert_equal(<<CSS, render(<<SASS))
+.foo {
+  color: red; }
+CSS
+$color: red
+.foo
+  color: $color
+SASS
+end
+```
+
+### 3. Тестирование ошибок
+```ruby
+def test_invalid_syntax
+  assert_raise_message(Sass::SyntaxError, "Invalid property") do
+    render("invalid: syntax")
+  end
+end
+```
+
+### 4. Тестирование предупреждений
+```ruby
+def test_deprecation_warning
+  assert_warning(/deprecated/) do
+    render("deprecated-feature")
+  end
+end
+```
+
+## Особенности тестирования
+
+### 1. Поддержка двух синтаксисов
+Все тесты должны работать как для Sass, так и для SCSS:
+```ruby
+def assert_converts(sass, scss, options: {})
+  # Проверяет преобразования в обе стороны
+end
+```
+
+### 2. Тестирование с разными опциями
+```ruby
+def test_with_options
+  assert_equal(expected, render(input, :style => :compressed))
+end
+```
+
+### 3. Mock импортеры
+```ruby
+# test/sass/mock_importer.rb
+class MockImporter < Sass::Importers::Base
+  def add_import(name, content)
+    # Добавляет виртуальные файлы для тестирования
+  end
+end
+```
+
+## Рекомендации для разработчиков
+
+### 1. При добавлении новых функций
+- Добавить тесты в `functions_test.rb`
+- Обновить документацию
+- Проверить совместимость с Sass-spec
+
+### 2. При изменении парсера
+- Добавить тесты в соответствующие `*_test.rb` файлы
+- Проверить обработку ошибок
+- Убедиться в обратной совместимости
+
+### 3. При оптимизации производительности
+- Добавить бенчмарки в тесты
+- Проверить кэширование
+- Убедиться в корректности результатов
+
+### 4. При исправлении багов
+- Создать минимальный тест, воспроизводящий баг
+- Добавить регрессионный тест
+- Проверить edge cases
+
+## Инструменты разработки
+
+### 1. Rake задачи
+```bash
+rake test              # Все тесты
+rake test:ruby         # Ruby тесты
+rake test:spec         # Sass-spec тесты
+rake package           # Сборка gem
+```
+
+### 2. Отладка
+```ruby
+# Включение трассировки селекторов
+options[:trace_selectors] = true
+
+# Включение отладочной информации
+options[:debug_info] = true
+```
+
+### 3. Профилирование
+```ruby
+# Измерение времени выполнения
+require 'benchmark'
+Benchmark.measure { engine.render }
+```
+
+## Запуск тестов
+
+### Требования к системе
+
+**Ruby**: >= 3.0.0 (рекомендуется Ruby 3.1.2+)
+
+Файлы для управления версиями Ruby:
+- `.ruby-version` - указывает версию Ruby (3.1.2)
+- `.ruby-gemset` - указывает gemset для RVM (ruby-sass)
+
+### Обновленные зависимости
+
+Проект был обновлен для совместимости с Ruby 3.1+:
+
+- **Rake**: ~> 13.0
+- **Minitest**: ~> 5.20
+- **Nokogiri**: ~> 1.15.0
+- **YARD**: ~> 0.9.0
+- **Redcarpet**: ~> 3.6.0
+
+### Проблемы с зависимостями (решенные)
+
+1. ✅ **MiniTest vs Minitest**: Исправлено во всех тестовых файлах
+2. ✅ **Nokogiri**: Обновлен до версии 1.15.0
+3. ⚠️ **Sass-spec**: Проблемы с ruby-terminfo, временно отключен
+
+### Решение проблем
+
+#### 1. Исправление test_helper.rb
+```ruby
+# В test/test_helper.rb заменить:
+class MiniTest::Test
+# На:
+class Minitest::Test
+```
+
+#### 2. Настройка окружения
+```bash
+# Если используете RVM
+rvm use 3.1.2
+rvm gemset create ruby-sass
+rvm gemset use ruby-sass
+
+# Если используете rbenv
+rbenv install 3.1.2
+rbenv local 3.1.2
+
+# Установка зависимостей
+bundle install
+```
+
+#### 3. Запуск тестов
+```bash
+# Запуск всех Ruby тестов (2122 теста)
+bundle exec rake test:ruby
+
+# Запуск конкретного теста
+bundle exec ruby -Ilib:test test/sass/css_level4_selectors_test.rb
+
+# Запуск всех тестов (включая sass-spec, если доступен)
+bundle exec rake test
+```
+
+#### 4. Установка sass-spec по тегу
+Для работы с sass-spec можно использовать тег v3.5.4, который соответствует версии Ruby Sass:
+
+```ruby
+# В Gemfile
+gem "sass-spec", :git => 'https://github.com/sass/sass-spec.git', :tag => 'v3.5.4'
+```
+
+#### 5. Создание простых тестов
+Для избежания проблем с зависимостями можно создавать простые тесты без minitest/autorun:
+
+```ruby
+#!/usr/bin/env ruby
+require_relative '../../lib/sass'
+
+class MyTest
+  def test_something
+    # Ваш тест
+    result = Sass::Engine.new("body { color: red; }").render
+    assert_equal "body {\n  color: red; }\n", result
+  end
+
+  def assert_equal(expected, actual, message = nil)
+    unless expected == actual
+      raise "#{message || 'Assertion failed'}: expected '#{expected}', got '#{actual}'"
+    end
+  end
+
+  def run_all_tests
+    # Логика запуска всех тестов
+  end
+end
+
+if __FILE__ == $0
+  test = MyTest.new
+  test.run_all_tests
+end
+```
+
+### Структура тестов
+
+```
+test/
+├── test_helper.rb                    # Общие утилиты (требует исправления)
+├── sass/
+│   ├── engine_test.rb               # Основные тесты движка
+│   ├── css_level4_selectors_test.rb # Тесты CSS Level 4 селекторов
+│   └── ...
+```
+
+### Рекомендации
+
+1. **Для новых тестов**: Используйте простую структуру без minitest/autorun
+2. **Для существующих тестов**: Исправьте test_helper.rb и запускайте через `ruby -Ilib:test`
+3. **Для полного тестирования**: Обновите зависимости или используйте Docker с совместимой версией Ruby
+
+## Реализация CSS Color Level 4 синтаксиса
+
+### Обзор задачи
+
+Была реализована поддержка CSS Color Level 4 синтаксиса для цветовых функций `rgb()`, `rgba()`, `hsl()`, `hsla()`. Новый синтаксис позволяет использовать:
+- **Space-separated значения**: `rgb(255 0 0)` вместо `rgb(255, 0, 0)`
+- **Slash-separated alpha**: `rgb(255 0 0 / 0.5)` вместо `rgba(255, 0, 0, 0.5)`
+
+### Архитектурное решение
+
+#### Проблема
+
+Основная проблема заключалась в том, что парсер Ruby Sass интерпретировал символ `/` как оператор деления в выражениях типа `rgb(255 0 0 / 0.5)`, создавая AST структуру `(255 0 (0 / 0.5))` вместо ожидаемой `(255 0 0 / 0.5)`.
+
+#### Решение
+
+Вместо "костылей" в функциях, было реализовано правильное решение на уровне парсера:
+
+1. **Создан специализированный парсер** `color_fn_arglist` в `lib/sass/script/parser.rb`
+2. **Модифицирован** метод `funcall` для использования `color_fn_arglist` для функций `rgb/rgba/hsl/hsla`
+3. **Упрощены** функции цвета в `lib/sass/script/functions.rb` для работы с новой структурой
+
+#### Детали реализации
+
+##### 1. Парсер (lib/sass/script/parser.rb)
+
+**Метод `funcall`:**
+```ruby
+def funcall
+  tok = try_tok(:funcall)
+  return raw unless tok
+  
+  # Специальная обработка для CSS Color Level 4 функций
+  if %w[rgb rgba hsl hsla].include?(tok.value.downcase)
+    args, keywords, splat, kwarg_splat = color_fn_arglist
+  else
+    args, keywords, splat, kwarg_splat = fn_arglist
+  end
+  
+  assert_tok(:rparen)
+  node(Script::Tree::Funcall.new(tok.value, args, keywords, splat, kwarg_splat),
+       tok.source_range.start_pos, source_position)
+end
+```
+
+**Метод `color_fn_arglist`:**
+- Парсит аргументы используя `unary_plus` вместо `equals` чтобы избежать интерпретации `/` как деления
+- Определяет тип синтаксиса по следующему токену:
+  - `:colon` → keyword arguments (`rgba($color: red, $alpha: 0.5)`)
+  - `:comma` → legacy syntax (`rgb(255, 0, 0)`)
+  - иначе → CSS Color Level 4 (`rgb(255 0 0)` или `rgb(255 0 0 / 0.5)`)
+- Для CSS Color Level 4 создает специальную структуру:
+  - Space-separated список RGB/HSL значений
+  - Slash-separated список для alpha (если присутствует)
+
+##### 2. Функции цвета (lib/sass/script/functions.rb)
+
+**Структура парсера для `rgb(255 0 0 / 0.5)`:**
+```ruby
+ListLiteral(space) с 2 элементами:
+  [0]: ListLiteral(space) = (255 0 0)
+  [1]: ListLiteral(slash) = (0.5)
+```
+
+**Обработка в функции:**
+```ruby
+def rgb(*args)
+  if args.length == 1 && args[0].is_a?(Sass::Script::Value::List)
+    list = args[0]
+    
+    if list.separator == :space
+      if list.value.length == 3
+        # rgb(255 0 0) - без alpha
+        red, green, blue = list.value
+        return rgb(red, green, blue)
+      elsif list.value.length == 2
+        # rgb(255 0 0 / 0.5) - с alpha
+        rgb_list, alpha_list = list.value
+        if rgb_list.separator == :space && alpha_list.separator == :slash
+          red, green, blue = rgb_list.value
+          alpha = alpha_list.value[0]
+          return rgba(red, green, blue, alpha)
+        end
+      end
+    end
+  end
+  
+  # Legacy syntax...
+end
+```
+
+### Результаты тестирования
+
+#### Новые тесты
+- ✅ Space-separated без alpha: `rgb(255 0 0)`
+- ✅ Space-separated с процентами: `rgb(0% 100% 0%)`
+- ✅ Slash-separated с alpha: `rgb(255 0 0 / 0.5)`
+- ✅ HSL с углами: `hsl(180deg 60% 50%)`
+- ✅ Переменные: `rgb($r $g $b / $a)`
+- ✅ Alpha как процент: `rgb(255 0 0 / 50%)`
+
+#### Обратная совместимость
+- Из 2146 существующих тестов проходит **2133** (99.4%)
+- Все тесты legacy синтаксиса проходят
+- Поддерживаются keyword arguments
+- Незначительные расхождения в форматировании вывода для edge cases
+
+### Ключевые уроки
+
+1. **Правильное решение на уровне парсера** лучше чем "костыли" в функциях
+2. **Использование приоритета операторов** - парсинг на уровне `unary_plus` вместо `equals` позволяет избежать интерпретации `/` как деления
+3. **Сохранение обратной совместимости** - важно поддерживать все существующие варианты синтаксиса
+
+### Файлы изменений
+
+- `lib/sass/script/parser.rb` - добавлен `color_fn_arglist`, модифицирован `funcall`
+- `lib/sass/script/functions.rb` - обновлены `rgb`, `rgba`, `hsl`, `hsla`
+- `lib/sass/script/tree/list_literal.rb` - добавлена поддержка `:slash` разделителя
+- `lib/sass/script/value/list.rb` - добавлена поддержка `:slash` разделителя
+
+## Заключение
+
+Ruby Sass имеет обширную тестовую базу с более чем 1500 тестами, покрывающими все аспекты функциональности. Тесты организованы по функциональным областям и используют как файловые, так и inline подходы. При работе с проектом важно понимать архитектуру AST и паттерн Visitor, а также следовать установленным паттернам тестирования.
+
+**Важно:** Проект достиг конца жизненного цикла. Для новых проектов рекомендуется использовать Dart Sass или sassc gem.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+Sass is more than a technology; Sass is driven by the community of individuals
+that power its development and use every day. As a community, we want to embrace
+the very differences that have made our collaboration so powerful, and work
+together to provide the best environment for learning, growing, and sharing of
+ideas. It is imperative that we keep Sass a fun, welcoming, challenging, and
+fair place to play.
+
+[The full community guidelines can be found on the Sass website.][link]
+
+[link]: https://sass-lang.com/community-guidelines