Formatting source

In AEL, the Agent Engineering Language, ael fmt formats your source files in one consistent style, so every project reads the same way and a review shows only real changes.

Usage

ael fmt
ael fmt src/agents/support.agent.ael
ael fmt --check
ael fmt --check --json

Argument or option	Meaning
`[path]`	A project folder or one `.ael` file. Without a path, the project in the current folder.
`--check`	Write nothing; list the files that would change.
`--json`	A machine-readable report of the files changed, or that would change.

What it formats

It formats:

Every source file of the project: main.ael, pack.ael, metadata.ael and every component file.
A component and its extension files as one unit. Naming one extension file formats the whole component, all of its files or none of them.

What it keeps

Comments, strings and prompt text, byte for byte. A # or a backtick inside a string stays exactly as you wrote it.
Your files. ael fmt never splits a file, moves code from one file to another or moves a header.
The size limit. If formatting would push a file past the size limit, the file is left exactly as it was and reported, with a suggestion to move helpers into an extension file.

Line breaks are written as line feeds.

Formatting a formatted file changes nothing. Before writing, ael fmt formats its own result a second time, and it writes nothing at all unless both passes agree.

Checking formatting

ael fmt --check builds the same plan, writes nothing, and lists the files that would change. It ends with a failure status when any file would change, so an automated build can require formatted source:

ael fmt --check

How files are written

Nothing is written until every selected file has been formatted and checked.
Files that would not change are not touched.
Each file is replaced in one step, so nothing ever reads a half-written file.
If a file changes while ael fmt is working, that file is left alone and reported.

Files are written one after another; there is no single step for the whole project. If writing stops part-way, for example because a disk is full, every file already written is complete and formatted, the report lists them, and running ael fmt again finishes the rest.

Formatting is separate from checking

ael fmt reads your files' structure, not their meaning. A formatted file may still fail ael check, and a file that formats cleanly has not been type-checked or built.

Syntax basics: the layout the formatter writes.
Checking source: checking is a separate step.