prometeu-studio/discussion/workflow/plans/PLN-0096-validate-doc-attribute-semantics-and-diagnostics.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0096	pbs-symbol-documentation-and-hover-markdown	Validate Doc attribute semantics and diagnostics	done	2026-07-15	DEC-0039	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