use std::collections::{BTreeMap, HashMap};
use std::fs;
use std::path::{Path, PathBuf};
use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize};
use thiserror::Error;
use crate::diagnostics::{
Diagnostic, DiagnosticCode, DiagnosticEntity, DiagnosticPath, DiagnosticSource, Severity,
};
use crate::documents::AuthoredFormat;
use crate::ir::SourceSpan;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct WorkspaceConfiguration {
pub project: ProjectConfiguration,
#[serde(default, skip_serializing_if = "PresentationDefaults::is_default")]
pub presentation: PresentationDefaults,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub repositories: Vec<RepositoryConfiguration>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub components: Vec<crate::components::ComponentConfiguration>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub packages: Vec<PackageConfiguration>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub package_bundles: Vec<PackageBundleConfiguration>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub content: Vec<ContentConfiguration>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub concepts: Vec<ConceptConfiguration>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub relationships: Vec<RelationshipConfiguration>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PackageBundleConfiguration {
pub package: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub path: Option<PathBuf>,
#[serde(
rename = "github-release",
default,
skip_serializing_if = "Option::is_none"
)]
pub github_release: Option<GitHubBundleRelease>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub mount: Option<String>,
#[serde(rename = "local-override", default, skip_serializing_if = "is_false")]
pub local_override: bool,
}
fn is_false(value: &bool) -> bool {
!value
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GitHubBundleRelease {
pub repository: String,
pub tag: String,
pub asset: String,
pub revision: String,
pub sha256: String,
}
pub(crate) fn valid_package_mount(path: &str) -> bool {
path.split('/').all(|part| {
!part.is_empty()
&& part
.bytes()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, b'-' | b'_'))
}) && !matches!(
path.split('/').next(),
Some("assets" | "__diplodocus" | "_redirects")
)
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct ProjectConfiguration {
pub name: String,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case", deny_unknown_fields)]
pub struct PresentationDefaults {
#[serde(skip_serializing_if = "Vec::is_empty")]
pub assets: Vec<SiteAsset>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub icons: Vec<SiteIcon>,
pub title: Option<String>,
pub description: Option<String>,
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
pub pages: BTreeMap<String, PageMetadata>,
#[serde(skip_serializing_if = "Option::is_none")]
pub home: Option<HomeDefaults>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub sections: Vec<NavigationSection>,
#[serde(skip_serializing_if = "HeaderDefaults::is_default")]
pub header: HeaderDefaults,
#[serde(skip_serializing_if = "Option::is_none")]
pub sidebar: Option<SidebarConfiguration>,
#[serde(skip_serializing_if = "Option::is_none")]
pub logo: Option<LogoDefaults>,
#[serde(skip_serializing_if = "Option::is_none")]
pub open_graph: Option<OpenGraphDefaults>,
#[serde(
deserialize_with = "deserialize_site_url",
skip_serializing_if = "Option::is_none"
)]
pub site_url: Option<String>,
#[serde(skip_serializing_if = "CanonicalUrlStyle::is_default")]
pub canonical_url_style: CanonicalUrlStyle,
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
pub redirects: BTreeMap<String, DiagnosticPath>,
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
pub fragment_aliases: BTreeMap<String, BTreeMap<String, FragmentAliasTarget>>,
#[serde(skip_serializing_if = "FooterDefaults::is_default")]
pub footer: FooterDefaults,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case", deny_unknown_fields)]
pub struct HeaderDefaults {
#[serde(skip_serializing_if = "ApiNavigation::is_default")]
pub api: ApiNavigation,
#[serde(skip_serializing_if = "Option::is_none")]
pub repositories: Option<Vec<String>>,
}
impl HeaderDefaults {
fn is_default(&self) -> bool {
self == &Self::default()
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ApiNavigation {
Links,
#[default]
Dropdown,
}
impl ApiNavigation {
fn is_default(&self) -> bool {
*self == Self::default()
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub enum FragmentAliasTarget {
Heading(String),
Anchor(String),
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case", deny_unknown_fields)]
pub struct PageMetadata {
#[serde(skip_serializing_if = "Option::is_none")]
pub title: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct SiteAsset {
pub repository: String,
pub path: DiagnosticPath,
pub publish: DiagnosticPath,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct SiteIcon {
pub path: DiagnosticPath,
#[serde(default)]
pub rel: SiteIconRel,
#[serde(default, rename = "type", skip_serializing_if = "Option::is_none")]
pub media_type: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub sizes: Option<String>,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum SiteIconRel {
#[default]
Icon,
AppleTouchIcon,
Manifest,
}
impl SiteIconRel {
pub(crate) fn as_str(self) -> &'static str {
match self {
Self::Icon => "icon",
Self::AppleTouchIcon => "apple-touch-icon",
Self::Manifest => "manifest",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum SidebarConfiguration {
Single(Vec<SidebarItem>),
Multiple(BTreeMap<String, Vec<SidebarItem>>),
}
impl SidebarConfiguration {
pub(crate) fn for_route(&self, route: &str) -> Option<(&str, &[SidebarItem])> {
match self {
Self::Single(items) => Some(("/", items)),
Self::Multiple(sidebars) => sidebars
.iter()
.filter(|(prefix, _)| route.starts_with(prefix.trim_start_matches('/')))
.max_by_key(|(prefix, _)| prefix.len())
.map(|(prefix, items)| (prefix.as_str(), items.as_slice())),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct SidebarItem {
pub text: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub link: Option<DiagnosticPath>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub items: Vec<SidebarItem>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub collapsed: Option<bool>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct NavigationSection {
pub label: String,
pub path: DiagnosticPath,
}
impl NavigationSection {
pub(crate) fn prefix(&self) -> &str {
self.path.as_str().strip_suffix("index.html").unwrap_or("")
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct HomeDefaults {
pub tagline: String,
pub description: String,
pub guide: DiagnosticPath,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub actions: Vec<HomeAction>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub features: Vec<HomeFeature>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct HomeAction {
pub label: String,
#[serde(flatten)]
pub target: HomeActionTarget,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub icon: Option<HomeActionIcon>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum HomeActionTarget {
Path(DiagnosticPath),
Url(#[serde(deserialize_with = "deserialize_external_url")] String),
}
impl<'de> Deserialize<'de> for HomeAction {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
#[derive(Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
struct Declaration {
label: String,
path: Option<DiagnosticPath>,
url: Option<String>,
icon: Option<HomeActionIcon>,
}
let declaration = Declaration::deserialize(deserializer)?;
let target = match (declaration.path, declaration.url) {
(Some(path), None) => HomeActionTarget::Path(path),
(None, Some(url)) => {
validate_external_url(&url).map_err(D::Error::custom)?;
HomeActionTarget::Url(url)
}
_ => {
return Err(D::Error::custom(
"homepage actions require exactly one of path or url",
));
}
};
Ok(Self {
label: declaration.label,
target,
icon: declaration.icon,
})
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum HomeActionIcon {
ArrowRight,
BookOpen,
Code,
Download,
Terminal,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct HomeFeature {
pub title: String,
pub description: String,
pub path: DiagnosticPath,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct LogoDefaults {
pub repository: String,
pub path: DiagnosticPath,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct OpenGraphDefaults {
pub repository: String,
pub path: DiagnosticPath,
pub alt: String,
}
impl PresentationDefaults {
fn is_default(&self) -> bool {
self == &Self::default()
}
pub(crate) fn site_base_url(&self) -> Result<Option<url::Url>, &'static str> {
self.site_url.as_deref().map(parse_site_url).transpose()
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case", deny_unknown_fields)]
pub struct FooterDefaults {
#[serde(skip_serializing_if = "Option::is_none")]
pub docs_version: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub copyright: Option<String>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub licenses: Vec<FooterLink>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub links: Vec<FooterLink>,
#[serde(deserialize_with = "deserialize_boolean")]
pub built_with: bool,
}
impl FooterDefaults {
fn is_default(&self) -> bool {
self == &Self::default()
}
}
fn deserialize_boolean<'de, D: Deserializer<'de>>(deserializer: D) -> Result<bool, D::Error> {
struct BooleanVisitor;
impl<'de> serde::de::Visitor<'de> for BooleanVisitor {
type Value = bool;
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("a boolean")
}
fn visit_bool<E: serde::de::Error>(self, value: bool) -> Result<bool, E> {
Ok(value)
}
}
deserializer.deserialize_any(BooleanVisitor)
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct FooterLink {
pub label: String,
#[serde(deserialize_with = "deserialize_external_url")]
pub url: String,
}
fn deserialize_external_url<'de, D: Deserializer<'de>>(
deserializer: D,
) -> Result<String, D::Error> {
let value = String::deserialize(deserializer)?;
validate_external_url(&value).map_err(D::Error::custom)?;
Ok(value)
}
fn validate_external_url(value: &str) -> Result<(), &'static str> {
let invalid =
"external links must use absolute HTTP or HTTPS URLs without credentials or whitespace";
let url = url::Url::parse(value).map_err(|_| invalid)?;
let authority = value
.split_once("://")
.map(|(_, rest)| rest.split(['/', '?', '#']).next().unwrap_or_default())
.ok_or(invalid)?;
if !matches!(url.scheme(), "http" | "https")
|| url.host_str().is_none()
|| authority.is_empty()
|| authority.contains('@')
|| value
.chars()
.any(|ch| ch.is_whitespace() || ch.is_control())
{
return Err(invalid);
}
Ok(())
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum CanonicalUrlStyle {
#[default]
File,
Clean,
}
impl CanonicalUrlStyle {
fn is_default(&self) -> bool {
*self == Self::default()
}
}
fn deserialize_site_url<'de, D: Deserializer<'de>>(
deserializer: D,
) -> Result<Option<String>, D::Error> {
let value = Option::<String>::deserialize(deserializer)?;
if let Some(value) = &value {
parse_site_url(value).map_err(D::Error::custom)?;
}
Ok(value)
}
fn parse_site_url(value: &str) -> Result<url::Url, &'static str> {
let invalid = "presentation.site-url must be an absolute HTTP or HTTPS URL without credentials, query parameters, fragments, or whitespace";
if value
.chars()
.any(|ch| ch.is_whitespace() || ch.is_control())
{
return Err(invalid);
}
let mut url = url::Url::parse(value).map_err(|_| invalid)?;
let authority = value
.split_once("://")
.map(|(_, rest)| rest.split(['/', '?', '#']).next().unwrap_or_default())
.ok_or(invalid)?;
if !matches!(url.scheme(), "http" | "https")
|| url.host_str().is_none()
|| authority.is_empty()
|| authority.contains('@')
|| url.query().is_some()
|| url.fragment().is_some()
{
return Err(invalid);
}
if !url.path().ends_with('/') {
url.set_path(&format!("{}/", url.path()));
}
Ok(url)
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct RepositoryConfiguration {
pub id: String,
pub path: PathBuf,
#[serde(skip_serializing_if = "Option::is_none")]
pub url: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub source_link_template: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub revision: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct PackageConfiguration {
pub id: String,
pub name: String,
pub slug: String,
pub ecosystem: String,
pub repository: String,
pub path: PathBuf,
pub metadata_path: PathBuf,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub overview: Option<PathBuf>,
#[serde(default, skip_serializing_if = "IncrementalConfiguration::is_default")]
pub incremental: IncrementalConfiguration,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub r: Option<RPackageConfiguration>,
#[serde(default)]
pub kind: PackageKind,
#[serde(default)]
pub visibility: PackageVisibility,
pub targets: Vec<ExtractionTargetConfiguration>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case", deny_unknown_fields)]
pub struct RPackageConfiguration {
pub documentation: RDocumentationMode,
pub extra_inputs: Vec<PathBuf>,
pub generated_outputs: Vec<PathBuf>,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum RDocumentationMode {
#[default]
Auto,
Roxygen2,
Rd,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case", deny_unknown_fields)]
pub struct IncrementalConfiguration {
pub cache: IncrementalCache,
pub depends_on: Vec<String>,
pub extra_inputs: Vec<PathBuf>,
pub environment_variables: Vec<String>,
}
impl IncrementalConfiguration {
pub(crate) fn is_default(&self) -> bool {
self == &Self::default()
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum IncrementalCache {
#[default]
Auto,
Off,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PackageKind {
#[default]
Package,
Component,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PackageVisibility {
#[default]
Public,
Internal,
Hidden,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct ExtractionTargetConfiguration {
pub id: String,
pub extractor: String,
pub path: PathBuf,
pub role: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub rust: Option<RustTargetConfiguration>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub julia: Option<JuliaTargetConfiguration>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case", deny_unknown_fields)]
pub struct JuliaTargetConfiguration {
pub extensions: Vec<PathBuf>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case", deny_unknown_fields)]
pub struct RustTargetConfiguration {
pub features: Vec<String>,
#[serde(deserialize_with = "deserialize_boolean")]
pub default_features: bool,
}
impl Default for RustTargetConfiguration {
fn default() -> Self {
Self {
features: Vec::new(),
default_features: true,
}
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ContentNavigation {
#[default]
All,
Index,
None,
}
impl ContentNavigation {
pub(crate) fn is_default(&self) -> bool {
*self == Self::All
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct ContentConfiguration {
pub id: String,
pub owner: String,
pub repository: String,
pub path: PathBuf,
pub mount: String,
pub format: AuthoredFormat,
#[serde(default, skip_serializing_if = "ContentNavigation::is_default")]
pub navigation: ContentNavigation,
#[serde(default, skip_serializing_if = "IncrementalConfiguration::is_default")]
pub incremental: IncrementalConfiguration,
#[serde(default)]
pub execution: ExecutionConfiguration,
}
impl<'de> Deserialize<'de> for ContentConfiguration {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
#[derive(Default, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
struct ExecutionDeclaration {
mode: Option<ExecutionMode>,
engine: Option<ExecutionEngine>,
kernel: Option<String>,
julia_project: Option<PathBuf>,
#[serde(default)]
declared_environment_inputs: Vec<PathBuf>,
}
#[derive(Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
struct Declaration {
id: String,
owner: String,
repository: String,
path: PathBuf,
mount: String,
format: AuthoredFormat,
#[serde(default)]
navigation: ContentNavigation,
#[serde(default)]
incremental: IncrementalConfiguration,
#[serde(default)]
execution: Option<ExecutionDeclaration>,
}
let declaration = Declaration::deserialize(deserializer)?;
let collection = Self {
id: declaration.id,
owner: declaration.owner,
repository: declaration.repository,
path: declaration.path,
mount: declaration.mount,
format: declaration.format,
navigation: declaration.navigation,
incremental: declaration.incremental,
execution: {
let execution = declaration.execution.unwrap_or_default();
let rmd = declaration.format == AuthoredFormat::Rmd;
ExecutionConfiguration {
mode: execution.mode.unwrap_or(if rmd {
ExecutionMode::Execute
} else {
ExecutionMode::Never
}),
engine: execution.engine.or(if rmd {
Some(ExecutionEngine::Knitr)
} else {
None
}),
kernel: execution.kernel,
julia_project: execution.julia_project,
declared_environment_inputs: execution.declared_environment_inputs,
}
},
};
collection
.validate_execution()
.map_err(|error| D::Error::custom(format!("content `{}`: {error}", collection.id)))?;
Ok(collection)
}
}
impl ContentConfiguration {
pub fn validate_execution(&self) -> Result<(), ExecutionConfigurationError> {
let execution = &self.execution;
if execution.julia_project.is_some()
&& !(self.format == AuthoredFormat::Documenter
&& execution.mode == ExecutionMode::Execute
&& execution.engine == Some(ExecutionEngine::Julia))
{
return Err(ExecutionConfigurationError::JuliaProject);
}
if self.format == AuthoredFormat::Rmd
&& (execution.mode != ExecutionMode::Execute
|| execution.engine != Some(ExecutionEngine::Knitr)
|| execution.kernel.is_some())
{
return Err(ExecutionConfigurationError::RmdExecution);
}
if execution.mode == ExecutionMode::Never {
for (field, declared) in [
("engine", execution.engine.is_some()),
("kernel", execution.kernel.is_some()),
(
"declared-environment-inputs",
!execution.declared_environment_inputs.is_empty(),
),
] {
if declared {
return Err(ExecutionConfigurationError::InactiveSetting { field });
}
}
return Ok(());
}
if self.format == AuthoredFormat::Gfm {
return Err(ExecutionConfigurationError::GfmExecution);
}
if self.format == AuthoredFormat::Documenter
&& (execution.engine != Some(ExecutionEngine::Julia)
|| execution.kernel.is_some()
|| execution.julia_project.is_none())
{
return Err(ExecutionConfigurationError::DocumenterExecution);
}
if let Some(project) = &execution.julia_project {
environment_input_components(project)
.map_err(|_| ExecutionConfigurationError::JuliaProject)?;
if !matches!(
project.file_name().and_then(|name| name.to_str()),
Some("Project.toml" | "JuliaProject.toml")
) {
return Err(ExecutionConfigurationError::JuliaProject);
}
}
if self.format == AuthoredFormat::Qmd {
if execution.engine != Some(ExecutionEngine::Jupyter) {
return Err(ExecutionConfigurationError::MissingEngine);
}
let kernel = execution
.kernel
.as_deref()
.ok_or(ExecutionConfigurationError::MissingKernel)?;
if !valid_kernel_selector(kernel) {
return Err(ExecutionConfigurationError::InvalidKernel);
}
}
let mut inputs = HashMap::new();
for (index, path) in execution.declared_environment_inputs.iter().enumerate() {
let components = environment_input_components(path).map_err(|reason| {
ExecutionConfigurationError::InvalidEnvironmentInput { index, reason }
})?;
if let Some(first_index) = inputs.insert(components, index) {
return Err(ExecutionConfigurationError::DuplicateEnvironmentInput {
index,
first_index,
});
}
}
Ok(())
}
}
pub(crate) fn valid_kernel_selector(kernel: &str) -> bool {
!kernel.is_empty()
&& !matches!(kernel, "." | "..")
&& kernel
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'.' | b'_'))
}
fn environment_input_components(path: &Path) -> Result<Vec<&str>, &'static str> {
let path = path.to_str().ok_or("paths must be valid UTF-8")?;
if path.is_empty() {
return Err("paths must not be empty");
}
if path.starts_with('/')
|| (path.as_bytes().get(1) == Some(&b':') && path.as_bytes()[0].is_ascii_alphabetic())
{
return Err("paths must be relative to the collection's repository");
}
if path.contains('\\') {
return Err("paths must use forward-slash separators");
}
if path.contains('\0') {
return Err("paths must not contain NUL bytes");
}
if path.contains(['*', '?', '[', ']', '{', '}']) {
return Err("declare individual files, not glob patterns");
}
if matches!(path.rsplit('/').next(), Some("" | "." | "..")) {
return Err("declare a file, not a directory reference");
}
let mut components = Vec::new();
for component in path.split('/') {
match component {
"" | "." => {}
".." => {
if components.pop().is_none() {
return Err("paths must not escape the collection's repository");
}
}
component => components.push(component),
}
}
Ok(components)
}
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum ExecutionConfigurationError {
#[error("R Markdown requires `mode: execute`, `engine: knitr`, and no kernel")]
RmdExecution,
#[error("`{field}` requires `mode: execute`")]
InactiveSetting {
field: &'static str,
},
#[error("`mode: execute` requires `format: qmd`")]
GfmExecution,
#[error(
"Documenter execution requires `engine: julia`, `julia-project: path/to/Project.toml`, and no kernel"
)]
DocumenterExecution,
#[error(
"`julia-project` must name a repository-relative Project.toml or JuliaProject.toml for Documenter execution with `engine: julia`"
)]
JuliaProject,
#[error("`mode: execute` requires `engine: jupyter`")]
MissingEngine,
#[error("`mode: execute` requires an explicit kernel")]
MissingKernel,
#[error(
"invalid kernel selector: use ASCII letters, digits, `-`, `.`, or `_`, excluding empty names, `.` and `..`"
)]
InvalidKernel,
#[error("invalid `declared-environment-inputs[{index}]`: {reason}")]
InvalidEnvironmentInput {
index: usize,
reason: &'static str,
},
#[error("`declared-environment-inputs[{index}]` duplicates input {first_index}")]
DuplicateEnvironmentInput {
index: usize,
first_index: usize,
},
}
impl ExecutionConfigurationError {
pub fn to_diagnostic(&self, collection: impl Into<String>) -> Diagnostic {
Diagnostic::new(
DiagnosticCode::InvalidExecutionConfiguration,
Severity::Error,
self.to_string(),
)
.with_entity(DiagnosticEntity::Content {
id: collection.into(),
})
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct ExecutionConfiguration {
#[serde(default)]
pub mode: ExecutionMode,
#[serde(skip_serializing_if = "Option::is_none")]
pub engine: Option<ExecutionEngine>,
#[serde(skip_serializing_if = "Option::is_none")]
pub kernel: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub julia_project: Option<PathBuf>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub declared_environment_inputs: Vec<PathBuf>,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ExecutionMode {
#[default]
Never,
Execute,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ExecutionEngine {
Jupyter,
Knitr,
Julia,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct ConceptConfiguration {
pub id: String,
pub kind: ConceptKind,
pub members: Vec<ConceptMember>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ConceptKind {
Equivalent,
Analogous,
Related,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct ConceptMember {
pub package: String,
pub item: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", deny_unknown_fields)]
pub struct RelationshipConfiguration {
pub from: String,
pub to: String,
pub kind: RelationshipKind,
#[serde(skip_serializing_if = "Option::is_none")]
pub version_constraint: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub provenance: Option<String>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum RelationshipKind {
DependsOn,
Binds,
Wraps,
GeneratedFrom,
}
#[derive(Debug, Error)]
pub enum ConfigurationError {
#[error("could not read configuration `{}`: {source}", path.display())]
Read {
path: PathBuf,
source: std::io::Error,
},
#[error("could not parse configuration `{}`: {source}", path.display())]
Parse {
path: PathBuf,
source: Box<serde_saphyr::Error>,
},
}
impl ConfigurationError {
pub fn to_diagnostic(&self, path: DiagnosticPath) -> Diagnostic {
let mut diagnostic = match self {
Self::Read { source, .. } => Diagnostic::new(
DiagnosticCode::ConfigurationReadFailed,
Severity::Error,
format!("could not read configuration: {}", source.kind()),
),
Self::Parse { source, .. } => {
let mut diagnostic = Diagnostic::new(
DiagnosticCode::InvalidConfiguration,
Severity::Error,
source.without_snippet().to_string(),
);
diagnostic.span = source.location().and_then(|location| {
let span = location.span();
let start = usize::try_from(span.byte_offset()?).ok()?;
let length = usize::try_from(span.byte_len()?).ok()?;
Some(SourceSpan {
start,
end: start.checked_add(length)?,
})
});
diagnostic
}
};
diagnostic.source = Some(DiagnosticSource::Configuration { path });
diagnostic.related_entity = Some(DiagnosticEntity::Configuration);
diagnostic
}
}
pub fn parse_configuration(
source: &str,
) -> Result<WorkspaceConfiguration, Box<serde_saphyr::Error>> {
serde_saphyr::from_str_with_options(
source,
serde_saphyr::options! {
no_schema: true,
strict_booleans: true,
},
)
.map_err(Box::new)
}
pub fn load_configuration(
path: impl AsRef<Path>,
) -> Result<WorkspaceConfiguration, ConfigurationError> {
let path = path.as_ref();
let source = fs::read_to_string(path).map_err(|source| ConfigurationError::Read {
path: path.to_owned(),
source,
})?;
parse_configuration(&source).map_err(|source| ConfigurationError::Parse {
path: path.to_owned(),
source,
})
}