angular-null-error-analyzer
Version:
CLI tool to detect potential null/undefined access and Angular template binding issues.
160 lines (103 loc) • 3.62 kB
Markdown
# angular-null-error-analyzer
CLI tool for detecting potential null/undefined access and Angular template binding issues in Angular projects.
## Features
- Detects unsafe property accesses in TypeScript files.
- Detects Angular template bindings without guards (`?.`) in HTML templates.
- Supports ignoring specific top-level objects or template bindings.
- Allows excluding files/folders from analysis (like `environments`, `spec.ts`, `assets`).
- Provides suggestions to use optional chaining or safer patterns.
- Detects non-null assertions (`!`) and usage of `any`.
## Installation
### Global Installation
```bash
npm install -g angular-null-error-analyzer
```
> Once installed, the CLI command `ng-analyze-null` will be available globally.
## Usage
```bash
# Analyze the current project directory
ng-analyze-null
# Analyze a specific Angular project path
ng-analyze-null /path/to/angular/project
```
## Configuration
You can create a `.ng-null-safety.json` file at the root of your project to customize exclusions, safe objects, and ignored bindings:
```json
{
"excludePaths": ["src/environments/**", "**/*.spec.ts", "src/assets/**"],
"safeObjects": ["fb", "fg", "loginForm"],
"ignoreBindings": ["disabled", "readonly"]
}
```
- **excludePaths**: Glob patterns to skip certain files or directories.
- **safeObjects**: Top-level objects considered safe; property accesses on these objects will not trigger warnings.
- **ignoreBindings**: Template attributes to ignore in HTML analysis (e.g., `[disabled]`, `[readonly]`).
> Default `ignoreBindings` includes `["disabled"]`.
## Detection Scenarios
### 1. TypeScript Property Access
**Unsafe:**
```ts
this.loginForm.valid
this.fb.group({...})
```
**Safe (optional chaining):**
```ts
this.loginForm?.valid
this.fb?.group({...})
```
### 2. Angular Template Binding
**Unsafe:**
```html
<input [value]="user.totalLikes" />
<button [disabled]="loginForm.invalid"></button>
```
**Safe (optional chaining):**
```html
<input [value]="user?.totalLikes" />
<button [disabled]="loginForm?.invalid"></button>
```
> Bindings listed in `ignoreBindings` will be ignored (e.g., `[disabled]`).
### 3. Non-null Assertions
**Unsafe:**
```ts
user!.name;
```
**Safe (optional chaining):**
```ts
user?.name;
```
### 4. Any Type Detection
Detects usage of `any` type in TypeScript:
```ts
let value: any; // ⚠️ may hide null/undefined issues
```
## Example CLI Output
```bash
📊 Total files analyzed: 21
⚠️ Issues found: 4
❌ [TemplateBinding] Binding without guard: [value]='user.totalLikes' (src/app/user/user.component.html:12)
💡 Suggestion: Use optional chaining: user?.totalLikes
❌ [PossibleNullAccess] Property access without null-check: this.loginForm.valid (src/app/login/login.ts:37)
💡 Suggestion: Consider using optional chaining: this.loginForm?.valid
```
## Notes
- `.spec.ts` files and test-related folders can be excluded via `excludePaths`.
- Safe objects and ignored bindings are configurable via `.ng-null-safety.json`.
- Works for Angular projects using TypeScript and HTML templates.
- Uses TypeScript AST and HTML parsing to detect unsafe property access patterns.
- Non-null assertions (`!`) and `any` type usage are also flagged as potential issues.
## Contributing
Contributions are welcome! Feel free to open issues or submit pull requests to improve the tool.
## License
MIT License