coverage-check 0.7.0 → 0.7.1

package/README.md

@@ -51,12 +51,29 @@ The `--suite` flag on `check` tells the tool to use fresh `--artifacts` for the
 **S3 key layout:**
 
 ```text
-<prefix>/<suite>/sha/<sha>/lcov.info          # payload
-<prefix>/<suite>/branch/<encoded-branch>/latest.json  # pointer: { "sha": "...", "timestamp": "..." }
+<prefix>/<suite>/sha/<sha>/lcov.info.gz       # gzip payload for new versioned writes
+<prefix>/<suite>/branch/<encoded-branch>/latest.json  # pointer with sha, payloadKey, encoding, byte counts, timestamp
 ```
 
 S3-backed stores need `s3:PutObject` for writes and `s3:GetObject` for reading branch pointers and baselines. The pointer reader also checks the previous unencoded pointer key (for example `branch/main/latest.json`) so stores written before branch-name encoding remain readable.
 
+Versioned S3 writes (`store-put --sha ... --branch ...`) gzip the LCOV payload and write pointer
+metadata with `payloadKey`, `encoding`, `rawBytes`, and `storedBytes`. Existing raw
+`sha/<sha>/lcov.info` payloads and legacy `<suite>/lcov.info` payloads remain readable. Legacy
+writes without `--sha`/`--branch` keep the old raw `<suite>/lcov.info` layout.
+
+Every S3 operation logs a concise diagnostic line to stderr with the operation name, bucket, key,
+elapsed time, and byte counts where applicable. Use these lines to distinguish payload writes,
+branch-pointer reads, and branch-pointer writes when CI storage stalls.
+
+S3 request bounds are configurable with environment variables:
+
+| Variable                                  | Default | Purpose                                  |
+| ----------------------------------------- | ------- | ---------------------------------------- |
+| `COVERAGE_CHECK_S3_CONNECTION_TIMEOUT_MS` | `5000`  | Socket connection timeout for S3 calls   |
+| `COVERAGE_CHECK_S3_REQUEST_TIMEOUT_MS`    | `30000` | Whole-request timeout for S3 calls       |
+| `COVERAGE_CHECK_S3_MAX_ATTEMPTS`          | `2`     | AWS SDK attempt count, including retries |
+
 ### Suite store with filesystem
 
 For local development or simpler deployments:

package/dist/src/s3-diagnostics.d.mts

@@ -0,0 +1,9 @@
+export type ClientLike = {
+    send(cmd: object): Promise<unknown>;
+};
+export type S3OperationDetails = {
+    rawBytes?: number;
+    storedBytes?: number;
+};
+export declare function createS3Client(region?: string): ClientLike;
+export declare function sendS3(client: ClientLike, bucket: string, operation: string, key: string, command: object, details?: S3OperationDetails): Promise<unknown>;

package/dist/src/s3-diagnostics.mjs

@@ -0,0 +1,60 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import { NodeHttpHandler } from "@smithy/node-http-handler";
+export function createS3Client(region) {
+    return new S3Client({
+        maxAttempts: readPositiveIntEnv("COVERAGE_CHECK_S3_MAX_ATTEMPTS", 2),
+        region,
+        requestHandler: new NodeHttpHandler({
+            connectionTimeout: readPositiveIntEnv("COVERAGE_CHECK_S3_CONNECTION_TIMEOUT_MS", 5000),
+            requestTimeout: readPositiveIntEnv("COVERAGE_CHECK_S3_REQUEST_TIMEOUT_MS", 30000),
+        }),
+    });
+}
+export async function sendS3(client, bucket, operation, key, command, details = {}) {
+    const start = performance.now();
+    try {
+        const result = await client.send(command);
+        logS3(bucket, operation, key, "ok", performance.now() - start, details);
+        return result;
+    }
+    catch (err) {
+        logS3(bucket, operation, key, "failed", performance.now() - start, {
+            ...details,
+            error: formatError(err),
+        });
+        throw err;
+    }
+}
+function logS3(bucket, operation, key, status, elapsedMs, details) {
+    const parts = [
+        "coverage-check s3",
+        `operation=${JSON.stringify(operation)}`,
+        `status=${status}`,
+        `bucket=${JSON.stringify(bucket)}`,
+        `key=${JSON.stringify(key)}`,
+        `elapsed_ms=${Math.round(elapsedMs)}`,
+    ];
+    if (details.rawBytes !== undefined)
+        parts.push(`raw_bytes=${details.rawBytes}`);
+    if (details.storedBytes !== undefined)
+        parts.push(`stored_bytes=${details.storedBytes}`);
+    if (details.error !== undefined)
+        parts.push(`error=${JSON.stringify(details.error)}`);
+    process.stderr.write(`${parts.join(" ")}\n`);
+}
+function readPositiveIntEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "")
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        process.stderr.write(`coverage-check s3 invalid ${name}=${JSON.stringify(raw)}; using ${fallback}\n`);
+        return fallback;
+    }
+    return value;
+}
+function formatError(err) {
+    if (err instanceof Error)
+        return `${err.name}: ${err.message}`;
+    return String(err);
+}

