Why Cargo Keeps Rerunning build.rs: Declaring the Generator's Real Inputs

protogen-naive/build.rs — 291 lines

//! Schema-driven code generator, the way build scripts are usually written.
//!
//! Reads every `.schema` file under `schema/`, parses the record
//! definitions and writes Rust structs with parse functions into
//! `$OUT_DIR/generated.rs`. The crate pulls the result in via `include!`.
//!
//! Deliberately missing: any `cargo:rerun-if-changed` directive. Without
//! it cargo falls back to "rerun when anything in the package changes",
//! so this script runs again after touching a file the schemas never see.

use std::collections::HashSet;
use std::env;
use std::fmt::Write as _;
use std::fs;
use std::path::{Path, PathBuf};
use std::time::Instant;

use anyhow::{Context, Result, ensure};

/// A single `name: type` line inside a record.
struct Field {
    name: String,
    ty: String,
}

/// One `record Name` block parsed from a schema file.
struct Record {
    name: String,
    fields: Vec<Field>,
    source: String,
}

/// Types the generator accepts on the right-hand side of a field.
const ALLOWED_TYPES: &[&str] = &[
    "u8", "u16", "u32", "u64", "i8", "i16", "i32", "i64", "f32", "f64", "bool", "String",
];

fn main() -> Result<()> {
    let started = Instant::now();
    let manifest_dir = env::var("CARGO_MANIFEST_DIR").context("CARGO_MANIFEST_DIR not set")?;
    let out_dir = env::var("OUT_DIR").context("OUT_DIR not set")?;
    let schema_dir = Path::new(&manifest_dir).join("schema");

    let files = schema_files(&schema_dir)?;
    ensure!(!files.is_empty(), "no .schema files in {schema_dir:?}");

    let mut records = Vec::new();
    for file in &files {
        let mut parsed = parse_schema_file(file)?;
        records.append(&mut parsed);
    }
    check_unique_names(&records)?;

    // Strict mode makes generated parsers reject unknown keys. The env
    // var is read here, at generation time, and baked into the output.
    let strict = env::var("PROTOGEN_STRICT").is_ok_and(|value| value == "1");

    let code = generate(&records, &files, strict)?;
    let target = PathBuf::from(&out_dir).join("generated.rs");
    fs::write(&target, code).with_context(|| format!("writing {target:?}"))?;

    // Visible in `cargo build -vv` output: proof of every rerun.
    println!(
        "protogen: {} records from {} schema files in {:?}",
        records.len(),
        files.len(),
        started.elapsed(),
    );
    Ok(())
}

/// Lists `.schema` files in the schema directory, sorted by name so the
/// generated output is deterministic.
fn schema_files(dir: &Path) -> Result<Vec<PathBuf>> {
    let entries = fs::read_dir(dir).with_context(|| format!("reading {dir:?}"))?;
    let mut files = Vec::new();
    for entry in entries {
        let path = entry.context("reading directory entry")?.path();
        let is_schema = path.extension().is_some_and(|ext| ext == "schema");
        if is_schema {
            files.push(path);
        }
    }
    files.sort();
    Ok(files)
}

/// Parses one schema file into records.
fn parse_schema_file(path: &Path) -> Result<Vec<Record>> {
    let text = fs::read_to_string(path).with_context(|| format!("reading {path:?}"))?;
    let source = path
        .file_name()
        .context("schema path has no file name")?
        .to_string_lossy()
        .into_owned();

    let mut records: Vec<Record> = Vec::new();
    for (index, raw_line) in text.lines().enumerate() {
        let line = raw_line.trim();
        let location = format!("{source}:{}", index + 1);
        if line.is_empty() {
            continue;
        }
        if line.starts_with('#') {
            continue;
        }
        if let Some(name) = line.strip_prefix("record ") {
            let name = name.trim();
            ensure!(is_type_name(name), "{location}: bad record name {name:?}");
            records.push(Record {
                name: name.to_string(),
                fields: Vec::new(),
                source: source.clone(),
            });
            continue;
        }
        let (name, ty) = line
            .split_once(':')
            .with_context(|| format!("{location}: expected `name: type`, got {line:?}"))?;
        let field = Field {
            name: name.trim().to_string(),
            ty: ty.trim().to_string(),
        };
        ensure!(
            is_field_name(&field.name),
            "{location}: bad field name {:?}",
            field.name
        );
        ensure!(
            ALLOWED_TYPES.contains(&field.ty.as_str()),
            "{location}: unsupported type {:?}",
            field.ty
        );
        let record = records
            .last_mut()
            .with_context(|| format!("{location}: field before any `record`"))?;
        record.fields.push(field);
    }
    for record in &records {
        ensure!(
            !record.fields.is_empty(),
            "{source}: record {} has no fields",
            record.name
        );
    }
    Ok(records)
}

