@appthrust/kest 0.3.0 → 0.3.1

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;
+}

package/ts/reporter/markdown/renderer/index.ts

@@ -0,0 +1,296 @@
+import { codeToANSIForcedColors } from "../../shiki";
+import type { MarkdownReporterOptions } from "../index";
+import type { Action, Report } from "../model";
+
+const markdownLang = "markdown";
+const markdownTheme = "catppuccin-mocha";
+
+type StdinReplacement = Readonly<{
+  placeholder: string;
+  stdin: string;
+  stdinLanguage: string;
+}>;
+
+function normalizeStdin(stdin: string): string {
+  // Match `ts/reporter/markdown.ts` behavior: keep content stable.
+  return stdin.replace(/^\n/, "").replace(/\s+$/, "");
+}
+
+function applyStdinReplacements(
+  highlightedMarkdown: string,
+  replacements: ReadonlyArray<StdinReplacement>
+): string {
+  if (replacements.length === 0) {
+    return highlightedMarkdown;
+  }
+
+  let current = highlightedMarkdown;
+  for (const r of replacements) {
+    const lines = current.split("\n");
+    const stdinLines = r.stdin.split("\n");
+    const out: Array<string> = [];
+    for (const line of lines) {
+      if (stripAnsi(line).includes(r.placeholder)) {
+        out.push(...stdinLines);
+      } else {
+        out.push(line);
+      }
+    }
+    current = out.join("\n");
+  }
+  return current;
+}
+
+async function highlightMarkdown(
+  markdown: string,
+  stdinReplacements: ReadonlyArray<StdinReplacement>
+): Promise<string> {
+  const stripped = stripAnsi(markdown);
+  try {
+    const highlightedMarkdown = await codeToANSIForcedColors(
+      stripped,
+      markdownLang,
+      markdownTheme
+    );
+
+    if (stdinReplacements.length === 0) {
+      // Keep output shape stable: always end with a single trailing newline.
+      return highlightedMarkdown.replace(/\n+$/, "\n");
+    }
+
+    const highlightedStdinList = await Promise.all(
+      stdinReplacements.map(async (r) => {
+        const highlightedStdin = await codeToANSIForcedColors(
+          r.stdin,
+          r.stdinLanguage,
+          markdownTheme
+        );
+        // Avoid inserting an extra blank line before `EOF`.
+        const trimmed = trimFinalNewline(
+          highlightedStdin.replace(/\n+$/, "\n")
+        );
+        return { ...r, stdin: trimmed } satisfies StdinReplacement;
+      })
+    );
+
+    const replaced = applyStdinReplacements(
+      highlightedMarkdown,
+      highlightedStdinList
+    );
+    return replaced.replace(/\n+$/, "\n");
+  } catch {
+    return stripped;
+  }
+}
+
+function stripAnsi(input: string): string {
+  // Prefer Bun's built-in ANSI stripper when available.
+  if (typeof Bun !== "undefined" && typeof Bun.stripANSI === "function") {
+    return Bun.stripANSI(input);
+  }
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intended
+  return input.replace(/\u001b\[[0-9;]*m/g, "");
+}
+
+function trimFinalNewline(input: string): string {
+  return input.replace(/\n$/, "");
+}
+
+function toBddHeading(keyword: string): string {
+  if (keyword.length === 0) {
+    return keyword;
+  }
+  return keyword.charAt(0).toUpperCase() + keyword.slice(1);
+}
+
+const statusEmojiByStatus = {
+  pending: "⏳",
+  success: "✅",
+  failure: "❌",
+} as const;
+
+function statusEmoji(status: keyof typeof statusEmojiByStatus): string {
+  return statusEmojiByStatus[status];
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: rendering is intentionally linear and explicit
+export function renderReport(
+  report: Report,
+  options: MarkdownReporterOptions
+): Promise<string> {
+  const enableANSI = options.enableANSI ?? false;
+
+  const renderedScenarios: Array<string> = [];
+  const stdinReplacements: Array<StdinReplacement> = [];
+  let stdinSeq = 0;
+
+  for (const scenario of report.scenarios) {
+    const isEmpty =
+      scenario.overview.length === 0 &&
+      scenario.details.length === 0 &&
+      scenario.cleanup.length === 0;
+    if (isEmpty) {
+      continue;
+    }
+
+    const overviewStatusByName = new Map<
+      string,
+      "pending" | "success" | "failure"
+    >(scenario.overview.map((o) => [o.name, o.status]));
+
+    const lines: Array<string> = [];
+
+    lines.push(`# ${stripAnsi(scenario.name)}`);
+    lines.push("");
+
+    // Overview
+    lines.push("## Scenario Overview");
+    lines.push("");
+    lines.push("| # | Action | Status |");
+    lines.push("|---|--------|--------|");
+    for (const [i, item] of scenario.overview.entries()) {
+      lines.push(
+        `| ${i + 1} | ${stripAnsi(item.name)} | ${statusEmoji(item.status)} |`
+      );
+    }
+    lines.push("");
+
+    // Details
+    lines.push("## Scenario Details");
+    lines.push("");
+
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: rendering is intentionally linear and explicit
+    const renderAction = (action: Action) => {
+      let status = overviewStatusByName.get(action.name);
+      if (!status) {
+        if (action.error) {
+          status = "failure";
+        } else if (action.command) {
+          status = "success";
+        } else {
+          status = "pending";
+        }
+      }
+      const emoji = statusEmoji(status);
+      const attemptsSuffix =
+        status === "failure" && typeof action.attempts === "number"
+          ? ` (Failed after ${action.attempts} attempts)`
+          : "";
+
+      lines.push(`**${emoji} ${stripAnsi(action.name)}**${attemptsSuffix}`);
+      lines.push("");
+
+      const cmd = action.command;
+      if (cmd) {
+        const base = [cmd.cmd, ...cmd.args].join(" ").trim();
+        const stdin = cmd.stdin?.text;
+        const stdinLanguage = cmd.stdin?.language ?? "text";
+
+        lines.push("```shell");
+        if (typeof stdin === "string") {
+          lines.push(`${base} <<EOF`);
+          if (enableANSI) {
+            const placeholder = `__KEST_STDIN_${stdinSeq++}__`;
+            stdinReplacements.push({
+              placeholder,
+              stdin: normalizeStdin(stripAnsi(stdin)),
+              stdinLanguage,
+            });
+            lines.push(placeholder);
+          } else {
+            lines.push(stripAnsi(stdin));
+          }
+          lines.push("EOF");
+        } else {
+          lines.push(base);
+        }
+        lines.push("```");
+        lines.push("");
+
+        const stdout = stripAnsi(cmd.stdout?.text ?? "");
+        if (stdout.trim().length > 0) {
+          const lang = cmd.stdout?.language ?? "text";
+          lines.push(`\`\`\`${lang} title="stdout"`);
+          lines.push(trimFinalNewline(stdout));
+          lines.push("```");
+          lines.push("");
+        }
+
+        const stderr = stripAnsi(cmd.stderr?.text ?? "");
+        if (stderr.trim().length > 0) {
+          const lang = cmd.stderr?.language ?? "text";
+          lines.push(`\`\`\`${lang} title="stderr"`);
+          lines.push(trimFinalNewline(stderr));
+          lines.push("```");
+          lines.push("");
+        }
+      }
+
+      if (status === "failure" && action.error?.message?.text) {
+        const messageText = stripAnsi(action.error.message.text);
+        const lang = action.error.message.language ?? "text";
+        lines.push("Error:");
+        lines.push("");
+        lines.push(`\`\`\`${lang}`);
+        lines.push(trimFinalNewline(messageText));
+        lines.push("```");
+        lines.push("");
+      }
+    };
+
+    for (const item of scenario.details) {
+      if (item.type === "BDDSection") {
+        lines.push(
+          `### ${toBddHeading(item.keyword)}: ${stripAnsi(item.description)}`
+        );
+        lines.push("");
+        for (const action of item.actions) {
+          renderAction(action);
+        }
+      }
+      if (item.type === "Action") {
+        renderAction(item);
+      }
+    }
+
+    // Cleanup
+    if (scenario.cleanup.length > 0) {
+      lines.push("### Cleanup");
+      lines.push("");
+      lines.push("| # | Action | Status |");
+      lines.push("|---|--------|--------|");
+      for (const [i, item] of scenario.cleanup.entries()) {
+        lines.push(
+          `| ${i + 1} | ${stripAnsi(item.action)} | ${item.status === "success" ? "✅" : "❌"} |`
+        );
+      }
+      lines.push("");
+
+      lines.push("```shellsession");
+      for (const [i, item] of scenario.cleanup.entries()) {
+        if (i > 0) {
+          lines.push("");
+        }
+        const base = [item.command.cmd, ...item.command.args].join(" ").trim();
+        lines.push(`$ ${stripAnsi(base)}`);
+        const output = stripAnsi(item.command.output);
+        if (output.trim().length > 0) {
+          lines.push(trimFinalNewline(output));
+        }
+      }
+      lines.push("```");
+    }
+
+    renderedScenarios.push(lines.join("\n"));
+  }
+
+  if (renderedScenarios.length === 0) {
+    return Promise.resolve("");
+  }
+  const rendered = renderedScenarios.join("\n\n");
+  const markdown = rendered.endsWith("\n") ? rendered : `${rendered}\n`;
+  if (!enableANSI) {
+    return Promise.resolve(markdown);
+  }
+  return highlightMarkdown(markdown, stdinReplacements);
+}

package/ts/reporter/shiki.ts

@@ -0,0 +1,58 @@
+export type CodeToANSI = (
+  code: string,
+  language: string,
+  theme: string
+) => Promise<string>;
+
+let codeToANSIPromise: Promise<CodeToANSI> | undefined;
+
+function loadCodeToANSI(): Promise<CodeToANSI> {
+  if (codeToANSIPromise) {
+    return codeToANSIPromise;
+  }
+
+  codeToANSIPromise = (async () => {
+    const env = typeof process !== "undefined" ? process.env : undefined;
+    const prevNoColor = env?.["NO_COLOR"];
+    const prevForceColor = env?.["FORCE_COLOR"];
+
+    // `@shikijs/cli` uses `ansis`, which disables colors when NO_COLOR is set.
+    // Force ANSI output when our callers explicitly request ANSI.
+    if (env) {
+      // biome-ignore lint/performance/noDelete: required to actually unset env vars
+      delete env["NO_COLOR"];
+      env["FORCE_COLOR"] = "3";
+    }
+
+    try {
+      const mod = await import("@shikijs/cli");
+      return mod.codeToANSI as unknown as CodeToANSI;
+    } finally {
+      if (env) {
+        if (prevNoColor === undefined) {
+          // biome-ignore lint/performance/noDelete: required to restore absence
+          delete env["NO_COLOR"];
+        } else {
+          env["NO_COLOR"] = prevNoColor;
+        }
+        if (prevForceColor === undefined) {
+          // biome-ignore lint/performance/noDelete: required to restore absence
+          delete env["FORCE_COLOR"];
+        } else {
+          env["FORCE_COLOR"] = prevForceColor;
+        }
+      }
+    }
+  })();
+
+  return codeToANSIPromise;
+}
+
+export async function codeToANSIForcedColors(
+  code: string,
+  language: string,
+  theme: string
+): Promise<string> {
+  const fn = await loadCodeToANSI();
+  return await fn(code, language, theme);
+}