HTTP API: entity

Jeden spustitelný artefakt, který objekt jmenuje, a zda ho strom drží.

field se uchovává vedle cesty, protože stejný objekt může jmenovat artefakty pod několika klíči a čtenář opravující nefunkční potřebuje vědět, na který řádek front matteru se podívat, ne který soubor chybí.

use majordomus_cli::capability::builtin::entity::ClaimedArtifact;

let a = ClaimedArtifact {
    field: "x-majordomus.tests".into(),
    path: "test/cases/277_entities_are_routable.sh".into(),
    present: true,
};
let wire = serde_json::to_value(&a).unwrap();
assert_eq!(wire["field"], serde_json::json!("x-majordomus.tests"));
assert_eq!(wire["present"], serde_json::json!(true));

Veřejná dokumentační stránka jedné entity, jak ji odvodí publikační rozhodnutí jejího druhu. Každý povrch, který entitu ukazuje, nese tuto hodnotu a vykresluje ji; žádný si neodvozuje vlastní veřejnou adresu.

use majordomus_cli::entity::Documentation;

let d = Documentation {
    projection: "entity".into(),
    route: Some("/adrs/adr-0056/".into()),
    url: Some("https://majordomus.dev/adrs/adr-0056/".into()),
    reason: None,
    declared_in: "site/data/publication.toml".into(),
};
let wire = serde_json::to_value(&d).unwrap();
assert_eq!(wire["url"], serde_json::json!("https://majordomus.dev/adrs/adr-0056/"));
// a field that does not apply is absent, not an empty string
assert!(wire.get("reason").is_none());

Jedna hrana tak, jak ji čte stránka entity.

Vše, co čtenář o druhém konci potřebuje, je tu — co ukázat, jaký druh věci to je a adresa, kam ho poslat — takže stránka vykreslí vztah, aniž by se kvůli němu vracela do indexu. route je None přesně tehdy, když je external pravda: file, test nebo command jmenuje vrstva a není jejím objektem, takže neexistuje stránka entity, na kterou odkazovat, a šablona ukáže prostý text místo mrtvého odkazu.

use majordomus_cli::entity::{Direction, Edge};
use majordomus_cli::order::Ordered;

let edge = Edge {
    direction: Direction::Incoming,
    edge: "depends_on".into(),
    field: "depends_on".into(),
    uri: Some("majordomus://rule/project.x@1".into()),
    kind: "rule".into(),
    label: "project.x@1".into(),
    title: Some("A rule".into()),
    route: Some("/cockpit/objects/rule/project-x-1".into()),
    external: false,
};

// the relation is the group and the direction ranks inside it; see the `Ordered` impl
let key = edge.order_key();
assert_eq!(key.group, Some("depends_on"));
assert_eq!(key.rank, Direction::Incoming as i64);
assert_eq!(key.identity, "majordomus://rule/project.x@1");

Co lze říct o vynucování objektu, aniž by se cokoli spouštělo.

meaning cestuje s state, aby každý povrch ukazoval o věci stejnou větu: samotný odznak vybízí každý renderer, aby napsal vlastní glosu, a právě v glose se „vyřešeno“ nenápadně mění v „prochází“. Druh, který nepojmenovává žádný artefakt, je Unclaimed s prázdným artifacts, což je odpověď, nikoli opomenutí.

use majordomus_cli::capability::builtin::entity::{Evidence, EvidenceState};

let e = Evidence {
    state: EvidenceState::Unclaimed,
    meaning: "This object names no executable artefact.".into(),
    artifacts: Vec::new(),
    proof: None,
};

// the empty collections are omitted from the wire, so absence reads as absence
let wire = serde_json::to_value(&e).unwrap();
assert_eq!(wire["state"], serde_json::json!("unclaimed"));
assert!(wire.get("artifacts").is_none());
assert!(wire.get("proof").is_none());

Co tento repozitář může říct o spustitelných artefaktech, které objekt jmenuje, a jen to. Slovo je zvoleno tak, aby ho žádný čtenář nepoplet s během.