/// Rejects duplicate record names across all schema files.
fn check_unique_names(records: &[Record]) -> Result<()> {
    let mut seen = HashSet::new();
    for record in records {
        let fresh = seen.insert(record.name.as_str());
        ensure!(
            fresh,
            "duplicate record name {} in {}",
            record.name,
            record.source
        );
    }
    Ok(())
}

/// `true` for `UpperCamel` identifiers.
fn is_type_name(name: &str) -> bool {
    let mut chars = name.chars();
    let head_ok = chars.next().is_some_and(|first| first.is_ascii_uppercase());
    head_ok && chars.all(|ch| ch.is_ascii_alphanumeric())
}

/// `true` for `lower_snake` identifiers.
fn is_field_name(name: &str) -> bool {
    let mut chars = name.chars();
    let head_ok = chars.next().is_some_and(|first| first.is_ascii_lowercase());
    head_ok && chars.all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '_')
}

/// Renders the whole generated module as one string.
fn generate(records: &[Record], files: &[PathBuf], strict: bool) -> Result<String> {
    let mut out = String::new();
    writeln!(out, "// Generated by build.rs — do not edit by hand.")?;
    writeln!(out)?;
    writeln!(out, "/// Number of records across all schema files.")?;
    writeln!(out, "pub const RECORD_COUNT: usize = {};", records.len())?;
    writeln!(out, "/// Schema files the build script consumed, sorted.")?;
    write!(out, "pub const SCHEMA_FILES: &[&str] = &[")?;
    for file in files {
        let name = file
            .file_name()
            .context("schema path has no file name")?
            .to_string_lossy();
        write!(out, "{name:?}, ")?;
    }
    writeln!(out, "];")?;
    writeln!(out, "/// Whether generated parsers reject unknown keys.")?;
    writeln!(out, "pub const STRICT_MODE: bool = {strict};")?;
    for record in records {
        render_record(&mut out, record, strict)?;
    }
    Ok(out)
}

