A Hybrid Unsupervised–Supervised Machine Learning Framework for Automated Multi-Language Code Quality Assessment: Design and Evaluation of CodeGuardian AI

Maintaining high code quality across large and distributed software repositories remains a persistent, structurally unsolved challenge in modern software engineering. Rule-based linters and static-analysis platforms enforce stylistic constraints but cannot learn from or generalise to the quality patterns latent in real-world codebases. This paper presents CodeGuardian AI, a hybrid unsupervised-supervised machine-learning pipeline that addresses this gap by (i) collecting 4,000 real-world source files-2,000 Python and 2,000 JavaScript-from GitHub via the Search API with MD5-based deduplication, (ii) extracting twenty static-analysis metrics per file spanning structural, documentation, style, and semantic quality dimensions using the Lizard library and custom language-aware parsing, (iii) discovering natural quality groupings through a pipeline of StandardScaler normalisation, PCA reduction to ten principal components, and K-Means clustering with k = 3, (iv) labelling the resulting clusters Good, Average, and Bad by ranking mean cyclomatic complexity, and (v) training five supervised classifiers on the labelled data. The Random Forest classifier achieves the highest test-set accuracy of 99.2% on Python files and 98.9% on JavaScript files. The trained pipeline is deployed as a Streamlit web application that accepts pasted code snippets and returns instant, colour-coded quality feedback (green / yellow / red) in under 400 ms on commodity hardware. Crucially, this paper provides honest methodological interpretation: the near-perfect classifier accuracy reflects successful recovery of the K-Means cluster structure rather than agreement with expert-annotated ground truth, and three candid limitations are enumerated. CodeGuardian AI establishes a fully open-source, reproducible reference implementation that bridges the gap between automated metric computation and human-interpretable quality judgements, lowering the barrier to rigorous quality practices for individual developers, small teams, and open-source contributors who lack access to commercial codeintelligence platforms.