ts-unused 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Gorbatchev
+
+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,295 @@
+# ts-unused
+
+A CLI tool that analyzes TypeScript projects to find unused exports and unused properties in types and interfaces.
+
+**ts-unused** is built with AI-assisted development in mind. Its primary goal is to audit codebases, especially those heavily modified by AI coding assistants, to identify dead code, unused types, _properties_, and exports. The intended workflow is to feed the tool's output back into an AI agent, allowing it to autonomously clean up and refactor the project. VSCode problem matcher makes it a fully integrated experience.
+
+## Features
+
+- **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
+- **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
+  - **WARNING**: Items with TODO comments that need attention
+  - **INFO**: Items only used in tests (testing helpers)
+- **TODO Comment Detection**: Identifies and highlights properties/types with TODO comments
+- **Excludes Test Files**: Automatically excludes test files from analysis to avoid false positives (but tracks test-only usage)
+- **Excludes @ts-nocheck Files**: Automatically excludes files with `// @ts-nocheck` on the first line
+- **Inline Type Support**: Analyzes inline object types in addition to named interfaces and type aliases
+- **VS Code Integration**: Problem matcher for displaying results in VS Code's Problems panel with severity indicators
+
+## Limitations
+
+- **Dynamic Access**: Properties accessed via computed property names (`obj[key]`) may not be detected
+- **Re-exports**: Items that are re-exported through barrel files are considered used
+- **Type Narrowing**: Properties accessed after type guards or conditional checks may not always be tracked through complex control flow
+
+## Comparison With Similar Tools
+
+### Feature Comparison
+
+| Feature | `ts-unused` | [`tsr`](https://github.com/line/tsr) | [`ts-unused-exports`](https://github.com/pzavolinsky/ts-unused-exports) |
+| :--- | :--- | :--- | :--- |
+| **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 |
+| **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 |
+| **VS Code Integration** | ✅ **Problem Matcher provided** | ❌ Manual setup required | ❌ Manual setup / ESLint plugin |
+| **Auto-Fix** | ✅ Removes unused code safely | ✅ **Primary Feature:** Auto-removes code | ❌ Manual removal required |
+| **Accuracy** | ⭐️ **High** (Language Service) | ⚡️ **Fast** (Custom Graph) | ⚡️ **Fast** (Custom Parser) |
+| **Entrypoints** | 🟢 Not required (Global scan) | 🔴 **Required** (Reachability graph) | 🟢 Not required (Global scan) |
+
+### vs [tsr](https://github.com/line/tsr)
+
+**tsr** is primarily a "tree-shaking" tool for source code, designed to automatically remove unused code.
+
+- **Goal**: `tsr` focuses on **removing** code (autofix), while `ts-unused` focuses on **reporting** and analysis.
+- **Detection**: `tsr` uses a reachability graph starting from defined entrypoints. If code isn't reachable, it's deleted. `ts-unused` scans all files and checks for global references using the TypeScript Language Service.
+
+### vs [ts-unused-exports](https://github.com/pzavolinsky/ts-unused-exports)
+
+**ts-unused-exports** is a specialized, high-performance tool for finding unused exported symbols.
+
+- **Performance**: `ts-unused-exports` uses a custom parser and resolver, making it potentially faster on very large codebases than `ts-unused` (which uses the full TypeScript Language Service).
+- **Accuracy**: `ts-unused` leverages the standard TypeScript Language Service, ensuring higher accuracy with complex re-exports, type inference, and aliasing.
+- **Granularity**: `ts-unused` provides deeper analysis for **unused properties** and **test-only usage**, whereas `ts-unused-exports` focuses strictly on exported symbols.
+
+## Installation
+
+```bash
+npm install -g ts-unused
+# or
+bun add -g ts-unused
+```
+
+## Usage
+
+### Check Command (Analysis Only)
+
+Analyze your project and report unused items without making any changes:
+
+```bash
+ts-unused check <path-to-tsconfig.json> [file-path-to-check]
+# or simply:
+ts-unused <path-to-tsconfig.json> [file-path-to-check]
+```
+
+### Fix Command (Auto-Remove)
+
+Automatically remove unused exports, properties, and delete unused files:
+
+```bash
+ts-unused fix <path-to-tsconfig.json>
+```
+
+**Safety Features:**
+- Checks git status before modifying each file
+- Skips files with uncommitted local changes
+- Reports which files were skipped
+- Continues processing other files if one fails
+- Provides detailed per-file logging
+
+### Example
+
+```bash
+# Analyze only
+ts-unused ./tsconfig.json
+
+# Auto-fix
+ts-unused fix ./tsconfig.json
+```
+
+## Output
+
+### Check Command Output
+
+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
+
+Each finding includes:
+- File path relative to the project root
+- Export/property name with location (`name:line:startColumn-endColumn`)
+- Severity level (`[ERROR]`, `[WARNING]`, or `[INFO]`)
+- Description of the issue
+
+The column positions are 1-based (VS Code standard) and the range highlights the entire identifier name in VS Code's editor and Problems panel.
+
+### Example Check Output
+
+```
+Analyzing TypeScript project: /path/to/tsconfig.json
+
+Unused Exports:
+
+packages/example/src/helpers.ts
+  unusedFunction:10:1-15 [ERROR] (Unused function)
+  createTestHelper:25:1-17 [INFO] (Used only in tests)
+
+packages/example/src/constants.ts
+  UNUSED_CONSTANT:20:7-22 [ERROR] (Unused const)
+
+Unused Type/Interface Properties:
+
+packages/example/src/types.ts
+  UserConfig.unusedProp:5:3-13 [ERROR] (Unused property)
+  UserConfig.futureFeature:12:3-16 [WARNING] (Unused property: [TODO] implement this later)
+  TestHelpers.mockData:8:3-11 [INFO] (Used only in tests)
+
+Summary:
+  Unused exports: 3
+  Unused properties: 3
+```
+
+### Example Fix Output
+
+```
+Fixing TypeScript project: /path/to/tsconfig.json
+
+Deleting: src/unused-file.ts (all exports unused)
+Fixing: src/helpers.ts
+  Removed unused export: unusedFunction
+Fixing: src/types.ts
+  Removed unused property: UserConfig.unusedProp
+Skipped: src/modified.ts (has local git changes)
+
+Summary:
+  Fixed exports: 1
+  Fixed properties: 1
+  Deleted files: 1
+  Skipped files: 1
+
+Skipped files (have local git changes):
+  src/modified.ts
+```
+
+### Severity Levels
+
+- **[ERROR]** - Completely unused code (red in VS Code)
+  - Should be removed or investigated
+  - No references found in production or test code
+
+- **[WARNING]** - Items with TODO comments (yellow in VS Code)
+  - Indicates planned but not yet implemented features
+  - Helps track technical debt
+
+- **[INFO]** - Used only in tests (blue in VS Code)
+  - Testing helpers, mocks, or test-specific utilities
+  - Defined outside test files but only referenced from tests
+  - Not necessarily a problem, but good to know
+
+## How It Works
+
+1. **Project Loading**: Uses ts-morph to load the TypeScript project based on the provided tsconfig.json
+2. **Export Analysis**: For each exported declaration, finds all references across the codebase
+3. **Property Analysis**: For interfaces and type aliases, checks each property for external references
+4. **Reference Categorization**: Tracks references separately:
+   - Total references (definition + all usages)
+   - Test references (from test files)
+   - Non-test references (from production code)
+5. **Severity Assignment**:
+   - Items with TODO comments → WARNING
+   - Items only used in tests (nonTestReferences === 1 && testReferences > 0) → INFO
+   - Completely unused items → ERROR
+6. **Structural Equivalence Checking**: When a property has no direct references, searches for structurally equivalent properties (same name and type signature) across all interfaces and type aliases - if any equivalent property is used, all are considered used
+7. **File Exclusion**: Automatically filters out from being analyzed:
+   - Test files (files in `__tests__` directories or ending in `.test.ts` or `.spec.ts`)
+   - Files with `// @ts-nocheck` on the first line
+   - Note: Test files are still scanned for references to track test-only usage
+
+## VS Code Integration
+
+Add this task to your `.vscode/tasks.json` to run the analyzer with problem matcher support:
+
+```json
+{
+  "label": "Find Unused Exports",
+  "type": "shell",
+  "command": "ts-unused",
+  "args": ["./tsconfig.json"],
+  "presentation": {
+    "echo": true,
+    "reveal": "always",
+    "focus": false,
+    "panel": "shared"
+  },
+  "problemMatcher": {
+    "owner": "ts-unused",
+    "fileLocation": ["relative", "${workspaceFolder}"],
+    "pattern": [
+      {
+        "regexp": "^([^\\s].*?)$",
+        "file": 1
+      },
+      {
+        "regexp": "^\\s+(.+?):(\\d+):(\\d+)-(\\d+)\\s+\\[(ERROR|WARNING|INFO)\\]\\s+\\((.+)\\)$",
+        "code": 1,
+        "line": 2,
+        "column": 3,
+        "endColumn": 4,
+        "severity": 5,
+        "message": 6,
+        "loop": true
+      }
+    ]
+  }
+}
+```
+
+This will:
+- Display results in VS Code's Problems panel
+- Show severity indicators (error, warning, info)
+- Allow clicking to navigate to the exact file location
+- Highlight the entire identifier (function name, property name, etc.) in the editor
+- Provide quick fixes and context
+
+## Advanced Features
+
+### 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:
+
+- **Interface Composition**: When spreading values between different interface types
+- **Type Transformations**: When converting from one type to another via object spreading
+- **Shared Property Patterns**: When multiple interfaces define the same property structure
+
+**Example:**
+
+```typescript
+// Source interface
+interface SourceOptions {
+  timeout: number;
+  retryCount: number;
+}
+
+// Different interface with same properties
+interface ProcessedOptions {
+  timeout: number;      // Same name and type
+  retryCount: number;   // Same name and type
+  additionalOption: string;
+}
+
+// Usage through type conversion
+function handler(sourceOpts: SourceOptions) {
+  const processedOpts: ProcessedOptions = {
+    ...sourceOpts,  // timeout and retryCount flow here
+    additionalOption: 'value'
+  };
+  
+  console.log(processedOpts.timeout);  // Accesses ProcessedOptions.timeout
+}
+```
+
+In this case, `SourceOptions.timeout` and `SourceOptions.retryCount` are **not** flagged as unused, even though they're never directly accessed. The analyzer recognizes that `ProcessedOptions.timeout` and `ProcessedOptions.retryCount` are structurally equivalent and used, so their counterparts in `SourceOptions` are also considered used.
+
+## License
+
+MIT License

package/dist/cli.js

@@ -0,0 +1,915 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import fs2 from "node:fs";
+import path10 from "node:path";
+
+// src/analyzeProject.ts
+import path6 from "node:path";
+import { Project } from "ts-morph";
+
+// src/findUnusedExports.ts
+import path2 from "node:path";
+
+// src/checkExportUsage.ts
+import path from "node:path";
+import { Node } from "ts-morph";
+function getExportKind(declaration) {
+  if (Node.isFunctionDeclaration(declaration)) {
+    return "function";
+  }
+  if (Node.isClassDeclaration(declaration)) {
+    return "class";
+  }
+  if (Node.isInterfaceDeclaration(declaration)) {
+    return "interface";
+  }
+  if (Node.isTypeAliasDeclaration(declaration)) {
+    return "type";
+  }
+  if (Node.isEnumDeclaration(declaration)) {
+    return "enum";
+  }
+  if (Node.isModuleDeclaration(declaration)) {
+    return "namespace";
+  }
+  if (Node.isVariableDeclaration(declaration)) {
+    const parent = declaration.getParent();
+    if (Node.isVariableDeclarationList(parent)) {
+      const declarationKind = parent.getDeclarationKind();
+      if (declarationKind === "const") {
+        return "const";
+      }
+    }
+    return "variable";
+  }
+  return "export";
+}
+function getNameNode(declaration) {
+  if (Node.isFunctionDeclaration(declaration) || Node.isClassDeclaration(declaration) || Node.isInterfaceDeclaration(declaration) || Node.isTypeAliasDeclaration(declaration) || Node.isEnumDeclaration(declaration) || Node.isVariableDeclaration(declaration)) {
+    return declaration.getNameNode();
+  }
+  return;
+}
+function checkExportUsage(exportName, declarations, sourceFile, tsConfigDir, isTestFile) {
+  const firstDeclaration = declarations[0];
+  if (!firstDeclaration) {
+    return null;
+  }
+  const declarationSourceFile = firstDeclaration.getSourceFile();
+  if (declarationSourceFile.getFilePath() !== sourceFile.getFilePath()) {
+    return null;
+  }
+  if (!Node.isReferenceFindable(firstDeclaration)) {
+    return null;
+  }
+  const references = firstDeclaration.findReferences();
+  let totalReferences = 0;
+  let testReferences = 0;
+  let nonTestReferences = 0;
+  for (const refGroup of references) {
+    const refs = refGroup.getReferences();
+    for (const ref of refs) {
+      const refSourceFile = ref.getSourceFile();
+      totalReferences++;
+      if (isTestFile(refSourceFile)) {
+        testReferences++;
+      } else {
+        nonTestReferences++;
+      }
+    }
+  }
+  const onlyUsedInTests = nonTestReferences === 1 && testReferences > 0;
+  if (totalReferences > 1 && !onlyUsedInTests) {
+    return null;
+  }
+  const kind = getExportKind(firstDeclaration);
+  const relativePath = path.relative(tsConfigDir, sourceFile.getFilePath());
+  const severity = onlyUsedInTests ? "info" : "error";
+  const nameNode = getNameNode(firstDeclaration);
+  const positionNode = nameNode || firstDeclaration;
+  const startPos = positionNode.getStart();
+  const lineStartPos = positionNode.getStartLinePos();
+  const character = startPos - lineStartPos + 1;
+  const endCharacter = character + exportName.length;
+  const result = {
+    filePath: relativePath,
+    exportName,
+    line: firstDeclaration.getStartLineNumber(),
+    character,
+    endCharacter,
+    kind,
+    severity,
+    onlyUsedInTests
+  };
+  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 = [];
+  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 exports = sourceFile.getExportedDeclarations();
+    for (const [exportName, declarations] of exports.entries()) {
+      const unusedExport = checkExportUsage(exportName, declarations, sourceFile, tsConfigDir, isTestFile);
+      if (unusedExport) {
+        results.push(unusedExport);
+      }
+    }
+  }
+  return results;
+}
+
+// src/findUnusedProperties.ts
+import path5 from "node:path";
+
+// src/analyzeInterfaces.ts
+import path3 from "node:path";
+
+// src/extractTodoComment.ts
+function extractTodoComment(prop) {
+  const leadingComments = prop.getLeadingCommentRanges();
+  for (const comment of leadingComments) {
+    const commentText = comment.getText();
+    const singleLineMatch = commentText.match(/\/\/\s*TODO\s+(.+)/i);
+    if (singleLineMatch) {
+      const todoText = singleLineMatch[1];
+      if (todoText) {
+        return todoText.trim();
+      }
+    }
+    const multiLineMatch = commentText.match(/\/\*+\s*TODO\s+(.+?)\*\//is);
+    if (multiLineMatch) {
+      const todoText = multiLineMatch[1];
+      if (todoText) {
+        return todoText.trim().replace(/\s+/g, " ");
+      }
+    }
+  }
+  return;
+}
+
+// src/findStructurallyEquivalentProperties.ts
+import { SyntaxKind } from "ts-morph";
+function checkInterfaceProperties(iface, propName, propType, originalProp, equivalentProps) {
+  const properties = iface.getProperties();
+  for (const p of properties) {
+    if (p === originalProp) {
+      continue;
+    }
+    if (p.getName() === propName) {
+      const pType = p.getType().getText();
+      if (pType === propType) {
+        equivalentProps.push(p);
+      }
+    }
+  }
+}
+function checkTypeAliasProperties(typeAlias, propName, propType, originalProp, equivalentProps) {
+  const typeNode = typeAlias.getTypeNode();
+  if (!typeNode || typeNode.getKind() !== SyntaxKind.TypeLiteral) {
+    return;
+  }
+  const properties = typeNode.getChildren().filter((child) => child.getKind() === SyntaxKind.PropertySignature);
+  for (const p of properties) {
+    if (p === originalProp) {
+      continue;
+    }
+    if (p.getKind() === SyntaxKind.PropertySignature && p.getName() === propName) {
+      const pType = p.getType().getText();
+      if (pType === propType) {
+        equivalentProps.push(p);
+      }
+    }
+  }
+}
+function findStructurallyEquivalentProperties(prop, project) {
+  const propName = prop.getName();
+  const propType = prop.getType().getText();
+  const equivalentProps = [];
+  const sourceFiles = project.getSourceFiles();
+  for (const sourceFile of sourceFiles) {
+    const interfaces = sourceFile.getInterfaces();
+    for (const iface of interfaces) {
+      checkInterfaceProperties(iface, propName, propType, prop, equivalentProps);
+    }
+    const typeAliases = sourceFile.getTypeAliases();
+    for (const typeAlias of typeAliases) {
+      checkTypeAliasProperties(typeAlias, propName, propType, prop, equivalentProps);
+    }
+  }
+  return equivalentProps;
+}
+
+// src/isPropertyUnused.ts
+function countPropertyReferences(prop, isTestFile) {
+  const references = prop.findReferences();
+  let totalReferences = 0;
+  let testReferences = 0;
+  let nonTestReferences = 0;
+  for (const refGroup of references) {
+    const refs = refGroup.getReferences();
+    for (const ref of refs) {
+      const refSourceFile = ref.getSourceFile();
+      totalReferences++;
+      if (isTestFile(refSourceFile)) {
+        testReferences++;
+      } else {
+        nonTestReferences++;
+      }
+    }
+  }
+  const result = {
+    totalReferences,
+    testReferences,
+    nonTestReferences
+  };
+  return result;
+}
+function isPropertyUnused(prop, isTestFile, project) {
+  const counts = countPropertyReferences(prop, isTestFile);
+  const onlyUsedInTests = counts.nonTestReferences === 1 && counts.testReferences > 0;
+  if (counts.totalReferences > 1 && !onlyUsedInTests) {
+    const result2 = { isUnusedOrTestOnly: false, onlyUsedInTests: false };
+    return result2;
+  }
+  const equivalentProps = findStructurallyEquivalentProperties(prop, project);
+  for (const equivalentProp of equivalentProps) {
+    const equivalentCounts = countPropertyReferences(equivalentProp, isTestFile);
+    const equivalentOnlyUsedInTests = equivalentCounts.nonTestReferences === 1 && equivalentCounts.testReferences > 0;
+    if (equivalentCounts.totalReferences > 1 && !equivalentOnlyUsedInTests) {
+      const result2 = { isUnusedOrTestOnly: false, onlyUsedInTests: false };
+      return result2;
+    }
+  }
+  const result = { isUnusedOrTestOnly: true, onlyUsedInTests };
+  return result;
+}
+
+// src/analyzeInterfaces.ts
+function analyzeInterfaces(sourceFile, tsConfigDir, isTestFile, results, project) {
+  const interfaces = sourceFile.getInterfaces();
+  for (const iface of interfaces) {
+    const interfaceName = iface.getName();
+    for (const prop of iface.getProperties()) {
+      const usage = isPropertyUnused(prop, isTestFile, project);
+      if (usage.isUnusedOrTestOnly) {
+        const relativePath = path3.relative(tsConfigDir, sourceFile.getFilePath());
+        const todoComment = extractTodoComment(prop);
+        let severity = "error";
+        if (todoComment) {
+          severity = "warning";
+        } else if (usage.onlyUsedInTests) {
+          severity = "info";
+        }
+        const propertyName = prop.getName();
+        const startPos = prop.getStart();
+        const lineStartPos = prop.getStartLinePos();
+        const character = startPos - lineStartPos + 1;
+        const endCharacter = character + propertyName.length;
+        const result = {
+          filePath: relativePath,
+          typeName: interfaceName,
+          propertyName,
+          line: prop.getStartLineNumber(),
+          character,
+          endCharacter,
+          todoComment,
+          severity,
+          onlyUsedInTests: usage.onlyUsedInTests
+        };
+        results.push(result);
+      }
+    }
+  }
+}
+
+// src/analyzeTypeAliases.ts
+import path4 from "node:path";
+import { Node as Node2 } from "ts-morph";
+function analyzeTypeLiteralMember(member, typeName, sourceFile, tsConfigDir, isTestFile, results, project) {
+  if (!Node2.isPropertySignature(member)) {
+    return;
+  }
+  const usage = isPropertyUnused(member, isTestFile, project);
+  if (!usage.isUnusedOrTestOnly) {
+    return;
+  }
+  const relativePath = path4.relative(tsConfigDir, sourceFile.getFilePath());
+  const todoComment = extractTodoComment(member);
+  let severity = "error";
+  if (todoComment) {
+    severity = "warning";
+  } else if (usage.onlyUsedInTests) {
+    severity = "info";
+  }
+  const propertyName = member.getName();
+  const startPos = member.getStart();
+  const lineStartPos = member.getStartLinePos();
+  const character = startPos - lineStartPos + 1;
+  const endCharacter = character + propertyName.length;
+  const result = {
+    filePath: relativePath,
+    typeName,
+    propertyName,
+    line: member.getStartLineNumber(),
+    character,
+    endCharacter,
+    todoComment,
+    severity,
+    onlyUsedInTests: usage.onlyUsedInTests
+  };
+  results.push(result);
+}
+function analyzeTypeAlias(typeAlias, sourceFile, tsConfigDir, isTestFile, results, project) {
+  const typeName = typeAlias.getName();
+  const typeNode = typeAlias.getTypeNode();
+  if (!typeNode) {
+    return;
+  }
+  if (!Node2.isTypeLiteral(typeNode)) {
+    return;
+  }
+  for (const member of typeNode.getMembers()) {
+    analyzeTypeLiteralMember(member, typeName, sourceFile, tsConfigDir, isTestFile, results, project);
+  }
+}
+function analyzeTypeAliases(sourceFile, tsConfigDir, isTestFile, results, project) {
+  const typeAliases = sourceFile.getTypeAliases();
+  for (const typeAlias of typeAliases) {
+    analyzeTypeAlias(typeAlias, sourceFile, tsConfigDir, isTestFile, results, project);
+  }
+}
+
+// src/findUnusedProperties.ts
+function findUnusedProperties(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 = path5.relative(tsConfigDir, sourceFile.getFilePath());
+      onProgress(relativePath);
+    }
+    analyzeInterfaces(sourceFile, tsConfigDir, isTestFile, results, project);
+    analyzeTypeAliases(sourceFile, tsConfigDir, isTestFile, results, project);
+  }
+  return results;
+}
+
+// src/isTestFile.ts
+var TEST_FILE_EXTENSIONS = [".test.ts", ".test.tsx", ".spec.ts", ".spec.tsx"];
+function isTestFile(sourceFile) {
+  const filePath = sourceFile.getFilePath();
+  return filePath.includes("__tests__") || TEST_FILE_EXTENSIONS.some((ext) => filePath.endsWith(ext));
+}
+
+// src/analyzeProject.ts
+function analyzeProject(tsConfigPath, onProgress, targetFilePath, isTestFile2 = isTestFile) {
+  const project = new Project({
+    tsConfigFilePath: tsConfigPath
+  });
+  const tsConfigDir = path6.dirname(tsConfigPath);
+  const allSourceFiles = project.getSourceFiles();
+  const filesToAnalyze = allSourceFiles.filter((sf) => {
+    if (isTestFile2(sf)) {
+      return false;
+    }
+    if (hasNoCheck(sf)) {
+      return false;
+    }
+    if (targetFilePath && sf.getFilePath() !== targetFilePath) {
+      return false;
+    }
+    return true;
+  });
+  const totalFiles = filesToAnalyze.length;
+  let currentFile = 0;
+  const filesProcessed = new Set;
+  const progressCallback = onProgress ? (filePath) => {
+    if (!filesProcessed.has(filePath)) {
+      filesProcessed.add(filePath);
+      currentFile++;
+      onProgress(currentFile, totalFiles, filePath);
+    }
+  } : undefined;
+  const unusedExports = findUnusedExports(project, tsConfigDir, isTestFile2, progressCallback, targetFilePath);
+  const unusedProperties = findUnusedProperties(project, tsConfigDir, isTestFile2, progressCallback, targetFilePath);
+  const unusedFiles = [];
+  const fileExportCounts = new Map;
+  for (const sourceFile of filesToAnalyze) {
+    const filePath = path6.relative(tsConfigDir, sourceFile.getFilePath());
+    const exports = sourceFile.getExportedDeclarations();
+    const totalExports = exports.size;
+    if (totalExports > 0) {
+      fileExportCounts.set(filePath, { total: totalExports, unused: 0 });
+    }
+  }
+  for (const unusedExport of unusedExports) {
+    const counts = fileExportCounts.get(unusedExport.filePath);
+    if (counts) {
+      counts.unused++;
+    }
+  }
+  for (const [filePath, counts] of fileExportCounts.entries()) {
+    if (counts.total > 0 && counts.unused === counts.total) {
+      unusedFiles.push(filePath);
+    }
+  }
+  const results = {
+    unusedExports,
+    unusedProperties,
+    unusedFiles
+  };
+  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";
+
+// src/checkGitStatus.ts
+import { execSync } from "node:child_process";
+import path7 from "node:path";
+function checkGitStatus(workingDir) {
+  const changedFiles = new Set;
+  try {
+    const gitRoot = execSync("git rev-parse --show-toplevel", {
+      cwd: workingDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "ignore"]
+    }).trim();
+    const output = execSync("git status --porcelain", {
+      cwd: workingDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "ignore"]
+    });
+    const lines = output.trim().split(`
+`);
+    for (const line of lines) {
+      if (!line)
+        continue;
+      const filename = line.slice(3).trim();
+      const actualFilename = filename.includes(" -> ") ? filename.split(" -> ")[1] : filename;
+      if (actualFilename) {
+        const absolutePath = path7.resolve(gitRoot, actualFilename);
+        changedFiles.add(absolutePath);
+      }
+    }
+  } catch (_error) {
+    return changedFiles;
+  }
+  return changedFiles;
+}
+
+// src/fixProject.ts
+function fixProject(tsConfigPath, onProgress, isTestFile2 = isTestFile) {
+  const results = {
+    fixedExports: 0,
+    fixedProperties: 0,
+    deletedFiles: 0,
+    skippedFiles: [],
+    errors: []
+  };
+  const analysis = analyzeProject(tsConfigPath, undefined, undefined, isTestFile2);
+  const tsConfigDir = path8.dirname(path8.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);
+    if (filesWithChanges.has(absoluteFilePath)) {
+      onProgress?.(`Skipped: ${relativeFilePath} (has local git changes)`);
+      results.skippedFiles.push(relativeFilePath);
+      continue;
+    }
+    try {
+      onProgress?.(`Deleting: ${relativeFilePath} (all exports unused)`);
+      fs.unlinkSync(absoluteFilePath);
+      deletedFiles.add(relativeFilePath);
+      results.deletedFiles++;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      results.errors.push({ file: relativeFilePath, error: errorMessage });
+      onProgress?.(`Error deleting ${relativeFilePath}: ${errorMessage}`);
+    }
+  }
+  if (deletedFiles.size > 0) {
+    cleanupBrokenImports(project, tsConfigDir, deletedFiles, filesWithChanges, onProgress, results);
+  }
+  const exportsByFile = new Map;
+  for (const unusedExport of analysis.unusedExports) {
+    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);
+    if (analysis.unusedFiles.includes(relativeFilePath)) {
+      continue;
+    }
+    if (filesWithChanges.has(absoluteFilePath)) {
+      onProgress?.(`Skipped: ${relativeFilePath} (has local git changes)`);
+      results.skippedFiles.push(relativeFilePath);
+      continue;
+    }
+    try {
+      const sourceFile = project.getSourceFile(absoluteFilePath);
+      if (!sourceFile) {
+        continue;
+      }
+      onProgress?.(`Fixing: ${relativeFilePath}`);
+      for (const unusedExport of exports) {
+        if (removeExport(sourceFile, unusedExport.exportName)) {
+          onProgress?.(`  ✓ Removed unused export: ${unusedExport.exportName}`);
+          results.fixedExports++;
+        }
+      }
+      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 propertiesByFile = new Map;
+  for (const unusedProperty of analysis.unusedProperties) {
+    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);
+    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;
+      }
+      if (!exportsByFile.has(relativeFilePath)) {
+        onProgress?.(`Fixing: ${relativeFilePath}`);
+      }
+      for (const unusedProperty of properties) {
+        if (removeProperty(sourceFile, unusedProperty.typeName, unusedProperty.propertyName)) {
+          onProgress?.(`  ✓ Removed unused property: ${unusedProperty.typeName}.${unusedProperty.propertyName}`);
+          results.fixedProperties++;
+        }
+      }
+      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}`);
+    }
+  }
+  return results;
+}
+function removeExport(sourceFile, exportName) {
+  const exportedDeclarations = sourceFile.getExportedDeclarations();
+  const declarations = exportedDeclarations.get(exportName);
+  if (!declarations || declarations.length === 0) {
+    return false;
+  }
+  for (const declaration of declarations) {
+    if (declaration.getKind() === SyntaxKind2.VariableDeclaration) {
+      const variableStatement = declaration.getFirstAncestorByKind(SyntaxKind2.VariableStatement);
+      if (variableStatement) {
+        variableStatement.remove();
+        continue;
+      }
+    }
+    if ("remove" in declaration && typeof declaration.remove === "function") {
+      declaration.remove();
+    }
+  }
+  return true;
+}
+function removeProperty(sourceFile, typeName, propertyName) {
+  const interfaces = sourceFile.getInterfaces();
+  for (const iface of interfaces) {
+    if (iface.getName() === typeName) {
+      const property = iface.getProperty(propertyName);
+      if (property) {
+        property.remove();
+        return true;
+      }
+    }
+  }
+  const typeAliases = sourceFile.getTypeAliases();
+  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);
+        const members = typeLiteral.getMembers();
+        for (const member of members) {
+          if (member.getKind() === SyntaxKind2.PropertySignature) {
+            const propSig = member.asKind(SyntaxKind2.PropertySignature);
+            if (propSig?.getName() === propertyName) {
+              propSig.remove();
+              return true;
+            }
+          }
+        }
+      }
+    }
+  }
+  return false;
+}
+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 absolutePath = sourceFile.getFilePath();
+    if (filesWithChanges.has(absolutePath)) {
+      continue;
+    }
+    const exportDeclarations = sourceFile.getExportDeclarations();
+    let hasValidExports = false;
+    const brokenExports = [];
+    for (const exportDecl of exportDeclarations) {
+      const moduleSpecifier = exportDecl.getModuleSpecifierValue();
+      if (moduleSpecifier) {
+        const resolvedPath = resolveImportPath(sourceFile.getFilePath(), moduleSpecifier);
+        const relativeResolvedPath = resolvedPath ? path8.relative(tsConfigDir, resolvedPath) : null;
+        if (relativeResolvedPath && deletedFiles.has(relativeResolvedPath)) {
+          brokenExports.push(exportDecl);
+        } else {
+          hasValidExports = true;
+        }
+      } else {
+        hasValidExports = true;
+      }
+    }
+    const hasOwnDeclarations = sourceFile.getFunctions().length > 0 || sourceFile.getClasses().length > 0 || sourceFile.getInterfaces().length > 0 || sourceFile.getTypeAliases().length > 0 || sourceFile.getVariableDeclarations().length > 0 || sourceFile.getEnums().length > 0;
+    if (hasOwnDeclarations) {
+      hasValidExports = true;
+    }
+    if (brokenExports.length > 0 && !hasValidExports) {
+      try {
+        onProgress?.(`Deleting: ${relativePath} (only re-exports from deleted files)`);
+        fs.unlinkSync(absolutePath);
+        if (results) {
+          results.deletedFiles++;
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (results) {
+          results.errors.push({ file: relativePath, error: errorMessage });
+        }
+        onProgress?.(`Error deleting ${relativePath}: ${errorMessage}`);
+      }
+    } else if (brokenExports.length > 0) {
+      try {
+        onProgress?.(`Fixing: ${relativePath}`);
+        for (const exportDecl of brokenExports) {
+          const moduleSpec = exportDecl.getModuleSpecifierValue();
+          exportDecl.remove();
+          onProgress?.(`  ✓ Removed broken re-export from: ${moduleSpec}`);
+        }
+        sourceFile.saveSync();
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (results) {
+          results.errors.push({ file: relativePath, error: errorMessage });
+        }
+        onProgress?.(`Error fixing ${relativePath}: ${errorMessage}`);
+      }
+    }
+  }
+}
+function resolveImportPath(fromFile, importPath) {
+  const fromDir = path8.dirname(fromFile);
+  if (importPath.startsWith(".")) {
+    const resolved = path8.resolve(fromDir, importPath);
+    const extensions = [".ts", ".tsx", ".js", ".jsx"];
+    for (const ext of extensions) {
+      const withExt = resolved + ext;
+      if (fs.existsSync(withExt)) {
+        return withExt;
+      }
+    }
+    for (const ext of extensions) {
+      const indexFile = path8.join(resolved, `index${ext}`);
+      if (fs.existsSync(indexFile)) {
+        return indexFile;
+      }
+    }
+    return `${resolved}.ts`;
+  }
+  return null;
+}
+
+// src/formatResults.ts
+import path9 from "node:path";
+function getSeverityMarker(severity) {
+  const markers = {
+    error: "[ERROR]",
+    warning: "[WARNING]",
+    info: "[INFO]"
+  };
+  return markers[severity];
+}
+function formatExportLine(item) {
+  const marker = getSeverityMarker(item.severity);
+  if (item.onlyUsedInTests) {
+    return `  ${item.exportName}:${item.line}:${item.character}-${item.endCharacter} ${marker} (Used only in tests)`;
+  }
+  return `  ${item.exportName}:${item.line}:${item.character}-${item.endCharacter} ${marker} (Unused ${item.kind})`;
+}
+function formatPropertyLine(item) {
+  const status = item.onlyUsedInTests ? "Used only in tests" : "Unused property";
+  const todoSuffix = item.todoComment ? `: [TODO] ${item.todoComment}` : "";
+  const marker = getSeverityMarker(item.severity);
+  return `  ${item.typeName}.${item.propertyName}:${item.line}:${item.character}-${item.endCharacter} ${marker} (${status}${todoSuffix})`;
+}
+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);
+    lines.push(relativePath);
+    for (const item of groupItems) {
+      lines.push(formatter(item));
+    }
+    lines.push("");
+  }
+  return lines;
+}
+function formatResults(results, tsConfigDir) {
+  const lines = [];
+  const cwd = process.cwd();
+  const unusedExportNames = new Set;
+  for (const exportItem of results.unusedExports) {
+    unusedExportNames.add(exportItem.exportName);
+  }
+  const propertiesToReport = results.unusedProperties.filter((prop) => !unusedExportNames.has(prop.typeName));
+  const unusedFileSet = new Set(results.unusedFiles);
+  const exportsToReport = results.unusedExports.filter((exp) => !unusedFileSet.has(exp.filePath));
+  if (results.unusedFiles.length > 0) {
+    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);
+      lines.push(relativePath);
+      lines.push("  file:1:1-1 [ERROR] (All exports unused - file can be deleted)");
+      lines.push("");
+    }
+  }
+  if (exportsToReport.length > 0) {
+    lines.push("Unused Exports:");
+    lines.push("");
+    lines.push(...formatGroupedItems(exportsToReport, formatExportLine, tsConfigDir, cwd));
+  }
+  if (propertiesToReport.length > 0) {
+    lines.push("Unused Type/Interface Properties:");
+    lines.push("");
+    lines.push(...formatGroupedItems(propertiesToReport, formatPropertyLine, tsConfigDir, cwd));
+  }
+  if (results.unusedFiles.length === 0 && exportsToReport.length === 0 && propertiesToReport.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}`);
+  }
+  return lines.join(`
+`);
+}
+function groupByFile(items) {
+  const grouped = new Map;
+  for (const item of items) {
+    const existing = grouped.get(item.filePath);
+    if (existing) {
+      existing.push(item);
+    } else {
+      grouped.set(item.filePath, [item]);
+    }
+  }
+  return grouped;
+}
+
+// src/cli.ts
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0) {
+    console.log("Usage: ts-unused <command> <path-to-tsconfig.json> [file-path-to-check]");
+    console.log("");
+    console.log("Commands:");
+    console.log("  check  - Analyze and report unused exports/properties (default)");
+    console.log("  fix    - Automatically remove unused exports/properties and delete unused files");
+    console.log("");
+    console.log("Examples:");
+    console.log("  ts-unused check tsconfig.json");
+    console.log("  ts-unused check ./project-dir    # looks for tsconfig.json inside");
+    console.log("  ts-unused fix tsconfig.json");
+    process.exit(1);
+  }
+  const firstArg = args[0] ?? "";
+  let command = "check";
+  let configIndex = 0;
+  if (firstArg === "check" || firstArg === "fix") {
+    command = firstArg;
+    configIndex = 1;
+  }
+  let tsConfigPath = path10.resolve(args[configIndex] ?? "");
+  if (fs2.existsSync(tsConfigPath) && fs2.statSync(tsConfigPath).isDirectory()) {
+    tsConfigPath = path10.join(tsConfigPath, "tsconfig.json");
+  }
+  const targetFilePath = args[configIndex + 1] ? path10.resolve(args[configIndex + 1]) : undefined;
+  if (command === "fix") {
+    console.log(`Fixing TypeScript project: ${tsConfigPath}`);
+    console.log("");
+    const results = fixProject(tsConfigPath, (message) => {
+      console.log(message);
+    });
+    console.log("");
+    console.log("Summary:");
+    console.log(`  Fixed exports: ${results.fixedExports}`);
+    console.log(`  Fixed properties: ${results.fixedProperties}`);
+    console.log(`  Deleted files: ${results.deletedFiles}`);
+    console.log(`  Skipped files: ${results.skippedFiles.length}`);
+    if (results.errors.length > 0) {
+      console.log("");
+      console.log("Errors:");
+      for (const error of results.errors) {
+        console.log(`  ${error.file}: ${error.error}`);
+      }
+    }
+    if (results.skippedFiles.length > 0) {
+      console.log("");
+      console.log("Skipped files (have local git changes):");
+      for (const file of results.skippedFiles) {
+        console.log(`  ${file}`);
+      }
+    }
+  } else {
+    console.log(`Analyzing TypeScript project: ${tsConfigPath}`);
+    if (targetFilePath) {
+      console.log(`Checking only: ${targetFilePath}`);
+    }
+    console.log("");
+    const results = analyzeProject(tsConfigPath, (current, total, filePath) => {
+      const percentage = Math.min(100, Math.floor(current / total * 100));
+      const barLength = 40;
+      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);
+      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 output = formatResults(results, tsConfigDir);
+    console.log(output);
+  }
+}
+main();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "ts-unused",
+  "version": "1.0.0",
+  "description": "Find unused exports and properties in TypeScript projects",
+  "license": "MIT",
+  "bin": {
+    "ts-unused": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "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",
+    "typecheck": "tsgo --noEmit",
+    "lint": "bun run fix && biome check src",
+    "fix": "biome check --write --unsafe src",
+    "sanity-check": "bun run scripts/sanity-check.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.8",
+    "@types/bun": "latest",
+    "@types/node": "^24.10.1",
+    "@typescript/native-preview": "^7.0.0-dev.20251128.1"
+  },
+  "dependencies": {
+    "ts-morph": "^27.0.2",
+    "typescript": "^5"
+  }
+}