prometeu-studio/discussion/workflow/plans/PLN-0095-implement-documentation-text-block-normalization.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0095	pbs-symbol-documentation-and-hover-markdown	Implement documentation text block normalization	open	2026-07-15	DEC-0039	compiler compiler-pbs studio lsp vscode editor hover documentation markdown

Briefing

Implement the normalization algorithm required before semantic validation and editor exposure.

Objective

Produce normalized Markdown text from a raw documentation text block using the rules locked by DEC-0039.

Dependencies

• Depends on PLN-0092.
• Depends on PLN-0094 for AST access to raw text block payloads.

Scope

• Strip incidental leading and trailing empty lines.
• Compute and remove common indentation from non-empty lines.
• Preserve internal line breaks and Markdown content after normalization.
• Provide a single reusable normalization implementation for parser/semantics/editorial surfaces.

Non-Goals

• Render Markdown.
• Sanitize Markdown for a specific editor.
• Reflow authored text.

Execution Method

1. Add a small normalization helper in the PBS frontend package, colocated with parser or semantic support according to local patterns.
2. Feed the helper raw documentation text block content without delimiters.
3. Normalize line endings deterministically before indentation calculation if existing source handling requires it.
4. Validate empty/whitespace-only content after normalization.
5. Add unit tests for no indentation, common indentation, blank first/last lines, mixed blank internal lines, Markdown lists, code spans, and whitespace-only payloads.

Acceptance Criteria

• Normalized output matches the spec for all required indentation cases.
• Whitespace-only content is detectable after normalization.
• The normalizer does not interpret Markdown and does not alter non-indentation content.

Tests

• New focused unit tests for the normalizer.
• Parser/semantic tests that consume normalized output through [Doc].

Affected Artifacts

• New or existing PBS frontend helper under prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs
• Corresponding tests under prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs