Quality metrics

This page is the single source of truth for dpone code-quality metrics. It contains the current generated snapshot, interpretation rules, CI gates and update commands.

Current quality summary

🟢 GREEN - architecture and code-quality gates are currently passing.

The latest release gate moved the quality dashboard from warning to green: generic reconciliation/API/type facades are protected by import rules, broad facades are lazy/delegating, module-size debt is closed, and architecture fitness now passes the strict avg_clustering <= 0.18 gate. The remaining work is continuous improvement, not a release blocker.

Current gate snapshot: - architecture_fitness: OK, avg_clustering = 0.177, cross_layer_ratio = 0.347. - module_size: OK, warn threshold 450 LOC, fail threshold 600 LOC, allowlisted debt 0. - layer_metrics: OK, intra_ratio = 0.653, cross_ratio = 0.347, baseline trend improving. - quality_metrics: generated quality dashboard is current.

Traffic-light interpretation: - 🟢 GREEN: no module-size failures, no import-rule violations, clustering is within target, and generated docs are current. - 🟡 YELLOW: no critical blocker, but there is allowlisted size/coupling debt or a metric near threshold. - 🔴 RED: forbidden imports, new non-allowlisted modules above max LOC, stale generated docs, or a worsening layer-metrics regression.

First recommendations: - Keep newly touched modules comfortably below 450 LOC where practical, even though the hard failure threshold is 600 LOC. - Keep command/runtime code behind service/protocol facades; do not import vendor adapters from generic core. - Watch avg_clustering and local clustering diagnostics before large feature work, because this is now the tightest architectural metric. - Treat broad facades as compatibility shims only: lazy re-export/delegation is acceptable, business logic is not.

Current generated snapshot

This section is auto-generated by dpone docs update-dev-metrics.

Quality summary

• Traffic light: 🟢 excellent
• Biggest module: 450 LOC (src/dpone/readiness/schema_evolution.py) → OK
• Avg clustering: 0.178 → OK
• Cross-layer ratio: 0.342 → OK
• First improvement target: keep broad service/command seams thin before adding new runtime features.

LOC (lines of code)

Repository-wide (**/*.py)

• Files: 1235
• Total lines: 154267
• Total SLOC: 129493
• Min: 0 (src/dpone/adapters/__init__.py)
• Max: 1843 (tests/test_operations_maturity_services.py)
• Avg: 124.91
• Median: 87

Repository-wide without tests (**/*.py, excluding tests/)

• Files: 982
• Total lines: 113300
• Total SLOC: 95593
• Max: 1043 (tools/type_matrix_certification.py)
• Avg: 115.38
• Median: 80

Top 15 largest modules in src/dpone/

Module	Lines
src/dpone/readiness/schema_evolution.py	450
src/dpone/runtime/sinks/clickhouse_impl.py	447
src/dpone/runtime/sinks/strategies/postgres/postgres_increment_merge.py	446
src/dpone/runtime/normalization/normalizer.py	443
src/dpone/readiness/nested_certification.py	442
src/dpone/runtime/connectors/api/connector.py	436
src/dpone/runtime/reconciliation/bigquery/store.py	434
src/dpone/integration_matrix_models.py	433
src/dpone/runtime/connectors/api/mindbox.py	431
src/dpone/runtime/connectors/api/omnidesk_connector.py	431
src/dpone/runtime/etl/processor.py	430
src/dpone/runtime/etl_logging/etl_logger.py	429
src/dpone/runtime/bootstrap.py	425
src/dpone/runtime/sinks/strategies/postgres/file_export_loader.py	423
src/dpone/dag/load_config_builder.py	422

Coupling / Cohesion (internal imports inside dpone.*)

• Modules: 958
• Internal import edges: 2143
• AVG Ce (fan-out): 2.24
• Median Ce: 1
• P90 Ce: 5
• P95 Ce: 7
• MAX Ce: 20 (dpone.commands.registry_core)
• MAX Ca (fan-in): 71 (dpone.app.context)
• LCC ratio (largest connected component): 0.930
• Avg clustering coefficient: 0.178
• Cohesion ratio (share of deps within slice): 0.587

