CodeGuardian is an AI-assisted code review prototype developed as a Final Degree Project. It connects static analysis, CI automation, model-backed proposal generation and controlled developer review in one reproducible workflow.
The project explores how a language model can help interpret static-analysis findings without removing the developer from the decision loop. CodeGuardian prepares the relevant source context, requests structured correction proposals, checks whether each proposal still applies to the current code and publishes only reviewable results. It is an academic prototype, not a production service or a guarantee of semantic correctness.
- An end-to-end academic workflow from pull-request analysis to reviewable suggestions.
- Structured outputs that can be exported as
codeguardian-results.json. - Batching and caching to keep model calls controlled and observable.
- Applicability checks that prevent a proposal from being applied to changed source.
- Python syntax validation and optional Maven compilation when a project provides a
pom.xml. - A human review step through the local CLI and VS Code extension before changes are applied.
- Execution metrics for findings, proposals, discarded suggestions, cache activity and token usage.
The implementation currently contains adapters for a pull-request provider, CI pipeline and static-analysis service. Provider and model credentials are supplied through the environment; the workflow is designed so that those integrations can be replaced without changing the review contract.
The project is organized into three repositories, integrated here as independent top-level directories:
| Directory | Responsibility |
|---|---|
codeguardian-core |
Python agent, validation logic, source-control synchronization, result export, CLI and VS Code extension |
codeguardian-infra |
Docker-based local environment with CI, static analysis and observability services |
sample-mixed |
Controlled Java and Python project used for tests and end-to-end demonstrations |
The original repository histories are preserved in the Git history of this unified repository.
- A pull request starts the configured CI pipeline.
- The pipeline checks out the source and identifies the project type.
- The static-analysis service reports code-quality findings.
- The CodeGuardian agent reads the pipeline contract and normalizes the findings.
- Related findings are grouped and the affected source context is located.
- The configured language-model adapter receives the bounded context and returns structured proposals.
- CodeGuardian checks that each proposal still matches the current source and validates the generated replacement.
- Valid suggestions are exported and synchronized as review comments through the configured source-control adapter.
- The developer reviews, accepts or discards suggestions locally through the CLI or VS Code extension.
- Execution metrics are exposed to the local observability stack.
The developer remains responsible for the final decision. The system does not claim that a generated proposal is correct merely because it passes syntax or applicability checks.
The following diagram summarizes the automated and manual parts of the workflow:
The editable source of the diagram is available at workflow.mmd.
The core agent is the orchestration layer. It reads the CI pull-request contract, obtains static-analysis findings, prepares bounded source context, validates generated replacements and synchronizes review comments through the configured adapter.
It also provides:
- issue normalization and deduplication;
- scope detection and batching by function or method;
- Python syntax validation;
- optional Maven compilation validation when a
pom.xmlis present; - optional optimization review for changed scopes;
- incremental comment synchronization;
- export of validated suggestions and execution metrics.
The local infrastructure includes a CI service, a static-analysis service and an observability stack. Their job is to provide repeatable inputs and execution data; CodeGuardian keeps proposal generation and validation in the core agent.
The extension provides the local review interface. The CLI performs file-level operations: listing suggestions, checking whether the original code still matches the current file and applying selected replacements.
Applications are recorded as local transactions so that Undo can restore the previous file state, including related edits captured by the transaction mechanism.
The infrastructure exports metrics such as analysis latency, token usage, cache activity, static-analysis findings, generated and discarded suggestions and comment-synchronization results. The included dashboards are intended for local demonstration and diagnosis.
The complete local environment is documented in codeguardian-infra/docs/end-to-end-demo.md.
Start the documented environment with:
cd codeguardian-infra
docker compose up -d --buildThe example services are exposed locally on the ports described in the infrastructure documentation. The demonstration target is sample-mixed, which contains controlled Java and Python findings for tracing the workflow from analysis to local review.
External credentials and running services are required for the full integration path. A local build or unit-test pass does not, by itself, prove that every external integration is available.
Credentials must be configured in the CI environment or supplied through environment variables. Keep secrets outside the repository. The exact variable names, pipeline contract and adapter settings are documented in codeguardian-core/README.md and codeguardian-infra/README.md.
Typical configuration concerns include:
- the static-analysis service and project key;
- the language-model adapter and its API credential;
- the pull-request/source-control adapter;
- CI credentials and comment permissions;
- metrics and observability endpoints.
The core repository contains automated unit tests for input parsing, issue normalization, patch applicability, syntax and build validation, comment synchronization, performance review, metrics aggregation and static-analysis result parsing.
Run the core tests with:
cd codeguardian-core
pytest -qThe end-to-end demonstration additionally exercises the configured CI, static-analysis, source-control and observability services. Those services require their own local setup and credentials.
- Generated suggestions are proposals; a developer must review the result before applying it.
- Syntax, build and applicability checks are safeguards, not proof of semantic correctness.
- Python replacements receive syntax validation, while Java projects with Maven can be checked with
mvn compilewhen the project contains apom.xml. - Other ecosystems use applicability validation by default rather than compilation or project-test execution.
- Optimization review is optional and does not replace profiling, benchmarks or project tests.
- External-service integration is covered by the controlled demonstration environment and is not represented as an independent production deployment.
- The repository is an academic prototype and should be evaluated with its documented dependencies, credentials and limits.