@freshworks/shiftleft-tools 1.1.18 → 1.1.19

package/README.md

@@ -70,6 +70,18 @@ shiftleft --version
 
 ## Usage
 
+| Command | Purpose | Key flags |
+|---|---|---|
+| `init-rules` | Symlink Cursor rules/skills into a repo | `--force`, `--skip-skills`, `--copy`, `--stack` |
+| `init-postman` | Scaffold Postman/Newman infra | `--name`, `--stack`, `--with-staging`, `--force` |
+| `link` | (Re)create Cursor symlinks | `--copy`, `--stack` |
+| `test` | Stage latest scripts + run orchestrator | *(flags pass through to run-all.sh)* |
+| `stage-scripts` | Stage library scripts only (no run) | `--stack` |
+| `protect` | Mark a staged script repo-owned | `--list`, `--remove` |
+| `update` | Refresh rules/skills/postman | `--rules`, `--skills`, `--postman`, `--force` |
+| `doctor` | Report drift vs latest | `--check`, `--json` |
+| `setup-pipeline` | Audit + scaffold pipeline | `-y/--yes`, `--force` |
+
 ### Claude Code skills: install the plugin (once per machine)
 
 Claude Code skills are delivered as a **plugin**, not copied into each repo — so
@@ -166,6 +178,10 @@ postman/scripts/
 └── database/                          # Node
 ```
 
+Java LocalStack/WireMock orchestration auto-detects the container runtime — **docker preferred, podman fallback** (`infra/container-runtime.sh`) — so S3/attachment tests run on podman-only machines.
+
+Java `runners/run-tests-local.sh` / `run-tests-staging.sh` ship **generic**. `/setup-api-tests` fills the repo-specific block (port, profile, Maven module, coverage package, JWT) and then runs `shiftleft protect` so staging won't overwrite your customizations.
+
 The library scripts are *not vendored*: `shiftleft test` (and the `run-all.sh`
 shim) re-stages them from the installed package before every run, so
 `npm i -g @freshworks/shiftleft-tools@latest` changes test behavior in every repo
@@ -186,9 +202,7 @@ shiftleft stage-scripts                # stage only (before calling staged scrip
 
 ### Protect a customized library script
 
-Staging overwrites library scripts from the package on every run. If your repo
-has customized one (e.g. a service-specific `runners/run-tests-local.sh`), mark
-it **protected** so staging leaves it alone:
+Staging overwrites library scripts from the package on every run. For Java repos, **`shiftleft protect` is the required final step of `/setup-api-tests`** — without it, every `shiftleft test` run silently discards your runner customizations. If you've manually customized a script, mark it **protected** so staging leaves it alone:
 
 ```bash
 shiftleft protect runners/run-tests-local.sh runners/run-tests-staging.sh
@@ -343,7 +357,7 @@ npm pack
 ## Requirements
 
 - Node.js 18+ and npm 8.4+ (for the CLI and Postman/Newman runner)
-- **Java projects:** Java 21+, Maven
+- **Java projects:** Java (version per your service; the local runner honors `JAVA_VERSION`), Maven, Docker or Podman
 - **Node projects:** Yarn (recommended), Mocha, nyc, Stryker
 - AWS CLI (for staging Postman tests with JWT from Secrets Manager)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freshworks/shiftleft-tools",
-  "version": "1.1.18",
+  "version": "1.1.19",
   "description": "CLI for managing Cursor rules/skills and Postman test infrastructure across Java Spring Boot and Node.js/Express projects",
   "type": "module",
   "main": "src/index.js",

package/templates/postman/scripts/lib/publish_health.py

