File Hotspots Scanner - CLI Documentation

The File Hotspots scanner performs lightweight complexity analysis using filesystem metadata only—never reading file contents. It identifies structural complexity that may indicate refactoring opportunities or migration challenges.

Privacy Guarantee

This scanner uses fs.stat() exclusively:

What It Reads	What It Never Reads
File names	File contents
File sizes	Source code
Directory structure	Comments or strings
File extensions	Import statements
Modification dates	Business logic

Note: For source-code-level analysis, see the Code Quality Scanner.

Metrics Collected

File Distribution

Counts files by extension across the workspace:

{
  "byExtension": {
    ".ts": 245,
    ".tsx": 89,
    ".json": 34,
    ".md": 12,
    ".css": 8
  }
}

Why it matters: Unusual distributions (e.g., more .js than .ts in a TypeScript project) may indicate incomplete migration.

Largest Files

Files ranked by byte size:

{
  "largestFiles": [
    {
      "path": "src/legacy/megaModule.ts",
      "bytes": 45230,
      "humanSize": "44.2 KB",
      "recommendation": "Consider breaking into smaller modules"
    },
    {
      "path": "src/api/handlers.ts",
      "bytes": 32100,
      "humanSize": "31.3 KB"
    }
  ]
}

Why it matters: Large files are often "god modules" that concentrate complexity and are harder to test and refactor.

Directory Depth

{
  "depth": {
    "max": 8,
    "average": 3.2,
    "deepestPath": "src/features/auth/providers/oauth/google/callbacks/"
  }
}

Why it matters: Deeply nested structures can indicate over-abstraction or unclear boundaries.

Use Cases

Refactoring Targets

Identify candidates for refactoring:

vg scan --format json | jq '.fileHotspots.largestFiles | .[0:5]'

Migration Assessment

Before major migrations, understand file distribution:

How many files need attention?
Where is complexity concentrated?
What's the overall project structure?

Code Review Prioritization

During reviews, focus on:

Files over a size threshold
Deep directory structures
Unusual file distributions

Example Output

{
  "fileHotspots": {
    "summary": {
      "totalFiles": 412,
      "totalDirectories": 67,
      "totalBytes": 2847392
    },
    "byExtension": {
      ".ts": 245,
      ".tsx": 89,
      ".json": 34,
      ".md": 22,
      ".css": 14,
      ".yml": 8
    },
    "largestFiles": [
      {
        "path": "src/legacy/bigModule.ts",
        "bytes": 45230,
        "humanSize": "44.2 KB"
      },
      {
        "path": "src/api/handlers.ts",
        "bytes": 32100,
        "humanSize": "31.3 KB"
      },
      {
        "path": "src/utils/helpers.ts",
        "bytes": 28400,
        "humanSize": "27.7 KB"
      }
    ],
    "depth": {
      "max": 8,
      "average": 3.2,
      "distribution": {
        "1-2": 45,
        "3-4": 312,
        "5-6": 48,
        "7+": 7
      }
    }
  }
}