Tři stavy jsou seřazeny podle toho, kolik čtenáři dovolují usoudit, a ten nejsilnější z nich o běhu stále nic nevypovídá: Resolved znamená, že soubory, na které objekt ukazuje, existují. proof na Evidence je místo, kde se ptá „prošlo to někdy“.

use majordomus_cli::capability::builtin::entity::EvidenceState;

// the wire spellings, which the Cockpit badge and the site template both read
for (state, word) in [
    (EvidenceState::Unclaimed, "unclaimed"),
    (EvidenceState::Dangling, "dangling"),
    (EvidenceState::Resolved, "resolved"),
] {
    assert_eq!(serde_json::to_value(state).unwrap(), serde_json::json!(word));
}

Kde žije úplnější odpověď o vynucování této entity.

Ukazatel, nikdy odpověď. Tento modul uvádí, co vidí ve stromu, a pak jmenuje schopnost, která může říct víc, aby stránka entity nevyrostla o druhou, slabší implementaci důkazu vedle té, která už existuje.

use majordomus_cli::capability::builtin::entity::ProofRef;

let p = ProofRef {
    capability: "rule.proves".into(),
    title: "What proves a rule".into(),
    address: "majordomus rule proves project.entities-are-routable@1".into(),
};
assert_eq!(
    serde_json::to_value(&p).unwrap()["capability"],
    serde_json::json!("rule.proves")
);

Jedno místo, kde lze tuto entitu dosáhnout, a jak.

Řádek tabulky „kde jinde se na to odpovídá“ na stránce entity. surface je vlastní jméno rozhraní, takže čtenář, který pracuje na příkazové řádce, a čtenář, který pracuje přes MCP, každý najde svůj vlastní řádek místo trasy, kterou by musel překládat.

use majordomus_cli::entity::Surface;

let s = Surface {
    surface: "mcp".into(),
    address: "majordomus://rule/project.x@1".into(),
    detail: "the file as read".into(),
};
assert_eq!(
    serde_json::to_value(&s).unwrap()["surface"],
    serde_json::json!("mcp")
);

Jeden objekt vrstvy jako adresovatelný uzel: co to je, kde se poskytuje, s čím je spojen a co lze říci o jeho vynucování.

Celá odpověď v jedné hodnotě, protože je to jedna otázka: každé rozhraní, které ukazuje entitu — stránka Cockpitu, GET /api/v1/entity, majordomus_entity, majordomus entity show — vykresluje tohle a nic si nesestavuje samo. Pole, které čtenář vidí na jednom rozhraní a na jiném ne, by znamenalo, že rozhraní zastává názor, což ADR 0004 vylučuje.

use majordomus_cli::capability::builtin::entity::EntityView;

// it round-trips through the wire shape every projection reads it as
let view: EntityView = serde_json::from_value(serde_json::json!({
    "uri": "majordomus://adr/adr-0056",
    "id": "adr.adr-0056",
    "kind": "adr",
    "identity": "adr-0056",
    "slug": "adr-0056",
    "route": "/cockpit/objects/adr/adr-0056",
    "kind_route": "/cockpit/objects/adr",
    "title": "Every object of the layer has a derived address",
    "provenance": { "path": "x.md", "directory": "x", "source_class": "adr", "bytes": 0 },
    "metadata": {},
    "media_type": "text/markdown",
    "content": "",
    "relations": [],
    "surfaces": [],
    "evidence": { "state": "unclaimed", "meaning": "nothing named" },
    "documentation": {
        "projection": "entity",
        "route": "/adrs/adr-0056/",
        "url": "https://majordomus.dev/adrs/adr-0056/",
        "declared_in": "site/data/publication.toml",
    },
}))
.unwrap();

assert_eq!(view.route, "/cockpit/objects/adr/adr-0056");
// the Cockpit route is the object's; the public page is the site's, and both are named
let public = view.documentation.as_ref().and_then(|d| d.url.as_deref());
assert_eq!(public, Some("https://majordomus.dev/adrs/adr-0056/"));
// the kind's index is the entity's route with the last segment removed
assert!(view.route.starts_with(&view.kind_route));

