\r \r

ErrorLens -- Error Handling & Exception Safety Analyzer\r

\r ErrorLens scans codebases for dangerous error handling patterns: empty catch blocks, swallowed exceptions, missing error boundaries, unhandled promise rejections, generic error types, missing finally blocks, bare except clauses, error message information leaks, unchecked error returns, and missing error propagation. Covers JS/TS, Python, Java, Go, Rust, and C#. Uses regex-based pattern matching against 90+ error handling anti-patterns, lefthook for git hook integration, and produces markdown reports with actionable remediation recommendations. 100% local. Zero telemetry.\r \r

Commands\r

\r

Free Tier (No license required)\r

\r

errorlens scan [file|directory]\r

One-shot error handling scan of files or directories.\r \r How to execute:\r

bash "\x3CSKILL_DIR>/scripts/errorlens.sh" scan [target]\r
```\r
\r
**What it does:**\r
1. Accepts a file path or directory (defaults to current directory)\r
2. Discovers all source files (skips .git, node_modules, binaries, images, .min.js)\r
3. Runs 90+ error handling pattern checks against each file\r
4. Respects .gitignore and allowlist files\r
5. Calculates an error safety score (0-100) per file and overall\r
6. Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (\x3C60)\r
7. Outputs findings with: file, line number, check ID, severity, description, recommendation\r
8. Exit code 0 if score >= 70, exit code 1 if too many issues found\r
9. Free tier limited to 5 files per scan\r
\r
**Example usage scenarios:**\r
- "Scan my code for error handling issues" -> runs `errorlens scan .`\r
- "Check this file for empty catch blocks" -> runs `errorlens scan src/api.ts`\r
- "Find swallowed exceptions in my project" -> runs `errorlens scan src/`\r
- "Are there unsafe error patterns in my code?" -> runs `errorlens scan .`\r
- "Check for missing error boundaries" -> runs `errorlens scan .`\r
\r
#### `errorlens hook`\r
Install git pre-commit hooks that scan staged files for error handling issues before every commit.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/errorlens.sh" hook install\r
```\r
\r
**What it does:**\r
1. Copies lefthook config to project root\r
2. Installs lefthook pre-commit hook\r
3. On every commit: scans all staged files for error handling issues, blocks commit if critical/high findings, shows remediation advice\r
\r
#### `errorlens report [directory]`\r
Generate a markdown error handling report with findings, severity breakdown, and remediation steps.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/errorlens.sh" report [directory]\r
```\r
\r
**What it does:**\r
1. Runs full scan of the directory\r
2. Generates a formatted markdown report from template\r
3. Includes per-file breakdowns, error safety scores, remediation priority\r
4. Output suitable for code reviews and quality audits\r
\r
### Pro Tier ($19/user/month -- requires ERRORLENS_LICENSE_KEY)\r
\r
#### `errorlens watch [directory]`\r
Continuous monitoring mode that watches for file changes and re-scans automatically.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/errorlens.sh" watch [directory]\r
```\r
\r
**What it does:**\r
1. Validates Pro+ license\r
2. Watches directory for file modifications\r
3. Re-scans changed files automatically on save\r
4. Displays live error handling score updates\r
5. Useful for development-time feedback\r
\r
#### `errorlens ci [directory]`\r
CI/CD integration mode with strict exit codes and machine-readable output.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/errorlens.sh" ci [directory]\r
```\r
\r
**What it does:**\r
1. Validates Pro+ license\r
2. Runs full scan with no file limit\r
3. Outputs findings in CI-friendly format\r
4. Exit code 0 = pass (score >= 70), 1 = fail\r
5. Supports severity threshold configuration\r
6. Suitable for GitHub Actions, GitLab CI, Jenkins, etc.\r
\r
### Team Tier ($39/user/month -- requires ERRORLENS_LICENSE_KEY with team tier)\r
\r
#### `errorlens team-report [directory]`\r
Aggregate team-level error handling metrics and trends.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/errorlens.sh" team-report [directory]\r
```\r
\r
**What it does:**\r
1. Validates Team+ license\r
2. Scans entire directory with full pattern set\r
3. Generates aggregate metrics per category (EC, SE, EB, GE, RP, IL)\r
4. Shows per-directory breakdown for team ownership analysis\r
5. Includes trend data if previous baselines exist\r
6. Reports team-wide error handling maturity score\r
\r
#### `errorlens baseline [directory]`\r
Establish a baseline of known error handling issues for incremental improvement tracking.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/errorlens.sh" baseline [directory]\r
```\r
\r
**What it does:**\r
1. Validates Team+ license\r
2. Scans directory and records all current findings as baseline\r
3. Saves baseline to .errorlens-baseline.json\r
4. Future scans only report NEW issues not in the baseline\r
5. Useful for legacy codebases with known accepted patterns\r
6. Enables incremental error handling improvement tracking\r
\r
#### `errorlens status`\r
Show license and configuration information.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/errorlens.sh" status\r
```\r
\r
## Detected Error Handling Patterns\r
\r
ErrorLens detects 90+ error handling anti-patterns across 6 categories:\r
\r
| Category | Examples | Severity |\r
|----------|----------|----------|\r
| **Empty Catches (EC)** | Empty catch blocks in JS/TS/Java/C#/Python, catch with only comments, catch with only pass, catch-all without logging | Critical/High |\r
| **Swallowed Exceptions (SE)** | Catch blocks that don't rethrow/log, exception variable unused, catch that returns null/undefined/false silently, ignored error callbacks | Critical/High |\r
| **Error Boundaries (EB)** | Missing React error boundaries, missing Express error middleware, missing global handlers, unhandled promise rejections, window.onerror | High/Medium |\r
| **Generic Errors (GE)** | Throwing generic Error/Exception, bare except in Python, catching Throwable in Java, catching Object in TS, overly broad error types | High/Medium |\r
| **Resource & Propagation (RP)** | Missing finally for resource cleanup, unchecked error returns in Go, missing error propagation (? in Rust), ignored Result types, missing defer/close | High/Medium |\r
| **Information Leak (IL)** | Stack traces in HTTP responses, error.message in API responses, console.error with sensitive data, verbose errors in production, raw exception details to users | High/Medium |\r
\r
## Configuration\r
\r
Users can configure ErrorLens in `~/.openclaw/openclaw.json`:\r
\r
```json\r
{\r
  "skills": {\r
    "entries": {\r
      "errorlens": {\r
        "enabled": true,\r
        "apiKey": "YOUR_LICENSE_KEY_HERE",\r
        "config": {\r
          "severityThreshold": "high",\r
          "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.test.*"],\r
          "ignoreChecks": [],\r
          "allowlistFile": ".errorlens-allowlist",\r
          "reportFormat": "markdown"\r
        }\r
      }\r
    }\r
  }\r
}\r
```\r
\r
## Important Notes\r
\r
- **Free tier** works immediately with no configuration\r
- **All scanning happens locally** -- no code is sent to external servers\r
- **License validation is offline** -- no phone-home or network calls\r
- Pattern matching only -- no AST parsing, no external dependencies beyond bash\r
- Supports scanning all file types in a single pass\r
- Git hooks use **lefthook** which must be installed (see install metadata above)\r
- Exit codes: 0 = clean (score >= 70), 1 = issues detected (for CI/CD integration)\r
\r
## Error Handling\r
\r
- If lefthook is not installed and user tries `hook install`, prompt to install it\r
- If license key is invalid or expired, show clear message with link to https://errorlens.pages.dev/renew\r
- If a file is binary, skip it automatically with no warning\r
- If no scannable files found in target, report clean scan with info message\r
- If .errorlens-allowlist is missing, skip allowlist filtering gracefully\r
\r
## When to Use ErrorLens\r
\r
The user might say things like:\r
- "Scan my code for error handling issues"\r
- "Find empty catch blocks in my project"\r
- "Check for swallowed exceptions"\r
- "Are there missing error boundaries?"\r
- "Scan for unsafe error patterns"\r
- "Find unhandled promise rejections"\r
- "Check if my error handling is correct"\r
- "Detect bare except clauses"\r
- "Run an error handling audit"\r
- "Set up pre-commit hooks for error handling"\r
- "Generate an error handling report"\r
- "Find catch blocks that don't rethrow"\r
- "Check for generic error types"\r
- "Scan for information leaks in error messages"\r
- "Audit my code for exception safety"\r
- "Find missing finally blocks"\r
- "Check for unchecked error returns in Go"\r
- "Baseline existing error handling issues"\r