docs: consolidate canonical specs and preserve PBS reference IDs
This commit is contained in:
@@ -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
|
||||
|
||||
+29
@@ -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());
|
||||
|
||||
+1
-2
@@ -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();
|
||||
|
||||
Reference in New Issue
Block a user