mod documenter;
mod references;
mod relationships;
mod workspace;
pub(crate) use documenter::reference as documenter_reference;
pub(crate) use references::in_package as resolve_package_item;
pub use references::resolve_item;
pub(crate) use references::resolve_rd_help;
pub(crate) use relationships::r_versions_equal;
pub(crate) use workspace::document_references;
pub(crate) use workspace::external_url_allowed;
pub use workspace::*;
use crate::configuration::{ContentConfiguration, ExecutionConfigurationError, ExecutionMode};
use crate::diagnostics::{Diagnostic, DiagnosticCode, Severity};
use crate::documents::AuthoredFormat;
use crate::ir::{Document, MetadataEntry, MetadataValue, SourceSpan};
pub fn validate_document_execution(
document: &Document,
collection: &ContentConfiguration,
) -> Result<Vec<Diagnostic>, ExecutionConfigurationError> {
collection.validate_execution()?;
if collection.format == AuthoredFormat::Gfm {
return Ok(Vec::new());
}
let Some(metadata) = &document.frontmatter else {
return Ok(Vec::new());
};
let MetadataValue::Mapping { entries, .. } = metadata else {
let span = match metadata {
MetadataValue::Null { span }
| MetadataValue::Scalar { span, .. }
| MetadataValue::Sequence { span, .. }
| MetadataValue::Unsupported { span, .. }
| MetadataValue::Mapping { span, .. } => *span,
};
return Ok(vec![metadata_error(
DiagnosticCode::InvalidQmdMetadata,
"document metadata must be a mapping".to_owned(),
span,
)]);
};
let mut context = ExecutionAuthority {
authorized: collection.execution.mode == ExecutionMode::Execute,
unauthorized: Vec::new(),
diagnostics: Vec::new(),
};
for entry in entries {
match entry.key.value.as_str() {
"<<" => context.reject_merge(entry),
"jupyter" | "engine" | "kernel" | "execution" => {
context.selector(entry, &entry.key.value);
}
"execute" => match &entry.value {
MetadataValue::Scalar { raw, .. } if raw.trim() == "true" => {
if !context.authorized {
context.unauthorized.push(entry.span);
}
}
MetadataValue::Scalar { raw, .. } if raw.trim() == "false" => {}
MetadataValue::Mapping { entries, .. } => {
for option in entries {
if matches!(option.key.value.as_str(), "mode" | "engine" | "kernel") {
context.selector(option, &format!("execute.{}", option.key.value));
} else if option.key.value == "<<" {
context.reject_merge(option);
}
}
}
_ => context.diagnostics.push(metadata_error(
DiagnosticCode::InvalidQmdMetadata,
"document `execute` must be an unquoted `true`, `false`, or a mapping"
.to_owned(),
entry.span,
)),
},
_ => {}
}
}
context
.unauthorized
.sort_by_key(|span| (span.start, span.end));
if let Some((&span, related_spans)) = context.unauthorized.split_first() {
context.diagnostics.push(Diagnostic {
code: DiagnosticCode::DocumentExecutionNotAuthorized,
severity: Severity::Error,
message: "document metadata cannot authorize execution in a collection with `mode = \"never\"`"
.to_owned(),
span: Some(span),
related_spans: related_spans.to_vec(),
related_entity: None,
source: None,
});
}
context.diagnostics.sort();
Ok(context.diagnostics)
}
struct ExecutionAuthority {
authorized: bool,
unauthorized: Vec<SourceSpan>,
diagnostics: Vec<Diagnostic>,
}
impl ExecutionAuthority {
fn reject_merge(&mut self, entry: &MetadataEntry) {
self.diagnostics.push(metadata_error(
DiagnosticCode::UnsupportedQmdMetadata,
"YAML merge keys cannot define document execution metadata".to_owned(),
entry.span,
));
}
fn selector(&mut self, entry: &MetadataEntry, key: &str) {
if self.authorized {
self.diagnostics.push(metadata_error(
DiagnosticCode::UnsupportedQmdMetadata,
format!("document `{key}` is unsupported; execution selectors belong to the collection configuration"),
entry.span,
));
} else {
self.unauthorized.push(entry.span);
}
}
}
fn metadata_error(code: DiagnosticCode, message: String, span: SourceSpan) -> Diagnostic {
Diagnostic {
code,
severity: Severity::Error,
message,
span: Some(span),
related_spans: Vec::new(),
related_entity: None,
source: None,
}
}