prometeu-studio/discussion/workflow/agendas/AGD-0048-pbs-lsp-formatting.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0048	pbs-lsp-formatting	PBS LSP Formatting	open	2026-07-15			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.