Import outcome states

Updated Oct 18, 2026

Hecate evaluates every in-scope import edge it finds and records exactly one outcome. An edge is in scope when it lies within the scanned package roots, or when it is external and the configuration puts it there: an external edge is in scope only when include_external_packages is enabled and a configured group claims its prefix. Any other external import is out of scope and receives no outcome at all. A green result therefore means no edge was forbidden and no coverage finding carried error severity, not that in-scope edges were quietly skipped. The states are:

State Meaning
permitted Both endpoints are classified, and the importer group may import the target.
forbidden Both endpoints are classified, and the importer group may not import the target.
exempted Forbidden in principle, but covered by a documented ignore_imports entry.
unclassified At least one endpoint matched no configured group.
unresolved The import target resolved to no known internal module.

permitted and forbidden edges are the normal case. The remaining three are reported in two different places:

  • unclassified and unresolved appear in the coverage section described below, and fail the check only under the conditions given there; and
  • exempted appears in the ignored section, which text output shows only when --show-ignored is passed.

An edge that matches an ignore_imports entry is recorded as exempted, so it is reported as ignored and not as coverage. A documented ignore is therefore the way to accept a known unclassified or unresolved edge without the coverage section reporting it.