dt-clean 1.0.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/dt-clean
+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 a single custom sponsorship URL

package/.nycrc

@@ -0,0 +1,15 @@
+{
+	"all": true,
+	"check-coverage": true,
+	"reporter": [
+		"text",
+		"lcov"
+	],
+	"include": [
+		"*.mjs"
+	],
+	"exclude": [
+		"eslint.config.mjs",
+		"test"
+	]
+}

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 - 2026-06-19
+
+### Commits
+
+- Initial implementation, readme, tests, types, etc [`202952a`](https://github.com/ljharb/dt-clean/commit/202952a1ed579c6864988bb421eda7e27e52c532)
+- Initial commit [`e817527`](https://github.com/ljharb/dt-clean/commit/e8175279344f1ce2c490779a6cb5900ed94ec6d2)
+- npm init [`9dd6e5c`](https://github.com/ljharb/dt-clean/commit/9dd6e5cbaa1000a0e029c1531c13e359769db844)
+- Only apps should have lockfiles [`dd98916`](https://github.com/ljharb/dt-clean/commit/dd9891647c9b54e793ddbb68cdd569fa0aad5967)
+- [meta] add version settings [`63d1636`](https://github.com/ljharb/dt-clean/commit/63d16368dfa19750fd19c6264e304f6a0491620c)

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,62 @@
+# dt-clean <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]
+
+Ensures the only DefinitelyTyped (`@types/*`) packages you have installed are the ones you need, and points out the ones you're missing.
+
+`dt-clean` inspects your `package.json` and, for each dependency, decides what should happen to its DefinitelyTyped types package:
+
+- **add**: the runtime package ships no types of its own, but a matching `@types/*` package exists on the registry.
+- **move**: an `@types/*` package is in `dependencies`, but belongs in `devDependencies`.
+- **remove**: an `@types/*` package is installed but no longer needed: the runtime package now bundles its own types, or it no longer corresponds to any dependency.
+- **keep**: the `@types/*` package is present and still needed. `@types/node` is always kept.
+
+## Usage
+
+```sh
+# report only (the default)
+npx dt-clean [dir]
+
+# apply the changes to package.json
+npx dt-clean --update [dir]
+```
+
+`dir` is the directory containing the `package.json` to inspect, and defaults to the current directory.
+
+By default, `dt-clean` only prints a report and changes nothing:
+
+```
+Package         State    Action  Version
+--------------  -------  ------  -------
+@types/express  present  remove  ^4.0.0
+@types/lodash   missing  add     ^4.17
+@types/node     present  keep    ^25.0.0
+
+3 `@types/*` packages: 1 keep, 0 move, 1 remove, 1 add.
+```
+
+The `State` column tells you whether each DefinitelyTyped package is currently `present` or `missing`; the `Action` column tells you what `--update` would do about it.
+
+With `--update` (`-u`), `dt-clean` edits `package.json` in place - adding, moving, and removing the relevant `@types/*` entries - and then reminds you to run `npm install` (or your package manager's equivalent) to sync `node_modules`.
+
+### Options
+
+- `-u`, `--update`: apply the changes to `package.json` (default: report only).
+- `--help`: show usage.
+
+[package-url]: https://npmjs.org/package/dt-clean
+[npm-version-svg]: https://versionbadg.es/ljharb/dt-clean.svg
+[npm-badge-png]: https://nodei.co/npm/dt-clean.png?downloads=true&stars=true
+[license-image]: https://img.shields.io/npm/l/dt-clean.svg
+[license-url]: LICENSE
+[downloads-image]: https://img.shields.io/npm/dm/dt-clean.svg
+[downloads-url]: https://npm-stat.com/charts.html?package=dt-clean
+[codecov-image]: https://codecov.io/gh/ljharb/dt-clean/branch/main/graphs/badge.svg
+[codecov-url]: https://app.codecov.io/gh/ljharb/dt-clean/
+[actions-image]: https://img.shields.io/github/check-runs/ljharb/dt-clean/main
+[actions-url]: https://github.com/ljharb/dt-clean/actions

package/applyChanges.d.ts

@@ -0,0 +1,9 @@
+import type { DTPackage, Version } from './getDelTa.d.ts';
+
+declare function applyChanges(cwd: string, delta: {
+    toAdd: Map<DTPackage, Version>;
+    toMove: Map<DTPackage, Version>;
+    toRemove: DTPackage[];
+}): Promise<boolean>;
+
+export = applyChanges;

package/applyChanges.mjs

@@ -0,0 +1,65 @@
+import { join } from 'path';
+import { readFile, writeFile } from 'fs/promises';
+
+/** @param {string} raw */
+function detectIndent(raw) {
+	const match = (/^[ \t]+/m).exec(raw);
+	return match?.[0] ?? '\t';
+}
+
+/** @type {<K extends string, V>(obj: Record<K, V>) => Record<K, V>} */
+function sortKeys(obj) {
+	return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+/** @import { PackageJSON } from './types/types.d.ts' */
+
+/** @type {import('./applyChanges.d.ts')} */
+export default async function applyChanges(cwd, {
+	toAdd,
+	toMove,
+	toRemove,
+}) {
+	const packageJSONpath = join(cwd, 'package.json');
+	const raw = `${await readFile(packageJSONpath)}`;
+
+	/** @type {PackageJSON} */
+	const pkg = JSON.parse(raw);
+
+	/** @type {NonNullable<PackageJSON['dependencies']>} */
+	const deps = { ...pkg.dependencies };
+	/** @type {NonNullable<PackageJSON['devDependencies']>} */
+	const devDeps = { ...pkg.devDependencies };
+
+	toMove.forEach((version, name) => {
+		delete deps[name];
+		devDeps[name] = version;
+	});
+	toAdd.forEach((version, name) => {
+		devDeps[name] = version;
+	});
+	toRemove.forEach((name) => {
+		delete deps[name];
+		delete devDeps[name];
+	});
+
+	const next = { ...pkg };
+	if (Object.keys(deps).length > 0) {
+		next.dependencies = sortKeys(deps);
+	} else {
+		delete next.dependencies;
+	}
+	if (Object.keys(devDeps).length > 0) {
+		next.devDependencies = sortKeys(devDeps);
+	} else {
+		delete next.devDependencies;
+	}
+
+	const serialized = `${JSON.stringify(next, null, detectIndent(raw))}\n`;
+	if (serialized === raw) {
+		return false;
+	}
+
+	await writeFile(packageJSONpath, serialized);
+	return true;
+}

package/bin.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import { resolve } from 'path';
+
+import pargs from 'pargs';
+
+import getDelTa from '#/getDelTa';
+import applyChanges from '#/applyChanges';
+import formatReport from '#/report';
+
+const {
+	values: { json, update },
+	positionals,
+	help,
+} = await pargs(import.meta.filename, {
+	allowPositionals: 1,
+	description: 'Reports which DefinitelyTyped (`@types/*`) packages a project should add, move, or remove. By default it only reports; with `--update` it edits `package.json`.',
+	options: {
+		json: {
+			default: false,
+			description: 'print the result as JSON on stdout (the human-readable report moves to stderr)',
+			type: 'boolean',
+		},
+		update: {
+			default: false,
+			description: 'apply the changes to `package.json`, then run `npm install` (or your package manager\'s equivalent)',
+			short: 'u',
+			type: 'boolean',
+		},
+	},
+	positionals: [{ description: 'directory containing the `package.json` to inspect (default: the current directory)', name: 'dir' }],
+});
+
+await help();
+
+const cwd = positionals.length > 0 ? resolve(positionals[0]) : process.cwd();
+
+const {
+	present,
+	toAdd,
+	toMove,
+	toRemain,
+	toRemove,
+} = await getDelTa(cwd);
+
+const report = formatReport({
+	present,
+	toAdd,
+	toMove,
+	toRemove,
+});
+
+if (json) {
+	console.log(JSON.stringify({
+		present: Object.fromEntries(present),
+		toAdd: Object.fromEntries(toAdd),
+		toMove: Object.fromEntries(toMove),
+		toRemain: Array.from(toRemain),
+		toRemove,
+	}, null, '\t'));
+	console.error(report);
+} else {
+	console.log(report);
+}
+
+if (update) {
+	const changed = await applyChanges(cwd, {
+		toAdd,
+		toMove,
+		toRemove,
+	});
+	console.error(changed
+		? '\nUpdated `package.json`; run `npm install` (or your package manager’s equivalent) to sync.'
+		: '\nNo changes needed.');
+} else if (toAdd.size + toMove.size + toRemove.length > 0) {
+	console.error('\nRe-run with `--update` (`-u`) to apply these changes to `package.json`.');
+}

package/getDelTa.d.ts

@@ -0,0 +1,18 @@
+declare function getDelTa(
+    cwd?: string,
+): Promise<getDelTa.DTDelta>;
+
+declare namespace getDelTa {
+    type Version = string & {};
+    type DTPackage<T extends string = string> = `@types/${T}`;
+
+    type DTDelta = {
+        present: Map<DTPackage, Version>;
+        toAdd: Map<DTPackage, Version>;
+        toMove: Map<DTPackage, Version>;
+        toRemain: Set<DTPackage>;
+        toRemove: DTPackage[];
+    };
+}
+
+export = getDelTa;

package/getDelTa.mjs

@@ -0,0 +1,146 @@
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { findPackageJSON } from 'module';
+import { mangleScopedPackage, typesPackageNameToRealName } from '@definitelytyped/utils';
+
+import hasTypes from 'hastypes';
+import semver from 'semver';
+
+/** @import getDelTA, { DTPackage, Version } from './getDelTa.d.ts' */
+/** @import { PackageJSON } from './types/types.d.ts'*/
+
+/** @type {<T>(entry: [string, T]) => entry is [DTPackage, T]} */
+function isDTPackageEntry([name]) {
+	return name.startsWith('@types/');
+}
+
+/** @type {<T extends string>(name: T) => DTPackage<T>} */
+function toDTName(name) {
+	return `@types/${mangleScopedPackage(name)}`;
+}
+
+/** @type {<T extends string>(name: DTPackage<T>) => T} */
+function fromDTName(name) {
+	return typesPackageNameToRealName(name);
+}
+
+/** @type {getDelTA} */
+export default async function getDelTa(cwd = process.cwd()) {
+	const packageJSONpath = join(cwd, 'package.json');
+	const anchor = pathToFileURL(packageJSONpath);
+
+	/** @type {PackageJSON} */
+	const {
+		dependencies,
+		devDependencies,
+	} = JSON.parse(`${await readFile(packageJSONpath)}`);
+
+	const deps = new Map(dependencies ? Object.entries(dependencies) : []);
+	const devDeps = new Map(devDependencies ? Object.entries(devDependencies) : []);
+
+	const allDeps = /** @type {const} */ ([...deps, ...devDeps]);
+
+	// `@types/*` packages declared as runtime `dependencies` belong in `devDependencies`.
+	const dtRuntimeDepsPresent = new Map(deps.entries().filter(isDTPackageEntry));
+
+	// every `@types/*` package present, whether a runtime or a dev dependency.
+	const dtPackagesPresent = new Map(allDeps.filter(isDTPackageEntry));
+
+	if (!existsSync(join(cwd, 'tsconfig.json'))) {
+		return {
+			present: dtPackagesPresent,
+			toAdd: new Map(),
+			toMove: new Map(),
+			toRemain: new Set(),
+			toRemove: dtPackagesPresent.keys().toArray(),
+		};
+	}
+
+	/** @type {(name: string) => Promise<Version | null>} */
+	async function installedVersion(name) {
+		try {
+			const pkgPath = /** @type {string} */ (findPackageJSON(name, anchor));
+			const { version } = JSON.parse(`${await readFile(pkgPath)}`);
+			return typeof version === 'string' ? version : null;
+		} catch {
+			return null;
+		}
+	}
+
+	/** @type {(name: string, declaredRange: string) => Promise<Version | null>} */
+	async function resolveVersion(name, declaredRange) {
+		const installed = await installedVersion(name);
+		if (installed !== null) {
+			return installed;
+		}
+		// keep any prerelease tag: a prerelease-only package (e.g. `1.0.0-beta.2`) has no coerced stable
+		// version on the registry, so dropping it would make the `@types` lookup miss
+		return semver.coerce(declaredRange, { includePrerelease: true })?.version ?? null;
+	}
+
+	// `node` is never a dependency, yet `@types/node` is always wanted, so it is exempt.
+	const nodeTypes = toDTName('node');
+
+	const pToRemove = Promise.all(dtPackagesPresent.keys()
+		.filter((name) => name !== nodeTypes)
+		.map(async (name) => {
+			const realName = fromDTName(name);
+			const range = deps.get(realName) ?? devDeps.get(realName);
+			// if the real package isn't a declared dependency it may still be installed (transitively, or
+			// as a type-only dependency whose types matter), so fall back to the installed version
+			const version = typeof range === 'undefined'
+				? await installedVersion(realName)
+				: await resolveVersion(realName, range);
+			if (version === null) {
+				// neither declared nor installed => a genuine orphan to remove; declared but unresolvable => keep
+				return /** @type {const} */ ([name, typeof range === 'undefined']);
+			}
+			// query the exact resolved version (a `major.minor` range can miss prerelease-only minors); a
+			// dependency whose lookup can't resolve is left alone rather than crashing the whole run
+			const shipsOwnTypes = await hasTypes(`${realName}@${version}`).catch(() => false) === true;
+			return /** @type {const} */ ([name, shipsOwnTypes]);
+		})
+		.toArray()).then((entries) => entries.filter(([, remove]) => remove).map(([name]) => name));
+
+	// `hastypes` returns `true` if `X` ships its own types, `false` if no `@types/X`
+	// exists, or the `@types/X` specifier string when one exists and is needed.
+	const pToAdd = Promise.all(allDeps
+		.filter(([name]) => !isDTPackageEntry([name, '']) && !dtPackagesPresent.has(toDTName(name)))
+		.map(async ([name, range]) => {
+			const version = await resolveVersion(name, range);
+			if (version === null) {
+				return null;
+			}
+			const result = await hasTypes(`${name}@${version}`).catch(() => null);
+			if (typeof result !== 'string') {
+				return null;
+			}
+			// `hastypes` resolves the `@types` specifier to a full caret range (`@types/x@^a.b.c`); use it as-is
+			const dtRange = result.slice(result.lastIndexOf('@') + 1);
+			return /** @type {const} */ ([toDTName(name), dtRange]);
+		}));
+
+	const [
+		toRemove,
+		toAdd,
+	] = await Promise.all([
+		pToRemove,
+		pToAdd,
+	]);
+
+	const removed = new Set(toRemove);
+
+	const toRemain = new Set(dtPackagesPresent.keys().filter((name) => !removed.has(name)));
+
+	const toMove = new Map(dtRuntimeDepsPresent.entries().filter(([name]) => !removed.has(name)));
+
+	return {
+		present: dtPackagesPresent,
+		toAdd: new Map(toAdd.filter((x) => x !== null)),
+		toMove,
+		toRemain,
+		toRemove,
+	};
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+	"name": "dt-clean",
+	"version": "1.0.0",
+	"description": "Ensures the only DefinitelyTyped (`@types`) packages you have installed are the ones you need",
+	"bin": "./bin.mjs",
+	"exports": {
+		"./package.json": "./package.json"
+	},
+	"imports": {
+		"#/*": "./*.mjs"
+	},
+	"scripts": {
+		"prepack": "npmignore --auto --commentLines=autogenerated",
+		"prepublish": "not-in-publish || npm run prepublishOnly",
+		"prepublishOnly": "safe-publish-latest",
+		"postlint": "tsc && attw -P",
+		"pretest": "npm run lint",
+		"test": "npm run tests-only",
+		"tests-only": "c8 tape 'test/*.mjs'",
+		"tests:live": "LIVE=1 tape 'test/fixtures.mjs'",
+		"tests:registry": "tape 'test/live/registry.mjs'",
+		"tests:projects": "tape 'test/live/projects.mjs'",
+		"lint": "eslint .",
+		"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/dt-clean.git"
+	},
+	"author": "Jordan Harband <ljharb@gmail.com>",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/ljharb/dt-clean/issues"
+	},
+	"homepage": "https://github.com/ljharb/dt-clean#readme",
+	"dependencies": {
+		"@definitelytyped/utils": "^0.1.14",
+		"es-errors": "^1.3.0",
+		"hastypes": "^4.0.4",
+		"pargs": "^1.4.2",
+		"semver": "^7.8.4"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.3",
+		"@ljharb/eslint-config": "^22.2.3",
+		"@ljharb/tsconfig": "^0.3.2",
+		"@types/node": "^25.9.3",
+		"@types/semver": "^7.7.1",
+		"auto-changelog": "^2.6.0",
+		"c8": "^11.0.0",
+		"eslint": "^10.5.0",
+		"esmock": "^2.7.6",
+		"globals": "^17.6.0",
+		"in-publish": "^2.0.1",
+		"npm-high-impact": "^1.13.0",
+		"npmignore": "^0.3.5",
+		"safe-publish-latest": "^2.0.0",
+		"tape": "^5.10.2",
+		"typescript": "next"
+	},
+	"engines": {
+		"node": "^24.16 || >= 26.3"
+	},
+	"auto-changelog": {
+		"output": "CHANGELOG.md",
+		"template": "keepachangelog",
+		"unreleased": false,
+		"commitLimit": false,
+		"backfillLimit": false,
+		"hideCredit": true
+	},
+	"publishConfig": {
+		"ignore": [
+			".github/workflows",
+			".c8rc.json",
+			"eslint.config.mjs",
+			"test",
+			"types"
+		]
+	}
+}

package/report.d.ts

@@ -0,0 +1,12 @@
+import type { DTDelta } from './getDelTa.d.ts';
+
+declare function formatReport(delta: formatReport.ReportDelta): string;
+
+declare namespace formatReport {
+    type ReportDelta = Pick<
+        DTDelta,
+        'present' | 'toAdd' | 'toMove' | 'toRemove'
+    >;
+}
+
+export = formatReport;

package/report.mjs

@@ -0,0 +1,82 @@
+const STATES = /** @type {const} */ ({
+	add: ['missing', 'add'],
+	keep: ['present', 'keep'],
+	move: ['present', 'move'],
+	remove: ['present', 'remove'],
+});
+
+/** @import { ReportDelta } from './report.d.ts' */
+
+/** @param {ReportDelta} delta */
+function toRows({
+	present,
+	toAdd,
+	toMove,
+	toRemove,
+}) {
+	const removed = new Set(toRemove);
+
+	const rows = present.entries().map(([name, version]) => {
+		const action = removed.has(name)
+			? 'remove'
+			: toMove.has(name)
+				? 'move'
+				: 'keep';
+
+		/** @typedef {typeof STATES[keyof typeof STATES][number]} State */
+
+		return /** @type {[typeof name, State, State, typeof version]} */ ([
+			name,
+			STATES[action][0],
+			STATES[action][1],
+			version,
+		]);
+	}).toArray();
+
+	toAdd.forEach((version, name) => {
+		rows.push([
+			name,
+			STATES.add[0],
+			STATES.add[1],
+			version,
+		]);
+	});
+
+	return rows.sort((a, b) => a[0].localeCompare(b[0]));
+}
+
+/** @param {string[]} headers @param {string[][]} rows */
+function table(headers, rows) {
+	const widths = headers.map((header, i) => Math.max(header.length, ...rows.map((row) => row[i].length)));
+
+	/** @param {string[]} cells */
+	function render(cells) {
+		return cells.map((cell, i) => cell.padEnd(widths[i])).join('  ').replace(/ +$/, '');
+	}
+	return /** @type {string[]} */ ([]).concat(
+		render(headers),
+		render(widths.map((width) => '-'.repeat(width))),
+		rows.map(render),
+	).join('\n');
+}
+
+/** @type {import('./report.d.ts')} */
+export default function formatReport(delta) {
+	const rows = toRows(delta);
+	if (rows.length === 0) {
+		return 'No `@types/*` packages are present or needed.';
+	}
+
+	/** @param {string} action */
+	function count(action) {
+		return rows.filter((row) => row[2] === action).length;
+	}
+	const summary = `${rows.length} \`@types/*\` package${rows.length === 1 ? '' : 's'}: ${count('keep')} keep, ${count('move')} move, ${count('remove')} remove, ${count('add')} add.`;
+
+	return `${table([
+		'Package',
+		'State',
+		'Action',
+		'Version',
+	], rows)}\n\n${summary}`;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"extends": "@ljharb/tsconfig",
+	"compilerOptions": {
+		"module": "NodeNext",
+		"target": "ESNext",
+		"types": [
+			"node",
+		],
+	},
+	"exclude": [
+		"coverage",
+	],
+}