@dragonshorn-studios/elyseum-cli 1.0.12 → 1.1.0

package/README.md

@@ -1,84 +1,172 @@
-# Elyseum CLI
+<div align="center">
+  <img src=".github/logo.svg" alt="Elyseum — CI quality ledger" width="720">
+</div>
 
-> **Notice:** This is a work-in-progress personal package. Use at your own risk.
+# Elyseum CLI
 
-Elyseum CLI is a command-line tool for coverage reporting. It provides various reporters to display coverage information in different formats.
+The producer half of the Elyseum suite: a command-line coverage engine —
+total & diff coverage from LCOV reports, terminal and PR reporters, quality
+gates — plus adapters that turn JUnit, Clover, Go, and LCOV reports into the
+versioned result envelope the
+[Elyseum](https://github.com/Dragonshorn-Studios/elyseum) host stores. Run it
+directly or through the
+[elyseum-coverage-reporter-action](https://github.com/Dragonshorn-Studios/elyseum-coverage-reporter-action).
 
 ## Installation
 
-You can install the package globally using npm:
+The canonical npm package is `@dragonshorn-studios/elyseum-cli`:
 
 ```bash
-npm install -g @dragonshorn/elyseum-cli
+npm install -g @dragonshorn-studios/elyseum-cli
 ```
 
-## Usage
+Requires Node >= 20.
 
-### Commands
+## Commands
 
-- `diff-coverage`: Calculate coverage for changed files.
-- `coverage`: Calculate coverage for all files.
+### `diff-coverage`
 
-### Options
+Computes coverage for changed lines between two refs (or an explicit changed-file list) and reports it.
 
-- `--reporter.coverage`: Coverage reporter(s), separated by commas. Available reporters: `cli-table`, `github-pr-comment`.
-- `--reporter.coverage.colors`: Use colors in coverage reporter (if supported).
-- `--reporter.coverage.details`: Show coverage details.
-- `--reporter.coverage.quality-gate`: Coverage quality gate.
+| Option | Default | Description |
+| --- | --- | --- |
+| `--diff-coverage.base` | `origin/main` (or `origin/$GITHUB_BASE_REF`) | Base branch/SHA |
+| `--diff-coverage.head` | `HEAD` (or `$GITHUB_SHA`) | Head branch/SHA |
+| `--diff-coverage.dynamic` | | Set to `gh` to resolve the base SHA from the GitHub pull request |
+| `--diff-coverage.changed-files` | | Comma-separated file list; skips git entirely |
+| `--diff-coverage.lcov-path` | `coverage/lcov.info` | LCOV report location |
 
-### Examples
+### `coverage`
 
-#### Calculate Coverage for Changed Files
+Aggregated coverage over the whole report.
 
-```bash
-elyseum-cli diff-coverage --head <HEAD_COMMIT> --base <BASE_COMMIT>
-```
+| Option | Default | Description |
+| --- | --- | --- |
+| `--coverage.lcov-path` | `coverage/lcov.info` | LCOV report location |
 
-#### Calculate Coverage for All Files
+### Reporters
 
-```bash
-elyseum-cli coverage
-```
+- `--reporter.coverage cli-table,markdown-table,github-pr-comment` (comma separated)
+- `--reporter.coverage.details` — per-file breakdown
+- `--reporter.coverage.quality-gate <n>` — changed-line coverage below `n` warns
+- `--reporter.coverage.quality-gate-fail <n>` — coverage at or below `n` fails the command (exit 1)
 
-#### Use Multiple Reporters
+## Configuration (`.elyseum.yml`)
 
-```bash
-elyseum-cli diff-coverage --reporter.coverage=cli-table,github-pr-comment
-```
+Precedence: CLI arguments (when explicitly given) beat the environment
+block, which beats the default block. Keys use the same names as the CLI
+options (nested with dots flattened):
 
-#### Use Colors in Coverage Reporter
+```yaml
+default-environment: auto
 
-```bash
-elyseum-cli diff-coverage --reporter.coverage.colors
+config:
+  coverage:
+    lcov-path: coverage/lcov.info
+  diff-coverage:
+    base: origin/main
+
+environments:
+  github:
+    reporter:
+      coverage:
+        quality-gate: 80
+        quality-gate-fail: 50
+  local: {}
 ```
 
-#### Show Coverage Details
+Validation lists every schema violation and exits with code 2. Note that a
+changed-file list given without a diff counts **every** coverable line of
+the listed file as changed — gates are therefore stricter in that mode.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | A configured quality gate failed |
+| 2 | Invalid configuration |
+| 3 | No git repository found (and no explicit changed-file list) |
+| 4 | LCOV report not found |
+| 5 | Any other calculation or runtime error |
+
+## Input adapters (`emit-envelope`)
+
+Adapters translate tool-specific reports into the versioned v1 envelope
+(pinned from the host: `schemas/envelope.v1.json`). Format selection is
+explicit — no auto-detection.
+
+| Option | Values | Reads |
+| --- | --- | --- |
+| `--emit-envelope.tests-format` | `vitest-json` \| `junit` \| `go-test-json` | test report |
+| `--emit-envelope.tests-input` | path or `-` (stdin) | test report |
+| `--emit-envelope.coverage-format` | `lcov` \| `clover` \| `go-coverprofile` | coverage report |
+| `--emit-envelope.coverage-input` | path or `-` (stdin) | coverage report |
+
+Example (Vitest + LCOV, i.e. Maomao):
 
 ```bash
-elyseum-cli diff-coverage --reporter.coverage.details
+elyseum-cli emit-envelope \
+  --emit-envelope.tests-format vitest-json \
+  --emit-envelope.tests-input tests/vitest.json \
+  --emit-envelope.coverage-format lcov \
+  --emit-envelope.coverage-input coverage/lcov.info \
+  --emit-envelope.out envelope.json
 ```
 
-#### Set Coverage Quality Gate
+Marller (Go): `--emit-envelope.tests-format go-test-json` with
+`go test -json ./...` output, and `--emit-envelope.coverage-format
+go-coverprofile` with `go test -coverprofile`. Laravel:
+`--emit-envelope.tests-format junit` with `--log-junit` output and
+`--emit-envelope.coverage-format clover` with `--coverage-clover`.
+
+Semantics:
+
+- Missing metrics are `null`/unknown, never zero (Go coverage provides no
+  function/branch data — those stay null).
+- Coverage absence does not invalidate test facts: with no coverage input,
+  the `coverage` section is omitted.
+- Failed tests (500), coverage files (2000), names (512), failure messages
+  (2048 chars) and coverage paths (1024 chars) are bounded before
+  serialization.
+- XML is parsed without external entity or DTD resolution; input is never
+  executed.
+- Malformed or truncated input fails with exit code 5 and an actionable
+  diagnostic.
+- Provenance (formats, CLI version) is recorded in the envelope's
+  `provenance` field.
+
+## Behavior notes
+
+- Percentages are always finite: a metric with zero eligible items (zero
+  changed lines, zero coverable lines, zero branches) reports 100%, never NaN.
+- Only added lines (`+`) count as changed; removed lines, context lines, and
+  comment-only/blank additions are excluded.
+- File paths are compared with leading slashes stripped.
+- Supported Node versions: >= 20 (CI tests Node 20 and 22).
+
+## Development
 
 ```bash
-elyseum-cli diff-coverage --reporter.coverage.quality-gate=80
+npm install
+npm run build     # rollup bundle into dist/
+npm test          # vitest unit + integration suites
+npm run pack:smoke  # npm pack + run the packed binary
+npm run ci        # build + test + pack smoke
 ```
 
-## Configuration
-
-You can also configure the CLI using a `.elyseum.yml` file. Here is an example configuration:
+Integration tests run the built CLI against a real fixture git repository and
+LCOV files; the pack smoke test verifies the published tarball contains the
+executable with its shebang.
 
-```yaml
-reporter:
-  coverage:
-    cli-table:
-      color: true
-      diff: true
-    github-pr-comment:
-      file: "github.pr.coverage.md"
-qualityGate: 80
-```
+## Repository roles
 
-## License
+| Repository | Role |
+| --- | --- |
+| [elyseum] | Host: users/projects/authz, ingest API, CI history UI. Source of truth for the versioned CI result envelope. |
+| [elyseum-cli] (this repo) | Producer CLI: reads local CI artifacts and emits the versioned envelope. |
+| [elyseum-coverage-reporter-action] | Thin GitHub Action wrapping this CLI; optional upload to Elyseum. |
 
-This project is licensed under the MIT License.
+[elyseum]: https://github.com/Dragonshorn-Studios/elyseum
+[elyseum-cli]: https://github.com/Dragonshorn-Studios/elyseum-cli
+[elyseum-coverage-reporter-action]: https://github.com/Dragonshorn-Studios/elyseum-coverage-reporter-action

package/dist/adapters/clover.d.ts

@@ -0,0 +1,10 @@
+import { CoverageFacts } from "./types";
+/**
+ * Clover XML coverage adapter (PHP `--coverage-clover`).
+ *
+ * Mapping, kept honest to what Clover provides: statements → line
+ * coverage, methods → function coverage, conditionals → branch coverage.
+ * A file with zero statements reports 100% (nothing to cover), never NaN.
+ */
+export declare function parseCloverXml(raw: string): CoverageFacts;
+//# sourceMappingURL=clover.d.ts.map

package/dist/adapters/clover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clover.d.ts","sourceRoot":"","sources":["../../src/adapters/clover.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAkEzD"}

package/dist/adapters/go-coverprofile.d.ts

@@ -0,0 +1,15 @@
+import { CoverageFacts } from "./types";
+/**
+ * Go coverprofile adapter (`go test -coverprofile=c.out ./...`).
+ *
+ * Go reports per-block statement sets with a hit count of 0 or 1, which we
+ * aggregate honestly: block counts map to statement counts, and coverage
+ * percentages are covered blocks / total blocks per file. Go provides no
+ * function or branch coverage, so those stay null — never zero.
+ *
+ * A profile with a `mode:` header and no blocks is an empty profile: the
+ * result is zero files with null percentages (unknown), not fabricated
+ * coverage.
+ */
+export declare function parseGoCoverprofile(raw: string): CoverageFacts;
+//# sourceMappingURL=go-coverprofile.d.ts.map

package/dist/adapters/go-coverprofile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"go-coverprofile.d.ts","sourceRoot":"","sources":["../../src/adapters/go-coverprofile.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAmE9D"}

package/dist/adapters/go-test-json.d.ts

@@ -0,0 +1,15 @@
+import { TestFacts } from "./types";
+/**
+ * Go test JSON adapter (`go test -json ./...`): a newline-delimited stream
+ * of events.
+ *
+ * - Leaf tests (pass/fail/skip) each count once; subtests are their own
+ *   leaves. Duration sums only top-level tests (subtest Elapsed would
+ *   double count), so duration_ms is approximate.
+ * - A package-level failure (panic, setup) becomes one failed identity with
+ *   bounded captured output.
+ * - Build failures (Action build-fail / build-output) become one failed
+ *   identity per package with bounded build output.
+ */
+export declare function parseGoTestJson(raw: string): TestFacts;
+//# sourceMappingURL=go-test-json.d.ts.map

package/dist/adapters/go-test-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"go-test-json.d.ts","sourceRoot":"","sources":["../../src/adapters/go-test-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiD,SAAS,EAAE,MAAM,SAAS,CAAC;AAKnF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CA4HtD"}

package/dist/adapters/index.d.ts

@@ -0,0 +1,18 @@
+import { CoverageFacts, TestFacts } from "./types";
+import { parseGoCoverprofile } from "./go-coverprofile";
+import { parseCloverXml } from "./clover";
+import { parseGoTestJson } from "./go-test-json";
+import { parseJunitXml } from "./junit";
+import { parseVitestJson } from "./vitest-json";
+export * from "./types";
+/**
+ * Adapter registry (elyseum-cli#7). Explicit format selection only — there
+ * is no auto-detection. Adding an adapter means adding a parser, a format
+ * literal here, and fixtures; the envelope and commands do not change.
+ */
+export type TestsParser = (raw: string) => TestFacts;
+export type CoverageParser = (raw: string) => CoverageFacts | Promise<CoverageFacts>;
+export declare function testsParserFor(format: string): TestsParser;
+export declare function coverageParserFor(format: string): CoverageParser;
+export { parseGoCoverprofile, parseCloverXml, parseGoTestJson, parseJunitXml, parseVitestJson };
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,cAAc,SAAS,CAAC;AAExB;;;;GAIG;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;AACrD,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAoDrF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAQ1D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAQhE;AAED,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC"}

package/dist/adapters/junit.d.ts

@@ -0,0 +1,15 @@
+import { TestFacts } from "./types";
+/**
+ * JUnit XML adapter (Pest/PHPUnit `--log-junit`, and JUnit-compatible
+ * output from other runners).
+ *
+ * Semantics: a <failure> child → failed; an <error> child → failed (the
+ * distinction is preserved in the message text); a <skipped> child →
+ * skipped; otherwise passed. Counts come from the <testcase> elements
+ * themselves, so they stay consistent even when suite attributes disagree.
+ *
+ * XML is parsed with fast-xml-parser, which performs no external entity or
+ * DTD resolution — the input is untrusted by contract.
+ */
+export declare function parseJunitXml(raw: string): TestFacts;
+//# sourceMappingURL=junit.d.ts.map

package/dist/adapters/junit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"junit.d.ts","sourceRoot":"","sources":["../../src/adapters/junit.ts"],"names":[],"mappings":"AACA,OAAO,EAAiD,SAAS,EAAE,MAAM,SAAS,CAAC;AAGnF;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAiGpD"}

package/dist/adapters/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Provider-neutral adapter contract (elyseum-cli#7). Adapters translate
+ * tool-specific test/coverage outputs into normalized facts consumed by the
+ * v1 envelope writer. Parsing is separate from orchestration and upload;
+ * adapters never execute project commands and treat all input as untrusted.
+ *
+ * Normalization semantics (docs/design notes in README):
+ * - Missing metrics are null/unknown, never fabricated as zero.
+ * - Zero tests, missing coverage, and zero executable lines are separate
+ *   states.
+ * - Failed-test names/messages and coverage paths are bounded here, before
+ *   serialization, so the envelope can never exceed the v1 limits.
+ */
+export interface NormalizedFailedTest {
+    name: string;
+    message: string | null;
+    file: string | null;
+    line: number | null;
+}
+export interface TestFacts {
+    total: number;
+    passed: number | null;
+    failed: number | null;
+    skipped: number | null;
+    duration_ms: number | null;
+    failed_tests: NormalizedFailedTest[];
+}
+export interface CoverageFacts {
+    line_percent: number | null;
+    function_percent: number | null;
+    branch_percent: number | null;
+    files: {
+        path: string;
+        line_percent: number | null;
+        function_percent: number | null;
+        branch_percent: number | null;
+    }[];
+}
+/** Bounded provenance metadata (top-level envelope additive field). */
+export interface Provenance {
+    tests_format?: string;
+    coverage_format?: string;
+    tool_versions?: Record<string, string>;
+}
+export declare const BOUNDS: {
+    readonly failed_tests: 500;
+    readonly coverage_files: 2000;
+    readonly failed_test_name: 512;
+    readonly failed_test_message: 2048;
+    readonly failed_test_file: 512;
+    readonly coverage_path: 1024;
+    readonly provenance_value: 64;
+};
+export declare const TESTS_FORMATS: readonly ["vitest-json", "junit", "go-test-json"];
+export declare const COVERAGE_FORMATS: readonly ["lcov", "clover", "go-coverprofile"];
+export type TestsFormat = (typeof TESTS_FORMATS)[number];
+export type CoverageFormat = (typeof COVERAGE_FORMATS)[number];
+export declare function isTestsFormat(value: string): value is TestsFormat;
+export declare function isCoverageFormat(value: string): value is CoverageFormat;
+/** Bounds a failed-test name to the documented length. */
+export declare function boundName(name: string): string;
+/** Bounds a failure message to the documented length. */
+export declare function boundMessage(message: string | null): string | null;
+/** Bounds a file path to the documented length. */
+export declare function boundPath(path: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,EAAE,CAAC;CACL;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,eAAO,MAAM,MAAM;;;;;;;;CAQT,CAAC;AAEX,eAAO,MAAM,aAAa,mDAAoD,CAAC;AAC/E,eAAO,MAAM,gBAAgB,gDAAiD,CAAC;AAE/E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AACzD,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAEjE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAEvE;AAED,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAOlE;AAED,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI9C"}

package/dist/adapters/vitest-json.d.ts

@@ -0,0 +1,12 @@
+import { TestFacts } from "./types";
+/**
+ * Vitest JSON reporter adapter (also consumes Jest-compatible JSON:
+ * numTotalTests / testResults[].assertionResults[]).
+ *
+ * Status mapping: passed → passed; failed → failed; skipped, pending and
+ * todo → skipped (numTodoTests folds into the skipped count). Only failed
+ * tests carry identity details. Vitest JSON reports no total duration, so
+ * duration_ms is null.
+ */
+export declare function parseVitestJson(raw: string): TestFacts;
+//# sourceMappingURL=vitest-json.d.ts.map

package/dist/adapters/vitest-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest-json.d.ts","sourceRoot":"","sources":["../../src/adapters/vitest-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiD,SAAS,EAAE,MAAM,SAAS,CAAC;AAGnF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CA2CtD"}

package/dist/commands/command.d.ts

@@ -1,6 +1,6 @@
 import { CustomConfig } from "../config";
 export interface Command {
-    run(args: any): Promise<void>;
+    run(args: any): Promise<number>;
     config?: CustomConfig;
     name: string;
 }

package/dist/commands/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/commands/command.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAIzC,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,cAAc;IACzB,QAAQ,EAAE,UAAU,CAAM;;IAQ1B,UAAU,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,GAAG,SAAS;IAU1C,oBAAoB;IASpB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;CAiBjC"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/commands/command.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAIzC,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,cAAc;IACzB,QAAQ,EAAE,UAAU,CAAM;;IAS1B,UAAU,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,GAAG,SAAS;IAK1C,oBAAoB;IASpB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;CAiBjC"}

package/dist/commands/coverage-command.d.ts

@@ -1,9 +1,9 @@
 import { Command, CommandMap } from "./command";
+import { CustomConfig } from "../config";
 export declare class CoverageCommand implements Command {
     name: string;
+    config?: CustomConfig;
     constructor(commands: CommandMap);
-    run(args: any): Promise<void>;
-    private calculateCoverage;
-    private getCoverageReport;
+    run(args: any): Promise<number>;
 }
 //# sourceMappingURL=coverage-command.d.ts.map

package/dist/commands/coverage-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coverage-command.d.ts","sourceRoot":"","sources":["../../src/commands/coverage-command.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEhD,qBAAa,eAAgB,YAAW,OAAO;IAC7C,IAAI,EAAE,MAAM,CAAc;gBACd,QAAQ,EAAE,UAAU;IAInB,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;YAoB5B,iBAAiB;YA8DjB,iBAAiB;CAWhC"}
+{"version":3,"file":"coverage-command.d.ts","sourceRoot":"","sources":["../../src/commands/coverage-command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAChD,OAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAKjD,qBAAa,eAAgB,YAAW,OAAO;IAC7C,IAAI,EAAE,MAAM,CAAc;IAC1B,MAAM,CAAC,EAAE,YAAY,CAOnB;gBAEU,QAAQ,EAAE,UAAU;IAInB,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;CA0B7C"}

package/dist/commands/diff-coverage-command.d.ts

@@ -4,9 +4,9 @@ export declare class DiffCoverageCommand implements Command {
     name: string;
     config?: CustomConfig;
     constructor(commands: CommandMap);
-    run(args: any): Promise<void>;
-    private calculateDiffCoverage;
-    private getCoverageReport;
-    private getChangedFiles;
+    run(args: any): Promise<number>;
+    private numberOption;
+    private resolveBaseSha;
+    private baseShaFromGithub;
 }
 //# sourceMappingURL=diff-coverage-command.d.ts.map

package/dist/commands/diff-coverage-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff-coverage-command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-coverage-command.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAChD,OAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAMjD,qBAAa,mBAAoB,YAAW,OAAO;IACjD,IAAI,EAAE,MAAM,CAAmB;IAC/B,MAAM,CAAC,EAAE,YAAY,CA2BnB;gBACU,QAAQ,EAAE,UAAU;IAInB,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;YAqI5B,qBAAqB;YAuLrB,iBAAiB;YAajB,eAAe;CA4E9B"}
+{"version":3,"file":"diff-coverage-command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-coverage-command.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAChD,OAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAyBjD,qBAAa,mBAAoB,YAAW,OAAO;IACjD,IAAI,EAAE,MAAM,CAAmB;IAC/B,MAAM,CAAC,EAAE,YAAY,CAiCnB;gBAEU,QAAQ,EAAE,UAAU;IAInB,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IA8F5C,OAAO,CAAC,YAAY;YAKN,cAAc;YAkBd,iBAAiB;CAgChC"}

package/dist/commands/emit-envelope-command.d.ts

@@ -0,0 +1,43 @@
+import { Command, CommandMap } from "./command";
+import { CustomConfig } from "../config";
+/**
+ * Builds the versioned CI result envelope from the facts this CLI can
+ * observe (LCOV coverage, git commit, CI environment) and writes it to a
+ * file or stdout. The envelope is validated against the pinned v1 schema
+ * before it is written — an invalid envelope is a CLI bug, not a user
+ * error, so it fails loudly with exit code 5.
+ */
+export declare class EmitEnvelopeCommand implements Command {
+    name: string;
+    config?: CustomConfig;
+    constructor(commands: CommandMap);
+    run(args: any): Promise<number>;
+    /**
+     * Reads an emit-envelope option from the merged config (CLI flag beats
+     * .elyseum.yml, which beats the declared default). Null/empty means the
+     * option was not given.
+     */
+    private option;
+    private intOption;
+    /**
+     * Collects normalized test facts from an explicit --tests-format +
+     * --tests-input pair. Auto-detection is deliberately not offered: an
+     * ambiguous format is a contract violation, not a convenience.
+     */
+    /**
+     * Manual test facts from the --tests-* flags (used when no adapter input
+     * is given). All absent means no tests section at all.
+     */
+    private testsFromFlags;
+    private collectTestsFacts;
+    /**
+     * Collects coverage facts. With --coverage-format, the explicit adapter
+     * path applies; otherwise the default LCOV report is used (backwards
+     * compatible with the plain coverage/diff-coverage flows).
+     */
+    private collectCoverageFacts;
+    private readInput;
+    private cliVersion;
+    private r4;
+}
+//# sourceMappingURL=emit-envelope-command.d.ts.map

package/dist/commands/emit-envelope-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-envelope-command.d.ts","sourceRoot":"","sources":["../../src/commands/emit-envelope-command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAChD,OAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AA8BjD;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,OAAO;IACjD,IAAI,EAAE,MAAM,CAAmB;IAC/B,MAAM,CAAC,EAAE,YAAY,CAqFnB;gBAEU,QAAQ,EAAE,UAAU;IAInB,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAwL5C;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,SAAS;IAgBjB;;;;OAIG;IACH;;;OAGG;IACH,OAAO,CAAC,cAAc;YAkCR,iBAAiB;IA0B/B;;;;OAIG;YACW,oBAAoB;YAiDpB,SAAS;IAevB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,EAAE;CAGX"}

package/dist/config.d.ts

@@ -14,6 +14,7 @@ declare class Config {
     private config;
     private constructor();
     private isSet;
+    private isObject;
     static getInstance(args?: any): Config;
     get(key: string, defaultValue?: any): any;
     getFirst(keys: string[], defaultValue?: any, converter?: any): any;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,GAAG,CAAC;IACb,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC;CAC9B;AAED,cAAM,MAAM;IACV,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAS;IAChC,OAAO,CAAC,MAAM,CAAM;IAEpB,OAAO;IA6EP,OAAO,CAAC,KAAK;WAIC,WAAW,CAAC,IAAI,GAAE,GAAQ,GAAG,MAAM;IAO1C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,GAAU,GAAG,GAAG;IAa/C,QAAQ,CACb,IAAI,EAAE,MAAM,EAAE,EACd,YAAY,GAAE,GAAU,EACxB,SAAS,GAAE,GAAmB,GAC7B,GAAG;WAUQ,GAAG,CACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EACvB,YAAY,GAAE,GAAU,GACvB,GAAG;WAUQ,SAAS,IAAI,GAAG;WAIhB,eAAe,IAAI,MAAM,EAAE;CAa1C;AAED,eAAe,MAAM,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,GAAG,CAAC;IACb,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC;CAC9B;AAED,cAAM,MAAM;IACV,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAS;IAChC,OAAO,CAAC,MAAM,CAAM;IAEpB,OAAO;IA4FP,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,QAAQ;WAIF,WAAW,CAAC,IAAI,GAAE,GAAQ,GAAG,MAAM;IAO1C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,GAAU,GAAG,GAAG;IAa/C,QAAQ,CACb,IAAI,EAAE,MAAM,EAAE,EACd,YAAY,GAAE,GAAU,EACxB,SAAS,GAAE,GAAmB,GAC7B,GAAG;WAUQ,GAAG,CACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EACvB,YAAY,GAAE,GAAU,GACvB,GAAG;WAUQ,SAAS,IAAI,GAAG;WAIhB,eAAe,IAAI,MAAM,EAAE;CAmB1C;AAED,eAAe,MAAM,CAAC"}

package/dist/core/ci-env.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolves the CI run identity from well-known environment variables, with
+ * a documented generic-CI fallback:
+ *
+ * - GitHub Actions: provider "github", run_id from GITHUB_RUN_ID, job_id
+ *   from GITHUB_JOB (the job's key; matrix legs share it — pass
+ *   --emit-envelope.run-job-id to disambiguate), attempt from
+ *   GITHUB_RUN_ATTEMPT, url from the canonical run URL.
+ * - Any other CI / local runs: provider "generic", run_id = the git HEAD
+ *   SHA, job_id null, attempt 1. The idempotency key is then the commit —
+ *   a rerun of the same commit overwrites the same logical run.
+ */
+export interface RunIdentity {
+    provider: string;
+    run_id: string;
+    job_id: string | null;
+    attempt: number;
+    url: string | null;
+}
+export declare function resolveRunIdentity(env: NodeJS.ProcessEnv, headSha: string): RunIdentity;
+/** Commit facts from the git checkout. Requires a git repository. */
+export declare function resolveCommitFacts(dir: string, headRef: string): Promise<{
+    sha: string;
+    branch: string;
+    committed_at: string | null;
+}>;
+//# sourceMappingURL=ci-env.d.ts.map

package/dist/core/ci-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-env.d.ts","sourceRoot":"","sources":["../../src/core/ci-env.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAqBvF;AAED,qEAAqE;AACrE,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CA+BvE"}

package/dist/core/envelope.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The pinned copy of the canonical Elyseum v1 CI result envelope contract.
+ * The schema and fixtures are owned by the elyseum host repository and
+ * pinned here per the workspace pairing rule; `validateEnvelope` is the
+ * self-check every emitted envelope passes before it is written.
+ *
+ * Drift between this copy and the host's canonical file is a contract
+ * violation; the planned cross-repo contract checks (elyseum#14) will
+ * catch it in CI.
+ */
+export declare const SUPPORTED_SCHEMA_VERSION = "1";
+export interface EnvelopeV1 {
+    schema_version: "1";
+    producer: {
+        name: string;
+        version: string;
+    };
+    run: {
+        provider: string;
+        run_id: string;
+        job_id?: string | null;
+        attempt: number;
+        url?: string | null;
+        started_at?: string | null;
+        finished_at?: string | null;
+    };
+    commit: {
+        sha: string;
+        branch: string;
+        base_sha?: string | null;
+        committed_at?: string | null;
+    };
+    tests?: {
+        total?: number | null;
+        passed?: number | null;
+        failed?: number | null;
+        skipped?: number | null;
+        duration_ms?: number | null;
+        failed_tests?: {
+            name: string;
+            message?: string | null;
+            file?: string | null;
+            line?: number | null;
+        }[];
+    };
+    coverage?: {
+        line_percent?: number | null;
+        function_percent?: number | null;
+        branch_percent?: number | null;
+        diff_percent?: number | null;
+        files?: {
+            path: string;
+            line_percent?: number | null;
+            function_percent?: number | null;
+            branch_percent?: number | null;
+        }[];
+    };
+    quality_gate?: {
+        conclusion: "passed" | "failed" | "unknown";
+    };
+    [key: string]: unknown;
+}
+export interface EnvelopeIssue {
+    pointer: string;
+    message: string;
+}
+/** Validates an envelope against the pinned v1 schema. Pure. */
+export declare function validateEnvelope(envelope: EnvelopeV1): EnvelopeIssue[];
+//# sourceMappingURL=envelope.d.ts.map

package/dist/core/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/core/envelope.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAU5C,MAAM,WAAW,UAAU;IACzB,cAAc,EAAE,GAAG,CAAC;IACpB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,GAAG,EAAE;QACH,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;IACF,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B,CAAC;IACF,KAAK,CAAC,EAAE;QACN,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,YAAY,CAAC,EAAE;YACb,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YACxB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;SACtB,EAAE,CAAC;KACL,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,KAAK,CAAC,EAAE;YACN,IAAI,EAAE,MAAM,CAAC;YACb,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YAC7B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YACjC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;SAChC,EAAE,CAAC;KACL,CAAC;IACF,YAAY,CAAC,EAAE;QAAE,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;KAAE,CAAC;IAC/D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,GAAG,aAAa,EAAE,CAUtE"}