forge/manifest_ledger/

hooks.rs

// #t(file: rust_alloc_in_loop) source inventory intentionally owns stable report strings.
// #t(file: rust_clone_in_loop) source inventory expands bounded hook call graphs.

use std::collections::{BTreeMap, BTreeSet};

use anyhow::{Context, Result, bail};
use ra_ap_syntax::{
    AstNode, Edition, SourceFile, SyntaxKind, SyntaxNode,
    ast::{self, HasArgList, HasModuleItem, HasName, LiteralKind},
};
use wowlab_fs::{
    directory::{self, EntryKind},
    file,
    path::{Path, PathBuf},
};
use wowlab_manifest_schema::{ItemManifestEntry, Manifest};

use super::types::{LedgerDisposition, LedgerFinding, LedgerRow, LedgerSource, OperationCategory};

// #t(rust_duplicate_strings) Each ledger stage owns explicit placeholder evidence without coupling its private modules.
pub(super) const PLACEHOLDER_EVIDENCE: &str = "hook body requires operation-level source inventory";

#[derive(Clone, Debug)]
struct HookBinding {
    manifest_key: String,
    function: String,
}

#[derive(Clone, Debug)]
struct SourceOperation {
    category: OperationCategory,
    disposition: LedgerDisposition,
    evidence: String,
    aura_reference: Option<AuraReference>,
    controlled: bool,
    coupled: bool,
}

#[derive(Clone, Debug)]
struct SourceCall {
    name: String,
    controlled: bool,
}

#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
enum AuraReference {
    Id(u32),
    Name(String),
}

#[derive(Clone, Debug)]
struct FunctionInfo {
    file: PathBuf,
    name: String,
    operations: Vec<SourceOperation>,
    calls: Vec<SourceCall>,
    imperative_procs: usize,
}

#[derive(Default)]
struct OperationVisitor {
    operations: Vec<SourceOperation>,
    calls: Vec<SourceCall>,
    imperative_procs: usize,
}

impl OperationVisitor {
    fn collect(block: &ast::BlockExpr) -> Self {
        let mut visitor = Self::default();

        for node in block.syntax().descendants() {
            let controlled = is_controlled(&node, block);

            if let Some(call) = ast::MethodCallExpr::cast(node.clone()) {
                let Some(name) = call.name_ref().map(|name| name.text().to_string()) else {
                    continue;
                };

                if let Some(mut operation) = classify_call(&name) {
                    operation.aura_reference = call
                        .arg_list()
                        .and_then(|arguments| arguments.args().next())
                        .as_ref()
                        .and_then(aura_reference);
                    operation.controlled = controlled;
                    visitor.operations.push(operation);
                }

                continue;
            }

            if let Some(call) = ast::CallExpr::cast(node.clone()) {
                let Some(ast::Expr::PathExpr(path)) = call.expr() else {
                    continue;
                };
                let Some(name) = path.path().as_ref().and_then(last_segment) else {
                    continue;
                };

                if let Some(mut operation) = classify_call(&name) {
                    operation.aura_reference = call
                        .arg_list()
                        .and_then(|arguments| arguments.args().next())
                        .as_ref()
                        .and_then(aura_reference);
                    operation.controlled = controlled;
                    visitor.operations.push(operation);
                }

                visitor.calls.push(SourceCall { name, controlled });

                continue;
            }

            if ast::RecordExpr::cast(node)
                .and_then(|record| record.path())
                .as_ref()
                .and_then(last_segment)
                .is_some_and(|name| is_imperative_proc_type(&name))
            {
                visitor.imperative_procs += 1;
            }
        }

        visitor
    }
}

fn is_controlled(node: &SyntaxNode, block: &ast::BlockExpr) -> bool {
    node.ancestors()
        .skip(1)
        .take_while(|ancestor| ancestor != block.syntax())
        .any(|ancestor| {
            ast::ForExpr::can_cast(ancestor.kind())
                || ast::IfExpr::can_cast(ancestor.kind())
                || ast::LoopExpr::can_cast(ancestor.kind())
                || ast::MatchExpr::can_cast(ancestor.kind())
                || ast::WhileExpr::can_cast(ancestor.kind())
        })
}

