Skip to main content

Crate conkit_signature

Crate conkit_signature 

Source
Expand description

Byte-in, byte-out signature contracts for Contract Kit.

The conkit-signature crate generates signature contracts from Rust source bytes, checks source bytes against existing contracts, resolves linked sketches to exact Rust items, and diffs current contracts against previous contract catalogs. It does not read from or write to the operating system. Callers provide logical CatalogPath names and bytes through FileCatalog, then decide where returned catalog entries should be stored.

Rust signatures live in combined YAML documents with root, an exact files allowlist, user-named nested signatures, signature-to-sketch links, and flattened sketches. Versioned language: rust shorthand is rejected. Repeated item macros with the same file, module path, and semantic name use one-based declaration occurrence as their structural identity: the first occurrence is unsuffixed, followed by #2, #3, and so on. Regeneration retains user labels by occurrence, and linked-sketch resolution uses that same occurrence to return the exact Rust item text.

§Operations

§Boundaries

conkit-signature owns signature-domain parsing, matching, generation, and diffing over catalog bytes. Filesystem walking, path normalization, persistence, archive transport, and terminal output belong to callers such as the conkit crate. This crate validates and preserves signature-owned sketch-link metadata but does not generate sketch code or perform snippet matching.

§Async execution

Start with SignatureContractKit::builder to configure the local kit. Public operation futures are executor-neutral, and direct .await is the normal integration. A task that is moved into an executor must own both its request and the kit, usually by moving an Arc clone into an async move block. That owning task future and its output satisfy Send + 'static; an operation future called directly still borrows the kit.

WorkOptions documents the complete worker-admission, cancellation, and timeout contract. Examples here use futures_executor::block_on only to remain self-contained; the crate does not select that executor for callers.

§Examples

Generate a contract from Rust source bytes, then check the same source against the generated contract.

use conkit_signature::{
    CatalogPath, CheckMode, CheckRequest, ContractScope, FileCatalog,
    GenerateDocument, GenerateRequest, GenerateTarget, ReportRequest,
    SignatureContractKit,
};

fn catalog_with(path: &str, bytes: &[u8]) -> Result<FileCatalog, Box<dyn std::error::Error>> {
    let mut catalog = FileCatalog::new();
    catalog.insert(CatalogPath::new(path)?, bytes.to_vec())?;
    Ok(catalog)
}

let kit = SignatureContractKit::builder().build()?;
let source_files = catalog_with("lib.rs", b"pub fn answer() -> u8 { 42 }\n")?;

let generated = futures_executor::block_on(kit.generate(GenerateRequest {
    source_files: source_files.clone(),
    target: GenerateTarget::New(GenerateDocument {
        contract_file: CatalogPath::new("main.yml")?,
        root: "../src".to_owned(),
        files: vec![CatalogPath::new("lib.rs")?],
    }),
    scope: ContractScope::Signatures,
}))?;

let contract_path = CatalogPath::new("main.yml")?;
let contract_yaml = std::str::from_utf8(
    generated.contract_files.get(&contract_path).expect("generated contract"),
)?;
assert!(contract_yaml.contains("root: ../src"));
assert!(contract_yaml.contains("files:"));
assert!(contract_yaml.contains("signature_type: function"));

let response = futures_executor::block_on(kit.check(CheckRequest {
    source_files,
    contract_files: generated.contract_files,
    report: ReportRequest::None,
    scope: ContractScope::Signatures,
    mode: CheckMode::Default,
}))?;

assert!(response.passed);
assert!(response.diagnostics.is_empty());

Structs§

CatalogPath
A validated logical catalog path.
CheckRequest
Request for SignatureContractKit::check.
CheckResponse
Response returned by SignatureContractKit::check.
DiffRequest
Request for SignatureContractKit::diff.
DiffResponse
Response returned by SignatureContractKit::diff.
FileCatalog
An ordered in-memory catalog of logical paths to byte contents.
GenerateDocument
Layout used when creating a combined contract document.
GenerateRequest
Request for SignatureContractKit::generate.
GenerateResponse
Response returned by SignatureContractKit::generate.
ResolveSketchesRequest
Request for SignatureContractKit::resolve_sketches.
ResolveSketchesResponse
Exact linked Rust items returned by sketch resolution.
ResolvedSketchSeed
Runtime-neutral source seed for one explicitly linked sketch.
SignatureCheckCounts
Signature totals reported by CheckResponse.
SignatureContractKit
Public handle for signature contract operations.
SignatureContractKitBuilder
Builder for SignatureContractKit.
SignatureContractKitError
Error type returned by conkit-signature public operations.
WorkOptions
CPU work scheduling options for SignatureContractKit.

Enums§

CheckDiagnostic
A diagnostic emitted while checking actual source signatures against expected contract signatures.
CheckMode
Determines whether diagnostics fail a check response.
ContractScope
Selects whether signature generation may coordinate linked-sketch cleanup.
DiffEntry
One changed top-level signature group reported by DiffResponse.
FileCatalogError
Errors returned by FileCatalog and CatalogPath.
GenerateTarget
Selects whether signature generation creates or updates combined documents.
ReportFormat
Output encoding for generated check reports.
ReportRequest
Optional report output for SignatureContractKit::check.
WorkParallelism
Worker parallelism and root-operation admission policy for the internal CPU work pool.