SonarQube Properties Skill

Purpose

Generate SonarQube project configuration file for code quality analysis and coverage reporting with automatic detection of test framework and coverage paths.

🚨 MANDATORY FILE COUNT

Expected Output: 1 file

• •sonar-project.properties

🔍 BEFORE GENERATING - CRITICAL RESEARCH REQUIRED

Perform these checks in order before generating the configuration:

1. •

   Application Name Detection: Use application_name parameter

   • •Format: Use application_name as-is for projectKey and projectName
   • •Placeholder: {application_name} will be replaced with actual value
   • •User Action Required: Inform user to review and update projectKey, projectName, and projectDescription after generation
2. •

   Test Framework Detection: Determine which test framework is used

   • •Check package.json dependencies:
     • •If "vitest" found → Vitest (uses coverage/lcov.info, coverage provider: v8 or istanbul)
     • •If "jest" found → Jest (uses coverage/lcov.info and coverage/clover.xml)
     • •If neither found → Default to Vitest (Vue 3 standard)
   • •Impact: Determines which coverage report paths to include
3. •

   Coverage Report Path Detection: Verify coverage output location

   • •Default: ./coverage/lcov.info (both Jest and Vitest)
   • •Additional for Jest: ./coverage/clover.xml
   • •Vitest v8 provider: Only lcov.info (no clover)
   • •Check: Verify coverage configuration in test framework config
   • •Fallback: Use standard paths if not specified
4. •

   Source Directory Detection: Verify source code location

   • •Standard: src directory
   • •Check: Verify src/ exists in project structure
   • •Alternative: If different, detect from package.json or tsconfig.json
5. •

   Coverage Exclusion Patterns: Detect files to exclude from coverage

   • •Always Exclude:
     • •Test files: src/**/*.spec.ts
     • •Entry point: src/main.ts (if exists)
   • •Conditionally Exclude (check if exists):
     • •Services: src/services/**/*.ts (API layer, tested with mocks)
     • •Router: src/**/router/*.ts (configuration, tested E2E)
     • •Store index: src/store/index.ts (setup file)
     • •Interfaces: src/**/interfaces/*.ts (type definitions only)
     • •Constants: src/**/shared/constants/**/*.ts (static data)
   • •Action: Build exclusion list based on detected files
6. •

   Language Detection: Verify primary language

   • •Standard: TypeScript (ts)
   • •Check: Look for typescript in package.json dependencies
   • •Alternative: If no TypeScript, use js
7. •

   Git Provider Detection: Determine SCM provider

   • •Default: git
   • •Check: .git directory exists
   • •Note: SonarQube property is informational
8. •

   Encoding Verification: Confirm source file encoding

   • •Standard: UTF-8
   • •Note: Modern projects always use UTF-8

Execution Checklist

Execute in this order:

• • 1. Get application_name from configuration parameters
• • 2. Detect test framework (Vitest vs Jest) from package.json
• • 3. Determine coverage report paths based on test framework
• • 4. Verify src/ directory exists
• • 5. Detect which files/directories exist for coverage exclusions:
  • • src/main.ts
  • • src/services/ directory
  • • src/**/router/ directories
  • • src/store/index.ts
  • • src/**/interfaces/ directories
  • • src/**/shared/constants/ directories
• • 6. Build coverage.exclusions list from detected patterns
• • 7. Verify TypeScript is used (check package.json)
• • 8. Generate sonar-project.properties with detected configuration
• • 9. Run validation script to confirm file exists and properties are valid
• • 10. IMPORTANT: Notify user to review projectKey, projectName, and projectDescription

Output

Primary Format: sonar-project.properties

For Vitest Projects (recommended):

