vm-file-deep-analyzer

# vm-file-deep-analyzer

## When to Use This Skill

- Reverse engineering an unknown codebase and need per-file structural analysis
- Documenting classes, methods, imports, and design patterns in a source file
- Assessing change readiness of a file (coupling, cohesion, risk, recommendations)
- Generating Mermaid class diagrams and logical flow diagrams from source code
- Building a file-level inventory for change impact analysis

## Unitary Function

**ONE responsibility:** Analyze a SINGLE source file and return a structured JSON report containing all classes, methods, imports, design patterns, change-readiness assessment, and Mermaid diagrams.

## NOT RESPONSIBLE FOR

- Analyzing multiple files at once (orchestrator handles batching)
- Cross-file dependency resolution (that is flow mapping)
- Data model / ER extraction (that is `vm-data-model-extractor`)
- Generating HTML reports (that is `vm-reverse-engineering-reporter`)
- Running tests or measuring coverage
- Modifying source code

## Input

```json
{
  "file_path": "/absolute/path/to/source/file.py",
  "file_id": "F001",
  "language": "python",
  "language_hint": "python",
  "framework_context": ["django", "django-rest-framework"],
  "scan_depth": "standard",
  "repo_root": "/absolute/path/to/repo"
}
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `file_path` | Yes | Absolute path to the source file to analyze |
| `file_id` | Yes | Unique file ID from the Master Checklist |
| `language` | Yes | Detected language (from Discovery phase) |
| `language_hint` | No | Override for language detection |
| `framework_context` | No | Known frameworks for pattern-aware analysis |
| `scan_depth` | No | `quick` (classes+imports only), `standard` (full), `deep` (+ complexity metrics) |
| `repo_root` | No | Repo root for computing relative import paths |

## Output

```json
{
  "generated_by": {
    "skill": "vm-file-deep-analyzer",
    "version": "1.0.0"
  },
  "file_id": "F001",
  "file_path": "src/auth/views.py",
  "summary": "Handles user authentication endpoints including login, logout, and registration",
  "language": "python",
  "framework_usage": ["django-rest-framework"],
  "loc": 120,
  "complexity_score": "moderate",
  "file_cyclomatic_complexity": 14,
  "classes": [
    {
      "name": "LoginView",
      "type": "class",
      "base_classes": ["APIView"],
      "interfaces": [],
      "purpose": "Processes login requests and returns JWT tokens",
      "line_start": 15,
      "line_end": 58,
      "methods": [
        {
          "name": "post",
          "visibility": "public",
          "parameters": [{"name": "request", "type": "Request", "purpose": "HTTP request with credentials"}],
          "return_type": "Response",
          "purpose": "Authenticates credentials and returns JWT pair",
          "complexity": "moderate",
          "cyclomatic_complexity": 6,
          "line_start": 22,
          "line_end": 55,
          "calls_to": ["UserService.aut