R/s3-metadata.R

Defines functions s3_function_identity s3_namespace_binding s3_metadata_context s3_prepare_packages s3_prepare_namespace s3_runtime_shape s3_function_record s3_generic_descriptor

# Inert namespace catalogs are prepared in the resolution worker. Request paths
# only read signatures, class summaries and registered method identities.
S3MetadataCache <- R6::R6Class("S3MetadataCache",
    private = list(snapshots = NULL, decoded = NULL, semantic_revision = 0L, cache_identity = NULL, generic_names = NULL),
    public = list(
        initialize = function(max_bytes = 16 * 1024^2, max_entries = 64L) {
            private$snapshots <- ByteLruCache$new(max_bytes, max_entries)
            private$decoded <- ByteLruCache$new(min(max_bytes, 8 * 1024^2), 8L)
            private$cache_identity <- new.env(parent = emptyenv())
            private$generic_names <- new.env(hash = TRUE, parent = emptyenv())
        },
        get = function(key, default = NULL) {
            if (private$decoded$has(key)) {
                return(private$decoded$get(key))
            }
            entry <- private$snapshots$get(key)
            if (is.null(entry)) {
                return(default)
            }
            value <- unserialize(memDecompress(entry$compressed, "gzip"))
            private$decoded$set(key, value)
            value
        },
        catalog = function(key) {
            entry <- private$snapshots$get(key)
            if (!is.null(entry)) entry$catalog
        },
        keys = function() private$snapshots$keys(),
        has = function(key) private$snapshots$has(key),
        may_dispatch = function(name) exists(name, private$generic_names, inherits = FALSE),
        revision = function() private$semantic_revision,
        identity = function() private$cache_identity,
        bytes = function() private$snapshots$bytes() + private$decoded$bytes(),
        set = function(key, value, protect = character()) {
            if (!is.list(value) || !identical(value$schema, 1L)) {
                return(invisible(NULL))
            }
            previous <- self$catalog(key)
            if (identical(previous$generation, value$generation)) {
                return(invisible(NULL))
            }
            catalog <- value[c("package", "generation", "dependencies", "callables", "error")]
            catalog$functions <- lapply(value$functions, function(fn) fn[c("name", "owner", "generic", "summary")])
            catalog$method_keys <- names(value$methods)
            catalog$object_keys <- names(value$objects)
            catalog$generic_names <- names(value$functions)[vapply(value$functions,
                    function(fn) !is.null(fn$generic), logical(1L))]
            catalog$.lazy <- TRUE
            private$snapshots$set(key, list(
                catalog = catalog,
                compressed = memCompress(serialize(value, NULL), "gzip")
            ), protect)
            private$decoded$remove(key)
            generics <- unique(unlist(lapply(private$snapshots$keys(), function(package) {
                private$snapshots$get(package)$catalog$generic_names
            }), use.names = FALSE))
            private$generic_names <- list2env(stats::setNames(rep(list(TRUE), length(generics)), generics),
                parent = emptyenv())
            private$semantic_revision <- private$semantic_revision + 1L
            invisible(value)
        },
        clear = function() {
            private$snapshots$clear()
            private$decoded$clear()
            private$generic_names <- new.env(hash = TRUE, parent = emptyenv())
            private$semantic_revision <- private$semantic_revision + 1L
        }
    )
)

s3_generic_descriptor <- function(fn) {
    if (!member_head(fn, "function")) {
        return(NULL)
    }
    body <- fn[[3L]]
    if (member_head(body, "{") && length(body) == 2L) body <- body[[2L]]
    if (member_head(body, "return") && length(body) == 2L) body <- body[[2L]]
    if (!member_head(body, "UseMethod") || length(body) < 2L ||
            !is.character(body[[2L]]) || length(body[[2L]]) != 1L) {
        return(NULL)
    }
    if (!length(fn[[2L]])) {
        return(NULL)
    }
    formal <- if (length(body) == 2L) names(fn[[2L]])[[1L]] else member_name(body[[3L]])
    if (!is.symbol(if (length(body) > 2L) body[[3L]] else as.name(formal)) ||
            is.null(formal) || !formal %in% names(fn[[2L]])) {
        return(NULL)
    }
    list(name = body[[2L]], formal = formal)
}

