From 3c51c3be85bb0d1bdb87ea0d6632f1c256912f27 Mon Sep 17 00:00:00 2001
From: Dimitri Staessens <dimitri@ouroboros.rocks>
Date: Sun, 6 Oct 2019 21:37:45 +0200
Subject: build: Add some required modules for node

---
 node_modules/postcss/docs/guidelines/plugin.md | 195 +++++++++++++++++++++++++
 node_modules/postcss/docs/guidelines/runner.md | 143 ++++++++++++++++++
 2 files changed, 338 insertions(+)
 create mode 100644 node_modules/postcss/docs/guidelines/plugin.md
 create mode 100644 node_modules/postcss/docs/guidelines/runner.md

(limited to 'node_modules/postcss/docs/guidelines')

diff --git a/node_modules/postcss/docs/guidelines/plugin.md b/node_modules/postcss/docs/guidelines/plugin.md
new file mode 100644
index 0000000..4814b0f
--- /dev/null
+++ b/node_modules/postcss/docs/guidelines/plugin.md
@@ -0,0 +1,195 @@
+# PostCSS Plugin Guidelines
+
+A PostCSS plugin is a function that receives and, usually,
+transforms a CSS AST from the PostCSS parser.
+
+The rules below are *mandatory* for all PostCSS plugins.
+
+See also [ClojureWerkz’s recommendations] for open source projects.
+
+[ClojureWerkz’s recommendations]:  http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/
+
+## 1. API
+
+### 1.1 Clear name with `postcss-` prefix
+
+The plugin’s purpose should be clear just by reading its name.
+If you wrote a transpiler for CSS 4 Custom Media, `postcss-custom-media`
+would be a good name. If you wrote a plugin to support mixins,
+`postcss-mixins` would be a good name.
+
+The prefix `postcss-` shows that the plugin is part of the PostCSS ecosystem.
+
+This rule is not mandatory for plugins that can run as independent tools,
+without the user necessarily knowing that it is powered by
+PostCSS — for example, [cssnext] and [Autoprefixer].
+
+[Autoprefixer]: https://github.com/postcss/autoprefixer
+[cssnext]:      http://cssnext.io/
+
+### 1.2. Do one thing, and do it well
+
+Do not create multitool plugins. Several small, one-purpose plugins bundled into
+a plugin pack is usually a better solution.
+
+For example, [cssnext] contains many small plugins,
+one for each W3C specification. And [cssnano] contains a separate plugin
+for each of its optimization.
+
+[cssnext]: http://cssnext.io/
+[cssnano]: https://github.com/ben-eb/cssnano
+
+### 1.3. Do not use mixins
+
+Preprocessors libraries like Compass provide an API with mixins.
+
+PostCSS plugins are different.
+A plugin cannot be just a set of mixins for [postcss-mixins].
+
+To achieve your goal, consider transforming valid CSS
+or using custom at-rules and custom properties.
+
+[postcss-mixins]: https://github.com/postcss/postcss-mixins
+
+### 1.4. Create plugin by `postcss.plugin`
+
+By wrapping your function in this method,
+you are hooking into a common plugin API:
+
+```js
+module.exports = postcss.plugin('plugin-name', function (opts) {
+    return function (root, result) {
+        // Plugin code
+    };
+});
+```
+
+## 2. Processing
+
+### 2.1. Plugin must be tested
+
+A CI service like [Travis] is also recommended for testing code in
+different environments. You should test in (at least) Node.js [active LTS](https://github.com/nodejs/LTS) and current stable version.
+
+[Travis]: https://travis-ci.org/
+
+### 2.2. Use asynchronous methods whenever possible
+
+For example, use `fs.writeFile` instead of `fs.writeFileSync`:
+
+```js
+postcss.plugin('plugin-sprite', function (opts) {
+    return function (root, result) {
+
+        return new Promise(function (resolve, reject) {
+            var sprite = makeSprite();
+            fs.writeFile(opts.file, function (err) {
+                if ( err ) return reject(err);
+                resolve();
+            })
+        });
+
+    };
+});
+```
+
+### 2.3. Set `node.source` for new nodes
+
+Every node must have a relevant `source` so PostCSS can generate
+an accurate source map.
+
+So if you add new declaration based on some existing declaration, you should
+clone the existing declaration in order to save that original `source`.
+
+```js
+if ( needPrefix(decl.prop) ) {
+    decl.cloneBefore({ prop: '-webkit-' + decl.prop });
+}
+```
+
+You can also set `source` directly, copying from some existing node:
+
+```js
+if ( decl.prop === 'animation' ) {
+    var keyframe = createAnimationByName(decl.value);
+    keyframes.source = decl.source;
+    decl.root().append(keyframes);
+}
+```
+
+### 2.4. Use only the public PostCSS API
+
+PostCSS plugins must not rely on undocumented properties or methods,
+which may be subject to change in any minor release. The public API
+is described in [API docs].
+
+[API docs]: http://api.postcss.org/
+
+## 3. Errors
+
+### 3.1. Use `node.error` on CSS relevant errors
+
+If you have an error because of input CSS (like an unknown name
+in a mixin plugin) you should use `node.error` to create an error
+that includes source position:
+
+```js
+if ( typeof mixins[name] === 'undefined' ) {
+    throw decl.error('Unknown mixin ' + name, { plugin: 'postcss-mixins' });
+}
+```
+
+### 3.2. Use `result.warn` for warnings
+
+Do not print warnings with `console.log` or `console.warn`,
+because some PostCSS runner may not allow console output.
+
+```js
+if ( outdated(decl.prop) ) {
+    result.warn(decl.prop + ' is outdated', { node: decl });
+}
+```
+
+If CSS input is a source of the warning, the plugin must set the `node` option.
+
+## 4. Documentation
+
+### 4.1. Document your plugin in English
+
+PostCSS plugins must have their `README.md` written in English. Do not be afraid
+of your English skills, as the open source community will fix your errors.
+
+Of course, you are welcome to write documentation in other languages;
+just name them appropriately (e.g. `README.ja.md`).
+
+### 4.2. Include input and output examples
+
+The plugin's `README.md` must contain example input and output CSS.
+A clear example is the best way to describe how your plugin works.
+
+The first section of the `README.md` is a good place to put examples.
+See [postcss-opacity](https://github.com/iamvdo/postcss-opacity) for an example.
+
+Of course, this guideline does not apply if your plugin does not
+transform the CSS.
+
+### 4.3. Maintain a changelog
+
+PostCSS plugins must describe the changes of all their releases
+in a separate file, such as `CHANGELOG.md`, `History.md`, or [GitHub Releases].
+Visit [Keep A Changelog] for more information about how to write one of these.
+
+Of course, you should be using [SemVer].
+
+[Keep A Changelog]: http://keepachangelog.com/
+[GitHub Releases]:  https://help.github.com/articles/creating-releases/
+[SemVer]:           http://semver.org/
+
+### 4.4. Include `postcss-plugin` keyword in `package.json`
+
+PostCSS plugins written for npm must have the `postcss-plugin` keyword
+in their `package.json`. This special keyword will be useful for feedback about
+the PostCSS ecosystem.
+
+For packages not published to npm, this is not mandatory, but is recommended
+if the package format can contain keywords.
diff --git a/node_modules/postcss/docs/guidelines/runner.md b/node_modules/postcss/docs/guidelines/runner.md
new file mode 100644
index 0000000..83f2087
--- /dev/null
+++ b/node_modules/postcss/docs/guidelines/runner.md
@@ -0,0 +1,143 @@
+# PostCSS Runner Guidelines
+
+A PostCSS runner is a tool that processes CSS through a user-defined list
+of plugins; for example, [`postcss-cli`] or [`gulp‑postcss`].
+These rules are mandatory for any such runners.
+
+For single-plugin tools, like [`gulp-autoprefixer`],
+these rules are not mandatory but are highly recommended.
+
+See also [ClojureWerkz’s recommendations] for open source projects.
+
+[ClojureWerkz’s recommendations]:  http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/
+[`gulp-autoprefixer`]: https://github.com/sindresorhus/gulp-autoprefixer
+[`gulp‑postcss`]:      https://github.com/w0rm/gulp-postcss
+[`postcss-cli`]:       https://github.com/postcss/postcss-cli
+
+## 1. API
+
+### 1.1. Accept functions in plugin parameters
+
+If your runner uses a config file, it must be written in JavaScript, so that
+it can support plugins which accept a function, such as [`postcss-assets`]:
+
+```js
+module.exports = [
+    require('postcss-assets')({
+        cachebuster: function (file) {
+            return fs.statSync(file).mtime.getTime().toString(16);
+        }
+    })
+];
+```
+
+[`postcss-assets`]: https://github.com/borodean/postcss-assets
+
+## 2. Processing
+
+### 2.1. Set `from` and `to` processing options
+
+To ensure that PostCSS generates source maps and displays better syntax errors,
+runners must specify the `from` and `to` options. If your runner does not handle
+writing to disk (for example, a gulp transform), you should set both options
+to point to the same file:
+
+```js
+processor.process({ from: file.path, to: file.path });
+```
+
+### 2.2. Use only the asynchronous API
+
+PostCSS runners must use only the asynchronous API.
+The synchronous API is provided only for debugging, is slower,
+and can’t work with asynchronous plugins.
+
+```js
+processor.process(opts).then(function (result) {
+    // processing is finished
+});
+```
+
+### 2.3. Use only the public PostCSS API
+
+PostCSS runners must not rely on undocumented properties or methods,
+which may be subject to change in any minor release. The public API
+is described in [API docs].
+
+[API docs]: http://api.postcss.org/
+
+## 3. Output
+
+### 3.1. Don’t show JS stack for `CssSyntaxError`
+
+PostCSS runners must not show a stack trace for CSS syntax errors,
+as the runner can be used by developers who are not familiar with JavaScript.
+Instead, handle such errors gracefully:
+
+```js
+processor.process(opts).catch(function (error) {
+    if ( error.name === 'CssSyntaxError' ) {
+        process.stderr.write(error.message + error.showSourceCode());
+    } else {
+        throw error;
+    }
+});
+```
+
+### 3.2. Display `result.warnings()`
+
+PostCSS runners must output warnings from `result.warnings()`:
+
+```js
+result.warnings().forEach(function (warn) {
+    process.stderr.write(warn.toString());
+});
+```
+
+See also [postcss-log-warnings] and [postcss-messages] plugins.
+
+[postcss-log-warnings]: https://github.com/davidtheclark/postcss-log-warnings
+[postcss-messages]:     https://github.com/postcss/postcss-messages
+
+### 3.3. Allow the user to write source maps to different files
+
+PostCSS by default will inline source maps in the generated file; however,
+PostCSS runners must provide an option to save the source map in a different
+file:
+
+```js
+if ( result.map ) {
+    fs.writeFile(opts.to + '.map', result.map.toString());
+}
+```
+
+## 4. Documentation
+
+### 4.1. Document your runner in English
+
+PostCSS runners must have their `README.md` written in English. Do not be afraid
+of your English skills, as the open source community will fix your errors.
+
+Of course, you are welcome to write documentation in other languages;
+just name them appropriately (e.g. `README.ja.md`).
+
+### 4.2. Maintain a changelog
+
+PostCSS runners must describe changes of all releases in a separate file,
+such as `ChangeLog.md`, `History.md`, or with [GitHub Releases].
+Visit [Keep A Changelog] for more information on how to write one of these.
+
+Of course you should use [SemVer].
+
+[Keep A Changelog]: http://keepachangelog.com/
+[GitHub Releases]:  https://help.github.com/articles/creating-releases/
+[SemVer]:           http://semver.org/
+
+### 4.3. `postcss-runner` keyword in `package.json`
+
+PostCSS runners written for npm must have the `postcss-runner` keyword
+in their `package.json`. This special keyword will be useful for feedback about
+the PostCSS ecosystem.
+
+For packages not published to npm, this is not mandatory, but recommended
+if the package format is allowed to contain keywords.
-- 
cgit v1.2.3