Domain

Its role

The domain gives meaning to the information collected from a Python project. It knows what a source module, import fact, dependency, and finding represent, and the rules that connect them.

The application supplies collected observations and asks these rules to work on them. The domain performs no file access and imports no graph library. Its graph contracts let an adapter supply the graph operations.

Process flow

Follow the collected sources through domain rules to the final report. The application coordinates these steps; the arrows show the main data flow, rather than parallel execution or every method call. Request and root validation happen before the observations shown here.

The shared snapshot carries sources, import facts, selected dependencies, original resolver dependencies, and external or unresolved imports. Each registered view then receives its own cycle analysis and selected checks. Cycle counts are computed even when no checks are selected.

Recoverable source failures continue as diagnostics alongside the available results. A registered view or check that raises or returns invalid output produces ExtensionError and stops the analysis without a report.

Follow an import

Imagine analysing the demo directory from its parent. Both files contain an ordinary, top-level import.

# demo/orders.py
import inventory

# demo/inventory.py
import orders

1. Give the observations stable identities

   Discovery supplies two SourceModule values. Their IDs become source:demo/orders.py and source:demo/inventory.py. Once the application has aligned paths, FactCanonicalizer turns the two drafts into identified ImportFact values.

2. Match each import to its target

   StaticImportResolver uses known bindings to connect orders to inventory, and back again. Each DependencyEdge keeps the fact ID and resolution kind explaining why that relationship exists.

3. Choose the relationships for analysis

   ArchitectureDependencyPolicy removes redundant package-base evidence where a fact already identifies a probable child. These plain imports keep both edges. The application places selected dependencies, the original resolver output, sources, and facts in one AnalysisSnapshot.

4. Build a view and explain its cycle

   A view turns the snapshot into a ViewGraph. CycleAnalyzer asks the graph contract for cyclic groups, interprets the supporting facts, and selects a witness: inventory → orders → inventory.

5. Turn the observation into a finding

   CycleCheck returns a CheckResult containing an error-level CycleFinding. The application adds the check ID and includes it in the view report.

Views and findings

The default composition includes source and package views for each of three import filters. Source views keep one node per file; package views group those sources after filtering.

PackageView wraps a source strategy. A module belongs to its immediate containing package; an initializer belongs to its own package. Nodes use package:<dotted-name> IDs with disjoint memberships. Parent packages do not duplicate child-package sources. Standalone modules and sources without reliable bindings remain individual source nodes, so the walkthrough's two standalone files retain their cycle in all six views.

An optional max_depth caps the package's dotted name: depth 1 groups acme.orders and acme.inventory under acme; depth 2 keeps them separate. Projection drops dependencies inside a node, merges original evidence between shared endpoints and retains isolated nodes. A package cycle may exist even if no individual source modules form a cycle.

Namespace package sources group without __init__.py. An import of only the namespace container has no source target, so it does not create a graph edge. GraphValidator verifies original evidence and disjoint source memberships for package views and extensions alike.

The snapshot's optional resolved_dependencies preserves resolver evidence removed by module-level dependency selection. Package projection restores exact-base evidence only for the same retained import fact whose probable-child evidence maps to the same target package. This retains certainty without adding an unrelated package relationship. Older snapshots without the extra collection remain supported.

A cycle finding describes one cyclic group and one witness. A group can contain several cycles. “Definite” means it contains a cycle supported by exact resolution; it does not predict a crash when Python executes the project.

UnresolvedImportCheck reports unresolved imports retained by the view, except unmodelled namespace bases. Extensions may return a RuleFinding for other observations. CheckResultValidator checks their shape, source references, and evidence.

Module map

Choose a module to jump to its classes below. Package initialisers are intentionally empty; callers import from the defining modules.

Every class

All 55 classes in this package, including value types, contracts, and internal helpers. Names link to the source file; descriptions match the role summaries in the code.