Move tools/scripts/** to scripts

.husky/pre-commit

@@ -2,15 +2,15 @@
 # but not on CI:
 # https://typicode.github.io/husky/#/?id=with-env-variables
 if [ "$CI" != "true" ]; then
-    . ./tools/scripts/check-node-version
+    . ./scripts/check-node-version
 fi
 
 # keep docs up to date
-node tools/scripts/maintain-readme/index.mjs
+node scripts/maintain-readme/index.mjs
 git add README.md
 
 # keep makefile up to date
-node tools/scripts/maintain-makefile/index.mjs
+node scripts/maintain-makefile/index.mjs
 git add Makefile
 
 corepack pnpm lint-staged

Makefile

@@ -7,7 +7,7 @@ export SHELL := /usr/bin/env bash
 # lists available `make` targets
 .PHONY: ls
 ls:
-	@node tools/scripts/list-make-targets.mjs
+	@node scripts/list-make-targets.mjs
 
 
 ###################################### DEV #####################################
@@ -56,7 +56,7 @@ lint: env
 	$(call log,"Linting projects")
 	@corepack pnpm -r lint
 	@corepack pnpm lint:packages
-	@node ./tools/scripts/check-packages-for-tslib.mjs
+	@node ./scripts/check-packages-for-tslib.mjs
 
 # check repo for formatting errors
 .PHONY: formatting\:check
@@ -135,7 +135,7 @@ env: check-node-version install
 .PHONY: check-node-version # PRIVATE
 check-node-version:
 	$(call log,"Checking Node")
-	@./tools/scripts/check-node-version
+	@./scripts/check-node-version
 
 # Install dependencies. If deps are up to date this is almost instant, so we can
 # run before every other target with very little DX cost.
@@ -149,7 +149,7 @@ install: check-node-version
 
 # This is a set of all possible project-specific tasks.
 #
-# IT IS AUTOGENERATED BY tools/scripts/maintain-makefile/index.mjs
+# IT IS AUTOGENERATED BY scripts/maintain-makefile/index.mjs
 #
 # It enables running the relevant npm-scripts wrapped in the
 # standardised Makefile prerequisites.

README.md

@@ -12,7 +12,7 @@
 The following packages live in `libs/@guardian/*` and are published to NPM:
 
 <!-- START PUBLISHED_PACKAGES -->
-<!-- THIS CONTENT IS AUTOGENERATED BY tools/scripts/maintain-readme/index.mjs -->
+<!-- THIS CONTENT IS AUTOGENERATED BY scripts/maintain-readme/index.mjs -->
 
 - [@guardian/ab-core](libs/@guardian/ab-core)
 - [@guardian/ab-react](libs/@guardian/ab-react)
@@ -48,7 +48,7 @@ _You'll be prompted to install any missing requirements if they are needed..._
 Tasks that apply to all projects are defined in the [`Makefile`](./Makefile):
 
 <!-- START TASKS -->
-<!-- THIS CONTENT IS AUTOGENERATED BY tools/scripts/maintain-readme/index.mjs -->
+<!-- THIS CONTENT IS AUTOGENERATED BY scripts/maintain-readme/index.mjs -->
 
 - `make build` _builds all projects_
 - `make build-storybook` _builds all storybooks_

package.json

@@ -4,10 +4,10 @@
 	"private": "true",
 	"type": "module",
 	"scripts": {
-		"build": "./tools/scripts/use-make-instead",
+		"build": "./scripts/use-make-instead",
 		"lint:packages": "syncpack lint",
 		"prepare": "husky",
-		"test": "./tools/scripts/use-make-instead"
+		"test": "./scripts/use-make-instead"
 	},
 	"devDependencies": {
 		"@changesets/cli": "2.27.1",
@@ -19,21 +19,18 @@
 		"@types/node": "20.14.10",
 		"@typescript-eslint/eslint-plugin": "8.1.0",
 		"@typescript-eslint/parser": "8.1.0",
-		"colorette": "2.0.20",
 		"eslint": "8.57.0",
 		"eslint-plugin-eslint-comments": "3.2.0",
 		"eslint-plugin-import": "2.29.1",
 		"eslint-plugin-react": "7.35.0",
 		"eslint-plugin-react-hooks": "4.6.2",
 		"eslint-plugin-storybook": "0.8.0",
-		"fast-glob": "3.3.2",
 		"husky": "9.1.4",
 		"lint-staged": "15.2.0",
 		"prettier": "3.3.3",
 		"sort-package-json": "2.10.0",
 		"syncpack": "12.4.0",
 		"typescript": "5.5.2",
-		"update-section": "0.3.3",
 		"wireit": "0.14.4"
 	},
 	"packageManager": "[email protected]",

pnpm-workspace.yaml

@@ -3,6 +3,6 @@ packages:
   - 'libs/**'
   - '!**/libs/@guardian/source/*/**'
   - '!**/libs/@guardian/source-development-kitchen/*/**'
-  - 'tools/**'
+  - 'scripts/**'
   - 'configs/**'
   - 'coverage'

scripts/@types/update-section.d.ts

@@ -0,0 +1,11 @@
+declare module 'update-section' {
+	function updateSection(
+		content: string,
+		section: string,
+		matchesStart: (line: string) => boolean,
+		matchesEnd: (line: string) => boolean,
+		top?: boolean,
+	): string;
+
+	export default updateSection;
+}

tools/scripts/lib/get-tasks.mjs → scripts/lib/get-tasks-by-package.mjs

@@ -1,22 +1,21 @@
 import fastGlob from 'fast-glob';
-import { readFile } from 'fs/promises';
+import { readFile } from 'node:fs/promises';
 
 /**
- * Get all npm-scripts from all packages in `libs` and `apps`, and returns them
- * as a list of tuples, e.g.
- *
- * [
- * 	['my-app', ['build', 'test']],
- * 	['my-lib', ['start', 'build']],
- * 	...
- * ]
+ * @typedef {string[]} TaskList - e.g. ['build', 'test']
+ * @typedef {[string, TaskList]} PackageTasks - e.g. ['my-app', ['build', 'test']]
  */
