Reference maps
In AEL, the Agent Engineering Language, a reference map shows what references what, and lists unused code and packages, for a whole project, a folder or one file. ael refmap prints it.
Usage
ael refmap
ael refmap src/api
ael refmap src/nodes/summarize.node.ael
ael 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 AEL 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 AEL 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. ael 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
ael 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.