/// Renders one struct plus its `parse` / `field_names` impl.
fn render_record(out: &mut String, record: &Record, strict: bool) -> Result<()> {
    writeln!(out)?;
    writeln!(out, "/// Generated from `{}`.", record.source)?;
    writeln!(out, "#[derive(Debug, Clone, PartialEq)]")?;
    writeln!(out, "pub struct {} {{", record.name)?;
    for field in &record.fields {
        writeln!(out, "    pub {}: {},", field.name, field.ty)?;
    }
    writeln!(out, "}}")?;
    writeln!(out)?;
    writeln!(out, "impl {} {{", record.name)?;
    writeln!(out, "    /// Field names in schema order.")?;
    writeln!(
        out,
        "    pub fn field_names() -> &'static [&'static str] {{"
    )?;
    write!(out, "        &[")?;
    for field in &record.fields {
        write!(out, "{:?}, ", field.name)?;
    }
    writeln!(out, "]")?;
    writeln!(out, "    }}")?;
    writeln!(out)?;
    writeln!(
        out,
        "    /// Parses a `key=value;key=value` line into the record."
    )?;
    writeln!(
        out,
        "    pub fn parse(input: &str) -> Result<Self, String> {{"
    )?;
    for field in &record.fields {
        writeln!(
            out,
            "        let mut {}: Option<{}> = None;",
            field.name, field.ty
        )?;
    }
    writeln!(out, "        for pair in input.split(';') {{")?;
    writeln!(out, "            let pair = pair.trim();")?;
    writeln!(out, "            if pair.is_empty() {{")?;
    writeln!(out, "                continue;")?;
    writeln!(out, "            }}")?;
    writeln!(out, "            let (key, value) = pair")?;
    writeln!(out, "                .split_once('=')")?;
    writeln!(
        out,
        "                .ok_or_else(|| format!(\"bad pair: {{pair}}\"))?;"
    )?;
    writeln!(out, "            match key.trim() {{")?;
    for field in &record.fields {
        let convert = if field.ty == "String" {
            "value.trim().to_string()".to_string()
        } else {
            format!(
                "value.trim().parse::<{}>().map_err(|error| format!(\"{}: {{error}}\"))?",
                field.ty, field.name
            )
        };
        writeln!(
            out,
            "                {:?} => {} = Some({convert}),",
            field.name, field.name
        )?;
    }
    if strict {
        writeln!(
            out,
            "                other => return Err(format!(\"unknown key: {{other}}\")),"
        )?;
    } else {
        writeln!(out, "                _other => {{}}")?;
    }
    writeln!(out, "            }}")?;
    writeln!(out, "        }}")?;
    writeln!(out, "        Ok(Self {{")?;
    for field in &record.fields {
        writeln!(
            out,
            "            {}: {}.ok_or(\"missing field: {}\")?,",
            field.name, field.name, field.name
        )?;
    }
    writeln!(out, "        }})")?;
    writeln!(out, "    }}")?;
    writeln!(out, "}}")?;
    Ok(())
}

protogen-naive/Cargo.toml — 11 lines

[package]
name = "protogen-naive"
version = "0.1.0"
edition = "2024"
publish = false

[dependencies]
anyhow = "1"

[build-dependencies]
anyhow = "1"

protogen-naive/src/lib.rs — 6 lines

//! Types generated at build time from `schema/*.schema`.
//!
//! The whole module body lives in `$OUT_DIR/generated.rs`; the build
//! script writes it, this file only pulls it in.

include!(concat!(env!("OUT_DIR"), "/generated.rs"));

protogen-naive/src/main.rs — 21 lines

//! Smoke check for the generated types: parse one wire line per record
//! kind and report what the build script produced.

use anyhow::{Error, Result};

use protogen_naive::{LimitConfig, RECORD_COUNT, SCHEMA_FILES, STRICT_MODE, SensorReading};

fn main() -> Result<()> {
    println!(
        "records generated: {RECORD_COUNT} from {} schema files",
        SCHEMA_FILES.len()
    );
    println!("strict mode: {STRICT_MODE}");
    println!("LimitConfig fields: {:?}", LimitConfig::field_names());

    let wire = "device_id=42;channel=3;temperature_mc=21500;\
                humidity_ppm=440000;captured_at_ms=1754300000000;healthy=true";
    let reading = SensorReading::parse(wire).map_err(Error::msg)?;
    println!("parsed: {reading:?}");
    Ok(())
}

protogen-naive/schema/core.schema — 22 lines

# Core telemetry records the ingest node accepts.
# Format: `record Name` opens a record, indented `name: type` lines
# declare fields, `#` starts a comment.

record SensorReading
  device_id: u32
  channel: u16
  temperature_mc: i32
  humidity_ppm: u32
  captured_at_ms: u64
  healthy: bool

record DeviceEvent
  device_id: u32
  kind: String
  payload: String
  emitted_at_ms: u64

record LimitConfig
  max_batch: u32
  flush_interval_ms: u64
  compression: String

protogen-precise/build.rs — 293 lines

//! Schema-driven code generator, incremental edition.
//!
//! Same generator as `01-rerun-everything`, one difference: it declares
//! its real inputs. `cargo:rerun-if-changed=schema/` narrows the rerun
//! trigger from "anything in the package" down to the schema directory,
//! and `cargo:rerun-if-env-changed` covers the env var the script reads.