pub(super) fn replace_hook_placeholders(
    rows: &mut Vec<LedgerRow>,
    slug: &str,
    hooks_dir: &Path,
    manifest: &Manifest,
) -> Result<()> {
    let spec_dir = hooks_dir.join(slug);
    let mut index = SourceIndex::load(&spec_dir)?;

    index.merge(SourceIndex::load(&hooks_dir.join("shared"))?);
    let aura_ids = manifest
        .auras
        .iter()
        .map(|(name, aura)| (name.clone(), aura.id))
        .collect();

    replace_bindings(rows, slug, &index, &spec_bindings(manifest), &aura_ids)
}

pub(super) fn replace_item_hook_placeholders(
    rows: &mut Vec<LedgerRow>,
    item_name: &str,
    hooks_dir: &Path,
    item: &ItemManifestEntry,
) -> Result<()> {
    let owner = format!("item:{item_name}");
    let module = item_name.to_ascii_lowercase();
    let file = hooks_dir.join("items").join(format!("{module}.rs"));
    let index = if directory::inspect(&file)?.is_some() {
        SourceIndex::load_file(&file)?
    } else {
        SourceIndex::default()
    };
    let aura_ids = item
        .auras
        .iter()
        .map(|(aura_name, aura)| (aura_name.clone(), aura.id))
        .collect();

    replace_bindings(
        rows,
        &owner,
        &index,
        &item_bindings(item_name, item),
        &aura_ids,
    )
}

pub(super) fn collect_imperative_proc_registrations(
    rows: &mut Vec<LedgerRow>,
    hooks_dir: &Path,
) -> Result<()> {
    let index = SourceIndex::load(hooks_dir)?;

    for function in index.functions.values().flatten() {
        for occurrence in 0..function.imperative_procs {
            let owner = owner_from_hook_path(hooks_dir, &function.file);

            rows.push(
                LedgerRow::new(
                    LedgerSource::new(
                        owner,
                        "(imperative hook registration)",
                        format!("impact_proc[{occurrence}]"),
                    ),
                    LedgerFinding::new(
                        OperationCategory::Proc,
                        LedgerDisposition::GenericGap,
                        "imperative impact proc registration; cross-check against DBC AU42/proc data",
                    ),
                )
                .hook(
                    &relative_path(hooks_dir, &function.file),
                    function.name.clone(),
                ),
            );
        }
    }

    Ok(())
}

#[cfg(test)]
pub(super) fn imperative_proc_count(hooks_dir: &Path) -> Result<usize> {
    let index = SourceIndex::load(hooks_dir)?;

    Ok(index
        .functions
        .values()
        .flatten()
        .map(|function| function.imperative_procs)
        .sum())
}

fn replace_bindings(
    rows: &mut Vec<LedgerRow>,
    owner: &str,
    index: &SourceIndex,
    bindings: &[HookBinding],
    aura_ids: &BTreeMap<String, u32>,
) -> Result<()> {
    for binding in bindings {
        let Some(position) = rows.iter().position(|row| {
            row.spec_or_item == owner
                && row.manifest_key == binding.manifest_key
                && row.evidence == PLACEHOLDER_EVIDENCE
        }) else {
            bail!(
                "{owner} hook binding {} has no ledger placeholder",
                binding.manifest_key
            );
        };
        let placeholder = rows.remove(position);
        let Some(function) = index.unique(&binding.function)? else {
            bail!(
                "{owner} hook function {} for {} was not found below the owning hook module",
                binding.function,
                binding.manifest_key
            );
        };
        let operations = index.expanded_operations(function);

        if operations.is_empty() {
            let mut resolved = placeholder;

            resolved.hook_file = Some(function.file.display().to_string());
            resolved.hook_function = Some(function.name.clone());
            resolved.evidence = "hook contains no recognized state mutation; inspect returned formula/control policy".to_string();
            rows.insert(position, resolved);
            continue;
        }

        for (operation_index, operation) in operations.into_iter().enumerate().rev() {
            let mut row = placeholder
                .clone()
                .hook(&function.file, function.name.clone());

            row.hook_operation = Some(operation_index + 1);
            row.category = operation.category;
            row.disposition = operation.disposition;
            row.evidence = operation.evidence;
            let coupled = operation.coupled;

            if let Some(aura_id) = operation
                .aura_reference
                .as_ref()
                .and_then(|reference| resolve_aura_reference(reference, aura_ids))
            {
                row.child_spell_ids.push(aura_id);

                if coupled {
                    row.evidence = format!("coupled {}", row.evidence);
                }
            }

            rows.insert(position, row);
        }
    }

    Ok(())
}

