coverage-check 0.2.1 → 0.2.2

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.2.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"
   ],
@@ -33,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);
-  });
-});

package/src/commands/check-args.mts

@@ -1,110 +0,0 @@
-import { makeStore } from "../store-factory.mts";
-import { assertSafePathComponent } from "../suite-store.mts";
-import type { SuiteStore } from "../suite-store.mts";
-import type { GhRunner } from "../github-comment.mts";
-
-export type CheckArgs = {
-  rules: string;
-  artifacts: string;
-  base: string;
-  head: string;
-  pr: number | null;
-  repo: string;
-  json: string | null;
-  stripPrefixes: string[];
-  store: SuiteStore | null;
-  suite: string | null;
-  /** Branch used to resolve baseline from the store. Default: "main". */
-  branch?: string;
-  gh?: GhRunner;
-  /** Path to append the GitHub step summary. Default: $GITHUB_STEP_SUMMARY. */
-  summaryFile?: string | null;
-};
-
-export function parseCheckArgs(argv: string[]): CheckArgs {
-  let storeFs: string | null = null;
-  let storeS3: string | null = null;
-  const args: Omit<CheckArgs, "store"> & { store: SuiteStore | null } = {
-    rules: ".coverage-rules.yml",
-    artifacts: "./coverage-artifacts",
-    base: "origin/main",
-    head: "HEAD",
-    pr: null,
-    repo: process.env["GITHUB_REPOSITORY"] ?? "",
-    json: null,
-    stripPrefixes: [],
-    store: null,
-    suite: null,
-    branch: "main",
-    summaryFile: process.env["GITHUB_STEP_SUMMARY"] ?? null,
-  };
-
-  for (let i = 0; i < argv.length; i++) {
-    const flag = argv[i]!;
-    const next = argv[i + 1];
-    const val = (): string => {
-      if (next === undefined || next.startsWith("--")) {
-        throw new Error(`${flag} requires a value`);
-      }
-      i++;
-      return next;
-    };
-    switch (flag) {
-      case "--rules":
-        args.rules = val();
-        break;
-      case "--artifacts":
-        args.artifacts = val();
-        break;
-      case "--base":
-        args.base = val();
-        break;
-      case "--head":
-        args.head = val();
-        break;
-      case "--repo":
-        args.repo = val();
-        break;
-      case "--json":
-        args.json = val();
-        break;
-      case "--suite": {
-        const s = val();
-        assertSafePathComponent(s, "suite");
-        args.suite = s;
-        break;
-      }
-      case "--strip-prefix":
-        args.stripPrefixes.push(val());
-        break;
-      case "--branch": {
-        const b = val();
-        assertSafePathComponent(b, "branch");
-        args.branch = b;
-        break;
-      }
-      case "--store":
-      case "--store-fs":
-        storeFs = val();
-        break;
-      case "--store-s3":
-        storeS3 = val();
-        break;
-      case "--pr": {
-        const raw = val();
-        if (!/^\d+$/.test(raw) || raw === "0")
-          throw new Error(`--pr must be a positive integer, got: ${JSON.stringify(raw)}`);
-        args.pr = parseInt(raw, 10);
-        break;
-      }
-      default:
-        throw new Error(`unknown flag: ${flag}`);
-    }
-  }
-
-  if (storeFs && storeS3) throw new Error("--store-fs and --store-s3 are mutually exclusive");
-  if (args.pr !== null && args.repo.trim() === "")
-    throw new Error("--repo is required when --pr is set (or define GITHUB_REPOSITORY)");
-  args.store = makeStore({ fs: storeFs, s3: storeS3 });
-  return args;
-}

package/src/commands/check.mts

