152 lines
7.0 KiB
Markdown
152 lines
7.0 KiB
Markdown
---
|
|
id: PLN-0007
|
|
ticket: pbs-game-facing-asset-refs-and-call-result-discard
|
|
title: Implement DEC-0006 Ignored Values Lowering and Warning
|
|
status: done
|
|
created: 2026-03-27
|
|
completed: 2026-03-27
|
|
tags: [compiler, pbs, implementation, diagnostics, lowering, expression-statements, warnings]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Implement `DEC-0006` so ignored materialized values in PBS `expression statement` positions are always explicitly discarded during lowering and also emit a warning in v1.
|
|
|
|
## Background
|
|
|
|
`DEC-0006` locks a general language rule:
|
|
|
|
- `expression statement` forms that produce a materialized value must not silently leak backend stack discipline into source semantics;
|
|
- the compiler must lower explicit discard behavior;
|
|
- the compiler must also emit a warning in v1.
|
|
|
|
The current lowering path already lowers expression statements as plain expression evaluation.
|
|
The existing executable stack analyzer already understands `POP`, but expression-statement lowering does not yet make discard behavior explicit.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Update PBS specs and diagnostics docs for ignored-value behavior.
|
|
- Add a warning diagnostic contract for ignored materialized values.
|
|
- Implement explicit discard lowering for expression statements that leave a materialized value.
|
|
- Add frontend and lowering tests covering both the warning and the discard behavior.
|
|
|
|
### Excluded
|
|
- Suppression syntax, lint categories, or configurable severity policy.
|
|
- API-specific special cases for ignored values.
|
|
- Non-PBS frontend work.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Propagate The Rule Into PBS Specs
|
|
|
|
**What:**
|
|
Make the ignored-values rule explicit in PBS normative docs.
|
|
|
|
**How:**
|
|
Update the specs so they state:
|
|
|
|
- `expression statement` may produce a value;
|
|
- if that value is materialized and not consumed, the compiler must lower an explicit discard;
|
|
- the v1 diagnostic policy is warning.
|
|
|
|
**File(s):**
|
|
- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
|
|
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
|
|
- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
|
|
- optional compiler-wide sync if needed: `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
|
|
|
|
### Step 2 - Add A Stable Warning Diagnostic Contract
|
|
|
|
**What:**
|
|
Define the PBS diagnostic identity for ignored values.
|
|
|
|
**How:**
|
|
Add a stable warning code and wire it through the diagnostics contract so tests can assert identity, phase, severity, and attribution.
|
|
|
|
**File(s):**
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsDiagnosticsContractTest.java`
|
|
- semantics tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/`
|
|
|
|
### Step 3 - Emit Ignored-Value Warnings During Semantics
|
|
|
|
**What:**
|
|
Detect ignored materialized values at the statement-analysis boundary and emit the new warning.
|
|
|
|
**How:**
|
|
Use the existing flow/statement analyzers to identify expression statements whose resulting type is materialized rather than unit-like, and emit the warning without blocking lowering.
|
|
|
|
**File(s):**
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowBodyAnalyzer.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowStatementAnalyzer.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowExpressionAnalyzer.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/PbsSemanticsOptionalResultTest.java`
|
|
- new focused test file if needed for ignored-value warnings
|
|
|
|
### Step 4 - Lower Explicit Discard Operations
|
|
|
|
**What:**
|
|
Make expression-statement lowering explicitly discard ignored values rather than implicitly leaving them to backend behavior.
|
|
|
|
**How:**
|
|
Update executable lowering so expression statements that produce materialized values emit the appropriate discard instruction sequence, then verify stack accounting remains correct.
|
|
|
|
**File(s):**
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableBodyLowerer.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableStackAnalyzer.java`
|
|
- lowering tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/`
|
|
|
|
### Step 5 - Add Regression And Contract Coverage
|
|
|
|
**What:**
|
|
Pin both the warning and the executable discard behavior with tests.
|
|
|
|
**How:**
|
|
Add tests that cover:
|
|
|
|
- pure expression statements returning a value;
|
|
- call expressions returning a value that is ignored;
|
|
- unit-returning expression statements that must not warn;
|
|
- executable lowering shape and stack behavior after explicit discard insertion.
|
|
|
|
**File(s):**
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- Semantics tests for warning emission on ignored non-unit values.
|
|
- Negative tests ensuring unit-valued expression statements do not warn.
|
|
- Lowering tests verifying discard instruction emission and stack balance.
|
|
|
|
### Integration Tests
|
|
- End-to-end frontend compilation tests showing warning emission without turning the program into an error.
|
|
- Targeted pipeline tests proving explicit discard lowering survives later executable lowering phases.
|
|
|
|
### Manual Verification
|
|
- Inspect diagnostics and confirm ignored-value reports are warnings, not errors.
|
|
- Inspect lowered instruction streams for representative ignored-value cases and confirm explicit discard behavior.
|
|
- Re-run targeted PBS frontend and lowering test suites.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] PBS emits a stable warning diagnostic for ignored materialized values in expression statements.
|
|
- [ ] Unit-like expression statements do not emit the ignored-value warning.
|
|
- [ ] Executable lowering emits explicit discard behavior for ignored materialized values.
|
|
- [ ] Stack analysis remains valid after the discard instruction path is added.
|
|
- [ ] The rule applies generally and is not limited to one API family.
|
|
|
|
## Dependencies
|
|
|
|
- `DEC-0006-pbs-ignored-values-lowering-and-warning`
|
|
- Existing PBS flow semantics and executable lowering infrastructure
|
|
|
|
## Risks
|
|
|
|
- The current semantics/lowering split may make it easy to warn in one place but forget to lower explicit discard in another.
|
|
- If the implementation does not distinguish unit-like from materialized values carefully, it may over-warn or under-warn.
|
|
- Later severity/suppression refinements may require reshaping the diagnostics API, so the first version should keep the contract minimal and stable.
|