#[derive(Default)]
struct SourceIndex {
    functions: BTreeMap<String, Vec<FunctionInfo>>,
}

impl SourceIndex {
    fn load(root: &Path) -> Result<Self> {
        if directory::inspect(root)?.is_none() {
            return Ok(Self::default());
        }

        let mut paths = Vec::new();

        collect_rust_paths(root, &mut paths)?;
        paths.sort();
        let mut index = Self::default();

        for path in paths {
            index.parse_file(&path)?;
        }

        Ok(index)
    }

    fn load_file(path: &Path) -> Result<Self> {
        let mut index = Self::default();

        index.parse_file(path)?;

        Ok(index)
    }

    fn parse_file(&mut self, path: &Path) -> Result<()> {
        let source = file::read_text(path)
            .with_context(|| format!("failed to read hook source {}", path.display()))?;
        let syntax = parse_hook_source(path, &source)?;
        let mut parsed_proc_count = 0;

        for item in syntax.items() {
            match item {
                ast::Item::Fn(function) => {
                    let (Some(name), Some(block)) = (function.name(), function.body()) else {
                        continue;
                    };

                    parsed_proc_count +=
                        self.insert_function(path, name.text().to_string(), &block);
                }
                ast::Item::Impl(implementation) => {
                    if let Some(items) = implementation.assoc_item_list() {
                        for item in items.assoc_items() {
                            if let ast::AssocItem::Fn(function) = item {
                                let (Some(name), Some(block)) = (function.name(), function.body())
                                else {
                                    continue;
                                };

                                parsed_proc_count +=
                                    self.insert_function(path, name.text().to_string(), &block);
                            }
                        }
                    }
                }
                _ => {}
            }
        }

        let token_proc_count = count_proc_structs(syntax.syntax());

        if token_proc_count > parsed_proc_count {
            let missing = token_proc_count - parsed_proc_count;

            self.functions
                .entry("<macro registration>".to_string())
                .or_default()
                .push(FunctionInfo {
                    file: path.to_path_buf(),
                    name: "<macro registration>".to_string(),
                    operations: Vec::new(),
                    calls: Vec::new(),
                    imperative_procs: missing,
                });
        }

        Ok(())
    }

    fn insert_function(&mut self, path: &Path, name: String, block: &ast::BlockExpr) -> usize {
        let mut visitor = OperationVisitor::collect(block);
        let duration_mutations: BTreeSet<_> = visitor
            .operations
            .iter()
            .filter(|operation| operation.evidence == "hook operation `extend_aura`")
            .filter_map(|operation| operation.aura_reference.clone())
            .collect();

        for operation in &mut visitor.operations {
            let aura_application = operation.evidence == "hook operation `apply_aura`";
            let coupled_duration = aura_application
                && operation
                    .aura_reference
                    .as_ref()
                    .is_some_and(|reference| duration_mutations.contains(reference));

            if is_aura_identity_operation(operation) && (operation.controlled || coupled_duration) {
                operation.coupled = true;
            }
        }

        let function = FunctionInfo {
            file: path.to_path_buf(),
            name: name.clone(),
            operations: visitor.operations,
            calls: visitor.calls,
            imperative_procs: visitor.imperative_procs,
        };
        let imperative_procs = function.imperative_procs;

        self.functions.entry(name).or_default().push(function);

        imperative_procs
    }