package/dist/src/s3-suite-store-reads.d.mts

@@ -0,0 +1,17 @@
+export type StoredPointer = {
+    sha: string;
+    timestamp?: string;
+    payloadKey?: string;
+    encoding?: "gzip";
+    rawBytes?: number;
+    storedBytes?: number;
+};
+type ReadContext = {
+    bucket: string;
+    key(...parts: string[]): string;
+    sendS3(operation: string, key: string, command: object): Promise<unknown>;
+};
+export declare function getLegacy(ctx: ReadContext, suite: string): Promise<Buffer | null>;
+export declare function shouldWritePointer(ctx: ReadContext, suite: string, branch: string, incomingTimestamp: string): Promise<boolean>;
+export declare function readPointer(ctx: ReadContext, suite: string, branch: string): Promise<StoredPointer>;
+export {};

package/dist/src/s3-suite-store-reads.mjs

@@ -0,0 +1,57 @@
+import { GetObjectCommand } from "@aws-sdk/client-s3";
+import { encodeBranchName, isNewerTimestamp } from "./suite-store.mjs";
+import { bodyToBuffer, isNotFound } from "./s3-utils.mjs";
+export async function getLegacy(ctx, suite) {
+    const key = ctx.key(suite, "lcov.info");
+    try {
+        const resp = (await ctx.sendS3("get legacy coverage payload", key, new GetObjectCommand({
+            Bucket: ctx.bucket,
+            Key: key,
+        })));
+        return bodyToBuffer(resp.Body);
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return null;
+        throw err;
+    }
+}
+export async function shouldWritePointer(ctx, suite, branch, incomingTimestamp) {
+    const key = ctx.key(suite, "branch", encodeBranchName(branch), "latest.json");
+    try {
+        const resp = (await ctx.sendS3("get branch pointer for compare", key, new GetObjectCommand({
+            Bucket: ctx.bucket,
+            Key: key,
+        })));
+        if (resp.Body === undefined)
+            return true;
+        const body = await bodyToBuffer(resp.Body);
+        const current = JSON.parse(body.toString("utf8"));
+        return !isNewerTimestamp(current.timestamp, incomingTimestamp);
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return true;
+        throw err;
+    }
+}
+export async function readPointer(ctx, suite, branch) {
+    const keys = [
+        ctx.key(suite, "branch", encodeBranchName(branch), "latest.json"),
+        ctx.key(suite, "branch", branch, "latest.json"),
+    ];
+    let lastNotFound;
+    for (const key of keys) {
+        try {
+            const resp = (await ctx.sendS3("get branch pointer", key, new GetObjectCommand({ Bucket: ctx.bucket, Key: key })));
+            const body = await bodyToBuffer(resp.Body);
+            return JSON.parse(body.toString("utf8"));
+        }
+        catch (err) {
+            if (!isNotFound(err))
+                throw err;
+            lastNotFound = err;
+        }
+    }
+    throw lastNotFound;
+}

package/dist/src/s3-suite-store.d.mts

@@ -1,7 +1,5 @@
+import type { ClientLike, S3OperationDetails } from "./s3-diagnostics.mts";
 import type { SuitePutMeta, SuiteStore } from "./suite-store.mts";
