\r \r

CacheLint -- Caching Anti-Pattern Analyzer\r

\r CacheLint scans codebases for application-level caching anti-patterns: Redis/Memcached misuse, missing cache invalidation after writes, TTL problems, cache stampede risks, architecture issues, and security hygiene gaps. It uses regex-based pattern matching against 90 caching-specific patterns across 6 categories, lefthook for git hook integration, and produces markdown reports with actionable remediation guidance. 100% local. Zero telemetry.\r \r Note: CacheLint focuses on application-level caching (Redis calls, Memcached operations, local cache usage, invalidation logic, TTL management). It does NOT analyze HTTP cache headers.\r \r

Commands\r

\r

Free Tier (No license required)\r

\r

cachelint scan [file|directory]\r

One-shot caching quality scan of files or directories.\r \r How to execute:\r

bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [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 30 caching patterns against each file (free tier limit)\r
4. Calculates a caching quality score (0-100) per file and overall\r
5. Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (\x3C60)\r
6. Outputs findings with: file, line number, check ID, severity, description, recommendation\r
7. Exit code 0 if score >= 70, exit code 1 if caching quality is poor\r
8. Free tier limited to first 30 patterns (CI + TE categories)\r
\r
**Example usage scenarios:**\r
- "Scan my code for caching issues" -> runs `cachelint scan .`\r
- "Check this file for cache anti-patterns" -> runs `cachelint scan src/cache-service.ts`\r
- "Find missing cache invalidation" -> runs `cachelint scan src/`\r
- "Audit cache TTL settings" -> runs `cachelint scan .`\r
- "Check for Redis misuse" -> runs `cachelint scan .`\r
\r
### Pro Tier ($19/user/month -- requires CACHELINT_LICENSE_KEY)\r
\r
#### `cachelint scan --tier pro [file|directory]`\r
Extended scan with 60 patterns covering invalidation, TTL, stampede, and Redis misuse.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [target] --tier pro\r
```\r
\r
**What it does:**\r
1. Validates Pro+ license\r
2. Runs 60 caching patterns (CI, TE, CS, RM categories)\r
3. Detects cache stampede risks and Redis anti-patterns\r
4. Identifies KEYS * usage, missing pipelines, unbounded lists\r
5. Full category breakdown reporting\r
\r
#### `cachelint scan --format json [directory]`\r
Generate JSON output for CI/CD integration.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format json\r
```\r
\r
#### `cachelint scan --format html [directory]`\r
Generate HTML report for browser viewing.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format html\r
```\r
\r
#### `cachelint scan --category CS [directory]`\r
Filter scan to a specific check category (CI, TE, CS, RM, CA, SH).\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --category CS\r
```\r
\r
### Team Tier ($39/user/month -- requires CACHELINT_LICENSE_KEY with team tier)\r
\r
#### `cachelint scan --tier team [directory]`\r
Full scan with all 90 patterns across all 6 categories including architecture and security.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --tier team\r
```\r
\r
**What it does:**\r
1. Validates Team+ license\r
2. Runs all 90 patterns across 6 categories\r
3. Includes cache architecture checks (N+1 gets, mixed strategies, no abstraction)\r
4. Includes security & hygiene (PII in keys, missing TLS, no encryption)\r
5. Full category breakdown with per-file results\r
\r
#### `cachelint scan --verbose [directory]`\r
Verbose output showing every matched line and pattern details.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --verbose\r
```\r
\r
#### `cachelint status`\r
Show license and configuration information.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" status\r
```\r
\r
## Check Categories\r
\r
CacheLint detects 90 caching anti-patterns across 6 categories:\r
\r
| Category | Code | Patterns | Description | Severity Range |\r
|----------|------|----------|-------------|----------------|\r
| **Cache Invalidation** | CI | 15 | Missing invalidation after writes, stale data, wrong write ordering | medium -- critical |\r
| **TTL & Expiry** | TE | 15 | Missing TTL, infinite cache, no jitter, hardcoded magic numbers | low -- high |\r
| **Cache Stampede** | CS | 15 | No lock on miss, thundering herd, missing singleflight, no stale-while-revalidate | low -- critical |\r
| **Redis/Store Misuse** | RM | 15 | KEYS *, FLUSHALL, no pipeline, missing pooling, synchronous calls | low -- critical |\r
| **Cache Architecture** | CA | 15 | N+1 gets, no abstraction, mixed strategies, no error fallback | low -- high |\r
| **Security & Hygiene** | SH | 15 | PII in keys, no TLS, missing encryption, no monitoring, key injection | low -- critical |\r
\r
## Tier-Based Pattern Access\r
\r
| Tier | Patterns | Categories |\r
|------|----------|------------|\r
| **Free** | 30 | CI, TE |\r
| **Pro** | 60 | CI, TE, CS, RM |\r
| **Team** | 90 | CI, TE, CS, RM, CA, SH |\r
| **Enterprise** | 90 | CI, TE, CS, RM, CA, SH + priority support |\r
\r
## Scoring\r
\r
CacheLint uses a deductive scoring system starting at 100 (perfect):\r
\r
| Severity | Point Deduction | Description |\r
|----------|-----------------|-------------|\r
| **Critical** | -25 per finding | Severe risk (stampede, KEYS *, FLUSHALL, wrong write order) |\r
| **High** | -15 per finding | Significant problem (missing invalidation, no TTL, N+1 gets) |\r
| **Medium** | -8 per finding | Moderate concern (no jitter, missing pooling, mixed strategies) |\r
| **Low** | -3 per finding | Informational / best practice suggestion |\r
\r
### Grading Scale\r
\r
| Grade | Score Range | Meaning |\r
|-------|-------------|---------|\r
| **A** | 90-100 | Excellent caching quality |\r
| **B** | 80-89 | Good caching with minor issues |\r
| **C** | 70-79 | Acceptable but needs improvement |\r
| **D** | 60-69 | Poor caching quality |\r
| **F** | Below 60 | Critical caching problems |\r
\r
- **Pass threshold:** 70 (Grade C or better)\r
- Exit code 0 = pass (score >= 70)\r
- Exit code 1 = fail (score \x3C 70)\r
\r
## Configuration\r
\r
Users can configure CacheLint in `~/.openclaw/openclaw.json`:\r
\r
```json\r
{\r
  "skills": {\r
    "entries": {\r
      "cachelint": {\r
        "enabled": true,\r
        "apiKey": "YOUR_LICENSE_KEY_HERE",\r
        "config": {\r
          "severityThreshold": "medium",\r
          "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.test.*"],\r
          "ignoreChecks": [],\r
          "reportFormat": "text"\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 = pass (score >= 70), 1 = fail (for CI/CD integration)\r
- Output formats: text (default), json, html\r
\r
## Error Handling\r
\r
- If lefthook is not installed and user tries hooks, prompt to install it\r
- If license key is invalid or expired, show clear message with link to https://cachelint.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 an invalid category is specified with --category, show available categories\r
\r
## When to Use CacheLint\r
\r
The user might say things like:\r
- "Scan my code for caching issues"\r
- "Check my cache invalidation logic"\r
- "Find missing TTL on cache entries"\r
- "Detect cache stampede risks"\r
- "Are there any Redis anti-patterns?"\r
- "Check for KEYS * usage in production code"\r
- "Audit my caching architecture"\r
- "Find security issues in cache usage"\r
- "Check for PII in cache keys"\r
- "Scan for missing cache invalidation"\r
- "Run a caching quality audit"\r
- "Generate a cache health report"\r
- "Check if my Redis calls use pipelines"\r
- "Find N+1 cache get patterns"\r
- "Check my code for cache stampede vulnerabilities"\r