    fn merge(&mut self, other: Self) {
        for (name, functions) in other.functions {
            self.functions.entry(name).or_default().extend(functions);
        }
    }

    fn unique(&self, name: &str) -> Result<Option<&FunctionInfo>> {
        let Some(functions) = self.functions.get(name) else {
            return Ok(None);
        };

        if functions.len() != 1 {
            bail!("hook function {name} is ambiguous across the owning module");
        }

        Ok(functions.first())
    }

    fn expanded_operations(&self, root: &FunctionInfo) -> Vec<SourceOperation> {
        let mut pending = vec![(root, false)];
        let mut reachable = BTreeMap::new();

        while let Some((function, inherited_control)) = pending.pop() {
            let identity = (function.file.clone(), function.name.clone());

            match reachable.get_mut(&identity) {
                Some(controlled) if *controlled && !inherited_control => *controlled = false,
                Some(_) => continue,
                None => {
                    reachable.insert(identity, inherited_control);
                }
            }

            for call in &function.calls {
                let Some(candidates) = self.functions.get(&call.name) else {
                    continue;
                };

                if let Some(local) = candidates
                    .iter()
                    .find(|candidate| candidate.file == function.file)
                    .or_else(|| (candidates.len() == 1).then(|| &candidates[0]))
                {
                    pending.push((local, inherited_control || call.controlled));
                }
            }
        }

        let mut operations = Vec::new();

        for ((file, name), inherited_control) in reachable {
            let Some(function) = self
                .functions
                .get(&name)
                .and_then(|candidates| candidates.iter().find(|candidate| candidate.file == file))
            else {
                continue;
            };

            operations.extend(function.operations.iter().cloned().map(|mut operation| {
                if inherited_control && is_aura_identity_operation(&operation) {
                    operation.coupled = true;
                }

                operation
            }));
        }

        operations
    }
}

fn parse_hook_source(path: &Path, source: &str) -> Result<SourceFile> {
    let parse = SourceFile::parse(source, Edition::Edition2024);
    let parse_errors = parse.errors();

    if !parse_errors.is_empty() {
        let details = parse_errors
            .iter()
            .map(ToString::to_string)
            .collect::<Vec<_>>()
            .join("; ");

        bail!("failed to parse hook source {}: {details}", path.display());
    }

    Ok(parse.tree())
}

fn is_aura_identity_operation(operation: &SourceOperation) -> bool {
    matches!(
        operation.evidence.as_str(),
        "hook operation `apply_aura`" | "hook operation `expire_aura`"
    )
}

fn collect_rust_paths(root: &Path, paths: &mut Vec<PathBuf>) -> Result<()> {
    let mut directories = vec![root.to_path_buf()];

    while let Some(current_dir) = directories.pop() {
        for entry in directory::entries(&current_dir)
            .with_context(|| format!("failed to walk hook directory {}", current_dir.display()))?
        {
            match entry.kind() {
                EntryKind::Directory => directories.push(entry.path().to_path_buf()),
                EntryKind::File
                    if entry
                        .path()
                        .extension()
                        .is_some_and(|extension| extension == "rs") =>
                {
                    paths.push(entry.path().to_path_buf());
                }
                _ => {}
            }
        }
    }

    Ok(())
}