use std::collections::HashSet;
use std::env;
use std::fmt::Write as _;
use std::fs;
use std::path::{Path, PathBuf};
use std::time::Instant;

use anyhow::{Context, Result, ensure};

/// A single `name: type` line inside a record.
struct Field {
    name: String,
    ty: String,
}

/// One `record Name` block parsed from a schema file.
struct Record {
    name: String,
    fields: Vec<Field>,
    source: String,
}

/// Types the generator accepts on the right-hand side of a field.
const ALLOWED_TYPES: &[&str] = &[
    "u8", "u16", "u32", "u64", "i8", "i16", "i32", "i64", "f32", "f64", "bool", "String",
];

fn main() -> Result<()> {
    let started = Instant::now();
    let manifest_dir = env::var("CARGO_MANIFEST_DIR").context("CARGO_MANIFEST_DIR not set")?;
    let out_dir = env::var("OUT_DIR").context("OUT_DIR not set")?;
    let schema_dir = Path::new(&manifest_dir).join("schema");

    let files = schema_files(&schema_dir)?;
    ensure!(!files.is_empty(), "no .schema files in {schema_dir:?}");

    let mut records = Vec::new();
    for file in &files {
        let mut parsed = parse_schema_file(file)?;
        records.append(&mut parsed);
    }
    check_unique_names(&records)?;

    // Strict mode makes generated parsers reject unknown keys. The env
    // var is read here, at generation time, and baked into the output.
    let strict = env::var("PROTOGEN_STRICT").is_ok_and(|value| value == "1");

    let code = generate(&records, &files, strict)?;
    let target = PathBuf::from(&out_dir).join("generated.rs");
    fs::write(&target, code).with_context(|| format!("writing {target:?}"))?;

    // The fix: declare the real inputs. Cargo now reruns this script
    // only when the schema directory or the declared env var changes.
    println!("cargo:rerun-if-changed=schema/");
    println!("cargo:rerun-if-env-changed=PROTOGEN_STRICT");

    // Visible in `cargo build -vv` output: proof of every rerun.
    println!(
        "protogen: {} records from {} schema files in {:?}",
        records.len(),
        files.len(),
        started.elapsed(),
    );
    Ok(())
}

/// Lists `.schema` files in the schema directory, sorted by name so the
/// generated output is deterministic.
fn schema_files(dir: &Path) -> Result<Vec<PathBuf>> {
    let entries = fs::read_dir(dir).with_context(|| format!("reading {dir:?}"))?;
    let mut files = Vec::new();
    for entry in entries {
        let path = entry.context("reading directory entry")?.path();
        let is_schema = path.extension().is_some_and(|ext| ext == "schema");
        if is_schema {
            files.push(path);
        }
    }
    files.sort();
    Ok(files)
}

/// Parses one schema file into records.
fn parse_schema_file(path: &Path) -> Result<Vec<Record>> {
    let text = fs::read_to_string(path).with_context(|| format!("reading {path:?}"))?;
    let source = path
        .file_name()
        .context("schema path has no file name")?
        .to_string_lossy()
        .into_owned();

    let mut records: Vec<Record> = Vec::new();
    for (index, raw_line) in text.lines().enumerate() {
        let line = raw_line.trim();
        let location = format!("{source}:{}", index + 1);
        if line.is_empty() {
            continue;
        }
        if line.starts_with('#') {
            continue;
        }
        if let Some(name) = line.strip_prefix("record ") {
            let name = name.trim();
            ensure!(is_type_name(name), "{location}: bad record name {name:?}");
            records.push(Record {
                name: name.to_string(),
                fields: Vec::new(),
                source: source.clone(),
            });
            continue;
        }
        let (name, ty) = line
            .split_once(':')
            .with_context(|| format!("{location}: expected `name: type`, got {line:?}"))?;
        let field = Field {
            name: name.trim().to_string(),
            ty: ty.trim().to_string(),
        };
        ensure!(
            is_field_name(&field.name),
            "{location}: bad field name {:?}",
            field.name
        );
        ensure!(
            ALLOWED_TYPES.contains(&field.ty.as_str()),
            "{location}: unsupported type {:?}",
            field.ty
        );
        let record = records
            .last_mut()
            .with_context(|| format!("{location}: field before any `record`"))?;
        record.fields.push(field);
    }
    for record in &records {
        ensure!(
            !record.fields.is_empty(),
            "{source}: record {} has no fields",
            record.name
        );
    }
    Ok(records)
}

