Skip to content

USAGE.md

Latest commit

 

History

History
120 lines (87 loc) · 3.34 KB

USAGE.md

File metadata and controls

120 lines (87 loc) · 3.34 KB

Codescape User Guide

1) Installation

Prerequisites

  • VS Code ^1.74.0
  • Node.js + npm
  • Java and/or Python project/workspace with .java / .py files

Build and run from source

  1. Clone and enter repo.
  2. Install dependencies: 
    npm install
  3. Compile: 
    npm run compile
  4. Launch extension host from VS Code with F5.

2) Opening the City View

Codescape currently supports two user-visible locations:

  1. Explorer sidebar view:
  • In VS Code explorer, open Codescape City (codescape.Cityview).
  1. Editor panel view:
  • Run command Create Panel (codescape.createPanel) from command palette.
  • This opens a tab titled Codescape.

Placement options in VS Code:

  • Tab: default open behavior.
  • Split pane: drag tab or use split editor command.
  • Bottom panel: with Codescape tab focused, run View: Move Editor into Panel.

3) What the Visualization Means

  • Building = parsed Java or Python entity (ClassInfo).
  • Building height = complexity proxy (methods + fields, min 1).
  • Building color = relationship signal (intended UX) and currently implemented as stable per-class palette assignment.
  • Related classes = computed in backend (relations.ts) for incremental updates.

Important current behavior:

  • Related classes are computed and sent in PARTIAL_STATE.
  • UI currently logs related classes and updates state subsets; dedicated relationship color/highlight encoding is not finalized.

4) Controls

  • Zoom in: mouse wheel up.
  • Zoom out: mouse wheel down.
  • Zoom range: 0.3 to 3.0.
  • Pan: not implemented.
  • Rotation: not implemented.

5) Incremental Updates

Codescape watches **/*.java and **/*.py and sends partial updates:

  • File changed:

    • Re-parse file.
    • Compute changed, removed, related.
    • Broadcast PARTIAL_STATE to active webviews.

  • File deleted:

    • Remove from store.
    • Broadcast PARTIAL_STATE with removed class names.

6) Excluding Files

Create .exclude in workspace root. Each line is a glob pattern matched with minimatch.

Example:

**/generated/**
**/build/**
**/test/**

7) Commands

Contributed commands (package.json):

  • codescape.createPanel -> Create Panel
  • codescape.scan -> Codescape Scan

Runtime-registered internal commands (not contributed in package.json):

  • codescape.dumpParseStore
  • codescape.exportParseStore

8) Practical Workflow

  1. Start extension host (F5).
  2. Open a Java or Python workspace in extension host window.
  3. Open Codescape via sidebar or Create Panel command.
  4. Edit/save Java or Python files and observe updates.
  5. Use zoom wheel to inspect layout.

9) Troubleshooting

  • City view not updating:

    • Confirm the .java or .py file is not excluded by .exclude.
    • Check extension host logs for parser errors.

  • Empty view:

    • Verify workspace has Java or Python files.
    • Run codescape.scan (re-parses backend store; current implementation may still require reopening/reloading view to reflect a full-state refresh).

  • Commands missing:

    • Recompile (npm run compile) and relaunch extension host.

10) Example Workspaces

For a known-good visual smoke test, open one of these folders in the extension host:

  • examples/java-city
  • examples/python-city

Both are intentionally small so the generated city stays compact and in view with the current layout algorithm.