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
@@ -30,8 +30,9 @@ class StudioApplicationConfigurationTest {
assertFalse(executor.isShutdown());
assertTrue(mcp.isRunning());
var tools = context.getBean(p.studio.app.mcp.McpToolRegistry.class).descriptors();
org.junit.jupiter.api.Assertions.assertEquals(1, tools.size());
org.junit.jupiter.api.Assertions.assertEquals(2, tools.size());
org.junit.jupiter.api.Assertions.assertEquals("studio_project_context", tools.get(0).path("name").asText());
org.junit.jupiter.api.Assertions.assertEquals("studio_reference_read", tools.get(1).path("name").asText());
}
assertTrue(executor.isShutdown());
assertFalse(mcp.isRunning());
@@ -45,8 +45,10 @@ class CompilerProjectKnowledgeTest {
assertEquals(List.of(root), result.editableRoots());
assertFalse(result.libraries().getFirst().editable());
assertTrue(result.libraries().getFirst().id().startsWith("sdk:pbs:"));
assertTrue(result.references().isEmpty());
assertTrue(result.limitations().stream().anyMatch(value -> value.contains("DOCUMENTATION_UNAVAILABLE")));
assertFalse(result.references().isEmpty());
assertTrue(result.references().stream().anyMatch(value -> value.id().equals("pbs:quickstart")));
assertTrue(language.referenceIds().contains("pbs:quickstart"));
assertFalse(result.limitations().stream().anyMatch(value -> value.contains("DOCUMENTATION_UNAVAILABLE")));
assertFalse(Files.exists(root.resolve(".workspace")));
assertFalse(Files.exists(root.resolve(".studio")));
}
@@ -0,0 +1,62 @@
package p.studio.app.compiler;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.automation.ProjectKnowledge;
import p.studio.compiler.FrontendRegistryService;
import p.studio.compiler.messages.BuilderPipelineConfig;
import p.studio.compiler.models.BuilderPipelineContext;
import p.studio.compiler.workspaces.BuilderPipelineService;
import p.studio.core.project.*;
import p.studio.utilities.logs.LogAggregator;
import java.nio.file.Files;
import java.nio.file.Path;
/** Separate JVM gate: product classes/resources must resolve exclusively from installDist JARs. */
public final class InstalledKnowledgeProbe {
public static void main(String[] arguments) throws Exception {
var provider = FrontendRegistryService.require("pbs");
check(provider.getClass().getProtectionDomain().getCodeSource().getLocation().getPath().endsWith(".jar"), "Frontend must come from installed JAR");
check(CompilerProjectKnowledge.class.getProtectionDomain().getCodeSource().getLocation().getPath().endsWith(".jar"), "App must come from installed JAR");
check(!Files.exists(Path.of("settings.gradle.kts")) && !Files.exists(Path.of("docs")), "No repository in working directory");
Path root = Files.createDirectory(Path.of("example")).toRealPath();
var docs = provider.documentation().orElseThrow().references(1, p.studio.AppMode.Game);
for (var reference : docs) {
if (reference.id().startsWith("pbs:example:game:1:")) {
Path file = root.resolve(reference.id().substring("pbs:example:game:1:".length()));
Files.createDirectories(file.getParent());
Files.writeString(file, reference.text());
}
}
var mapper = new ObjectMapper();
var access = new ProjectAccessRegistry();
var registration = access.register(root, () -> { throw new AssertionError("References require no grant"); }, () -> true);
var catalog = new ProjectCatalogService(root, mapper, new ProjectLocalStudioSetupStore(mapper));
var knowledge = new CompilerProjectKnowledge(access, catalog, mapper);
var context = knowledge.context(root);
for (var kind : java.util.List.of(ProjectKnowledge.ReferenceKind.QUICKSTART, ProjectKnowledge.ReferenceKind.SYNTAX,
ProjectKnowledge.ReferenceKind.SEMANTICS, ProjectKnowledge.ReferenceKind.EXAMPLE, ProjectKnowledge.ReferenceKind.SDK))
check(context.references().stream().anyMatch(ref -> ref.kind() == kind), "Missing " + kind);
for (var reference : docs) {
var actual = new StringBuilder();
int offset = 0;
while (true) {
var page = knowledge.readReference(root, reference.id(), offset, 997);
actual.append(page.text());
if (page.nextOffset() == null) break;
offset = page.nextOffset();
}
check(actual.toString().equals(reference.text()), "Incorrect installed reference: " + reference.id());
}
var result = BuilderPipelineService.INSTANCE.compile(
BuilderPipelineContext.fromConfig(new BuilderPipelineConfig(false, root.toString())), LogAggregator.empty());
check(result.diagnostics().stream().noneMatch(issue -> issue.isError()), "Example must compile without errors");
check(result.bytecodeBytes().length > 0, "Example must produce bytecode");
registration.unsubscribe();
System.out.println("Installed knowledge verified: " + docs.size() + " references; example compiled");
}
private static void check(boolean condition, String message) {
if (!condition) throw new AssertionError(message);
}
}
@@ -0,0 +1,33 @@
package p.studio.app.compiler;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;
import static org.junit.jupiter.api.Assertions.*;
class InstalledKnowledgeTest {
@TempDir Path outsideRepository;
@Test void installedJarsProvideAllReferencesAndCompileTheExampleOutsideTheCheckout() throws Exception {
Path distribution = Path.of(System.getProperty("studio.test.distribution"));
String jars;
try (var files = Files.list(distribution.resolve("lib"))) {
jars = files.filter(file -> file.toString().endsWith(".jar")).sorted()
.map(Path::toString).collect(Collectors.joining(java.io.File.pathSeparator));
}
String probeClasses = Path.of(InstalledKnowledgeProbe.class.getProtectionDomain().getCodeSource().getLocation().toURI()).toString();
Path output = outsideRepository.resolve("probe.log");
var process = new ProcessBuilder(Path.of(System.getProperty("java.home"), "bin", "java").toString(),
"-cp", jars + java.io.File.pathSeparator + probeClasses, InstalledKnowledgeProbe.class.getName())
.directory(outsideRepository.toFile()).redirectErrorStream(true).redirectOutput(output.toFile()).start();
try {
assertTrue(process.waitFor(45, TimeUnit.SECONDS), "Installed knowledge probe timed out");
String log = Files.readString(output);
assertEquals(0, process.exitValue(), log);
assertTrue(log.contains("references; example compiled"), log);
} finally { if (process.isAlive()) process.destroyForcibly().waitFor(); }
}
}
@@ -0,0 +1,143 @@
package p.studio.app.compiler;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import p.studio.api.automation.*;
import p.studio.compiler.FrontendRegistryService;
import p.studio.compiler.models.FrontendSpec;
import p.studio.compiler.services.*;
import p.studio.core.project.*;
import p.studio.utilities.structures.ReadOnlySet;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.*;
import static org.junit.jupiter.api.Assertions.*;
class ProjectReferencesTest {
@TempDir Path root;
final ObjectMapper mapper = new ObjectMapper();
final ProjectAccessRegistry access = new ProjectAccessRegistry();
CompilerProjectKnowledge knowledge(String language, String sdk) throws Exception {
writeManifest(language, sdk);
access.register(root, () -> { throw new AssertionError("Read needs no grant"); }, () -> true);
return new CompilerProjectKnowledge(access, new ProjectCatalogService(root, mapper, new ProjectLocalStudioSetupStore(mapper)), mapper);
}
void writeManifest(String language, String sdk) throws Exception {
mapper.writeValue(root.resolve("prometeu.json").toFile(), Map.of("name", "References", "version", "1.0.0",
"language", language, "stdlib", sdk, "target", "Game", "dependencies", List.of()));
}
@Test void pbsReferenceKindsAndVersionsMatchTheInstalledProviderAndPaginateExactly() throws Exception {
var knowledge = knowledge("pbs", "1");
var context = knowledge.context(root);
var kinds = context.references().stream().map(ProjectKnowledge.Reference::kind).collect(java.util.stream.Collectors.toSet());
assertTrue(kinds.containsAll(List.of(ProjectKnowledge.ReferenceKind.QUICKSTART, ProjectKnowledge.ReferenceKind.SYNTAX,
ProjectKnowledge.ReferenceKind.SEMANTICS, ProjectKnowledge.ReferenceKind.EXAMPLE, ProjectKnowledge.ReferenceKind.SDK)));
assertEquals(context.references().size(), context.languages().getFirst().referenceIds().size());
for (var reference : context.references()) {
assertEquals("pbs", reference.owner());
if (reference.kind() == ProjectKnowledge.ReferenceKind.SDK || reference.kind() == ProjectKnowledge.ReferenceKind.EXAMPLE) {
assertEquals("1", reference.version().value());
assertTrue(reference.version().source().contains("SDK"));
} else assertFalse(reference.version().known());
}
var sdk = "pbs:sdk:game:1:sdk/gfx/main.pbs";
var expected = FrontendRegistryService.require("pbs").documentation().orElseThrow().references(1, p.studio.AppMode.Game)
.stream().filter(ref -> ref.id().equals(sdk)).findFirst().orElseThrow().text();
var actual = new StringBuilder();
int offset = 0;
do {
var page = knowledge.readReference(root, sdk, offset, 97);
assertEquals(expected.codePointCount(0, expected.length()), page.total());
actual.append(page.text());
if (page.nextOffset() == null) break;
offset = page.nextOffset();
} while (true);
assertEquals(expected, actual.toString());
assertTrue(actual.toString().contains("fn fill_rect"));
}
@Test void unknownAndTraversalLikeIdsNeverReadFilesOrUrls() throws Exception {
var knowledge = knowledge("pbs", "1");
Path secret = root.resolve("secret.txt");
Files.writeString(secret, "not a reference");
for (String id : List.of(secret.toString(), secret.toUri().toString(), "../secret.txt", "pbs:../secret.txt",
"pbs-knowledge/index.json", "pbs:%2e%2e/secret.txt", "https://example.invalid", "pbs:unknown")) {
assertEquals(AutomationFailure.Code.REFERENCE_NOT_FOUND,
assertThrows(AutomationException.class, () -> knowledge.readReference(root, id, 0, 100)).failure().code());
}
}
@Test void changedSdkCannotReadPreviouslyAdvertisedSdkOrExampleIds() throws Exception {
var knowledge = knowledge("pbs", "1");
assertTrue(knowledge.context(root).languages().getFirst().referenceIds().contains("pbs:sdk:game:1:sdk/gfx/main.pbs"));
writeManifest("pbs", "999");
var context = knowledge.context(root);
assertTrue(context.references().stream().noneMatch(ref -> ref.kind() == ProjectKnowledge.ReferenceKind.SDK || ref.kind() == ProjectKnowledge.ReferenceKind.EXAMPLE));
assertTrue(context.limitations().stream().anyMatch(value -> value.contains("no installed SDK reference")));
assertEquals(AutomationFailure.Code.REFERENCE_NOT_FOUND, assertThrows(AutomationException.class,
() -> knowledge.readReference(root, "pbs:sdk:game:1:sdk/gfx/main.pbs", 0, 100)).failure().code());
assertFalse(knowledge.readReference(root, "pbs:quickstart", 0, 100).text().isEmpty());
}
@Test void paginationCountsUnicodeCodePointsAndAcceptsTheExactEnd() throws Exception {
String id = "reference-test";
register(id, Optional.of((sdk, target) -> List.of(new FrontendReferenceProvider.Reference(
id + ":text", "Unicode text", FrontendReferenceProvider.Kind.QUICKSTART, null, "unknown", "A😀é\nB"))));
try {
var knowledge = knowledge(id, "1");
var emoji = knowledge.readReference(root, id + ":text", 1, 1);
assertEquals("😀", emoji.text());
assertEquals(5, emoji.total());
assertEquals(2, emoji.nextOffset());
var end = knowledge.readReference(root, id + ":text", 5, 100);
assertEquals("", end.text()); assertNull(end.nextOffset());
for (int offset : List.of(-1, 6, Integer.MAX_VALUE))
assertThrows(IllegalArgumentException.class, () -> knowledge.readReference(root, id + ":text", offset, 1));
for (int limit : List.of(0, -1, 16001))
assertThrows(IllegalArgumentException.class, () -> knowledge.readReference(root, id + ":text", 0, limit));
} finally { FrontendRegistryService.unregister(id); }
}
@Test void missingDocumentationAndUnsupportedLanguageHaveExplicitFailures() throws Exception {
String id = "reference-test";
register(id, Optional.empty());
try {
var knowledge = knowledge(id, "1");
assertTrue(knowledge.context(root).references().isEmpty());
assertEquals(AutomationFailure.Code.DOCUMENTATION_UNAVAILABLE, assertThrows(AutomationException.class,
() -> knowledge.readReference(root, id + ":text", 0, 100)).failure().code());
writeManifest("uninstalled", "1");
assertEquals(AutomationFailure.Code.UNSUPPORTED_LANGUAGE, assertThrows(AutomationException.class,
() -> knowledge.readReference(root, id + ":text", 0, 100)).failure().code());
} finally { FrontendRegistryService.unregister(id); }
}
@Test void failingProviderDoesNotAdvertiseUnreadableReferences() throws Exception {
String id = "reference-test";
register(id, Optional.of((sdk, target) -> { throw new IllegalStateException("Missing installed index"); }));
try {
var knowledge = knowledge(id, "1");
var context = knowledge.context(root);
assertTrue(context.references().isEmpty());
assertTrue(context.limitations().stream().anyMatch(value -> value.contains("cannot load installed references")));
assertEquals(AutomationFailure.Code.DOCUMENTATION_UNAVAILABLE, assertThrows(AutomationException.class,
() -> knowledge.readReference(root, id + ":text", 0, 100)).failure().code());
} finally { FrontendRegistryService.unregister(id); }
}
private void register(String id, Optional<FrontendReferenceProvider> documentation) {
FrontendRegistryService.register(new FrontendProvider() {
@Override public FrontendSpec specification() {
return FrontendSpec.builder().languageId(id).allowedExtensions(ReadOnlySet.from("alt"))
.sourceRoots(ReadOnlySet.from("src")).stdlibVersions(List.of(FrontendSpec.Stdlib.of(1))).build();
}
@Override public FrontendPhaseService compiler() { throw new AssertionError("No compilation for reference reads"); }
@Override public Optional<FrontendReferenceProvider> documentation() { return documentation; }
});
}
}
@@ -129,6 +129,20 @@ class LocalMcpServerTest {
assertEquals("pbs", value.path("languages").get(0).path("id").asText());
assertTrue(value.path("languages").get(0).path("languageVersion").path("value").isNull());
assertFalse(java.nio.file.Files.exists(root.resolve(".studio")));
var params = (com.fasterxml.jackson.databind.node.ObjectNode) call.path("params");
params.put("name", "studio_reference_read");
var arguments = (com.fasterxml.jackson.databind.node.ObjectNode) params.path("arguments");
arguments.put("referenceId", "pbs:quickstart");
var page = mapper.readTree(post(call.toString()).body()).path("result").path("structuredContent").path("value");
assertEquals(0, page.path("offset").asInt());
assertEquals(4000, page.path("text").asText().codePointCount(0, page.path("text").asText().length()));
assertEquals(4000, page.path("nextOffset").asInt());
arguments.put("offset", 4294967296L);
assertEquals(-32602, mapper.readTree(post(call.toString()).body()).path("error").path("code").asInt());
arguments.remove("offset");
arguments.put("referenceId", "../../prometeu.json");
var missing = mapper.readTree(post(call.toString()).body()).path("result");
assertEquals("REFERENCE_NOT_FOUND", missing.path("structuredContent").path("error").path("code").asText());
registration.unsubscribe();
var denied = mapper.readTree(post(call.toString()).body()).path("result");
assertTrue(denied.path("isError").asBoolean());