diff --git a/.github/workflows/dotnet-ci.yml b/.github/workflows/dotnet-ci.yml index c061531..36373ee 100644 --- a/.github/workflows/dotnet-ci.yml +++ b/.github/workflows/dotnet-ci.yml @@ -1,4 +1,4 @@ -name: .NET CI +name: .NET CI/CD on: push: @@ -8,7 +8,7 @@ on: jobs: build: - + name: Build & Test (CI) runs-on: ubuntu-latest steps: @@ -23,3 +23,23 @@ jobs: run: dotnet build --no-restore - name: Test run: dotnet test --no-build --verbosity normal + + publish: + name: Publish (CD) + runs-on: ubuntu-latest + needs: build + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + + steps: + - uses: actions/checkout@v4 + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 9.0.x + - name: Publish application + run: dotnet publish "JustBigO(Fun)/JustBigO(Fun).csproj" -c Release -o ./publish + - name: Upload build artifact + uses: actions/upload-artifact@v4 + with: + name: justbigofun-app + path: ./publish diff --git a/AI_USAGE_REPORT.md b/AI_USAGE_REPORT.md deleted file mode 100644 index 8fe335b..0000000 --- a/AI_USAGE_REPORT.md +++ /dev/null @@ -1,32 +0,0 @@ -# AI Usage Report: Development of JustBigO-Fun - -This report fulfills the requirement for Part B (AI Usage Report) of the MDS project. It documents how AI tools were integrated into the software development lifecycle (SDLC) of this project. - -## 1. AI Tools Used -- **GitHub Copilot / Gemini CLI**: Used for code generation, refactoring, and boilerplate reduction. -- **Llama 3.2 (Local via Ollama)**: Integrated directly into the application as the "Mentor Agent" for code translation, completion, and complexity analysis. -- **Semantic Kernel**: Used as the orchestration framework to connect the .NET backend with the local LLM. - -## 2. AI in the Development Phases - -### A. Requirements & Planning -- AI was used to help brainstorm and refine the 12 User Stories found in the `BACKLOG.md`. -- Structural planning for the Docker-based sandbox was assisted by AI suggestions for security and isolation. - -### B. Implementation -- **Reflexion Loop**: A key architectural pattern implemented where the AI autonomously fixes its own code by reading compiler errors. This logic was co-authored with AI to ensure robust error handling. -- **Unit Testing**: 13 automated tests were generated and refined using AI, including specialized "evals" that check the structural integrity of AI-generated responses. -- **SignalR Integration**: The real-time streaming logic for AI responses was implemented using AI-assisted boilerplate generation. - -### C. Testing & CI/CD -- The GitHub Actions pipeline configuration (`dotnet-ci.yml`) was generated by AI based on the project structure. -- AI was used to identify edge cases in the `DockerCodeExecutor` (e.g., handling TLE and OOM errors). - -## 3. Reflections on AI-Driven Development -The use of AI significantly accelerated the implementation of complex features like the multi-language transpiler. However, human oversight was critical in: -1. **Safety**: Ensuring the Docker sandbox is properly isolated. -2. **Logic Verification**: Identifying that the AI initially ignored cancellation tokens, which was subsequently fixed to allow for proper timeout handling. -3. **Prompt Engineering**: Tuning the "Absolute Laws" in the system prompts to prevent the AI from providing full solutions when only hints were requested. - -## 4. Conclusion -AI was not just a tool for writing code, but a core component of the project's architecture. By treating the AI as a "mentor" within the app and an "assistant" during development, we achieved a feature-rich platform in a fraction of the usual development time. diff --git a/README.md b/README.md index be65b79..b3c0787 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,64 @@ # JustBigO-Fun -JustBigO-Fun is an ASP.NET Core 9.0 MVC platform for algorithmic challenges, inspired by sites like LeetCode. It provides a full-stack environment for users to browse coding problems, submit solutions, and have them validated against test cases. +JustBigO-Fun is an ASP.NET Core 9.0 MVC platform for algorithmic challenges, inspired by sites like LeetCode. -## Key Features +> 📄 The application's technical documentation (features, tech stack, run instructions) is in the **[Project Documentation](#project-documentation)** section at the end of this README. + +--- + +## MDS Evaluation — AI-Driven Software Development Process (Component B) + +This section maps each evaluation-rubric item to the corresponding artifacts and evidence in the repository. **Every item below involved the use of AI tools** (Gemini web, Cursor, Gemini CLI, Claude Code) — details in the [dedicated report](./docs/AI_USAGE_REPORT.md). + +### 1. User stories (min. 10) & backlog creation — 2 pts +The user stories and backlog were created and managed in **Jira**, formulated and refined with AI (Gemini web) in the standard format ("As a user, I want… so that…"), together with their acceptance criteria. + +**Jira board (screenshots):** + +![Jira board — backlog](./docs/jira1.png) + +![Jira board — sprint/board view](./docs/jira2.png) + +### 2. Diagrams (UML, component architecture, workflows) — 1 pt +The architecture, component, and workflow diagrams (e.g., the Reflexion loop, the sandbox execution flow) were generated and clarified with AI assistance. + +- 📐 **Diagrams:** [`docs/DIAGRAMS.md`](./docs/DIAGRAMS.md) + +### 3. Source control with git (branching, merge/rebase, pull requests, min. 5 commits/student) — 1 pt +Development was done on feature branches (`feature/generic-executor-metrics`, `fix/admin-area-overhaul`, `Transpilare`, `Indicii_US12_US13`, etc.), with merges, conflict resolution, and pull requests (#4–#19). AI was used to draft commit/PR messages and to resolve merge conflicts. + +- 🔗 **Pull requests:** [PRs link](ADD_LINK_HERE) +- 🔗 **Commit history:** [commits link](ADD_LINK_HERE) + +### 4. Automated tests (including agent evals) — 2 pts +The test suite in [`JustBigO(Fun).Tests/`](./JustBigO(Fun).Tests/) covers Controllers, Models, Hubs, and Services. It includes **agent evals** (`AI/CodeTranslatorAgentTests.cs`, `GeminiHintGeneratorTests.cs`, `GeminiRefactoringSuggestionGeneratorTests.cs`) that verify the structural integrity of AI-generated responses. + +- 🧪 **Tests:** [`JustBigO(Fun).Tests/`](./JustBigO(Fun).Tests/) + +### 5. Bug reporting and resolution via pull request — 1 pt +Real bugs identified and fixed via PR with AI assistance (diagnosis + fix), e.g.: "No redirect to login page" and "Grey text on dark background" (PR #17), fixing tests after resource-limit changes, and stopping the AI query after a timeout. + +- 🐛 **Bug + fix (PR):** [bug/PR link](ADD_LINK_HERE) + +### 6. CI/CD pipeline — 1 pt +The pipeline is configured in GitHub Actions and was generated with AI based on the project structure: +- **CI** (`build` job, runs on every push/PR): restore → build → run tests on .NET 9. +- **CD** (`publish` job, runs only on push to `main`, after CI passes): `dotnet publish` in Release mode and uploads the deployable build as a downloadable artifact. + +- ⚙️ **Workflow:** [`.github/workflows/dotnet-ci.yml`](./.github/workflows/dotnet-ci.yml) + +### 7. Report on the use of AI tools — 2 pts +A detailed report on the AI tools used by each team member and across each development phase. + +- 📄 **Report:** [`docs/AI_USAGE_REPORT.md`](./docs/AI_USAGE_REPORT.md) + +--- + +## Project Documentation + +It provides a full-stack environment for users to browse coding problems, submit solutions, and have them validated against test cases. + +### Key Features - **Problem Library**: Browse a collection of algorithmic challenges with difficulty levels, tags, and detailed descriptions. - **Solution Submission**: Submit C#, Python, Java, and C++ code for evaluation. @@ -11,7 +67,7 @@ JustBigO-Fun is an ASP.NET Core 9.0 MVC platform for algorithmic challenges, ins - **Admin Dashboard**: Secure area for managing problems, including CRUD operations and batch uploading test cases (`.in`/`.out` files). - **Identity & RBAC**: Complete authentication system with role-based access control for users and administrators. -## Tech Stack +### Tech Stack - **Backend**: .NET 9.0, ASP.NET Core MVC, C#, SignalR - **Database**: SQL Server with Entity Framework Core @@ -20,9 +76,9 @@ JustBigO-Fun is an ASP.NET Core 9.0 MVC platform for algorithmic challenges, ins - **Local AI Engine**: Semantic Kernel & Ollama (Llama 3.2) - **Frontend**: Razor Views, Bootstrap, Vanilla CSS, Monaco Editor -## Getting Started +### Getting Started -### Prerequisites +#### Prerequisites To run this project locally, you must have the following installed and running: - [.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) @@ -30,7 +86,7 @@ To run this project locally, you must have the following installed and running: - [Docker Desktop](https://www.docker.com/products/docker-desktop) (**Must be running** in the background) - [Ollama](https://ollama.com/) (**Must be installed** for the local AI agent) -### Setup Instructions +#### Setup Instructions 1. **Clone the repository**: ```bash @@ -67,7 +123,7 @@ To run this project locally, you must have the following installed and running: - **Admin Email**: `admin@justbigofun.local` - **Admin Password**: `Admin123!` -## Project Structure +### Project Structure - `JustBigO(Fun)/Controllers/`: MVC controllers including a dedicated `Admin` area for problem management. - `JustBigO(Fun)/Hubs/`: SignalR hubs for real-time AI code streaming. @@ -76,7 +132,7 @@ To run this project locally, you must have the following installed and running: - `JustBigO(Fun)/Data/`: EF Core context and seeders (`ProblemSeeder`, `AdminSeeder`). - `JustBigO(Fun)/Views/`: Razor views for the public interface and administrative tools. -## Development Conventions +### Development Conventions - **Surgical Updates**: Follow existing patterns for adding new features or fixing bugs. - **Validation**: Use Data Annotations for model validation. diff --git a/docs/AI_USAGE_REPORT.md b/docs/AI_USAGE_REPORT.md new file mode 100644 index 0000000..dc42780 --- /dev/null +++ b/docs/AI_USAGE_REPORT.md @@ -0,0 +1,108 @@ +# Report on the Use of AI Tools in Software Development + +**Project:** JustBigO-Fun — platform for algorithmic challenges (ASP.NET Core 9.0 MVC) +**Course:** MDS — Component B, item "Report on the use of AI tools during software development" (2 pts) +**Date:** June 2026 + +> Terminology note: AI appears on **two distinct planes** in this project, which we treat separately: +> 1. **AI as part of the product** — the agents integrated into the application (Mentor / Transpiler on Llama 3.2 via Ollama + Semantic Kernel, plus the Gemini-based generators). These are functionality, not code-writing tools. +> 2. **AI as a development tool** — the tools the team used to *build* the project (Gemini web, Cursor, Gemini CLI, Claude Code). **This report focuses mainly on plane 2**, as required. + +--- + +## 1. Team and AI Tools Used + +| Member | AI development tools | Primary way of working | +|--------|----------------------|------------------------| +| Bâcă Ionuț-Adelin | **Gemini (web)** | Conversational in the browser: snippet generation, explanations, copy-paste debugging. | +| Ștefan Rotaru | **Gemini (web)** | Conversational in the browser: writing problem descriptions, explanations, and code fragments. | +| Popescu Iulia-Maria | **Gemini (web) + Cursor** | Gemini for exploration/questions, Cursor as an AI-integrated IDE (context-aware autocomplete, inline editing, chat over files). | +| Dumitrescu Mădălina-Camelia | **Gemini CLI**, and in the final stages **Claude Code** | Agentic in the terminal, with direct access to the repo files; transition to Claude Code for the complex end-of-project tasks. | + +**Note on the evolution:** the team started with **conversational** tools (Gemini web — copy-paste answers, no code access) and gradually migrated to **agentic** tools integrated into the workflow (Cursor in the IDE; Gemini CLI and Claude Code in the terminal, with direct file access, command execution, and multi-file editing). This transition reduced the "copy-paste" overhead and improved accuracy, because the agentic tools could see the project's real context. + +--- + +## 2. Profile of Each Tool, as Used in the Project + +### Gemini (web) +- **Used by the entire team.** +- **Strengths in practice:** instant access, no setup; good for conceptual explanations, writing problem descriptions, and generating isolated fragments. +- **Limitations encountered:** does not "see" the codebase → answers that don't match the real structure; requires manual copy-paste and adaptation; easy to lose context between messages. + +### Cursor +- **Used by:** Popescu Iulia-Maria. +- **Strengths:** file-context autocomplete, inline editing, chat that "sees" the open files. Sped up writing Razor Views and UI logic. +- **Limitations:** suggestions on large files needed manual review; occasionally proposed patterns that diverged from the project's conventions. + +### Gemini CLI +- **Used by:** Dumitrescu Mădălina-Camelia. +- **Strengths:** agentic in the terminal, with access to files and commands — suited for repetitive tasks and integration with the git workflow. The `GEMINI.md` file in the repo served as persistent context/instructions for the agent. +- **Limitations:** on very complex tasks (large refactors, resolving merge conflicts) it needed step-by-step guidance. + +### Claude Code +- **Used by:** Dumitrescu Mădălina-Camelia, in the **final stages**. +- **Strengths:** strong on multi-file, high-complexity tasks at the end of the project — the Admin area overhaul (problem editor with Markdown + Monaco, test CRUD, auto-ordering), the admin dashboard with user/role management, and the stabilization of tests and timeout flows. It worked directly on the repo (reading, editing, running commands, git). +- **Limitations:** usage limits (we reserved it for complex tasks); tends to over-engineer, so it had to be constrained to "surgical" changes; architectural decisions and generated code require human verification (running tests/app) before merge. + +--- + +## 3. Use of AI Across Each Phase of the Process (mapped to the B rubric) + +### 3.1 User stories & backlog (2 pts) +- User stories were **brainstormed and refined with Gemini (web)** by Dumitrescu Mădălina-Camelia. +- AI was used to rephrase them into the standard format ("As a user, I want… so that…") and to identify acceptance criteria. + +### 3.2 Diagrams (1 pt) +- `DIAGRAMS.md` (architecture / workflow / component diagrams) was generated and clarified with AI assistance — see commit `f03c9e3 docs: improve diagrams clarity`. +- Gemini helped translate the flows (e.g., the Reflexion loop, the sandbox execution flow) into text/Mermaid diagrams. + +### 3.3 Source control with git (1 pt) +- The feature-branch flow (`feature/generic-executor-metrics`, `fix/admin-area-overhaul`, `Transpilare`, `Indicii_US12_US13`, etc.), merges, and **pull requests** (#4–#19) was supported by AI for: + - drafting commit messages and PR descriptions; + - **resolving merge conflicts** (e.g., `9e0cfae`, `f76e98d` — conflicts in `Solve.cshtml` and `ICodeExecutor.cs` resolved with AI assistance, keeping both features). +- Gemini CLI and Claude Code could run git commands directly, easing rebases and integration. + +### 3.4 Automated tests, including agent evals (2 pts) +- The suite in `JustBigO(Fun).Tests/` was generated and refined with AI: + - **Controllers:** `HomeControllerTests`, `SubmissionControllerTests`; + - **Models:** `ProblemTests`; + - **Hubs:** `TranslationHubTests` (SignalR streaming); + - **Services:** `DockerCodeExecutorTests` (TLE/OOM cases), `AgentComplexityAnalyzerTests`, `CurrentCodeCompletionServiceTests`. +- **Agent evals** (an explicit requirement): `AI/CodeTranslatorAgentTests.cs`, `GeminiHintGeneratorTests.cs`, `GeminiRefactoringSuggestionGeneratorTests.cs` — these check the structural integrity of AI-generated responses (not just "classic" code). See also commits `fa0c206` and `fac9b74`. + +### 3.5 Bug reporting and resolution via pull request (1 pt) +- Real bugs identified and fixed via PR, with AI assistance: + - "No redirect to login page" and "Grey text on dark background" → `52d065b`, PR #17 (`ui-fixes`); + - fixing tests after the resource-limit changes → `bc794ff`; + - stopping the AI query after a timeout (stability) → `bda94f0`, `452db2b`. +- AI was used both to **diagnose** the cause and to propose the fix and draft the PR. + +### 3.6 CI/CD pipeline (1 pt) +- `.github/workflows/dotnet-ci.yml` was **generated with AI** based on the project structure (build + run tests on .NET 9). See commit `fac9b74`, which introduces the CI/CD pipeline together with the automated tests. + +### 3.7 Implementation (as much working AI-written code as possible) +Significant AI-assisted/generated code contributions: +- **The "Reflexion" loop** — the agent re-reads its own compiler errors and fixes its code before displaying it (co-authored with AI). +- **Multi-language transpiler** (C# / Python / Java / C++) and the completion/hints feature. +- **SignalR integration** for real-time streaming of AI responses. +- **Docker sandbox** (`DockerCodeExecutor`, `Runner.Dockerfile`) for isolated execution, handling TLE/OOM. +- **Admin area overhaul** (problem editor with Markdown + Monaco, test CRUD, auto-ordering) and the **admin dashboard** with RBAC — built in the final stages with **Claude Code**. + +--- + +## 4. Comparative Reflections and Lessons Learned + +1. **Conversational vs. agentic.** Gemini web was excellent for exploration and learning, but costly in time (copy-paste, re-adaptation). The agentic tools (Cursor, Gemini CLI, Claude Code), having code access, produced more correct and faster changes on the real codebase. +2. **Matching tool to task.** For isolated, conceptual tasks → Gemini web. For in-IDE editing → Cursor. For terminal and git automation → Gemini CLI. For complex, multi-file, end-of-project tasks → Claude Code. +3. **Human oversight remained critical**, especially for: + - **Safety:** properly isolating the Docker sandbox. + - **Logical correctness:** the AI initially ignored cancellation tokens, which was caught and fixed to allow real timeouts. + - **Prompt engineering:** tuning the "absolute laws" in the system prompts so the agent gives **hints**, not full solutions, when only a hint is requested. +4. **Adoption curve.** Moving from Gemini web to agentic tools was the single biggest source of productivity gains in the second half of the project. + +--- + +## 5. Conclusion + +AI was present across **all phases** of the development lifecycle — from user stories and diagrams, to implementation, tests/evals, bug fixing via PR, and CI/CD. The team used a complementary mix of tools (Gemini web, Cursor, Gemini CLI, Claude Code), evolving from conversational assistance toward agentic tools integrated into the workflow. The result is a feature-rich platform delivered in considerably less time, where AI served both as a **development tool** and as an **architectural component** of the final product (the Mentor/Transpiler agents in the application). diff --git a/DIAGRAMS.md b/docs/DIAGRAMS.md similarity index 100% rename from DIAGRAMS.md rename to docs/DIAGRAMS.md diff --git a/docs/jira1.png b/docs/jira1.png new file mode 100644 index 0000000..c3bf4c0 Binary files /dev/null and b/docs/jira1.png differ diff --git a/docs/jira2.png b/docs/jira2.png new file mode 100644 index 0000000..f39efec Binary files /dev/null and b/docs/jira2.png differ