@caweb/cli 1.4.2 → 1.4.3

package/README.md

@@ -31,7 +31,7 @@
 ### `caweb start`  
 Generates the required wp-env.json, starts the WordPress environment, downloads any CAWebPublishing sources and approved plugins.  
 <pre>
-caweb start [options]
+Usage: caweb start [options]
 
 Starts two CAWebPublishing WordPress instances
 development on port 8888 (​http://localhost:8888​) (override with WP_ENV_PORT)
@@ -52,7 +52,7 @@ Options:
 </pre>
 ### `caweb stop`  
 <pre>
-caweb stop
+Usage: caweb stop
 
 Stops running WordPress for development and tests and frees the ports.
 
@@ -61,7 +61,7 @@ Options:
 </pre>
 ### `caweb clean [environment]`  
 <pre>
-caweb clean [environment]
+Usage: caweb clean [environment]
 
 Cleans the WordPress databases.
 
@@ -75,7 +75,7 @@ Options:
 </pre>
 ### `caweb run <container> [command...]`  
 <pre>
-caweb run &lt;container&gt; [command...]
+Usage: 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
@@ -98,7 +98,7 @@ Options:
 </pre>
 ### `caweb destroy`  
 <pre>
-caweb destroy
+Usage: caweb destroy
 
 Destroy the WordPress environment. Deletes docker containers, volumes, and
 networks associated with the WordPress environment and removes local files.
@@ -109,7 +109,7 @@ Options:
 </pre>
 ### `caweb logs [environment]`  
 <pre>
-caweb logs [environment]
+Usage: caweb logs [environment]
 
 displays PHP and Docker logs for given WordPress environment.
 
@@ -123,7 +123,7 @@ Options:
 </pre>
 ### `caweb install-path`  
 <pre>
-caweb install-path
+Usage: 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.
@@ -133,7 +133,7 @@ Options:
 </pre>
 ### `caweb shell [environment]`  
 <pre>
-caweb shell [environment]
+Usage: caweb shell [environment]
 
 Open shell terminal in WordPress environment.
 
@@ -146,7 +146,7 @@ Options:
 </pre>
 ### `caweb update-plugins [environment]`  
 <pre>
-caweb update-plugins [environment]
+Usage: caweb update-plugins [environment]
 
 Updates all plugins in the WordPress environment.
 
@@ -160,7 +160,7 @@ Options:
 
 ### `caweb create-block [options] <slug>`  
 <pre>
-caweb create-block [options] &lt;slug&gt;
+Usage: caweb create-block [options] &lt;slug&gt;
 
 Scaffold for WordPress plugin to register CA.gov Design System Block.
 
@@ -172,7 +172,7 @@ Options:
 </pre>
 ### `caweb update-block [options] <slug>`  
 <pre>
-caweb update-block [options] &lt;slug&gt;
+Usage: caweb update-block [options] &lt;slug&gt;
 
 Updates a CA.gov Design System Block.
 
@@ -185,7 +185,7 @@ Options:
 ### `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;
+Usage: caweb sync &lt;from&gt; &lt;to&gt;
 
 Sync changes from one destination to another.
 
@@ -197,4 +197,30 @@ 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>
+### `caweb a11y <url>`  
+Runs accessibility checks.
+<pre>
+Usage: caweb a11y url
+
+Runs accessibility checks.
+
+Arguments:
+  url               URL or local file to scan for accessibility checks.
+
+Options:
+  -h, --help         display help for command
+</pre>
+### `caweb a11y <url>`  
+Runs WordPress CSS Audit tool against projects.
+<pre>
+Usage: caweb audit [options] [files...]
+
+Runs WordPress CSS Audit tool against projects.
+
+Arguments:
+  files          Files or directory path to CSS files. (default: "build")
+
+Options:
+  -h, --help         display help for command
 </pre>

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 );