validate-npm-package-name-cli 1.0.0

package/.eslintrc

@@ -0,0 +1,9 @@
+{
+	"root": true,
+
+	"extends": "@ljharb/eslint-config/node/latest",
+
+	"rules": {
+		"no-extra-parens": "off",
+	},
+}

package/.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: [ljharb]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: npm/validate-npm-package-name-cli
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v1.0.0 - 2025-02-26
+
+### Commits
+
+- Initial implementation, tests, readme, types [`f124d4f`](https://github.com/ljharb/validate-npm-package-name-cli/commit/f124d4f6395fb7e9730150f86efdee7192a0d846)
+- Initial commit [`d54f61b`](https://github.com/ljharb/validate-npm-package-name-cli/commit/d54f61b4a62960b2bb2fa1058928fe2a081a4899)
+- npm init [`bb7b57e`](https://github.com/ljharb/validate-npm-package-name-cli/commit/bb7b57e5572d392aec1924eef5865670cab11d85)
+- Only apps should have lockfiles [`19b86ee`](https://github.com/ljharb/validate-npm-package-name-cli/commit/19b86eecc5061fe286bab03bb8fee78c286de13d)
+- [Tests] rename `require` due to TS bug [`4be4bf9`](https://github.com/ljharb/validate-npm-package-name-cli/commit/4be4bf91f1f7197b57058e84cc6a49941dc7f8a2)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jordan Harband
+
+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.

package/README.md

@@ -0,0 +1,50 @@
+# validate-npm-package-name-cli <sup>[![Version Badge][npm-version-svg]][package-url]</sup>
+
+[![github actions][actions-image]][actions-url]
+[![coverage][codecov-image]][codecov-url]
+[![License][license-image]][license-url]
+[![Downloads][downloads-image]][downloads-url]
+
+[![npm badge][npm-badge-png]][package-url]
+
+CLI for https://npmjs.com/validate-npm-package-name - give me a string and I'll tell you if it's a valid npm package name.
+
+## Usage
+
+```sh
+npx validate-npm-package-name-cli npm # if not installed
+
+validate-npm-package-name-cli npm # if installed and in the PATH
+```
+
+```sh
+$ validate-npm-package-name-cli --help
+Usage:
+validate-npm-package-name-cli <npm package specifier>
+```
+
+## Install
+
+```
+npm install --save-dev validate-npm-package-name-cli
+```
+
+## License
+
+MIT
+
+[package-url]: https://npmjs.org/package/validate-npm-package-name-cli
+[npm-version-svg]: https://versionbadg.es/ljharb/validate-npm-package-name-cli.svg
+[deps-svg]: https://david-dm.org/ljharb/validate-npm-package-name-cli.svg
+[deps-url]: https://david-dm.org/ljharb/validate-npm-package-name-cli
+[dev-deps-svg]: https://david-dm.org/ljharb/validate-npm-package-name-cli/dev-status.svg
+[dev-deps-url]: https://david-dm.org/ljharb/validate-npm-package-name-cli#info=devDependencies
+[npm-badge-png]: https://nodei.co/npm/validate-npm-package-name-cli.png?downloads=true&stars=true
+[license-image]: https://img.shields.io/npm/l/validate-npm-package-name-cli.svg
+[license-url]: LICENSE
+[downloads-image]: https://img.shields.io/npm/dm/validate-npm-package-name-cli.svg
+[downloads-url]: https://npm-stat.com/charts.html?package=validate-npm-package-name-cli
+[codecov-image]: https://codecov.io/gh/ljharb/validate-npm-package-name-cli/branch/main/graphs/badge.svg
+[codecov-url]: https://app.codecov.io/gh/ljharb/validate-npm-package-name-cli/
+[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/validate-npm-package-name-cli
+[actions-url]: https://github.com/ljharb/validate-npm-package-name-cli/actions

package/bin.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { styleText } from 'util';
+import pargs from './pargs.mjs';
+
+const {
+	positionals: [packageName],
+	help,
+} = await pargs(import.meta.filename, {
+	allowPositionals: 1,
+	minPositionals: 1,
+});
+
+await help();
+
+import validate from 'validate-npm-package-name';
+
+const {
+	validForNewPackages,
+	warnings,
+	errors,
+} = validate(packageName);
+
+if (validForNewPackages) {
+	console.log(styleText('green', packageName));
+} else {
+	warnings?.forEach((warning) => console.warn(styleText('yellow', warning)));
+	errors?.forEach((error) => console.error(styleText('red', error)));
+
+	process.exitCode = 1;
+}

package/help.txt

@@ -0,0 +1,2 @@
+Usage:
+validate-npm-package-name-cli <npm package specifier>

package/package.json

@@ -0,0 +1,91 @@
+{
+	"name": "validate-npm-package-name-cli",
+	"version": "1.0.0",
+	"description": "CLI for npmjs.com/validate-npm-package-name - give me a string and I'll tell you if it's a valid npm package name",
+	"bin": "./bin.mjs",
+	"main": false,
+	"exports": {
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"prepack": "npmignore --auto --commentLines=autogenerated",
+		"prepublish": "not-in-publish || npm run prepublishOnly",
+		"prepublishOnly": "safe-publish-latest",
+		"lint": "eslint --ext=js,mjs .",
+		"postlint": "tsc && attw -P",
+		"pretest": "npm run lint",
+		"tests-only": "c8 tape 'test/**/*.mjs'",
+		"test": "npm run tests-only",
+		"posttest": "npx npm@'>= 10.2' audit --production",
+		"version": "auto-changelog && git add CHANGELOG.md",
+		"postversion": "auto-changelog && git add CHANGELOG.md && git commit --no-edit --amend && git tag -f \"v$(node -e \"console.log(require('./package.json').version)\")\""
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ljharb/validate-npm-package-name-cli.git"
+	},
+	"keywords": [
+		"npm",
+		"package",
+		"name",
+		"names",
+		"valid",
+		"validate",
+		"validation"
+	],
+	"author": "Jordan Harband <ljharb@gmail.com>",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/ljharb/validate-npm-package-name-cli/issues"
+	},
+	"homepage": "https://github.com/ljharb/validate-npm-package-name-cli#readme",
+	"dependencies": {
+		"validate-npm-package-name": "^6.0.0"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.17.4",
+		"@ljharb/eslint-config": "^21.1.1",
+		"@ljharb/tsconfig": "^0.2.3",
+		"@types/node": "^22.13.5",
+		"@types/tape": "^5.8.1",
+		"@types/validate-npm-package-name": "^4.0.2",
+		"auto-changelog": "^2.5.0",
+		"c8": "^10.1.3",
+		"eslint": "=8.8.0",
+		"in-publish": "^2.0.1",
+		"npmignore": "^0.3.1",
+		"safe-publish-latest": "^2.0.0",
+		"tape": "^5.9.0",
+		"typescript": "next",
+		"undici-types": "^7.3.0"
+	},
+	"engines": {
+		"node": "^22.14 || >= 23.9"
+	},
+	"c8": {
+		"all": true,
+		"reporter": [
+			"html",
+			"text",
+			"lcov"
+		],
+		"exclude": [
+			"coverage",
+			"test",
+			"pargs.mjs"
+		]
+	},
+	"auto-changelog": {
+		"output": "CHANGELOG.md",
+		"template": "keepachangelog",
+		"unreleased": false,
+		"commitLimit": false,
+		"backfillLimit": false,
+		"hideCredit": true
+	},
+	"publishConfig": {
+		"ignore": [
+			".github/workflows"
+		]
+	}
+}

package/pargs.d.mts

@@ -0,0 +1,65 @@
+export type ExtractIterable<T> = T extends Iterable<infer U> ? U : never;
+
+// export type GroupedByString<T> = { [k: string]: null | T[] };
+
+// declare function groupByString<T>(iterable: Iterable<T>, cb: (item: T) => string): GroupedByString<T>;
+
+import { parseArgs, type ParseArgsConfig as PAC } from "util";
+
+export type ParseArgsConfig = PAC;
+
+type ParseArgsOptionsConfig = NonNullable<ParseArgsConfig['options']>;
+
+type ParseArgsOptionConfig = ParseArgsOptionsConfig[keyof ParseArgsOptionsConfig];
+
+export type PargsConfig = Omit<ParseArgsConfig, 'args' | 'strict' | 'allowPositionals' | 'options'> & {
+    options?: {
+        [longOption: string]: ParseArgsOptionConfig | (Omit<ParseArgsOptionConfig, 'type'> & {
+            type: 'enum';
+            choices: string[];
+        });
+    };
+    allowPositionals?: boolean | number;
+    minPositionals?: number;
+};
+
+export type PargsRootConfig = PargsConfig & {
+    subcommands: Record<string, PargsConfig>
+};
+
+export type ParseArgsError = (Error | TypeError) & {
+    code:
+        | 'ERR_PARSE_ARGS_UNKNOWN_OPTION'
+        | 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE'
+        | 'ERR_INVALID_ARG_TYPE'
+        | 'ERR_INVALID_ARG_VALUE'
+        | 'ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL'
+};
+
+export type OptionToken = Extract<
+    NonNullable<
+        ReturnType<typeof parseArgs>['tokens']
+    >[number],
+    { kind: 'option' }
+>;
+
+export type PargsParsed<T extends (PargsConfig | PargsRootConfig)> = (
+    T extends PargsRootConfig ? {
+        command: { name: keyof T['subcommands'] } & PargsParsed<PargsConfig>,
+    } : {}
+) & {
+    errors: string[],
+    help(): Promise<void>,
+} & ReturnType<typeof parseArgs>;
+
+// declare function pargs<C extends PargsRootConfig>(
+//     entrypointPath: ImportMeta['filename'],
+//     obj: C,
+// ): Promise<PargsParsed<C>>;
+
+declare function pargs<C extends PargsRootConfig | PargsConfig>(
+    entrypointPath: ImportMeta['filename'],
+    obj: C,
+): Promise<PargsParsed<C>>;
+
+export default pargs;

package/pargs.mjs

@@ -0,0 +1,217 @@
+import { parseArgs } from 'util';
+import { dirname, join } from 'path';
+import { realpathSync } from 'fs';
+import { readFile } from 'fs/promises';
+
+const { hasOwn } = Object;
+
+/** @type {(e: unknown) => e is import('./pargs.mjs').ParseArgsError} */
+function isParseArgsError(e) {
+	return !!e
+		&& typeof e === 'object'
+		&& 'code' in e
+		&& (
+			e.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION'
+			|| e.code === 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE'
+			|| e.code === 'ERR_INVALID_ARG_TYPE'
+			|| e.code === 'ERR_INVALID_ARG_VALUE'
+			|| e.code === 'ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL'
+		);
+}
+
+/* eslint max-lines-per-function: 0, max-statements: 0, complexity: 0, sort-keys: 0, no-magic-numbers: 0 */
+
+/** @type {import('./pargs.mjs').default} */
+export default async function pargs(entrypointPath, obj) {
+	const argv = process.argv.flatMap((arg) => {
+		try {
+			const realpathedArg = realpathSync(arg);
+			if (
+				realpathedArg === process.execPath
+				|| realpathedArg === entrypointPath
+			) {
+				return [];
+			}
+		} catch (e) { /**/ }
+		return arg;
+	});
+
+	if ('help' in obj || (obj.options && 'help' in obj.options)) {
+		throw new TypeError('The "help" option is reserved');
+	}
+
+	/** @type {string[]} */
+	const errors = [];
+
+	if ('subcommands' in obj && (!obj.subcommands || typeof obj.subcommands !== 'object')) {
+		throw new TypeError('Error: `subcommands` must be an object');
+	}
+
+	const { subcommands, ...passedConfig } = obj;
+
+	if ('subcommands' in obj && Object.keys(obj.subcommands).length === 0) {
+		throw new TypeError('Error: `subcommands` must be an object with at least one key');
+	}
+
+	if ('subcommands' in obj && 'allowPositionals' in passedConfig) {
+		throw new TypeError('Error: `allowPositionals` is not allowed when `subcommands` is defined');
+	}
+
+	const enums = { __proto__: null };
+
+	/** @type {{ options: import('./pargs.mjs').ParseArgsConfig['options'] & { help: { default: false, type: 'boolean' } } }} */
+	const normalizedOptions = Object.fromEntries(Object.entries(passedConfig.options ?? {}).flatMap(([key, value]) => {
+		if (value.type !== 'enum') {
+			return [[key, value]];
+		}
+
+		if (!Array.isArray(value.choices) || !value.choices.every((x) => typeof x === 'string')) {
+			throw new TypeError(`Error: enum choices must be an array of strings; \`${key}\` is invalid`);
+		}
+
+		enums[key] = value;
+		return [[key, { ...value, type: 'string' }]];
+	}).concat([
+		[
+			'help',
+			{
+				default: false,
+				type: 'boolean',
+			},
+		],
+	]));
+
+	/** @type {import('./pargs.mjs').ParseArgsConfig & { tokens: true, allowNegative: true, strict: true, options: typeof normalizedOptions }} */
+	const newObj = {
+		args: subcommands ? argv.slice(0, 1) : argv,
+		...passedConfig,
+		options: normalizedOptions,
+		tokens: true,
+		allowNegative: true,
+		allowPositionals: !!subcommands || typeof passedConfig.allowPositionals !== 'undefined',
+		minPositionals: 0,
+		strict: true,
+	};
+
+	// console.log(newObj.options);
+
+	try {
+		const { tokens, ...results } = parseArgs(newObj);
+
+		const enumEntries = Object.entries(enums);
+		if (enumEntries.length > 0) {
+			enumEntries.forEach(([key, config]) => {
+				const value = results.values[key];
+				// console.log(key, config, value);
+
+				if (!config.choices.includes(value)) {
+					errors.push(`Error: Invalid value for option "${key}"`);
+				}
+			});
+		}
+
+		// eslint-disable-next-line no-inner-declarations
+		async function help() {
+			if (('help' in results.values && results.values.help) || errors.length > 0) {
+				const helpText = await `${await readFile(join(dirname(entrypointPath), './help.txt'), 'utf-8')}`;
+				if (errors.length === 0) {
+					console.log(helpText);
+				} else {
+					console.error(`${helpText}${errors.length === 0 ? '' : '\n'}`);
+
+					process.exitCode ||= parseInt('1'.repeat(errors.length), 2);
+					errors.forEach((error) => console.error(error));
+				}
+
+				process.exit();
+			}
+		}
+
+		const { allowPositionals, minPositionals } = passedConfig;
+
+		const posCount = typeof allowPositionals === 'number' ? allowPositionals : allowPositionals || subcommands ? Infinity : 0;
+		if (results.positionals.length > posCount) {
+			errors.push(`Only ${posCount} positional arguments allowed; got ${results.positionals.length}`);
+		}
+		if (!results.values.help && typeof minPositionals === 'number' && results.positionals.length < minPositionals) {
+			errors.push(`At least ${posCount} positional arguments are required; got ${results.positionals.length}`);
+		}
+
+		const optionTokens = tokens.filter(/** @type {(token: typeof tokens[number]) => token is import('./pargs.mjs').OptionToken} */ (token) => token.kind === 'option');
+
+		const bools = obj.options ? Object.entries(obj.options).filter(([, { type }]) => type === 'boolean') : [];
+		const boolMap = new Map(bools.concat([['help', newObj.options.help]]));
+		for (let i = 0; i < optionTokens.length; i += 1) {
+			const { name, value } = optionTokens[i];
+			if (boolMap.has(name) && typeof value !== 'boolean' && typeof value !== 'undefined') {
+				errors.push(`Error: Argument --${name} must be a boolean`);
+			}
+		}
+
+		const passedArgs = new Set(optionTokens.map(({ name, rawName }) => (rawName === '--no-help' ? rawName : name)));
+
+		const groups = Object.groupBy(passedArgs, (x) => x.replace(/^no-/, ''));
+		for (let i = 0; i < bools.length; i++) {
+			const [key] = bools[i];
+			if ((groups[key]?.length ?? 0) > 1) {
+				errors.push(`Error: Arguments \`--${key}\` and \`--no-${key}\` are mutually exclusive`);
+			}
+			if (passedArgs.has(`no-${key}`)) {
+				results.values[key] = !results.values[`no-${key}`];
+			}
+			delete results.values[`no-${key}`];
+		}
+
+		const knownOptions = Object.keys(newObj.options);
+		const unknownArgs = knownOptions.length > 0 ? passedArgs.difference(new Set(knownOptions)) : passedArgs;
+		if (unknownArgs.size > 0) {
+			errors.push(`Error: Unknown option(s): ${Array.from(unknownArgs, (x) => `\`${x}\``).join(', ')}`);
+		}
+
+		/** @type {undefined | import('./pargs.mjs').PargsParsed<import('./pargs.mjs').PargsConfig>} */
+		let command;
+		if (subcommands) {
+			const subcommand = argv[0];
+			// eslint-disable-next-line no-extra-parens
+			if (hasOwn(/** @type {object} */ (subcommands), subcommand)) {
+				process.argv.splice(process.argv.indexOf(subcommand), 1);
+				command = await pargs(entrypointPath, subcommands[subcommand]);
+			} else {
+				errors.push(`Error: unknown command "${command}"`);
+			}
+		}
+
+		return {
+			help,
+			errors,
+			...results,
+			...command && {
+				help: ('help' in command && command.help) || help,
+				command: {
+					name: argv[0],
+					...command,
+				},
+			},
+			...obj.tokens && { tokens },
+		};
+	} catch (e) {
+		const fakeErrors = [`Error: ${!!e && typeof e === 'object' && 'message' in e && e.message}`];
+		if (isParseArgsError(e)) {
+			return {
+				async help() {
+					const helpText = await `${await readFile(join(dirname(entrypointPath), './help.txt'), 'utf-8')}`;
+					console.error(`${helpText}'\n`);
+
+					process.exitCode ||= parseInt('1', 2);
+					console.error(fakeErrors[0]);
+
+					process.exit();
+				},
+				values: {},
+				positionals: [],
+				errors: fakeErrors,
+			};
+		}
+		throw e;
+	}
+}

package/test/bin.mjs

@@ -0,0 +1,82 @@
+import test from 'tape';
+
+import { join } from 'path';
+import { promisify, styleText } from 'util';
+import { execFile as execFileC } from 'child_process';
+import { createRequire } from 'module';
+
+const requireX = createRequire(import.meta.url);
+const pkgJSON = requireX('../package.json');
+
+const execFile = promisify(execFileC);
+
+const { PATH, DEBUG } = process.env;
+
+const bin = join(import.meta.dirname, '../bin.mjs');
+
+/**
+ * @param {test.Test} t
+ * @param {string} pkg
+ * @param {{ code?: number, out?: string, err?: string, outC?: string, errC?: string }} expected
+ */
+async function run(t, pkg, expected) {
+	t.test(`package: ${pkg}`, async (st) => {
+		const [
+			{ stdout: outB, stderr: errB, code = 0 },
+			{ stdout: stdoutColorB, stderr: stderrColorB },
+		] = await Promise.all([
+			execFile(bin, [pkg], { env: { PATH, NO_COLORS: '1' } }),
+			execFile(bin, [pkg], { env: { PATH, FORCE_COLOR: '1' } }),
+		].map((x) => x.catch((e) => e)));
+
+		const stdout = `${outB}`.trim();
+		const stderr = `${errB}`.trim();
+		const stdoutColor = `${stdoutColorB}`.trim();
+		const stderrColor = `${stderrColorB}`.trim();
+
+		st.equal(code, Number(expected.code ?? 0), 'should have expected exit code');
+
+		const { out = '', err = '', outC = '', errC = '' } = expected;
+		if (DEBUG) {
+			`${stdout}`.split('\n').forEach((line, lineIndex) => {
+				st.equal(line, out.split('\n')[lineIndex], `should have expected output ${lineIndex}`);
+			});
+			`${stdoutColor}`.split('\n').forEach((line, lineIndex) => {
+				st.equal(line, outC.split('\n')[lineIndex], `should have expected output ${lineIndex}`);
+			});
+		} else {
+			st.equal(`${stdout}`, out, 'should have expected output');
+			st.equal(`${stderr}`, err, 'should have expected error output');
+			st.equal(`${stdoutColor}`, outC, 'should have expected color output');
+			st.equal(`${stderrColor}`, errC, 'should have expected color error output');
+		}
+	});
+}
+
+test('cli', async (t) => {
+	process.env.FORCE_COLOR = '1'; // for faucet etc
+
+	const y = /** @type {const} */ ([
+		'es-abstract',
+		'jsonstream',
+		...Object.keys(pkgJSON.dependencies),
+		...Object.keys(pkgJSON.devDependencies),
+	]);
+
+	await Promise.all(y.map((pkg) => run(t, pkg, { out: pkg, outC: styleText('green', pkg) })));
+
+	const n = /** @type {const} */ ([
+		['foo bar', 'name can only contain URL-friendly characters'],
+		['JSONStream', '', 'name can no longer contain capital letters'],
+	]);
+
+	await Promise.all(n.map(([
+		pkg,
+		errors,
+		warnings = '',
+	]) => run(t, pkg, {
+		code: 1,
+		err: `${warnings}\n${errors}`.split('\n').filter(Boolean).join('\n'),
+		errC: `${warnings && styleText('yellow', warnings)}\n${errors && styleText('red', errors)}`.split('\n').filter(Boolean).join('\n'),
+	})));
+});

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+	"extends": "@ljharb/tsconfig",
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"resolveJsonModule": true,
+	},
+	"exclude": [
+		"coverage",
+	],
+}