Référence › Référence du langage › Lint rules

Référence › Référence du langage

Cette page n’est pas encore traduite : voici la version anglaise.

Lint rules

Every problem archec check can report, by area, with its code and severity.

On this page: Style: how the model reads (archec vet) · Parse and files · Names and references · Types, values and units · Ports, links and interfaces · Behaviour: states, actions and tests · Code: TypeScript, Python and code blocks · Requirements and traces · Safety and security · Timing and budgets · Deployment: processors, cores and routes · Containers · Boards, pins and parts · Physics and simulation · CAD: geometry, limits and clearances (archec cad) · FPGA components: what can be synthesised, widths (archec gen --target vhdl), the device and the limits of archec synth · Execution and memory: threads, placements, allocators, buffering · Signal processing: algorithms, composites, metrics, dataflow links · Libraries, generators and what leaves the machine · Views, animations and stories · The product's user interface

Style: how the model reads (archec vet)#

Code Severity What it finds
naming hint A name not in its case (archec vet): PascalCase for definitions, systems and types, snake_case for parts, ports, functions and variables, SCREAMING_CASE for messages, constants and literals; requirement ids upper-case.
bad-place error A canvas line that places something other than a block.
canvas hint A canvas line to write differently (a block placed twice, a size without a place).
arche-body hint A Python body that says only what the action language says (archec vet): written as a ```arche body, archec checks it and translates it to C, Rust and Go. The quick fix converts it.
code-in-model hint A long Python block in a model file (archec vet): it reads better in a .py file beside it.
declaration-set hint A declaration of the Arche app outside app/*.arche (archec vet).
defaults hint A property every requirement of the file gives alike: written once in defaults.
defaults-child warning A declaration inside defaults: a defaults block gives property values only.
duration-math hint Arithmetic on durations that could be written as one value.
empty-system hint A system with no parts yet.
extends hint A definition built on another written in the long form.
long-form hint A long form (archec vet): archec fmt writes the short, standard one, with the same meaning.
no-system hint No system declared: nothing appears on an Arche canvas.
position-twice warning A block placed in its own at and in a canvas.
property-group hint Properties that go together written apart (archec vet): fmt writes their group.
property-order hint Properties out of their order (archec vet): fmt puts them in it.
same-line hint Two items on one line (archec vet): one per line, ; only inside a one-line block.
vague-word warning A requirement that says a word that cannot be verified ("as fast as possible", "TBD").
advanced hint In a project at level simple, a declaration beyond the 1.0 core (docs/core.md: a process, a hazard, the Arche app…): set level full in the project to use it. Completion then offers everything.

Parse and files#

Code Severity What it finds
syntax error The text does not parse.
include-not-found error An include names a file that does not exist.
include-cycle warning Files include each other (each is still loaded once).
schema error Generated YAML that fails the Arche project schema (archec build, archec validate).
alias-keyword warning An old spelling of a keyword or a property (msg, porttype, unit "m/s"), or a word written in its other meaning (mode for a state: mode is for operating modes). The message says what to write: Write \state` (…). Read until 0.12; archec fmt` writes the standard one.
renamed warning / error An old name of a declaration a library renamed (its library.arche says renamed "1.0", { Led: GpioLed }): read as the new name, a warning up to the edition the rename is made for, an error from the next. The quick fix and archec fix write the new name (docs/editions.md).
not-core error With archec check --core only: a declaration or a property outside the 1.0 core (docs/core.md). The message names the extension it belongs to. Extensions keep working; they have no stability promise yet.
old-form warning A second way of writing the same thing: a test case's step blocks (write its timeline: at 0ms do …, at 10ms expect …) or a simulation's stimulus (write at 5ms do …). Read until edition 0.13, an error from it; the quick fix and archec fmt rewrite it exactly, or the message says why it cannot.
emit warning Something the emitter could not write to Arche (an address it could not resolve).
hyphen-minus error A name with a - read as one name where a subtraction was meant: write spaces around -.
include-twice error A part of a body included twice.
missing-separator warning A word read as part of the Python before it: a ; or a new line is missing.
optional-here error optional on a variable or an argument, which always holds a value.
requires-in-body error requires inside a body: it belongs at the top of the file.
unknown-defaults error defaults for a declaration that takes no properties.
edition error A project edition archec cannot read (write edition "0.12"), or newer than this archec knows: update archec.

Names and references#

Code Severity What it finds
duplicate error Two declarations share an id in the same scope.
unresolved error A name does not resolve: type, message, definition, port, function, state, requirement…
unknown-property warning A property the element does not have (with a did-you-mean). It is still emitted.
instance-cycle error A component definition contains an instance of itself.
unknown-porttype warning A port type that is neither built in nor declared.
unused hint A message, type or component definition never referenced.
dangling-ref warning An Arche address written as a string that names nothing of the project.
extends-cycle error A definition that extends itself, directly or not.
extends-instance error extends on a part: only a definition is built on another.
index error An index on a block that is not a repeated part, or out of its range.
interface-cycle error An interface that extends itself.
rule warning A breach of one of the project's rules, or rules that could not be run.
expand-depth error expand with something else than how many calls down it goes (expand 2).
expand-nothing warning expand on a step whose target has no such function, or whose function calls nothing: there is no tree to draw.
calls-not-in-body hint A function that lists calls g while its ```arche body never calls g(): expand draws the body, so the list and the code disagree.
seqstep-not-called warning A step from a component to one inside it that none of its functions lists in its calls: the sequence and the code disagree. Checked only for a component that writes calls.
seqref-cycle error A sequence whose ref comes back to it, directly or through other sequences: it would play forever.
seqref-participant warning A ref to another scenario's sequence whose steps reach components that are not participants of this one.
text-ref warning A [name] in a text that names nothing in the model.
translation warning An entry of a translations block that names nothing, or says again what is written inline.

