Node.js CI Standard

Nexa standard

nexa-backend and new Nexa Node.js/TypeScript services use Vitest as the unit-test runner. Jest is not part of the approved baseline. A different runner requires an approved engineering exception and migration rationale.

Biome 2.5.3 is the only approved formatter and linter. The shared workflow runs @biomejs/biome@2.5.3 check .; repositories do not add Prettier or ESLint checks.

Required stages

1. npm ci using the committed lock file.
2. Biome format validation.
3. Biome linting.
4. TypeScript strict type checking with no emit.
5. vitest run for unit tests.
6. Vitest coverage in LCOV and machine-readable test results for CI and SonarQube.
7. SonarQube maintainability and coverage analysis.
8. Semgrep, Gitleaks, and Trivy filesystem/config scanning.
9. Multi-stage Docker runtime build.
10. Trivy image scan, Syft SBOM, Cosign signing where required, and multi-registry publication.

Backend expectations

Tests cover validation, authorization, service logic, error paths, and external-client adapters. Unit tests do not call live Databricks, Snowflake, identity, LLM, or other remote services. Those boundaries are isolated behind adapters and validated later by deployed API, contract, and integration suites.

The application exposes a deterministic health endpoint. Production images exclude development dependencies and source maps unless explicitly required and protected. Graceful shutdown handles Kubernetes termination signals.

Required script contract

The repository exposes stable commands that work locally and in CI:

{
  "scripts": {
    "format:check": "biome format .",
    "lint": "biome lint . --diagnostic-level=error",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage"
  }
}

Names may be adapted during migration, but the reusable workflow contract must resolve to these capabilities.

Example caller

jobs:
  ci:
    uses: dataready-ai/nexa-ci/.github/workflows/node-ci.yml@v1
    with:
      node-version: '24'
      package-manager: npm
      test-command: npm run test
      coverage-command: npm run test:coverage
      image-name: nexa-backend
      docker-runtime-target: runtime
      ecr-repository: aws-iac-nexa-backend
      acr-repository: nexa-backend
      spcs-repository: NEXA_BACKEND_REPO
    secrets: inherit

Reporting boundary

Vitest results and LCOV coverage are source-CI evidence and feed SonarQube. Browser/E2E, deployed API, and contract suites are post-deployment evidence and do not replace the Vitest merge gate.