From c18fc686138d751c9b92f3f566cd1cb3e72e2c17 Mon Sep 17 00:00:00 2001 From: speak-agent <248744407+speak-agent@users.noreply.github.com> Date: Sat, 26 Sep 2026 08:21:26 +0800 Subject: [PATCH] S2 0.3.0: a single-document answer may describe a workspace in part --- docs/specs/CHANGELOG.md | 11 +++++++++++ docs/specs/README.md | 2 +- docs/specs/s2-discovery.md | 8 +++++--- docs/specs/schema/s2-discovery.schema.json | 4 ++++ 4 files changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/specs/CHANGELOG.md b/docs/specs/CHANGELOG.md index d7741f2..0fe5818 100644 --- a/docs/specs/CHANGELOG.md +++ b/docs/specs/CHANGELOG.md @@ -2,6 +2,17 @@ Changes to the specifications in this directory. Each specification is versioned independently. +## 2026-09-26 — S2 0.3.0: a partial single-document answer + +In single-document mode a document may carry `data` together with `error` diagnostics. It describes +everything except what those diagnostics name; the producer names each part it could not describe +(a workspace member or a package) in the diagnostic's new optional `path` field, and a consumer uses +the rest of the document (S2-3.4-12, S2-3.4-13). `data` is present when the command described the +workspace in whole or in part; a command without `data` has still failed (S2-3.4-11). A consumer +written for 0.2.0 reads such a document as a success with errors, which is the intended reading. +mcpp implements it with mcpp-community/mcpp#699 (in #702); before, one workspace member's planning +failure used to remove every member's sets. + ## 2026-09-25 — S3: issue categories, the degraded hold, module syntax in semantic tokens Added `category` (optional) to `CxxModulesIssue`: `code`, `engine`, `environment` or `project`, diff --git a/docs/specs/README.md b/docs/specs/README.md index b054966..efe1612 100644 --- a/docs/specs/README.md +++ b/docs/specs/README.md @@ -5,7 +5,7 @@ This directory holds the normative specifications that let C++ named modules be | Spec | Title | Version | Status | Schema | |---|---|---|---|---| | [S1](s1-build-database.md) | C++ Build Database: IDE Profile | profile-version 0.2.0 | Draft | [s1-build-database.schema.json](schema/s1-build-database.schema.json) | -| [S2](s2-discovery.md) | Build Database Discovery Protocol | 0.2.0 | Draft | [s2-discovery.schema.json](schema/s2-discovery.schema.json) | +| [S2](s2-discovery.md) | Build Database Discovery Protocol | 0.3.0 | Draft | [s2-discovery.schema.json](schema/s2-discovery.schema.json) | | [S3](s3-lsp-extensions.md) | Language Server Protocol Extensions for C++ Modules | protocol version 1 | Draft | TypeScript interfaces in the text | | [S4](s4-semantic-kit.md) | Semantic Kit | kit-version 1 | Draft | [s4-kit.schema.json](schema/s4-kit.schema.json) | | [S5](s5-semantic-query.md) | Semantic Queries for C++ Code | 0.1.0 | Draft | TypeScript interfaces in the text | diff --git a/docs/specs/s2-discovery.md b/docs/specs/s2-discovery.md index 82690ec..266c504 100644 --- a/docs/specs/s2-discovery.md +++ b/docs/specs/s2-discovery.md @@ -3,7 +3,7 @@ | | | |---|---| | Specification | S2 | -| Version | 0.2.0 | +| Version | 0.3.0 | | Status | Draft | | Schema | [`schema/s2-discovery.schema.json`](schema/s2-discovery.schema.json) | | Examples | [`examples/s2-request.json`](examples/s2-request.json), [`examples/s2-messages.jsonl`](examples/s2-messages.jsonl), [`examples/s2-envelope.json`](examples/s2-envelope.json) | @@ -92,11 +92,13 @@ A producer that already prints machine-readable envelopes offers discovery as on | `kind` | string | MUST | A name ending in `.build-database`, for example `mcpp.build-database`. S2-3.4-2 | | `kindVersion` | integer | MUST | `1`. S2-3.4-3 | | `effects` | string[] | MUST | What running the command did, for example `read-project`. S2-3.4-4 | -| `data` | object | conditional MUST | Present when the command succeeded: `database` (object, MUST), the S1 document; `watch` (string[], MUST), as in section 3.3; `inputs-fingerprint` (string, SHOULD), a digest of the inputs `watch` names. S2-3.4-5, S2-3.4-6, S2-3.4-7, S2-3.4-8 | -| `diagnostics` | object[] | MUST | Each with `code`, `severity` (`error`, `warning` or `note`) and `message`. S2-3.4-9 | +| `data` | object | conditional MUST | Present when the command described the workspace in whole or in part: `database` (object, MUST), the S1 document; `watch` (string[], MUST), as in section 3.3; `inputs-fingerprint` (string, SHOULD), a digest of the inputs `watch` names. S2-3.4-5, S2-3.4-6, S2-3.4-7, S2-3.4-8 | +| `diagnostics` | object[] | MUST | Each with `code`, `severity` (`error`, `warning` or `note`) and `message`; `path` (string, MAY) names the file the diagnostic concerns, relative to the workspace root. S2-3.4-9 | The consumer writes nothing to the command's standard input. Before running it, the consumer reads the producer's protocol description, ` --protocol-version`: a JSON object whose `kinds` maps kind names to versions and whose `commands` maps command names to the `effects` they may have. A consumer **MUST** use single-document mode only when `kinds` contains the build-database kind, and **MUST** run the command only when the workspace is trusted and the listed effects are acceptable. A command without `data` has failed; its `diagnostics` say why. S2-3.4-10, S2-3.4-11 +A document may carry `data` together with `error` diagnostics. It describes everything except what those diagnostics name: the producer **MUST** name each part it could not describe, such as a workspace member or a package, in an `error` diagnostic whose `path` is that part's build description file, and a consumer **SHOULD** use the rest of the document and report the errors. The command's exit status is non-zero in this case. S2-3.4-12, S2-3.4-13 + In this mode the producer does not write a database file. The consumer keeps the document where it keeps its own state. Example: [`examples/s2-envelope.json`](examples/s2-envelope.json). diff --git a/docs/specs/schema/s2-discovery.schema.json b/docs/specs/schema/s2-discovery.schema.json index 228cc07..f3c02c1 100644 --- a/docs/specs/schema/s2-discovery.schema.json +++ b/docs/specs/schema/s2-discovery.schema.json @@ -202,6 +202,10 @@ }, "message": { "type": "string" + }, + "path": { + "type": "string", + "description": "The file the diagnostic concerns, relative to the workspace root (section 3.4)." } } }