ts-unused 1.0.2 → 1.0.3

package/README.md

@@ -104,6 +104,103 @@ ts-unused ./tsconfig.json
 
 # Auto-fix
 ts-unused fix ./tsconfig.json
+
+# With custom config path
+ts-unused ./tsconfig.json --config ./custom.config.ts
+```
+
+## Configuration
+
+Create an `unused.config.ts` file in your project root (same directory as `tsconfig.json`) to customize the analysis behavior.
+
+### Example Configuration
+
+```typescript
+import { defineConfig } from "ts-unused";
+
+export default defineConfig({
+  // Custom patterns for identifying test files
+  testFilePatterns: [
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/__tests__/**",
+    "**/Test*.ts", // Include files like TestLogger.ts
+  ],
+
+  // Files to completely ignore during analysis
+  ignoreFilePatterns: [
+    "**/generated/**",
+    "**/*.d.ts",
+  ],
+
+  // Export names to ignore (supports glob patterns)
+  ignoreExports: [
+    "formatLogMessage", // Specific export
+    "internal*",        // All exports starting with "internal"
+  ],
+
+  // Property names to ignore in interfaces/types
+  ignoreProperties: [
+    "message",    // Common error property
+    "_*",         // Private-like properties
+  ],
+
+  // Type names to skip property analysis for
+  ignoreTypes: [
+    "*Config",    // Skip all config types
+    "Options",
+  ],
+
+  // Whether to ignore module augmentation declarations
+  // (declare module "..." blocks)
+  ignoreModuleAugmentations: true,
+
+  // Toggle specific analysis features
+  analyzeExports: true,
+  analyzeProperties: true,
+  analyzeNeverReturnedTypes: true,
+  detectUnusedFiles: true,
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `testFilePatterns` | `string[]` | `["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx", "**/__tests__/**"]` | Glob patterns for test file detection |
+| `ignoreFilePatterns` | `string[]` | `[]` | Files to completely ignore during analysis |
+| `ignoreExports` | `string[]` | `[]` | Export names to ignore (supports glob patterns) |
+| `ignoreProperties` | `string[]` | `[]` | Property names to ignore (supports glob patterns) |
+| `ignoreTypes` | `string[]` | `[]` | Type names to skip property analysis for |
+| `ignoreModuleAugmentations` | `boolean` | `true` | Whether to ignore `declare module` blocks |
+| `analyzeExports` | `boolean` | `true` | Enable/disable unused export detection |
+| `analyzeProperties` | `boolean` | `true` | Enable/disable unused property detection |
+| `analyzeNeverReturnedTypes` | `boolean` | `true` | Enable/disable never-returned type detection |
+| `detectUnusedFiles` | `boolean` | `true` | Enable/disable completely unused file detection |
+
+### Pattern Syntax
+
+The configuration supports glob-like patterns:
+
+- `*` - Matches any characters except `/`
+- `**` - Matches any characters including `/`
+- `?` - Matches any single character
+
+Examples:
+- `**/*.test.ts` - All `.test.ts` files in any directory
+- `**/Test*.ts` - All files starting with `Test` and ending with `.ts`
+- `internal*` - Names starting with `internal`
+- `*Config` - Names ending with `Config`
+
+### CLI Options
+
+```bash
+ts-unused [command] <path-to-tsconfig.json> [options]
+
+Options:
+  --config, -c <path>  Path to configuration file (default: unused.config.ts in project dir)
 ```
 
 ## Output
@@ -355,6 +452,179 @@ function handler(sourceOpts: SourceOptions) {
 
 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.
 
+## Programmatic API
+
+ts-unused can be used as a library in your own tools and scripts.
+
+### Installation
+
+```bash
+npm install ts-unused
+# or
+bun add ts-unused
+```
+
+### Basic Usage
+
+```typescript
+import path from "node:path";
+import { analyzeProject, loadConfigSync, formatResults } from "ts-unused";
+
+// Given a project root with unused.config.ts
+const projectRoot = "/path/to/your/project";
+const tsConfigPath = path.join(projectRoot, "tsconfig.json");
+
+// Load config from unused.config.ts (auto-detected in project directory)
+const config = loadConfigSync(tsConfigPath);
+
+// Analyze with config
+const results = analyzeProject(tsConfigPath, undefined, undefined, { config });
+
+// Format and print results (same output as CLI)
+const output = formatResults(results, projectRoot);
+console.log(output);
+```
+
+### API Reference
+
+#### `analyzeProject(tsConfigPath, onProgress?, targetFilePath?, options?)`
+
+Analyzes a TypeScript project for unused exports, properties, and never-returned types.
+
+```typescript
+import { analyzeProject, type AnalysisResults, type AnalyzeProjectOptions } from "ts-unused";
+
+const options: AnalyzeProjectOptions = {
+  config: {
+    ignoreFilePatterns: ["**/generated/**"],
+    ignoreExports: ["internal*"],
+    analyzeProperties: true,
+  },
+};
+
+const results: AnalysisResults = analyzeProject(
+  "./tsconfig.json",
+  (current, total, filePath) => console.log(`Processing ${current}/${total}: ${filePath}`),
+  undefined, // targetFilePath - analyze all files
+  options
+);
+
+console.log(`Found ${results.unusedExports.length} unused exports`);
+console.log(`Found ${results.unusedProperties.length} unused properties`);
+console.log(`Found ${results.unusedFiles.length} completely unused files`);
+console.log(`Found ${results.neverReturnedTypes?.length ?? 0} never-returned types`);
+```
+
+**Parameters:**
+- `tsConfigPath` - Path to tsconfig.json
+- `onProgress` - Optional callback for progress updates
+- `targetFilePath` - Optional path to analyze a single file
+- `options` - Optional `AnalyzeProjectOptions` object with `config` and/or `isTestFile`
+
+**Returns:** `AnalysisResults` object with arrays of findings
+
+#### `fixProject(tsConfigPath, onProgress?, isTestFile?)`
+
+Automatically removes unused exports, properties, and deletes unused files.
+
+```typescript
+import { fixProject, type FixResults } from "ts-unused";
+
+const results: FixResults = fixProject(
+  "./tsconfig.json",
+  (message) => console.log(message)
+);
+
+console.log(`Fixed ${results.fixedExports} exports`);
+console.log(`Fixed ${results.fixedProperties} properties`);
+console.log(`Fixed ${results.fixedNeverReturnedTypes} never-returned types`);
+console.log(`Deleted ${results.deletedFiles} files`);
+console.log(`Skipped ${results.skippedFiles.length} files (git changes)`);
+```
+
+**Parameters:**
+- `tsConfigPath` - Path to tsconfig.json
+- `onProgress` - Optional callback for status messages
+- `isTestFile` - Optional custom test file detection function
+
+**Returns:** `FixResults` object with counts and lists of changes
+
+#### `formatResults(results, tsConfigDir)`
+
+Formats analysis results into a human-readable string (same format as CLI output).
+
+```typescript
+import { analyzeProject, formatResults } from "ts-unused";
+
+const results = analyzeProject("./tsconfig.json");
+const formatted = formatResults(results, "./");
+console.log(formatted);
+```
+
+#### `loadConfig(tsConfigPath)` / `loadConfigSync(tsConfigPath)`
+
+Loads configuration from `unused.config.ts` in the project directory.
+
+```typescript
+import { loadConfig, loadConfigSync, type UnusedConfig } from "ts-unused";
+
+// Async version
+const config: UnusedConfig = await loadConfig("./tsconfig.json");
+
+// Sync version  
+const configSync: UnusedConfig = loadConfigSync("./tsconfig.json");
+
+// Use with analyzeProject
+const results = an![alt text](image.png)alyzeProject("./tsconfig.json", undefined, undefined, { config });
+```
+
+#### `defineConfig(config)`
+
+Type-safe helper for creating configuration files.
+
+```typescript
+// unused.config.ts
+import { defineConfig } from "ts-unused";
+
+export default defineConfig({
+  ignoreFilePatterns: ["**/generated/**"],
+  ignoreExports: ["internal*"],
+});
+```
+
+#### `createIsTestFile(patterns)`
+
+Creates a custom test file detection function from glob patterns.
+
+```typescript
+import { analyzeProject, createIsTestFile } from "ts-unused";
+
+const isTestFile = createIsTestFile([
+  "**/*.test.ts",
+  "**/*.spec.ts", 
+  "**/test/**",
+]);
+
+const results = analyzeProject("./tsconfig.json", undefined, undefined, { isTestFile });
+```
+
+#### Pattern Matching Utilities
+
+```typescript
+import { matchesPattern, matchesFilePattern, patternToRegex } from "ts-unused";
+
+// Match a name against patterns
+matchesPattern("internalHelper", ["internal*"]); // true
+matchesPattern("publicApi", ["internal*"]); // false
+
+// Match a file path against patterns
+matchesFilePattern("/project/src/generated/types.ts", ["**/generated/**"]); // true
+
+// Convert a glob pattern to RegExp
+const regex = patternToRegex("**/*.test.ts");
+regex.test("src/utils.test.ts"); // true
+```
+
 ## License
 
-MIT License
+MIT License

package/dist/analyzeFunctionReturnTypes.js

@@ -0,0 +1,235 @@
+import path from "node:path";
+import { SyntaxKind } from "ts-morph";
+/**
+ * Analyzes a function to detect union type branches in the return type that are never actually returned
+ */
+export function analyzeFunctionReturnTypes(func, sourceFile, tsConfigDir) {
+    const results = [];
+    const functionName = func.getName();
+    // Skip functions without names
+    if (!functionName) {
+        return results;
+    }
+    // Get the return type node
+    const returnTypeNode = func.getReturnTypeNode();
+    if (!returnTypeNode) {
+        return results;
+    }
+    // Get the actual Type from the type checker
+    const returnType = returnTypeNode.getType();
+    // Try to unwrap Promise first
+    const unwrappedPromise = unwrapPromiseType(returnType);
+    const typeToCheck = unwrappedPromise || returnType;
+    // Check if it's a union type (or contains a union after unwrapping Promise)
+    if (!typeToCheck.isUnion()) {
+        return results;
+    }
+    // Get all union type branches
+    const unionTypes = typeToCheck.getUnionTypes();
+    if (unionTypes.length < 2) {
+        // Not a meaningful union
+        return results;
+    }
+    // Get all return statements in the function
+    const returnStatements = func.getDescendantsOfKind(SyntaxKind.ReturnStatement);
+    // Collect types of all returned values
+    const returnedTypes = [];
+    for (const returnStmt of returnStatements) {
+        const expression = returnStmt.getExpression();
+        if (expression) {
+            const exprType = expression.getType();
+            // Unwrap Promise if needed
+            const unwrapped = unwrapPromiseType(exprType);
+            returnedTypes.push(unwrapped || exprType);
+        }
+    }
+    // If no return statements, can't determine what's returned
+    if (returnedTypes.length === 0) {
+        return results;
+    }
+    // Check if any returned type is a generic type assignable to the whole union but not to specific branches
+    // This happens with destructured objects or other inferred types that satisfy the union structurally
+    for (const returnedType of returnedTypes) {
+        if (returnedType.isAssignableTo(typeToCheck)) {
+            // Check if this type is assignable to ANY specific union branch
+            let assignableToAnyBranch = false;
+            for (const unionBranch of unionTypes) {
+                if (returnedType.isAssignableTo(unionBranch)) {
+                    assignableToAnyBranch = true;
+                    break;
+                }
+            }
+            // If assignable to the union but NOT to any specific branch,
+            // this is a generic type that could be any branch - skip analysis
+            if (!assignableToAnyBranch) {
+                return results;
+            }
+        }
+    }
+    // Group enum literals by their parent enum
+    // If any enum member is returned, we consider the entire enum as "returned"
+    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);
+            }
+        }
+    }
+    // Check which enums have at least one returned value
+    for (const [enumName, enumBranches] of enumGroups.entries()) {
+        for (const returnedType of returnedTypes) {
+            // Check if this returned type is any member of this enum
+            for (const enumBranch of enumBranches) {
+                if (isTypeAssignableTo(returnedType, enumBranch)) {
+                    enumsWithReturnedValues.add(enumName);
+                    break;
+                }
+            }
+            if (enumsWithReturnedValues.has(enumName)) {
+                break;
+            }
+        }
+    }
+    // Group union branches by display name to handle boolean (true/false) and avoid duplicates
+    const branchMap = new Map();
+    for (const unionBranch of unionTypes) {
+        const displayName = getTypeDisplayName(unionBranch);
+        if (!branchMap.has(displayName)) {
+            branchMap.set(displayName, unionBranch);
+        }
+    }
+    // Check each unique union branch to see if it's ever returned
+    for (const [displayName, unionBranch] of branchMap.entries()) {
+        // Skip enum literal branches if the enum has at least one returned value
+        if (unionBranch.isEnumLiteral()) {
+            const enumName = getEnumNameFromLiteral(unionBranch);
+            if (enumName && enumsWithReturnedValues.has(enumName)) {
+                // This enum has at least one returned value, so don't flag any of its members
+                continue;
+            }
+        }
+        let isReturned = false;
+        for (const returnedType of returnedTypes) {
+            // Check if the returned type is assignable to this union branch
+            if (isTypeAssignableTo(returnedType, unionBranch)) {
+                isReturned = true;
+                break;
+            }
+        }
+        if (!isReturned) {
+            // This union branch is never returned
+            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;
+}
+/**
+ * Unwrap Promise<T> to get T
+ */
+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;
+}
+/**
+ * Check if sourceType is assignable to targetType
+ */
+function isTypeAssignableTo(sourceType, targetType) {
+    // Use TypeScript's built-in type checker for assignability
+    // This properly handles structural compatibility, inferred types, etc.
+    if (sourceType.isAssignableTo(targetType)) {
+        return true;
+    }
+    // Special handling for boolean literals (true/false)
+    // TypeScript represents boolean as true | false, so we need to check
+    // if both are boolean literals when comparing
+    const sourceText = sourceType.getText();
+    const targetText = targetType.getText();
+    const isBooleanLiteral = (text) => text === "true" || text === "false";
+    if (isBooleanLiteral(sourceText) && isBooleanLiteral(targetText)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Extract the enum name from an enum literal type
+ * For example: "Status.Idle" -> "Status"
+ */
+function getEnumNameFromLiteral(type) {
+    if (!type.isEnumLiteral()) {
+        return null;
+    }
+    const typeText = type.getText();
+    // Strip import paths first
+    const cleanedText = typeText.replace(/import\([^)]+\)\./g, "");
+    // Extract enum name from "EnumName.MemberName"
+    const lastDotIndex = cleanedText.lastIndexOf(".");
+    if (lastDotIndex > 0) {
+        return cleanedText.substring(0, lastDotIndex);
+    }
+    return null;
+}
+/**
+ * Get a readable display name for a type
+ */
+function getTypeDisplayName(type) {
+    const symbol = type.getSymbol();
+    // If it has a symbol with a name, use that
+    if (symbol) {
+        const name = symbol.getName();
+        if (name && name !== "__type") {
+            return name;
+        }
+    }
+    // Otherwise, use the type text
+    let typeText = type.getText();
+    // Strip import paths from type text
+    // Pattern: import("path/to/file").TypeName -> TypeName
+    typeText = typeText.replace(/import\([^)]+\)\./g, "");
+    // Simplify common type texts
+    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";
+    // Truncate very long types (e.g., inline object types)
+    const MAX_TYPE_LENGTH = 100;
+    if (typeText.length > MAX_TYPE_LENGTH) {
+        return `${typeText.substring(0, MAX_TYPE_LENGTH)}...`;
+    }
+    return typeText;
+}

