STIG code metrics and NEXY

Why NEXY is useful

Raw engineering quantities cannot be compared directly:

These values have different units, different natural ranges, overlapping meaning, and different statistical distributions. Averaging the raw numbers would be meaningless. STIG converts each metric into the same normalized percentile scale first, then computes a weighted average of the available included elementary percentiles.

STIG then maps the percentile to a fixed NEXY zone. In this guide, lowercase p is the exact internal percentile fraction in 0.0 .. 1.0. Uppercase P<n> is the displayed integer percentile marker on the 0 .. 100 scale, written without a space, for example P9, P98, or P100.

In the gauge, these zones are drawn as an equal-zone visual scale: each zone gets exactly 1/7 of the colored arc, even though the underlying percentile ranges have different widths. This keeps narrow zones such as outliers visible and comparable in the UI. The pointer is placed by first selecting the zone from p, then interpolating within that zone's equal-width visual band.

For example, P9 means the 9th percentile, i.e. 9% of the reference population is at or below that modeled value. It is the boundary from Very low to Low.

After normalization, different metrics can be compared, displayed, and combined without pretending that every metric is linear, normally distributed, or measured in the same unit.

NEXY is designed for STIG software metrics, but the idea is general. It can be used for any engineering quantity for which a sufficiently large and representative measurement set exists: code size, path complexity, number of interface signals, timing values, resource usage, physical magnitudes, reference thresholds, or other system measurements.

Engineering quantity

A NEXY-modeled quantity is any measurable engineering value.

Examples:

Each quantity has a separate metric model for the scope where it is used. A function-level line-count model is not the same model as a sink-level or component-level line-count model.

Scopes

STIG uses the same source-code metric names at three scopes. Analyzer-derived source-location metrics are emitted only for scopes where the analyzer produced the required IR graph evidence.

For source-code function metrics, sourceCodeSelection.from(...) chooses the compile-command artifact. Then sourceCodeSelection.include(...) and sourceCodeSelection.exclude(...) filter both the compilation units passed to clang-tidy and the function-definition rows accepted from its diagnostics. This second filter is important because clang-tidy can report functions defined in headers included by a selected compilation unit. Dependency functions outside the selected element source folder do not enter element-core totals.

Raw values are scope-specific. Component totals are naturally larger than single-function values because a component contains more code. NEXY values are scope-normalized, so the same displayed NEXY scale is used for functions, sinks, and components.

Metric catalog

LLVM-derived source links in this table are pinned to Extra Clang Tools 18.1.8, matching STIG's pinned LLVM major version 18. The readability-function-size check is the correct clang-tidy source for lines, statements, branches, parameters, and variables: STIG parses those values from the check's diagnostic notes and links each row to the corresponding threshold option.

Analyzer graph metrics are availability-sensitive. If the analyzer was not run, the metric is unavailable and STIG omits it from the scored NEXY input set. STIG does not substitute 0 for an unavailable analyzer metric, and the composite NEXY denominator is the sum of the weights of available scored metrics only. Z3/path-feasibility checking is not required for the current analyzer graph metrics.

Cognitive complexity and BrDf

BrDf is computed from data-flow graph evidence. It counts unique selected source lines mapped from branch-classified LLVM IR instructions in the per-sink data-flow slice. Cognitive complexity for straight-line code is normally 0, because there is no control flow to understand.

For simple flat control flow, a useful rule of thumb is:

That approximation stops being reliable when nesting, boolean operator sequences, switch/case handling, lambdas, early exits, or other readability rules matter. Cognitive complexity intentionally penalizes code that is harder for humans to follow, while cyclomatic complexity stays closer to path counting.

For that reason, STIG uses cognitive complexity as the primary function-level readability metric and keeps BrDf for graph/slice-level branching evidence.

Metric model

For every metric and every scope, STIG uses a metric model.

A metric model contains:

• the metric key and scope;

• the metric direction, for example HIGHER_IS_MORE_COMPLEX;

• one distribution model;

• one raw-value display model.

