khive-pack-knowledge 0.16.0

Knowledge verb pack — lore corpus (atoms/domains), TF-IDF retrieval, concept registration
use std::collections::{BTreeMap, BTreeSet};

use khive_runtime::graph_lint::{
    InspectedLintEdge, LintReport, LintRuleId as Rule, LintSeverity as Severity, LintSubject,
    LintSummary, LintViolation,
};
use khive_storage::{Entity, Note};
use serde_json::Value;
use uuid::Uuid;

use super::{params::Selection, stats};

fn entity_subject(entity: &Entity) -> LintSubject {
    LintSubject::Entity {
        namespace: entity.namespace.clone(),
        entity_id: entity.id,
        entity_name: entity.name.clone(),
        entity_kind: entity.kind.clone(),
    }
}

fn violation(
    subject: LintSubject,
    rule: Rule,
    severity: Severity,
    message: impl Into<String>,
    suggestion: &str,
) -> LintViolation {
    LintViolation {
        subject,
        rule,
        severity,
        message: message.into(),
        suggestion: suggestion.into(),
        auto_fixable: matches!(
            rule,
            Rule::DanglingEdge | Rule::DuplicateName | Rule::SupersededNotMarked
        ),
        member_ids: None,
    }
}

fn property_string<'a>(entity: &'a Entity, key: &str) -> Option<&'a str> {
    entity.properties.as_ref()?.as_object()?.get(key)?.as_str()
}

