@reflex-stack/tsp 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# TSP
+
+**TypeScript Package** (tsp), scaffolds and build **Typescript** sources to **EcmaScript modules** and publish them as modular packages to **NPM** or **JSR**.
+
+## Init a new library
+
+First, create the associated **git repository** and clone it.
+
+Run this command in git trunk :
+```bash
+npx @reflex-stack/tsp init
+```
+
+## Created files
+
+```
+├─ dist/
+├─ src/
+│  ├─ submodule
+│  │  └─ index.ts
+│  └─ index.ts
+├─ tests/
+│  └─ test.js
+├─ .gitignore
+├─ .npmignore
+├─ LICENCE ( if MIT )
+├─ package.json
+├─ package-lock.json
+├─ README.md
+└─ tsconfig.json
+```
+
+## Available commands
+
+#### Build sources
+```shell
+npm run build
+```
+- Will clear `./dist`, build sources from `.ts` files to `.js` and `.d.ts` files.
+- Will generate size report and generate `./reports` directory with JSON and SVG files.
+
+> Run `npm run build --noSizeReport`
+
+#### Test
+- `npm run test`
+> Will clear `./dist`, build sources and run tests. No size report.
+
+#### Publish
+- `npm run publish`
+> Will clear `./dist`, build sources and run tests, and start publish process.
+> This will ask you how to upgrade package.json version, push to git and npm.
+
+
+## Size report
+- TODO SVG doc
+- TODO JSON doc
+
+## tsconfig
+- TODO doc, explain forbidden properties
+
+## TSP config
+- TODO tsp config
+
+## Next
+- TODO config override from package

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@reflex-stack/tsp",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "tsp": "./src/cli.js"
+  },
+  "scripts": {
+    "publish": "node ./src/cli.js publish"
+  },
+  "author": "Alexis Bouhet",
+  "license": "MIT",
+  "description": "",
+  "dependencies": {
+    "@types/node": "^22.10.2",
+    "@zouloux/cli": "^0.2.8",
+    "@zouloux/files": "^3.0.4",
+    "brotli-size": "^4.0.0",
+    "stach": "^2.0.1",
+    "terser": "^5.37.0",
+    "typescript": "^5.7.2"
+  }
+}