Types, values and units#

Code Severity What it finds
property-value warning A property value of the wrong shape, or not one of the allowed values.
missing-unit / bad-unit warning A duration written without a time unit, or with a non-time unit.
out-of-range error A value does not fit its integer type, or a named type's range.
type-mismatch / array-length warning A value of the wrong kind for its type, or a list of the wrong length.
pointer-value error A pointer (*T) initialised with something that is not an address: an integer, a constant or nil.
pointer-on-wire warning A pointer in a message payload: an address means nothing in the receiver's memory.
void-value error void used as a value type; only *void (an untyped pointer) holds something.
array-length warning An array value with another number of items than its type says.
bad-unit warning A duration written with a unit that is not a time unit.
flow-unit warning A link between ports in different units: the value crosses unconverted.
missing-unit warning A duration written without its unit.
tolerance warning A tolerance on something with nothing to vary.
type-mismatch warning A value of another type than the one declared.
union warning A union with no cases, or a case named case.
unit-mismatch warning Quantities of different kinds added or compared.
range-reversed warning A range lo..hi (or a force-range) whose lo is above its hi: nothing is in it, and a value saturated by it is wrong.
unknown-unit info A unit not in the units catalog.
generic-args error A generic struct used with the wrong arguments: their number, or a type where a number is expected (N: int) or the reverse. Ring<Sample, 64> for struct Ring<T, N: int>.
native-type warning A type … native that names itself in no language (cpp "ns::T" include "t.h", rust "crate::T"), or a language's name on a type that is not native.
Code Severity What it finds
direction warning sends on an in port, handlers on an out port.
link-direction warning A link from an input port or to an output port.
link-type-mismatch warning The two ends of a link have different port types.
carries-unsent warning A link carries a message its source port does not send.
handler-kind warning A message handler on a port type that answers HTTP (or nothing), or the reverse.
unhandled-message warning A link delivers a message the target port has no handler for.
gpio-payload warning A GPIO port sending several messages or a non-bool message.
contract-unmet warning At a link, what the sending end guarantees does not imply what the receiving end assumes: a range wider than the one assumed, another value, a later deadline, another quantity.
contract-unknown hint An assumption archec cannot decide at a link: nothing guaranteed on the field, units it does not convert, a clause it cannot read.
bad-endpoint error A link end that is neither a port nor a component.
comm-property warning A delivery property (pattern, buffer, depth…) where it means nothing.
delegate-conflict error A delegated port with another type than the port it stands for.
flow-mismatch warning A link carrying one quantity into a port that takes another.
implicit-interface hint An interface used and not declared.
missing-operation warning A port that provides an interface whose operations its component does not implement.
no-reply error A request-reply server port with no handler.
no-subscriber hint A published topic nothing subscribes to.
operation-signature warning An operation implemented with another number of arguments than its interface says.
pattern-mismatch error Two ends of a link with different interaction patterns.
request-direction hint A request-reply client port that is an in.
self-link hint A link from a component to itself.
wire-field error A message field its wire format cannot hold: a struct, array, text or optional; bits outside 1..64; a float in other than 32 or 64 bits without scale; a checksum that is not one unsigned byte at a multiple of 8; a signed or scaled counter.
wire-overlap error Two fields of a message's wire format share a bit of the frame: move one with at.
wire-size error A field of a message's wire format past the frame's size, or a size that is not a whole number of bytes.
wire-range warning A field's range its bits do not carry once scaled (raw × scale + offset), an enum literal that does not fit its bits; as an info, a field cut to fewer bits than its type with no range to say so.
wire-frame warning A message a route puts on a CAN bus is longer than the frame: 8 bytes on classic CAN, 64 on CAN FD.
unprovided-interface warning A link from a port that requires an interface to one that does not provide it.
wrong-side warning A port used from the wrong side of a link (an in as a source, an out as a target).
oneway-result error / warning A oneway operation that gives something back: a result (-> T), an out or inout argument (errors), or raises (a warning: the caller, which does not wait, hears of no exception).
raises-not-exception warning An operation that raises a struct, a type or an enum: what it raises is declared exception E { … }.
param-direction warning An out or inout argument with a default: the operation writes it.
dataflow-source warning A dataflow sink linked to a port that is not a dataflow source, or to a source that streams another type of sample (vector).
dataflow-backpressure warning The two ends of a dataflow link that do not say the same backpressure.
no-service warning A port that calls a service no in port serves.
topic-wired warning A pub-sub port with a topic that is also linked: a topic is matched by its name, not by links.
topic-part warning A part of a topic ({id}) that is not a field of the messages the port carries, or ({id: T}) whose type is not one.

Behaviour: states, actions and tests#

