instruction-md 0.3.0

Read, check, resolve and verify instruction.md documents (the specification's first edition, instruction/1): the reader, the agent text, composition and signature verification
Documentation
//! The inline checks (§11.1, §12), over the prose the reader found: an inline kind this specification or the
//! document's extensions do not define, a missing required attribute or label, a typed reference to an id the
//! document does not have or to one of another kind, a citation of a source the backmatter does not record, an
//! undeclared parameter, a footnote without its definition. [`check`] is the reader's diagnostics with these, in
//! source order — what an editor shows and what a renderer reports.

use serde_json::Value;

use crate::attributes::parse_attributes;
use crate::inline::{TokenType, inline_tokens};
use crate::js::{js_trim, truthy};
use crate::read::{ReadOptions, Reading, read, sort_diagnostics};
use crate::registry::{self, inline_attr_spec, inline_required, registry, typed_reference};
use crate::types::{Diagnostic, Severity};

/// Where a typed reference's target is.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Target {
    /// In this document: the id, the kind of what has it, and whether that is the kind the reference says (any, for
    /// ref; any resource kind, for resource).
    Local { id: String, kind: String, matches: bool },
    /// Named as #id, and nothing in this document has it.
    Missing { id: String },
    /// Elsewhere: a named reference's URI, or the reference itself.
    External { uri: String },
}

/// Resolves a typed reference's ref against the document (§11.1): #id, an included #alias/id, a named reference, a
/// URI.
pub fn resolve_target(r: &Reading, kind: &str, reference: &str) -> Target {
    if let Some(id) = reference.strip_prefix('#')
        && !reference.contains('/')
    {
        let Some(found) = r.identity(id) else {
            return Target::Missing { id: id.to_string() };
        };
        let matches = kind == "ref"
            || found.kind == kind
            || kind == "resource" && registry::kind(&found.kind).is_some_and(|k| k.family == "resource");
        return Target::Local { id: id.to_string(), kind: found.kind.clone(), matches };
    }
    let named =
        r.document.metadata.front.get("references").and_then(|refs| refs.get(reference)).and_then(|n| n.get("uri")).and_then(Value::as_str);
    Target::External { uri: named.unwrap_or(reference).to_string() }
}

/// A document's diagnostics: the reader's and the inline checks', in source order.
pub fn check(text: &str, opts: &ReadOptions) -> Vec<Diagnostic> {
    check_reading(&read(text, opts))
}

/// [`check`] of a document already read.
pub fn check_reading(r: &Reading) -> Vec<Diagnostic> {
    let mut out = r.diagnostics.clone();
    out.extend(inline_diagnostics(r));
    out.extend(workflows_diagnostics(r));
    sort_diagnostics(&mut out, false);
    out
}

/// Each `:::workflow{dialect="instruction/workflow"}` body's diagnostics ([`crate::workflow`]), in document order:
/// its parsed YAML or JSON (the reader reports a body that doesn't parse or isn't a mapping), placed on the body's
/// lines. Another dialect is its own.
pub fn workflows_diagnostics(r: &Reading) -> Vec<Diagnostic> {
    let mut out = Vec::new();
    let extensions = r.document.metadata.front.get("extensions").and_then(Value::as_object);
    crate::objects::walk(&r.document.body, &mut |n, _| {
        if n.kind == "workflow"
            && crate::js::is_str(n.attrs.get("dialect"), crate::workflow::WORKFLOW_DIALECT)
            && let (Some(data), Some(range)) = (n.value.as_ref().and_then(|v| v.data.as_ref()), n.range)
        {
            // the body's lines: between the opener and the closing fence (which an unclosed container lacks)
            let (start, end) = (range.start as usize, range.end as usize);
            let closed = end > start && r.lines.get(end - 1).is_some_and(|l| is_closing_fence(l));
            let last = if closed { end - 1 } else { end };
            let lines: Vec<(u32, &str)> = r
                .lines
                .get(start..last.min(r.lines.len()))
                .unwrap_or(&[])
                .iter()
                .enumerate()
                .map(|(i, t)| ((start + 1 + i) as u32, t.as_str()))
                .collect();
            let at = lines.first().map_or(range.start, |l| l.0);
            out.extend(crate::workflow::check(data, &lines, at, extensions));
        }
        true
    });
    out
}

