deslop-cli 0.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Million Software, Inc.
+
+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,67 @@
+# deslop-cli
+
+CLI for [deslop-js](https://github.com/aidenybai/deslop-js) — find unused files, exports, dependencies, and circular imports.
+
+## Install
+
+```bash
+npm install -g deslop-cli
+```
+
+Requires Node.js 22 or later.
+
+## Usage
+
+Pass an explicit project root when possible (especially in monorepos):
+
+```bash
+deslop ./my-app
+deslop analyze ./my-app
+```
+
+Analyze the current directory:
+
+```bash
+deslop
+```
+
+Output JSON:
+
+```bash
+deslop ./my-app --json
+```
+
+Fail CI when unused code is found (files, exports, or dependencies — not circular imports):
+
+```bash
+deslop ./my-app --fail-on-issues
+```
+
+Fail CI when circular imports are found:
+
+```bash
+deslop ./my-app --fail-on-cycles
+```
+
+### Options
+
+| Option                    | Description                                                       |
+| ------------------------- | ----------------------------------------------------------------- |
+| `[root]`                  | Project root directory (default: `.`; must exist)                 |
+| `-e, --entry <pattern>`   | Entry point glob patterns                                         |
+| `-i, --ignore <pattern>`  | Glob patterns to exclude                                          |
+| `--extensions <ext>`      | File extensions to scan (e.g. `.ts` `.vue`)                        |
+| `--tsconfig <path>`       | Path to tsconfig.json for alias resolution                        |
+| `--report-types`          | Include type-only exports in results                              |
+| `--include-entry-exports` | Report unused exports from entry files                            |
+| `--json`                  | Output results as JSON                                            |
+| `--fail-on-issues`        | Exit 1 when unused files, exports, or dependencies are found      |
+| `--fail-on-cycles`        | Exit 1 when circular imports are found                            |
+
+### Exit codes
+
+| Code | Meaning                                      |
+| ---- | -------------------------------------------- |
+| `0`  | Success (no failure flags triggered)         |
+| `1`  | Issues found (per `--fail-on-*` flags) or runtime error |
+| `2`  | Invalid project root                         |

package/dist/cli.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { analyze, defineConfig } from "deslop-js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/constants.ts
+const PACKAGE_JSON_FILENAME = "package.json";
+const MISSING_PACKAGE_JSON_WARNING = "Warning: no package.json found in project root; dependency analysis may be incomplete.";
+
+//#endregion
+//#region src/format-result.ts
+const formatIssueCount = (count, singularLabel, pluralLabel) => {
+	return `${count} unused ${count === 1 ? singularLabel : pluralLabel}`;
+};
+const formatHumanReadableResult = (result) => {
+	const lines = [];
+	lines.push(`Analyzed ${result.totalFiles} files (${result.totalExports} exports) in ${result.analysisTimeMs.toFixed(0)}ms`);
+	lines.push("");
+	if (result.unusedFiles.length > 0) {
+		lines.push(formatIssueCount(result.unusedFiles.length, "file", "files"));
+		for (const unusedFile of result.unusedFiles) lines.push(`  ${unusedFile.path}`);
+		lines.push("");
+	}
+	if (result.unusedExports.length > 0) {
+		lines.push(formatIssueCount(result.unusedExports.length, "export", "exports"));
+		for (const unusedExport of result.unusedExports) lines.push(`  ${unusedExport.path}:${unusedExport.line}  ${unusedExport.name}`);
+		lines.push("");
+	}
+	if (result.unusedDependencies.length > 0) {
+		lines.push(formatIssueCount(result.unusedDependencies.length, "dependency", "dependencies"));
+		for (const unusedDependency of result.unusedDependencies) {
+			const dependencyKind = unusedDependency.isDevDependency ? "dev" : "prod";
+			lines.push(`  ${unusedDependency.name} (${dependencyKind})`);
+		}
+		lines.push("");
+	}
+	if (result.circularDependencies.length > 0) {
+		const cycleLabel = result.circularDependencies.length === 1 ? "cycle" : "cycles";
+		lines.push(`${result.circularDependencies.length} circular ${cycleLabel}`);
+		for (const circularDependency of result.circularDependencies) lines.push(`  ${circularDependency.files.join(" → ")}`);
+		lines.push("");
+	}
+	if (result.unusedFiles.length + result.unusedExports.length + result.unusedDependencies.length + result.circularDependencies.length === 0) lines.push("No unused files, exports, dependencies, or circular imports found.");
+	return lines.join("\n").trimEnd() + "\n";
+};
+const hasUnusedIssues = (result) => result.unusedFiles.length > 0 || result.unusedExports.length > 0 || result.unusedDependencies.length > 0;
+const hasCircularIssues = (result) => result.circularDependencies.length > 0;
+
+//#endregion
+//#region src/utils/validate-root-directory.ts
+const validateRootDirectory = (root) => {
+	const resolvedPath = resolve(root);
+	if (!existsSync(resolvedPath)) return {
+		isValid: false,
+		resolvedPath,
+		errorMessage: `Project root does not exist: ${resolvedPath}`,
+		missingPackageJson: false
+	};
+	if (!statSync(resolvedPath).isDirectory()) return {
+		isValid: false,
+		resolvedPath,
+		errorMessage: `Project root is not a directory: ${resolvedPath}`,
+		missingPackageJson: false
+	};
+	return {
+		isValid: true,
+		resolvedPath,
+		missingPackageJson: !existsSync(join(resolvedPath, PACKAGE_JSON_FILENAME))
+	};
+};
+
+//#endregion
+//#region src/run-analyze.ts
+const defaultAnalyzeOutput = () => ({
+	stdout: process.stdout,
+	stderr: process.stderr
+});
+const resolveAnalyzeExitCode = (result, options) => {
+	if (options.failOnIssues && hasUnusedIssues(result)) return 1;
+	if (options.failOnCycles && hasCircularIssues(result)) return 1;
+	return 0;
+};
+const runAnalyze = async (options, output = defaultAnalyzeOutput()) => {
+	const rootValidation = validateRootDirectory(options.root);
+	if (!rootValidation.isValid) {
+		output.stderr.write(`deslop: ${rootValidation.errorMessage}\n`);
+		return 2;
+	}
+	if (rootValidation.missingPackageJson) output.stderr.write(`deslop: ${MISSING_PACKAGE_JSON_WARNING}\n`);
+	const result = await analyze(defineConfig({
+		rootDir: rootValidation.resolvedPath,
+		entryPatterns: options.entry,
+		ignorePatterns: options.ignore ?? [],
+		includeExtensions: options.extensions,
+		tsConfigPath: options.tsconfig,
+		reportTypes: options.reportTypes,
+		includeEntryExports: options.includeEntryExports
+	}));
+	if (options.json) output.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+	else output.stdout.write(formatHumanReadableResult(result));
+	return resolveAnalyzeExitCode(result, options);
+};
+
+//#endregion
+//#region src/utils/read-package-version.ts
+const isPackageJsonWithVersion = (value) => typeof value === "object" && value !== null && "version" in value && typeof value.version === "string";
+const readPackageVersion = (moduleUrl) => {
+	const packageJsonPath = resolve(dirname(fileURLToPath(moduleUrl)), "../package.json");
+	const parsedJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+	if (!isPackageJsonWithVersion(parsedJson)) throw new Error(`Invalid package.json at ${packageJsonPath}: missing version field`);
+	return parsedJson.version;
+};
+
+//#endregion
+//#region src/cli.ts
+const toAnalyzeOptions = (root, optionValues) => ({
+	root: root ?? ".",
+	entry: optionValues.entry,
+	ignore: optionValues.ignore,
+	extensions: optionValues.extensions,
+	tsconfig: optionValues.tsconfig,
+	reportTypes: Boolean(optionValues.reportTypes),
+	includeEntryExports: Boolean(optionValues.includeEntryExports),
+	json: Boolean(optionValues.json),
+	failOnIssues: Boolean(optionValues.failOnIssues),
+	failOnCycles: Boolean(optionValues.failOnCycles)
+});
+const runAnalyzeAction = async (root, optionValues) => {
+	const exitCode = await runAnalyze(toAnalyzeOptions(root, optionValues));
+	process.exitCode = exitCode;
+};
+const addAnalyzeOptions = (command) => command.argument("[root]", "project root directory", ".").option("-e, --entry <pattern...>", "entry point glob patterns").option("-i, --ignore <pattern...>", "glob patterns to exclude from analysis").option("--extensions <extension...>", "file extensions to scan (e.g. .ts .vue)").option("--tsconfig <path>", "path to tsconfig.json for path alias resolution").option("--report-types", "include type-only exports in results").option("--include-entry-exports", "report unused exports from entry files").option("--json", "output results as JSON").option("--fail-on-issues", "exit with code 1 when unused files, exports, or dependencies are found").option("--fail-on-cycles", "exit with code 1 when circular imports are found");
+const program = new Command();
+program.name("deslop").description("Find unused files, exports, dependencies, and circular imports in JavaScript projects").version(readPackageVersion(import.meta.url));
+addAnalyzeOptions(program).action(runAnalyzeAction);
+addAnalyzeOptions(program.command("analyze").description("Find unused files, exports, dependencies, and circular imports")).action(runAnalyzeAction);
+program.parseAsync(process.argv).catch((error) => {
+	const message = error instanceof Error ? error.stack ?? error.message : String(error);
+	process.stderr.write(`deslop: ${message}\n`);
+	process.exitCode = 1;
+});
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "deslop-cli",
+  "version": "0.0.10",
+  "description": "CLI for deslop-js — find unused files, exports, and dependencies",
+  "keywords": [
+    "cli",
+    "dead-code",
+    "dependencies",
+    "exports",
+    "javascript",
+    "typescript",
+    "unused"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Aiden Bai",
+    "email": "aiden@million.dev"
+  },
+  "type": "module",
+  "bin": {
+    "deslop": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "deslop-js": "0.0.10"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}