/// Rejects duplicate record names across all schema files.
fn check_unique_names(records: &[Record]) -> Result<()> {
    let mut seen = HashSet::new();
    for record in records {
        let fresh = seen.insert(record.name.as_str());
        ensure!(
            fresh,
            "duplicate record name {} in {}",
            record.name,
            record.source
        );
    }
    Ok(())
}

/// `true` for `UpperCamel` identifiers.
fn is_type_name(name: &str) -> bool {
    let mut chars = name.chars();
    let head_ok = chars.next().is_some_and(|first| first.is_ascii_uppercase());
    head_ok && chars.all(|ch| ch.is_ascii_alphanumeric())
}

/// `true` for `lower_snake` identifiers.
fn is_field_name(name: &str) -> bool {
    let mut chars = name.chars();
    let head_ok = chars.next().is_some_and(|first| first.is_ascii_lowercase());
    head_ok && chars.all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '_')
}

/// Renders the whole generated module as one string.
fn generate(records: &[Record], files: &[PathBuf], strict: bool) -> Result<String> {
    let mut out = String::new();
    writeln!(out, "// Generated by build.rs — do not edit by hand.")?;
    writeln!(out)?;
    writeln!(out, "/// Number of records across all schema files.")?;
    writeln!(out, "pub const RECORD_COUNT: usize = {};", records.len())?;
    writeln!(out, "/// Schema files the build script consumed, sorted.")?;
    write!(out, "pub const SCHEMA_FILES: &[&str] = &[")?;
    for file in files {
        let name = file
            .file_name()
            .context("schema path has no file name")?
            .to_string_lossy();
        write!(out, "{name:?}, ")?;
    }
    writeln!(out, "];")?;
    writeln!(out, "/// Whether generated parsers reject unknown keys.")?;
    writeln!(out, "pub const STRICT_MODE: bool = {strict};")?;
    for record in records {
        render_record(&mut out, record, strict)?;
    }
    Ok(out)
}

