govgate 0.2.0 → 0.2.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 HatStack
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 HatStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,143 +1,143 @@
-# govgate
-
-Pipeline-step CLI for the MT Testing Tool: parses standard test output (JUnit XML),
-maps tests to test cases, reports a run, and **gates the release** via its exit code.
-No SDK in application code — only the pipeline YAML changes.
-
-```
-npx govgate report test-results/junit.xml --env uat
-```
-
-Works identically in GitHub Actions and Azure DevOps. .NET is covered without a NuGet
-package: `dotnet test --logger "junit"` (JunitXml.TestLogger) and point the CLI at the
-output. Jest/Vitest/Playwright/pytest/NUnit/xUnit all emit JUnit XML natively or via a
-standard reporter.
-
-## Commands
-
-### `govgate report <files-or-globs...>`
-
-| Flag | Default | Meaning |
-|---|---|---|
-| `--url <url>` | `MT_TESTING_TOOL_URL` | Tool deployment URL |
-| `--api-key <key>` | `MT_TESTING_TOOL_API_KEY` | API key (env var strongly preferred) |
-| `--config <path>` | `.mt-testing.json` searched upward | Config file |
-| `--suite <slug>` | config `suite` | Target suite |
-| `--env <slug>` | config `defaultEnvironment` | Environment for the run |
-| `--name <name>` | derived from CI context | Run name |
-| `--build-version <v>` | short commit SHA from CI | Build version |
-| `--external-url <url>` | CI build URL | "Build ↗" link on the run page |
-| `--format junit` | `junit` | Input format (v1: junit only) |
-| `--run-id <uuid>` | — | Append to an existing run (multi-job) |
-| `--no-complete` | completes | Leave run in progress; skip the gate |
-| `--fail-on <list>` | `fail` | Gate: `fail` or `fail,blocked` |
-| `--min-executed <pct>` | — | Gate: minimum executed percentage |
-| `--actor <label>` | `govgate` | Tested-by label |
-| `--dry-run` | — | Parse + map + print; post nothing |
-
-### `govgate complete --run-id <uuid> [--fail-on ...] [--min-executed ...]`
-
-Completes a run left open by `--no-complete` and evaluates the gate over **all** results
-in the run (including those posted by other jobs).
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| 0 | Success / gate passed |
-| 1 | **Gate violated** — fail the pipeline step |
-| 2 | Usage or configuration error |
-| 3 | API / network error |
-
-Unmapped tests and unknown case numbers are loud warnings, never non-zero exits.
-
-## Mapping tests to cases
-
-Resolution per test (results are unioned):
-
-1. **Tags**: any `@mt-<caseNumber>` in the test name or classname —
-   `it("completes checkout @mt-2", ...)`.
-2. **Method-name tokens** (v0.2.0+): for identifier-style names (no whitespace — i.e.
-   what .NET JUnit loggers emit), an underscore-delimited `Mt<n>` token maps the test:
-   `Mt5_DuplicateEmail_Rejected`, `Profiles_Mt12_NotFound`, `Delete_Resolves_MT28`.
-   Embedded substrings (`GMT5_…`, `Format2_…`) do not match.
-3. **Config patterns** in `.mt-testing.json`:
-
-```jsonc
-{
-  "suite": "checkout-regression",
-  "defaultEnvironment": "dev",
-  "mappings": {
-    "4":  ["checkout.spec.ts::pays with saved card"],
-    "7":  ["auth/*.spec.ts::*expired session*", "Login flow > redirects*"],
-    "12": ["*newsletter*"]
-  }
-}
-```
-
-Pattern grammar: `*` is the only wildcard; matching is case-insensitive against the
-bare test name, or against the full `file::name` id when the pattern contains `::`.
-
-Aggregation per case is worst-status-wins: any failing mapped test → `fail`; otherwise
-any passing → `pass`; all skipped → the case is not posted (stays pending — a skipped
-test is a non-observation). Suite cases with no mapped tests stay pending and are
-listed as "uncovered" in the summary.
-
-Use the `map-tests` Claude Code skill (in the
-[Maersk-Training/mt-testing-tool](https://github.com/Maersk-Training/mt-testing-tool)
-repo under `skills/`) to generate the mapping semi-automatically, and `--dry-run` to
-validate it.
-
-## .NET specifics (learned the hard way)
-
-- **Emit JUnit**: `dotnet add package JunitXml.TestLogger`, then
-  `dotnet test --logger "junit;LogFilePath=test-results/junit.xml"`.
-- **The logger writes method names, not `DisplayName`s** — `@mt` tags in DisplayNames
-  never reach the XML. Use `Mt<n>` method tokens (above) or `mappings` patterns, and
-  keep method names unique across the project. Verify with `--dry-run`.
-- **Two-tier pattern**: `[Trait("Category","Unit")]` (mocked; build-pipeline gate) vs
-  `[Trait("Category","Smoke")]` (HTTP against the deployed env; release pipeline,
-  after deploy). Filter with `--filter "Category=Unit"` /
-  `--TestCaseFilter:"Category=Smoke"`.
-- **Classic Release has no source checkout**: `dotnet publish` the test project into
-  the build artifact (`drop/tests/`) and run it with the ".NET Core" task using
-  Command `custom` + `vstest` — the `run` command does NOT execute arbitrary commands.
-- The full ADO runbook (variable groups, stage scoping, exact task configs) lives in
-  `skills/onboard-repo/reference.md` in the
-  [Maersk-Training/mt-testing-tool](https://github.com/Maersk-Training/mt-testing-tool)
-  repo — or run the `onboard-repo` skill.
-
-## Multi-job pipelines
-
-```bash
-# job A — creates the run, leaves it open
-govgate report unit-results.xml --no-complete       # emits MT_RUN_ID (GH output / ADO variable)
-
-# job B — appends to the same run
-govgate report e2e-results.xml --run-id $MT_RUN_ID --no-complete
-
-# final job — completes + gates over everything
-govgate complete --run-id $MT_RUN_ID --fail-on fail --min-executed 80
-```
-
-See `docs/examples/github-actions-ci-report.yml` and
-`docs/examples/azure-devops-ci-report.yml` in the
-[Maersk-Training/mt-testing-tool](https://github.com/Maersk-Training/mt-testing-tool)
-repo for full pipelines.
-
-## Registry
-
-Published **publicly on npmjs** as `govgate` — it contains no secrets or org-specific
-logic, so any pipeline can `npx govgate …` with **zero registry config and zero
-tokens**. (This deliberately replaced the earlier private GitHub Packages setup, which
-taxed every consuming repo with `.npmrc` + `read:packages` token wiring.)
-
-Releasing: push a `v<version>` tag (or run the *Publish* workflow manually). The
-workflow authenticates to npm via **Trusted Publishing (OIDC)** — there is **no
-`NPM_TOKEN` secret**; GitHub Actions mints a short-lived identity per run. One-time
-setup: configure this repo + `publish-cli.yml` as a trusted publisher on the npm
-package's *Settings → Trusted Publishing* page.
-
-**No registry at all** (local/dev): run straight from a checkout —
-`node <path-to>/govGate/dist/index.js report …` — or
-`npm exec --package=<path-to>.tgz -- govgate …` after `npm pack`.
+# govgate
+
+Pipeline-step CLI for the MT Testing Tool: parses standard test output (JUnit XML),
+maps tests to test cases, reports a run, and **gates the release** via its exit code.
+No SDK in application code — only the pipeline YAML changes.
+
+```
+npx govgate report test-results/junit.xml --env uat
+```
+
+Works identically in GitHub Actions and Azure DevOps. .NET is covered without a NuGet
+package: `dotnet test --logger "junit"` (JunitXml.TestLogger) and point the CLI at the
+output. Jest/Vitest/Playwright/pytest/NUnit/xUnit all emit JUnit XML natively or via a
+standard reporter.
+
+## Commands
+
+### `govgate report <files-or-globs...>`
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--url <url>` | `MT_TESTING_TOOL_URL` | Tool deployment URL |
+| `--api-key <key>` | `MT_TESTING_TOOL_API_KEY` | API key (env var strongly preferred) |
+| `--config <path>` | `.mt-testing.json` searched upward | Config file |
+| `--suite <slug>` | config `suite` | Target suite |
+| `--env <slug>` | config `defaultEnvironment` | Environment for the run |
+| `--name <name>` | derived from CI context | Run name |
+| `--build-version <v>` | short commit SHA from CI | Build version |
+| `--external-url <url>` | CI build URL | "Build ↗" link on the run page |
+| `--format junit` | `junit` | Input format (v1: junit only) |
+| `--run-id <uuid>` | — | Append to an existing run (multi-job) |
+| `--no-complete` | completes | Leave run in progress; skip the gate |
+| `--fail-on <list>` | `fail` | Gate: `fail` or `fail,blocked` |
+| `--min-executed <pct>` | — | Gate: minimum executed percentage |
+| `--actor <label>` | `govgate` | Tested-by label |
+| `--dry-run` | — | Parse + map + print; post nothing |
+
+### `govgate complete --run-id <uuid> [--fail-on ...] [--min-executed ...]`
+
+Completes a run left open by `--no-complete` and evaluates the gate over **all** results
+in the run (including those posted by other jobs).
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success / gate passed |
+| 1 | **Gate violated** — fail the pipeline step |
+| 2 | Usage or configuration error |
+| 3 | API / network error |
+
+Unmapped tests and unknown case numbers are loud warnings, never non-zero exits.
+
+## Mapping tests to cases
+
+Resolution per test (results are unioned):
+
+1. **Tags**: any `@mt-<caseNumber>` in the test name or classname —
+   `it("completes checkout @mt-2", ...)`.
+2. **Method-name tokens** (v0.2.0+): for identifier-style names (no whitespace — i.e.
+   what .NET JUnit loggers emit), an underscore-delimited `Mt<n>` token maps the test:
+   `Mt5_DuplicateEmail_Rejected`, `Profiles_Mt12_NotFound`, `Delete_Resolves_MT28`.
+   Embedded substrings (`GMT5_…`, `Format2_…`) do not match.
+3. **Config patterns** in `.mt-testing.json`:
+
+```jsonc
+{
+  "suite": "checkout-regression",
+  "defaultEnvironment": "dev",
+  "mappings": {
+    "4":  ["checkout.spec.ts::pays with saved card"],
+    "7":  ["auth/*.spec.ts::*expired session*", "Login flow > redirects*"],
+    "12": ["*newsletter*"]
+  }
+}
+```
+
+Pattern grammar: `*` is the only wildcard; matching is case-insensitive against the
+bare test name, or against the full `file::name` id when the pattern contains `::`.
+
+Aggregation per case is worst-status-wins: any failing mapped test → `fail`; otherwise
+any passing → `pass`; all skipped → the case is not posted (stays pending — a skipped
+test is a non-observation). Suite cases with no mapped tests stay pending and are
+listed as "uncovered" in the summary.
+
+Use the `map-tests` Claude Code skill (in the
+[Maersk-Training/mt-testing-tool](https://github.com/Maersk-Training/mt-testing-tool)
+repo under `skills/`) to generate the mapping semi-automatically, and `--dry-run` to
+validate it.
+
+## .NET specifics (learned the hard way)
+
+- **Emit JUnit**: `dotnet add package JunitXml.TestLogger`, then
+  `dotnet test --logger "junit;LogFilePath=test-results/junit.xml"`.
+- **The logger writes method names, not `DisplayName`s** — `@mt` tags in DisplayNames
+  never reach the XML. Use `Mt<n>` method tokens (above) or `mappings` patterns, and
+  keep method names unique across the project. Verify with `--dry-run`.
+- **Two-tier pattern**: `[Trait("Category","Unit")]` (mocked; build-pipeline gate) vs
+  `[Trait("Category","Smoke")]` (HTTP against the deployed env; release pipeline,
+  after deploy). Filter with `--filter "Category=Unit"` /
+  `--TestCaseFilter:"Category=Smoke"`.
+- **Classic Release has no source checkout**: `dotnet publish` the test project into
+  the build artifact (`drop/tests/`) and run it with the ".NET Core" task using
+  Command `custom` + `vstest` — the `run` command does NOT execute arbitrary commands.
+- The full ADO runbook (variable groups, stage scoping, exact task configs) lives in
+  `skills/onboard-repo/reference.md` in the
+  [Maersk-Training/mt-testing-tool](https://github.com/Maersk-Training/mt-testing-tool)
+  repo — or run the `onboard-repo` skill.
+
+## Multi-job pipelines
+
+```bash
+# job A — creates the run, leaves it open
+govgate report unit-results.xml --no-complete       # emits MT_RUN_ID (GH output / ADO variable)
+
+# job B — appends to the same run
+govgate report e2e-results.xml --run-id $MT_RUN_ID --no-complete
+
+# final job — completes + gates over everything
+govgate complete --run-id $MT_RUN_ID --fail-on fail --min-executed 80
+```
+
+See `docs/examples/github-actions-ci-report.yml` and
+`docs/examples/azure-devops-ci-report.yml` in the
+[Maersk-Training/mt-testing-tool](https://github.com/Maersk-Training/mt-testing-tool)
+repo for full pipelines.
+
+## Registry
+
+Published **publicly on npmjs** as `govgate` — it contains no secrets or org-specific
+logic, so any pipeline can `npx govgate …` with **zero registry config and zero
+tokens**. (This deliberately replaced the earlier private GitHub Packages setup, which
+taxed every consuming repo with `.npmrc` + `read:packages` token wiring.)
+
+Releasing: push a `v<version>` tag (or run the *Publish* workflow manually). The
+workflow authenticates to npm via **Trusted Publishing (OIDC)** — there is **no
+`NPM_TOKEN` secret**; GitHub Actions mints a short-lived identity per run. One-time
+setup: configure this repo + `publish-cli.yml` as a trusted publisher on the npm
+package's *Settings → Trusted Publishing* page.
+
+**No registry at all** (local/dev): run straight from a checkout —
+`node <path-to>/govGate/dist/index.js report …` — or
+`npm exec --package=<path-to>.tgz -- govgate …` after `npm pack`.

package/dist/index.js

@@ -0,0 +1,572 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { Command } from "commander";
+import { glob } from "tinyglobby";
+
+// src/api.ts
+var ApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+  status;
+};
+var BATCH_SIZE = 500;
+var ApiClient = class {
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+  }
+  baseUrl;
+  apiKey;
+  async request(method, path, body) {
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0
+      });
+    } catch (e) {
+      throw new ApiError(`Could not reach ${this.baseUrl}: ${e.message}`, 0);
+    }
+    const text2 = await res.text();
+    if (!res.ok) {
+      let detail = text2;
+      try {
+        detail = JSON.parse(text2).error ?? text2;
+      } catch {
+      }
+      throw new ApiError(`${method} ${path} -> ${res.status}: ${detail}`, res.status);
+    }
+    return JSON.parse(text2);
+  }
+  createRun(input) {
+    return this.request("POST", "/api/v1/runs", { ...input, source: "ci" });
+  }
+  async postResults(runId, results) {
+    let updated = 0;
+    const unknownCaseNumbers = [];
+    for (let i = 0; i < results.length; i += BATCH_SIZE) {
+      const batch = results.slice(i, i + BATCH_SIZE);
+      const res = await this.request(
+        "POST",
+        `/api/v1/runs/${runId}/results`,
+        { results: batch }
+      );
+      updated += res.updated;
+      unknownCaseNumbers.push(...res.unknownCaseNumbers);
+    }
+    return { updated, unknownCaseNumbers };
+  }
+  completeRun(runId) {
+    return this.request("PATCH", `/api/v1/runs/${runId}`, { status: "completed" });
+  }
+  getSummary(runId) {
+    return this.request("GET", `/api/v1/runs/${runId}/summary`);
+  }
+  getSuiteCases(slug) {
+    return this.request("GET", `/api/v1/suites/${slug}/cases`);
+  }
+};
+
+// src/ci-context.ts
+import { appendFileSync } from "fs";
+import { hostname } from "os";
+function detectCiContext(env = process.env) {
+  if (env.GITHUB_ACTIONS === "true") {
+    const repo = env.GITHUB_REPOSITORY;
+    return {
+      provider: "github",
+      defaultRunName: `CI \u2014 ${env.GITHUB_WORKFLOW ?? "workflow"} #${env.GITHUB_RUN_NUMBER ?? "?"} \u2014 ${env.GITHUB_REF_NAME ?? "?"}`,
+      buildVersion: env.GITHUB_SHA?.slice(0, 8),
+      externalUrl: repo && env.GITHUB_RUN_ID ? `${env.GITHUB_SERVER_URL ?? "https://github.com"}/${repo}/actions/runs/${env.GITHUB_RUN_ID}` : void 0
+    };
+  }
+  if (env.TF_BUILD === "True") {
+    const collection = env.SYSTEM_COLLECTIONURI;
+    const project = env.SYSTEM_TEAMPROJECT;
+    return {
+      provider: "azure-devops",
+      defaultRunName: `CI \u2014 ${env.BUILD_DEFINITIONNAME ?? "pipeline"} #${env.BUILD_BUILDNUMBER ?? "?"} \u2014 ${env.BUILD_SOURCEBRANCHNAME ?? "?"}`,
+      buildVersion: env.BUILD_SOURCEVERSION?.slice(0, 8),
+      externalUrl: collection && project && env.BUILD_BUILDID ? `${collection}${encodeURIComponent(project)}/_build/results?buildId=${env.BUILD_BUILDID}` : void 0
+    };
+  }
+  return {
+    provider: "generic",
+    defaultRunName: `CI \u2014 ${hostname()} \u2014 ${(/* @__PURE__ */ new Date()).toISOString()}`
+  };
+}
+function emitRunIdVariable(runId, ctx, env = process.env) {
+  console.log(`MT_RUN_ID=${runId}`);
+  if (ctx.provider === "github" && env.GITHUB_OUTPUT) {
+    appendFileSync(env.GITHUB_OUTPUT, `run-id=${runId}
+`);
+  } else if (ctx.provider === "azure-devops") {
+    console.log(`##vso[task.setvariable variable=MT_RUN_ID;isOutput=true]${runId}`);
+  }
+}
+
+// src/config.ts
+import { readFileSync, existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+var ConfigError = class extends Error {
+};
+function findConfigFile(startDir, explicitPath) {
+  if (explicitPath) {
+    const p = resolve(startDir, explicitPath);
+    if (!existsSync(p)) throw new ConfigError(`Config file not found: ${p}`);
+    return p;
+  }
+  let dir = resolve(startDir);
+  for (; ; ) {
+    const candidate = join(dir, ".mt-testing.json");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function loadFileConfig(path) {
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    throw new ConfigError(`Could not parse ${path}: ${e.message}`);
+  }
+  if (typeof data !== "object" || data === null) {
+    throw new ConfigError(`${path} must contain a JSON object`);
+  }
+  const cfg = data;
+  const out = {};
+  if (cfg.suite !== void 0) {
+    if (typeof cfg.suite !== "string") throw new ConfigError(`${path}: "suite" must be a string`);
+    out.suite = cfg.suite;
+  }
+  if (cfg.defaultEnvironment !== void 0) {
+    if (typeof cfg.defaultEnvironment !== "string")
+      throw new ConfigError(`${path}: "defaultEnvironment" must be a string`);
+    out.defaultEnvironment = cfg.defaultEnvironment;
+  }
+  if (cfg.mappings !== void 0) {
+    if (typeof cfg.mappings !== "object" || cfg.mappings === null)
+      throw new ConfigError(`${path}: "mappings" must be an object`);
+    const mappings = {};
+    for (const [key, value] of Object.entries(cfg.mappings)) {
+      if (!/^\d+$/.test(key))
+        throw new ConfigError(`${path}: mapping key "${key}" must be a case number`);
+      if (!Array.isArray(value) || value.some((v) => typeof v !== "string"))
+        throw new ConfigError(`${path}: mappings["${key}"] must be an array of pattern strings`);
+      mappings[key] = value;
+    }
+    out.mappings = mappings;
+  }
+  return out;
+}
+function resolveConfig(flags, cwd = process.cwd()) {
+  const configPath = findConfigFile(cwd, flags.config);
+  const file = configPath ? loadFileConfig(configPath) : {};
+  const url = flags.url ?? process.env.MT_TESTING_TOOL_URL;
+  const apiKey = flags.apiKey ?? process.env.MT_TESTING_TOOL_API_KEY;
+  const suite = flags.suite ?? file.suite;
+  const environment = flags.env ?? file.defaultEnvironment;
+  if (!url) {
+    throw new ConfigError(
+      "Tool URL missing. Set MT_TESTING_TOOL_URL or pass --url https://<your-deployment>"
+    );
+  }
+  if (!apiKey) {
+    throw new ConfigError(
+      "API key missing. Set MT_TESTING_TOOL_API_KEY (create one in the tool: Admin -> API keys, scoped to this application)."
+    );
+  }
+  if (!suite) {
+    throw new ConfigError(
+      'Suite missing. Pass --suite <slug> or add { "suite": "<slug>" } to .mt-testing.json in the repo root.'
+    );
+  }
+  return {
+    url: url.replace(/\/+$/, ""),
+    apiKey,
+    suite,
+    environment,
+    mappings: file.mappings ?? {},
+    configPath
+  };
+}
+
+// src/gate.ts
+function parseFailOn(value) {
+  const parts = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  const valid = ["fail", "blocked"];
+  for (const p of parts) {
+    if (!valid.includes(p)) throw new Error(`Invalid --fail-on value '${p}' (allowed: fail, blocked)`);
+  }
+  return parts;
+}
+function executedPercent(counts) {
+  if (counts.total === 0) return 0;
+  return Math.round((counts.total - counts.pending) / counts.total * 1e3) / 10;
+}
+function evaluateGate(counts, options) {
+  const reasons = [];
+  for (const status of options.failOn) {
+    if (counts[status] > 0) {
+      reasons.push(`${counts[status]} case(s) with status '${status}'`);
+    }
+  }
+  const pct = executedPercent(counts);
+  if (options.minExecuted !== void 0 && pct < options.minExecuted) {
+    reasons.push(`executed ${pct}% < required ${options.minExecuted}%`);
+  }
+  return { passed: reasons.length === 0, reasons, executedPercent: pct };
+}
+
+// src/mapping.ts
+var TAG_RE = /@mt-(\d+)\b/g;
+var METHOD_TAG_RE = /(?:^|_)mt[-_]?(\d+)(?=_|$)/gi;
+function patternToRegex(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`, "i");
+}
+function tagCases(test) {
+  const haystack = `${test.name} ${test.classname ?? ""}`;
+  const cases = [...haystack.matchAll(TAG_RE)].map((m) => Number(m[1]));
+  if (!/\s/.test(test.name)) {
+    cases.push(...[...test.name.matchAll(METHOD_TAG_RE)].map((m) => Number(m[1])));
+  }
+  return cases;
+}
+function resolveCases(test, mappings) {
+  const cases = new Set(tagCases(test));
+  for (const [num, patterns] of Object.entries(mappings)) {
+    for (const pattern of patterns) {
+      const regex = patternToRegex(pattern);
+      const candidates = pattern.includes("::") ? [test.id] : [test.name, test.id];
+      if (candidates.some((c) => regex.test(c))) {
+        cases.add(Number(num));
+        break;
+      }
+    }
+  }
+  return [...cases];
+}
+var NOTE_CAP = 4e3;
+var MESSAGE_CAP = 500;
+function truncate(s, cap) {
+  return s.length <= cap ? s : s.slice(0, cap - 12) + "\u2026 [truncated]";
+}
+function buildNotes(tests, status) {
+  if (status === "pass") {
+    const ids = tests.filter((t) => t.status === "pass").map((t) => t.id);
+    const shown = ids.slice(0, 10);
+    const more = ids.length - shown.length;
+    return truncate(
+      `${ids.length} automated test(s) passed:
+` + shown.map((id) => `- ${id}`).join("\n") + (more > 0 ? `
+\u2026 and ${more} more` : ""),
+      NOTE_CAP
+    );
+  }
+  const failing = tests.filter((t) => t.status === "fail");
+  return truncate(
+    `${failing.length} automated test(s) failed:
+` + failing.map((t) => `- ${t.id}: ${truncate(t.message ?? "no message", MESSAGE_CAP)}`).join("\n"),
+    NOTE_CAP
+  );
+}
+function mapTestsToCases(tests, mappings) {
+  const byCase = /* @__PURE__ */ new Map();
+  const unmappedTests = [];
+  for (const test of tests) {
+    const cases = resolveCases(test, mappings);
+    if (cases.length === 0) {
+      unmappedTests.push(test);
+      continue;
+    }
+    for (const num of cases) {
+      const list = byCase.get(num) ?? [];
+      list.push(test);
+      byCase.set(num, list);
+    }
+  }
+  const results = [];
+  const skippedOnlyCases = [];
+  for (const [caseNumber, caseTests] of [...byCase.entries()].sort((a, b) => a[0] - b[0])) {
+    const anyFail = caseTests.some((t) => t.status === "fail");
+    const anyPass = caseTests.some((t) => t.status === "pass");
+    if (!anyFail && !anyPass) {
+      skippedOnlyCases.push(caseNumber);
+      continue;
+    }
+    const status = anyFail ? "fail" : "pass";
+    results.push({ caseNumber, status, notes: buildNotes(caseTests, status), tests: caseTests });
+  }
+  return { results, unmappedTests, skippedOnlyCases };
+}
+
+// src/parsers/junit.ts
+import { XMLParser } from "fast-xml-parser";
+function asArray(value) {
+  if (value === void 0) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function text(node) {
+  if (node == null) return "";
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  const obj = node;
+  const parts = [obj["@_message"], obj["@_type"], obj["#text"]].filter((v) => v != null && v !== "").map(String);
+  return parts.join(" \u2014 ");
+}
+function parseTestcase(tc) {
+  const name = String(tc["@_name"] ?? "(unnamed test)");
+  const classname = tc["@_classname"] ? String(tc["@_classname"]) : void 0;
+  const file = tc["@_file"] ? String(tc["@_file"]) : void 0;
+  let status = "pass";
+  let message;
+  const failure = asArray(tc.failure)[0];
+  const error = asArray(tc.error)[0];
+  if (failure !== void 0 || error !== void 0) {
+    status = "fail";
+    message = text(failure ?? error).trim() || "Test failed (no message in report)";
+  } else if (tc.skipped !== void 0) {
+    status = "skipped";
+  }
+  const scope = file ?? classname;
+  return {
+    id: scope ? `${scope}::${name}` : name,
+    name,
+    classname,
+    file,
+    status,
+    message,
+    timeSec: tc["@_time"] !== void 0 ? Number(tc["@_time"]) : void 0
+  };
+}
+function collectSuites(node, out) {
+  for (const suite of asArray(node.testsuite)) {
+    out.push(suite);
+    collectSuites(suite, out);
+  }
+}
+function parseJUnitXml(xml) {
+  const parser = new XMLParser({
+    ignoreAttributes: false,
+    parseAttributeValue: false,
+    parseTagValue: false
+  });
+  const doc = parser.parse(xml);
+  const suites = [];
+  const root = doc.testsuites ?? doc;
+  if (doc.testsuites !== void 0) collectSuites(root, suites);
+  else if (doc.testsuite !== void 0) collectSuites(doc, suites);
+  const tests = [];
+  for (const suite of suites) {
+    for (const tc of asArray(suite.testcase)) {
+      tests.push(parseTestcase(tc));
+    }
+  }
+  return tests;
+}
+
+// src/summary.ts
+function printMappingTable(outcome) {
+  console.log("\nMapped cases:");
+  if (outcome.results.length === 0) {
+    console.log("  (none \u2014 no tests matched a case tag or mapping pattern)");
+  }
+  for (const r of outcome.results) {
+    console.log(`  #${r.caseNumber} -> ${r.status.toUpperCase()} (${r.tests.length} test(s))`);
+    for (const t of r.tests) console.log(`      ${t.status.padEnd(7)} ${t.id}`);
+  }
+  if (outcome.skippedOnlyCases.length) {
+    console.log(
+      `  Cases with only skipped tests (not reported): ${outcome.skippedOnlyCases.map((n) => `#${n}`).join(", ")}`
+    );
+  }
+  if (outcome.unmappedTests.length) {
+    console.log(`
+Unmapped tests (${outcome.unmappedTests.length}) \u2014 add @mt-<case> tags or .mt-testing.json mappings:`);
+    for (const t of outcome.unmappedTests.slice(0, 20)) console.log(`  - ${t.id}`);
+    if (outcome.unmappedTests.length > 20)
+      console.log(`  \u2026 and ${outcome.unmappedTests.length - 20} more`);
+  }
+}
+function printCounts(counts, executedPercent2) {
+  console.log(
+    `
+Run totals: ${counts.total} cases \u2014 pass ${counts.pass}, fail ${counts.fail}, blocked ${counts.blocked}, na ${counts.na}, pending ${counts.pending} (${executedPercent2}% executed)`
+  );
+}
+function printUnknownCases(unknown) {
+  if (!unknown.length) return;
+  console.error(
+    `
+!! WARNING: ${unknown.length} reported case number(s) do not exist in the suite: ${unknown.map((n) => `#${n}`).join(", ")}
+!! Their results were DROPPED. Fix the @mt tags / mappings or re-import the suite.`
+  );
+}
+function printGate(verdict) {
+  if (verdict.passed) {
+    console.log("\nGate: PASSED");
+  } else {
+    console.error(`
+Gate: FAILED
+${verdict.reasons.map((r) => `  - ${r}`).join("\n")}`);
+  }
+}
+function printRunUrl(baseUrl, runId) {
+  console.log(`
+Run: ${baseUrl}/runs/${runId}`);
+}
+
+// src/index.ts
+var EXIT_GATE_FAILED = 1;
+var EXIT_USAGE = 2;
+var EXIT_API = 3;
+function fail(code, message) {
+  console.error(`Error: ${message}`);
+  process.exit(code);
+}
+function handleError(e) {
+  if (e instanceof ConfigError) fail(EXIT_USAGE, e.message);
+  if (e instanceof ApiError) fail(EXIT_API, e.message);
+  fail(EXIT_API, e instanceof Error ? e.message : String(e));
+}
+function gateOptionsFrom(opts) {
+  const gate = { failOn: parseFailOn(opts.failOn) };
+  if (opts.minExecuted !== void 0) {
+    const pct = Number(opts.minExecuted);
+    if (!Number.isFinite(pct) || pct < 0 || pct > 100) {
+      throw new ConfigError("--min-executed must be a number between 0 and 100");
+    }
+    gate.minExecuted = pct;
+  }
+  return gate;
+}
+async function parseFiles(patterns, format) {
+  if (format !== "junit") {
+    throw new ConfigError(`Unsupported --format '${format}' (v1 supports: junit)`);
+  }
+  const files = await glob(patterns, { absolute: true });
+  if (files.length === 0) {
+    throw new ConfigError(`No files matched: ${patterns.join(", ")}`);
+  }
+  const tests = [];
+  for (const file of files) {
+    tests.push(...parseJUnitXml(readFileSync2(file, "utf8")));
+  }
+  if (tests.length === 0) {
+    throw new ConfigError(`Parsed ${files.length} file(s) but found no test cases`);
+  }
+  return tests;
+}
+async function completeAndGate(api, url, runId, gate) {
+  await api.completeRun(runId);
+  const summary = await api.getSummary(runId);
+  printCounts(summary.counts, summary.executedPercent);
+  const verdict = evaluateGate(summary.counts, gate);
+  printGate(verdict);
+  printRunUrl(url, runId);
+  if (!verdict.passed) process.exit(EXIT_GATE_FAILED);
+}
+var program = new Command().name("govgate").description("Report CI test results to the MT Testing Tool and gate releases on the outcome.");
+program.command("report").description("Parse test result files (JUnit XML), map tests to cases, and report a run").argument("<files...>", "result files or globs, e.g. test-results/*.xml").option("--url <url>", "tool URL (or MT_TESTING_TOOL_URL)").option("--api-key <key>", "API key (prefer MT_TESTING_TOOL_API_KEY)").option("--config <path>", "path to .mt-testing.json (default: searched upward)").option("--suite <slug>", "suite slug (overrides config)").option("--env <slug>", "environment slug (overrides config)").option("--name <name>", "run name (default: derived from CI context)").option("--build-version <v>", "build version (default: short commit SHA from CI)").option("--external-url <url>", "link to the build/PR (default: from CI context)").option("--format <format>", "input format", "junit").option("--run-id <uuid>", "append results to an existing run instead of creating one").option("--no-complete", "leave the run in progress (multi-job pipelines); skips the gate").option("--fail-on <list>", "statuses that fail the gate: fail | fail,blocked", "fail").option("--min-executed <pct>", "minimum executed percentage required by the gate").option("--actor <label>", "tested-by label on results", "govgate").option("--dry-run", "parse and map only; post nothing").action(async (files, opts) => {
+  try {
+    const flags = {
+      url: opts.url,
+      apiKey: opts.apiKey,
+      suite: opts.suite,
+      env: opts.env,
+      config: opts.config
+    };
+    const tests = await parseFiles(files, opts.format);
+    const config = opts.dryRun ? tryResolveConfig(flags) : resolveConfig(flags);
+    const mappings = config?.mappings ?? {};
+    const outcome = mapTestsToCases(tests, mappings);
+    console.log(
+      `Parsed ${tests.length} test(s) from ${files.join(", ")} \u2014 ${outcome.results.length} case(s) mapped, ${outcome.unmappedTests.length} unmapped test(s)`
+    );
+    printMappingTable(outcome);
+    if (opts.dryRun) {
+      if (config) {
+        const api2 = new ApiClient(config.url, config.apiKey);
+        const suite = await api2.getSuiteCases(config.suite);
+        const known = new Set(suite.cases.map((c) => c.caseNumber));
+        const unknown = outcome.results.map((r) => r.caseNumber).filter((n) => !known.has(n));
+        printUnknownCases(unknown);
+      } else {
+        console.log("\n(dry run without credentials \u2014 case numbers not validated against the suite)");
+      }
+      console.log("\nDry run \u2014 nothing was posted.");
+      return;
+    }
+    const gate = gateOptionsFrom(opts);
+    const api = new ApiClient(config.url, config.apiKey);
+    const ci = detectCiContext();
+    let runId = opts.runId ?? "";
+    if (!runId) {
+      const run = await api.createRun({
+        suiteSlug: config.suite,
+        environmentSlug: config.environment,
+        name: opts.name ?? ci.defaultRunName,
+        buildVersion: opts.buildVersion ?? ci.buildVersion,
+        externalUrl: opts.externalUrl ?? ci.externalUrl
+      });
+      runId = run.runId;
+      console.log(
+        `
+Created run '${opts.name ?? ci.defaultRunName}' (${run.totalCases} cases, ${run.autoNa} auto-N/A)`
+      );
+      emitRunIdVariable(runId, ci);
+    }
+    const { updated, unknownCaseNumbers } = await api.postResults(
+      runId,
+      outcome.results.map((r) => ({
+        caseNumber: r.caseNumber,
+        status: r.status,
+        notes: r.notes,
+        actor: opts.actor
+      }))
+    );
+    console.log(`Posted ${updated} result(s).`);
+    printUnknownCases(unknownCaseNumbers);
+    if (opts.complete) {
+      await completeAndGate(api, config.url, runId, gate);
+    } else {
+      console.log("\nRun left in progress (--no-complete). Finish with: govgate complete --run-id " + runId);
+      printRunUrl(config.url, runId);
+    }
+  } catch (e) {
+    handleError(e);
+  }
+});
+function tryResolveConfig(flags) {
+  try {
+    return resolveConfig(flags);
+  } catch {
+    return void 0;
+  }
+}
+program.command("complete").description("Complete a run and evaluate the gate (final job of a multi-job pipeline)").requiredOption("--run-id <uuid>", "run to complete").option("--url <url>", "tool URL (or MT_TESTING_TOOL_URL)").option("--api-key <key>", "API key (prefer MT_TESTING_TOOL_API_KEY)").option("--config <path>", "path to .mt-testing.json").option("--suite <slug>", "suite slug (only used for config resolution)").option("--fail-on <list>", "statuses that fail the gate: fail | fail,blocked", "fail").option("--min-executed <pct>", "minimum executed percentage required by the gate").action(async (opts) => {
+  try {
+    const config = resolveConfig({
+      url: opts.url,
+      apiKey: opts.apiKey,
+      suite: opts.suite ?? "unused",
+      config: opts.config
+    });
+    const gate = gateOptionsFrom(opts);
+    const api = new ApiClient(config.url, config.apiKey);
+    await completeAndGate(api, config.url, opts.runId, gate);
+  } catch (e) {
+    handleError(e);
+  }
+});
+program.parseAsync().catch(handleError);

package/package.json

@@ -1,41 +1,42 @@
-{
-  "name": "govgate",
-  "version": "0.2.0",
-  "description": "Governance gate for releases: report CI test results (JUnit XML) to your testing tool and gate promotion on the outcome.",
-  "license": "MIT",
-  "author": "HatStack",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Sejersen92/govGate.git"
-  },
-  "homepage": "https://github.com/Sejersen92/govGate#readme",
-  "bugs": {
-    "url": "https://github.com/Sejersen92/govGate/issues"
-  },
-  "type": "module",
-  "bin": {
-    "govgate": "./dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "commander": "^14.0.2",
-    "fast-xml-parser": "^5.3.4",
-    "tinyglobby": "^0.2.15"
-  },
-  "devDependencies": {
-    "@types/node": "^20.19.43",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
-  }
-}
+{
+  "name": "govgate",
+  "version": "0.2.1",
+  "description": "Governance gate for releases: report CI test results (JUnit XML) to your testing tool and gate promotion on the outcome.",
+  "license": "MIT",
+  "author": "HatStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sejersen92/govGate.git"
+  },
+  "homepage": "https://github.com/Sejersen92/govGate#readme",
+  "bugs": {
+    "url": "https://github.com/Sejersen92/govGate/issues"
+  },
+  "type": "module",
+  "bin": {
+    "govgate": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "fast-xml-parser": "^5.3.4",
+    "tinyglobby": "^0.2.15"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}