pub(super) fn evaluate(
    entities: &[Entity],
    notes: &[Note],
    edges: &[InspectedLintEdge],
    selection: &Selection,
) -> LintReport {
    let live: BTreeMap<Uuid, &Entity> = entities
        .iter()
        .filter(|entity| entity.deleted_at.is_none())
        .map(|entity| (entity.id, entity))
        .collect();
    let degrees = stats::degrees(entities, edges);
    let witnesses = edges.iter().filter(|observed| {
        observed.edge.deleted_at.is_none()
            && observed.source_live
            && observed.target_live
            && observed.contract_valid == Some(true)
    });
    let mut outgoing_relations = BTreeMap::<Uuid, BTreeSet<String>>::new();
    let mut implements_concept = BTreeSet::new();
    let mut superseded = BTreeSet::new();
    for observed in witnesses {
        let relation = observed.edge.relation.to_string();
        if relation == "implements"
            && live
                .get(&observed.edge.target_id)
                .is_some_and(|target| target.kind == "concept")
        {
            implements_concept.insert(observed.edge.source_id);
        }
        if relation == "supersedes" {
            superseded.insert(observed.edge.target_id);
        }
        outgoing_relations
            .entry(observed.edge.source_id)
            .or_default()
            .insert(relation);
    }
    let outgoing = |id: Uuid, relation: &str| {
        outgoing_relations
            .get(&id)
            .is_some_and(|relations| relations.contains(relation))
    };
    let mut violations = Vec::new();
    let mut groups = BTreeMap::<(&str, &str, &str), Vec<&Entity>>::new();
    for entity in live.values() {
        let subject = entity_subject(entity);
        let degree = degrees[&entity.id];
        if degree == 0 {
            violations.push(violation(
                subject.clone(),
                Rule::OrphanEntity,
                Severity::Error,
                "Entity has no visible incident edges",
                "Connect the entity to related graph records",
            ));
        }
        let minimum = match entity.kind.as_str() {
            "concept" => 4,
            "project" => 3,
            "person" => 1,
            _ => 0,
        };
        if degree < minimum {
            violations.push(violation(
                subject.clone(),
                Rule::MinEdgeDensity,
                Severity::Error,
                format!(
                    "Entity has degree {degree}, below the {minimum} minimum for {}",
                    entity.kind
                ),
                "Add meaningful relationships after checking the entity's context",
            ));
        }
        if matches!(entity.kind.as_str(), "project" | "resource")
            && entity.entity_type.as_deref().is_none_or(str::is_empty)
        {
            let legacy = entity
                .properties
                .as_ref()
                .and_then(Value::as_object)
                .is_some_and(|object| object.contains_key("entity_type"));
            let message = if legacy {
                "Canonical entity_type is absent or empty; legacy properties.entity_type does not satisfy the rule"
            } else {
                "Canonical entity_type is absent or empty"
            };
            violations.push(violation(
                subject.clone(),
                Rule::MissingEntityType,
                Severity::Warn,
                message,
                "Set the canonical entity_type column to an allowed subtype",
            ));
        }
        let paper = entity.kind == "concept" && property_string(entity, "type") == Some("paper");
        if paper && !outgoing(entity.id, "introduced_by") {
            violations.push(violation(
                subject.clone(),
                Rule::MissingIntroducedBy,
                Severity::Warn,
                "Concept paper lacks a live valid outgoing introduced_by witness",
                "Link the paper concept to its introducer",
            ));
        }
        if entity.kind == "project" && !implements_concept.contains(&entity.id) {
            violations.push(violation(
                subject.clone(),
                Rule::MissingImplements,
                Severity::Warn,
                "Project lacks a live valid implements edge to a concept",
                "Link the project to a concept it implements",
            ));
        }
        if superseded.contains(&entity.id)
            && property_string(entity, "status") != Some("deprecated")
        {
            violations.push(violation(
                subject.clone(),
                Rule::SupersededNotMarked,
                Severity::Warn,
                "Live entity is superseded but is not marked deprecated",
                "Mark the observed entity deprecated through a guarded property update",
            ));
        }
        if entity.kind == "concept"
            && !["instance_of", "extends", "variant_of"]
                .iter()
                .any(|relation| outgoing(entity.id, relation))
        {
            violations.push(violation(
                subject.clone(),
                Rule::ConceptNoParent,
                Severity::Warn,
                "Concept lacks a live valid outgoing parent witness",
                "Link the concept to its parent with instance_of, extends, or variant_of",
            ));
        }
        if paper {
            let object = entity.properties.as_ref().and_then(Value::as_object);
            let missing: Vec<_> = ["authors", "year", "source"]
                .into_iter()
                .filter(|key| !object.is_some_and(|object| object.contains_key(*key)))
                .collect();
            if !missing.is_empty() {
                violations.push(violation(
                    subject,
                    Rule::PaperMissingMetadata,
                    Severity::Info,
                    format!(
                        "Concept paper lacks property members: {}",
                        missing.join(", ")
                    ),
                    "Add the missing paper metadata members",
                ));
            }
        }
        groups
            .entry((&entity.namespace, &entity.kind, &entity.name))
            .or_default()
            .push(entity);
    }
    for members in groups.values_mut().filter(|members| members.len() > 1) {
        members.sort_by_key(|entity| entity.id);
        let mut row = violation(entity_subject(members[0]), Rule::DuplicateName, Severity::Warn, format!("{} live entities share this exact namespace, kind and name", members.len()), "Create a question about the observed duplicates; do not choose a merge winner automatically");
        row.member_ids = Some(members.iter().map(|entity| entity.id).collect());
        violations.push(row);
    }
    for observed in edges
        .iter()
        .filter(|observed| observed.edge.deleted_at.is_none())
    {
        let subject = LintSubject::Edge {
            namespace: observed.edge.namespace.clone(),
            edge_id: observed.edge.id.0,
        };
        if observed.source_soft_deleted || observed.target_soft_deleted {
            violations.push(violation(subject.clone(), Rule::DanglingEdge, Severity::Error, "Edge has a confirmed soft-deleted endpoint", "Soft-delete the unchanged edge only while a local observed endpoint remains tombstoned"));
        }
        if observed.contract_valid == Some(false) {
            violations.push(violation(
                subject.clone(),
                Rule::DirectionViolation,
                Severity::Error,
                "Resolved endpoint types violate the shared link contract",
                "Repair the endpoint modeling under the current base and pack rules",
            ));
        }
        if observed.edge.weight < 0.3 {
            violations.push(violation(
                subject,
                Rule::LowWeightEdge,
                Severity::Info,
                "Edge weight is below 0.3",
                "Review the relationship's strength and evidence",
            ));
        }
    }
    for note in notes.iter().filter(|note| note.deleted_at.is_none()) {
        if !outgoing(note.id, "annotates") {
            violations.push(violation(
                LintSubject::Note {
                    namespace: note.namespace.clone(),
                    note_id: note.id,
                    note_kind: note.kind.clone(),
                },
                Rule::NoteNoAnnotates,
                Severity::Info,
                "Note lacks a live valid outgoing annotates witness",
                "Annotate a visible live entity, note, edge or event allowed by the link contract",
            ));
        }
    }
    violations
        .retain(|row| selection.rules.contains(&row.rule) && row.severity >= selection.severity);
    violations.sort_by(|left, right| {
        (
            left.rule.as_str(),
            left.subject.namespace(),
            left.subject.substrate(),
            left.subject.id(),
        )
            .cmp(&(
                right.rule.as_str(),
                right.subject.namespace(),
                right.subject.substrate(),
                right.subject.id(),
            ))
    });
    let mut summary = LintSummary {
        total: violations.len() as u64,
        fixed: selection.fix.then_some(0),
        ..LintSummary::default()
    };
    for row in &violations {
        *summary.by_rule.entry(row.rule).or_default() += 1;
        match row.severity {
            Severity::Error => summary.errors += 1,
            Severity::Warn => summary.warnings += 1,
            Severity::Info => summary.infos += 1,
        }
    }
    LintReport {
        violations,
        summary,
        stats: stats::collect(entities, notes, edges),
    }
}

#[cfg(test)]
#[path = "rules_tests.rs"]
mod tests;