ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
use super::{ALIAS_PREFIX, DEPTH_CEILING, alias, aliases, refused};

/// The mint at the defaults, which is what a declaration naming no `alias(…)` gets.
fn minted(table: &str, depth: usize) -> String {
  alias(ALIAS_PREFIX, table, depth)
}

/// **The alias wears the reserved prefix and always carries its depth.**
///
/// The depth is rendered even at zero, which is the shape being one shape: a reader indexing the
/// array can read the depth back out of the name, and a mint that dropped it for the first entry
/// would spell two different scopes the same way the moment a second one existed.
#[test]
fn an_alias_wears_the_prefix_and_its_depth() {
  assert_eq!(minted("scene", 0), "__ig_scene_0__");
  assert_eq!(minted("scene", 7), "__ig_scene_7__");
  // Past one digit the depth renders whole rather than wrapping — a `% 10` here would spell 12 as
  // `__ig_scene_2__` and collide with the third level.
  assert_eq!(minted("scene", 12), "__ig_scene_12__");
  assert!(minted("scene", 0).starts_with(ALIAS_PREFIX));
}

/// **Every depth gets its own name**, which is the whole of what makes a nested relation
/// addressable.
///
/// The mutation this catches is the parity scheme the module note refuses: two alternating names
/// pass a test that only ever nests once, and fail silently at the third level.
#[test]
fn the_table_is_distinct_at_every_depth() {
  let minted = aliases(ALIAS_PREFIX, "scene", DEPTH_CEILING);

  assert_eq!(minted.len(), DEPTH_CEILING);
  for (depth, name) in minted.iter().enumerate() {
    assert_eq!(name, &alias(ALIAS_PREFIX, "scene", depth));
  }
  let mut sorted = minted.clone();
  sorted.sort();
  sorted.dedup();
  assert_eq!(sorted.len(), DEPTH_CEILING, "{minted:?}");
}

/// **A clamped alias keeps the prefix and the depth whole, and two long names stay distinct.**
///
/// PostgreSQL truncates an identifier at 63 bytes and MySQL at 64 — SILENTLY — so an alias that
/// arrived longer would reach the server cut, and two aliases differing only past the cut would
/// arrive as ONE name over the wrong row source. The clamp cuts the TABLE instead, and it cannot be
/// a plain truncation: these two names share a leading run far longer than the budget, so
/// truncating alone would spell them identically.
#[test]
fn the_clamp_protects_the_prefix_the_depth_and_distinctness() {
  let shared = "a_very_long_table_name_that_a_generator_would_plausibly_emit";
  let first = minted(shared, 3);
  let second = minted(&format!("{shared}_second"), 3);

  assert!(first.len() <= 63, "{} bytes: {first}", first.len());
  assert!(second.len() <= 63, "{} bytes: {second}", second.len());
  assert!(first.starts_with(ALIAS_PREFIX));
  assert!(first.ends_with("_3__"), "{first}");
  assert!(second.ends_with("_3__"), "{second}");
  assert_ne!(first, second);
}

/// A clamped table stays distinct across its own depths too — the digest is a function of the NAME,
/// so it is the same in every entry and the depth is what still separates them.
#[test]
fn a_clamped_table_is_still_distinct_at_every_depth() {
  let minted = aliases(
    ALIAS_PREFIX,
    "a_very_long_table_name_that_a_generator_would_plausibly_emit",
    DEPTH_CEILING,
  );
  let mut sorted = minted.clone();
  sorted.sort();
  sorted.dedup();

  assert_eq!(sorted.len(), DEPTH_CEILING, "{minted:?}");
  assert!(minted.iter().all(|name| name.len() <= 63), "{minted:?}");
}

/// A multi-byte name is cut on a CHARACTER boundary, so a clamped alias is still a string.
///
/// The ceiling counts bytes, which is the engine's own unit, while a cut inside a multi-byte
/// character produces no `str` at all — so the two units have to be reconciled where the cut is
/// made rather than where the budget is computed.
#[test]
fn the_clamp_cuts_on_a_character_boundary() {
  // `RustSafeName` keeps the external face verbatim, which is the face an alias is built from.
  let minted = minted(&"é".repeat(60), 0);

  assert!(minted.len() <= 63, "{} bytes: {minted}", minted.len());
  assert!(minted.starts_with("__ig_é"), "{minted}");
}

/// **A declared prefix moves the whole family**, and nothing else about a name moves with it.
///
/// The table and the depth stay where they were, so a schema that overrode the namespace to dodge
/// its own legacy tables still reads its aliases the same way — which is the point of moving the
/// prefix rather than the shape.
#[test]
fn a_declared_prefix_moves_every_name() {
  let minted = aliases("__mine", "scene", 3);

  assert_eq!(
    minted,
    ["__mine_scene_0__", "__mine_scene_1__", "__mine_scene_2__"]
  );
}

