dt-clean 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.1.0](https://github.com/ljharb/dt-clean/compare/v1.0.1...v1.1.0) - 2026-06-21
+
+### Commits
+
+- [New] add `--auto`, meant for the `dependencies` lifecycle script [`bc60a91`](https://github.com/ljharb/dt-clean/commit/bc60a91bf4f3e4d0964f8dcb71d1b0d1182612f9)
+- [Tests] treat taken-down registry packages as skipped, not failures [`d020cc6`](https://github.com/ljharb/dt-clean/commit/d020cc62dd06de08189eebfe45e79a372ec8e5a1)
+- [meta] run `dt-clean --setup` [`459cc0c`](https://github.com/ljharb/dt-clean/commit/459cc0cc3a5a2b64e498946c8930ae49899eb8b3)
+
+## [v1.0.1](https://github.com/ljharb/dt-clean/compare/v1.0.0...v1.0.1) - 2026-06-19
+
+### Commits
+
+- [Fix] exit nonzero when changes are needed [`7c19b07`](https://github.com/ljharb/dt-clean/commit/7c19b07735c33d4a757f822355fd7a02760f7aed)
+- [readme] use proper indefinite article [`a63be72`](https://github.com/ljharb/dt-clean/commit/a63be726dd3655a1e9bbecc7d8726b8637700888)
+- [Deps] update `semver` [`a93456c`](https://github.com/ljharb/dt-clean/commit/a93456cda93fbde6d1c23b5b76418a60c11b14ea)
+- [Dev Deps] downgrade `@types/node` [`7aa7c07`](https://github.com/ljharb/dt-clean/commit/7aa7c072d0003816e40591b7aa56cdcbe217fa92)
+
 ## v1.0.0 - 2026-06-19
 
 ### Commits

package/README.md

@@ -12,8 +12,8 @@ Ensures the only DefinitelyTyped (`@types/*`) packages you have installed are th
 `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.
+- **move**: a `@types/*` package is in `dependencies`, but belongs in `devDependencies`.
+- **remove**: a `@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
@@ -47,8 +47,60 @@ With `--update` (`-u`), `dt-clean` edits `package.json` in place - adding, movin
 ### Options
 
 - `-u`, `--update`: apply the changes to `package.json` (default: report only).
+- `--setup`: idempotently wire `dt-clean --auto` into a `dependencies` lifecycle script, without overwriting any existing script (see [Automatic cleanup](#automatic-cleanup)).
+- `--auto`: for use in a `dependencies` lifecycle script - apply the changes like `--update` during `npm install`, but during `npm ci` only print what would change and exit `0` (see [Automatic cleanup](#automatic-cleanup)).
 - `--help`: show usage.
 
+### Automatic cleanup
+
+To keep your `@types/*` set tidy on every install, run `dt-clean --auto` from a [`dependencies` lifecycle script](https://docs.npmjs.com/cli/using-npm/scripts#npm-install) - the one npm's installer (arborist) runs after any operation that changes `node_modules`.
+
+The one-step way to set this up, in any project, is:
+
+```sh
+npx dt-clean --setup
+```
+
+`--setup` edits `package.json` for you and is safe to run anywhere:
+
+- if you have no `dependencies` script, it adds `"dependencies": "dt-clean --auto"`;
+- if you already have one, it adds `dt-clean --auto` to a free `postdependencies` (or `predependencies`) hook instead, so your existing script is never touched - and if every hook is taken, it appends `&& dt-clean --auto` to your `dependencies` script rather than clobbering it;
+- if `dt-clean --auto` is already wired in, it does nothing.
+
+It only ever adds this one invocation and leaves the rest of your `package.json` (and its formatting) alone, so it's safe to re-run. The result is simply the equivalent of:
+
+```json
+{
+  "scripts": {
+    "dependencies": "dt-clean --auto"
+  }
+}
+```
+
+Once it's wired in, `dt-clean --auto` inspects `npm_command` to decide what to do:
+
+- under `npm install`, it applies the changes for you, so a fresh install keeps your `@types/*` set tidy automatically;
+- under `npm ci` (typically used in CI pipelines, where `package.json` must not be mutated), it only prints what would change and exits `0`, so it never edits a checked-in file and never fails the install.
+
+When `npm_command` is anything else (or absent), `--auto` applies the changes, exactly as under `npm install`.
+
+To avoid surprising edits, `--auto` runs *only* inside the `dependencies` lifecycle (or its `predependencies`/`postdependencies` hooks): it checks `npm_lifecycle_event`, and if it is invoked any other way (for example directly from the shell) it refuses to do anything and exits nonzero. Use `--update` to apply changes manually.
+
+### Exit codes
+
+In the default report-only mode, the exit code is a bitmask of the kinds of pending changes, so a clean project exits `0` and you can fail CI (or a `git` pre-commit hook) on drift:
+
+| Value | Meaning                                  |
+| ----- | ---------------------------------------- |
+| `1`   | there are `@types/*` packages to remove  |
+| `2`   | there are `@types/*` packages to add     |
+| `4`   | there are `@types/*` packages to move    |
+
+The bits combine, so a project that needs both an add and a remove exits `3`, and one that needs all three exits `7`.
+
+With `--update`, `dt-clean` applies the changes, leaving the project clean, so a successful run always exits `0`;
+a nonzero exit then means the update itself failed.
+
 [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

package/applyChanges.mjs

@@ -1,11 +1,7 @@
 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';
-}
+import detectIndent from '#/detectIndent';
 
 /** @type {<K extends string, V>(obj: Record<K, V>) => Record<K, V>} */
 function sortKeys(obj) {

package/bin.mjs

@@ -7,20 +7,37 @@ import pargs from 'pargs';
 import getDelTa from '#/getDelTa';
 import applyChanges from '#/applyChanges';
 import formatReport from '#/report';
+import exitCode from '#/exitCode';
+import setupScripts from '#/setup';
 
 const {
-	values: { json, update },
+	values: {
+		auto,
+		json,
+		setup,
+		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: {
+		auto: {
+			default: false,
+			description: 'for a `dependencies` lifecycle script (or its `pre`/`post` hooks): apply the changes like `--update` during `npm install`, but during `npm ci` only print what would change and exit zero',
+			type: 'boolean',
+		},
 		json: {
 			default: false,
 			description: 'print the result as JSON on stdout (the human-readable report moves to stderr)',
 			type: 'boolean',
 		},
+		setup: {
+			default: false,
+			description: 'idempotently add `dt-clean --auto` to a `dependencies` lifecycle script in `package.json`, without overwriting any existing script',
+			type: 'boolean',
+		},
 		update: {
 			default: false,
 			description: 'apply the changes to `package.json`, then run `npm install` (or your package manager\'s equivalent)',
@@ -35,43 +52,85 @@ await help();
 
 const cwd = positionals.length > 0 ? resolve(positionals[0]) : process.cwd();
 
-const {
-	present,
-	toAdd,
-	toMove,
-	toRemain,
-	toRemove,
-} = await getDelTa(cwd);
+const { npm_command: npmCommand, npm_lifecycle_event: lifecycleEvent } = process.env;
 
-const report = formatReport({
-	present,
-	toAdd,
-	toMove,
-	toRemove,
-});
+// the `dependencies` lifecycle and its `pre`/`post` hooks are the only safe slots for `--auto`,
+// since npm runs them after a reify; `postdependencies`/`predependencies` let you add it without
+// clobbering an existing `dependencies` script.
+const DEPENDENCY_HOOKS = [
+	'predependencies',
+	'dependencies',
+	'postdependencies',
+];
 
-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);
+if (setup) {
+	const { action, script } = await setupScripts(cwd);
+	console.log({
+		chained: `Appended \`dt-clean --auto\` to the existing \`${script}\` script in \`package.json\`.`,
+		present: `\`${script}\` already runs \`dt-clean --auto\`; nothing to do.`,
+		set: `Added \`dt-clean --auto\` to the \`${script}\` script in \`package.json\`.`,
+	}[action]);
+} else if (auto && (!lifecycleEvent || !DEPENDENCY_HOOKS.includes(lifecycleEvent))) {
+	console.error('`--auto` only runs inside a `dependencies` (or `pre`/`postdependencies`) lifecycle script (see the README); use `--update` to apply changes manually.');
+	process.exitCode = 1;
 } else {
-	console.log(report);
-}
+	const {
+		present,
+		toAdd,
+		toMove,
+		toRemain,
+		toRemove,
+	} = await getDelTa(cwd);
 
-if (update) {
-	const changed = await applyChanges(cwd, {
+	const report = formatReport({
+		present,
 		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`.');
+
+	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 || (auto && npmCommand !== 'ci')) {
+		// `--update` applies the changes, leaving the project clean, so a successful run exits zero;
+		// only an error (e.g. a failed write, which throws) yields a nonzero exit.
+		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 {
+		const code = exitCode({
+			toAdd,
+			toMove,
+			toRemove,
+		});
+		if (auto) {
+			// `--auto` under `npm ci`: leave the exit code at zero so a CI install never fails; the
+			// report above already lists what `npm install` would change.
+			if (code > 0) {
+				console.error('\n`npm ci` detected; `package.json` left unchanged. Run `npm install` or `dt-clean --update` to apply these changes.');
+			}
+		} else {
+			// report-only: the exit code is a bitmask of the pending change kinds, so a clean project exits zero.
+			process.exitCode = code;
+			if (code > 0) {
+				console.error('\nRe-run with `--update` (`-u`) to apply these changes to `package.json`.');
+			}
+		}
+	}
 }

package/detectIndent.d.ts

@@ -0,0 +1,3 @@
+declare function detectIndent(raw: string): string;
+
+export = detectIndent;

package/detectIndent.mjs

@@ -0,0 +1,5 @@
+/** @type {import('./detectIndent.d.ts')} */
+export default function detectIndent(raw) {
+	const match = (/^[ \t]+/m).exec(raw);
+	return match?.[0] ?? '\t';
+}

package/exitCode.mjs

@@ -0,0 +1,31 @@
+/** @import { DTDelta } from './getDelTa.d.ts' */
+
+export const TO_REMOVE = 1;
+export const TO_ADD = 2;
+export const TO_MOVE = 4;
+
+/** @typedef {1 | 2 | 4 | 3 | 6 | 7} PossibleExitCode */
+
+/**
+ * In report-only mode the exit code is a bitmask of the pending change kinds, so a clean
+ * delta is `0` and any combination of kinds combines (e.g. add + remove is `3`).
+ *
+ * @type {(delta: Pick<DTDelta, 'toAdd' | 'toMove' | 'toRemove'>) => PossibleExitCode}
+ */
+export default function exitCode({
+	toAdd,
+	toMove,
+	toRemove,
+}) {
+	let code = 0;
+	if (toRemove.length > 0) {
+		code |= TO_REMOVE;
+	}
+	if (toAdd.size > 0) {
+		code |= TO_ADD;
+	}
+	if (toMove.size > 0) {
+		code |= TO_MOVE;
+	}
+	return /** @type {PossibleExitCode} */ (code);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dt-clean",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "Ensures the only DefinitelyTyped (`@types`) packages you have installed are the ones you need",
 	"bin": "./bin.mjs",
 	"exports": {
@@ -23,7 +23,8 @@
 		"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)\")\""
+		"postversion": "auto-changelog && git add CHANGELOG.md && git commit --no-edit --amend && git tag -f \"v$(node -e \"console.log(require('./package.json').version)\")\"",
+		"dependencies": "dt-clean --auto"
 	},
 	"repository": {
 		"type": "git",
@@ -40,13 +41,13 @@
 		"es-errors": "^1.3.0",
 		"hastypes": "^4.0.4",
 		"pargs": "^1.4.2",
-		"semver": "^7.8.4"
+		"semver": "^7.8.5"
 	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "^0.18.3",
 		"@ljharb/eslint-config": "^22.2.3",
 		"@ljharb/tsconfig": "^0.3.2",
-		"@types/node": "^25.9.3",
+		"@types/node": "^24.13.2",
 		"@types/semver": "^7.7.1",
 		"auto-changelog": "^2.6.0",
 		"c8": "^11.0.0",

package/setup.d.ts

@@ -0,0 +1,12 @@
+declare function setup(cwd: string): Promise<setup.SetupResult>;
+
+declare namespace setup {
+    type DependencyHook = 'predependencies' | 'dependencies' | 'postdependencies';
+
+    type SetupResult = {
+        action: 'present' | 'set' | 'chained';
+        script: DependencyHook;
+    };
+}
+
+export = setup;

package/setup.mjs

@@ -0,0 +1,57 @@
+import { join } from 'path';
+import { readFile, writeFile } from 'fs/promises';
+
+import detectIndent from '#/detectIndent';
+
+/** @import { PackageJSON } from './types/types.d.ts' */
+/** @import { SetupResult } from './setup.d.ts' */
+
+const AUTO = 'dt-clean --auto';
+
+// listed most-preferred first: the `dependencies` event itself, then its `post`/`pre` hooks.
+const HOOKS = /** @type {const} */ ([
+	'dependencies',
+	'postdependencies',
+	'predependencies',
+]);
+
+/** @param {string | undefined} script */
+function hasAuto(script) {
+	// matches a `dt-clean … --auto` invocation confined to one `&&`/`;`/`|`-delimited segment
+	return typeof script === 'string' && (/\bdt-clean\b[^&|;]*--auto\b/).test(script);
+}
+
+/** @type {import('./setup.d.ts')} */
+export default async function setup(cwd) {
+	const packageJSONpath = join(cwd, 'package.json');
+	const raw = `${await readFile(packageJSONpath)}`;
+
+	/** @type {PackageJSON} */
+	const pkg = JSON.parse(raw);
+
+	/** @type {NonNullable<PackageJSON['scripts']>} */
+	const scripts = { ...pkg.scripts };
+
+	const present = HOOKS.find((hook) => hasAuto(scripts[hook]));
+	if (present) {
+		return { action: 'present', script: present };
+	}
+
+	const free = HOOKS.find((hook) => !scripts[hook]);
+
+	/** @type {SetupResult} */
+	let result;
+	if (free) {
+		scripts[free] = AUTO;
+		result = { action: 'set', script: free };
+	} else {
+		// every hook is occupied, so chain onto `dependencies` rather than clobber anything.
+		scripts.dependencies = `${scripts.dependencies} && ${AUTO}`;
+		result = { action: 'chained', script: 'dependencies' };
+	}
+
+	const next = { ...pkg, scripts };
+	await writeFile(packageJSONpath, `${JSON.stringify(next, null, detectIndent(raw))}\n`);
+
+	return result;
+}