gaman-core 0.3.22

Offline core engine for Gaman migrations
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

//! User-facing documentation derived from registered semantic drift properties.

use crate::states::EntityKind;

/// Documentation for one dialect property comparator used by `verify`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DriftPropertyDoc {
    /// Entity kind whose modeled form owns this property.
    pub entity_kind: EntityKind,
    /// Stable property identifier used in drift findings.
    pub property: &'static str,
    /// Semantic value compared between replay and inspection.
    pub compared: &'static str,
    /// Related information intentionally excluded from this comparison.
    pub ignored: &'static str,
    /// Canonicalization applied before comparison.
    pub normalization: &'static str,
    /// Additional limitation users should consider when interpreting drift.
    pub note: Option<&'static str>,
}

/// Builds the public contract entry for one registered comparator.
pub(super) fn property_doc(entity_kind: EntityKind, property: &'static str) -> DriftPropertyDoc {
    let (compared, normalization) = property_semantics(property);
    DriftPropertyDoc {
        entity_kind,
        property,
        compared,
        ignored: ignored_semantics(entity_kind),
        normalization,
        note: opaque_note(entity_kind),
    }
}

fn property_semantics(property: &str) -> (&'static str, &'static str) {
    match property {
        "name" => ("stable entity identity", "exact identifier comparison"),
        "schema" => (
            "canonical schema identity",
            "dialect schema canonicalization",
        ),
        "type" => ("canonical column type", "dialect type alias normalization"),
        "nullable" | "primary_key" | "unique" | "security_definer" => {
            ("modeled boolean state", "exact boolean comparison")
        }
        "default" => (
            "modeled default expression",
            "dialect-safe literal canonicalization",
        ),
        "columns" | "to_columns" | "values" | "events" => (
            "ordered modeled values",
            "order-preserving exact comparison",
        ),
        "on_delete" | "on_update" => (
            "canonical foreign-key action",
            "canonical action keyword comparison",
        ),
        "definition" | "predicate" | "check" | "generated" => (
            "stable inspected expression text",
            "dialect comparator normalization",
        ),
        _ => (
            "registered modeled metadata",
            "comparator-specific canonicalization",
        ),
    }
}

fn ignored_semantics(entity_kind: EntityKind) -> &'static str {
    match entity_kind {
        EntityKind::Function => "function body and opaque raw SQL",
        EntityKind::View => "view body when it is not a registered stable property",
        EntityKind::Trigger => "trigger body, WHEN source, and opaque raw SQL",
        EntityKind::Index => {
            "access method, operator classes, collation, sort metadata, and opaque raw SQL"
        }
        EntityKind::Table => "unmanaged table options and unregistered catalog metadata",
        _ => "unregistered properties and opaque raw SQL",
    }
}

fn opaque_note(entity_kind: EntityKind) -> Option<&'static str> {
    matches!(
        entity_kind,
        EntityKind::Index
            | EntityKind::Constraint
            | EntityKind::Trigger
            | EntityKind::Function
            | EntityKind::View
            | EntityKind::Extension
    )
    .then_some("opaque forms are verified by owned presence only")
}