@@ -0,0 +1,178 @@
+"""
+Publish a normalized test-health row to DynamoDB after each ShiftLeft run.
+
+Gated: only writes when SHIFTLEFT_PUBLISH_METRICS=true and SHIFTLEFT_HEALTH_TABLE is set.
+A publish failure logs a warning and never fails the build.
+"""
+
+import os
+import re
+
+
+def _normalize_repo(url):
+    """git@github.com:owner/repo.git  or  https://github.com/owner/repo.git  →  owner/repo"""
+    url = (url or '').strip()
+    # SSH
+    m = re.match(r'git@[^:]+:(.+?)(?:\.git)?$', url)
+    if m:
+        return m.group(1)
+    # HTTPS
+    m = re.match(r'https?://[^/]+/(.+?)(?:\.git)?$', url)
+    if m:
+        return m.group(1)
+    return url
+
+
+def build_row(metrics, meta):
+    """
+    Build a normalized DynamoDB item from computed metrics and run context.
+
+    metrics keys (all optional):
+      mutation          – dict with keys killed/survived/no_coverage(or noCoverage)/timeout/total
+      api_coverage      – api-coverage-matrix JSON dict
+      postman           – dict: assertions_total/passed/failed, collections_passed/failed
+      postman_collections – list of per-collection dicts (name, assertions_total/passed/failed, status)
+
+    meta keys:
+      git_repo, git_commit, git_branch, pr_number
+      datetime      – ISO-8601 string (UTC)
+      display_name  – human-readable service name
+      stack         – 'Java' | 'NodeJS' etc.
+      environment   – 'local' | 'staging'
+      mutation_tool – 'pit' | 'stryker'
+      products      – optional list of product slugs (multi-product repos)
+    """
+    postman = metrics.get('postman') or {}
+    api_coverage = metrics.get('api_coverage')
+    mutation = metrics.get('mutation')
+    postman_collections = metrics.get('postman_collections') or []
+
+    # --- passRate ---
+    assertions_total = int(postman.get('assertions_total', 0))
+    assertions_passed = int(postman.get('assertions_passed', 0))
+    assertions_failed = int(postman.get('assertions_failed', 0))
+    col_passed = int(postman.get('collections_passed', 0))
+    col_failed = int(postman.get('collections_failed', 0))
+    if assertions_total > 0:
+        pass_status = 'pass' if assertions_failed == 0 else 'fail'
+    else:
+        pass_status = 'unknown'
+
+    pass_rate = {
+        'collectionsTotal': col_passed + col_failed,
+        'collectionsPassed': col_passed,
+        'assertionsTotal': assertions_total,
+        'assertionsPassed': assertions_passed,
+        'assertionsFailed': assertions_failed,
+        'status': pass_status,
+    }
+
+    # --- coverage (API coverage) ---
+    if api_coverage:
+        cov_pct = float(api_coverage.get('coverage_percent', 0))
+        well_pct = float(api_coverage.get('well_tested_percent', 0))
+        qp_pct = float(api_coverage.get('query_params_percent', 0))
+        skipped = int(api_coverage.get('skipped_tests', 0))
+        gaps = (api_coverage.get('gaps') or [])[:25]
+        by_method = api_coverage.get('by_method') or {}
+    else:
+        cov_pct = well_pct = qp_pct = 0.0
+        skipped = 0
+        gaps = []
+        by_method = {}
+
+    coverage = {
+        'coveragePercent': cov_pct,
+        'wellTestedPercent': well_pct,
+        'queryParamsPercent': qp_pct,
+        'skippedTests': skipped,
+        'gaps': gaps,
+        'byMethod': by_method,
+    }
+
+    # --- mutation ---
+    mut_row = None
+    if mutation:
+        killed = int(mutation.get('killed', 0))
+        survived = int(mutation.get('survived', 0))
+        # PIT uses no_coverage; normalize to noCoverage
+        no_cov = int(mutation.get('noCoverage', mutation.get('no_coverage', 0)))
+        timeout = int(mutation.get('timeout', 0))
+        total = int(mutation.get('total', 0))
+        denominator = killed + survived + no_cov
+        score = round((killed / denominator * 100), 2) if denominator > 0 else 0.0
+        mut_row = {
+            'tool': meta.get('mutation_tool', 'pit'),
+            'killed': killed,
+            'survived': survived,
+            'noCoverage': no_cov,
+            'timeout': timeout,
+            'total': total,
+            'score': score,
+        }
+
+    # --- failures (top 25 failing collections) ---
+    failures = [
+        {
+            'suite': col.get('name', ''),
+            'test': '',
+            'reason': f"{col.get('assertions_failed', 0)} assertion(s) failed",
+        }
+        for col in postman_collections
+        if int(col.get('assertions_failed', 0)) > 0
+    ][:25]
+
+    # --- suites (per-collection breakdown) ---
+    suites = [
+        {
+            'name': col.get('name', ''),
+            'assertionsTotal': int(col.get('assertions_total', 0)),
+            'assertionsPassed': int(col.get('assertions_passed', 0)),
+            'coveragePercent': 0,
+        }
+        for col in postman_collections
+    ]
+
+    repo = _normalize_repo(meta.get('git_repo', ''))
+
+    row = {
+        'Repo': repo,
+        'DateTime': meta.get('datetime', ''),
+        'displayName': meta.get('display_name', ''),
+        'stack': meta.get('stack', ''),
+        'environment': meta.get('environment', ''),
+        'prNumber': meta.get('pr_number', ''),
+        'commitSha': meta.get('git_commit', ''),
+        'passRate': pass_rate,
+        'coverage': coverage,
+        'failures': failures,
+        'suites': suites,
+    }
+    if mut_row:
+        row['mutation'] = mut_row
+    products = meta.get('products') or []
+    if products:
+        row['products'] = products
+
+    return row
+
+
+def publish(row):
+    """Write row to DynamoDB. Gated by SHIFTLEFT_PUBLISH_METRICS=true. Never fails the build."""
+    flag = os.environ.get('SHIFTLEFT_PUBLISH_METRICS', '').strip().lower()
+    if flag not in ('true', '1', 'yes'):
+        return
+    table_name = os.environ.get('SHIFTLEFT_HEALTH_TABLE', 'mp-shiftleft-health')
+    if not table_name:
+        return
+    if not row.get('Repo') or not row.get('DateTime'):
+        print('[publish_health] Warning: Repo or DateTime missing — skipping publish.')
+        return
+    try:
+        import boto3
+        dynamodb = boto3.resource('dynamodb')
+        table = dynamodb.Table(table_name)
+        table.put_item(Item=row)
+        print(f'[publish_health] Published health row: {row["Repo"]} @ {row["DateTime"]}')
+    except Exception as exc:
+        print(f'[publish_health] Warning: publish failed (non-fatal): {exc}')

