feat(studio): improve compiler reliability and AI diagnostics
Preserve structured diagnostics, source attribution, phase outcomes and revision context through compiler, Studio, LSP, MCP and JavaFX. Add project service discovery and resilient VS Code reconnection. Correct all eight reproduced PBS production failures in expression context, sibling executable bindings and nominal owner identity. Consolidate specs, lessons, immutable baseline evidence and the maintained source-to-guest qualification runner. Validation: required Gradle gate recorded 724 tests, with 711 passed and 13 skipped. Full corpus passed 168 compilation observations and 108 guest runs (104 successes and four deliberate faults); supplemental controls passed 42 compilations and 16 guest runs. TypeScript compilation, two Node discovery tests and discussion validation passed.
This commit is contained in:
@@ -409,3 +409,19 @@ modifying approval policy. Revocation removes published access even before
|
||||
asynchronous worker/runtime cleanup finishes. New grants never restore old task
|
||||
IDs or receipts. Full integrated native-client acceptance belongs to PLN-0140;
|
||||
the prior HTTP acceptance alone is insufficient.
|
||||
|
||||
## Explained build and language outcomes
|
||||
|
||||
ShipperPrepareResult preserves status/logs/manifestPath/emittedArtifacts/diagnostics and adds issues/summary/context. Shipper remains an internal orchestration structure; this contract does not require direct public access. Existing automation tools and DEV snapshots expose its result.
|
||||
|
||||
OperationState.SUCCEEDED means the callable completed mechanically. Build approval is independent: compiler-build, pack-validation, pack and manifest MUST all pass. Packer validation MUST have SUCCESS status and canPack=true. A failed validation with an empty asset list is still a rejection. A usable buildId is issued only for a successful current task build. Compiler warnings survive successful builds and pack failures.
|
||||
|
||||
summary includes scope (document/project/build), validationStatus (passed/rejected/failed/incomplete/not-evaluated/cancelled), nullable errors/warnings/infos counts, stage states and coverage. Unknown counts are null, never invented zeroes. Stage states are not-run/running/passed/rejected/failed/cancelled. Producer/verification failures are distinct from program rejection; a bounded detail sample never determines approval. Detail coverage and input-revision coverage are independent.
|
||||
|
||||
Cancellation is ShipperPreparationStatus.CANCELLED and validationStatus=cancelled. Preserve known partial issues/stages and do not issue a buildId. Cancel acknowledgement is independent of workerTerminated. Final tracked build results and the canonical session diagnostic view are published only after actual managed-worker termination. A cancelled worker's late return must not overwrite task revocation or turn into successful approval. Existing task admission, deduplication and explicit return authority remain unchanged.
|
||||
|
||||
DEV and the existing build surface render the canonical public view: summary, counts, stages, code/check, explanation, and individually expandable facts, semantic context, related origins and suggested checks. They MUST NOT reclassify logs or invoke another compiler. Source navigation checks project admission and the current digest before selecting a range. Changed source is labelled stale; unavailable revisions do not guarantee a current range. The diagnostic viewer is read-only, and generated/external navigation retains its existing read-only authority.
|
||||
|
||||
Language queries use a 10000 ms execution budget from admission (including queue/read/connect/initialize/analysis/query) plus a 2000 ms cleanup response window. Cancel pending requests and owned socket/listener/executors. shutdownNow is not evidence of termination. If a child remains alive, the caller may return the primary failure with workerTerminated=false, but the managed worker remains alive/busy until that child actually stops. Manual control and successor admission cannot be released early. Preserve the first failure and attach cleanup state rather than replacing it with a later failure.
|
||||
|
||||
Conformance distinguishes model/projection tests, source-navigation tests and real JavaFX desktop inspection. Model tests alone do not establish visual inspection. The integrated corpus uses production compiler/packer/LSP and authenticated MCP; controlled invalid IR and stubborn-child/protocol fixtures are explicitly identified test injections.
|
||||
|
||||
@@ -266,7 +266,7 @@ IDs from another task or project cannot be used. Client sockets/listeners close
|
||||
on success, failure, timeout or cancellation; project-server shutdown closes its
|
||||
accepted sockets and executor. A lost client does not independently grant control.
|
||||
|
||||
The adapter bounds connect time to 2 seconds and the LSP exchange to 10 seconds;
|
||||
The adapter bounds connect time to 2 seconds within the shared 10-second admission-relative execution budget, followed by a 2-second cleanup response window;
|
||||
Core bounds the request worker wait to 12 seconds. Documents are limited to 4 MiB
|
||||
of UTF-8 and task-local hierarchy state to 1024 items. These are adapter resource
|
||||
guards, unrelated to the runtime's deterministic frame/watchdog semantics.
|
||||
@@ -638,3 +638,35 @@ The coding client continues to own its configured stdio process and initial trus
|
||||
Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.
|
||||
|
||||
See the [complete animation contract](12.%20Animation%20Authoring%20Specification.md).
|
||||
|
||||
## Explained diagnostics and same-analysis LSP extension
|
||||
|
||||
The existing tools remain the entry points. studio_operation_get adds issues/summary/context to its build result; studio_language_query preserves operation/result/limitations and adds analysis/context. AutomationFailure adds neutral details. runtimeError remains reserved for native runtime data. Result fields and errors are declared in mcp/studio-tools-v1.json.
|
||||
|
||||
Correlation uses the applicable projectRoot/taskId/operationId/clientRequestId/queryId/analysisId/buildId. queryId identifies the admitted synchronous language query; it does not imply a new persisted operation registry. source FileId remains compilation-local and is qualified by analysis/input identity. Context identifies actual observed source inputs with SHA-256, language/SDK/target/profile values and honest partial coverage. A per-connection version=1 is not a global disk revision. Configuration values without a captured manifest-byte revision and pack/assets inputs MUST remain explicitly limited.
|
||||
|
||||
The LSP client advertises experimental.prometeuDiagnosticAnalysis={version:1}. A supporting real compiler-backed project server returns:
|
||||
|
||||
```json
|
||||
{"prometeuDiagnosticAnalysis":{"version":1,"method":"prometeu/documentAnalysis","diagnosticDataVersion":1}}
|
||||
```
|
||||
|
||||
For each didOpen/didChange, the server retains one analysisId and its complete analysis result. Located standard diagnostics contain data.prometeu={version:1,analysisId,issueId,issue}. Under the shared detail budget, identity and an explicit omission limitation replace the omitted issue. Locationless/project issues remain in the complementary analysis envelope and MUST NOT be coerced into standard zero ranges.
|
||||
|
||||
The request prometeu/documentAnalysis accepts {textDocument:{uri,version},contentSha256}. It returns {analysisId,document,issues,summary,inputs,configuration} from that retained analysis, without running a second backend/semantic analysis to produce details. document identifies the exact opened content. Current URI/version/digest mismatch returns JSON-RPC -32020 with reason ANALYSIS_REVISION_MISMATCH; unavailable retained analysis returns -32021 with ANALYSIS_UNAVAILABLE. Closing/disconnecting clears retained data. Analysis execution failure is an error, never successful empty diagnostics.
|
||||
|
||||
When the capability is absent, preserve standard results, report ANALYSIS_DETAILS_UNAVAILABLE, and use limited/unavailable rich coverage with not-evaluated validation. This fallback does not qualify the enriched integration. Empty standard diagnostics alone cannot establish project/build validity.
|
||||
|
||||
| Failure code | Mechanism |
|
||||
| --- | --- |
|
||||
| LANGUAGE_QUERY_TIMEOUT | Admission-relative execution deadline expired. |
|
||||
| LANGUAGE_QUERY_CANCELLED | Query interrupted or cancelled. |
|
||||
| LANGUAGE_SERVER_UNAVAILABLE | Project endpoint absent/unreachable. |
|
||||
| LANGUAGE_QUERY_PROTOCOL_FAILURE | Unexpected JSON-RPC/protocol failure. |
|
||||
| LANGUAGE_QUERY_INTERNAL_FAILURE | Analysis/query execution failed internally or advertised analysis is unavailable. |
|
||||
| LANGUAGE_QUERY_CLEANUP_FAILED | Owned query resource cleanup failed. |
|
||||
| LANGUAGE_QUERY_REVISION_MISMATCH | Analysis document identity differs from requested revision. |
|
||||
|
||||
Details retain component, operation/method, queryId, applicable identity, executionBudgetMs, cleanupBudgetMs, workerTerminated and cleanup. Preserve existing authority, read-only, unsupported and parameter errors. The first failure wins; cleanup status is attached independently. The default budget is 10000+2000 ms as specified by Studio 10. This does not alter runtime deadlines.
|
||||
|
||||
Conformance: StructuredDiagnosticsIntegrationTest exercises all eight unchanged PBS sources (now corrected positives), F1-local and the file-private negative control through authenticated HTTP MCP and the real project LSP; McpTaskToolsTest controlled invalid common IR exercises RET/join through the production backend/gateway/build tool. DiagnosticAnalysisProtocolTest checks retained identity/mismatch/unavailable; LanguageFailureContractTest checks real-socket controlled faults, fallback and delayed child termination. Existing task tests retain deduplication, cross-project isolation and revocation gates.
|
||||
|
||||
@@ -208,3 +208,26 @@ writes before retrying cleanup. Canceling that confirmation sends no consent.
|
||||
Neither task release, Stop, reclaim nor a timeout implicitly permits discard.
|
||||
Forced termination remains infrastructure failure with unknown publication
|
||||
outcome; it MUST NOT manufacture a durable save result.
|
||||
|
||||
|
||||
## Project LSP endpoint discovery
|
||||
|
||||
An open project's Studio LSP adapter MUST atomically publish `.studio/lsp.json`
|
||||
after its loopback server starts. Schema version 1 contains `schemaVersion`,
|
||||
`projectRoot` (canonical filesystem path), `sessionId` (fresh for each boot),
|
||||
`processId`, `host` (`127.0.0.1`) and `port` (the actual OS-assigned port).
|
||||
Publication failure MUST stop the newly started server. Shutdown MUST stop the
|
||||
server and remove discovery only when its session identity still owns the file.
|
||||
The file is transient, unversioned, carries no credential and MUST be independent
|
||||
of automation grants. It does not change the public LSP configuration default.
|
||||
|
||||
The VS Code extension MUST default to discovering this file for exactly one local
|
||||
workspace project, validate schema/root/process/host/port, and initialize against
|
||||
that canonical workspace. It MUST NOT silently select one of several roots or
|
||||
fall back to a fixed port. Absent or dead-process discovery means waiting for
|
||||
Studio; malformed metadata MUST be reported without connecting. File creation,
|
||||
replacement or deletion and workspace/configuration changes MUST restart discovery.
|
||||
Retries MUST use capped exponential backoff (2–30 seconds), reset after connection,
|
||||
and stop at extension shutdown. Connection state MUST be visible without recurring
|
||||
error popups. Explicit manual mode MAY use configured host/port for other hosts.
|
||||
The server's project binding validation remains authoritative.
|
||||
|
||||
@@ -199,3 +199,25 @@ Filesystem publication MUST NOT run under a long-held authority monitor.
|
||||
Glyph-bank animation authoring, generated-source navigation, strict task-scoped MCP tools and preview use the shared animation service and validation contract. UI/MCP preserve project authority, expected revisions, conflict/cancellation/revocation and document handoff. Persist only the canonical animation sidecar; keep generated PBS read-only and neutral services independent of JavaFX/transports.
|
||||
|
||||
See the [complete animation contract](12.%20Animation%20Authoring%20Specification.md).
|
||||
|
||||
## Explained diagnostic values and producer boundaries
|
||||
|
||||
StudioDiagnostic MUST carry the canonical logical issue through immutable JSON-compatible values. Studio API/Core MUST NOT depend on compiler AST/IR classes, PBS, LSP4j, transport objects or Throwable serialization. Existing code/severity/message constructors remain compatible.
|
||||
|
||||
| Field group | Contract |
|
||||
| --- | --- |
|
||||
| Identity | issueId identifies one producer event within analysisId. The same event keeps its ID in standard LSP data, complementary analysis, MCP and UI. Repeated events remain distinct. |
|
||||
| Producer and rule | producer has component, owner and languageId; code is the original producer code. codeOrigin marks producer versus studio-adapter. templateId/templateParameters remain separate from message. checkId identifies the detector independently of a shared code. |
|
||||
| Classification | severity, phase, stageId and failureKind preserve the producer's classification. Detection phase MUST NOT become an inferred cause. |
|
||||
| Explanation | explanation has id, summary, rule and availability. Text is deterministic and owner-maintained, never generated by an LLM at query time. Unknown checks report unavailable explanation. |
|
||||
| Evidence | facts, semanticContext, origin, related, suggestedChecks and limitations retain observed values and their availability. Suggested checks are investigations, not automatic source edits. |
|
||||
|
||||
semanticContext contains availability (available/partial/unavailable/not-applicable) and facts. Each fact is {value,availability,reason}, where availability is available/not-recorded/unavailable/not-applicable. An observed null is available; missing observations MUST NOT be represented as an observed null. Declared types, expression types and actual resolution constraints are separate concepts.
|
||||
|
||||
Origins keep UTF-8 byte spans, UTF-16 ranges and qualified IRVM coordinates separate. Convert a span only using matching captured source bytes. Missing origins, generated code, mixed input revisions and unavailable source text MUST NOT produce a fabricated zero range. Function context belongs in related context when no instruction source is recorded. Detection and context are not causal attribution.
|
||||
|
||||
The app compiler gateway translates complete warnings and BuildException payloads into neutral output or CompilerBuildFailure. Core MUST NOT catch compiler-domain exceptions directly. Packer adaptation preserves severity/category/blocking/evidencePath and asset identity; PACKER_<CATEGORY> is explicitly an adapter code. Asset ID MUST NOT be interpreted as a bank ID.
|
||||
|
||||
A shared public view contains issues, summary and context. Detail projection is limited to 1024 whole issues and 1 MiB of UTF-8 JSON issues. At a boundary, include a whole prefix, report partial detail coverage and LIMIT_EXCEEDED with budgets/total count, and retain full authoritative counts/evaluation separately. No issue field may be silently cut. UI and MCP consume this same view; underlying producer results remain complete.
|
||||
|
||||
Conformance: DiagnosticPayloadTest, StructuredShipperTest, StructuredDiagnosticsIntegrationTest and the compiler attribution/conversion regressions.
|
||||
|
||||
Reference in New Issue
Block a user