sass 3.2.7 → 3.3.0.rc.1

data/lib/sass/engine.rb

@@ -1,6 +1,9 @@
 require 'set'
 require 'digest/sha1'
 require 'sass/cache_stores'
+require 'sass/source/position'
+require 'sass/source/range'
+require 'sass/source/map'
 require 'sass/tree/node'
 require 'sass/tree/root_node'
 require 'sass/tree/rule_node'
@@ -26,6 +29,7 @@ require 'sass/tree/debug_node'
 require 'sass/tree/warn_node'
 require 'sass/tree/import_node'
 require 'sass/tree/charset_node'
+require 'sass/tree/at_root_node'
 require 'sass/tree/visitors/base'
 require 'sass/tree/visitors/perform'
 require 'sass/tree/visitors/cssize'
@@ -39,6 +43,7 @@ require 'sass/selector'
 require 'sass/environment'
 require 'sass/script'
 require 'sass/scss'
+require 'sass/stack'
 require 'sass/error'
 require 'sass/importers'
 require 'sass/shared'
@@ -52,12 +57,12 @@ module Sass
   # `name`: `String`
   # : The name of the mixin/function.
   #
-  # `args`: `Array<(Script::Node, Script::Node)>`
+  # `args`: `Array<(Script::Tree::Node, Script::Tree::Node)>`
   # : The arguments for the mixin/function.
   #   Each element is a tuple containing the variable node of the argument
   #   and the parse tree for the default value of the argument.
   #
-  # `splat`: `Script::Node?`
+  # `splat`: `Script::Tree::Node?`
   # : The variable node of the splat argument for this callable, or null.
   #
   # `environment`: {Sass::Environment}
@@ -188,6 +193,16 @@ module Sass
         options[:filesystem_importer].new(p.to_s)
       end
 
+      # Remove any deprecated importers if the location is imported explicitly
+      options[:load_paths].reject! do |importer|
+        importer.is_a?(Sass::Importers::DeprecatedPath) &&
+          options[:load_paths].find do |other_importer|
+            other_importer.is_a?(Sass::Importers::Filesystem) &&
+              other_importer != importer &&
+              other_importer.root == importer.root
+          end
+      end
+
       # Backwards compatibility
       options[:property_syntax] ||= options[:attribute_syntax]
       case options[:property_syntax]
@@ -246,7 +261,7 @@ module Sass
     #   See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
     # @see {Sass::Engine.for_file}
     # @see {Sass::Plugin}
-    def initialize(template, options={})
+    def initialize(template, options = {})
       @options = self.class.normalize_options(options)
       @template = template
     end
@@ -259,9 +274,27 @@ module Sass
     #   cannot be converted to UTF-8
     # @raise [ArgumentError] if the document uses an unknown encoding with `@charset`
     def render
-      return _render unless @options[:quiet]
-      Sass::Util.silence_sass_warnings {_render}
+      return encode_and_set_charset(_to_tree.render) unless @options[:quiet]
+      Sass::Util.silence_sass_warnings {encode_and_set_charset(_to_tree.render)}
+    end
+
+    # Render the template to CSS and return the source map.
+    #
+    # @param sourcemap_uri [String] The sourcemap URI to use in the
+    #   `@sourceMappingURL` comment. If this is relative, it should be relative
+    #   to the location of the CSS file.
+    # @return [(String, Sass::Source::Map)] The rendered CSS and the associated
+    #   source map
+    # @raise [Sass::SyntaxError] if there's an error in the document, or if the
+    #   public URL for this document couldn't be determined.
+    # @raise [Encoding::UndefinedConversionError] if the source encoding
+    #   cannot be converted to UTF-8
+    # @raise [ArgumentError] if the document uses an unknown encoding with `@charset`
+    def render_with_sourcemap(sourcemap_uri)
+      return _render_with_sourcemap(sourcemap_uri) unless @options[:quiet]
+      Sass::Util.silence_sass_warnings {_render_with_sourcemap(sourcemap_uri)}
     end
+
     alias_method :to_css, :render
 
     # Parses the document into its parse tree. Memoized.
@@ -269,9 +302,11 @@ module Sass
     # @return [Sass::Tree::Node] The root of the parse tree.
     # @raise [Sass::SyntaxError] if there's an error in the document
     def to_tree
-      @tree ||= @options[:quiet] ?
-        Sass::Util.silence_sass_warnings {_to_tree} :
-        _to_tree
+      @tree ||= if @options[:quiet]
+                  Sass::Util.silence_sass_warnings {_to_tree}
+                else
+                  _to_tree
+                end
     end
 
     # Returns the original encoding of the document,
@@ -300,7 +335,8 @@ module Sass
     #
     # @private
     def _dependencies(seen, engines)
-      return if seen.include?(key = [@options[:filename], @options[:importer]])
+      key = [@options[:filename], @options[:importer]]
+      return if seen.include?(key)
       seen << key
       engines << self
       to_tree.grep(Tree::ImportNode) do |n|