-type ClientLike = {
-    send(cmd: object): Promise<unknown>;
-};
 export type S3SuiteStoreOptions = {
     bucket: string;
     prefix?: string;
@@ -10,19 +8,19 @@ export type S3SuiteStoreOptions = {
     client?: ClientLike;
 };
 export declare class S3SuiteStore implements SuiteStore {
-    private readonly bucket;
+    readonly bucket: string;
     private readonly prefix;
     private readonly client;
     constructor({ bucket, prefix, region, client }: S3SuiteStoreOptions);
-    private key;
+    key(...parts: string[]): string;
     list(): Promise<string[]>;
     get(suite: string, opts?: {
         sha?: string;
         branch?: string;
     }): Promise<Buffer | null>;
     put(suite: string, lcov: Buffer, meta?: SuitePutMeta): Promise<void>;
-    private getLegacy;
-    private shouldWritePointer;
-    private readPointer;
+    sendS3(operation: string, key: string, command: object, details?: S3OperationDetails): Promise<unknown>;
+    private getVersionedPayload;
+    private putLegacyPayload;
+    private putPointer;
 }
-export {};

package/dist/src/s3-suite-store.mjs

@@ -1,5 +1,8 @@
-import { GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
-import { assertSafePathComponent, assertValidTimestamp, encodeBranchName, isNewerTimestamp, } from "./suite-store.mjs";
+import { GetObjectCommand, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { assertSafePathComponent, assertValidTimestamp, encodeBranchName } from "./suite-store.mjs";
+import { createS3Client, sendS3 } from "./s3-diagnostics.mjs";
+import { getLegacy, readPointer, shouldWritePointer } from "./s3-suite-store-reads.mjs";
 import { bodyToBuffer, isNotFound } from "./s3-utils.mjs";
 export class S3SuiteStore {
     bucket;
@@ -8,7 +11,7 @@ export class S3SuiteStore {
     constructor({ bucket, prefix, region, client }) {
         this.bucket = bucket;
         this.prefix = prefix ? prefix.replace(/\/+$/, "") : "";
-        this.client = client ?? new S3Client({ region });
+        this.client = client ?? createS3Client(region);
     }
     key(...parts) {
         return this.prefix ? [this.prefix, ...parts].join("/") : parts.join("/");
@@ -18,7 +21,7 @@ export class S3SuiteStore {
         const suites = [];
         let continuationToken;
         do {
-            const resp = (await this.client.send(new ListObjectsV2Command({
+            const resp = (await this.sendS3("list suites", this.key(), new ListObjectsV2Command({
                 Bucket: this.bucket,
                 Prefix: pfx,
                 Delimiter: "/",
@@ -36,112 +39,101 @@ export class S3SuiteStore {
         if (opts?.sha !== undefined)
             assertSafePathComponent(opts.sha, "sha");
         let sha = opts?.sha;
+        let pointer = null;
         if (!sha) {
             const branch = opts?.branch ?? "main";
             try {
-                const pointer = await this.readPointer(suite, branch);
+                pointer = await readPointer(this, suite, branch);
                 assertSafePathComponent(pointer.sha, "sha");
                 sha = pointer.sha;
             }
             catch (err) {
                 if (isNotFound(err))
-                    return this.getLegacy(suite);
+                    return getLegacy(this, suite);
                 throw err;
             }
         }
-        try {
-            const resp = (await this.client.send(new GetObjectCommand({
-                Bucket: this.bucket,
-                Key: this.key(suite, "sha", sha, "lcov.info"),
-            })));
-            return bodyToBuffer(resp.Body);
-        }
-        catch (err) {
-            if (isNotFound(err))
-                return null;
-            throw err;
-        }
+        return this.getVersionedPayload(suite, sha, pointer, opts?.sha !== undefined);
     }
     async put(suite, lcov, meta) {
         assertSafePathComponent(suite, "suite");
         if (meta === undefined) {
-            await this.client.send(new PutObjectCommand({
-                Bucket: this.bucket,
-                Key: this.key(suite, "lcov.info"),
-                Body: lcov,
-                ContentType: "text/plain",
-            }));
+            await this.putLegacyPayload(suite, lcov);
             return;
         }
         const { sha, branch } = meta;
         assertSafePathComponent(sha, "sha");
         const ts = meta.timestamp ?? new Date().toISOString();
         assertValidTimestamp(ts);
-        await this.client.send(new PutObjectCommand({
+        const payload = gzipSync(lcov);
+        const payloadKey = this.key(suite, "sha", sha, "lcov.info.gz");
+        await this.sendS3("put coverage payload", payloadKey, new PutObjectCommand({
             Bucket: this.bucket,
-            Key: this.key(suite, "sha", sha, "lcov.info"),
-            Body: lcov,
+            Key: payloadKey,
+            Body: payload,
+            ContentEncoding: "gzip",
             ContentType: "text/plain",
-        }));
-        if (!(await this.shouldWritePointer(suite, branch, ts)))
+        }), { rawBytes: lcov.byteLength, storedBytes: payload.byteLength });
+        if (!(await shouldWritePointer(this, suite, branch, ts)))
             return;
-        await this.client.send(new PutObjectCommand({
-            Bucket: this.bucket,
-            Key: this.key(suite, "branch", encodeBranchName(branch), "latest.json"),
-            Body: Buffer.from(JSON.stringify({ sha, timestamp: ts }), "utf8"),
-            ContentType: "application/json",
-        }));
+        await this.putPointer(suite, branch, sha, ts, payloadKey, lcov.byteLength, payload.byteLength);
     }
-    async getLegacy(suite) {
-        try {
-            const resp = (await this.client.send(new GetObjectCommand({
-                Bucket: this.bucket,
-                Key: this.key(suite, "lcov.info"),
-            })));
-            return bodyToBuffer(resp.Body);
-        }
-        catch (err) {
-            if (isNotFound(err))
-                return null;
-            throw err;
-        }
+    sendS3(operation, key, command, details = {}) {
+        return sendS3(this.client, this.bucket, operation, key, command, details);
     }
-    async shouldWritePointer(suite, branch, incomingTimestamp) {
-        try {
-            const resp = (await this.client.send(new GetObjectCommand({
-                Bucket: this.bucket,
-                Key: this.key(suite, "branch", encodeBranchName(branch), "latest.json"),
-            })));
-            if (resp.Body === undefined)
-                return true;
-            const body = await bodyToBuffer(resp.Body);
-            const current = JSON.parse(body.toString("utf8"));
-            return !isNewerTimestamp(current.timestamp, incomingTimestamp);
+    async getVersionedPayload(suite, sha, pointer, explicitSha) {
+        let candidates;
+        if (pointer?.payloadKey !== undefined) {
+            candidates = [{ key: pointer.payloadKey, encoding: pointer.encoding }];
         }
-        catch (err) {
-            if (isNotFound(err))
-                return true;
-            throw err;
+        else if (explicitSha) {
+            candidates = [
+                { key: this.key(suite, "sha", sha, "lcov.info.gz"), encoding: "gzip" },
+                { key: this.key(suite, "sha", sha, "lcov.info"), encoding: undefined },
+            ];
         }
-    }
-    async readPointer(suite, branch) {
-        const keys = [
-            this.key(suite, "branch", encodeBranchName(branch), "latest.json"),
-            this.key(suite, "branch", branch, "latest.json"),
-        ];
-        let lastNotFound;
-        for (const key of keys) {
+        else {
+            candidates = [{ key: this.key(suite, "sha", sha, "lcov.info"), encoding: undefined }];
+        }
+        for (const candidate of candidates) {
             try {
-                const resp = (await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: key })));
+                const resp = (await this.sendS3("get coverage payload", candidate.key, new GetObjectCommand({
+                    Bucket: this.bucket,
+                    Key: candidate.key,
+                })));
                 const body = await bodyToBuffer(resp.Body);
-                return JSON.parse(body.toString("utf8"));
+                return candidate.encoding === "gzip" ? gunzipSync(body) : body;
             }
             catch (err) {
                 if (!isNotFound(err))
                     throw err;
-                lastNotFound = err;
             }
         }
-        throw lastNotFound;
+        return null;
+    }
+    async putLegacyPayload(suite, lcov) {
+        const key = this.key(suite, "lcov.info");
+        await this.sendS3("put legacy coverage payload", key, new PutObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+            Body: lcov,
+            ContentType: "text/plain",
+        }));
+    }
+    async putPointer(suite, branch, sha, timestamp, payloadKey, rawBytes, storedBytes) {
+        const pointerKey = this.key(suite, "branch", encodeBranchName(branch), "latest.json");
+        await this.sendS3("put branch pointer", pointerKey, new PutObjectCommand({
+            Bucket: this.bucket,
+            Key: pointerKey,
+            Body: Buffer.from(JSON.stringify({
+                sha,
+                timestamp,
+                payloadKey,
+                encoding: "gzip",
+                rawBytes,
+                storedBytes,
+            }), "utf8"),
+            ContentType: "application/json",
+        }));
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coverage-check",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Patch-coverage gate: checks that newly added lines meet per-path coverage thresholds. Supports per-suite LCOV accumulation for conditional CI.",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1048.0",
+    "@smithy/node-http-handler": "^4.7.7",
     "js-yaml": "^4.1.1",
     "monocart-coverage-reports": "^2.12.11"
   },