/// Renders one struct plus its `parse` / `field_names` impl.
fn render_record(out: &mut String, record: &Record, strict: bool) -> Result<()> {
    writeln!(out)?;
    writeln!(out, "/// Generated from `{}`.", record.source)?;
    writeln!(out, "#[derive(Debug, Clone, PartialEq)]")?;
    writeln!(out, "pub struct {} {{", record.name)?;
    for field in &record.fields {
        writeln!(out, "    pub {}: {},", field.name, field.ty)?;
    }
    writeln!(out, "}}")?;
    writeln!(out)?;
    writeln!(out, "impl {} {{", record.name)?;
    writeln!(out, "    /// Field names in schema order.")?;
    writeln!(
        out,
        "    pub fn field_names() -> &'static [&'static str] {{"
    )?;
    write!(out, "        &[")?;
    for field in &record.fields {
        write!(out, "{:?}, ", field.name)?;
    }
    writeln!(out, "]")?;
    writeln!(out, "    }}")?;
    writeln!(out)?;
    writeln!(
        out,
        "    /// Parses a `key=value;key=value` line into the record."
    )?;
    writeln!(
        out,
        "    pub fn parse(input: &str) -> Result<Self, String> {{"
    )?;
    for field in &record.fields {
        writeln!(
            out,
            "        let mut {}: Option<{}> = None;",
            field.name, field.ty
        )?;
    }
    writeln!(out, "        for pair in input.split(';') {{")?;
    writeln!(out, "            let pair = pair.trim();")?;
    writeln!(out, "            if pair.is_empty() {{")?;
    writeln!(out, "                continue;")?;
    writeln!(out, "            }}")?;
    writeln!(out, "            let (key, value) = pair")?;
    writeln!(out, "                .split_once('=')")?;
    writeln!(
        out,
        "                .ok_or_else(|| format!(\"bad pair: {{pair}}\"))?;"
    )?;
    writeln!(out, "            match key.trim() {{")?;
    for field in &record.fields {
        let convert = if field.ty == "String" {
            "value.trim().to_string()".to_string()
        } else {
            format!(
                "value.trim().parse::<{}>().map_err(|error| format!(\"{}: {{error}}\"))?",
                field.ty, field.name
            )
        };
        writeln!(
            out,
            "                {:?} => {} = Some({convert}),",
            field.name, field.name
        )?;
    }
    if strict {
        writeln!(
            out,
            "                other => return Err(format!(\"unknown key: {{other}}\")),"
        )?;
    } else {
        writeln!(out, "                _other => {{}}")?;
    }
    writeln!(out, "            }}")?;
    writeln!(out, "        }}")?;
    writeln!(out, "        Ok(Self {{")?;
    for field in &record.fields {
        writeln!(
            out,
            "            {}: {}.ok_or(\"missing field: {}\")?,",
            field.name, field.name, field.name
        )?;
    }
    writeln!(out, "        }})")?;
    writeln!(out, "    }}")?;
    writeln!(out, "}}")?;
    Ok(())
}

protogen-incomplete/build.rs — 294 lines

//! Schema-driven code generator, the trap edition.
//!
//! Same generator as the other two crates, but the directives at the
//! bottom are wrong in the classic way: rerun-if-changed points at ONE
//! schema file, while the script reads the whole directory plus an env
//! var. Cargo believes the declaration, not the actual reads — so edits
//! to `extra.schema`, new schema files and `PROTOGEN_STRICT` changes all
//! produce silently stale generated types.

use std::collections::HashSet;
use std::env;
use std::fmt::Write as _;
use std::fs;
use std::path::{Path, PathBuf};
use std::time::Instant;

use anyhow::{Context, Result, ensure};

/// A single `name: type` line inside a record.
struct Field {
    name: String,
    ty: String,
}

/// One `record Name` block parsed from a schema file.
struct Record {
    name: String,
    fields: Vec<Field>,
    source: String,
}

/// Types the generator accepts on the right-hand side of a field.
const ALLOWED_TYPES: &[&str] = &[
    "u8", "u16", "u32", "u64", "i8", "i16", "i32", "i64", "f32", "f64", "bool", "String",
];

fn main() -> Result<()> {
    let started = Instant::now();
    let manifest_dir = env::var("CARGO_MANIFEST_DIR").context("CARGO_MANIFEST_DIR not set")?;
    let out_dir = env::var("OUT_DIR").context("OUT_DIR not set")?;
    let schema_dir = Path::new(&manifest_dir).join("schema");

    let files = schema_files(&schema_dir)?;
    ensure!(!files.is_empty(), "no .schema files in {schema_dir:?}");

    let mut records = Vec::new();
    for file in &files {
        let mut parsed = parse_schema_file(file)?;
        records.append(&mut parsed);
    }
    check_unique_names(&records)?;

    // Strict mode makes generated parsers reject unknown keys. The env
    // var is read here, at generation time, and baked into the output.
    let strict = env::var("PROTOGEN_STRICT").is_ok_and(|value| value == "1");

    let code = generate(&records, &files, strict)?;
    let target = PathBuf::from(&out_dir).join("generated.rs");
    fs::write(&target, code).with_context(|| format!("writing {target:?}"))?;

    // The trap: one file declared, the rest of the inputs forgotten.
    // From here on cargo trusts this line and ignores everything else.
    println!("cargo:rerun-if-changed=schema/base.schema");

    // Visible in `cargo build -vv` output: proof of every rerun.
    println!(
        "protogen: {} records from {} schema files in {:?}",
        records.len(),
        files.len(),
        started.elapsed(),
    );
    Ok(())
}

