feat: add CI coverage gate, data model docs, and README update

.github/workflows/CI.yaml

@@ -105,6 +105,153 @@ jobs:
         run: cargo build --all --verbose
 
   # ─────────────────────────────────────────────
+  coverage:
+    name: Contract Coverage (>= 80%)
+    runs-on: ubuntu-latest
+    needs: build
+    defaults:
+      run:
+        working-directory: contracts
+    env:
+      CARGO_TERM_COLOR: always
+      RUSTUP_TOOLCHAIN: stable
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust toolchain (with LLVM tools for tarpaulin)
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: llvm-tools-preview
+      - name: Install cargo-binstall
+        run: curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
+      - name: Install cargo-tarpaulin (pre-built binary)
+        run: cargo binstall cargo-tarpaulin -y
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            contracts/target
+          key: ${{ runner.os }}-cargo-coverage-${{ hashFiles('''contracts/Cargo.lock''') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-coverage-
+            ${{ runner.os }}-cargo-
+      - name: Run per-crate coverage (fail under 80%)
+        run: |
+          set -euo pipefail
+          mkdir -p ../coverage/contracts
+          echo "# Contract coverage report" > ../coverage/contracts/SUMMARY.md
+          OVERALL_STATUS=0
+          # Soroban contracts compile to wasm32/cdylib but their tests run on
+          # the host (x86_64). `--engine llvm` instruments the host test
+          # binaries; requires the llvm-tools-preview component installed above.
+          for crate in access_control common_types manage_hub membership_token payment_escrow resource_credits workspace_booking; do
+            if [ ! -f "$crate/Cargo.toml" ]; then
+              echo "::warning::Skipping missing crate $crate"
+              continue
+            fi
+            echo ""
+            echo ""
+            echo "========================================================"
+            echo " Coverage for crate: $crate"
+            echo "========================================================"
+            if ! cargo tarpaulin \
+                --manifest-path "$crate/Cargo.toml" \
+                --engine llvm \
+                --timeout 300 \
+                --fail-under 80 \
+                --out Xml Stdout \
+                --output-dir "../coverage/contracts/$crate"; then
+              echo "::error file=$crate::Coverage for $crate is below 80% (or tarpaulin failed)."
+              OVERALL_STATUS=1
+            fi
+          done
+          if [ "$OVERALL_STATUS" -ne 0 ]; then
+            echo "::error::One or more contract crates fell below the 80% coverage threshold."
+            exit 1
+          fi
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: contract-coverage
+          path: coverage/contracts
+          if-no-files-found: ignore
+
+      - name: Upload coverage to Codecov (contracts)
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          directory: ../coverage/contracts
+          flags: contracts
+          fail_ci_if_error: true
+          verbose: true
+
+  # ─────────────────────────────────────────────
+  # NO PLACEHOLDER TESTS
+  # Fails if any test file contains placeholder-style content or filenames.
+  # Placeholder tests (e.g. expect(1+1).toBe(2)) are often created as
+  # scaffolding and accidentally committed.
+  # ─────────────────────────────────────────────
+  no-placeholders:
+    name: No Placeholder Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check for placeholder test files
+        run: |
+          set -euo pipefail
+          HAS_PLACEHOLDER=false
+
+          # Check 1: Filename-based — flag files with "placeholder" or "template"
+          # in the name that look like test files.
+          # Exclude node_modules/ to avoid false positives from dependency files.
+          MATCHES_BY_NAME=$(find . -type f -not -path '*/node_modules/*' \
+            \( -name '*placeholder*' -o -name '*template*' \) \
+            \( -name '*.test.*' -o -name '*.spec.*' \) 2>/dev/null || true)
+
+          if [ -n "$MATCHES_BY_NAME" ]; then
+            echo "::error::Test files with placeholder/template in filename:"
+            echo "$MATCHES_BY_NAME" | sed 's/^/  /'
+            HAS_PLACEHOLDER=true
+          fi
+
+          # Check 2: Content-based — flag test files whose describe() or it()
+          # description suggests a placeholder or template.
+          if command -v rg &>/dev/null; then
+            MATCHES_BY_CONTENT=$(
+              rg -l \
+                --glob '*.test.*' \
+                --glob '*.spec.*' \
+                -e 'describe\(("placeholder"|'"'"'placeholder'"'"'|"template"|'"'"'template'"'"')' \
+                -e 'it\(("should pass"|'"'"'should pass'"'"'|"is a placeholder"|'"'"'is a placeholder'"'"')' \
+                2>/dev/null || true
+            )
+          else
+            # fallback to grep
+            MATCHES_BY_CONTENT=$(
+              grep -rl \
+                --include='*.test.*' \
+                --include='*.spec.*' \
+                -E "describe\(\"placeholder\"|describe\('placeholder'|describe\(\"template\"|describe\('template'|it\(\"should pass\"|it\('should pass'|it\(\"is a placeholder\"|it\('is a placeholder'" \
+                2>/dev/null || true
+            )
+          fi
+
+          if [ -n "$MATCHES_BY_CONTENT" ]; then
+            echo "::error::Test files with placeholder-style descriptions:"
+            echo "$MATCHES_BY_CONTENT" | sed 's/^/  /'
+            HAS_PLACEHOLDER=true
+          fi
+
+          if [ "$HAS_PLACEHOLDER" = true ]; then
+            echo ""
+            echo "::error::Placeholder test files detected — remove or replace them with real tests."
+            exit 1
+          fi
+
+          echo "  No placeholder test files found."
+
   # SEMGREP — Reentrancy guard enforcement
   # (TEMPORARILY DISABLED — uncomment to re-enable)
   # ─────────────────────────────────────────────
@@ -165,8 +312,17 @@ jobs:
       - name: Build (TypeScript check)
         run: npm run build
 
-      - name: Unit tests
-        run: npm run test -- --passWithNoTests
+      - name: Unit tests with coverage
+        run: npm run test:cov -- --passWithNoTests
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage/lcov.info
+          flags: backend
+          fail_ci_if_error: true
+          verbose: true
 
   # ─────────────────────────────────────────────
   # FRONTEND — Next.js
@@ -196,7 +352,155 @@ jobs:
       - name: Lint
         run: npm run lint
 
+      - name: Tests with coverage
+        run: npm run test:cov
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage/lcov.info
+          flags: frontend
+          fail_ci_if_error: true
+          verbose: true
+
       - name: Build
         run: npm run build
         env:
           NEXT_PUBLIC_API_URL: http://localhost:3001
+
+  # ─────────────────────────────────────────────
+  # DATA-MODEL SYNC CHECK
+  # Fails the build if any TypeORM entity file or migration is modified
+  # without updating backend/docs/data-model.md.
+  # See https://github.com/NovaCoreLabs1/NovaLabs/issues/140
+  # ─────────────────────────────────────────────
+  verify-data-model:
+    name: Verify Data Model Sync
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Detect entity/migration changes without doc update
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PUSH_BASE_SHA: ${{ github.event.before }}
+        run: |
+          set -euo pipefail
+          # Determine which commits to diff against depending on event type.
+          # - For pull_request: compare PR head against the PR's base SHA.
+          # - For push (incl. merges): compare HEAD against the previous SHA.
+          # - Fallback (e.g. workflow_dispatch): skip the check.
+          case "$EVENT_NAME" in
+            pull_request)
+              BASE_SHA="$PR_BASE_SHA"
+              ;;
+            push)
+              BASE_SHA="$PUSH_BASE_SHA"
+              ;;
+            *)
+              echo "Skipping data-model sync check for event: $EVENT_NAME"
+              exit 0
+              ;;
+          esac
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "::warning::No base SHA available; skipping data-model sync check."
+            exit 0
+          fi
+          git fetch --no-tags --depth=1 origin "$BASE_SHA"
+          ENTITY_CHANGED="$(git diff --name-only "$BASE_SHA"...HEAD | grep -E '(^|/)entities/.*\.entity\.ts$' || true)"
+          MIGRATION_CHANGED="$(git diff --name-only "$BASE_SHA"...HEAD | grep -E '(^|/)migrations/.*\.ts$' || true)"
+          DOC_CHANGED="$(git diff --name-only "$BASE_SHA"...HEAD | grep -E '(^|/)backend/docs/data-model\.md$' || true)"
+          SCHEMA_CHANGED="$ENTITY_CHANGED$MIGRATION_CHANGED"
+          if [ -n "$SCHEMA_CHANGED" ] && [ -z "$DOC_CHANGED" ]; then
+            {
+              echo "::error::TypeORM entities or migrations were modified but backend/docs/data-model.md was not updated."
+              echo "::error::Files changed:"
+              [ -n "$ENTITY_CHANGED" ] && printf '::error file=%s::Entity file changed without docs update\n' $ENTITY_CHANGED
+              [ -n "$MIGRATION_CHANGED" ] && printf '::error file=%s::Migration file changed without docs update\n' $MIGRATION_CHANGED
+              echo "::error::Please update backend/docs/data-model.md to keep the ER diagram and field reference in sync."
+            }
+            exit 1
+          fi
+          echo "No entity/migration/doc sync issues detected."
+          if [ -n "$SCHEMA_CHANGED" ]; then
+            echo "Schema files changed (and docs updated):"
+            printf '  %s\n' $SCHEMA_CHANGED
+          fi
+
+  # ─────────────────────────────────────────────
+  # AUTO-GENERATE ER DIAGRAM (erdia)
+  # Regenerates the Mermaid ER diagram from TypeORM entities and fails
+  # if the generated output differs from what is committed. Developers
+  # run `npm run db:diagram` locally after entity changes.
+  # See https://github.com/NovaCoreLabs1/NovaLabs/issues/140
+  # ─────────────────────────────────────────────
+  generate-er-diagram:
+    name: Generate ER Diagram
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    defaults:
+      run:
+        working-directory: backend
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: novalabs
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d novalabs"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: backend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate ER diagram with erdia
+        run: npm run db:diagram
+        env:
+          DATABASE_HOST: localhost
+          DATABASE_PORT: 5432
+          DATABASE_USERNAME: postgres
+          DATABASE_PASSWORD: password
+          DATABASE_NAME: novalabs
+
+      - name: Check generated docs match committed version
+        run: |
+          OUTPUT_DIR="docs/erd"
+          if [ -d "$OUTPUT_DIR" ]; then
+            CHANGES="$(git status --porcelain -- "$OUTPUT_DIR/" 2>/dev/null || true)"
+            if [ -z "$CHANGES" ]; then
+              echo "Generated ER diagram matches committed version."
+            else
+              echo "Generated ER diagram differs from committed version."
+              echo "   Run 'npm run db:diagram' locally and commit the changes."
+              echo ""
+              git status -- "$OUTPUT_DIR/"
+              exit 1
+            fi
+          else
+            echo "erdia output directory not found - run erdia locally first."
+            echo "   npm run db:diagram"
+            echo "   Then commit the docs/erd/ directory."
+          fi

.gitignore

@@ -0,0 +1,60 @@
+# dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# testing
+coverage/
+.nyc_output/
+
+# next.js
+.next/
+out/
+
+# production
+build/
+dist/
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.idea/
+*.swp
+*.swo
+*~
+
+# TypeScript
+*.tsbuildinfo
+
+# Stryker temp files
+.stryker-tmp
+
+# Logs
+logs/
+*.log
+
+# Stryker mutation testing output
+reports/
+
+# OS files
+Thumbs.db