@appthrust/kest 0.2.0 → 0.3.1

package/ts/recording/index.ts

@@ -1,126 +1,92 @@
-interface BaseEvent<
-  Kind extends string,
-  Data extends Record<string, unknown> = Record<string, never>,
-> {
-  readonly kind: Kind;
-  readonly data: Data;
-}
-
 export type Event =
-  | ScenarioStartedEvent
-  | CommandRunEvent
-  | CommandResultEvent
-  | RetryEvent
+  | ScenarioEvent
   | ActionEvent
+  | CommandEvent
+  | RetryEvent
   | RevertingsEvent
   | BDDEvent;
 
-export type ScenarioStartedEvent = BaseEvent<
-  "ScenarioStarted",
-  {
-    readonly name: string;
-  }
->;
-
-export type RetryEvent =
-  | RetryStartEvent
-  | RetryAttemptEvent
-  | RetryFailureEvent
-  | RetryEndEvent;
+type ScenarioEvent =
+  | BaseEvent<
+      "ScenarioStart",
+      {
+        readonly name: string;
+      }
+    >
+  | BaseEvent<"ScenarioEnd", Record<string, never>>;
+
+type ActionEvent =
+  | BaseEvent<
+      "ActionStart",
+      {
+        readonly description: string;
+      }
+    >
+  | BaseEvent<
+      "ActionEnd",
+      {
+        readonly ok: boolean;
+        readonly error?: undefined | Error;
+      }
+    >;
+
+type CommandEvent =
+  | BaseEvent<
+      "CommandRun",
+      {
+        readonly cmd: string;
+        readonly args: ReadonlyArray<string>;
+        readonly stdin?: undefined | string;
+        readonly stdinLanguage?: undefined | string;
+      }
+    >
+  | BaseEvent<
+      "CommandResult",
+      {
+        readonly exitCode: number;
+        readonly stdout: string;
+        readonly stderr: string;
+        readonly stdoutLanguage?: undefined | string;
+        readonly stderrLanguage?: undefined | string;
+      }
+    >;
+
+type RetryEvent =
+  | BaseEvent<"RetryStart", Record<string, never>>
+  | BaseEvent<
+      "RetryEnd",
+      | {
+          readonly attempts: number;
+          readonly success: true;
+          readonly reason: "success";
+        }
+      | {
+          readonly attempts: number;
+          readonly success: false;
+          readonly reason: "timeout";
+          readonly error: Error;
+        }
+    >;
+
+type RevertingsEvent =
+  | BaseEvent<"RevertingsStart">
+  | BaseEvent<"RevertingsEnd">;
+
+type BDDEvent =
+  | BaseEvent<"BDDGiven", { readonly description: string }>
+  | BaseEvent<"BDDWhen", { readonly description: string }>
+  | BaseEvent<"BDDThen", { readonly description: string }>
+  | BaseEvent<"BDDAnd", { readonly description: string }>
+  | BaseEvent<"BDBut", { readonly description: string }>;
 
