zwilias / elm-xref

Experimental tool for finding unused functions/finding usages

elm-xref

Cross-referencing tools for Elm. Find unused code, and figure out where specific functions are used.

Installation

npm i -g elm-xref

Usage

To index a project and find unused functions, execute elm-xref in the same directory as your elm.json. This works for both application as well as package projects.

To find usages of a function, specify the fully qualified function name as an argument.

Examples on rtfeldman/elm-spa-example@c8c3201:

# To find unused functions:
$ elm-xref
Unused functions:
 - /Users/ilias/Src/elm/elm-spa-example/src/Api.elm:294:1       Api.cacheStorageKey
 - /Users/ilias/Src/elm/elm-spa-example/src/Api.elm:299:1       Api.credStorageKey
 - /Users/ilias/Src/elm/elm-spa-example/src/Api.elm:73:1        Api.decode
 - /Users/ilias/Src/elm/elm-spa-example/src/Author.elm:120:1    Author.follow
 - /Users/ilias/Src/elm/elm-spa-example/src/Author.elm:125:1    Author.unfollow
 - /Users/ilias/Src/elm/elm-spa-example/src/Avatar.elm:55:1     Avatar.toMaybeString
 - /Users/ilias/Src/elm/elm-spa-example/src/Email.elm:30:7      Email.Email
 - /Users/ilias/Src/elm/elm-spa-example/src/Email.elm:44:1      Email.decoder
 - /Users/ilias/Src/elm/elm-spa-example/src/Email.elm:39:1      Email.encode
 - /Users/ilias/Src/elm/elm-spa-example/src/Email.elm:34:1      Email.toString
 - /Users/ilias/Src/elm/elm-spa-example/src/Main.elm:112:7      Main.ChangedRoute
 - /Users/ilias/Src/elm/elm-spa-example/src/Page.elm:26:7       Page.Login
 - /Users/ilias/Src/elm/elm-spa-example/src/Page.elm:27:7       Page.Register
 - /Users/ilias/Src/elm/elm-spa-example/src/Page.elm:28:7       Page.Settings
 - /Users/ilias/Src/elm/elm-spa-example/src/Page/Settings.elm:90:7      Page.Settings.Valid
 - /Users/ilias/Src/elm/elm-spa-example/src/Page/Settings.elm:456:1     Page.Settings.nothingIfEmpty
 - /Users/ilias/Src/elm/elm-spa-example/src/Route.elm:19:7      Route.Root

# To find usages of `Maybe.Just`:
$ elm-xref Maybe.Just
Usages:
 - Api.storeCredWith (113)
 - Article.faveDecoder (231)
 - Article.favorite (221)
 - Article.Comment.post (80, 81)
 - Article.Slug.urlParser (22)
 - Author.followDecoder (145)
 - Author.requestFollow (132)
 - Main.changeRouteTo (179)
 - Page.Article.Editor.create (535, 536)
 - Page.Article.Editor.edit (560)
 - Page.Article.Editor.getSlug (583, 586, 589, 592, 595)
 - Page.Settings.nothingIfEmpty (462)
 - Session.cred (42)
 - Session.viewer (32)
 - Username.urlParser (43)

Value constructors of types are also tracked. Note that only constructing values is tracked as usage - pattern matches and destructuring are not tracked as usage.

Usage tracking isn't terribly clever. This tool only does static analysis and does not attempt to evaluate any expressions. As a result, functions that only appear in "obviously unreachable code" (i.e. conditionals that always evaluate to False) do very much count as usage.

Roadmap

• Support whitelisting (f.e. with phantom types or internal modules with consistent API)
• Show unused parameters
• Support type aliases (as function and in type signatures)

License

See the LICENSE file.

elm-xref's Issues

Allow to specify entrypoint

Hi, and thanks a lot for writing this tool and updating it for Elm 0.19
I'm planning on using it in my resource packing workflow. The plan is this:

1. Scan all the resources and code-generate Elm files that expose the resources as functions.
2. Scan the resource functions for usage
3. Only pack the resources that are actually used
   I think elm-xref can help a lot with this, but one thing I'm not clear on is how to find out which entrypoints use a certain function. This is important to me because our Elm codebase has many entrypoints, and they could become unused as the codebase changes, but may still contribute to the usage of a function.

