chore(tools): rework tools

Author: GerkinDev

tools/proto/package.json

@@ -12,7 +12,10 @@
     "email": "gerkin@knodes.org",
     "name": "GerkinDev"
   },
-  "keywords": ["typedoc","documentation"],
+  "keywords": [
+    "typedoc",
+    "documentation"
+  ],
   "main": "dist/index.js",
   "files": [
     "src",

tools/sync-proto-modules/package-json.js

@@ -1,17 +1,15 @@
-const assert = require( 'assert' );
-const { readFile, writeFile } = require( 'fs/promises' );
+const { readFile } = require( 'fs/promises' );
 const { resolve } = require( 'path' );
 
 const { memoize, cloneDeep, defaultsDeep, uniq } = require( 'lodash' );
 const semver = require( 'semver' );
-const { normalizePath } = require( 'typedoc' );
 
-const { readProjectPackageJson, getDocsUrl, assertDiffFile } = require( './utils' );
-const { formatPackages, resolveRoot } = require( '../utils' );
+const { syncFile, formatPackage, getDocsUrl } = require( './utils' );
+const { resolveRoot } = require( '../utils' );
 
 /**
  * @param {boolean} checkOnly
- * @returns {import('./utils').ProtoHandler<{getProtoPkg: (v: string) => string, rootJson: any, rootJsonStr: string, rootPath: string}}
+ * @returns {import('./utils').ProtoHandler<{getProtoPkg: (v: string) => Promise<string>, rootJson: any, rootJsonStr: string, rootPath: string}}
  */
 module.exports.packageJson = async checkOnly => ( {
 	setup: async () => {
@@ -21,27 +19,22 @@ module.exports.packageJson = async checkOnly => ( {
 		const rootJson = JSON.parse( rootJsonStr );
 		return { getProtoPkg, rootJson, rootJsonStr, rootPath };
 	},
-	run: async ( proto, { path: projectPath }, projects, _, { getProtoPkg, rootJson: rootPackageJson } ) => {
-		const { packageContent = {}, path: packagePath } = await readProjectPackageJson( projectPath ) ?? {};
+	run: async ( proto, { path: projectPath, pkgJsonPath, pkgJson }, projects, _, { getProtoPkg, rootJson: rootPackageJson } ) => {
 		const protoPkgContent = await getProtoPkg( proto );
 		const protoPkg = JSON.parse( protoPkgContent
 			.replace( /\{projectRelDir\}/g, projectPath )
-			.replace( /\{projectTypeDocUrl\}/g, getDocsUrl( packageContent ) ) );
-		const newProjectPkg = defaultsDeep( cloneDeep( protoPkg ), packageContent );
+			.replace( /\{projectTypeDocUrl\}/g, getDocsUrl( pkgJson ) ) );
+		const newProjectPkg = defaultsDeep( cloneDeep( protoPkg ), pkgJson );
 		[ 'keywords', 'files' ].forEach( prop => newProjectPkg[prop] = uniq( [
 			...( protoPkg[prop] ?? [] ),
-			...( packageContent[prop] ?? [] ),
+			...( pkgJson[prop] ?? [] ),
 		]
 			.map( k => k.toLowerCase() ) )
 			.sort() );
-		if( checkOnly ){
-			assert.deepStrictEqual( newProjectPkg, packageContent );
-		} else {
-			await writeFile( packagePath, JSON.stringify( newProjectPkg, null, 2 ) );
-		}
+		await syncFile( checkOnly, pkgJsonPath, await formatPackage( newProjectPkg ) );
 
 		rootPackageJson['devDependencies'] = rootPackageJson['devDependencies'] ?? {};
-		Object.entries( packageContent )
+		Object.entries( syncFile )
 			.filter( ( [ k ] ) => k.toLowerCase().includes( 'dependencies' ) )
 			.forEach( ( [ k, v ] ) => {
 				const rootPkgDeps = rootPackageJson['devDependencies'] ?? {};
@@ -64,22 +57,12 @@ module.exports.packageJson = async checkOnly => ( {
 				};
 			} );
 	},
-	tearDown: async( proto, projects, _, { rootJson: rootJson, rootJsonStr: rootJsonStr, rootPath } ) => {
+	tearDown: async( proto, projects, _, { rootJson, rootPath } ) => {
 		rootJson['devDependencies'] = {
 			...rootJson['devDependencies'],
 			...Object.fromEntries( projects.map( p => [ p.pkgName, `file:${p.path}` ] ) ),
 		};
-		await writeFile( rootPath, `${JSON.stringify( rootJson, null, 2 )  }\n` );
-		if( checkOnly ){
-			try {
-				await formatPackages( rootPath );
-				await assertDiffFile( rootPath, rootJsonStr, true );
-			} finally {
-				await writeFile( rootPath, rootJsonStr );
-			}
-		} else {
-			await formatPackages( rootPath, ...projects.map( p => normalizePath( resolve( p.path, 'package.json' ) ) ) );
-		}
+		await syncFile( checkOnly, rootPath, await formatPackage( rootJson ) );
 	},
 	handleFile: filename => /(\/|^)package\.json$/.test( filename ),
 } );

tools/sync-proto-modules/readme.js

@@ -1,28 +1,24 @@
 const { yellow } = require( 'chalk' );
 const { glob } = require( 'glob' );
 
-const { tryReadFile, getDocsUrl, readProjectPackageJson, syncFile } = require( './utils' );
+const { tryReadFile, getDocsUrl, syncFile } = require( './utils' );
 
 class Readme {
 	constructor( checkOnly ){
 		this.name = 'readme';
 		this.checkOnly = checkOnly;
 	}
 
-	async run( _proto, { path: projectPath } ){
+	async run( _proto, { path: projectPath, pkgJson } ){
 		const readmeFiles = await glob( `${projectPath}/@(readme|README).@(md|MD)` );
 		if( readmeFiles.length > 1 ){
 			throw new Error( 'Multiple README files' );
 		}
 		const readmeFile = readmeFiles[0] ?? `${projectPath}/README.md`;
 		const readmeContent = ( await tryReadFile( readmeFile, 'utf-8' ) ) ?? '';
-		const { packageContent } = await readProjectPackageJson( projectPath );
-		if( !packageContent ){
-			throw new Error();
-		}
 		const result = ( await [ this._replaceHeader, this._replaceInstall ].reduce( async ( content, fn ) => {
 			const c = await content;
-			return fn( c, packageContent );
+			return fn( c, pkgJson );
 		}, Promise.resolve( readmeContent ) ) ).replace( /\r\n/g, '\n' );
 		await syncFile( this.checkOnly, readmeFile, result );
 	}

tools/sync-proto-modules/sync-fs.js

@@ -1,14 +1,14 @@
 const assert = require( 'assert' );
 const { createHash } = require( 'crypto' );
-const { readFile, mkdir, access, copyFile, unlink, writeFile } = require( 'fs/promises' );
+const { readFile, mkdir, access, copyFile, unlink } = require( 'fs/promises' );
 
 const { resolve, join } = require( 'path' );
 
 const { bold } = require( 'chalk' );
 const { glob } = require( 'glob' );
 const { memoize, partition, isString } = require( 'lodash' );
 
-const { tryReadFile } = require( './utils' );
+const { syncFile, tryReadFile } = require( './utils' );
 
 const checksum = async file => createHash( 'md5' )
 	.update( ( await readFile( file, 'utf-8' ) ).replace( /\r?\n/g, '\n' ), 'utf-8' )
@@ -140,7 +140,7 @@ module.exports.syncFs = checkOnly => {
 				...cache,
 				...changed,
 			};
-			await writeFile( cacheFile, Object.entries( newCache )
+			await syncFile( checkOnly, cacheFile, Object.entries( newCache )
 				.filter( ( [ , v ] ) => isString( v ) )
 				.map( entry => entry.join( ' :: ' ) )
 				.join( '\n' ) );

tools/sync-proto-modules/typedoc-submodule.js

@@ -1,30 +1,46 @@
-const assert = require( 'assert' );
+const { resolve } = require( 'path' );
 
-const { spawn, captureStream, resolveRoot } = require( '../utils' );
+const { SemVer } = require( 'semver' );
+
+const { syncFile } = require( './utils/diff' );
+const { formatPackage } = require( './utils/package-json' );
+const { resolveRoot } = require( '../utils' );
+
+/**
+ * @param {boolean} checkOnly
+ * @param {SemVer} version
+ * @returns {<T extends {}>(pkg: T, path: string) => Promise<T>}
+ */
+const syncPkgTypedocVersion = ( checkOnly, version ) => async ( pkg, path ) => {
+	if( 'typedoc' in pkg.dependencies ){
+		pkg.dependencies.typedoc = `^${version.major}.${version.minor}.0`;
+	}
+	if( 'typedoc' in pkg.peerDependencies ){
+		pkg.peerDependencies.typedoc = `^${version.major}.${version.minor}.0`;
+	}
+	if( 'typedoc' in pkg.devDependencies ){
+		pkg.devDependencies.typedoc = `^${version.format()}`;
+	}
+	await syncFile( checkOnly, path, await formatPackage( pkg ) );
+	return pkg;
+};
 
 /**
  * @param {boolean} checkOnly
- * @returns {import('./utils').ProtoHandler}
+ * @returns {import('./utils').ProtoHandler<ReturnType<typeof syncPkgTypedocVersion>>}
  */
 module.exports.typedocSubmodule = async checkOnly => ( {
-	tearDown: async () => {
-		const typedocDir = resolveRoot( 'typedoc' );
-		const packageTypedoc = require( '../../package.json' ).devDependencies.typedoc.replace( /^\D*/, '' );
-		const submoduleTypedoc = ( await spawn(
-			'git',
-			[ '-C', typedocDir, 'describe', '--tags' ],
-			{ stdio: [ null, captureStream(), captureStream() ] } ) )
-			.stdout.trim().replace( /^v/, '' );
-		if( checkOnly ){
-			assert.equal( packageTypedoc, submoduleTypedoc, `The packages typedoc version ${packageTypedoc} does not match the submodule typedoc version ${submoduleTypedoc}` );
-		} else if( packageTypedoc !== submoduleTypedoc ){
-			console.log( 'Moving typedoc to the expected tag' );
-			await spawn(
-				'git',
-				[ '-C', typedocDir, 'fetch', '--tags' ] );
-			await spawn(
-				'git',
-				[ '-C', typedocDir, 'switch', `tags/v${packageTypedoc}`, '--detach' ] );
-		}
+	setup: async proto => {
+		const submoduleDir = resolveRoot( 'typedoc' );
+		const submoduleVersion = require( resolve( submoduleDir, 'package.json' ) ).version;
+		const doSync = syncPkgTypedocVersion( checkOnly, new SemVer( submoduleVersion ) );
+		const protoPkgPath = resolve( proto, 'package.json' );
+		const protoPkgJson = require( protoPkgPath );
+		await doSync( protoPkgJson, protoPkgPath );
+		return doSync;
+	},
+	run: async ( proto, project, projects, handlers, doSync ) => {
+		const syncedPkg = await doSync( project.pkgJson, project.pkgJsonPath );
+		Object.assign( project.pkgJson, syncedPkg );
 	},
 } );

tools/sync-proto-modules/utils/diff.js

@@ -1,9 +1,11 @@
 const { writeFile, readFile } = require( 'fs/promises' );
 
-const { bgRed, bgGreen, grey, bold } = require( 'chalk' );
+const { bgRed, bgGreen, grey, bold, bgGrey } = require( 'chalk' );
 const Diff = require( 'diff' );
 const { pad } = require( 'lodash' );
 
+const { relativeToRoot } = require( '../../utils' );
+
 const linesCount = str => ( str.match( /\n/g )?.length ?? 0 ) + 1;
 const formatNl = fn => ( str, newLine = true ) => fn( str === '' && newLine ? '↵' : str );
 
@@ -38,14 +40,17 @@ const getLinesDiff = ( { lines, color, printLine, sameLine, isAdd, totalLines0,
 	return lines.join( '\n' );
 };
 
+const errors = [];
 module.exports.assertDiffFile = async ( filename, expectedContent, invert = false ) => {
 	const actualContent = await readFile( filename, 'utf-8' );
 
-	const diff = Diff.diffWords( expectedContent, actualContent );
+	const diff = Diff.diffLines( expectedContent, actualContent );
 	if( diff.length === 1 ){
 		return;
 	}
 
+	console.log( bgGrey( relativeToRoot( filename ) ) );
+
 	let line = 1;
 	let lineDelta = 0;
 	let sameLine = false;
@@ -81,7 +86,13 @@ module.exports.assertDiffFile = async ( filename, expectedContent, invert = fals
 		}
 	} );
 	console.log();
-	throw new Error( `File ${filename} does not match the expected content` );
+	errors.push( new Error( `File ${filename} does not match the expected content` ) );
+};
+module.exports.summarizeErrors = () => {
+	if( errors.length ){
+		// eslint-disable-next-line no-undef -- Actually exists
+		throw new AggregateError( errors, 'Some files are incorrect' );
+	}
 };
 
 module.exports.syncFile = async ( checkOnly, filename, expectedContent ) => {

tools/sync-proto-modules/utils/index.js

@@ -1,7 +1,6 @@
 const assert = require( 'assert' );
 
 const { readFile } = require( 'fs/promises' );
-const { resolve } = require( 'path' );
 
 const SemVer = require( 'semver' );
 
@@ -36,24 +35,9 @@ module.exports.getDocsUrl = pkgJson => {
 	return `${docsUrl}/modules/${( pkgJson.name ?? assert.fail( 'No name' ) ).replace( /[^a-z0-9]/gi, '_' )}.html`;
 };
 
-module.exports.readProjectPackageJson = async projectPath => {
-	const projectPkgPath = resolve( projectPath, 'package.json' );
-	const content = await module.exports.tryReadFile( projectPkgPath );
-	if( content ){
-		return {
-			packageContent: JSON.parse( content ),
-			path: projectPkgPath,
-		};
-	} else {
-		return {
-			packageContent: undefined,
-			path: projectPkgPath,
-		};
-	}
-};
-
 module.exports = {
 	...module.exports,
 	...require( './yaml' ),
 	...require( './diff' ),
+	...require( './package-json' ),
 };

tools/sync-proto-modules/utils/package-json.js

@@ -0,0 +1,8 @@
+const format = require( 'format-package' ).default;
+
+module.exports.formatPackage = async content => {
+	if( typeof content === 'string' ){
+		content = JSON.parse( content );
+	}
+	return format( content, {} );
+};

tools/sync-proto-modules/utils/yaml.js

@@ -6,7 +6,7 @@ const { parseDocument: parseYamlDocument, visit, stringify: stringifyYaml, YAMLS
 const resolveRefFactory = ( anchorsMap, vars ) => ( ref, src ) => {
 	if( ref.startsWith( '*' ) ){
 		const node = anchorsMap[ref.slice( 1 )]?.clone() ??
-            assert.fail( `Missing alias "${ref}" in expression "${JSON.stringify( src )}"` );
+			assert.fail( `Missing alias "${ref}" in expression "${JSON.stringify( src )}"` );
 		node.anchor = undefined;
 		return {
 			'': () => stringifyYaml( node ).trim(),
@@ -18,7 +18,7 @@ const resolveRefFactory = ( anchorsMap, vars ) => ( ref, src ) => {
 		};
 	} else {
 		const val = vars[ref] ??
-            assert.fail( `Missing variable "${ref}" in expression "${JSON.stringify( src )}"` );
+			assert.fail( `Missing variable "${ref}" in expression "${JSON.stringify( src )}"` );
 		return {
 			'': () => val,
 			'!': () => val.toString(),

tools/sync-proto.js

@@ -9,6 +9,7 @@ const { packageJson } = require( './sync-proto-modules/package-json' );
 const { readme } = require( './sync-proto-modules/readme' );
 const { syncFs } = require( './sync-proto-modules/sync-fs' );
 const { typedocSubmodule } = require( './sync-proto-modules/typedoc-submodule' );
+const { summarizeErrors } = require( './sync-proto-modules/utils' );
 const { selectProjects, createStash } = require( './utils' );
 
 if( require.main === module ){
@@ -35,9 +36,9 @@ if( require.main === module ){
 			const initialValue = Promise.resolve( [] );
 			const handlers = await [
 				syncFs,
+				typedocSubmodule,
 				packageJson,
 				readme,
-				typedocSubmodule,
 				circleCi,
 				changelog,
 				issueTemplate,
@@ -55,6 +56,7 @@ if( require.main === module ){
 			for( const handler of handlers ){
 				await handler.tearDown?.( protoDir, projects, handlers, setups.get( handler ) );
 			}
+			summarizeErrors();
 		} catch( e ){
 			console.error( e );
 			process.exit( 1 );