Skip to main content

instruction_md/
lib.rs

1//! **instruction-md** — the instruction.md specification's first edition (`instruction/1`) in Rust: the reader and
2//! its checks, the inline syntax, composition into the resolved artifact and the agent's text, the registry, the
3//! formatter, digests and signature verification.
4//!
5//! It is a port of the Go SDK (`sdks/go`), itself a port of the TypeScript reference (`@instruction-md/spec`), held to
6//! them by the specification's conformance cases and the reference's vectors.
7//!
8//! ```
9//! use instruction_md::{read, ReadOptions, check_reading};
10//!
11//! let doc = "---\nspec: \"1\"\nparameters:\n  tz: { type: string, default: UTC }\n---\n\
12//!            MUST: plan the day in ${tz}.\nBECAUSE: the owner reads the brief at 7.\n";
13//! let r = read(doc, &ReadOptions::default());
14//! assert!(check_reading(&r).is_empty());
15//! assert_eq!(r.text(None), "MUST: plan the day in UTC.\nBECAUSE: the owner reads the brief at 7.\n");
16//! ```
17//!
18//! Every function takes untrusted text: none panics, and every problem is a [`Diagnostic`] with a stable code.
19//!
20//! Cargo features: `verify` (default) is signature verification (`verify_author`, `verify_delivery`) and signing
21//! for tests and tooling, by `ring`; without it the crate depends on `serde` and `serde_json` alone.
22#![forbid(unsafe_code)]
23
24pub mod allowance;
25pub mod attributes;
26pub mod bindings;
27pub mod check;
28pub mod digest;
29pub mod inline;
30pub mod jcs;
31mod js;
32pub mod legacy;
33pub mod lines;
34pub mod objects;
35pub mod pattern;
36pub mod policy;
37pub mod protocol;
38pub mod read;
39pub mod registry;
40pub mod resolve;
41pub mod text;
42pub mod types;
43#[cfg(feature = "verify")]
44pub mod verify;
45pub mod workflow;
46pub mod yaml;
47
48pub use attributes::parse_attributes;
49pub use check::{Target, check, check_reading, inline_diagnostics, resolve_target, workflows_diagnostics};
50pub use digest::{author_digest, digest, digest_text, front_matter_id, sha256_hex};
51pub use inline::{InlineToken, TokenType, inline_tokens, split_wiki};
52pub use jcs::{canonical_json, json_digest};
53pub use js::js_number;
54pub use legacy::{LEGACY_SYNTAX, legacy_diagnostics};
55pub use lines::{LineInfo, classify_lines, format};
56pub use objects::{
57    ConfigurationBlock, ConnectedObject, Location, carries_configuration, configuration_blocks, connected_objects, is_connected, is_layout,
58    walk,
59};
60pub use pattern::Pattern;
61pub use policy::{
62    AUTHOR_POLICY_KEY, HOST_POLICY_KEY, INTEGRATED_KINDS, LayerProblem, NamedTools, Policy, PolicyFrom, PolicyLayer, ServerPolicy,
63    ServerTools, ToolDefault, authored_candidates, host_block, layer_of, merge_policy, named_tools, normalize_target, remote_targets,
64    with_host_block,
65};
66pub use read::{ReadOptions, Reading, SplitBackmatter, Stripped, read, split_backmatter, strip_comments, value_fits, value_from};
67pub use registry::{AttrSpec, KindSpec, Registry, all_families, attr_spec, canonical_kind, inline_attr_spec, is_rule, registry};
68pub use resolve::{
69    Dependency, ExtensionBinding, Loader, Manifest, Provenance, RESOLVED_FORMAT, Resolution, ResolveOptions, Resolved, ResolvedDocument,
70    Selector, Source, references_of, resolve, resolve_tree, resolve_uri, resolve_with, slug,
71};
72pub use text::{Known, ReferenceRecord, TextOptions, to_text, value_text};
73pub use types::{
74    Attrs, Diagnostic, Document, Form, Identity, Metadata, Node, NodeType, Object, Parameter, Range, Severity, StructuredValue, TREE_FORMAT,
75};
76#[cfg(feature = "verify")]
77pub use verify::{
78    DeliveryVerifyOptions, Jwk, SigningKey, VERIFY_CODES, VerifyOptions, VerifyResult, public_jwk, sign_jws, verify_author, verify_delivery,
79};
80pub use workflow::{
81    WORKFLOW_DIALECT, WORKFLOW_SCOPES, WorkflowKind, WorkflowLimits, WorkflowRegistry, workflow_diagnostics, workflow_registry,
82    workflow_scope,
83};
84pub use yaml::parse_yaml;
85
86/// The specification commit the vendored registry and conformance data are from.
87pub const SPEC_COMMIT: &str = "4bb0328";
88
89/// Reads a document and gives its agent text with its declared defaults — the shortcut a runtime needs: the text an
90/// agent receives (`instruction-text/1`) and every diagnostic: the reader's, the inline checks', a native workflow's
91/// ([`workflows_diagnostics`]) and the lines written in Specification 1.1 ([`legacy_diagnostics`]), as the TypeScript CLI
92/// reports them. An error among the diagnostics means the document should not be delivered.
93pub fn deliver(text: &str, params: Option<&Object>) -> (String, Vec<Diagnostic>) {
94    let r = read(text, &ReadOptions::default());
95    let mut diagnostics = check_reading(&r);
96    let legacy = legacy_diagnostics(text);
97    if !legacy.is_empty() {
98        diagnostics.extend(legacy);
99        // (stable: by line, the reader's before the 1.1 lines', as the CLI orders them)
100        diagnostics.sort_by_key(|d| d.line().unwrap_or(0));
101    }
102    (r.text(params), diagnostics)
103}