DarkCodeReader

Interactive codebase structure and execution flow visualization for VS Code. Understand any codebase at a glance — especially useful when working with AI-generated code.

Quick Start

Install from the VS Code Marketplace or install the .vsix file manually
Open any project in VS Code
Press Cmd+Shift+P (or Ctrl+Shift+P) and type DarkCodeReader: Analyze Workspace
A graph panel opens showing your file dependencies — click any file node to expand and see its functions, classes, and methods

That's it. No configuration needed.

Features

Structure Graph (Static Analysis)

Visualize how your codebase is connected without running any code.

File-first view — starts with a clean file-level dependency map
Click to expand — click any file node to reveal its functions, classes, and methods
Click to collapse — click an expanded file to hide its children again
Sticky positioning — drag nodes to arrange the graph how you want; they stay put
Double-click any node to jump directly to that code in the editor
Search and filter — find nodes by name, filter by type (files/functions/classes)
Language support — TypeScript, JavaScript, and Python

Each file node shows:

A number badge indicating how many definitions it contains
A summary (e.g. "3 fn, 1 cls") below the label
Size proportional to how much code it contains

Execution Graph (Runtime Tracing)

See what actually happens when your code runs.

Node.js tracing — uses the Chrome DevTools Protocol profiler (near-zero overhead)
Python tracing — uses sys.settrace to capture function calls in real-time
Flame chart view — horizontal bars showing call depth and relative timing
Flow view — tree layout showing the call hierarchy
Hit counts — see how many times each function was called

How to Use

Three ways to start

Method	What it does
Command Palette (`Cmd+Shift+P`)	Type "DarkCodeReader" to see all commands
Right-click a file	In the explorer or editor, right-click any `.ts`, `.js`, or `.py` file
Activity bar	Click the DarkCodeReader icon in the left sidebar

Available commands

Command	Description
`DarkCodeReader: Analyze Workspace`	Scan the entire project and show the structure graph
`DarkCodeReader: Analyze Current File`	Show just the current file and its direct dependencies
`DarkCodeReader: Start Execution Tracing`	Run a script with instrumentation
`DarkCodeReader: Stop Execution Tracing`	Stop tracing and show the execution graph
`DarkCodeReader: Show Structure Graph`	Reopen the structure graph panel
`DarkCodeReader: Show Execution Graph`	Reopen the execution graph panel

Interacting with the graph

Click a file node to expand/collapse its contents
Click a function/class/method node to see its details in the side panel
Double-click any node to open that file at the exact line in the editor
Drag nodes to reposition them — they stay where you put them
Scroll to zoom in/out
Click + drag the background to pan
Use the toolbar to search, filter by node type, zoom to fit, or toggle labels

Settings

Setting	Default	Description
`darkCodeReader.pythonPath`	`python3`	Path to your Python interpreter
`darkCodeReader.excludePatterns`	`node_modules`, `dist`, `.git`, etc.	Glob patterns to exclude from analysis
`darkCodeReader.maxFileSize`	`1048576` (1 MB)	Skip files larger than this
`darkCodeReader.maxNodes`	`500`	Maximum nodes to display

Supported Languages

Language	Static Analysis	Runtime Tracing
TypeScript	Full (imports, functions, classes, methods, call graph)	Via Node.js Inspector
JavaScript	Full (same as TypeScript)	Via Node.js Inspector
Python	Full (imports, functions, classes, methods)	Via `sys.settrace`

How It Works

Static Analysis

TypeScript/JavaScript: Uses the TypeScript Compiler API to parse your project. It reads your tsconfig.json, creates a type-checked program, and walks the AST to extract imports, function declarations, class hierarchies, and call relationships.
Python: Spawns a subprocess using Python's built-in ast module (no external dependencies). Parses each .py file to extract imports, function/class definitions, and method relationships.

Runtime Tracing

Node.js: Launches your script with --inspect and connects via the Chrome DevTools Protocol. Uses the CPU Profiler (not debugger stepping) for near-zero overhead. Captures the full call tree with hit counts.
Python: Wraps your script with sys.settrace to capture every function call and return event. Filters out standard library and site-packages to show only your code.

Development

# Clone and install
git clone https://github.com/goldwinstewart/DarkCodeReader.git
cd DarkCodeReader
npm install

# Build
npm run build

# Watch mode (rebuilds on file changes)
npm run watch

# Run in VS Code
# Press F5 to launch the Extension Development Host

# Run smoke tests
node test/smoke-test.mjs

# Package for distribution
npx @vscode/vsce package --allow-missing-repository

Project Structure

src/
  extension.ts              Main entry point
  analyzers/
    TypeScriptAnalyzer.ts   TS/JS static analysis via Compiler API
    PythonAnalyzer.ts       Python static analysis via ast module
    AnalyzerFactory.ts      Language detection and routing
  tracers/
    NodeInspectorTracer.ts  JS/TS runtime tracing via CDP
    PythonTracer.ts         Python runtime tracing via sys.settrace
    TracerFactory.ts        Language detection and routing
  graph/
    GraphBuilder.ts         Transforms analysis results into graph data
    GraphFilter.ts          Search and filter logic
  webview/
    WebviewManager.ts       Manages the VS Code webview panel
  commands/
    analyzeWorkspace.ts     Full workspace analysis command
    analyzeFile.ts          Single file analysis command
    tracing.ts              Start/stop tracing commands

webview-ui/
  src/
    main.ts                 Webview entry point and message handling
    graphs/
      StructureGraph.ts     D3.js force-directed graph for static analysis
      ExecutionGraph.ts     D3.js flame chart / flow graph for tracing
    styles/
      main.css              VS Code theme-integrated styles

License

MIT