CodeFlow Mapper

A VS Code extension that statically analyzes a Python codebase (FastAPI first; Flask, Django/DRF, Celery and plain scripts too), finds its entry points, traces function calls across files, and renders an interactive flowchart of how the application executes.

Project code is never imported or executed. Python files are only parsed with the standard-library ast module by a bundled read-only script.

Features

Analysis

• Framework detection from dependencies, imports and real FastAPI() / Flask() / APIRouter() / Blueprint() / Celery() objects.
• Entry points: FastAPI apps (including app factories), routers and include_router prefixes, which give full paths like /api/v1/users/signup. Also route decorators, add_api_route, middleware, exception handlers, lifespan / on_event, Flask blueprints, Django ROOT_URLCONF → include() → views/CBVs/DRF routers, Celery tasks, if __name__ == "__main__", uvicorn.run("app.main:app"), and pyproject console scripts.
• Cross-file call resolution: imports (absolute, relative, re-exports, star imports), classes, inheritance, self.attr types from constructors, parameter/return annotations, Annotated[..., Depends()] type aliases, context managers, nested functions.
• Relationship types: calls, instantiates, depends (FastAPI DI), callback (add_task, submit, Thread(target=…), Celery .delay), decorates, includes, registers, handles, lifespan.
• Honest confidence levels: direct, framework, inferred (e.g. getattr(obj, "literal"), a unique method name on an untyped receiver) and unresolved (dynamic calls). Imports alone never create execution edges.
• Database, HTTP, queue, cache, storage and AI SDK calls are classified as leaf nodes (SQLAlchemy, SQLModel, Mongo, Redis, httpx, requests, boto3, OpenAI and others).
• Recursion and circular imports terminate safely and are marked as back edges.

Visualization (React + React Flow webview, follows your VS Code theme)

• Overview: routing tree plus package layers and external systems.
• Execution Flow: from the app or any endpoint, with depth control and lazy +N expansion.
• Function Explorer: callers and callees of any function.
• Explore Function Internals: control flow inside a function (sequential calls, if/elif/else yes/no branches, loops with back edges, try/except/finally, with, match, return/raise). Call steps can be drilled into progressively, with a breadcrumb trail.
• Impact analysis: everything upstream and downstream of a function, plus the affected endpoints.
• Details panel with signature, docstring, highlighted source, incoming/outgoing calls with line numbers, depth stats, and a button to open the file in the editor. Double-click any node to jump to the exact file and line.
• Search, filters (node kind, relationship kind, confidence, file/directory text), legend and minimap.
• Bottom panel with logs, unresolved calls, warnings and indexing status.
• Export to PNG, SVG, Mermaid, JSON (view or full graph) and Markdown architecture docs.

VS Code integration

• CodeFlow activity bar with Entry Points and Modules trees.
• CodeLens above every function: N callers · M calls | internals | impact.
• Status bar summary.
• Incremental re-analysis on save: only changed files are re-parsed, and only their importers and callers are re-resolved.
• gzip analysis cache per workspace, parallel parsing workers, cancellable progress, and a UI that stays responsive.
• Workspace Trust: in Restricted Mode, interpreters chosen by the workspace are never run and AI is disabled.

Optional AI (off by default)

• "Explain function", "Explain execution path" and architecture summaries using Anthropic or any OpenAI-compatible endpoint (OpenAI, Azure, Ollama, LM Studio, vLLM).
• Nothing is sent without a confirmation dialog that lists exactly which files and lines leave your machine. codeflow.ai.includeGlobs limits which sources may ever be sent. API keys are stored in VS Code Secret Storage.

Commands

Requirements

• VS Code 1.85+
• Python 3.8+ on PATH, or set codeflow.pythonPath. The Python extension's selected interpreter is used when available. It is only used to run the bundled read-only parser. Code using syntax newer than your interpreter (e.g. Python 3.14 except A, B:) is handled by a line-preserving compatibility rewrite; anything else is reported in the Warnings tab.
• Node.js 18+ and npm, only to build from source.

Install

From the packaged file

code --install-extension codeflow-mapper-0.1.0.vsix

Or use VS Code → Extensions → … → Install from VSIX….

Build from source

