@plune-ai/cli 0.15.0 → 0.17.0

package/dist/reporter-core.d.cts

@@ -50,11 +50,17 @@ interface Attachment {
     url: string;
     contentType?: string;
 }
-/** A file the runner kept for an attempt, where it lies on this machine. */
+/**
+ * A file the runner kept for an attempt: where it lies on this machine, or — for a text a test attached as
+ * a `body`, which leaves no file — the bytes themselves. Playwright gives one of the two; were both here,
+ * the bytes are what is sent.
+ */
 interface ResultFile {
     name: string;
     contentType?: string;
-    path: string;
+    path?: string;
+    /** Only a JSON or a plain text — the types the platform keeps as a text; see `filesOf`. */
+    body?: Buffer;
 }
 /** One assertion's outcome, in the shape the platform already stores for its own runner. */
 interface AssertionRecord {
@@ -117,7 +123,8 @@ interface PendingResult {
     /**
      * The files the runner kept for this attempt, passed or not — built by `filesOf`. Never part of a
      * batch: the paths are this machine's. Once the platform has accepted the result, the core uploads
-     * the screenshots among them to it (platform ADR 0040).
+     * the screenshots and the text files among them to it (platform ADR 0040) — never a body to the
+     * fallback file either, which keeps a file by its path and leaves the bytes out.
      */
     files?: ResultFile[];
 }
@@ -137,8 +144,8 @@ interface FailureDetail {
         line: number;
         column?: number;
     };
-    /** The files the runner kept for the attempt, by name. The screenshots among them are uploaded to the
-     * result besides (`files`); the rest stay in the CI run. */
+    /** The files the runner kept for the attempt, by name. The screenshots and text files among them are
+     * uploaded to the result besides (`files`); the rest stay in the CI run. */
     artifacts?: {
         name: string;
         contentType?: string;
@@ -177,11 +184,13 @@ interface FailedAttempt {
     errors: AttemptError[];
     /** The declared steps, outermost first — as the JSON report keeps them. */
     steps: DeclaredStep[];
-    /** What the runner kept; `path` is what makes one a file. */
+    /** What the runner kept; `path` is what makes one a file, and a `body` — the bytes of a test's own
+     * attachment — is one to the platform only as a text. */
     attachments: {
         name: string;
         contentType?: string;
         path?: string;
+        body?: Buffer;
     }[];
     /** `metadata.ci.buildHref` of the run — the CI run that produced the report. */
     buildHref?: string;
@@ -200,6 +209,12 @@ interface ExpectedEntry {
     testCaseId?: string;
     externalKey?: KeyRef;
 }
+/**
+ * Why the platform would not take the tests offered to it (plune-ai/cli#71): its review queue is at its
+ * ceiling, the project is at its case limit, or anything else — a throttle, an outage, a run that is not
+ * there. What a person does next depends on which, and only the first two have advice of their own.
+ */
+type UnofferedWhy = 'queue' | 'cases' | 'other';
 /** The run as the platform answers with it. Only `id` is load-bearing for the client. */
 interface RunRecord {
     id: string;
@@ -240,6 +255,12 @@ interface RunStats extends SubmitCounts {
      * queue at capacity means "empty it and import again"; nothing else here means that.
      */
     unoffered: number;
+    /**
+     * Why they were not, said by the platform's own words and present only when `unoffered` is not zero:
+     * that is what carries the reason the paragraph above says a subtraction cannot. The platform's line
+     * about it is printed with the failure; this is what a command turns into the advice that fits.
+     */
+    unofferedWhy?: UnofferedWhy;
     /**
      * Results not delivered, written to the fallback file instead of the platform (#790): a batch
      * refused for any reason — its size, the network, the token, a closed run — or a result whose keys
@@ -256,6 +277,16 @@ interface RunStats extends SubmitCounts {
         skipped: number;
         failed: number;
     };
+    /**
+     * The same for the JSON and plain-text files of the accepted results (plune-ai/plune#928): counted
+     * apart from the screenshots because the two have limits of their own — 512 KiB and ten a result against
+     * 2 MB and twenty — and a person reading "3 skipped" has to know which kind it was.
+     */
+    textFiles: {
+        uploaded: number;
+        skipped: number;
+        failed: number;
+    };
 }
 /** Everything the core needs to talk to a deployment. */
 interface ReporterConfig {
@@ -375,6 +406,20 @@ interface EnvSettings {
     ignored: string[];
 }
 declare function readEnv(env?: NodeJS.ProcessEnv): EnvSettings;
+/**
+ * The commit and the branch a run belongs to (plune-ai/plune#927), for `meta.sha` and `meta.branch`.
+ *
+ * `reported` is what the runner said about its CI — Playwright's `metadata.ci`, or the copy of it in
+ * its JSON report — and outranks the job's variables: it is a project's own word where the CI is one
+ * Playwright does not know, and it is where the tests ran when another job imports the report. So a
+ * report naming a commit other than this job's gets that commit and no branch of this job's: half of
+ * each would be a commit on a branch it is not on. Playwright gives no branch on GitHub at all, which
+ * is why the job's variables are read there.
+ *
+ * Each field is present only when something said it: outside a CI there is nothing to say, and nothing
+ * is guessed.
+ */
+declare function ciCommit(reported?: unknown, env?: NodeJS.ProcessEnv): Pick<RunMeta, 'sha' | 'branch'>;
 
 /**
  * What ends up in a deferred batch.
@@ -397,10 +442,21 @@ declare const DEFAULT_FALLBACK_PATH: string;
  *
  * `runId: null` is a real state, not a missing value — the platform was unreachable when the run
  * was supposed to be created, so these results have no run yet and replay has to make one.
+ *
+ * `meta` is where that run came from — the commit and branch, the CI run, the runner (plune-ai/plune#927).
+ * Recorded so the run replay makes is the run the reporter would have made; replay reads it and nothing
+ * else about the machine it runs on. A line written before the field existed has none.
+ *
+ * `session` marks the reporter session that wrote the line, made once by that session (plune-ai/cli#45).
+ * A run of 24 tests at a batch of 10 is three lines, and replay opens one run for the lines that share a
+ * marker rather than one for each. A line written before the field existed has none, and is one run's
+ * worth by itself — nothing in it says otherwise.
  */
 interface DeferredBatch {
     runId: string | null;
     externalKey: string | null;
+    session?: string;
+    meta?: RunMeta;
     results: DeferredResult[];
 }
 /**
@@ -442,6 +498,11 @@ declare function errorContextOf(attempt: FailedAttempt, home?: string): string;
  * The files the runner kept for one attempt, whatever its status: a screenshot of a test that passed
  * is how a person sees what it checked (plune-ai/plune#913). Which of them the platform takes, the
  * session decides as it uploads — once, for both roads.
+ *
+ * A file is what has a `path`. What a test attached as a `body` leaves none — Playwright hands the bytes
+ * over and keeps nothing — so a JSON or a text is kept with its bytes (plune-ai/plune#928), and nothing
+ * else is: an image, a trace or a page is not taken from memory, and a suite whose screenshots are
+ * bodies must not hold them all until a batch is sent.
  */
 declare function filesOf(attempt: FailedAttempt): ResultFile[];
 /**
@@ -496,4 +557,4 @@ interface PlatformClient {
 }
 declare function createClient(opts: ClientOptions): PlatformClient;
 
-export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, appendBatch, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };
+export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };

package/dist/reporter-core.d.ts

@@ -50,11 +50,17 @@ interface Attachment {
     url: string;
     contentType?: string;
 }
-/** A file the runner kept for an attempt, where it lies on this machine. */
+/**
+ * A file the runner kept for an attempt: where it lies on this machine, or — for a text a test attached as
+ * a `body`, which leaves no file — the bytes themselves. Playwright gives one of the two; were both here,
+ * the bytes are what is sent.
+ */
 interface ResultFile {
     name: string;
     contentType?: string;
-    path: string;
+    path?: string;
+    /** Only a JSON or a plain text — the types the platform keeps as a text; see `filesOf`. */
+    body?: Buffer;
 }
 /** One assertion's outcome, in the shape the platform already stores for its own runner. */
 interface AssertionRecord {
@@ -117,7 +123,8 @@ interface PendingResult {
     /**
      * The files the runner kept for this attempt, passed or not — built by `filesOf`. Never part of a
      * batch: the paths are this machine's. Once the platform has accepted the result, the core uploads
-     * the screenshots among them to it (platform ADR 0040).
+     * the screenshots and the text files among them to it (platform ADR 0040) — never a body to the
+     * fallback file either, which keeps a file by its path and leaves the bytes out.
      */
     files?: ResultFile[];
 }
@@ -137,8 +144,8 @@ interface FailureDetail {
         line: number;
         column?: number;
     };
-    /** The files the runner kept for the attempt, by name. The screenshots among them are uploaded to the
-     * result besides (`files`); the rest stay in the CI run. */
+    /** The files the runner kept for the attempt, by name. The screenshots and text files among them are
+     * uploaded to the result besides (`files`); the rest stay in the CI run. */
     artifacts?: {
         name: string;
         contentType?: string;
@@ -177,11 +184,13 @@ interface FailedAttempt {
     errors: AttemptError[];
     /** The declared steps, outermost first — as the JSON report keeps them. */
     steps: DeclaredStep[];
-    /** What the runner kept; `path` is what makes one a file. */
+    /** What the runner kept; `path` is what makes one a file, and a `body` — the bytes of a test's own
+     * attachment — is one to the platform only as a text. */
     attachments: {
         name: string;
         contentType?: string;
         path?: string;
+        body?: Buffer;
     }[];
     /** `metadata.ci.buildHref` of the run — the CI run that produced the report. */
     buildHref?: string;
@@ -200,6 +209,12 @@ interface ExpectedEntry {
     testCaseId?: string;
     externalKey?: KeyRef;
 }
+/**
+ * Why the platform would not take the tests offered to it (plune-ai/cli#71): its review queue is at its
+ * ceiling, the project is at its case limit, or anything else — a throttle, an outage, a run that is not
+ * there. What a person does next depends on which, and only the first two have advice of their own.
+ */
+type UnofferedWhy = 'queue' | 'cases' | 'other';
 /** The run as the platform answers with it. Only `id` is load-bearing for the client. */
 interface RunRecord {
     id: string;
@@ -240,6 +255,12 @@ interface RunStats extends SubmitCounts {
      * queue at capacity means "empty it and import again"; nothing else here means that.
      */
     unoffered: number;
+    /**
+     * Why they were not, said by the platform's own words and present only when `unoffered` is not zero:
+     * that is what carries the reason the paragraph above says a subtraction cannot. The platform's line
+     * about it is printed with the failure; this is what a command turns into the advice that fits.
+     */
+    unofferedWhy?: UnofferedWhy;
     /**
      * Results not delivered, written to the fallback file instead of the platform (#790): a batch
      * refused for any reason — its size, the network, the token, a closed run — or a result whose keys
@@ -256,6 +277,16 @@ interface RunStats extends SubmitCounts {
         skipped: number;
         failed: number;
     };
+    /**
+     * The same for the JSON and plain-text files of the accepted results (plune-ai/plune#928): counted
+     * apart from the screenshots because the two have limits of their own — 512 KiB and ten a result against
+     * 2 MB and twenty — and a person reading "3 skipped" has to know which kind it was.
+     */
+    textFiles: {
+        uploaded: number;
+        skipped: number;
+        failed: number;
+    };
 }
 /** Everything the core needs to talk to a deployment. */
 interface ReporterConfig {
@@ -375,6 +406,20 @@ interface EnvSettings {
     ignored: string[];
 }
 declare function readEnv(env?: NodeJS.ProcessEnv): EnvSettings;
+/**
+ * The commit and the branch a run belongs to (plune-ai/plune#927), for `meta.sha` and `meta.branch`.
+ *
+ * `reported` is what the runner said about its CI — Playwright's `metadata.ci`, or the copy of it in
+ * its JSON report — and outranks the job's variables: it is a project's own word where the CI is one
+ * Playwright does not know, and it is where the tests ran when another job imports the report. So a
+ * report naming a commit other than this job's gets that commit and no branch of this job's: half of
+ * each would be a commit on a branch it is not on. Playwright gives no branch on GitHub at all, which
+ * is why the job's variables are read there.
+ *
+ * Each field is present only when something said it: outside a CI there is nothing to say, and nothing
+ * is guessed.
+ */
+declare function ciCommit(reported?: unknown, env?: NodeJS.ProcessEnv): Pick<RunMeta, 'sha' | 'branch'>;
 
 /**
  * What ends up in a deferred batch.
@@ -397,10 +442,21 @@ declare const DEFAULT_FALLBACK_PATH: string;
  *
  * `runId: null` is a real state, not a missing value — the platform was unreachable when the run
  * was supposed to be created, so these results have no run yet and replay has to make one.
+ *
+ * `meta` is where that run came from — the commit and branch, the CI run, the runner (plune-ai/plune#927).
+ * Recorded so the run replay makes is the run the reporter would have made; replay reads it and nothing
+ * else about the machine it runs on. A line written before the field existed has none.
+ *
+ * `session` marks the reporter session that wrote the line, made once by that session (plune-ai/cli#45).
+ * A run of 24 tests at a batch of 10 is three lines, and replay opens one run for the lines that share a
+ * marker rather than one for each. A line written before the field existed has none, and is one run's
+ * worth by itself — nothing in it says otherwise.
  */
 interface DeferredBatch {
     runId: string | null;
     externalKey: string | null;
+    session?: string;
+    meta?: RunMeta;
     results: DeferredResult[];
 }
 /**
@@ -442,6 +498,11 @@ declare function errorContextOf(attempt: FailedAttempt, home?: string): string;
  * The files the runner kept for one attempt, whatever its status: a screenshot of a test that passed
  * is how a person sees what it checked (plune-ai/plune#913). Which of them the platform takes, the
  * session decides as it uploads — once, for both roads.
+ *
+ * A file is what has a `path`. What a test attached as a `body` leaves none — Playwright hands the bytes
+ * over and keeps nothing — so a JSON or a text is kept with its bytes (plune-ai/plune#928), and nothing
+ * else is: an image, a trace or a page is not taken from memory, and a suite whose screenshots are
+ * bodies must not hold them all until a batch is sent.
  */
 declare function filesOf(attempt: FailedAttempt): ResultFile[];
 /**
@@ -496,4 +557,4 @@ interface PlatformClient {
 }
 declare function createClient(opts: ClientOptions): PlatformClient;
 
-export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, appendBatch, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };
+export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };