DevToolz
A CLI with a set of independent commands for routine dev chores — clears junk out of the code, fixes broken paths in package.json, checks doc examples against the real code.
When you'd reach for this
Fourteen independent commands are rarely called one at a time — here are four moments in working on a package where several of them solve the same problem together.
Junk piles up while you work
Commented-out code, a forgotten console.log, an empty catch block, and a "TODO: fix this later" note — the usual pile by commit time, not worth cleaning up by hand. strip-comments, console-strip, empty-catch, and todo-report catch all of it in one pass, without touching what should stay.
Package structure before you publish
Before npm publish, you want confidence in the package's own structure: no dead export, no forgotten or phantom dependency, no import cycle, no path in package.json pointing at nothing. dead-exports, unused-deps, circular-imports, and exports-doctor check all of it in one pass.
Docs and CI shouldn't lie
A README example copied from working code once, and an npm run command mentioned in a CI config, both drift from reality easily while the package keeps changing — and a reader or a red build notices first, not you. readme-check typechecks examples against the real build; scripts-check cross-checks mentioned scripts against what package.json actually declares.
Right yesterday, wrong today
Three moments where code was right when it was written and quietly stopped being right: an import whose case drifted works on Windows and fails on Linux CI, a test stays green long after its source got renamed, a // @ts-ignore keeps quiet even though the error under it is a different one now. case-check, orphan-tests, and stale-ts-ignore catch exactly that kind of drift.
At a glance
Comment removal
strip-comments clears out //, /* */, /** */, and <!-- --> — including .vue files, where <script> goes through the same parser and <!-- --> inside <template> through a line-aware scan. --keep-jsdoc leaves a /** */ directly above an exported declaration alone, so IDE tooltips survive.
Debug output removal
console-strip removes console.log/console.debug/debugger calls left in by mistake — console.warn/console.error are left alone by default, often legitimate production logging rather than debug leftovers. Only a call that's a whole statement on its own gets deleted; one that's part of a larger expression is just listed separately.
Dead export detection
dead-exports finds named exports nothing in the project imports, while understanding the difference between "unused inside the repo" and "unused, period" — a package's own public entry points are exempt by default, and --strict checks them too when that's actually wanted.
Import case checking
case-check finds imports whose case doesn't match the real file on disk — something Windows and macOS forgive and Linux CI doesn't. Every path segment is checked, including tsconfig.json aliases; --fix rewrites the specifier to its real case.
package.json exports diagnostics
exports-doctor resolves every path package.json declares (main/module/types/bin/exports) against what's actually on disk — including the sneaky case where the runtime path resolves fine but no types are declared for that same path anywhere.
README example typechecking
readme-check pulls fenced ts code blocks out of README/docs and actually typechecks them with the TypeScript Compiler API against the package's own build — including a self-referencing import by the package's published name. Nothing ever runs, only compiles.
Unused dependency detection
unused-deps finds package.json dependencies nothing imports, and the reverse — "phantom" dependencies genuinely used but never declared. Aware of the usual ways a package gets used without a direct import, like being invoked from scripts or mentioned in a config file.
Circular import detection
circular-imports finds import cycles in your own code — the kind that can silently produce undefined at runtime in ESM. Shows every cycle as its full chain, and one made entirely of import type is hidden by default — that's not a runtime bug.
Empty catch block detection
empty-catch finds catch blocks that do nothing with the error, or do so little it's effectively swallowed — a body that's nothing but console.* calls, with no throw and no write to an outer-scope variable. A comment inside the block exempts the finding.
TODO comment summary
todo-report collects TODO/FIXME/HACK comments across the whole project into one list — file:line plus the note's actual text, even one wrapped across several lines. --max turns the default "fail on any finding" into a ratchet for debt a project already knows about.
npm script consistency check
scripts-check cross-checks package.json's scripts against README and .github/workflows — a mentioned but undeclared script is a real broken link, a declared but never-mentioned one is a weaker signal. npm's own reserved lifecycle scripts are exempt.
Orphan test detection
orphan-tests finds test files whose source disappeared — renamed or deleted, the test still green and testing nothing real anymore. Reliable under a simple naming convention: X.test.ts next to X.ts, or in a sibling __tests__ directory.
Stale @ts-ignore detection
stale-ts-ignore finds a // @ts-ignore that no longer suppresses anything — the code below it was fixed, the comment wasn't removed, and now it silently hides whatever different error shows up there next. Runs a real project-wide typecheck twice and compares the delta.
Web interface
devtoolz ui starts a local web interface: forms, tables and previews instead of flags, a file browser for picking folders, findings next to the code, import cycles as a graph. File changes are approved one by one, with a backup and an undo. The server listens on 127.0.0.1 only, behind a one-time token.
