Hook Reference: Automate a reference resource

.eslintrc.js

@@ -9,7 +9,7 @@ module.exports = {
 		'@wordpress/valid-sprintf': 'warn',
 		'jsdoc/check-tag-names': [
 			'error',
-			{ definedTags: [ 'jest-environment' ] },
+			{ definedTags: [ 'jest-environment', 'hook' ] },
 		],
 		'import/no-extraneous-dependencies': 'warn',
 		'import/no-unresolved': 'warn',

bin/hook-reference/data.js

@@ -0,0 +1,73 @@
+const { readFile } = require( 'fs' ).promises;
+const exec = require( 'await-exec' );
+const { parse } = require( 'comment-parser/lib' );
+const { relative, resolve } = require( 'path' );
+const chalk = require( 'chalk' );
+
+const getHooks = ( parsedData ) =>
+	parsedData.filter( ( docBlock ) =>
+		docBlock.tags.some( ( tag ) => tag.tag === 'hook' )
+	);
+
+const getSourceFile = ( file, commit, { source } ) => {
+	const first = source[ 0 ].number + 1;
+	const last = source[ source.length - 1 ].number + 1;
+
+	return `https://github.com/woocommerce/woocommerce-admin/blob/${ commit }/${ file }#L${ first }-L${ last }`;
+};
+
+const logProgress = ( fileName, { tags } ) => {
+	const hook = tags.find( ( tag ) => tag.tag === 'hook' );
+	console.log(
+		chalk.cyan( `${ hook.name } ` ) +
+			chalk.yellow( 'generated in ' ) +
+			chalk.yellow.underline( fileName )
+	);
+};
+
+const addSourceFiles = async ( hooks, fileName ) => {
+	const { stdout } = await exec( 'git log --pretty="format:%H" -1' );
+	const commit = stdout.trim();
+
+	return hooks.map( ( hook ) => {
+		logProgress( fileName, hook );
+		hook.sourceFile = getSourceFile( fileName, commit, hook );
+		return hook;
+	} );
+};
+
+const prepareHooks = async ( path ) => {
+	const data = await readFile( path, 'utf-8' ).catch( ( err ) =>
+		console.error( 'Failed to read file', err )
+	);
+	const fileName = relative( resolve( __dirname, '../../' ), path );
+
+	const parsedData = parse( data );
+	const rawHooks = getHooks( parsedData );
+	return await addSourceFiles( rawHooks, fileName );
+};
+
+const makeDocObjects = async ( path ) => {
+	const hooks = await prepareHooks( path );
+	return hooks.map( ( { description, tags, sourceFile } ) => {
+		const example = tags.find( ( tag ) => tag.tag === 'example' );
+		const hook = tags.find( ( tag ) => tag.tag === 'hook' );
+		return {
+			description,
+			sourceFile,
+			name: hook ? hook.name : '',
+			example: example ? example.description : '',
+		};
+	} );
+};
+
+const createData = async ( paths ) => {
+	const data = await Promise.all(
+		paths.map( async ( path ) => {
+			return await makeDocObjects( path );
+		} )
+	);
+	return data.flat();
+};
+
+module.exports = createData;

bin/hook-reference/data.json

@@ -0,0 +1,8 @@
+[
+    {
+        "description": "List of homepage stats enabled by default",
+        "sourceFile": "https://github.com/woocommerce/woocommerce-admin/blob/ff1a3cb2f3857cfa759fb3c93cedfe630dbd5510/client/homescreen/stats-overview/defaults.js#L5-L16",
+        "name": "woocommerce_admin_homepage_default_stats",
+        "example": "addFilter( 'woocommerce_admin_homepage_default_stats', 'plugin-domain', ( defaultStats ) => defaultStats.filter( ( stat ) => stat !== 'jetpack/stats/views' ) );"
+    }
+]

bin/hook-reference/index.js

@@ -0,0 +1,39 @@
+const fs = require( 'fs' );
+const { stat, readdir, writeFile } = require( 'fs' ).promises;
+const { resolve } = require( 'path' );
+const createData = require( './data' );
+const chalk = require( 'chalk' );
+
+async function getFilePaths( dir ) {
+	const subdirs = await readdir( dir );
+	const files = await Promise.all(
+		subdirs.map( async ( subdir ) => {
+			const res = resolve( dir, subdir );
+			return ( await stat( res ) ).isDirectory()
+				? getFilePaths( res )
+				: res;
+		} )
+	);
+	return files.reduce( ( a, f ) => a.concat( f ), [] );
+}
+
+const writeJSONFile = async ( data ) => {
+	const fileName = 'bin/hook-reference/data.json';
+	const stringifiedData = JSON.stringify( data, null, 4 );
+	await writeFile( fileName, stringifiedData + '\n' );
+
+	console.log( '\n' );
+	console.log(
+		chalk.greenBright(
+			'A new Hook Reference data source has been created. See `/bin/hook-reference/data.json` and be sure to commit changes.'
+		)
+	);
+};
+
+console.log( chalk.green( 'Preparing Hook Reference data file' ) );
+console.log( '\n' );
+
+getFilePaths( 'client' )
+	.then( ( paths ) => createData( paths ) )
+	.then( ( data ) => writeJSONFile( data ) )
+	.catch( ( e ) => console.error( e ) );

client/homescreen/stats-overview/defaults.js

@@ -2,7 +2,18 @@
  * External dependencies
  */
 import { applyFilters } from '@wordpress/hooks';
-
+/**
+ * List of homepage stats enabled by default
+ *
+ * @hook woocommerce_admin_homepage_default_stats
+ * @example
+ * addFilter(
+ *	'woocommerce_admin_homepage_default_stats',
+ *	'plugin-domain',
+ *	( defaultStats ) =>
+ *		defaultStats.filter( ( stat ) => stat !== 'jetpack/stats/views' )
+ *);
+ */
 export const DEFAULT_STATS = applyFilters(
 	'woocommerce_admin_homepage_default_stats',
 	[

package.json

@@ -77,7 +77,8 @@
 		"build-storybook": "build-storybook  -c ./storybook",
 		"changelog": "node ./bin/changelog --changelogSrcType='ZENHUB_RELEASE'",
 		"bump-version": "npm run -s install-if-deps-outdated && php ./bin/update-version.php",
-		"wp-env-mysql-port": "node ./docker/wc-admin-wp-env/mysql-port.js"
+		"wp-env-mysql-port": "node ./docker/wc-admin-wp-env/mysql-port.js",
+		"create-hook-reference": "node ./bin/hook-reference/index.js"
 	},
 	"changelog": {
 		"labelPrefix": "[Type]",
@@ -176,11 +177,13 @@
 		"@wordpress/scripts": "12.6.1",
 		"ast-types": "0.14.2",
 		"autoprefixer": "10.2.4",
+		"await-exec": "^0.1.2",
 		"babel-jest": "26.6.3",
 		"babel-loader": "8.2.2",
 		"babel-plugin-transform-class-properties": "6.24.1",
 		"babel-plugin-transform-es2015-template-literals": "6.22.0",
 		"chalk": "4.1.0",
+		"comment-parser": "^1.1.2",
 		"concurrently": "5.3.0",
 		"config": "3.3.6",
 		"copy-webpack-plugin": "5.1.1",

readme.txt

@@ -122,6 +122,7 @@ Release and roadmap notes are available on the [WooCommerce Developers Blog](htt
 - Add: CES survey for importing products #6419
 - Add: CES survey for adding product categories, tags, and attributes #6418
 - Add: Include tracking for mail poet installs in the selective bundle install #6603
+- Dev: Add script automation for gathering hooks and filters. #6454
 
 == 2.1.3 3/14/2021  ==