---
id: AGD-0048
ticket: pbs-lsp-formatting
title: PBS LSP Formatting
status: open
created: 2026-07-15
resolved:
decision:
tags: [studio, lsp, vscode, compiler-pbs, editor, formatting]
---

## Pain

Domain owner: `studio/lsp`

PBS formatting is not automated, so style drifts across files, especially around attributes, services, blocks, imports, and multi-line Doc text blocks.

## Context

The LSP does not announce documentFormattingProvider. PBS has a parser and AST, but formatting must preserve documentation text block content while normalizing surrounding syntax and indentation.

## Open Questions

- [ ] Should formatting be AST-based, token-based, or hybrid to preserve comments and text blocks?
- [ ] What canonical style should PBS use for attributes, braces, imports, params, and text blocks?
- [ ] Should the first wave support full document formatting only, or also range/on-type formatting?

## Options

### Option A - Token-preserving formatter

- **Approach:** Format from tokens and trivia, preserving comments and documentation text block contents.
- **Pro:** Safer for active editing and text blocks.
- **Con:** Harder to enforce deep structural layout.
- **Maintainability:** Good if PBS formatting remains mostly syntactic.

### Option B - AST pretty-printer

- **Approach:** Reprint code from the AST using canonical style rules.
- **Pro:** Produces consistent output.
- **Con:** Risks losing comments/trivia and cannot handle malformed files well.
- **Maintainability:** Strong only after AST/trivia ownership is explicit.

## Tradeoffs

Formatting must not damage `Doc` text blocks. That makes trivia preservation a first-class requirement rather than an implementation detail.

## Recommendation

Prefer Option A or a hybrid token/AST formatter. Avoid a pure AST pretty-printer until comments/trivia are modeled.

## Discussion

Formatter decision should define canonical style before implementation.

## Resolution

Ainda em aberto.

## Next Step

Decide PBS canonical formatting rules for attributes, braces, imports, params, and text blocks.