Skip to main content

Crate conkit_sketch

Crate conkit_sketch 

Source
Expand description

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

The conkit-sketch crate checks source bytes against expected code snippets stored in combined contract YAML, refreshes linked sketch code, and compares sketch catalogs semantically. Callers provide logical CatalogPath names and bytes through FileCatalog, then decide where returned reports or updated combined documents should be stored.

Sketch matching is intentionally language-neutral. The crate normalizes contract snippets and source files the same way, then verifies that each expected normalized line sequence appears in the declared source file. A minimal signature index follows each top-level signature’s sketch link to infer the sketch’s source file and signature type. Rust parsing and AST-derived source extraction remain outside this crate.

§Contracts and matching

Each YAML document contains exactly root, files, signatures, and sketches. A flattened sketch record has a null-valued identifier beside signature_type and code; its linked signature owns the file and sketch fields. The later version/language reverse-link dialect is not accepted. Only direct root-level .yaml and .yml catalog entries are considered; nested YAML entries are ignored.

Matching collapses whitespace within each line, removes empty lines, and compares the remaining lines as one contiguous ordered sequence. Source bytes do not need to be UTF-8: malformed source lines use an ASCII-whitespace fallback that preserves every other byte. A sketch still matches only the logical source path declared by its linked signature.

§Semantic diffing

SketchContractKit::diff treats the sketch identifier as identity. For a sketch present in both catalogs, the linked source file, linked signature label, signature_type, and normalized code are semantic. The containing contract document, YAML formatting, YAML comments outside code, and mapping order are nonsemantic.

Normalization removes blank lines and collapses whitespace within each line, so those changes alone do not produce a diff. Line order and every token or comment inside code remain semantic.

§Generation and reports

Generation accepts one SketchSeed for every explicit signature link and refreshes only the flattened sketch’s code. It preserves the combined document’s root, file allowlist, signatures, links, identifiers, and kinds. The response returns the complete input catalog, including unchanged nested YAML and non-YAML passthrough entries, and counts the linked sketches that were refreshed. Returned catalog bytes are deterministic and are never written to the operating system by this crate.

A check can return YAML or JSON report bytes through ReportRequest. The caller chooses the logical output path and persists those bytes if desired.

§Errors and diagnostics

Malformed YAML, invalid contract fields, duplicate sketch identifiers, and invalid generation seeds return SketchContractKitError. A valid sketch that references a missing source file or whose snippet does not match is represented by SketchDiagnostic in a successful CheckResponse. CheckMode determines whether those diagnostics make the response fail.

§Runtime and storage boundaries

conkit-sketch owns sketch YAML parsing, normalization, matching, semantic diffing, diagnostics, report bytes, and generation from caller-provided resolved seeds. Filesystem walking, path normalization, terminal output, and cross-domain orchestration belong to callers such as the conkit crate.

Start with SketchContractKit::builder to configure the local kit and call its operations directly with .await. The futures are executor-neutral: the crate does not select the executor that polls them. To place an operation in a spawned task, that task must own both its request and the kit, commonly by moving an Arc clone into an async move block. That owning future and its output satisfy Send + 'static; a method future which still borrows a local kit is not promised to be 'static.

CPU work runs on a reusable Rayon-backed pool. WorkOptions documents the complete worker-budget, root-admission, cancellation, and caller-deadline contract. Catalogs, diagnostics, generated entries, and rendered output remain deterministic regardless of worker scheduling.

§Examples

Refresh a linked sketch, then check the same source against it.

use conkit_sketch::{
    CatalogPath, CheckMode, CheckRequest, FileCatalog, GenerateRequest,
    ReportRequest, SketchContractKit, SketchSeed,
};

let source_path = CatalogPath::new("lib.rs")?;
let contract_path = CatalogPath::new("main.yml")?;
let mut source_files = FileCatalog::new();
source_files.insert(
    source_path.clone(),
    b"pub fn answer() -> u8 { 42 }\n".to_vec(),
)?;
let mut contract_files = FileCatalog::new();
contract_files.insert(contract_path.clone(), br#"root: ../src
files: [lib.rs]
signatures:
  - answer_signature:
      file: lib.rs
      signature_type: function
      sketch: answer_body
sketches:
  - answer_body:
    signature_type: function
    code: old code
"#.to_vec())?;

let kit = SketchContractKit::builder().build()?;
let generated = futures_executor::block_on(kit.generate(GenerateRequest {
    contract_files,
    seeds: vec![SketchSeed {
        contract_file: contract_path.clone(),
        sketch_id: "answer_body".to_owned(),
        signature_type: "function".to_owned(),
        file: source_path.clone(),
        code: "pub fn answer() -> u8 { 42 }".to_owned(),
    }],
}))?;

assert_eq!(generated.sketch_count, 1);
assert!(generated
    .contract_files
    .get(&contract_path)
    .is_some());

let checked = futures_executor::block_on(kit.check(CheckRequest {
    source_files,
    contract_files: generated.contract_files,
    report: ReportRequest::None,
    mode: CheckMode::Strict,
}))?;

assert!(checked.passed);
assert!(checked.diagnostics.is_empty());
assert_eq!(checked.counts.matched_sketch_count, 1);

Structs§

CatalogPath
A validated logical catalog path.
CheckRequest
Request for SketchContractKit::check.
CheckResponse
Response returned by SketchContractKit::check.
DiffRequest
Request for SketchContractKit::diff.
DiffResponse
Response returned by SketchContractKit::diff.
FileCatalog
An ordered in-memory catalog of logical paths to byte contents.
GenerateRequest
Request for SketchContractKit::generate.
GenerateResponse
Response returned by SketchContractKit::generate.
SketchCheckCounts
Scope and outcome totals for a completed sketch check.
SketchContractKit
Public handle for sketch contract operations.
SketchContractKitBuilder
Builder for SketchContractKit.
SketchContractKitError
Error type returned by conkit-sketch public operations.
SketchSeed
Caller-supplied refresh data for one linked sketch.
WorkOptions
CPU work-pool configuration for SketchContractKit.

Enums§

CheckMode
Controls how diagnostics affect CheckResponse::passed.
DiffEntry
One semantic sketch change returned by DiffResponse.
FileCatalogError
Errors returned by FileCatalog mutation and CatalogPath validation.
ReportFormat
Output encoding for generated sketch check reports.
ReportRequest
Selects whether a sketch check returns an encoded report.
SketchDiagnostic
A per-sketch diagnostic from a completed check.
WorkParallelism
Worker-count and root-operation admission policy for the crate-owned CPU pool.