alloy_devtools/

api.rs

//! Stable public API surface for developer-tool contracts.

/// Describes the current Sprint 9 scope for this crate.
#[must_use]
pub const fn scope() -> &'static str {
    "phase-4-v1"
}

/// Shared developer-tool verbs across the platform.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ToolVerb {
    /// Inspect a plan or config.
    Inspect,
    /// Validate inputs or environment.
    Validate,
    /// Benchmark a workload.
    Benchmark,
    /// Report evidence or summaries.
    Report,
}

impl ToolVerb {
    /// Returns the canonical CLI spelling.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Inspect => "inspect",
            Self::Validate => "validate",
            Self::Benchmark => "benchmark",
            Self::Report => "report",
        }
    }
}

/// Shared command metadata used by top-level packages and downstream tools.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct CommandSpec<'a> {
    /// Canonical verb.
    pub verb: ToolVerb,
    /// Artifact class produced or consumed by the command.
    pub artifact_class: &'a str,
    /// Short command purpose.
    pub description: &'a str,
}

const CORE_COMMANDS: [CommandSpec<'static>; 4] = [
    CommandSpec {
        verb: ToolVerb::Inspect,
        artifact_class: "plan",
        description: "Inspect a plan, config, or evaluator surface.",
    },
    CommandSpec {
        verb: ToolVerb::Validate,
        artifact_class: "validation",
        description: "Validate environment, inputs, or supported capabilities.",
    },
    CommandSpec {
        verb: ToolVerb::Benchmark,
        artifact_class: "benchmark",
        description: "Run benchmark capture for the selected workload.",
    },
    CommandSpec {
        verb: ToolVerb::Report,
        artifact_class: "report",
        description: "Produce evidence, summaries, and operator-facing reports.",
    },
];

/// Returns the required shared command catalog.
#[must_use]
pub const fn core_command_catalog() -> &'static [CommandSpec<'static>] {
    &CORE_COMMANDS
}

/// Builds a stable artifact stem for developer-facing outputs.
#[must_use]
pub fn artifact_name(
    package_name: &str,
    version: &str,
    maturity_tier: &str,
    artifact_class: &str,
) -> String {
    format!("{package_name}-{version}-{maturity_tier}-{artifact_class}")
}

/// Shared ownership record for integrated acceptance and release packet assets.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct OwnershipRecord<'a> {
    /// Capability or asset area being owned.
    pub area: &'a str,
    /// Primary owning repo or team.
    pub owner: &'a str,
    /// Artifact or packet input expected from the owner.
    pub artifact: &'a str,
}

impl<'a> OwnershipRecord<'a> {
    /// Builds a stable ownership record.
    #[must_use]
    pub const fn new(area: &'a str, owner: &'a str, artifact: &'a str) -> Self {
        Self {
            area,
            owner,
            artifact,
        }
    }
}

/// Shared topology assembly packet metadata used to freeze Phase 3 interfaces.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TopologyAssemblyPacket<'a> {
    /// Stable packet identifier.
    pub packet_id: &'a str,
    /// Shared topology profile name.
    pub topology_profile: &'a str,
    /// Version or scope marker for the packet.
    pub scope: &'a str,
    /// Primary ownership records referenced by the packet.
    pub ownership: &'a [OwnershipRecord<'a>],
}

impl<'a> TopologyAssemblyPacket<'a> {
    /// Builds a stable topology assembly packet.
    #[must_use]
    pub const fn new(
        packet_id: &'a str,
        topology_profile: &'a str,
        scope: &'a str,
        ownership: &'a [OwnershipRecord<'a>],
    ) -> Self {
        Self {
            packet_id,
            topology_profile,
            scope,
            ownership,
        }
    }

    /// Returns whether the packet declares at least one owning surface.
    #[must_use]
    pub fn has_owners(&self) -> bool {
        !self.ownership.is_empty()
    }
}

/// Shared release checklist item for Phase 3 assembly and later Sprint 7 fill-in.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ReleaseChecklistItem<'a> {
    /// Checklist item identifier.
    pub item_id: &'a str,
    /// Responsible owner for the item.
    pub owner: &'a str,
    /// Evidence or artifact required before the item can be marked done.
    pub required_artifact: &'a str,
}