@@ -1,147 +0,0 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { parseLcov } from "../lcov-parser.mts";
-import { mergeLcov } from "../lcov-merge.mts";
-import { getChangedLines } from "../diff-parser.mts";
-import { loadRules } from "../rules.mts";
-import { computePatchCoverage } from "../patch-coverage.mts";
-import { collapseRanges, renderFailureComment } from "../report.mts";
-import { upsertComment } from "../github-comment.mts";
-import { collectLcovFiles, buildStripPrefixes } from "../load-artifacts.mts";
-import { writeSummary } from "../step-summary.mts";
-import { parseCheckArgs } from "./check-args.mts";
-import type { CheckArgs } from "./check-args.mts";
-import type { SuiteSource } from "../step-summary.mts";
-import type { LcovData } from "../types.mts";
-export type { CheckArgs } from "./check-args.mts";
-
-const stdout = (msg: string) => process.stdout.write(`${msg}\n`);
-const stderr = (msg: string) => process.stderr.write(`${msg}\n`);
-
-export async function main(argv: string[]): Promise<number> {
-  let args: CheckArgs;
-  try {
-    args = parseCheckArgs(argv);
-  } catch (err) {
-    stderr(`coverage-check: ${String(err)}`);
-    return 2;
-  }
-  return runCheck(args);
-}
-
-export async function runCheck(args: CheckArgs): Promise<number> {
-  let rules;
-  try {
-    rules = loadRules(args.rules);
-  } catch (err) {
-    stderr(`coverage-check: failed to load rules: ${err}`);
-    return 2;
-  }
-
-  const branch = args.branch ?? "main";
-  const stripPrefixes = buildStripPrefixes(args.stripPrefixes);
-  const reports: LcovData[] = [];
-  const suiteSources: SuiteSource[] = [];
-
-  if (args.store !== null) {
-    const suites = await args.store.list();
-    for (const suite of suites) {
-      if (suite === args.suite) continue;
-      const buf = await args.store.get(suite, { branch });
-      if (buf !== null) {
-        const lcov = parseLcov(buf.toString("utf8"), stripPrefixes);
-        reports.push(lcov);
-        suiteSources.push({ suite, source: "store", lcov });
-      }
-    }
-  }
-
-  const lcovFiles = collectLcovFiles(args.artifacts);
-  const freshLcovs: LcovData[] = [];
-  for (const f of lcovFiles) {
-    const lcov = parseLcov(readFileSync(f, "utf8"), stripPrefixes);
-    reports.push(lcov);
-    freshLcovs.push(lcov);
-  }
-  if (freshLcovs.length > 0) {
-    suiteSources.push({
-      suite: args.suite ?? "(current)",
-      source: "fresh",
-      lcov: mergeLcov(freshLcovs),
-    });
-  }
-
-  if (reports.length === 0) {
-    stderr(`coverage-check: no coverage data found — skipping`);
-    return 0;
-  }
-
-  const lcov = mergeLcov(reports);
-
-  let diff;
-  try {
-    diff = await getChangedLines(args.base, args.head);
-  } catch (err) {
-    stderr(`coverage-check: git diff failed: ${err}`);
-    return 2;
-  }
-
-  const { buckets, informational } = computePatchCoverage(diff, lcov, rules);
-  const passed = buckets.every((b) => b.passed);
-  const result = { buckets, informational, passed };
-
-  if (args.json) {
-    writeFileSync(args.json, JSON.stringify(result, null, 2));
-  }
-
-  const runUrl =
-    process.env["GITHUB_SERVER_URL"] && process.env["GITHUB_RUN_ID"]
-      ? `${process.env["GITHUB_SERVER_URL"]}/${args.repo}/actions/runs/${process.env["GITHUB_RUN_ID"]}`
-      : "N/A";
-
-  if (!passed) {
-    stdout("\ncoverage-check: FAILED\n");
-    for (const bucket of buckets.filter((b) => !b.passed)) {
-      /* c8 ignore next -- bucket.coverable is always > 0 by patch-coverage.mts L36 guard */
-      const pct =
-        bucket.coverable > 0 ? `${((bucket.hit / bucket.coverable) * 100).toFixed(1)}%` : "—";
-      stdout(
-        `  ${bucket.rule}: ${pct} (${bucket.hit}/${bucket.coverable}) — threshold ${bucket.threshold}%`,
-      );
-      for (const file of bucket.files.filter((f) => f.uncoveredLines.length > 0)) {
-        stdout(`    ${file.file}: ${collapseRanges(file.uncoveredLines)}`);
-      }
-    }
-  } else {
-    stdout("\ncoverage-check: PASSED\n");
-    for (const bucket of buckets) {
-      /* c8 ignore next -- bucket.coverable is always > 0 by patch-coverage.mts L36 guard */
-      const pct =
-        bucket.coverable > 0 ? `${((bucket.hit / bucket.coverable) * 100).toFixed(1)}%` : "—";
-      stdout(`  ${bucket.rule}: ${pct} ✓`);
-    }
-  }
-
-  const summaryFile =
-    args.summaryFile !== undefined
-      ? args.summaryFile
-      : (process.env["GITHUB_STEP_SUMMARY"] ?? null);
-  if (summaryFile) {
-    try {
-      writeSummary(summaryFile, suiteSources, result, runUrl, branch);
-    } catch (err) {
-      stderr(`coverage-check: failed to write step summary: ${err}`);
-      return 2;
-    }
-  }
-
-  if (args.pr !== null && args.repo) {
-    const body = passed ? "" : renderFailureComment(result, runUrl);
-    try {
-      await upsertComment(body, args.repo, args.pr, passed, args.gh);
-    } catch (err) {
-      stderr(`coverage-check: failed to post PR comment: ${err}`);
-    }
-  }
-
-  return passed ? 0 : 1;
-}