alef_core/

hash.rs

//! Content hashing and generated-file headers.
//!
//! Every file produced by alef gets a standard header that identifies it as
//! generated, tells agents/developers how to fix issues, and embeds a blake3
//! hash so `alef verify` can detect staleness without external state.
//!
//! # Hash semantics
//!
//! As of alef v0.9.0, the embedded `alef:hash:<hex>` value is an
//! **input-deterministic** fingerprint produced by [`compute_generation_hash`]:
//!
//! ```text
//! blake3(sorted(rust_source_files) + alef.toml + alef_version)
//! ```
//!
//! Every file emitted by a single `alef generate` run carries the same hash —
//! it identifies the inputs that produced the run, not the byte-content of the
//! individual file. `alef verify` recomputes the same input hash and compares
//! it to the disk hash without inspecting any file body, which makes verify
//! immune to downstream formatters (rustfmt, rubocop, dotnet format, spotless,
//! biome, mix format, php-cs-fixer, etc.) reformatting alef-generated content.
//!
//! Pre-v0.9.0 alef used per-file output hashing (`hash_content` over the
//! normalised generated content). That function is still exported for the
//! handful of callers that hash arbitrary content (IR cache, language hash for
//! incremental skipping), but it is no longer the verify path.

use std::path::Path;

const HASH_PREFIX: &str = "alef:hash:";

/// The standard header text (without comment delimiters).
/// Used by [`header`] to produce language-specific comment blocks.
const HEADER_BODY: &str = "\
This file is auto-generated by alef — DO NOT EDIT.
To regenerate: alef generate
To verify freshness: alef verify --exit-code
Issues & docs: https://github.com/kreuzberg-dev/alef";

/// Comment style for the generated header.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CommentStyle {
    /// `// line comment`  (Rust, Go, Java, C#, TypeScript, C, PHP)
    DoubleSlash,
    /// `# line comment`   (Python, Ruby, Elixir, R, TOML, Shell, Makefile)
    Hash,
    /// `/* block comment */` (C headers)
    Block,
}

/// Return the standard alef header as a comment block.
///
/// ```text
/// // This file is auto-generated by alef — DO NOT EDIT.
/// // To regenerate: alef generate
/// // To verify freshness: alef verify --exit-code
/// // Issues & docs: https://github.com/kreuzberg-dev/alef
/// ```
pub fn header(style: CommentStyle) -> String {
    match style {
        CommentStyle::DoubleSlash => HEADER_BODY.lines().map(|l| format!("// {l}\n")).collect(),
        CommentStyle::Hash => HEADER_BODY.lines().map(|l| format!("# {l}\n")).collect(),
        CommentStyle::Block => {
            let mut out = String::from("/*\n");
            for line in HEADER_BODY.lines() {
                out.push_str(&format!(" * {line}\n"));
            }
            out.push_str(" */\n");
            out
        }
    }
}

/// The marker string that `inject_hash_line` and `extract_hash` look for.
/// Every alef-generated header contains this on the first line.
const HEADER_MARKER: &str = "auto-generated by alef";

/// Blake3 hash of a content string, returned as hex.
///
/// Used by the IR / language caches and any caller that needs a hash of an
/// in-memory string. **Not used for the embedded `alef:hash:` header** — that
/// is computed once per `alef generate` run by [`compute_generation_hash`].
pub fn hash_content(content: &str) -> String {
    blake3::hash(content.as_bytes()).to_hex().to_string()
}

