docs: consolidate canonical specs and preserve PBS reference IDs

This commit is contained in:
2026-10-28 15:11:00 +00:00
parent 9504f4694a
commit 3a3417eb44
74 changed files with 3231 additions and 270 deletions
@@ -13,11 +13,9 @@ dependencies {
// 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 pbsAlignmentSpecs = rootProject.layout.projectDirectory.dir("docs/compiler/pbs/specs")
val pbsResources = layout.projectDirectory.dir("src/main/resources")
val generatePbsKnowledge by tasks.registering(Sync::class) {
from(pbsSpecs) { include("*.md"); into("pbs-knowledge/specs") }
from(pbsAlignmentSpecs) { 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 {
@@ -29,13 +27,37 @@ val generatePbsKnowledge by tasks.registering(Sync::class) {
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()!!.toList() + (pbsAlignmentSpecs.asFile.listFiles()?.toList() ?: emptyList())).filter { it.extension == "md" }.sortedBy { it.name }.forEach { source ->
// Published filename IDs alias the single canonical numbered resource.
val legacyReferenceIds = mapOf(
"14" to "typed-arrays-and-optional-execution.md",
"15" to "first-class-functions-and-captures.md",
"16" to "generic-contracts.md",
"17" to "generic-structs-and-free-functions.md",
"18" to "input-and-existing-type-runtime-alignment.md",
"19" to "service-constants-and-runtime-math.md",
"20" to "runtime-random-integration.md",
"21" to "sdk-list-and-cursor.md",
"22" to "sdk-linked-and-cursor.md",
"23" to "sdk-set-and-identity.md",
"24" to "sdk-map-and-keyval.md",
"25" to "sdk-stack-and-queue.md"
)
val sources = checkNotNull(pbsSpecs.asFile.listFiles()) { "Missing canonical PBS specifications: $pbsSpecs" }
.filter { it.extension == "md" }.sortedBy { it.name }
check(legacyReferenceIds.keys.all { chapter -> sources.any { it.name.substringBefore(". ") == chapter } }) {
"Missing canonical target for a published PBS reference ID"
}
sources.forEach { source ->
val chapter = source.name.substringBefore(". ")
val quickstart = source.name == "README.md"
val title = source.readLines().first { it.startsWith("# ") }.removePrefix("# ")
val kind = if (quickstart) "QUICKSTART" else if (chapter == "3") "SYNTAX" else "SEMANTICS"
val resource = "pbs-knowledge/specs/${source.name}"
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)
title, kind, resource, source)
legacyReferenceIds[chapter]?.let { legacy ->
entry("pbs:spec:$legacy", title, kind, resource, source)
}
}
fileTree(pbsResources) { include("game/stdlib/**/*.pbs", "game/stdlib/**/*.barrel") }.files.sorted().forEach { source ->
val path = source.relativeTo(pbsResources.asFile).invariantSeparatorsPath
@@ -9,6 +9,35 @@ import java.util.*;
import static org.junit.jupiter.api.Assertions.*;
class PbsDocumentationTest {
@Test void publishedFeatureIdsResolveToTheSameCanonicalChapterResourceAndHash() throws Exception {
// These IDs were published before the chapters were numbered.
var legacyIds = List.of("typed-arrays-and-optional-execution.md",
"first-class-functions-and-captures.md", "generic-contracts.md",
"generic-structs-and-free-functions.md", "input-and-existing-type-runtime-alignment.md",
"service-constants-and-runtime-math.md", "runtime-random-integration.md",
"sdk-list-and-cursor.md", "sdk-linked-and-cursor.md", "sdk-set-and-identity.md",
"sdk-map-and-keyval.md", "sdk-stack-and-queue.md");
var references = new PbsDocumentation().references(1, AppMode.Game).stream()
.collect(java.util.stream.Collectors.toMap(FrontendReferenceProvider.Reference::id, ref -> ref));
var entries = new HashMap<String, com.fasterxml.jackson.databind.JsonNode>();
try (var stream = getClass().getClassLoader().getResourceAsStream("pbs-knowledge/index.json")) {
assertNotNull(stream);
new com.fasterxml.jackson.databind.ObjectMapper().readTree(stream).get("references")
.forEach(entry -> entries.put(entry.get("id").asText(), entry));
}
for (int i = 0; i < legacyIds.size(); i++) {
String oldId = "pbs:spec:" + legacyIds.get(i);
String chapterId = "pbs:spec:" + (14 + i);
assertNotNull(references.get(oldId), oldId);
assertNotNull(references.get(chapterId), chapterId);
assertEquals(references.get(chapterId).text(), references.get(oldId).text(), oldId);
assertEquals(references.get(chapterId).kind(), references.get(oldId).kind(), oldId);
assertEquals(entries.get(chapterId).get("resource"), entries.get(oldId).get("resource"), oldId);
assertEquals(entries.get(chapterId).get("sha256"), entries.get(oldId).get("sha256"), oldId);
assertTrue(entries.get(oldId).get("resource").asText().startsWith("pbs-knowledge/specs/" + (14 + i) + ". "));
}
}
@Test void installedIndexHasAllKindsUniqueIdsAndExactSdkSources() throws Exception {
var references = new PbsDocumentation().references(1, AppMode.Game);
assertEquals(references.size(), references.stream().map(FrontendReferenceProvider.Reference::id).distinct().count());
@@ -178,10 +178,9 @@ class BackendConformanceMatrixSpecTest {
private Path locateRepoRoot() {
var cursor = Path.of(System.getProperty("user.dir")).toAbsolutePath().normalize();
while (cursor != null) {
final var hasDocs = Files.isDirectory(cursor.resolve("docs/compiler/general/specs"));
final var hasCurrentDocs = Files.isDirectory(cursor.resolve("docs/specs/compiler"));
final var hasCompiler = Files.isDirectory(cursor.resolve("prometeu-compiler"));
if ((hasDocs || hasCurrentDocs) && hasCompiler) {
if (hasCurrentDocs && hasCompiler) {
return cursor;
}
cursor = cursor.getParent();