morphir-workspace 0.2.0

Portable, root-confined Morphir workspace discovery
Documentation
use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::{DiscoveryFailure, RelativePath, WorkspaceDiagnostic};

/// The state of a discovered workspace.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "kebab-case")]
pub enum WorkspaceState {
    /// The workspace was opened successfully.
    Open,
    /// The workspace was opened with workspace-level errors.
    Error,
}

/// The state of a discovered project.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "kebab-case")]
pub enum ProjectState {
    /// The project has been discovered but not loaded.
    Unloaded,
    /// The project could not be discovered completely.
    Error,
}

/// A deterministic, provider-neutral snapshot of a workspace.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct WorkspaceSnapshot {
    /// The protocol version used to produce this snapshot.
    pub protocol_version: semver::Version,
    /// The workspace configuration path relative to the development root,
    /// when one exists.
    pub config_anchor: Option<RelativePath>,
    /// The configured workspace name, when present.
    pub name: Option<String>,
    /// The overall workspace state.
    pub state: WorkspaceState,
    /// Discovered projects, sorted by canonical relative path and then name.
    pub projects: Vec<ProjectSnapshot>,
    /// Workspace diagnostics, sorted by project path, path, code, severity,
    /// and message.
    pub diagnostics: Vec<WorkspaceDiagnostic>,
}

/// In-memory discovery details for native hosts that need the exact effective
/// configuration values produced by the portable discovery pass.
///
/// This sidecar is deliberately not part of the serialized discovery protocol.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct WorkspaceDiscoveryDetails {
    /// The provider-neutral workspace snapshot.
    pub snapshot: WorkspaceSnapshot,
    /// The fully merged effective configuration at the workspace root.
    pub root_effective: Value,
    /// Fully merged effective configurations for valid projects, keyed by path.
    pub project_effective: BTreeMap<RelativePath, Value>,
}

/// A deterministic, provider-neutral snapshot of a project.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ProjectSnapshot {
    /// The project name. A synthesized project (see
    /// [`ProjectOrigin::Synthesized`]) carries the explicit name from
    /// `DiscoveryRequest::cli_overlay`'s `project.name`, when the request
    /// supplied one; otherwise it emits `""` here; a later provider-synthesis
    /// step fills it in.
    pub name: String,
    /// The project version, when configured.
    pub version: Option<String>,
    /// The project path relative to the development root.
    pub relative_path: RelativePath,
    /// The project configuration path, when one exists.
    pub config_anchor: Option<RelativePath>,
    /// The source directory relative to this project's [`Self::relative_path`].
    pub source_directory: RelativePath,
    /// The project state.
    pub state: ProjectState,
    /// Project diagnostics, sorted by project path, path, code, severity, and
    /// message.
    pub diagnostics: Vec<WorkspaceDiagnostic>,
    /// Where this project came from.
    pub origin: ProjectOrigin,
    /// The modules this project exposes. `None` when not yet determined;
    /// `Some(vec![])` means the project exposes no modules.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub exposed_modules: Option<Vec<String>>,
}

/// Where a discovered project came from.
///
/// `config_anchor` records *which* manifest a project was read from but not
/// *whether* there was one. A caller applies different configuration rules to
/// a synthesized project, and inferring that from an absent anchor turns a
/// policy decision into a missing field.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
pub enum ProjectOrigin {
    /// Read from the manifest at this path.
    #[serde(rename_all = "camelCase")]
    Manifest { path: RelativePath },
    /// Synthesized from these sources, in the order the request gave them.
    /// Development-root-relative, copied verbatim from
    /// [`SourceSelection::paths`](crate::SourceSelection::paths).
    #[serde(rename_all = "camelCase")]
    Synthesized { inputs: Vec<RelativePath> },
}

/// The provider-neutral result of workspace discovery.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "status", rename_all = "kebab-case")]
pub enum DiscoveryResponse {
    /// Discovery completed and produced a snapshot.
    Success {
        /// The discovered workspace snapshot.
        snapshot: WorkspaceSnapshot,
    },
    /// Discovery failed before a snapshot could be produced.
    Failure {
        /// The fatal discovery failure.
        error: DiscoveryFailure,
    },
}

impl DiscoveryResponse {
    /// Converts the wire response into a conventional Rust result.
    pub fn into_result(self) -> Result<WorkspaceSnapshot, DiscoveryFailure> {
        match self {
            Self::Success { snapshot } => Ok(snapshot),
            Self::Failure { error } => Err(error),
        }
    }
}