ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! **THE KIND ANSWERS EVERY QUESTION, AND THIS IS THE TABLE IT ANSWERS THEM IN.**
//!
//! [`NodeKind`] is a vocabulary with ten questions hung off it, and until the fourth kind arrived
//! nothing pinned a single answer: every arm was checked by the compiler for BEING there and by
//! nobody for being right. A kind's row is spent on refusal sentences an author reads and on
//! structural forks an emission takes, so a silently-swapped answer is a wrong sentence or a wrong
//! emission and neither one fails to compile.
//!
//! Two kinds of teeth here, and only the second kind is worth much on its own:
//!
//! - The TABLE, which restates each row. It catches a changed answer and, more usefully, it makes an
//!   eighth kind state its whole row in one place rather than discovering the questions one compile
//!   error at a time.
//! - The LAWS — that holding rows implies storing, that only a derived index carries a borrowed key,
//!   that no two kinds answer to one word. These are independent of the table and are what would
//!   actually catch a kind wired up wrong.

use super::NodeKind;

/// Every kind, in the order [`NodeKind`] declares them.
const ALL: [NodeKind; 7] = [
  NodeKind::Operator,
  NodeKind::Entity,
  NodeKind::Record,
  NodeKind::Aggregate,
  NodeKind::Fulltext,
  NodeKind::Vector,
  NodeKind::Blob,
];

/// The kinds that hold ROWS — the record family's row-holding rungs.
const ROW_HOLDING: [NodeKind; 2] = [NodeKind::Record, NodeKind::Aggregate];

/// The kinds whose key is their upstream's.
const DERIVED: [NodeKind; 3] = [NodeKind::Fulltext, NodeKind::Vector, NodeKind::Blob];

/// One kind's WORDS — what an author writes and what a refusal calls it back.
struct Words {
  macro_word: &'static str,
  noun: &'static str,
  plural: &'static str,
  article: &'static str,
}

/// One kind's ANSWERS — every predicate an emission or a front end forks on.
struct Answers {
  storage_block: Option<&'static str>,
  holds_rows: bool,
  election: Option<&'static str>,
  derives_its_key: bool,
  dressable: bool,
  stores: bool,
}

/// **THE ROSTER IS WHOLE**, stated as an exhaustive match with no wildcard: an eighth kind is a
/// compile error here, and the error lands beside the table it has to fill in rather than somewhere
/// a reader would have to be told about.
#[test]
fn the_roster_holds_every_kind() {
  const fn rostered(kind: NodeKind) -> bool {
    match kind {
      NodeKind::Operator
      | NodeKind::Entity
      | NodeKind::Record
      | NodeKind::Aggregate
      | NodeKind::Fulltext
      | NodeKind::Vector
      | NodeKind::Blob => true,
    }
  }

  for kind in ALL {
    assert!(rostered(kind), "{kind:?} is missing from the roster");
  }
}

/// **THE WORD ROWS** — the macro an author writes, and the three forms a refusal assembles a
/// sentence out of.
#[test]
fn every_kind_carries_its_words() {
  const fn words(kind: NodeKind) -> Words {
    match kind {
      NodeKind::Operator => Words {
        macro_word: "operator",
        noun: "operator",
        plural: "operators",
        article: "an",
      },
      NodeKind::Entity => Words {
        macro_word: "entity",
        noun: "entity",
        plural: "entities",
        article: "an",
      },
      NodeKind::Record => Words {
        macro_word: "record",
        noun: "record",
        plural: "records",
        article: "a",
      },
      NodeKind::Aggregate => Words {
        macro_word: "aggregate",
        noun: "aggregate",
        plural: "aggregates",
        article: "an",
      },
      NodeKind::Fulltext => Words {
        macro_word: "fulltext",
        noun: "full-text index",
        plural: "full-text indexes",
        article: "a",
      },
      NodeKind::Vector => Words {
        macro_word: "vector",
        noun: "embedding index",
        plural: "embedding indexes",
        article: "an",
      },
      NodeKind::Blob => Words {
        macro_word: "blob",
        noun: "artifact family",
        plural: "artifact families",
        article: "an",
      },
    }
  }

  for kind in ALL {
    let want = words(kind);
    assert_eq!(kind.as_str(), want.macro_word, "{kind:?} macro word");
    assert_eq!(kind.noun(), want.noun, "{kind:?} noun");
    assert_eq!(kind.plural(), want.plural, "{kind:?} plural");
    assert_eq!(kind.article(), want.article, "{kind:?} article");
  }
}

