From 6ba06da7f7b0ae3cdf26ab84439ce30fd4af351b Mon Sep 17 00:00:00 2001 From: ffrostfall Date: Wed, 23 Apr 2025 17:05:12 -0400 Subject: [PATCH 1/3] Initial commit --- docs/luaurc-definition-files.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 docs/luaurc-definition-files.md diff --git a/docs/luaurc-definition-files.md b/docs/luaurc-definition-files.md new file mode 100644 index 0000000..136a45d --- /dev/null +++ b/docs/luaurc-definition-files.md @@ -0,0 +1,21 @@ +# Definition Files in .luaurc Configs + +## Summary + +Implement a field in the `.luaurc` configuration file named "definitionFiles", which accepts an array of paths to ".d.luau" files (aka, declaration files). These definition files would be passed into the typechecker for any luau file under that configuration. + +## Motivation + +As cross-runtime code becomes increasingly common, the model which language servers use today (pass definition files into the API) is proving to not scale. Projects with multiple runtime targets suffer from bad editor experience, and great difficulty in getting types to be correct. + +## Design + +This is the bulk of the proposal. Explain the design in enough detail for somebody familiar with the language to understand, and include examples of how the feature is used. + +## Drawbacks + +This brings declaration files to be in a much more user-facing spot, when definition files are not meant to be user-facing. + +## Alternatives + +What other designs have been considered? What is the impact of not doing this? From 27872f0c7e2af0871b27188725407c0c4d84557e Mon Sep 17 00:00:00 2001 From: ffrostfall <80861876+ffrostfall@users.noreply.github.com> Date: Wed, 23 Apr 2025 22:01:43 -0400 Subject: [PATCH 2/3] Write Design + Drawbacks --- docs/luaurc-definition-files.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/luaurc-definition-files.md b/docs/luaurc-definition-files.md index 136a45d..93f447a 100644 --- a/docs/luaurc-definition-files.md +++ b/docs/luaurc-definition-files.md @@ -10,12 +10,12 @@ As cross-runtime code becomes increasingly common, the model which language serv ## Design -This is the bulk of the proposal. Explain the design in enough detail for somebody familiar with the language to understand, and include examples of how the feature is used. +When analyzing a file, include all of the files specified in the `declarationFiles` field in analyzation. This supercedes the `globals` field, which should be deprecated. ## Drawbacks -This brings declaration files to be in a much more user-facing spot, when definition files are not meant to be user-facing. +This brings declaration files to be in a much more user-facing spot, when definition files are not meant to be user-facing. This could cause confusion, as definition files are currently largely undocumented and have poor syntax. ## Alternatives -What other designs have been considered? What is the impact of not doing this? +TODO From de8ffdc761b98c0e3b48b61b0d0ea4230001f6f7 Mon Sep 17 00:00:00 2001 From: ffrostfall <80861876+ffrostfall@users.noreply.github.com> Date: Sun, 27 Apr 2025 13:02:08 -0400 Subject: [PATCH 3/3] Revisions --- docs/luaurc-definition-files.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/luaurc-definition-files.md b/docs/luaurc-definition-files.md index 93f447a..25d73c5 100644 --- a/docs/luaurc-definition-files.md +++ b/docs/luaurc-definition-files.md @@ -2,20 +2,32 @@ ## Summary -Implement a field in the `.luaurc` configuration file named "definitionFiles", which accepts an array of paths to ".d.luau" files (aka, declaration files). These definition files would be passed into the typechecker for any luau file under that configuration. +Implement a field in the `.luaurc` configuration file named "definitionFiles", which accepts an array of paths to ".d.luau" files (aka, definition files). These definition files would be passed into the typechecker for any luau file under that configuration. ## Motivation -As cross-runtime code becomes increasingly common, the model which language servers use today (pass definition files into the API) is proving to not scale. Projects with multiple runtime targets suffer from bad editor experience, and great difficulty in getting types to be correct. +As cross-runtime code becomes increasingly common, the model which language servers use today (pass definition files into the API) is proving to not scale. Projects with multiple runtime targets suffer from bad editor experience, and great difficulty in getting types to be correct. This is because you cannot manage runtime types on a per-folder basis, which makes monorepos difficult, as types from, for example, the Lute runtime, will leak into Roblox files. + +Taking advantage of `.luaurc`'s inheriting behavior allows for granular control over definition files. This could be used for something like specifying testing framework globals used within a `tests` directory, when the project is under a runtime with definition files already. ## Design -When analyzing a file, include all of the files specified in the `declarationFiles` field in analyzation. This supercedes the `globals` field, which should be deprecated. +When analyzing a file, include all of the files specified in the `definitionFiles` field in analyzation. This supercedes the `globals` field, which is deprecated under this proposal. + +If a specified path is relative, then it should be resolved from the path of the luaurc file specifying it. + +Example usage: + +``` +{ + "definitionFiles": [ "~/.lute/typedefs/0.1.0/globals.d.luau" ] +} +``` ## Drawbacks -This brings declaration files to be in a much more user-facing spot, when definition files are not meant to be user-facing. This could cause confusion, as definition files are currently largely undocumented and have poor syntax. +This brings definition files to be in a much more user-facing spot, when definition files are not meant to be user-facing. This could cause confusion, as definition files are currently largely undocumented and have poor syntax. ## Alternatives -TODO +This isn't truly necessary, and relying on code editors to provide type definition files does work.