package/templates/postman/scripts/lib/report_combined.py

@@ -13,6 +13,30 @@ from report_utils import (
 from report_unit import parse_surefire_reports, parse_jacoco_report, parse_mutation_data
 
 
+def _parse_stryker_json(path):
+    """Parse Stryker mutation-report.json into the same shape as parse_mutation_data."""
+    killed = survived = no_coverage = timeout = 0
+    try:
+        with open(path, 'r') as f:
+            data = json.load(f)
+        for fdata in data.get('files', {}).values():
+            for m in fdata.get('mutants', []):
+                st = m.get('status', '')
+                if st == 'Killed':
+                    killed += 1
+                elif st == 'Survived':
+                    survived += 1
+                elif st == 'NoCoverage':
+                    no_coverage += 1
+                elif st == 'Timeout':
+                    timeout += 1
+    except Exception as e:
+        print(f'Warning: Could not parse stryker JSON {path}: {e}')
+    total = killed + survived + no_coverage + timeout
+    return {'killed': killed, 'survived': survived, 'no_coverage': no_coverage, 'timeout': timeout, 'total': total,
+            'mutator_stats': {}, 'survived_mutations': []}
+
+
 def generate_combined_report(args):
     output_html = args.output_file
 
@@ -20,6 +44,11 @@ def generate_combined_report(args):
     jacoco = parse_jacoco_report(args.jacoco_xml) if args.jacoco_xml and os.path.isfile(args.jacoco_xml) else None
     mutation = parse_mutation_data(args.mutations_xml) if args.mutations_xml and os.path.isfile(args.mutations_xml) else None
 
+    # Node stack: Stryker mutation report (--stryker-json)
+    stryker_json_path = getattr(args, 'stryker_json', None)
+    if mutation is None and stryker_json_path and os.path.isfile(stryker_json_path):
+        mutation = _parse_stryker_json(stryker_json_path)
+
     api_coverage = None
     if args.api_coverage_file and os.path.isfile(args.api_coverage_file):
         with open(args.api_coverage_file, 'r') as f:
@@ -178,6 +207,39 @@ def generate_combined_report(args):
     ])
 
     postman_collections = _load_postman_collections(args)
+
+    # Publish normalized health row to DynamoDB (gated by SHIFTLEFT_PUBLISH_METRICS env var)
+    try:
+        import datetime as _dt
+        from publish_health import build_row, publish
+        _mut_tool = 'stryker' if getattr(args, 'stryker_json', None) else 'pit'
+        _metrics = {
+            'mutation': mutation,
+            'api_coverage': api_coverage,
+            'postman': {
+                'assertions_total': postman_total,
+                'assertions_passed': postman_passed,
+                'assertions_failed': postman_failed,
+                'collections_passed': postman_col_passed,
+                'collections_failed': postman_col_failed,
+            },
+            'postman_collections': postman_collections,
+        }
+        _meta = {
+            'git_repo': getattr(args, 'git_repo', '') or '',
+            'git_commit': getattr(args, 'git_commit', '') or '',
+            'git_branch': getattr(args, 'git_branch', '') or '',
+            'pr_number': getattr(args, 'pr_number', '') or '',
+            'datetime': _dt.datetime.utcnow().isoformat() + 'Z',
+            'display_name': getattr(args, 'logo', ''),
+            'stack': getattr(args, 'stack', '') or '',
+            'environment': getattr(args, 'env', '') or '',
+            'mutation_tool': _mut_tool,
+        }
+        publish(build_row(_metrics, _meta))
+    except Exception as _e:
+        print(f'[health] Warning: publish health failed (non-fatal): {_e}')
+
     products_present = sorted(set(c['product'] for c in postman_collections))
     real_products = [p for p in products_present if p and p != 'default']
     is_multi_product = len(real_products) > 1

package/templates/postman/scripts/lib/report_generator.py

@@ -98,6 +98,16 @@ def main():
     comb.add_argument('--postman-consolidated-html')
     comb.add_argument('--env', default=None)
     comb.add_argument('--timestamp', default=None)
