Fixes and the beginner level
archec can fix the mistakes a newcomer makes most often. A fix is a set of text
edits that archec computes from the checked model (in src/fixes.ts). Once a
fix is applied, its diagnostic is gone. The tests apply every kind of fix and
check the model again.
A first fix#
This model has a typo: the link ends on lamp.cdm, but the port is cmd.
message GO: bool
component Lamp "Lamp" {
in cmd: can receives GO
}
component Button "Button" {
out click: can sends GO
}
system Room "Room" {
part lamp: Lamp
part button: Button
button.click -> lamp.cdm
}
Save it as main.arche and check it:
archec check main.arche
main.arche:14:19 error Cannot find 'lamp.cdm' in Room. Did you mean 'lamp'? [unresolved]
| button.click -> lamp.cdm
| ^^^^^^^^
✗ 1 error(s), 0 warning(s)
Now let archec fix it:
archec fix main.arche
main.arche:14 [unresolved] Change to 'cmd'
--- main.arche
@@ line 14 @@
part button: Button
+ button.click -> lamp.cmd
- button.click -> lamp.cdm
}
1 fix(es) applied in 1 file(s)
archec check main.arche now prints ✓ no errors.
Where the fixes are#
- In VS Code: the light bulb on a diagnostic (Ctrl+. or Cmd+.). The first
fix in the list is the preferred one. It is the one that Fix all and Auto
Fix apply. Every diagnostic also has Explain [code]. It opens, beside the
editor, what
archec explain <code>says. archec fix <main.arche>: applies the preferred fix of each diagnostic, one fix per place. Then it checks again, and repeats until no fix applies. It prints each fix and the diff. Options:--dry-runshows the fixes and writes nothing;--only unresolved,missing-unitapplies only the fixes for those codes;--vetalso applies the fixes of style findings (the findings ofarchec vet).
- The MCP server (
archec mcp): itsfixtool gives the fixes of each diagnostic as edits, by line and column. So an AI assistant applies the fix instead of guessing it. Withapply: true, the tool does whatarchec fixdoes.
What is fixed#
Some fixes are offered, not applied. These are the fixes that guess what to
write, or that remove something. The editor offers them, and archec fix
leaves them alone. Read such a fix before you choose it.
| Code | The fix |
|---|---|
unresolved (and unknown-porttype) |
A definition, type, interface or other name declared in a file of the project that the model does not include: the message says which file, and the fix adds include "<file>". When several files declare it, each is offered, and none is applied. A name the store has (Pid, Bme280): the fix adds its uses and include. Otherwise the closest name in scope, by edit distance. For a link end, this is a part, or a port of that part. Otherwise a definition, a type, a message or a state. The last choice is to declare the missing name. |
unknown-property |
The closest property of that kind of declaration. Removing the property is offered, not applied. |
property-value |
The closest allowed value: buffer smaple → sample. A name where a text goes is put in quotes. |
missing-unit / bad-unit |
The time unit: 10 → 10ms, 10sec → 10s. |
unknown-unit |
The closest unit of the catalog. Declaring the unit is offered. |
direction |
The port's direction is changed to match what it does: an in port that sends becomes inout. |
link-direction |
The two ends of the link are swapped, when that puts both on the right side. Otherwise the port becomes inout. |
wrong-side |
buffer, depth, overflow and stale-after move from the out port to the one link that leaves it. |
duplicate |
The second one is renamed: cmd → cmd2. |
missing-separator |
A ; is added before a property that is glued to the Python. |
include-not-found |
The file is created, empty. |
naming |
The name is changed to the naming convention, with every use (offered). The editor's rename also renames the uses in Python. archec fix --only naming renames the uses in the model. |
unused |
Removed (offered, not applied). |
no-system, empty-system |
A system with a part of each definition; or a part; or a component and a part of it (offered, not applied). |
requirement-no-text |
text "The system shall …", for you to complete (offered, not applied). |
arche-body |
A Python body that says only what the action language can say is rewritten as a ```arche body. For example self.state == "Ready" → state == Ready, await goto("Auto") → goto Auto, send(self.p, M(f=1)) → send p M { f: 1 }. The fix is refused when the body does more: a list that grows, a library call, a name the model does not have. It is a style finding, so only archec fix --vet or --only arche-body applies it. |
advanced |
level full is added to the project (offered, not applied). |
archec fix never leaves the model worse. A pass of fixes can add errors, for
example a rename that misses a use. When it does, archec tries each fix of that
pass on its own and drops those that add an error.
In plain words#
The beginner level rewrites the common messages in plain words, and lists what exists. Turn it on in one of three ways:
archec check --beginner;- the environment variable
ARCHE_LEVEL=beginner; - the VS Code setting
arche.levelset tobeginner.
With the model of the first fix:
archec check --beginner main.arche
main.arche:14:19 error You used `cdm` but `lamp` has no port called that. Did you mean `cmd`? Its ports are: cmd. [unresolved]
| button.click -> lamp.cdm
| ^^^^^^^^
✗ 1 error(s), 0 warning(s)
1 of them fix themselves: `archec fix main.arche` (`--dry-run` shows how first)
The simple level#
A project can say how much of the language it uses:
project "Pump" {
level simple
}
At level simple, completion offers exactly the 1.0 core of the language
(core.md), its declarations and their properties:
- the project, its libraries and
include; - data, messages and units, requirements;
system,componentandpart, ports, interfaces and links;fn,var,handlerandstates;- test plans, and where it runs: a
deployment, its binaries, threads and chains.
Everything else still reads and builds. A declaration outside the core gets a
hint, advanced. The hint says to set level full to use it.
With no level in the project, the VS Code setting arche.level decides:
beginner is the simple level, and expert (the default) is everything.
Limits#
- A fix that guesses what to write, or that removes something, is never
applied by
archec fix. You choose it in the editor. - The
arche-bodyfix rewrites only a simple Python body. A body with a list, a library call or a name the model does not have stays Python. archec fix --only namingrenames the uses in the model only. The editor's rename also follows the Python.
Every error code#
Each diagnostic code has its page — what it means, how to fix it, and its automatic fix, if any: the error codes, by area.