fix: resolve BA-106, BA-118, BA-124, BA-125 — provider resilience, social ownership, CI gates, ops docs

.github/workflows/backend-academy.yml

@@ -1,5 +1,29 @@
 name: BackendAcademy CI
 
+# Issue #692 — BA-124: Add comprehensive lint, typecheck, and CI gates
+#
+# This workflow runs on every push / PR touching BackendAcademy sources.
+# All jobs must pass before a PR can be merged.
+#
+# Job overview
+# ─────────────────────────────────────────────────
+# typecheck          TypeScript compiler check (no emit)
+# lint               ESLint on all src/** TypeScript files
+# unit-tests         Jest unit tests (*.spec.ts) in-process
+# integration-tests  Learner-journey and AI integration specs
+# build              Production nest build (must succeed after lint+types pass)
+#
+# Failure guidance
+# ─────────────────────────────────────────────────
+# typecheck:        Fix TypeScript errors reported by `npm run typecheck`.
+#                   Common causes: missing types, wrong generics, strict-null mismatches.
+# lint:             Run `npm run lint` locally. Auto-fixable issues: `npm run lint -- --fix`.
+# unit-tests:       Run `npm run test:unit` locally with NODE_ENV=test.
+#                   Check the failing spec file reported in the output.
+# integration-tests: Run `npx jest --config jest.config.ts --runInBand src/integration/learner-journey.spec.ts src/ai`
+#                   Requires no external dependencies — uses in-memory fixtures.
+# build:            Run `npm run build` locally. Usually fails when typecheck fails first.
+
 on:
   push:
     branches: [ main ]
@@ -12,13 +36,103 @@ on:
       - 'BackendAcademy/**'
       - '.github/workflows/backend-academy.yml'
 
+defaults:
+  run:
+    working-directory: BackendAcademy
+
 jobs:
+  # ─────────────────────────────────────────────
+  # 1. TypeScript type checking
+  # ─────────────────────────────────────────────
+  typecheck:
+    name: TypeScript typecheck
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: BackendAcademy/package-lock.json
+
+      - name: Install dependencies
+        # --legacy-peer-deps: joi-to-typescript (devDependency) pins joi@17
+        # while the app targets joi@18.
+        run: npm ci --no-audit --no-fund --legacy-peer-deps
+
+      - name: Run TypeScript compiler check
+        run: npm run typecheck
+
+  # ─────────────────────────────────────────────
+  # 2. Lint
+  # ─────────────────────────────────────────────
+  lint:
+    name: ESLint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: BackendAcademy/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci --no-audit --no-fund --legacy-peer-deps
+
+      - name: Run ESLint
+        run: npm run lint
+
+  # ─────────────────────────────────────────────
+  # 3. Unit tests
+  # ─────────────────────────────────────────────
+  unit-tests:
+    name: Unit tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: BackendAcademy/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci --no-audit --no-fund --legacy-peer-deps
+
+      # BA-124: Run all unit specs (*.spec.ts) isolated from integration tests.
+      # Tests run in-band to avoid shared-state flakiness from parallel workers.
+      - name: Run unit tests
+        env:
+          NODE_ENV: test
+        run: npm run test:unit
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: BackendAcademy/coverage/
+          retention-days: 7
+
+  # ─────────────────────────────────────────────
+  # 4. Integration & AI tests
+  # ─────────────────────────────────────────────
   integration-and-ai-tests:
     name: Learner journey & AI tests
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: BackendAcademy
 
     steps:
       - name: Checkout code
@@ -28,6 +142,8 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: BackendAcademy/package-lock.json
 
       - name: Install dependencies
         # --legacy-peer-deps: joi-to-typescript (devDependency) pins joi@17
@@ -41,3 +157,35 @@ jobs:
         env:
           NODE_ENV: test
         run: npx jest --config jest.config.ts --runInBand src/integration/learner-journey.spec.ts src/ai
+
+  # ─────────────────────────────────────────────
+  # 5. Production build
+  # ─────────────────────────────────────────────
+  build:
+    name: Production build
+    runs-on: ubuntu-latest
+    needs: [typecheck, lint]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: BackendAcademy/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci --no-audit --no-fund --legacy-peer-deps
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: BackendAcademy/dist/
+          retention-days: 3