-export const getTasks = async () => {
+
+/**
+ * Gets all npm-scripts from all packages in `libs` and `apps`.
+ */
+export const getTasksByPackage = async () => {
 	const packages = await fastGlob(['{libs,apps}/**/package.json'], {
 		followSymbolicLinks: false,
 		ignore: ['**/node_modules', '**/dist'],
 	});
 
+	/** @type PackageTasks[] */
 	const tasks = [];
 
 	for (const pkg of packages) {

tools/scripts/list-make-targets.mjs → scripts/list-make-targets.mjs

@@ -1,5 +1,5 @@
 import { getMakeTargets } from './lib/get-make-targets.mjs';
-import { getTasks } from './lib/get-tasks.mjs';
+import { getTasksByPackage } from './lib/get-tasks-by-package.mjs';
 
 const blue = '\x1b[34m';
 const dim = '\x1b[2m';
@@ -22,14 +22,22 @@ console.log(
 	`${orange}You can also run any of the individual project tasks by running ${blue}make <project>:<task>${reset}${orange}:${reset}`,
 );
 
-const tasks = await getTasks();
+const tasks = await getTasksByPackage();
 
 const taskList = [];
-for (const task of tasks) {
-	if (!taskList.at(-1)?.includes(task.split(':')[0])) {
-		taskList.push('');
+
+for (const tasksByPkg of tasks) {
+	const [pkg, scripts] = tasksByPkg;
+
+	for (const script of scripts) {
+		const makeTarget = `${pkg}:${script}`;
+
+		if (!taskList.at(-1)?.includes(`${pkg}:`)) {
+			taskList.push('');
+		}
+
+		taskList.push(`${blue}make ${makeTarget}${reset}`);
 	}
-	taskList.push(`${blue}make ${task}${reset}`);
 }
 
 console.log(taskList.join('\n'));

tools/scripts/maintain-makefile/index.mjs → scripts/maintain-makefile/index.mjs

@@ -2,18 +2,26 @@ import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { pathFromRoot, projectRoot } from '../project-paths.mjs';
-import { getTasks } from '../lib/get-tasks.mjs';
+import { getTasksByPackage } from '../lib/get-tasks-by-package.mjs';
 
 import _updateSection from 'update-section';
 
+/**
+ * @param {object} options
+ * @param {string} options.contents
+ * @param {string} options.updates
+ * @returns {string}
+ */
 const updateSection = ({ contents, updates }) => {
 	const START = `############################## START PROJECT_TASKS #############################`;
 	const END = `############################### END PROJECT_TASKS ##############################`;
 
+	/**	@param {string} line */
 	function matchesStart(line) {
 		return line.includes(START);
 	}
 
+	/**	@param {string} line */
 	function matchesEnd(line) {
 		return line.includes(END);
 	}
@@ -32,7 +40,7 @@ const thisFilePathFromRoot = pathFromRoot(thisFilePath);
 const makefilePath = path.resolve(projectRoot, 'Makefile');
 let contents = await readFile(makefilePath, 'utf8');
 
-const tasks = await getTasks();
+const tasks = await getTasksByPackage();
 
 const tasksList = [
 	'# This is a set of all possible project-specific tasks.',

tools/scripts/maintain-readme/index.mjs → scripts/maintain-readme/index.mjs

@@ -6,17 +6,28 @@ import { getPackageList } from './get-package-list.mjs';
 import { getMakeTargets } from '../lib/get-make-targets.mjs';
 import { format } from 'prettier';
 import prettierConfig from '@guardian/prettier';
-import { getTasks } from '../lib/get-tasks.mjs';
+import { getTasksByPackage } from '../lib/get-tasks-by-package.mjs';
 import _updateSection from 'update-section';
 
+/**
+ *
+ * @param {object} options
+ * @param {string} options.contents
+ * @param {string} options.tag
+ * @param {string} options.updates
+ * @param {string} options.updater
+ * @returns string
+ */
 const updateSection = ({ contents, tag, updates, updater }) => {
 	const START = `<!-- START ${tag} -->`;
 	const END = `<!-- END ${tag} -->`;
 
+	/**	@param {string} line */
 	function matchesStart(line) {
 		return line.includes(START);
 	}
 
+	/**	@param {string} line */
 	function matchesEnd(line) {
 		return line.includes(END);
 	}
@@ -54,7 +65,7 @@ const makeTargetsList = makeTargets
 	.map(({ target, description }) => `- \`make ${target}\` _${description}_`)
 	.join('\n');
 
-const tasks = await getTasks();
+const tasks = await getTasksByPackage();
 
 const tasksList = [
 	'### Project-specific tasks',

scripts/package.json

@@ -0,0 +1,9 @@
+{
+	"private": true,
+	"type": "module",
+	"dependencies": {
+		"colorette": "2.0.20",
+		"fast-glob": "3.3.2",
+		"update-section": "0.3.3"
+	}
+}

scripts/project-paths.mjs

@@ -0,0 +1,8 @@
+import path from 'node:path';
+
+export const projectRoot = path.resolve(import.meta.dirname, '..');
+
+/**
+ * @param {string} target
+ */
+export const pathFromRoot = (target) => path.relative(projectRoot, target);

scripts/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../tsconfig.base.json",
+	"compilerOptions": {
+		"checkJs": true
+	},
+	"include": ["**/*"],
+	"exclude": ["deno"]
+}