package PBS references and expose paginated MCP reads
This commit is contained in:
@@ -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) }
|
||||
|
||||
+7
@@ -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);
|
||||
}
|
||||
}
|
||||
|
||||
+78
@@ -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;
|
||||
}
|
||||
}
|
||||
}
|
||||
+8
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"name": "pbs-reference-example",
|
||||
"version": "1.0.0",
|
||||
"language": "pbs",
|
||||
"stdlib": "1",
|
||||
"target": "Game",
|
||||
"dependencies": []
|
||||
}
|
||||
+19
@@ -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;
|
||||
}
|
||||
}
|
||||
+2
@@ -0,0 +1,2 @@
|
||||
pub fn init() -> void;
|
||||
pub fn frame() -> void;
|
||||
+60
@@ -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);
|
||||
}
|
||||
}
|
||||
+4
@@ -12,4 +12,8 @@ public interface FrontendProvider {
|
||||
default Optional<FrontendLanguageService> languageService() {
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
default Optional<FrontendReferenceProvider> documentation() {
|
||||
return Optional.empty();
|
||||
}
|
||||
}
|
||||
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
package p.studio.compiler.services;
|
||||
|
||||
import p.studio.AppMode;
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
|
||||
/** Owner-maintained, installed reference texts. This is not a filesystem or network reader. */
|
||||
public interface FrontendReferenceProvider {
|
||||
List<Reference> references(int stdlibVersion, AppMode target);
|
||||
|
||||
enum Kind { QUICKSTART, SYNTAX, SEMANTICS, EXAMPLE, SDK, LIBRARY }
|
||||
|
||||
record Reference(String id, String title, Kind kind, String version, String versionSource, String text) {
|
||||
public Reference {
|
||||
Objects.requireNonNull(id); Objects.requireNonNull(title); Objects.requireNonNull(kind);
|
||||
Objects.requireNonNull(versionSource); Objects.requireNonNull(text);
|
||||
if (id.isBlank() || title.isBlank() || versionSource.isBlank() || version != null && version.isBlank())
|
||||
throw new IllegalArgumentException("Blank reference metadata");
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user