bQUARKz
0342df1d4e
All checks were successful
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.95% (17314/27950)
* Branch Coverage: 53.06% (6712/12651)
* Lines of Code: 27950
* Cyclomatic Complexity: 11194
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 579
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
78 lines
4.6 KiB
Markdown
78 lines
4.6 KiB
Markdown
---
|
|
id: LSN-0052
|
|
ticket: pbs-autocomplete-parameter-names
|
|
title: Canonical callable parameter names through PBS editor assistance
|
|
created: 2026-05-14
|
|
tags: [compiler-pbs, studio, lsp, autocomplete, signature-help, stdlib]
|
|
---
|
|
|
|
## Context
|
|
|
|
PBS editor assistance is compiler-backed. Completion, hover, and signature help should therefore expose the same callable shape that the compiler understands, not a parallel UI-only interpretation.
|
|
|
|
Before this discussion, some callable surfaces could reach editor assistance with synthesized labels such as `arg0` and `arg1`. Those labels made stdlib and method calls harder to use because they erased the public meaning of each argument exactly where the editor is meant to help.
|
|
|
|
`DEC-0036` made callable parameter names normative semantic metadata. `PLN-0078`, `PLN-0079`, and `PLN-0080` implemented that rule in specs, compiler semantics, and LSP regression coverage.
|
|
|
|
## Key Decisions
|
|
|
|
### Compiler semantics own parameter identity
|
|
|
|
**What:** Every user-visible PBS callable must expose a semantic parameter list with canonical name, zero-based order, type when known, and origin/source metadata.
|
|
|
|
**Why:** Completion, hover, signature help, diagnostics, and later documentation surfaces need one source of truth for callable shape. If each editor adapter invents labels independently, stdlib and host-backed API names drift from compiler truth.
|
|
|
|
**Trade-offs:** This makes stdlib and host-backed parameter names part of public API shape. Renaming them becomes compatibility-sensitive, but that cost is appropriate because these names are visible to users and tooling.
|
|
|
|
### Generated ordinal names stay internal
|
|
|
|
**What:** `arg0`, `arg1`, and equivalent ordinal placeholders must not appear in user-facing editor or LSP output.
|
|
|
|
**Why:** A generated ordinal name is not a public API name. Publishing it trains users and tests to rely on a placeholder that carries no semantic meaning.
|
|
|
|
**Trade-offs:** If a callable genuinely lacks a canonical parameter name, the boundary should represent the metadata as incomplete instead of fabricating a plausible-looking name. That can make missing metadata more visible, but it prevents false API contracts.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
The compiler-side pattern is to keep parameter identity attached to callable symbols, not only to AST declarations used by direct hover paths.
|
|
|
|
The PBS semantic support model now carries `CallableParameter` records beside callable input types. This preserves:
|
|
|
|
- authored parameter name;
|
|
- parameter order;
|
|
- resolved type view;
|
|
- source span as origin metadata.
|
|
|
|
Editor-facing formatting should then render signatures from those semantic parameters. Direct AST formatting and model-backed callable formatting should produce the same names for user-authored methods, stdlib services, host-backed declarations, and visible builtin/intrinsic method surfaces.
|
|
|
|
The LSP bridge should stay thin. It should map compiler editorial signatures into baseline completion, hover, and signature-help payloads without inventing names. The LSP4J mapper should preserve labels and parameter lists exactly as received from the baseline protocol model.
|
|
|
|
## Pitfalls
|
|
|
|
- Do not fix missing parameter names with an editor-side rename table. That creates a second source of callable truth.
|
|
- Do not treat stdlib parameter names as incidental implementation details. They are public API surface once completion and signature help expose them.
|
|
- Do not use `argN` as a harmless fallback in tests. A passing test that expects `arg0` is a regression against the semantic contract.
|
|
- Be careful when testing stdlib signatures that reference imported types. A test for parameter identity should not accidentally become a test for transitive type rendering unless that is the intended scope.
|
|
|
|
## Final Result
|
|
|
|
The implemented slice updated:
|
|
|
|
- PBS and compiler specs to define callable parameter identity and `argN` leak prevention;
|
|
- PBS compiler semantic callable symbols to preserve structured parameter metadata;
|
|
- PBS editorial formatting to render semantic names instead of synthesized ordinals;
|
|
- LSP bridge and mapper tests to prove completion, hover, and signature help preserve semantic names.
|
|
|
|
The validating commits were:
|
|
|
|
- `4e00584` implements `PLN-0078`;
|
|
- `eab763f` implements `PLN-0079`;
|
|
- `db8c514` implements `PLN-0080`.
|
|
|
|
## Takeaways
|
|
|
|
- Parameter names are structural callable metadata, not documentation prose.
|
|
- Editor assistance should consume compiler semantics rather than patching over missing names locally.
|
|
- Public stdlib and host-backed parameter renames need compatibility review.
|
|
- Missing semantic metadata is better exposed as incomplete than disguised as `arg0`.
|