/// Compute the input-deterministic generation hash that alef embeds into the
/// header of every generated file.
///
/// The hash is a fingerprint of everything that determines the output of
/// `alef generate`:
///
/// - All Rust source files alef parses to build the IR (sorted by path so the
///   order in `alef.toml`'s `[crate].sources` doesn't matter)
/// - The contents of `alef.toml` itself (any config change → new hash)
/// - The alef CLI version (`CARGO_PKG_VERSION` of `alef-cli` at build time)
///
/// `alef verify` recomputes this hash and compares it against the
/// `alef:hash:<hex>` line in each generated file. Because the hash never
/// touches the generated bytes, downstream formatters (rustfmt, rubocop,
/// spotless, dotnet format, php-cs-fixer, biome, mix format, …) can reformat
/// alef-generated files freely without breaking verify.
///
/// # Errors
/// Returns an error if any source file or the config file is missing or
/// unreadable.
pub fn compute_generation_hash(
    sources: &[std::path::PathBuf],
    config_path: &Path,
    alef_version: &str,
) -> std::io::Result<String> {
    let mut hasher = blake3::Hasher::new();

    // Sort by path so the hash is stable regardless of source-file ordering.
    let mut sorted: Vec<&std::path::PathBuf> = sources.iter().collect();
    sorted.sort();

    for source in sorted {
        let content = std::fs::read(source)?;
        // Mix the path in too — the same content at a different path can
        // produce different IR (different `rust_path` on extracted types).
        hasher.update(b"src\0");
        hasher.update(source.to_string_lossy().as_bytes());
        hasher.update(b"\0");
        hasher.update(&content);
    }

    let config_content = std::fs::read(config_path)?;
    hasher.update(b"config\0");
    hasher.update(&config_content);

    hasher.update(b"alef\0");
    hasher.update(alef_version.as_bytes());

    Ok(hasher.finalize().to_hex().to_string())
}

/// Inject an `alef:hash:<hex>` line immediately after the first header marker
/// line found in the first 10 lines.  The comment syntax is inferred from the
/// marker line itself.
///
/// If no marker line is found, the content is returned unchanged.
pub fn inject_hash_line(content: &str, hash: &str) -> String {
    let mut result = String::with_capacity(content.len() + 80);
    let mut injected = false;

    for (i, line) in content.lines().enumerate() {
        result.push_str(line);
        result.push('\n');

        if !injected && i < 10 && line.contains(HEADER_MARKER) {
            let trimmed = line.trim();
            let hash_line = if trimmed.starts_with("<!--") {
                // XML comment: inject hash line as XML comment
                format!("<!-- {HASH_PREFIX}{hash} -->")
            } else if trimmed.starts_with("//") {
                format!("// {HASH_PREFIX}{hash}")
            } else if trimmed.starts_with('#') {
                format!("# {HASH_PREFIX}{hash}")
            } else if trimmed.starts_with("/*") || trimmed.starts_with(" *") || trimmed.ends_with("*/") {
                format!(" * {HASH_PREFIX}{hash}")
            } else {
                format!("// {HASH_PREFIX}{hash}")
            };
            result.push_str(&hash_line);
            result.push('\n');
            injected = true;
        }
    }

    // Preserve original trailing-newline behavior.
    if !content.ends_with('\n') && result.ends_with('\n') {
        result.pop();
    }

    result
}

/// Extract the hash from an `alef:hash:<hex>` token in the first 10 lines.
pub fn extract_hash(content: &str) -> Option<String> {
    for (i, line) in content.lines().enumerate() {
        if i >= 10 {
            break;
        }
        if let Some(pos) = line.find(HASH_PREFIX) {
            let rest = &line[pos + HASH_PREFIX.len()..];
            // Trim trailing comment closers and whitespace.
            let hex = rest.trim().trim_end_matches("*/").trim_end_matches("-->").trim();
            if !hex.is_empty() {
                return Some(hex.to_string());
            }
        }
    }
    None
}

