Convert the module system proposal to stable specifications (sass#2777)

Author: nex3

spec/README.md

@@ -0,0 +1 @@
+spec.md

spec/at-rules/extend.md

@@ -6,16 +6,24 @@ many interacting layers and a lot of intricate case analysis.
 
 ## Table of Contents
 
-* [Definition](#definition)
+* [Definitions](#definitions)
+  * [Extender](#extender)
+  * [Target](#target)
+  * [Extension](#extension)
+  * [Extendee](#extendee)
+  * [The `extend()` Function](#the-extend-function)
+* [Semantics](#semantics)
+  * [Executing an `@extend` Rule](#executing-an-extend-rule)
+  * [Resolving a Module's Extensions](#resolving-a-modules-extensions)
   * [Limitations](#limitations)
   * [Specificity](#specificity)
     * [The First Law](#the-first-law)
     * [The Second Law](#the-second-law)
 
-## Definition
+## Definitions
 
-First, let's give names to the various selectors involved with a given use of
-`@extend`:
+These definitions provide names to the various selectors involved with a given
+use of `@extend`:
 
 ```scss
 .extender {
@@ -28,16 +36,185 @@ First, let's give names to the various selectors involved with a given use of
 }
 ```
 
-The **extender** is the selector list for the style rule in which the `@extend`
-rule appears. The **target** is the simple selector that's used as an argument
-to `@extend`. The **extendee** is the selector list elsewhere in the stylesheet
-that contains the target and is modified to include the extender as well. We
-also use the function `extend(extendee, target, extender)` to refer to the
-result of extending `extendee` with `extender {@extend target}` (much like the
-Sass function `selector-extend()`).
+### Extender
 
-Given these definitions, the `@extend` rule means that **all elements matching
-the extender should be styled as though they match the target as well**.
+An `@extend` rule's *extender* is the [selector list][] for the style rule in
+which the `@extend` rule appears.
+
+[selector list]: https://drafts.csswg.org/selectors-4/#selector-list
+
+### Target
+
+An `@extend` rule's *target* is the [simple selector][] that's used as an
+argument to `@extend`.
+
+[simple selector]: https://drafts.csswg.org/selectors-4/#simple
+
+### Extension
+
+An *extension* is a collection of various properties.
+
+> An extension is a more abstract representation of the information inherent in
+> an `@extend` rule. As such, all `@extend` rules define extensions, but not all
+> extensions directly correspond to `@extend` rules.
+
+* The *extender*, a [selector list][].
+* The *target*, a [simple selector][].
+
+### Extendee
+
+An *extendee* is a selector list being modified by an [extension](#extension).
+It's only defined within the scope of a single application of a given extension.
+
+> If an extendee contains that extensions's target, it will usually be modified
+> to include the extension's extender as well.
+
+### The `extend()` Function
+
+As a shorthand, we use the function notation `extend(extendee, target,
+extender)` to refer to the result of extending `extendee` with `extender
+{@extend target}` (much like the Sass function `selector-extend()`). We further
+use `extend(extendee, extension)` as a shorthand for `extend(extendee,
+extension.target, extension.extender)`.
+
+## Semantics
+
+The `@extend` rule means that all elements matching the [extender](#extender)
+should be styled as though they match the [target](#target) as well. The
+`@extend` rule only applies to CSS in the module in which it's defined and
+that module's transitive dependencies.
+
+> Because Sass can't directly affect how the browser applies styles to elements,
+> these semantics are approximated by duplicating each [extendee](#extendee)
+> with the target replaced by the extender. Rather than being a naïve textual
+> replacement, the extender is integrated intelligently into the extendee to
+> match the semantics as best as possible.
+
+### Executing an `@extend` Rule
+
+To execute an `@extend` rule `rule`:
+
+* If there is no [current style rule][], throw an error.
+
+  [current style rule]: ../style-rules.md#current-style-rule
+
+* Let `selector` be the result of evaluating all interpolation in `rule`'s
+  selector and parsing the result as a list of simple selectors.
+
+* If `selector` contains any parent selectors, throw an error.
+
+* Let `extension` be an [extension](#extension) whose extender is the current
+  style rule's selector and whose target is `selector`.
+
+* Add `extension` to [the current module][]'s extensions.
+
+  [the current module]: ../spec.md#the-current-module
+
+> Note that this adds the extension to the module being evaluated, not the
+> module in which the `@extend` lexically appears. This means that `@extend`s
+> are effectively dynamically scoped, not lexically scoped.
+
+### Resolving a Module's Extensions
+
+This algorithm takes a [module][] `starting-module` and returns a [CSS tree][]
+that includes CSS for *all* modules transitively used or forwarded by
+`starting-module`.
+
+[module]: ../modules.md#module
+[CSS tree]: ../modules.md#css-tree
+
+* Let `new-selectors` be an empty map from style rules to selectors. For the
+  purposes of this map, style rules are compared using *reference equality*,
+  meaning that style rules at different points in the CSS tree are always
+  considered different even if their contents are the same.
+
+* Let `new-extensions` be an empty map from modules to sets of
+  [extensions](#extension).
+
+* Let `extended` be the subgraph of the [module graph][] containing
+  modules that are transitively reachable from `starting-module`.
+
+  [module graph]: ../modules.md#module-graph
+
+* For each module `domestic` in `extended`, in reverse [topological][] order:
+
+  [topological]: https://en.wikipedia.org/wiki/Topological_sorting
+
+  * Let `downstream` be the set of modules in `extended` whose dependencies
+    include `domestic`.
+
+  * For each style rule `rule` in `domestic`'s CSS:
+
+    * Let `selector` be the result of applying `domestic`'s extensions to
+      `rule`'s selector.
+
+    * Let `selector-lists` be an empty set of selector lists.
+
+    * For each module `foreign` in `downstream`:
+
+      * Let `extended-selector` be `extend(selector, new-extensions[foreign])`.
+
+        > `new-extensions[foreign]` is guaranteed to be populated at this point
+        > because `extended` is traversed in reverse topological order, which
+        > means that `foreign`'s own extensions will already have been resolved
+        > by the time we start working on modules upstream of it.
+
+      * Add `selector` to `selector-lists`.
+
+    * Set `new-selectors[rule]` to a selector that matches the union of all
+      elements matched by selectors in `selector-lists`. This selector must obey
+      [the specificity laws](#specificity) relative to the selectors from which
+      it was generated. For the purposes of [the first law](#the-first-law),
+      "the original extendee" is considered only to refer to selectors that
+      appear in `domestic`'s CSS, *not* selectors that were added by other
+      modules' extensions.
+
+      > Implementations are expected to trim redundant selectors from
+      > `selector-lists` as much as possible. For the purposes of the first law
+      > of extend, "the original extendee" is *only* the selectors in `rule`'s
+      > selector. The new complex selectors in `selector` generated from
+      > `domestic`'s extensions don't count as "original", and may be optimized
+      > away.
+
+    * For every extension `extension` whose extender appears in `rule`'s
+      selector:
+
+      * For every complex selector `complex` in `new-selectors[rule]`:
+
+        * Add a copy of `extension` with its extender replaced by `complex` to
+          `new-extensions[domestic]`.
+
+* Let `css` be an empty CSS tree.
+
+* Define a mutating recursive procedure, *traversing*, which takes a module
+  `domestic`:
+
+  * If `domestic` has already been traversed, do nothing.
+
+  * Otherwise, traverse every module in `domestic`'s dependencies.
+
+    > Because this traverses modules depth-first, it emits CSS in reverse
+    > topological order.
+    
+  * Let `initial-imports` be the longest initial subsequence of top-level
+    statements in `domestic`'s CSS tree that contains only comments and
+    `@import` rules *and* that ends with an `@import` rule.
+
+  * Insert a copy of `initial-imports` in `css` after the last `@import` rule, or
+    at the beginning of `css` if it doesn't contain any `@import` rules.
+
+  * For each top-level statement `statement` in `domestic`'s CSS tree after
+    `initial-imports`:
+
+    * If `statement` is an `@import` rule, insert a copy of `statement` in `css`
+      after the last `@import` rule, or at the beginning of `css` if it doesn't
+      contain any `@import` rules.
+
+    * Otherwise, add a copy of `statement` to the end of `css`, with any style
+      rules' selectors replaced with the corresponding selectors in
+      `new-selectors`.
+
+* Return `css`.
 
 ### Limitations
 
@@ -76,7 +253,6 @@ required to meet the full definition.
 When modifying the extendee during extension, the implementation must provide
 two guarantees about the result. These are known as the "laws of extend".
 
-
 #### The First Law
 
 The first law of `@extend` says that the specificity of the first generated

spec/at-rules/forward.md

@@ -0,0 +1,101 @@
+# `@forward`
+
+The `@forward` rule loads a [module][] from a URL and adds its members to the
+public API of the current module without making them available to use within the
+current stylesheet.
+
+[module]: ../modules.md#module
+
+## Table of Contents
+
+* [Syntax](#syntax)
+* [Semantics](#semantics)
+
+## Syntax
+
+The grammar for the `@forward` rule is as follows:
+
+<x><pre>
+**ForwardRule** ::= '@forward' QuotedString AsClause? (ShowClause | HideClause)?
+**AsClause**    ::= 'as' Identifier '*'
+**ShowClause**  ::= 'show' MemberName (',' MemberName)*
+**HideClause**  ::= 'hide' MemberName (',' MemberName)*
+**MemberName**  ::= '$'? Identifier
+</pre></x>
+
+`@forward` rules must be at the top level of the document, and must come before
+any rules other than `@charset` or `@use`. The `QuotedString`'s contents, known
+as the rule's *URL*, must be a [valid URL string][] (for non-[special][] base
+URL). No whitespace is allowed after `$` in `MemberName`, or before `*` in
+`AsClause`.
+
+[valid URL string]: https://url.spec.whatwg.org/#valid-url-string
+[special]: https://url.spec.whatwg.org/#special-scheme
+
+## Semantics
+
+> Note that `@forward` *does not* make any APIs available to the current module;
+> that is purely the domain of `@use`. It *does* include the forwarded module's
+> CSS tree, but it's not visible to `@extend` without also using the module.
+
+To execute a `@forward` rule `rule`:
+
+* If `rule` has an `AsClause` with identifier `prefix`:
+
+  * Let `rule-config` be an empty [configuration][].
+
+    [configuration]: ../modules.md#configuration
+
+  * For each variable `variable` in [the current configuration][]:
+
+    [the current configuration]: ../spec.md#current-configuration
+
+    * If `variable`'s name begins with `prefix`:
+
+      * Let `suffix` be the portion of `variable`'s name after `prefix`.
+
+      * Add a variable to `rule-config` with the name `suffix` and with the
+        same value as `variable`.
+
+* Otherwise, let `rule-config` be the current configuration.
+
+* Let `forwarded` be the result of [loading the module][] with `rule`'s URL
+  string and `rule-config`.
+
+  [loading the module]: ../modules.md#loading-a-module
+
+* For every member `member` in `forwarded`:
+
+  * Let `name` be `member`'s name.
+  
+  * If `rule` has an `AsClause` `as`, prepend `as`'s identifier to `name` (after
+    the `$` if `member` is a variable).
+
+  * If there's a member defined at the top level of [the current source file][]
+    named `name` with the same type as `member`, do nothing.
+
+    [the current source file]: ../spec.md#current-source-file
+
+  * Otherwise, if `rule` has a `show` clause that doesn't include `name`
+    (including `$` for variables), do nothing.
+
+    > It's not possible to show/hide a mixin without showing/hiding the
+    > equivalent function, or to do the reverse.
+
+  * Otherwise, if `rule` has a `hide` clause that does include `name` (including
+    `$` for variables), do nothing.
+
+  * Otherwise, if another `@forward` rule's module has a member named `name`
+    with the same type as `member`, throw an error.
+
+  * Otherwise, add `member` to [the current module][] with the name `name`.
+
+    [the current module]: ../spec.md#current-module
+
+    > It's possible for the same member to be added to a given module multiple
+    > times if it's forwarded with different prefixes. All of these names refer
+    > to the same logical member, so for example if a variable gets set that
+    > change will appear for all of its names.
+    >
+    > It's also possible for a module's members to have multiple prefixes added,
+    > if they're forwarded with prefixes multiple times.

spec/at-rules/function.md

@@ -0,0 +1,40 @@
+# `@function`
+
+## Table of Contents
+
+* [Syntax](#syntax)
+* [Semantics](#semantics)
+
+## Syntax
+
+<x><pre>
+**FunctionRule** ::= '@function' Identifier ArgumentDeclaration '{' Statements '}'
+</pre></x>
+
+No whitespace is allowed between the `Identifier` and the `ArgumentDeclaration`
+in `FunctionRule`.
+
+## Semantics
+
+To execute a `@function` rule `rule`:
+
+* Let `name` be the value of `rule`'s `Identifier`.
+
+* If `rule` is outside of any block of statements:
+
+  * If `name` *doesn't* begin with `-` or `_`, set [the current module][]'s
+    function `name` to `rule`.
+
+    [the current module]: ../spec.md#current-module
+
+    > This overrides the previous definition, if one exists.
+
+  * Set [the current import context][]'s function `name` to `rule`.
+
+    [the current import context]: ../spec.md#current-import-context
+
+    > This happens regardless of whether or not it begins with `-` or `_`.
+
+* Otherwise, set the innermost block's [scope][]'s function `name` to `value`.
+
+  [scope]: ../variables.md#scope