dt-clean 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.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
@@ -49,6 +49,21 @@ With `--update` (`-u`), `dt-clean` edits `package.json` in place - adding, movin
 - `-u`, `--update`: apply the changes to `package.json` (default: report only).
 - `--help`: show usage.
 
+### 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/bin.mjs

@@ -7,6 +7,7 @@ import pargs from 'pargs';
 import getDelTa from '#/getDelTa';
 import applyChanges from '#/applyChanges';
 import formatReport from '#/report';
+import exitCode from '#/exitCode';
 
 const {
 	values: { json, update },
@@ -64,6 +65,8 @@ if (json) {
 }
 
 if (update) {
+	// `--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,
@@ -72,6 +75,15 @@ if (update) {
 	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`.');
+} else {
+	// report-only: the exit code is a bitmask of the pending change kinds, so a clean project exits zero.
+	const code = exitCode({
+		toAdd,
+		toMove,
+		toRemove,
+	});
+	process.exitCode = code;
+	if (code > 0) {
+		console.error('\nRe-run with `--update` (`-u`) to apply these changes to `package.json`.');
+	}
 }

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.0.1",
 	"description": "Ensures the only DefinitelyTyped (`@types`) packages you have installed are the ones you need",
 	"bin": "./bin.mjs",
 	"exports": {
@@ -40,13 +40,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",