We do a lot of delegation throughout the Jekyll codebase. Is the "Forwardable" module insufficient for this?

If I remember correctly, the main motivation behind this was to avoid initialising interim objects. At the time, using Forwardable's def_delegators method resulted in allocating an Array object on every invocation of the delegated method. Anyways, this method has been designated as a private_class_method so that it can be changed or removed with minimal side-effects.

@meta is a very generic name which doesn't explain what this variable is used for. Could we use a more descriptive name that tells us what it holds?

The Hash instance assigned to the variable contains the data of constituent data files. I had therefore considered naming the variable @data, then @metadata and finally just @meta.
Naming things is hard 😢
I will try to come up with better names..

It's @files right? in DataReader, the code does data[key] = DataFile.new... which stores into this hash by method_missing. https://github.com/jekyll/jekyll/pull/8771/files#diff-ae0ebeb5a3a44f07ee61a0e5851d165c646ddab160824029c467bffea3717e7bR51

I'd call it @files or something like that since that's what it's storing? Is it storing anything else?

@parkr, @files makes me think of an Array of file objects like how we have an array of staticfiles. But DataFile isn't technically a file object either, only a container for the "parsed data" of the actual data file on disk. The closest I think that will express the intention correctly is calling this variable a @registry and DataFile to be DataEntry instead.

to_liquid is generally a means of sanitizing output, converting into a Drop, or returning a simpler data structure. I don't see a private below here so we'd be exposing #merge, #merge!, and all other Hash methods (from method_missing). It seems like we'd rather simply expose the #[](key) method to Liquid? I'd rather see a simple Drop here which grants basic access to the underlying Hash of File objects.

This was intentional to maintain backwards-compatibility.
As of Jekyll 4.2.x, the top-level objects of site_data are Hash instances. Hash#to_liquid returns the current Hash instance. So all of the public methods should continue to be invokable in the future.

This needs a method comment describing the inputs, since it's a bit vague (e.g. is "path" relative or absolute?)

@content throughout the Jekyll codebase generally refers to plain text. Perhaps @data or @structured_content would help indicate that this is generally not a text value, but rather False, Array, or Hash.

In generally, I try to not use class names which match stdlib names, like File. It can just confuse things a bit. We could try Jekyll::DataFile and Jekyll::DataDirectory, or something which doesn't match the stdlib name File.

There are no unit tests for this anywhere – is that intentional? I would be happy to see simple unit tests for creating an instance and checking equality, where you have some custom code.

The cucumber test suite is quite slow as it is. An optimization in a later PR could be to limit these waits to a smaller value and/or use a more granular mtime in our incremental meantime. 🤔

A comment here would still be nice, since I have to make certain assumptions about these variables. Something like:

# Create a DataFile.
# site - the Jekyll::Site this file belongs to
# abs_path - the absolute path to the file
# data - the parsed contents of the data file

If the comment is wrong, then it only helps to illustrate why a comment is helpful 😜

Your assumptions here are correct. I'll add the suggested comment to avoid assumptions. 🙂

It's @files right? in DataReader, the code does data[key] = DataFile.new... which stores into this hash by method_missing. https://github.com/jekyll/jekyll/pull/8771/files#diff-ae0ebeb5a3a44f07ee61a0e5851d165c646ddab160824029c467bffea3717e7bR51

I'd call it @files or something like that since that's what it's storing? Is it storing anything else?

Is the only reason we have DataHash for this one line?

Primarily yes. But also to avoid manipulating the Ruby Core class Hash.
Ultimately, we need a way to detect what entities are dependent on a given data file or directory of data files to trigger the entity's re-rendering when data file(s) change. The most common way end-users directly consume Jekyll::Site#site_data is via Liquid drops: {{ site.data[my_var] }}. Therefore, the only access to the parent entity's path attribute is via the Liquid context. So, we need an object that behaves like Ruby's own Hash yet be aware of render context and remain the same subclass after execution of certain methods (that return a Hash object irrespective of the caller class).
The last point is debatable because I don't quite remember which methods exactly and therefore cannot assert whether modern Ruby versions have addressed that oddity.

Gotcha, thanks for the reiteration.