implements PLN-0133
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 62.84% (18504/29445) * Branch Coverage: 53.33% (7215/13528) * Lines of Code: 29445 * Cyclomatic Complexity: 11850 #### Quality Gates Summary Output truncated.
Test / Build skipped: 15, passed: 669
Intrepid/Prometeu/Studio/pipeline/head This commit looks good

Add PBS document symbols as an AST-backed hierarchical outline of
the open .pbs file on FrontendLanguageService. Recovered syntax is
enough; unnamed InvalidDecl is omitted; barrels, imports, locals,
and compile-only frontends stay empty. Advertise documentSymbolProvider
with hierarchical DocumentSymbol.

Housekeep DSC-0041 with LSN-0070.
This commit is contained in:
2026-09-21 10:16:14 +01:00
parent 331ad752d1
commit 5d3d48e802
25 changed files with 1183 additions and 66 deletions
@@ -6,6 +6,7 @@ import p.studio.compiler.messages.FrontendPhaseContext;
import p.studio.compiler.models.FrontendSemanticToken;
import p.studio.compiler.pbs.ast.PbsAst;
import p.studio.compiler.pbs.semantics.PbsEditorialCompletionCandidate;
import p.studio.compiler.pbs.semantics.PbsEditorialDocumentSymbol;
import p.studio.compiler.pbs.semantics.PbsEditorialLocation;
import p.studio.compiler.pbs.semantics.PbsEditorialResolvedSymbol;
import p.studio.compiler.pbs.semantics.PbsEditorialSignatureHelp;
@@ -16,6 +17,7 @@ import p.studio.compiler.services.PBSFrontendPhaseService.PbsSemanticReadSurface
import p.studio.compiler.services.FrontendCompletionCandidate;
import p.studio.compiler.services.FrontendDefinitionLocation;
import p.studio.compiler.services.FrontendDocumentRequest;
import p.studio.compiler.services.FrontendDocumentSymbol;
import p.studio.compiler.services.FrontendDocumentation;
import p.studio.compiler.services.FrontendEditorialContext;
import p.studio.compiler.services.FrontendHover;
@@ -267,6 +269,18 @@ public final class PBSFrontendLanguageService implements FrontendLanguageService
return List.copyOf(mapped.values());
}
@Override
public List<FrontendDocumentSymbol> documentSymbols(
final FrontendDocumentRequest request,
final FrontendEditorialContext editorialContext) {
if (editorialContext == null || !(editorialContext.syntaxTree() instanceof PbsAst.File ast)) {
return List.of();
}
return editorialSupportService.documentSymbols(ast).stream()
.map(this::toFrontendDocumentSymbol)
.toList();
}
@Override
public List<FrontendSemanticToken> semanticTokens(final FrontendDocumentRequest request) {
return semanticTokens(request == null ? "" : request.documentText());
@@ -314,6 +328,20 @@ public final class PBSFrontendLanguageService implements FrontendLanguageService
return FrontendSymbolKind.valueOf(kind.name());
}
private FrontendDocumentSymbol toFrontendDocumentSymbol(final PbsEditorialDocumentSymbol symbol) {
final int start = toOffset(symbol.span().getStart());
final int end = toOffset(symbol.span().getEnd());
return new FrontendDocumentSymbol(
symbol.name(),
toFrontendSymbolKind(symbol.kind()),
symbol.detail(),
start,
end,
start,
end,
symbol.children().stream().map(this::toFrontendDocumentSymbol).toList());
}
private List<EditorialDocument> projectDocuments(
final FrontendDocumentRequest request,
final FrontendEditorialContext editorialContext,
@@ -0,0 +1,321 @@
package p.studio.compiler.pbs.semantics;
import p.studio.compiler.pbs.ast.PbsAst;
import p.studio.compiler.source.Span;
import p.studio.utilities.structures.ReadOnlyList;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
final class PbsAstDocumentSymbols {
private PbsAstDocumentSymbols() {
}
static List<PbsEditorialDocumentSymbol> list(final PbsAst.File ast) {
if (ast == null || ast.topDecls() == null) {
return List.of();
}
final ArrayList<PbsEditorialDocumentSymbol> symbols = new ArrayList<>();
for (final PbsAst.TopDecl topDecl : ast.topDecls()) {
symbolFor(topDecl).ifPresent(symbols::add);
}
return List.copyOf(symbols);
}
private static Optional<PbsEditorialDocumentSymbol> symbolFor(final PbsAst.TopDecl topDecl) {
if (topDecl instanceof PbsAst.FunctionDecl functionDecl) {
return callableSymbol(
functionDecl.name(),
PbsEditorialSymbolKind.FUNCTION,
functionDecl.parameters(),
functionDecl.returnKind(),
functionDecl.returnType(),
functionDecl.resultErrorType(),
functionDecl.span());
}
if (topDecl instanceof PbsAst.StructDecl structDecl) {
return structSymbol(structDecl);
}
if (topDecl instanceof PbsAst.ServiceDecl serviceDecl) {
return namedSymbol(
serviceDecl.name(),
PbsEditorialSymbolKind.SERVICE,
"",
serviceDecl.span(),
methodSymbols(serviceDecl.methods()));
}
if (topDecl instanceof PbsAst.ContractDecl contractDecl) {
return namedSymbol(
contractDecl.name(),
PbsEditorialSymbolKind.CONTRACT,
"",
contractDecl.span(),
signatureSymbols(contractDecl.signatures()));
}
if (topDecl instanceof PbsAst.HostDecl hostDecl) {
return namedSymbol(
hostDecl.name(),
PbsEditorialSymbolKind.HOST,
"",
hostDecl.span(),
signatureSymbols(hostDecl.signatures()));
}
if (topDecl instanceof PbsAst.BuiltinTypeDecl builtinTypeDecl) {
return builtinTypeSymbol(builtinTypeDecl);
}
if (topDecl instanceof PbsAst.EnumDecl enumDecl) {
return enumSymbol(enumDecl);
}
if (topDecl instanceof PbsAst.ErrorDecl errorDecl) {
return errorSymbol(errorDecl);
}
if (topDecl instanceof PbsAst.CallbackDecl callbackDecl) {
return callableSymbol(
callbackDecl.name(),
PbsEditorialSymbolKind.CALLBACK,
callbackDecl.parameters(),
callbackDecl.returnKind(),
callbackDecl.returnType(),
callbackDecl.resultErrorType(),
callbackDecl.span());
}
if (topDecl instanceof PbsAst.GlobalDecl globalDecl) {
return namedSymbol(
globalDecl.name(),
PbsEditorialSymbolKind.GLOBAL,
formatTypeRef(globalDecl.explicitType()),
globalDecl.span(),
List.of());
}
if (topDecl instanceof PbsAst.ConstDecl constDecl) {
return namedSymbol(
constDecl.name(),
PbsEditorialSymbolKind.CONST,
formatTypeRef(constDecl.explicitType()),
constDecl.span(),
List.of());
}
if (topDecl instanceof PbsAst.ImplementsDecl implementsDecl) {
return namedSymbol(
implementsDecl.contractName(),
PbsEditorialSymbolKind.CONTRACT,
implementsDecl.ownerName() == null ? "" : implementsDecl.ownerName(),
implementsDecl.span(),
methodSymbols(implementsDecl.methods()));
}
return Optional.empty();
}
private static Optional<PbsEditorialDocumentSymbol> structSymbol(final PbsAst.StructDecl structDecl) {
final ArrayList<PbsEditorialDocumentSymbol> children = new ArrayList<>();
for (final PbsAst.StructField field : structDecl.fields()) {
namedSymbol(
field.name(),
PbsEditorialSymbolKind.FIELD,
formatTypeRef(field.typeRef()),
field.span(),
List.of()).ifPresent(children::add);
}
for (final PbsAst.CtorDecl ctorDecl : structDecl.ctors()) {
namedSymbol(
ctorDecl.name(),
PbsEditorialSymbolKind.CONSTRUCTOR,
ctorDetail(ctorDecl.parameters()),
ctorDecl.span(),
List.of()).ifPresent(children::add);
}
children.addAll(methodSymbols(structDecl.methods()));
return namedSymbol(
structDecl.name(),
PbsEditorialSymbolKind.STRUCT,
"",
structDecl.span(),
children);
}
private static Optional<PbsEditorialDocumentSymbol> builtinTypeSymbol(final PbsAst.BuiltinTypeDecl builtinTypeDecl) {
final ArrayList<PbsEditorialDocumentSymbol> children = new ArrayList<>();
for (final PbsAst.BuiltinFieldDecl field : builtinTypeDecl.fields()) {
namedSymbol(
field.name(),
PbsEditorialSymbolKind.FIELD,
formatTypeRef(field.typeRef()),
field.span(),
List.of()).ifPresent(children::add);
}
children.addAll(signatureSymbols(builtinTypeDecl.signatures()));
return namedSymbol(
builtinTypeDecl.name(),
PbsEditorialSymbolKind.BUILTIN_TYPE,
"",
builtinTypeDecl.span(),
children);
}
private static Optional<PbsEditorialDocumentSymbol> enumSymbol(final PbsAst.EnumDecl enumDecl) {
final ArrayList<PbsEditorialDocumentSymbol> children = new ArrayList<>();
for (final PbsAst.EnumCase enumCase : enumDecl.cases()) {
final String detail = enumCase.explicitValue() == null ? "" : String.valueOf(enumCase.explicitValue());
namedSymbol(
enumCase.name(),
PbsEditorialSymbolKind.ENUM,
detail,
enumCase.span(),
List.of()).ifPresent(children::add);
}
return namedSymbol(
enumDecl.name(),
PbsEditorialSymbolKind.ENUM,
"",
enumDecl.span(),
children);
}
private static Optional<PbsEditorialDocumentSymbol> errorSymbol(final PbsAst.ErrorDecl errorDecl) {
final ArrayList<PbsEditorialDocumentSymbol> children = new ArrayList<>();
for (final String label : errorDecl.cases()) {
namedSymbol(
label,
PbsEditorialSymbolKind.ERROR,
"",
errorDecl.span(),
List.of()).ifPresent(children::add);
}
return namedSymbol(
errorDecl.name(),
PbsEditorialSymbolKind.ERROR,
"",
errorDecl.span(),
children);
}
private static List<PbsEditorialDocumentSymbol> methodSymbols(final ReadOnlyList<PbsAst.FunctionDecl> methods) {
if (methods == null || methods.isEmpty()) {
return List.of();
}
final ArrayList<PbsEditorialDocumentSymbol> symbols = new ArrayList<>();
for (final PbsAst.FunctionDecl method : methods) {
callableSymbol(
method.name(),
PbsEditorialSymbolKind.METHOD,
method.parameters(),
method.returnKind(),
method.returnType(),
method.resultErrorType(),
method.span()).ifPresent(symbols::add);
}
return symbols;
}
private static List<PbsEditorialDocumentSymbol> signatureSymbols(
final ReadOnlyList<PbsAst.FunctionSignature> signatures) {
if (signatures == null || signatures.isEmpty()) {
return List.of();
}
final ArrayList<PbsEditorialDocumentSymbol> symbols = new ArrayList<>();
for (final PbsAst.FunctionSignature signature : signatures) {
callableSymbol(
signature.name(),
PbsEditorialSymbolKind.METHOD,
signature.parameters(),
signature.returnKind(),
signature.returnType(),
signature.resultErrorType(),
signature.span()).ifPresent(symbols::add);
}
return symbols;
}
private static Optional<PbsEditorialDocumentSymbol> callableSymbol(
final String name,
final PbsEditorialSymbolKind kind,
final ReadOnlyList<PbsAst.Parameter> parameters,
final PbsAst.ReturnKind returnKind,
final PbsAst.TypeRef returnType,
final PbsAst.TypeRef resultErrorType,
final Span span) {
return namedSymbol(
name,
kind,
callableDetail(parameters, returnKind, returnType, resultErrorType),
span,
List.of());
}
private static Optional<PbsEditorialDocumentSymbol> namedSymbol(
final String name,
final PbsEditorialSymbolKind kind,
final String detail,
final Span span,
final List<PbsEditorialDocumentSymbol> children) {
if (name == null || name.isBlank() || span == null || span.isNone()) {
return Optional.empty();
}
return Optional.of(new PbsEditorialDocumentSymbol(name, kind, detail, span, children));
}
private static String callableDetail(
final ReadOnlyList<PbsAst.Parameter> parameters,
final PbsAst.ReturnKind returnKind,
final PbsAst.TypeRef returnType,
final PbsAst.TypeRef resultErrorType) {
return "(" + formatParameters(parameters) + ") -> " + formatReturn(returnKind, returnType, resultErrorType);
}
private static String ctorDetail(final ReadOnlyList<PbsAst.Parameter> parameters) {
return "(" + formatParameters(parameters) + ")";
}
private static String formatParameters(final ReadOnlyList<PbsAst.Parameter> parameters) {
if (parameters == null || parameters.isEmpty()) {
return "";
}
final ArrayList<String> parts = new ArrayList<>(parameters.size());
for (final PbsAst.Parameter parameter : parameters) {
parts.add(parameter.name() + ": " + formatTypeRef(parameter.typeRef()));
}
return String.join(", ", parts);
}
private static String formatReturn(
final PbsAst.ReturnKind returnKind,
final PbsAst.TypeRef returnType,
final PbsAst.TypeRef resultErrorType) {
if (returnKind == null) {
return formatTypeRef(returnType);
}
return switch (returnKind) {
case INFERRED_UNIT, EXPLICIT_UNIT -> "void";
case PLAIN -> formatTypeRef(returnType);
case RESULT -> {
final String errorType = formatTypeRef(resultErrorType);
if (returnType == null || returnType.kind() == PbsAst.TypeRefKind.UNIT) {
yield "result<" + errorType + ">";
}
yield "result<" + errorType + "> " + formatTypeRef(returnType);
}
};
}
private static String formatTypeRef(final PbsAst.TypeRef typeRef) {
if (typeRef == null) {
return "void";
}
return switch (typeRef.kind()) {
case UNIT -> typeRef.name() == null || typeRef.name().isBlank() ? "void" : typeRef.name();
case SELF -> "Self";
case SIMPLE -> typeRef.name() == null ? "void" : typeRef.name();
case OPTIONAL -> "optional " + formatTypeRef(typeRef.inner());
case GROUP -> "(" + formatTypeRef(typeRef.inner()) + ")";
case NAMED_TUPLE -> {
final ArrayList<String> fields = new ArrayList<>(typeRef.fields().size());
for (final var field : typeRef.fields()) {
fields.add(field.label() + ": " + formatTypeRef(field.typeRef()));
}
yield "(" + String.join(", ", fields) + ")";
}
case ERROR -> "unknown";
};
}
}
@@ -0,0 +1,22 @@
package p.studio.compiler.pbs.semantics;
import p.studio.compiler.source.Span;
import java.util.List;
import java.util.Objects;
public record PbsEditorialDocumentSymbol(
String name,
PbsEditorialSymbolKind kind,
String detail,
Span span,
List<PbsEditorialDocumentSymbol> children) {
public PbsEditorialDocumentSymbol {
name = Objects.requireNonNull(name, "name").trim();
kind = Objects.requireNonNull(kind, "kind");
detail = detail == null ? "" : detail;
span = Objects.requireNonNull(span, "span");
children = children == null ? List.of() : List.copyOf(children);
}
}
@@ -74,6 +74,10 @@ public final class PbsEditorialSupportService {
return context.resolveSymbolHover(token.lexeme(), tokenIndex, scopeState);
}
public List<PbsEditorialDocumentSymbol> documentSymbols(final PbsAst.File ast) {
return PbsAstDocumentSymbols.list(ast);
}
public List<PbsEditorialLocation> definition(
final String sourceText,
final PbsAst.File ast,
@@ -434,6 +434,131 @@ final class PbsEditorialSupportServiceTest {
return locations;
}
@Test
void shouldBuildAstBackedOutlineHierarchyAndKeepOverloadsAsSiblings() {
final var source = """
import { Log } from @sdk:log;
[Init]
fn init() -> void { return; }
fn helper(a: int) -> int { return a; }
fn helper(a: int, b: int) -> int { return a; }
declare struct Point(x: int, pub y: int) {
ctor make(x: int) { return; }
fn run() -> void { return; }
}
declare contract TickLike { fn tick(dt: int) -> void; }
declare service Physics { fn tick() -> void { return; } }
declare error Io { NotFound; Busy; }
declare enum Mode(Idle = 0, Run = 1);
declare callback OnClick(x: int) -> result<Io> int;
declare global STATE: int = 10;
declare const LIMIT: int = 10;
implements TickLike for Point using s { fn tick(dt: int) -> void { return; } }
fn frame() -> void {
let local = 1;
helper(local);
}
""";
final var ast = parseOrdinary(source);
final var symbols = service.documentSymbols(ast);
assertEquals(List.of(
"init",
"helper",
"helper",
"Point",
"TickLike",
"Physics",
"Io",
"Mode",
"OnClick",
"STATE",
"LIMIT",
"TickLike",
"frame"), names(symbols));
assertTrue(symbols.stream().noneMatch(symbol -> symbol.name().equals("Log") || symbol.name().equals("local")));
assertTrue(symbols.getFirst().name().equals("init"));
assertFalse(symbols.getFirst().name().contains("Init"));
assertEquals("(a: int) -> int", symbols.get(1).detail());
assertEquals("(a: int, b: int) -> int", symbols.get(2).detail());
final var point = requireNamed(symbols, "Point");
assertEquals(PbsEditorialSymbolKind.STRUCT, point.kind());
assertEquals(List.of("x", "y", "make", "run"), names(point.children()));
assertEquals(PbsEditorialSymbolKind.FIELD, point.children().getFirst().kind());
assertEquals("int", point.children().getFirst().detail());
assertEquals(PbsEditorialSymbolKind.CONSTRUCTOR, point.children().get(2).kind());
assertEquals("(x: int)", point.children().get(2).detail());
assertEquals(PbsEditorialSymbolKind.METHOD, point.children().get(3).kind());
final var contract = symbols.get(4);
assertEquals(PbsEditorialSymbolKind.CONTRACT, contract.kind());
assertEquals(List.of("tick"), names(contract.children()));
assertEquals("(dt: int) -> void", contract.children().getFirst().detail());
final var physics = requireNamed(symbols, "Physics");
assertEquals(PbsEditorialSymbolKind.SERVICE, physics.kind());
assertEquals(List.of("tick"), names(physics.children()));
final var error = requireNamed(symbols, "Io");
assertEquals(PbsEditorialSymbolKind.ERROR, error.kind());
assertEquals(List.of("NotFound", "Busy"), names(error.children()));
final var mode = requireNamed(symbols, "Mode");
assertEquals(PbsEditorialSymbolKind.ENUM, mode.kind());
assertEquals(List.of("Idle", "Run"), names(mode.children()));
assertEquals("0", mode.children().getFirst().detail());
final var callback = requireNamed(symbols, "OnClick");
assertEquals(PbsEditorialSymbolKind.CALLBACK, callback.kind());
assertEquals("(x: int) -> result<Io> int", callback.detail());
assertEquals(PbsEditorialSymbolKind.GLOBAL, requireNamed(symbols, "STATE").kind());
assertEquals("int", requireNamed(symbols, "STATE").detail());
assertEquals(PbsEditorialSymbolKind.CONST, requireNamed(symbols, "LIMIT").kind());
final var implementsSymbol = symbols.get(11);
assertEquals("TickLike", implementsSymbol.name());
assertEquals("Point", implementsSymbol.detail());
assertEquals(PbsEditorialSymbolKind.CONTRACT, implementsSymbol.kind());
assertEquals(List.of("tick"), names(implementsSymbol.children()));
}
@Test
void shouldOmitInvalidDeclarationsAndKeepNamedDeclsFromRecoveredAst() {
final var source = """
declare ;
fn ok() -> int { return 1; }
""";
final var ast = parseAllowingErrors(source);
final var symbols = service.documentSymbols(ast);
assertEquals(List.of("ok"), names(symbols));
assertEquals(PbsEditorialSymbolKind.FUNCTION, symbols.getFirst().kind());
}
@Test
void shouldOutlineHostAndBuiltinTypeDeclarationsFromInterfaceModules() {
final var source = """
declare host Gfx {
fn clear(color: int) -> void;
}
declare builtin type Color(
pub r: int
) {
fn pack() -> int;
}
""";
final var ast = parseInterface(source, new FileId(0));
final var symbols = service.documentSymbols(ast);
assertEquals(List.of("Gfx", "Color"), names(symbols));
assertEquals(PbsEditorialSymbolKind.HOST, symbols.getFirst().kind());
assertEquals(List.of("clear"), names(symbols.getFirst().children()));
assertEquals(PbsEditorialSymbolKind.BUILTIN_TYPE, symbols.get(1).kind());
assertEquals(List.of("r", "pack"), names(symbols.get(1).children()));
}
private PbsEditorialResolvedSymbol requireHover(
final String source,
final PbsAst.File ast,
@@ -455,6 +580,26 @@ final class PbsEditorialSupportServiceTest {
return ReadOnlyList.wrap(topDecls);
}
private List<String> names(final List<PbsEditorialDocumentSymbol> symbols) {
return symbols.stream().map(PbsEditorialDocumentSymbol::name).toList();
}
private PbsEditorialDocumentSymbol requireNamed(
final List<PbsEditorialDocumentSymbol> symbols,
final String name) {
return symbols.stream()
.filter(symbol -> symbol.name().equals(name))
.findFirst()
.orElseThrow(() -> new AssertionError("missing symbol: " + name + " in " + names(symbols)));
}
private PbsAst.File parseAllowingErrors(final String source) {
final var diagnostics = DiagnosticSink.empty();
final var fileId = new FileId(0);
final var tokens = PbsLexer.lex(source, fileId, diagnostics);
return PbsParser.parse(tokens, fileId, diagnostics, PbsParser.ParseMode.ORDINARY);
}
private PbsAst.File parseOrdinary(final String source) {
return parse(source, new FileId(0), PbsParser.ParseMode.ORDINARY);
}