diff --git a/docs/pbs/pull-requests/INDEX.md b/docs/pbs/pull-requests/INDEX.md index 3f94e83b..17511670 100644 --- a/docs/pbs/pull-requests/INDEX.md +++ b/docs/pbs/pull-requests/INDEX.md @@ -17,3 +17,15 @@ Este indice organiza uma sequencia de PRs atomicas para levar `frontends/pbs` ao 13. `PR-011-pbs-gate-u-conformance-fixtures.md` Cada documento e auto contido e inclui: `Briefing`, `Target`, `Method`, `Acceptance Criteria` e `Tests`. + +## Non-Conformance Remediation PRs + +14. `PR-012-pbs-byte-offset-spans.md` +15. `PR-013-pbs-import-unresolved-diagnostics.md` +16. `PR-014-pbs-switch-wildcard-rules.md` +17. `PR-015-pbs-this-self-context-validation.md` +18. `PR-016-pbs-assignment-target-and-field-access-semantics.md` +19. `PR-017-pbs-const-evaluation-and-dependency-rules.md` +20. `PR-018-pbs-result-flow-ok-err-handle-rules.md` +21. `PR-019-pbs-non-unit-fallthrough-diagnostics.md` +22. `PR-020-pbs-lowering-admission-gates.md` diff --git a/docs/pbs/pull-requests/PR-012-pbs-byte-offset-spans.md b/docs/pbs/pull-requests/PR-012-pbs-byte-offset-spans.md new file mode 100644 index 00000000..071071bf --- /dev/null +++ b/docs/pbs/pull-requests/PR-012-pbs-byte-offset-spans.md @@ -0,0 +1,45 @@ +# PR-012 - PBS Lexer Byte-Offset Spans + +## Briefing + +Lexer spans are currently tracked as Java `String` character indices. The PBS syntax spec requires stable byte offsets. This PR aligns token/span attribution with byte offsets and keeps diagnostics deterministic. + +## Motivation + +Without byte offsets, diagnostics and downstream attribution diverge on non-ASCII sources, violating the lexical contract. + +## Target + +- `prometeu-frontend-pbs` lexer and span attribution behavior. +- Diagnostics and AST attribution consumers that depend on lexer spans. + +## Scope + +- Convert lexer position accounting to UTF-8 byte offsets. +- Preserve existing tokenization semantics. +- Keep parser/semantics APIs unchanged. + +## Method + +- Introduce byte-accurate cursor accounting in lexer scanning. +- Emit token start/end using byte offsets. +- Validate compatibility with parser and diagnostics sinks. +- Add regression fixtures with non-ASCII source content. + +## Acceptance Criteria + +- All emitted tokens include UTF-8 byte offsets. +- Diagnostics from lexer/parser over non-ASCII sources point to correct byte spans. +- Existing ASCII tests remain green. +- New non-ASCII span tests are added and deterministic. + +## Tests + +- Extend lexer tests with UTF-8 multibyte identifiers/strings. +- Add parser span-attribution tests over multibyte source. +- Run full `prometeu-frontend-pbs` test suite. + +## Non-Goals + +- Changing token classes or grammar. +- Changing message wording policy. diff --git a/docs/pbs/pull-requests/PR-013-pbs-import-unresolved-diagnostics.md b/docs/pbs/pull-requests/PR-013-pbs-import-unresolved-diagnostics.md new file mode 100644 index 00000000..b865b986 --- /dev/null +++ b/docs/pbs/pull-requests/PR-013-pbs-import-unresolved-diagnostics.md @@ -0,0 +1,44 @@ +# PR-013 - PBS Unresolved Import Diagnostics + +## Briefing + +Import resolution currently ignores missing target modules in frontend linking validation. This PR enforces deterministic diagnostics for unresolved module imports and unresolved imported symbols. + +## Motivation + +Silent import misses break the diagnostics contract and defer user-actionable errors. + +## Target + +- Module import validation in `PbsModuleVisibilityValidator`. +- Linking diagnostic coverage for import failures. + +## Scope + +- Emit errors for missing target module references. +- Keep existing public-symbol checks. +- Preserve deterministic, source-first attribution. + +## Method + +- Extend import validation to detect absent target modules. +- Report diagnostics on the importing site. +- Keep related-span behavior where applicable. + +## Acceptance Criteria + +- Importing a non-existent module always emits deterministic linking/import diagnostic. +- Importing a non-public symbol still emits existing diagnostic. +- Diagnostic attribution points to import site. +- No silent pass for unresolved imports remains. + +## Tests + +- Add tests for missing module import. +- Add tests for missing symbol import in existing module. +- Verify phase and diagnostic code stability. + +## Non-Goals + +- Full manifest/dependency resolver redesign. +- Loader/runtime capability checks. diff --git a/docs/pbs/pull-requests/PR-014-pbs-switch-wildcard-rules.md b/docs/pbs/pull-requests/PR-014-pbs-switch-wildcard-rules.md new file mode 100644 index 00000000..f98a716b --- /dev/null +++ b/docs/pbs/pull-requests/PR-014-pbs-switch-wildcard-rules.md @@ -0,0 +1,42 @@ +# PR-014 - PBS Switch Wildcard Rule Enforcement + +## Briefing + +Switch semantics do not currently enforce all wildcard constraints. This PR enforces: at most one wildcard arm, and rejection of mixed `default` and `_` in the same switch. + +## Motivation + +Wildcard ambiguity weakens deterministic static semantics and conformance. + +## Target + +- Switch expression semantic validation in flow analyzer. +- Required static diagnostics for wildcard rule violations. + +## Scope + +- Enforce wildcard-count and wildcard-mixing rules. +- Preserve existing selector/type compatibility checks. + +## Method + +- Track wildcard token form used per switch arm. +- Emit diagnostics for duplicate wildcard and mixed wildcard spellings. +- Keep existing exhaustiveness behavior. + +## Acceptance Criteria + +- Two wildcard arms are rejected deterministically. +- `default` + `_` in one switch is rejected deterministically. +- Existing duplicate-pattern logic for non-wildcards remains unchanged. + +## Tests + +- Add tests for duplicate wildcard arms. +- Add tests for mixed `default`/`_` arms. +- Run semantic control-flow suite. + +## Non-Goals + +- New switch syntax. +- Runtime switch lowering changes. diff --git a/docs/pbs/pull-requests/PR-015-pbs-this-self-context-validation.md b/docs/pbs/pull-requests/PR-015-pbs-this-self-context-validation.md new file mode 100644 index 00000000..ade295a0 --- /dev/null +++ b/docs/pbs/pull-requests/PR-015-pbs-this-self-context-validation.md @@ -0,0 +1,43 @@ +# PR-015 - PBS this/Self Context Validation + +## Briefing + +The frontend accepts `this` and `Self` outside allowed contexts without required diagnostics. This PR adds explicit static checks for invalid usage. + +## Motivation + +Context-free acceptance of `this`/`Self` is non-conformant and creates type ambiguity. + +## Target + +- `this` expression analysis. +- `Self` type-surface analysis in declarations. +- Error catalog and deterministic diagnostics. + +## Scope + +- Reject `this` outside struct method, service method, and ctor bodies. +- Reject `Self` outside struct/service method declarations and ctors. + +## Method + +- Add callable-context metadata into flow/type validation. +- Emit dedicated diagnostics for invalid `this` and invalid `Self` usage. +- Keep valid owner contexts unchanged. + +## Acceptance Criteria + +- Invalid `this` usage emits deterministic static diagnostic. +- Invalid `Self` usage emits deterministic static diagnostic. +- Valid struct/service/ctor contexts remain accepted. + +## Tests + +- Add positive tests for valid `this`/`Self` contexts. +- Add negative tests for top-level functions and unrelated declarations. +- Run declaration + flow semantic suites. + +## Non-Goals + +- Introducing new receiver features. +- Altering `Self` syntax. diff --git a/docs/pbs/pull-requests/PR-016-pbs-assignment-target-and-field-access-semantics.md b/docs/pbs/pull-requests/PR-016-pbs-assignment-target-and-field-access-semantics.md new file mode 100644 index 00000000..f6095def --- /dev/null +++ b/docs/pbs/pull-requests/PR-016-pbs-assignment-target-and-field-access-semantics.md @@ -0,0 +1,44 @@ +# PR-016 - PBS Assignment Target and Field Access Semantics + +## Briefing + +Assignment validation currently does not enforce target existence, assignability, mutability, or write-access constraints. This PR closes those gaps. + +## Motivation + +Unchecked assignment targets allow invalid programs through static semantics. + +## Target + +- Assignment statement semantic analysis. +- Struct field read/write access validation (`private`, `pub`, `pub mut`). + +## Scope + +- Resolve LValue path against known symbols. +- Validate assignment compatibility and write permissions. +- Emit deterministic diagnostics for invalid target/write access. + +## Method + +- Add LValue resolver in flow semantic analyzer. +- Use struct metadata (`isPublic`, `isMutable`) for access checks. +- Distinguish read-access and write-access diagnostics. + +## Acceptance Criteria + +- Missing assignment target is rejected deterministically. +- Writes to private fields from invalid contexts are rejected. +- Writes to non-`pub mut` external fields are rejected. +- Type mismatch in assignment is reported deterministically. + +## Tests + +- Add assignment tests for local, field, and nested member targets. +- Add negative access tests (`pub` read-only vs `pub mut`). +- Add type-mismatch assignment tests. + +## Non-Goals + +- New mutation syntax. +- Runtime memory model changes. diff --git a/docs/pbs/pull-requests/PR-017-pbs-const-evaluation-and-dependency-rules.md b/docs/pbs/pull-requests/PR-017-pbs-const-evaluation-and-dependency-rules.md new file mode 100644 index 00000000..acd4e4de --- /dev/null +++ b/docs/pbs/pull-requests/PR-017-pbs-const-evaluation-and-dependency-rules.md @@ -0,0 +1,45 @@ +# PR-017 - PBS Const Evaluation and Dependency Rules + +## Briefing + +`declare const` validation only checks explicit type and initializer presence. This PR implements constant-expression legality, dependency ordering, cycle detection, and initializer type compatibility. + +## Motivation + +Const declarations are part of static semantics and must be deterministic across files. + +## Target + +- Const semantic validation layer. +- Diagnostic coverage for constant expression failures. + +## Scope + +- Enforce allowed constant-expression subset. +- Resolve const dependencies module-wide, independent of source-file order. +- Reject cycles and unresolved const references. +- Validate initializer type compatibility with declared const type. + +## Method + +- Build const dependency graph from top-level declarations. +- Evaluate in topological order. +- Emit stable diagnostics for disallowed forms and graph failures. + +## Acceptance Criteria + +- Non-constant initializer forms are rejected deterministically. +- Cross-file const references resolve independent of source order. +- Cycles are rejected deterministically. +- Incompatible const initializer types are rejected. + +## Tests + +- Add const-expression positive/negative fixtures. +- Add cross-file dependency and cycle tests. +- Add type-compatibility tests. + +## Non-Goals + +- General compile-time function execution. +- Runtime const materialization strategy changes. diff --git a/docs/pbs/pull-requests/PR-018-pbs-result-flow-ok-err-handle-rules.md b/docs/pbs/pull-requests/PR-018-pbs-result-flow-ok-err-handle-rules.md new file mode 100644 index 00000000..92e33d7c --- /dev/null +++ b/docs/pbs/pull-requests/PR-018-pbs-result-flow-ok-err-handle-rules.md @@ -0,0 +1,44 @@ +# PR-018 - PBS Result Flow (ok/err/handle) Rule Enforcement + +## Briefing + +Result-flow rules are only partially enforced. This PR enforces allowed positions for `ok/err`, error-label validation, and `handle` arm terminal form requirements. + +## Motivation + +Result-flow constructs are normative control-flow surfaces and must not behave as unconstrained expressions. + +## Target + +- `ok(...)` and `err(...)` validation in return-flow contexts. +- `handle` semantic validation, including terminal form of block arms. + +## Scope + +- Restrict `ok/err` to allowed result-flow positions. +- Validate `err(E.case)` against declared error type. +- In `handle` block arms, enforce terminal `ok(payload)` or `err(E2.case)`. + +## Method + +- Add expression-use/context flags for result-flow forms. +- Add dedicated diagnostics for invalid placement and invalid error labels. +- Add terminal-check pass for handle block arms. + +## Acceptance Criteria + +- `ok/err` outside allowed positions are rejected deterministically. +- `return ok/err` validates declared `result` contract. +- `handle` block arms violating terminal rules are rejected deterministically. +- Existing propagate (`!`) and handle exhaustiveness checks remain stable. + +## Tests + +- Add positive and negative fixtures for `return ok/err`. +- Add invalid-position tests for `ok/err` as ordinary expression. +- Add `handle` arm terminal-form tests. + +## Non-Goals + +- New result syntax. +- Runtime trap policy changes. diff --git a/docs/pbs/pull-requests/PR-019-pbs-non-unit-fallthrough-diagnostics.md b/docs/pbs/pull-requests/PR-019-pbs-non-unit-fallthrough-diagnostics.md new file mode 100644 index 00000000..79ef8882 --- /dev/null +++ b/docs/pbs/pull-requests/PR-019-pbs-non-unit-fallthrough-diagnostics.md @@ -0,0 +1,42 @@ +# PR-019 - PBS Non-Unit Fallthrough Diagnostics + +## Briefing + +The frontend does not currently reject fallthrough of plain non-unit functions and `result` functions at end-of-body paths. This PR adds control-flow completion checks. + +## Motivation + +Return-surface obligations are normative and must be statically enforced. + +## Target + +- Callable body completion validation for function/method/ctor contexts. + +## Scope + +- Reject plain non-unit callable bodies that may complete without explicit return. +- Reject `result` callable bodies that may complete without explicit return. +- Preserve existing unit and optional fallthrough behavior. + +## Method + +- Add path-completion analysis over statement/block graph. +- Integrate with existing flow body analyzer. +- Emit deterministic diagnostics with stable code/phase. + +## Acceptance Criteria + +- Possible fallthrough on plain non-unit callable is rejected. +- Possible fallthrough on `result` callable is rejected. +- `void` and `optional` callable fallthrough behavior remains valid. + +## Tests + +- Add positive/negative control-flow completion fixtures. +- Cover nested `if`/`switch`/loop interactions. +- Run full flow semantics suite. + +## Non-Goals + +- Dataflow-based optimization. +- Runtime control-flow instrumentation. diff --git a/docs/pbs/pull-requests/PR-020-pbs-lowering-admission-gates.md b/docs/pbs/pull-requests/PR-020-pbs-lowering-admission-gates.md new file mode 100644 index 00000000..93f7bb11 --- /dev/null +++ b/docs/pbs/pull-requests/PR-020-pbs-lowering-admission-gates.md @@ -0,0 +1,43 @@ +# PR-020 - PBS Lowering Admission Gates + +## Briefing + +Lowering currently proceeds even when syntax/static/linking diagnostics contain errors. This PR introduces explicit admission gates so invalid programs are rejected before IR lowering. + +## Motivation + +Lowering must not convert required rejections into accepted lowered artifacts. + +## Target + +- `PbsFrontendCompiler` and `PBSFrontendPhaseService` lowering flow. +- Frontend-to-IR admission policy. + +## Scope + +- Block IR emission for source units with fatal diagnostics. +- Preserve deterministic diagnostics already emitted by previous phases. +- Keep successful paths unchanged. + +## Method + +- Introduce phase gate checks before `lowerFunctions` / file merge. +- Ensure failed units are excluded from emitted IR. +- Keep build issue adaptation behavior stable. + +## Acceptance Criteria + +- Files/modules with syntax/static/linking errors are not lowered. +- No invalid callable appears in IR output after failed admission. +- Valid files continue lowering unchanged. + +## Tests + +- Add tests proving failed parse/semantic/linking input does not emit IR functions. +- Add tests proving clean input still emits expected IR. +- Run frontend phase service and compiler suites. + +## Non-Goals + +- Redefining diagnostics severity policy. +- Introducing partial lowering recovery strategy.