s3_summary_names <- list(
    base = c(
        "structure", "list", "data.frame", "c", ":", "identity", "invisible",
        "factor", "ordered", "as.Date", "as.POSIXct", "as.POSIXlt", "as.difftime",
        "matrix", "array", "table", "as.table", "as.data.frame", "as.numeric", "as.double",
        "as.integer", "as.character", "as.logical", "as.raw", "seq_len", "seq_along", "rep", "unclass"
    ),
    stats = c(
        "ts", "lm", "glm", "aov", "loess", "smooth.spline", "nls", "prcomp",
        "princomp", "hclust", "kmeans", "t.test", "wilcox.test", "cor.test", "chisq.test"
    ),
    utils = "read.csv", tibble = c("tibble", "as_tibble"),
    data.table = c("data.table", "as.data.table", "setDT", "setDF"),
    dplyr = c("group_by", "rowwise", "mutate", "select", "filter", "arrange", "summarise", "bind_rows", "left_join"),
    MASS = c("rlm", "glm.nb", "polr"), survival = c("coxph", "survfit"),
    rpart = "rpart", nlme = "lme"
)

s3_function_record <- function(
    fn,
    name,
    package,
    require_dispatch_or_summary = FALSE,
    summary_cache = NULL) {
    if (!is.function(fn) || is.object(fn)) {
        return(NULL)
    }
    owner <- if (is.primitive(fn)) {
        "base"
    } else if (isNamespace(environment(fn))) {
        unname(getNamespaceName(environment(fn)))
    } else {
        package
    }
    syntax <- if (typeof(fn) == "closure") member_function_syntax(fn) else NULL
    arguments <- if (is.null(syntax)) args(fn) else NULL
    formals <- if (!is.null(syntax)) syntax[[2L]] else if (is.function(arguments)) formals(arguments) else NULL
    foreign_environment <- typeof(fn) == "closure" && !isNamespace(environment(fn)) &&
        !identical(environment(fn), baseenv())
    generic <- if (!foreign_environment) s3_generic_descriptor(syntax)
    summary <- NULL
    candidates <- s3_summary_names[[owner]]
    if (length(candidates)) {
        if (is.environment(summary_cache)) {
            owner_summaries <- summary_cache[[owner]]
            if (is.null(owner_summaries)) {
                owner_ns <- asNamespace(owner)
                owner_summaries <- stats::setNames(lapply(candidates, function(candidate) {
                    member_binding(owner_ns, candidate, materialize = TRUE)
                }), candidates)
                summary_cache[[owner]] <- owner_summaries
            }
            for (candidate in candidates) {
                original <- owner_summaries[[candidate]]
                if (identical(original[[1L]], "value") && identical(original[[2L]], fn)) {
                    summary <- paste(owner, candidate, sep = "::")
                    break
                }
            }
        } else {
            for (candidate in candidates) {
                original <- member_binding(asNamespace(owner), candidate, materialize = TRUE)
                if (identical(original[[1L]], "value") && identical(original[[2L]], fn)) {
                    summary <- paste(owner, candidate, sep = "::")
                    break
                }
            }
        }
    }
    if (isTRUE(require_dispatch_or_summary) && is.null(generic) && is.null(summary)) {
        return(NULL)
    }
    list(
        name = name, package = package, owner = owner, formals = formals,
        body_hash = if (!is.null(syntax)) s3_function_identity(syntax, owner),
        generic = generic, summary = summary,
        identity = digest::digest(list(owner, formals, if (!is.null(generic) || !is.null(summary)) syntax),
            algo = "xxhash64"
        )
    )
}

