Add strict LSP-backed Bridge formatter with syntax-safe aborts and editor-config-aware indentation (#99)

* Initial plan

* Add LSP document formatting and safe pretty-printer API

Co-authored-by: aarne <82001+aarne@users.noreply.github.com>

* Address review feedback for formatter API and LSP handler

Co-authored-by: aarne <82001+aarne@users.noreply.github.com>

* Remove formatBridge compatibility API and switch playground/tests to strict formatter

Co-authored-by: aarne <82001+aarne@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: aarne <82001+aarne@users.noreply.github.com>

Author: Copilot

packages/bridge-parser/src/bridge-printer.ts

@@ -6,9 +6,34 @@
  * from the token stream, applying consistent formatting rules.
  */
 import type { IToken } from "chevrotain";
+import type { CstNode } from "chevrotain";
 import { BridgeLexer } from "./parser/lexer.ts";
-
-const INDENT = "  ";
+import { parseBridgeCst } from "./parser/parser.ts";
+
+const DEFAULT_FORMATTING_OPTIONS = {
+  tabSize: 2,
+  insertSpaces: true,
+} as const;
+
+export type BridgeFormattingOptions = {
+  tabSize: number;
+  insertSpaces: boolean;
+};
+
+function resolveFormattingOptions(
+  options?: Partial<BridgeFormattingOptions>,
+): BridgeFormattingOptions {
+  const rawTabSize = options?.tabSize;
+  const tabSize =
+    typeof rawTabSize === "number" && Number.isInteger(rawTabSize)
+      ? Math.max(1, rawTabSize)
+    : DEFAULT_FORMATTING_OPTIONS.tabSize;
+
+  return {
+    tabSize,
+    insertSpaces: options?.insertSpaces ?? DEFAULT_FORMATTING_OPTIONS.insertSpaces,
+  };
+}
 
 // ── Comment handling ─────────────────────────────────────────────────────────
 
@@ -142,10 +167,29 @@ function isTopLevelBlockStart(group: IToken[]): boolean {
 /**
  * Format Bridge DSL source code with consistent styling.
  *
- * @param source - The Bridge DSL source text to format
- * @returns Formatted source text, or the original if parsing fails
+ * Throws on syntax-invalid input when called with a source string.
  */
-export function formatBridge(source: string): string {
+type PrettyPrintInput = string | { source: string; cst: CstNode };
+
+export function prettyPrintToSource(
+  input: PrettyPrintInput,
+  options?: Partial<BridgeFormattingOptions>,
+): string {
+  const source = typeof input === "string" ? input : input.source;
+  if (typeof input === "string") {
+    parseBridgeCst(source);
+  }
+  return formatBridgeInternal(source, options);
+}
+
+function formatBridgeInternal(
+  source: string,
+  options?: Partial<BridgeFormattingOptions>,
+): string {
+  const formatting = resolveFormattingOptions(options);
+  const indentUnit = formatting.insertSpaces
+    ? " ".repeat(formatting.tabSize)
+    : "\t";
   const lexResult = BridgeLexer.tokenize(source);
 
   if (lexResult.errors.length > 0) {
@@ -313,7 +357,7 @@ export function formatBridge(source: string): string {
         if (lastCommentLine > 0 && commentLine > lastCommentLine + 1) {
           output.push("\n"); // Preserve blank line between comments
         }
-        output.push(INDENT.repeat(lineStartDepth) + comment.image + "\n");
+        output.push(indentUnit.repeat(lineStartDepth) + comment.image + "\n");
         lastCommentLine = commentLine;
       }
     }
@@ -371,7 +415,7 @@ export function formatBridge(source: string): string {
         );
         if (hasContentAfter && lineOutput.length > 0) {
           // Emit the line with the brace, content will continue on next iteration
-          output.push(INDENT.repeat(currentIndent) + lineOutput + "\n");
+          output.push(indentUnit.repeat(currentIndent) + lineOutput + "\n");
           lineOutput = "";
           lastType = null;
           currentIndent = depth; // Update indentation for remaining content
@@ -390,7 +434,7 @@ export function formatBridge(source: string): string {
 
         // Output anything accumulated first
         if (lineOutput.length > 0) {
-          output.push(INDENT.repeat(depth) + lineOutput + "\n");
+          output.push(indentUnit.repeat(depth) + lineOutput + "\n");
           lineOutput = "";
         }
         // Decrement depth, then emit brace at new (outer) depth
@@ -405,7 +449,7 @@ export function formatBridge(source: string): string {
         }
 
         // Emit the closing brace immediately
-        output.push(INDENT.repeat(depth) + braceOutput + "\n");
+        output.push(indentUnit.repeat(depth) + braceOutput + "\n");
         continue;
       }
 
@@ -458,7 +502,7 @@ export function formatBridge(source: string): string {
 
     // Emit the line
     if (lineOutput.length > 0) {
-      output.push(INDENT.repeat(currentIndent) + lineOutput + "\n");
+      output.push(indentUnit.repeat(currentIndent) + lineOutput + "\n");
     }
 
     lastOutputLine = originalLine;

packages/bridge-parser/src/index.ts

@@ -10,6 +10,7 @@
 export {
   parseBridgeChevrotain as parseBridge,
   parseBridgeChevrotain,
+  parseBridgeCst,
   parseBridgeDiagnostics,
   PARSER_VERSION,
 } from "./parser/index.ts";
@@ -25,7 +26,10 @@ export {
 
 // ── Formatter ───────────────────────────────────────────────────────────────
 
-export { formatBridge } from "./bridge-printer.ts";
+export {
+  prettyPrintToSource,
+  type BridgeFormattingOptions,
+} from "./bridge-printer.ts";
 
 // ── Language service ────────────────────────────────────────────────────────
 

packages/bridge-parser/src/parser/index.ts

@@ -5,6 +5,7 @@
  */
 export {
   parseBridgeChevrotain,
+  parseBridgeCst,
   parseBridgeDiagnostics,
   PARSER_VERSION,
 } from "./parser.ts";

packages/bridge-parser/src/parser/parser.ts

@@ -1240,6 +1240,23 @@ export function parseBridgeChevrotain(text: string): BridgeDocument {
   return internalParse(text);
 }
 
+export function parseBridgeCst(text: string): CstNode {
+  const lexResult = BridgeLexer.tokenize(text);
+  if (lexResult.errors.length > 0) {
+    const e = lexResult.errors[0];
+    throw new Error(`Line ${e.line}: Unexpected character "${e.message}"`);
+  }
+
+  parserInstance.input = lexResult.tokens;
+  const cst = parserInstance.program();
+  if (parserInstance.errors.length > 0) {
+    const e = parserInstance.errors[0];
+    throw new Error(e.message);
+  }
+
+  return cst;
+}
+
 // ── Diagnostic types ──────────────────────────────────────────────────────
 
 export type BridgeDiagnostic = {

packages/bridge-syntax-highlight/README.md

@@ -15,6 +15,8 @@ Full IDE support for [The Bridge](https://github.com/stackables/bridge): a decla
   - Tool hover: function name, deps, wires
   - Define hover: subgraph details
   - Const hover: name and raw value
+- **Document formatting** — format `.bridge` files through the standard `textDocument/formatting` LSP request
+- Formatter respects your local editor settings (`editor.tabSize`, `editor.insertSpaces`) and works with `editor.formatOnSave`
 - Error recovery — partial AST is built even on broken files, so diagnostics remain accurate while you're mid-edit
 
 ### Syntax Highlighting

packages/bridge-syntax-highlight/package.json

@@ -39,7 +39,12 @@
         "scopeName": "source.bridge",
         "path": "./syntaxes/bridge.tmLanguage.json"
       }
-    ]
+    ],
+    "configurationDefaults": {
+      "[bridge]": {
+        "editor.defaultFormatter": "stackables.bridge-syntax-highlight"
+      }
+    }
   },
   "scripts": {
     "prebuild": "pnpm --filter @stackables/bridge build",

packages/bridge-syntax-highlight/src/server.ts

@@ -22,9 +22,11 @@ import {
   DiagnosticSeverity,
   CompletionItemKind,
   MarkupKind,
+  Range,
+  TextEdit,
 } from "vscode-languageserver/node";
 import { TextDocument } from "vscode-languageserver-textdocument";
-import { BridgeLanguageService } from "@stackables/bridge";
+import { BridgeLanguageService, parseBridgeCst, prettyPrintToSource } from "@stackables/bridge";
 import type { CompletionKind } from "@stackables/bridge";
 
 // ── Connection & document manager ──────────────────────────────────────────
@@ -49,6 +51,7 @@ connection.onInitialize(
     capabilities: {
       textDocumentSync: TextDocumentSyncKind.Incremental,
       hoverProvider: true,
+      documentFormattingProvider: true,
       completionProvider: {
         triggerCharacters: ["."],
       },
@@ -131,6 +134,37 @@ connection.onCompletion((params) => {
   }));
 });
 
+connection.onDocumentFormatting((params) => {
+  const doc = documents.get(params.textDocument.uri);
+  if (!doc) return null;
+
+  const text = doc.getText();
+
+  try {
+    const cst = parseBridgeCst(text);
+    const formatted = prettyPrintToSource(
+      { source: text, cst },
+      {
+        tabSize: params.options.tabSize,
+        insertSpaces: params.options.insertSpaces,
+      },
+    );
+
+    const range = Range.create(
+      { line: 0, character: 0 },
+      doc.positionAt(text.length),
+    );
+
+    return [TextEdit.replace(range, formatted)];
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    connection.console.warn(
+      `Bridge formatting aborted due to syntax errors: ${message}`,
+    );
+    return null;
+  }
+});
+
 // ── Start ──────────────────────────────────────────────────────────────────
 
 documents.listen(connection);

packages/bridge/test/bridge-printer-examples.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { describe, test } from "node:test";
-import { formatBridge } from "../src/index.ts";
+import { formatSnippet } from "./formatter-test-utils.ts";
 
 /**
  * ============================================================================
@@ -19,7 +19,7 @@ tool geo from std.httpCall`;
 
 tool geo from std.httpCall
 `;
-    assert.equal(formatBridge(input), expected);
+    assert.equal(formatSnippet(input), expected);
   });
 
   test("tool with body", () => {
@@ -36,7 +36,7 @@ tool geo from std.httpCall {
   .method = GET
 }
 `;
-    assert.equal(formatBridge(input), expected);
+    assert.equal(formatSnippet(input), expected);
   });
 
   test("bridge block with assignments", () => {
@@ -56,7 +56,7 @@ bridge Query.test {
   o.value <- i.value
 }
 `;
-    assert.equal(formatBridge(input), expected);
+    assert.equal(formatSnippet(input), expected);
   });
 
   test("define block", () => {
@@ -70,7 +70,7 @@ o.x<-i.y
   o.x <- i.y
 }
 `;
-    assert.equal(formatBridge(input), expected);
+    assert.equal(formatSnippet(input), expected);
   });
 
   test("bridge with comment, tool handles, and pipes", () => {
@@ -102,7 +102,7 @@ bridge Query.greet {
   o.lower <- lc:i.name
 }
 `;
-    assert.equal(formatBridge(input), expected);
+    assert.equal(formatSnippet(input), expected);
   });
 
   test("ternary expressions preserve formatting", () => {
@@ -123,7 +123,7 @@ bridge Query.pricing {
 }
 `;
     // Should not change
-    assert.equal(formatBridge(input), input);
+    assert.equal(formatSnippet(input), input);
   });
 
   test("blank line between top-level blocks", () => {
@@ -158,14 +158,14 @@ define helper {
   with input as i
 }
 `;
-    assert.equal(formatBridge(input), expected);
+    assert.equal(formatSnippet(input), expected);
   });
 
   test("not operator preserves space", () => {
     const input = `o.requireMFA <- not i.verified
 `;
     // Should not change
-    assert.equal(formatBridge(input), input);
+    assert.equal(formatSnippet(input), input);
   });
 
   test("blank lines between comments are preserved", () => {
@@ -174,6 +174,6 @@ define helper {
 #sdasdsd
 `;
     // Should not change
-    assert.equal(formatBridge(input), input);
+    assert.equal(formatSnippet(input), input);
   });
 });