From 79c722717ffd96e5c5b5a9493ff01fda8a5171be Mon Sep 17 00:00:00 2001
From: Varun Saini <61795485+vrn-sn@users.noreply.github.com>
Date: Wed, 25 Sep 2024 15:01:16 -0700
Subject: [PATCH] RFC: Amended Require Syntax and Resolution Semantics (#56)

* Add amended-alias-resolution.md

* Move alternatives into main design section for discussion

* Remove certain references to ../

Relative path parenting must already be done explicitly and is not up for discussion.

* Clarify that (3a) supports implicit relative paths

* Link old implementations to these approaches

* Add autocomplete details to (1c)

* Move approaches (2), (3a), (3b) to Alternatives

* Remove references to ../

* Add details about (1c) being compatible with (1a/b)

* Remove paths

* Propose approach (1c)

* Remove implicit ordering for file matching (error)

* Nit: "require statements" -> "require expressions"
---
 docs/amended-require-resolution.md | 241 +++++++++++++++++++++++++++++
 docs/require-by-string-aliases.md  |   2 +
 2 files changed, 243 insertions(+)
 create mode 100644 docs/amended-require-resolution.md

diff --git a/docs/amended-require-resolution.md b/docs/amended-require-resolution.md
new file mode 100644
index 0000000..b9a35c3
--- /dev/null
+++ b/docs/amended-require-resolution.md
@@ -0,0 +1,241 @@
+# Amended Require Syntax and Resolution Semantics
+
+## Summary
+
+We need to finalize a syntax for aliases in require expressions and determine intuitive resolution semantics as we prepare to build a package management system.
+
+## Motivation
+
+In an [old RFC for require-by-string](https://github.com/luau-lang/luau/pull/969), we removed the `@` prefix from aliases altogether and opted for the following design:
+the path `require("my/module")` is resolved by first checking if `my` is an alias defined in a `.luaurc` file.
+If so, we perform a string substitution on `my`.
+If not, we try to resolve `my/module` relative to the requiring file.
+This is identical to approach (3a) below.
+
+This design changed in the next few months and became what we now have in [require-by-string-aliases.md](require-by-string-aliases.md):
+when requiring an alias, it must be prepended with the `@` prefix.
+Otherwise, we will assume the given string does not contain an alias and will resolve it relative to the requiring file.
+This is identical to approach (1a) below.
+
+As we prepare to build an official Luau package management system, we need unambiguous alias functionality.
+This RFC documents the final design decision made after discussion.
+
+Note: The numbered labels below are preserved from an earlier version of this document.
+Discussion in the [PR](https://github.com/luau-lang/rfcs/pull/56) refers to these approaches by their labels, so they have been left as-is in this document.
+
+## Design
+
+### Context
+
+Assume that the following `.luaurc` file is defined:
+```json
+{
+    "aliases": {
+        "libs": "/My/Libraries/Directory"
+    }
+}
+```
+Additionally, assume that we have a file named `dependency.luau` located in these two locations:
+1. `./libs/dependency.luau`
+2. `/My/Libraries/Directory/dependency.luau`
+
+### (1) Make explicit prefixes necessary
+
+#### (1c) All explicit prefixes necessary
+
+We will always require prefixes for disambiguation.
+In other words, any unprefixed path will _always_ result in an error.
+```luau
+-- Error: must have either "@", "./", or "../" prefix
+require("libs/dependency")
+
+-- Requires ./libs/dependency.luau
+require("./libs/dependency")
+
+-- Requires /My/Libraries/Directory/dependency.luau
+require("@libs/dependency")
+```
+
+A benefit of this approach is that the role of autocomplete becomes fairly well-defined.
+When `require("` is typed, autocomplete has only three options to display: the `@`, `./`, and `../` prefixes.
+After a prefix has been typed, autocomplete will either display defined aliases or local modules, depending on the prefix.
+Approaches (1a) and (1b) would be less clear about this, as `require("` could be followed by a string component or one of the three prefixes.
+
+An additional benefit of this approach is that it is forwards-compatible with both (1a) and (1b), which are now in Alternatives.
+We effectively reserve unprefixed paths with this approach and can support either (1a) or (1b) further down the road.
+After a package manager has been implemented, we will likely have a better sense for which option makes the most sense: mapping unprefixed paths to local modules, to aliased modules, or to nothing (keeping unprefixed paths unsupported).
+
+### Removing `paths`
+
+As part of the push to make require expressions more explicit, we will remove `paths`, as aliases defined in `aliases` serve a similar purpose and are more explicit.
+
+### Throw an error if multiple files matched
+
+Currently, we allow `require` to resolve to both `.luau` and `.lua` files, implicitly preferring `.luau` if both are present.
+In line with this proposal's move toward explicit resolution semantics, this behavior will be revised.
+We will continue to support `.luau` and `.lua` files, but we will throw an error if both are present.
+
+We also currently support requiring a directory if it contains an `init.luau` or `init.lua` file.
+If the name of a file matches the name of a sibling directory, we will now also throw an error to avoid ambiguity.
+
+For example, calling `require("./module")` from `requirer.luau` would throw an error in each of these cases (non-exhaustive).
+
+Conflict between `module.lua` and `module.luau`:
+```
+.
+├── module.lua
+├── module.luau
+└── requirer.luau
+```
+
+Conflict between `module` directory and `module.luau`:
+```
+.
+├── module
+│   └── init.luau
+├── module.luau
+└── requirer.luau
+```
+
+## Drawbacks
+
+The main drawback of this approach is that it is quite strict and not backwards-compatible with any existing code that uses unprefixed require expressions.
+However, because of its forwards compatibility with approaches (1a) and (1b), it is possible for us to relax these restrictions in the future.
+
+From an aesthetic point of view, this approach is slightly more cluttered than other approaches, as every path must begin with a prefix.
+
+The removal of `paths` and changes to the implicit resolution order for different file types may also create concerns for backwards compatibility.
+
+## Alternatives
+
+### (1) Make explicit prefixes necessary
+
+Although (1a) and (1b) are both explicit approaches, they take opposite stances on whether writing relative-path requires or aliased-path requires should be optimized for the developer.
+Currently, relative-path requires are far more common, which fits well with approach (1a).
+In the context of a package management system, however, we would expect aliased paths to be used more frequently, which fits better with approach (1b).
+
+These approaches have been moved to Alternatives since they are both backwards-compatible with approach (1c).
+Rather than making an arbitrary decision now, it makes more sense for us to choose (1c) now and reevaluate once package management is a reality.
+
+#### (1a) Make aliases explicit with `@` prefix
+
+We make usage of the `@` prefix necessary in aliased require expressions.
+This means that any unprefixed string is always treated as an unaliased path.
+```luau
+-- Requires ./libs/dependency.luau
+require("libs/dependency")
+
+-- Requires ./libs/dependency.luau
+require("./libs/dependency")
+
+-- Requires /My/Libraries/Directory/dependency.luau
+require("@libs/dependency")
+```
+
+The main drawback of this approach is that projects with many _external_ dependencies will have many `@` symbols appearing within require expressions.
+
+This is similar to [Lune's approach](https://lune-org.github.io/docs/getting-started/2-introduction/8-modules#file-require-statements) and is identical to the approach currently described in [require-by-string-aliases.md](require-by-string-aliases.md).
+
+#### (1b) Make relative paths explicit with `./` prefix
+
+We make usage of the `./` prefix necessary in relative require expressions.
+This means that any unprefixed string is always treated as an aliased path.
+```luau
+-- Requires /My/Libraries/Directory/dependency.luau
+require("libs/dependency")
+
+-- Requires ./libs/dependency.luau
+require("./libs/dependency")
+
+-- Requires /My/Libraries/Directory/dependency.luau
+require("@libs/dependency")
+```
+
+The main drawback of this approach is that projects with many _internal_ dependencies will have many `./` symbols appearing within require expressions.
+
+This is similar to [darklua's approach](https://darklua.com/docs/path-require-mode/).
+
+### (2) Strongly recommend explicit prefixes
+
+We don't make the `@` or `./` prefixes necessary like in approach (1c), but we strongly recommend them.
+
+This can be accomplished by allowing unprefixed paths but throwing an error if they resolve to multiple files.
+There is a performance cost to this: currently, if we successfully match a given path to a file, we stop searching for other matches.
+If this approach were implemented, we would need to search for at most two matching files in case we need to throw an error.
+In the case of multiple nested directories with their own `.luaurc` files and `paths` arrays, this search could take linear time with respect to the total number of paths defined, in the worst case.
+
+Of course, developers could use the `@` or `./` prefixes to explicitly specify a search type and eliminate this performance cost.
+```luau
+-- Error: ./libs/dependency.luau exists and .luaurc defines a distinct "libs" alias
+-- Would require ./libs/dependency.luau if "libs" alias did not exist
+-- Would require /My/Libraries/Directory/dependency.luau if ./libs/dependency.luau did not exist
+require("libs/dependency")
+
+-- Requires ./libs/dependency.luau
+require("./libs/dependency")
+
+-- Requires /My/Libraries/Directory/dependency.luau
+require("@libs/dependency")
+```
+
+This is a compromise between approaches (1a) and (1b) that sacrifices performance for compatibility and readability.
+Unfortunately, this approach could lead to unexpected behavior if users have globally defined `.luaurc` files that conflict with scripts that expect certain aliases to not be defined.
+
+### (3) Use implicit resolution ordering to avoid `@` prefix
+
+If we choose to remove the `@` prefix, we must define an implicit resolution ordering.
+In essence, aliases must either represent overrides or fallbacks for relative path resolution.
+These approaches are not being considered since implicit resolution ordering can be confusing, and people may disagree on which ordering is best.
+
+#### (3a) Aliases as overrides
+
+If aliases were overrides, we would have the following behavior.
+This is identical to the [old RFC](https://github.com/luau-lang/luau/pull/969)'s behavior.
+```luau
+-- Requires /My/Libraries/Directory/dependency.luau
+require("libs/dependency")
+
+-- Requires ./libs/dependency.luau
+require("./libs/dependency")
+
+-- Error: there is no "@libs" alias in .luaurc
+require("@libs/dependency")
+```
+
+If the `libs` alias did not exist, however, we would have the following:
+```luau
+-- Requires ./libs/dependency.luau
+require("libs/dependency")
+
+-- Requires ./libs/dependency.luau
+require("./libs/dependency")
+
+-- Error: there is no "@libs" alias in .luaurc
+require("@libs/dependency")
+```
+
+#### (3b) Aliases as fallbacks
+
+If aliases were fallbacks, we would have the following behavior.
+```luau
+-- Requires ./libs/dependency.luau
+require("libs/dependency")
+
+-- Requires ./libs/dependency.luau
+require("./libs/dependency")
+
+-- Error: there is no "@libs" alias in .luaurc
+require("@libs/dependency")
+```
+
+If `./libs/dependency.luau` did not exist, however, we would have the following:
+```luau
+-- Requires /My/Libraries/Directory/dependency.luau
+require("libs/dependency")
+
+-- Error: does not exist
+require("./libs/dependency")
+
+-- Error: there is no "@libs" alias in .luaurc
+require("@libs/dependency")
+```
\ No newline at end of file
diff --git a/docs/require-by-string-aliases.md b/docs/require-by-string-aliases.md
index ec8e669..63ef37c 100644
--- a/docs/require-by-string-aliases.md
+++ b/docs/require-by-string-aliases.md
@@ -12,6 +12,8 @@ Luau itself currently supports a basic require-by-string syntax that allows for
 
 ## Design
 
+Parts of this design are now obsoleted by [this RFC](https://github.com/luau-lang/rfcs/pull/56).
+
 #### Aliases
 
 Aliases can be used to bind an absolute or relative path to a convenient, case-insensitive name that can be required directly.