Struct Discovery 

pub struct Discovery {
    pub selector: Selector,
    pub reason: String,
    pub via: Option<String>,
    pub edge: Option<String>,
    pub depth: usize,
    pub confidence: f64,
    pub weight: f64,
}

One way an entry was reached: which selector, why, how far from a seed, and how much the compiler trusts it. An entry keeps every one of these, because “five discovery paths found the same ADR” is the interesting fact, not a thing to hide.

A Discovery is a kind of way in, not one traversal. Thirty-three issues of one milestone all reach that milestone along belongs_to, and recording that thirty-three times would say the answer had thirty-three reasons when it has one — so a path already recorded for the same selector, edge and reason is kept rather than repeated.

via and edge are present exactly when they mean something: a seed was not reached from anything and followed no edge, so both are absent and are skipped on the wire rather than serialised as null. confidence is 1.0 for every declared selector and less only for Selector::IntentMatch; weight is what this particular path contributes to relevance, which is a different quantity — how much it counts, against how sure it is.

use majordomus_cli::devcontext::{Discovery, Selector};
use serde_json::json;

// the request named it: nothing to come via, no edge followed, depth zero
let seed: Discovery = serde_json::from_value(json!({
    "selector": "seed",
    "reason": "named in the request",
    "depth": 0,
    "confidence": 1.0,
    "weight": 1.0,
})).unwrap();
assert_eq!(seed.selector, Selector::Seed);
assert!(seed.via.is_none() && seed.edge.is_none());
assert!(seed.selector.declared() && seed.confidence == 1.0);

// the wire form omits them rather than carrying nulls a reader must skip
let wire = serde_json::to_value(&seed).unwrap();
assert!(wire.get("via").is_none() && wire.get("edge").is_none());

// a relation says both where it came from and which edge it followed
let walked: Discovery = serde_json::from_value(json!({
    "selector": "relation",
    "reason": "the decision in force over this scope",
    "via": "majordomus://issue/I0301",
    "edge": "governed_by",
    "depth": 1,
    "confidence": 1.0,
    "weight": 0.9,
})).unwrap();
assert_eq!(walked.edge.as_deref(), Some("governed_by"));
assert_eq!(walked.via.as_deref(), Some("majordomus://issue/I0301"));

// and a guess says so, in the one field that distinguishes the two halves of an answer
let guessed: Discovery = serde_json::from_value(json!({
    "selector": "intent_match",
    "reason": "the intent's words occur in it",
    "depth": 2,
    "confidence": 0.4,
    "weight": 0.4,
})).unwrap();
assert!(!guessed.selector.declared() && guessed.confidence < 1.0);

Fields

selector: Selector

What reached it.

reason: String

Why it was included, in words a person reads without this file.

via: Option<String>

The entry this one was reached from, when it was reached from one.

edge: Option<String>

The edge kind followed, for Relation.

depth: usize

Hops from a seed; a seed is 0.

confidence: f64

1.0 when the repository declared this path, less when it was inferred.

weight: f64

What this path contributes to the entry’s relevance.

Trait Implementations

impl Clone for Discovery

fn clone(&self) -> Discovery

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Discovery

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Discovery

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for Discovery

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl PartialEq for Discovery

fn eq(&self, other: &Discovery) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Discovery

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Discovery