The distribution model converts between raw metric values and percentile fractions. For code metrics this is typically a right-skewed count/score model, for example a lognormal model. It is either:

• a manual/reference quantile table, where STIG stores explicit percentile to raw-value points; or

• a typed statistical distribution with typed factors, for example LogNormalDistributionModel(logMean, logStandardDeviation) or PoissonDistributionModel(lambda).

The type system can also represent a normal distribution, but the shipped STIG code-metric defaults do not use normal models. Raw code metrics are usually non-negative counts or scores with right-skewed tails, so lognormal models are the current default.

The raw-value display model carries units, tick rounding, and reference range metadata. It is separate from the distribution model. Gauge positions use the equal-zone visual axis: each NEXY zone receives the same angular width, and the pointer is interpolated inside that zone from the percentile's relative position inside the zone.

The intended calibration workflow is empirical: fit each model on a large, good-quality, representative software baseline, then keep the fitted model fixed for report interpretation. This makes NEXY a reality-based percentile metric: the raw value is compared with an observed reference distribution, not only with normative threshold values. External thresholds such as HIS can still be used as anchors or cross-checks; in the current defaults, the function-level medium-to-high boundary is aligned with HIS-style values where a suitable reference exists.

Current STIG defaults use lognormal distribution models and logarithmic raw-value metadata for all shipped NEXY metric models. These defaults are approximate engineering calibrations and are expected to improve when a larger curated measurement baseline is available. At function scope, the median (P50) is derived as P75 / 2, and the low-to-medium boundary (P25) is derived as P75 / 4.

Sink and component models use the same metric ratios as the function models. The default sink scale is 20x the function raw boundaries, and the default component scale is 50x the function raw boundaries. Therefore, if one function-level metric has twice the raw boundary of another, the same ratio is kept for sink and component models.

The analyzer-derived metrics are sink-only. Their calibration uses reduced reference anchors because they count unique source locations selected for one sink rather than complete-function clang-tidy totals. The current raw boundaries are:

This halves every raw quantile of the former analyzer-metric calibration while preserving the lognormal distribution shape and the P25:P50:P75 ratio.

STIG does not compute or select models when a report is opened. Reports use the stored metric model as the single source of truth. In the future, an offline model-building workflow may produce better metric models from a larger measurement baseline, but the report-time model shape remains the same.

From raw value to elementary NEXY

For an elementary metric, elementary NEXY is the percentile of the raw value under the selected model:

If no parametric distribution is selected, STIG can use a manual/reference quantile table:

This makes NEXY model-independent at the user level. The report does not need to explain whether the metric was lognormal, Poisson, or a quantile table in order for the user to interpret NEXY 92: it means the value is higher than about 92% of the reference baseline. This is a percentile rank, not a statistical p-value.

NEXY zones

NEXY uses the same percentile zones for every metric. The table uses displayed NEXY values:

50 is shown as the median/middle marker. It is useful for understanding the scale, but it is not a split between action bands.

Decision thresholds

The primary process thresholds are:

The metric model may also define P0.1, P50, and P99.9 reference points for range calculations and diagnostics. The compact gauge labels focus on zone boundaries, because those are the decision edges.

Gauges and rulers

STIG reports use two complementary visualizations.

Precomputed render plans

All gauge and ruler mathematics is computed in Kotlin during report generation. The generated report embeds a small render plan for each displayed gauge/ruler. JavaScript only renders the already computed plan.

For an elementary metric, the render plan contains:

• raw value, with a separate visible label that omits the unit;

• unitful raw label for metadata/export;

• exact NEXY value as a 0.0 .. 1.0 fraction;

• visible NEXY label rounded to the nearest integer on the 0 .. 100 scale;

• zone/band;

• raw tick labels;

• equal-zone axis positions;

• overflow information, if the raw value is outside the visible range.

For a composite metric, the render plan contains only normalized NEXY values, because a composite score has no raw physical unit.

This keeps the browser renderer simple and makes Kotlin the single source of truth for metric-model application, CDF/inverse-CDF calculations, rounding, and classification.