Jeden druh vrstvy, s jeho adresou a počtem objektů, které drží.

example nese jeden objekt druhu, aby katalog druhů byl místem, odkud čtenář může jít, ne seznamem slov: druh s počtem a bez cesty dovnitř je mrtvý řádek. Je None jen u druhu, jehož objekt index nedrží.

use majordomus_cli::capability::builtin::entity::KindEntry;

let e: KindEntry = serde_json::from_value(serde_json::json!({
    "kind": "adr",
    "count": 52,
    "route": "/cockpit/objects/adr",
}))
.unwrap();

assert_eq!(e.kind, "adr");
// the route is the kind's, derived — never a per-kind entry in a table of routes
assert_eq!(e.route, majordomus_cli::entity::kind_route(&e.kind));
assert!(e.example.is_none());

Každý druh vrstvy, každý s jeho routou, a každá kolize rout, která existuje.

Ta dvě čísla porovnává scripts/ci/entity-check: objekty, které index drží, proti objektům, které mají adresu. Hlásí se společně, v jedné odpovědi, aby se kontrola ptala na jednu otázku, místo aby spojovala dva seznamy a sama rozhodovala, co rozdíl znamená.

use majordomus_cli::capability::builtin::entity::KindList;

let healthy: KindList = serde_json::from_value(serde_json::json!({
    "count": 1,
    "kinds": [{ "kind": "adr", "count": 52, "route": "/cockpit/objects/adr" }],
    "routable": 52,
}))
.unwrap();

let held: usize = healthy.kinds.iter().map(|k| k.count).sum();
// every object addressable, and no collision: the only state the gate accepts
assert_eq!(held, healthy.routable);
assert!(healthy.collisions.is_empty());

Kterým směrem vztah vede od čtené entity.

Směr je vlastností čtení, nikoli relace: jedna hrana v graph::RELATIONS je odchozí na stránce objektu, který ji deklaroval, a příchozí na stránce objektu, který pojmenovává. Nic ve vrstvě Incoming nezapisuje.

use majordomus_cli::entity::Direction;

// the wire spelling, which every surface shows and the site template reads
assert_eq!(
    serde_json::to_string(&Direction::Outgoing).unwrap(),
    "\"outgoing\""
);
assert_eq!(
    serde_json::to_string(&Direction::Incoming).unwrap(),
    "\"incoming\""
);
// declared before derived, which is the order an entity page renders the two sections
assert!((Direction::Outgoing as u8) < (Direction::Incoming as u8));

Dva objekty jednoho druhu, jejichž identity se redukují na stejnou trasu.

Nese obě identity i oba soubory, protože čtenář, který to musí opravit, potřebuje vědět, které dvě věci kolidovaly a kde jsou zapsány — počet by mu řekl jen to, že strom je odmítnut. correction je věta, kterou collisions napsal o tomto konkrétním páru.

#### use majordomus_cli::{Object, Provenance};
#### fn object(kind: &str, identity: &str) -> Object {
####     Object { kind: kind.into(), identity: identity.into(),
####         uri: format!("majordomus://{kind}/{identity}"), title: None, description: None,
####         metadata: serde_json::json!({}), body: String::new(), content: String::new(),
####         media_type: "text/markdown",
####         provenance: Provenance { path: format!("{identity}.md"), directory: "x".into(),
####             source_class: kind.into(), section: None, bytes: 0, member: None } }
#### }
use majordomus_cli::entity::{collisions, Collision};

// `a.b` and `a-b` are two identities and one slug
let objects = vec![object("rule", "a.b"), object("rule", "a-b")];
let found: Vec<Collision> = collisions(&objects);

assert_eq!(found.len(), 1);
assert_eq!(found[0].kind, "rule");
assert_eq!(found[0].slug, "a-b");
assert_eq!(found[0].identities, ["a.b", "a-b"]);
assert!(!found[0].correction.is_empty());