ts-unused 1.0.0 → 1.0.1

package/README.md

@@ -9,7 +9,8 @@ A CLI tool that analyzes TypeScript projects to find unused exports and unused p
 - **Finds Unused Exports**: Identifies functions, classes, types, interfaces, and constants that are exported but never imported or used elsewhere
 - **Finds Completely Unused Files**: Identifies files where all exports are unused, suggesting the entire file can be deleted
 - **Finds Unused Type Properties**: Detects properties in interfaces and type aliases that are defined but never accessed
-- **Auto-Fix Command**: Automatically removes unused exports, properties, and deletes unused files with git safety checks
+- **Finds Never-Returned Types**: Detects union type branches in function return types that are declared but never actually returned
+- **Auto-Fix Command**: Automatically removes unused exports, properties, deletes unused files, and fixes never-returned types with git safety checks
 - **Structural Property Equivalence**: Handles property re-declarations across multiple interfaces - properties are considered "used" if structurally equivalent properties (same name and type) are accessed in any interface
 - **Three-Tier Severity System**: Categorizes findings by severity level for better prioritization
   - **ERROR**: Completely unused code that should be removed
@@ -36,6 +37,7 @@ A CLI tool that analyzes TypeScript projects to find unused exports and unused p
 | **Goal** | **Report & Analyze** | **Remove (Tree-Shake)** | **Report** |
 | **Unused Exports** | ✅ Detects and reports | ✅ Detects and removes | ✅ Detects and reports |
 | **Unused Properties** | ✅ **Unique:** Checks `interface`/`type` properties | ❌ No property checks | ❌ No property checks |
+| **Never-Returned Types** | ✅ **Unique:** Detects unused union branches | ❌ Not supported | ❌ Not supported |
 | **Test-Only Usage** | ✅ **Unique:** Identifies "Used only in tests" | ⚠️ May delete if not entrypoint | ❌ No distinction |
 | **Comment Support** | ✅ **Unique:** TODOs change severity | ✅ Skip/Ignore only | ✅ Skip/Ignore only |
 | **Unused Files** | ✅ Reports completely unused files | ✅ Deletes unreachable files | ✅ Explicit report flag |
@@ -113,7 +115,8 @@ The script outputs:
 1. **Completely Unused Files**: Files where all exports are unused (candidates for deletion)
 2. **Unused Exports**: Functions, types, interfaces, and constants that are exported but never used
 3. **Unused Properties**: Properties in types/interfaces that are defined but never accessed
-3. **Summary**: Total count of unused items found
+4. **Never-Returned Types**: Union type branches in function return types that are never actually returned
+5. **Summary**: Total count of unused items found
 
 Each finding includes:
 - File path relative to the project root
@@ -144,9 +147,16 @@ packages/example/src/types.ts
   UserConfig.futureFeature:12:3-16 [WARNING] (Unused property: [TODO] implement this later)
   TestHelpers.mockData:8:3-11 [INFO] (Used only in tests)
 
+Never-Returned Types:
+
+packages/example/src/api.ts
+  processRequest.ErrorResult:15:17-28 [ERROR] (Never-returned type in union)
+  fetchData.TimeoutError:42:25-37 [ERROR] (Never-returned type in union)
+
 Summary:
   Unused exports: 3
   Unused properties: 3