Rounding

Classification uses the exact model-derived NEXY value. Displayed NEXY labels are rounded to the nearest integer on the 0 .. 100 scale, and raw tick labels are rounded for readability.

For integer count metrics, the default display policy is compact integer rounding: small values stay exact integers, while larger values are rounded to three significant digits so compact gauges do not print noisy labels.

The rounded label is not parsed back into the decision. A value is classified by its exact percentile, not by the rounded NEXY or raw-value text printed on the ruler.

If a project exports a raw integer gate for another process, that export may choose a conservative rounding rule explicitly. That is separate from the visual rounding used by the NEXY report.

Overflow

The raw ruler reports whether a value is outside the reference raw range (P0.1 .. P99.9 in the default models). The marker remains at its computed equal-zone position for the computed percentile, coerced to the 0 .. 100 gauge range.

For a value above P99.9, the report may show:

This avoids hiding the difference between a value that is slightly above P98 and a value that is massively above the displayed range.

Composite NEXY

A component, function, or sink/output can have several elementary metric NEXY values:

STIG keeps the individual values visible, because engineers need to know why a metric was flagged. It also computes one summary value: the weighted average of all available included elementary NEXY values.

For example, if lines has NEXY 55 with weight 0.25, and statements has NEXY 65 with weight 0.10, their combined contribution is:

Weights are deliberately allowed to be non-equal. Metrics can overlap in meaning, for example lines and statements both describe size. STIG can keep both metrics visible while using weights to control their relative contribution to the composite.

The current function-level clang-tidy collection path uses these default source-code metric weights:

Report-generation paths that do not pass an explicit weight map use the model application default weight 1.0 for each included available metric.

Weights do not need to sum to 1. STIG divides by the sum of the weights of the available scored metrics.

If an analyzer-gated metric is unavailable, STIG omits that metric from the scored input set and emits an availability diagnostic. It does not substitute 0, and it does not keep the unavailable metric in the denominator.

Generated results report composite coverage: candidate metric count/weight, scored metric count/weight, and omitted metric count/weight. That makes a score based on partial evidence visibly different from a score based on the full candidate set.

The composite NEXY is classified using the same NEXY zones as elementary metrics.

Safety-mechanism interpretation

NEXY does not replace hazard analysis. It answers a narrower question:

For a component output or sink, the report can map the NEXY zone to additional engineering labels:

The compact report column is titled Measures. It classifies the complexity-driven need for supplementary safety mechanisms, additional analysis, additional verification, or alternative argumentation. It does not downgrade the baseline measures required by ASIL, hazard analysis, interface criticality, actuator authority, or explicit safety requirements. These four values and their popup explanations are defined by the SafetyMeasureImpact enum; its exhaustive mapping from NexyZone is the single policy used by component, sink, aggregate, and JSON reports.

For components, the same zone can also be mapped to a project-defined complexity class. STIG derives that class from the component-level NEXY band instead of computing it with a second formula.

The careful wording is:

not:

A safety mechanism can still be required by ASIL, hazard analysis, interface criticality, actuator authority, or an explicit safety requirement even when all complexity metrics are low.

External thresholds such as HIS

NEXY can be aligned with external engineering thresholds.

For example, if a HIS-style threshold for statements is 50, the metric model can compute:

The report can then show that the external threshold is the medium-to-high boundary for the function-level statement model. This is better than hard-coding a magic raw number into every scope, because the metric model explains where that raw number sits in the observed engineering population.

External thresholds do not replace NEXY. They are additional reference marks on the same reference scale.

What users should read in the report

For each metric, read the report as follows:

1. Look at the raw value to understand the absolute size.

2. Look at the NEXY value to understand how unusual the value is.

3. Use the raw ruler to see the reference threshold values in real units.

4. Use the NEXY gauge and zone to understand the engineering action band.

5. For composite decisions, use the weighted-average NEXY zone.

A good report line therefore contains both views:

and, for a composite:

The individual metrics explain the cause. The composite NEXY values summarize the engineering attention level.