npm install
npm --prefix webview-ui install
npm run build          # webview (Vite) + extension (esbuild)
npm run package        # → codeflow-mapper-0.1.0.vsix

Run / debug in VS Code

1. Open this folder in VS Code.
2. Run npm install && npm --prefix webview-ui install && npm run build.
3. Press F5 (Run Extension). A new Extension Development Host window opens.
4. Open a FastAPI project in that window, then run CodeFlow: Analyze Workspace.

For iterative work, run npm run watch:ext, and rebuild the UI with npm run build:ui after changing webview-ui/.

Headless CLI

node dist/cli.js path/to/project --markdown ARCHITECTURE.md --mermaid flow.mmd --json graph.json

Browser harness (UI without VS Code)

npm run build:harness && node dist/harness.js test-fixtures/invoice_app 5173
# open http://localhost:5173

This runs the real analysis engine and controller behind the real webview bundle.

Tests

npm test

The suite covers the acceptance cases: FastAPI entry points and full paths, cross-file calls, nested internals, conditionals, recursion/circular imports, exact source locations, and a synthetic 1,500-file repository. It also covers the Flask and Django fixtures, incremental updates, the cache and exports. If CFM_REAL_REPO points at a checkout of fastapi/full-stack-fastapi-template/backend, the suite analyzes it too.

Settings

Directories always ignored: .venv, venv, node_modules, __pycache__, .git, dist, build, .next, site-packages and tool caches.

Architecture

python/codeflow_extract.py        read-only AST extractor (NDJSON per file; defs, calls, flow, decorators, DI)
src/
  extension.ts                    commands, tree views, CodeLens, watcher, status bar, AI, trust handling
  parsers/pythonParser.ts         interpreter discovery, parallel extractor workers, cancellation
  analyzer/
    projectScanner.ts             walk + .gitignore + exclusions + manifests
    moduleIndex.ts                file ↔ dotted module mapping (flat, src/, monorepo, namespace pkgs)
    symbolResolver.ts             abstract values: names, imports, attrs, MRO, annotations, returns
    callGraphBuilder.ts           nodes + call/instantiate/depends/callback/decorates edges, diagnostics
    entryPointDetector.ts         FastAPI/Starlette/Flask/Django/DRF/Celery/scripts + full route paths
    controlFlowAnalyzer.ts        per-function CFG for "Explore Function Internals"
    frameworkDetector.ts          framework summary
    externalCatalog.ts            DB/HTTP/queue/cache/storage/AI library classification
    analysisEngine.ts             orchestration, cache, incremental updates, queries
  graph/                          CodeGraph, traversals (overview/execution/explorer/impact), exporters
  webview/                        panel host + host-agnostic FlowController (message protocol)
  shared/model.ts                 graph + message types shared with the UI
  ai/                             provider-independent LLM access + prompt builder with disclosure
webview-ui/                       React + @xyflow/react + dagre UI
scripts/harness.ts                browser harness
test/ , test-fixtures/            vitest suite + FastAPI, Flask and Django fixture apps

The data flow is: scan → parse (Python, parallel, cached) → module index → symbol resolution → call graph → framework layer → views. On save, only changed files are re-parsed, and only their importers and callers are re-resolved.

Known limitations

• Static analysis only. Dynamic dispatch (getattr with computed names, registries in dicts, plugin loading, monkey-patching) is shown as unresolved or inferred, never guessed as certain.
• Types are inferred from annotations, constructors and simple assignments. Untyped parameters limit resolution (DB/HTTP receivers are still classified heuristically, marked as inferred).
• JavaScript/TypeScript/Node/Express analysis is not implemented yet. package.json projects are detected and reported only.
• Django include() with inline lists loses the outer prefix. Class-based view dispatch is approximated by HTTP-method handlers.
• Absolute imports are resolved relative to the importer's ancestor directories and common source roots, not your runtime sys.path.
• AI output is generated from static facts. Treat it as an explanation, not ground truth.

Next milestones

1. JavaScript/TypeScript via the TypeScript compiler API (Express/Nest entry points).
2. Type inference from Pydantic / dataclass fields and simple data-flow across assignments.
3. Graph diff between git revisions ("what did this PR change in the flow?").
4. Streaming AI responses and natural-language graph queries.
5. Persisted layouts, pinned nodes and shareable views.

License

MIT