feat(parse-server-mongo): real JS line coverage via NODE_V8_COVERAGE

Replaces the prior API-route-surface "coverage" (counting fired
routes / curated route table) with actual V8 line coverage of the
parse-server library code under node_modules/parse-server/lib.

Architecture:
  - `Dockerfile.coverage` extends the base image with a graceful-
    shutdown shim (coverage-entrypoint.js installs SIGTERM/SIGINT
    handlers calling process.exit(0)) so V8 actually flushes its
    coverage data on `compose stop`. Without that shim, express's
    app.listen pins the loop and the kernel signal-kills node
    (exit 143) before NODE_V8_COVERAGE writes anything.
  - `docker-compose.coverage.yml` is an OVERLAY: applied via
    `-f docker-compose.yml -f docker-compose.coverage.yml`. It
    sets NODE_V8_COVERAGE=/coverage and bind-mounts the host
    ./coverage dir. The base `Dockerfile` and `docker-compose.yml`
    are untouched, so keploy/integrations and keploy/enterprise
    CI lanes consume the base compose and pay zero coverage cost.
  - `coverage-report.js` reads V8's per-process JSON dumps and
    produces a `Covered N/M (XX.X%)` summary plus a c8-shaped
    coverage-summary.json. We don't use `c8 report` because c8
    filters node_modules even when --include is set, and
    parse-server lives entirely under node_modules/parse-server.
    The custom tool walks V8's nested ranges (block coverage)
    and resolves per-line execution count to the deepest range.
  - `flow.sh::parse_coverage` shells into the coverage image to
    run coverage-report.js against the dumped V8 data; when called
    against the base image (no overlay) it prints
    "INFO: ... uninstrumented" and exits 0 so enterprise lanes'
    `flow.sh coverage || true` informational calls keep working.

Removed:
  - `parse_list_routes` (curated route table denominator).
  - `parse_collect_recorded_routes` (keploy-tests / fired-routes
    reader).
  - The legacy route-surface `parse_coverage` body.
  - `list-routes` subcommand.

Validated locally: helper produced `coverage=38.7` to GITHUB_OUTPUT
against a fresh stack (signup + record-traffic + clean stop).
38.7% reflects coverage of node_modules/parse-server/lib —
mongo paths ~46%, REST ~52%, Auth ~40%, schema ~58%; postgres
adapter ~7% (mongo storage selected) and LiveQuery ~3% (not
exercised), which is the expected distribution.

Signed-off-by: Akash Kumar <meakash7902@gmail.com>

Author: AkashKumar7902

.github/workflows/scripts/run-and-measure-parse-server.sh

@@ -1,62 +1,49 @@
 #!/usr/bin/env bash
 #
-# run-and-measure-parse-server.sh — bring parse-server + mongo up via
-# the sample's compose, run flow.sh bootstrap + record-traffic with
-# the per-call audit log enabled, run flow.sh coverage, and emit
-# `coverage=PCT` onto $GITHUB_OUTPUT for the downstream
-# coverage-gate job.
+# run-and-measure-parse-server.sh — bring parse-server + mongo up
+# under the coverage overlay, run flow.sh bootstrap + record-traffic,
+# stop parse-server cleanly so V8 flushes NODE_V8_COVERAGE, run
+# flow.sh coverage, and emit `coverage=PCT` onto $GITHUB_OUTPUT
+# for the downstream coverage-gate job.
 #
-# Called from .github/workflows/parse-server-mongo.yml's
-# build-coverage and release-coverage jobs (one per ref under
-# comparison). Both jobs source the same script so the
-# measurement is identical across refs — any drift in the
-# numerator definition would otherwise produce a misleading
-# delta.
+# Coverage isolation contract:
+#   * Base `Dockerfile` and `docker-compose.yml` are untouched.
+#   * The overlay `Dockerfile.coverage` + `docker-compose.coverage.yml`
+#     installs the V8 coverage entrypoint shim and sets
+#     NODE_V8_COVERAGE. ONLY this script applies the overlay; the
+#     keploy/integrations and keploy/enterprise CI lanes consume
+#     the base compose and pay zero coverage-instrumentation cost.
 #