+    # Node-stack unit/mutation inputs
+    comb.add_argument('--stryker-json')
+    comb.add_argument('--mocha-xml')
+    comb.add_argument('--lcov')
+    # Run context for health publishing
+    comb.add_argument('--git-repo', default='')
+    comb.add_argument('--git-commit', default='')
+    comb.add_argument('--git-branch', default='')
+    comb.add_argument('--pr-number', default='')
+    comb.add_argument('--stack', default='')
 
     args = parser.parse_args()
 

package/templates/postman/scripts/run-all.sh

@@ -51,6 +51,13 @@ REPORTS_DIR="$POSTMAN_DIR/reports"
 APP_PORT="${APP_PORT:-9090}"
 TIMESTAMP=$(date +"%Y%m%d-%H%M%S")
 
+# Git / CI run context for health publishing
+GIT_COMMIT=$(git -C "$PROJECT_ROOT" rev-parse HEAD 2>/dev/null || echo "unknown")
+GIT_BRANCH=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+GIT_REPO=$(git -C "$PROJECT_ROOT" config --get remote.origin.url 2>/dev/null || echo "unknown")
+PR_NUMBER="${CHANGE_ID:-${GITHUB_PR_NUMBER:-}}"
+export GIT_COMMIT GIT_BRANCH GIT_REPO PR_NUMBER
+
 # Environment selection (local or staging)
 POSTMAN_ENV="${POSTMAN_ENV:-local}"
 
@@ -369,7 +376,9 @@ if [ "$SKIP_REPORT" = false ]; then
     echo -e "${YELLOW}Generating combined report...${NC}"
 
 # Build report arguments as an array to handle spaces properly
-REPORT_ARGS=(combined "$COMBINED_OUTPUT" --logo "$REPORT_LOGO" --env "$POSTMAN_ENV" --timestamp "$TIMESTAMP")
+REPORT_ARGS=(combined "$COMBINED_OUTPUT" --logo "$REPORT_LOGO" --env "$POSTMAN_ENV" --timestamp "$TIMESTAMP" --stack "Java")
+REPORT_ARGS+=(--git-repo "$GIT_REPO" --git-commit "$GIT_COMMIT" --git-branch "$GIT_BRANCH")
+[ -n "${PR_NUMBER:-}" ] && REPORT_ARGS+=(--pr-number "$PR_NUMBER")
 
 # Unit test data (use preserved unit test JaCoCo, not the postman one)
 [ -d "$SUREFIRE_DIR" ] && REPORT_ARGS+=(--surefire-dir "$SUREFIRE_DIR")

package/templates/postman-node/requirements.txt

@@ -1 +1,2 @@
 defusedxml>=0.7.1
+boto3>=1.28.0

package/templates/postman-node/scripts/run-all.sh

@@ -33,6 +33,13 @@ source "$SCRIPT_DIR/lib/cleanup-stryker.sh"
 REPORTS_DIR="$POSTMAN_DIR/reports"
 TIMESTAMP=$(date +"%Y%m%d-%H%M%S")
 
+# Git / CI run context for health publishing
+GIT_COMMIT=$(git -C "$PROJECT_ROOT" rev-parse HEAD 2>/dev/null || echo "unknown")
+GIT_BRANCH=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+GIT_REPO=$(git -C "$PROJECT_ROOT" config --get remote.origin.url 2>/dev/null || echo "unknown")
+PR_NUMBER="${CHANGE_ID:-${GITHUB_PR_NUMBER:-}}"
+export GIT_COMMIT GIT_BRANCH GIT_REPO PR_NUMBER
+
 POSTMAN_ENV="${POSTMAN_ENV:-local}"
 SKIP_UNIT=false
 SKIP_MUTATION=false
@@ -246,7 +253,9 @@ if [ "$SKIP_REPORT" = false ]; then
 
     "$SCRIPT_DIR/report-generators/stage-report-artifacts.sh" "$PROJECT_ROOT" "$REPORTS_DIR"
 
-    REPORT_ARGS=(combined "$COMBINED_OUTPUT" --logo "API Service")
+    REPORT_ARGS=(combined "$COMBINED_OUTPUT" --logo "API Service" --stack "NodeJS")
+    REPORT_ARGS+=(--git-repo "$GIT_REPO" --git-commit "$GIT_COMMIT" --git-branch "$GIT_BRANCH")
+    [ -n "${PR_NUMBER:-}" ] && REPORT_ARGS+=(--pr-number "$PR_NUMBER")
 
     [ -f "$MOCHA_XML" ] && REPORT_ARGS+=(--mocha-xml "$MOCHA_XML")
     [ -f "$LCOV" ] && REPORT_ARGS+=(--lcov "$LCOV")