impl<'a> ReleaseChecklistItem<'a> {
    /// Builds a release checklist item.
    #[must_use]
    pub const fn new(item_id: &'a str, owner: &'a str, required_artifact: &'a str) -> Self {
        Self {
            item_id,
            owner,
            required_artifact,
        }
    }
}

/// Shared closeout packet metadata for Phase 4 appliance and support releases.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ReleaseCloseoutPacket<'a> {
    /// Stable packet identifier.
    pub packet_id: &'a str,
    /// Shared release family or profile name.
    pub release_family: &'a str,
    /// Scope marker for the packet.
    pub scope: &'a str,
    /// Attachment points owned by producing repos.
    pub attachments: &'a [OwnershipRecord<'a>],
}

impl<'a> ReleaseCloseoutPacket<'a> {
    /// Builds a stable closeout packet.
    #[must_use]
    pub const fn new(
        packet_id: &'a str,
        release_family: &'a str,
        scope: &'a str,
        attachments: &'a [OwnershipRecord<'a>],
    ) -> Self {
        Self {
            packet_id,
            release_family,
            scope,
            attachments,
        }
    }

    /// Returns whether the packet names at least one downstream attachment.
    #[must_use]
    pub fn has_attachments(&self) -> bool {
        !self.attachments.is_empty()
    }
}

#[cfg(test)]
mod tests {
    use super::{
        OwnershipRecord, ReleaseChecklistItem, ReleaseCloseoutPacket, ToolVerb,
        TopologyAssemblyPacket, artifact_name, core_command_catalog, scope,
    };

    #[test]
    fn sprint_9_scope_is_exposed() {
        assert_eq!(scope(), "phase-4-v1");
    }

    #[test]
    fn catalog_contains_required_shared_verbs() {
        let verbs: Vec<_> = core_command_catalog()
            .iter()
            .map(|command| command.verb)
            .collect();

        assert!(verbs.contains(&ToolVerb::Inspect));
        assert!(verbs.contains(&ToolVerb::Validate));
        assert!(verbs.contains(&ToolVerb::Benchmark));
        assert!(verbs.contains(&ToolVerb::Report));
    }

    #[test]
    fn artifact_name_is_stable_and_portfolio_readable() {
        assert_eq!(
            artifact_name(
                "graph-rag-evaluator",
                "0.1.0",
                "embedded-evaluator",
                "report"
            ),
            "graph-rag-evaluator-0.1.0-embedded-evaluator-report"
        );
    }

    #[test]
    fn topology_assembly_packet_tracks_ownership_inputs() {
        let owners = [OwnershipRecord::new(
            "compiled-plan-cache",
            "rhodium",
            "compiled-plan-cache-contract",
        )];
        let packet = TopologyAssemblyPacket::new(
            "phase-3-topology-packet",
            "reference-stack-v1",
            "phase-3-v1",
            &owners,
        );

        assert!(packet.has_owners());
        assert_eq!(packet.topology_profile, "reference-stack-v1");
        assert_eq!(packet.ownership[0].owner, "rhodium");
    }

    #[test]
    fn release_checklist_item_carries_owner_and_artifact() {
        let item = ReleaseChecklistItem::new(
            "flagship-benchmark-evidence",
            "rhodium",
            "benchmark-evidence-packet",
        );

        assert_eq!(item.owner, "rhodium");
        assert_eq!(item.required_artifact, "benchmark-evidence-packet");
    }

    #[test]
    fn closeout_packet_tracks_attachment_points() {
        let attachments = [
            OwnershipRecord::new("appliance-profile", "rhodium", "appliance-package"),
            OwnershipRecord::new(
                "certification-support",
                "strontium",
                "certification-starter-pack",
            ),
        ];
        let packet = ReleaseCloseoutPacket::new(
            "phase-4-closeout-packet",
            "appliance-and-support",
            "phase-4-v1",
            &attachments,
        );

        assert!(packet.has_attachments());
        assert_eq!(packet.release_family, "appliance-and-support");
        assert_eq!(packet.attachments[0].owner, "rhodium");
    }
}