/// `^:{3,}[ \t]*$`
fn is_closing_fence(l: &str) -> bool {
    let rest = l.trim_start_matches(':');
    l.len() - rest.len() >= 3 && rest.bytes().all(|b| b == b' ' || b == b'\t')
}

/// The inline checks' diagnostics, prose node by prose node.
pub fn inline_diagnostics(r: &Reading) -> Vec<Diagnostic> {
    let mut out = Vec::new();
    let front = &r.document.metadata.front;
    let extensions = front.get("extensions").and_then(Value::as_object);
    let sources: Vec<&str> = match r.document.metadata.back.get("sources") {
        Some(Value::Array(list)) => list.iter().filter_map(|s| s.get("id").and_then(Value::as_str)).collect(),
        _ => Vec::new(),
    };
    for node in &r.prose_order {
        let breaks: Vec<usize> = node.source.match_indices('\n').map(|(i, _)| i).collect();
        for t in inline_tokens(&node.source) {
            // the node's first line plus the line breaks before the token
            let at = node.range.map_or(1, |rg| rg.start) + breaks.partition_point(|&b| b < t.start) as u32;
            let mut diag = |code: &'static str, severity: Severity, message: String| out.push(Diagnostic::new(code, severity, message, at));
            match t.token_type {
                TokenType::Param => {
                    if r.parameter(&t.name).is_none() {
                        diag(
                            "parameter-optional",
                            Severity::Warning,
                            format!("${{{}}} is not a declared parameter, so it stays as written", t.name),
                        );
                    }
                    continue;
                }
                TokenType::Footnote => {
                    if !r.footnotes.contains_key(&t.label) {
                        diag(
                            "footnote-missing",
                            Severity::Warning,
                            format!("the footnote [^{}] has no definition, so it stays as text", t.label),
                        );
                    }
                    continue;
                }
                TokenType::Directive => {}
                _ => continue,
            }
            let where_ = format!(":{}[…]", t.kind);
            if let Some((alias, _)) = t.kind.split_once(':') {
                if !truthy(extensions.and_then(|e| e.get(alias))) {
                    diag(
                        "extension-unavailable",
                        Severity::Error,
                        format!("{where_}: the extension alias \"{alias}\" is not declared in the front matter's extensions"),
                    );
                }
                continue;
            }
            if !registry().inline.contains_key(&t.kind) {
                diag(
                    "unknown-kind",
                    Severity::Error,
                    format!("{where_} is not an inline kind of this specification; it is kept as written"),
                );
                continue;
            }
            let mut attrs = crate::types::Attrs::new();
            if let Some(list) = &t.attributes {
                let kind = t.kind.clone();
                let spec_of = move |k: &str| inline_attr_spec(&kind, k);
                let (parsed, problems) = parse_attributes(list, &spec_of, true);
                attrs = parsed;
                for p in problems {
                    diag("invalid-attributes", Severity::Error, format!("{where_}: {p}"));
                }
            }
            if let Some(need) = inline_required(&t.kind) {
                match attrs.get(need) {
                    None => diag("invalid-attributes", Severity::Error, format!("{where_} needs {need}=…")),
                    Some(Value::String(s)) if s.is_empty() => {
                        diag("invalid-attributes", Severity::Error, format!("{where_} needs {need}=…"))
                    }
                    _ => {}
                }
            }
            if js_trim(&t.label).is_empty() {
                diag("invalid-attributes", Severity::Error, format!("{where_}: its label is required, the text a reader sees"));
            }
            let reference = match attrs.get("ref") {
                Some(Value::String(s)) if !s.is_empty() => s.clone(),
                _ => continue,
            };
            if t.kind == "cite" {
                if !sources.contains(&reference.as_str()) {
                    diag("reference-optional", Severity::Warning, format!("{where_}: the backmatter's sources record no \"{reference}\""));
                }
                continue;
            }
            if !typed_reference(&t.kind) && t.kind != "ref" {
                continue;
            }
            match resolve_target(r, &t.kind, &reference) {
                Target::Missing { id } => {
                    diag("reference-optional", Severity::Warning, format!("{where_}: nothing in this document has the id \"{id}\""))
                }
                Target::Local { id, kind, matches: false } => {
                    diag("reference-kind", Severity::Error, format!("{where_} names #{id}, which is a {kind}, not a {}", t.kind))
                }
                _ => {}
            }
        }
    }
    out
}