s3_runtime_shape <- function(object, depth = 0L) {
    if (depth > 2L || isS4(object) || is.environment(object) || is.function(object)) {
        return(NULL)
    }
    dims <- attr(object, "dim", exact = TRUE)
    plain <- unclass(object)
    fields <- if (is.data.frame(object) && length(plain) <= 256L) {
        lapply(plain, s3_runtime_shape, depth = depth + 1L)
    }
    s3_value(classes = .class2(object), type = typeof(object), fields = fields, dimensions = dims,
        explicit_class = !is.null(attr(object, "class", exact = TRUE)))
}

s3_prepare_namespace <- function(package, identity = NULL) {
    ns <- asNamespace(package)
    exports <- getNamespaceExports(ns)
    if (length(exports) > 10000L) stop("Namespace exceeds S3 metadata budget")
    functions <- objects <- methods <- list()
    callables <- character()
    summary_cache <- new.env(hash = TRUE, parent = emptyenv())
    for (name in exports) {
        binding <- s3_namespace_binding(ns, name)
        if (!identical(binding[[1L]], "value")) next
        if (is.function(binding[[2L]])) {
            callables <- c(callables, name)
            record <- s3_function_record(
                binding[[2L]], name, package,
                require_dispatch_or_summary = TRUE,
                summary_cache = summary_cache
            )
            if (!is.null(record)) functions[[name]] <- record
        }
    }
    # Namespace re-exports and registrations can contain actual closures rather
    # than names. Read cells with [[, and preserve the implementation's owner.
    registered_export_names <- character()
    registrations <- tryCatch(getNamespaceInfo(ns, "S3methods"), error = function(e) NULL)
    if (is.matrix(registrations)) {
        for (i in seq_len(nrow(registrations))) {
            generic <- registrations[[i, 1L]]
            class <- registrations[[i, 2L]]
            method <- registrations[[i, 3L]]
            if (!is.character(generic) || !is.character(class)) next
            key <- paste(generic, class, sep = ".")
            generic_fn <- tryCatch(get(generic, ns), error = function(e) NULL)
            owner <- if (is.function(generic_fn) && isNamespace(environment(generic_fn))) {
                unname(getNamespaceName(environment(generic_fn)))
            } else if (is.primitive(generic_fn)) {
                "base"
            } else {
                NULL
            }
            table <- if (!is.null(owner)) get0(".__S3MethodsTable__.", asNamespace(owner), inherits = FALSE)
            fn <- if (is.environment(table)) get0(key, table, inherits = FALSE)
            if (!is.function(fn)) {
                fn <- if (is.function(method)) {
                    method
                } else if (is.character(method)) {
                    binding <- member_binding(ns, method, materialize = TRUE)
                    if (identical(binding[[1L]], "value")) binding[[2L]]
                }
            }
            record <- s3_function_record(
                fn, if (is.character(method)) method else key, package,
                summary_cache = summary_cache
            )
            if (!is.null(record)) {
                if (record$name %in% exports) {
                    functions[[record$name]] <- record
                    registered_export_names <- c(registered_export_names, record$name)
                }
                record$generic <- generic
                record$generic_package <- owner
                record$class <- class
                methods[[paste(owner, key, sep = "::")]] <- record
            }
        }
    }
    # Base has no namespace S3method declarations. Its live registry also
    # contains methods installed by package load hooks, including replacements
    # for conventional base bindings. Retain these under the owning generic.
    table <- get0(".__S3MethodsTable__.", ns, inherits = FALSE)
    generics <- Filter(function(record) !is.null(record$generic) && identical(record$owner, package), functions)
    if (is.environment(table)) {
        registered_names <- package_metadata_sort(ls(table, all.names = TRUE, sorted = FALSE))
        for (generic_record in generics) {
            generic <- generic_record$generic$name
            prefix <- paste0(generic, ".")
            for (key in registered_names[startsWith(registered_names, prefix)]) {
                id <- paste(package, key, sep = "::")
                if (!is.null(methods[[id]])) next
                binding <- member_binding(table, key, materialize = TRUE)
                if (!identical(binding[[1L]], "value")) next
                fn <- binding[[2L]]
                method_package <- if (is.function(fn) && isNamespace(environment(fn))) {
                    unname(getNamespaceName(environment(fn)))
                } else {
                    package
                }
                record <- s3_function_record(fn, key, method_package, summary_cache = summary_cache)
                if (is.null(record)) next
                record$generic <- generic
                record$generic_package <- package
                record$class <- substring(key, nchar(prefix) + 1L)
                methods[[id]] <- record
            }
        }
    }
    # Only functions visible from the ordinary calling environment may be
    # considered unregistered methods. Private generic.class bindings do not
    # become applicable just because their namespace is loaded.
    visible <- if (package == "base") {
        package_metadata_sort(ls(ns, all.names = TRUE, sorted = FALSE))
    } else {
        exports
    }
    for (name in visible) {
        if (!grepl(".", name, fixed = TRUE)) next
        if (!is.null(functions[[name]]) && !(name %in% registered_export_names)) next
        binding <- s3_namespace_binding(ns, name)
        if (!identical(binding[[1L]], "value") || !is.function(binding[[2L]])) next
        record <- s3_function_record(binding[[2L]], name, package, summary_cache = summary_cache)
        if (!is.null(record)) functions[[name]] <- record
    }
    lazy <- tryCatch(names(getNamespaceInfo(ns, "lazydata")), error = function(e) character())
    object_names <- unique(c(if (package == "datasets") exports else character(), lazy))
    for (name in object_names) {
        binding <- s3_namespace_binding(ns, name)
        if (!identical(binding[[1L]], "value") && name %in% lazy) {
            data_env <- getNamespaceInfo(ns, "lazydata")
            binding <- member_binding(data_env, name, materialize = TRUE)
        }
        if (identical(binding[[1L]], "value")) {
            shape <- s3_runtime_shape(binding[[2L]])
            if (!is.null(shape)) objects[[name]] <- shape
        }
    }
    dependencies <- if (package == "base") character() else names(getNamespaceImports(ns))
    result <- list(
        schema = 1L, package = package, functions = functions, callables = callables, objects = objects,
        methods = methods, dependencies = dependencies,
        identity = if (is.null(identity)) package_metadata_identity(package) else identity
    )
    size <- as.numeric(utils::object.size(result))
    if (size > 8 * 1024^2) stop(sprintf("Namespace %s exceeds S3 metadata budget (%d bytes)", package, size))
    result$generation <- digest::digest(result, algo = "xxhash64")
    result
}

