package PBS references and expose paginated MCP reads

This commit is contained in:
2026-09-29 08:48:33 +01:00
parent 58f11a8123
commit feb57c5298
23 changed files with 738 additions and 21 deletions
@@ -1,3 +1,5 @@
import java.security.MessageDigest
plugins {
id("gradle.java-library-conventions")
}
@@ -8,3 +10,47 @@ dependencies {
implementation(project(":prometeu-compiler:prometeu-frontend-api"))
implementation(project(":prometeu-compiler:prometeu-compiler-core"))
}
// Build-time projection of owner-maintained sources; no second normative copy is edited by Studio.
val pbsSpecs = rootProject.layout.projectDirectory.dir("docs/specs/compiler-languages/pbs")
val pbsResources = layout.projectDirectory.dir("src/main/resources")
val generatePbsKnowledge by tasks.registering(Sync::class) {
from(pbsSpecs) { include("*.md"); into("pbs-knowledge/specs") }
into(layout.buildDirectory.dir("generated/pbsKnowledge"))
inputs.files(fileTree(pbsResources) { include("game/stdlib/**/*.pbs", "game/stdlib/**/*.barrel", "pbs-knowledge/examples/**") })
doLast {
val entries = mutableListOf<Map<String, Any?>>()
fun entry(id: String, title: String, kind: String, resource: String, source: File, sdk: Int? = null, target: String? = null) {
check(source.isFile) { "Missing PBS reference: $source" }
val digest = MessageDigest.getInstance("SHA-256").digest(source.readBytes())
.joinToString("") { "%02x".format(it) }
entries.add(linkedMapOf("id" to id, "title" to title, "kind" to kind,
"resource" to resource, "sha256" to digest, "sdkVersion" to sdk, "target" to target))
}
pbsSpecs.asFile.listFiles()!!.filter { it.extension == "md" }.sortedBy { it.name }.forEach { source ->
val chapter = source.name.substringBefore(". ")
val quickstart = source.name == "README.md"
entry(if (quickstart) "pbs:quickstart" else "pbs:spec:$chapter",
source.readLines().first { it.startsWith("# ") }.removePrefix("# "),
if (quickstart) "QUICKSTART" else if (chapter == "3") "SYNTAX" else "SEMANTICS",
"pbs-knowledge/specs/${source.name}", source)
}
fileTree(pbsResources) { include("game/stdlib/**/*.pbs", "game/stdlib/**/*.barrel") }.files.sorted().forEach { source ->
val path = source.relativeTo(pbsResources.asFile).invariantSeparatorsPath
val parts = path.split('/')
val sdk = parts[2].toInt()
val module = parts.drop(3).dropLast(1).joinToString(":")
entry("pbs:sdk:game:$sdk:${parts.drop(3).joinToString("/")}", "PBS SDK $sdk @$module / ${source.name}",
"SDK", path, source, sdk, "Game")
}
fileTree(pbsResources.dir("pbs-knowledge/examples/game/1")) { include("**/*") }.files.sorted().forEach { source ->
val relative = source.relativeTo(pbsResources.dir("pbs-knowledge/examples/game/1").asFile).invariantSeparatorsPath
entry("pbs:example:game:1:$relative", "PBS Game / SDK 1 example: $relative", "EXAMPLE",
"pbs-knowledge/examples/game/1/$relative", source, 1, "Game")
}
check(entries.map { it["id"] }.distinct().size == entries.size) { "Duplicate PBS reference IDs" }
destinationDir.resolve("pbs-knowledge/index.json").writeText(groovy.json.JsonOutput.prettyPrint(
groovy.json.JsonOutput.toJson(mapOf("schemaVersion" to 1, "owner" to "pbs", "references" to entries))))
}
}
sourceSets.main { resources.srcDir(generatePbsKnowledge) }
@@ -11,6 +11,8 @@ import java.util.Optional;
public final class PBSFrontendProvider implements FrontendProvider {
private final FrontendPhaseService compiler;
private final PBSFrontendLanguageService languageService;
private final p.studio.compiler.services.FrontendReferenceProvider documentation =
new p.studio.compiler.pbs.documentation.PbsDocumentation();
public PBSFrontendProvider() {
this(new PBSFrontendPhaseService(), new PBSFrontendLanguageService());
@@ -41,4 +43,9 @@ public final class PBSFrontendProvider implements FrontendProvider {
public Optional<FrontendLanguageService> languageService() {
return Optional.of(languageService);
}
@Override
public Optional<p.studio.compiler.services.FrontendReferenceProvider> documentation() {
return Optional.of(documentation);
}
}
@@ -0,0 +1,78 @@
package p.studio.compiler.pbs.documentation;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.AppMode;
import p.studio.compiler.services.FrontendReferenceProvider;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.*;
import java.io.InputStream;
import java.util.function.Function;
/** Loads only the build-generated PBS index and its packaged resources, never user-supplied paths. */
public final class PbsDocumentation implements FrontendReferenceProvider {
private record Index(int schemaVersion, String owner, List<Entry> references) {}
private record Entry(String id, String title, Kind kind, String resource, String sha256,
Integer sdkVersion, String target) {}
private record Installed(Entry entry, Reference reference) {}
private final Function<String, InputStream> resources;
private volatile List<Installed> installed;
public PbsDocumentation() { this(PbsDocumentation.class.getClassLoader()::getResourceAsStream); }
PbsDocumentation(Function<String, InputStream> resources) { this.resources = Objects.requireNonNull(resources); }
@Override public List<Reference> references(int stdlibVersion, AppMode target) {
Objects.requireNonNull(target);
return installed().stream()
.filter(item -> item.entry().sdkVersion() == null || item.entry().sdkVersion() == stdlibVersion)
.filter(item -> item.entry().target() == null || item.entry().target().equals(target.name()))
.map(Installed::reference).toList();
}
private List<Installed> installed() {
if (installed != null) return installed;
synchronized (this) {
if (installed != null) return installed;
try {
var index = new ObjectMapper().readValue(resource("pbs-knowledge/index.json"), Index.class);
if (index.schemaVersion() != 1 || !"pbs".equals(index.owner()) || index.references() == null)
throw new IOException("Invalid PBS reference index");
var entries = new ArrayList<Installed>();
var ids = new HashSet<String>();
for (var entry : index.references()) {
if (entry.id() == null || !entry.id().startsWith("pbs:") || !ids.add(entry.id())
|| entry.sdkVersion() != null && entry.sdkVersion() < 1)
throw new IOException("Invalid or duplicate PBS reference identity");
byte[] bytes = resource(entry.resource());
if (!HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(bytes)).equals(entry.sha256()))
throw new IOException("PBS reference does not match its installed index");
String content = StandardCharsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT)
.onUnmappableCharacter(CodingErrorAction.REPORT).decode(ByteBuffer.wrap(bytes)).toString();
entries.add(new Installed(entry, new Reference(entry.id(), entry.title(), entry.kind(),
entry.sdkVersion() == null ? null : entry.sdkVersion().toString(),
entry.sdkVersion() == null ? "unknown" : "installed PBS SDK major; target=" + entry.target(), content)));
}
installed = List.copyOf(entries);
return installed;
} catch (Exception failure) {
throw new IllegalStateException("Installed PBS documentation is unavailable", failure);
}
}
}
private byte[] resource(String path) throws IOException {
if (path == null || path.contains("..") || path.contains(":") || path.contains("\\")
|| !(path.startsWith("pbs-knowledge/") || path.startsWith("game/stdlib/")))
throw new IOException("Invalid PBS reference resource");
try (var stream = resources.apply(path)) {
if (stream == null) throw new IOException("Missing PBS reference resource");
byte[] bytes = stream.readNBytes(4 * 1024 * 1024 + 1);
if (bytes.length > 4 * 1024 * 1024) throw new IOException("PBS reference resource is too large");
return bytes;
}
}
}
@@ -0,0 +1,8 @@
{
"name": "pbs-reference-example",
"version": "1.0.0",
"language": "pbs",
"stdlib": "1",
"target": "Game",
"dependencies": []
}
@@ -0,0 +1,19 @@
import { Color } from @core:color;
import { Gfx } from @sdk:gfx;
declare global x: int = 0;
[Init]
fn init() -> void {
x = 0;
}
[Frame]
fn frame() -> void {
Gfx.clear(Color.rgb(16, 20, 28));
Gfx.fill_rect(x, 32, 16, 16, Color.rgb(240, 160, 48));
x = x + 1;
if (x > 120) {
x = 0;
}
}
@@ -0,0 +1,2 @@
pub fn init() -> void;
pub fn frame() -> void;
@@ -0,0 +1,60 @@
package p.studio.compiler.pbs.documentation;
import org.junit.jupiter.api.Test;
import p.studio.AppMode;
import p.studio.compiler.services.FrontendReferenceProvider;
import java.io.ByteArrayInputStream;
import java.nio.charset.StandardCharsets;
import java.util.*;
import static org.junit.jupiter.api.Assertions.*;
class PbsDocumentationTest {
@Test void installedIndexHasAllKindsUniqueIdsAndExactSdkSources() throws Exception {
var references = new PbsDocumentation().references(1, AppMode.Game);
assertEquals(references.size(), references.stream().map(FrontendReferenceProvider.Reference::id).distinct().count());
for (var kind : List.of(FrontendReferenceProvider.Kind.QUICKSTART, FrontendReferenceProvider.Kind.SYNTAX,
FrontendReferenceProvider.Kind.SEMANTICS, FrontendReferenceProvider.Kind.EXAMPLE, FrontendReferenceProvider.Kind.SDK))
assertTrue(references.stream().anyMatch(ref -> ref.kind() == kind));
for (var reference : references) {
assertFalse(reference.text().isBlank());
if (reference.kind() != FrontendReferenceProvider.Kind.SDK) continue;
try (var stream = getClass().getClassLoader().getResourceAsStream("game/stdlib/1/" + reference.id().substring("pbs:sdk:game:1:".length()))) {
assertNotNull(stream);
assertEquals(new String(stream.readAllBytes(), StandardCharsets.UTF_8), reference.text());
assertEquals("1", reference.version());
}
}
}
@Test void unsupportedSdkOrTargetDoesNotBorrowAnotherSdkOrExample() {
var docs = new PbsDocumentation();
for (var selection : List.of(docs.references(999, AppMode.Game), docs.references(1, AppMode.Shell))) {
assertFalse(selection.isEmpty());
assertTrue(selection.stream().noneMatch(ref -> ref.kind() == FrontendReferenceProvider.Kind.SDK || ref.kind() == FrontendReferenceProvider.Kind.EXAMPLE));
assertTrue(selection.stream().allMatch(ref -> ref.version() == null && ref.versionSource().equals("unknown")));
}
}
@Test void missingIndexAndCorruptedContentFailExplicitly() {
assertThrows(IllegalStateException.class, () -> new PbsDocumentation(path -> null).references(1, AppMode.Game));
var corrupt = new PbsDocumentation(path -> path.equals("pbs-knowledge/index.json")
? getClass().getClassLoader().getResourceAsStream(path)
: new ByteArrayInputStream("corrupted resource".getBytes(StandardCharsets.UTF_8)));
assertThrows(IllegalStateException.class, () -> corrupt.references(1, AppMode.Game));
}
@Test void invalidIndexResourceCannotReachTheResourceLoader() {
var opened = new ArrayList<String>();
String invalidIndex = """
{"schemaVersion":1,"owner":"pbs","references":[
{"id":"pbs:bad","title":"Bad","kind":"SYNTAX","resource":"../private.txt","sha256":"invalid"}
]}
""";
var docs = new PbsDocumentation(path -> {
opened.add(path);
return new ByteArrayInputStream(invalidIndex.getBytes(StandardCharsets.UTF_8));
});
assertThrows(IllegalStateException.class, () -> docs.references(1, AppMode.Game));
assertEquals(List.of("pbs-knowledge/index.json"), opened);
}
}