/// **A declared depth is the array's length**, which is the whole of what makes `DEPTH_CEILING` a
/// default rather than a wall.
///
/// Both directions: sixteen mints past the eighth entry, and one mints the entry the outermost
/// `FROM` never wears and nothing else. The mutation this catches is an emission that reads the
/// depth and then sizes the array by the constant anyway — the sixteenth name is what tells the two
/// apart.
#[test]
fn a_declared_depth_is_the_length() {
  let deep = aliases(ALIAS_PREFIX, "scene", 16);

  assert_eq!(deep.len(), 16);
  assert_eq!(deep[15], "__ig_scene_15__");
  assert_eq!(deep[DEPTH_CEILING], "__ig_scene_8__");
  assert_eq!(aliases(ALIAS_PREFIX, "scene", 1), ["__ig_scene_0__"]);
}

/// **A depth of zero is refused**, and the sentence says what an empty table would do.
#[test]
fn a_depth_of_zero_aliases_nothing() {
  let why = refused(ALIAS_PREFIX, 0).expect("an alias array with no depths aliases nothing");

  assert!(why.contains("aliases nothing"), "{why}");
  assert!(refused(ALIAS_PREFIX, 1).is_none());
}

/// **A prefix that does not lead `__` is refused**, and the reason is the FENCE rather than the
/// mint.
///
/// A minted name is legal SQL whatever it starts with. What a bare prefix would do is confiscate a
/// namespace: the fence refuses every declared column and table name inside the prefix, so
/// `prefix = "tmp"` would make `tmp_cache` undeclarable in a schema whose author has one.
#[test]
fn a_prefix_leads_with_the_framework_fence() {
  let why = refused("mine", DEPTH_CEILING).expect("a bare prefix confiscates a namespace");

  assert!(why.contains("does not begin `__`"), "{why}");
  assert!(refused("", DEPTH_CEILING).is_some(), "nor is an empty one");
  assert!(refused("__mine", DEPTH_CEILING).is_none());
}

/// **A prefix outside the alias charset is refused** — a minted name is read back by eye at a
/// `FROM`, and the joiner it is assembled with is `_`.
#[test]
fn a_prefix_is_letters_digits_and_underscores() {
  let why = refused("__my-name", DEPTH_CEILING).expect("`-` is not in the alias charset");

  assert!(why.contains('-'), "{why}");
  assert!(refused("__my name", DEPTH_CEILING).is_some(), "nor a space");
  assert!(refused("__mine2", DEPTH_CEILING).is_none());
}

/// **A prefix long enough to eat the table's name is refused**, which is the arithmetic the clamp
/// rests on stated as a rule.
///
/// Everything an alias carries competes for the same sixty-three bytes: the prefix, the depth's
/// digits, the separators, and — once a table is long enough to be clamped — the eight-digit digest
/// that keeps two clamped names apart. Past the line there is nothing left for the table to be
/// recognisable by, and the mint would be spelling a name that stands for nothing.
#[test]
fn a_prefix_leaves_room_for_the_table_it_stands_for() {
  let hungry = "__".to_owned() + &"x".repeat(52);
  let why = refused(&hungry, DEPTH_CEILING).expect("nothing is left for the table");

  assert!(why.contains("bytes for the table's own name"), "{why}");
  // The DEEPEST entry is what the rule is measured at, so widening the depth alone can cross the
  // line: this prefix fits while the deepest name renders in one digit, and does not at two.
  let borderline = "__".to_owned() + &"x".repeat(46);
  assert!(refused(&borderline, 10).is_none(), "{borderline}");
  assert!(refused(&borderline, 11).is_some(), "{borderline}");
}

/// **Every alias a clean pair mints fits inside the ceiling**, prefix and depth both moved.
///
/// The clamp's budget is computed from the prefix's OWN length, so a long declared prefix takes its
/// bytes out of the table rather than out of the ceiling. The mutation this catches is a budget
/// still computed against `ALIAS_PREFIX`: every name here would come back over sixty-three bytes,
/// and PostgreSQL would truncate them into collisions.
#[test]
fn a_declared_prefix_pays_for_itself_out_of_the_table() {
  let prefix = "__legacy_schema_namespace";
  assert!(refused(prefix, 12).is_none());

  let minted = aliases(
    prefix,
    "a_table_name_long_enough_to_need_the_clamp_twice_over",
    12,
  );

  assert!(minted.iter().all(|name| name.len() <= 63), "{minted:?}");
  assert!(
    minted.iter().all(|name| name.starts_with(prefix)),
    "{minted:?}"
  );
  let mut sorted = minted.clone();
  sorted.sort();
  sorted.dedup();
  assert_eq!(sorted.len(), 12, "{minted:?}");
}