@tested/cli 0.1.7 → 0.1.8

package/dist/tested.js

@@ -46,6 +46,8 @@ function badge(kind) {
       return pc.cyan("[INFO]");
     case "skip":
       return pc.cyan("[SKIP]");
+    case "missing":
+      return pc.yellow("[MISSING]");
   }
 }
 function metricBar(pct3, width = 10) {
@@ -349,24 +351,576 @@ function registerInitCommand(program2) {
 }
 
 // src/commands/setup.ts
-import { existsSync as existsSync4 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync5 } from "fs";
+import { join as join6 } from "path";
 import "commander";
 
 // src/commands/doctor.ts
-import { existsSync as existsSync3, accessSync, constants as fsConstants } from "fs";
-import { basename, isAbsolute as isAbsolute2, join as join4, resolve as resolve4 } from "path";
+import { existsSync as existsSync4, accessSync, constants as fsConstants } from "fs";
+import { basename as basename2, isAbsolute as isAbsolute2, join as join5, resolve as resolve5 } from "path";
 import "commander";
 import { simpleGit as simpleGit3 } from "simple-git";
 
 // src/config.ts
-import { readFile } from "fs/promises";
-import { join as join2 } from "path";
+import { readFile as readFile4 } from "fs/promises";
+import { join as join3 } from "path";
 import { parse as parseYaml } from "yaml";
 
 // src/schemas.ts
 import { z as z2 } from "zod";
 
+// src/core/coverage.ts
+import { readFile as readFile3, stat as stat2 } from "fs/promises";
+import { basename } from "path";
+
+// src/core/istanbul.ts
+import { readFile } from "fs/promises";
+
+// src/core/coverage-model.ts
+import { isAbsolute, relative, resolve } from "path";
+function resolveCoverageEntryPath(repoRoot, entryPath) {
+  const cleaned = entryPath.trim().replace(/\\/g, "/");
+  if (cleaned.startsWith("file://")) {
+    try {
+      return decodeURIComponent(new URL(cleaned).pathname);
+    } catch {
+      return resolve(repoRoot, cleaned.replace(/^file:\/\//, ""));
+    }
+  }
+  return isAbsolute(cleaned) ? resolve(cleaned) : resolve(repoRoot, cleaned);
+}
+function isCoveragePathInsideRoot(repoRoot, entryPath) {
+  const root = resolve(repoRoot);
+  let absPath;
+  try {
+    absPath = resolveCoverageEntryPath(root, entryPath);
+  } catch {
+    return false;
+  }
+  const relPath = relative(root, absPath).split("\\").join("/");
+  if (!relPath || relPath === "") return true;
+  if (isAbsolute(relPath)) return false;
+  if (relPath === ".." || relPath.startsWith("../")) return false;
+  return true;
+}
+function toFileCoverage(repoRoot, entryPath, statements) {
+  if (!isCoveragePathInsideRoot(repoRoot, entryPath)) return null;
+  const absPath = resolveCoverageEntryPath(repoRoot, entryPath);
+  const relPath = relative(resolve(repoRoot), absPath).split("\\").join("/");
+  return { path: relPath, absPath, statements };
+}
+function statementsFromLineHits(lineHits) {
+  return [...lineHits].filter(([line]) => Number.isInteger(line) && line > 0).sort((a, b) => a[0] - b[0]).map(([line, hits]) => ({
+    id: String(line),
+    startLine: line,
+    endLine: line,
+    hits: Number.isFinite(hits) && hits > 0 ? hits : 0
+  }));
+}
+function mergeLineHits(into, line, hits) {
+  if (!Number.isInteger(line) || line <= 0) return;
+  const n = Number.isFinite(hits) && hits > 0 ? hits : 0;
+  into.set(line, (into.get(line) ?? 0) + n);
+}
+function fileCoverageFromLineHits(repoRoot, entryPath, lineHits) {
+  return toFileCoverage(repoRoot, entryPath, statementsFromLineHits(lineHits));
+}
+
+// src/core/istanbul.ts
+function parseIstanbulString(raw, repoRoot, pathForError) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `Istanbul/V8 JSON is not valid JSON${pathForError ? ` (${pathForError})` : ""}`
+    );
+  }
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new Error("Istanbul/V8 JSON must be an object of file entries");
+  }
+  const out = [];
+  for (const entry of Object.values(data)) {
+    if (!entry || typeof entry !== "object" || typeof entry.path !== "string") {
+      continue;
+    }
+    if (!entry.statementMap || typeof entry.statementMap !== "object") {
+      continue;
+    }
+    const statements = Object.entries(
+      entry.statementMap
+    ).map(([id, loc]) => ({
+      id,
+      startLine: loc.start.line,
+      endLine: loc.end.line,
+      hits: entry.s?.[id] ?? 0
+    }));
+    const file = toFileCoverage(repoRoot, entry.path, statements);
+    if (file) out.push(file);
+  }
+  return out;
+}
+
+// src/core/formats/lcov.ts
+function parseLcov(raw, repoRoot) {
+  const byFile = /* @__PURE__ */ new Map();
+  let current = null;
+  for (const rawLine of raw.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (line.startsWith("SF:")) {
+      current = line.slice(3).trim();
+      if (current && !byFile.has(current)) byFile.set(current, /* @__PURE__ */ new Map());
+      continue;
+    }
+    if (line === "end_of_record") {
+      current = null;
+      continue;
+    }
+    if (!current || !line.startsWith("DA:")) continue;
+    const payload = line.slice(3);
+    const comma = payload.indexOf(",");
+    if (comma < 0) continue;
+    const lineNo = Number(payload.slice(0, comma));
+    const hitsRaw = payload.slice(comma + 1).split(",")[0] ?? "0";
+    const hits = Number(hitsRaw);
+    mergeLineHits(byFile.get(current), lineNo, hits);
+  }
+  const out = [];
+  for (const [path, hits] of byFile) {
+    const file = fileCoverageFromLineHits(repoRoot, path, hits);
+    if (file) out.push(file);
+  }
+  return out;
+}
+
+// src/core/formats/xml.ts
+function decodeXmlEntities(s) {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+function xmlAttr(tag, name) {
+  const re = new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, "i");
+  const m = tag.match(re);
+  if (!m) return void 0;
+  return decodeXmlEntities(m[2] ?? m[3] ?? "");
+}
+
+// src/core/formats/cobertura.ts
+function parseCobertura(raw, repoRoot) {
+  const byFile = /* @__PURE__ */ new Map();
+  const classRe = /<class\b([^>]*)>([\s\S]*?)<\/class>|<class\b([^>]*)\s*\/>/gi;
+  let classMatch;
+  while ((classMatch = classRe.exec(raw)) !== null) {
+    const attrs = (classMatch[1] ?? classMatch[3] ?? "").trim();
+    const body = classMatch[2] ?? "";
+    const filename = xmlAttr(attrs, "filename")?.trim();
+    const name = xmlAttr(attrs, "name")?.trim();
+    const path = classPath(filename, name);
+    if (!path) continue;
+    let hits = byFile.get(path);
+    if (!hits) {
+      hits = /* @__PURE__ */ new Map();
+      byFile.set(path, hits);
+    }
+    const lineRe = /<line\b([^>]*)\/?>/gi;
+    let lineMatch;
+    while ((lineMatch = lineRe.exec(body)) !== null) {
+      const lineAttrs = lineMatch[1] ?? "";
+      const number = Number(xmlAttr(lineAttrs, "number"));
+      const hitCount = Number(xmlAttr(lineAttrs, "hits") ?? "0");
+      mergeLineHits(hits, number, hitCount);
+    }
+  }
+  const out = [];
+  for (const [path, hits] of byFile) {
+    const file = fileCoverageFromLineHits(repoRoot, path, hits);
+    if (file) out.push(file);
+  }
+  return out;
+}
+function classPath(filename, name) {
+  if (filename) {
+    if (filename.includes("/") || filename.includes("\\")) return filename;
+    if (name && name.includes(".")) {
+      const dir = name.split(".").slice(0, -1).join("/");
+      return dir ? `${dir}/${filename}` : filename;
+    }
+    return filename;
+  }
+  if (name) return name.replace(/\./g, "/");
+  return null;
+}
+
+// src/core/formats/gcov.ts
+import { readdir, readFile as readFile2, stat } from "fs/promises";
+import { join as join2 } from "path";
+function parseGcov(raw, repoRoot) {
+  const byFile = /* @__PURE__ */ new Map();
+  let current = null;
+  for (const rawLine of raw.split(/\r?\n/)) {
+    const parsed = parseGcovLine(rawLine);
+    if (!parsed) continue;
+    if (parsed.lineNo === 0) {
+      const source = sourceFromMeta(parsed.source);
+      if (source) {
+        current = source;
+        if (!byFile.has(current)) byFile.set(current, /* @__PURE__ */ new Map());
+      }
+      continue;
+    }
+    if (parsed.hits === null) continue;
+    if (!current) continue;
+    mergeLineHits(byFile.get(current), parsed.lineNo, parsed.hits);
+  }
+  const out = [];
+  for (const [path, hits] of byFile) {
+    const file = fileCoverageFromLineHits(repoRoot, path, hits);
+    if (file) out.push(file);
+  }
+  return out;
+}
+async function parseGcovPath(opts) {
+  const info = await stat(opts.path);
+  if (info.isDirectory()) {
+    const names = (await readdir(opts.path)).filter((n) => n.endsWith(".gcov")).sort();
+    if (names.length === 0) {
+      throw new Error(
+        `no .gcov files in ${opts.path}. Run \`gcov\` on your .gcda files (binary .gcno/.gcda notes are not parsed).`
+      );
+    }
+    const byPath = /* @__PURE__ */ new Map();
+    const absByPath = /* @__PURE__ */ new Map();
+    for (const name of names) {
+      const filePath = join2(opts.path, name);
+      const raw2 = await readFile2(filePath, "utf8");
+      for (const file of parseGcov(raw2, opts.repoRoot)) {
+        let hits = byPath.get(file.path);
+        if (!hits) {
+          hits = /* @__PURE__ */ new Map();
+          byPath.set(file.path, hits);
+          absByPath.set(file.path, file.absPath);
+        }
+        for (const s of file.statements) {
+          mergeLineHits(hits, s.startLine, s.hits);
+        }
+      }
+    }
+    return [...byPath.entries()].map(([path, hits]) => ({
+      path,
+      absPath: absByPath.get(path),
+      statements: statementsFromLineHits(hits)
+    }));
+  }
+  const raw = await readFile2(opts.path, "utf8");
+  return parseGcov(raw, opts.repoRoot);
+}
+function parseGcovLine(rawLine) {
+  const first = rawLine.indexOf(":");
+  if (first < 0) return null;
+  const second = rawLine.indexOf(":", first + 1);
+  if (second < 0) return null;
+  const countField = rawLine.slice(0, first).trim();
+  const lineNo = Number(rawLine.slice(first + 1, second).trim());
+  if (!Number.isInteger(lineNo)) return null;
+  const source = rawLine.slice(second + 1);
+  if (countField === "-" || countField === "") {
+    return { hits: null, lineNo, source };
+  }
+  if (countField.startsWith("#") || countField.startsWith("=")) {
+    return { hits: 0, lineNo, source };
+  }
+  const hits = Number.parseInt(countField.replace(/\*+$/, ""), 10);
+  if (!Number.isFinite(hits)) return { hits: 0, lineNo, source };
+  return { hits, lineNo, source };
+}
+function sourceFromMeta(source) {
+  const trimmed = source.trim();
+  const m = trimmed.match(/^Source:(.*)$/);
+  if (!m) return null;
+  const path = (m[1] ?? "").trim();
+  return path || null;
+}
+
+// src/core/formats/jacoco.ts
+function parseJacoco(raw, repoRoot) {
+  const byFile = /* @__PURE__ */ new Map();
+  const pkgRe = /<package\b([^>]*)>([\s\S]*?)<\/package>/gi;
+  let pkgMatch;
+  while ((pkgMatch = pkgRe.exec(raw)) !== null) {
+    const pkgName = xmlAttr(pkgMatch[1] ?? "", "name")?.trim() ?? "";
+    const pkgPath = normalizePackagePath(pkgName);
+    const body = pkgMatch[2] ?? "";
+    const sfRe = /<sourcefile\b([^>]*)>([\s\S]*?)<\/sourcefile>/gi;
+    let sfMatch;
+    while ((sfMatch = sfRe.exec(body)) !== null) {
+      const sourceName = xmlAttr(sfMatch[1] ?? "", "name")?.trim();
+      if (!sourceName) continue;
+      const path = pkgPath ? `${pkgPath}/${sourceName}` : sourceName;
+      let hits = byFile.get(path);
+      if (!hits) {
+        hits = /* @__PURE__ */ new Map();
+        byFile.set(path, hits);
+      }
+      const lineRe = /<line\b([^>]*)\/?>/gi;
+      let lineMatch;
+      while ((lineMatch = lineRe.exec(sfMatch[2] ?? "")) !== null) {
+        const lineAttrs = lineMatch[1] ?? "";
+        const nr = Number(xmlAttr(lineAttrs, "nr"));
+        const ci = Number(xmlAttr(lineAttrs, "ci") ?? "0");
+        mergeLineHits(hits, nr, Number.isFinite(ci) ? ci : 0);
+      }
+    }
+  }
+  const out = [];
+  for (const [path, hits] of byFile) {
+    const file = fileCoverageFromLineHits(repoRoot, path, hits);
+    if (file) out.push(file);
+  }
+  return out;
+}
+function normalizePackagePath(name) {
+  if (!name) return "";
+  if (name.includes("/")) return name.replace(/\\/g, "/");
+  return name.replace(/\./g, "/");
+}
+
+// src/core/formats/simplecov.ts
+function parseSimpleCov(raw, repoRoot) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    throw new Error("SimpleCov coverage file is not valid JSON");
+  }
+  const byFile = /* @__PURE__ */ new Map();
+  if (isSimpleCovJsonGem(data)) {
+    for (const file of data.files) {
+      const filename = typeof file.filename === "string" ? file.filename : "";
+      if (!filename) continue;
+      addCoverageArray(byFile, filename, file.coverage);
+    }
+  } else if (isSimpleCovResultset(data)) {
+    for (const suite of Object.values(data)) {
+      if (!suite || typeof suite !== "object") continue;
+      const coverage = suite.coverage;
+      if (!coverage || typeof coverage !== "object") continue;
+      for (const [filename, entry] of Object.entries(
+        coverage
+      )) {
+        addCoverageArray(byFile, filename, linesFromResultsetEntry(entry));
+      }
+    }
+  } else {
+    throw new Error(
+      "Not a SimpleCov resultset or simplecov-json report. Expected coverage/.resultset.json"
+    );
+  }
+  const out = [];
+  for (const [path, hits] of byFile) {
+    const file = fileCoverageFromLineHits(repoRoot, path, hits);
+    if (file) out.push(file);
+  }
+  return out;
+}
+function isSimpleCovJsonGem(data) {
+  return typeof data === "object" && data !== null && Array.isArray(data.files) && data.files.some(
+    (f) => typeof f === "object" && f !== null && typeof f.filename === "string"
+  );
+}
+function isSimpleCovResultset(data) {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return false;
+  }
+  if (isSimpleCovJsonGem(data)) return false;
+  return Object.values(data).some((suite) => {
+    if (typeof suite !== "object" || suite === null) return false;
+    const coverage = suite.coverage;
+    return typeof coverage === "object" && coverage !== null;
+  });
+}
+function linesFromResultsetEntry(entry) {
+  if (Array.isArray(entry)) return entry;
+  if (entry && typeof entry === "object" && "lines" in entry) {
+    return entry.lines;
+  }
+  return void 0;
+}
+function addCoverageArray(byFile, filename, coverage) {
+  if (!Array.isArray(coverage)) return;
+  let hits = byFile.get(filename);
+  if (!hits) {
+    hits = /* @__PURE__ */ new Map();
+    byFile.set(filename, hits);
+  }
+  coverage.forEach((cell, idx) => {
+    if (cell === null || cell === void 0) return;
+    const n = typeof cell === "number" ? cell : Number(cell);
+    if (!Number.isFinite(n)) return;
+    mergeLineHits(hits, idx + 1, n);
+  });
+}
+
+// src/core/coverage.ts
+var COVERAGE_FORMATS = [
+  "istanbul-json",
+  "v8-json",
+  "lcov",
+  "cobertura",
+  "jacoco",
+  "gcov",
+  "simplecov"
+];
+function resolveCoverageFormat(format) {
+  return format === "v8-json" ? "istanbul-json" : format;
+}
+var MISSING_COVERAGE = "coverage file missing. Run `tested run` first, or set coverage.path in .tested.yaml.";
+async function parseCoverage(opts) {
+  const explicit = opts.format ? resolveCoverageFormat(opts.format) : void 0;
+  let info;
+  try {
+    info = await stat2(opts.path);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw missingCoverageError(opts.path);
+    }
+    throw err;
+  }
+  if (info.isDirectory()) {
+    const format2 = explicit ?? detectFormatFromPath(opts.path) ?? "gcov";
+    if (format2 !== "gcov") {
+      throw new Error(
+        `coverage path ${opts.path} is a directory; only gcov accepts a directory of .gcov files`
+      );
+    }
+    return parseGcovPath({ path: opts.path, repoRoot: opts.repoRoot });
+  }
+  let raw;
+  try {
+    raw = await readFile3(opts.path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw missingCoverageError(opts.path);
+    }
+    throw err;
+  }
+  const format = explicit ?? detectFormatFromContents(raw) ?? detectFormatFromPath(opts.path) ?? defaultIstanbulIfCoverageFinal(opts.path);
+  if (!format) {
+    throw new Error(
+      `Unable to detect coverage format for ${opts.path}. Set coverage.format in .tested.yaml (${COVERAGE_FORMATS.filter((f) => f !== "v8-json").join(", ")}).`
+    );
+  }
+  return parseCoverageText({
+    raw,
+    path: opts.path,
+    repoRoot: opts.repoRoot,
+    format
+  });
+}
+function parseCoverageText(opts) {
+  switch (opts.format) {
+    case "istanbul-json":
+      return parseIstanbulString(opts.raw, opts.repoRoot, opts.path);
+    case "lcov":
+      return parseLcov(opts.raw, opts.repoRoot);
+    case "cobertura":
+      return parseCobertura(opts.raw, opts.repoRoot);
+    case "jacoco":
+      return parseJacoco(opts.raw, opts.repoRoot);
+    case "gcov":
+      return parseGcov(opts.raw, opts.repoRoot);
+    case "simplecov":
+      return parseSimpleCov(opts.raw, opts.repoRoot);
+    default: {
+      const _exhaustive = opts.format;
+      throw new Error(`Unsupported coverage format: ${String(_exhaustive)}`);
+    }
+  }
+}
+function detectFormatFromPath(filePath) {
+  const base = basename(filePath).toLowerCase();
+  if (base === "coverage-final.json") return "istanbul-json";
+  if (base === "lcov.info" || base.endsWith(".lcov")) return "lcov";
+  if (base.includes("cobertura")) return "cobertura";
+  if (base.includes("jacoco")) return "jacoco";
+  if (base.endsWith(".gcov")) return "gcov";
+  if (base === ".resultset.json" || base === "resultset.json") return "simplecov";
+  return void 0;
+}
+function detectFormatFromContents(raw) {
+  const text = raw.replace(/^\uFEFF/, "");
+  const trimmed = text.trimStart();
+  if (!trimmed) return void 0;
+  if (/^\s*-:\s*0:Source:/m.test(trimmed.slice(0, 4e3))) return "gcov";
+  const headLines = trimmed.slice(0, 2e3);
+  if (/^(TN:|SF:|DA:\d)/m.test(headLines)) return "lcov";
+  if (trimmed.startsWith("<?xml") || trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<coverage") || trimmed.startsWith("<report")) {
+    return detectXmlFormat(trimmed.slice(0, 8e3));
+  }
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      const data = JSON.parse(text);
+      if (isCoveragePyJson(data)) {
+        throw new Error(
+          "coverage.py JSON is not supported. Emit lcov or Cobertura XML (pytest-cov `--cov-report=lcov` or `--cov-report=xml`) instead."
+        );
+      }
+      if (isIstanbulJson(data)) return "istanbul-json";
+      if (isSimpleCovJsonGem(data) || isSimpleCovResultset(data)) {
+        return "simplecov";
+      }
+    } catch (err) {
+      if (err instanceof Error && /coverage\.py JSON/.test(err.message)) {
+        throw err;
+      }
+      return void 0;
+    }
+  }
+  const firstData = trimmed.split(/\r?\n/).find((l) => l.includes(":"));
+  if (firstData && /^\s*(?:#####|=======|\d+)\s*:\s*\d+:/.test(firstData)) {
+    return "gcov";
+  }
+  return void 0;
+}
+function detectXmlFormat(head) {
+  const lower = head.toLowerCase();
+  if (lower.includes("cobertura")) return "cobertura";
+  if (lower.includes("jacoco")) return "jacoco";
+  if (lower.includes("<report") && /<line\b[^>]*\bci\s*=/.test(lower)) {
+    return "jacoco";
+  }
+  if (lower.includes("<coverage") && /<line\b[^>]*\bhits\s*=/.test(lower)) {
+    return "cobertura";
+  }
+  if (lower.includes("<report")) return "jacoco";
+  if (lower.includes("<coverage")) return "cobertura";
+  return void 0;
+}
+function defaultIstanbulIfCoverageFinal(filePath) {
+  const base = basename(filePath).toLowerCase();
+  if (base === "coverage-final.json") return "istanbul-json";
+  return void 0;
+}
+function isIstanbulJson(data) {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return false;
+  }
+  const values = Object.values(data);
+  if (values.length === 0) return true;
+  return values.some(
+    (v) => typeof v === "object" && v !== null && "statementMap" in v && "s" in v
+  );
+}
+function isCoveragePyJson(data) {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return false;
+  }
+  const rec = data;
+  return typeof rec.meta === "object" && rec.meta !== null && typeof rec.files === "object" && rec.files !== null && !Array.isArray(rec.files);
+}
+function missingCoverageError(path) {
+  return new Error(`${MISSING_COVERAGE} (${path})`);
+}
+
 // src/core/junit.ts
 import { z } from "zod";
 function testCaseKey(classname, name) {
@@ -404,14 +958,14 @@ var TestReportSchema = z.object({
   ).max(50),
   slowest: z.array(TestCaseRefSchema).max(15)
 });
