@ljharb/unused-files 0.1.0

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/@ljharb/unused-files
+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).
+
+## v0.1.0 - 2024-03-13
+
+### Commits
+
+- Initial implementation, tests, readme, types [`bb8f77e`](https://github.com/ljharb/unused-files/commit/bb8f77e0de26f496a1b31f93fc5d6cedf6b81c32)
+- Initial commit [`891f569`](https://github.com/ljharb/unused-files/commit/891f56957344e97a98628b4b3c51bd9a4c617a78)
+- npm init [`82926ab`](https://github.com/ljharb/unused-files/commit/82926ab583b8cdd4603ac92bd06461a32c5138be)
+- Only apps should have lockfiles [`04a0888`](https://github.com/ljharb/unused-files/commit/04a088837dbc0f441c57b2244591454fd8b9e563)
+- [types] use the DT PR instead of waiting on the package [`32687bf`](https://github.com/ljharb/unused-files/commit/32687bfa844a97e64ef0cf24abd20e806991f0d1)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 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,59 @@
+# @ljharb/unused-files <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]
+
+List unused files in your package.
+
+## Usage
+
+```sh
+npx @ljharb/unused-files # if not installed
+
+unused-files # if installed and in the PATH
+```
+
+```sh
+$ unused-files --help
+Usage: unused-files [options]
+
+Options:
+  --ignorePattern <pattern>  Ignore files matching the given pattern
+    [string]
+    [multiple]
+    [default: .github/**, coverage/**, test/**, tests/**, example/**]
+
+  --json                     Output the result as a JSON array
+    [boolean]
+    [default: false]
+```
+
+## Install
+
+```
+npm install --save-dev @ljharb/unused-files
+```
+
+## License
+
+MIT
+
+[package-url]: https://npmjs.org/package/@ljharb/unused-files
+[npm-version-svg]: https://versionbadg.es/ljharb/unused-files.svg
+[deps-svg]: https://david-dm.org/ljharb/unused-files.svg
+[deps-url]: https://david-dm.org/ljharb/unused-files
+[dev-deps-svg]: https://david-dm.org/ljharb/unused-files/dev-status.svg
+[dev-deps-url]: https://david-dm.org/ljharb/unused-files#info=devDependencies
+[npm-badge-png]: https://nodei.co/npm/@ljharb/unused-files.png?downloads=true&stars=true
+[license-image]: https://img.shields.io/npm/l/@ljharb/unused-files.svg
+[license-url]: LICENSE
+[downloads-image]: https://img.shields.io/npm/dm/@ljharb/unused-files.svg
+[downloads-url]: https://npm-stat.com/charts.html?package=@ljharb/unused-files
+[codecov-image]: https://codecov.io/gh/ljharb/unused-files/branch/main/graphs/badge.svg
+[codecov-url]: https://app.codecov.io/gh/ljharb/unused-files/
+[actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/unused-files
+[actions-url]: https://github.com/ljharb/unused-files/actions

package/bin.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+
+import unusedFiles from './index.mjs';
+
+import pargs from './pargs.mjs';
+
+const help = await readFile(join(import.meta.dirname, './help.txt'), 'utf8');
+
+const { values: { json, ignorePattern } } = pargs(help, import.meta.filename, {
+	options: {
+		ignorePattern: {
+			default: undefined,
+			multiple: true,
+			type: 'string',
+		},
+		json: {
+			default: false,
+			type: 'boolean',
+		},
+	},
+});
+
+// eslint-disable-next-line no-extra-parens
+const files = await unusedFiles(process.cwd(), /** @type {string[] | undefined} */ (ignorePattern));
+
+if (json) {
+	console.log(JSON.stringify(files, null, '\t'));
+} else {
+	files.forEach((x) => console.log(x));
+}

package/help.txt

@@ -0,0 +1,11 @@
+Usage: unused-files [options]
+
+Options:
+  --ignorePattern <pattern>  Ignore files matching the given pattern
+    [string]
+    [multiple]
+    [default: .github/**, coverage/**, test/**, tests/**, example/**]
+
+  --json                     Output the result as a JSON array
+    [boolean]
+    [default: false]

package/index.mjs

@@ -0,0 +1,41 @@
+import { relative } from 'path';
+import micromatch from 'micromatch';
+
+export default async function unusedFiles(
+	cwd = process.cwd(),
+	ignorePattern = [
+		'.github/**',
+		'coverage/**',
+		'test/**',
+		'tests/**',
+		'example/**',
+	],
+) {
+	const origArgv = process.argv;
+	let files;
+	try {
+		process.argv = origArgv.slice(0, 2);
+		const { main: knip } = await import('knip');
+
+		({ issues: { files } } = await knip({
+			cwd,
+			fixTypes: [],
+			gitignore: true,
+			isFix: false,
+			isIncludeEntryExports: true,
+			isIsolateWorkspaces: false,
+			isProduction: true,
+			isShowProgress: false,
+			isStrict: true,
+			tags: [[], []],
+		}));
+	} finally {
+		process.argv = origArgv;
+	}
+
+	return Array.from(files).flatMap((x) => (
+		micromatch.isMatch(relative(cwd, x), ignorePattern)
+			? []
+			: `./${relative(cwd, x)}`
+	));
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+	"name": "@ljharb/unused-files",
+	"version": "0.1.0",
+	"description": "List unused files in your package.",
+	"bin": "./bin.mjs",
+	"main": false,
+	"sideEffects": false,
+	"exports": {
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"prepublishOnly": "safe-publish-latest",
+		"prepublish": "not-in-publish || npm run prepublishOnly",
+		"prepack": "npmignore --auto",
+		"lint": "eslint --ext=js,mjs .",
+		"postlint": "tsc -p . && attw -P",
+		"pretest": "npm run lint",
+		"tests-only": "c8 tape 'test/**/*.mjs'",
+		"test": "npm run tests-only",
+		"posttest": "aud --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/unused-files.git"
+	},
+	"keywords": [
+		"unused",
+		"files",
+		"package"
+	],
+	"author": "Jordan Harband <ljharb@gmail.com>",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/ljharb/unused-files/issues"
+	},
+	"homepage": "https://github.com/ljharb/unused-files#readme",
+	"dependencies": {
+		"knip": "^5.0.4",
+		"micromatch": "^4.0.5",
+		"object.groupby": "^1.0.2"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.15.1",
+		"@ljharb/eslint-config": "^21.1.0",
+		"@ljharb/tsconfig": "^0.2.0",
+		"@types/micromatch": "^4.0.6",
+		"@types/object.groupby": "https://gitpkg.now.sh/DefinitelyTyped/DefinitelyTyped/types/object.groupby?2489af71f28f861b4bf3884ecf35a3d204e3bb48",
+		"@types/tape": "^5.6.4",
+		"@types/webpack": "^5.28.5",
+		"aud": "^2.0.4",
+		"auto-changelog": "^2.4.0",
+		"c8": "^9.1.0",
+		"eslint": "^8.8.0",
+		"in-publish": "^2.0.1",
+		"npmignore": "^0.3.1",
+		"playwright": "^1.42.1",
+		"safe-publish-latest": "^2.0.0",
+		"tape": "^5.7.5",
+		"typescript": "next"
+	},
+	"engines": {
+		"node": "^20.11.1 || >= 21.7.1"
+	},
+	"auto-changelog": {
+		"output": "CHANGELOG.md",
+		"template": "keepachangelog",
+		"unreleased": false,
+		"commitLimit": false,
+		"backfillLimit": false,
+		"hideCredit": true
+	},
+	"publishConfig": {
+		"access": "public",
+		"ignore": [
+			".github/workflows",
+			".eslintrc",
+			".nycrc",
+			"test"
+		]
+	}
+}

package/pargs.d.ts

@@ -0,0 +1,5 @@
+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>;

package/pargs.mjs

@@ -0,0 +1,100 @@
+import { parseArgs } from 'util';
+import { realpathSync } from 'fs';
+
+import groupByPolyfill from 'object.groupby/polyfill';
+
+const groupBy = groupByPolyfill();
+
+/** @typedef {import('util').ParseArgsConfig} ParseArgsConfig */
+
+/** @typedef {(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'}} ParseArgsError */
+
+/** @type {(e: unknown) => e is 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'
+		);
+}
+
+/** @type {(helpText: string, entrypointPath: string, obj: Exclude<ParseArgsConfig, 'args'>) => ReturnType<typeof parseArgs>} */
+export default function pargs(helpText, 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) {
+		throw new TypeError('The "help" option is reserved');
+	}
+
+	const bools = obj.options ? Object.entries(obj.options).filter(([key, { type }]) => type === 'boolean' && key !== 'help') : [];
+	const inverseBools = Object.fromEntries(bools.map(([key, value]) => [
+		`no-${key}`,
+		{ default: !value.default, type: 'boolean' },
+	]));
+	/** @type {ParseArgsConfig & { tokens: true }} */
+	const newObj = {
+		args: argv,
+		...obj,
+		options: {
+			...obj.options,
+			...inverseBools,
+			help: {
+				default: false,
+				type: 'boolean',
+			},
+		},
+		tokens: true,
+	};
+
+	try {
+		const { tokens, ...results } = parseArgs(newObj);
+
+		if ('help' in results.values && results.values.help) {
+			console.log(helpText);
+			process.exit(0);
+		}
+
+		/** @typedef {Extract<typeof tokens[number], { kind: 'option' }>} OptionToken */
+		const optionTokens = tokens.filter(/** @type {(token: typeof tokens[number]) => token is OptionToken} */ (token) => token.kind === 'option');
+		const passedArgs = new Set(optionTokens.map(({ name }) => name));
+		const groups = groupBy(passedArgs, (x) => x.replace(/^no-/, ''));
+		bools.forEach(([key]) => {
+			if ((groups[key]?.length ?? 0) > 1) {
+				console.log(helpText);
+				console.error(`Error: Arguments --${key} and --no-${key} are mutually exclusive`);
+				process.exit(2);
+			}
+			if (passedArgs.has(`no-${key}`)) {
+				// @ts-expect-error
+				results.values[key] = !results.values[`no-${key}`];
+			}
+			// @ts-expect-error
+			delete results.values[`no-${key}`];
+		});
+
+		return obj.tokens ? { ...results, tokens } : results;
+	} catch (e) {
+		if (isParseArgsError(e)) {
+			console.log(helpText);
+			console.error(`Error: ${e.message}`);
+			process.exit(1);
+		}
+		throw e;
+	}
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"extends": "@ljharb/tsconfig",
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "NodeNext",
+		"moduleResolution": "nodenext",
+		"resolveJsonModule": false,
+	},
+	"exclude": [
+		"coverage",
+		"test/fixtures",
+	],
+}