Skip to main content

conkit_signature/
lib.rs

1//! Byte-in, byte-out signature contracts for Contract Kit.
2//!
3//! The `conkit-signature` crate generates signature contracts from Rust source
4//! bytes, checks source bytes against existing contracts, resolves linked
5//! sketches to exact Rust items, and diffs current contracts against previous
6//! contract catalogs.
7//! It does not read from or write to the operating system. Callers provide
8//! logical [`CatalogPath`] names and bytes through [`FileCatalog`], then decide
9//! where returned catalog entries should be stored.
10//!
11//! Rust signatures live in combined YAML documents with `root`, an exact
12//! `files` allowlist, user-named nested `signatures`, signature-to-sketch links,
13//! and flattened `sketches`. Versioned `language: rust` shorthand is rejected.
14//! Repeated item macros with the same file, module path, and semantic name use
15//! one-based declaration occurrence as their structural identity: the first
16//! occurrence is unsuffixed, followed by `#2`, `#3`, and so on. Regeneration
17//! retains user labels by occurrence, and linked-sketch resolution uses that
18//! same occurrence to return the exact Rust item text.
19//!
20//! # Operations
21//!
22//! - [`SignatureContractKit::check`] compares actual source signatures with
23//!   expected contract signatures and can return a rendered report catalog.
24//! - [`SignatureContractKit::generate`] creates or updates combined contract
25//!   documents from Rust source bytes.
26//! - [`SignatureContractKit::resolve_sketches`] returns exact source text and
27//!   metadata for explicitly linked sketches.
28//! - [`SignatureContractKit::diff`] compares grouped signature identities in
29//!   current and previous contract catalogs.
30//!
31//! # Boundaries
32//!
33//! `conkit-signature` owns signature-domain parsing, matching, generation, and diffing
34//! over catalog bytes. Filesystem walking, path normalization, persistence,
35//! archive transport, and terminal output belong to callers such as the `conkit`
36//! crate. This crate validates and preserves signature-owned sketch-link
37//! metadata but does not generate sketch code or perform snippet matching.
38//!
39//! # Async execution
40//!
41//! Start with [`SignatureContractKit::builder`] to configure the local kit.
42//! Public operation futures are executor-neutral, and direct `.await` is the
43//! normal integration. A task that is moved into an executor must own both its
44//! request and the kit, usually by moving an [`Arc`](std::sync::Arc) clone into
45//! an `async move` block. That owning task future and its output satisfy
46//! `Send + 'static`; an operation future called directly still borrows the kit.
47//!
48//! [`WorkOptions`] documents the complete worker-admission, cancellation, and
49//! timeout contract. Examples here use `futures_executor::block_on` only to
50//! remain self-contained; the crate does not select that executor for callers.
51//!
52//! # Examples
53//!
54//! Generate a contract from Rust source bytes, then check the same source
55//! against the generated contract.
56//!
57//! ```
58//! use conkit_signature::{
59//!     CatalogPath, CheckMode, CheckRequest, ContractScope, FileCatalog,
60//!     GenerateDocument, GenerateRequest, GenerateTarget, ReportRequest,
61//!     SignatureContractKit,
62//! };
63//!
64//! fn catalog_with(path: &str, bytes: &[u8]) -> Result<FileCatalog, Box<dyn std::error::Error>> {
65//!     let mut catalog = FileCatalog::new();
66//!     catalog.insert(CatalogPath::new(path)?, bytes.to_vec())?;
67//!     Ok(catalog)
68//! }
69//!
70//! let kit = SignatureContractKit::builder().build()?;
71//! let source_files = catalog_with("lib.rs", b"pub fn answer() -> u8 { 42 }\n")?;
72//!
73//! let generated = futures_executor::block_on(kit.generate(GenerateRequest {
74//!     source_files: source_files.clone(),
75//!     target: GenerateTarget::New(GenerateDocument {
76//!         contract_file: CatalogPath::new("main.yml")?,
77//!         root: "../src".to_owned(),
78//!         files: vec![CatalogPath::new("lib.rs")?],
79//!     }),
80//!     scope: ContractScope::Signatures,
81//! }))?;
82//!
83//! let contract_path = CatalogPath::new("main.yml")?;
84//! let contract_yaml = std::str::from_utf8(
85//!     generated.contract_files.get(&contract_path).expect("generated contract"),
86//! )?;
87//! assert!(contract_yaml.contains("root: ../src"));
88//! assert!(contract_yaml.contains("files:"));
89//! assert!(contract_yaml.contains("signature_type: function"));
90//!
91//! let response = futures_executor::block_on(kit.check(CheckRequest {
92//!     source_files,
93//!     contract_files: generated.contract_files,
94//!     report: ReportRequest::None,
95//!     scope: ContractScope::Signatures,
96//!     mode: CheckMode::Default,
97//! }))?;
98//!
99//! assert!(response.passed);
100//! assert!(response.diagnostics.is_empty());
101//! # Ok::<(), Box<dyn std::error::Error>>(())
102//! ```
103#![deny(missing_docs)]
104#![deny(rustdoc::broken_intra_doc_links)]
105#![deny(rustdoc::private_intra_doc_links)]
106
107mod api;
108mod error;
109mod files;
110mod inventory;
111mod languages;
112mod work;
113
114pub use crate::api::{
115    CheckDiagnostic, CheckMode, CheckRequest, CheckResponse, ContractScope, DiffEntry, DiffRequest,
116    DiffResponse, GenerateDocument, GenerateRequest, GenerateResponse, GenerateTarget,
117    ReportFormat, ReportRequest, ResolveSketchesRequest, ResolveSketchesResponse,
118    ResolvedSketchSeed, SignatureCheckCounts, SignatureContractKit, SignatureContractKitBuilder,
119};
120pub use crate::error::SignatureContractKitError;
121pub use crate::files::{CatalogPath, FileCatalog, FileCatalogError};
122pub use crate::work::{WorkOptions, WorkParallelism};