Syntax error for node v6.10.2

There is a syntax error for ... in node v6.10.2. Any plan to support older versions? Spread operator is supported from v8.6.0.

elm-xref
/Users/akoppela/.nvm/versions/node/v6.10.2/lib/node_modules/elm-xref/index.js:227
                return { ...pkg, version: versions[0] };
                         ^^^
SyntaxError: Unexpected token ...
    at createScript (vm.js:56:10)
    at Object.runInThisContext (vm.js:97:10)
    at Module._compile (module.js:542:28)
    at Object.Module._extensions..js (module.js:579:10)
    at Module.load (module.js:487:32)
    at tryModuleLoad (module.js:446:12)
    at Function.Module._load (module.js:438:3)
    at Module.runMain (module.js:604:10)
    at run (bootstrap_node.js:393:7)
    at startup (bootstrap_node.js:150:9)

3 moderate severity vulnerabilities when installing elm-xref

semver-regex  <3.1.3
Severity: moderate
Regular Expression Denial of Service (ReDOS) - https://github.com/advisories/GHSA-44c6-4v22-4mhx
fix available via `npm audit fix --force`
Will install [email protected], which is a breaking change
node_modules/semver-regex
  semver-sort  <=0.0.4
  Depends on vulnerable versions of semver-regex
  node_modules/semver-sort
    elm-xref  >=0.3.2
    Depends on vulnerable versions of semver-sort
    node_modules/elm-xref

3 moderate severity vulnerabilities

Support a Structured Output Format

For example, when passing a --format=json flag, have the entire stdout output be a JSON object.

My desire is to be able to call elm-xref from a Haskell build script, parse the output, and prettily print the warnings of multiple tools(this, elm-analyse, elm-format --validate, etc.).

I can currently parse the output format, but it'd be nice if I didn't have to tweak if the end-user formatting ever changes.

Windows support

The current algorithm for getting elm's home directory expects a .elm folder, but on Windows the folder is under appdata, for example on my machine:

C:\Users\gigobyte\AppData\Roaming\elm\0.19.0\package\NoRedInk\elm-json-decode-pipeline\1.0.0\elm.json

instead of

C:\Users\gigobyte\.elm\0.19.0\package\NoRedInk\elm-json-decode-pipeline\1.0.0\elm.json

This, of course, results in an ENOENT error when trying to run elm-xref.

`elm-xref` doesn't work when dependency has not been installed with 0.19.0 specifically

I noticed elm-xref crashes when a dependency has not been installed with the specific 0.19.0 version.
When I have a project in 0.19.1, and I have never installed a dependency using Elm 0.19.0 (or never used 0.19.0), elm-xref will print an error like

{ Error: ENOENT: no such file or directory, scandir '/home/jeroen/.elm/0.19.0/package/elm/core'
  errno: -2,
  code: 'ENOENT',
  syscall: 'scandir',
  path: '/home/jeroen/.elm/0.19.0/package/elm/core' }

and then not do any verification. The process then exits with status code 0, meaning that it doesn't block our tests or CI (where we never installed dependencies with 0.19.0), but we also "silently" lost the guarantee of not having unused functions.

To reproduce

• Go to your Elm home (~/.elm/ on UNIX systems and C:/Users/<user>/AppData/Roaming/elm on Windows), and (re)move the 0.19.0 directory if present
• Create a new Elm project using Elm 0.19.1
• Run elm-xref on the project
• Notice a crash

Investigation

elm-xref seems to have hardcoded looking for dependencies in the 0.19.0 directory.

For applications, I suggest looking for the version present in the project's elm.json file.
For packages, I am not sure what would be best, as we don't have the version of the compiler that is actually used (0.19.1 could be used by the developer, but the package supports 0.19.0). Maybe trying all 0.19.x folders present in the Elm home from latest to oldest until a dependency is found?

Thanks!

While I'm here, let me take the opportunity to thank you for this wonderful tool 😊
It has been so useful to me and my projects to keep them clean ❤️

Should consider Test functions as entry points

so that dead code can be found among the e.g. helpers for a test suite