From d8db99eb81e9e2dff3d22074dcc02dc5d02d2dd7 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 15 Jul 2026 07:20:42 +0100 Subject: [PATCH] implements PLN-0101 --- discussion/index.ndjson | 2 +- ...me-artifacts-from-doc-metadata-lowering.md | 2 +- .../compiler/pbs/PbsFrontendCompilerTest.java | 111 ++++++++++++++++++ 3 files changed, 113 insertions(+), 2 deletions(-) diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 8f143683..9c5e8e35 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,7 +1,7 @@ {"type":"meta","next_id":{"DSC":39,"AGD":42,"DEC":40,"PLN":103,"LSN":55,"CLSN":1}} {"type":"discussion","id":"DSC-0038","status":"done","ticket":"studio-packer-rgba8888-asset-pipeline","title":"Studio and Packer RGBA8888 Asset Pipeline Alignment","created_at":"2026-05-23","updated_at":"2026-07-14","tags":["studio","packer","assets","glyph-bank","palette","rgba8888","runtime-alignment"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0053","file":"discussion/lessons/DSC-0038-studio-packer-rgba8888-asset-pipeline/LSN-0053-rgba8888-is-the-canonical-studio-packer-palette-contract.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14"}]} {"type":"discussion","id":"DSC-0037","status":"done","ticket":"pbs-autocomplete-parameter-names","title":"PBS autocomplete parameter names for stdlib and method calls","created_at":"2026-05-08","updated_at":"2026-05-14","tags":["compiler-pbs","studio","lsp","autocomplete","signature-help","stdlib"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0037-pbs-autocomplete-parameter-names/LSN-0052-canonical-callable-parameter-names-through-pbs-editor-assistance.md","status":"done","created_at":"2026-05-14","updated_at":"2026-05-14"}]} -{"type":"discussion","id":"DSC-0036","status":"in_progress","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-07-15","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-pbs-symbol-documentation-and-hover-markdown.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-07-15"}],"decisions":[{"id":"DEC-0039","file":"DEC-0039-pbs-symbol-documentation-with-doc-markdown-text-blocks.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15","ref_agenda":"AGD-0039"}],"plans":[{"id":"PLN-0092","file":"PLN-0092-specify-pbs-doc-attribute-and-markdown-text-block-syntax.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0093","file":"PLN-0093-implement-pbs-lexer-support-for-documentation-text-blocks.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0094","file":"PLN-0094-extend-pbs-attribute-parser-and-ast-for-doc-markdown-payloads.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0095","file":"PLN-0095-implement-documentation-text-block-normalization.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0096","file":"PLN-0096-validate-doc-attribute-semantics-and-diagnostics.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0097","file":"PLN-0097-attach-doc-metadata-to-pbs-semantic-symbols.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0098","file":"PLN-0098-expose-doc-metadata-through-pbs-editorial-and-lsp-surfaces.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0099","file":"PLN-0099-render-doc-markdown-in-hover-composition.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0100","file":"PLN-0100-author-doc-metadata-for-stdlib-sdk-and-interface-declarations.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0101","file":"PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0102","file":"PLN-0102-add-end-to-end-doc-documentation-conformance-coverage.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0036","status":"in_progress","ticket":"pbs-symbol-documentation-and-hover-markdown","title":"Modelo de documentacao de simbolos em PBS e consumo markdown no hover","created_at":"2026-05-08","updated_at":"2026-07-15","tags":["compiler","compiler-pbs","studio","lsp","vscode","editor","hover","documentation","markdown"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-pbs-symbol-documentation-and-hover-markdown.md","status":"accepted","created_at":"2026-05-08","updated_at":"2026-07-15"}],"decisions":[{"id":"DEC-0039","file":"DEC-0039-pbs-symbol-documentation-with-doc-markdown-text-blocks.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15","ref_agenda":"AGD-0039"}],"plans":[{"id":"PLN-0092","file":"PLN-0092-specify-pbs-doc-attribute-and-markdown-text-block-syntax.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0093","file":"PLN-0093-implement-pbs-lexer-support-for-documentation-text-blocks.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0094","file":"PLN-0094-extend-pbs-attribute-parser-and-ast-for-doc-markdown-payloads.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0095","file":"PLN-0095-implement-documentation-text-block-normalization.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0096","file":"PLN-0096-validate-doc-attribute-semantics-and-diagnostics.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0097","file":"PLN-0097-attach-doc-metadata-to-pbs-semantic-symbols.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0098","file":"PLN-0098-expose-doc-metadata-through-pbs-editorial-and-lsp-surfaces.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0099","file":"PLN-0099-render-doc-markdown-in-hover-composition.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0100","file":"PLN-0100-author-doc-metadata-for-stdlib-sdk-and-interface-declarations.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0101","file":"PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]},{"id":"PLN-0102","file":"PLN-0102-add-end-to-end-doc-documentation-conformance-coverage.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0039"]}],"lessons":[]} {"type":"discussion","id":"DSC-0035","status":"done","ticket":"pbs-lsp-editor-assistance-wave-1","title":"Wave 1 de assistencia editorial via LSP para PBS no VS Code","created_at":"2026-05-08","updated_at":"2026-05-08","tags":["studio","lsp","vscode","compiler","compiler-pbs","editor","completion","hover","signature-help"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0035-pbs-lsp-editor-assistance-wave-1/LSN-0051-compiler-backed-editor-assistance-for-pbs.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]} {"type":"discussion","id":"DSC-0034","status":"done","ticket":"frontend-semantic-host-projection-flexibility","title":"Frontend semantic vocabulary flexibility and declarative host projection","created_at":"2026-05-06","updated_at":"2026-05-07","tags":["compiler","compiler-general","frontend","semantics","vscode","host-projection","lsp"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0034-frontend-semantic-host-projection-flexibility/LSN-0048-frontend-owned-semantic-vocabularies-with-declarative-host-projection.md","status":"done","created_at":"2026-05-07","updated_at":"2026-05-07"}]} {"type":"discussion","id":"DSC-0033","status":"done","ticket":"frontend-visual-theme-spec-and-css-retirement","title":"Frontend visual theme spec and retirement of host-consumed semantic CSS","created_at":"2026-05-06","updated_at":"2026-05-08","tags":["compiler","compiler-general","frontend","presentation","theming","studio","vscode","lsp","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0033-frontend-visual-theme-spec-and-css-retirement/LSN-0050-frontend-owned-visual-themes-with-structured-contract-and-host-adapters.md","status":"done","created_at":"2026-05-08","updated_at":"2026-05-08"}]} diff --git a/discussion/workflow/plans/PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md b/discussion/workflow/plans/PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md index 4f1549d0..dac12ebf 100644 --- a/discussion/workflow/plans/PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md +++ b/discussion/workflow/plans/PLN-0101-protect-runtime-artifacts-from-doc-metadata-lowering.md @@ -2,7 +2,7 @@ id: PLN-0101 ticket: pbs-symbol-documentation-and-hover-markdown title: Protect runtime artifacts from Doc metadata lowering -status: open +status: done created: 2026-07-15 ref_decisions: [DEC-0039] tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown] diff --git a/prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java b/prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java index c3ae0dc3..249fb649 100644 --- a/prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java +++ b/prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java @@ -4,6 +4,8 @@ import org.junit.jupiter.api.Test; import p.studio.compiler.messages.Addressable; import p.studio.compiler.messages.FESurfaceContext; import p.studio.compiler.messages.HostAdmissionContext; +import p.studio.compiler.models.IRBackendExecutableFunction; +import p.studio.compiler.models.IRBackendFile; import p.studio.compiler.models.IRHiddenGlobalKind; import p.studio.compiler.models.IRGlobalVisibility; import p.studio.compiler.models.IRSyntheticCallableKind; @@ -52,6 +54,57 @@ class PbsFrontendCompilerTest { assertEquals(1, functions.get(1).parameterCount()); } + @Test + void shouldNotLowerDocMetadataIntoRuntimeBackendArtifacts() { + final var undocumentedSource = """ + declare global SCORE: int = 0; + + fn add_one(value: int) -> int { + return value + 1; + } + + [Init] + fn boot() -> void { + SCORE = add_one(41); + return; + } + """; + final var marker = "THIS_DOC_PAYLOAD_MUST_NOT_APPEAR_IN_RUNTIME_ARTIFACTS"; + final var documentedSource = """ + declare global SCORE: int = 0; + + [Doc(markdown = \""" + Adds one to a value. + + This deliberately large documentation payload is editor metadata only: + THIS_DOC_PAYLOAD_MUST_NOT_APPEAR_IN_RUNTIME_ARTIFACTS. + \""")] + fn add_one(value: int) -> int { + return value + 1; + } + + [Doc(markdown = \""" + Initializes the score global. + \""")] + [Init] + fn boot() -> void { + SCORE = add_one(41); + return; + } + """; + + final var compiler = new PbsFrontendCompiler(); + final var undocumentedDiagnostics = DiagnosticSink.empty(); + final var documentedDiagnostics = DiagnosticSink.empty(); + final var undocumentedBackend = compiler.compileFile(new FileId(20), undocumentedSource, undocumentedDiagnostics); + final var documentedBackend = compiler.compileFile(new FileId(20), documentedSource, documentedDiagnostics); + + assertTrue(undocumentedDiagnostics.isEmpty(), diagnosticsSummary(undocumentedDiagnostics)); + assertTrue(documentedDiagnostics.isEmpty(), diagnosticsSummary(documentedDiagnostics)); + assertEquals(runtimeFingerprint(undocumentedBackend), runtimeFingerprint(documentedBackend)); + assertFalse(String.valueOf(documentedBackend).contains(marker)); + } + @Test void shouldExposeGlobalsAndSyntheticLifecycleArtifactsInBackendFile() { final var source = """ @@ -812,4 +865,62 @@ class PbsFrontendCompilerTest { assertEquals(1L, pixel.fields().get(1).slotStart()); assertEquals(2L, pixel.fields().get(2).slotStart()); } + + private static String runtimeFingerprint(final IRBackendFile backend) { + final var out = new StringBuilder(); + out.append("functions:"); + backend.functions().forEach(function -> out + .append(function.name()).append('/') + .append(function.parameterCount()).append('/') + .append(function.hasExplicitReturnType()).append(';')); + out.append("synthetic:"); + backend.syntheticFunctions().forEach(function -> out + .append(function.moduleId()).append('/') + .append(function.callableName()).append('/') + .append(function.kind()).append(';')); + out.append("globals:"); + backend.globals().forEach(global -> out + .append(global.moduleId()).append('/') + .append(global.name()).append('/') + .append(global.declaredTypeSurface()).append('/') + .append(global.slot()).append('/') + .append(global.visibility()).append('/') + .append(global.hiddenKind()).append(';')); + out.append("executables:"); + backend.executableFunctions().forEach(function -> { + out.append(function.moduleId()).append('/') + .append(function.callableName()).append('/') + .append(function.callableId().getIndex()).append('/') + .append(function.paramSlots()).append('/') + .append(function.localSlots()).append('/') + .append(function.returnSlots()).append('/') + .append(function.maxStackSlots()).append('{'); + function.instructions().forEach(instruction -> appendInstructionFingerprint(out, instruction)); + out.append("};"); + }); + out.append("modules:").append(backend.modulePool()).append(';'); + out.append("callables:").append(backend.callableSignatures()).append(';'); + out.append("intrinsics:").append(backend.intrinsicPool()).append(';'); + return out.toString(); + } + + private static void appendInstructionFingerprint( + final StringBuilder out, + final IRBackendExecutableFunction.Instruction instruction) { + out.append(instruction.kind()).append('(') + .append(instruction.calleeModuleId()).append(',') + .append(instruction.calleeCallableName()).append(',') + .append(instruction.calleeCallableId() == null ? "" : instruction.calleeCallableId().getIndex()).append(',') + .append(instruction.hostCall()).append(',') + .append(instruction.intrinsicCall()).append(',') + .append(instruction.label()).append(',') + .append(instruction.targetLabel()).append(',') + .append(instruction.expectedArgSlots()).append(',') + .append(instruction.expectedRetSlots()) + .append(");"); + } + + private static String diagnosticsSummary(final DiagnosticSink diagnostics) { + return diagnostics.stream().map(d -> d.getCode() + ":" + d.getMessage()).toList().toString(); + } }