This document describes the quality attributes currently measured for build scripts in this project and the low-level metrics used to characterize each attribute.

The README is intentionally methodology-first:

• it documents only metrics that are currently computed by the pipeline
• it groups metrics by quality attribute rather than by implementation script
• it focuses on metric definitions, formulas, and build-system-specific calculation rules

Supported build systems:

• Gradle Groovy DSL: .gradle and .groovy
• Gradle Kotlin DSL: .gradle.kts
• Maven: pom.xml
• Ant: build.xml

• 1. Scope and Conventions
• 2. Quality Attribute Overview
• 3. Complexity
• 4. Dependency Quality
• 5. Determinism and Reproducibility
• 6. Maintainability
• 7. Coupling and Cohesion
• 8. Evolution and Change Activity
• 9. Security
• 10. Reliability

The before/after pipeline reports most metrics with paired fields:

• *_Before
• *_After
• *_Delta when a direct delta is meaningful

When the GitHub commit runner is used, the pipeline also creates a per-commit output directory:

• results/commits/<commit_sha>/

That directory contains one CSV per focused view for the changed build files in that commit:

• summary_metrics.csv
• maintainability_metrics.csv
• understandability_metrics.csv
• modularity_metrics.csv
• security_metrics.csv
• reliability_metrics.csv

Each CSV stores one row per changed build file in that commit, including the full File_Path, the File_Name, and the metrics for that quality view. The pipeline does not create separate per-file CSV folders inside the commit directory.

The formulas below are written for a single build file b. The pipeline applies the same definitions to both snapshots.

Several quality attributes reuse the same base quantities.

• Build_Modularity_* fields are referenced by the pipeline, but the implementation source is not present in the current workspace. They are therefore not treated as documented metrics in this README.
• Conceptual or proposed metrics that are not currently computed by the pipeline are intentionally omitted.
• When a metric is unsupported for a specific build syntax, that limitation is stated explicitly in the relevant section.

Style_Conformance_Score is a normalized metric in the 0..1 range:

Style_Conformance_Score(b) = max(0, 1 - (violations(b) / BLOC(b)))

The pipeline also emits a focused understandability output file:

• results/understandability_metrics.csv

Complexity captures the structural and cognitive burden of understanding and modifying a build script.

• Cyclomatic_Complexity is computed with CodeNarc and aggregated at file level.
• Halstead_Volume is computed from a Groovy AST-based operator/operand extractor.

• Cyclomatic_Complexity is computed with detekt by summing file-level CyclomaticComplexMethod findings.
• Halstead_Volume is currently not implemented for Kotlin DSL in this pipeline, so the emitted value is 0.0.

Cyclomatic_Complexity is implemented as a build-logic complexity heuristic:

BLC_maven = 1 + count(profile) + count(activation) + count(execution)

Halstead_Volume is computed from XML structure:

• operators: XML tag names
• operands: child-tag occurrences

Cyclomatic_Complexity is implemented as a build-logic complexity heuristic:

BLC_ant = 1
        + count(condition/operator tags)
        + count(if attributes)
        + count(unless attributes)
        + count(extra dependency edges from depends)

Halstead_Volume is computed from XML structure:

• operators: non-project and non-description XML tags
• operands: attribute names

Dependency quality reflects how explicitly and stably a build file declares the external artifacts it consumes.

If Dependency_Count(b) = 0, the implementation returns:

DSS(b) = 0.0

• Dependency declarations are extracted from string-style and map-style dependency declarations.
• Local property-resolution heuristics are applied before classifying versions.

• Dependency versions are read from dependency declarations.
• If a dependency omits a local version, the pipeline consults local dependencyManagement when available.
• Local <properties> are resolved before classification.

• Dependencies are inferred from versioned JAR references found in XML attribute values.
• Versions are extracted from JAR file names after resolving simple property references.

Determinism measures the degree to which a build script avoids constructs that can make repeated executions produce variable results.

If BLOC(b) = 0, the implementation returns:

BDS(b) = 0.0

BDS is implemented for all supported build systems:

• Gradle
• Maven
• Ant

The current detector is text-based and scans the file contents for the construct families above.

Maintainability captures how easy a build script is to inspect, modify, and evolve without introducing extra effort or breakage.

For maintainability, this project now considers only:

• BLOC
• Cyclomatic_Complexity
• Halstead_Volume
• Clone_Density
• maintainability smells

The pipeline also emits a maintainability-focused output file:

• results/maintainability_metrics.csv

A maintainability score can be expressed as:

Maintainability(b) =
(
  1 / (1 + BLOC(b))
  + 1 / (1 + Normalized_CC(b))
  + 1 / (1 + Normalized_HV(b))
  + (1 - Clone_Density(b))
  + (1 - MSD(b))
) / 5

Where:

• Normalized_CC(b) = Cyclomatic_Complexity(b) / BLOC(b)
• Normalized_HV(b) = Halstead_Volume(b) / BLOC(b)
• MSD(b) = Maintainability_Smell_Density

Interpretation:

• lower build size, lower control-flow complexity, and lower Halstead volume increase maintainability
• higher duplication reduces maintainability through 1 - Clone_Density(b)
• higher smell density reduces maintainability through inverse normalization

The maintainability-focused CSV includes:

• BLOC_Before and BLOC_After
• Cyclomatic_Complexity_Before and Cyclomatic_Complexity_After
• Normalized_CC_Before and Normalized_CC_After
• Halstead_Volume_Before and Halstead_Volume_After
• Normalized_HV_Before and Normalized_HV_After
• Clone_Density_Before and Clone_Density_After
• Maintainability_Smell_Count_Before and Maintainability_Smell_Count_After
• Maintainability_Smell_Density_Before and Maintainability_Smell_Density_After
• Maintainability_Smell_Summary_Before and Maintainability_Smell_Summary_After