-# Inputs (all from the workflow env):
-#   PARSE_FIRED_ROUTES_FILE   — per-call audit log path; passed
-#                               through to flow.sh so its
-#                               record-traffic loop logs each
-#                               (METHOD, URL) pair, and so its
-#                               coverage subcommand uses that
-#                               file as the standalone numerator.
-#   PARSE_PHASE               — label spliced into flow.sh's
-#                               token-file slot so build vs.
-#                               release runs don't collide. Also
-#                               surfaced in the coverage report
-#                               header for log diffing.
-#   GITHUB_OUTPUT             — standard GH Actions sink for step
-#                               outputs.
+# Inputs (from the workflow env):
+#   PARSE_PHASE       — label spliced into flow.sh's token-file slot
+#                       so build vs. release runs don't collide.
+#   GITHUB_OUTPUT     — standard GH Actions sink for step outputs.
 set -Eeuo pipefail
 
-# Defaults match the sample's docker-compose.yml env-substituted
-# vars; exporting them makes it explicit which values the helper
-# is pinning so a future compose-side rename doesn't silently
-# desync the helper from the sample.
 export PARSE_APP_CONTAINER="${PARSE_APP_CONTAINER:-parse-server-mongo-app}"
 export PARSE_MONGO_CONTAINER="${PARSE_MONGO_CONTAINER:-parse-server-mongo-mongo}"
 export PARSE_HOST_PORT="${PARSE_HOST_PORT:-6100}"
 export PARSE_CONTAINER_PORT="${PARSE_CONTAINER_PORT:-6100}"
 export PARSE_APP_ID="${PARSE_APP_ID:-keploy-parse-app}"
 export PARSE_MASTER_KEY="${PARSE_MASTER_KEY:-keploy-parse-master}"
 export PARSE_MOUNT_PATH="${PARSE_MOUNT_PATH:-/parse}"
-# flow.sh reads APP_PORT (host-side) for the curl base; keep it
-# aligned with PARSE_HOST_PORT.
 export APP_PORT="${APP_PORT:-${PARSE_HOST_PORT}}"
-: "${PARSE_FIRED_ROUTES_FILE:?PARSE_FIRED_ROUTES_FILE must be set by the workflow}"
 
-# Reset audit log for this run; otherwise a prior run's entries
-# would inflate the numerator on a re-trigger.
-: >"$PARSE_FIRED_ROUTES_FILE"
+mkdir -p coverage
+chmod 777 coverage      # node UID inside container differs from runner UID
+sudo rm -rf coverage/coverage-* coverage/coverage_report.txt coverage/coverage-summary.json 2>/dev/null \
+    || rm -rf coverage/coverage-* coverage/coverage_report.txt coverage/coverage-summary.json 2>/dev/null \
+    || true
 
-# Bring up parse-server + mongo. The sample's compose builds the
-# parse-server image from the Dockerfile in this directory and
-# wires mongo via a fixed-IP user-defined network so the URI is
-# stable across runs.
-docker compose up -d --build
+COMPOSE=(docker compose -f docker-compose.yml -f docker-compose.coverage.yml)
 