/// Lists `.schema` files in the schema directory, sorted by name so the
/// generated output is deterministic.
fn schema_files(dir: &Path) -> Result<Vec<PathBuf>> {
    let entries = fs::read_dir(dir).with_context(|| format!("reading {dir:?}"))?;
    let mut files = Vec::new();
    for entry in entries {
        let path = entry.context("reading directory entry")?.path();
        let is_schema = path.extension().is_some_and(|ext| ext == "schema");
        if is_schema {
            files.push(path);
        }
    }
    files.sort();
    Ok(files)
}

/// Parses one schema file into records.
fn parse_schema_file(path: &Path) -> Result<Vec<Record>> {
    let text = fs::read_to_string(path).with_context(|| format!("reading {path:?}"))?;
    let source = path
        .file_name()
        .context("schema path has no file name")?
        .to_string_lossy()
        .into_owned();

    let mut records: Vec<Record> = Vec::new();
    for (index, raw_line) in text.lines().enumerate() {
        let line = raw_line.trim();
        let location = format!("{source}:{}", index + 1);
        if line.is_empty() {
            continue;
        }
        if line.starts_with('#') {
            continue;
        }
        if let Some(name) = line.strip_prefix("record ") {
            let name = name.trim();
            ensure!(is_type_name(name), "{location}: bad record name {name:?}");
            records.push(Record {
                name: name.to_string(),
                fields: Vec::new(),
                source: source.clone(),
            });
            continue;
        }
        let (name, ty) = line
            .split_once(':')
            .with_context(|| format!("{location}: expected `name: type`, got {line:?}"))?;
        let field = Field {
            name: name.trim().to_string(),
            ty: ty.trim().to_string(),
        };
        ensure!(
            is_field_name(&field.name),
            "{location}: bad field name {:?}",
            field.name
        );
        ensure!(
            ALLOWED_TYPES.contains(&field.ty.as_str()),
            "{location}: unsupported type {:?}",
            field.ty
        );
        let record = records
            .last_mut()
            .with_context(|| format!("{location}: field before any `record`"))?;
        record.fields.push(field);
    }
    for record in &records {
        ensure!(
            !record.fields.is_empty(),
            "{source}: record {} has no fields",
            record.name
        );
    }
    Ok(records)
}

/// Rejects duplicate record names across all schema files.
fn check_unique_names(records: &[Record]) -> Result<()> {
    let mut seen = HashSet::new();
    for record in records {
        let fresh = seen.insert(record.name.as_str());
        ensure!(
            fresh,
            "duplicate record name {} in {}",
            record.name,
            record.source
        );
    }
    Ok(())
}

/// `true` for `UpperCamel` identifiers.
fn is_type_name(name: &str) -> bool {
    let mut chars = name.chars();
    let head_ok = chars.next().is_some_and(|first| first.is_ascii_uppercase());
    head_ok && chars.all(|ch| ch.is_ascii_alphanumeric())
}

/// `true` for `lower_snake` identifiers.
fn is_field_name(name: &str) -> bool {
    let mut chars = name.chars();
    let head_ok = chars.next().is_some_and(|first| first.is_ascii_lowercase());
    head_ok && chars.all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '_')
}

/// Renders the whole generated module as one string.
fn generate(records: &[Record], files: &[PathBuf], strict: bool) -> Result<String> {
    let mut out = String::new();
    writeln!(out, "// Generated by build.rs — do not edit by hand.")?;
    writeln!(out)?;
    writeln!(out, "/// Number of records across all schema files.")?;
    writeln!(out, "pub const RECORD_COUNT: usize = {};", records.len())?;
    writeln!(out, "/// Schema files the build script consumed, sorted.")?;
    write!(out, "pub const SCHEMA_FILES: &[&str] = &[")?;
    for file in files {
        let name = file
            .file_name()
            .context("schema path has no file name")?
            .to_string_lossy();
        write!(out, "{name:?}, ")?;
    }
    writeln!(out, "];")?;
    writeln!(out, "/// Whether generated parsers reject unknown keys.")?;
    writeln!(out, "pub const STRICT_MODE: bool = {strict};")?;
    for record in records {
        render_record(&mut out, record, strict)?;
    }
    Ok(out)
}

