ts-analyzer 1.3.1 → 1.3.7

package/README.md

@@ -1,42 +1,147 @@
 # ts-analyzer
 
-ts-analyzer is a static analysis tool for checking TypeScript code quality, focusing on type safety and structural complexity.
+![npm](https://img.shields.io/npm/v/ts-analyzer)
+![coverage](https://img.shields.io/badge/coverage-88%25-brightgreen)
+![license](https://img.shields.io/npm/l/ts-analyzer)
+
+`ts-analyzer` is a code analysis tool that checks your TypeScript and JavaScript projects. It looks at how safe your types are, how complex your code is, and finds common mistakes.
+
+---
 
 ## Features
 
-- TypeScript safety metrics (type coverage, any usage, assertions).
-- Cyclomatic complexity and nesting depth analysis.
-- Detection of anti-patterns like magic numbers, callback hell, and god files.
-- Formatted output in Text, JSON, and HTML.
+- **Type Safety Checks**: It calculates your real type coverage. It tracks things like `any` usage, generics, and assertions.
+- **Code Complexity**: It checks how hard your code is to read by measuring cyclomatic complexity and nested blocks.
+- **Anti-patterns**: It spots bad practices like Magic Numbers, Callback Hell, huge files, and functions with too many parameters.
+- **Reports**: You can view the results as a nice HTML page, JSON, or just plain text in your terminal.
+- **Tested**: The project has around 88% test coverage using Vitest.
 
-## Quick Start
+---
 
-```bash
-npx ts-analyzer
+## How It Works
+
+### Type Safety
+The tool looks at your code to see if your variables and parameters actually have types, or if they are just left as `any`.
+
+```text
+┌─────────────────────┐
+│ TypeScript Files    │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐    ┌─────────────────────┐
+│ AST Analysis        │───>│ Node Classification │
+└─────────┬───────────┘    └─────────┬───────────┘
+          │                          │
+          ▼                          ▼
+┌─────────────────────┐    ┌─────────────────────┐
+│ Explicitly Typed    │    │ Implicitly Typed    │
+│ Nodes               │    │ Nodes               │
+└─────────┬───────────┘    └─────────┬───────────┘
+          │                          │
+          └──────────┬──────────────┘
+                     │
+                     ▼
+┌─────────────────────┐    ┌─────────────────────┐
+│ Type Coverage       │<───│ tsconfig.json       │
+│ Calculation         │    │ Analysis            │
+└─────────┬───────────┘    └─────────────────────┘
+          │
+          ▼
+┌─────────────────────┐
+│ "any" & Assertion   │
+│ Penalty Calculation │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│ Final Type Safety   │
+│ Score & Rating      │
+└─────────────────────┘
 ```
 
-## Usage
+* **Score**: It calculates a score based on your type coverage percentage, minus a penalty if you use `any` or type assertions too much.
+* **tsconfig**: You get extra bonus points if your `tsconfig.json` has strict settings enabled.
+
+### Code Complexity
+It looks at your functions to see how complicated they are:
+1. **Cyclomatic Complexity**: How many different paths your code can take.
+2. **Nesting Depth**: How many blocks are inside each other (to avoid Callback Hell).
+3. **Size**: How many lines and parameters your functions have.
+
+Based on this, it gives a rating: <30 is simple, 30-60 is moderate, and >60 means it's too complex.
+
+### Why switch to `ts-analyzer`?
+This tool is an upgrade from `react-loc-analyzer`. Instead of just counting lines, it actually understands your TypeScript code and gives you useful feedback to improve it.
+
+---
+
+## Quick Start
+
+You can run it directly using npx:
 
-Analyze a specific directory:
 ```bash
-ts-analyzer /path/to/project
+npx ts-analyzer /path/to/project
 ```
 
-Available options:
-- `-f, --format <type>`: `text`, `json`, or `html`.
-- `-e, --exclude <patterns>`: Comma-separated ignore patterns.
-- `--no-safety`: Skip type-safety analysis.
-- `--no-complexity`: Skip complexity analysis.
+Some options you can use:
+- `-f, --format <type>`: Choose between `text`, `json`, or `html`
+- `-e, --exclude <patterns>`: Folders to ignore, separated by commas
+- `--no-safety` / `--no-complexity`: Skip specific checks to run faster
 
-## Development
+## Example Reports
 
-Run tests:
-```bash
-npm test
+### JSON Output
+When you run `npx ts-analyzer /path -f json`, it generates structured data you can use in your CI/CD pipelines:
+
+```json
+{
+  "files": 156,
+  "totalLines": 15234,
+  "codeLines": 12845,
+  "typescriptSafety": {
+    "tsPercentage": "84.6",
+    "avgTypeCoverage": "92.3",
+    "totalAnyCount": 12,
+    "avgTypeSafetyScore": 85,
+    "overallComplexity": "Low"
+  },
+  "codeComplexity": {
+    "avgComplexity": "3.2",
+    "maxComplexity": 12,
+    "overallComplexity": "Low",
+    "codeSmells": {
+      "magicNumbers": 0,
+      "callbackHell": 0,
+      "godFiles": 0
+    }
+  }
+}
 ```
 
-Generate coverage:
+### HTML Output
+When you run `npx ts-analyzer /path -f html`, it creates a `ts-analyzer-report.html` file. This acts as a beautiful visual dashboard with:
+- **Project Summary Cards**: Big, clear numbers for your total lines and code lines.
+- **Color-coded Progress Bars**: Visual bars for Type Coverage percentages (turns red if too low).
+- **Red/Green Indicators**: Fast visual checks for code smells like Callback Hell and God Files.
+
+## Config File
+You don't have to type arguments every time. Just create a `ts-analyzer.config.json` in your project folder:
+```json
+{
+  "safety": true,
+  "complexity": true,
+  "format": "text",
+  "exclude": ["node_modules", "dist", ".next"],
+  "include": [".js", ".ts", ".tsx"]
+}
+```
+
+## Development
+To work on this project, install the dependencies and run the tests:
 ```bash
+npm install
+npm test
 npm run test:coverage
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-analyzer",
-  "version": "1.3.1",
+  "version": "1.3.7",
   "repository": "github:amir-valizadeh/ts-analyzer",
   "description": "Comprehensive TypeScript code analyzer with type safety and complexity metrics",
   "main": "dist/src/index.js",