@freshworks/shiftleft-tools 1.1.8

package/templates/jenkins/Jenkinsfile-node.groovy

@@ -0,0 +1,450 @@
+#!groovy
+
+utilObj = new Utils()
+
+pipeline {
+
+    agent {
+        kubernetes {
+            yaml k8sPodTemplate(pod: 'jnlp+node+dind24')
+            defaultContainer 'node-base'
+        }
+    }
+
+    // Artifacts will be retained 10 days or 50 builds
+    options {
+        buildDiscarder(logRotator(numToKeepStr: '10', artifactNumToKeepStr: '50'))
+        disableConcurrentBuilds()
+    }
+
+    environment {
+        NODE_VERSION = utilObj.getNodeVersionFromPackageJSON()
+    }
+
+    parameters {
+        choice(choices: 'dev\nstaging\nproduction', description: '', name: 'deployTo')
+        string(name: 'image_version', defaultValue: '', description: 'Image version for Staging/Production deployment [Recommended]')
+    }
+
+    stages {
+        stage('Checkout & Setup') {
+            when {
+                expression {
+                    params.deployTo == 'dev'
+                }
+            }
+            steps {
+                checkoutCode(env.NODE_VERSION)
+            }
+        }
+
+        stage ('Code Sanity') {
+            when {
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                doCodeSanity(env.NODE_VERSION)
+            }
+        }
+
+        stage ('Unit Tests') {
+            when {
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                runUnitTests(env.NODE_VERSION)
+            }
+        }
+
+        stage ('Mutation Tests') {
+            when {
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                script {
+                    // Full scan (all scoped files) for CI — local dev uses "since" mode (changed files only)
+                    utilObj.runCmd('yarn install --ignore-engines && yarn mutation-tests:full', env.NODE_VERSION)
+                }
+            }
+            post {
+                always {
+                    publishHTML([
+                        allowMissing: true,
+                        alwaysLinkToLastBuild: true,
+                        keepAll: true,
+                        reportDir: 'coverage/mutation',
+                        reportFiles: 'index.html',
+                        reportName: 'Stryker Mutation Report',
+                        reportTitles: 'Mutation testing (full scan)'
+                    ])
+                }
+            }
+        }
+
+        stage ('Integration Tests') {
+            when {
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                runIntegrationTests(env.NODE_VERSION)
+            }
+        }
+
+        stage('SonarQube analysis') {
+            when {
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                runSonarQubeAnalysis()
+            }
+        }
+
+        // Shift-left Postman (isoforge + Newman), API coverage matrix, and combined quality report.
+        stage('Staging Postman, API Coverage & Quality Report') {
+            when {
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                script {
+                    runShiftLeftStagingPostman()
+                }
+                script {
+                    sh """
+                        set -e
+                        # Library scripts are staged from the shiftleft-tools package (gitignored cache)
+                        shiftleft stage-scripts
+                        # Adjust routes dir to match your actual route/controller dir (src/controllers, src/routes, etc.)
+                        ./postman/scripts/report-generators/node-api-coverage-matrix.sh ./src/controllers ./postman
+                    """
+                }
+                script {
+                    generateQualityReport()
+                }
+            }
+            post {
+                always {
+                    publishHTML([
+                        allowMissing: true,
+                        alwaysLinkToLastBuild: true,
+                        keepAll: true,
+                        reportDir: 'postman/reports',
+                        reportFiles: 'api-coverage-matrix-latest.html',
+                        reportName: 'API Coverage Matrix',
+                        reportTitles: 'Postman vs Express route coverage'
+                    ])
+                }
+            }
+        }
+
+        stage ('Build') {
+            when {
+                branch 'master'
+                expression {
+                    params.deployTo == 'dev' && params.image_version == ''
+                }
+            }
+            steps {
+                buildProject(env.NODE_VERSION, '', false)
+            }
+        }
+
+        stage('Security Tests') {
+            when {
+                expression {
+                    params.deployTo == 'dev'
+                }
+            }
+            steps {
+                runSecurityTests('SERVICE_NAME')
+            }
+        }
+
+        stage ('Promote Image') {
+            when {
+                branch 'master'
+                expression {
+                    params.deployTo == 'production'
+                }
+            }
+            steps {
+                promote('SERVICE_NAME', false, params.image_version)
+            }
+        }
+
+        stage ('Deploy Image') {
+            when {
+                branch 'master'
+            }
+            steps {
+                deployArgo(params.deployTo, 'SERVICE_NAME', params.image_version)
+            }
+        }
+    }
+
+    post {
+        always {
+            sendEmail()
+            deleteDir()
+        }
+    }
+}
+
+/**
+ * Shift-left: build PR image (tag from shiftleftBuildLabels), isoforge shiftleft_feature_stack for SERVICE_NAME,
+ * run Postman against staging with routing header to isolation pod, publish reports, teardown.
+ * Gate: PR comment body must start with "shiftleft"
+ * Replace ISO_HEADER and ISO_HEADER_VALUE with values from isoforge header_map for this service.
+ */
+// Ensure the shiftleft CLI is installed. `shiftleft stage-scripts` / run-all.sh
+// (which execs `shiftleft test`) stage the library scripts from the package, so
+// CI agents need the CLI. Idempotent. Requires a Jenkins "Secret text" credential
+// (id below) holding the Nexus npm basic-auth token, i.e. the value for
+// //nexuscentral.runwayci.com/repository/npm-group/:_auth=  (base64 of user:pass).
+def ensureShiftleftCli() {
+    withCredentials([string(credentialsId: 'nexus-npm-auth', variable: 'NEXUS_NPM_AUTH')]) {
+        sh '''#!/bin/bash --login
+            set -e
+            if ! command -v shiftleft >/dev/null 2>&1; then
+                echo "//nexuscentral.runwayci.com/repository/npm-group/:_auth=${NEXUS_NPM_AUTH}" >> "$HOME/.npmrc"
+                npm install -g shiftleft-tools \
+                    --registry=https://nexuscentral.runwayci.com/repository/npm-group/ --prefer-online
+            fi
+        '''
+    }
+}
+
+def runShiftLeftStagingPostman() {
+    ensureShiftleftCli()
+    def buildCause = ''
+    def latestArgoSha = ''
+    def serviceName = utilObj.getK8ServiceName(utilObj.getRepoName())
+    // Replace with your service's isoforge routing header and account ID
+    def isoRouteHeader = 'ISO_HEADER'
+    def isoRouteValue = 'ISO_HEADER_VALUE'
+
+    try {
+        def causes = currentBuild.rawBuild.getCauses()
+        if (causes && causes.size() > 0) {
+            def cause = causes[0]
+            if (cause?.class?.toString()?.contains('GitHubPullRequestCommentCause')) {
+                buildCause = cause.getCommentBody() ?: ''
+            }
+            cause = null
+        }
+    } catch (Exception e) {
+        echo "Could not get build cause: ${e.message}"
+    }
+
+    echo "Build Cause = ${buildCause}"
+    echo "K8s service (isoforge/Argo): ${serviceName}"
+    if (!buildCause.startsWith('shiftleft')) {
+        echo 'Branch build with no intention of shift left integration test.'
+        return
+    }
+
+    lock('SERVICE_NAME-postman-stage') {
+        def sl = shiftleftBuildLabels()
+        def branchNameSetup = "${sl.gitBranchBase}/${serviceName}-shiftleftFeatureStack"
+        def branchNameTeardown = "${sl.gitBranchBase.replace('iso-setup-', 'iso-teardown-')}/${serviceName}-shiftleftFeatureStack"
+        def imageTag = sl.imageTag
+
+        echo "gitBranchBase: ${sl.gitBranchBase} imageTag: ${imageTag}"
+        echo "Branch setup: ${branchNameSetup}  teardown: ${branchNameTeardown}"
+        echo "Building image for isolation (tag: ${imageTag})"
+        buildProject(env.NODE_VERSION, '', false, imageTag)
+
+        // SECURITY: GH_TOKEN only exposed to git/gh commands
+        withCredentials([string(credentialsId: 'GITHUB_RUNWAYCI_TOKEN', variable: 'GH_TOKEN')]) {
+            utilObj.runCmd("""
+                set -euo pipefail
+                git clone git@github.com:freshdesk/freshapps-k8s.git
+                cd freshapps-k8s
+                isoforge version
+                git checkout -b ${branchNameSetup}
+
+                isoforge setup \\
+                    --service ${serviceName} \\
+                    --namespace shiftleft_feature_stack \\
+                    --imageTag ${imageTag} \\
+                    --header ${isoRouteHeader} \\
+                    --headerValue ${isoRouteValue}
+
+                if [[ -n "\$(git status --porcelain)" ]]; then
+                    git add .
+                    git commit -m "Isolation setup for ${serviceName} in shiftleftFeatureStack"
+                    git push origin ${branchNameSetup}
+                else
+                    echo "No changes to commit, check previous steps"
+                    exit 1
+                fi
+
+                gh pr create \\
+                    --title "Staging Isoforge-${BUILD_NUMBER} ${serviceName} shiftleftFeatureStack" \\
+                    --body "Isolation setup for ${serviceName} in shiftleftFeatureStack" \\
+                    --base main \\
+                    --head ${branchNameSetup}
+
+                gh pr merge ${branchNameSetup} \\
+                    --squash \\
+                    --admin
+
+                git checkout main
+                git pull origin main
+            """, NODE_VERSION)
+
+            latestArgoSha = sh(returnStdout: true, script: '''
+                cd freshapps-k8s && git rev-parse HEAD
+            ''').trim()
+        }
+        echo "Latest SHA (freshapps-k8s) after setup = ${latestArgoSha}"
+
+        withCredentials([string(credentialsId: 'ARGO_API_TOKEN', variable: 'ARGO_API_TOKEN')]) {
+            utilObj.runCmd("""
+                argoapi application --revision ${latestArgoSha} --service ${serviceName} \\
+                    --namespace NAMESPACE
+            """, NODE_VERSION)
+        }
+
+        // IRSA on the pod supplies AWS for Secrets Manager access
+        updateShiftLeftStatus('pending')
+        try {
+            utilObj.runCmd("""
+                set -euo pipefail
+                cd postman
+                npm ci --ignore-scripts
+                npm audit --audit-level=critical 2>&1 || echo "WARNING: audit found issues"
+                npm audit signatures 2>&1 || echo "WARNING: signature verification failed"
+                npm audit --json > ../audit-report.json 2>&1 || true
+                # Library scripts are staged from the shiftleft-tools package (gitignored cache)
+                shiftleft stage-scripts
+                ./scripts/run-tests.sh staging
+            """, NODE_VERSION)
+            echo 'Shift left Postman tests completed'
+            updateShiftLeftStatus('success', '/PostmanTestReport-ShiftLeft/')
+        } catch (Exception e) {
+            updateShiftLeftStatus('failure', '/PostmanTestReport-ShiftLeft/')
+            echo "Staging Postman tests failed: ${e.getMessage()}"
+            currentBuild.result = 'UNSTABLE'
+        }
+
+        archiveArtifacts artifacts: 'audit-report.json', allowEmptyArchive: true
+
+        if (fileExists('postman/reports')) {
+            publishHTML([
+                allowMissing: true,
+                alwaysLinkToLastBuild: true,
+                keepAll: true,
+                reportDir: 'postman/reports',
+                reportFiles: 'consolidated-staging-*.html',
+                reportName: 'PostmanTestReport-ShiftLeft',
+                reportTitles: 'SERVICE_NAME Staging (Isoforge) Postman'
+            ])
+        } else {
+            echo 'postman/reports missing, skipping HTML report publication'
+        }
+
+        withCredentials([string(credentialsId: 'GITHUB_RUNWAYCI_TOKEN', variable: 'GH_TOKEN')]) {
+            utilObj.runCmd("""
+                set -euo pipefail
+                cd freshapps-k8s
+                git pull origin main
+                git checkout -b ${branchNameTeardown}
+
+                isoforge teardown \\
+                    --service ${serviceName} \\
+                    --namespace shiftleft_feature_stack
+
+                if [[ -n "\$(git status --porcelain)" ]]; then
+                    git add .
+                    git commit -m "Teardown ${serviceName} in shiftleftFeatureStack"
+                    git push origin ${branchNameTeardown}
+                else
+                    echo "No changes to commit for teardown, check previous steps"
+                    exit 1
+                fi
+
+                gh pr create \\
+                    --title "Staging Isoforge-Teardown-${BUILD_NUMBER} ${serviceName}" \\
+                    --body "Isolation teardown for ${serviceName} in shiftleftFeatureStack" \\
+                    --base main \\
+                    --head ${branchNameTeardown}
+
+                gh pr merge ${branchNameTeardown} \\
+                    --squash \\
+                    --admin
+            """, NODE_VERSION)
+        }
+
+        withCredentials([string(credentialsId: 'ARGO_API_TOKEN', variable: 'ARGO_API_TOKEN')]) {
+            utilObj.runCmd("""
+                argoapi sync
+            """, NODE_VERSION)
+        }
+    }
+}
+
+def generateQualityReport() {
+    ensureShiftleftCli()
+    echo "Generating Combined Quality Report..."
+    try {
+        utilObj.runCmd("""
+            set -euo pipefail
+            cd postman/scripts
+
+            # Stage Stryker/nyc HTML under postman/reports/artifacts for relative links in quality report
+            ./stage-report-artifacts.sh "\${WORKSPACE}" "\${WORKSPACE}/postman/reports" || true
+
+            # Generate combined report — reuses existing results from prior stages:
+            #   --skip-unit      reuses unit test results from Unit Tests stage
+            #   --skip-mutation  reuses Stryker results from Mutation Tests stage
+            #   --skip-postman   reuses Newman JSON from ShiftLeft stage
+            #   --skip-coverage  reuses API coverage matrix already generated
+            ./run-all.sh --skip-unit --skip-mutation --skip-postman --skip-coverage --no-delay
+        """, NODE_VERSION)
+    } catch (Exception e) {
+        echo "Quality report generation failed: ${e.getMessage()}"
+        currentBuild.result = 'UNSTABLE'
+    }
+
+    if (fileExists('postman/reports')) {
+        def qualityReport = sh(
+            returnStdout: true,
+            script: "ls -t postman/reports/quality-report-*.html 2>/dev/null | head -1 | xargs -r basename"
+        ).trim()
+        if (qualityReport) {
+            publishHTML([
+                allowMissing: true,
+                alwaysLinkToLastBuild: true,
+                keepAll: true,
+                reportDir: 'postman/reports',
+                reportFiles: qualityReport,
+                includes: '**/*',
+                reportName: 'QualityReport',
+                reportTitles: 'Combined Quality Report'
+            ])
+        }
+        archiveArtifacts artifacts: 'postman/reports/**', allowEmptyArchive: true
+    }
+}
+
+def updateShiftLeftStatus(String state, String targetUrlPath = '') {
+    withCredentials([string(credentialsId: 'GITHUB_RUNWAYCI_TOKEN', variable: 'GITHUB_RUNWAYCI_TOKEN')]) {
+        def targetUrl = targetUrlPath ? "${env.BUILD_URL}${targetUrlPath}" : "${env.BUILD_URL}"
+        utilObj.runCmd("""
+            octocat status --context shiftleft-SERVICE_NAME-postman --description "ShiftLeft SERVICE_NAME Postman" --state ${state} --target_url "${targetUrl}"
+            octocat label --label shifted-left
+        """, NODE_VERSION)
+    }
+}