@@ -311,8 +347,34 @@ module Sass
 
     private
 
-    def _render
-      rendered = _to_tree.render
+    def _render_with_sourcemap(sourcemap_uri)
+      if @options[:filename].nil?
+        raise Sass::SyntaxError.new(<<ERR)
+Error generating source map: couldn't determine public URL for the source stylesheet.
+  No filename is available so there's nothing for the source map to link to.
+ERR
+      elsif @options[:importer].nil? ||
+        !(@options[:importer].public_url(@options[:filename]) ||
+          @options[:importer].is_a?(Sass::Importers::Filesystem))
+        raise Sass::SyntaxError.new(<<ERR)
+Error generating source map: couldn't determine public URL for "#{@options[:filename]}".
+  Without a public URL, there's nothing for the source map to link to.
+  Custom importers should define the #public_url method.
+ERR
+      end
+
+      rendered, sourcemap = _to_tree.render_with_sourcemap
+      compressed = @options[:style] == :compressed
+      rendered << "\n" if rendered[-1] != ?\n
+      rendered << "\n" unless compressed
+      rendered << "/*# sourceMappingURL="
+      rendered << Sass::Util.escape_uri(sourcemap_uri)
+      rendered << " */"
+      rendered = encode_and_set_charset(rendered)
+      return rendered, sourcemap
+    end
+
+    def encode_and_set_charset(rendered)
       return rendered if ruby1_8?
       begin
         # Try to convert the result to the original encoding,
@@ -330,7 +392,7 @@ module Sass
         key = sassc_key
         sha = Digest::SHA1.hexdigest(@template)
 
-        if root = @options[:cache_store].retrieve(key, sha)
+        if (root = @options[:cache_store].retrieve(key, sha))
           root.options = @options
           return root
         end
@@ -339,7 +401,7 @@ module Sass
       check_encoding!
 
       if @options[:syntax] == :scss
-        root = Sass::SCSS::Parser.new(@template, @options[:filename]).parse
+        root = Sass::SCSS::Parser.new(@template, @options[:filename], @options[:importer]).parse
       else
         root = Tree::RootNode.new(@template)
         append_children(root, tree(tabulate(@template)).first, true)
@@ -424,12 +486,15 @@ END
           raise SyntaxError.new(message, :line => index)
         end
 
-        lines << Line.new(line.strip, line_tabs, index, tab_str.size, @options[:filename], [])
+        lines << Line.new(line.strip, line_tabs, index, line_tab_str.size, @options[:filename], [])
       end
       lines
     end
 
+    # @comment
+    #   rubocop:disable ParameterLists
     def try_comment(line, last, tab_str, comment_tab_str, index)
+      # rubocop:enable ParameterLists
       return unless last && last.comment?
       # Nested comment stuff must be at least one whitespace char deeper
       # than the normal indentation
@@ -454,7 +519,8 @@ MSG
       nodes = []
       while (line = arr[i]) && line.tabs >= base
         if line.tabs > base
