@tested/cli 0.1.7 → 0.1.8

package/README.md

@@ -25,7 +25,7 @@ CI uses the composite Action (`tested-hq/cli/action@main`). It installs `@tested
 ```yaml
 - uses: tested-hq/cli/action@main
   with:
-    version: 0.1.7
+    version: 0.1.8
     token: ${{ secrets.TESTED_TOKEN }}
 ```
 
@@ -130,12 +130,72 @@ No executable lines in the patch — patch gate skipped. Project threshold met.
 
 If `thresholds` is missing from `.tested.yaml`, `tested check` prints a notice on stderr and exits 0 — configs that haven't opted in stay green.
 
+### Flags (per package)
+
+Independent floors so a monorepo total cannot hide one package. Each flag is graded from **this run's** coverage files — no carryforward.
+
+```yaml
+flags:
+  frontend:
+    paths: ["apps/web/**", "packages/ui/**"]
+    thresholds:
+      patch: 90   # inherits project from thresholds.project
+  backend:
+    paths: ["apps/api/**"]
+```
+
+`tested check` applies global `thresholds` plus each flag whose paths appear in the merged coverage. Per-flag patch is new executable lines in those paths. A flag with no files this run is **missing** (fail / pending) — never last week's numbers.
+
+A job already scoped to one package: `tested check --flag frontend` (Action `flag:`). That coverage file **is** the flag.
+
+`--json` lists per-flag results (`flags.frontend.patchCheck` → `tested.dev / patch / frontend`). `tested push` sends that same `flags` map on ingest so the app can post those GitHub checks. `tested diff --json` includes it too.
+
+## Coverage formats
+
+`tested diff` / `tested check` / `tested push` all read the same internal model (file path + statement hits). Parsers normalize these artifacts into that model:
+
+| `coverage.format` | Typical path | Produced by |
+|---|---|---|
+| `istanbul-json` (or `v8-json`) | `coverage/coverage-final.json` | Vitest, Jest, nyc — V8 coverage emitted as Istanbul JSON |
+| `lcov` | `coverage/lcov.info`, `*.lcov` | lcov, vitest lcov reporter, pytest-cov `--cov-report=lcov` |
+| `cobertura` | `coverage/cobertura.xml`, `coverage.xml` | Cobertura, pytest-cov `--cov-report=xml` |
+| `jacoco` | `jacoco.xml` | JaCoCo (Maven / Gradle) |
+| `gcov` | `*.gcov` or a directory of them | GNU `gcov` **text** reports (not raw `.gcno` / `.gcda` notes) |
+| `simplecov` | `coverage/.resultset.json` | SimpleCov (Ruby) |
+
+When `coverage.format` is omitted, the CLI auto-detects from the filename and, if needed, the file contents. `coverage/coverage-final.json` is treated as Istanbul/V8 JSON (the default). Set format explicitly in `.tested.yaml` when you want to pin it:
+
+```yaml
+coverage:
+  path: coverage/lcov.info
+  format: lcov   # optional — auto-detected from lcov.info
+```
+
+Multiple files in one job are merged (union of paths, **max** hits — not averaged, not last-file-wins):
+
+```yaml
+coverage:
+  path:
+    - coverage/lcov.info
+    - coverage/python.xml
+```
+
+Or pass `--file` repeatedly / Action `files`. A CI matrix must not conclude the gate on shard 1 of N: `tested push --parts N --part 1` sends `coverageMerge.complete: false`; only `--complete` or the last part posts checks. See the Action README on GitHub (`tested-hq/cli/action`).
+
+`ignores` globs apply after parse, same as before.
+
+**pytest-cov:** emit lcov or Cobertura XML (`--cov-report=lcov` / `--cov-report=xml`). coverage.py JSON is not ingested.
+
+**gcov:** run `gcov` on your `.gcda` files in CI and point `coverage.path` at the resulting `.gcov` text (or the directory that contains them). Binary notes are not parsed.
+
+**SimpleCov:** the default `coverage/.resultset.json` (and the `simplecov-json` gem report) are accepted. Array index 0 is line 1; `null` is non-executable.
+
 ### GitHub Actions
 
 ```yaml
 - uses: tested-hq/cli/action@main
   with:
-    version: 0.1.7
+    version: 0.1.8
     push: true
     pr-number: ${{ github.event.pull_request.number }}
     token: ${{ secrets.TESTED_TOKEN }}
@@ -150,6 +210,8 @@ $ tested check --json
 {"patch":{"pct":87.3,"threshold":80,"pass":true},"project":{"pct":92.1,"threshold":90,"pass":true},"overall":"pass"}
 ```
 
+When `flags` are configured, `tested check --json` and `tested diff --json` include a `flags` map (status, patch/project totals, and `tested.dev / patch / <name>` slugs). `tested push` posts that same map as a sibling field on the ingest body.
+
 `--json` suppresses the human layout; the exit code is unchanged.
 
 ## Share (`tested push`)
@@ -173,7 +235,11 @@ $ tested push
 | `--owner` / `--name` | Repo identity (default: `GITHUB_REPOSITORY`, else `origin` remote) |
 | `--pr-title`, `--author`, `--base-ref`, `--head-ref` | PR metadata overrides |
 | `--base` | Git base for the coverage diff (same as `tested diff --base`) |
+| `--junit` / `TESTED_JUNIT` | JUnit XML for flakes / suite time (or auto-detect `junit.xml`, `test-results/junit.xml`, `coverage/junit.xml`) |
 | `--run-url` | Optional CI run URL |
+| `--file` | Coverage file to merge (repeatable) |
+| `--parts` / `--part` / `--complete` / `--incomplete` | Matrix shard handshake (`coverageMerge`) |
+| `--run-id` / `--shard` | Group shards for one CI run + SHA |
 | `--json` | Machine output: `{ "shareUrl", "expiresAt?" }` |
 
 ### `tested run` extra args
@@ -192,3 +258,18 @@ Typical CI step after `tested check`:
   env:
     TESTED_TOKEN: ${{ secrets.TESTED_TOKEN }}
 ```
+
+## Release
+
+Ship `@tested/cli` from a GitHub Release. `.github/workflows/release.yml` publishes to npm with [trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC). No `NPM_TOKEN`.
+
+1. Bump `version` in `package.json` on `main` and merge.
+2. From that commit: `gh release create vX.Y.Z --generate-notes` (tag must match `package.json`, e.g. `v0.1.9` → `0.1.9`).
+
+One-time npmjs.com setup (package settings → Trusted Publisher → GitHub Actions):
+
+- Organization: `tested-hq`
+- Repository: `cli`
+- Workflow filename: `release.yml`
+- Environment: (none)
+- Allowed action: `npm publish`