ShippedLarge

Add dagre-based auto-layout (top-to-bottom, left-to-right) with commands, toolbar button, selection and missing-coordinate placement

Proposed by Jonathan Miller 1 month agoFunding opened 1 month agoFunded 1 month agoShipped 1 month ago
Acceptance · round 1
Shipped
CINo checks
Automated reviewPass with concerns

This delivers a clean, pure dagre-based layout module with both required modes, a thorough unit test suite covering every listed layout criterion, three commands, a palette button, placement of missing coordinates on open through the undoable edit path, and full README documentation. Selection-subset layout is correctly skipped because the editor has no multi-selection, though the engine supports it. The main gaps are that no CI ran and the new integration tests were never executed. There is also mild scope creep (optional width/height) and a possible fixture-mutation issue in the integration tests.

Acceptance criteria · 12 of 14 met
  • YESLayout unit tests: no overlaps for 10 or more nodes in both modes`layout.test.ts` 'produces no overlapping nodes for a 12-node diagram' runs for each mode in `LAYOUT_MODES`.
  • YESOn an acyclic graph, target y > source y (top-to-bottom) and target x > source x (left-to-right)The 'orders every connector from source to target along the layout axis' test checks both modes on `bigDag`.
  • YESNode count, ids, labels, connectors and metadata are unchanged; input is not mutatedThe 'keeps ids, labels, types, sizes, connectors and metadata unchanged' test compares a snapshot of the input and uses `stripPositions`.
  • YESAll resulting positions are at least 0`assertNonNegative` runs in several tests, plus a test that clamps a negative origin.
  • YESCycles and disconnected components do not throwA test covers cycles, mutual edges, a self-loop, an isolated node and an edge to a missing node in both modes.
  • YESSubset layout changes only the selected nodes and keeps the original bounding-box top-leftThe 'lays out only the selected subset, anchored at its original top-left' test checks unselected nodes stay put and the top-left is preserved.
  • YESPartial missing-coordinate layout leaves positioned nodes unchanged and has no overlapsThe 'places only the missing nodes below the positioned ones' test runs per mode, asserting a and b are unchanged and there are no overlaps.
  • YESA test or fixture shows a JSON diagram with no x/y gets non-overlapping positions on loadA unit test parses 10 coordinate-less nodes and calls `placeUnpositioned`; the `unpositioned.diagram.json` fixture and an integration test cover opening the file, but that integration test was not run.
  • YESThe three commands are in `contributes.commands` and registered on activation`package.json` adds the three commands with commandPalette `when` clauses, and `extension.ts` registers them via `AUTO_LAYOUT_COMMANDS`.
  • YESA webview toolbar button triggers the default layoutThe `#auto-layout` button in the palette posts `{type:'autoLayout'}`, which the host handles with `DEFAULT_LAYOUT_MODE`; a webview unit test covers the click.
  • PARTIALAfter layout and save, the JSON has the new positions and reload causes no re-layoutA unit test round-trips through `serializeDiagram`/`parseDiagramWithPlacement` with no unpositioned nodes; the integration tests checking save and reopen were not executed.
  • YES`dagre` is in dependencies and bundled`package.json` dependencies includes `dagre ^0.8.5`; the esbuild bundling is claimed in the PR, but the build config is not shown in the diff.
  • UNCLEARExisting tests and build passNo CI ran; the builder reports unit tests, lint and build pass locally, with integration tests unrun.
  • YESREADME documents modes, commands, toolbar button and AI workflowThe new 'Auto layout' and 'AI workflow' sections cover all four, and note that selection is skipped because multi-selection does not exist.
Concerns
  • No CI ran on this commit, and the new VS Code integration tests were never executed (the sandbox had no network). The command registration, placement on open, undo/redo and save/reload are verified only by code reading and by the pure unit tests.
  • The integration tests save layouts into `test-fixtures/workspace/unpositioned.diagram.json` and `sample.diagram.json`. Unless the harness copies the workspace fresh for each run, a second run will fail the `unpositioned.length === 6` assertion, and the sample fixture is left permanently re-laid-out.
  • Scope creep: `width`/`height` are now optional in the parser, which loosens validation. It is reasonable and documented, but it was not requested; the spec says no schema changes beyond position values.
  • If the user undoes the automatic placement on open, the previously unpositioned nodes revert to placeholder (0,0) coordinates, which then serialize as real positions on save. The nodes stack at the origin and are no longer treated as missing on reload.
  • Groups/containers (scope item 6) are not mentioned anywhere. The model appears to have no container concept, so skipping it is likely correct, but the visible diff does not note this.
CI details
No CI checks ran on this commit.

