AEL Docs
Follow updates
Menu
Follow updates
Browse the documentation

AEL 1.0.0

Checking source

In AEL, the Agent Engineering Language, ael check checks your code without building or running it, and reports every problem as a diagnostic that points at your source.

Usage

ael check
ael check src/nodes
ael check src/nodes/summarize.node.ael
ael check --target <target>
ael check --json
Argument or optionMeaning
[path]The project, one folder of it or one source file. Without a path, the project in the current folder.
--target <target>The target to check for.
--jsonDiagnostics in machine-readable form. See Diagnostics.

What it checks

It checks that:

  • Files and roles. The three root files are present, every other source file is named <name>.<role>.ael or, for a language file, <name>.<lang>.ael, and each declares exactly one component whose name matches its file name. Extension files hold only private helper functions of their component.
  • The entry point. main.ael declares main followed by the name in metadata.ael, such as main support(); main main() is refused.
  • Size. Every source file is within the size limit, the bodies of functions in other languages included.
  • Headers. Imports of reusable functions come before the first declaration and name files that exist; every export you select with refer … select … is used in code that can run.
  • Visibility. Each call reaches a function the calling file is allowed to see: its own helpers, global functions of its folder and the folders above, and what it imports or selects.
  • Types and ownership. Every value, input and output has the type its use requires, and ownership rules hold.
  • Effects and capabilities. Each piece of code does only what it has been allowed to do.
  • Hooks. Every hook exists, has the right type for where it is attached, and runs in a valid group.
  • Configuration. Settings are known fields with values of the right type.
  • Subagents. A subagent, a short-lived agent that an agent spawns at run time, is imported where it is named and spawned only where spawning is allowed, with limits that fit those of the agent that spawns it. See Subagents.
  • Isolation. You mark an agent, node or subagent as isolated: it always runs in a sandbox in its own process, outside the shared communication layer, reachable only through the edges you declare and holding only the resources it declares itself. The check refuses an isolated component that reaches anything else. Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it: on macOS, on Windows, on microcontroller boards, on other Linux targets and on any host without those facilities, an isolated component is refused, never run without isolation. See Isolated components.
  • Bindings. An agent, subagent or node declares the memory, skills, knowledge, storage and database it uses, each bound to a package you select, and the check refuses any use it did not declare. See Bindings and storage.
  • Functions in other languages. Your application can hold private functions written in other languages, with typed AEL signatures. Their file names, their privacy, their options and their signatures are checked, and every type in a signature must be one that can cross to the other language. See Functions in other languages.
  • Packages. Every package a file uses is declared by the nearest pack.ael, locked in its pack.lock and installed.
  • The target. The target can offer what the program needs. A feature it cannot support fails here, not on the device.

Every component is checked, including those that main does not reach.

A folder or one file

A folder or a file is checked in the context of its project. It keeps the global functions, imports and packages it inherits from the folders above it, so its result agrees with a check of the whole project. ael check and the build run the same checks, so the two agree.

What it never does

  • It changes no file, and never creates a missing one.
  • It installs no package and contacts no registry: a package that is declared but not installed is reported, with the command that installs it.
  • It runs none of your code and no package code.

If a file changes while ael check is reading the project, it reports that rather than check a mix of old and new files. Run it again once your edits are saved.

Diagnostics

Each problem is reported with its file, line and column, a message and, where it helps, the other places involved, such as the earlier declaration of a duplicate name. With --json, each diagnostic follows the published diagnostic schema. Diagnostics describes both forms.

When any problem is found, ael check ends with a failure status, so an automated build stops there.