/// **THE ANSWER ROWS** — the six predicates every fork in the two front ends and the emission reads.
#[test]
fn every_kind_answers_every_question() {
  const fn answers(kind: NodeKind) -> Answers {
    match kind {
      NodeKind::Operator => Answers {
        storage_block: None,
        holds_rows: false,
        election: None,
        derives_its_key: false,
        dressable: false,
        stores: false,
      },
      NodeKind::Entity => Answers {
        storage_block: None,
        holds_rows: false,
        election: None,
        derives_its_key: false,
        dressable: true,
        stores: false,
      },
      NodeKind::Record => Answers {
        storage_block: None,
        holds_rows: true,
        election: None,
        derives_its_key: false,
        dressable: true,
        stores: true,
      },
      NodeKind::Aggregate => Answers {
        storage_block: None,
        holds_rows: true,
        election: None,
        derives_its_key: false,
        dressable: true,
        stores: true,
      },
      NodeKind::Fulltext => Answers {
        storage_block: Some("fulltext"),
        holds_rows: false,
        election: Some("searchable"),
        derives_its_key: true,
        dressable: false,
        stores: true,
      },
      NodeKind::Vector => Answers {
        storage_block: Some("vector"),
        holds_rows: false,
        election: Some("knn"),
        derives_its_key: true,
        dressable: false,
        stores: true,
      },
      NodeKind::Blob => Answers {
        storage_block: Some("blob"),
        holds_rows: false,
        election: None,
        derives_its_key: true,
        dressable: false,
        stores: true,
      },
    }
  }

  for kind in ALL {
    let want = answers(kind);
    assert_eq!(kind.storage_block(), want.storage_block, "{kind:?} block");
    assert_eq!(kind.holds_rows(), want.holds_rows, "{kind:?} rows");
    assert_eq!(kind.election(), want.election, "{kind:?} election");
    assert_eq!(kind.derives_its_key(), want.derives_its_key, "{kind:?} key");
    assert_eq!(kind.dressable(), want.dressable, "{kind:?} dressing");
    assert_eq!(kind.stores(), want.stores, "{kind:?} storing");
  }
}

/// **NO TWO KINDS ANSWER TO ONE WORD.** A shared macro word would be a declaration nobody could
/// route, and a shared noun would be a refusal that names the wrong kind back at its author — which
/// is worse than a wrong word, because the sentence still reads.
#[test]
fn the_words_name_one_kind_each() {
  for (at, one) in ALL.iter().enumerate() {
    for other in &ALL[at + 1..] {
      assert_ne!(one.as_str(), other.as_str(), "{one:?} vs {other:?}");
      assert_ne!(one.noun(), other.noun(), "{one:?} vs {other:?}");
      assert_ne!(one.plural(), other.plural(), "{one:?} vs {other:?}");
    }
  }
}

/// **THE ARTICLE AGREES WITH THE NOUN IT PRECEDES.** The whole point of keeping it beside the word
/// is that a sentence assembled with the wrong one is a refusal the reader trips over on the way to
/// the rule; a kind added later that took `article` by copy-paste is exactly the mistake this
/// catches, and no compiler catches it.
///
/// The rule read here is the NAIVE one — a leading vowel takes `an` — which is exactly right for
/// all seven nouns and would be wrong for *a unit* or *an hour*. A kind whose noun starts that way
/// fails here rather than silently, which is the right way round: the failure is a sentence to read
/// aloud once and then except, not a bug to find.
#[test]
fn the_article_agrees_with_its_noun() {
  for kind in ALL {
    let vowel = matches!(
      kind.noun().as_bytes().first(),
      Some(b'a' | b'e' | b'i' | b'o' | b'u')
    );
    let want = if vowel { "an" } else { "a" };
    assert_eq!(
      kind.article(),
      want,
      "{kind:?} says `{article} {noun}`",
      article = kind.article(),
      noun = kind.noun()
    );
  }
}

