How-to guides › Fix common mistakes

How-to guides

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-run shows the fixes and writes nothing;
    • --only unresolved,missing-unit applies only the fixes for those codes;
    • --vet also applies the fixes of style findings (the findings of archec vet).
  • The MCP server (archec mcp): its fix tool gives the fixes of each diagnostic as edits, by line and column. So an AI assistant applies the fix instead of guessing it. With apply: true, the tool does what archec fix does.

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.level set to beginner.

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, component and part, ports, interfaces and links;
  • fn, var, handler and states;
  • 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-body fix 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 naming renames 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.