Application

Its role

The application turns a caller's choices into an organised analysis run. Its incoming port is ProjectAnalyzer.analyse(request); AnalyseProject implements that workflow.

Filesystem access, parsing, and graph-library operations arrive through injected collaborators. The application itself performs no external I/O. This allows the same workflow to run with real adapters or in-memory substitutes.

Follow a request

A caller supplies demo as the source root, its parent as the base directory, and the default analysis options.

# demo/orders.py
import inventory

# demo/inventory.py
import orders

1. Validate and locate

   OptionValidator checks the request and options. ProjectAccess then locates the roots and base directory. Invalid requests stop before source discovery or metadata access.

2. Collect a catalogue

   SourceCatalogBuilder asks SourceDiscovery for sources and ImportFactSource for drafts. It applies shared report paths and source IDs, reconciles bindings across roots, and asks the domain canonicaliser to assign fact IDs. The result is one SourceCatalog.

3. Resolve and assess scope

   AnalyseProject combines discovered and configured targets, calls the import resolver, and gathers coverage diagnostics. LayoutDiagnosticService uses project observations to flag questionable root choices without changing the selected roots.

4. Run registered views and checks

   The use case builds an AnalysisSnapshot. StrategyEngine normalises it, builds and validates each registered view, prepares its cycle analysis, and runs its selected checks. It attaches check IDs to findings, converts requested dependencies into readable ReportDependency values, and creates a ViewReport for each view.

5. Return the assembled report

   The domain coverage policy determines completeness. AnalyseProject combines sources, coverage, and all view reports in an AnalysisReport. The configured analyser can be reused; each run keeps its observations separate.

Reports and failures

For the example, report.status is complete, while every built-in view contains a cycle error finding. The default gate is structural, and report.selected_view gives convenient access to that view's report.

AnalysisOptions.package_max_depth is an optional positive integer. The application validates it before project access, then configures immutable package strategies for that run. A supplied value overrides their constructor depth; omission keeps that configuration. Reusing the analyser does not retain a previous request's override.

StrategyRegistry names the available views and checks and selects checks per view. Custom strategies use the same workflow and result validation. An empty check selection leaves coverage requirements in place; cycle counts are still computed for the view.

The default registry includes three source views and their three package counterparts. ViewRegistration.report_dependencies defaults to false and is enabled for the package views. Their ViewReport.dependencies contains every inter-node relationship, even outside cycles, with original source endpoints, locations, statements and resolution kinds. The field is None when not requested and an empty tuple when requested but the graph has no dependencies. It is independent of cycle detail and selected checks.

The application returns Python values. The CLI adapter is responsible for JSON presentation and exit codes. Changing the gate selects which findings determine the CLI result; it does not reduce the coverage requirements.

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 28 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.