-export interface ErrorSummary {
-  readonly name?: undefined | string;
-  readonly message: string;
+interface BaseEvent<
+  Kind extends string,
+  Data extends Record<string, unknown> = Record<string, never>,
+> {
+  readonly kind: Kind;
+  readonly data: Data;
 }
 
-export type RetryStartEvent = BaseEvent<"RetryStart", Record<string, never>>;
-
-export type RetryAttemptEvent = BaseEvent<
-  "RetryAttempt",
-  {
-    readonly attempt: number;
-  }
->;
-
-export type RetryFailureEvent = BaseEvent<
-  "RetryFailure",
-  {
-    readonly attempt: number;
-    readonly error: ErrorSummary;
-  }
->;
-
-export type RetryEndEvent = BaseEvent<
-  "RetryEnd",
-  | {
-      readonly attempts: number;
-      readonly success: true;
-      readonly reason: "success";
-    }
-  | {
-      readonly attempts: number;
-      readonly success: false;
-      readonly reason: "timeout";
-      readonly error: ErrorSummary;
-    }
->;
-
-export type CommandRunEvent = BaseEvent<
-  "CommandRun",
-  {
-    readonly cmd: string;
-    readonly args: ReadonlyArray<string>;
-    readonly stdin?: undefined | string;
-    readonly stdinLanguage?: undefined | string;
-  }
->;
-
-export type CommandResultEvent = BaseEvent<
-  "CommandResult",
-  {
-    readonly exitCode: number;
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly stdoutLanguage?: undefined | string;
-    readonly stderrLanguage?: undefined | string;
-  }
->;
-
-export type ActionEvent = ActionStartEvent | ActionEndEvent;
-
-export type ActionPhase = "mutate" | "revert" | "query";
-
-export type ActionStartEvent = BaseEvent<
-  "ActionStart",
-  {
-    readonly action: string; // e.g. "CreateNamespaceAction"
-    readonly phase: ActionPhase;
-    readonly input?: undefined | Readonly<Record<string, unknown>>;
-  }
->;
-
-export type ActionEndEvent = BaseEvent<
-  "ActionEnd",
-  {
-    readonly action: string; // e.g. "CreateNamespaceAction"
-    readonly phase: ActionPhase;
-    readonly ok: boolean;
-    readonly error?: undefined | ErrorSummary;
-    readonly output?: undefined | Readonly<Record<string, unknown>>;
-  }
->;
-
-export type RevertingsEvent = RevertingsStartEvent | RevertingsEndEvent;
-export type RevertingsStartEvent = BaseEvent<"RevertingsStart">;
-export type RevertingsEndEvent = BaseEvent<"RevertingsEnd">;
-
-export type BDDEvent = BaseEvent<
-  "BDDGiven" | "BDDWhen" | "BDDThen" | "BDDAnd" | "BDBut",
-  {
-    readonly description: string;
-  }
->;
-
 export class Recorder {
   private readonly events: Array<Event> = [];
 

package/ts/reporter/markdown/index.ts

@@ -0,0 +1,23 @@
+import type { Event } from "../../recording";
+import type { Reporter } from "../interface";
+import { parseEvents } from "./parser";
+import { renderReport } from "./renderer";
+
+export interface MarkdownReporterOptions {
+  /**
+   * If true, keep ANSI escape codes (colors) in error messages.
+   * If false (default), remove ANSI escape codes.
+   */
+  enableANSI?: undefined | boolean;
+}
+
+export function newMarkdownReporter(
+  options: MarkdownReporterOptions = {}
+): Reporter {
+  return {
+    report(events: ReadonlyArray<Event>): Promise<string> {
+      const report = parseEvents(events);
+      return renderReport(report, options);
+    },
+  };
+}

package/ts/reporter/markdown/model.ts

@@ -0,0 +1,63 @@
+export interface Report {
+  scenarios: Array<Scenario>;
+}
+
+export interface Scenario {
+  name: string;
+  overview: Array<OverviewItem>;
+  details: Array<Tagged<"BDDSection", BDDSection> | Tagged<"Action", Action>>;
+  cleanup: Array<CleanupItem>;
+}
+
+type Tagged<Tag extends string, Target extends object> = Target & {
+  readonly type: Tag;
+};
+
+export interface OverviewItem {
+  name: string;
+  status: "pending" | "success" | "failure";
+}
+
+export interface BDDSection {
+  keyword: "given" | "when" | "then" | "and" | "but";
+  description: string;
+  actions: Array<Action>;
+}
+
+export interface Action {
+  name: string;
+  attempts?: undefined | number;
+  command?: undefined | Command;
+  error?: undefined | Error;
+}
+
+export interface Command {
+  cmd: string;
+  args: Array<string>;
+  stdin?: Text;
+  stdout?: Text;
+  stderr?: Text;
+}
+
+export interface Text {
+  text: string;
+  language?: undefined | string;
+}
+
+export interface Error {
+  message: Text;
+  stack?: undefined | string;
+}
+
+export interface CleanupItem {
+  action: string;
+  resource?: undefined | string;
+  status: "success" | "failure";
+  command: CleanupCommand;
+}
+
+export interface CleanupCommand {
+  cmd: string;
+  args: Array<string>;
+  output: string;
+}

package/ts/reporter/markdown/parser/index.ts

@@ -0,0 +1,361 @@
+import type { Event } from "../../../recording";
+import type {
+  Action,
+  BDDSection,
+  CleanupItem,
+  Command,
+  Report,
+  Scenario,
+} from "../model";
+
+const bddKeywordByKind = {
+  BDDGiven: "given",
+  BDDWhen: "when",
+  BDDThen: "then",
+  BDDAnd: "and",
+  BDBut: "but",
+} as const;
+
+type BDDEvent = Extract<
+  Event,
+  { kind: "BDDGiven" | "BDDWhen" | "BDDThen" | "BDDAnd" | "BDBut" }
+>;
+
+interface ParseState {
+  report: Report;
+  currentScenario: Scenario | undefined;
+  currentBDDSection: BDDSection | undefined;
+  inCleanup: boolean;
+  currentAction: Action | undefined;
+  currentOverviewIndex: number | undefined;
+  currentCleanup: CleanupItem | undefined;
+}
+
+export function parseEvents(events: ReadonlyArray<Event>): Report {
+  const state: ParseState = {
+    report: { scenarios: [] },
+    currentScenario: undefined,
+    currentBDDSection: undefined,
+    inCleanup: false,
+    currentAction: undefined,
+    currentOverviewIndex: undefined,
+    currentCleanup: undefined,
+  };
+
+  for (const event of events) {
+    const bdd = bddFromEvent(event);
+    if (bdd) {
+      handleBDDEvent(state, bdd);
+      continue;
+    }
+    handleNonBDDEvent(state, event);
+  }
+
+  return state.report;
+}
+
+function handleNonBDDEvent(state: ParseState, event: Event): void {
+  if (event.kind.startsWith("BDD")) {
+    return;
+  }
+
+  switch (event.kind) {
+    case "ScenarioStart":
+      handleScenarioStart(state, event);
+      return;
+    case "ScenarioEnd":
+      clearScenarioProgressState(state);
+      return;
+    case "RevertingsStart":
+      state.inCleanup = true;
+      clearCurrentActionState(state);
+      return;
+    case "RevertingsEnd":
+      state.inCleanup = false;
+      clearCurrentActionState(state);
+      return;
+    case "ActionStart":
+      handleActionStart(state, event);
+      return;
+    case "ActionEnd":
+      handleActionEnd(state, event);
+      return;
+    case "CommandRun":
+      handleCommandRun(state, event);
+      return;
+    case "CommandResult":
+      handleCommandResult(state, event);
+      return;
+    case "RetryEnd":
+      handleRetryEnd(state, event);
+      return;
+    case "RetryStart":
+      return;
+    default:
+      return;
+  }
+}
+
+function handleActionStart(
+  state: ParseState,
+  event: Extract<Event, { kind: "ActionStart" }>
+): void {
+  const scenario = ensureScenario(state.currentScenario, state.report);
+  if (state.inCleanup) {
+    const cleanup: CleanupItem = {
+      action: event.data.description,
+      status: "success",
+      command: { cmd: "", args: [], output: "" },
+    };
+    scenario.cleanup.push(cleanup);
+    state.currentCleanup = cleanup;
+    state.currentAction = undefined;
+    state.currentOverviewIndex = undefined;
+    return;
+  }
+
+  const action: Action = { name: event.data.description };
+  scenario.overview.push({
+    name: event.data.description,
+    status: "pending",
+  });
+  state.currentOverviewIndex = scenario.overview.length - 1;
+
+  if (state.currentBDDSection) {
+    state.currentAction = action;
+    state.currentBDDSection.actions.push(action);
+    return;
+  }
+
+  // NOTE: keep a shared reference between `state.currentAction` and `details`
+  // so that subsequent Command*/Retry*/ActionEnd events update what is shown in
+  // the scenario details even when the action is outside a BDD section.
+  const taggedAction = { type: "Action" as const, ...action };
+  scenario.details.push(taggedAction);
+  state.currentAction = taggedAction;
+}
+
+function applyRegularActionEnd(
+  state: ParseState,
+  event: Extract<Event, { kind: "ActionEnd" }>
+): void {
+  const { currentScenario, currentAction } = state;
+  if (!currentScenario) {
+    return;
+  }
+  if (!currentAction) {
+    return;
+  }
+
+  if (state.currentOverviewIndex !== undefined) {
+    const overviewItem = currentScenario.overview[state.currentOverviewIndex];
+    if (overviewItem) {
+      overviewItem.status = event.data.ok ? "success" : "failure";
+    }
+  }
+
+  if (!event.data.ok && event.data.error) {
+    currentAction.error = {
+      message: {
+        text: event.data.error.message,
+        language: isDiffLike(event.data.error.message) ? "diff" : "text",
+      },
+    };
+  }
+
+  state.currentAction = undefined;
+  state.currentOverviewIndex = undefined;
+}
+
+function handleCommandResult(
+  state: ParseState,
+  event: Extract<Event, { kind: "CommandResult" }>
+): void {
+  if (state.inCleanup) {
+    if (state.currentCleanup) {
+      state.currentCleanup.command.output =
+        event.data.stdout.length > 0 ? event.data.stdout : event.data.stderr;
+    }
+    return;
+  }
+
+  const { currentAction } = state;
+  if (!currentAction?.command) {
+    return;
+  }
+
+  currentAction.command.stdout = {
+    text: event.data.stdout,
+    ...(event.data.stdoutLanguage
+      ? { language: event.data.stdoutLanguage }
+      : {}),
+  };
+  currentAction.command.stderr = {
+    text: event.data.stderr,
+    ...(event.data.stderrLanguage
+      ? { language: event.data.stderrLanguage }
+      : {}),
+  };
+}
+
+function handleCommandRun(
+  state: ParseState,
+  event: Extract<Event, { kind: "CommandRun" }>
+): void {
+  if (state.inCleanup) {
+    if (state.currentCleanup) {
+      state.currentCleanup.command = {
+        cmd: event.data.cmd,
+        args: [...event.data.args],
+        output: "",
+      };
+    }
+    return;
+  }
+
+  if (!state.currentAction) {
+    return;
+  }
+  state.currentAction.command = createCommandFromRun(event);
+}
+
+function handleScenarioStart(
+  state: ParseState,
+  event: Extract<Event, { kind: "ScenarioStart" }>
+): void {
+  state.currentScenario = {
+    name: event.data.name,
+    overview: [],
+    details: [],
+    cleanup: [],
+  };
+  state.report.scenarios.push(state.currentScenario);
+  clearScenarioProgressState(state);
+}
+
+function handleActionEnd(
+  state: ParseState,
+  event: Extract<Event, { kind: "ActionEnd" }>
+): void {
+  if (handleCleanupActionEnd(state, event)) {
+    return;
+  }
+
+  applyRegularActionEnd(state, event);
+}
+
+function handleCleanupActionEnd(
+  state: ParseState,
+  event: Extract<Event, { kind: "ActionEnd" }>
+): boolean {
+  if (!state.inCleanup) {
+    return false;
+  }
+
+  if (state.currentCleanup) {
+    state.currentCleanup.status = event.data.ok ? "success" : "failure";
+  }
+  state.currentCleanup = undefined;
+  return true;
+}
+
+function handleRetryEnd(
+  state: ParseState,
+  event: Extract<Event, { kind: "RetryEnd" }>
+): void {
+  if (state.inCleanup) {
+    return;
+  }
+  if (!state.currentAction) {
+    return;
+  }
+  state.currentAction.attempts = event.data.attempts;
+}
+
+function handleBDDEvent(state: ParseState, bdd: BDDSection): void {
+  const scenario = ensureScenario(state.currentScenario, state.report);
+  scenario.details.push({
+    type: "BDDSection",
+    ...bdd,
+  });
+  state.currentScenario = scenario;
+  state.currentBDDSection = bdd;
+}
+
+function createCommandFromRun(
+  run: Extract<Event, { kind: "CommandRun" }>
+): Command {
+  return {
+    cmd: run.data.cmd,
+    args: [...run.data.args],
+    ...(typeof run.data.stdin === "string"
+      ? {
+          stdin: {
+            text: run.data.stdin,
+            ...(run.data.stdinLanguage
+              ? { language: run.data.stdinLanguage }
+              : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+function ensureScenario(
+  scenario: Scenario | undefined,
+  report: Report
+): Scenario {
+  if (scenario) {
+    return scenario;
+  }
+  const created: Scenario = {
+    name: "Scenario",
+    overview: [],
+    details: [],
+    cleanup: [],
+  };
+  report.scenarios.push(created);
+  return created;
+}
+
+function clearScenarioProgressState(state: ParseState): void {
+  state.currentBDDSection = undefined;
+  state.inCleanup = false;
+  clearCurrentActionState(state);
+}
+
+function clearCurrentActionState(state: ParseState): void {
+  state.currentAction = undefined;
+  state.currentOverviewIndex = undefined;
+  state.currentCleanup = undefined;
+}
+
+function bddFromEvent(event: Event): BDDSection | undefined {
+  if (!isBDDEvent(event)) {
+    return undefined;
+  }
+  const keyword = bddKeywordByKind[event.kind];
+  return { keyword, description: event.data.description, actions: [] };
+}
+
+function isDiffLike(message: string): boolean {
+  const lines = message.split(/\r?\n/);
+  let sawPlus = false;
+  let sawMinus = false;
+  for (const line of lines) {
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      sawPlus = true;
+    }
+    if (line.startsWith("-") && !line.startsWith("---")) {
+      sawMinus = true;
+    }
+    if (sawPlus && sawMinus) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isBDDEvent(event: Event): event is BDDEvent {
+  return event.kind in bddKeywordByKind;
+}