-# Wait for /parse/health to return 200. Cold parse-server boot on
-# a GH runner is mostly mongo init + npm start; budget ~120s.
+# Bring up parse-server + mongo under the coverage overlay. The
+# Dockerfile.coverage layer wraps node so SIGTERM produces a clean
+# `process.exit(0)` (otherwise express's app.listen pins the loop
+# and signal-kills bypass V8's coverage flush).
+"${COMPOSE[@]}" up -d --build
+
+# Wait for /parse/health to return 200.
 for i in $(seq 1 120); do
     code=$(curl -sS -o /dev/null -w '%{http_code}' \
         -H "X-Parse-Application-Id: ${PARSE_APP_ID}" \
@@ -65,34 +52,35 @@ for i in $(seq 1 120); do
     sleep 2
 done
 
-# Single-phase: parse-server's compose has no SKIP_INIT-style
-# flag (mongo is empty on every fresh `compose up -d`), so
-# flow.sh::parse_bootstrap idempotently signs up the fixed user
-# and persists the session token under
+# Idempotent signup + session-token persistence under
 # /tmp/parse-token-${PARSE_PHASE}.
 bash flow.sh bootstrap 240
 
-# Drive traffic. flow.sh::parse_record_traffic reads the
-# persisted session token and exercises the curated REST +
-# GraphQL surface against the running backend.
+# Exercise the REST + GraphQL surface.
 bash flow.sh record-traffic
 
-# Coverage report — uses PARSE_FIRED_ROUTES_FILE as numerator
-# since no keploy/test-set-* tree exists in the standalone case.
-# parse_coverage prints to stdout, so tee into the artifact path
-# the workflow uploads.
-bash flow.sh coverage | tee coverage_report.txt
+# Stop parse-server cleanly so the SIGTERM handler's process.exit(0)
+# fires and V8 flushes NODE_V8_COVERAGE.
+"${COMPOSE[@]}" stop -t 30 parse-server
+
+# Generate the coverage report from the V8 dumps. flow.sh::parse_coverage
+# launches a one-off container against the same coverage volume.
+bash flow.sh coverage
+
+if [ ! -f coverage_report.txt ]; then
+    echo "::error::flow.sh coverage produced no coverage_report.txt"
+    exit 1
+fi
 
-# Pull the percentage out of the report's `Covered N/M (XX.X%)`
-# line. Anchored on the parenthesised form so a future change to
-# the report's prose doesn't break the parse.
+# Parse `Covered N/M (XX.X%)` — anchored on the parenthesised form
+# so a future report-prose change doesn't break the parse.
 pct=$(grep -oE '\([0-9]+\.[0-9]+%\)' coverage_report.txt | head -1 | tr -d '()%')
 if [ -z "$pct" ]; then
     echo "::error::Could not parse coverage percentage from coverage_report.txt"
     cat coverage_report.txt || true
     exit 1
 fi
 echo "coverage=${pct}" >>"$GITHUB_OUTPUT"
-echo "coverage: ${pct}% (audit log: $PARSE_FIRED_ROUTES_FILE)"
+echo "coverage: ${pct}% (JS line coverage via NODE_V8_COVERAGE + custom report)"
 
-docker compose down -v --remove-orphans
+"${COMPOSE[@]}" down -v --remove-orphans

parse-server-mongo/.gitignore

@@ -0,0 +1,2 @@
+coverage/
+coverage_report.txt

parse-server-mongo/Dockerfile.coverage

@@ -0,0 +1,45 @@
+# Coverage overlay image for parse-server-mongo.
+#
+# Extends the base sample image build chain (node:20-bookworm-slim +
+# parse-server deps + index.js) with c8 (for `c8 report`) and a
+# tiny JavaScript entrypoint shim that registers SIGTERM/SIGINT
+# handlers calling process.exit(0) — without that, parse-server's
+# express server pins the event loop and signal-driven kills
+# bypass V8's coverage flush, leaving NODE_V8_COVERAGE empty.
+#
+# IMPORTANT: this image is only consumed by docker-compose.coverage.yml.
+# The base Dockerfile and docker-compose.yml stay uninstrumented so
+# enterprise's keploy compat lane pays no coverage-instrumentation
+# cost.
+FROM node:20-bookworm-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates curl dumb-init && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /usr/src/app
+
+COPY package*.json ./
+RUN npm install --omit=dev
+
+COPY index.js ./
+
+# c8 is the report generator (we use NODE_V8_COVERAGE for raw data
+# collection at runtime, then `c8 report` post-hoc to produce
+# json-summary / lcov). Installing globally keeps the app's own
+# node_modules byte-identical to the base image.
+RUN npm install -g c8@10.1.2
+
+# Graceful-shutdown shim: parse-server's app.listen() pins the
+# event loop, so a `compose stop` (SIGTERM) would kill node by
+# signal — exit code 143 — before V8's NODE_V8_COVERAGE writer
+# runs. Calling process.exit(0) from a SIGTERM handler turns the
+# kill into a clean exit, so V8 dumps coverage to NODE_V8_COVERAGE
+# before the process terminates.
+RUN printf "process.on('SIGTERM', () => process.exit(0));\nprocess.on('SIGINT', () => process.exit(0));\nrequire('/usr/src/app/index.js');\n" \
+    > /usr/src/app/coverage-entrypoint.js
+
+EXPOSE 1337
+
+ENTRYPOINT ["dumb-init", "--"]
+CMD ["node", "/usr/src/app/coverage-entrypoint.js"]

parse-server-mongo/coverage-report.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+//
+// coverage-report.js — convert NODE_V8_COVERAGE dumps into a
+// `Covered N/M (XX.X%)` line-coverage summary for the running
+// `flow.sh coverage` subcommand.
+//
+// Why a custom tool: c8's report path filters `node_modules/**` by
+// default and the include-overrides don't reliably reach into a
+// vendored library tree. The V8 data does contain those scripts —
+// c8 just refuses to include them. This script reads the same V8
+// dumps c8 reads and applies exactly the filter we want.
+//
+// V8 coverage shape (block-level when NODE_V8_COVERAGE is set):
+// each `function.ranges` is a list of nested ranges. The outermost
+// range is the function body with its call count. Inner ranges
+// flag basic blocks that V8 tracks separately — most of them are
+// branches with count=0 that did NOT execute. A byte position's
+// effective execution count is determined by the DEEPEST range
+// that contains it. We compute line coverage from that.
+//
+// Inputs (env):
+//   NODE_V8_COVERAGE      — directory containing coverage-*.json
+//                           V8 dumps (default /coverage).
+//   COVERAGE_INCLUDE      — substring; only file URLs containing
+//                           this string contribute to the metric
+//                           (default: "node_modules/parse-server/lib").
+//   COVERAGE_REPORT_FILE  — output path for the human-readable
+//                           summary (default coverage_report.txt
+//                           in CWD).
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const dumpDir = process.env.NODE_V8_COVERAGE || '/coverage';
+const filter = process.env.COVERAGE_INCLUDE || 'node_modules/parse-server/lib';
+const reportFile = process.env.COVERAGE_REPORT_FILE || 'coverage_report.txt';
+
+const dumps = fs.readdirSync(dumpDir)
+    .filter(f => f.startsWith('coverage-') && f.endsWith('.json'));
+
+if (dumps.length === 0) {
+    console.log(`INFO: no V8 coverage dumps under ${dumpDir} — base image is uninstrumented (apply docker-compose.coverage.yml overlay to enable)`);
+    fs.writeFileSync(reportFile, '');
+    process.exit(0);
+}
+
+// Per-file state: source bytes, line-start offsets, totalLines set,
+// coveredLines set. Aggregated across multiple V8 dumps and across
+// all functions/ranges in each dump.
+const files = new Map();
+
+function ensureFileEntry(filepath) {
+    let entry = files.get(filepath);
+    if (entry) return entry;
+    if (!fs.existsSync(filepath)) return null;
+    const src = fs.readFileSync(filepath, 'utf8');
+    const lineStartOffsets = [0];
+    let off = 0;
+    for (const ch of src) {
+        off += Buffer.byteLength(ch, 'utf8');
+        if (ch === '\n') lineStartOffsets.push(off);
+    }
+    // totalLines: every line whose source has at least one
+    // non-whitespace, non-pure-bracket-or-comment char. This
+    // approximates the "executable line" set Istanbul/coverage.py
+    // count, with predictable bias on heavily braced styles.
+    const lines = src.split('\n');
+    const total = new Set();
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed === '' ||
+            /^\/\//.test(trimmed) || /^\*/.test(trimmed) || /^\/\*/.test(trimmed) ||
+            /^[\{\}\)\];,]+$/.test(trimmed)) {
+            continue;
+        }
+        total.add(i + 1);
+    }
+    entry = { src, lineStartOffsets, totalLines: total, executedRanges: [] };
+    files.set(filepath, entry);
+    return entry;
+}
+
+function offsetToLine(entry, byteOffset) {
+    // Largest i such that lineStartOffsets[i] <= byteOffset.
+    let lo = 0, hi = entry.lineStartOffsets.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >>> 1;
+        if (entry.lineStartOffsets[mid] <= byteOffset) lo = mid; else hi = mid - 1;
+    }
+    return lo + 1;
+}
+
+let scriptCount = 0;
+let matchingScripts = 0;
+for (const dumpName of dumps) {
+    const data = JSON.parse(fs.readFileSync(path.join(dumpDir, dumpName), 'utf8'));
+    for (const result of data.result || []) {
+        scriptCount++;
+        const url = result.url || '';
+        if (!url.startsWith('file://')) continue;
+        if (!url.includes(filter)) continue;
+        matchingScripts++;
+        const filepath = url.replace(/^file:\/\//, '');
+        const entry = ensureFileEntry(filepath);
+        if (!entry) continue;
+        // Collect every range; we'll resolve nesting per-line below.
+        for (const fn of result.functions || []) {
+            for (const range of fn.ranges || []) {
+                entry.executedRanges.push({
+                    start: range.startOffset,
+                    end: range.endOffset,
+                    count: range.count,
+                });
+            }
+        }
+    }
+}
+
+// For each file, resolve per-line execution count by finding the
+// deepest range containing the line's first non-whitespace byte.
+// Deepest = smallest end-start (most specific).
+function resolveCoverage(entry) {
+    const ranges = entry.executedRanges;
+    // Sort by start asc, end desc — outermost first, innermost last
+    // when starts tie. (Not strictly required for the per-line
+    // search below; just makes the data tidy.)
+    ranges.sort((a, b) => (a.start - b.start) || (b.end - a.end));
+
+    const covered = new Set();
+    for (const lineNum of entry.totalLines) {
+        const lineStart = entry.lineStartOffsets[lineNum - 1];
+        // Pick the deepest (smallest-span) range whose [start,end)
+        // contains lineStart. If none, the line isn't in any
+        // tracked function — typically top-level module code; treat
+        // as uncovered. If the deepest range has count > 0, line
+        // is covered.
+        let best = null;
+        let bestSpan = Infinity;
+        for (const r of ranges) {
+            if (r.start <= lineStart && lineStart < r.end) {
+                const span = r.end - r.start;
+                if (span < bestSpan) {
+                    best = r;
+                    bestSpan = span;
+                }
+            }
+        }
+        if (best && best.count > 0) covered.add(lineNum);
+    }
+    return covered;
+}
+
+let totalLines = 0;
+let coveredLines = 0;
+const perFile = [];
+for (const [filepath, entry] of files) {
+    const covered = resolveCoverage(entry);
+    totalLines += entry.totalLines.size;
+    coveredLines += covered.size;
+    perFile.push({
+        filepath,
+        total: entry.totalLines.size,
+        covered: covered.size,
+    });
+}
+
+const pct = totalLines > 0 ? (coveredLines * 100 / totalLines) : 0;
+const pctFmt = pct.toFixed(1);
+
+perFile.sort((a, b) => a.filepath.localeCompare(b.filepath));
+
+const out = [];
+out.push('============== parse-server line coverage (V8, custom report) ==============');
+out.push(`V8 dumps consumed:        ${dumps.length}`);
+out.push(`Scripts in V8 dump:       ${scriptCount}`);
+out.push(`Scripts matching filter:  ${matchingScripts}`);
+out.push(`Source files measured:    ${files.size}`);
+out.push('');
+out.push('Per-file coverage (top 20 by uncovered lines):');
+const sortedByMissing = perFile.slice().sort((a, b) => (b.total - b.covered) - (a.total - a.covered));
+for (const r of sortedByMissing.slice(0, 20)) {
+    const rel = r.filepath.replace(/^.*node_modules\//, '');
+    const p = r.total > 0 ? (r.covered * 100 / r.total).toFixed(1) : '0.0';
+    out.push(`  ${rel.padEnd(58)} ${String(r.covered).padStart(5)}/${String(r.total).padStart(5)}  ${p.padStart(5)}%`);
+}
+out.push('');
+out.push(`Covered ${coveredLines}/${totalLines} (${pctFmt}%)`);
+out.push('============================================================================');
+
+const text = out.join('\n') + '\n';
+fs.writeFileSync(reportFile, text);
+process.stdout.write(text);
+
+// Also drop a c8-style json-summary alongside.
+const summary = {
+    total: {
+        lines:      { total: totalLines, covered: coveredLines, skipped: 0, pct: parseFloat(pctFmt) },
+        statements: { total: totalLines, covered: coveredLines, skipped: 0, pct: parseFloat(pctFmt) },
+        functions:  { total: 0, covered: 0, skipped: 0, pct: 0 },
+        branches:   { total: 0, covered: 0, skipped: 0, pct: 0 },
+    },
+};
+fs.writeFileSync(path.join(dumpDir, 'coverage-summary.json'), JSON.stringify(summary));