/// Renders one struct plus its `parse` / `field_names` impl.
fn render_record(out: &mut String, record: &Record, strict: bool) -> Result<()> {
    writeln!(out)?;
    writeln!(out, "/// Generated from `{}`.", record.source)?;
    writeln!(out, "#[derive(Debug, Clone, PartialEq)]")?;
    writeln!(out, "pub struct {} {{", record.name)?;
    for field in &record.fields {
        writeln!(out, "    pub {}: {},", field.name, field.ty)?;
    }
    writeln!(out, "}}")?;
    writeln!(out)?;
    writeln!(out, "impl {} {{", record.name)?;
    writeln!(out, "    /// Field names in schema order.")?;
    writeln!(
        out,
        "    pub fn field_names() -> &'static [&'static str] {{"
    )?;
    write!(out, "        &[")?;
    for field in &record.fields {
        write!(out, "{:?}, ", field.name)?;
    }
    writeln!(out, "]")?;
    writeln!(out, "    }}")?;
    writeln!(out)?;
    writeln!(
        out,
        "    /// Parses a `key=value;key=value` line into the record."
    )?;
    writeln!(
        out,
        "    pub fn parse(input: &str) -> Result<Self, String> {{"
    )?;
    for field in &record.fields {
        writeln!(
            out,
            "        let mut {}: Option<{}> = None;",
            field.name, field.ty
        )?;
    }
    writeln!(out, "        for pair in input.split(';') {{")?;
    writeln!(out, "            let pair = pair.trim();")?;
    writeln!(out, "            if pair.is_empty() {{")?;
    writeln!(out, "                continue;")?;
    writeln!(out, "            }}")?;
    writeln!(out, "            let (key, value) = pair")?;
    writeln!(out, "                .split_once('=')")?;
    writeln!(
        out,
        "                .ok_or_else(|| format!(\"bad pair: {{pair}}\"))?;"
    )?;
    writeln!(out, "            match key.trim() {{")?;
    for field in &record.fields {
        let convert = if field.ty == "String" {
            "value.trim().to_string()".to_string()
        } else {
            format!(
                "value.trim().parse::<{}>().map_err(|error| format!(\"{}: {{error}}\"))?",
                field.ty, field.name
            )
        };
        writeln!(
            out,
            "                {:?} => {} = Some({convert}),",
            field.name, field.name
        )?;
    }
    if strict {
        writeln!(
            out,
            "                other => return Err(format!(\"unknown key: {{other}}\")),"
        )?;
    } else {
        writeln!(out, "                _other => {{}}")?;
    }
    writeln!(out, "            }}")?;
    writeln!(out, "        }}")?;
    writeln!(out, "        Ok(Self {{")?;
    for field in &record.fields {
        writeln!(
            out,
            "            {}: {}.ok_or(\"missing field: {}\")?,",
            field.name, field.name, field.name
        )?;
    }
    writeln!(out, "        }})")?;
    writeln!(out, "    }}")?;
    writeln!(out, "}}")?;
    Ok(())
}

protogen-incomplete/schema/base.schema — 15 lines

# Wire records, part one. The build script declares THIS file
# in rerun-if-changed — and only this file.

record SensorReading
  device_id: u32
  channel: u16
  temperature_mc: i32
  captured_at_ms: u64
  healthy: bool

record DeviceEvent
  device_id: u32
  kind: String
  payload: String
  emitted_at_ms: u64

protogen-incomplete/schema/extra.schema — 8 lines

# Wire records, part two. The build script reads this file as well —
# but forgot to declare it in rerun-if-changed. Edits here are invisible
# to cargo: the generated types silently go stale.

record LimitConfig
  max_batch: u32
  flush_interval_ms: u64
  compression: String