-function decodeXmlEntities(s) {
+function decodeXmlEntities2(s) {
   return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
 }
 function attr(tag, name) {
   const re = new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, "i");
   const m = tag.match(re);
   if (!m) return void 0;
-  return decodeXmlEntities(m[2] ?? m[3] ?? "");
+  return decodeXmlEntities2(m[2] ?? m[3] ?? "");
 }
 function parseJunitXml(xml) {
   const cases = [];
@@ -438,7 +992,7 @@ function parseJunitXml(xml) {
       message = fm ? attr(fm[1] ?? "", "message") : void 0;
       if (!message) {
         const inner = body.match(/<failure\b[^>]*>([\s\S]*?)<\/failure>/i);
-        if (inner?.[1]?.trim()) message = decodeXmlEntities(inner[1].trim()).slice(0, 500);
+        if (inner?.[1]?.trim()) message = decodeXmlEntities2(inner[1].trim()).slice(0, 500);
       }
     } else if (/<error\b/i.test(body)) {
       status = "error";
@@ -541,22 +1095,43 @@ function parseJunitToTestReport(xml) {
 }
 
 // src/schemas.ts
+var CoverageFormatSchema = z2.enum(COVERAGE_FORMATS);
+var FLAG_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+var FlagNameSchema = z2.string().regex(FLAG_NAME_PATTERN, "flag names must be alphanumeric plus _ . -");
+var FlagThresholdsSchema = z2.object({
+  patch: z2.number().min(0).max(100).optional(),
+  project: z2.number().min(0).max(100).optional()
+});
+var FlagConfigSchema = z2.object({
+  paths: z2.array(z2.string().min(1)).min(1),
+  thresholds: FlagThresholdsSchema.optional()
+});
 var TestedConfigSchema = z2.object({
   ignores: z2.array(z2.string()).default([]),
   coverage: z2.object({
-    format: z2.literal("istanbul-json").default("istanbul-json"),
-    path: z2.string().default("coverage/coverage-final.json")
+    /** Omit to auto-detect from path and file contents. */
+    format: CoverageFormatSchema.optional(),
+    /**
+     * One file or a list of files to merge (union of paths, max hits).
+     * A CI matrix that uploads many files in one job should list them here
+     * or pass `--file` / Action `files`.
+     */
+    path: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]).default("coverage/coverage-final.json")
   }).prefault({}),
   base: z2.string().default("origin/main"),
   testRunner: z2.enum(["vitest", "jest", "pytest"]).nullable().default(null),
   // Patch / project coverage gates. `tested init` writes these so users can
   // tune what counts as "passing" — schema MUST accept them so loadConfig
-  // doesn't silently drop the field. Enforcement in `diff` lands in a
-  // follow-up; today we just round-trip the values cleanly.
+  // doesn't silently drop the field.
   thresholds: z2.object({
     patch: z2.number().min(0).max(100),
     project: z2.number().min(0).max(100)
-  }).optional()
+  }).optional(),
+  /**
+   * Per-package gates. Each flag is graded from this run's coverage files
+   * only — a missing path is missing (pending/fail), never last week's totals.
+   */
+  flags: z2.record(FlagNameSchema, FlagConfigSchema).optional()
 });
 var UncoveredRangeSchema = z2.object({
   start: z2.number().int().positive(),
@@ -588,6 +1163,25 @@ var DiffOutputSchema = z2.object({
   files: z2.array(FileCoverageSchema),
   ignored: z2.array(z2.string())
 });
+var FlagMetricJsonSchema = z2.object({
+  pct: z2.number().min(0).max(100),
+  threshold: z2.number().min(0).max(100),
+  pass: z2.boolean(),
+  executable: z2.number().int().nonnegative(),
+  covered: z2.number().int().nonnegative(),
+  skipped: z2.literal(true).optional(),
+  reason: z2.string().optional()
+});
+var FlagResultJsonSchema = z2.object({
+  status: z2.enum(["pass", "fail", "missing"]),
+  present: z2.boolean(),
+  reason: z2.string().optional(),
+  patchCheck: z2.string(),
+  projectCheck: z2.string(),
+  patch: FlagMetricJsonSchema,
+  project: FlagMetricJsonSchema
+});
+var FlagsJsonMapSchema = z2.record(FlagNameSchema, FlagResultJsonSchema);
 
 // src/config.ts
 var DEFAULT_IGNORES = [
@@ -608,10 +1202,10 @@ var DEFAULT_IGNORES = [
   "stubs/**"
 ];
 async function loadConfig(opts) {
-  const file = join2(opts.cwd, ".tested.yaml");
+  const file = join3(opts.cwd, ".tested.yaml");
   let raw = {};
   try {
-    const text = await readFile(file, "utf8");
+    const text = await readFile4(file, "utf8");
     raw = parseYaml(text) ?? {};
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
@@ -621,13 +1215,129 @@ async function loadConfig(opts) {
   return { ...parsed, ignores: [...merged] };
 }
 
+// src/core/coverage-paths.ts
+import { existsSync as existsSync2 } from "fs";
+import { resolve as resolve3 } from "path";
+
+// src/core/assert-within-root.ts
+import { resolve as resolve2, sep } from "path";
+function assertWithinRoot(root, resolvedPath) {
+  const safeRoot = resolve2(root) + sep;
+  const safePath = resolve2(resolvedPath);
+  if (!safePath.startsWith(safeRoot)) {
+    throw new Error(
+      `Path traversal rejected: ${safePath} is outside repository root ${safeRoot}`
+    );
+  }
+}
+
+// src/core/merge-coverage.ts
+function statementKey(stmt) {
+  return `${stmt.startLine}:${stmt.endLine}:${stmt.id}`;
+}
+function sameRange(a, b) {
+  return a.startLine === b.startLine && a.endLine === b.endLine;
+}
+function mergeStatements(left, right) {
+  const out = /* @__PURE__ */ new Map();
+  for (const stmt of left) {
+    out.set(statementKey(stmt), { ...stmt });
+  }
+  for (const stmt of right) {
+    const exact = statementKey(stmt);
+    const existing = out.get(exact);
+    if (existing) {
+      existing.hits = Math.max(existing.hits, stmt.hits);
+      continue;
+    }
+    const rangeMatch = [...out.values()].find((prev) => sameRange(prev, stmt));
+    if (rangeMatch) {
+      rangeMatch.hits = Math.max(rangeMatch.hits, stmt.hits);
+      continue;
+    }
+    out.set(exact, { ...stmt });
+  }
+  return [...out.values()].sort(
+    (a, b) => a.startLine - b.startLine || a.endLine - b.endLine || a.id.localeCompare(b.id)
+  );
+}
+function mergeFileCoverage(shards) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const shard of shards) {
+    for (const file of shard) {
+      const existing = byPath.get(file.path);
+      if (!existing) {
+        byPath.set(file.path, {
+          path: file.path,
+          absPath: file.absPath,
+          statements: file.statements.map((s) => ({ ...s }))
+        });
+        continue;
+      }
+      byPath.set(file.path, {
+        path: existing.path,
+        absPath: existing.absPath,
+        statements: mergeStatements(existing.statements, file.statements)
+      });
+    }
+  }
+  return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// src/core/coverage-paths.ts
+function coveragePathList(path) {
+  const list = Array.isArray(path) ? [...path] : [path];
+  return list.map((p) => p.trim()).filter((p) => p.length > 0);
+}
+function parseCoverageFileList(raw) {
+  if (raw === void 0 || raw === null) return [];
+  return raw.split(/[\n,]+/).map((p) => p.trim()).filter((p) => p.length > 0);
+}
+function collectCoverageFile(value, prev) {
+  const next = value.trim();
+  return next ? [...prev, next] : prev;
+}
+function resolveCoveragePaths(opts) {
+  const fromFlag = (opts.files ?? []).map((p) => p.trim()).filter((p) => p.length > 0);
+  if (fromFlag.length > 0) return fromFlag;
+  const fromEnv = parseCoverageFileList(opts.env?.TESTED_COVERAGE_FILES);
+  if (fromEnv.length > 0) return fromEnv;
+  return coveragePathList(opts.configPath);
+}
+function existingCoveragePaths(paths, cwd, existsFn = existsSync2) {
+  return paths.filter((rel) => {
+    const abs = resolve3(cwd, rel);
+    return existsFn(abs);
+  });
+}
+async function parseAndMergeCoverage(opts) {
+  if (opts.paths.length === 0) {
+    throw new Error(
+      "coverage file missing. Run `tested run` first, or set coverage.path in .tested.yaml."
+    );
+  }
+  const shards = [];
+  for (const rel of opts.paths) {
+    const coveragePath = resolve3(opts.cwd, rel);
+    assertWithinRoot(opts.repoRoot, coveragePath);
+    shards.push(
+      await parseCoverage({
+        path: coveragePath,
+        repoRoot: opts.repoRoot,
+        ...opts.format ? { format: opts.format } : {}
+      })
+    );
+  }
+  return mergeFileCoverage(shards);
+}
+
 // src/commands/push.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync2, statSync } from "fs";
+import { join as join4 } from "path";
 import "commander";
 
 // src/core/computeDiff.ts
-import { resolve as resolve3 } from "path";
+import { resolve as resolve4 } from "path";
 
 // src/git.ts
 import { simpleGit as simpleGit2 } from "simple-git";
@@ -740,50 +1450,6 @@ async function gitUserName(ctx) {
   }
 }
 
-// src/core/istanbul.ts
-import { readFile as readFile2 } from "fs/promises";
-import { isAbsolute, relative, resolve } from "path";
-function isCoveragePathInsideRoot(repoRoot, entryPath) {
-  const root = resolve(repoRoot);
-  const absPath = resolve(entryPath);
-  const relPath = relative(root, absPath).split("\\").join("/");
-  if (!relPath || relPath === "") return true;
-  if (isAbsolute(relPath)) return false;
-  if (relPath === ".." || relPath.startsWith("../")) return false;
-  return true;
-}
-async function parseIstanbul(opts) {
-  let raw;
-  try {
-    raw = await readFile2(opts.path, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") {
-      throw new Error(
-        `coverage-final.json not found at ${opts.path}. Run \`tested run\` first.`
-      );
-    }
-    throw err;
-  }
-  const data = JSON.parse(raw);
-  const root = resolve(opts.repoRoot);
-  const out = [];
-  for (const entry of Object.values(data)) {
-    if (!isCoveragePathInsideRoot(root, entry.path)) {
-      continue;
-    }
-    const absPath = resolve(entry.path);
-    const relPath = relative(root, absPath).split("\\").join("/");
-    const statements = Object.entries(entry.statementMap).map(([id, loc]) => ({
-      id,
-      startLine: loc.start.line,
-      endLine: loc.end.line,
-      hits: entry.s[id] ?? 0
-    }));
-    out.push({ path: relPath, absPath, statements });
-  }
-  return out;
-}
-
 // src/core/diff.ts
 var FILE_HEADER = /^diff --git a\/(.+?) b\/(.+?)$/;
 var HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
@@ -837,18 +1503,6 @@ function splitByIgnore(paths, patterns) {
   return { kept, ignored };
 }
 
-// src/core/assert-within-root.ts
-import { resolve as resolve2, sep } from "path";
-function assertWithinRoot(root, resolvedPath) {
-  const safeRoot = resolve2(root) + sep;
-  const safePath = resolve2(resolvedPath);
-  if (!safePath.startsWith(safeRoot)) {
-    throw new Error(
-      `Path traversal rejected: ${safePath} is outside repository root ${safeRoot}`
-    );
-  }
-}
-
 // src/core/patch.ts
 var EMPTY_PATCH_REASON = "no executable lines in the patch";
 function isEmptyPatch(totals) {
@@ -981,7 +1635,7 @@ function buildDiffOutput(args) {
 }
 
 // src/core/computeDiff.ts
-async function computeDiff(opts) {
+async function computeDiffContext(opts) {
   const { cwd, config } = opts;
   const ctx = opts.ctx ?? await openRepo(cwd);
   const requested = assertSafeGitRef(opts.baseRef ?? config.base);
@@ -989,9 +1643,16 @@ async function computeDiff(opts) {
   const head = await headSha(ctx);
   const diffText = await unifiedDiff(ctx, base);
   const addedByFile = parseUnifiedDiff(diffText);
-  const coveragePath = resolve3(cwd, config.coverage.path);
-  assertWithinRoot(ctx.repoRoot, coveragePath);
-  const allFiles = await parseIstanbul({ path: coveragePath, repoRoot: ctx.repoRoot });
+  const coveragePaths = resolveCoveragePaths({
+    ...opts.coveragePaths ? { files: opts.coveragePaths } : {},
+    configPath: config.coverage.path
+  });
+  const allFiles = await parseAndMergeCoverage({
+    paths: coveragePaths,
+    cwd,
+    repoRoot: ctx.repoRoot,
+    ...config.coverage.format ? { format: config.coverage.format } : {}
+  });
   const { kept, ignored } = splitByIgnore(
     allFiles.map((f) => f.path),
     config.ignores
@@ -1000,11 +1661,12 @@ async function computeDiff(opts) {
   const files = allFiles.filter((f) => keptSet.has(f.path));
   let projectDelta = null;
   if (opts.withBaseCoverage) {
-    const baseCoveragePath = resolve3(cwd, opts.withBaseCoverage);
+    const baseCoveragePath = resolve4(cwd, opts.withBaseCoverage);
     assertWithinRoot(ctx.repoRoot, baseCoveragePath);
-    const baseFiles = await parseIstanbul({
+    const baseFiles = await parseCoverage({
       path: baseCoveragePath,
-      repoRoot: ctx.repoRoot
+      repoRoot: ctx.repoRoot,
+      ...config.coverage.format ? { format: config.coverage.format } : {}
     });
     const baseKept = baseFiles.filter((f) => !ignored.includes(f.path));
     const baseExec = baseKept.reduce((n, f) => n + f.statements.length, 0);
@@ -1023,7 +1685,7 @@ async function computeDiff(opts) {
     })();
     projectDelta = Math.round((headPct - basePct) * 10) / 10;
   }
-  return buildDiffOutput({
+  const diff = buildDiffOutput({
     base: baseRef,
     head,
     files,
@@ -1031,6 +1693,201 @@ async function computeDiff(opts) {
     ignored,
     projectDelta
   });
+  return { diff, files, addedByFile };
+}
+
+// src/core/flags.ts
+import { minimatch as minimatch2 } from "minimatch";
+var MISSING_FLAG_REASON = "no coverage files matched this flag in this run";
+var SCOPED_MISSING_FLAG_REASON = "no coverage files in this run for this flag";
+var MATCH_OPTS = { dot: true, matchBase: true };
+function pathMatchesFlag(filePath, patterns) {
+  const normalized = filePath.replace(/\\/g, "/");
+  return patterns.some(
+    (p) => minimatch2(normalized, p, MATCH_OPTS) || minimatch2(normalized, `**/${p}`, MATCH_OPTS)
+  );
+}
+function filterFilesByFlag(files, patterns) {
+  return files.filter((f) => pathMatchesFlag(f.path, patterns));
+}
+function resolveFlagThresholds(flag, global) {
+  return {
+    patch: flag.thresholds?.patch ?? global.patch,
+    project: flag.thresholds?.project ?? global.project
+  };
+}
+function unknownFlagError(name, configured) {
+  const list = configured.length > 0 ? configured.join(", ") : "(none)";
+  return new Error(`unknown flag "${name}" \u2014 configured flags: ${list}`);
+}
+function totalsToMetric(totals, threshold, kind) {
+  const empty = isEmptyPatch(totals);
+  if (kind === "patch" && empty) {
+    return {
+      pct: totals.pct,
+      threshold,
+      pass: true,
+      executable: totals.executable,
+      covered: totals.covered,
+      skipped: true,
+      reason: EMPTY_PATCH_REASON
+    };
+  }
+  const pass = totals.pct >= threshold;
+  return {
+    pct: totals.pct,
+    threshold,
+    pass,
+    executable: totals.executable,
+    covered: totals.covered
+  };
+}
+function missingMetric(threshold) {
+  return {
+    pct: 0,
+    threshold,
+    pass: false,
+    executable: 0,
+    covered: 0
+  };
+}
+function checkSlug(kind, name) {
+  return `tested.dev / ${kind} / ${name}`;
+}
+function evaluatePresentFlag(name, files, addedByFile, thresholds) {
+  const patch = computePatchCoverage(files, addedByFile);
+  const project = computeProjectCoverage(files);
+  const patchMetric = totalsToMetric(patch.totals, thresholds.patch, "patch");
+  const projectMetric = totalsToMetric(project.totals, thresholds.project, "project");
+  const status = patchMetric.pass && projectMetric.pass ? "pass" : "fail";
+  return {
+    name,
+    present: true,
+    status,
+    patchCheck: checkSlug("patch", name),
+    projectCheck: checkSlug("project", name),
+    patch: patchMetric,
+    project: projectMetric
+  };
+}
+function missingFlag(name, thresholds, reason) {
+  return {
+    name,
+    present: false,
+    status: "missing",
+    reason,
+    patchCheck: checkSlug("patch", name),
+    projectCheck: checkSlug("project", name),
+    patch: missingMetric(thresholds.patch),
+    project: missingMetric(thresholds.project)
+  };
+}
+function evaluateFlags(input) {
+  const flags = input.config.flags;
+  const global = input.config.thresholds;
+  if (!flags || !global) return [];
+  const names = Object.keys(flags);
+  if (input.onlyFlag !== void 0 && input.onlyFlag !== "") {
+    const def = flags[input.onlyFlag];
+    if (!def) throw unknownFlagError(input.onlyFlag, names);
+    const thresholds = resolveFlagThresholds(def, global);
+    if (input.files.length === 0) {
+      return [missingFlag(input.onlyFlag, thresholds, SCOPED_MISSING_FLAG_REASON)];
+    }
+    return [evaluatePresentFlag(input.onlyFlag, input.files, input.addedByFile, thresholds)];
+  }
+  const results = [];
+  for (const name of names) {
+    const def = flags[name];
+    const thresholds = resolveFlagThresholds(def, global);
+    const matched = filterFilesByFlag(input.files, def.paths);
+    if (matched.length === 0) {
+      results.push(missingFlag(name, thresholds, MISSING_FLAG_REASON));
+      continue;
+    }
+    results.push(evaluatePresentFlag(name, matched, input.addedByFile, thresholds));
+  }
+  return results;
+}
+function flagsPass(results) {
+  return results.every((f) => f.status === "pass");
+}
+function flagsToJson(results) {
+  const out = {};
+  for (const flag of results) {
+    out[flag.name] = {
+      status: flag.status,
+      present: flag.present,
+      ...flag.reason ? { reason: flag.reason } : {},
+      patchCheck: flag.patchCheck,
+      projectCheck: flag.projectCheck,
+      patch: flag.patch,
+      project: flag.project
+    };
+  }
+  return out;
+}
+function resolveFlagsJson(input) {
+  const results = evaluateFlags(input);
+  return results.length > 0 ? flagsToJson(results) : void 0;
+}
+
+// src/core/coverage-merge.ts
+function emptyToUndef(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+}
+function parsePositiveInt(raw, label) {
+  const trimmed = emptyToUndef(raw);
+  if (trimmed === void 0) return void 0;
+  const n = Number(trimmed);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`invalid ${label} "${raw}" \u2014 expected a positive integer`);
+  }
+  return n;
+}
+function resolveCoverageMerge(cli, env = process.env) {
+  if (cli.complete && cli.incomplete) {
+    throw new Error("cannot pass both --complete and --incomplete");
+  }
+  const totalParts = parsePositiveInt(cli.parts ?? env.TESTED_PARTS, "--parts");
+  const part = parsePositiveInt(cli.part ?? env.TESTED_PART, "--part");
+  const runId = emptyToUndef(cli.runId ?? env.TESTED_RUN_ID);
+  const shard = emptyToUndef(cli.shard ?? env.TESTED_SHARD);
+  if (part !== void 0 && totalParts !== void 0 && part > totalParts) {
+    throw new Error(`--part ${part} is greater than --parts ${totalParts}`);
+  }
+  let complete;
+  if (cli.complete) {
+    complete = true;
+  } else if (cli.incomplete) {
+    complete = false;
+  } else if (totalParts !== void 0) {
+    complete = part !== void 0 && part === totalParts;
+  } else {
+    complete = true;
+  }
+  const state = { complete };
+  if (totalParts !== void 0) state.totalParts = totalParts;
+  if (part !== void 0) state.part = part;
+  if (runId !== void 0) state.runId = runId;
+  if (shard !== void 0) state.shard = shard;
+  return state;
+}
+function toCoverageMergePayload(state) {
+  const payload = { complete: state.complete };
+  if (state.totalParts !== void 0) payload.totalParts = state.totalParts;
+  if (state.part !== void 0) payload.part = state.part;
+  if (state.runId !== void 0) payload.runId = state.runId;
+  if (state.shard !== void 0) payload.shard = state.shard;
+  return payload;
+}
+function hasShardMetadata(state) {
+  return !state.complete || state.totalParts !== void 0 || state.part !== void 0 || state.runId !== void 0 || state.shard !== void 0;
+}
+function formatIncompleteGateMessage(state) {
+  const part = state.part !== void 0 && state.totalParts !== void 0 ? `part ${state.part} of ${state.totalParts}` : state.totalParts !== void 0 ? `waiting for ${state.totalParts} parts` : "incomplete shard";
+  return `coverage shard is incomplete (${part}). The patch/project gate runs only on --complete or the last part.`;
 }
 
 // src/commands/push.ts
@@ -1056,10 +1913,10 @@ function parseGitHubRepository(repo) {
 var tokenArgvWarned = false;
 function readTokenFile(filePath, opts) {
   const read = opts?.readFileSyncFn ?? readFileSync2;
-  const stat = opts?.statSyncFn ?? statSync;
+  const stat3 = opts?.statSyncFn ?? statSync;
   let mode;
   try {
-    const st = stat(filePath);
+    const st = stat3(filePath);
     mode = st.mode;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -1331,8 +2188,10 @@ function buildIngestBody(input) {
       state: "open"
     },
     runUrl: input.runUrl,
-    diff: input.diff,
-    ...input.testReport ? { testReport: input.testReport } : {}
+    ...input.diff ? { diff: input.diff } : {},
+    ...input.testReport ? { testReport: input.testReport } : {},
+    ...input.coverageMerge ? { coverageMerge: input.coverageMerge } : {},
+    ...input.flags ? { flags: input.flags } : {}
   };
 }
 function buildMainlineIngestBody(input) {
@@ -1343,11 +2202,13 @@ function buildMainlineIngestBody(input) {
       defaultBranch: input.defaultBranch
     },
     runUrl: input.runUrl,
-    diff: input.diff,
+    ...input.diff ? { diff: input.diff } : {},
     ref: input.ref,
     isDefaultBranch: true,
     headSha: input.headSha,
-    ...input.testReport ? { testReport: input.testReport } : {}
+    ...input.testReport ? { testReport: input.testReport } : {},
+    ...input.coverageMerge ? { coverageMerge: input.coverageMerge } : {},
+    ...input.flags ? { flags: input.flags } : {}
   };
 }
 var DEFAULT_JUNIT_CANDIDATES = [
@@ -1358,10 +2219,10 @@ var DEFAULT_JUNIT_CANDIDATES = [
 ];
 function resolveJunitPath(opts) {
   const env = opts.env ?? process.env;
-  const exists = opts.existsSyncFn ?? existsSync2;
+  const exists = opts.existsSyncFn ?? existsSync3;
   if (opts.flag && opts.flag.trim()) {
     const p = opts.flag.trim();
-    const abs = p.startsWith("/") ? p : join3(opts.cwd, p);
+    const abs = p.startsWith("/") ? p : join4(opts.cwd, p);
     if (!exists(abs)) {
       throw new Error(`JUnit file not found: ${p}`);
     }
@@ -1369,14 +2230,14 @@ function resolveJunitPath(opts) {
   }
   const fromEnv = env.TESTED_JUNIT?.trim();
   if (fromEnv) {
-    const abs = fromEnv.startsWith("/") ? fromEnv : join3(opts.cwd, fromEnv);
+    const abs = fromEnv.startsWith("/") ? fromEnv : join4(opts.cwd, fromEnv);
     if (!exists(abs)) {
       throw new Error(`TESTED_JUNIT file not found: ${fromEnv}`);
     }
     return abs;
   }
   for (const rel of DEFAULT_JUNIT_CANDIDATES) {
-    const abs = join3(opts.cwd, rel);
+    const abs = join4(opts.cwd, rel);
     if (exists(abs)) return abs;
   }
   return null;
@@ -1422,15 +2283,12 @@ async function postIngest(opts) {
       parsed = null;
     }
   }
-  if (res.status === 200) {
-    const data = parsed;
-    if (!data) {
-      return {
-        ok: false,
-        status: res.status,
-        message: "ingest succeeded but response was empty"
-      };
-    }
+  const concludesGate = opts.body.coverageMerge?.complete !== false;
+  const handshakeOnly = concludesGate && !opts.body.diff;
+  const acceptIncomplete = opts.body.coverageMerge?.complete === false;
+  const successStatus = res.status === 200 || acceptIncomplete && res.status === 202;
+  if (successStatus) {
+    const data = parsed ?? {};
     if (data.mainline === true) {
       return {
         ok: true,
@@ -1438,11 +2296,20 @@ async function postIngest(opts) {
         data: {
           mainline: true,
           ...typeof data.date === "string" ? { date: data.date } : {},
-          ...typeof data.projectPct === "number" ? { projectPct: data.projectPct } : {}
+          ...typeof data.projectPct === "number" ? { projectPct: data.projectPct } : {},
+          ...acceptIncomplete ? { complete: false } : {}
         }
       };
     }
-    if (typeof data.shareUrl !== "string" || !data.shareUrl) {
+    const shareUrl2 = typeof data.shareUrl === "string" && data.shareUrl ? data.shareUrl : void 0;
+    if (concludesGate && !handshakeOnly && !acceptIncomplete && !shareUrl2) {
+      if (parsed === null) {
+        return {
+          ok: false,
+          status: res.status,
+          message: "ingest succeeded but response was empty"
+        };
+      }
       return {
         ok: false,
         status: res.status,
@@ -1453,8 +2320,9 @@ async function postIngest(opts) {
       ok: true,
       status: res.status,
       data: {
-        shareUrl: data.shareUrl,
-        ...typeof data.expiresAt === "string" ? { expiresAt: data.expiresAt } : {}
+        ...shareUrl2 ? { shareUrl: shareUrl2 } : {},
+        ...typeof data.expiresAt === "string" ? { expiresAt: data.expiresAt } : {},
+        ...acceptIncomplete || handshakeOnly ? { complete: concludesGate } : {}
       }
     };
   }
@@ -1471,7 +2339,8 @@ async function postIngest(opts) {
   }
   return { ok: false, status: res.status, message, ...code ? { code } : {} };
 }
-function formatPushSuccess(data, json) {
+function formatPushSuccess(data, json, merge) {
+  const incomplete = merge ? !merge.complete : data.complete === false;
   if (json) {
     const payload = {};
     if (data.shareUrl) payload.shareUrl = data.shareUrl;
@@ -1479,9 +2348,23 @@ function formatPushSuccess(data, json) {
     if (data.mainline) payload.mainline = true;
     if (data.date) payload.date = data.date;
     if (typeof data.projectPct === "number") payload.projectPct = data.projectPct;
+    if (merge && hasShardMetadata(merge)) {
+      payload.complete = merge.complete;
+      if (merge.part !== void 0) payload.part = merge.part;
+      if (merge.totalParts !== void 0) payload.totalParts = merge.totalParts;
+    } else if (incomplete) {
+      payload.complete = false;
+    }
     return { stdout: JSON.stringify(payload) + "\n", stderr: "" };
   }
   const lines = [];
+  if (incomplete && merge) {
+    lines.push(successLine(`uploaded shard (${formatIncompleteGateMessage(merge)})`));
+    if (data.shareUrl) {
+      lines.push(dim(`  ${shareUrl(data.shareUrl)}  (pending \u2014 not a gate result)`));
+    }
+    return { stdout: lines.join("\n") + "\n", stderr: "" };
+  }
   if (data.mainline) {
     lines.push(
       successLine(
@@ -1537,7 +2420,8 @@ function formatPushError(status, message, code, identity) {
 }
 async function executePush(cli, deps) {
   const env = deps.env ?? process.env;
-  const computeDiffFn = deps.computeDiffFn ?? computeDiff;
+  const computeDiffFn = deps.computeDiffFn;
+  const computeDiffContextFn = deps.computeDiffContextFn ?? computeDiffContext;
   const fetchFn = deps.fetchFn ?? globalThis.fetch;
   const openRepoFn = deps.openRepoFn ?? openRepo;
   const loadConfigFn = deps.loadConfigFn ?? loadConfig;
@@ -1601,6 +2485,14 @@ async function executePush(cli, deps) {
     const message = err instanceof Error ? err.message : String(err);
     return { exitCode: 1, stdout: "", stderr: errorBlock(message) };
   }
+  let merge;
+  try {
+    merge = resolveCoverageMerge(cli, env);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { exitCode: 1, stdout: "", stderr: errorBlock(message) };
+  }
+  const coverageMerge = toCoverageMergePayload(merge);
   const config = await loadConfigFn({ cwd: deps.cwd });
   const ctx = await openRepoFn(deps.cwd);
   const peeked = await peekRepoIdentity({
@@ -1609,32 +2501,68 @@ async function executePush(cli, deps) {
     env,
     ctx
   });
+  const coveragePaths = resolveCoveragePaths({
+    ...cli.file && cli.file.length > 0 ? { files: cli.file } : {},
+    env,
+    configPath: config.coverage.path
+  });
+  const existingCoverage = existingCoveragePaths(coveragePaths, deps.cwd);
+  const handshakeOnly = merge.complete && existingCoverage.length === 0 && (cli.complete === true || merge.totalParts !== void 0);
   let diff;
-  try {
-    let baseOverride = cli.base;
-    if (baseOverride === void 0 && prNumber !== null) {
-      const resolved = await resolvePrPushBase({
+  let files = [];
+  let addedByFile = /* @__PURE__ */ new Map();
+  if (!handshakeOnly) {
+    try {
+      let baseOverride = cli.base;
+      if (baseOverride === void 0 && prNumber !== null) {
+        const resolved = await resolvePrPushBase({
+          ctx,
+          requested: config.base,
+          prNumber,
+          ...peeked.owner != null ? { owner: peeked.owner } : {},
+          ...peeked.name != null ? { name: peeked.name } : {},
+          fetchFn,
+          env,
+          onProgress
+        });
+        if (resolved !== void 0) baseOverride = resolved;
+      }
+      onProgress("computing diff\u2026");
+      const diffOpts = {
+        cwd: deps.cwd,
+        config,
+        ...baseOverride !== void 0 ? { baseRef: baseOverride } : {},
         ctx,
-        requested: config.base,
-        prNumber,
-        ...peeked.owner != null ? { owner: peeked.owner } : {},
-        ...peeked.name != null ? { name: peeked.name } : {},
-        fetchFn,
-        env,
-        onProgress
+        ...coveragePaths.length > 0 ? { coveragePaths } : {}
+      };
+      if (computeDiffFn) {
+        diff = await computeDiffFn(diffOpts);
+      } else {
+        const computed = await computeDiffContextFn(diffOpts);
+        diff = computed.diff;
+        files = computed.files;
+        addedByFile = computed.addedByFile;
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { exitCode: 1, stdout: "", stderr: errorBlock(message) };
+    }
+  } else {
+    onProgress("complete handshake (no local coverage)\u2026");
+  }
+  let flags;
+  if (!handshakeOnly && !computeDiffFn) {
+    try {
+      flags = resolveFlagsJson({
+        config,
+        files,
+        addedByFile,
+        ...cli.flag && cli.flag.trim() ? { onlyFlag: cli.flag.trim() } : {}
       });
-      if (resolved !== void 0) baseOverride = resolved;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { exitCode: 1, stdout: "", stderr: errorBlock(message) };
     }
-    onProgress("computing diff\u2026");
-    diff = await computeDiffFn({
-      cwd: deps.cwd,
-      config,
-      ...baseOverride !== void 0 ? { baseRef: baseOverride } : {},
-      ctx
-    });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { exitCode: 1, stdout: "", stderr: errorBlock(message) };
   }
   let owner = cli.owner ?? peeked.owner ?? void 0;
   let name = cli.name ?? peeked.name ?? void 0;
@@ -1690,13 +2618,19 @@ async function executePush(cli, deps) {
       env
     });
     if (junitPath) {
-      onProgress("parsing JUnit\u2026");
+      onProgress(`parsing JUnit (${junitPath})\u2026`);
       testReport = loadTestReportFromJunit(junitPath);
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return { exitCode: 1, stdout: "", stderr: errorBlock(message) };
   }
+  const mergeFields = {
+    coverageMerge,
+    ...diff ? { diff } : {},
+    ...testReport ? { testReport } : {},
+    ...flags ? { flags } : {}
+  };
   const body = mainline ? buildMainlineIngestBody({
     owner,
     name,
@@ -1704,8 +2638,7 @@ async function executePush(cli, deps) {
     headSha: sha,
     ref: `refs/heads/${baseRef}`,
     runUrl: cli.runUrl ?? null,
-    diff,
-    ...testReport ? { testReport } : {}
+    ...mergeFields
   }) : buildIngestBody({
     owner,
     name,
@@ -1716,10 +2649,11 @@ async function executePush(cli, deps) {
     headRef,
     headSha: sha,
     runUrl: cli.runUrl ?? null,
-    diff,
-    ...testReport ? { testReport } : {}
+    ...mergeFields
   });
-  onProgress(mainline ? "uploading mainline coverage\u2026" : "uploading\u2026");
+  onProgress(
+    !merge.complete ? "uploading shard (incomplete)\u2026" : mainline ? "uploading mainline coverage\u2026" : handshakeOnly ? "sending complete handshake\u2026" : "uploading\u2026"
+  );
   const result = await postIngest({ apiBase, token, body, fetchFn });
   if (!result.ok) {
     return {
@@ -1731,11 +2665,12 @@ async function executePush(cli, deps) {
       })
     };
   }
-  const formatted = formatPushSuccess(result.data, cli.json);
+  const formatted = formatPushSuccess(result.data, cli.json, merge);
   return {
     exitCode: 0,
     stdout: formatted.stdout,
     stderr: formatted.stderr,
+    complete: merge.complete,
     ...result.data.shareUrl !== void 0 ? { shareUrl: result.data.shareUrl } : {},
     ...result.data.expiresAt !== void 0 ? { expiresAt: result.data.expiresAt } : {}
   };
@@ -1759,7 +2694,15 @@ function registerPushCommand(program2) {
     "Base branch name sent to the API (default: .tested.yaml base or main)"
   ).option("--head-ref <ref>", "Head branch name (default: current branch)").option("--run-url <url>", "Optional CI run URL attached to the ingest").option("--base <ref>", "Git base ref to diff against (same as `tested diff --base`)").option(
     "--junit <path>",
-    "JUnit XML for test analytics (flakes / slowest). Also TESTED_JUNIT or junit.xml"
+    "JUnit XML for test analytics (flakes / slowest). Also TESTED_JUNIT or auto-detect junit.xml / test-results/junit.xml / coverage/junit.xml"
+  ).option(
+    "--file <path>",
+    "Coverage file to merge (repeatable). Overrides coverage.path.",
+    collectCoverageFile,
+    []
+  ).option("--complete", "Conclude the gate (last shard / finish job)", false).option("--incomplete", "Upload a shard without concluding GitHub checks", false).option("--parts <n>", "Total shard count (Codecov after_n_builds / Qlty total-parts-count)").option("--part <n>", "1-based shard index").option("--run-id <id>", "CI run id grouping shards for one SHA (or TESTED_RUN_ID)").option("--shard <id>", "Optional shard label (or TESTED_SHARD)").option(
+    "--flag <name>",
+    "This coverage file is the named flag (job already scoped \u2014 omit other packages)"
   ).option("--json", "Emit machine-readable JSON instead of the share URL only", false).action(async (opts) => {
     try {
       const result = await executePush(opts, { cwd: process.cwd() });
@@ -1833,7 +2776,7 @@ function isReadableFile(path, exists) {
 async function runDoctor(deps) {
   const cwd = deps.cwd;
   const env = deps.env ?? process.env;
-  const exists = deps.existsSyncFn ?? existsSync3;
+  const exists = deps.existsSyncFn ?? existsSync4;
   const gitFactory = deps.gitFactory ?? simpleGit3;
   const loadConfigFn = deps.loadConfigFn ?? loadConfig;
   const resolveTokenFn = deps.resolveTokenFn ?? resolveToken;
@@ -1880,7 +2823,7 @@ async function runDoctor(deps) {
       detail: "not a git repository \u2014 run from a repo root"
     });
   }
-  const configPath = join4(cwd, ".tested.yaml");
+  const configPath = join5(cwd, ".tested.yaml");
   const hasConfig = exists(configPath);
   if (hasConfig) {
     checks.push({
@@ -1897,19 +2840,21 @@ async function runDoctor(deps) {
       detail: "missing \u2014 run: tested setup  (or tested init)"
     });
   }
-  let coverageRel = "coverage/coverage-final.json";
+  let coverageRels = ["coverage/coverage-final.json"];
   if (hasConfig) {
     try {
       const config = await loadConfigFn({ cwd });
-      coverageRel = config.coverage.path;
+      const listed = coveragePathList(config.coverage.path);
+      if (listed.length > 0) coverageRels = listed;
     } catch {
     }
   }
-  const coverageAbs = resolve4(cwd, coverageRel);
-  if (isReadableFile(coverageAbs, exists)) {
+  const coverageRel = coverageRels.join(", ");
+  const missing = coverageRels.filter((rel) => !isReadableFile(resolve5(cwd, rel), exists));
+  if (missing.length === 0) {
     checks.push({
       id: "coverage",
-      label: "Coverage file",
+      label: coverageRels.length > 1 ? "Coverage files" : "Coverage file",
       status: "pass",
       detail: coverageRel,
       optional: true
@@ -1917,9 +2862,9 @@ async function runDoctor(deps) {
   } else {
     checks.push({
       id: "coverage",
-      label: "Coverage file",
+      label: coverageRels.length > 1 ? "Coverage files" : "Coverage file",
       status: "warn",
-      detail: `missing ${coverageRel} \u2014 run: tested run`,
+      detail: `missing ${missing.join(", ")} \u2014 run: tested run`,
       optional: true
     });
   }
@@ -2042,7 +2987,7 @@ async function runDoctor(deps) {
   }
   const testedBin = env.TESTED_BIN;
   if (testedBin !== void 0 && testedBin !== "") {
-    const base = basename(testedBin);
+    const base = basename2(testedBin);
     const okName = TESTED_BIN_BASENAME_RE.test(base);
     if (!okName) {
       checks.push({
@@ -2127,7 +3072,7 @@ import pc3 from "picocolors";
 // package.json
 var package_default = {
   name: "@tested/cli",
-  version: "0.1.7",
+  version: "0.1.8",
   description: "Coverage your agent can use. CLI for patch + project coverage with agent-readable JSON output.",
   license: "MIT",
   homepage: "https://tested.dev",
@@ -2278,13 +3223,13 @@ function formatSetupHuman(opts) {
 async function runSetup(deps) {
   const cwd = deps.cwd;
   const env = deps.env ?? process.env;
-  const exists = deps.existsSyncFn ?? existsSync4;
+  const exists = deps.existsSyncFn ?? existsSync5;
   const runInitFn = deps.runInitFn ?? runInit;
   const runDoctorFn = deps.runDoctorFn ?? runDoctor;
   const force = deps.force ?? false;
   const hooks = deps.hooks ?? false;
   const json = deps.json ?? false;
-  const configPath = join5(cwd, ".tested.yaml");
+  const configPath = join6(cwd, ".tested.yaml");
   let initRan = false;
   let initResult = null;
   if (!exists(configPath) || force) {
@@ -2368,8 +3313,8 @@ function registerSetupCommand(program2) {
 }
 
 // src/commands/run.ts
-import { existsSync as existsSync5 } from "fs";
-import { isAbsolute as isAbsolute3, resolve as resolve5, sep as sep2 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { isAbsolute as isAbsolute3, resolve as resolve6, sep as sep2 } from "path";
 import { spawn } from "child_process";
 import "commander";
 function splitRunArgs(extraArgs) {
@@ -2439,8 +3384,8 @@ function shouldEnforceSafeRun(opts) {
   return false;
 }
 function configPathEscapesRoot(configPath, repoRoot) {
-  const root = resolve5(repoRoot);
-  const abs = isAbsolute3(configPath) ? resolve5(configPath) : resolve5(repoRoot, configPath);
+  const root = resolve6(repoRoot);
+  const abs = isAbsolute3(configPath) ? resolve6(configPath) : resolve6(repoRoot, configPath);
   const safeRoot = root.endsWith(sep2) ? root : root + sep2;
   return !(abs === root || abs.startsWith(safeRoot));
 }
@@ -2491,7 +3436,8 @@ function registerRunCommand(program2) {
       return;
     }
     const config = await loadConfig({ cwd });
-    const coveragePath = resolve5(cwd, config.coverage.path);
+    const coverageRel = coveragePathList(config.coverage.path)[0] ?? "coverage/coverage-final.json";
+    const coveragePath = resolve6(cwd, coverageRel);
     const { command, args } = resolveRunCommand({
       runner: config.testRunner,
       extraArgs: forwarded
@@ -2503,14 +3449,14 @@ function registerRunCommand(program2) {
     const child = spawn(command, args, { stdio: "inherit" });
     child.on("exit", (code) => {
       const exit = code ?? 1;
-      const coverageWritten = existsSync5(coveragePath);
+      const coverageWritten = existsSync6(coveragePath);
       if (json) {
         const payload = buildRunJsonOutput({
           command,
           args,
           exitCode: exit,
           coverageWritten,
-          coveragePath: config.coverage.path
+          coveragePath: coverageRel
         });
         process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
         process.exit(exit);
@@ -2524,7 +3470,7 @@ function registerRunCommand(program2) {
         process.stderr.write("\n");
         process.stderr.write(
           dim(
-            coverageWritten ? `tests failed (exit ${exit}); coverage still written to ${config.coverage.path}` : `tests failed (exit ${exit}); no coverage file at ${config.coverage.path}`
+            coverageWritten ? `tests failed (exit ${exit}); coverage still written to ${coverageRel}` : `tests failed (exit ${exit}); no coverage file at ${coverageRel}`
           ) + "\n"
         );
       }
@@ -2665,21 +3611,29 @@ function formatHuman(out, opts = {}) {
 
 // src/commands/diff.ts
 function registerDiffCommand(program2) {
-  program2.command("diff").description("Compute patch + project coverage against a base ref").option("--base <ref>", "Git base ref to diff against", void 0).option("--with-base-coverage <path>", "Compare project coverage against a baseline JSON", void 0).option("--json", "Emit schema-v1 JSON instead of human text", false).action(async (opts) => {
+  program2.command("diff").description("Compute patch + project coverage against a base ref").option("--base <ref>", "Git base ref to diff against", void 0).option("--with-base-coverage <path>", "Compare project coverage against a baseline JSON", void 0).option(
+    "--file <path>",
+    "Coverage file to merge (repeatable). Overrides coverage.path.",
+    collectCoverageFile,
+    []
+  ).option("--json", "Emit schema-v1 JSON instead of human text", false).action(async (opts) => {
     try {
       const cwd = process.cwd();
       const config = await loadConfig({ cwd });
-      const output = await computeDiff({
+      const { diff, files, addedByFile } = await computeDiffContext({
         cwd,
         config,
         ...opts.base !== void 0 ? { baseRef: opts.base } : {},
-        ...opts.withBaseCoverage !== void 0 ? { withBaseCoverage: opts.withBaseCoverage } : {}
+        ...opts.withBaseCoverage !== void 0 ? { withBaseCoverage: opts.withBaseCoverage } : {},
+        ...opts.file && opts.file.length > 0 ? { coveragePaths: opts.file } : {}
       });
       if (opts.json) {
-        process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+        const flags = resolveFlagsJson({ config, files, addedByFile });
+        const payload = flags ? { ...diff, flags } : diff;
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
       } else {
         process.stdout.write(
-          formatHuman(output, {
+          formatHuman(diff, {
             ...config.thresholds ? { thresholds: config.thresholds } : {},
             tips: true
           }) + "\n"
@@ -2694,11 +3648,107 @@ function registerDiffCommand(program2) {
 }
 
 // src/commands/check.ts
+import { existsSync as existsSync7 } from "fs";
 import "commander";
-function formatMetricLine(label, pct3, threshold, pass) {
+function formatIncompleteCheck(state, json) {
+  const message = formatIncompleteGateMessage(state);
+  if (json) {
+    return {
+      skipped: true,
+      patchPass: true,
+      projectPass: true,
+      overall: "pass",
+      flagResults: [],
+      stdout: JSON.stringify({
+        overall: "pending",
+        complete: false,
+        ...state.part !== void 0 ? { part: state.part } : {},
+        ...state.totalParts !== void 0 ? { totalParts: state.totalParts } : {},
+        note: message
+      }) + "\n",
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  return {
+    skipped: true,
+    patchPass: true,
+    projectPass: true,
+    overall: "pass",
+    flagResults: [],
+    stdout: "",
+    stderr: `${dim("tested.dev \u2014 coverage gate")}  ${badge("info")}
+
+${dim(`  ${message}`)}
+${tip("tested push --complete  (or --parts N --part N)")}
+`,
+    exitCode: 0
+  };
+}
+function formatCompleteHandshakeCheck(json) {
+  const note = "no local coverage files \u2014 complete handshake only. The app merges stored shards; this job does not evaluate the gate.";
+  if (json) {
+    return {
+      skipped: true,
+      patchPass: true,
+      projectPass: true,
+      overall: "pass",
+      flagResults: [],
+      stdout: JSON.stringify({ overall: "pending", complete: true, note }) + "\n",
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  return {
+    skipped: true,
+    patchPass: true,
+    projectPass: true,
+    overall: "pass",
+    flagResults: [],
+    stdout: "",
+    stderr: `${dim("tested.dev \u2014 coverage gate")}  ${badge("info")}
+
+${dim(`  ${note}`)}
+`,
+    exitCode: 0
+  };
+}
+function formatMetricLine(label, pct3, threshold, pass, indent = "  ") {
   const pctStr = pct3.toFixed(1);
   const status = pass ? badge("pass") : badge("fail");
-  return `  ${label.padEnd(8)}  ${pctStr}%  (threshold ${threshold})  ${status}`;
+  return `${indent}${label.padEnd(8)}  ${pctStr}%  (threshold ${threshold})  ${status}`;
+}
+function formatFlagLines(results) {
+  if (results.length === 0) return [];
+  const lines = [""];
+  for (const flag of results) {
+    if (flag.status === "missing") {
+      lines.push(
+        `  ${flag.name}  ${dim(flag.reason ?? "missing this run")}  ${badge("missing")}`
+      );
+      continue;
+    }
+    lines.push(`  ${flag.name}  ${flag.status === "pass" ? badge("pass") : badge("fail")}`);
+    if (flag.patch.skipped) {
+      lines.push(
+        `    ${"Patch".padEnd(8)}  ${dim("-")}  ${EMPTY_PATCH_REASON}  ${badge("skip")}`
+      );
+    } else {
+      lines.push(
+        formatMetricLine("Patch", flag.patch.pct, flag.patch.threshold, flag.patch.pass, "    ")
+      );
+    }
+    lines.push(
+      formatMetricLine(
+        "Project",
+        flag.project.pct,
+        flag.project.threshold,
+        flag.project.pass,
+        "    "
+      )
+    );
+  }
+  return lines;
 }
 function runCheck(input) {
   const { config, diff, json } = input;
@@ -2708,6 +3758,7 @@ function runCheck(input) {
       patchPass: true,
       projectPass: true,
       overall: "pass",
+      flagResults: [],
       stdout: "",
       stderr: `${dim("tested.dev \u2014 coverage gate")}  ${badge("info")}
 
@@ -2724,7 +3775,14 @@ ${tip("add thresholds.patch / thresholds.project to enforce")}
   const patchSkipped = isEmptyPatch(diff.patch);
   const patchPass = patchSkipped ? true : patchPct >= patchThreshold;
   const projectPass = projectPct >= projectThreshold;
-  const overall = patchPass && projectPass ? "pass" : "fail";
+  const flagResults = evaluateFlags({
+    config,
+    files: input.files ?? [],
+    addedByFile: input.addedByFile ?? /* @__PURE__ */ new Map(),
+    ...input.onlyFlag !== void 0 ? { onlyFlag: input.onlyFlag } : {}
+  });
+  const flagsOk = flagsPass(flagResults);
+  const overall = patchPass && projectPass && flagsOk ? "pass" : "fail";
   const exitCode = overall === "pass" ? 0 : 1;
   if (json) {
     const payload = {
@@ -2735,6 +3793,7 @@ ${tip("add thresholds.patch / thresholds.project to enforce")}
         ...patchSkipped ? { skipped: true, reason: EMPTY_PATCH_REASON } : {}
       },
       project: { pct: projectPct, threshold: projectThreshold, pass: projectPass },
+      ...flagResults.length > 0 ? { flags: flagsToJson(flagResults) } : {},
       overall,
       ...patchSkipped ? { note: EMPTY_PATCH_REASON } : {}
     };
@@ -2743,6 +3802,7 @@ ${tip("add thresholds.patch / thresholds.project to enforce")}
       patchPass,
       projectPass,
       overall,
+      flagResults,
       stdout: JSON.stringify(payload) + "\n",
       stderr: "",
       exitCode
@@ -2761,11 +3821,20 @@ ${tip("add thresholds.patch / thresholds.project to enforce")}
     lines.push(formatMetricLine("Patch", patchPct, patchThreshold, patchPass));
   }
   lines.push(formatMetricLine("Project", projectPct, projectThreshold, projectPass));
+  lines.push(...formatFlagLines(flagResults));
   if (overall === "fail") {
     lines.push("");
     if (patchSkipped) {
       lines.push(dim("No executable lines in the patch \u2014 patch gate skipped."));
     }
+    const missing = flagResults.filter((f) => f.status === "missing");
+    if (missing.length > 0) {
+      lines.push(
+        dim(
+          "Missing flags fail this run (no carryforward). Collect that package's coverage or scope the job with --flag."
+        )
+      );
+    }
     lines.push(tip("add tests for uncovered ranges: tested diff"));
   } else {
     lines.push("");
@@ -2781,6 +3850,7 @@ ${tip("add thresholds.patch / thresholds.project to enforce")}
     patchPass,
     projectPass,
     overall,
+    flagResults,
     stdout: lines.join("\n"),
     stderr: "",
     exitCode
@@ -2789,10 +3859,47 @@ ${tip("add thresholds.patch / thresholds.project to enforce")}
 function registerCheckCommand(program2) {
   program2.command("check").description(
     "Exit non-zero if patch or project coverage falls below configured thresholds."
-  ).option("--json", "Emit machine-readable JSON to stdout (exit code unchanged).", false).option("--base <ref>", "Git base ref to diff against", void 0).action(async (opts) => {
+  ).option("--json", "Emit machine-readable JSON to stdout (exit code unchanged).", false).option("--base <ref>", "Git base ref to diff against", void 0).option(
+    "--file <path>",
+    "Coverage file to merge (repeatable). Overrides coverage.path.",
+    collectCoverageFile,
+    []
+  ).option("--complete", "Conclude the gate (last shard / finish job)", false).option("--incomplete", "Do not evaluate the gate (shard 1 of N)", false).option("--parts <n>", "Total shard count (gate waits until last part / --complete)").option("--part <n>", "1-based shard index").option(
+    "--flag <name>",
+    "Evaluate only this flag (job already scoped \u2014 the coverage file is the flag)"
+  ).action(async (opts) => {
     try {
       const cwd = process.cwd();
       const config = await loadConfig({ cwd });
+      let merge;
+      try {
+        merge = resolveCoverageMerge(opts);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(formatCliError(message));
+        process.exitCode = 1;
+        return;
+      }
+      if (!merge.complete) {
+        const result2 = formatIncompleteCheck(merge, opts.json);
+        if (result2.stderr) process.stderr.write(result2.stderr);
+        if (result2.stdout) process.stdout.write(result2.stdout);
+        process.exitCode = result2.exitCode;
+        return;
+      }
+      const coveragePaths = resolveCoveragePaths({
+        ...opts.file && opts.file.length > 0 ? { files: opts.file } : {},
+        configPath: config.coverage.path
+      });
+      const existing = existingCoveragePaths(coveragePaths, cwd, existsSync7);
+      const handshakeOnly = merge.complete && existing.length === 0 && (opts.complete || merge.totalParts !== void 0);
+      if (handshakeOnly) {
+        const result2 = formatCompleteHandshakeCheck(opts.json);
+        if (result2.stderr) process.stderr.write(result2.stderr);
+        if (result2.stdout) process.stdout.write(result2.stdout);
+        process.exitCode = result2.exitCode;
+        return;
+      }
       if (!config.thresholds) {
         const result2 = runCheck({
           config,
@@ -2813,12 +3920,20 @@ function registerCheckCommand(program2) {
         process.exitCode = result2.exitCode;
         return;
       }
-      const diff = await computeDiff({
+      const { diff, files, addedByFile } = await computeDiffContext({
         cwd,
         config,
-        ...opts.base !== void 0 ? { baseRef: opts.base } : {}
+        ...opts.base !== void 0 ? { baseRef: opts.base } : {},
+        ...coveragePaths.length > 0 ? { coveragePaths } : {}
+      });
+      const result = runCheck({
+        config,
+        diff,
+        json: opts.json,
+        files,
+        addedByFile,
+        ...opts.flag && opts.flag.trim() ? { onlyFlag: opts.flag.trim() } : {}
       });
-      const result = runCheck({ config, diff, json: opts.json });
       if (result.stderr) process.stderr.write(result.stderr);
       if (result.stdout) process.stdout.write(result.stdout);
       process.exitCode = result.exitCode;
@@ -2831,8 +3946,8 @@ function registerCheckCommand(program2) {
 }
 
 // src/commands/explain.ts
-import { readFile as readFile3 } from "fs/promises";
-import { resolve as resolve6 } from "path";
+import { readFile as readFile5 } from "fs/promises";
+import { resolve as resolve7 } from "path";
 import "commander";
 function parseLocation(input) {
   const idx = input.lastIndexOf(":");
@@ -2893,9 +4008,12 @@ function registerExplainCommand(program2) {
       const { path: relPath, line } = parseLocation(location);
       const config = await loadConfig({ cwd });
       const ctx = await openRepo(cwd);
-      const coveragePath = resolve6(cwd, config.coverage.path);
-      assertWithinRoot(ctx.repoRoot, coveragePath);
-      const files = await parseIstanbul({ path: coveragePath, repoRoot: ctx.repoRoot });
+      const files = await parseAndMergeCoverage({
+        paths: resolveCoveragePaths({ configPath: config.coverage.path }),
+        cwd,
+        repoRoot: ctx.repoRoot,
+        ...config.coverage.format ? { format: config.coverage.format } : {}
+      });
       const file = files.find((f) => f.path === relPath);
       if (!file) {
         process.stderr.write(`error: no coverage data for ${relPath}
@@ -2903,9 +4021,9 @@ function registerExplainCommand(program2) {
         process.exitCode = 2;
         return;
       }
-      const resolvedSource = resolve6(ctx.repoRoot, relPath);
+      const resolvedSource = resolve7(ctx.repoRoot, relPath);
       assertWithinRoot(ctx.repoRoot, resolvedSource);
-      const source = await readFile3(resolvedSource, "utf8");
+      const source = await readFile5(resolvedSource, "utf8");
       const sourceLines = source.split("\n");
       const result = explainAt(file, line, sourceLines);
       if (opts.json) {
@@ -3017,11 +4135,11 @@ async function runToken(opts) {
 async function runWhoami(opts) {
   const env = opts.env ?? process.env;
   const identity = await resolveRepoIdentity(opts);
-  const resolve7 = opts.resolveTokenFn ?? resolveToken;
+  const resolve8 = opts.resolveTokenFn ?? resolveToken;
   let tokenSet = false;
   let source = null;
   try {
-    const token = resolve7({ env, isTTY: false, warn: () => {
+    const token = resolve8({ env, isTTY: false, warn: () => {
     } });
     tokenSet = Boolean(token);
     source = tokenSet ? tokenSourceFromEnv(env) : null;