luacheckrc

[bmos]

I've been using luacheck to check my code and really like the detection of non-whitelisted globals (among other things) since it makes typos nearly impossible.
Unfortunately, luacheck doesn't know about the (many) globals that are part of the FG rulesets and API.

I've also made a GitHub Action (https://github.com/FG-Unofficial-Developers-Guild/action-generate-luacheckrc) which allows you to generate a luacheckrc file from the rulesets and extensions that you work with.
The README is pretty clearly written, but you can find my personal example here (https://github.com/bmos/FG-luacheck/blob/main/.github/workflows/main.yml) along with its output here (https://github.com/bmos/FG-luacheck/blob/main/.luacheckrc).

For insight into how I personally use this:
I use VSCodium (https://vscodium.com/) for development along with the LuaCoderAssist extension (https://github.com/liwangqian/LuaCoderAssist). Setting it up is a bit goofy ("config file path" means path to directory, not path to file -- this of course means the file must have the expected name of ".luacheckrc" -- and you also need to disable "define the luacheck cli options automatically"), but it has a bunch of very neat features to help with lua development and encourage use of slim functions. By using my luacheckrc config file (https://raw.githubusercontent.com/bmos/FG-luacheck/main/.luacheckrc) in this way, it automatically underlines MANY common mistakes in real-time as you're editing scripts. For people who want to use global functions without being warned or having to create specific exemptions, add "allow_defined_top = true" to the top of the .luacheckrc file. (suggested by MeAndUnique)

[JustinFreitas]

I use it! I add any external class names to it that I reference in my code. I'll check out your config and see how it works for me. Thanks.

[bmos]

Spent most of my day today working on a script to programmatically generate a luacheck file from extracted ruleset folders.
Still need to figure out a solution for all the global scripts that are accessed in windowclass scripts, but this is a huge improvement.
Here is the output: https://github.com/bmos/FG-luacheck/blob/main/.luacheckrc

[Moon Wizard]

Thanks for the submissions you've found so far in your analysis. Very interested in seeing how this turns out, as it may be an interesting tool for our internal ruleset developers.

Regards,
JPG

[bmos]

Still haven't gotten started with the windowcontrol object names (since these are like high level scripts in that they have functions accessible under them), but my GitHub action that creates a luacheckrc file based on FG rulesets with base.xml + lua files and extensions with extension.xml + lua files is ready for wider use :)

https://github.com/FG-Unofficial-Developers-Guild/action-generate-luacheckrc

The README probably has everything needed to generate your own luacheckrc file based on the rulesets and extensions you use/work with and serves as a pretty complete demo. You will have to supply your own unzipped copies of the rulesets and extensions, since those are not mine to share publicly.

[MostTornBrain]

Oh wow! Thanks for sharing this bmos! Having come at lua programming from a purely hobby endeavor, I did not know a thing such as luacheck existed. But as someone that uses static code analysis tools in my day job, I greatly appreciate this tip. I'll definitely take a look at this. I had recently wondered what the little "lua check" tag was on the github page for one of your extensions, but with so little free time, I got distracted and completely forgot about it.

Cheers,
Brian

[bmos]

Oh wow! Thanks for sharing this bmos! Having come at lua programming from a purely hobby endeavor, I did not know a thing such as luacheck existed. But as someone that uses static code analysis tools in my day job, I greatly appreciate this tip. I'll definitely take a look at this. I had recently wondered what the little "lua check" tag was on the github page for one of your extensions, but with so little free time, I got distracted and completely forgot about it.

Cheers,
BrianYou're welcome! Hopefully it helps you make the most of your hobby time :)
Let me know if you have any config questions. I use the file for both auto-linting on github of PRs and commits and also use it in Atom (GitHub's cross-platform open source code editor) with the linter-luacheck plugin so that it analyses my code whenever I stop typing.

[bmos]

action-generate-luacheck v1.1 (https://github.com/FG-Unofficial-Developers-Guild/action-generate-luacheckrc/releases/tag/v1.1) now scans provided extensions as well and re-formats package names to avoid syntax errors from luacheck.
It also scans lua files that aren't 'high level scripts', although not yet to the extent I would like (they aren't nested under the windowcontrol name). You can see an example here (https://github.com/bmos/FG-luacheck/blob/482f545fc327a533f7c6829cc3cbaccf50ceb3f1/.luacheckrc#L4167).

I have updated the FG-luacheck repo (https://github.com/bmos/FG-luacheck/) accordingly so a better pregen file is available to use (now 44,953 lines up from 22,680 lines generated with v1.0)

[bmos]

After working on this some more, I released v1.2 (https://github.com/FG-Unofficial-Developers-Guild/action-generate-luacheckrc/releases/tag/v1.2) handles those interface scripts very differently. You can see an example here (https://github.com/bmos/FG-luacheck/blob/169db7b2e9d77b73aca4f52e0f49e5d8996cb19e/.luacheckrc#L4621). I have updated the FG-luacheck repo (https://github.com/bmos/FG-luacheck/) accordingly so a better pregen file is available to use (now 45,642 lines up from 44,953 lines generated with v1.1).

Furthermore, today I have released v1.2 which simplifies std definition names of extensions by getting the correct author+name from extension.xml and using that rather than the filename. I have again updated the the FG-luacheck repo (https://github.com/bmos/FG-luacheck/) so a better pregen file is available to use without setting up your own action (still 45,642 lines).

[bmos]

After working on this some more, I released v1.2 (https://github.com/FG-Unofficial-Developers-Guild/action-generate-luacheckrc/releases/tag/v1.2) which handles interface scripts very differently (functions are now nested under the parent windowcontrol rather than the script name--since that doesn't actually matter). You can see an example here (https://github.com/bmos/FG-luacheck/blob/169db7b2e9d77b73aca4f52e0f49e5d8996cb19e/.luacheckrc#L4621). I have updated the FG-luacheck repo (https://github.com/bmos/FG-luacheck/) accordingly so a better pregen file is available to use (now 45,642 lines up from 44,953 lines generated with v1.1)

Furthermore, today I have released v1.3 (https://github.com/FG-Unofficial-Developers-Guild/action-generate-luacheckrc/releases/tag/v1.3) which simplifies std definition names of extensions by getting the correct author+name from extension.xml and using that rather than the filename. I have again updated the the FG-luacheck repo (https://github.com/bmos/FG-luacheck/) so a better pregen file is available to use without setting up your own action (still 45,642 lines).

The next thing to tackle is detecting globals that are tables and whitelisting all child entries so that adding entries to ruleset tables doesn't result in a warning.

[MostTornBrain]

With luacheck, how does one prevent the warnings about "setting non-standard global variable" for every FGU function override defined? Do I need to add each one to the globals list in the .luacheckrc file?

Examples are onClickDown(), sourceupdate(), onSourceUpdate(), and onFirstLayout(). They all get flagged as non-standard global variable definitions by luacheck. I was assuming I need to make these global to override the existing functions for the same windowclass. Should I actually declare them local?

What's the actual scope of scripts that override/merge with an existing windowsclass or are loaded via tags in the XML? Are they really global, or is there some implied scope/block boundary created by the windowclass that includes them and its a limitation that luacheck can't detect the implied scope because that's way out of context of how the tool operates? Not sure if that is really a lua question or more of a question about an implementation detail with how FGU integrates lua and provides support for extensions.

Thanks for any clarification,
Brian

[bmos]

With luacheck, how does one prevent the warnings about "setting non-standard global variable" for every FGU function override defined? Do I need to add each one to the globals list in the .luacheckrc file?

Examples are onClickDown(), sourceupdate(), onSourceUpdate(), and onFirstLayout(). They all get flagged as non-standard global variable definitions by luacheck. I was assuming I need to make these global to override the existing functions for the same windowclass. Should I actually declare them local?

What's the actual scope of scripts that override/merge with an existing windowsclass or are loaded via tags in the XML? Are they really global, or is there some implied scope/block boundary created by the windowclass that includes them and its a limitation that luacheck can't detect the implied scope because that's way out of context of how the tool operates? Not sure if that is really a lua question or more of a question about an implementation detail with how FGU integrates lua and provides support for extensions.

Thanks for any clarification,
Brian
Ah, those should be added here for now: https://github.com/bmos/FG-luacheck/blob/main/.luacheckrc_header
I don't have a comprehensive list, so please add whatever you find :) Or just post them here and I can add them.
Eventually I need to revise my parser to auto-whitelist globals based on the templates they inherit.

[bmos]

Made some progress today toward getting templates working.
At this point they're included in definitions, but they don't append themselves to objects that use them.
Coming soon, hopefully. The number of lines has actually decreased since adding this, so I have left the luacheckrc file alone and just saved the new one on a public testing branch. Use whichever works best for you (probably the main branch for now).

The other big problem I have realized is that many very low-level/core FG functions are written in <script> tags in xml files. At the moment my code doesn't handle these at all. That one is a big less straightforward to solve, so I'm going to try and finish the parsing of templates whose scripts are in discrete lua files first.

[bmos]

Lots of changes since the 26th.

In-xml interface scripts are now parsed.
Templates are now handled, both for script files and in-xml scripts.

https://raw.githubusercontent.com/bmos/FG-luacheck/main/.luacheckrc

The remaining primary issue is that adding items to ruleset global tables produces a warning from luacheckrc.

[bmos]

I'd love to hear suggestions on this issue:

When running luacheck on a lua file attached to an interface object, luacheck doesn't know what the parent template of the file is (so it doesn't know about the functions whitelisted in that template). Since this is not a function of my parser script, but rather of luacheck, I would have to fork luacheck iteself to add some feature for scope detection (which would be FG specific) if I wanted to actually 'fix' this.

One easier option is to add all functions to a global definition table which would resolve those errors. The downside is that luacheckrc would not know if you're calling a function that doesn't exist in that interface object. For example, using "setComboBoxReadOnly" would not show an error if used in a script that was attached to a numbercontrol. Effectively it would be whitelisting all functions of all interface objects for use in all interface scripts.

Another option is to add per-file definitions via a lua comment such as "-- luacheck: globals getName" which would allow use of that function in the file. This is a significant task for each developer, but would preserve much more linting functionality. (https://github.com/FG-Unofficial-Developers-Guild/action-generate-luacheckrc/issues/7)

I'm feeling kind of stumped.

EDIT:
There might be a solution built into luacheck. (https://luacheck.readthedocs.io/en/stable/config.html#per-file-and-per-path-overrides)
It would require generating a luacheck file for each project it's used in (something I was already considering that could be a big improvement for execution speed and flexibility).
* Parse project to create an array linking script filenames to their interface object names.
* Run current parsing logic on the inherited dataset (such as CoreRPG and Moon Tracker extension).
* Use inherited dataset to add per-file whitelists for any files found in project.

The downside is that you would have to re-run this program on the project directory whenever you created a new file.

[bmos]

Updated the luacheck_headers (https://github.com/bmos/FG-luacheck/blob/main/.luacheckrc_header) file to specifically whitelist all API functions listed in the customer portal/documentation (https://fantasygroundsunity.atlassian.net/wiki/spaces/FGCP/pages/996644556/API+-+Packages). This allows for typo-detection for things like "DB.getVaalue".

Also, for insight into how I personally use this:
I use VSCodium (https://vscodium.com/) for development along with the LuaCoderAssist extension (https://github.com/liwangqian/LuaCoderAssist). Setting it up is a bit goofy ("config file path" means path to directory, not path to file -- this of course means the file must have the expected name of ".luacheckrc" -- and you also need to disable "define the luacheck cli options automatically"), but it has a bunch of very neat features to help with lua development and encourage use of slim functions.

By using my luacheckrc config file in this way, it automatically underlines MANY common code errors in real-time as you're editing scripts.

For people who want to use global functions without being warned or having to create specific exemptions, add "allow_defined_top = true" to the top of the .luacheckrc file. (suggested by MeAndUnique)

[Jiminimonka]

Love it!

[bmos]

action-generate-luacheck v1.8 - enable all detected global definitions (https://github.com/FG-Unofficial-Developers-Guild/action-generate-luacheckrc/releases/tag/v1.8)
* std global definitions are now automatically added to the std string based on scanned packages
* if encountering empty xml <script> tags, post a warning message and continue. previously, an error was encountered.
* package names and authors are now parsed differently. previously, author tags with a colon would not be read correctly. suggested author format is a comma-separated list with the primary maintainer at the beginning.

action-generate-luacheck v1.9 - nil error fixes, sorting improvements, more error messaging (https://github.com/FG-Unofficial-Developers-Guild/action-generate-luacheckrc/releases/tag/v1.9)
* Definitions are now sorted using a more consistent ordering function to prevent uneccessary changes to the output config. This makes it much easier to tell what has changed in the output between runs.
* Most missing values will add an error to the output to assist in diagnosing missing global definitions.
* Most missing values will no longer cause script to fail with nil error.