Heuristic interpretation

• AVG Ce = 2.24 → OK (lower is usually better; big fan-out hints 'god modules')
• P90 Ce = 5 → OK (if P90 grows, responsibilities are spreading)
• Avg clustering = 0.178 → OK (higher clustering often means more cycles/tight coupling)

Top 15 modules by fan-out (Ce)

• dpone.commands.registry_core: 20
• dpone.ops.catalog_artifacts: 20
• dpone.runtime.credentials.factory: 19
• dpone.ops.catalog_release: 18
• dpone.runtime.etl.processor: 18
• dpone.runtime.bootstrap: 16
• dpone.strategy_intelligence: 16
• dpone.runtime.sinks.postgres: 15
• dpone.runtime.sinks.bigquery: 14
• dpone.runtime.sinks.clickhouse_impl: 14
• dpone.commands.registry_docs: 13
• dpone.manifest.explain: 13
• dpone.runtime.etl.nested_load: 13
• dpone.runtime.sinks.mssql: 13
• dpone.ops.catalog_core: 12

Top 15 modules by fan-in (Ca)

• dpone.app.context: 71
• dpone.runtime.artifacts: 63
• dpone.contracts.errors: 57
• dpone.output: 55
• dpone.config: 48
• dpone.runtime.sources.base: 42
• dpone._compat: 38
• dpone.runtime.sinks.base: 34
• dpone.runtime.etl_logging: 32
• dpone.runtime.etl_logging.etl_logger: 32
• dpone.ops.checksums: 24
• dpone.runtime.sources.strategies.api.base: 21
• dpone.dag.edge_explain: 18
• dpone.dag.yaml_types: 18
• dpone.contracts.technical_columns: 17

Layer / Slice architecture metrics

• Layers observed: 39
• Internal import edges: 2027
• Intra-layer edges: 1334
• Cross-layer edges: 693
• Intra-layer ratio: 0.658

• Cross-layer ratio: 0.342

• Excluded layers: dpone.compat (126 modules, 116 edges removed from this coarse architecture view)

Heuristic interpretation

• Intra-layer ratio = 0.658 → OK (higher means more dependencies stay within their own layer)
• Cross-layer ratio = 0.342 → OK (lower means cleaner boundaries between layers)
• Top cross-layer / cross-slice flows below help spot architecture seams that may need ports, facades or further extraction.

Layer summary

