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.10.1, the embedded `alef:hash:<hex>` value is a **per-file
//! source+output fingerprint** produced by [`compute_file_hash`]:
//!
//! ```text
//! blake3(sources_hash || file_content_without_hash_line)
//! ```
//!
//! Where `sources_hash` is [`compute_sources_hash`] over the sorted Rust source
//! files alef parses to build the IR. The hash deliberately does **not**
//! include the alef version or `alef.toml`: any input change that affects the
//! generated bytes is already reflected by hashing the file content itself,
//! and excluding the alef version makes `alef verify` idempotent across
//! `alef` upgrades — a CI run on a tagged repo continues to pass after the
//! alef CLI is bumped, as long as the rust sources and emitted file contents
//! are unchanged.
//!
//! `alef generate` finalises the embedded hash *after* downstream formatters
//! (rustfmt, rubocop, dotnet format, spotless, biome, mix format, php-cs-fixer,
//! mix format, …) have run, so the embedded hash describes the actual
//! on-disk byte-content. `alef verify` reads the file, strips the
//! `alef:hash:` line, recomputes the same hash, and compares — no
//! regeneration, no writes.
//!
//! Pre-v0.10.1 alef used a single input-deterministic hash that incorporated
//! the alef CLI version, which forced every consumer repo to re-run
//! `alef generate` after every alef bump even when nothing else changed.

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 by [`compute_file_hash`].
pub fn hash_content(content: &str) -> String {
    blake3::hash(content.as_bytes()).to_hex().to_string()
}

/// Compute a stable hash over the Rust source files that alef extracts.
///
/// This is the "source side" of the per-file verify hash. Sources are sorted
/// by path so the hash is stable regardless of ordering in
/// `alef.toml`'s `[crate].sources`. The path is mixed in alongside the
/// content because the same byte-content at a different path produces
/// different IR (the `rust_path` on extracted types differs).
///
/// Used by [`compute_file_hash`]; not by itself the value embedded in any
/// file header.
///
/// # Errors
/// Returns an error if any source file is missing or unreadable.
pub fn compute_sources_hash(sources: &[std::path::PathBuf]) -> std::io::Result<String> {
    let mut hasher = blake3::Hasher::new();
    let mut sorted: Vec<&std::path::PathBuf> = sources.iter().collect();
    sorted.sort();
    for source in sorted {
        let content = std::fs::read(source)?;
        hasher.update(b"src\0");
        hasher.update(source.to_string_lossy().as_bytes());
        hasher.update(b"\0");
        hasher.update(&content);
    }
    Ok(hasher.finalize().to_hex().to_string())
}

/// Compute the per-file verify hash that alef embeds in each generated file.
///
/// `sources_hash` comes from [`compute_sources_hash`]. `content` is the file
/// content; any pre-existing `alef:hash:` line is stripped before hashing so
/// the function is idempotent — calling it on file content that already has a
/// hash line returns the same value as calling it on the same content with no
/// hash line. This makes the verify path symmetric with the generate path:
///
/// - **Generate**: write the file, run formatters, then call this with the
///   on-disk content and inject the result.
/// - **Verify**: read the file, extract the existing hash line, call this
///   with the on-disk content, compare.
pub fn compute_file_hash(sources_hash: &str, content: &str) -> String {
    let stripped = strip_hash_line(content);
    let mut hasher = blake3::Hasher::new();
    hasher.update(b"sources\0");
    hasher.update(sources_hash.as_bytes());
    hasher.update(b"\0content\0");
    hasher.update(stripped.as_bytes());
    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_sources_hash / compute_file_hash --------------------------

    use std::path::{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 sources_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 h_a = compute_sources_hash(&[s_a]).unwrap();
        let h_b = compute_sources_hash(&[s_b]).unwrap();
        assert_ne!(
            h_a, h_b,
            "same content at a different path can produce different IR (rust_path differs)"
        );
    }

    #[test]
    fn sources_hash_errors_on_missing_source() {
        let dir = tempdir().unwrap();
        let bogus = dir.path().join("does-not-exist.rs");
        assert!(compute_sources_hash(&[bogus]).is_err());
    }

    #[test]
    fn sources_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 sources = vec![s1, s2];
        let h1 = compute_sources_hash(&sources).unwrap();
        let h2 = compute_sources_hash(&sources).unwrap();
        assert_eq!(h1, h2);
    }

    #[test]
    fn sources_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 h_forward = compute_sources_hash(&[s1.clone(), s2.clone()]).unwrap();
        let h_reverse = compute_sources_hash(&[s2, s1]).unwrap();
        assert_eq!(h_forward, h_reverse);
    }

    #[test]
    fn sources_hash_changes_with_content() {
        let dir = tempdir().unwrap();
        let s = write_file(dir.path(), "a.rs", "fn a() {}");
        let h_before = compute_sources_hash(std::slice::from_ref(&s)).unwrap();
        std::fs::write(&s, "fn a() { let _ = 1; }").unwrap();
        let h_after = compute_sources_hash(&[s]).unwrap();
        assert_ne!(h_before, h_after);
    }

    #[test]
    fn file_hash_idempotent_under_strip_hash_line() {
        // The defining property: hash(content with hash line) == hash(content without hash line).
        // This is what makes the verify path symmetric with the generate path.
        let sources_hash = "abc123";
        let bare = "// auto-generated by alef\nfn body() {}\n";
        let with_line = "// auto-generated by alef\n// alef:hash:deadbeef\nfn body() {}\n";

        let h1 = compute_file_hash(sources_hash, bare);
        let h2 = compute_file_hash(sources_hash, with_line);
        assert_eq!(h1, h2, "hash must ignore an existing alef:hash: line");
    }

    #[test]
    fn file_hash_changes_when_sources_change() {
        let content = "// auto-generated by alef\nfn body() {}\n";
        let h_a = compute_file_hash("sources_a", content);
        let h_b = compute_file_hash("sources_b", content);
        assert_ne!(h_a, h_b);
    }

    #[test]
    fn file_hash_changes_when_content_changes() {
        let sources_hash = "abc123";
        let h_a = compute_file_hash(sources_hash, "fn a() {}\n");
        let h_b = compute_file_hash(sources_hash, "fn b() {}\n");
        assert_ne!(h_a, h_b);
    }

    #[test]
    fn file_hash_independent_of_alef_version() {
        // Idempotency property: the hash is purely a function of (sources, content).
        // Bumping the alef CLI version must not change it. Encoded by the type
        // signature — there is no version parameter — but make it explicit so
        // a future regression that re-introduces a version dimension is caught.
        let h = compute_file_hash("sources_hash", "fn a() {}\n");
        assert_eq!(h.len(), 64, "blake3 hex output is 64 chars");
    }

    #[test]
    fn file_hash_round_trip_via_inject_extract() {
        // Simulate the full generate/verify cycle:
        // 1. generate: compute hash from stripped content, inject into header
        // 2. verify: read back, extract hash, recompute from content, compare
        let sources_hash = "abc123";
        let raw = "// auto-generated by alef\nfn body() {}\n";
        let file_hash = compute_file_hash(sources_hash, raw);
        let on_disk = inject_hash_line(raw, &file_hash);

        let extracted = extract_hash(&on_disk).expect("hash line should be present");
        let recomputed = compute_file_hash(sources_hash, &on_disk);
        assert_eq!(extracted, file_hash);
        assert_eq!(recomputed, file_hash);
        assert_eq!(extracted, recomputed, "verify must reproduce the embedded hash");
    }
}