s3_prepare_packages <- function(
    packages,
    cache_dir = package_metadata_cache_root(),
    lib_paths = .libPaths()) {
    .libPaths(lib_paths)
    lib_paths <- package_metadata_startup_lib_paths(lib_paths)
    previous <- options(languageserver.package_cache_dir = cache_dir)
    on.exit(options(previous), add = TRUE)
    namespaces <- list()
    pending <- unique(c(startup_packages, packages))
    # Load the requested namespaces before snapshotting any owning registry.
    # A dependency's load hook may replace a method on a startup generic.
    while (length(pending) && length(namespaces) < 64L) {
        package <- pending[[1L]]
        pending <- pending[-1L]
        if (package %in% names(namespaces)) next
        namespaces[[package]] <- tryCatch({
            ns <- asNamespace(package)
            list(dependencies = if (package == "base") character() else names(getNamespaceImports(ns)))
        }, error = function(e) list(dependencies = character(), error = conditionMessage(e)))
        pending <- unique(c(pending, setdiff(namespaces[[package]]$dependencies, names(namespaces))))
    }
    result <- list()
    context <- package_metadata_context(names(namespaces), lib_paths = lib_paths)
    for (package in names(namespaces)) {
        result[[package]] <- tryCatch({
            identity <- package_metadata_identity(package, lib_paths = lib_paths, context = context)
            path <- package_metadata_cache_path("s3", identity)
            cached <- package_metadata_cache_read(path, identity, function(value) {
                identical(value$schema, 1L) && identical(value$identity, identity)
            })
            if (!is.null(cached)) {
                cached
            } else {
                value <- s3_prepare_namespace(package, identity = identity)
                package_metadata_cache_write(path, identity, value)
                value
            }
        }, error = function(e) {
            list(
                schema = 1L, package = package, functions = list(), objects = list(), methods = list(),
                dependencies = character(), generation = "", error = conditionMessage(e)
            )
        })
    }
    result
}

