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 option | Meaning |
|---|---|
[path] | The project, one folder of it or one source file. Without a path, the project in the current folder. |
--json | The 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:
| Status | Meaning |
|---|---|
| Referenced | Reached from a starting point: main in a program, every public export in a package. |
| Installed but unused | A package that is installed but never selected by any file. |
| Unreachable | A component that nothing reached from a starting point refers to. |
| Kept | Kept for a stated reason, such as a public export of a package. |
| Unresolved | A 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.
Related
- Using packages: selecting exports, and why a selected export must be used.
- Why a package is in a project: the dependency path that brings in a package.
- Building a program: what goes into the program.