Code Severity What it finds
unreachable-state warning A state no transition reaches from the initial state (initial X, else the first state); entering a composite state starts in its pseudo initial child (else its first), and a transition that never fires leads nowhere.
deadlock-state warning / hint A reachable state with no way out (nor from a state around it) that is not pseudo final: a warning when the machine has a final state (or the state is a pseudo-state), a hint when it has none (a latched fault is often meant). A state every state falls into (* -> Fault) is a safe state; a component whose code calls goto(…) is not checked.
unknown-trigger warning / hint A transition's trigger that is neither a message, nor an event, nor a port or member of its part, nor raised in any code of the model: nothing fires it, so the machine never takes it. A warning when it is close to a name that exists (a typo: on TEMPP for the message TEMP) or when the project declares its events (event dry_run); a hint otherwise. Declare it (event dry_run), or fix the name.
dead-transition warning A transition on a message no input port of the component receives, or with a guard that is false.
shadowed-transition warning A transition an earlier one from the same state, on the same trigger and with no guard, always beats.
nondeterministic hint Two transitions from the same state on the same trigger whose guards are not plainly exclusive (else, not g, x < 0 / x >= 0).
block-not-simulated hint A blocking queue: the simulator keeps the message and marks where the sender would wait, but the sender is not stopped.
test-line error A test case's line in the action language (at 1ms do send probe.water WATER { temperature: 20.0 }, within 50ms expect ctl.state == Idle) that does not check: a part, a variable, a port, a message, a field or a state the model does not have, or a body's statement (wait, goto). Its names are the system's: a part by its path, then one of its variables, its ports or its state.
arche-test-line hint A Python test line that the action language says too (send(p.out, M(a=1)) → send p.out M { a: 1 }, True → true, x.state == "S" → x.state == S): written so, it is checked and in the core. The quick fix, or archec fix, writes it over.
decision-incomplete warning An accepted decision that does not say what was chosen or why.
decision-option warning A decision whose choice is not one of the options weighed.
mode-initial warning Two initial operating modes.
no-step hint A periodic thread with no step: nothing releases it in the simulation.
step-without-period warning A step on a thread with no period.
timeline warning A moment of a test case earlier than the one before it.
action error A body in the action language (```arche) that does not parse or does not type: a name not defined, a value of the wrong type, a port that does not send that message, a state the part does not have. The message says what was expected.
bad-fault error A fault in a test step that names no link end, part or function it can act on.

Code: TypeScript, Python and code blocks#

Code Severity What it finds
no-body warning / info Python calls self.f() (or a handler names f) but f has no body, so Arche cannot run it.
missing-await warning A component function called from Python without await.
not-simulated hint A Python body the action language cannot say (a list comprehension, sorted(…, key=…), try): archec sim and archec test --sim web run it in python3, the editor's Run does not simulate it. Only in a project with a simulation block or a test plan.
code-not-found error A code property names a .ts or .py file that does not exist.
handlers error A handlers property that names no handler language: typescript, python or arche (docs/handlers.md).
handlers-language warning Code in another language than the one Arche runs the project in (simulation.yaml behavioral.language, from the project's handlers): a python block in a TypeScript project, a .ts file in a Python one. `archec sim` runs it; Arche would read it as the project's language. Write it in that language or as arche (translated), or set handlers.
test-typescript warning Test code (a do, an expect, a setup) in a TypeScript project that archec cannot write as TypeScript: Arche runs a project's test code in its language, and archec translates the Python it is written in (and, True, abs, MSG(k=v), if c: …), but not a if c else b, in, //, a def, with, try, f-strings or lambdas. Write it so, or in a ```ts block.
code-language error A body in a block of a language that is not a handler language:ts, python or arche (a bare ``` is the project's language).
ts error / warning TypeScript that does not read (a syntax error, on its line), what has no JavaScript of its own (an enum, a namespace), an import of a module (Arche runs each body on its own: only "arche" and "./arche", the editor's), a top-level let (its value is not kept between calls), or top-level code that never runs.
ts-portable info / warning A TypeScript body outside the portable subset (docs/handlers.md, "Portable TypeScript"): the construct named (an array, a ternary, a method of a value, reply…) or what the action language's check says. The simulators run it; `archec gen --target c
convert-todo warning A statement archec convert-handlers could not translate, kept as a TODO(convert): comment with the original: write it in the new language, then remove the comment.
py-not-found error A code property names a function that no .py or .ts file in scope defines (quick fix: create it).
py-params error A function's parameters are not self and the fn's arguments, or name something Arche does not give that hook (in TypeScript, a message's hook takes self, msg).
py-duplicate error Two .py files in the same scope define the same name.
python error / warning A .py file that cannot be read (unclosed bracket or string), a top-level name changed by a function (the change is lost when the call ends), or top-level code that never runs.
py-shadowed warning A ``` block where the component's .py file also has the def of the same name: the block wins.
py-unused warning A def of a .py file the model does not use (neither named, bound by its name, nor called).
fn-placement hint A function analysed on one thread but simulated on its part's thread.
component-not-self-contained warning A component folder that uses a name declared outside it: copied into another project, it would miss it (requires "…").

Requirements and traces#

Code Severity What it finds
bad-trace-kind error A trace with an unknown relationship kind.
requirement-unverified info No test plan or case verifies the requirement.
requirement-unsatisfied info No element satisfies the requirement.
requirement-no-text / requirement-wording info / hint A requirement without text, or without "shall".
requirement-link warning A link to a requirement written from its far end: satisfied-by or verified-by on the requirement, trace satisfies / trace verifies, or tests in a requirement's verify block. Write it on what satisfies or verifies it: satisfies REQ-1 on the component, part, port or function, verifies REQ-1 on the test case, test plan or scenario. Read until 0.13; the quick fix and archec fmt move it when both ends are in one file, archec refactor move-traces when they are not (a trace with a comment stays: no property says one).
duplicate-trace hint The same trace written twice.
requirement-no-text info A requirement with no text.
requirement-wording hint A requirement text with no "shall": is it a requirement or a note?
suspect warning A link to a requirement reworded since the last baseline: check it still holds, then take a new baseline.
ears error A requirement's ears sentence archec cannot read, or about a part, a state or a message the model does not have. `[while ,] [when
formal error A requirement's formal property archec verify cannot read: a word it does not know, a part with no state machine, a state the part does not have. never brakes in Fault, always …, eventually … [within 50ms], a in X leads to b in Y [within 50ms]; within goes with eventually and leads to only.
req-conflict warning Requirements no implementation can satisfy together (archec verify --conflicts): a minimal set, with the inputs that defeat every choice of states. Read over each part's states (any of them, from the initial one), the messages it receives (one per tick) and time in ticks (the deadlines' common divisor). Change one of them: a wider state, a longer deadline, a while that leaves the other out.

Safety and security#

Code Severity What it finds
asil-inherit warning A requirement that derives from one with an ASIL (a safety goal, a requirement) and has a lower one that is not a decomposition asil "B(D)", or none written (info).
dal-inherit warning A requirement that derives from one with a DO-178C DAL and has a lower one, or none written (info).
asil-decomposition warning Decomposed requirements (asil "B(D)") of one parent that do not add up to its ASIL (ISO 26262-9: D = C+A = B+B = D+QM, C = B+A = C+QM, B = A+A = B+QM), or a decomposition of one requirement alone.
asil-independence warning Two requirements that decompose the same parent and are satisfied by the same element: a decomposition needs independent elements.
asil-allocation warning An element written with a lower ASIL than a requirement it satisfies.
dal-allocation warning An element written with a lower DAL than a requirement it satisfies.
asil-too-low warning A safety goal written with a lower ASIL than its hazard needs (from severity, exposure and controllability).
cal-too-low warning A security goal written with a lower CAL than its threats need.
error-unreached info A hazard whose error … on … no error source reaches: nothing in the model produces it, or it is contained on the way.
fmea-mismatch warning A failure mode whose written causes are not the hazards its error reaches in the error model.
fmea-rpn warning A failure mode with a high RPN that nothing mitigates.
fta-mismatch warning A hazard whose fault tree as written (caused-by, gates) has other minimal cut sets than the one derived from the error model.
gate-cycle error A fault-tree gate that contains itself.
hazard-no-goal warning A hazard with an ASIL and no safety goal answering it.
hazard-target warning A hazard whose rate from its causes is above its target.
stpa-incomplete warning / hint A control action not considered for each of the four types of unsafe control action (nor said not-applicable), one with no controller or process, a UCA with no type; a UCA with no loss scenario (hint).
stpa-no-path warning A control action no link carries from its controller to its process, or feedback no link brings back.
uca-untraced warning An unsafe control action that leads to no hazard (causes) or that no constraint prevents (constraint, a requirement); a loss scenario with no constraint (hint).
mixed-criticality warning Safety levels mixed in one address space, with no freedom from interference.
security-risk warning A threat with a high risk and no treatment.
tara-incomplete warning An attack path whose feasibility is unknown.

Timing and budgets#

Code Severity What it finds
watchdog-timeout error A watchdog with no timeout (an error: when would it run out?) or no on-timeout (a warning: nothing happens). watchdog w { timeout 50ms; on-timeout ```arche … ``` }, restarted by kick w.
budget-on-system info A budget on a system: archec checks it, Arche holds budgets on components.
budget-over warning What the parts beneath draw adds up to more than the budget.
budget-unit warning A draw in another unit than its budget: it is not counted (nothing is converted).
bus-load warning A bus loaded above 70 %: arbitration delays grow fast.
chain-gap warning A latency chain with two steps no link joins.
chain-incomplete hint A latency chain whose duration cannot be bounded (a step with no known cost).
deadline warning A thread whose worst-case response time is above its deadline.
deadline-handler warning An on-deadline with no deadline (it never runs), or a transition's deadline with no on-deadline (past it, the transition is only dropped). A port or a transition with both: a trigger the part starts on later than the deadline after it was sent runs on-deadline instead.
e2e-budget warning A latency chain longer than its budget.
handler-blocking warning A thread that can miss its deadline because a message handler runs first.
memory-budget warning Processes that may use more memory than their processor has.
missing-wcet hint A periodic thread whose cost is unknown (no wcet): the timing analysis leaves it out.
overload error A core loaded above 100 %.
unbounded-queue hint A queue with no size on a thread of a deployment.

Deployment: processors, cores and routes#

Code Severity What it finds
allocation-target warning Something allocated to an element that is not a component.
memory-overlap warning Two memory blocks of a component overlap in the address space.
memory-misaligned warning A memory block of 2-, 4- or 8-byte elements at an address that is not a multiple of its element: a bus reads or writes it in two accesses, not at once.
memory-field-width warning A field of a memory block past the bits of one element (bits "15:8" in a uint8 block), wider than its type holds, or with bits that do not read as "hi:lo".
memory-field-overlap warning Two fields of a memory block share a bit.
bus-address error Two devices with the same address on one I²C bus (a board's port, or a bus component): they would both answer.
binary-target error A binary that runs on no processor (on …).
simulation-only warning A deployment that puts a simulation-only part (its Python runs only in simulation) on a microcontroller: `archec gen --target c
bus-unreachable error A route over a bus a processor is not linked to.
core-override hint A thread placed on a core outside its process: Arche pins a process to one core.
deployment-choice warning Several deployments and none named: the Arche project gets the first.
deployment-system error A deployment that does not say which system it places (system …).
double-allocation error A part or a function on two threads.
no-route error A link between two processors with no route over a bus.
not-a-processor warning A binary placed on a component with no cores.
route-bus error A route with no bus (over …), or over a component that is not one.
route-link warning A route for a link that does not exist.
route-local hint A route for a link whose two ends run on one processor.
rtos-process hint A process on an RTOS: one address space, so its threads are tasks.
runs-target error A thread that runs something other than a part or a function.
unallocated warning A part with behaviour that runs on no thread of the deployment.
unknown-core error A thread placed on a core its processor does not have.
unpinned hint A thread or a process with no core.

Containers#

Code Severity What it finds
container-binary-on error A binary inside a container that also says on: it runs on the container's processor.
container-cpuset error A thread of a container placed on a core outside the container's core list (its cpuset).
container-can warning A container whose link goes over a CAN bus without network host: a SocketCAN interface is a network interface, not a device.
container-device warning A container whose link goes over a bus other than CAN (a serial line…) while it sees no host device (device "/dev/…").
container-empty warning A container that runs no binary of the model.
container-host error A container on a processor that is not Linux, or has no container runtime.
container-image warning A container that names no image after its id.
container-network error A link leaving a container that has network none.
container-rt warning A policy fifo / rr thread in a container without capabilities sys_nice.

Boards, pins and parts#

Code Severity What it finds
implicit-catalog warning A kind, layer or tag used without being declared: declare it (it is added to its catalog as is; the quick fix declares it).
board-pin warning A pin in pins { … } on a board (or a part of one) that its chip does not name so, or a role archec does not read; the nearest pin is offered as a fix.
pin-function warning A pin the board cannot use for that role: against its pinout (I²C SDA on a pin with no SDA, a PWM output on a pin with no timer, an analog input on a pin with no ADC, one port's pins on two peripherals); and the RP2040's fixed functions (UART TX on GPIO 0, 4, 8…), an ESP32's input-only pins (34–39) as an output, a pin wired to the module's flash.
pin-conflict warning One pin used by two ports of a board (those the system links, or whose pins a part writes; a Linux header pin's port and the bus on it), or by two roles of one port; or a one-pin port (a header pin, a LED) linked to two parts.
pin-pair warning A link whose ends' pins do not pair: a tx with no rx at the other end (SPI and I2C: the same role), or a CAN controller on a bus with only one of tx and rx.
pin-level warning A link between two ports whose pins { level … } differ (3.3V and 5V), a board's io-level being its ports' level: a level shifter goes between them.
board-peripheral warning Two ports on one peripheral of a board (both on I2C1, two servos on the PWM0 channel), or more ports of a kind than the board has (a 5th I²C on a board with 4, a 3rd PWM output on one with 2): its peripherals and pinout say what it has.
board-supply warning A part powered from a board's rail whose voltage it does not take (voltage on both power ports: a 3.3 V sensor on the 5 V rail, a 5 V sonar on the 3.3 V one); the quick fix links it to the rail that fits.
board-current warning The parts powered from one rail draw more than it gives (current on the rail and on each part's power port, or a part's power over the rail's voltage): the Pico's 3V3(OUT) gives 300 mA.
part-lifecycle warning A part number at its end of life, or not recommended for new designs, as the last archec parts found (.arche/parts-cache.json, with its date): find a replacement. Only when the cache exists; archec check never looks it up.
part-stock warning A part number none of which is in stock, or that the distributor does not know, as the last archec parts found.

Physics and simulation#

Code Severity What it finds
equation error An equation not written der(x) = … or y = …, or a name in it the component does not have.
physical-balance error A part with physical ports whose equations are not as many as its unknowns: one per variable without a value (and per state), per potential of each port, per out signal; a port's flow comes from its links. A var with a value and no der is a parameter.
physical-structure error A physical network that cannot be sorted: fewer equations than unknowns (under-determined: a missing equation, a port not linked), more (over-determined), or as many but not one for each — states tied by an equation (two capacitors in parallel, a voltage source across a capacitor, two masses joined rigidly), a higher-index system archec does not reduce: put a resistor, a spring or a damper between them.
physical-link error A link that joins a physical port to a port of another type, or to a port that is not physical.
physical-value error A parameter of a physical part whose value is not a number archec can work out.
fit-no-influence warning archec fit: a parameter the measured signals do not change (its column of the Jacobian is zero). It is left at its value: fit it with a signal it moves, or leave it out of --params.
fit-correlated warning archec fit: two parameters that change the signals in the same way (correlation above 0.999, or a singular JᵀJ). The data cannot tell them apart, so their values are poorly known: measure a signal that separates them, or fix one.
body error A part's shape or joint that does not read: shape box 0.1m, 0.1m, 0.4m at 0, 0, -0.2m (box, sphere, capsule, cylinder), joint hinge y at 0, 0, 1m rot z 90deg range -1.5..1.5 = 0.3 (hinge, slide, ball, free, fixed; rot roll, pitch, yaw or an axis and an angle).
realism-port warning How a sensor reads (noise, resolution) said where no sensor reads — on an in port that provides no interface, or on a part that is not kind sensor — or how an actuator acts (gain, lag, force-range) where no actuator acts: on an out port, or a part that is not kind actuator. It does nothing there.
keyframe-name error A line of a keyframe that names nothing it can set: write part.variable = value, part.joint = value (a part on a hinge or a slide) or actuator.port = value (the in port of a kind actuator part).
body-unmapped warning In a system whose parts say their shape or joint, a part archec gen --target mujoco cannot place: a mass with no shape (a 0.1 m box is assumed), a joint on a part with no mass or shape, a sensor MuJoCo has no model of, a sensor or an actuator with no hinge or slide to measure or drive, an actuator nothing commands.

CAD: geometry, limits and clearances (archec cad)#

Code Severity What it finds
cad-file error A cad that names no Python file that is there, or a material or density that cannot be read.
cad-limit error A limit on a geometry that cannot be read: no such component, no cad on it, no material for a mass, or a bound in the wrong kind of unit.
cad-clearance error A clearance that cannot be read: a part that is not there or has no geometry, or a bound that is not a length.
cad-place error A part placed (at box.mount) on a part that is not there, that has no geometry, or that has no such anchor.
cad-limit-over warning What archec cad measured of a geometry does not keep a limit of a requirement.
cad-clearance-short warning Two placed parts are nearer than a clearance asks, or run into each other.
cad-fit error A fits that cannot be read: a part that is not there or has no geometry, a board that says no mounting hole (pcb, or hole lines), a board that does not sit on the part that holds it.
cad-fit-off warning A standoff the box gives a board is not under one of its mounting holes, within the tolerance of fits.
cad-board error A board's pcb that names no KiCad board that is there or has no outline, or an outline or a hole that cannot be read.
cad-board-read warning Something of a board's mechanics is read with a doubt: a hole outside the outline, a mounting hole with no drilled pad, an arc of an old KiCad file.
cad-outline-differs warning A board's geometry (cad) is not the size its outline says (its pcb, or outline).
cad-sourced error A sourced that names no system.
cad-unsourced warning A requirement asks that a system is sourced, and a bought part of it has no part number.
cad-sourcing info A bought part, in a system whose parts have a geometry, has no part number (product { part-number "…" }): it cannot be ordered.
cad-erc warning KiCad's electrical rules check (kicad-cli sch erc) found violations in the schematic beside a board's pcb, when archec cad last ran it.
cad-drc warning KiCad's design rules check (kicad-cli pcb drc) found violations in a board's pcb, when archec cad last ran it.
cad-mass-differs warning A part says a mass that is not the one measured of its geometry (by more than 1 %): the measured mass is the one the physics and the budget use.
cad-shape-differs warning A part says a shape whose size is not that of its built geometry (by more than 2 %, and 1 mm): the geometry is the one drawn and simulated.
cad-stale info A geometry's file changed since archec cad built it: its measures are of the old file.
cad-not-built info A geometry archec cad has not built yet: nothing is measured.

FPGA components: what can be synthesised, widths (archec gen --target vhdl), the device and the limits of archec synth#

Code Severity What it finds
fpga-synthesis error In an FPGA component (one with clock clk 100MHz): something hardware cannot be made of — a floating-point type, a string, a duration as a value, an array with no size, a while loop or a for whose bounds are not constants, a call to another part's function, a Python or TypeScript body, a wait outside fn main. The message says what to write instead (docs/fpga.md).
fpga-recursion error In an FPGA component: a function that calls itself (directly or through another), or one called from an on-enter or on-exit that changes state. Hardware has no stack: write the loop it stands for.
fpga-width warning In an FPGA component: an assignment whose value was declared wider than what takes it (a uint16 into a uint8): the top bits are lost. Widen the target, or keep the bits you want with a mask.
fpga-cdc error A link between two FPGA parts on different clocks. A bool signal goes through two flip-flops of the reader's clock and a message through a handshake: archec writes both. A signal of several bits is an error: its bits do not change at one instant for another clock — send it as a message. A bool into a slower clock is a warning: a pulse shorter than a cycle of that clock can be missed (docs/fpga.md).
fpga-overflow warning In an FPGA component: overflow drop-oldest or overflow block on a message port. Hardware here does one thing with a full port: a message sent to it is dropped (and the test run says so), or the top of fn main waits for room. Give the port a depth, or send from fn main (docs/fpga.md).
fpga-divide warning In an FPGA component: a division or a remainder by anything but a constant power of two. It is synthesised, as a large and slow circuit that must settle within one cycle.
fpga-loop warning In an FPGA component: a loop of thousands of turns (each turn is a copy of its body), or a return from inside a loop, which some tools do not synthesise.
synth-limit error A limit on what synthesis measures (limit Pwm.luts <= 500, limit Pwm.fmax >= 100MHz) that cannot be read: its name is not an FPGA component or a system with FPGA parts, or its bound is not a whole number of cells (luts, ffs, bram, dsp) or a frequency (fmax).
synth-device warning The chip of a kind fpga part is not a device archec synth can build for: it knows the iCE40 (iCE40UP5K-SG48) and the ECP5 (LFE5U-25F-6BG381) families.
fpga-clock error An FPGA component's clock that cannot be read (clock clk 100MHz: a name, then a frequency above zero) — or, as a warning, a cycle that is not a whole number of nanoseconds: the simulator and the testbench round it.
fpga-reset error An FPGA component's reset that cannot be read: a name, then active high or active low, and sync or async.
fpga-step error An FPGA component's step that names no function of the component, or one that takes parameters: it is called on every cycle, with nothing.

Execution and memory: threads, placements, allocators, buffering#

Code Severity What it finds
exec-no-thread error A part placed execution active that no thread runs: an active part needs a thread (its queue and its executor).
exec-conflict error A part said passive or protected that a thread runs (it is active), or placed in another process than the thread that runs it; on a port, an execution (a warning: a port has none of its own).
runs-port error A thread that runs an out port: a thread runs the messages a port receives.
affinity-core warning A thread whose core is not among the cores of its affinity.
alloc-size warning An allocator with no block-size: what it holds, and what it overflows, are unknown.
alloc-memory error An allocator in a memory of another processor that is not shared.
alloc-local-mapped error An allocator in a local memory (not shared) that is mapped: a local memory is not mapped into other processes.
alloc-overflow error An allocator too small for what is in it: a child allocator (blocks × block-size, aligned) larger than one block of its parent, children that need more than a one-block parent has, more children or uses than it has blocks, a buffer or a working memory larger than its blocks, allocators that need more than their memory's size; or an allocator inside itself through its parents.
alloc-other-process error A part (or a port's buffering) that takes memory from an allocator of another process or binary; a binary's allocator not shared used from one of its processes (a warning).
memory-role warning A `memory saved
buffering-share-destroy error A dataflow port's buffering that shares its buffer (transfer share) and frees it once sent (destroy after-transfer): the consumers would read freed memory.
buffering-reuse error build reuse on an input, without the input it reuses, or naming one that is not an input of the part.
buffering-port warning buffering on a place of a part: it is a port's, place the port.
Code Severity What it finds
algo-stereotype warning A stereotype on a component that is not kind algorithm, an instance's stereotype (disable-thresholds, bypass-config-threading) on a definition or an algorithm's on a part, a splitter without one input and several outputs, a joiner without several inputs and one output.
algo-parameter warning A `parameter configuration
algo-composite warning A part of a composite algorithm that is not an algorithm.
algo-execute hint An algorithm with nothing to run: no fn execute, no input that reacts, no state machine.
algo-precedence error Parts of a composite that run after each other in a circle, or one after itself.
metric-no-producer warning An input that reads a metric on a topic filter (/chain/*/SNR) that no part publishes on.

Libraries, generators and what leaves the machine#

Code Severity What it finds
gen-stranded warning Your code in a USER CODE region of generated/ belongs to an element the model no longer has: it was renamed or removed without the rename tool, so archec gen will stop and ask where it goes (--move a=b, or --orphans ok). The editor's Rename and archec refactor rename record a rename in arche.renames.json and carry the code by themselves.
generator error A generator says what it is in more than one way (or in none: templates, script or command), names a folder or a file that does not exist, starts from a generator that does not exist (or goes round), asks for a version of the generator model this archec does not give, names in builtins or after something that is not a target, or is a hook (after) of templates. The same for an importer and an exporter (docs/plugins.md): an importer is a script or a command, without extensions it runs only by --importer (a warning), and neither has after.
generator-option warning A generator (an importer, an exporter, or a binary's or a process's options <generator> { … }) sets an option that it, or the one it starts from, does not declare (a warning); or a value of the wrong type, not among the option's values, or a default that does not fit its own type (errors).
egress error A project allow or deny that names no service (claude, local-ai, store, polarion, parts, issues, libraries, sigstore, github, or all), a URL without its scheme, a second ai, or a private that is not a "glob" (docs/ai-engineering.md).
library-archec error A library that needs another archec version.
library-changed warning A library whose files changed under the version arche.lock recorded.
library-conflict error Two versions of one library asked for.
library-lock warning A library not in arche.lock, or not in the version it names.
library-trust error A package from the Arche Store that the project's trust does not accept: trust verified takes only verified publishers, trust reviewed also reviewed packages.
library-sigstore error A package from the Arche Store taken without a Sigstore bundle cosign verified, in a project whose trust asks for one (trust reviewed, sigstore): archec add it again where cosign is installed.
library-yanked warning A package from the Arche Store its publisher yanked (archec store outdated records it): archec add takes a newer version.
library-missing error A library the project uses that is in none of its libraries folders.
library-version error A version range that is not one, or that no version of the library is in.
shelf-suggest hint Something written by hand that a shelf of the store already has: a function that looks like a PID, a debounce or a CRC (arche-algorithms), a message whose fields are a Vec3 or a GeoPoint (arche-types), a component named as a store device. The editor shows it at the beginner level (arche.suggestions); its quick fix adds the uses and the include, and replaces a message or a struct when its fields are the very same. archec suggest lists them all.

Views, animations and stories#

Code Severity What it finds
animation-template error An animation names a template Arche does not have (archec animation list shows them), or has neither a template nor code "x.html".
animation-code error An animation's code names an HTML file that does not exist (relative to the file the animation is written in).
animation-data warning An animation gives its template data it does not read, of the wrong shape (a word where a number is wanted, a field its records do not have), a path that names nothing, or a formula over names that are not constants or parameters. Each key, its shape and its sample: archec animation show <template>.
animation-binding error / warning An animation's machine or scenario names nothing (or a component with no state machine, a scenario with no sequence) — an error; or its template draws nothing from it — a warning: states and lifecycle draw a state machine, sequence plays a scenario.
animation-param warning An animation's params names something that is not a constant or parameter, or its own drawing (code) reads a parameter params does not send — it would arrive undefined.
animation-library info This build of archec has no animation library (vendor/animations.js): templates are not checked and drawings are not written.
animation-visual warning A story step animates something that is not a visual or an animation of the project.
latex-unbalanced warning Unbalanced $ or braces in LaTeX math.
bad-color warning A color literal that is not #rgb / #rrggbb.
view-empty warning A term of a view's query (include, exclude) that matches nothing in its system, or a view that shows nothing: a block renamed or moved, a kind or tag no block has.
view-query error A term of a view's query that cannot be read: *, a path (adcu, adcu.*, adcu.**), kind k, tag t, layer l, or a -> b / a <-> b with those; depth a whole number.

The product's user interface#

Code Severity What it finds
ui-structure error / warning A ui that does not hold together: a word that is not one of a screen (guage), two screens or elements of one name, an element outside a screen, a display that is not WxH, an initial that is not a screen, a gauge or a telltale with nothing to show, a color that is not one. docs/ui.md.
ui-binding error / warning What a ui element is bound to, or what its action does, that does not hold: a name the ui does not see (its part's variables, port.MESSAGE.field, state, part.state, part.variable, constants), a value of the wrong type for the element (a gauge, bar, slider or stepper shows a number, a toggle a bool, enabled and visible take a condition), a unit other than the element's or its range's, a send of a message the port does not send or with arguments its fields do not take, a goto to no screen, a variable of another part set. The message says what was expected.
ui-dead-press warning / hint A press that reaches nothing: it sends on a port with no link, or to a part whose port does not receive that message (no receives, handler or transition on it); as a hint, a button with no on press.
ui-test error / warning A ui step of a test case that does not hold: press, long-press, release or change on a name that is no element of a ui (a part with no ui, an element the ui does not have), change on an element that is not a toggle, slider, select, input or stepper or without a value, an expectation that reads what an element does not show (hmi.engage.colour: text, label, value, display, enabled, visible, on, shown, options) or an element with nothing after it; as a warning, a press on an element with no on press. Ui steps run on the browser simulator (archec test). docs/ui.md#testing-a-ui.
ui-unreachable warning A screen no goto reaches from the one the ui starts on, or a screen (not the start) with no way out — no back, no goto from it or from an overlay. A dialog the model opens (dialog X when <condition>) is reached from every screen.
ui-safety warning / hint A safety-relevant message — on a port a hazard's error … on names, said in a hazard's or a safety goal's text, or tagged safety — shown on some screens only, not in an overlay nor by a telltale: on the other screens nobody sees it. As a hint, one the ui's part receives and never shows. And a dialog a safety condition opens (dialog X when bus.BRAKE_FAULT — a safety-relevant message, what a telltale in an overlay reads, the state of a part tagged safety or with an ASIL) whose button leaves it while the condition holds: enabled not bus.BRAKE_FAULT on it keeps the dialog up until the condition clears.
ui-fit warning A screen whose content needs more than the display (an estimate: the elements' usual sizes, the gaps), a text wider than the display, a touch target under 9 mm at the display's dpi, or a fits none of whose layouts fits the display.
ui-bound error / warning / hint A for whose list can hold more items than its max (Fault[9] with max 8: the last ones are never shown; the quick fix draws them all), a for with no max or a max that is not a whole number of 1 or more (errors: an embedded display has no heap to spare, so the model says how many rows a screen holds); as a hint, a list with no declared length. docs/ui.md.
ui-a11y warning / hint Contrast under WCAG AA — the theme's text on its backgrounds and buttons (4.5:1), a colored text (4.5:1) or a colored telltale, gauge or bar (3:1) on the background — a button with no text nor icon, a telltale that says it by its color alone; as a hint, an image with no alt.
ui-text warning A text of the ui not translated into a language the project's other texts are ("…" en "…", or a translations entry).

archec explain <code> says more about one code, and archec explain <area> lists the codes of an area.