60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
---
|
|
id: PLN-0095
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Implement documentation text block normalization
|
|
status: open
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0039]
|
|
tags: [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`
|