minicss 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 64d957ba44321d035f80d2f0a1d1f23d268c33c8a169a869192fa0dc6cf51dcc
+  data.tar.gz: 758db44357f78c2f43c2a714bb9cfcfba5e8b001e0ec3fc0c9a10b967e2ef005
+SHA512:
+  metadata.gz: c1f6547128ba426bd55bbe0a6fb23302810082216de1df340c8f22a17ef9400c912ab6b2b1a0c362130fd0cee5524a40ff923ac69d6ae55abbef5f5621929dfe
+  data.tar.gz: 244a8692b6e8e950551270f82bd7b4a3fddb52ee00a47637f17ad5bd13fbdec78da25f6e1ba1208f29ce641f93350e137b815f08f173e178a99e73b49c6402d8

data/.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+tab_width = 2
+trim_trailing_whitespace = true

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,66 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - spec/parsing_tests/*
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Lint/MixedRegexpCaptureTypes:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Layout/CaseIndentation:
+  EnforcedStyle: end
+
+Layout/MultilineOperationIndentation:
+  EnforcedStyle: indented
+
+Layout/SpaceAroundOperators:
+  EnforcedStyleForExponentOperator: space
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
+
+Style/SignalException:
+  Exclude:
+    - spec/**/*
+
+Naming/PredicateMethod:
+  Exclude:
+    - lib/minicss/css/parser.rb
+
+Lint/HashCompareByIdentity:
+  Exclude:
+    - lib/minicss/sel.rb

data/ACKNOWLEDGMENTS.md