package/templates/postman/.husky/pre-commit

@@ -0,0 +1,19 @@
+#!/bin/sh
+# Auto-format staged JSON files in postman folder before commit
+
+# Get list of staged JSON files in postman folder
+STAGED_JSON=$(git diff --cached --name-only --diff-filter=ACM -- 'postman/**/*.json')
+
+if [ -n "$STAGED_JSON" ]; then
+    echo "Formatting staged Postman JSON files..."
+    
+    # Format each staged file
+    echo "$STAGED_JSON" | while read -r file; do
+        if [ -f "$file" ]; then
+            npx --prefix postman prettier --write "$file"
+            git add "$file"
+        fi
+    done
+    
+    echo "Done formatting."
+fi

package/templates/postman/.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "printWidth": 120,
+  "tabWidth": 2,
+  "useTabs": false
+}

package/templates/postman/README.md.ejs

@@ -0,0 +1,147 @@
+# <%= serviceName %> Postman Tests
+
+API integration tests using Postman/Newman.
+
+## Prerequisites
+
+- Node.js 18+
+- npm 8.4+
+- Application running locally (for local tests)
+<% if (includeStaging) { %>- AWS CLI configured with staging profile (for staging tests)
+- `jq` installed (`brew install jq`)<% } %>
+
+## Setup
+
+```bash
+cd postman
+npm install
+```
+
+## Running Tests
+
+### Local Environment
+
+Start the application first, then:
+
+```bash
+cd postman/scripts
+./runners/run-tests-local.sh
+```
+<% if (includeStaging) { %>
+### Staging Environment
+
+```bash
+cd postman/scripts
+AWS_PROFILE=staging ./runners/run-tests-staging.sh
+```
+
+Staging config is in `postman/config/staging.json` — set your AWS secret name, JWT parameters, and base URL there.
+<% } %>
+### All Tests + Quality Report (Unit + Mutation + Postman + Coverage)
+
+```bash
+cd postman/scripts
+./run-all.sh                        # Run everything (local)
+./run-all.sh --skip-mutation        # Skip slow mutation tests
+./run-all.sh --env staging          # Run Postman against staging
+./run-all.sh --skip-unit --skip-mutation  # Postman + coverage only
+```
+
+## Test Reports
+
+Reports are generated in `postman/reports/`:
+- `quality-report-*.html` — Combined quality report (unit + mutation + Postman + coverage)
+- `consolidated-*.html` — Postman test summary across all collections
+- `api-coverage-matrix-*.html` — API endpoint coverage matrix
+- `test-local-*.html` / `test-staging-*.html` — Per-collection Newman reports
+
+## API Coverage
+
+Check that all endpoints have 2xx test coverage:
+
+```bash
+cd postman/scripts
+./report-generators/java-api-coverage-matrix.sh
+```
+
+## Mutation Testing
+
+Verify unit test quality with PIT:
+
+```bash
+cd postman/scripts
+./report-generators/mutation-report.sh
+```
+
+## Directory Structure
+
+```
+postman/
+  collections/       # Newman collection JSON files
+  environments/      # Postman environment files
+  config/            # Environment config (staging.json etc.)
+  reports/           # Generated test reports (gitignored)
+  scripts/
+    run-all.sh                    # Unified runner (all phases)
+    runners/
+      run-tests-local.sh          # Local Postman tests
+      run-tests-staging.sh        # Staging Postman tests
+    report-generators/
+      java-api-coverage-matrix.sh # API coverage analysis
+      mutation-report.sh          # PIT mutation report
+      generate-consolidated-report.sh
+      stage-report-artifacts.sh
+    auth/                         # JWT generation scripts
+    infra/                        # WireMock start/stop scripts
+    lib/                          # Python report generators
+```
+
+## Adding New Tests
+
+1. Create or update collection in `collections/`
+2. Follow naming: `XX-description.json`
+3. Add to `runners/run-tests-local.sh`<% if (includeStaging) { %> and `runners/run-tests-staging.sh`<% } %>
+4. Run coverage report to verify 100% 2xx coverage
+
+## Collection Naming
+
+- `01-core.json` - Core CRUD operations
+- `02-authorization.json` - Auth tests
+- `03-validation.json` - Invalid input tests
+- `XX-feature.json` - Feature-specific tests
+
+## Test Naming Conventions
+
+- `GET - Endpoint - 200 valid request`
+- `POST - Endpoint - 201 created`
+- `GET - Endpoint - 404 not found`
+- `POST - Endpoint - 400 invalid input`
+
+## Environment Variables
+
+Key variables in `environments/`:
+- `base_url` - API base URL
+- `auth_token` - JWT token
+- `environment` - `local`<% if (includeStaging) { %> or `staging`<% } %>
+<% if (includeStaging) { %>
+## Staging Config (`config/staging.json`)
+
+```json
+{
+  "base_url": "https://your-service-staging.freshworks.com/api/v1",
+  "aws": {
+    "secretName": "your-secret-name",
+    "client": "your_client",
+    "issuer": "your_issuer",
+    "region": "us-west-2"
+  },
+  "jwt": {
+    "api_issuer": "your_client",
+    "api_account_id": "1",
+    "api_account_domain": "freshworks.com"
+  }
+}
+```
+
+AWS credentials are fetched via CLI (`AWS_PROFILE=staging`) and cleared before npm runs to prevent supply chain exposure.
+<% } %>