Doc export file paths all start with ile://

[rhys-vdw]

How are you using the lua-language-server?

Command Line

Which OS are you using?

Windows WSL

What is the issue affecting?

Other

Expected Behaviour

Paths in exported doc JSON should start with file:/// as in the example:

"file": "file:///c%3A/Users/Me/Documents/Array.lua",

Actual Behaviour

Missing the leading f:

"file": "ile:///home/rhys/spring/./cont/base/springcontent/LuaHandler/handler.lua",

Reproduction steps

rhys@RhysDesktop:~/spring$ lua-language-server --doc . --doc_out_path docs/
root uri = file:///home/rhys/spring/.
Documentation exported:91/2488

docs/doc.json
docs/doc.md

Additional Notes

rhys@RhysDesktop:~/spring$ lua-language-server --version
<Unknown>

rhys@RhysDesktop:~/spring$ lua-language-server --help
Content-Length: 55

{"jsonrpc":"2.0","method":"$/hello","params":["world"]}

How do you get a version?

Log File

No response

[rhys-vdw]

Ah...

rhys@RhysDesktop:~/spring$ brew info lua-language-server
==> lua-language-server: stable 3.13.0 (bottled), HEAD

[tomlau10]

This may be a related issue: #2964, which points out that the file uri format seems changed since a recent refactor PR #2821 by a contributor.

I strongly suspect that there maybe some hidden bugs in that refactor PR. 🤔

[rhys-vdw]

We are currently working on a full documentation export for a large RTS engine, so it should be a good test case. Is there a prior release version we can try rolling back to to compare doc export before this PR was merged?

[tomlau10]

By looking at the release page, #2821 is released in v3.10.6, so I guess you may try the prior release v3.10.5 🤔

[rhys-vdw]

I can't work out how to install a historic version with brew.

rhys@RhysDesktop:~/spring/doc/site$ brew install [email protected]
Warning: No available formula with the name "[email protected]". Did you mean lua-language-server?
==> Searching for similarly named formulae...
==> Formulae
lua-language-server

To install lua-language-server, run:
  brew install lua-language-server

rhys@RhysDesktop:~/spring/doc/site$ brew search lua-language-server
==> Formulae
lua-language-server                    vala-language-server                   yaml-language-server                   sql-language-server                    bash-language-server

Is this possible?

[rhys-vdw]

Okay, I just installed directly from the GitHub releases. I can confirm that this version does not have the above issue, and also fixes #2977. It seems this PR may have introduced a number of issues.

[tomlau10]

I just took some time to debug into this, found the logic that causing this issue, but have yet come up with a good solution 😕

• the file path of each file is transformed by this export.getLocalPath()
  

  lua-language-server/script/cli/doc/export.lua

  Lines 57 to 65 in 7f76050

  	function export.getLocalPath(uri)
  	--remove uri root (and prefix)
  	local local_file_uri = uri
  	local i, j = local_file_uri:find(DOC)
  	if not j then
  	return '[FORIEGN]'..uri
  	end
  	return local_file_uri:sub( j + 1 )
  	end

• the uri here is the file:///... string
• the DOC global here is the --doc=xxx value that passed in via CLI

---

I believe this logic intends to remove the path prefix, such that each paths in the output are relative to the supplied directory. For example:

• /data/test/a.lua
• /data/test/b.lua
• by using --doc=/data/test
  => the expected paths in output md/json will just be /a.lua, /b.lua

‼️ However when using --doc=., since . means match anything in a standard string.find()
=> this just match the 1st char
=> j = 1 (the end index of the match)
=> so the last statement return local_file_uri:sub( j + 1 ) gives ile://... 🤦‍♂️

Now you may think that we can simply pass plaintext=true in string.find
=> local_file_uri:find(DOC, 1, true)
But that's not enough ‼️
Because DOC can just be ., and there can be cases that the project folder is located in some directory with name aaa.bbb
=> this will still matches the . in the middle

---

Workaround 1

• use absolute path when invoking from cli, such as

lua-language-server --doc=$PWD --doc_out_path docs/

=> each file path will now be /a.lua, /b.lua, ...

• if you don't want to / at the begining, then use $PWD/

lua-language-server --doc=$PWD/ --doc_out_path docs/

=> each file path will now be a.lua, b.lua, ...

Workaround 2

Judging from the diff in #2821, the original handling of file name is just to use guide.getUri()
And that #2821 actually provides a Lua.docScriptPath config for you to override the functions in that export module.
So you can have the following:

• in .luarc.json

   ...
   "docScriptPath": "export.lua"

• export.lua

function export.getLocalPath(uri)
    return uri
end

• finally trigger through cli using absolute path with /

lua-language-server --doc=$PWD/ --doc_out_path docs/

=> now you should have the classic uri result