coverage-check 0.1.1 → 0.2.2

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

@@ -0,0 +1,147 @@
+import { GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
+import { assertSafePathComponent, assertValidTimestamp, encodeBranchName, isNewerTimestamp, } from "./suite-store.mjs";
+import { bodyToBuffer, isNotFound } from "./s3-utils.mjs";
+export class S3SuiteStore {
+    bucket;
+    prefix;
+    client;
+    constructor({ bucket, prefix, region, client }) {
+        this.bucket = bucket;
+        this.prefix = prefix ? prefix.replace(/\/+$/, "") : "";
+        this.client = client ?? new S3Client({ region });
+    }
+    key(...parts) {
+        return this.prefix ? [this.prefix, ...parts].join("/") : parts.join("/");
+    }
+    async list() {
+        const pfx = this.prefix ? `${this.prefix}/` : "";
+        const suites = [];
+        let continuationToken;
+        do {
+            const resp = (await this.client.send(new ListObjectsV2Command({
+                Bucket: this.bucket,
+                Prefix: pfx,
+                Delimiter: "/",
+                ...(continuationToken ? { ContinuationToken: continuationToken } : {}),
+            })));
+            suites.push(...(resp.CommonPrefixes ?? [])
+                .map((cp) => cp.Prefix?.replace(pfx, "").replace(/\/$/, "") ?? "")
+                .filter(Boolean));
+            continuationToken = resp.IsTruncated ? resp.NextContinuationToken : undefined;
+        } while (continuationToken);
+        return suites;
+    }
+    async get(suite, opts) {
+        assertSafePathComponent(suite, "suite");
+        if (opts?.sha !== undefined)
+            assertSafePathComponent(opts.sha, "sha");
+        let sha = opts?.sha;
+        if (!sha) {
+            const branch = opts?.branch ?? "main";
+            try {
+                const pointer = await this.readPointer(suite, branch);
+                assertSafePathComponent(pointer.sha, "sha");
+                sha = pointer.sha;
+            }
+            catch (err) {
+                if (isNotFound(err))
+                    return this.getLegacy(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;
+        }
+    }
+    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",
+            }));
+            return;
+        }
+        const { sha, branch } = meta;
+        assertSafePathComponent(sha, "sha");
+        const ts = meta.timestamp ?? new Date().toISOString();
+        assertValidTimestamp(ts);
+        await this.client.send(new PutObjectCommand({
+            Bucket: this.bucket,
+            Key: this.key(suite, "sha", sha, "lcov.info"),
+            Body: lcov,
+            ContentType: "text/plain",
+        }));
+        if (!(await this.shouldWritePointer(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",
+        }));
+    }
+    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;
+        }
+    }
+    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);
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return true;
+            throw err;
+        }
+    }
+    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) {
+            try {
+                const resp = (await this.client.send(new GetObjectCommand({ Bucket: this.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-utils.d.mts

@@ -0,0 +1,2 @@
+export declare function isNotFound(err: unknown): boolean;
+export declare function bodyToBuffer(body: unknown): Promise<Buffer>;

package/dist/src/s3-utils.mjs

@@ -0,0 +1,14 @@
+import { Readable } from "node:stream";
+import { buffer } from "node:stream/consumers";
+export function isNotFound(err) {
+    return err instanceof Error && (err.name === "NoSuchKey" || err.name === "NotFound");
+}
+export async function bodyToBuffer(body) {
+    if (body instanceof Readable)
+        return buffer(body);
+    if (body instanceof Uint8Array)
+        return Buffer.from(body);
+    if (body instanceof Blob)
+        return Buffer.from(await body.arrayBuffer());
+    throw new Error("unexpected S3 response body type");
+}

package/dist/src/step-summary.d.mts

@@ -0,0 +1,9 @@
+import type { LcovData } from "./types.mts";
+import type { CoverageCheckResult } from "./types.mts";
+export type SuiteSource = {
+    suite: string;
+    source: "fresh" | "store";
+    lcov: LcovData;
+};
+export declare function buildSummaryMarkdown(suiteSources: SuiteSource[], result: CoverageCheckResult, runUrl: string, branch?: string): string;
+export declare function writeSummary(summaryFile: string, suiteSources: SuiteSource[], result: CoverageCheckResult, runUrl: string, branch?: string): void;

package/dist/src/step-summary.mjs

@@ -0,0 +1,70 @@
+import { appendFileSync } from "node:fs";
+function suiteTotals(lcov) {
+    let hit = 0;
+    let total = 0;
+    for (const lines of lcov.values()) {
+        for (const count of lines.values()) {
+            total++;
+            if (count > 0)
+                hit++;
+        }
+    }
+    return { hit, total };
+}
+function pctStr(hit, total) {
+    if (total === 0)
+        return "—";
+    return `${((hit / total) * 100).toFixed(1)}% (${hit}/${total})`;
+}
+function escMd(s) {
+    return s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
+function codeSpan(s) {
+    const escaped = escMd(s);
+    const longestRun = Math.max(0, ...Array.from(escaped.matchAll(/`+/g), (m) => m[0].length));
+    if (longestRun === 0)
+        return `\`${escaped}\``;
+    const ticks = "`".repeat(longestRun + 1);
+    return `${ticks} ${escaped} ${ticks}`;
+}
+export function buildSummaryMarkdown(suiteSources, result, runUrl, branch = "main") {
+    const suiteRows = suiteSources
+        .map(({ suite, source, lcov }) => {
+        const { hit, total } = suiteTotals(lcov);
+        const sourceLabel = source === "fresh" ? "fresh" : `store (${escMd(branch)})`;
+        return `| ${codeSpan(suite)} | ${sourceLabel} | ${pctStr(hit, total)} |`;
+    })
+        .join("\n");
+    const suiteTable = [
+        "| Suite | Source | Line coverage |",
+        "|---|---|---|",
+        suiteRows || "| — | — | — |",
+    ].join("\n");
+    const ruleRows = result.buckets
+        .map((b) => {
+        const status = b.passed ? "✅" : "❌";
+        const pct = b.coverable > 0 ? `${((b.hit / b.coverable) * 100).toFixed(1)}%` : "—";
+        return `| ${codeSpan(b.rule)} | ${b.threshold}% | ${pct} | ${status} |`;
+    })
+        .join("\n");
+    const ruleTable = [
+        "| Rule | Threshold | Patch coverage | Status |",
+        "|---|---|---|---|",
+        ruleRows || "| — | — | — | — |",
+    ].join("\n");
+    const overall = result.passed ? "✅ passed" : "❌ failed";
+    const runLink = runUrl !== "N/A" ? `\n\n_[View run](${runUrl})_` : "";
+    return `## Coverage summary — ${overall}
+
+### Suite totals
+
+${suiteTable}
+
+### Patch coverage
+
+${ruleTable}${runLink}
+`;
+}
+export function writeSummary(summaryFile, suiteSources, result, runUrl, branch) {
+    appendFileSync(summaryFile, buildSummaryMarkdown(suiteSources, result, runUrl, branch), "utf8");
+}

package/dist/src/store-factory.d.mts

@@ -0,0 +1,11 @@
+import type { SuiteStore } from "./suite-store.mts";
+/** Parse "bucket/prefix" or "bucket" into S3SuiteStore constructor args. */
+export declare function parseS3Spec(spec: string): {
+    bucket: string;
+    prefix?: string;
+};
+/** Build a SuiteStore from CLI flag values. Returns null if neither is set. */
+export declare function makeStore(opts: {
+    fs?: string | null;
+    s3?: string | null;
+}): SuiteStore | null;

package/dist/src/store-factory.mjs

@@ -0,0 +1,23 @@
+import { FileSystemSuiteStore } from "./suite-store.mjs";
+import { S3SuiteStore } from "./s3-suite-store.mjs";
+/** Parse "bucket/prefix" or "bucket" into S3SuiteStore constructor args. */
+export function parseS3Spec(spec) {
+    const slash = spec.indexOf("/");
+    const bucket = slash === -1 ? spec : spec.slice(0, slash);
+    if (!bucket)
+        throw new Error(`invalid S3 spec ${JSON.stringify(spec)}: bucket must not be empty`);
+    if (slash === -1)
+        return { bucket };
+    const prefix = spec.slice(slash + 1).replace(/^\/+|\/+$/g, "");
+    return prefix ? { bucket, prefix } : { bucket };
+}
+/** Build a SuiteStore from CLI flag values. Returns null if neither is set. */
+export function makeStore(opts) {
+    if (opts.s3 != null) {
+        const { bucket, prefix } = parseS3Spec(opts.s3);
+        return new S3SuiteStore({ bucket, prefix });
+    }
+    if (opts.fs != null)
+        return new FileSystemSuiteStore(opts.fs);
+    return null;
+}

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

@@ -0,0 +1,51 @@
+import type { SuiteMeta } from "./types.mts";
+export declare function assertSafePathComponent(value: string, label: string): void;
+export type { SuiteMeta };
+export type SuitePutMeta = {
+    sha: string;
+    branch: string;
+    timestamp?: string;
+};
+export declare function encodeBranchName(branch: string): string;
+export declare function decodeBranchName(encoded: string): string;
+export interface SuiteStore {
+    /** Returns all suite names currently in the store. */
+    list(): Promise<string[]>;
+    /**
+     * Returns the merged LCOV bytes for a suite, or null if absent.
+     * Resolves by sha if opts.sha is set; otherwise follows the branch pointer
+     * (opts.branch, defaulting to "main").
+     */
+    get(suite: string, opts?: {
+        sha?: string;
+        branch?: string;
+    }): Promise<Buffer | null>;
+    /** Stores the merged LCOV bytes for a suite. sha and branch enable pointer storage. */
+    put(suite: string, lcov: Buffer, meta?: SuitePutMeta): Promise<void>;
+}
+/**
+ * Filesystem-backed SuiteStore.
+ *
+ * Layout:
+ *   <root>/<suite>/sha/<sha>/lcov.info      — LCOV payload
+ *   <root>/<suite>/branch/<encoded-branch>/latest.json — { sha, timestamp }
+ *
+ * Legacy layout is still readable/writable when no sha/branch metadata is given:
+ *   <root>/<suite>/lcov.info
+ *
+ * Transport is the caller's responsibility (e.g. S3 sync, git orphan branch).
+ */
+export declare class FileSystemSuiteStore implements SuiteStore {
+    private readonly root;
+    constructor(root: 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;
+}
+export declare function isNewerTimestamp(current: string | undefined, incoming: string): boolean;
+export declare function assertValidTimestamp(timestamp: string): void;

package/dist/src/suite-store.mjs

@@ -0,0 +1,154 @@
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export function assertSafePathComponent(value, label) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value === "." ||
+        value === ".." ||
+        value.includes("/") ||
+        value.includes("\\")) {
+        throw new Error(`invalid ${label}: ${JSON.stringify(value)}`);
+    }
+}
+export function encodeBranchName(branch) {
+    if (typeof branch !== "string" || branch.length === 0) {
+        throw new Error(`invalid branch: ${JSON.stringify(branch)}`);
+    }
+    return Buffer.from(branch, "utf8").toString("base64url");
+}
+export function decodeBranchName(encoded) {
+    assertSafePathComponent(encoded, "branch");
+    return Buffer.from(encoded, "base64url").toString("utf8");
+}
+/**
+ * Filesystem-backed SuiteStore.
+ *
+ * Layout:
+ *   <root>/<suite>/sha/<sha>/lcov.info      — LCOV payload
+ *   <root>/<suite>/branch/<encoded-branch>/latest.json — { sha, timestamp }
+ *
+ * Legacy layout is still readable/writable when no sha/branch metadata is given:
+ *   <root>/<suite>/lcov.info
+ *
+ * Transport is the caller's responsibility (e.g. S3 sync, git orphan branch).
+ */
+export class FileSystemSuiteStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async list() {
+        try {
+            return readdirSync(this.root, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+    }
+    async get(suite, opts) {
+        assertSafePathComponent(suite, "suite");
+        if (opts?.sha !== undefined)
+            assertSafePathComponent(opts.sha, "sha");
+        let sha = opts?.sha;
+        if (!sha) {
+            const branch = opts?.branch ?? "main";
+            const pointerPaths = [
+                join(this.root, suite, "branch", encodeBranchName(branch), "latest.json"),
+                join(this.root, suite, "branch", branch, "latest.json"),
+            ];
+            try {
+                const pointer = readPointerFile(pointerPaths);
+                assertSafePathComponent(pointer.sha, "sha");
+                sha = pointer.sha;
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return this.getLegacy(suite);
+                throw err;
+            }
+        }
+        const lcovPath = join(this.root, suite, "sha", sha, "lcov.info");
+        try {
+            return readFileSync(lcovPath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+    async put(suite, lcov, meta) {
+        assertSafePathComponent(suite, "suite");
+        if (meta === undefined) {
+            const suiteDir = join(this.root, suite);
+            mkdirSync(suiteDir, { recursive: true });
+            writeFileSync(join(suiteDir, "lcov.info"), lcov);
+            return;
+        }
+        const { sha, branch } = meta;
+        assertSafePathComponent(sha, "sha");
+        const shaDir = join(this.root, suite, "sha", sha);
+        mkdirSync(shaDir, { recursive: true });
+        writeFileSync(join(shaDir, "lcov.info"), lcov);
+        const branchDir = join(this.root, suite, "branch", encodeBranchName(branch));
+        mkdirSync(branchDir, { recursive: true });
+        const pointerPath = join(branchDir, "latest.json");
+        const timestamp = meta.timestamp ?? new Date().toISOString();
+        assertValidTimestamp(timestamp);
+        if (!this.shouldWritePointer(pointerPath, timestamp))
+            return;
+        writeFileSync(pointerPath, JSON.stringify({ sha, timestamp }, null, 2));
+    }
+    getLegacy(suite) {
+        try {
+            return readFileSync(join(this.root, suite, "lcov.info"));
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+    shouldWritePointer(pointerPath, incomingTimestamp) {
+        try {
+            const current = JSON.parse(readFileSync(pointerPath, "utf8"));
+            return !isNewerTimestamp(current.timestamp, incomingTimestamp);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return true;
+            throw err;
+        }
+    }
+}
+export function isNewerTimestamp(current, incoming) {
+    assertValidTimestamp(incoming);
+    if (!current)
+        return false;
+    const currentMs = Date.parse(current);
+    const incomingMs = Date.parse(incoming);
+    return Number.isFinite(currentMs) && Number.isFinite(incomingMs) && currentMs > incomingMs;
+}
+export function assertValidTimestamp(timestamp) {
+    if (!Number.isFinite(Date.parse(timestamp))) {
+        throw new Error(`invalid timestamp: ${JSON.stringify(timestamp)}`);
+    }
+}
+function readPointerFile(paths) {
+    let lastNotFound = null;
+    for (const path of paths) {
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            lastNotFound = err;
+        }
+    }
+    throw lastNotFound;
+}

package/dist/src/types.d.mts

@@ -0,0 +1,36 @@
+export type CoverageRule = {
+    paths: string;
+    patch_coverage_min: number;
+};
+export type CoverageRules = {
+    rules: CoverageRule[];
+};
+/** Map from repo-root-relative file path to map of line number → hit count. */
+export type LcovData = Map<string, Map<number, number>>;
+/** Map from repo-root-relative file path to set of added/modified line numbers. */
+export type DiffLines = Map<string, Set<number>>;
+export type FileCoverageResult = {
+    file: string;
+    coverable: number;
+    hit: number;
+    uncoveredLines: number[];
+    rule: string | null;
+};
+export type BucketResult = {
+    rule: string;
+    threshold: number;
+    coverable: number;
+    hit: number;
+    files: FileCoverageResult[];
+    passed: boolean;
+};
+export type CoverageCheckResult = {
+    buckets: BucketResult[];
+    informational: FileCoverageResult[];
+    passed: boolean;
+};
+export type SuiteMeta = {
+    sha?: string;
+    branch?: string;
+    timestamp?: string;
+};

package/dist/src/types.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,16 +1,29 @@
 {
   "name": "coverage-check",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "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",
   "type": "module",
   "bin": {
-    "coverage-check": "./bin/coverage-check.mts"
+    "coverage-check": "./bin/coverage-check.mjs"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/src/coverage-check.d.mts",
+      "import": "./dist/src/coverage-check.mjs"
+    },
+    "./src/*.mts": {
+      "types": "./dist/src/*.d.mts",
+      "import": "./dist/src/*.mjs"
+    },
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/src/coverage-check.d.mts",
   "files": [
-    "bin/**",
-    "src/**",
+    "dist/**",
+    "bin/coverage-check.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -18,6 +31,7 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1048.0",
     "js-yaml": "^4.1.1"
   },
   "devDependencies": {
@@ -32,7 +46,8 @@
   },
   "scripts": {
     "prepare": "husky",
-    "prepublishOnly": "npm run typecheck && npm test",
+    "build": "tsc --project tsconfig.build.json",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint src/ bin/",
     "format": "oxfmt src/ bin/ README.md",

package/bin/coverage-check.mts

@@ -1,6 +0,0 @@
-#!/usr/bin/env -S node --experimental-strip-types --no-warnings
-
-import { main } from "../src/cli.mts";
-
-/* c8 ignore next */
-process.exit(await main(process.argv.slice(2)));

package/src/cli.mts

@@ -1,15 +0,0 @@
-import { main as checkMain } from "./commands/check.mts";
-import { main as storePutMain } from "./commands/store-put.mts";
-
-const stderr = (msg: string) => process.stderr.write(`${msg}\n`);
-
-export async function main(argv: string[]): Promise<number> {
-  const sub = argv[0];
-
-  if (!sub || sub.startsWith("-")) return checkMain(argv);
-  if (sub === "check") return checkMain(argv.slice(1));
-  if (sub === "store-put") return storePutMain(argv.slice(1));
-
-  stderr(`coverage-check: unknown subcommand: ${JSON.stringify(sub)}`);
-  return 2;
-}

package/src/cli.test.mts

@@ -1,45 +0,0 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { main } from "./cli.mts";
-
-describe("cli subcommand dispatch", () => {
-  let tmpDir: string;
-  let rulesPath: string;
-  let artifactsDir: string;
-
-  beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), "cli-dispatch-"));
-    rulesPath = join(tmpDir, "rules.yml");
-    artifactsDir = join(tmpDir, "artifacts");
-    mkdirSync(artifactsDir);
-    writeFileSync(rulesPath, "rules:\n  - paths: backend/**\n    patch_coverage_min: 90\n");
-  });
-
-  afterEach(() => {
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it("defaults to check when no args given", async () => {
-    // No args → check → no lcov files → returns 0
-    expect(await main(["--rules", rulesPath, "--artifacts", artifactsDir])).toBe(0);
-  });
-
-  it("explicit check subcommand works", async () => {
-    expect(await main(["check", "--rules", rulesPath, "--artifacts", artifactsDir])).toBe(0);
-  });
-
-  it("explicit store-put subcommand returns 2 when --suite is missing", async () => {
-    expect(await main(["store-put", "--store", "/tmp/store"])).toBe(2);
-  });
-
-  it("returns 2 for unknown subcommand", async () => {
-    expect(await main(["unknown-command"])).toBe(2);
-  });
-
-  it("flags-first argument (starting with --) goes to check", async () => {
-    // '--rules' starts with '-', so dispatch goes to check
-    expect(await main(["--rules", rulesPath, "--artifacts", artifactsDir])).toBe(0);
-  });
-});