// #t(fn: rust_cyclomatic_complexity) this is the exhaustive manifest-hook binding inventory.
fn spec_bindings(manifest: &Manifest) -> Vec<HookBinding> {
    let mut bindings = vec![HookBinding {
        manifest_key: "mastery.hook".to_string(),
        function: path_function(&manifest.mastery.hook),
    }];

    if let Some(handler) = &manifest.spec.custom_handler {
        bindings.push(HookBinding {
            manifest_key: "spec.custom_handler".to_string(),
            function: path_function(handler),
        });
    }

    if let Some(hook) = &manifest.mastery.crit_damage_hook {
        bindings.push(HookBinding {
            manifest_key: "mastery.crit_damage_hook".to_string(),
            function: path_function(hook),
        });
    }

    for (name, aura) in &manifest.auras {
        if let Some(hook) = &aura.expire_hook {
            bindings.push(HookBinding {
                manifest_key: format!("auras.{name}.expire_hook"),
                function: suffixed(hook, "_hook"),
            });
        }

        if let Some(hook) = &aura.tick_hook {
            bindings.push(HookBinding {
                manifest_key: format!("auras.{name}.tick_hook"),
                function: suffixed(hook, "_hook"),
            });
        }
    }

    for (name, spell) in &manifest.spells {
        if let Some(hook) = &spell.hook {
            bindings.push(HookBinding {
                manifest_key: format!("spells.{name}.hook"),
                function: suffixed(hook, "_hook"),
            });
        }

        if let Some(hook) = spell
            .channel
            .as_ref()
            .and_then(|channel| channel.tick_hook.as_ref())
        {
            bindings.push(HookBinding {
                manifest_key: format!("spells.{name}.channel.tick_hook"),
                function: suffixed(hook, "_tick_hook"),
            });
        }
    }

    for (name, attack) in &manifest.auto_attacks {
        if let Some(hook) = &attack.hook {
            bindings.push(HookBinding {
                manifest_key: format!("auto_attacks.{name}.hook"),
                function: path_function(hook),
            });
        }
    }

    bindings
}

fn item_bindings(name: &str, item: &ItemManifestEntry) -> Vec<HookBinding> {
    let mut bindings =
        Vec::with_capacity(item.spells.len() + usize::from(item.player_cast_hook.is_some()));

    for (spell_name, spell) in &item.spells {
        if let Some(hook) = &spell.hook {
            bindings.push(HookBinding {
                manifest_key: format!("spells.{spell_name}.hook"),
                function: path_function(hook),
            });
        }
    }

    if let Some(hook) = &item.player_cast_hook {
        bindings.push(HookBinding {
            manifest_key: format!("items.{name}.player_cast_hook"),
            function: path_function(hook),
        });
    }

    bindings
}

fn suffixed(path: &str, suffix: &str) -> String {
    let function = path_function(path);

    if function.ends_with(suffix) {
        function
    } else {
        format!("{function}{suffix}")
    }
}

fn path_function(path: &str) -> String {
    path.rsplit("::").next().unwrap_or(path).to_string()
}

fn last_segment(path: &ast::Path) -> Option<String> {
    path.segment()?
        .name_ref()
        .map(|name| name.text().to_string())
}

fn is_imperative_proc_type(name: &str) -> bool {
    matches!(
        name,
        "ImpactProc" | "AccumulatingImpactProc" | "ImpactEffectProc"
    )
}

fn count_proc_structs(root: &SyntaxNode) -> usize {
    let mut count = 0;
    let mut pending_proc_ident = false;

    for token in root
        .descendants_with_tokens()
        .filter_map(ra_ap_syntax::NodeOrToken::into_token)
        .filter(|token| !token.kind().is_trivia())
    {
        if token.kind() == SyntaxKind::IDENT {
            pending_proc_ident = is_imperative_proc_type(token.text());
        } else if token.text() == "{" {
            if pending_proc_ident {
                count += 1;
            }

            pending_proc_ident = false;
        } else if token.text() != ":" {
            pending_proc_ident = false;
        }
    }

    count
}

