cleanup
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.54% (17430/28323)
* Branch Coverage: 52.41% (6739/12858)
* Lines of Code: 28323
* Cyclomatic Complexity: 11353
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 611
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.54% (17430/28323)
* Branch Coverage: 52.41% (6739/12858)
* Lines of Code: 28323
* Cyclomatic Complexity: 11353
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 611
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
This commit is contained in:
-63
@@ -1,63 +0,0 @@
|
||||
---
|
||||
id: PLN-0092
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Specify PBS Doc attribute and markdown text block syntax
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Update the PBS normative specs so `DEC-0039` is reflected before code changes begin. This plan is the specification gate for the `[Doc(markdown = """...""")]` feature.
|
||||
|
||||
## Objective
|
||||
|
||||
Define the syntax, static semantics, AST shape, diagnostics, and stdlib documentation policy for compiler-owned PBS symbol documentation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Requires accepted decision `DEC-0039`.
|
||||
- Must be completed before parser, semantic, LSP, and stdlib implementation plans are accepted as complete.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add `[Doc(markdown = """...""")]` to the PBS attribute surface.
|
||||
- Define triple-quoted documentation text blocks as documentation-only payloads, not runtime strings.
|
||||
- Define documentable named API declarations and explicitly exclude parameters.
|
||||
- Define normalization, duplicate handling, invalid shape diagnostics, and non-runtime lowering rules.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Implement lexer, parser, semantics, or LSP code.
|
||||
- Define general multiline runtime strings.
|
||||
- Define VSCode rendering details beyond the compiler/LSP ownership boundary.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Update `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md` with the canonical `[Doc(markdown = """...""")]` syntax, allowed declaration sites, attribute ordering rule, and text block delimiter rules.
|
||||
2. Update `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md` with reserved `Doc` validation, duplicate rejection, parameter exclusion, empty normalized payload rejection, and non-documentable target diagnostics.
|
||||
3. Update `docs/specs/compiler-languages/pbs/11. AST Specification.md` with an AST representation for documentation attributes and documentation text block payloads.
|
||||
4. Update `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` with required diagnostic categories for unterminated text block, invalid `Doc` shape, duplicate `Doc`, empty payload, and invalid target.
|
||||
5. Update `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md` with the rule that stdlib, SDK, and interface modules use the same authored `Doc` surface.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Specs define all normative rules from `DEC-0039` without deferring syntax or semantics to implementation judgment.
|
||||
- The specs explicitly state that `"""..."""` is documentation-only for this feature.
|
||||
- The specs explicitly state that parameters never receive `[Doc]` in v1.
|
||||
- The specs identify propagation boundaries: compiler resolves, LSP transports, editor renders.
|
||||
|
||||
## Tests
|
||||
|
||||
- Run any existing spec conformance tests that validate PBS spec references.
|
||||
- No code behavior tests are required in this plan.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/11. AST Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
-62
@@ -1,62 +0,0 @@
|
||||
---
|
||||
id: PLN-0093
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Implement PBS lexer support for documentation text blocks
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Add lexical support for triple-quoted documentation text blocks required by `[Doc(markdown = """...""")]`.
|
||||
|
||||
## Objective
|
||||
|
||||
Teach the PBS lexer to tokenize documentation text blocks without turning triple quotes into a general runtime string feature.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0092` for the normative syntax.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add a dedicated token kind for documentation text block payloads or an equivalent lexer representation.
|
||||
- Recognize `"""` open and close delimiters.
|
||||
- Preserve source text and spans for parser and diagnostics.
|
||||
- Report unterminated documentation text blocks with useful span information.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Parse or validate `[Doc]` attribute shapes.
|
||||
- Normalize indentation.
|
||||
- Lower documentation to runtime artifacts.
|
||||
- Add general multiline string expressions.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Update `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsTokenKind.java` with a documentation text block token if a distinct token is the cleanest local pattern.
|
||||
2. Update `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsLexer.java` to recognize `"""..."""` and preserve its raw lexeme and span.
|
||||
3. Ensure ordinary string scanning remains unchanged for `"..."`.
|
||||
4. Add or update lexer diagnostics in `LexErrors.java` only if existing unterminated-string diagnostics cannot accurately represent unterminated documentation text blocks.
|
||||
5. Add focused tests in `PbsLexerTest` for valid text blocks, multiline payloads, embedded single quotes/double quotes, and unterminated blocks.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- The lexer can tokenize a multiline documentation text block.
|
||||
- Unterminated documentation text blocks produce a deterministic diagnostic.
|
||||
- Ordinary string literals keep current behavior.
|
||||
- `"""..."""` is not accepted as an expression-level runtime string by this plan.
|
||||
|
||||
## Tests
|
||||
|
||||
- `./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test` or the repository-equivalent targeted compiler frontend test task.
|
||||
- Focused `PbsLexerTest` cases for documentation text blocks.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsLexer.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsTokenKind.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/LexErrors.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/lexer/PbsLexerTest.java`
|
||||
-59
@@ -1,59 +0,0 @@
|
||||
---
|
||||
id: PLN-0094
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Extend PBS attribute parser and AST for Doc markdown payloads
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Extend parsing and AST representation so `[Doc(markdown = """...""")]` can be represented structurally before semantic validation.
|
||||
|
||||
## Objective
|
||||
|
||||
Parse documentation text block attribute values and expose them in AST without accepting alternate `Doc` shapes as valid semantics.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0092`.
|
||||
- Depends on `PLN-0093` for lexer support.
|
||||
|
||||
## Scope
|
||||
|
||||
- Extend attribute values to carry documentation text block payloads.
|
||||
- Preserve raw payload and spans needed for normalization and diagnostics.
|
||||
- Keep parser recovery consistent with existing attribute parsing.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Validate whether `Doc` is allowed on a declaration.
|
||||
- Normalize the text block.
|
||||
- Attach documentation to semantic symbols.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Update `PbsAst.AttributeValue` variants in `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java` to include a documentation text block value or equivalent typed payload.
|
||||
2. Update `PbsAttributeParser` so attribute arguments can parse `markdown = """..."""`.
|
||||
3. Keep existing string, int, and bool attribute argument parsing unchanged.
|
||||
4. Ensure parser diagnostics remain syntax-level: malformed attribute structure is parse error; invalid `Doc` shape is left to semantic validation where possible.
|
||||
5. Add parser tests proving `Doc` attributes parse on top-level and nested declaration forms that already support attributes.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `[Doc(markdown = """...""")]` parses into a distinct AST value or unambiguous attribute value representation.
|
||||
- Existing attributes such as `[Init]`, `[Frame]`, `[Host(...)]`, and `[InitAllowed]` continue to parse.
|
||||
- Invalid generic attribute syntax still recovers at the same boundaries as before.
|
||||
|
||||
## Tests
|
||||
|
||||
- Targeted parser tests under `prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/parser`.
|
||||
- Existing PBS parser test suite.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsAttributeParser.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/parser/PbsParserTest.java`
|
||||
-59
@@ -1,59 +0,0 @@
|
||||
---
|
||||
id: PLN-0095
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Implement documentation text block normalization
|
||||
status: done
|
||||
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`
|
||||
-64
@@ -1,64 +0,0 @@
|
||||
---
|
||||
id: PLN-0096
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Validate Doc attribute semantics and diagnostics
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Enforce the semantic contract of `[Doc]` after syntax can represent it.
|
||||
|
||||
## Objective
|
||||
|
||||
Reject invalid `Doc` usage and produce clear diagnostics for all invalid shapes and targets required by `DEC-0039`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0092`.
|
||||
- Depends on `PLN-0094`.
|
||||
- Depends on `PLN-0095`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Reserve `Doc` as a compiler-recognized attribute.
|
||||
- Accept only `Doc(markdown = """...""")`.
|
||||
- Reject aliases, positional arguments, extra arguments, duplicate `Doc`, empty normalized payload, parameter targets, and non-documentable targets.
|
||||
- Keep duplicates as semantic errors rather than parse errors.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Attach documentation to final symbol metadata.
|
||||
- Expose documentation through LSP.
|
||||
- Author stdlib documentation.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Locate existing declaration and reserved attribute validators, including `PbsDeclarationSemanticsValidator`, `PbsDeclarationRuleValidator`, and interface-module reserved attribute checks.
|
||||
2. Add `Doc` validation in the semantic phase that already validates declaration attributes.
|
||||
3. Define allowed declaration categories according to the spec: named API declarations that can carry attributes.
|
||||
4. Add or extend `PbsSemanticsErrors` diagnostics for invalid `Doc` target, invalid shape, duplicate attribute, missing `markdown`, extra arguments, and empty payload.
|
||||
5. Add tests covering valid declaration targets and every invalid case.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Every invalid shape named by `DEC-0039` produces a semantic diagnostic.
|
||||
- Parameters never accept `[Doc]`.
|
||||
- Duplicate `[Doc]` on one declaration is rejected semantically.
|
||||
- Existing reserved attributes keep their current behavior.
|
||||
|
||||
## Tests
|
||||
|
||||
- `PbsSemanticsDeclarationsTest`
|
||||
- `PbsInterfaceModuleSemanticsTest`
|
||||
- `PbsDiagnosticsContractTest`
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationSemanticsValidator.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationRuleValidator.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java`
|
||||
- PBS semantics tests
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
id: PLN-0097
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Attach Doc metadata to PBS semantic symbols
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Once `[Doc]` is syntactically and semantically valid, attach normalized documentation to compiler-owned semantic symbol data.
|
||||
|
||||
## Objective
|
||||
|
||||
Make documentation available from resolved PBS symbols without requiring LSP or editor code to reparse source.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0095`.
|
||||
- Depends on `PLN-0096`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Introduce an internal documentation metadata model with format and text.
|
||||
- Attach normalized Markdown to documented named API symbols.
|
||||
- Preserve the distinction between documentation metadata and runtime semantics.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Render hover markdown.
|
||||
- Write stdlib documentation content.
|
||||
- Lower documentation into runtime artifacts.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a compiler-side documentation metadata model, for example `format = markdown` plus normalized `text`.
|
||||
2. Extend symbol or editorial-resolution structures so documented declarations expose this metadata.
|
||||
3. Update symbol collection/binding paths for functions, methods, structs/classes, services, hosts, builtin/stdlib declarations, and interface declarations.
|
||||
4. Ensure imported/stdlib declarations can carry the same metadata once parsed.
|
||||
5. Add compiler tests proving documentation is attached to the intended declaration and not to parameters or unrelated symbols.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Resolved symbols can expose documentation as structured metadata, not an untyped hover-only string.
|
||||
- Documentation metadata is absent for undocumented symbols.
|
||||
- Documentation does not change type checking, name resolution, or runtime behavior.
|
||||
|
||||
## Tests
|
||||
|
||||
- Focused PBS semantic/editorial support tests.
|
||||
- Existing name resolution and declaration tests to catch regressions.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics`
|
||||
- `PbsEditorialResolvedSymbol`
|
||||
- `PbsEditorialSupportService`
|
||||
- Symbol/declaration binding code touched by documented declaration categories
|
||||
-60
@@ -1,60 +0,0 @@
|
||||
---
|
||||
id: PLN-0098
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Expose Doc metadata through PBS editorial and LSP surfaces
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Transport compiler-resolved documentation through the existing PBS editorial and LSP message boundaries.
|
||||
|
||||
## Objective
|
||||
|
||||
Expose normalized Markdown documentation to LSP consumers without source reparsing.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0097`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Extend compiler editorial result models to include documentation metadata.
|
||||
- Extend LSP baseline messages where required.
|
||||
- Keep documentation as Markdown-oriented structured data at the boundary.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Final hover layout composition.
|
||||
- VSCode automated rendering tests.
|
||||
- Runtime artifact changes.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Extend PBS editorial models such as `PbsEditorialResolvedSymbol`, completion candidates, or hover source models with optional documentation metadata.
|
||||
2. Extend LSP API records under `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/messages` only where the baseline protocol needs to carry documentation.
|
||||
3. Update bridge code under `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler` to map compiler documentation to LSP baseline messages.
|
||||
4. Preserve backward-compatible behavior for symbols without documentation.
|
||||
5. Add tests proving the LSP service receives compiler-resolved documentation.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- LSP-facing code consumes compiler-resolved documentation metadata.
|
||||
- No LSP code reparses PBS source to discover `[Doc]`.
|
||||
- Existing completion, hover, and signature help behavior remains stable for undocumented code.
|
||||
|
||||
## Tests
|
||||
|
||||
- PBS editorial support tests.
|
||||
- LSP bridge tests.
|
||||
- Existing `prometeu-lsp` protocol mapping tests.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialResolvedSymbol.java`
|
||||
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/messages`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler`
|
||||
- Related LSP tests
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
id: PLN-0099
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Render Doc markdown in hover composition
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Use transported documentation metadata in hover output while preserving the compiler/LSP/editor ownership boundary.
|
||||
|
||||
## Objective
|
||||
|
||||
Compose hover Markdown from signature/kind metadata and normalized `[Doc]` documentation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0098`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add documentation content to PBS hover composition.
|
||||
- Keep Markdown rendering responsibility in the editor/client.
|
||||
- Preserve hover behavior for undocumented symbols.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Automate VSCode visual tests.
|
||||
- Define a full documentation website generator.
|
||||
- Change signature help parameter documentation behavior.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Locate the PBS hover composition path in `PbsEditorialSupportService` and LSP bridge/mapping code.
|
||||
2. Compose hover Markdown in deterministic order: signature/kind surface, documentation Markdown, then origin/type/shape metadata as currently appropriate.
|
||||
3. Avoid escaping or reflowing normalized Markdown beyond safe composition separators.
|
||||
4. Ensure undocumented symbols keep existing hover output.
|
||||
5. Add hover tests with paragraphs, lists, and code spans from `[Doc]`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Hover includes normalized authored Markdown for documented symbols.
|
||||
- Hover does not include empty documentation sections.
|
||||
- Markdown lists do not become accidental code blocks due to indentation.
|
||||
- VSCode validation remains manual for this wave.
|
||||
|
||||
## Tests
|
||||
|
||||
- PBS editorial hover tests.
|
||||
- LSP hover mapping tests that assert `MarkupKind.MARKDOWN` payloads.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `PbsEditorialSupportService`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping`
|
||||
- Hover-related tests
|
||||
-60
@@ -1,60 +0,0 @@
|
||||
---
|
||||
id: PLN-0100
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Author Doc metadata for stdlib SDK and interface declarations
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Apply the new documentation model to repository-owned PBS stdlib, SDK, and interface declarations.
|
||||
|
||||
## Objective
|
||||
|
||||
Author English `[Doc(markdown = """...""")]` documentation for stdlib/API surfaces so editor assistance has useful content.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0092`.
|
||||
- Should run after `PLN-0096` so authored docs are validated by compiler tests.
|
||||
- Benefits from `PLN-0099` for hover verification but does not require it to author source docs.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add English Markdown documentation to stdlib, SDK, and interface declarations.
|
||||
- Document parameters inside the owning declaration Markdown.
|
||||
- Keep documentation concise and API-focused.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Add `[Doc]` to parameters.
|
||||
- Generate external documentation sites.
|
||||
- Change stdlib semantics or host binding behavior.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Inventory stdlib and SDK PBS files under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib`.
|
||||
2. Add `[Doc(markdown = """...""")]` to public named API declarations that users see in completion/hover.
|
||||
3. Document parameter meaning inside callable Markdown when needed.
|
||||
4. Ensure host/interface declarations use the same `Doc` shape.
|
||||
5. Run stdlib compile and interface conformance tests.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Public stdlib/SDK declarations that are user-facing have concise English documentation.
|
||||
- No parameters receive `[Doc]`.
|
||||
- Existing stdlib behavior and host ABI bindings are unchanged.
|
||||
|
||||
## Tests
|
||||
|
||||
- `PbsGateUStdlibCompileTest`
|
||||
- `PbsGateUSdkInterfaceConformanceTest`
|
||||
- Relevant PBS frontend tests.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/**`
|
||||
- Stdlib/interface compile tests
|
||||
-58
@@ -1,58 +0,0 @@
|
||||
---
|
||||
id: PLN-0101
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Protect runtime artifacts from Doc metadata lowering
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Guard the decision that `[Doc]` is compile/editor metadata and must not be lowered into runtime artifacts by default.
|
||||
|
||||
## Objective
|
||||
|
||||
Ensure documentation metadata does not affect IR, bytecode, cartridge output, stack behavior, or runtime validation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0097`.
|
||||
- Should be validated before end-to-end conformance closure.
|
||||
|
||||
## Scope
|
||||
|
||||
- Confirm lowering ignores `Doc` metadata.
|
||||
- Add regression tests comparing runtime-facing output with and without docs where practical.
|
||||
- Protect constant pool and cartridge artifacts from documentation payload bloat.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Define a future packaging format for documentation.
|
||||
- Remove compiler/editor metadata before LSP consumption.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Inspect PBS lowering paths under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering`.
|
||||
2. Ensure documented declarations lower identically to undocumented declarations for runtime-facing IR/backend artifacts.
|
||||
3. Add golden or structural tests comparing compiled output for equivalent documented and undocumented programs.
|
||||
4. Ensure large documentation payloads do not appear in runtime constant pools unless a future decision explicitly changes that.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Runtime-facing artifacts are unchanged by adding `[Doc]`.
|
||||
- Compiler/editor metadata remains available before lowering for LSP/editor consumers.
|
||||
- Golden artifact tests or equivalent regression tests cover this boundary.
|
||||
|
||||
## Tests
|
||||
|
||||
- `PbsGoldenArtifactsTest`
|
||||
- Backend/lowering tests relevant to PBS IR output.
|
||||
- Any artifact comparison test already used by the compiler frontend.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- PBS lowering package
|
||||
- Golden artifact test resources if needed
|
||||
- Compiler backend artifact tests
|
||||
-73
@@ -1,73 +0,0 @@
|
||||
---
|
||||
id: PLN-0102
|
||||
ticket: pbs-symbol-documentation-and-hover-markdown
|
||||
title: Add end-to-end Doc documentation conformance coverage
|
||||
status: done
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0039]
|
||||
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Close the feature with end-to-end tests that prove the whole `[Doc]` contract works across compiler and LSP boundaries.
|
||||
|
||||
## Objective
|
||||
|
||||
Validate that syntax, normalization, semantics, metadata attachment, LSP exposure, hover composition, stdlib docs, and runtime exclusion all satisfy `DEC-0039`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0092` through `PLN-0101`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add integrated compiler tests for valid and invalid `[Doc]`.
|
||||
- Add LSP tests for hover documentation payloads.
|
||||
- Add conformance coverage for normalization and runtime exclusion.
|
||||
- Define a manual VSCode checklist for final visual validation.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Automate VSCode UI rendering.
|
||||
- Add new documentation syntax beyond `[Doc(markdown = """...""")]`.
|
||||
- Reopen decision scope.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Create one or more fixture PBS files using `[Doc]` on functions, methods, structs/classes when available, services, hosts, and interface declarations.
|
||||
2. Add negative fixtures for parameters, duplicate `Doc`, empty payload, missing `markdown`, extra arguments, alias names, and invalid targets.
|
||||
3. Add LSP tests proving hover transports Markdown and does not reparse source.
|
||||
4. Add runtime artifact tests proving docs do not lower.
|
||||
5. Record a short manual VSCode validation checklist covering paragraph rendering, list rendering, code spans, indentation behavior, and undocumented-symbol fallback.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- All decision rules have at least one compiler or LSP test.
|
||||
- Manual VSCode validation scope is documented but not automated.
|
||||
- The feature can be implemented without returning to the agenda or decision for missing requirements.
|
||||
|
||||
## Tests
|
||||
|
||||
- Full relevant PBS frontend test suite.
|
||||
- Relevant LSP module tests.
|
||||
- Runtime/lowering golden tests.
|
||||
- Manual VSCode checklist execution before final housekeeping.
|
||||
|
||||
## Manual VSCode Validation Checklist
|
||||
|
||||
This plan intentionally does not automate VSCode UI rendering. Before final housekeeping, validate manually that:
|
||||
|
||||
- hover renders a `Doc` paragraph below the symbol signature and kind;
|
||||
- Markdown lists render from `- item` documentation lines;
|
||||
- code spans such as `` `color` `` render as inline code;
|
||||
- normalized indentation from `[Doc(markdown = """...""")]` does not leak leading source indentation into hover;
|
||||
- undocumented symbols still show the existing hover fallback without an empty documentation block;
|
||||
- completion documentation matches the same Markdown payload used by hover.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- PBS frontend tests and fixtures
|
||||
- LSP tests and fixtures
|
||||
- Golden/runtime artifact tests
|
||||
- Optional manual validation note in the implementation PR or plan completion record
|
||||
Reference in New Issue
Block a user