feat: initial scaffold for cq-demo-app-002

Author: emmanuelknafo

.coverage

@@ -0,0 +1,69 @@
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+env:
+  AZURE_RG: rg-cq-demo-002
+  APP_NAME: cq-demo-app-002
+  LOCATION: canadacentral
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: prod
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Azure Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Create Resource Group
+        run: az group create --name ${{ env.AZURE_RG }} --location ${{ env.LOCATION }}
+
+      - name: Deploy Infrastructure
+        id: infra
+        run: |
+          outputs=$(az deployment group create \
+            --resource-group ${{ env.AZURE_RG }} \
+            --template-file infra/main.bicep \
+            --parameters appName=${{ env.APP_NAME }} \
+            --query 'properties.outputs' -o json)
+          echo "acrName=$(echo $outputs | jq -r '.acrName.value')" >> $GITHUB_OUTPUT
+          echo "appServiceName=$(echo $outputs | jq -r '.appServiceName.value')" >> $GITHUB_OUTPUT
+
+      - name: Build and Push to ACR
+        run: |
+          az acr build \
+            --registry ${{ steps.infra.outputs.acrName }} \
+            --image ${{ env.APP_NAME }}:${{ github.sha }} \
+            --image ${{ env.APP_NAME }}:latest \
+            .
+
+      - name: Deploy to Web App for Containers
+        uses: azure/webapps-deploy@v3
+        with:
+          app-name: ${{ steps.infra.outputs.appServiceName }}
+          images: ${{ steps.infra.outputs.acrName }}.azurecr.io/${{ env.APP_NAME }}:${{ github.sha }}
+
+      - name: Health Check
+        run: |
+          APP_URL=$(az webapp show -g ${{ env.AZURE_RG }} -n ${{ steps.infra.outputs.appServiceName }} --query defaultHostName -o tsv)
+          sleep 30
+          curl -sf --retry 5 --retry-delay 10 "https://$APP_URL/health" || exit 1
+
+      - name: Summary
+        run: |
+          APP_URL=$(az webapp show -g ${{ env.AZURE_RG }} -n ${{ steps.infra.outputs.appServiceName }} --query defaultHostName -o tsv)
+          echo "### ✅ ${{ env.APP_NAME }}" >> $GITHUB_STEP_SUMMARY
+          echo "Deployed to: https://$APP_URL" >> $GITHUB_STEP_SUMMARY

.github/workflows/deploy.yml

@@ -0,0 +1,14 @@
+# ---------- Build stage ----------
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# ---------- Runtime stage ----------
+FROM python:3.12-slim
+WORKDIR /app
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+COPY src/ ./src/
+EXPOSE 5000
+CMD ["python", "-m", "flask", "--app", "src/app", "run", "--host=0.0.0.0", "--port=5000"]

Dockerfile

