Reading diagnostics

Updated Oct 18, 2026

A violation has this shape:

HEC001: sample.domain.model:1 imports forbidden module sample.adapters.db (domain -> adapter)

The fields are:

  • rule identifier;
  • importing module and source line;
  • imported module;
  • importing group and imported group.

Exit code 0 means the package passed, including runs whose only findings are warnings. Exit code 1 means Hecate found architecture violations, or a finding at error severity such as an unclassified module under unclassified_modules = "error". Exit code 2 means configuration, command-line input, or package-root validation failed. 2 also covers a scanned source file that Hecate could not read or parse: the file and the reason are reported on standard error, so a broken checkout is never mistaken for an architecture finding.

Configuration validation also rejects a prefix in a later group when an earlier group's equal or broader prefix already claims it. The diagnostic names both groups and prefixes and exits with code 2. Move a narrower exception group before the broader group, remove a dead prefix, or correct the group that should own the prefix. Equal prefixes cannot be fixed by reordering; remove the duplicate from one group.