/// **HOLDING ROWS IMPLIES STORING, AND IMPLIES NO BLOCK TO STORE IN.** Both halves are the unwrap
/// read back: a row-holding kind names its databases BARE at the head, so it has no storage block of
/// its own and every block in the vocabulary is refused on it.
#[test]
fn a_row_holding_kind_stores_and_wraps_nothing() {
  for kind in ALL {
    assert_eq!(
      kind.holds_rows(),
      ROW_HOLDING.contains(&kind),
      "{kind:?} against the row-holding roster"
    );
    if kind.holds_rows() {
      assert!(kind.stores(), "{kind:?} holds rows and must store");
      assert!(
        kind.storage_block().is_none(),
        "{kind:?} holds rows, so its store words are bare at the head"
      );
    }
  }
}

/// **A BORROWED KEY IS THE DERIVED INDEXES' AND NOBODY ELSE'S**, and everything that follows from it
/// follows only for them: a block of its own, and an election word where the kind ranks rather than
/// addresses. An electing kind that minted its own key would be a declaration reaching
/// [`RecordModel`](super::RecordModel) with a corpus hung off a field, which nothing downstream
/// reads.
#[test]
fn only_a_derived_index_carries_its_upstreams_key() {
  for kind in ALL {
    assert_eq!(
      kind.derives_its_key(),
      DERIVED.contains(&kind),
      "{kind:?} against the derived roster"
    );
    if kind.derives_its_key() {
      assert!(
        kind.storage_block().is_some(),
        "{kind:?} borrows a key, so its storage is its own macro's block"
      );
    }
    if kind.election().is_some() {
      assert!(
        kind.derives_its_key(),
        "{kind:?} elects a subject, which only a derived index has"
      );
    }
  }
}

/// **AN AGGREGATE STORES AND MINTS**, which is the seat [`NodeKind::derives_its_key`] pre-argued
/// before there was a kind sitting in it — *a kind that stored without minting or minted without
/// storing would be a coherent thing to add*.
///
/// It is the one kind that NAMES AN UPSTREAM and still carries a key of its own. That is the whole
/// distinction from the three derived indexes, whose shape it otherwise shares: a derived index's
/// entry is about ONE upstream row, so the row's key is the entry's; an aggregate's row is about a
/// GROUP its own declaration projects, so the key is the group and the group is its to mint.
#[test]
fn an_aggregate_stores_and_mints_its_own_key() {
  assert!(NodeKind::Aggregate.stores());
  assert!(!NodeKind::Aggregate.derives_its_key());
  assert!(NodeKind::Aggregate.holds_rows());
}

/// **THE AGGREGATE'S STORAGE ANSWERS ARE A RECORD'S TO THE LETTER**, which is the storage ruling
/// stated as an assertion rather than as a paragraph: the macro mints the `(group…, measure…)` row
/// shape and hands it to the RECORD pass, so every question about where the rows live, how they are
/// declared, whether they publish and whether a write lane lands has one answer across both kinds.
///
/// The fence this is worth having: the tasks after this one wire the grammar, the fold, the emission
/// and the wire face, and any of them could reach for a storage answer of the aggregate's own. The
/// day one does, the design fork it would be re-opening fires here instead of shipping quietly.
///
/// The WORDS are deliberately outside it. Those differ, and must — a refusal that called an
/// aggregate a record would be naming the wrong declaration back at its author.
#[test]
fn an_aggregates_storage_answers_are_a_records() {
  let (aggregate, record) = (NodeKind::Aggregate, NodeKind::Record);

  assert_eq!(aggregate.storage_block(), record.storage_block());
  assert_eq!(aggregate.holds_rows(), record.holds_rows());
  assert_eq!(aggregate.derives_its_key(), record.derives_its_key());
  assert_eq!(aggregate.dressable(), record.dressable());
  assert_eq!(aggregate.stores(), record.stores());
  assert_eq!(aggregate.election(), record.election());

  assert_ne!(aggregate.as_str(), record.as_str());
  assert_ne!(aggregate.noun(), record.noun());
}

/// **AN AGGREGATE ELECTS NO INDEX SUBJECT.** Its fields carry roles — one names a group column, one
/// names a measure — and neither is of this tier: `election` is the word the derived-index grammar
/// spends deciding which field grows a corpus and an engine leg, and an aggregate grows neither.
///
/// Pinned because the reflex points the other way. A kind whose fields obviously carry markers looks
/// like a kind that answers here, and answering would enrol it in the engine machinery on the
/// strength of a spelling.
#[test]
fn an_aggregate_elects_no_index_subject() {
  assert_eq!(NodeKind::Aggregate.election(), None);
  assert_eq!(NodeKind::Aggregate.storage_block(), None);
}