Reference maps
In AEL, the Agent Engineering Language, a reference map will show what references what, and list unused code and packages, for a whole project, a folder or one file. ael refmap (command names may change before launch) will print it.
Status
Planned for AEL Beta 0.0.1. AEL is not available yet.
Package names on this page are preview naming and may change before launch.
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 will show:
- 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 will get 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 will come with its reason and the chain of references that keeps it. When a server/http app uses only GET, the map will show 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 will be
main, with what AEL registers for it. A file that exists will not be a starting point just because it exists. - A package. Every public export will be a starting point, so an export that nothing in the package calls will not be 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 will be included, so the view never hides a dependency. Naming an extension file will show its component, with the extension's part marked.
Text strings will never create references. A function you pass as a value, or a hook you attach, will.
The map and the build
Every build will start from the same map. ael build will compute it from the checked or compiled code, verify it, and only then build the program, keeping only what the program reaches. A map saved earlier, or edited by hand, will never be trusted by a build.
What it never does
ael refmap will run no code, install no package and change no source file. Large maps will be shown in a shortened form on screen; the build will always use 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.