package/src/cli.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env sh
+':' //# comment; exec /usr/bin/env "${RUNTIME:-node}" "$0" "$@"
+
+
+import { askInput, CLICommands, execAsync, nicePrint, oraTask, execSync, table, askList, newLine } from "@zouloux/cli";
+import { build, clearOutput } from "./commands/build.js";
+import { getUserPackageJson, naiveHumanFileSize, showIntroMessage } from "./utils.js";
+import { cleanSizeReports, generateJSON, generateSVGs, sizeReport } from "./commands/size-report.js";
+import { init } from "./commands/init.js";
+import { getConfig } from "./config.js";
+import { test } from "./commands/test.js";
+
+
+// ----------------------------------------------------------------------------- COMMANDS
+
+const commands = new CLICommands({
+	noSizeReport: false,
+	noIntro: false,
+})
+
+// Executed for all commands
+commands.before((args, flags, commandName) => {
+	if ( commandName !== "publish" && !flags.noIntro)
+		showIntroMessage(!commandName || commandName === "init")
+})
+
+/**
+ * INIT COMMAND
+ * Create a new ecma-build library ready to be published.
+ */
+commands.add("init", async (args, flags, commandName) => {
+	await init()
+})
+
+/**
+ * BUILD COMMAND
+ * options: --noSizeReport
+ */
+commands.add("build", async (args, flags) => {
+
+	const userPackage = getUserPackageJson()
+	const config = getConfig(userPackage)
+
+	await oraTask('Cleaning output', async ( task ) => {
+		await clearOutput( config )
+		task.success()
+	})
+
+	await oraTask('Building with tsc', async ( task ) => {
+		await build( config )
+		task.success('Built ✨')
+	}, (error, task) => {
+		task.error()
+		console.log(error.stdout ?? '')
+		console.log(error.stderr ?? '')
+	})
+
+	// CLI Flag to disable reports and only build
+	if ( flags.noSizeReport )
+		return
+
+	// Generate size report
+	const report = await oraTask('Generating size report', async ( task ) => {
+		// Extract "exports" from package.json and use them as bundle directories
+		if ( typeof userPackage.exports !== "object" )
+			nicePrint(`{b/r}Invalid export property in package.json.`)
+		const bundles = Object.keys( userPackage.exports )
+		// Generate report data
+		let report = await sizeReport( bundles, config )
+		task.success()
+		return report
+	})
+
+	// Generate
+	if ( config["generate-svg-report"] || config["generate-json-report"] ) {
+		await oraTask('Generating report files', async ( task ) => {
+			// Clean report directory
+			await cleanSizeReports( config )
+			// Generate JSON
+			if ( config["generate-json-report"] )
+				generateJSON( report, config )
+			// Generate SVG files
+			if ( config["generate-svg-report"] )
+				await generateSVGs( report, config )
+		})
+	}
+
+	// Print report table in CLI
+	const tableData = [
+		// Table header
+		["Bundle", "Original size", "Brotli size"]
+	]
+	// Table helpers
+	const tablePrint = s => nicePrint(s, { output: "return", newLine: false })
+	const tableLine = () => tableData.push(['', '', ''])
+	// Total bundle size
+	let totalOriginalSize = 0
+	let totalBrotliSize = 0
+	// Browse report bundles
+	report.forEach( bundleReport => {
+		tableLine()
+		// Count total bundle size
+		totalOriginalSize += bundleReport.sizes[0]
+		totalBrotliSize += bundleReport.sizes[2]
+		// Show bundle report
+		const isMainModule = bundleReport.name === "main"
+		tableData.push([
+			userPackage.name + (isMainModule ? "" : `/${bundleReport.name}`),
+			tablePrint(`{b}${naiveHumanFileSize(bundleReport.sizes[0])}`),
+			tablePrint(`{c/b}${naiveHumanFileSize(bundleReport.sizes[2])}`),
+		])
+		// Show sub-files reports
+		const totalFiles = bundleReport.files.length
+		bundleReport.files.map( (file, i) => {
+			tableData.push([
+				tablePrint(`{d}${i === totalFiles - 1 ? "└" : "├"}─ ${file.path}`),
+				tablePrint(`{d}${naiveHumanFileSize(file.sizes[0])}`),
+				tablePrint(`{d}${naiveHumanFileSize(file.sizes[2])}`),
+			])
+		})
+	})
+	// Show total if more than 1 bundle
+	if ( report.length > 1 ) {
+		tableLine()
+		tableData.push([
+			tablePrint(`{b}Total`),
+			tablePrint(`{b}${naiveHumanFileSize(totalOriginalSize)}`),
+			tablePrint(`{g/b}${naiveHumanFileSize(totalBrotliSize)}`),
+		])
+	}
+	// Print table
+	newLine()
+	table(tableData, true, [20], '  ')
+	newLine()
+})
+
+/**
+ * TEST COMMAND
+ */
+commands.add("test", async (args, flags, commandName) => {
+
+	const userPackage = getUserPackageJson()
+	const config = getConfig(userPackage)
+
+	await test( config )
+})
+
+commands.add("publish", async (args, flags, commandName) => {
+	// Check NPM connected user
+	await oraTask({text: `Connecting to npm`}, async task => {
+		try {
+			const whoami = await execAsync(`npm whoami`, 0)
+			task.success(nicePrint(`Hello {b/c}@${whoami}`, {output: 'return'}).trim())
+			return whoami
+		}
+		catch (e) {
+			task.error(`Please connect to npm with ${chalk.bold('npm login')}`)
+		}
+	})
+	// TODO : When test will build only needed files, move build after tests
+	//  (to build all files after test has succeed)
+	// Compile
+	//await CLICommands.run(`build`, cliArguments, cliOptions)
+	//await CLICommands.run(`test`, cliArguments, cliOptions)
+
+	// todo : Internal build
+	// todo : Run test command
+	// todo : Internal run report
+	// Prepare commands
+	const userPackage = getUserPackageJson()
+	let { version, name } = userPackage
+	const config = getConfig( userPackage )
+	const libraryExecOptions = { cwd: config.cwd };
+	const stdioLevel = 3;
+	// Test this library, and exit if it fails
+	// Test passed, show current version and git status
+	newLine()
+	nicePrint(`📦 Current version of {b/c}${name}{/} is {b/c}${version}`)
+	// Ask how to increment version
+	const increment = await askList(`How to increment ?`, {
+		patch: 'patch (0.0.X) - No new features, patch bugs or optimize code',
+		minor: 'minor (0.X.0) - No breaking change, have new or improved features',
+		major: 'major (X.0.0) - Breaking change',
+		// Keep but publish on NPM (if already increment in package.json)
+		keep: `keep (${ version }) - Publish current package.json version`,
+		// Push on git but no lib publish
+		push: `push - Push on git only, no npm publish`,
+		// Skip this lib (no publish at all, go to next library)
+		skip: `skip - Do not publish ${ name }`,
+	}, { returnType: 'key' });
+	// Go to next library
+	if ( increment === 'skip' )
+		return
+	// execSync(`git status -s`, stdioLevel, libraryExecOptions)
+	// Ask for commit message
+	let message = await askInput(`Commit message ?`);
+	message = message.replace(/["']/g, "'");
+	// If we increment, use npm version
+	if ( increment !== 'keep' && increment !== 'push' ) {
+		version = execSync(`npm version ${increment} --no-git-tag-version -m"${name} - %s - ${message}"`, stdioLevel, libraryExecOptions).toString().trim();
+	}
+	// Add to git and push
+	execSync(`git add .`, stdioLevel, libraryExecOptions);
+	execSync(`git commit -m"${name} - ${version} : ${message}"`, stdioLevel, libraryExecOptions);
+	execSync(`git push`, stdioLevel, libraryExecOptions);
+	// Publish on npm as public
+	// FIXME : Access public as an option for private repositories
+	// Ingore script to avoid infinite loop (if "package.json.scripts.publish" == "tsbundle publish")
+	if ( increment !== 'push' ) {
+		execSync(`npm publish --access public --ignore-scripts`, stdioLevel, libraryExecOptions);
+		nicePrint(`👌 {b/g}${name}{/}{g} Published, new version is {b/g}${version}`)
+	}
+	else {
+		nicePrint(`👍 {b/g}${name}{/}{g} Pushed to git`)
+	}
+})
+
+commands.start(function (commandName) {
+	if ( commandName )
+		return
+	nicePrint(`{b/r}Command '${commandName}' not found`)
+	newLine()
+	nicePrint(`Available commands :`)
+	commands.list().forEach( command => nicePrint(`- ${command}`) )
+})

package/src/commands/build.js

@@ -0,0 +1,15 @@
+import { execStream } from "@zouloux/cli";
+import { Directory } from "@zouloux/files";
+import { join } from "node:path";
+
+
+export async function clearOutput ( config ) {
+	const dir = new Directory( join(config.cwd, config.dist) )
+	await dir.ensureParents()
+	await dir.clean()
+}
+
+export async function build ( config ) {
+	const command = `tsc -p tsconfig.json --rootDir ${config.src} --outDir ${config.dist} --declaration true --noEmitOnError true --pretty`
+	await execStream(command, { cwd: config.cwd }, () => {})
+}

package/src/commands/init.js

@@ -0,0 +1,245 @@
+import { nicePrint, askInput, askList, newLine, oraTask, execAsync } from "@zouloux/cli"
+import { getConfig } from "../config.js";
+import { getGitRemoteUrl, getTSPPackageJson } from "../utils.js";
+import { existsSync, writeFileSync } from "node:fs";
+import { Stach } from "stach";
+import { mkdirSync } from "fs";
+import { join } from "node:path";
+
+const licenceTemplate = `MIT License
+
+Copyright (c) 2022 {{ authorName }}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.`
+
+const readmeTemplate = `# {{ packageTextName }}
+Main bundle is
+<picture style="display: inline-block">
+  <source media="(prefers-color-scheme: dark)" srcset="./reports/main-dark.svg">
+  <img src="./reports/main-light.svg">
+</picture>
+Optional submodule is only
+<picture style="display: inline-block">
+  <source media="(prefers-color-scheme: dark)" srcset="./reports/submodule-dark.svg">
+  <img src="./reports/submodule-light.svg">
+</picture>
+
+## Install
+
+\`npm i {{ packageNPMName }}\`
+
+## Usage
+
+##### Main module
+- \`import { ... } from "{{ packageNPMName }}"\`
+
+##### Sub module
+- \`import { ... } from "{{ packageNPMName }}/submodule"\`
+
+## tsp commands
+
+##### Build
+- \`npm run build\`
+##### Test
+- \`npm run test\`
+##### Publish
+- \`npm run publish\`
+`
+
+const tsconfigTemplate = `{
+	"compilerOptions": {
+		// Compilation level target
+		// If using a bundler in your project it should be the previous or current year
+		"target" : "{{esLevel}}",
+		// TS libs used, include needed lib.
+		// It should contain the target and "DOM" if it runs in the browser
+		// https://www.typescriptlang.org/tsconfig/#lib
+		"lib": [{{libs}}],
+		// Module config, you should not change it
+		"module": "NodeNext",
+		"isolatedModules": false,
+		"allowImportingTsExtensions": false,
+		// Compiler config
+		"strict": {{tsStrict}},
+		"allowJs": false,
+		"useDefineForClassFields" : true,
+		"allowSyntheticDefaultImports": true,
+		// ---
+		// Feel free to configure this file for your needs
+		// https://www.typescriptlang.org/tsconfig/
+		// ---
+		// Forbidden props are :
+		// - rootDir
+		// - outDir
+		// - declaration
+		// - noEmitOnError
+		// - pretty
+	}
+}
+`
+
+const gitIgnoreTemplate = `.DS_Store
+.idea
+tmp
+node_modules
+dist
+`
+
+const npmIgnoreTemplate = `.DS_Store
+.idea
+LICENCE
+tmp/
+src/
+.github/
+docs/
+`
+
+const rootIndexTs = `// Root index file, export elements here
+// Import nothing from submodule to keep things separated
+export function randomFunction () {
+  return 5
+}
+`
+const subModuleIndexTs = `// Sub-module index file, export elements here
+// You can import elements from root
+
+// Always import with the js extension, event in ts files
+import { randomFunction } from "../index.js"
+
+export function subRandomFunction () {
+	return randomFunction() * 12
+}
+`
+
+const testFile = `// Write your test file here
+console.log("No test implemented yet")
+process.exit(0)
+`
+
+export async function init () {
+	// Check if some critical file already exists and warn before overriding
+	if ( existsSync("package.json") ) {
+		nicePrint(`{o}package.json is already existing. Continuing will override files in this directory.`)
+		const sure = await askList("Are you sure to continue ?", ["Yes", "No"], { defaultIndex: 1, returnType: "index" })
+		if ( sure === 1 )
+			return
+	}
+	// Get git remote
+	const config = getConfig()
+	let remoteURL = getGitRemoteUrl( config.cwd )
+	if ( !remoteURL )
+		nicePrint(`{o}Before scaffolding your TypeScript package, you should create the associated git repository.`)
+	else
+		nicePrint(`{d}Git origin is {/}${remoteURL}`)
+	newLine()
+	const options = { remoteURL }
+	options.packageTextName = await askInput(`Package name, in plain text {d}ex : My Package`, { notEmpty: true })
+	options.packageNPMName = await askInput(`Package name, for NPM, with namespace {d}ex : @mynamespace/mypackage`, { notEmpty: true })
+	options.authorName = await askInput(`Author name`, { notEmpty: true })
+	options.licenceName = await askInput(`Licence name`, { defaultValue: "MIT" })
+	options.esLevel = await askInput(`ES Level for tsconfig`, { defaultValue: "es2023" })
+	options.tsStrict = await askList(`Use strict Typescript?`, ["Yes", "No"], { defaultIndex: 1, returnType: "index" })
+	options.domAccess = await askList(`Will it have access to DOM?`, ["Yes", "No"], { defaultIndex: 0, returnType: "index" })
+	options.svgReport = await askList(`Export SVG size report on build for README.md?`, ["Yes", "No"], { defaultIndex: 0, returnType: "index" })
+	options.jsonReport = await askList(`Export JSON size report on build?`, ["Yes", "No"], { defaultIndex: 1, returnType: "index" })
+	options.domAccess = options.domAccess === 0
+	options.tsStrict = options.tsStrict === 0
+	options.svgReport = options.svgReport === 0
+	options.jsonReport = options.jsonReport === 0
+	options.libs = [options.domAccess ? "DOM" : "", options.esLevel]
+		.filter( Boolean )
+		.map( s => `"${s}"`)
+	options.tspVersion = getTSPPackageJson().version
+	// Generate package json
+	const packageJson = {
+		name: options.packageNPMName,
+		version: "0.1.0",
+		type: "module",
+		author: options.authorName,
+		licence: options.licenceName,
+		main: "./dist/index.js",
+		types: "./dist/index.d.ts",
+		exports: {
+			".": {
+				types: "./dist/index.d.ts",
+				default: "./dist/index.js"
+			},
+			"./submodule": {
+				types: "./dist/submodule/index.d.ts",
+				default: "./dist/submodule/index.js"
+			}
+		},
+		tsp: {
+			runtime: "node",
+			src: './src',
+			dist: './dist',
+			tests: './tests',
+			"test-files": ['test.js'],
+			tmp: './tmp',
+			reports: './reports',
+			"generate-json-report": options.jsonReport,
+			"generate-svg-report": options.svgReport
+		},
+		scripts: {
+			build: "tsp build",
+			test: "tsp build --noSizeReport && tsp test --noIntro",
+			publish: "tsp build && tsp test --noIntro && tsp publish --noIntro"
+		},
+		dependencies: {
+			"@reflex-stack/tsp": options.tspVersion
+		}
+	}
+	// Inject git remote
+	if ( options.remoteURL ) {
+		packageJson.repository = {
+			type: "git",
+			url: options.remoteURL
+		}
+	}
+	// Create directories
+	mkdirSync(config.tests, { recursive: true })
+	mkdirSync(config.dist, { recursive: true })
+	mkdirSync(join(config.src, "submodule"), { recursive: true })
+	// Generate root files
+	if ( options.licenceName === "MIT" )
+		writeFileSync("LICENCE", Stach(licenceTemplate, options))
+	writeFileSync("README.md", Stach(readmeTemplate, options))
+	writeFileSync(".gitignore", Stach(gitIgnoreTemplate, options))
+	writeFileSync(".npmignore", Stach(npmIgnoreTemplate, options))
+	writeFileSync("tsconfig.json", Stach(tsconfigTemplate, options))
+	writeFileSync("package.json", JSON.stringify(packageJson, null, 2))
+	// Generate src files
+	writeFileSync(join(config.src, "index.ts"), Stach(rootIndexTs, options))
+	writeFileSync(join(config.src, "submodule", "index.ts"), Stach(subModuleIndexTs, options))
+	// Generate test file
+	writeFileSync(join(config.tests, "test.js"), Stach(testFile, options))
+	// Install dependencies
+	await oraTask("Installing dependencies", async () => {
+		await execAsync(`npm i typescript terser`, false, { cwd: config.cwd })
+	})
+	// Show commands
+	newLine()
+	nicePrint(`{b/g}Package ${options.packageNPMName} created ✨`)
+	newLine()
+	nicePrint(`Available commands :`)
+	nicePrint(`- npm run build`)
+	nicePrint(`- npm run test`)
+	nicePrint(`- npm run publish`)
+	newLine()
+}