PBS autocomplete parameter names for stdlib and method calls
This commit is contained in:
+100
@@ -0,0 +1,100 @@
|
||||
---
|
||||
id: PLN-0078
|
||||
ticket: pbs-autocomplete-parameter-names
|
||||
title: Specify PBS callable parameter identity in the semantic model
|
||||
status: open
|
||||
created: 2026-05-08
|
||||
ref_decisions: [DEC-0036]
|
||||
tags: [compiler-pbs, studio, lsp, autocomplete, signature-help, stdlib]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0036` makes callable parameter names normative semantic metadata. Before implementation, the PBS and compiler specs need a clear contract for callable parameter identity so code changes do not invent a narrower interpretation.
|
||||
|
||||
This plan is the specification and conformance planning slice. It does not implement Java code. It defines the target semantic shape, public API compatibility rule, and test expectations that downstream plans must satisfy.
|
||||
|
||||
## Objective
|
||||
|
||||
Update normative documentation so every PBS user-visible callable has a canonical semantic parameter list with stable names, order, type when known, and origin. Define that generated ordinal placeholders such as `arg0` are internal only and must not appear in user-facing editor/LSP surfaces.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on accepted decision `DEC-0036`.
|
||||
- Must precede `PLN-0079` and `PLN-0080` because those plans implement and consume the contract defined here.
|
||||
- Related but not blocked by `DSC-0036`; parameter documentation can attach prose later, but docs do not own structural names.
|
||||
|
||||
## Scope
|
||||
|
||||
- Update PBS static semantics and stdlib/SDK specs to define canonical callable parameter identity.
|
||||
- Update compiler conformance/spec-to-test documentation to require `argN` leak prevention.
|
||||
- Update LSP/editor assistance roadmap/spec text if a current spec surface exists for completion, hover, or signature help.
|
||||
- Record that stdlib and host-backed parameter names are public API surface.
|
||||
- Define the minimum semantic parameter record:
|
||||
- name;
|
||||
- order;
|
||||
- type when known;
|
||||
- origin/source sufficient for implementation and diagnostics.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No Java/Kotlin implementation changes.
|
||||
- No VS Code extension changes.
|
||||
- No authored parameter prose documentation design.
|
||||
- No optional/default/rest parameter design unless an existing PBS callable already exposes that shape.
|
||||
- No editor-only rename map.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Update PBS static semantic documentation:
|
||||
- Target: `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`.
|
||||
- Add a section for resolved callable parameter identity.
|
||||
- State that every user-visible callable symbol MUST expose canonical parameter names through the compiler semantic model.
|
||||
- State that generated ordinal placeholders MUST NOT be treated as public parameter names.
|
||||
|
||||
2. Update stdlib/SDK resolution documentation:
|
||||
- Target: `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`.
|
||||
- Add the requirement that stdlib and SDK/host-backed callable definitions carry stable public parameter names.
|
||||
- State that parameter renames are API compatibility-sensitive.
|
||||
|
||||
3. Update host-backed and intrinsic documentation:
|
||||
- Targets:
|
||||
- `docs/specs/compiler-languages/pbs/6. VM-owned vs Host-backed.md`
|
||||
- `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- Clarify that visible host-backed and intrinsic callables must be projected into the same semantic callable parameter shape.
|
||||
|
||||
4. Update compiler conformance documentation:
|
||||
- Target: `docs/specs/compiler/13. Conformance Test Specification.md`.
|
||||
- Add conformance expectations for semantic callable parameter preservation and LSP/editor `argN` leak prevention.
|
||||
|
||||
5. Update roadmap/spec references for LSP if still current:
|
||||
- Targets:
|
||||
- `docs/roadmaps/lsp/LSP - base PRs.md`
|
||||
- `docs/roadmaps/lsp/LSP - roadmap remain.md`
|
||||
- Add a short reference that editor assistance consumes compiler semantic parameter names.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Specs explicitly state the compiler semantic model is the canonical owner of parameter names.
|
||||
- Specs explicitly cover user-authored PBS, stdlib, builtins, host-backed APIs, and visible intrinsics.
|
||||
- Specs explicitly ban generated ordinal placeholders from user-facing editor/LSP output.
|
||||
- Specs state stdlib and host-backed parameter names are public API compatibility surface.
|
||||
- The plan leaves no permission for an editor-only rename map as the canonical solution.
|
||||
|
||||
## Tests
|
||||
|
||||
- Run `discussion validate`.
|
||||
- If spec conformance tests exist for docs links or matrices, run the relevant Gradle test target.
|
||||
- Manual review gate: confirm every MUST from `DEC-0036` is represented in the updated specs.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/6. VM-owned vs Host-backed.md`
|
||||
- `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `docs/specs/compiler/13. Conformance Test Specification.md`
|
||||
- `docs/roadmaps/lsp/LSP - base PRs.md`
|
||||
- `docs/roadmaps/lsp/LSP - roadmap remain.md`
|
||||
+114
@@ -0,0 +1,114 @@
|
||||
---
|
||||
id: PLN-0079
|
||||
ticket: pbs-autocomplete-parameter-names
|
||||
title: Project canonical parameter names through PBS compiler callables
|
||||
status: open
|
||||
created: 2026-05-08
|
||||
ref_decisions: [DEC-0036]
|
||||
tags: [compiler-pbs, studio, lsp, autocomplete, signature-help, stdlib]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0036` requires all user-visible callables to expose canonical parameter names through the PBS compiler semantic callable model. This plan implements that compiler-side projection.
|
||||
|
||||
The immediate pain is visible in stdlib/editor assistance, but the implementation target is all callable symbols: user-authored PBS functions and methods, stdlib callables, builtins, host-backed APIs, and visible compiler intrinsics.
|
||||
|
||||
## Objective
|
||||
|
||||
Add or complete compiler semantic callable parameter metadata so every user-visible callable carries canonical parameter names, order, type when known, and origin. Ensure generated names such as `arg0` remain internal and are represented as missing/incomplete metadata rather than public names.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on accepted decision `DEC-0036`.
|
||||
- Should follow `PLN-0078` so implementation matches the updated spec wording.
|
||||
- Must complete before `PLN-0080` can fully consume semantic parameter names in LSP/editor assistance.
|
||||
|
||||
## Scope
|
||||
|
||||
- Inspect and update PBS callable semantic types and resolution paths.
|
||||
- Preserve source parameter names for user-authored PBS declarations.
|
||||
- Project stdlib resource declarations into the same callable parameter model.
|
||||
- Project host-backed, builtin, and visible intrinsic callables into the same model.
|
||||
- Add semantic/conformance tests for parameter names and `argN` leak prevention at the compiler boundary.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No LSP protocol formatting work; that belongs to `PLN-0080`.
|
||||
- No VS Code extension behavior changes.
|
||||
- No authored parameter descriptions.
|
||||
- No generated editor-side alias table.
|
||||
- No broad refactor of name resolution beyond callable parameter identity.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Locate the current semantic callable model:
|
||||
- Inspect:
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsCallableShape.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialSignature.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialResolvedSymbol.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialSupportService.java`
|
||||
- Identify where parameter lists currently lose real names or synthesize ordinal placeholders.
|
||||
|
||||
2. Preserve user-authored parameter names:
|
||||
- Inspect parser/AST sources:
|
||||
- `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/PbsDeclarationParser.java`
|
||||
- Ensure declaration parameter identifiers survive into semantic callable shapes.
|
||||
|
||||
3. Project stdlib parameter names:
|
||||
- Inspect stdlib resources:
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/**/main.pbs`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/**/mod.barrel`
|
||||
- Inspect loaders:
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/stdlib/InterfaceModuleLoader.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/stdlib/StdlibEnvironmentResolver.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContextService.java`
|
||||
- Ensure stdlib declarations expose authored parameter names through the same semantic callable model.
|
||||
|
||||
4. Project builtin, host-backed, and intrinsic parameters:
|
||||
- Inspect:
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsBuiltinLayoutResolver.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsHostAdmissionValidator.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsCallableShapeSurfaceService.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/IRVMIntrinsicRegistry.java`
|
||||
- Enrich descriptors that currently lack stable names.
|
||||
- If a descriptor genuinely lacks a real public name, represent that as incomplete metadata rather than `argN`.
|
||||
|
||||
5. Add compiler tests:
|
||||
- Extend or add tests near:
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/PbsEditorialSupportServiceTest.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/PbsSemanticsDeclarationsTest.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/stdlib/InterfaceModuleLoaderTest.java`
|
||||
- Assert user-authored and stdlib callables expose real parameter names.
|
||||
- Assert public semantic callable output does not contain `arg0`, `arg1`, or equivalent generated ordinal placeholders.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Every semantic callable exposed to editor assistance has a structured parameter list with names, order, type when known, and origin.
|
||||
- User-authored PBS functions preserve declared parameter names.
|
||||
- Stdlib declarations expose stable authored parameter names.
|
||||
- Builtin, host-backed, and visible intrinsic callables either expose real names or report missing metadata without fabricating public `argN` names.
|
||||
- Compiler tests fail if public semantic callable metadata leaks `argN`.
|
||||
- No editor/LSP-only rename map is introduced.
|
||||
|
||||
## Tests
|
||||
|
||||
- `./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test` if the Gradle path is valid in the current build.
|
||||
- If module targeting differs, run the nearest available PBS frontend test task from `./gradlew projects`.
|
||||
- Run focused tests for:
|
||||
- `PbsEditorialSupportServiceTest`
|
||||
- `PbsSemanticsDeclarationsTest`
|
||||
- `InterfaceModuleLoaderTest`
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsCallableShape.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialSignature.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialResolvedSymbol.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsEditorialSupportService.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/stdlib/InterfaceModuleLoader.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContextService.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/**`
|
||||
- PBS frontend semantic and stdlib tests.
|
||||
+112
@@ -0,0 +1,112 @@
|
||||
---
|
||||
id: PLN-0080
|
||||
ticket: pbs-autocomplete-parameter-names
|
||||
title: Propagate semantic parameter names to PBS LSP editor assistance
|
||||
status: open
|
||||
created: 2026-05-08
|
||||
ref_decisions: [DEC-0036]
|
||||
tags: [compiler-pbs, studio, lsp, autocomplete, signature-help, stdlib]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0036` requires completion, signature help, and hover to consume callable parameter names from the compiler semantic model and prevents generated ordinal placeholders from reaching user-facing editor/LSP output.
|
||||
|
||||
This plan implements the LSP/editor consumption slice after compiler semantic callable metadata exists.
|
||||
|
||||
## Objective
|
||||
|
||||
Propagate canonical semantic parameter names into PBS completion, signature help, hover, and VS Code-facing protocol mapping. Add tests proving `arg0`, `arg1`, and equivalent generated placeholders do not leak through user-facing LSP/editor surfaces.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on accepted decision `DEC-0036`.
|
||||
- Should follow `PLN-0078` for spec contract alignment.
|
||||
- Requires `PLN-0079` or equivalent compiler semantic metadata before final acceptance.
|
||||
|
||||
## Scope
|
||||
|
||||
- Update PBS editorial support outputs consumed by the LSP bridge.
|
||||
- Update LSP baseline messages/mappers if the protocol shape needs richer parameter metadata.
|
||||
- Update completion item construction to use semantic parameter names in labels/details/snippets.
|
||||
- Update signature help to display semantic parameter names and types.
|
||||
- Update hover signatures to use the same parameter identity.
|
||||
- Update VS Code extension only if it formats snippets or signatures locally.
|
||||
- Add LSP/protocol tests that reject `argN` leakage.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No compiler semantic model implementation; that belongs to `PLN-0079`.
|
||||
- No authored parameter prose documentation.
|
||||
- No final design for optional/default/rest parameter UI unless already surfaced by compiler metadata.
|
||||
- No UI-only guesswork for missing names.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Identify current LSP/editor assistance boundary:
|
||||
- Inspect:
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/LanguageServiceBridge.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineCompletionItem.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineSignature.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineSignatureHelp.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineHover.java`
|
||||
- Map which fields currently carry callable signatures and parameters.
|
||||
|
||||
2. Consume semantic parameter names from compiler outputs:
|
||||
- Update bridge/mapping code so completion/signature/hover surfaces use parameter names from PBS semantic callable metadata.
|
||||
- Do not generate display names from method names, types, docs, or local maps.
|
||||
- Treat missing semantic names as incomplete metadata and apply a non-misleading fallback UI that does not show `argN`.
|
||||
|
||||
3. Update protocol mapping:
|
||||
- Inspect:
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping/Lsp4jProtocolMessageMapper.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping/ProtocolMessageMapper.java`
|
||||
- Ensure LSP4J completion/signature/hover conversion preserves semantic parameter names.
|
||||
- Ensure snippet placeholders, if emitted, use canonical parameter names.
|
||||
|
||||
4. Update VS Code extension if required:
|
||||
- Inspect:
|
||||
- `tools/vscode-extension/src/extension.ts`
|
||||
- If the extension formats call snippets or signatures locally, remove any generated ordinal placeholders and consume protocol-provided semantic names.
|
||||
|
||||
5. Add LSP/editor tests:
|
||||
- Extend:
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridgeTest.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/services/protocol/PrometeuTextDocumentServiceTest.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/services/protocol/PrometeuLanguageServerTest.java`
|
||||
- Assert completion labels/details/snippets do not contain `arg0` or `arg1`.
|
||||
- Assert signature help parameter labels use semantic names.
|
||||
- Assert hover callable signatures use the same semantic names.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Completion surfaces use canonical semantic parameter names and do not leak `argN`.
|
||||
- Signature help surfaces use canonical semantic parameter names and do not leak `argN`.
|
||||
- Hover callable signatures use canonical semantic parameter names and do not leak `argN`.
|
||||
- The same callable uses the same parameter names across completion, signature help, and hover.
|
||||
- Missing parameter metadata is represented without fabricating public ordinal names.
|
||||
- VS Code extension behavior remains compatible with protocol outputs.
|
||||
|
||||
## Tests
|
||||
|
||||
- Run focused LSP tests:
|
||||
- `CompilerLanguageServiceBridgeTest`
|
||||
- `PrometeuTextDocumentServiceTest`
|
||||
- `PrometeuLanguageServerTest`
|
||||
- Run the LSP Gradle test task for `prometeu-lsp-v1` if available.
|
||||
- Run VS Code extension tests/build if the extension code changes:
|
||||
- `npm test` or `npm run compile` in `tools/vscode-extension`, depending on available scripts.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler/CompilerLanguageServiceBridge.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/LanguageServiceBridge.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineCompletionItem.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineSignature.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineSignatureHelp.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/BaselineHover.java`
|
||||
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping/Lsp4jProtocolMessageMapper.java`
|
||||
- `tools/vscode-extension/src/extension.ts` if local formatting is present.
|
||||
- LSP protocol and bridge tests.
|
||||
Reference in New Issue
Block a user