+  Never-returned types: 2
 ```
 
 ### Example Fix Output
@@ -159,11 +169,15 @@ Fixing: src/helpers.ts
   Removed unused export: unusedFunction
 Fixing: src/types.ts
   Removed unused property: UserConfig.unusedProp
+Fixing: src/api.ts
+  ✓ Removed never-returned type 'ErrorResult' from processRequest
+  ✓ Removed never-returned type 'TimeoutError' from fetchData
 Skipped: src/modified.ts (has local git changes)
 
 Summary:
   Fixed exports: 1
   Fixed properties: 1
+  Fixed never-returned types: 2
   Deleted files: 1
   Skipped files: 1
 
@@ -253,6 +267,57 @@ This will:
 
 ## Advanced Features
 
+### Never-Returned Types Detection
+
+The analyzer detects when functions declare union types in their return type signature but never actually return certain branches of that union. This commonly occurs when:
+
+- **Error Handling**: Functions declare error types but never return errors in practice
+- **Refactoring**: Code evolution leaves unused type branches behind
+- **Over-Engineering**: Return types are declared too broadly for actual usage
+
+**Example:**
+
+```typescript
+interface SuccessResult {
+  success: true;
+  data: string;
+}
+
+interface ErrorResult {
+  success: false;
+  error: string;
+}
+
+type ResultType = SuccessResult | ErrorResult;
+
+// ErrorResult is never returned
+export function processData(): ResultType {
+  // This function only ever returns SuccessResult
+  return { success: true, data: "processed" };
+}
+```
+
+**Detection Capabilities:**
+- Analyzes all function return statements to determine actual return types
+- Handles `Promise<Union>` types for async functions
+- Works with type aliases and direct union declarations
+- Supports primitive unions (`string | number | boolean`)
+- Handles multi-way unions (3+ types)
+- Normalizes boolean literals (`true | false` → `boolean`)
+
+**Auto-Fix Behavior:**
+- Removes never-returned types from the union declaration
+- Preserves `Promise<>` wrapper for async functions
+- Simplifies to single type when only one branch remains
+- Skips functions that are completely unused (they get removed entirely)
+
+After fixing the example above, the return type would become:
+```typescript
+export function processData(): SuccessResult {
+  return { success: true, data: "processed" };
+}
+```
+
 ### Structural Property Equivalence
 
 The analyzer handles cases where properties are re-declared across multiple interfaces with the same name and type. This commonly occurs with:

package/dist/cli.js

@@ -2,17 +2,240 @@
 
 // src/cli.ts
 import fs2 from "node:fs";
-import path10 from "node:path";
+import path12 from "node:path";
 
 // src/analyzeProject.ts
-import path6 from "node:path";
+import path8 from "node:path";
 import { Project } from "ts-morph";
 
-// src/findUnusedExports.ts
+// src/findNeverReturnedTypes.ts
 import path2 from "node:path";
+import { SyntaxKind as SyntaxKind2 } from "ts-morph";
 
-// src/checkExportUsage.ts
+// src/analyzeFunctionReturnTypes.ts
 import path from "node:path";
+import { SyntaxKind } from "ts-morph";
+function analyzeFunctionReturnTypes(func, sourceFile, tsConfigDir) {
+  const results = [];
+  const functionName = func.getName();
+  if (!functionName) {
+    return results;
+  }
+  const returnTypeNode = func.getReturnTypeNode();
+  if (!returnTypeNode) {
+    return results;
+  }
+  const returnType = returnTypeNode.getType();
+  const unwrappedPromise = unwrapPromiseType(returnType);
+  const typeToCheck = unwrappedPromise || returnType;
+  if (!typeToCheck.isUnion()) {
+    return results;
+  }
+  const unionTypes = typeToCheck.getUnionTypes();
+  if (unionTypes.length < 2) {
+    return results;
+  }
+  const returnStatements = func.getDescendantsOfKind(SyntaxKind.ReturnStatement);
+  const returnedTypes = [];
+  for (const returnStmt of returnStatements) {
+    const expression = returnStmt.getExpression();
+    if (expression) {
+      const exprType = expression.getType();
+      const unwrapped = unwrapPromiseType(exprType);
+      returnedTypes.push(unwrapped || exprType);
+    }
+  }
+  if (returnedTypes.length === 0) {
+    return results;
+  }
+  for (const returnedType of returnedTypes) {
+    if (returnedType.isAssignableTo(typeToCheck)) {
+      let assignableToAnyBranch = false;
+      for (const unionBranch of unionTypes) {
+        if (returnedType.isAssignableTo(unionBranch)) {
+          assignableToAnyBranch = true;
+          break;
+        }
+      }
+      if (!assignableToAnyBranch) {
+        return results;
+      }
+    }
+  }
+  const enumGroups = new Map;
+  const enumsWithReturnedValues = new Set;
+  for (const unionBranch of unionTypes) {
+    if (unionBranch.isEnumLiteral()) {
+      const enumName = getEnumNameFromLiteral(unionBranch);
+      if (enumName) {
+        if (!enumGroups.has(enumName)) {
+          enumGroups.set(enumName, []);
+        }
+        enumGroups.get(enumName)?.push(unionBranch);
+      }
+    }
+  }
+  for (const [enumName, enumBranches] of enumGroups.entries()) {
+    for (const returnedType of returnedTypes) {
+      for (const enumBranch of enumBranches) {
+        if (isTypeAssignableTo(returnedType, enumBranch)) {
+          enumsWithReturnedValues.add(enumName);
+          break;
+        }
+      }
+      if (enumsWithReturnedValues.has(enumName)) {
+        break;
+      }
+    }
+  }
+  const branchMap = new Map;
+  for (const unionBranch of unionTypes) {
+    const displayName = getTypeDisplayName(unionBranch);
+    if (!branchMap.has(displayName)) {
+      branchMap.set(displayName, unionBranch);
+    }
+  }
+  for (const [displayName, unionBranch] of branchMap.entries()) {
+    if (unionBranch.isEnumLiteral()) {
+      const enumName = getEnumNameFromLiteral(unionBranch);
+      if (enumName && enumsWithReturnedValues.has(enumName)) {
+        continue;
+      }
+    }
+    let isReturned = false;
+    for (const returnedType of returnedTypes) {
+      if (isTypeAssignableTo(returnedType, unionBranch)) {
+        isReturned = true;
+        break;
+      }
+    }
+    if (!isReturned) {
+      const relativePath = path.relative(tsConfigDir, sourceFile.getFilePath());
+      const nameNode = func.getNameNode();
+      if (nameNode) {
+        const startPos = nameNode.getStart();
+        const lineStartPos = nameNode.getStartLinePos();
+        const character = startPos - lineStartPos + 1;
+        const endCharacter = character + functionName.length;
+        results.push({
+          filePath: relativePath,
+          functionName,
+          neverReturnedType: displayName,
+          line: nameNode.getStartLineNumber(),
+          character,
+          endCharacter,
+          severity: "error"
+        });
+      }
+    }
+  }
+  return results;
+}
+function unwrapPromiseType(type) {
+  const symbol = type.getSymbol();
+  if (symbol?.getName() === "Promise") {
+    const typeArgs = type.getTypeArguments();
+    if (typeArgs.length > 0 && typeArgs[0]) {
+      return typeArgs[0];
+    }
+  }
+  return null;
+}
+function isTypeAssignableTo(sourceType, targetType) {
+  if (sourceType.isAssignableTo(targetType)) {
+    return true;
+  }
+  const sourceText = sourceType.getText();
+  const targetText = targetType.getText();
+  const isBooleanLiteral = (text) => text === "true" || text === "false";
+  if (isBooleanLiteral(sourceText) && isBooleanLiteral(targetText)) {
+    return true;
+  }
+  return false;
+}
+function getEnumNameFromLiteral(type) {
+  if (!type.isEnumLiteral()) {
+    return null;
+  }
+  const typeText = type.getText();
+  const cleanedText = typeText.replace(/import\([^)]+\)\./g, "");
+  const lastDotIndex = cleanedText.lastIndexOf(".");
+  if (lastDotIndex > 0) {
+    return cleanedText.substring(0, lastDotIndex);
+  }
+  return null;
+}
+function getTypeDisplayName(type) {
+  const symbol = type.getSymbol();
+  if (symbol) {
+    const name = symbol.getName();
+    if (name && name !== "__type") {
+      return name;
+    }
+  }
+  let typeText = type.getText();
+  typeText = typeText.replace(/import\([^)]+\)\./g, "");
+  if (typeText === "string")
+    return "string";
+  if (typeText === "number")
+    return "number";
+  if (typeText === "boolean")
+    return "boolean";
+  if (typeText === "true" || typeText === "false")
+    return "boolean";
+  if (typeText === "null")
+    return "null";
+  if (typeText === "undefined")
+    return "undefined";
+  const MAX_TYPE_LENGTH = 100;
+  if (typeText.length > MAX_TYPE_LENGTH) {
+    return `${typeText.substring(0, MAX_TYPE_LENGTH)}...`;
+  }
+  return typeText;
+}
+
+// src/hasNoCheck.ts
+function hasNoCheck(sourceFile) {
+  const fullText = sourceFile.getFullText();
+  const firstLine = fullText.split(`
+`)[0];
+  if (!firstLine) {
+    return false;
+  }
+  return firstLine.trim() === "// @ts-nocheck";
+}
+
+// src/findNeverReturnedTypes.ts
+function findNeverReturnedTypes(project, tsConfigDir, isTestFile, onProgress, targetFilePath) {
+  const results = [];
+  for (const sourceFile of project.getSourceFiles()) {
+    if (isTestFile(sourceFile)) {
+      continue;
+    }
+    if (hasNoCheck(sourceFile)) {
+      continue;
+    }
+    if (targetFilePath && sourceFile.getFilePath() !== targetFilePath) {
+      continue;
+    }
+    if (onProgress) {
+      const relativePath = path2.relative(tsConfigDir, sourceFile.getFilePath());
+      onProgress(relativePath);
+    }
+    const functions = sourceFile.getDescendantsOfKind(SyntaxKind2.FunctionDeclaration);
+    for (const func of functions) {
+      const funcResults = analyzeFunctionReturnTypes(func, sourceFile, tsConfigDir);
+      results.push(...funcResults);
+    }
+  }
+  return results;
+}
+
+// src/findUnusedExports.ts
+import path4 from "node:path";
+
+// src/checkExportUsage.ts
+import path3 from "node:path";
 import { Node } from "ts-morph";
 function getExportKind(declaration) {
   if (Node.isFunctionDeclaration(declaration)) {
@@ -84,7 +307,7 @@ function checkExportUsage(exportName, declarations, sourceFile, tsConfigDir, isT
     return null;
   }
   const kind = getExportKind(firstDeclaration);
-  const relativePath = path.relative(tsConfigDir, sourceFile.getFilePath());
+  const relativePath = path3.relative(tsConfigDir, sourceFile.getFilePath());
   const severity = onlyUsedInTests ? "info" : "error";
   const nameNode = getNameNode(firstDeclaration);
   const positionNode = nameNode || firstDeclaration;
@@ -105,17 +328,6 @@ function checkExportUsage(exportName, declarations, sourceFile, tsConfigDir, isT
   return result;
 }
 
-// src/hasNoCheck.ts
-function hasNoCheck(sourceFile) {
-  const fullText = sourceFile.getFullText();
-  const firstLine = fullText.split(`
-`)[0];
-  if (!firstLine) {
-    return false;
-  }
-  return firstLine.trim() === "// @ts-nocheck";
-}
-
 // src/findUnusedExports.ts
 function findUnusedExports(project, tsConfigDir, isTestFile, onProgress, targetFilePath) {
   const results = [];
@@ -130,7 +342,7 @@ function findUnusedExports(project, tsConfigDir, isTestFile, onProgress, targetF
       continue;
     }
     if (onProgress) {
-      const relativePath = path2.relative(tsConfigDir, sourceFile.getFilePath());
+      const relativePath = path4.relative(tsConfigDir, sourceFile.getFilePath());
       onProgress(relativePath);
     }
     const exports = sourceFile.getExportedDeclarations();
@@ -145,10 +357,10 @@ function findUnusedExports(project, tsConfigDir, isTestFile, onProgress, targetF
 }
 
 // src/findUnusedProperties.ts
-import path5 from "node:path";
+import path7 from "node:path";
 
 // src/analyzeInterfaces.ts
-import path3 from "node:path";
+import path5 from "node:path";
 
 // src/extractTodoComment.ts
 function extractTodoComment(prop) {
@@ -174,7 +386,7 @@ function extractTodoComment(prop) {
 }
 
 // src/findStructurallyEquivalentProperties.ts
-import { SyntaxKind } from "ts-morph";
+import { SyntaxKind as SyntaxKind3 } from "ts-morph";
 function checkInterfaceProperties(iface, propName, propType, originalProp, equivalentProps) {
   const properties = iface.getProperties();
   for (const p of properties) {
@@ -191,15 +403,15 @@ function checkInterfaceProperties(iface, propName, propType, originalProp, equiv
 }
 function checkTypeAliasProperties(typeAlias, propName, propType, originalProp, equivalentProps) {
   const typeNode = typeAlias.getTypeNode();
-  if (!typeNode || typeNode.getKind() !== SyntaxKind.TypeLiteral) {
+  if (!typeNode || typeNode.getKind() !== SyntaxKind3.TypeLiteral) {
     return;
   }
-  const properties = typeNode.getChildren().filter((child) => child.getKind() === SyntaxKind.PropertySignature);
+  const properties = typeNode.getChildren().filter((child) => child.getKind() === SyntaxKind3.PropertySignature);
   for (const p of properties) {
     if (p === originalProp) {
       continue;
     }
-    if (p.getKind() === SyntaxKind.PropertySignature && p.getName() === propName) {
+    if (p.getKind() === SyntaxKind3.PropertySignature && p.getName() === propName) {
       const pType = p.getType().getText();
       if (pType === propType) {
         equivalentProps.push(p);
@@ -278,7 +490,7 @@ function analyzeInterfaces(sourceFile, tsConfigDir, isTestFile, results, project
     for (const prop of iface.getProperties()) {
       const usage = isPropertyUnused(prop, isTestFile, project);
       if (usage.isUnusedOrTestOnly) {
-        const relativePath = path3.relative(tsConfigDir, sourceFile.getFilePath());
+        const relativePath = path5.relative(tsConfigDir, sourceFile.getFilePath());
         const todoComment = extractTodoComment(prop);
         let severity = "error";
         if (todoComment) {
@@ -309,7 +521,7 @@ function analyzeInterfaces(sourceFile, tsConfigDir, isTestFile, results, project
 }
 
 // src/analyzeTypeAliases.ts
-import path4 from "node:path";
+import path6 from "node:path";
 import { Node as Node2 } from "ts-morph";
 function analyzeTypeLiteralMember(member, typeName, sourceFile, tsConfigDir, isTestFile, results, project) {
   if (!Node2.isPropertySignature(member)) {
@@ -319,7 +531,7 @@ function analyzeTypeLiteralMember(member, typeName, sourceFile, tsConfigDir, isT
   if (!usage.isUnusedOrTestOnly) {
     return;
   }
-  const relativePath = path4.relative(tsConfigDir, sourceFile.getFilePath());
+  const relativePath = path6.relative(tsConfigDir, sourceFile.getFilePath());
   const todoComment = extractTodoComment(member);
   let severity = "error";
   if (todoComment) {
@@ -379,7 +591,7 @@ function findUnusedProperties(project, tsConfigDir, isTestFile, onProgress, targ
       continue;
     }
     if (onProgress) {
-      const relativePath = path5.relative(tsConfigDir, sourceFile.getFilePath());
+      const relativePath = path7.relative(tsConfigDir, sourceFile.getFilePath());
       onProgress(relativePath);
     }
     analyzeInterfaces(sourceFile, tsConfigDir, isTestFile, results, project);
@@ -400,7 +612,7 @@ function analyzeProject(tsConfigPath, onProgress, targetFilePath, isTestFile2 =
   const project = new Project({
     tsConfigFilePath: tsConfigPath
   });
-  const tsConfigDir = path6.dirname(tsConfigPath);
+  const tsConfigDir = path8.dirname(tsConfigPath);
   const allSourceFiles = project.getSourceFiles();
   const filesToAnalyze = allSourceFiles.filter((sf) => {
     if (isTestFile2(sf)) {
@@ -426,43 +638,50 @@ function analyzeProject(tsConfigPath, onProgress, targetFilePath, isTestFile2 =
   } : undefined;
   const unusedExports = findUnusedExports(project, tsConfigDir, isTestFile2, progressCallback, targetFilePath);
   const unusedProperties = findUnusedProperties(project, tsConfigDir, isTestFile2, progressCallback, targetFilePath);
+  const neverReturnedTypes = findNeverReturnedTypes(project, tsConfigDir, isTestFile2, progressCallback, targetFilePath);
   const unusedFiles = [];
   const fileExportCounts = new Map;
   for (const sourceFile of filesToAnalyze) {
-    const filePath = path6.relative(tsConfigDir, sourceFile.getFilePath());
+    const filePath = path8.relative(tsConfigDir, sourceFile.getFilePath());
     const exports = sourceFile.getExportedDeclarations();
     const totalExports = exports.size;
     if (totalExports > 0) {
-      fileExportCounts.set(filePath, { total: totalExports, unused: 0 });
+      fileExportCounts.set(filePath, { total: totalExports, unused: 0, testOnly: 0 });
     }
   }
   for (const unusedExport of unusedExports) {
     const counts = fileExportCounts.get(unusedExport.filePath);
     if (counts) {
       counts.unused++;
+      if (unusedExport.onlyUsedInTests) {
+        counts.testOnly++;
+      }
     }
   }
   for (const [filePath, counts] of fileExportCounts.entries()) {
-    if (counts.total > 0 && counts.unused === counts.total) {
+    const allExportsUnused = counts.total > 0 && counts.unused === counts.total;
+    const hasAnyTestOnlyExports = counts.testOnly > 0;
+    if (allExportsUnused && !hasAnyTestOnlyExports) {
       unusedFiles.push(filePath);
     }
   }
   const results = {
     unusedExports,
     unusedProperties,
-    unusedFiles
+    unusedFiles,
+    neverReturnedTypes
   };
   return results;
 }
 
 // src/fixProject.ts
 import fs from "node:fs";
-import path8 from "node:path";
-import { Project as Project2, SyntaxKind as SyntaxKind2 } from "ts-morph";
+import path10 from "node:path";
+import { Project as Project2, SyntaxKind as SyntaxKind4 } from "ts-morph";
 
 // src/checkGitStatus.ts
 import { execSync } from "node:child_process";
-import path7 from "node:path";
+import path9 from "node:path";
 function checkGitStatus(workingDir) {
   const changedFiles = new Set;
   try {
@@ -484,7 +703,7 @@ function checkGitStatus(workingDir) {
       const filename = line.slice(3).trim();
       const actualFilename = filename.includes(" -> ") ? filename.split(" -> ")[1] : filename;
       if (actualFilename) {
-        const absolutePath = path7.resolve(gitRoot, actualFilename);
+        const absolutePath = path9.resolve(gitRoot, actualFilename);
         changedFiles.add(absolutePath);
       }
     }
@@ -499,19 +718,20 @@ function fixProject(tsConfigPath, onProgress, isTestFile2 = isTestFile) {
   const results = {
     fixedExports: 0,
     fixedProperties: 0,
+    fixedNeverReturnedTypes: 0,
     deletedFiles: 0,
     skippedFiles: [],
     errors: []
   };
   const analysis = analyzeProject(tsConfigPath, undefined, undefined, isTestFile2);
-  const tsConfigDir = path8.dirname(path8.resolve(tsConfigPath));
+  const tsConfigDir = path10.dirname(path10.resolve(tsConfigPath));
   const filesWithChanges = checkGitStatus(tsConfigDir);
   const project = new Project2({
     tsConfigFilePath: tsConfigPath
   });
   const deletedFiles = new Set;
   for (const relativeFilePath of analysis.unusedFiles) {
-    const absoluteFilePath = path8.resolve(tsConfigDir, relativeFilePath);
+    const absoluteFilePath = path10.resolve(tsConfigDir, relativeFilePath);
     if (filesWithChanges.has(absoluteFilePath)) {
       onProgress?.(`Skipped: ${relativeFilePath} (has local git changes)`);
       results.skippedFiles.push(relativeFilePath);
@@ -531,15 +751,71 @@ function fixProject(tsConfigPath, onProgress, isTestFile2 = isTestFile) {
   if (deletedFiles.size > 0) {
     cleanupBrokenImports(project, tsConfigDir, deletedFiles, filesWithChanges, onProgress, results);
   }
+  const neverReturnedByFile = new Map;
+  for (const neverReturned of analysis.neverReturnedTypes || []) {
+    if (neverReturned.severity !== "error") {
+      continue;
+    }
+    if (!neverReturnedByFile.has(neverReturned.filePath)) {
+      neverReturnedByFile.set(neverReturned.filePath, []);
+    }
+    neverReturnedByFile.get(neverReturned.filePath)?.push(neverReturned);
+  }
+  const unusedExportNames = new Set;
+  for (const unusedExport of analysis.unusedExports) {
+    if (unusedExport.severity === "error") {
+      unusedExportNames.add(`${unusedExport.filePath}:${unusedExport.exportName}`);
+    }
+  }
+  for (const [relativeFilePath, neverReturnedItems] of neverReturnedByFile.entries()) {
+    const absoluteFilePath = path10.resolve(tsConfigDir, relativeFilePath);
+    if (analysis.unusedFiles.includes(relativeFilePath)) {
+      continue;
+    }
+    if (filesWithChanges.has(absoluteFilePath)) {
+      if (!results.skippedFiles.includes(relativeFilePath)) {
+        onProgress?.(`Skipped: ${relativeFilePath} (has local git changes)`);
+        results.skippedFiles.push(relativeFilePath);
+      }
+      continue;
+    }
+    try {
+      const sourceFile = project.getSourceFile(absoluteFilePath);
+      if (!sourceFile) {
+        continue;
+      }
+      onProgress?.(`Fixing: ${relativeFilePath}`);
+      if (neverReturnedItems) {
+        for (const neverReturned of neverReturnedItems) {
+          const exportKey = `${relativeFilePath}:${neverReturned.functionName}`;
+          if (unusedExportNames.has(exportKey)) {
+            continue;
+          }
+          if (removeNeverReturnedType(sourceFile, neverReturned.functionName, neverReturned.neverReturnedType)) {
+            onProgress?.(`  ✓ Removed never-returned type '${neverReturned.neverReturnedType}' from ${neverReturned.functionName}`);
+            results.fixedNeverReturnedTypes++;
+          }
+        }
+      }
+      sourceFile.saveSync();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      results.errors.push({ file: relativeFilePath, error: errorMessage });
+      onProgress?.(`Error fixing ${relativeFilePath}: ${errorMessage}`);
+    }
+  }
   const exportsByFile = new Map;
   for (const unusedExport of analysis.unusedExports) {
+    if (unusedExport.severity !== "error") {
+      continue;
+    }
     if (!exportsByFile.has(unusedExport.filePath)) {
       exportsByFile.set(unusedExport.filePath, []);
     }
     exportsByFile.get(unusedExport.filePath)?.push(unusedExport);
   }
   for (const [relativeFilePath, exports] of exportsByFile.entries()) {
-    const absoluteFilePath = path8.resolve(tsConfigDir, relativeFilePath);
+    const absoluteFilePath = path10.resolve(tsConfigDir, relativeFilePath);
     if (analysis.unusedFiles.includes(relativeFilePath)) {
       continue;
     }
@@ -553,7 +829,9 @@ function fixProject(tsConfigPath, onProgress, isTestFile2 = isTestFile) {
       if (!sourceFile) {
         continue;
       }
-      onProgress?.(`Fixing: ${relativeFilePath}`);
+      if (!neverReturnedByFile.has(relativeFilePath)) {
+        onProgress?.(`Fixing: ${relativeFilePath}`);
+      }
       for (const unusedExport of exports) {
         if (removeExport(sourceFile, unusedExport.exportName)) {
           onProgress?.(`  ✓ Removed unused export: ${unusedExport.exportName}`);
@@ -569,13 +847,16 @@ function fixProject(tsConfigPath, onProgress, isTestFile2 = isTestFile) {
   }
   const propertiesByFile = new Map;
   for (const unusedProperty of analysis.unusedProperties) {
+    if (unusedProperty.severity !== "error") {
+      continue;
+    }
     if (!propertiesByFile.has(unusedProperty.filePath)) {
       propertiesByFile.set(unusedProperty.filePath, []);
     }
     propertiesByFile.get(unusedProperty.filePath)?.push(unusedProperty);
   }
   for (const [relativeFilePath, properties] of propertiesByFile.entries()) {
-    const absoluteFilePath = path8.resolve(tsConfigDir, relativeFilePath);
+    const absoluteFilePath = path10.resolve(tsConfigDir, relativeFilePath);
     if (analysis.unusedFiles.includes(relativeFilePath)) {
       continue;
     }
@@ -591,7 +872,7 @@ function fixProject(tsConfigPath, onProgress, isTestFile2 = isTestFile) {
       if (!sourceFile) {
         continue;
       }
-      if (!exportsByFile.has(relativeFilePath)) {
+      if (!exportsByFile.has(relativeFilePath) && !neverReturnedByFile.has(relativeFilePath)) {
         onProgress?.(`Fixing: ${relativeFilePath}`);
       }
       for (const unusedProperty of properties) {
@@ -616,8 +897,8 @@ function removeExport(sourceFile, exportName) {
     return false;
   }
   for (const declaration of declarations) {
-    if (declaration.getKind() === SyntaxKind2.VariableDeclaration) {
-      const variableStatement = declaration.getFirstAncestorByKind(SyntaxKind2.VariableStatement);
+    if (declaration.getKind() === SyntaxKind4.VariableDeclaration) {
+      const variableStatement = declaration.getFirstAncestorByKind(SyntaxKind4.VariableStatement);
       if (variableStatement) {
         variableStatement.remove();
         continue;
@@ -644,12 +925,12 @@ function removeProperty(sourceFile, typeName, propertyName) {
   for (const typeAlias of typeAliases) {
     if (typeAlias.getName() === typeName) {
       const typeNode = typeAlias.getTypeNode();
-      if (typeNode && typeNode.getKind() === SyntaxKind2.TypeLiteral) {
-        const typeLiteral = typeNode.asKindOrThrow(SyntaxKind2.TypeLiteral);
+      if (typeNode && typeNode.getKind() === SyntaxKind4.TypeLiteral) {
+        const typeLiteral = typeNode.asKindOrThrow(SyntaxKind4.TypeLiteral);
         const members = typeLiteral.getMembers();
         for (const member of members) {
-          if (member.getKind() === SyntaxKind2.PropertySignature) {
-            const propSig = member.asKind(SyntaxKind2.PropertySignature);
+          if (member.getKind() === SyntaxKind4.PropertySignature) {
+            const propSig = member.asKind(SyntaxKind4.PropertySignature);
             if (propSig?.getName() === propertyName) {
               propSig.remove();
               return true;
@@ -661,10 +942,131 @@ function removeProperty(sourceFile, typeName, propertyName) {
   }
   return false;
 }
+function removeNeverReturnedType(sourceFile, functionName, neverReturnedType) {
+  const functions = sourceFile.getFunctions();
+  for (const func of functions) {
+    if (func.getName() === functionName) {
+      const returnTypeNode = func.getReturnTypeNode();
+      if (!returnTypeNode) {
+        return false;
+      }
+      const returnType = returnTypeNode.getType();
+      let typeToCheck = returnType;
+      let isPromise = false;
+      const symbol = returnType.getSymbol();
+      if (symbol?.getName() === "Promise") {
+        const typeArgs = returnType.getTypeArguments();
+        if (typeArgs.length > 0 && typeArgs[0]) {
+          typeToCheck = typeArgs[0];
+          isPromise = true;
+        }
+      }
+      if (!typeToCheck.isUnion()) {
+        return false;
+      }
+      const unionTypes = typeToCheck.getUnionTypes();
+      const hasInlineObjectType = unionTypes.some((ut) => ut.getSymbol()?.getName() === "__type");
+      const hasEnumLiteral = unionTypes.some((ut) => ut.isEnumLiteral());
+      if (hasInlineObjectType || hasEnumLiteral) {
+        const originalTypeText = returnTypeNode.getText();
+        let typeTextToModify = originalTypeText;
+        let promiseWrapper = "";
+        if (isPromise) {
+          const promiseMatch = originalTypeText.match(/^Promise<(.+)>$/s);
+          if (promiseMatch?.[1]) {
+            typeTextToModify = promiseMatch[1];
+            promiseWrapper = "Promise<>";
+          }
+        }
+        const branches = splitUnionType(typeTextToModify);
+        const normalizedRemove = normalizeTypeText(neverReturnedType === "true" || neverReturnedType === "false" ? "boolean" : neverReturnedType);
+        const remainingBranches = branches.filter((branch) => {
+          const trimmed = branch.trim();
+          const normalized = normalizeTypeText(trimmed === "true" || trimmed === "false" ? "boolean" : trimmed);
+          return normalized !== normalizedRemove;
+        });
+        if (remainingBranches.length === 0 || remainingBranches.length === branches.length) {
+          return false;
+        }
+        let newReturnType = remainingBranches.join(" | ");
+        if (promiseWrapper) {
+          newReturnType = `Promise<${newReturnType}>`;
+        }
+        func.setReturnType(newReturnType);
+        return true;
+      } else {
+        const typesToKeep = [];
+        for (const ut of unionTypes) {
+          const symbol2 = ut.getSymbol();
+          const typeName = symbol2?.getName() || ut.getText();
+          const normalizedName = typeName === "true" || typeName === "false" ? "boolean" : typeName;
+          const normalizedRemove = neverReturnedType === "true" || neverReturnedType === "false" ? "boolean" : neverReturnedType;
+          if (normalizedName !== normalizedRemove && !typesToKeep.includes(typeName)) {
+            typesToKeep.push(typeName);
+          }
+        }
+        let newReturnType;
+        if (typesToKeep.length === 1 && typesToKeep[0]) {
+          newReturnType = typesToKeep[0];
+        } else if (typesToKeep.length > 1) {
+          newReturnType = typesToKeep.join(" | ");
+        }
+        if (!newReturnType) {
+          return false;
+        }
+        if (isPromise) {
+          newReturnType = `Promise<${newReturnType}>`;
+        }
+        func.setReturnType(newReturnType);
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function splitUnionType(typeText) {
+  const branches = [];
+  let current = "";
+  let depth = 0;
+  let inString = false;
+  let stringChar = "";
+  for (let i = 0;i < typeText.length; i++) {
+    const char = typeText[i];
+    const prevChar = i > 0 ? typeText[i - 1] : "";
+    if ((char === '"' || char === "'") && prevChar !== "\\") {
+      if (!inString) {
+        inString = true;
+        stringChar = char;
+      } else if (char === stringChar) {
+        inString = false;
+        stringChar = "";
+      }
+    }
+    if (!inString) {
+      if (char === "{" || char === "<" || char === "(") {
+        depth++;
+      } else if (char === "}" || char === ">" || char === ")") {
+        depth--;
+      } else if (char === "|" && depth === 0) {
+        branches.push(current);
+        current = "";
+        continue;
+      }
+    }
+    current += char;
+  }
+  if (current) {
+    branches.push(current);
+  }
+  return branches;
+}
+function normalizeTypeText(typeText) {
+  return typeText.replace(/;\s*([}\]>])/g, " $1").replace(/\s+/g, " ").trim();
+}
 function cleanupBrokenImports(project, tsConfigDir, deletedFiles, filesWithChanges, onProgress, results) {
   const sourceFiles = project.getSourceFiles();
   for (const sourceFile of sourceFiles) {
-    const relativePath = path8.relative(tsConfigDir, sourceFile.getFilePath());
+    const relativePath = path10.relative(tsConfigDir, sourceFile.getFilePath());
     const absolutePath = sourceFile.getFilePath();
     if (filesWithChanges.has(absolutePath)) {
       continue;
@@ -676,7 +1078,7 @@ function cleanupBrokenImports(project, tsConfigDir, deletedFiles, filesWithChang
       const moduleSpecifier = exportDecl.getModuleSpecifierValue();
       if (moduleSpecifier) {
         const resolvedPath = resolveImportPath(sourceFile.getFilePath(), moduleSpecifier);
-        const relativeResolvedPath = resolvedPath ? path8.relative(tsConfigDir, resolvedPath) : null;
+        const relativeResolvedPath = resolvedPath ? path10.relative(tsConfigDir, resolvedPath) : null;
         if (relativeResolvedPath && deletedFiles.has(relativeResolvedPath)) {
           brokenExports.push(exportDecl);
         } else {
@@ -724,9 +1126,9 @@ function cleanupBrokenImports(project, tsConfigDir, deletedFiles, filesWithChang
   }
 }
 function resolveImportPath(fromFile, importPath) {
-  const fromDir = path8.dirname(fromFile);
+  const fromDir = path10.dirname(fromFile);
   if (importPath.startsWith(".")) {
-    const resolved = path8.resolve(fromDir, importPath);
+    const resolved = path10.resolve(fromDir, importPath);
     const extensions = [".ts", ".tsx", ".js", ".jsx"];
     for (const ext of extensions) {
       const withExt = resolved + ext;
@@ -735,7 +1137,7 @@ function resolveImportPath(fromFile, importPath) {
       }
     }
     for (const ext of extensions) {
-      const indexFile = path8.join(resolved, `index${ext}`);
+      const indexFile = path10.join(resolved, `index${ext}`);
       if (fs.existsSync(indexFile)) {
         return indexFile;
       }
@@ -746,7 +1148,7 @@ function resolveImportPath(fromFile, importPath) {
 }
 
 // src/formatResults.ts
-import path9 from "node:path";
+import path11 from "node:path";
 function getSeverityMarker(severity) {
   const markers = {
     error: "[ERROR]",
@@ -768,12 +1170,16 @@ function formatPropertyLine(item) {
   const marker = getSeverityMarker(item.severity);
   return `  ${item.typeName}.${item.propertyName}:${item.line}:${item.character}-${item.endCharacter} ${marker} (${status}${todoSuffix})`;
 }
+function formatNeverReturnedLine(item) {
+  const marker = getSeverityMarker(item.severity);
+  return `  ${item.functionName}:${item.line}:${item.character}-${item.endCharacter} ${marker} (Type '${item.neverReturnedType}' in return type is never returned)`;
+}
 function formatGroupedItems(items, formatter, tsConfigDir, cwd) {
   const lines = [];
   const grouped = groupByFile(items);
   for (const [filePath, groupItems] of grouped.entries()) {
-    const absolutePath = path9.resolve(tsConfigDir, filePath);
-    const relativePath = path9.relative(cwd, absolutePath);
+    const absolutePath = path11.resolve(tsConfigDir, filePath);
+    const relativePath = path11.relative(cwd, absolutePath);
     lines.push(relativePath);
     for (const item of groupItems) {
       lines.push(formatter(item));
@@ -796,8 +1202,8 @@ function formatResults(results, tsConfigDir) {
     lines.push("Completely Unused Files:");
     lines.push("");
     for (const filePath of results.unusedFiles) {
-      const absolutePath = path9.resolve(tsConfigDir, filePath);
-      const relativePath = path9.relative(cwd, absolutePath);
+      const absolutePath = path11.resolve(tsConfigDir, filePath);
+      const relativePath = path11.relative(cwd, absolutePath);
       lines.push(relativePath);
       lines.push("  file:1:1-1 [ERROR] (All exports unused - file can be deleted)");
       lines.push("");
@@ -813,13 +1219,20 @@ function formatResults(results, tsConfigDir) {
     lines.push("");
     lines.push(...formatGroupedItems(propertiesToReport, formatPropertyLine, tsConfigDir, cwd));
   }
-  if (results.unusedFiles.length === 0 && exportsToReport.length === 0 && propertiesToReport.length === 0) {
+  const neverReturnedTypes = results.neverReturnedTypes || [];
+  if (neverReturnedTypes.length > 0) {
+    lines.push("Never-Returned Types:");
+    lines.push("");
+    lines.push(...formatGroupedItems(neverReturnedTypes, formatNeverReturnedLine, tsConfigDir, cwd));
+  }
+  if (results.unusedFiles.length === 0 && exportsToReport.length === 0 && propertiesToReport.length === 0 && neverReturnedTypes.length === 0) {
     lines.push("No unused exports or properties found!");
   } else {
     lines.push("Summary:");
     lines.push(`  Completely unused files: ${results.unusedFiles.length}`);
     lines.push(`  Unused exports: ${exportsToReport.length}`);
     lines.push(`  Unused properties: ${propertiesToReport.length}`);
+    lines.push(`  Never-returned types: ${neverReturnedTypes.length}`);
   }
   return lines.join(`
 `);
@@ -860,11 +1273,11 @@ function main() {
     command = firstArg;
     configIndex = 1;
   }
-  let tsConfigPath = path10.resolve(args[configIndex] ?? "");
+  let tsConfigPath = path12.resolve(args[configIndex] ?? "");
   if (fs2.existsSync(tsConfigPath) && fs2.statSync(tsConfigPath).isDirectory()) {
-    tsConfigPath = path10.join(tsConfigPath, "tsconfig.json");
+    tsConfigPath = path12.join(tsConfigPath, "tsconfig.json");
   }
-  const targetFilePath = args[configIndex + 1] ? path10.resolve(args[configIndex + 1]) : undefined;
+  const targetFilePath = args[configIndex + 1] ? path12.resolve(args[configIndex + 1]) : undefined;
   if (command === "fix") {
     console.log(`Fixing TypeScript project: ${tsConfigPath}`);
     console.log("");
@@ -903,11 +1316,11 @@ function main() {
       const filledLength = Math.min(barLength, Math.max(0, Math.floor(current / total * barLength)));
       const emptyLength = Math.max(0, barLength - filledLength);
       const bar = "█".repeat(filledLength) + "░".repeat(emptyLength);
-      const fileName = path10.basename(filePath);
+      const fileName = path12.basename(filePath);
       process.stdout.write(`\r\x1B[KProgress: [${bar}] ${percentage}% (${current}/${total}) ${fileName}`);
     }, targetFilePath);
     process.stdout.write("\r\x1B[K");
-    const tsConfigDir = path10.dirname(path10.resolve(tsConfigPath));
+    const tsConfigDir = path12.dirname(path12.resolve(tsConfigPath));
     const output = formatResults(results, tsConfigDir);
     console.log(output);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-unused",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Find unused exports and properties in TypeScript projects",
   "license": "MIT",
   "bin": {
@@ -13,11 +13,13 @@
   "scripts": {
     "clean": "rm -rf dist",
     "build:js": "bun build src/cli.ts --outdir dist --target node --external ts-morph --external typescript",
-    "build": "bun lint && bun test && bun clean && bun build:js && bun sanity-check --no-build",
+    "build": "bun clean && bun build:js",
     "typecheck": "tsgo --noEmit",
     "lint": "bun run fix && biome check src",
     "fix": "biome check --write --unsafe src",
-    "sanity-check": "bun run scripts/sanity-check.ts"
+    "sanity-check": "bun run scripts/sanity-check.ts",
+    "prepublish": "bun lint && bun test && bun run build && bun sanity-check --no-build",
+    "cli": "bun run src/cli.ts"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.8",