instruction-md 0.5.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
//! Specification 1.1 syntax this edition reads differently (`instruction.md/legacy-syntax`): the TypeScript
//! package's `legacyDiagnostics` (its upgrade.ts `legacyLines`), line for line. A 1.1 block `:::!kind{…}` is not a
//! directive here — it reads as prose, and the agent receives it as written — so a reader that delivers a document
//! reports it rather than deliver what its author did not mean. This crate reports; the conversion (`upgrade`) is
//! the TypeScript package's.

use std::sync::LazyLock;

use serde_json::Value;

use crate::js::{JS_DOT, JS_SPACES, js_trim};
use crate::pattern::Pattern;
use crate::types::{Diagnostic, Severity};
use crate::yaml::load_yaml;

/// The code of a line written in Specification 1.1.
pub const LEGACY_SYNTAX: &str = "instruction.md/legacy-syntax";

struct Rx {
    section: Pattern,
    code: Pattern,
    variant: Pattern,
    identity: Pattern,
    param_or_tool: Pattern,
    sigil_link: Pattern,
    parameters: Pattern,
}

static RX: LazyLock<Rx> = LazyLock::new(|| {
    let sp = JS_SPACES;
    let p = |s: &str| Pattern::must(s);
    // (`\b` written out: a word character's neighbour is a non-word character or the line's edge)
    Rx {
        section: p(&format!(
            r"^(#{{1,6}})[ \t]+!([A-Za-z][A-Za-z0-9_-]*)[ \t]+([A-Za-z0-9][A-Za-z0-9._-]*)[{sp}]*(\{{{JS_DOT}*\}})?[{sp}]*#*[{sp}]*$"
        )),
        code: p(r"^ {0,3}(`{3,}|~{3,})"),
        variant: p(r"^:{3,}(?:when|unless|otherwise)(?:[^A-Za-z0-9_]|$)"),
        identity: p(r"^:{2,}[A-Za-z][A-Za-z0-9_-]*\{(?:[^}]*[^}A-Za-z0-9_])?name="),
        param_or_tool: p(r"^:{2,}(?:param|tool)(?:[^A-Za-z0-9_]|$)"),
        sigil_link: p(&format!(
            r"\[([#@&])([^\]]+)\]\(((?:instruction|principal|agent|server|skill|model|service|sandbox|connector)://)([^){sp}]+)\)"
        )),
        parameters: p(r"^parameters[ \t]*:"),
    }
});

/// The lines of a text that use Specification 1.1 syntax, each an error with what it needs, in line order: a sigil
/// block (`:::!kind`, `::!kind`, `## !kind name`), a variant (`:::when`, `:::unless`, `:::otherwise`), a `name=`
/// identity, a sigil reference link (`[@On-call](principal://…)`), a front matter parameter list, and a closed end
/// matter. Fenced code is skipped.
///
/// ```
/// use instruction_md::{legacy_diagnostics, LEGACY_SYNTAX};
///
/// let ds = legacy_diagnostics(":::!policy{name=privacy}\nKeep it private.\n:::\n");
/// assert_eq!(ds[0].code, LEGACY_SYNTAX);
/// assert_eq!(ds[0].line(), Some(1));
/// assert_eq!(ds[0].message, "a Specification 1.1 block: this edition writes a block without `!`, as :::kind{…} or ::kind{…}");
/// ```
pub fn legacy_diagnostics(text: &str) -> Vec<Diagnostic> {
    let rx = &*RX;
    let mut out: Vec<(usize, &'static str)> = Vec::new();
    let lines = js_lines(text);
    // the metadata: a parameter list, and the end matter's closing ---
    let mut body_start = 0;
    if lines.first() == Some(&"---")
        && let Some(close) = lines.iter().skip(1).position(|l| *l == "---").map(|i| i + 1)
    {
        body_start = close + 1;
        let front = load_yaml(&lines[1..close].join("\n"));
        let at = lines.iter().enumerate().position(|(i, l)| i > 0 && i < close && rx.parameters.is_match(l));
        if let (Ok((Value::Object(m), _)), Some(at)) = (front, at)
            && m.get("parameters").is_some_and(Value::is_array)
        {
            out.push((at + 1, "a Specification 1.1 parameter list: this edition declares parameters as a mapping, name: { type: … }"));
        }
    }
    if let Some(close) = closed_end_matter(&lines, body_start) {
        out.push((close + 1, "a Specification 1.1 end matter: this edition's backmatter runs to the end of the file, with no closing ---"));
    }
    let mut code: Option<String> = None;
    for (i, line) in lines.iter().enumerate() {
        if let Some(c) = rx.code.captures(line) {
            let marker = c.get(line, 1).unwrap_or("");
            code = match code {
                None => Some(marker.to_string()),
                Some(open) if js_trim(line).starts_with(open.as_str()) => None,
                Some(open) => Some(open),
            };
            continue;
        }
        if code.is_some() {
            continue;
        }
        let n = i + 1;
        let b = line.as_bytes();
        let colons = b.iter().take_while(|&&c| c == b':').count();
        if colons >= 2 && b.get(colons) == Some(&b'!') || rx.section.is_match(line) {
            out.push((n, "a Specification 1.1 block: this edition writes a block without `!`, as :::kind{…} or ::kind{…}"));
        } else if rx.variant.is_match(line) {
            out.push((n, "a Specification 1.1 variant: this edition delivers every reader the same text"));
        } else if rx.identity.is_match(line) && !rx.param_or_tool.is_match(line) {
            out.push((n, "a Specification 1.1 identity: this edition names a block with id="));
        } else if rx.sigil_link.find(line).is_some() {
            out.push((n, "a Specification 1.1 reference link: this edition writes :person[Label]{ref=…}"));
        }
    }
    out.sort_by_key(|(line, _)| *line);
    out.into_iter()
        .map(|(line, message)| {
            let mut d = Diagnostic::new(LEGACY_SYNTAX, Severity::Error, message, line.min(u32::MAX as usize) as u32);
            d.remedy = "convert the document to this edition".into();
            d
        })
        .collect()
}

/// `text.split(/\r\n|\r|\n/)`: a final line ending leaves an empty last line.
fn js_lines(text: &str) -> Vec<&str> {
    let mut out = Vec::new();
    let b = text.as_bytes();
    let (mut start, mut i) = (0, 0);
    while i < b.len() {
        match b[i] {
            b'\n' => {
                out.push(&text[start..i]);
                start = i + 1;
            }
            b'\r' => {
                out.push(&text[start..i]);
                if b.get(i + 1) == Some(&b'\n') {
                    i += 1;
                }
                start = i + 1;
            }
            _ => {}
        }
        i += 1;
    }
    out.push(&text[start..]);
    out
}

/// A 1.1 end matter: a `---` line after a blank line, a YAML mapping, and a `---` that closes it as the text's last
/// line with text; its closing line (0-based), or none.
fn closed_end_matter(lines: &[&str], body_start: usize) -> Option<usize> {
    let mut last = lines.len().checked_sub(1)?;
    while js_trim(lines[last]).is_empty() {
        if last <= body_start {
            return None;
        }
        last -= 1;
    }
    if last <= body_start || lines[last] != "---" {
        return None;
    }
    for i in (body_start + 1..last).rev() {
        if lines[i] != "---" {
            continue;
        }
        if !js_trim(lines[i - 1]).is_empty() || i + 1 == last {
            return None;
        }
        return match load_yaml(&lines[i + 1..last].join("\n")) {
            Ok((Value::Object(_), _)) => Some(last),
            _ => None,
        };
    }
    None
}