-          raise SyntaxError.new("The line was indented #{line.tabs - base} levels deeper than the previous line.",
+          raise SyntaxError.new(
+            "The line was indented #{line.tabs - base} levels deeper than the previous line.",
             :line => line.index) if line.tabs > base + 1
 
           nodes.last.children, i = tree(arr, i)
@@ -468,6 +534,7 @@ MSG
 
     def build_tree(parent, line, root = false)
       @line = line.index
+      @offset = line.offset
       node_or_nodes = parse_line(parent, line, root)
 
       Array(node_or_nodes).each do |node|
@@ -551,12 +618,25 @@ WARNING
           # which begin with ::,
           # as well as pseudo-classes
           # if we're using the new property syntax
-          Tree::RuleNode.new(parse_interp(line.text))
+          Tree::RuleNode.new(parse_interp(line.text), full_line_range(line))
         else
+          name_start_offset = line.offset + 1 # +1 for the leading ':'
           name, value = line.text.scan(PROPERTY_OLD)[0]
           raise SyntaxError.new("Invalid property: \"#{line.text}\".",
             :line => @line) if name.nil? || value.nil?
-          parse_property(name, parse_interp(name), value, :old, line)
+
+          value_start_offset = name_end_offset = name_start_offset + name.length
+          unless value.empty?
+            # +1 and -1 both compensate for the leading ':', which is part of line.text
+            value_start_offset = name_start_offset + line.text.index(value, name.length + 1) - 1
+          end
+
+          property = parse_property(name, parse_interp(name), value, :old, line, value_start_offset)
+          property.name_source_range = Sass::Source::Range.new(
+            Sass::Source::Position.new(@line, to_parser_offset(name_start_offset)),
+            Sass::Source::Position.new(@line, to_parser_offset(name_end_offset)),
+            @options[:filename], @options[:importer])
+          property
         end
       when ?$
         parse_variable(line)
@@ -565,12 +645,12 @@ WARNING
       when DIRECTIVE_CHAR
         parse_directive(parent, line, root)
       when ESCAPE_CHAR
-        Tree::RuleNode.new(parse_interp(line.text[1..-1]))
+        Tree::RuleNode.new(parse_interp(line.text[1..-1]), full_line_range(line))
       when MIXIN_DEFINITION_CHAR
         parse_mixin_definition(line)
       when MIXIN_INCLUDE_CHAR
         if line.text[1].nil? || line.text[1] == ?\s
-          Tree::RuleNode.new(parse_interp(line.text))
+          Tree::RuleNode.new(parse_interp(line.text), full_line_range(line))
         else
           parse_mixin_include(line, root)
         end
@@ -582,32 +662,70 @@ WARNING
     def parse_property_or_rule(line)
       scanner = Sass::Util::MultibyteStringScanner.new(line.text)
       hack_char = scanner.scan(/[:\*\.]|\#(?!\{)/)
-      parser = Sass::SCSS::Parser.new(scanner, @options[:filename], @line)
-
-      unless res = parser.parse_interp_ident
-        return Tree::RuleNode.new(parse_interp(line.text))
+      offset = line.offset
+      offset += hack_char.length if hack_char
+      parser = Sass::SCSS::Parser.new(scanner,
+        @options[:filename], @options[:importer],
+        @line, to_parser_offset(offset))
+
+      unless (res = parser.parse_interp_ident)
+        parsed = parse_interp(line.text, line.offset)
+        return Tree::RuleNode.new(parsed, full_line_range(line))
       end
+
+      ident_range = Sass::Source::Range.new(
+        Sass::Source::Position.new(@line, to_parser_offset(line.offset)),
+        Sass::Source::Position.new(@line, parser.offset),
+        @options[:filename], @options[:importer])
+      offset = parser.offset - 1
       res.unshift(hack_char) if hack_char
-      if comment = scanner.scan(Sass::SCSS::RX::COMMENT)
+
+      # Handle comments after a property name but before the colon.
+      if (comment = scanner.scan(Sass::SCSS::RX::COMMENT))
         res << comment
+        offset += comment.length
       end
 
       name = line.text[0...scanner.pos]
-      if scanner.scan(/\s*:(?:\s|$)/)
-        parse_property(name, res, scanner.rest, :new, line)
+      if (scanned = scanner.scan(/\s*:(?:\s+|$)/)) # test for a property
+        offset += scanned.length
+        property = parse_property(name, res, scanner.rest, :new, line, offset)
+        property.name_source_range = ident_range
+        property
       else
         res.pop if comment
-        Tree::RuleNode.new(res + parse_interp(scanner.rest))
+
+        if (trailing = (scanner.scan(/\s*#{Sass::SCSS::RX::COMMENT}/) ||
+                        scanner.scan(/\s*#{Sass::SCSS::RX::SINGLE_LINE_COMMENT}/)))
+          trailing.strip!
+        end
+        interp_parsed = parse_interp(scanner.rest)
+        selector_range = Sass::Source::Range.new(
+          ident_range.start_pos,
+          Sass::Source::Position.new(@line, to_parser_offset(line.offset) + line.text.length),
+          @options[:filename], @options[:importer])
+        rule = Tree::RuleNode.new(res + interp_parsed, selector_range)
+        rule << Tree::CommentNode.new([trailing], :silent) if trailing
+        rule
       end
     end
 
-    def parse_property(name, parsed_name, value, prop, line)
+    # @comment
+    #   rubocop:disable ParameterLists
+    def parse_property(name, parsed_name, value, prop, line, start_offset)
+      # rubocop:enable ParameterLists
       if value.strip.empty?
-        expr = Sass::Script::String.new("")
+        expr = Sass::Script::Tree::Literal.new(Sass::Script::Value::String.new(""))
+        end_offset = start_offset
       else
-        expr = parse_script(value, :offset => line.offset + line.text.index(value))
+        expr = parse_script(value, :offset => to_parser_offset(start_offset))
+        end_offset = expr.source_range.end_pos.offset - 1
       end
       node = Tree::PropNode.new(parse_interp(name), expr, prop)
+      node.value_source_range = Sass::Source::Range.new(
+        Sass::Source::Position.new(line.index, to_parser_offset(start_offset)),
+        Sass::Source::Position.new(line.index, to_parser_offset(end_offset)),
+        @options[:filename], @options[:importer])
       if value.strip.empty? && line.children.empty?
         raise SyntaxError.new(
           "Invalid property: \"#{node.declaration}\" (no value)." +
@@ -618,15 +736,24 @@ WARNING
     end
 
     def parse_variable(line)
-      name, value, default = line.text.scan(Script::MATCH)[0]
+      name, value, flags = line.text.scan(Script::MATCH)[0]
       raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath variable declarations.",
         :line => @line + 1) unless line.children.empty?
       raise SyntaxError.new("Invalid variable: \"#{line.text}\".",
         :line => @line) unless name && value
+      flags = flags ? flags.split(/\s+/) : []
+      if (invalid_flag = flags.find {|f| f != '!default' && f != '!global'})
+        raise SyntaxError.new("Invalid flag \"#{invalid_flag}\".", :line => @line)
+      end
 
-      expr = parse_script(value, :offset => line.offset + line.text.index(value))
+      # This workaround is needed for the case when the variable value is part of the identifier,
+      # otherwise we end up with the offset equal to the value index inside the name:
+      # $red_color: red;
+      var_lhs_length = 1 + name.length # 1 stands for '$'
+      index = line.text.index(value, line.offset + var_lhs_length) || 0
+      expr = parse_script(value, :offset => to_parser_offset(line.offset + index))
 
-      Tree::VariableNode.new(name, expr, default)
+      Tree::VariableNode.new(name, expr, flags.include?('!default'), flags.include?('!global'))
     end
 
     def parse_comment(line)
@@ -636,107 +763,162 @@ WARNING
         if silent
           value = [line.text]
         else
-          value = self.class.parse_interp(line.text, line.index, line.offset, :filename => @filename)
-          value[0].slice!(2) if loud # get rid of the "!"
+          value = self.class.parse_interp(
+            line.text, line.index, to_parser_offset(line.offset), :filename => @filename)
         end
         value = with_extracted_values(value) do |str|
           str = str.gsub(/^#{line.comment_tab_str}/m, '')[2..-1] # get rid of // or /*
           format_comment_text(str, silent)
         end
-        type = if silent then :silent elsif loud then :loud else :normal end
+        type = if silent
+                 :silent
+               elsif loud
+                 :loud
+               else
+                 :normal
+               end
         Tree::CommentNode.new(value, type)
       else
-        Tree::RuleNode.new(parse_interp(line.text))
+        Tree::RuleNode.new(parse_interp(line.text), full_line_range(line))
       end
     end
 
+    DIRECTIVES = Set[:mixin, :include, :function, :return, :debug, :warn, :for,
+      :each, :while, :if, :else, :extend, :import, :media, :charset, :content,
+      :at_root]
+
+    # @comment
+    #   rubocop:disable MethodLength
     def parse_directive(parent, line, root)
       directive, whitespace, value = line.text[1..-1].split(/(\s+)/, 2)
       offset = directive.size + whitespace.size + 1 if whitespace
 
-      # If value begins with url( or ",
-      # it's a CSS @import rule and we don't want to touch it.
-      case directive
-      when 'import'
-        parse_import(line, value, offset)
-      when 'mixin'
-        parse_mixin_definition(line)
-      when 'content'
-        parse_content_directive(line)
-      when 'include'
-        parse_mixin_include(line, root)
-      when 'function'
-        parse_function(line, root)
-      when 'for'
-        parse_for(line, root, value)
-      when 'each'
-        parse_each(line, root, value)
-      when 'else'
-        parse_else(parent, line, value)
-      when 'while'
-        raise SyntaxError.new("Invalid while directive '@while': expected expression.") unless value
-        Tree::WhileNode.new(parse_script(value, :offset => offset))
-      when 'if'
-        raise SyntaxError.new("Invalid if directive '@if': expected expression.") unless value
-        Tree::IfNode.new(parse_script(value, :offset => offset))
-      when 'debug'
-        raise SyntaxError.new("Invalid debug directive '@debug': expected expression.") unless value
-        raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath debug directives.",
-          :line => @line + 1) unless line.children.empty?
-        offset = line.offset + line.text.index(value).to_i
-        Tree::DebugNode.new(parse_script(value, :offset => offset))
-      when 'extend'
-        raise SyntaxError.new("Invalid extend directive '@extend': expected expression.") unless value
-        raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath extend directives.",
-          :line => @line + 1) unless line.children.empty?
-        optional = !!value.gsub!(/\s+#{Sass::SCSS::RX::OPTIONAL}$/, '')
-        offset = line.offset + line.text.index(value).to_i
-        Tree::ExtendNode.new(parse_interp(value, offset), optional)
-      when 'warn'
-        raise SyntaxError.new("Invalid warn directive '@warn': expected expression.") unless value
-        raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath warn directives.",
-          :line => @line + 1) unless line.children.empty?
-        offset = line.offset + line.text.index(value).to_i
-        Tree::WarnNode.new(parse_script(value, :offset => offset))
-      when 'return'
-        raise SyntaxError.new("Invalid @return: expected expression.") unless value
-        raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath return directives.",
-          :line => @line + 1) unless line.children.empty?
-        offset = line.offset + line.text.index(value).to_i
-        Tree::ReturnNode.new(parse_script(value, :offset => offset))
-      when 'charset'
-        name = value && value[/\A(["'])(.*)\1\Z/, 2] #"
-        raise SyntaxError.new("Invalid charset directive '@charset': expected string.") unless name
-        raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath charset directives.",
-          :line => @line + 1) unless line.children.empty?
-        Tree::CharsetNode.new(name)
-      when 'media'
+      directive_name = directive.gsub('-', '_').to_sym
+      if DIRECTIVES.include?(directive_name)
+        return send("parse_#{directive_name}_directive", parent, line, root, value, offset)
+      end
+
+      unprefixed_directive = directive.gsub(/^-[a-z0-9]+-/i, '')
+      if unprefixed_directive == 'supports'
         parser = Sass::SCSS::Parser.new(value, @options[:filename], @line)
-        Tree::MediaNode.new(parser.parse_media_query_list.to_a)
-      else
-        unprefixed_directive = directive.gsub(/^-[a-z0-9]+-/i, '')
-        if unprefixed_directive == 'supports'
-          parser = Sass::SCSS::Parser.new(value, @options[:filename], @line)
-          return Tree::SupportsNode.new(directive, parser.parse_supports_condition)
-        end
+        return Tree::SupportsNode.new(directive, parser.parse_supports_condition)
+      end
+
+      Tree::DirectiveNode.new(
+        value.nil? ? ["@#{directive}"] : ["@#{directive} "] + parse_interp(value, offset))
+    end
+
+    def parse_while_directive(parent, line, root, value, offset)
+      raise SyntaxError.new("Invalid while directive '@while': expected expression.") unless value
+      Tree::WhileNode.new(parse_script(value, :offset => offset))
+    end
+
+    def parse_if_directive(parent, line, root, value, offset)
+      raise SyntaxError.new("Invalid if directive '@if': expected expression.") unless value
+      Tree::IfNode.new(parse_script(value, :offset => offset))
+    end
+
+    def parse_debug_directive(parent, line, root, value, offset)
+      raise SyntaxError.new("Invalid debug directive '@debug': expected expression.") unless value
+      raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath debug directives.",
+        :line => @line + 1) unless line.children.empty?
+      offset = line.offset + line.text.index(value).to_i
+      Tree::DebugNode.new(parse_script(value, :offset => offset))
+    end
 
-        Tree::DirectiveNode.new(
-          value.nil? ? ["@#{directive}"] : ["@#{directive} "] + parse_interp(value, offset))
+    def parse_extend_directive(parent, line, root, value, offset)
+      raise SyntaxError.new("Invalid extend directive '@extend': expected expression.") unless value
+      raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath extend directives.",
+        :line => @line + 1) unless line.children.empty?
+      optional = !!value.gsub!(/\s+#{Sass::SCSS::RX::OPTIONAL}$/, '')
+      offset = line.offset + line.text.index(value).to_i
+      interp_parsed = parse_interp(value, offset)
+      selector_range = Sass::Source::Range.new(
+        Sass::Source::Position.new(@line, to_parser_offset(offset)),
+        Sass::Source::Position.new(@line, to_parser_offset(line.offset) + line.text.length),
+        @options[:filename], @options[:importer]
+      )
+      Tree::ExtendNode.new(interp_parsed, optional, selector_range)
+    end
+    # @comment
+    #   rubocop:enable MethodLength
+
+    def parse_warn_directive(parent, line, root, value, offset)
+      raise SyntaxError.new("Invalid warn directive '@warn': expected expression.") unless value
+      raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath warn directives.",
+        :line => @line + 1) unless line.children.empty?
+      offset = line.offset + line.text.index(value).to_i
+      Tree::WarnNode.new(parse_script(value, :offset => offset))
+    end
+
+    def parse_return_directive(parent, line, root, value, offset)
+      raise SyntaxError.new("Invalid @return: expected expression.") unless value
+      raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath return directives.",
+        :line => @line + 1) unless line.children.empty?
+      offset = line.offset + line.text.index(value).to_i
+      Tree::ReturnNode.new(parse_script(value, :offset => offset))
+    end
+
+    def parse_charset_directive(parent, line, root, value, offset)
+      name = value && value[/\A(["'])(.*)\1\Z/, 2] # "
+      raise SyntaxError.new("Invalid charset directive '@charset': expected string.") unless name
+      raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath charset directives.",
+        :line => @line + 1) unless line.children.empty?
+      Tree::CharsetNode.new(name)
+    end
+
+    def parse_media_directive(parent, line, root, value, offset)
+      parser = Sass::SCSS::Parser.new(value,
+        @options[:filename], @options[:importer],
+        @line, to_parser_offset(@offset))
+      offset = line.offset + line.text.index('media').to_i - 1
+      parsed_media_query_list = parser.parse_media_query_list.to_a
+      node = Tree::MediaNode.new(parsed_media_query_list)
+      node.source_range = Sass::Source::Range.new(
+        Sass::Source::Position.new(@line, to_parser_offset(offset)),
+        Sass::Source::Position.new(@line, to_parser_offset(line.offset) + line.text.length),
+        @options[:filename], @options[:importer])
+      node
+    end
+
+    def parse_at_root_directive(parent, line, root, value, offset)
+      return Sass::Tree::AtRootNode.new unless value
+
+      if value.start_with?('(')
+        parser = Sass::SCSS::Parser.new(value,
+          @options[:filename], @options[:importer],
+          @line, to_parser_offset(@offset))
+        offset = line.offset + line.text.index('at-root').to_i - 1
+        return Tree::AtRootNode.new(parser.parse_at_root_query)
       end
+
+      at_root_node = Tree::AtRootNode.new
+      parsed = parse_interp(value, offset)
+      rule_node = Tree::RuleNode.new(parsed, full_line_range(line))
+
+      # The caller expects to automatically add children to the returned node
+      # and we want it to add children to the rule node instead, so we
+      # manually handle the wiring here and return nil so the caller doesn't
+      # duplicate our efforts.
+      append_children(rule_node, line.children, false)
+      at_root_node << rule_node
+      parent << at_root_node
+      nil
     end
 
-    def parse_for(line, root, text)
-      var, from_expr, to_name, to_expr = text.scan(/^([^\s]+)\s+from\s+(.+)\s+(to|through)\s+(.+)$/).first
+    def parse_for_directive(parent, line, root, value, offset)
+      var, from_expr, to_name, to_expr =
+        value.scan(/^([^\s]+)\s+from\s+(.+)\s+(to|through)\s+(.+)$/).first
 
       if var.nil? # scan failed, try to figure out why for error message
-        if text !~ /^[^\s]+/
+        if value !~ /^[^\s]+/
           expected = "variable name"
-        elsif text !~ /^[^\s]+\s+from\s+.+/
+        elsif value !~ /^[^\s]+\s+from\s+.+/
           expected = "'from <expr>'"
         else
           expected = "'to <expr>' or 'through <expr>'"
         end
-        raise SyntaxError.new("Invalid for directive '@for #{text}': expected #{expected}.")
+        raise SyntaxError.new("Invalid for directive '@for #{value}': expected #{expected}.")
       end
       raise SyntaxError.new("Invalid variable \"#{var}\".") unless var =~ Script::VALIDATE
 
@@ -746,31 +928,35 @@ WARNING
       Tree::ForNode.new(var, parsed_from, parsed_to, to_name == 'to')
     end
 
-    def parse_each(line, root, text)
-      var, list_expr = text.scan(/^([^\s]+)\s+in\s+(.+)$/).first
+    def parse_each_directive(parent, line, root, value, offset)
+      vars, list_expr = value.scan(/^([^\s]+(?:\s*,\s*[^\s]+)*)\s+in\s+(.+)$/).first
 
-      if var.nil? # scan failed, try to figure out why for error message
-        if text !~ /^[^\s]+/
+      if vars.nil? # scan failed, try to figure out why for error message
+        if value !~ /^[^\s]+/
           expected = "variable name"
-        elsif text !~ /^[^\s]+\s+from\s+.+/
+        elsif value !~ /^[^\s]+(?:\s*,\s*[^\s]+)*[^\s]+\s+from\s+.+/
           expected = "'in <expr>'"
         end
-        raise SyntaxError.new("Invalid for directive '@each #{text}': expected #{expected}.")
+        raise SyntaxError.new("Invalid each directive '@each #{value}': expected #{expected}.")
+      end
+
+      vars = vars.split(',').map do |var|
+        var.strip!
+        raise SyntaxError.new("Invalid variable \"#{var}\".") unless var =~ Script::VALIDATE
+        var[1..-1]
       end
-      raise SyntaxError.new("Invalid variable \"#{var}\".") unless var =~ Script::VALIDATE
 
-      var = var[1..-1]
       parsed_list = parse_script(list_expr, :offset => line.offset + line.text.index(list_expr))
-      Tree::EachNode.new(var, parsed_list)
+      Tree::EachNode.new(vars, parsed_list)
     end
 
-    def parse_else(parent, line, text)
+    def parse_else_directive(parent, line, root, value, offset)
       previous = parent.children.last
       raise SyntaxError.new("@else must come after @if.") unless previous.is_a?(Tree::IfNode)
 
-      if text
-        if text !~ /^if\s+(.+)/
-          raise SyntaxError.new("Invalid else directive '@else #{text}': expected 'if <expr>'.")
+      if value
+        if value !~ /^if\s+(.+)/
+          raise SyntaxError.new("Invalid else directive '@else #{value}': expected 'if <expr>'.")
         end
         expr = parse_script($1, :offset => line.offset + line.text.index($1))
       end
@@ -781,7 +967,7 @@ WARNING
       nil
     end
 
-    def parse_import(line, value, offset)
+    def parse_import_directive(parent, line, root, value, offset)
       raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath import directives.",
         :line => @line + 1) unless line.children.empty?
 
@@ -789,8 +975,9 @@ WARNING
       values = []
 
       loop do
-        unless node = parse_import_arg(scanner, offset + scanner.pos)
-          raise SyntaxError.new("Invalid @import: expected file to import, was #{scanner.rest.inspect}",
+        unless (node = parse_import_arg(scanner, offset + scanner.pos))
+          raise SyntaxError.new(
+            "Invalid @import: expected file to import, was #{scanner.rest.inspect}",
             :line => @line)
         end
         values << node
@@ -802,35 +989,80 @@ WARNING
           :line => @line)
       end
 
-      return values
+      values
     end
 
+    # @comment
+    #   rubocop:disable MethodLength
     def parse_import_arg(scanner, offset)
       return if scanner.eos?
 
       if scanner.match?(/url\(/i)
-        script_parser = Sass::Script::Parser.new(scanner, @line, offset, @options)
+        script_parser = Sass::Script::Parser.new(scanner, @line, to_parser_offset(offset), @options)
         str = script_parser.parse_string
-        media_parser = Sass::SCSS::Parser.new(scanner, @options[:filename], @line)
-        media = media_parser.parse_media_query_list
-        return Tree::CssImportNode.new(str, media.to_a)
+
+        media_parser = Sass::SCSS::Parser.new(scanner,
+          @options[:filename], @options[:importer],
+          @line, str.source_range.end_pos.offset)
+        if (media = media_parser.parse_media_query_list)
+          end_pos = Sass::Source::Position.new(@line, media_parser.offset + 1)
+          node = Tree::CssImportNode.new(str, media.to_a)
+        else
+          end_pos = str.source_range.end_pos
+          node = Tree::CssImportNode.new(str)
+        end
+
+        node.source_range = Sass::Source::Range.new(
+          str.source_range.start_pos, end_pos,
+          @options[:filename], @options[:importer])
+        return node
       end
 
-      unless str = scanner.scan(Sass::SCSS::RX::STRING)
-        return Tree::ImportNode.new(scanner.scan(/[^,;]+/))
+      unless (str = scanner.scan(Sass::SCSS::RX::STRING))
+        scanned = scanner.scan(/[^,;]+/)
+        node = Tree::ImportNode.new(scanned)
+        start_parser_offset = to_parser_offset(offset)
+        node.source_range = Sass::Source::Range.new(
+          Sass::Source::Position.new(@line, start_parser_offset),
+          Sass::Source::Position.new(@line, start_parser_offset + scanned.length),
+          @options[:filename], @options[:importer])
+        return node
       end
 
+      start_offset = offset
+      offset += str.length
       val = scanner[1] || scanner[2]
-      scanner.scan(/\s*/)
+      scanned = scanner.scan(/\s*/)
       if !scanner.match?(/[,;]|$/)
-        media_parser = Sass::SCSS::Parser.new(scanner, @options[:filename], @line)
+        offset += scanned.length if scanned
+        media_parser = Sass::SCSS::Parser.new(scanner,
+          @options[:filename], @options[:importer], @line, offset)
         media = media_parser.parse_media_query_list
-        Tree::CssImportNode.new(str || uri, media.to_a)
-      elsif val =~ /^(https?:)?\/\//
-        Tree::CssImportNode.new("url(#{val})")
+        node = Tree::CssImportNode.new(str || uri, media.to_a)
+        node.source_range = Sass::Source::Range.new(
+          Sass::Source::Position.new(@line, to_parser_offset(start_offset)),
+          Sass::Source::Position.new(@line, media_parser.offset),
+          @options[:filename], @options[:importer])
+      elsif val =~ %r{^(https?:)?//}
+        node = Tree::CssImportNode.new("url(#{val})")
+        node.source_range = Sass::Source::Range.new(
+          Sass::Source::Position.new(@line, to_parser_offset(start_offset)),
+          Sass::Source::Position.new(@line, to_parser_offset(offset)),
+          @options[:filename], @options[:importer])
       else
-        Tree::ImportNode.new(val)
+        node = Tree::ImportNode.new(val)
+        node.source_range = Sass::Source::Range.new(
+          Sass::Source::Position.new(@line, to_parser_offset(start_offset)),
+          Sass::Source::Position.new(@line, to_parser_offset(offset)),
+          @options[:filename], @options[:importer])
       end
+      node
+    end
+    # @comment
+    #   rubocop:enable MethodLength
+
+    def parse_mixin_directive(parent, line, root, value, offset)
+      parse_mixin_definition(line)
     end
 
     MIXIN_DEF_RE = /^(?:=|@mixin)\s*(#{Sass::SCSS::RX::IDENT})(.*)$/
@@ -839,45 +1071,53 @@ WARNING
       raise SyntaxError.new("Invalid mixin \"#{line.text[1..-1]}\".") if name.nil?
 
       offset = line.offset + line.text.size - arg_string.size
-      args, splat = Script::Parser.new(arg_string.strip, @line, offset, @options).
+      args, splat = Script::Parser.new(arg_string.strip, @line, to_parser_offset(offset), @options).
         parse_mixin_definition_arglist
       Tree::MixinDefNode.new(name, args, splat)
     end
 
     CONTENT_RE = /^@content\s*(.+)?$/
-    def parse_content_directive(line)
+    def parse_content_directive(parent, line, root, value, offset)
       trailing = line.text.scan(CONTENT_RE).first.first
-      raise SyntaxError.new("Invalid content directive. Trailing characters found: \"#{trailing}\".") unless trailing.nil?
+      unless trailing.nil?
+        raise SyntaxError.new(
+          "Invalid content directive. Trailing characters found: \"#{trailing}\".")
+      end
       raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath @content directives.",
         :line => line.index + 1) unless line.children.empty?
       Tree::ContentNode.new
     end
 
+    def parse_include_directive(parent, line, root, value, offset)
+      parse_mixin_include(line, root)
+    end
+
     MIXIN_INCLUDE_RE = /^(?:\+|@include)\s*(#{Sass::SCSS::RX::IDENT})(.*)$/
     def parse_mixin_include(line, root)
       name, arg_string = line.text.scan(MIXIN_INCLUDE_RE).first
       raise SyntaxError.new("Invalid mixin include \"#{line.text}\".") if name.nil?
 
       offset = line.offset + line.text.size - arg_string.size
-      args, keywords, splat = Script::Parser.new(arg_string.strip, @line, offset, @options).
-        parse_mixin_include_arglist
-      Tree::MixinNode.new(name, args, keywords, splat)
+      args, keywords, splat, kwarg_splat =
+        Script::Parser.new(arg_string.strip, @line, to_parser_offset(offset), @options).
+          parse_mixin_include_arglist
+      Tree::MixinNode.new(name, args, keywords, splat, kwarg_splat)
     end
 
     FUNCTION_RE = /^@function\s*(#{Sass::SCSS::RX::IDENT})(.*)$/
-    def parse_function(line, root)
+    def parse_function_directive(parent, line, root, value, offset)
       name, arg_string = line.text.scan(FUNCTION_RE).first
       raise SyntaxError.new("Invalid function definition \"#{line.text}\".") if name.nil?
 
       offset = line.offset + line.text.size - arg_string.size
-      args, splat = Script::Parser.new(arg_string.strip, @line, offset, @options).
+      args, splat = Script::Parser.new(arg_string.strip, @line, to_parser_offset(offset), @options).
         parse_function_definition_arglist
       Tree::FunctionNode.new(name, args, splat)
     end
 
     def parse_script(script, options = {})
       line = options[:line] || @line
-      offset = options[:offset] || 0
+      offset = options[:offset] || @offset + 1
       Script.parse(script, line, offset, @options)
     end
 
@@ -890,7 +1130,7 @@ WARNING
       end
 
       return silent ? "//" : "/* */" if content.empty?
-      content.last.gsub!(%r{ ?\*/ *$}, '')
+      content.last.gsub!(/ ?\*\/ *$/, '')
       content.map! {|l| l.gsub!(/^\*( ?)/, '\1') || (l.empty? ? "" : " ") + l}
       content.first.gsub!(/^ /, '') unless removed_first
       if silent
@@ -905,8 +1145,20 @@ WARNING
       self.class.parse_interp(text, @line, offset, :filename => @filename)
     end
 
+    # Parser tracks 1-based line and offset, so our offset should be converted.
+    def to_parser_offset(offset)
+      offset + 1
+    end
+
+    def full_line_range(line)
+      Sass::Source::Range.new(
+        Sass::Source::Position.new(@line, to_parser_offset(line.offset)),
+        Sass::Source::Position.new(@line, to_parser_offset(line.offset) + line.text.length),
+        @options[:filename], @options[:importer])
+    end
+
     # It's important that this have strings (at least)
-    # at the beginning, the end, and between each Script::Node.
+    # at the beginning, the end, and between each Script::Tree::Node.
     #
     # @private
     def self.parse_interp(text, line, offset, options)
@@ -914,12 +1166,13 @@ WARNING
       rest = Sass::Shared.handle_interpolation text do |scan|
         escapes = scan[2].size
         res << scan.matched[0...-2 - escapes]
-        if escapes % 2 == 1
+        if escapes.odd?
           res << "\\" * (escapes - 1) << '#{'
         else
           res << "\\" * [0, escapes - 1].max
+          # Add 1 to emulate to_parser_offset.
           res << Script::Parser.new(
-            scan, line, offset + scan.pos - scan.matched_size, options).
+            scan, line, offset + scan.pos - scan.matched_size + 1, options).
             parse_interpolated
         end
       end