// #t(fn: rust_cyclomatic_complexity) one ordered classifier keeps mutation names mutually exclusive.
fn classify_call(name: &str) -> Option<SourceOperation> {
    let (category, disposition) = if name.starts_with("deal_")
        || name == "add_residual_damage"
        || name == "schedule_ground_effect"
    {
        (OperationCategory::Damage, LedgerDisposition::GenericGap)
    } else if name.starts_with("apply_aura") || name == "extend_aura" {
        (OperationCategory::AuraApply, LedgerDisposition::GenericGap)
    } else if name.starts_with("expire_aura")
        || name.starts_with("consume_aura")
        || name == "reduce_aura"
    {
        (OperationCategory::AuraRemove, LedgerDisposition::GenericGap)
    } else if name.contains("resource") && (name.starts_with("gain") || name.starts_with("spend")) {
        (OperationCategory::Resource, LedgerDisposition::GenericGap)
    } else if name.contains("cooldown") || name.contains("recharge") {
        (OperationCategory::Cooldown, LedgerDisposition::GenericGap)
    } else if name.contains("resolved_spell_effect_targets") || name.starts_with("target_") {
        (OperationCategory::Targeting, LedgerDisposition::GenericGap)
    } else if name.contains("guardian") || name.contains("pet_") || name == "summon_pet" {
        (OperationCategory::ActorOrPet, LedgerDisposition::Unresolved)
    } else if name.contains("replacement") || name.contains("override_spell") {
        (
            OperationCategory::Replacement,
            LedgerDisposition::GenericGap,
        )
    } else if name.starts_with("schedule_") || name.contains("spec_runtime_mut") {
        (
            OperationCategory::OrderedContent,
            LedgerDisposition::ContentOrdering,
        )
    } else {
        return None;
    };

    Some(SourceOperation {
        category,
        disposition,
        evidence: format!("hook operation `{name}`"),
        aura_reference: None,
        controlled: false,
        coupled: false,
    })
}

fn aura_reference(expression: &ast::Expr) -> Option<AuraReference> {
    let mut expression = expression.clone();

    loop {
        match expression {
            ast::Expr::FieldExpr(field) => expression = field.expr()?,
            ast::Expr::Literal(literal) => {
                return match literal.kind() {
                    LiteralKind::IntNumber(value) => u32::try_from(value.value().ok()?)
                        .ok()
                        .map(AuraReference::Id),
                    _ => None,
                };
            }
            ast::Expr::ParenExpr(paren) => expression = paren.expr()?,
            ast::Expr::PathExpr(path) => {
                return path
                    .path()
                    .as_ref()
                    .and_then(last_segment)
                    .and_then(|name| {
                        let normalized = name.strip_prefix("AURA_").unwrap_or(&name);

                        (normalized != "AURA").then(|| AuraReference::Name(normalized.to_string()))
                    });
            }
            ast::Expr::RefExpr(reference) => expression = reference.expr()?,
            _ => return None,
        }
    }
}

fn resolve_aura_reference(
    reference: &AuraReference,
    aura_ids: &BTreeMap<String, u32>,
) -> Option<u32> {
    match reference {
        AuraReference::Id(id) => Some(*id),
        AuraReference::Name(name) => aura_ids.get(name).copied(),
    }
}

fn owner_from_hook_path(root: &Path, file: &Path) -> String {
    let relative = file.strip_prefix(root).unwrap_or(file);
    let mut components = relative.components();
    let first = components.next().map_or_else(
        || "unknown".to_string(),
        |component| component.as_os_str().to_string_lossy().into_owned(),
    );

    if first == "items" {
        let item = components
            .next()
            .and_then(|component| {
                Path::new(component.as_os_str())
                    .file_stem()
                    .map(|stem| stem.to_string_lossy().to_ascii_uppercase())
            })
            .unwrap_or_else(|| "UNKNOWN".to_string());

        format!("item:{item}")
    } else {
        first
    }
}

fn relative_path(root: &Path, file: &Path) -> PathBuf {
    file.strip_prefix(root)
        .map_or_else(|_| file.to_path_buf(), Path::to_path_buf)
}

#[cfg(test)]
mod tests;