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
//! **instruction-md** — the instruction.md specification's first edition (`instruction/1`) in Rust: the reader and
//! its checks, the inline syntax, composition into the resolved artifact and the agent's text, the registry, the
//! formatter, digests and signature verification.
//!
//! It is a port of the Go SDK (`sdks/go`), itself a port of the TypeScript reference (`@instruction-md/spec`), held to
//! them by the specification's conformance cases and the reference's vectors.
//!
//! ```
//! use instruction_md::{read, ReadOptions, check_reading};
//!
//! let doc = "---\nspec: \"1\"\nparameters:\n  tz: { type: string, default: UTC }\n---\n\
//!            MUST: plan the day in ${tz}.\nBECAUSE: the owner reads the brief at 7.\n";
//! let r = read(doc, &ReadOptions::default());
//! assert!(check_reading(&r).is_empty());
//! assert_eq!(r.text(None), "MUST: plan the day in UTC.\nBECAUSE: the owner reads the brief at 7.\n");
//! ```
//!
//! Every function takes untrusted text: none panics, and every problem is a [`Diagnostic`] with a stable code.
//!
//! Cargo features: `verify` (default) is signature verification (`verify_author`, `verify_delivery`) and signing
//! for tests and tooling, by `ring`; without it the crate depends on `serde` and `serde_json` alone.
#![forbid(unsafe_code)]

pub mod allowance;
pub mod attributes;
pub mod bindings;
pub mod check;
pub mod digest;
pub mod inline;
pub mod jcs;
mod js;
pub mod legacy;
pub mod lines;
pub mod objects;
pub mod pattern;
pub mod policy;
pub mod protocol;
pub mod read;
pub mod registry;
pub mod resolve;
pub mod text;
pub mod types;
#[cfg(feature = "verify")]
pub mod verify;
pub mod workflow;
pub mod yaml;

pub use attributes::parse_attributes;
pub use check::{Target, check, check_reading, inline_diagnostics, resolve_target, workflows_diagnostics};
pub use digest::{author_digest, digest, digest_text, front_matter_id, sha256_hex};
pub use inline::{InlineToken, TokenType, inline_tokens, split_wiki};
pub use jcs::{canonical_json, json_digest};
pub use js::js_number;
pub use legacy::{LEGACY_SYNTAX, legacy_diagnostics};
pub use lines::{LineInfo, classify_lines, format};
pub use objects::{
    ConfigurationBlock, ConnectedObject, Location, carries_configuration, configuration_blocks, connected_objects, is_connected, is_layout,
    walk,
};
pub use pattern::Pattern;
pub use policy::{
    AUTHOR_POLICY_KEY, HOST_POLICY_KEY, INTEGRATED_KINDS, LayerProblem, NamedTools, Policy, PolicyFrom, PolicyLayer, ServerPolicy,
    ServerTools, ToolDefault, authored_candidates, host_block, layer_of, merge_policy, named_tools, normalize_target, remote_targets,
    with_host_block,
};
pub use read::{ReadOptions, Reading, SplitBackmatter, Stripped, read, split_backmatter, strip_comments, value_fits, value_from};
pub use registry::{AttrSpec, KindSpec, Registry, all_families, attr_spec, canonical_kind, inline_attr_spec, is_rule, registry};
pub use resolve::{
    Dependency, ExtensionBinding, Loader, Manifest, Provenance, RESOLVED_FORMAT, Resolution, ResolveOptions, Resolved, ResolvedDocument,
    Selector, Source, references_of, resolve, resolve_tree, resolve_uri, resolve_with, slug,
};
pub use text::{Known, ReferenceRecord, TextOptions, to_text, value_text};
pub use types::{
    Attrs, Diagnostic, Document, Form, Identity, Metadata, Node, NodeType, Object, Parameter, Range, Severity, StructuredValue, TREE_FORMAT,
};
#[cfg(feature = "verify")]
pub use verify::{
    DeliveryVerifyOptions, Jwk, SigningKey, VERIFY_CODES, VerifyOptions, VerifyResult, public_jwk, sign_jws, verify_author, verify_delivery,
};
pub use workflow::{
    WORKFLOW_DIALECT, WORKFLOW_SCOPES, WorkflowKind, WorkflowLimits, WorkflowRegistry, workflow_diagnostics, workflow_registry,
    workflow_scope,
};
pub use yaml::parse_yaml;

/// The specification commit the vendored registry and conformance data are from.
pub const SPEC_COMMIT: &str = "bf4f9a0";

/// Reads a document and gives its agent text with its declared defaults — the shortcut a runtime needs: the text an
/// agent receives (`instruction-text/1`) and every diagnostic: the reader's, the inline checks', a native workflow's
/// ([`workflows_diagnostics`]) and the lines written in Specification 1.1 ([`legacy_diagnostics`]), as the TypeScript CLI
/// reports them. An error among the diagnostics means the document should not be delivered.
pub fn deliver(text: &str, params: Option<&Object>) -> (String, Vec<Diagnostic>) {
    let r = read(text, &ReadOptions::default());
    let mut diagnostics = check_reading(&r);
    let legacy = legacy_diagnostics(text);
    if !legacy.is_empty() {
        diagnostics.extend(legacy);
        // (stable: by line, the reader's before the 1.1 lines', as the CLI orders them)
        diagnostics.sort_by_key(|d| d.line().unwrap_or(0));
    }
    (r.text(params), diagnostics)
}