Layer	Modules	Out	In	Intra	Cross-out	Cross-in	Avg Ce	Avg Ca	Cohesion	Target layers	Source layers
dpone._compat	1	0	38	0	0	38	0.00	38.00	1.000	0	9
dpone.adapters	4	3	2	0	3	2	0.75	0.50	0.000	1	1
dpone.api	1	3	0	0	3	0	3.00	0.00	0.000	2	0
dpone.app	5	6	74	1	5	73	1.20	14.80	0.167	3	3
dpone.cli	3	5	2	1	4	1	1.67	0.67	0.200	3	1
dpone.cli_render	20	54	32	18	36	14	2.70	1.60	0.333	6	1
dpone.commands	69	323	89	88	235	1	4.68	1.29	0.272	14	1
dpone.config	3	2	67	2	0	65	0.67	22.33	1.000	0	8
dpone.connector_sdk	4	2	3	2	0	1	0.50	0.75	1.000	0	1
dpone.contracts	7	6	98	5	1	93	0.86	14.00	0.833	1	11
dpone.core	7	10	1	1	9	0	1.43	0.14	0.100	4	0
dpone.dag	34	92	97	62	30	35	2.71	2.85	0.674	5	5
dpone.integration_matrix	1	2	1	0	2	1	2.00	1.00	0.000	2	1
dpone.integration_matrix_behavior	1	2	2	0	2	2	2.00	2.00	0.000	2	2
dpone.integration_matrix_constants	1	0	6	0	0	6	0.00	6.00	1.000	0	6
dpone.integration_matrix_counts	1	1	4	0	1	4	1.00	4.00	0.000	1	4
dpone.integration_matrix_models	1	5	1	0	5	1	5.00	1.00	0.000	5	1
dpone.integration_matrix_samples	1	4	1	0	4	1	4.00	1.00	0.000	4	1
dpone.integration_matrix_selection	1	1	1	0	1	1	1.00	1.00	0.000	1	1
dpone.integration_matrix_wide	1	1	1	0	1	1	1.00	1.00	0.000	1	1
dpone.lib	14	24	11	10	14	1	1.71	0.79	0.417	3	1
dpone.manifest	37	95	95	69	26	26	2.57	2.57	0.726	3	6
dpone.metrics	11	12	24	12	0	12	1.09	2.18	1.000	0	1
dpone.observability	6	2	3	2	0	1	0.33	0.50	1.000	0	1
dpone.operations	38	38	0	0	38	0	1.00	0.00	0.000	1	0
dpone.ops	67	114	160	111	3	49	1.70	2.39	0.974	3	2
dpone.orchestration	6	6	9	5	1	4	1.00	1.50	0.833	1	1
dpone.output	1	1	55	0	1	55	1.00	55.00	0.000	1	3
dpone.output_table	1	0	11	0	0	11	0.00	11.00	1.000	0	2
dpone.ports	7	13	16	6	7	10	1.86	2.29	0.462	4	4
dpone.readiness	38	82	86	48	34	38	2.16	2.26	0.585	7	3
dpone.root	1	0	0	0	0	0	0.00	0.00	1.000	0	0
dpone.runtime	332	899	823	781	118	42	2.71	2.48	0.869	6	5
dpone.services	58	144	135	56	88	79	2.48	2.33	0.389	10	6
dpone.staging	2	3	1	1	2	0	1.50	0.50	0.333	1	0
dpone.storage	6	6	7	5	1	2	1.00	1.17	0.833	1	1
dpone.strategy_intelligence	29	58	53	41	17	12	2.00	1.83	0.707	4	2
dpone.supply_chain	7	3	4	3	0	1	0.43	0.57	1.000	0	1
dpone.type_system	5	5	14	4	1	10	1.00	2.80	0.800	1	4

Top 15 cross-layer dependency flows

From layer	To layer	Edges
dpone.commands	dpone.services	58
dpone.commands	dpone.app	54
dpone.runtime	dpone.config	48
dpone.commands	dpone.output	47
dpone.operations	dpone.ops	38
dpone.runtime	dpone._compat	24
dpone.manifest	dpone.contracts	22
dpone.runtime	dpone.contracts	21
dpone.readiness	dpone.runtime	19
dpone.runtime	dpone.readiness	17
dpone.services	dpone.app	17
dpone.cli_render	dpone.services	16
dpone.commands	dpone.dag	16
dpone.dag	dpone.contracts	15
dpone.commands	dpone.cli_render	14

Top 15 cross-slice dependency flows

From slice	To slice	Edges
dpone.runtime	dpone.config	48
dpone.operations	dpone.ops	38
dpone.runtime	dpone._compat	24
dpone.manifest	dpone.contracts	22
dpone.runtime	dpone.contracts	21
dpone.readiness	dpone.runtime	19
dpone.runtime	dpone.readiness	17
dpone.commands.manifest	dpone.services.manifest	16
dpone.commands.dag	dpone.dag	15
dpone.dag	dpone.contracts	15
dpone.commands.dag	dpone.services.dag	14
dpone.strategy_intelligence	dpone.runtime	13
dpone.services.docs	dpone.app	12
dpone.services.docs	dpone.metrics	12
dpone.commands.docs	dpone.app	11

How to update this page

dpone docs update-dev-metrics

CI check:

dpone docs update-dev-metrics --check

Layer-metrics gate (thresholds + regression vs baseline):

dpone docs check-layer-metrics

Architecture-fitness gate (coupling hot spots + high-responsibility classes):

dpone docs check-architecture-fitness

Module-size gate (LOC/SLOC + explicit debt baseline):

dpone docs check-module-size

Refresh the committed baseline snapshot:

dpone docs check-layer-metrics --write-baseline
dpone docs check-module-size --write-baseline

