Merge pull request #65 from NHSDigital/conventions

Update project conventions

Author: tvararu

.env.example

@@ -1,12 +1,12 @@
-FLASK_APP=mavis_reporting:create_app
+FLASK_APP=mavis.reporting:create_app
 FLASK_ENV=development
 # Required by Flask - used internally
 SECRET_KEY=(some random hex string)
-# Used as part of the OAuth 2.0 Authorization Code flow 
-# to identify this application to Mavis when requesting an 
+# Used as part of the OAuth 2.0 Authorization Code flow
+# to identify this application to Mavis when requesting an
 # authorization code
 CLIENT_ID=(some random hex string)
 # Used for signing / decoding-and-verifying-the-signature-of JWTs
 CLIENT_SECRET=(some random hex string)
 MAVIS_ROOT_URL=http://localhost:4000/
-SESSION_TTL_SECONDS=600
+SESSION_TTL_SECONDS=600

.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on: [push]
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # Full history is needed to scan all commits
+      - uses: jdx/mise-action@v3
+        with:
+          cache: true
+      - run: gitleaks detect --verbose --redact
+
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: jdx/mise-action@v3
+        with:
+          cache: true
+      - env:
+          SECRET_KEY: "${{ secrets.SECRET_KEY_FOR_TESTS }}"
+        run: make test
+
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: jdx/mise-action@v3
+        with:
+          cache: true
+      - run: make lint
+
+  coverage:
+    needs: [pytest]
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    outputs:
+      badge_url: ${{ steps.upload-coverage-badge-artifact-step.outputs.artifact-url }}
+      html_report_url: ${{ steps.upload-html-report-artifact-step.outputs.artifact-url }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: jdx/mise-action@v3
+        with:
+          cache: true
+      - env:
+          SECRET_KEY: "${{ secrets.SECRET_KEY_FOR_TESTS }}"
+          COVERAGE_THRESHOLD: 80
+        run: make test-coverage
+      - uses: actions/upload-artifact@v4
+        id: upload-html-report-artifact-step
+        if: always()
+        with:
+          name: coverage-html
+          path: htmlcov
+          retention-days: 10
+          compression-level: 0
+      - uses: actions/upload-artifact@v4
+        id: upload-coverage-badge-artifact-step
+        if: always()
+        with:
+          name: coverage-badge
+          path: coverage.svg
+          retention-days: 10
+          compression-level: 0

.github/workflows/deploy-application.yml

@@ -30,7 +30,7 @@ on:
         required: true
         type: string
 
-permissions: { }
+permissions: {}
 
 concurrency:
   group: deploy-mavis-${{ inputs.environment }}
@@ -95,14 +95,13 @@ jobs:
         with:
           role-to-assume: ${{ env.aws_role }}
           aws-region: eu-west-2
-      - name: Install poetry
-        run: pipx install poetry
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
       - name: Setup python
         uses: actions/setup-python@v5
         with:
           python-version: 3.13.0
-          cache: poetry
-      - run: poetry install
+      - run: uv sync --dev
       - name: Get image digest
         id: get-image-digest
         run: |
@@ -133,7 +132,7 @@ jobs:
         run: mv ${{ steps.create-task-definition.outputs.task-definition }} ${{ runner.temp }}/reporting-task-definition.json
       - name: Populate SSM parameters for reporting service
         run: |
-          poetry run scripts/populate_ssm_parameters.py ${{ inputs.environment }} reporting
+          uv run scripts/populate_ssm_parameters.py ${{ inputs.environment }} reporting
       - name: Upload artifact for reporting task definition
         uses: actions/upload-artifact@v4
         with:
@@ -151,7 +150,7 @@ jobs:
   deploy:
     name: Deploy reporting service
     runs-on: ubuntu-latest
-    needs: [ prepare-deployment, approve-deployments ]
+    needs: [prepare-deployment, approve-deployments]
     permissions:
       id-token: write
     steps:

.github/workflows/lint-and-test.yaml

@@ -13,14 +13,14 @@ __pycache__/
 .ruff_cache/
 node_modules/
 .idea/
-mavis_reporting/static/css/*
-!mavis_reporting/static/css/.keep
+mavis/reporting/static/css/*
+!mavis/reporting/static/css/.keep
 
-mavis_reporting/static/js/*
-!mavis_reporting/static/js/.keep
+mavis/reporting/static/js/*
+!mavis/reporting/static/js/.keep
 
-mavis_reporting/static/favicons/*
-!mavis_reporting/static/favicons/.keep
+mavis/reporting/static/favicons/*
+!mavis/reporting/static/favicons/.keep
 
 sentinel
 

.gitignore

@@ -1,3 +1,3 @@
-python 3.13.0
-poetry 2.1.3
-gitleaks 8.28.0
+gitleaks latest
+python 3.13
+uv latest

.tool-versions

@@ -2,30 +2,32 @@ FROM python:3.13.7-alpine AS builder
 
 WORKDIR /app
 
-ADD package.json package-lock.json pyproject.toml poetry.lock Makefile /app/
+ADD package.json package-lock.json pyproject.toml uv.lock Makefile /app/
 
 RUN apk add build-base libffi-dev npm bash curl
 
-RUN pip install poetry
-RUN make install
+RUN pip install uv
 
+ADD ./mavis/reporting /app/mavis/reporting
+ADD README.md /app/
+
+RUN uv sync --frozen --all-extras
+RUN npm install
+
+FROM builder
 
-FROM builder 
 WORKDIR /app
 
-ADD ./mavis_reporting /app/mavis_reporting
 RUN make build-assets
 
-# Create a new group `app` with Group ID `1000`.
 RUN addgroup --gid 1000 app
-# Create a new user `app`, sets home directory to `/app`, User ID `1000`, in
-# the group `app`. The `-DH` option results in a system account.
 RUN adduser app -h /app -u 1000 -G app -DH
-# Change the user for subsequent commands in Dockerfile to the user with ID
-# `1000`.
+RUN mkdir -p /app/.cache/uv && chown -R app:app /app/.cache
+RUN chown -R app:app /app/.venv
+
 USER 1000
 
 VOLUME ["/tmp", "/var/tmp", "/usr/tmp"]
 
 # pass through additional arguments like --workers=5 via GUNICORN_CMD_ARGS
-CMD ["poetry", "run", "gunicorn", "--bind", "0.0.0.0:5000", "mavis_reporting:create_app()"]
+CMD ["uv", "run", "gunicorn", "--bind", "0.0.0.0:5000", "mavis.reporting:create_app()"]

Dockerfile

@@ -11,11 +11,10 @@ clean:
 	@rm -rf .venv
 	@rm -rf __pycache__
 
-sentinel: package.json package-lock.json pyproject.toml poetry.lock
+sentinel: package.json package-lock.json pyproject.toml uv.lock
 	@echo "== Installing dependencies =="
 	@npm install || (echo "Failed to install npm dependencies"; exit 1)
-	@poetry config virtualenvs.in-project true
-	@poetry install || (echo "Failed to install Python dependencies"; exit 1)
+	@uv sync --all-extras || (echo "Failed to install Python dependencies"; exit 1)
 
 	@echo "== Copying NHSUK favicons =="
 	@make copy-nhsuk-favicons
@@ -31,22 +30,22 @@ install: sentinel
 
 .PHONY: lint
 lint: install
-	poetry run ruff check .
+	uv run ruff check .
 
 .PHONY: lint-fix
 lint-fix: install
-	poetry run ruff check --fix .
+	uv run ruff check --fix .
 
 .PHONY: dev
 dev: install
 	@echo "== Starting development servers =="
 	@echo "Press Ctrl+C to stop all processes"
-	@poetry run honcho start -f Procfile.dev
+	@uv run honcho start -f Procfile.dev
 
 .PHONY: copy-nhsuk-favicons
 copy-nhsuk-favicons:
-	mkdir -p mavis_reporting/static/favicons
-	cp -r node_modules/nhsuk-frontend/dist/nhsuk/assets/images/* mavis_reporting/static/favicons/
+	mkdir -p mavis/reporting/static/favicons
+	cp -r node_modules/nhsuk-frontend/dist/nhsuk/assets/images/* mavis/reporting/static/favicons/
 
 build-docker:
 	docker build -t ${DOCKER_IMAGE} .
@@ -57,13 +56,13 @@ run-docker:
 
 test: install
 	@echo "Running all tests .."
-	@poetry run pytest tests --verbose
+	@uv run pytest tests --verbose
 
 .PHONY: test-coverage
 test-coverage: install
 	@echo "Checking coverage on all tests .."
-	@poetry run coverage run -m  pytest tests --verbose
-	@poetry run coverage report --fail-under=${COVERAGE_THRESHOLD}
-	@poetry run coverage html
-	@poetry run coverage xml coverage.xml
-	@poetry run coverage-badge -o coverage.svg
+	@uv run coverage run -m  pytest tests --verbose
+	@uv run coverage report --fail-under=${COVERAGE_THRESHOLD}
+	@uv run coverage html
+	@uv run coverage xml coverage.xml
+	@uv run coverage-badge -o coverage.svg

Makefile

@@ -1,3 +1,3 @@
 scss: npm run build:scss:dev
 js: npm run build:js:dev
-flask: poetry run flask run --debug -p 5001
+flask: uv run flask run --debug -p 5001

Procfile.dev

@@ -21,9 +21,9 @@ A Flask-based web application for the commissioner reporting component of Mavis.
 
 2. **Install project dependencies**
 
-   This will install the project dependencies using Poetry and NPM.
+   This will install the project dependencies using uv and NPM.
 
-   Note that the Poetry virtual environment will be created in the `.venv` directory to allow IDEs to use the correct Python interpreter.
+   Note that the uv virtual environment will be created in the `.venv` directory to allow IDEs to use the correct Python interpreter.
 
    ```bash
    make install