/// Strip the `alef:hash:` line from content (for fallback comparison).
pub fn strip_hash_line(content: &str) -> String {
    let mut result = String::with_capacity(content.len());
    for line in content.lines() {
        if line.contains(HASH_PREFIX) {
            continue;
        }
        result.push_str(line);
        result.push('\n');
    }
    // Preserve original trailing-newline behavior.
    if !content.ends_with('\n') && result.ends_with('\n') {
        result.pop();
    }
    result
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_header_double_slash() {
        let h = header(CommentStyle::DoubleSlash);
        assert!(h.contains("// This file is auto-generated by alef"));
        assert!(h.contains("// Issues & docs: https://github.com/kreuzberg-dev/alef"));
    }

    #[test]
    fn test_header_hash() {
        let h = header(CommentStyle::Hash);
        assert!(h.contains("# This file is auto-generated by alef"));
    }

    #[test]
    fn test_header_block() {
        let h = header(CommentStyle::Block);
        assert!(h.starts_with("/*\n"));
        assert!(h.contains(" * This file is auto-generated by alef"));
        assert!(h.ends_with(" */\n"));
    }

    #[test]
    fn test_inject_and_extract_rust() {
        let h = header(CommentStyle::DoubleSlash);
        let content = format!("{h}use foo;\n");
        let hash = hash_content(&content);
        let injected = inject_hash_line(&content, &hash);
        assert!(injected.contains(HASH_PREFIX));
        assert_eq!(extract_hash(&injected), Some(hash));
    }

    #[test]
    fn test_inject_and_extract_python() {
        let h = header(CommentStyle::Hash);
        let content = format!("{h}import foo\n");
        let hash = hash_content(&content);
        let injected = inject_hash_line(&content, &hash);
        assert!(injected.contains(&format!("# {HASH_PREFIX}")));
        assert_eq!(extract_hash(&injected), Some(hash));
    }

    #[test]
    fn test_inject_and_extract_c_block() {
        let h = header(CommentStyle::Block);
        let content = format!("{h}#include <stdio.h>\n");
        let hash = hash_content(&content);
        let injected = inject_hash_line(&content, &hash);
        assert!(injected.contains(HASH_PREFIX));
        assert_eq!(extract_hash(&injected), Some(hash));
    }

    #[test]
    fn test_inject_php_line2() {
        let h = header(CommentStyle::DoubleSlash);
        let content = format!("<?php\n{h}namespace Foo;\n");
        let hash = hash_content(&content);
        let injected = inject_hash_line(&content, &hash);
        let lines: Vec<&str> = injected.lines().collect();
        assert_eq!(lines[0], "<?php");
        assert!(lines[1].contains(HEADER_MARKER));
        assert!(lines.iter().any(|l| l.contains(HASH_PREFIX)));
        assert_eq!(extract_hash(&injected), Some(hash));
    }

    #[test]
    fn test_no_header_returns_unchanged() {
        let content = "fn main() {}\n";
        let injected = inject_hash_line(content, "abc123");
        assert_eq!(injected, content);
        assert_eq!(extract_hash(&injected), None);
    }

    #[test]
    fn test_strip_hash_line() {
        let content = "// auto-generated by alef\n// alef:hash:abc123\nuse foo;\n";
        let stripped = strip_hash_line(content);
        assert_eq!(stripped, "// auto-generated by alef\nuse foo;\n");
    }

    #[test]
    fn test_roundtrip() {
        let h = header(CommentStyle::Hash);
        let original = format!("{h}import sys\n");
        let hash = hash_content(&original);
        let injected = inject_hash_line(&original, &hash);
        let stripped = strip_hash_line(&injected);
        assert_eq!(stripped, original);
        assert_eq!(hash_content(&stripped), hash);
    }

    // ----- compute_generation_hash tests -----------------------------------

    use std::path::PathBuf;
    use tempfile::tempdir;

    fn write_file(dir: &Path, name: &str, content: &str) -> PathBuf {
        let path = dir.join(name);
        std::fs::write(&path, content).unwrap();
        path
    }

    #[test]
    fn generation_hash_stable_across_runs() {
        let dir = tempdir().unwrap();
        let s1 = write_file(dir.path(), "a.rs", "fn a() {}");
        let s2 = write_file(dir.path(), "b.rs", "fn b() {}");
        let cfg = write_file(dir.path(), "alef.toml", "name = \"x\"");
        let sources = vec![s1, s2];

        let h1 = compute_generation_hash(&sources, &cfg, "0.9.0").unwrap();
        let h2 = compute_generation_hash(&sources, &cfg, "0.9.0").unwrap();
        assert_eq!(h1, h2, "same inputs must produce same hash");
    }

    #[test]
    fn generation_hash_path_order_independent() {
        let dir = tempdir().unwrap();
        let s1 = write_file(dir.path(), "a.rs", "fn a() {}");
        let s2 = write_file(dir.path(), "b.rs", "fn b() {}");
        let cfg = write_file(dir.path(), "alef.toml", "name = \"x\"");

        let h_forward = compute_generation_hash(&[s1.clone(), s2.clone()], &cfg, "0.9.0").unwrap();
        let h_reverse = compute_generation_hash(&[s2, s1], &cfg, "0.9.0").unwrap();
        assert_eq!(h_forward, h_reverse, "source ordering must not affect the hash");
    }

    #[test]
    fn generation_hash_changes_when_alef_version_changes() {
        let dir = tempdir().unwrap();
        let s = write_file(dir.path(), "a.rs", "fn a() {}");
        let cfg = write_file(dir.path(), "alef.toml", "name = \"x\"");
        let sources = [s];

        let h_a = compute_generation_hash(&sources, &cfg, "0.9.0").unwrap();
        let h_b = compute_generation_hash(&sources, &cfg, "0.9.1").unwrap();
        assert_ne!(h_a, h_b, "different alef versions must produce different hashes");
    }

    #[test]
    fn generation_hash_changes_when_config_changes() {
        let dir = tempdir().unwrap();
        let s = write_file(dir.path(), "a.rs", "fn a() {}");
        let cfg_a = write_file(dir.path(), "alef-a.toml", "name = \"x\"");
        let cfg_b = write_file(dir.path(), "alef-b.toml", "name = \"y\"");
        let sources = [s];

        let h_a = compute_generation_hash(&sources, &cfg_a, "0.9.0").unwrap();
        let h_b = compute_generation_hash(&sources, &cfg_b, "0.9.0").unwrap();
        assert_ne!(h_a, h_b, "different config must produce different hashes");
    }

    #[test]
    fn generation_hash_changes_when_source_content_changes() {
        let dir = tempdir().unwrap();
        let s = write_file(dir.path(), "a.rs", "fn a() {}");
        let cfg = write_file(dir.path(), "alef.toml", "name = \"x\"");

        let h_before = compute_generation_hash(std::slice::from_ref(&s), &cfg, "0.9.0").unwrap();
        std::fs::write(&s, "fn a() { let _ = 1; }").unwrap();
        let h_after = compute_generation_hash(&[s], &cfg, "0.9.0").unwrap();
        assert_ne!(h_before, h_after, "modified source must produce different hash");
    }

    #[test]
    fn generation_hash_changes_when_path_changes_even_if_content_same() {
        let dir = tempdir().unwrap();
        let s_a = write_file(dir.path(), "a.rs", "fn a() {}");
        std::fs::create_dir_all(dir.path().join("moved")).unwrap();
        let s_b = write_file(dir.path(), "moved/a.rs", "fn a() {}");
        let cfg = write_file(dir.path(), "alef.toml", "name = \"x\"");

        let h_a = compute_generation_hash(&[s_a], &cfg, "0.9.0").unwrap();
        let h_b = compute_generation_hash(&[s_b], &cfg, "0.9.0").unwrap();
        assert_ne!(
            h_a, h_b,
            "same content at a different path can produce different IR (rust_path differs), so the hash must reflect path"
        );
    }

    #[test]
    fn generation_hash_errors_on_missing_source() {
        let dir = tempdir().unwrap();
        let cfg = write_file(dir.path(), "alef.toml", "name = \"x\"");
        let bogus = dir.path().join("does-not-exist.rs");

        let err = compute_generation_hash(&[bogus], &cfg, "0.9.0");
        assert!(err.is_err(), "missing source must surface as an error");
    }
}