Metric groups

1. LOC / SLOC (lines of code)

These metrics show raw module size and help spot oversized files. LOC counts all physical lines; SLOC counts non-empty, non-comment source lines. The generated report tracks both repository-wide metrics and the same metrics excluding tests, because production module size and test volume have different meanings.

Useful heuristics: - max LOC < 600 is the hard target for “regular” modules. - LOC <= 450 is the warning target for newly touched modules. - files above ~800-1000 LOC are strong candidates for splitting. - median LOC is often more informative than average, because a few large modules can skew the average.

2. Module-level coupling / cohesion

These metrics are based on the internal import graph inside dpone.*.

• Ce (fan-out) — how many internal modules a module imports. Lower is usually better.
• Ca (fan-in) — how many internal modules import a module. High fan-in can be fine for stable shared abstractions.
• LCC ratio — size of the largest connected component in the import graph. Very high values can mean the system is too entangled.
• Avg clustering — a proxy for “triangles” in the graph. Higher values often indicate tight coupling and hidden cycles.
• Cohesion ratio — share of imports that stay within the same slice. Higher is usually better.

Heuristics used in the generated report: - AVG Ce: OK ≤ 6, WARN ≤ 12, ALERT > 12 - P90 Ce: OK ≤ 12, WARN ≤ 18, ALERT > 18 - Avg clustering: OK ≤ 0.18, WARN ≤ 0.25, ALERT > 0.25

3. Layer / slice architecture metrics

These metrics complement module-level coupling by looking at architectural boundaries.

• Layer summary groups modules into coarse layers such as dpone.commands, dpone.services, dpone.manifest, dpone.dag, dpone.runtime, dpone.ports, dpone.adapters.
• Cross-layer flows show the strongest allowed layer→layer dependencies.
• Cross-slice flows go one level deeper (commands.dag -> services.dag, services.docs -> metrics, etc.) and help identify where abstractions may still leak.

Useful heuristics: - Intra-layer ratio — higher is better. A rough target is >= 0.55. - Cross-layer ratio — lower is better. A rough target is <= 0.45.

These are not absolute pass/fail thresholds. Some orchestration-heavy layers (commands, services) will naturally depend on several other layers. The main value is tracking trends over time and spotting unexpectedly heavy flows.

Baseline vs target

The current generated snapshot is recorded above on this page. Regression baselines live in docs/layer_metrics_baseline.json and docs/module_size_baseline.json.

Recommended long-term goals: - max module LOC < 600 - max module SLOC < 500 - max Ce < 12 - avg clustering <= 0.18 - no forbidden cross-layer imports (enforced by dpone docs check-import-rules) - no new non-allowlisted module-size failures (enforced by dpone docs check-module-size) - cross-layer ratio trending downward release over release

Layer-metrics gate in CI

Recommended CI step:

dpone docs check-layer-metrics \
  --baseline docs/layer_metrics_baseline.json \
  --min-intra-layer-ratio 0.55 \
  --max-cross-layer-ratio 0.45 \
  --allowed-ratio-regression 0.02 \
  --allowed-flow-regression 5

What it checks: - absolute thresholds for intra-layer / cross-layer ratios; - optional cap for the largest cross-layer flow; - regression against the committed baseline snapshot in docs/layer_metrics_baseline.json.

This is intentionally a coarse architectural gate. It does not replace dpone docs check-import-rules; instead, it complements it by catching trend regressions even when no forbidden import rule is violated.

Module-size gate in CI

Recommended CI step:

dpone docs check-module-size \
  --baseline docs/module_size_baseline.json \
  --warn-lines 450 \
  --max-lines 600

What it checks: - LOC and SLOC per Python module; - new modules above the hard max; - existing debt only when documented in docs/module_size_baseline.json; - focused refactor progress when allowlisted modules shrink below thresholds.

Current baseline policy: - No allowlisted modules may remain above 600 LOC by default. - New baseline entries require an explicit owner, reason, remediation target and architecture-review justification. - Compatibility facades are allowed, but must delegate immediately and must not accumulate business logic.