sonar.projectKey={application_name}
sonar.projectName={application_name}
sonar.projectDescription=Vue 3 application for {application_name}
sonar.sources=src
sonar.language=ts
sonar.sourceEncoding=UTF-8
sonar.scm.provider=git
sonar.qualitygate.wait=true
sonar.javascript.lcov.reportPaths=./coverage/lcov.info
sonar.tests=src
sonar.test.inclusions=src/**/*.spec.ts
sonar.exclusions=src/**/*.spec.ts
sonar.coverage.exclusions=src/main.ts,src/services/**/*.ts,src/**/router/*.ts

For Jest Projects:

sonar.projectKey={application_name}
sonar.projectName={application_name}
sonar.projectDescription=Vue 3 application for {application_name}
sonar.sources=src
sonar.language=ts
sonar.sourceEncoding=UTF-8
sonar.scm.provider=git
sonar.qualitygate.wait=true
sonar.javascript.lcov.reportPaths=./coverage/lcov.info
sonar.clover.reportPaths=./coverage/clover.xml
sonar.tests=src
sonar.test.inclusions=src/**/*.spec.ts
sonar.exclusions=src/**/*.spec.ts
sonar.coverage.exclusions=src/main.ts,src/services/**/*.ts,src/**/router/*.ts

Key Difference: Jest includes sonar.clover.reportPaths, Vitest does not.

🛑 BLOCKING VALIDATION CHECKPOINT

After generating the file, run this validation:

#!/bin/bash

# Validate sonar-project.properties exists
if [ ! -f "sonar-project.properties" ]; then
  echo "✗ ERROR: sonar-project.properties not found"
  exit 1
fi

echo "✓ Found: sonar-project.properties"

# Validate required properties exist
REQUIRED_PROPS=(
  "sonar.projectKey"
  "sonar.projectName"
  "sonar.sources"
  "sonar.language"
  "sonar.sourceEncoding"
  "sonar.qualitygate.wait"
  "sonar.javascript.lcov.reportPaths"
  "sonar.tests"
  "sonar.test.inclusions"
  "sonar.exclusions"
  "sonar.coverage.exclusions"
)

MISSING_PROPS=()
for prop in "${REQUIRED_PROPS[@]}"; do
  if ! grep -q "^$prop=" sonar-project.properties; then
    MISSING_PROPS+=("$prop")
  fi
done

if [ ${#MISSING_PROPS[@]} -gt 0 ]; then
  echo "✗ ERROR: Missing required properties:"
  printf '  - %s\n' "${MISSING_PROPS[@]}"
  exit 1
fi

# Validate coverage report paths exist or are configured
LCOV_PATH=$(grep "^sonar.javascript.lcov.reportPaths=" sonar-project.properties | cut -d'=' -f2)
if [ -z "$LCOV_PATH" ]; then
  echo "✗ ERROR: Missing LCOV report path"
  exit 1
fi

# Check for test framework specific paths
if grep -q "vitest" package.json; then
  echo "✓ Detected Vitest - LCOV only"
  if grep -q "sonar.clover.reportPaths" sonar-project.properties; then
    echo "⚠️ WARNING: Vitest detected but clover path included (Jest-specific)"
  fi
elif grep -q "jest" package.json; then
  echo "✓ Detected Jest - LCOV + Clover"
  if ! grep -q "sonar.clover.reportPaths" sonar-project.properties; then
    echo "⚠️ WARNING: Jest detected but clover path missing"
  fi
fi

# Validate sources directory exists
SOURCES_DIR=$(grep "^sonar.sources=" sonar-project.properties | cut -d'=' -f2)
if [ ! -d "$SOURCES_DIR" ]; then
  echo "✗ ERROR: Sources directory not found: $SOURCES_DIR"
  exit 1
fi

echo "✓ Sources directory exists: $SOURCES_DIR"

# Validate language is set correctly
LANGUAGE=$(grep "^sonar.language=" sonar-project.properties | cut -d'=' -f2)
if [ "$LANGUAGE" != "ts" ] && [ "$LANGUAGE" != "js" ]; then
  echo "✗ ERROR: Invalid language: $LANGUAGE (expected 'ts' or 'js')"
  exit 1
fi

echo "✓ Language: $LANGUAGE"

# Validate encoding
ENCODING=$(grep "^sonar.sourceEncoding=" sonar-project.properties | cut -d'=' -f2)
if [ "$ENCODING" != "UTF-8" ]; then
  echo "⚠️ WARNING: Non-standard encoding: $ENCODING (expected 'UTF-8')"
fi

# Validate exclusions are properly formatted (no spaces after commas in list)
EXCLUSIONS=$(grep "^sonar.coverage.exclusions=" sonar-project.properties | cut -d'=' -f2)
if [[ "$EXCLUSIONS" =~ ", " ]]; then
  echo "⚠️ WARNING: Coverage exclusions contain spaces after commas (should be comma-separated without spaces)"
fi

echo ""
echo "✓ SonarQube configuration validation passed"
echo ""
echo "⚠️ IMPORTANT: Please review and update the following properties:"
echo "   - sonar.projectKey (currently: $(grep '^sonar.projectKey=' sonar-project.properties | cut -d'=' -f2))"
echo "   - sonar.projectName (currently: $(grep '^sonar.projectName=' sonar-project.properties | cut -d'=' -f2))"
echo "   - sonar.projectDescription (currently: $(grep '^sonar.projectDescription=' sonar-project.properties | cut -d'=' -f2))"

Validation Requirements:

1. •✅ File sonar-project.properties exists
2. •✅ All required properties present
3. •✅ Coverage report paths configured based on test framework
4. •✅ Sources directory exists
5. •✅ Language is valid (ts or js)
6. •✅ Encoding is UTF-8
7. •⚠️ Coverage exclusions properly formatted (no spaces)
8. •⚠️ User notified to review projectKey, projectName, projectDescription

Template Reference

See: examples.md in this directory for:

• •Complete sonar-project.properties examples (Vitest and Jest variants)
• •Detailed property explanations with why each is configured
• •Test framework detection guide
• •Coverage path verification commands
• •Common issues and troubleshooting
• •Property customization guide

Notes

Key Features

• •Automatic Test Framework Detection: Vitest vs Jest from package.json
• •Dynamic Coverage Paths: Adapts to test framework capabilities
• •Smart Exclusions: Only excludes files that exist in project
• •Application Name Integration: Uses configured application_name parameter
• •User Review Required: Notifies user to update project metadata

Property Essentials

• •projectKey/projectName: Uses application_name, user must review
• •projectDescription: Generic description, user should customize
• •sources: Always src (standard Vue project structure)
• •language: ts for TypeScript projects
• •sourceEncoding: Always UTF-8 (modern standard)
• •scm.provider: git (standard version control)
• •qualitygate.wait: true (wait for quality gate results)

Coverage Configuration

• •LCOV: Universal format supported by both Jest and Vitest
• •Clover: Jest-specific XML format (not used by Vitest)
• •Test Inclusions: src/**/*.spec.ts (all test files)
• •Source Exclusions: Test files excluded from analysis
• •Coverage Exclusions: Entry points, services, routers, config files

