ECS for Control: check-ecs

Manual page for check-ecs, the checker: a built program against the check-points of the review guide, the findings under their identifiers.

Name

check-ecs – check an ECS program against the review guide's check-points: the findings by identifier and reading, with the position in the sources

Synopsis

check-ecs program-dir [--checks ids] [--allow-lists file]

Description

check-ecs reads a program written to the architecture of ECS for Control: Concepts and checks it against the check-points of ECS for Control: Review Guide, those the guide marks as tool-checked. It prints one line per finding, the check-point and the reading it is read under first, and ends with a summary. It reads the sources and the build products alone, never an ECS file.

The check runs in two stations. Station 0 is the extract: the program is read as extract-ecs reads it, as a built program, every module by its kind declaration, every kind for what it establishes, and every finding of that reading is the extract's (Station 0, below). The check layer then runs every check-point the guide allots to check-ecs beyond the extract over what station 0 read, against the import allow-lists (The Check Layer, below). The two tools divide the guide between them: extract-ecs is station 0, check-ecs is station 0 and the check layer. The program's label is the program directory's name.

Options

--checks ids: Run the named check-points only, a comma-separated list of identifiers, SYSTEM.7 or SCHEDULE/CONS.1, and sections, SYSTEM, PROGRAM or SCHEDULE/CONS, each section standing for every check-point under it. A name that is neither is an error. A named check-point that has no function, because the reviewer reads it or station 0 does, is listed as such. Without --checks every check-point runs.
--allow-lists file: Read the imports against file, a project's own copy of the allow-lists file, instead of the library's file in ref/ beside the programs. The file's name and its head line's edition appear in the report's first line (The Allow-Lists File, below).

Station 0

The program is read as a built program, exactly as the extract-ecs manual page describes under The Built Program and The Kind Declaration: the linker's map file is the module list, the build is verified by its own products, and every module declares its kind in its text. A program that is not built as it stands, or a kind declaration that cannot be read, is refused as extract-ecs refuses it, with every failure listed, and nothing further runs.

What the extract reads is reported here under the identifiers of the guide, in the extract's form: the roles and their sort, the placement by directory, the pair checks between kinds, the singletons, the tokens and surfaces, the manifests, the crossings. These findings are the same lines extract-ecs prints, and a violation among them counts in the verdict as a violation of the check layer does. The check layer runs over the extract whatever station 0 found; a check-point that needs what a finding withheld passes over the module.

The Check Layer

The check layer holds every reading the review guide allots to check-ecs: the kinds' numbered check-points, the exports and the imports of every kind, the pairs of kinds and the program-wide checks over the manifests, the schedules and the crossings. Each check-point is a function over the extract; the guide's identifier is the function's name in the report, and the guide's wording is what it reads. Which check-points these are is said under every check-point of the guide, in its status line, so that a reader of a finding goes from the identifier to the guide's entry and finds there what was read and why it matters.

The imports are read against the allow-lists file, the library's statement of which kinds each kind may import and with which qualifier; a program module of a kind the importer's group does not name is a finding, and every library module is recorded by the extract and never a finding. The file is the subject of The Allow-Lists File, below.

The Report

The report goes to standard output. It opens with the program's label, its counts, the allow-lists file read, and the date and time of the check with the tool's version, so that a series of reports is traced over time; then station 0's result, then the check layer's size and its findings, then the summary:

check-ecs: EcsControlSchedule-v29: 56 modules, 2 schedules, 5 partitions; allow-lists: imports.ecs -- lib/v3.2, 2026-10-28; checked 2026-11-02 16:40 check-ecs 1.0
station 0, the extract: clean
check layer: 80 check-points, 94 readings
  SYSTEM.I-a  PrintPartition/PrintClipSystem.mod:18: SYSTEM PrintClipSystem imports ObservationPorts (SPORT): not in SYSTEM's list
check-ecs: EcsControlSchedule-v29: 79 passed, 1 with findings, 1 violation

Each finding is one line: the identifier of the check-point and the reading, as the review guide cites them, then the file and the line it concerns, then the finding; the findings of one block are aligned on the identifier. Station 0's findings, when there are any, stand under their own count line in the same form. An observation ends in (observation); it is a reading the reviewer should see that withholds nothing. The summary counts the check-points that passed and those with findings, then the violations and the observations; the check-points that passed are counted, not listed.

The exit code is the verdict: 0 when no violation was found, observations never blocking; 1 when a violation was found, station 0's or the check layer's; 2 when the program was refused or the run was in error, a program not built as it stands, a declaration that cannot be read, an unknown name under --checks, an allow-lists file missing or mis-defined, or a path that is not a program directory.

The Allow-Lists File

The imports are read against the allow-lists file, ref/imports.ecs beside the example programs, next to the reference implementations, the library's file: one group per kind listing the kinds a module of that kind may import and the framework modules it may import by name, each entry with a qualifier where the kind's placement restricts it. --allow-lists names a project's own copy, in the same notation; its head line names the library edition the copy derives from, and the report's first line shows the file's name and that edition. A file that cannot be loaded, missing or mis-defined, is an error listed before anything is read, with every error of the file at once.

What It Does Not Do

It does not read an ECS file: the program is read from its sources, and what extract-ecs would write is read here for the check. The two agree because they are one reading.
It does not compile, link or build: a stale build is refused, never repaired.
It does not hold every check-point: the ones the guide marks as the reviewer's are read by hand, and a named one is listed as such under --checks.
It does not edit a source, a build product or a file. It writes the report and nothing else.
It does not rank or filter: every finding of every check-point run is printed, the reviewer weighs them against the guide's entries.

Examples

The examples are run in the program directory and write the tool by its name; how the name is run, python -m check-ecs with PYTHONPATH set or the path to the script, is the subject of Running the Python Tools. The ECS tools live beside the example programs, in examples/v3.2/rpi/pico2/EcsControlSchedule/ecs-tools/, not in the repository's tools/ directory; a PYTHONPATH that names tools/ is extended by that directory for the module form.

Check the program against every check-point:

check-ecs .

Run the SYSTEM section and one program-wide check-point:

check-ecs . --checks SYSTEM,PROGRAM.4

Check under a project's own allow-lists file:

check-ecs . --allow-lists project-imports.ecs