Tracked maintainability smell categories:

• EMPTY_INCOMPLETE_TAGS
• INCONSISTENT_DEPENDENCY_MANAGEMENT
• LACK_OF_ERROR_HANDLING
• MISSING_DEPENDENCY_VERSION
• SUSPICIOUS_COMMENTS
• DEPRECATED_DEPENDENCIES
• OUTDATED_DEPENDENCIES

• BLOC, Cyclomatic_Complexity, and Halstead_Volume reuse the definitions from Section 3.
• Clone_Density is computed with PMD CPD when available, with a repeated-line-window fallback when the preferred duplication path is unavailable.
• Maintainability smells are counted without weighting; each finding contributes equally to the smell count.

Coupling and cohesion describe the extent to which build logic is externally connected and internally related.

Component meanings:

• T_int: internal task or target dependency links
• V_shared: variables or properties shared by multiple internal elements
• C_internal: internal configuration references reused across elements
• M: inter-module references
• D: external dependencies
• P: plugins
• R: repositories or remote artifact sources
• E: external commands or build-script execution hooks
• U: environment variables, absolute paths, and URL-based resources

The elements compared depend on the build system:

• Gradle: task feature sets
• Maven: plugin execution feature sets
• Ant: target feature sets

Modularity is not currently exported as a standalone implemented pipeline field in this workspace, but it can be operationalized from cohesion and coupling as:

MS(b) =
(
  Build_Cohesion(b)
  + (1 - Coupling_Ratio(b))
  + 1 / (1 + NCP_External(b))
  + (1 - Clone_Density(b))
) / 4

Where:

• MS(b) = modularity score
• Build_Cohesion(b) rewards stronger internal relatedness of build elements
• 1 - Coupling_Ratio(b) rewards a lower proportion of external coupling
• 1 / (1 + NCP_External(b)) rewards lower size-normalized external coupling
• 1 - Clone_Density(b) rewards lower duplication across build logic

Interpretation:

• higher cohesion, lower external coupling, and lower duplication indicate stronger modularity

The pipeline also emits a focused modularity output file with the separately tracked low-level metrics:

• results/modularity_metrics.csv

The modularity-focused CSV includes:

• CP_Internal_Before and CP_Internal_After
• CP_External_Before and CP_External_After
• NCP_Internal_Before and NCP_Internal_After
• NCP_External_Before and NCP_External_After
• Build_Cohesion_Before and Build_Cohesion_After
• Clone_Density_Before and Clone_Density_After

Evolution metrics characterize how frequently a build file changes and how much code churn it experiences over time.

The current before/after pipeline uses a rolling observation window ending at the analyzed commit.

Security is characterized through smell-based indicators rather than a single aggregate security score.

A security score can be operationalized directly from the security smell density:

SS(b) = max(0, 1 - (Security_Smell_Count(b) / max(BLOC(b), 1)))

Equivalently, using the documented density metric:

SS(b) = max(0, 1 - Security_Smell_Density(b))

Where:

• SS(b) = security score
• Security_Smell_Count(b) counts security smell findings
• Security_Smell_Density(b) normalizes those findings by build lines of code

Interpretation:

• more security smells imply lower security

Tracked security smell categories:

• HARDCODED_CREDENTIALS
• INSECURE_URLS
• WILDCARD_USAGE
• HARDCODED_PATHS_AND_URLS
• DEPRECATED_DEPENDENCIES
• OUTDATED_DEPENDENCIES

The pipeline also emits a focused security output file:

• results/security_metrics.csv

The security-focused CSV includes:

• Before_Security_Smell_Count and After_Security_Smell_Count
• Before_Security_Smell_Density and After_Security_Smell_Density
• Before_Security_Smell_Summary and After_Security_Smell_Summary
• Before_HARDCODED_CREDENTIALS and After_HARDCODED_CREDENTIALS
• Before_INSECURE_URLS and After_INSECURE_URLS
• Before_WILDCARD_USAGE and After_WILDCARD_USAGE
• Before_HARDCODED_PATHS_AND_URLS and After_HARDCODED_PATHS_AND_URLS
• Before_DEPRECATED_DEPENDENCIES and After_DEPRECATED_DEPENDENCIES
• Before_OUTDATED_DEPENDENCIES and After_OUTDATED_DEPENDENCIES

Reliability captures build-script robustness using issue density, dependency stability, and external-system reliance.

Where:

• HC = hardcoded credentials count
• IU = insecure URLs count
• WU = wildcard usage count
• HP = hardcoded paths or URLs count
• DD = deprecated dependencies count
• OD = outdated dependencies count

• higher RE means fewer reliability issues per build line
• higher DSS means a larger share of dependencies are pinned to fixed versions
• lower EDR means less reliance on external systems

The pipeline also emits a focused reliability output file:

• results/reliability_metrics.csv

The reliability-focused CSV includes:

• RE_Before and RE_After
• DSS_Before and DSS_After
• EDR_Before and EDR_After
• higher RM therefore indicates a more reliable build file overall

The overall reliability metric used in this project is:

RM(b) = (RE(b) + DSS(b) + (1 - EDR(b))) / 3

This combines:

• issue-based reliability through RE
• dependency stability through DSS
• reduced external-system exposure through 1 - EDR

EDR is derived from the coupling model:

EDR(b) = (D + P + R + E + U) / CP_Total(b)

Local module links M are intentionally excluded from the EDR numerator because they represent project-internal structure rather than reliance on external systems.

The current implementation keeps two reliability views:

• RE: issue-based reliability derived only from reliability issues and BLOC
• RM: overall reliability derived from RE, DSS, and EDR

BDS is intentionally not folded into RM in the current pipeline; it remains a separate determinism attribute.