Browse the documentation

Early preview

Reference maps

In the Open Engineering Language, a reference map shows what references what, and lists unused code and packages, for a whole project, a folder or one file. oel refmap prints it.

Usage

oel refmap
oel refmap src/api
oel refmap src/nodes/summarize.node.oel
oel refmap --json
Argument or optionMeaning
[path]The project, one folder of it or one source file. Without a path, the project in the current folder.
--jsonThe map in machine-readable form.

What the map shows

The map shows:

  • Every component of your project, and every export of the installed packages.
  • What each one references and what references it: calls, imports of reusable functions, package exports selected with refer … select …, hooks, routes and agent workflows.
  • References that the Compiler adds for you, such as a hook attachment or a mounted route, marked as such.
  • Direct and indirect package dependencies, with the scope each comes from.

Each item gets one status:

StatusMeaning
ReferencedReached from a starting point: main in a program, every public export in a package.
Installed but unusedA package that is installed but never selected by any file.
UnreachableA component that nothing reached from a starting point refers to.
KeptKept for a stated reason, such as a public export of a package.
UnresolvedA reference that could not be resolved; it is also reported as a diagnostic.

Everything that is kept comes with its reason and the chain of references that keeps it. When a server/http app uses only GET, the map shows the GET handler and the shared HTTP code as referenced, and the POST and PUT handlers as unused.

Three views

  • A program. The only starting point is main, with what the Compiler registers for it. A file that exists is not a starting point just because it exists.
  • A package. Every public export is a starting point, so an export that nothing in the package calls is not reported as unused.
  • A folder or one file. What that part references, and its status in the whole project. The global functions, imports and packages it inherits are included, so the view never hides a dependency. Naming an extension file shows its component, with the extension's part marked.

Text strings never create references. A function you pass as a value, or a hook you attach, does.

The map and the build

Every build starts from the same map. oel build computes it from the checked or compiled code, verifies it, and only then builds the program, keeping only what the program reaches. A map saved earlier, or edited by hand, is never trusted by a build.

What it never does

oel refmap runs no code, installs no package and changes no source file. Large maps are shown in a shortened form on screen; the build always uses the complete map.