% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils_helpers.R
\name{.hm_build_col_map}
\alias{.hm_build_col_map}
\title{Build a complete col_map with dictionary inference and alias materialization}
\usage{
.hm_build_col_map(data, col_map, keys, fn = "")
}
\arguments{
\item{data}{The data.frame being analysed (modified locally; original
is not altered outside the function call).}

\item{col_map}{Named list of user-supplied key -> column-name mappings, or
\code{NULL} for full auto-inference.}

\item{keys}{Character vector of short internal keys to resolve.}

\item{fn}{Calling function name string (for messages).}
}
\value{
A list with four elements:
\describe{
\item{data}{The (possibly augmented) data.frame.}
\item{col_map}{Complete named list of key -> resolved column name.}
\item{user_keys}{Keys that were explicitly provided in the original
\code{col_map} argument.}
\item{inferred_keys}{Keys resolved by dictionary inference or literal
fallback (i.e., not in \code{user_keys}).}
}
}
\description{
Combines three previously separate steps into one call:
\enumerate{
\item User-supplied entries in \code{col_map} are treated as authoritative
Layer 0 seeds -- they are never overwritten.
\item \code{hm_col_report()} fills any remaining unmatched keys via the
full synonym dictionary (exact -> case-insensitive -> contains layers).
\item Literal-name fallback: if a key in \code{keys} still has no match,
but the key name exists verbatim as a column in \code{data}, it is
used directly.
\item Materialization: for every mapped key \code{k} where
\code{col_map[[k]] != k} and \code{k} is \emph{not} already a column
in \code{data}, a copy \code{data[[k]] <- data[[col_map[[k]]]]} is
added. This ensures that downstream pre-computation helpers (which
check \code{names(data)} for dependency names) and their
\code{compute()} closures (which use literal key names) both resolve
correctly even when the physical column has a non-standard name.
}
}
\keyword{internal}