@@ -0,0 +1,47 @@
+# Acknowledgments
+
+MiniCSS makes use of the following open source projects:
+
+## @LeaVerou/parsel
+
+`MiniCSS::Sel` is heavily based on Lea Verou's [`parsel`](https://github.com/leaverou/parsel) project:
+
+```
+MIT License
+
+Copyright (c) 2020 Lea Verou
+
+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.
+```
+
+## @heyvito/css-parsing-tests
+
+Test cases were generated by the implementation-independant, JSON-based tests for CSS parsers `css-parsing-tests`, forked from [CourtBouillon/css-parsing-tests](https://github.com/CourtBouillon/css-parsing-tests), currently living at [heyvito/css-parsing-tests](https://github.com/heyvito/css-parsing-tests):
+
+```
+Written in 2013 by Simon Sapin.
+Updated in 2025 by Vito Sartori.
+
+To the extent possible under law, the author(s) have dedicated all copyright
+and related and neighboring rights to this work to the public domain worldwide.
+This work is distributed without any warranty.
+
+See the CC0 Public Domain Dedication:
+http://creativecommons.org/publicdomain/zero/1.0/
+```

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Vito Sartori
+
+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,178 @@
+# MiniCSS
+
+MiniCSS is a pure Ruby implementation of the CSS Syntax Level 3 tokenizer,
+parser, serializer, and selector toolkit. It provides fast, dependency-free
+primitives for building linters, minifiers, and other CSS-aware tooling
+without reaching for native extensions.
+
+## Features
+
+- Pure Ruby tokenizer and parser with zero native dependencies and support
+for Ruby 3.4+.
+- Battle-tested against the JSON-based `css-parsing-tests` suite for
+standards-compliant parsing.
+- High-level AST wrappers (`MiniCSS::AST::Rule`, `Decl`, `AtRule`, `Function`,
+`Number`, and more) ready for programmatic inspection.
+- Bidirectional selector helpers (`MiniCSS::Sel`) for tokenizing, walking,
+computing specificity, and turning selector ASTs back into strings.
+- Serializer that converts AST nodes back into normalized CSS, enabling
+round-tripping and rewrites.
+- Accepts either strings or IO objects, with optional Unicode range
+tokenization via `allow_unicode_ranges`.
+
+## Installation
+
+Add MiniCSS to your project with Bundler:
+
+```bash
+bundle add minicss
+```
+
+Or install it directly:
+
+```bash
+gem install minicss
+```
+
+## Quick Start
+
+```ruby
+require "minicss"
+
+css = <<~CSS
+  @media (min-width: 768px) {
+    .button.primary {
+      color: #fff;
+      background: rgb(0 0 0 / 80%);
+    }
+  }
+CSS
+
+sheet = MiniCSS.parse(css)
+
+sheet.each do |node|
+  case node
+  when MiniCSS::AST::AtRule
+    puts "At-rule: @#{node.name} #{MiniCSS.serialize(node.prelude)}"
+    node.child_rules.each { puts "  Child: #{MiniCSS.serialize(_1)}" }
+  when MiniCSS::AST::Rule
+    selector = MiniCSS::Sel.stringify(node.selector)
+    puts "Rule: #{selector}"
+    node.decls.each do |decl|
+      value = MiniCSS.serialize(decl.value)
+      important = decl.important? ? " !important" : ""
+      puts "  #{decl.name}: #{value}#{important}"
+    end
+  when MiniCSS::AST::SyntaxError
+    warn "Syntax error: #{node.reason}"
+  end
+end
+```
+
+## Tokenizing CSS
+
+```ruby
+tokens = MiniCSS.tokenize(".btn { color: #fff; }")
+tokens.map { |token| [token.kind, token.literal] }
+# => [[:delim, "."], [:ident, "btn"], [:whitespace, " "], [:left_curly, "{"],
+#     [:whitespace, " "], [:ident, "color"], [:colon, ":"], [:whitespace, " "],
+#     [:hash, "#fff"], [:semicolon, ";"], [:whitespace, " "], [:right_curly, "}"]]
+
+unicode_tokens = MiniCSS.tokenize("div { content: U+4E00-9FFF; }", allow_unicode_ranges: true)
+```
+
+Every token carries positional information via `token.pos_start` and
+`token.pos_end`, making it easy to surface diagnostics.
+
+## Working with Selectors
+
+```ruby
+selector_ast = MiniCSS::Sel.parse("button#primary.action:hover")
+MiniCSS::Sel.specificity(selector_ast)
+# => [1, 2, 1]
+
+MiniCSS::Sel.walk(selector_ast) do |token, parent|
+  puts "#{token[:type]} → #{token[:content]}"
+end
+# id → #primary
+# class → .action
+# pseudo-class → :hover
+# type → button
+
+MiniCSS::Sel.stringify(selector_ast)
+# => "button#primary.action:hover"
+```
+
+Selectors are represented as nested hashes and arrays, mirroring the structure
+produced by Lea Verou’s parsel, which `MiniCSS::Sel` is based on.
+
+## Serializing CSS
+
+`MiniCSS.serialize` accepts any AST node (or array of nodes) returned by
+`MiniCSS.parse`:
+
+```ruby
+ast = MiniCSS.parse(".card { margin: 1rem; padding: 1rem; }")
+MiniCSS.serialize(ast)
+# => ".card{margin:1rem;padding:1rem;}"
+```
+
+This makes it easy to transform stylesheets and emit normalized output.
+
+## Handling Errors
+
+When the parser encounters invalid input it emits `MiniCSS::AST::SyntaxError`
+nodes alongside the rest of the AST:
+
+```ruby
+errors = MiniCSS.parse("p { color: }").grep(MiniCSS::AST::SyntaxError)
+errors.each { warn _1.reason }
+# Syntax error details, including source offsets, are preserved from the tokenizer.
+```
+
+You can introspect the original token stream to report accurate diagnostics.
+
+## Development
+
+- Install dependencies: `bundle install`
+- Run the test suite: `bundle exec rspec`
+- Check style and linting: `bundle exec rubocop`
+- Run everything: `bundle exec rake`
+
+Helpful utilities:
+
+- `bin/console` starts an IRB session with MiniCSS preloaded.
+- `bin/gen-specs.rb` regenerates the specs under `spec/parsing_tests` from the
+external `css-parsing-tests` fixtures.
+
+## Contributing
+
+Bug reports, feature requests, and pull requests are welcome. By participating
+you agree to abide by the project’s Code of Conduct (see CODE_OF_CONDUCT.md).
+Please include tests whenever you add or change behavior.
+
+## License
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2025 Vito Sartori
+
+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/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/minicss/ast/at_rule.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class AtRule
+      attr_accessor :name, :prelude, :child_rules
+
+      def initialize(rule)
+        @name = rule.name.literal.gsub(/^@/, "")
+        @prelude = rule.prelude.map { AST.convert(it) }
+        @prelude.pop while @prelude.last == " "
+        @prelude.shift while @prelude.first == " "
+        @child_rules = rule.child_rules.map { AST.convert it }
+      end
+    end
+  end
+end

data/lib/minicss/ast/bad_token.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class BadToken
+      attr_accessor :kind, :value
+
+      def initialize(css)
+        @kind = css.kind
+        @value = css.literal
+      end
+    end
+  end
+end

data/lib/minicss/ast/block.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class Block
+      RIGHT_TOKENS = {
+        left_parenthesis: ")",
+        left_curly: "}",
+        left_square_bracket: "]"
+      }.freeze
+
+      LEFT_TOKENS = {
+        left_parenthesis: "(",
+        left_curly: "{",
+        left_square_bracket: "["
+      }.freeze
+
+      attr_accessor :associated_token, :value
+
+      def initialize(css)
+        @associated_token = css.associated_token
+        @value = css.value.map { AST.convert(it) }
+      end
+
+      def right_token = RIGHT_TOKENS[@associated_token]
+      def left_token = LEFT_TOKENS[@associated_token]
+    end
+  end
+end

data/lib/minicss/ast/decl.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class Decl
+      attr_accessor :name, :value, :important
+
+      def initialize(decl)
+        @name = decl.name.literal
+        @value = decl.value.map { AST.convert(it) }
+        @important = decl.important
+      end
+
+      def important? = important
+    end
+  end
+end

data/lib/minicss/ast/decl_list.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class DeclList < Array
+      def initialize(old = nil)
+        super()
+        if old.is_a? Array
+          append(*old)
+        elsif old
+          append(old)
+        end
+      end
+    end
+  end
+end
+
+# Feci quod potui, faciant meliora potentes.

data/lib/minicss/ast/dimension.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class Dimension < Number
+      attr_accessor :unit
+
+      def initialize(css)
+        super
+        @unit = css.opts[:unit]
+      end
+    end
+  end
+end

data/lib/minicss/ast/function.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class Function
+      attr_accessor :raw_name, :name, :value
+
+      def initialize(func)
+        @raw_name = func.name.literal
+        @name = raw_name.strip.gsub(/\($/, "")
+        @value = func.value.map { AST.convert(it) }
+      end
+    end
+  end
+end

data/lib/minicss/ast/number.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class Number
+      attr_accessor :raw, :value, :type, :sign
+
+      def initialize(css)
+        @raw = css.literal
+        @value, @type, @sign = css.opts.slice(:value, :type, :sign_character).values
+      end
+    end
+  end
+end

data/lib/minicss/ast/percentage.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class Percentage < Number
+    end
+  end
+end

data/lib/minicss/ast/rule.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class Rule
+      attr_accessor :selector, :child_rules, :decls, :raw_selector
+
+      def initialize(struct)
+        raise "Expected CSS::AST::QualifiedRule, found #{struct.class}" unless struct.is_a? CSS::AST::QualifiedRule
+
+        @raw_selector = struct.prelude.map(&:literal).join
+        begin
+          @selector = Sel.parse(raw_selector)
+          @valid_selector = true
+        rescue StandardError => e
+          pos = struct.prelude.first.pos_start
+          @selector = "Failed parsing selector at #{pos.line}:#{pos.column}: #{e}"
+          @valid_selector = false
+        end
+
+        @child_rules = struct.child_rules.map { AST.convert(it) }
+        @decls = struct.decls.map { AST.convert(it) }
+      end
+
+      def valid_selector? = @valid_selector
+    end
+  end
+end

data/lib/minicss/ast/string_token.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MiniCSS
+  module AST
+    class StringToken
+      attr_accessor :value, :quoting
+
+      def initialize(css)
+        @value = css.literal
+        @quoting = css.opts[:quoting]
+      end
+    end
+  end
+end