@caweb/cli 1.4.2 → 1.4.4

package/README.md

@@ -18,183 +18,5 @@
   - phpMyAdmin test site started at http://localhost:9090
 - Uses CAWebPublishing [External Project Template Configuration](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/packages-create-block-external-template/) when creating Gutenberg Blocks, see configurations [here](https://github.com/CAWebPublishing/cli/lib/template)
 - Allows for syncing of WordPress instance via Rest API, to maintain ID's please ensure [CAWebPublishing Development Toolbox](https://github.com/CAWebPublishing/caweb-dev/) plugin is installed. 
-- Adds config.yml to both cli containers.  
-<b>Example config.yml file</b>
-<pre>
-    path: /var/www/html
-    apache_modules:
-      - mod_rewrite
-</pre>
-
-
-## Command Reference
-### `caweb start`  
-Generates the required wp-env.json, starts the WordPress environment, downloads any CAWebPublishing sources and approved plugins.  
-<pre>
-caweb start [options]
-
-Starts two CAWebPublishing WordPress instances
-development on port 8888 (​http://localhost:8888​) (override with WP_ENV_PORT)
-tests on port 8889 (​http://localhost:8889​) (override with WP_ENV_TESTS_PORT).
-After first install, use the '--update' flag to download updates to mapped sources and to re-apply CAWeb configuration options.
-
-Options:
-  --bare           True if excluding any downloads from CAWeb, use this if you want to use a local version of the CAWeb Theme, Configurations will still be applied. (default: false)
-  -h, --help       display help for command
-  -m, --multisite  True if converting to multisite. (default: false)
-  -p, --plugin     True if root directory is a plugin. (default: false)
-  --scripts        Execute any configured lifecycle scripts. (default: true)
-  --subdomain      If passed, the network will use subdomains, instead of subdirectories. Doesn't work with 'localhost', make sure to set Port to 80. (default: false)
-  -t, --theme      True if root directory is a theme. (default: false)
-  --update         Download source updates and apply WordPress configuration. (default: false)
-  --xdebug <mode>  Enables Xdebug. If not passed, Xdebug is turned off. If no modes are set, uses "debug". You may set multiple Xdebug modes by passing them in a comma-separated list:
-                   `--xdebug=develop,coverage`. See https://xdebug.org/docs/all_settings#mode for information about Xdebug modes.
-</pre>
-### `caweb stop`  
-<pre>
-caweb stop
-
-Stops running WordPress for development and tests and frees the ports.
-
-Options:
-  --debug    Enable debug output.                     [boolean] [default: false]
-</pre>
-### `caweb clean [environment]`  
-<pre>
-caweb clean [environment]
-
-Cleans the WordPress databases.
-
-Positionals:
-  environment  Which environments' databases to clean.
-            [string] [choices: "all", "development", "tests"] [default: "tests"]
-
-Options:
-  --debug    Enable debug output.                     [boolean] [default: false]
-  --scripts  Execute any configured lifecycle scripts. [boolean] [default: true]
-</pre>
-### `caweb run <container> [command...]`  
-<pre>
-caweb run &lt;container&gt; [command...]
-
-Runs an arbitrary command in one of the underlying Docker containers. A double
-dash can be used to pass arguments to the container without parsing them. This
-is necessary if you are using an option that is defined below. You can use
-`bash` to open a shell session and both `composer` and `phpunit` are available
-in all WordPress and CLI containers. WP-CLI is also available in the CLI
-containers.
-
-Positionals:
-  container  The underlying Docker service to run the command on.
-              [string] [required] [choices: "mysql", "tests-mysql", "wordpress",
-                                          "tests-wordpress", "cli", "tests-cli"]
-  command    The command to run.                           [array] [default: []]
-
-Options:
-  --debug    Enable debug output.                     [boolean] [default: false]
-  --env-cwd  The command's working directory inside of the container. Paths
-             without a leading slash are relative to the WordPress root.
-                                                         [string] [default: "."]
-</pre>
-### `caweb destroy`  
-<pre>
-caweb destroy
-
-Destroy the WordPress environment. Deletes docker containers, volumes, and
-networks associated with the WordPress environment and removes local files.
-
-Options:
-  --debug    Enable debug output.                     [boolean] [default: false]
-  --scripts  Execute any configured lifecycle scripts. [boolean] [default: true]
-</pre>
-### `caweb logs [environment]`  
-<pre>
-caweb logs [environment]
-
-displays PHP and Docker logs for given WordPress environment.
-
-Positionals:
-  environment  Which environment to display the logs from.
-      [string] [choices: "development", "tests", "all"] [default: "development"]
-
-Options:
-  --debug    Enable debug output.                     [boolean] [default: false]
-  --watch    Watch for logs as they happen.            [boolean] [default: true]
-</pre>
-### `caweb install-path`  
-<pre>
-caweb install-path
-
-Get the path where all of the environment files are stored. This includes the
-Docker files, WordPress, PHPUnit files, and any sources that were downloaded.
-
-Options:
-  --debug    Enable debug output.                     [boolean] [default: false]
-</pre>
-### `caweb shell [environment]`  
-<pre>
-caweb shell [environment]
-
-Open shell terminal in WordPress environment.
-
-Positionals:
-  environment  Which environment to open terminal in.
-             [string] [choices: "development", "tests"] [default: "development"]
-
-Options:
-  --debug    Enable debug output.                     [boolean] [default: false]
-</pre>
-### `caweb update-plugins [environment]`  
-<pre>
-caweb update-plugins [environment]
-
-Updates all plugins in the WordPress environment.
-
-Positionals:
-  environment  Which environment to update.
-             [string] [choices: "development", "tests"] [default: "development"]
-
-Options:
-  --debug    Enable debug output.                     [boolean] [default: false]
-</pre>
-
-### `caweb create-block [options] <slug>`  
-<pre>
-caweb create-block [options] &lt;slug&gt;
-
-Scaffold for WordPress plugin to register CA.gov Design System Block.
-
-Arguments:
-  slug           Plugin slug to use.
-
-Options:
-  -h, --help     display help for command
-</pre>
-### `caweb update-block [options] <slug>`  
-<pre>
-caweb update-block [options] &lt;slug&gt;
-
-Updates a CA.gov Design System Block.
-
-Arguments:
-  slug           Plugin slug to update.
-
-Options:
-  -h, --help     display help for command
-</pre>
-### `caweb sync <from> <to>`  
-In order for the sync process to work correctly, you must have a caweb.json file in the project root directory. For more information read [caweb.json](./docs/SYNC.MD) configuration.
-<pre>
-caweb sync &lt;from&gt; &lt;to&gt;
-
-Sync changes from one destination to another.
-
-Arguments:
-  from               Target Site URL with current changes.
-  to                 Destination Site URL that should be synced.
-
-Options:
-  -h, --help         display help for command
-  -i, --include [include...]     IDs to of taxonomies to include. Omitting this option will sync all items for given taxonomy.
-  -t, --tax [tax...]  Taxonomy that should be synced. Omitting this option will sync the full site. (choices: "pages", "posts", "media", "menus")
-</pre>
+- Allows for generation of  WordPress CSS Audits 
+- Allows for IBM Accessibility Scan reports.

package/bin/css-audit/.editorconfig

@@ -0,0 +1,12 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = tab
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/bin/css-audit/.github/workflows/build-report.yml

@@ -0,0 +1,46 @@
+name: Build Report
+on:
+  push:
+    branches:
+      # Run only on pushes to report
+      - report
+  schedule:
+    # Run every day at 9am UTC.
+    # * is a special character in YAML so you have to quote this string
+    - cron:  '0 9 * * *'
+  workflow_dispatch:
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout CSS Audit
+      uses: actions/checkout@v2
+      with:
+        ref: report
+    - name: Checkout WordPress Core
+      uses: actions/checkout@v2
+      with:
+        repository: WordPress/wordpress-develop
+        path: wordpress
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v1
+      with:
+        node-version: 14.x
+
+    - name: Install dependencies
+      run: npm install
+
+    - name: Build the audit report
+      run: npm run css-audit -- wordpress/src/wp-admin/css/*.css wordpress/src/wp-includes/css/*.css
+
+    - name: Commit changes
+      uses: EndBug/add-and-commit@v5
+      with:
+        author_name: github-actions
+        author_email: 41898282+github-actions[bot]@users.noreply.github.com
+        message: "[Automated] Update report"
+        branch: "report"
+        add: "public"
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/bin/css-audit/.github/workflows/merge-trunk-to-report.yml

@@ -0,0 +1,17 @@
+name: Merge trunk into report branch
+on:
+  push:
+    branches:
+      # Run on pushes to trunk
+      - 'trunk'
+jobs:
+  merge-branch:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Merge trunk -> report
+        uses: devmasx/merge-branch@v1.3.1
+        with:
+          type: now
+          target_branch: report
+          github_token: ${{ secrets.GITHUB_TOKEN }}

package/bin/css-audit/.github/workflows/node.yaml

@@ -0,0 +1,32 @@
+name: Node.js CI
+
+on:
+  push:
+    paths:
+    - '**.js'
+  pull_request:
+    paths:
+    - '**.js'
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14.x]
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+
+    - run: npm install
+
+    - run: npm test
+      env:
+        CI: true

package/bin/css-audit/.nvmrc

@@ -0,0 +1 @@
+14

package/bin/css-audit/README.md

@@ -0,0 +1,131 @@
+# CSS Audit
+
+This project contains an automated audit of the core WordPress CSS, including the number of distinct colors used, most specific selectors, how many properties use `!important`, and more. [View the audit report here.](https://wordpress.github.io/css-audit/public/wp-admin) This report is regenerated every day at 09:00 UTC, and runs over the latest CSS in [WordPress/wordpress-develop](https://github.com/WordPress/wordpress-develop/).
+
+To generate this report, there is a tool `css-audit`, which runs a set of [audits](./src/audits).
+
+## Local Environment
+
+To run the audits yourself, download or clone this repo, then install the dependencies. You will need [node & npm](https://nodejs.org/en/) installed.
+
+```
+$ git clone git@github.com:wordpress/css-audit.git
+$ cd css-audit
+$ npm install
+$ npm run css-audit -- <files...>
+```
+
+If you want to work on the audits yourself, [fork this repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) to your account first. You can submit issues or PRs.
+
+## Running Audits
+
+To run the audits, you need a list of CSS files, and to indicate which audits you want to run. `yarn` and `npm` both automatically expand globs (`folder/*`), so you can use that, or pass in a list of CSS files. The audits are described below, and can be run via the following CLI args, or via configuration file (described in the next section).
+
+```
+$ npm run css-audit -- <files ...> [options]
+
+Usage: css-audit -- <files...> [options]
+
+--colors          Run colors audit.
+--important       Run !important audit.
+--display-none    Run display: none audit.
+--selectors       Run selectors audit.
+--media-queries   Run media queries audit.
+--property-values Run audit for a given set of property values, comma-separated.
+--recommended     Run recommended audits (colors, important, selectors). Default: true.
+--all             Run all audits (except property values, as it requires a value).
+--format          Format to use for displaying report.
+--filename        If using a format that outputs to a file, specify the file name.
+--help            Show this message.
+```
+
+
+### Configuration File
+
+The program will prioritize configuration from CLI arguments, and will fallback to configuration stored in a file called `css-audit.config.js`.
+
+```
+module.exports = {
+	format: 'json',
+	audits: [
+		'colors',
+		'important',
+		'display-none',
+		'selectors',
+		'media-queries',
+		[ 'property-values', 'font-size' ],
+		[ 'property-values', 'padding-top,padding-bottom' ],
+	],
+};
+```
+
+## Generating HTML Reports
+
+To generate an HTML report, use the `--format=html` option and specify a name for the file with the `--filename=name` option. This will output a `{name}.html` file in public/ that is viewable on Github Pages.
+
+For example, generating a report for wp-admin using the below strategy for pulling down CSS files from SVN:
+
+```
+npm run css-audit -- v5.5/**/* --format=html --all --filename=wp-admin
+```
+
+In the configuration file, the argument `filename` can be added as a simple property: value combination, the same as `format` in the example. See the [default `css-audit.config.js`](./css-audit.config.js).
+
+## Getting core CSS files
+
+You can download the source files of CSS (not minified or RTL'd) from the svn repository. The following code will create a new directory, `v5.5`, and download just the files from each `css` folder.
+
+```
+mkdir v5.5
+svn export https://develop.svn.wordpress.org/branches/5.5/src/wp-admin/css --depth files v5.5/admin
+svn export https://develop.svn.wordpress.org/branches/5.5/src/wp-includes/css --depth files v5.5/includes
+```
+
+If you want to run this on trunk (code currently in development), you can swap out `branches/5.5` for `trunk`. You could also swap the `5.5` for `5.4`, etc. Example:
+
+```
+mkdir trunk
+svn export https://develop.svn.wordpress.org/trunk/src/wp-admin/css --depth files trunk/admin
+svn export https://develop.svn.wordpress.org/trunk/src/wp-includes/css --depth files trunk/includes
+```
+
+Now you can run the audits:
+
+```
+npm run css-audit -- v5.5/**/* --recommended
+```
+
+## Available Audits
+
+- `colors`
+  - Number of unique colors — normalizes hex colors so that uppercase & lowercase are not counted twice
+  - Number of unique colors (ignoring opacity)
+  - List of all colors
+  - Top 10 most-used colors
+  - Top 10 least-used colors
+- `important`
+  - Number of times `!important` is used
+  - Top properties that use !important
+- `property-values` — needs a list of properties to inspect.
+  - Usage: `--property-values=[properties]`. For example: `--property-values=display`, or `--property-values=padding,margin`
+  - Number of unique values for [property]
+  - Top 10 most-used values for [property]
+  - Top 10 least-used values for [property]
+- `selectors`
+  - Total number of selectors
+  - Number of selectors with IDs — not "number of IDs", a lot of selectors use multiple IDs, but they'd only be counted once
+  - Top 10 selectors with the highest specificity
+  - Top 10 selectors by length
+- `display-none`
+  - Number of times `display: none` is used
+  - Places where `display: none` is used
+- `typography`
+  - A collection of information about various typography-related properties
+
+## Technical details
+
+This tool parses each CSS file and creates an AST, which the audits traverse to pull out data. It uses [`postcss`](https://postcss.org/) for most audits, but [`csstree`](https://github.com/csstree/csstree) for the `media-queries` audit. PostCSS gives us the plugins ecosystem so that we can use `postcss-values-parser`, while csstree generates a much more detailed AST that robustly identifies media queries.
+
+- [PostCSS API documentation](https://postcss.org/api/)
+- [csstree documentation](https://github.com/csstree/csstree/tree/master/docs)
+- [AST Explorer](https://astexplorer.net/) — great tool for identifying how the CSS is parsed.

package/bin/css-audit/css-audit.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+	format: 'html',
+	filename: 'wp-admin',
+	audits: [
+		'colors',
+		'alphas',
+		'important',
+		'display-none',
+		'selectors',
+		'media-queries',
+		'typography',
+	],
+};

package/bin/css-audit/index.js

@@ -0,0 +1,38 @@
+/**
+ * Node dependencies
+ */
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * Internal dependencies
+ */
+const { runAudits } = require( './src/run' );
+const { getArg, getFileArgsFromCLI, getHelp } = require( './src/utils/cli' );
+
+const input = getFileArgsFromCLI();
+
+if ( getArg( '--help', true ) || ! input.length ) {
+	console.log( getHelp() );
+	process.exit( 0 );
+}
+
+const cssFiles = [];
+input.forEach( ( file ) => {
+	const filePath = path.resolve( process.env.INIT_CWD, file );
+	const stats = fs.statSync( filePath );
+	if ( stats.isDirectory() ) {
+		return;
+	}
+	if ( file.match( /min\.css$/ ) ) {
+		return;
+	}
+	cssFiles.push( {
+		name: file,
+		content: String( fs.readFileSync( filePath ) ),
+	} );
+} );
+
+const result = runAudits( cssFiles );
+
+console.log( result );