huly-platform/foundations/server/common/scripts/README.md

Coverage Scripts Documentation

This directory contains Node.js scripts for managing code coverage in the huly.server monorepo.

Scripts Overview

1. merge-coverage.js

Merges individual package coverage reports into a single LCOV file.

Usage:

node merge-coverage.js

What it does:

• Scans packages/, pods/, and tests/ directories for coverage reports
• Finds all coverage/lcov.info files
• Merges them into a single coverage/lcov.info at the root
• Resolves file paths to absolute paths
• Handles duplicate TN (test name) headers

Output:

• coverage/lcov.info - Merged coverage data

---

2. generate-coverage-html.js

Generates HTML coverage reports from LCOV data.

Usage:

node generate-coverage-html.js [input-lcov-file] [output-directory]

Default usage:

node generate-coverage-html.js coverage/lcov.info coverage/html

What it does:

• Parses LCOV format coverage data
• Uses Istanbul library to generate HTML reports
• Creates interactive HTML pages with line-by-line coverage
• Resolves source file paths
• Post-processes HTML to fix missing source code

Output:

• coverage/html/index.html - Main coverage report
• coverage/html/**/*.html - Per-file coverage reports

Dependencies:

• lcov-parse - Parses LCOV format
• istanbul-lib-coverage - Coverage map management
• istanbul-lib-report - Report context
• istanbul-reports - HTML report generation

---

3. show-coverage-summary.js

Displays a summary of coverage statistics by package.

Usage:

node show-coverage-summary.js [lcov-file]

Default usage:

node show-coverage-summary.js coverage/lcov.info

What it does:

• Parses the merged LCOV file
• Aggregates coverage by package
• Displays formatted table with:
  • Covered lines
  • Total lines
  • Coverage percentage
• Shows overall totals

Example Output:

==============================================
COVERAGE SUMMARY BY PACKAGE
==============================================

Package                     Covered     Total  Coverage
----------------------------------------------
datalake                         10        10   100.00%
minio                           111       165    67.27%
postgres                        815      1351    60.33%
...
----------------------------------------------
TOTAL                          1156      2220    52.07%

---

4. run-tests-with-coverage.js

Runs tests with coverage for all packages sequentially.

Usage:

node run-tests-with-coverage.js

What it does:

• Scans all packages in packages/ directory
• For each package with a test script:
  • Runs npm test -- --coverage --silent
  • Extracts and displays coverage summary
• Reports which packages passed/failed

Note: This is an alternative to rush test for running tests individually.

---

NPM Scripts

The package.json in this directory provides convenient aliases:

# Merge coverage reports
npm run coverage:merge

# Generate HTML report
npm run coverage:html

# Show coverage summary
npm run coverage:summary

# Run all package tests with coverage
npm run test:coverage

---

Complete Coverage Workflow

Using Rush (Recommended)

# Run all tests with coverage and generate reports
rush coverage

This command does:

1. rush test - Runs all package tests (coverage enabled by jest.config.js)
2. node scripts/merge-coverage.js - Merges all LCOV files
3. node scripts/generate-coverage-html.js - Generates HTML report

Manual Workflow

# 1. Run tests with coverage (coverage enabled in jest.config.js)
rush test

# 2. Merge coverage reports
node common/scripts/merge-coverage.js

# 3. Generate HTML report
node common/scripts/generate-coverage-html.js coverage/lcov.info coverage/html

# 4. View summary
node common/scripts/show-coverage-summary.js

---

Jest Configuration

All packages have coverage enabled by default in jest.config.js:

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testMatch: ['**/?(*.)+(spec|test).[jt]s?(x)'],
  roots: ['./src'],
  collectCoverage: true, // ✅ Enabled by default
  coverageReporters: ['text-summary', 'html', 'lcov'], // ✅ LCOV format
  coverageDirectory: 'coverage' // ✅ Output directory
}

---

Output Files

coverage/
├── lcov.info              # Merged LCOV coverage data
└── html/                  # HTML reports
    ├── index.html         # Main report page
    ├── base.css           # Styling
    ├── prettify.js        # Code highlighting
    └── [package]/         # Per-package reports
        └── [file].html    # Per-file coverage

packages/
└── [package-name]/
    └── coverage/
        ├── lcov.info      # Package-specific LCOV
        └── html/          # Package-specific HTML

---

Coverage Thresholds

Current overall coverage: 52.07%

Per-package targets:

• ✅ ≥90%: Excellent coverage
• ✅ 70-89%: Good coverage
• ⚠️ 50-69%: Moderate coverage (needs improvement)
• 🔴 <50%: Low coverage (priority improvement)

---

Troubleshooting

No LCOV files found

Error: No lcov files found in packages/pods/tests/*/coverage/lcov.info

Solution: Run tests first with rush test to generate coverage files.

Missing dependencies

Error: Cannot find module 'lcov-parse'

Solution:

cd common/scripts
npm install

Source files not found in HTML report

The scripts attempt to resolve source file paths using multiple strategies:

1. Absolute path (if exists)
2. Relative to package directory
3. Suffix match in repository

If files still can't be found, check that source files exist and paths in LCOV are correct.

---

Legacy Scripts

The following bash scripts have been replaced with Node.js versions:

• ❌ show-coverage.sh → ✅ run-tests-with-coverage.js
• ❌ show-coverage-summary.sh → ✅ show-coverage-summary.js

The bash scripts are kept for backward compatibility but the Node.js versions are recommended for better cross-platform support.

---

CI/CD Integration

The LCOV format is compatible with common coverage tools:

• Codecov: bash <(curl -s https://codecov.io/bash)
• Coveralls: cat coverage/lcov.info | coveralls
• SonarQube: Configure sonar.javascript.lcov.reportPaths=coverage/lcov.info

---

See Also

• COVERAGE_REPORT.md - Full coverage analysis
• Jest Documentation
• Istanbul Documentation