newspack-scripts 5.5.1-alpha.3 → 5.5.2

package/README.md

@@ -6,12 +6,11 @@ Scripts for Newspack, heavily inspired by [`react-scripts`](https://github.com/f
 
 ## Available scripts
 
-### test
+Repos consuming the `newspack-scripts` package can use the following NPM scripts. Prefix each at the command line with `npm run` (or [`bun run`](https://bun.sh/)) to execute.
 
-Will run `jest` tests. Useful flags:
+### start
 
-- `--watch` to run in file watch mode,
-- `--coverage` to collect test coverage
+Execute with `npm start`. This is the only script you run without the `run` prefix. This will install Composer and NPM dependencies, then run the `watch` command to start a development build. Best used when cloning a repo for the first time, or when you need to restore a locally cloned repo to a fresh state.
 
 ### build
 
@@ -21,6 +20,33 @@ Will run `wp-scripts build` to create optimised production builds.
 
 Will run `wp-scripts start` to start a development build in devserver/watch mode.
 
+### lint:js, lint:scss, lint
+
+Will run `wp-scripts lint-js`, `wp-scripts lint-style`, or both. See the [`@wordpress/scripts` handbook](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) for implementation details and additional options.
+
+### fix:js
+
+Will run `wp-scripts lint-js --fix`, allowing ESLint to correct any autofixable code quality errors it finds. Note that code quality errors are separate from formatting, which is handled by `format:js` (see below).
+
+### format:js
+
+Will run `wp-scripts format-js` to reformat JS files according to [Prettier](https://prettier.io/) rules. Note that formatting is separate from code quality errors, which are handled by `fix:js` (see above).
+
+### format:scss
+
+Will run `wp-scripts lint-style --fix` to reformat SCSS files according to [Stylelint](https://stylelint.io/) rules.
+
+### test
+
+Will run `jest` tests. Useful flags:
+
+- `--watch` to run in file watch mode,
+- `--coverage` to collect test coverage
+
+### lint:php, fix:php
+
+Will run `phpcs` or `phpcbf` to lint or autofix PHP files, respectively. Note that you must install these PHP packages via `composer install` or `npm start` before you can use these locally.
+
 ### commit
 
 Uses [`commitizen`](https://www.npmjs.com/package/commitizen) to create a structured commit message.
@@ -39,23 +65,18 @@ Will validate TypeScript code in the project. This requires a `tsconfig.json` fi
 
 ```json
 {
-  "extends": "newspack-scripts/config/tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src"
-  },
-  "include": ["src"]
+	"extends": "newspack-scripts/config/tsconfig.json",
+	"compilerOptions": {
+		"rootDir": "src",
+		"jsx": "react-jsx"
+	},
+	"include": [
+		"src",
+		"src/**/*.json"
+	]
 }
 ```
 
-### proxy
-
-Allows you to proxy NPM CLI commands through this repository's dependencies, so if a repository consumes the `newspack-scripts` NPM package, it can access any executables installed as a dependency in [package.json](https://github.com/Automattic/newspack-scripts/blob/trunk/package.json). e.g. `newspack-scripts proxy semantic-release --dry-run` will run `semantic-release --dry-run` but using the executable from `newspack-scripts` instead of whatever repository you're running the command from. This allows for more flexible use of NPM commands where the prefab configs and scripts this repo provides are too opinionated or aren't sufficient.
-
-Other examples:
-
-- `newspack-scripts proxy eslint 'src/**/*.{js,jsx,ts,tsx}'` will lint all JS/JSX/TS/TSX files inside the `./src` directory.
-- `newspack-scripts proxy stylelint 'src/**/*.scss'` will lint all SCSS files inside the `./src` directory.
-
 ---
 
 ## Semantic Release
@@ -124,12 +145,11 @@ The `webpack.config.js` file should use this package's config-extending function
 const getBaseWebpackConfig = require("newspack-scripts/config/getWebpackConfig");
 
 const webpackConfig = getBaseWebpackConfig(
-  { WP: true },
-  {
-    entry: {
-      "some-script": "./src/some-script.js",
-    },
-  }
+	{
+		entry: {
+			'output-file': './src/entrypoint-file.js',
+		},
+	}
 );
 
 module.exports = webpackConfig;
@@ -140,36 +160,69 @@ module.exports = webpackConfig;
 A basic `babel.config.js`:
 
 ```js
-module.exports = (api) => {
-  api.cache(true);
-  return {
-    extends: "newspack-scripts/config/babel.config.js",
-  };
+module.exports = api => {
+	api.cache( true );
+	return {
+		extends: 'newspack-scripts/config/babel.config.js',
+	};
+};
+```
+
+### ESLint
+
+`@wordpress/scripts` uses ESLint under the hood for JS code quality linting. Note that this is separate from code formatting, which is handled by Prettier (see below).
+
+Because of ESLint's [issue](https://github.com/eslint/eslint/issues/3458) with resolving dependencies of extended configurations, a patch has to be used to use this config in a stand-alone fashion: install `@rushstack/eslint-patch` and set up the `.eslintrc.js` like so:
+
+```js
+require( '@rushstack/eslint-patch/modern-module-resolution' );
+
+module.exports = {
+	extends: [ './node_modules/newspack-scripts/config/eslintrc.js' ],
+	// Additional options…
 };
 ```
 
-### eslint
+### Prettier
+
+`@wordpress/scripts` uses [Prettier](https://prettier.io/) under the hood for JS formatting. Note that this is separate from code quality, which is handled by ESLint (see above).
 
-Because of eslint's [issue](https://github.com/eslint/eslint/issues/3458) with resolving dependencies of extended configurations, a patch has to be used to use this config in a stand-alone fashion: install `@rushstack/eslint-patch` and set up the `.eslintrc.js` like so:
+To configure Prettier rules, extend this repo's config by creating a `.prettierrc.js` file like so:
 
 ```js
-require("@rushstack/eslint-patch/modern-module-resolution");
+const baseConfig = require( './node_modules/newspack-scripts/config/prettier.config.js' );
 
 module.exports = {
-  extends: ["./node_modules/newspack-scripts/config/eslintrc.js"],
-  // Additional options…
+	...baseConfig,
+	// Additional options…
 };
 ```
 
+You should also include a [`.prettierignore` file](https://prettier.io/docs/en/ignore.html) to tell Prettier which files and directories it should ignore, using [gitignore syntax](https://git-scm.com/docs/gitignore#_pattern_format):
+
+```
+dist
+node_modules
+release
+vendor
+```
+
 ### stylelint
 
-Use this package's stylelint executable and config file when running it, e.g.:
+`@wordpress/scripts` uses [Stylelint](https://stylelint.io/) under the hood for SCSS linting and formatting.
 
 ```shell
-newspack-scripts proxy stylelint '**/*.scss' --customSyntax postcss-scss --config=./node_modules/newspack-scripts/config/stylelint.config.js
+newspack-scripts wp-scripts lint-style '**/*.scss' --customSyntax postcss-scss
 ```
 
-_Note: Due to issue with dependency resolving, you might end up a different version of `prettier` in project's `node_modules` and `node_modules/newspack-scripts/node_modules`. See https://github.com/Automattic/newspack-scripts/issues/1 for more information._
+Extend this repo's config with a `.stylelintrc.js` file like so:
+
+```js
+module.exports = {
+	extends: [ './node_modules/newspack-scripts/config/stylelint.config.js' ],
+	// Additional options…
+};
+```
 
 ### TypeScript
 
@@ -216,4 +269,4 @@ Note that before the first time updating you'll need to set the API key for Circ
 
 ### `@wordpress/*` packages
 
-This project list [`@wordpress/*` packages](https://github.com/WordPress/gutenberg/tree/trunk/packages) as dependencies in order to provide them to consumers. In a project using `@wordpress/scripts` (e.g. a consumer of `newspack-scripts`), the `@wordpress/*` packages are sourced from WP Core, not `node_modules`. The packages should be included in `node_modules`, though, to be available in other environments – notably when running tests. See [Dependency Extraction Webpack Plugin](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin) for more information.
+This project lists [`@wordpress/*` packages](https://github.com/WordPress/gutenberg/tree/trunk/packages) as dependencies in order to provide them to consumers. In a project using `@wordpress/scripts` (e.g. a consumer of `newspack-scripts`), the `@wordpress/*` packages are sourced from WP Core, not `node_modules`. The packages should be included in `node_modules`, though, to be available in other environments – notably when running tests. See [Dependency Extraction Webpack Plugin](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin) for more information.

package/bin/newspack-scripts.js

@@ -8,15 +8,12 @@ const [ scriptName, ...nodeArgs ] = process.argv.slice( 2 );
 if (
 	[
 		'test',
-		'build',
-		'watch',
 		'commit',
 		'commitlint',
-		'eslint',
-		'proxy',
-		'stylelint',
 		'release',
+		'semantic-release',
 		'typescript-check',
+		'wp-scripts',
 	].includes( scriptName )
 ) {
 	const result = spawn.sync(

package/config/eslintrc.js

@@ -1,14 +1,19 @@
 const wpRecommended = require.resolve( '@wordpress/eslint-plugin/configs/recommended' );
 const reactRecommended = require.resolve( '@wordpress/eslint-plugin/configs/react' );
 
-// Assume `@wordpress/*` packages are available. This is because `@wordpress/scripts` is using
-// Dependency Extraction Webpack Plugin to use core WP packages instead of those from
-// node_modules. The packages should still be part of the project (they are listed in this
-// project's package.json) so that they are available in testing environment.
-// More on this:
-// - https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin
-// - https://github.com/WordPress/gutenberg/issues/35630
-const GLOBALLY_AVAILABLE_PACKAGES = [ '@wordpress/.*' ];
+/**
+ *  Assume `@wordpress/*` packages are available. This is because `@wordpress/scripts` is using
+ * Dependency Extraction Webpack Plugin to use core WP packages instead of those from
+ * node_modules. The packages should still be part of the project (they are listed in this
+ * project's package.json) so that they are available in testing environment.
+ *
+ * More on this:
+ * - https: *www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin
+ * - https: *github.com/WordPress/gutenberg/issues/35630
+ *
+ * React is also included here as it's a peer dependency of @wordpress/scripts.
+ */
+const GLOBALLY_AVAILABLE_PACKAGES = [ '@wordpress/.*', 'react' ];
 
 module.exports = {
 	extends: [
@@ -16,8 +21,8 @@ module.exports = {
 		'plugin:import/warnings',
 		'plugin:@typescript-eslint/eslint-recommended',
 		'plugin:@typescript-eslint/recommended',
-		wpRecommended,
 		reactRecommended,
+		wpRecommended,
 	],
 	env: {
 		browser: true,
@@ -32,14 +37,13 @@ module.exports = {
 			},
 		},
 	},
-	ignorePatterns: [ 'dist/', 'node_modules/', 'scripts/' ],
-	parser: '@typescript-eslint/parser',
+	ignorePatterns: [ 'dist/', 'node_modules/', 'release/', 'scripts/', '/vendor' ],
 	rules: {
 		'arrow-parens': 'off',
 		camelcase: 'off',
-		'no-console': 'off',
+		// Disallow logging.
+		'no-console': 'error',
 		'no-mixed-operators': 'off',
-		'space-before-function-paren': 'off',
 		'wrap-iife': 'off',
 		// Some dependencies are injected by WP, and should not be declared in package.json (won't be used anyway).
 		// See https://github.com/WordPress/gutenberg/blob/e035f71/packages/dependency-extraction-webpack-plugin/README.md#behavior-with-scripts
@@ -62,13 +66,12 @@ module.exports = {
 		'@typescript-eslint/no-empty-function': 'off',
 		// Fail on unused vars.
 		'@typescript-eslint/no-unused-vars': 'error',
-		// Disallow logging.
-		'no-console': 'error',
 		// Handle the issue where no-shadow is a false positive when declaring TS enums.
 		// See https://github.com/typescript-eslint/typescript-eslint/issues/2483
 		'no-shadow': 'off',
 		'@typescript-eslint/no-shadow': 'error',
 		'@typescript-eslint/ban-ts-comment': 'warn',
 		'@typescript-eslint/no-explicit-any': 'warn',
+		'prettier/prettier': 'off', // We're mainly concerned about code quality rules, not formatting. npm run format:js can be used to reformat JS if desired.
 	},
 };

package/config/prettier.config.js

@@ -0,0 +1,6 @@
+const wpConfig = require( '@wordpress/prettier-config' );
+
+module.exports = {
+	...wpConfig,
+	arrowParens: 'avoid',
+};

package/config/stylelint.config.js

@@ -1,5 +1,7 @@
 module.exports = {
-	extends: [ 'stylelint-config-standard' ],
+	extends: [
+		'@wordpress/stylelint-config',
+	],
 	rules: {
 		'rule-empty-line-before': null,
 		'at-rule-empty-line-before': null,
@@ -26,7 +28,7 @@ module.exports = {
 				ignoreAnnotations: [ '/default/' ],
 			},
 		],
-		'media-query-no-invalid': null,
 		'media-feature-range-notation': null,
+		'max-line-length': null,
 	},
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "newspack-scripts",
-	"version": "5.5.1-alpha.3",
+	"version": "5.5.2",
 	"description": "",
 	"bin": {
 		"newspack-scripts": "./bin/newspack-scripts.js"
@@ -36,9 +36,10 @@
 		"@wordpress/icons": "^10.0.0",
 		"@wordpress/keycodes": "^4.0.0",
 		"@wordpress/plugins": "^7.0.0",
-		"@wordpress/scripts": "^28.0.0",
+		"@wordpress/prettier-config": "^4.1.0",
+		"@wordpress/scripts": "^28.1.0",
+		"@wordpress/stylelint-config": "^22.1.0",
 		"@wordpress/url": "^4.0.0",
-		"ajv": "^8.16.0",
 		"autoprefixer": "^10.4.19",
 		"commitizen": "^4.3.0",
 		"cross-spawn": "^7.0.3",
@@ -52,21 +53,14 @@
 		"postcss": "^8.4.38",
 		"postcss-focus-within": "^5.0.4",
 		"postcss-scss": "^4.0.9",
-		"prettier": "^3.3.2",
+		"prettier": "npm:wp-prettier@^3.0.3",
 		"semantic-release": "^19.0.5",
 		"semantic-release-version-bump": "^1.4.1",
-		"stylelint": "^16.6.1",
-		"stylelint-config-standard": "^36.0.0",
+		"stylelint": "^14.2.0",
 		"typescript": "^5.4.5",
 		"yargs": "^17.7.2"
 	},
 	"overrides": {
-		"@eslint/eslintrc": {
-			"ajv": "^6.0.0"
-		},
-		"terser-webpack-plugin": {
-			"ajv": "^6.0.0"
-		},
 		"history": "4.9.0",
 		"path-to-regexp": "1.7.0"
 	},
@@ -88,5 +82,6 @@
 	},
 	"browserslist": [
 		"extends @wordpress/browserslist-config"
-	]
+	],
+	"prettier": "@wordpress/prettier-config"
 }

package/scripts/commitlint.js

@@ -2,9 +2,10 @@
 
 const spawn = require( 'cross-spawn' );
 const path = require( 'path' );
+const commitlint = require.resolve( '@commitlint/cli/cli' );
 
 const result = spawn.sync(
-	`${ process.cwd() }/node_modules/.bin/commitlint`,
+	commitlint,
 	[ '--config', path.resolve( __dirname, '../config/commitlint.config.js' ) ],
 	{
 		stdio: 'inherit',

package/scripts/release.js

@@ -18,8 +18,22 @@ if ( shouldPublishOnNPM ) {
 	utils.log( `Will publish on npm` );
 }
 
-const getConfig = ( { gitBranchName } ) => {
-	const branchType = gitBranchName.split( '/' )[ 0 ];
+const getConfig = ({ gitBranchName }) => {
+	const branchType = gitBranchName.split("/")[0];
+	const githubConfig = {
+		assets: [
+			{
+				path: `./release/${process.env.CIRCLE_PROJECT_REPONAME}.zip`,
+				label: `${process.env.CIRCLE_PROJECT_REPONAME}.zip`,
+			},
+		],
+	};
+
+	// Only post GH PR comments for alpha, hotfix/*, and release branches.
+	if ( ! ["alpha", "hotfix", "release"].includes(branchType) ) {
+		githubConfig.successComment = false;
+		githubConfig.failComment = false;
+	}
 
 	const config = {
 		dryRun: otherArgs.dryRun,
@@ -28,52 +42,43 @@ const getConfig = ( { gitBranchName } ) => {
 
 		branches: [
 			// `release` branch is published on the main distribution channel (a new version on GH).
-			'release',
+			"release",
 			// `alpha` branch – for regular pre-releases.
 			{
-				name: 'alpha',
+				name: "alpha",
 				prerelease: true,
 			},
 			// `hotfix/*` branches – for releases outside of the release schedule.
 			{
-				name: 'hotfix/*',
+				name: "hotfix/*",
 				// With `prerelease: true`, the `name` would be used for the pre-release tag. A name with a `/`
 				// is not valid, though. See https://semver.org/#spec-item-9.
 				prerelease: '${name.replace(/\\//g, "-")}',
 			},
 			// `epic/*` branches – for beta testing/QA pre-release builds.
 			{
-				name: 'epic/*',
+				name: "epic/*",
 				// With `prerelease: true`, the `name` would be used for the pre-release tag. A name with a `/`
 				// is not valid, though. See https://semver.org/#spec-item-9.
 				prerelease: '${name.replace(/\\//g, "-")}',
 			},
 		],
-		prepare: [ '@semantic-release/changelog', '@semantic-release/npm' ],
+		prepare: ["@semantic-release/changelog", "@semantic-release/npm"],
 		plugins: [
-			'@semantic-release/commit-analyzer',
-			'@semantic-release/release-notes-generator',
+			"@semantic-release/commit-analyzer",
+			"@semantic-release/release-notes-generator",
 			[
 				// Whether to publish on npm.
-				'@semantic-release/npm',
+				"@semantic-release/npm",
 				{
 					npmPublish: shouldPublishOnNPM,
 				},
 			],
-			'semantic-release-version-bump',
+			"semantic-release-version-bump",
 			// Add the built ZIP archive to GH release.
 			[
-				'@semantic-release/github',
-				{
-					assets: [
-						{
-							path: `./release/${ process.env.CIRCLE_PROJECT_REPONAME }.zip`,
-							label: `${ process.env.CIRCLE_PROJECT_REPONAME }.zip`,
-						},
-					],
-					// Only post GH PR comments for alpha, hotfix/*, and release branches.
-					successComment: [ 'alpha', 'hotfix', 'release' ].includes( branchType ),
-				},
+				"@semantic-release/github",
+				githubConfig,
 			],
 		],
 	};
@@ -109,7 +114,7 @@ const getConfig = ( { gitBranchName } ) => {
 			path: '@semantic-release/git',
 			assets,
 			message:
-        'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
+				'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
 		} );
 	} else {
 		utils.log(

package/scripts/semantic-release.js

@@ -0,0 +1,25 @@
+/**
+ * A proxy for the semantic-release executable.
+ * Note: most Newspack repos use the `release` script.
+ * Only newspack-theme currently uses this script.
+ */
+
+'use strict';
+
+const spawn = require( 'cross-spawn' );
+const utils = require( './utils/index.js' );
+const sr = require.resolve( 'semantic-release/bin/semantic-release' );
+
+utils.log( 'Starting TypeScript check…' );
+
+const args = process.argv.slice( 2 ) || [];
+
+const result = spawn.sync( sr, args, {
+	stdio: 'inherit',
+} );
+
+if ( result.status === 0 ) {
+	utils.log( 'All good!' );
+}
+
+process.exit( result.status );

package/scripts/typescript-check.js

@@ -1,13 +1,12 @@
 'use strict';
 
 const spawn = require( 'cross-spawn' );
-const path = require( 'path' );
-const modules = require( './utils/modules' );
 const utils = require( './utils/index.js' );
+const tsc = require.resolve( 'typescript/bin/tsc' );
 
 utils.log( 'Starting TypeScript check…' );
 
-const result = spawn.sync( `${ process.cwd() }/node_modules/.bin/tsc`, [], {
+const result = spawn.sync( tsc, [], {
 	stdio: 'inherit',
 } );
 

package/scripts/utils/modules.js

@@ -4,18 +4,22 @@ const rootDirectory = fs.realpathSync( process.cwd() );
 
 module.exports = {
 	rootDirectory,
-	args: ( cmd, opts = [] ) => {
+	// Get webpack bundle args for `build` and `start` commands.
+	buildArgs: ( cmd, args = [] ) => {
+		if ( 'build' !== cmd && 'start' !== cmd ) {
+			return [ cmd, ...args ];
+		}
+
 		const defaults = [
-			cmd,
 			'--config',
 			'webpack.config.js',
 		];
 
 		// Default build path: ./dist
-		if ( ! opts.includes( '--output-path' ) ) {
+		if ( ! args.includes( '--output-path' ) ) {
 			defaults.push( '--output-path', 'dist' );
 		}
 
-		return [ ...defaults, ...opts ];
+		return [ cmd, ...defaults, ...args ];
 	},
 };

package/scripts/{build.js → wp-scripts.js}

@@ -5,18 +5,19 @@ const modules = require( './utils/modules' );
 const utils = require( './utils/index.js' );
 const wpScripts = require.resolve( '@wordpress/scripts/bin/wp-scripts' );
 
-utils.log( 'Starting to build…' );
-
 const args = process.argv.slice( 2 );
+const cmd = args.shift();
+
+utils.log( `Running ${ cmd }...` );
 
-const buildResult = spawn.sync( wpScripts, modules.args( 'build', args ), {
+const result = spawn.sync( wpScripts, modules.buildArgs( cmd, args ), {
 	cwd: modules.rootDirectory,
 	stdio: 'inherit',
-	env: { ...process.env, NODE_ENV: 'production' },
+	env: { ...process.env, NODE_ENV: 'build' === cmd ? 'production' : 'development' },
 } );
 
-if ( buildResult.status === 0 ) {
-	utils.log( 'Build succeeded!' );
+if ( result.status === 0 ) {
+	utils.log( `${ cmd } complete!` );
 }
 
-process.exit( buildResult.status );
+process.exit( result.status );

package/src/jobs/lint-js-scss.yml

@@ -1,5 +1,5 @@
 description: >
-  Lint the JS & SCSS files.
+  Lint the JS & SCSS (temporarily skipped) files.
 
 executor: default
 
@@ -8,4 +8,4 @@ steps:
   - set_node_version
   - run:
       name: Run Linter
-      command: npm run lint
+      command: npm run lint:js # Temporarily skip linting SCSS due to stylelint config updates. Remove :js when ready to re-enable linting of SCSS.

package/scripts/proxy.js

@@ -1,29 +0,0 @@
-'use strict';
-
-/**
- * Run a command via newspack-script's dependencies.
- * Usage: newspack-scripts proxy <command> [args]
- */
-
-const path = require( 'path' );
-const spawn = require( 'cross-spawn' );
-const modules = require( './utils/modules' );
-const utils = require( './utils/index.js' );
-
-const args = process.argv.slice( 2 );
-const dependency = args.shift();
-const cmd = path.resolve( __dirname, `../node_modules/.bin/${ dependency }` );
-
-utils.log( `Running command: ${ dependency } ${ args.join( ' ' ) }` );
-
-const result = spawn.sync(
-	cmd,
-	args,
-	{
-		cwd: modules.rootDirectory,
-		stdio: 'inherit',
-		env: { ...process.env, NODE_ENV: 'semantic-release' === cmd ? 'production' : 'development' },
-	}
-);
-
-process.exit( result.status );

package/scripts/watch.js

@@ -1,16 +0,0 @@
-'use strict';
-
-const spawn = require( 'cross-spawn' );
-const modules = require( './utils/modules' );
-const utils = require( './utils/index.js' );
-const wpScripts = require.resolve( '@wordpress/scripts/bin/wp-scripts' );
-
-utils.log( 'Starting to watch…' );
-
-const args = process.argv.slice( 2 );
-
-spawn.sync( wpScripts, modules.args( 'start', args ), {
-	cwd: modules.rootDirectory,
-	stdio: 'inherit',
-	env: { ...process.env, NODE_ENV: 'development' },
-} );