ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! The FOLD an open vocabulary reads every word through — the ONE relation, and the one place it is
//! written.
//!
//! A closed vocabulary's parse is an exact match: its words are its own, a client writes one of
//! them, and a word that is not one of them is a refusal. An OPEN one meets its words in whichever
//! spelling a producer happens to use — `leftShoulder` from a Swift enum, `left_shoulder` from a
//! Python model, `LEFT_SHOULDER` from a protobuf, `Left Shoulder` from a label file — and every one
//! of those is the SAME value. So the door folds before it compares, and what it folds is ASCII case
//! and the three separators.
//!
//! # Why the SEPARATORS go and not just the case
//!
//! A fold that dropped only case would put three of those four spellings on the escape, where they
//! would compare unequal to the variant they name and to each other. The four are not four values;
//! they are four languages writing one.
//!
//! # It is not a SYNONYM table, and the line is the rule
//!
//! `leftShoulder` and `left_shoulder` are one word in two spellings — a fact about a producer's
//! language. `pinky_mcp` and `little_mcp` are two words somebody decided meant the same thing, which
//! is a claim this layer has no authority to make. The fold covers the first and nothing of the
//! second: a vocabulary that wants the second writes a variant for it, or spells it with
//! `#[ingraph(rename = "…")]`.
//!
//! # ONE definition, workspace-wide
//!
//! Both halves of an open vocabulary's door read this module: [`folds_to`] is what the emitted
//! `new` compares each roster word with, and [`folded`] is what it builds the escape's carried word
//! out of. There is no second fold in `ingraph-codegen`, in an expansion, or beside a declaration —
//! an emitted door names `__private::name::folds_to` and calls THIS function, so a change to the
//! relation moves every vocabulary at once and two of them cannot come to disagree.

#[cfg(test)]
mod tests;

/// The three bytes a fold drops wherever they appear.
///
/// A separator and not a character: what they carry is a producer's word BOUNDARY, which every
/// language writes differently and none of them means.
const fn separator(byte: u8) -> bool {
  matches!(byte, b'_' | b'-' | b' ')
}

/// Does `spelling` name the value whose canonical word is `canonical`?
///
/// The comparison IS the fold, WALKED rather than materialised: ASCII case is ignored on both sides
/// and `_`, `-` and a space are skipped wherever they appear, so `leftShoulder`, `left_shoulder`,
/// `LEFT-SHOULDER` and `Left Shoulder` all answer `true` against `left_shoulder`.
///
/// # Why it is a walk and not a normalised copy
///
/// A door that folded its input into a buffer would need a buffer wide enough for every spelling and
/// an answer for the ones that overran it. Walking has neither: the operand is read once per
/// candidate, nothing is allocated, and a spelling of any length is answered.
///
/// # It is BYTE-WISE, and that is the ASCII half of the relation stated honestly
///
/// Only ASCII letters are lowered — `to_ascii_lowercase`'s own domain — so two spellings differing
/// in a non-ASCII letter's case are two words. That is the same line [`folded`] draws, which is what
/// makes the two agree: a folded copy and a folded comparison answer alike, because they drop the
/// same three bytes and lower the same letters.
///
/// # `const`, and the walk is INDEXED for exactly that
///
/// A roster of lanes is a `const`, and the ruling that created it asks for its collisions to be
/// refused AT THE DECLARATION — which means this relation has to be spendable in a constant. So the
/// walk advances two byte INDEXES rather than two filtered iterators; `Iterator::next` is not
/// callable in a constant and `str::as_bytes` is. Nothing else moved: the same three bytes are
/// skipped, the same ASCII case is ignored, and the same pairs answer alike — which this module's
/// own suite pins, unedited, across the widening.
#[must_use]
pub const fn folds_to(spelling: &str, canonical: &str) -> bool {
  let (sent, named) = (spelling.as_bytes(), canonical.as_bytes());
  let (mut at, mut against) = (0usize, 0usize);

  loop {
    while at < sent.len() && separator(sent[at]) {
      at += 1;
    }
    while against < named.len() && separator(named[against]) {
      against += 1;
    }
    if at == sent.len() || against == named.len() {
      // BOTH exhausted is the fold; one of them is a word the other is a prefix of.
      return at == sent.len() && against == named.len();
    }
    if !sent[at].eq_ignore_ascii_case(&named[against]) {
      return false;
    }
    at += 1;
    against += 1;
  }
}

/// The fold, MATERIALISED — what an escape carries.
///
/// The escape holds a FOLDED word rather than the spelling it arrived in, which is what keeps an
/// open vocabulary's [`Eq`] and [`Hash`] about NAMES rather than about spellings: two producers
/// writing `left_paw_extra` and `leftPawExtra` for one word this vocabulary does not name are one
/// value here, compare equal, and land in one bucket.
///
/// It is the same relation [`folds_to`] walks, and it is worth saying which way round they agree:
/// two spellings fold to the same [`String`] exactly when `folds_to` answers `true` for either
/// against the other.
///
/// A [`String`] rather than a carrier, because the carrier is the DECLARATION'S: an escape variant's
/// field type is whatever it was written as, and the emitted door reaches it through
/// [`From<&str>`](From) — so this hands back the one form every carrier is built from.
#[must_use]
pub fn folded(word: &str) -> String {
  let mut folded = String::with_capacity(word.len());

  for character in word.chars() {
    if matches!(character, '_' | '-' | ' ') {
      continue;
    }

    folded.push(character.to_ascii_lowercase());
  }

  folded
}