package/dist/analyzeInterfaces.d.ts

@@ -1,3 +1,7 @@
 import type { Project, SourceFile } from "ts-morph";
 import type { IsTestFileFn, UnusedPropertyResult } from "./types";
-export declare function analyzeInterfaces(sourceFile: SourceFile, tsConfigDir: string, isTestFile: IsTestFileFn, results: UnusedPropertyResult[], project: Project): void;
+export interface AnalyzeInterfacesOptions {
+    ignoreProperties?: string[];
+    ignoreTypes?: string[];
+}
+export declare function analyzeInterfaces(sourceFile: SourceFile, tsConfigDir: string, isTestFile: IsTestFileFn, results: UnusedPropertyResult[], project: Project, options?: AnalyzeInterfacesOptions): void;

package/dist/analyzeInterfaces.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { extractTodoComment } from "./extractTodoComment";
+import { isPropertyUnused } from "./isPropertyUnused";
+import { matchesPattern } from "./patternMatcher";
+export function analyzeInterfaces(sourceFile, tsConfigDir, isTestFile, results, project, options = {}) {
+    const { ignoreProperties = [], ignoreTypes = [] } = options;
+    const interfaces = sourceFile.getInterfaces();
+    for (const iface of interfaces) {
+        const interfaceName = iface.getName();
+        // Skip ignored types
+        if (ignoreTypes.length > 0 && matchesPattern(interfaceName, ignoreTypes)) {
+            continue;
+        }
+        for (const prop of iface.getProperties()) {
+            const propertyName = prop.getName();
+            // Skip ignored properties
+            if (ignoreProperties.length > 0 && matchesPattern(propertyName, ignoreProperties)) {
+                continue;
+            }
+            const usage = isPropertyUnused(prop, isTestFile, project);
+            if (usage.isUnusedOrTestOnly) {
+                const relativePath = path.relative(tsConfigDir, sourceFile.getFilePath());
+                const todoComment = extractTodoComment(prop);
+                // Determine severity: warning for TODO, info for test-only, error for completely unused
+                let severity = "error";
+                if (todoComment) {
+                    severity = "warning";
+                }
+                else if (usage.onlyUsedInTests) {
+                    severity = "info";
+                }
+                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);
+            }
+        }
+    }
+}

package/dist/analyzeProject.d.ts

@@ -1,2 +1,13 @@
+import { type UnusedConfig } from "./config";
 import type { AnalysisResults, IsTestFileFn } from "./types";
-export declare function analyzeProject(tsConfigPath: string, onProgress?: (current: number, total: number, filePath: string) => void, targetFilePath?: string, isTestFile?: IsTestFileFn): AnalysisResults;
+export interface AnalyzeProjectOptions {
+    /**
+     * Configuration options for the analysis.
+     */
+    config?: UnusedConfig;
+    /**
+     * Custom test file detection function (overrides config.testFilePatterns).
+     */
+    isTestFile?: IsTestFileFn;
+}
+export declare function analyzeProject(tsConfigPath: string, onProgress?: (current: number, total: number, filePath: string) => void, targetFilePath?: string, isTestFileOrOptions?: IsTestFileFn | AnalyzeProjectOptions): AnalysisResults;