BackersAccepted
1 accept · 0 rebuild · 0 not voted · quorum 1 of 1
MaintainerMerge

Accepted by the backers and merged by the maintainer.

Ballots · 1
AcceptJonathan Miller

Automated review cost $0.18, counted as builder cost.

Feature: Automatic Diagram Layout

Motivation

Large or AI-generated diagrams are hard to read when nodes are placed by hand or have no coordinates. Auto-layout arranges nodes and connectors predictably, so AI workflows can create structure without calculating x/y positions.

Scope

  1. Layout engine module (pure, reusable). Add a module, for example src/layout/, that has no vscode imports and is testable in plain Node. It takes the diagram model (nodes with sizes, connectors), a mode and an optional subset of node ids. It returns new positions only and never mutates its input.
    • Required modes: top-to-bottom and left-to-right, both hierarchical.
    • tree and force are optional follow-ups. They are not required and should not be added unless trivial.
    • Use dagre as a new runtime dependency. Switch to elkjs only if dagre cannot meet the required behavior, and explain why in the PR.
    • Cycles and disconnected components must not throw.
    • The API should be generic enough that a future CLI or MCP tool can call it directly.
  2. VS Code commands, contributed in package.json and registered in the extension:
    • Diagrammer: Auto Layout uses the default mode, top-to-bottom.
    • Diagrammer: Auto Layout Top to Bottom.
    • Diagrammer: Auto Layout Left to Right.
    • Each command applies to the active Diagrammer editor. The commands are the AI-facing entry point. No separate CLI or LM tool is in scope.
  3. Toolbar action. Add a button in the diagram webview toolbar that applies the default layout. A mode dropdown is optional.
  4. Selection. If the editor already supports multi-selection:
    • When 2 or more nodes are selected, layout applies only to those nodes.
    • Otherwise layout applies to the whole diagram.
    • Unselected nodes keep their positions.
    • The laid-out subset is placed with its top-left at the original top-left of the subset's bounding box.
    • If multi-selection does not exist, skip this item and note it in the PR.
  5. Missing coordinates on open. When a diagram is opened and some nodes lack x/y:
    • Only those nodes are positioned, using the default mode. Nodes that already have x/y never move.
    • Assumption: if all nodes lack coordinates, lay out the whole diagram.
    • Assumption: if only some nodes lack coordinates, lay them out as a subset and place that block in free space below the bounding box of the positioned nodes, so nothing overlaps.
    • Assumption: this auto-placement is applied through the normal edit path, so the document becomes dirty and the user can save it.
    • A diagram where every node has coordinates is never re-laid out automatically.
  6. Groups/containers. If the model has containers, children must stay inside their container's bounds. If there is no such concept, skip this item.
  7. Persistence. Layout changes go through the existing edit/save path and use the existing JSON format. The change marks the document dirty and is undoable if undo exists. No schema changes beyond position values.
  8. Documentation. Update the README to cover:
    • the layout modes;
    • the commands;
    • the toolbar button;
    • the AI workflow: write nodes and connectors without coordinates, then open the file or run Diagrammer: Auto Layout.

Acceptance Criteria

  • Unit tests for the layout module, run without VS Code:
    • For a diagram with 10 or more nodes, no two node bounding boxes overlap after top-to-bottom and after left-to-right.
    • In top-to-bottom on an acyclic graph, every connector's target y is greater than its source y. In left-to-right, the same holds for x.
    • Node count, ids, labels, connector source/target pairs and metadata are unchanged by layout.
    • All resulting positions are at least 0.
    • Graphs with cycles and graphs with disconnected components lay out without throwing.
    • Subset layout changes only the selected nodes' positions, and the subset's top-left equals its original bounding-box top-left.
    • Partial missing-coordinate layout leaves positioned nodes unchanged and produces no overlaps.
  • A test or fixture shows that a JSON diagram with no x/y values gets non-overlapping positions on load.
  • The three commands are in package.json contributes.commands and are registered in the extension activation code.
  • A webview toolbar button triggers the default layout.
  • After layout and save, the JSON contains the new positions, and reloading yields the same positions without a further automatic layout.
  • dagre is added to package.json dependencies and is included in the packaged or bundled extension.
  • The existing tests and build pass.
  • The README documents the modes, the commands, the toolbar button and the AI workflow.

Out of Scope

  • Tree and force-directed modes (optional follow-ups).
  • A CLI, MCP or language-model tool integration.
  • Connector-crossing optimization beyond what dagre provides.
  • Orthogonal or CAD-style edge routing.
  • 3D layouts, collaborative layout and animated transitions.
  • New diagram schema fields.

No comments yet.