Coverage Exclusion Philosophy

• •Test Files: No runtime code, shouldn't count toward coverage
• •Entry Point (main.ts): Application bootstrap, tested through E2E
• •Services: API layer, tested with mocks, not unit testable
• •Router: Configuration files, tested through E2E navigation
• •Store Index: Setup/configuration, not meaningful to unit test
• •Interfaces: TypeScript type definitions only, no runtime code
• •Constants: Static data, no logic to test

Test Framework Differences

• •Vitest: Modern, Vue 3 recommended, v8 or istanbul coverage, LCOV only
• •Jest: Legacy but widely used, multiple coverage formats (LCOV + Clover)
• •Detection: Check package.json dependencies for framework presence
• •Default: Assume Vitest if neither found (Vue 3 standard)

Quality Gate Configuration

• •qualitygate.wait=true: CI/CD pipeline waits for SonarQube analysis
• •Purpose: Prevent merging code that fails quality standards
• •Timeout: Controlled by SonarQube server configuration
• •Impact: CI/CD build may fail if quality gate not passed

Maintenance Considerations

• •SonarQube Version: Properties may change between SonarQube versions
• •Coverage Formats: Verify test framework still generates expected formats
• •Path Changes: Update if project structure changes
• •New Exclusions: Add patterns as project grows
• •Property Deprecation: Monitor SonarQube release notes

Common Customizations

• •Organization Key: Add sonar.organization for SonarCloud
• •Branch Analysis: Add sonar.branch.name for branch-specific analysis
• •PR Analysis: Add PR-specific properties for pull request decoration
• •Authentication: Add sonar.login token (usually in CI/CD environment)
• •Additional Exclusions: Extend based on project needs