ProjectScaffold for VS Code

Diagram editor for software architecture inside VS Code: modules, ports, typed interfaces and constrained links, saved as a plain *.scaffold.yaml / *.scaffold.yml / *.scaffold.json file that feeds code skeleton generators. Built-in code generation: C++ (C++98 to C++20), Python and SCA over CORBA, with executables calling each other across binaries.

• Features
• Getting started
• Working with the preview
• Dependencies and IDL files
• Code generation
• Commands
• Settings
• Keyboard shortcuts
• Limitations
• Documentation

Features

• Text and diagram side by side: edit either one, the other follows. Undo, save, hot exit and git diff stay VS Code's: the file is a regular text document.
• Linked selection: the text cursor and the diagram selection follow each other.
• Side bar with the app's Explorer and Code generation, for the file being edited.
• Two layouts: integrated (tools in the VS Code side bar) or full (every tool docked in the diagram, like the web app).
• VS Code integration: Problems panel, Outline and breadcrumbs, an output channel, the color theme.
• Multi-project architectures: projects use the types, interfaces and modules of other project files and of OMG IDL files.
• Generate Code from editable Liquid templates; hand-written code kept across generations.
• Export the diagram as PNG / SVG, the app settings as a JSON file to import elsewhere.

Getting started

1. Create a file ending with .scaffold.yaml, for example hello.scaffold.yaml:

   schemaVersion: 1
   project:
     name: Hello
   types: []
   interfaces:
     - name: Greeting
       messages:
         - name: greet
           params:
             - name: who
               type: { kind: primitive, name: string }
           returns: { kind: primitive, name: string }
   modules:
     - name: Client
       ports:
         - { name: greeting, role: out, interface: Greeting }
     - name: Server
       ports:
         - { name: greeting, role: in, interface: Greeting }
   links:
     - name: client_to_server
       from: { module: Client, port: greeting }
       to: { module: Server, port: greeting }
       constraints:
         direction: bidirectional
         ack: { required: false }
         performance: { class: normal }
         remote: { enabled: false }
   

2. Open Preview (Ctrl+K V, or the icon in the editor title): the diagram opens beside the text.

3. Add modules (Ctrl+M), drag between an out port and an in port to link them, edit types and interfaces in the side bar. Every change lands in the text.

4. Generate Code (editor title) writes a C++17 CMake project into generated/hello next to the file.

Larger examples, with dependencies, binaries and IDL files: examples/.

Working with the preview

Opening

The preview opens on the left of the text by default (projectScaffold.preview.position).

Editing

• Changes made on either side update the other. Undo in the preview undoes the diagram's changes; undo in the text, the text's.
• Selecting an entity in the side bar shows it in the diagram and the text. Opening a view or an editor from the side bar opens it in the diagram (a preview when none is open); a dependency shows in the diagram's Inspector.
• App settings (theme, link style, port style, grid, minimap…) are in the Settings panel, with the diagram's Inspector (Ctrl+,). Theme VS Code (the default) follows the VS Code color theme.

Layouts

Switch with the Full / Integrated button of the diagram's toolbar, Window › Full layout, the editor title button (Switch to Full Layout / Switch to Integrated Layout) or the setting projectScaffold.preview.layout. Every open preview follows, keeping its views; back to the integrated layout, the ProjectScaffold side bar shows. Each layout keeps its own panel arrangement.

VS Code panels

Errors block code generation; warnings do not.

Dependencies and IDL files

• Add dependency… (diagram's Insert menu, or + in the Explorer's Dependencies) lists the project files and IDL files of the workspace, several at once (Browse… for others). Their types and interfaces are used read-only, like the project's own; their modules can be placed and linked to.
• Dependencies are refreshed from the files next to the document.
• Import projects or IDL files copies their content into the project instead.
• IDL files (#include read next to the file and in its parent folders) open in VS Code's own editor.

See Dependencies and IDL files.

Code generation

Generate Code (text editor title, diagram title, explorer right-click menu, side bar) renders the project's template set into generated/<project> next to the file (projectScaffold.generate.outputDir). A preview opens for it when no diagram shows the file. Generate Code Into… picks another directory, remembered for the file. The project must have no errors.

The project picks its set in Inspector › Project › Code generation (generation.templates in the file), or with Code Templates…, which also picks a folder of templates of your own (projectScaffold.generate.templates). A template set in <output directory>/.scaffold/templates/ replaces the built-in one.

Code written inside the user sections is kept when generating again:

bool Controller::setMode(const ::common::Mode mode)
{
    // <user:method.setMode>
    return mode != ::common::Mode::Fault; // kept across generations
    // </user:method.setMode>
}

• Files changed outside their user sections are reported as conflicts, not overwritten.
• Sections with no place left (renamed method, module or port) go to <file>.orphans, never lost.
• .scaffold-gen.json in the output directory records what was generated: keep it with the code.

See Code generation.

Commands

All under ProjectScaffold: in the command palette.

Settings

Keyboard shortcuts

While a diagram has the focus, its shortcuts win over VS Code's: Ctrl+P (go to), Ctrl+Shift+P / F1 (its own command palette), Ctrl+M, Ctrl+D, Ctrl+G, Ctrl+L, Ctrl+I, Ctrl+, , Ctrl+Alt+L / H / V, Alt+Enter, F2… ? lists them all. See Keyboard shortcuts.

Limitations

• Workspace files (*.scaffold-workspace.yaml) are not opened: open project files one by one.
• IDL files are edited as text in VS Code's editor, not in the diagram.

Documentation

• File format: the language-agnostic YAML / JSON, described by schema/scaffold.schema.json. The editor section holds layout only and is ignored by generators.
• Editor: diagram, views, binaries, arrange.
• C++ and Python mapping, Links between binaries, Writing templates.
• All guides: docs/.

Build from source

scripts/build_vscode.sh
code --install-extension dist-vscode/project-scaffold-vscode-<version>.vsix

See Building.