# Registries and exported functions may be replaced by load hooks or tracing
# without changing package files. Include their current inert syntax in S3 keys.
s3_metadata_context <- function(packages) {
    records <- lapply(packages, function(package) {
        tryCatch({
            ns <- asNamespace(package)
            describe <- function(scope, names, exported = FALSE) {
                stats::setNames(lapply(names, function(name) {
                    record <- if (exported) {
                        s3_namespace_binding(scope, name)
                    } else {
                        member_binding(scope, name, materialize = TRUE)
                    }
                    value <- record[[2L]]
                    owner <- if (typeof(value) == "closure" && isNamespace(environment(value))) {
                        unname(getNamespaceName(environment(value)))
                    }
                    list(kind = record[[1L]], owner = owner,
                        foreign_environment = typeof(value) == "closure" && !isNamespace(environment(value)) &&
                            !identical(environment(value), baseenv()),
                        syntax = if (typeof(value) == "closure") value,
                        primitive = if (is.primitive(value)) name)
                }), names)
            }
            table <- member_binding(ns, ".__S3MethodsTable__.")[[2L]]
            lazy <- tryCatch(getNamespaceInfo(ns, "lazydata"), error = function(e) NULL)
            objects <- unique(c(if (package == "datasets") getNamespaceExports(ns), names(lazy)))
            shapes <- stats::setNames(lapply(objects, function(name) {
                record <- s3_namespace_binding(ns, name)
                if (!identical(record[[1L]], "value") && is.environment(lazy) && name %in% names(lazy)) {
                    record <- member_binding(lazy, name, materialize = TRUE)
                }
                if (identical(record[[1L]], "value")) s3_runtime_shape(record[[2L]])
            }), objects)
            tokens <- list(exports = describe(ns, getNamespaceExports(ns), exported = TRUE), objects = shapes,
                methods = if (is.environment(table) && length(table)) {
                    describe(table, package_metadata_sort(ls(table, all.names = TRUE, sorted = FALSE)))
                })
            # Section-qualified names keep exported and registered aliases apart.
            # Canonical function syntax is reused only while the current binding
            # token and owning namespace are unchanged.
            stats::setNames(lapply(names(tokens), function(section) {
                package_metadata_validation_records(paste(package, "s3", section, sep = ":"), tokens[[section]],
                    list(namespace = ns, metadata = s3_metadata_context, shapes = s3_runtime_shape))
            }), names(tokens))
        }, error = function(e) list(error = conditionMessage(e)))
    })
    if (any(vapply(records, function(record) !is.null(record$error), logical(1L)))) return(NULL)
    digest::digest(records, algo = "xxhash64")
}

s3_namespace_binding <- function(ns, name) {
    # Re-exports can resolve through the imports environment into base.
    # Stop at an existing binding so active bindings never expose a fallback.
    base <- asNamespace("base")
    scopes <- if (identical(ns, base)) list(ns) else list(ns, parent.env(ns), base)
    for (scope in scopes) {
        if (exists(name, scope, inherits = FALSE)) {
            return(member_binding(scope, name, materialize = TRUE))
        }
    }
    member_binding(ns, name, materialize = TRUE)
}

s3_function_identity <- function(fn, owner = "local") {
    syntax <- as.call(list(as.name("function"), fn[[2L]], fn[[3L]]))
    digest::digest(list(owner, deparse1(syntax, collapse = "\n")), algo = "sha256")
}

Try the languageserver package in your browser

Any scripts or data that you put into this service are public.

languageserver documentation built on Nov. 16, 2026, 9:07 a.m.