deslop-cli 0.0.10 → 0.0.12

package/README.md

@@ -1,6 +1,8 @@
 # deslop-cli
 
-CLI for [deslop-js](https://github.com/aidenybai/deslop-js) — find unused files, exports, dependencies, and circular imports.
+Deslop JavaScript code.
+
+CLI for [deslop-js](https://github.com/aidenybai/deslop-js). Finds unused files, dead exports, dead dependencies, circular imports, redundant aliases, duplicate types, and other DRY violations.
 
 ## Install
 
@@ -25,13 +27,13 @@ Analyze the current directory:
 deslop
 ```
 
-Output JSON:
+Output JSON for programmatic consumption:
 
 ```bash
 deslop ./my-app --json
 ```
 
-Fail CI when unused code is found (files, exports, or dependencies — not circular imports):
+Fail CI when unused code is found (files, exports, or dependencies, not circular imports):
 
 ```bash
 deslop ./my-app --fail-on-issues
@@ -43,6 +45,30 @@ Fail CI when circular imports are found:
 deslop ./my-app --fail-on-cycles
 ```
 
+## What `deslop` reports
+
+The default scan emits the following finding categories (each grouped in human output, fully detailed in `--json`):
+
+| Category                  | What it catches                                                                  |
+| ------------------------- | -------------------------------------------------------------------------------- |
+| `unusedFiles`             | Files unreachable from any entry point                                           |
+| `unusedExports`           | Exported symbols never imported anywhere                                         |
+| `unusedDependencies`      | `package.json` deps not imported                                                 |
+| `circularDependencies`    | Import cycles                                                                    |
+| `redundantAliases`        | `import { x as x }`, useless re-export renames                                   |
+| `duplicateExports`        | Same name exported twice from one module                                         |
+| `duplicateImports`        | Same specifier imported on multiple lines (merge them)                           |
+| `redundantTypePatterns`   | `T & {}`, `Partial<Partial<T>>`, `Pick<T, keyof T>`, empty `extends`             |
+| `identityWrappers`        | `const wrap = (x) => fn(x)`, calls without transforming                          |
+| `duplicateTypeDefinitions`| Same structural type declared in multiple files                                  |
+| `duplicateInlineTypes`    | Anonymous `{ a, b, c }` shapes repeated across modules                           |
+| `simplifiableFunctions`   | `(x) => { return f(x) }`, `await x; return x;`, useless `async`                  |
+| `simplifiableExpressions` | `!!x`, `x ? x : y`, `cond ? true : false`, `x !== null && x !== undefined`       |
+| `duplicateConstants`      | Same literal value used in N files under different names                         |
+| `analysisErrors`          | Structured info / warning / error notes (parse failures, skipped files, etc.)    |
+
+Type-aware findings (`unusedTypes`, `unusedClassMembers`, `misclassifiedDependencies`, etc.) require enabling the semantic layer programmatically. See the [`deslop-js` README](https://github.com/aidenybai/deslop-js#semantic-type-aware-analysis). They are not exposed via CLI flags yet.
+
 ### Options
 
 | Option                    | Description                                                       |
@@ -50,7 +76,7 @@ deslop ./my-app --fail-on-cycles
 | `[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`)                        |
+| `--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                            |
@@ -60,8 +86,16 @@ deslop ./my-app --fail-on-cycles
 
 ### Exit codes
 
-| Code | Meaning                                      |
-| ---- | -------------------------------------------- |
-| `0`  | Success (no failure flags triggered)         |
+| Code | Meaning                                                 |
+| ---- | ------------------------------------------------------- |
+| `0`  | Success (no failure flags triggered)                    |
 | `1`  | Issues found (per `--fail-on-*` flags) or runtime error |
-| `2`  | Invalid project root                         |
+| `2`  | Invalid project root                                    |
+
+### Confidence tiers
+
+Every redundancy finding carries a confidence tier (`high` / `medium` / `low`) visible in human and JSON output. Use `high` for CI gates; `medium` and `low` are best as code-review prompts. Some patterns flagged at `medium` (`x ?? null`, single-name `duplicateConstants` across packages) have legitimate intent ripgrep alone can't disambiguate.
+
+### Skipped files
+
+Files identified as empty, binary, or minified bundles are skipped with an `info`-severity `analysisErrors` note. This isn't an error. It means the file looked machine-generated or non-source and was excluded from analysis to avoid producing irrelevant findings.

package/dist/cli.mjs

@@ -42,10 +42,121 @@ const formatHumanReadableResult = (result) => {
 		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.");
+	if (result.unusedTypes.length > 0) {
+		const typeLabel = result.unusedTypes.length === 1 ? "type" : "types";
+		lines.push(`${result.unusedTypes.length} unused ${typeLabel}`);
+		for (const unusedType of result.unusedTypes) lines.push(`  ${unusedType.path}:${unusedType.line}  ${unusedType.name} (${unusedType.kind}, ${unusedType.confidence})`);
+		lines.push("");
+	}
+	if (result.unusedEnumMembers.length > 0) {
+		const memberLabel = result.unusedEnumMembers.length === 1 ? "enum member" : "enum members";
+		lines.push(`${result.unusedEnumMembers.length} unused ${memberLabel}`);
+		for (const unusedMember of result.unusedEnumMembers) lines.push(`  ${unusedMember.path}:${unusedMember.line}  ${unusedMember.enumName}.${unusedMember.memberName} (${unusedMember.confidence})`);
+		lines.push("");
+	}
+	if (result.unusedClassMembers.length > 0) {
+		const classLabel = result.unusedClassMembers.length === 1 ? "class member" : "class members";
+		lines.push(`${result.unusedClassMembers.length} unused ${classLabel}`);
+		for (const unusedMember of result.unusedClassMembers) lines.push(`  ${unusedMember.path}:${unusedMember.line}  ${unusedMember.className}.${unusedMember.memberName} (${unusedMember.memberKind}, ${unusedMember.confidence})`);
+		lines.push("");
+	}
+	if (result.misclassifiedDependencies.length > 0) {
+		const depLabel = result.misclassifiedDependencies.length === 1 ? "dependency" : "dependencies";
+		lines.push(`${result.misclassifiedDependencies.length} misclassified ${depLabel}`);
+		for (const finding of result.misclassifiedDependencies) lines.push(`  ${finding.name}  ${finding.declaredAs} → ${finding.suggestedAs} (${finding.confidence})`);
+		lines.push("");
+	}
+	if (result.redundantAliases.length > 0) {
+		const aliasLabel = result.redundantAliases.length === 1 ? "alias" : "aliases";
+		lines.push(`${result.redundantAliases.length} redundant ${aliasLabel}`);
+		for (const finding of result.redundantAliases) lines.push(`  ${finding.path}:${finding.line}  [${finding.kind}] ${finding.name}`);
+		lines.push("");
+	}
+	if (result.duplicateExports.length > 0) {
+		const exportLabel = result.duplicateExports.length === 1 ? "export" : "exports";
+		lines.push(`${result.duplicateExports.length} duplicate ${exportLabel}`);
+		for (const finding of result.duplicateExports) lines.push(`  ${finding.path}  ${finding.name} (${finding.occurrences.length}x)`);
+		lines.push("");
+	}
+	if (result.duplicateImports.length > 0) {
+		const importLabel = result.duplicateImports.length === 1 ? "import" : "imports";
+		lines.push(`${result.duplicateImports.length} duplicate ${importLabel}`);
+		for (const finding of result.duplicateImports) lines.push(`  ${finding.path}  ${finding.specifier} (${finding.occurrences.length}x)`);
+		lines.push("");
+	}
+	if (result.redundantTypePatterns.length > 0) {
+		const patternLabel = result.redundantTypePatterns.length === 1 ? "type pattern" : "type patterns";
+		lines.push(`${result.redundantTypePatterns.length} redundant ${patternLabel}`);
+		for (const finding of result.redundantTypePatterns) lines.push(`  ${finding.path}:${finding.line}  ${finding.typeName} [${finding.kind}] → ${finding.suggestion}`);
+		lines.push("");
+	}
+	if (result.identityWrappers.length > 0) {
+		const wrapperLabel = result.identityWrappers.length === 1 ? "wrapper" : "wrappers";
+		lines.push(`${result.identityWrappers.length} identity ${wrapperLabel}`);
+		for (const finding of result.identityWrappers) lines.push(`  ${finding.path}:${finding.line}  ${finding.wrapperName} → ${finding.wrappedExpression}`);
+		lines.push("");
+	}
+	if (result.duplicateTypeDefinitions.length > 0) {
+		const defLabel = result.duplicateTypeDefinitions.length === 1 ? "type definition group" : "type definition groups";
+		lines.push(`${result.duplicateTypeDefinitions.length} duplicate ${defLabel}`);
+		for (const finding of result.duplicateTypeDefinitions) {
+			const instanceLabels = finding.instances.map((instance) => `${instance.typeName}@${instance.path}:${instance.line}`).join(", ");
+			lines.push(`  [${finding.confidence}] ${instanceLabels}`);
+		}
+		lines.push("");
+	}
+	if (result.analysisErrors.length > 0) {
+		const fatalCount = result.analysisErrors.filter((error) => error.severity === "fatal").length;
+		const warningCount = result.analysisErrors.filter((error) => error.severity === "warning").length;
+		const infoCount = result.analysisErrors.filter((error) => error.severity === "info").length;
+		const counts = [
+			fatalCount > 0 ? `${fatalCount} fatal` : null,
+			warningCount > 0 ? `${warningCount} warning` : null,
+			infoCount > 0 ? `${infoCount} info` : null
+		].filter((entry) => entry !== null).join(", ");
+		lines.push(`${result.analysisErrors.length} analysis ${result.analysisErrors.length === 1 ? "error" : "errors"} (${counts})`);
+		for (const error of result.analysisErrors.slice(0, 20)) {
+			const location = error.path ? ` ${error.path}` : "";
+			lines.push(`  [${error.severity}/${error.module}/${error.code}]${location}  ${error.message}`);
+		}
+		if (result.analysisErrors.length > 20) lines.push(`  … and ${result.analysisErrors.length - 20} more`);
+		lines.push("");
+	}
+	if (result.duplicateInlineTypes.length > 0) {
+		const inlineLabel = result.duplicateInlineTypes.length === 1 ? "inline type group" : "inline type groups";
+		lines.push(`${result.duplicateInlineTypes.length} duplicate ${inlineLabel}`);
+		for (const finding of result.duplicateInlineTypes) {
+			lines.push(`  [${finding.confidence}] ${finding.preview} (${finding.occurrences.length} sites)`);
+			for (const occurrence of finding.occurrences) lines.push(`    ${occurrence.path}:${occurrence.line}  ${occurrence.context}${occurrence.nearestName ? `  ${occurrence.nearestName}` : ""}`);
+		}
+		lines.push("");
+	}
+	if (result.simplifiableFunctions.length > 0) {
+		const fnLabel = result.simplifiableFunctions.length === 1 ? "function" : "functions";
+		lines.push(`${result.simplifiableFunctions.length} simplifiable ${fnLabel}`);
+		for (const finding of result.simplifiableFunctions) lines.push(`  ${finding.path}:${finding.line}  [${finding.kind}, ${finding.confidence}] ${finding.functionName ?? "?"} → ${finding.suggestion}`);
+		lines.push("");
+	}
+	if (result.simplifiableExpressions.length > 0) {
+		const exprLabel = result.simplifiableExpressions.length === 1 ? "expression" : "expressions";
+		lines.push(`${result.simplifiableExpressions.length} simplifiable ${exprLabel}`);
+		for (const finding of result.simplifiableExpressions) lines.push(`  ${finding.path}:${finding.line}  [${finding.kind}, ${finding.confidence}] ${finding.snippet} → ${finding.suggestion}`);
+		lines.push("");
+	}
+	if (result.duplicateConstants.length > 0) {
+		const constLabel = result.duplicateConstants.length === 1 ? "constant group" : "constant groups";
+		lines.push(`${result.duplicateConstants.length} duplicate ${constLabel}`);
+		for (const finding of result.duplicateConstants) {
+			lines.push(`  [${finding.confidence}] ${finding.literalPreview} (${finding.occurrences.length} copies)`);
+			for (const occurrence of finding.occurrences.slice(0, 3)) lines.push(`    ${occurrence.path}:${occurrence.line}  const ${occurrence.constantName}`);
+			if (finding.occurrences.length > 3) lines.push(`    … and ${finding.occurrences.length - 3} more`);
+		}
+		lines.push("");
+	}
+	if (result.unusedFiles.length + result.unusedExports.length + result.unusedDependencies.length + result.circularDependencies.length + result.unusedTypes.length + result.unusedEnumMembers.length + result.unusedClassMembers.length + result.misclassifiedDependencies.length + result.redundantAliases.length + result.duplicateExports.length + result.duplicateImports.length + result.redundantTypePatterns.length + result.identityWrappers.length + result.duplicateTypeDefinitions.length + result.duplicateInlineTypes.length + result.simplifiableFunctions.length + result.simplifiableExpressions.length + result.duplicateConstants.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 hasUnusedIssues = (result) => result.unusedFiles.length > 0 || result.unusedExports.length > 0 || result.unusedDependencies.length > 0 || result.unusedTypes.length > 0 || result.unusedEnumMembers.length > 0 || result.unusedClassMembers.length > 0 || result.misclassifiedDependencies.length > 0 || result.redundantAliases.length > 0 || result.duplicateExports.length > 0 || result.duplicateImports.length > 0 || result.redundantTypePatterns.length > 0 || result.identityWrappers.length > 0 || result.duplicateTypeDefinitions.length > 0 || result.duplicateInlineTypes.length > 0 || result.simplifiableFunctions.length > 0 || result.simplifiableExpressions.length > 0 || result.duplicateConstants.length > 0;
 const hasCircularIssues = (result) => result.circularDependencies.length > 0;
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deslop-cli",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "CLI for deslop-js — find unused files, exports, and dependencies",
   "keywords": [
     "cli",
@@ -16,7 +16,6 @@
     "name": "Aiden Bai",
     "email": "aiden@million.dev"
   },
-  "type": "module",
   "bin": {
     "deslop": "./dist/cli.mjs"
   },
@@ -26,18 +25,19 @@
     "README.md",
     "LICENSE"
   ],
-  "engines": {
-    "node": ">=22"
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
     "commander": "^14.0.3",
-    "deslop-js": "0.0.10"
+    "deslop-js": "0.0.12"
   },
   "devDependencies": {
     "@types/node": "^25.6.0"
   },
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=22"
   },
   "scripts": {
     "build": "vp pack",