feat(ide): define snapshot protocol model

mcpp-community · wellwei · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026
commit 210a31b485d46bf30e9fb4e3af783adc12e6edfd
diff --git a/src/ide/model.cppm b/src/ide/model.cppm
@@ -0,0 +1,115 @@
+export module mcpp.ide.model;
+
+import std;
+
+export namespace mcpp::ide {
+
+enum class SnapshotState {
+    Partial,
+    Stale,
+    Unavailable,
+    Ready,
+};
+
+enum class ArtifactState {
+    Missing,
+    Stale,
+};
+
+enum class Severity {
+    Warning,
+    Error,
+};
+
+std::string_view wire_name(SnapshotState state) {
+    switch (state) {
+    case SnapshotState::Partial: return "partial";
+    case SnapshotState::Stale: return "stale";
+    case SnapshotState::Unavailable: return "unavailable";
+    case SnapshotState::Ready: return "ready";
+    }
+    return {};
+}
+
+std::string_view wire_name(ArtifactState state) {
+    switch (state) {
+    case ArtifactState::Missing: return "missing";
+    case ArtifactState::Stale: return "stale";
+    }
+    return {};
+}
+
+std::string_view wire_name(Severity severity) {
+    switch (severity) {
+    case Severity::Warning: return "warning";
+    case Severity::Error: return "error";
+    }
+    return {};
+}
+
+struct Position {
+    std::size_t line = 0;
+    std::size_t column = 0;
+};
+
+struct Range {
+    Position start;
+    Position end;
+};
+
+struct Diagnostic {
+    std::string code;
+    Severity severity = Severity::Error;
+    std::string message;
+    std::filesystem::path path;
+    std::optional<Range> range;
+};
+
+struct Selectors {
+    std::optional<std::string> package;
+    bool workspace = false;
+    std::optional<std::string> profile;
+    std::optional<std::string> target;
+    std::vector<std::string> features;
+    std::vector<std::string> capabilities;
+    bool includeDevDependencies = false;
+};
+
+struct InspectRequest {
+    std::filesystem::path start;
+    Selectors selectors;
+};
+
+struct DeclaredTarget {
+    std::string name;
+    std::string kind;
+    std::optional<std::string> main;
+};
+
+struct WorkspaceMember {
+    std::string name;
+    std::string version;
+    std::string workspacePath;
+    std::filesystem::path root;
+    std::filesystem::path manifest;
+    std::vector<DeclaredTarget> targets;
+};
+
+struct CompileCommandsArtifact {
+    std::string member;
+    std::filesystem::path path;
+    ArtifactState state = ArtifactState::Missing;
+};
+
+struct WorkspaceInspection {
+    SnapshotState state = SnapshotState::Unavailable;
+    InspectRequest request;
+    std::filesystem::path workspaceRoot;
+    std::filesystem::path workspaceManifest;
+    std::vector<WorkspaceMember> members;
+    std::vector<std::string> selectedMembers;
+    std::vector<CompileCommandsArtifact> compileCommands;
+    std::vector<Diagnostic> diagnostics;
+};
+
+} // namespace mcpp::ide
diff --git a/tests/fixtures/ide/snapshot-v1.json b/tests/fixtures/ide/snapshot-v1.json
@@ -0,0 +1,71 @@
+{
+  "schemaVersion": 1,
+  "kind": "mcpp.ide.snapshot",
+  "snapshotId": "fnv1a64:0000000000000000",
+  "state": "partial",
+  "mcppVersion": "2026.8.5.2",
+  "protocol": {
+    "min": 1,
+    "max": 1
+  },
+  "capabilities": [
+    "workspace-inspection",
+    "manifest-diagnostics",
+    "compile-commands-location"
+  ],
+  "request": {
+    "start": "/workspace/app",
+    "mode": "read-only",
+    "selectors": {
+      "package": null,
+      "workspace": false,
+      "profile": null,
+      "target": null,
+      "features": [],
+      "capabilities": [],
+      "includeDevDependencies": false
+    }
+  },
+  "workspace": {
+    "root": "/workspace/app",
+    "manifest": "/workspace/app/mcpp.toml",
+    "members": [
+      {
+        "name": "app",
+        "version": "1.0.0",
+        "workspacePath": ".",
+        "root": "/workspace/app",
+        "manifest": "/workspace/app/mcpp.toml",
+        "targets": [
+          {
+            "name": "app",
+            "kind": "binary",
+            "main": "src/main.cpp"
+          }
+        ]
+      }
+    ],
+    "selectedMembers": [
+      "app"
+    ]
+  },
+  "artifacts": {
+    "state": "partial",
+    "compileCommands": [
+      {
+        "member": "app",
+        "path": "/workspace/app/compile_commands.json",
+        "state": "missing"
+      }
+    ]
+  },
+  "diagnostics": [
+    {
+      "code": "MCPP_IDE_ARTIFACTS_MISSING",
+      "severity": "warning",
+      "message": "Compile commands are unavailable for one or more selected members.",
+      "path": "/workspace/app/mcpp.toml",
+      "range": null
+    }
+  ]
+}
diff --git a/tests/unit/test_ide_snapshot.cpp b/tests/unit/test_ide_snapshot.cpp
@@ -0,0 +1,16 @@
+#include <gtest/gtest.h>
+
+import std;
+import mcpp.ide.model;
+
+TEST(IdeSnapshotModel, WireNamesAreStable) {
+    using namespace mcpp::ide;
+    EXPECT_EQ(wire_name(SnapshotState::Partial), "partial");
+    EXPECT_EQ(wire_name(SnapshotState::Stale), "stale");
+    EXPECT_EQ(wire_name(SnapshotState::Unavailable), "unavailable");
+    EXPECT_EQ(wire_name(SnapshotState::Ready), "ready");
+    EXPECT_EQ(wire_name(ArtifactState::Missing), "missing");
+    EXPECT_EQ(wire_name(ArtifactState::Stale), "stale");
+    EXPECT_EQ(wire_name(Severity::Warning), "warning");
+    EXPECT_EQ(wire_name(Severity::Error), "error");
+}