@@ -0,0 +1,86 @@
+# cq-demo-app-002 — Inventory Management API (Python / Flask)
+
+A Python/Flask REST API for inventory management. This demo app contains **intentional code quality violations** for use with the Code Quality Scanner in the Agentic Accelerator Framework.
+
+## Intentional Violations
+
+| Category | File(s) | Description |
+|----------|---------|-------------|
+| **High Complexity** | `src/services/inventory_service.py` | `process_inventory_update()` has CCN > 15 with deeply nested if/elif/else for stock levels, warehouse zones, reorder thresholds, and supplier routing |
+| **High Complexity** | `src/routes/inventory.py` | `list_inventory()` has deeply nested filter logic with 7+ nesting levels |
+| **Code Duplication** | `src/services/report_service.py` ↔ `src/services/inventory_service.py` | Nearly identical aggregation logic with minor field name changes |
+| **Code Duplication** | `src/routes/reports.py` ↔ `src/routes/inventory.py` | Repeated filtering and sorting patterns |
+| **Lint — Unused Imports** | `src/utils/validators.py`, `src/services/*.py`, `src/utils/formatters.py` | `os`, `sys`, `hashlib`, `math`, `json`, `re` imported but never used |
+| **Lint — Broad Exceptions** | `src/utils/validators.py` | `except Exception:` and bare `except:` used throughout |
+| **Lint — Missing Docstrings** | `src/utils/formatters.py` | All functions lack docstrings |
+| **Lint — Naming** | `src/utils/formatters.py` | `Format_Alert_Badge()`, `FormatReorderEstimate()` violate snake_case convention |
+| **Lint — Mutable Default** | `src/utils/validators.py` | `validate_inventory_input(data, allowed_fields=[...])` uses mutable default argument |
+| **Lint — format() vs f-string** | `src/utils/formatters.py` | Uses `"{}".format()` instead of f-strings throughout |
+| **Low Coverage** | `tests/test_app.py` | Only 3 tests covering health, index, and list. Services and utils are completely untested (~30% coverage) |
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | App info |
+| GET | `/health` | Health check |
+| GET | `/api/inventory/` | List inventory (query params: `warehouse`, `zone`, `category`, `low_stock`, `sort_by`, `order`) |
+| GET | `/api/inventory/<id>` | Get item by ID |
+| POST | `/api/inventory/<id>/update` | Update stock (body: `action`, `quantity`, `reason`, `target_warehouse`, `priority`) |
+| GET | `/api/inventory/summary` | Inventory summary by warehouse |
+| GET | `/api/inventory/reorder` | Reorder recommendations |
+| GET | `/api/reports/inventory` | Inventory status report |
+| GET | `/api/reports/warehouse-utilization` | Warehouse utilization report |
+| GET | `/api/reports/supplier-performance` | Supplier performance report |
+| GET | `/api/reports/stock-alerts` | Stock alert report |
+
+## Run Locally
+
+Build and run with Docker (works in GitHub Codespaces):
+
+```bash
+docker build -t cq-demo-app-002 .
+docker run -p 5000:5000 cq-demo-app-002
+```
+
+Then open [http://localhost:5000](http://localhost:5000) to see the app info, or try:
+
+```bash
+curl http://localhost:5000/health
+curl http://localhost:5000/api/inventory/
+curl http://localhost:5000/api/inventory/1
+curl http://localhost:5000/api/inventory/summary
+curl http://localhost:5000/api/inventory/reorder
+curl http://localhost:5000/api/reports/stock-alerts
+```
+
+### Run without Docker
+
+```bash
+pip install -r requirements.txt
+python -m flask --app src/app run --host=0.0.0.0 --port=5000
+```
+
+### Run Tests
+
+```bash
+pip install -r requirements.txt
+pytest tests/ -v --cov=src --cov-report=term-missing
+```
+
+## Scanning
+
+This app is designed to produce findings with:
+
+- **Ruff** — unused imports, missing docstrings, broad exceptions, naming conventions, mutable defaults, format vs f-string
+- **Lizard** — high cyclomatic complexity (CCN > 15) in `process_inventory_update()`
+- **jscpd** — code duplication between `inventory_service.py` / `report_service.py` and `inventory.py` / `reports.py`
+- **pytest-cov** — low test coverage (< 50%)
+
+## Tech Stack
+
+- Python 3.12
+- Flask 3.x
+- pytest + pytest-cov
+- Docker (multi-stage build)
+- Azure Web App for Containers (via Bicep + ACR)

README.md

@@ -0,0 +1,72 @@
+@description('Logical app name used for resource naming')
+param appName string = 'cq-demo-app-002'
+
+@description('Azure region for all resources')
+param location string = resourceGroup().location
+
+var suffix = uniqueString(resourceGroup().id)
+var acrName = 'acr${suffix}'
+var appServicePlanName = 'plan-${appName}-${suffix}'
+var appServiceName = '${appName}-${suffix}'
+
+resource acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
+  name: acrName
+  location: location
+  sku: {
+    name: 'Basic'
+  }
+  properties: {
+    adminUserEnabled: true
+  }
+}
+
+resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
+  name: appServicePlanName
+  location: location
+  kind: 'linux'
+  sku: {
+    name: 'B1'
+    tier: 'Basic'
+  }
+  properties: {
+    reserved: true
+  }
+}
+
+resource webApp 'Microsoft.Web/sites@2023-12-01' = {
+  name: appServiceName
+  location: location
+  kind: 'app,linux,container'
+  identity: {
+    type: 'SystemAssigned'
+  }
+  properties: {
+    serverFarmId: appServicePlan.id
+    siteConfig: {
+      linuxFxVersion: 'DOCKER|${acr.properties.loginServer}/${appName}:latest'
+      appSettings: [
+        {
+          name: 'DOCKER_REGISTRY_SERVER_URL'
+          value: 'https://${acr.properties.loginServer}'
+        }
+        {
+          name: 'DOCKER_REGISTRY_SERVER_USERNAME'
+          value: acr.listCredentials().username
+        }
+        {
+          name: 'DOCKER_REGISTRY_SERVER_PASSWORD'
+          value: acr.listCredentials().passwords[0].value
+        }
+        {
+          name: 'WEBSITES_ENABLE_APP_SERVICE_STORAGE'
+          value: 'false'
+        }
+      ]
+    }
+  }
+}
+
+output acrName string = acr.name
+output acrLoginServer string = acr.properties.loginServer
+output appServiceName string = webApp.name
+output appUrl string = 'https://${webApp.properties.defaultHostName}'

infra/main.bicep

@@ -0,0 +1,21 @@
+[project]
+name = "cq-demo-app-002"
+version = "1.0.0"
+description = "Inventory Management API — Python/Flask demo app with intentional code quality violations"
+requires-python = ">=3.12"
+dependencies = [
+    "flask>=3.0,<4.0",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "D", "UP"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pyproject.toml

@@ -0,0 +1,3 @@
+flask>=3.0,<4.0
+pytest>=8.0,<9.0
+pytest-cov>=5.0,<6.0

requirements.txt

@@ -0,0 +1,31 @@
+from flask import Flask
+import os, logging
+
+from src.routes.inventory import inventory_bp
+from src.routes.reports import reports_bp
+
+
+def create_app():
+    app = Flask(__name__)
+
+    app.config["SECRET_KEY"] = "super-secret-key-hardcoded"  # noqa: S105 — Intentional: hardcoded secret
+    app.config["DEBUG"] = True  # Intentional: debug mode enabled
+
+    app.register_blueprint(inventory_bp, url_prefix="/api/inventory")
+    app.register_blueprint(reports_bp, url_prefix="/api/reports")
+
+    @app.route("/")
+    def index():
+        return {"status": "ok", "app": "cq-demo-app-002", "version": "1.0.0"}
+
+    @app.route("/health")
+    def health():
+        return {"status": "healthy"}
+
+    return app
+
+
+app = create_app()
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=5000, debug=True)