From 3f8dce013bdb036d22939cb90f00daed507e7378 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 10:43:59 +0800 Subject: [PATCH] feat(package): project manifest, deterministic lockfile and root discovery Blueprint section 8, minimum viable P3: - marqdo.yaml parsing/validation: project identity, dependency sources (path or git with mandatory exact rev), plugin requirements, capability requests; absolute dependency paths, ambiguous sources and unpinned git are errors. - marqdo.lock: lock_version, sorted packages, canonical YAML with no timestamps or machine paths so repeated locking is byte-identical. - discover_root walks up to the nearest marqdo.yaml. - Manifest::template for `marqdo init`. --- crates/marqdo-package/Cargo.toml | 10 +- crates/marqdo-package/src/lib.rs | 353 +++++++++++++++++++++++++++++++ 2 files changed, 357 insertions(+), 6 deletions(-) create mode 100644 crates/marqdo-package/src/lib.rs diff --git a/crates/marqdo-package/Cargo.toml b/crates/marqdo-package/Cargo.toml index 65e82e4..1a389d5 100644 --- a/crates/marqdo-package/Cargo.toml +++ b/crates/marqdo-package/Cargo.toml @@ -9,12 +9,10 @@ repository.workspace = true authors.workspace = true [dependencies] -marqdo-span = { workspace = true } serde = { workspace = true } serde_yaml = { workspace = true } -serde_json = { workspace = true } -sha2 = { workspace = true } -hex = { workspace = true } -thiserror = { workspace = true } -walkdir = { workspace = true } + + +[dev-dependencies] +tempfile = { workspace = true } diff --git a/crates/marqdo-package/src/lib.rs b/crates/marqdo-package/src/lib.rs new file mode 100644 index 0000000..144cb08 --- /dev/null +++ b/crates/marqdo-package/src/lib.rs @@ -0,0 +1,353 @@ +//! Project manifest, lockfile and dependency resolution. +//! +//! Blueprint ยง8: `marqdo.yaml` is the project manifest, `marqdo.lock` the +//! reproducible lockfile, and front matter imports are explicit document-level +//! bindings. This crate only parses and serialises these files; it never runs +//! project code and never executes install scripts. + +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; + +use serde::{Deserialize, Serialize}; + +/// Manifest file name. +pub const MANIFEST_FILE: &str = "marqdo.yaml"; +/// Lockfile name. +pub const LOCK_FILE: &str = "marqdo.lock"; + +/// Project identity and runtime constraint. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ProjectInfo { + /// Package name. + pub name: String, + /// Package version. + pub version: String, + /// Required Marqdo runtime range (informational in M0.5). + #[serde(default)] + pub marqdo: Option, +} + +/// One declared dependency source. Exactly one source form is allowed. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +pub struct Dependency { + /// Local path relative to the project root. + #[serde(skip_serializing_if = "Option::is_none")] + pub path: Option, + /// Git URL (must be pinned by `rev` for reproducible builds). + #[serde(skip_serializing_if = "Option::is_none")] + pub git: Option, + /// Exact git revision. + #[serde(skip_serializing_if = "Option::is_none")] + pub rev: Option, +} + +impl Dependency { + /// Validate that exactly one source is declared and that Git is pinned. + pub fn validate(&self, name: &str) -> Result<(), String> { + match (&self.path, &self.git) { + (Some(_), Some(_)) => Err(format!( + "dependency `{name}` declares both path and git; choose one" + )), + (None, None) => Err(format!( + "dependency `{name}` must declare a path or a pinned git source" + )), + (None, Some(_)) if self.rev.is_none() => Err(format!( + "dependency `{name}` uses git without an exact rev; pin the revision for reproducible builds" + )), + (Some(path), None) if path.is_absolute() => Err(format!( + "dependency `{name}` path must be project-relative" + )), + _ => Ok(()), + } + } +} + +/// Capability requests. Requests are not grants: the host decides. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct CapabilityRequests { + /// File system requests. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub fs: Option, + /// Allowed network hosts (empty means none). + #[serde(default)] + pub net: Option, + /// May the project request process execution. + #[serde(default)] + pub process: Option, +} + +/// File system capability requests. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct FsRequests { + /// Read globs. + #[serde(default)] + pub read: Vec, + /// Write globs. + #[serde(default)] + pub write: Vec, +} + +/// Network capability requests. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct NetRequests { + /// Allowed hosts. + #[serde(default)] + pub hosts: Vec, +} + +/// The `marqdo.yaml` project manifest. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct Manifest { + /// Project identity. + pub project: ProjectInfo, + /// Dependencies keyed by local name. + #[serde(default)] + pub dependencies: BTreeMap, + /// Plugin requirements keyed by plugin name. + #[serde(default)] + pub plugins: BTreeMap, + /// Capability requests. + #[serde(default)] + pub capabilities: CapabilityRequests, +} + +/// A requested plugin (installation is not authorization). +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct PluginRequirement { + /// Requested version requirement. + pub version: String, +} + +impl Manifest { + /// Parse a manifest from YAML. + pub fn from_yaml(yaml: &str) -> Result { + let manifest: Manifest = serde_yaml::from_str(yaml) + .map_err(|error| format!("invalid {MANIFEST_FILE}: {error}"))?; + manifest.validate()?; + Ok(manifest) + } + + /// Load a manifest from disk. + pub fn load(path: &Path) -> Result { + let yaml = std::fs::read_to_string(path) + .map_err(|error| format!("cannot read {}: {error}", path.display()))?; + Self::from_yaml(&yaml) + } + + /// Validate manifest invariants. + pub fn validate(&self) -> Result<(), String> { + if self.project.name.trim().is_empty() { + return Err("project.name must not be empty".to_string()); + } + if self.project.version.trim().is_empty() { + return Err("project.version must not be empty".to_string()); + } + for (name, dependency) in &self.dependencies { + dependency.validate(name)?; + } + for (name, plugin) in &self.plugins { + if plugin.version.trim().is_empty() { + return Err(format!( + "plugin `{name}` must declare a version requirement" + )); + } + } + Ok(()) + } + + /// Canonical YAML serialization (stable key order, no timestamps). + pub fn to_yaml(&self) -> String { + serde_yaml::to_string(self).unwrap_or_default() + } + + /// Minimal manifest used by `marqdo init`. + pub fn template(project_name: &str) -> Self { + Self { + project: ProjectInfo { + name: project_name.to_string(), + version: "0.1.0".to_string(), + marqdo: Some(">=0.1,<1".to_string()), + }, + dependencies: BTreeMap::new(), + plugins: BTreeMap::new(), + capabilities: CapabilityRequests::default(), + } + } +} + +/// One pinned dependency entry in `marqdo.lock`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct LockedPackage { + /// Local dependency name. + pub name: String, + /// Source description (`path:...` or `git:...@rev`). + pub source: String, + /// SHA-256 of the resolved module tree, when computable. + #[serde(skip_serializing_if = "Option::is_none")] + pub sha256: Option, +} + +/// The `marqdo.lock` lockfile. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct LockFile { + /// Lock format version. + pub lock_version: u32, + /// Locked packages in deterministic order. + pub packages: Vec, +} + +impl Default for LockFile { + fn default() -> Self { + Self { + lock_version: 1, + packages: Vec::new(), + } + } +} + +impl LockFile { + /// Parse a lockfile. + pub fn from_yaml(yaml: &str) -> Result { + let mut lock: LockFile = + serde_yaml::from_str(yaml).map_err(|error| format!("invalid {LOCK_FILE}: {error}"))?; + if lock.lock_version != 1 { + return Err(format!( + "unsupported lock_version {} (expected 1)", + lock.lock_version + )); + } + lock.packages.sort_by(|a, b| a.name.cmp(&b.name)); + Ok(lock) + } + + /// Load a lockfile from disk. + pub fn load(path: &Path) -> Result { + let yaml = std::fs::read_to_string(path) + .map_err(|error| format!("cannot read {}: {error}", path.display()))?; + Self::from_yaml(&yaml) + } + + /// Canonical YAML serialization: sorted packages, no absolute paths or + /// timestamps, so repeated `lock` runs are byte-identical. + pub fn to_yaml(&self) -> String { + let mut sorted = self.clone(); + sorted.packages.sort_by(|a, b| a.name.cmp(&b.name)); + serde_yaml::to_string(&sorted).unwrap_or_default() + } + + /// Find a locked package by name. + pub fn package(&self, name: &str) -> Option<&LockedPackage> { + self.packages.iter().find(|package| package.name == name) + } +} + +/// Discover the project root by walking up from `start` to the nearest +/// directory containing `marqdo.yaml`. +pub fn discover_root(start: &Path) -> Option { + let mut current = if start.is_dir() { + start.to_path_buf() + } else { + start.parent()?.to_path_buf() + }; + loop { + if current.join(MANIFEST_FILE).is_file() { + return Some(current); + } + let parent = current.parent()?.to_path_buf(); + if parent == current { + return None; + } + current = parent; + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const MANIFEST: &str = r#" +project: + name: example + version: 0.1.0 +dependencies: + geometry: + path: ./packages/geometry + quantum: + git: https://github.com/example/quantum-mq + rev: 0123456789abcdef0123456789abcdef01234567 +capabilities: + fs: + read: ["./data/**"] + write: ["./output/**"] + net: + hosts: [] + process: false +"#; + + #[test] + fn parses_manifest_and_validates_sources() { + let manifest = Manifest::from_yaml(MANIFEST).unwrap(); + assert_eq!(manifest.project.name, "example"); + assert_eq!(manifest.dependencies.len(), 2); + let read = &manifest.capabilities.fs.as_ref().unwrap().read; + assert_eq!(read, &vec!["./data/**".to_string()]); + assert_eq!(manifest.capabilities.process, Some(false)); + } + + #[test] + fn git_dependency_requires_rev() { + let yaml = "project:\n name: p\n version: 0.1.0\ndependencies:\n x:\n git: https://example/x\n"; + let error = Manifest::from_yaml(yaml).unwrap_err(); + assert!(error.contains("rev")); + } + + #[test] + fn lockfile_serialization_is_stable_and_sorted() { + let lock = LockFile { + lock_version: 1, + packages: vec![ + LockedPackage { + name: "z".into(), + source: "path:z".into(), + sha256: None, + }, + LockedPackage { + name: "a".into(), + source: "path:a".into(), + sha256: Some("abc".into()), + }, + ], + }; + let a = lock.to_yaml(); + let b = lock.to_yaml(); + assert_eq!(a, b); + assert!(a.find("name: a").unwrap() < a.find("name: z").unwrap()); + let parsed = LockFile::from_yaml(&a).unwrap(); + assert_eq!(parsed.packages.len(), 2); + } + + #[test] + fn rejects_absolute_dependency_paths() { + let yaml = "project:\n name: p\n version: 0.1.0\ndependencies:\n x:\n path: /tmp/x\n"; + assert!(Manifest::from_yaml(yaml).is_err()); + } + + #[test] + fn discovers_project_root() { + let dir = tempfile::tempdir().unwrap(); + let nested = dir.path().join("a/b"); + std::fs::create_dir_all(&nested).unwrap(); + std::fs::write( + dir.path().join(MANIFEST_FILE), + "project:\n name: p\n version: 0.1.0\n", + ) + .unwrap(); + assert_eq!( + discover_root(&nested).unwrap(), + dir.path() + .canonicalize() + .unwrap_or_else(|_| dir.path().to_path_buf()) + ); + assert!(discover_root(Path::new("/")).is_none()); + } +}