executable-stories-formatters 1.10.0 → 1.11.0

package/dist/cli.js

@@ -3483,9 +3483,9 @@ function buildDataTable(table2, line) {
     const rowLine = line + 1 + r;
     rows.push({
       location: { line: rowLine },
-      cells: table2.rows[r].map((cell) => ({
+      cells: table2.rows[r].map((cell2) => ({
         location: { line: rowLine },
-        value: cell
+        value: cell2
       })),
       id: ""
     });
@@ -3586,7 +3586,7 @@ function buildPickleTable(table2) {
   });
   for (const row of table2.rows) {
     rows.push({
-      cells: row.map((cell) => ({ value: cell }))
+      cells: row.map((cell2) => ({ value: cell2 }))
     });
   }
   return { rows };
@@ -4685,7 +4685,7 @@ function formatDocEntry(doc) {
       return `${escapeHtml2(doc.label)}${doc.lang ? ` (${escapeHtml2(doc.lang)})` : ""}: <code>${escapeHtml2(doc.content)}</code>`;
     case "table": {
       const header = `<tr>${doc.columns.map((c) => `<th>${escapeHtml2(c)}</th>`).join("")}</tr>`;
-      const rows = doc.rows.map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml2(cell)}</td>`).join("")}</tr>`).join("");
+      const rows = doc.rows.map((row) => `<tr>${row.map((cell2) => `<td>${escapeHtml2(cell2)}</td>`).join("")}</tr>`).join("");
       return `${escapeHtml2(doc.label)}<table>${header}${rows}</table>`;
     }
     case "link":
@@ -5722,7 +5722,7 @@ ${tc.errorStack}` : "");
           table([
             tableRow(entry.columns.map((c) => tableHeader(c))),
             ...entry.rows.map(
-              (row) => tableRow(row.map((cell) => tableCell(cell)))
+              (row) => tableRow(row.map((cell2) => tableCell(cell2)))
             )
           ])
         );
@@ -10557,7 +10557,7 @@ var COMPLETION_SUBCOMMANDS = [
   ["init-astro", "Scaffold a thin Astro docs site"],
   ["new", "Scaffold a docs page from a template"],
   ["check-links", "Scan docs for broken links"],
-  ["push", "Send a run to Executable Stories Cloud"],
+  ["push", "Send a run to a cloud ingest endpoint"],
   ["coverage", "Compare stories against a test-management system (read-only)"],
   ["sync", "Push cases, executions, and evidence to TestRail or Xray"],
   ["import-openapi", "Generate API doc pages from an OpenAPI spec"],
@@ -11297,10 +11297,11 @@ import { synthesizeStories as synthesizeStories2 } from "executable-stories-core
 var EXIT_SUCCESS = 0;
 var EXIT_PUSH_FAILED = 1;
 var EXIT_USAGE = 4;
+var EXIT_GATE_BLOCKED = 5;
 var HELP = `Usage:
   executable-stories push <run.json> [options]
 
-Send a run to Executable Stories Cloud. <run.json> is either a StoryReport v1
+Send a run to a cloud ingest endpoint. <run.json> is either a StoryReport v1
 (e.g. reports/index.story-report.json) or a raw run JSON, which is converted
 through the standard pipeline first.
 
@@ -11314,12 +11315,20 @@ Options:
   --git-sha <sha>    Default: current git HEAD.
   --base <ref>       Send files changed since <ref> (e.g. origin/main) so the
                      cloud can recommend a test scope for the change.
+  --gate             After pushing, ask the cloud whether this commit is safe
+                     to release and exit 5 if it is blocked. The policy lives
+                     in your organization's settings, not in a file here.
   -h, --help         Show this help.
 
-Exit codes: 0 pushed, 1 push rejected/failed, 4 usage error.`;
+Under GitHub Actions, repo/branch/sha, the base commit, and PR metadata are
+read from the environment, the run URL and recommended scope are written to
+the job summary, and the run id is written to GITHUB_OUTPUT as ingest-run-id.
+
+Exit codes: 0 pushed, 1 push rejected/failed, 4 usage error, 5 gate blocked.`;
 function defaultDeps() {
   return {
     readFile: (filePath) => fs14.readFileSync(filePath, "utf8"),
+    appendFile: (filePath, text2) => fs14.appendFileSync(filePath, text2),
     fetchFn: fetch,
     git: (args) => {
       try {
@@ -11340,6 +11349,42 @@ function repoSlugFromRemote(remoteUrl) {
 function isStoryReport(data) {
   return typeof data.schemaVersion === "string";
 }
+function githubContext(deps) {
+  const env = deps.env;
+  const context = {
+    repo: env.GITHUB_REPOSITORY,
+    // GITHUB_HEAD_REF is the source branch on a pull_request event, where
+    // GITHUB_REF_NAME would be the synthetic "<n>/merge" ref.
+    branch: env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME,
+    gitSha: env.GITHUB_SHA
+  };
+  let event;
+  try {
+    event = JSON.parse(deps.readFile(env.GITHUB_EVENT_PATH ?? ""));
+  } catch {
+    return context;
+  }
+  context.prNumber = event.pull_request?.number;
+  context.prUrl = event.pull_request?.html_url;
+  const baseSha = event.pull_request?.base?.sha ?? event.before;
+  if (baseSha && !/^0+$/.test(baseSha)) {
+    if (deps.git(["cat-file", "-e", baseSha]) === void 0) {
+      deps.git(["fetch", "--depth=1", "origin", baseSha]);
+    }
+    context.baseSha = baseSha;
+  }
+  return context;
+}
+function summaryWriter(deps) {
+  const summaryPath = deps.env.GITHUB_STEP_SUMMARY;
+  return (markdown) => {
+    if (summaryPath) deps.appendFile(summaryPath, `${markdown}
+`);
+  };
+}
+function cell(text2) {
+  return text2.replaceAll("|", "\\|");
+}
 async function runPush(rawArgs, depsOverride = {}) {
   const deps = { ...defaultDeps(), ...depsOverride };
   let parsed;
@@ -11354,6 +11399,7 @@ async function runPush(rawArgs, depsOverride = {}) {
         branch: { type: "string" },
         "git-sha": { type: "string" },
         base: { type: "string" },
+        gate: { type: "boolean" },
         help: { type: "boolean", short: "h" }
       }
     });
@@ -11375,7 +11421,7 @@ async function runPush(rawArgs, depsOverride = {}) {
   const key = parsed.values.key ?? deps.env.EXECUTABLE_STORIES_API_KEY;
   if (!key) {
     deps.error(
-      "push needs an API key: pass --key or set EXECUTABLE_STORIES_API_KEY. Create one in Executable Stories Cloud (Settings -> Ingest key)."
+      "push needs an API key: pass --key or set EXECUTABLE_STORIES_API_KEY. Create one in your cloud instance's settings (Ingest key)."
     );
     return EXIT_USAGE;
   }
@@ -11399,16 +11445,20 @@ async function runPush(rawArgs, depsOverride = {}) {
       return EXIT_USAGE;
     }
   }
-  const repo = parsed.values.repo ?? repoSlugFromRemote(deps.git(["config", "--get", "remote.origin.url"]) ?? "");
+  const onActions = deps.env.GITHUB_ACTIONS === "true";
+  const github = onActions ? githubContext(deps) : {};
+  const summary = summaryWriter(deps);
+  const repo = parsed.values.repo ?? github.repo ?? repoSlugFromRemote(deps.git(["config", "--get", "remote.origin.url"]) ?? "");
   if (!repo) {
     deps.error("Could not infer the repository slug from git. Pass --repo <org/name>.");
     return EXIT_USAGE;
   }
-  const branch = parsed.values.branch ?? deps.git(["rev-parse", "--abbrev-ref", "HEAD"]);
-  const gitSha = parsed.values["git-sha"] ?? deps.git(["rev-parse", "HEAD"]);
+  const branch = parsed.values.branch ?? github.branch ?? deps.git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const gitSha = parsed.values["git-sha"] ?? github.gitSha ?? deps.git(["rev-parse", "HEAD"]);
   const baseUrl = parsed.values.url ?? deps.env.EXECUTABLE_STORIES_URL ?? "https://app.executablestories.com";
   const base = parsed.values.base;
-  const changedFiles = base ? deps.git(["diff", "--name-only", `${base}...HEAD`])?.split("\n").filter(Boolean) ?? [] : [];
+  const baseSha = base ? deps.git(["rev-parse", base]) : github.baseSha;
+  const changedFiles = baseSha ? deps.git(["diff", "--name-only", `${baseSha}...HEAD`])?.split("\n").filter(Boolean) ?? [] : [];
   if (base && changedFiles.length === 0) {
     deps.error(`Warning: no changed files found against ${base}; pushing without change metadata.`);
   }
@@ -11424,9 +11474,13 @@ async function runPush(rawArgs, depsOverride = {}) {
         repo,
         branch,
         gitSha,
-        source: "serve",
+        // "serve" named a subcommand that no longer exists (ADR 0006). The
+        // cloud accepts both; "local" is what this is.
+        source: onActions ? "action" : "local",
         report,
-        ...changedFiles.length > 0 ? { changedFiles, baseSha: deps.git(["rev-parse", base]) } : {}
+        ...changedFiles.length > 0 ? { changedFiles, baseSha } : {},
+        ...github.prNumber ? { prNumber: github.prNumber } : {},
+        ...github.prUrl ? { prUrl: github.prUrl } : {}
       })
     });
   } catch (err) {
@@ -11439,12 +11493,97 @@ async function runPush(rawArgs, depsOverride = {}) {
     deps.error(`Push rejected: HTTP ${response.status}${retryAfter ? ` (retry after ${retryAfter}s)` : ""}: ${body.slice(0, 500)}`);
     return EXIT_PUSH_FAILED;
   }
-  let runId = "";
+  let result = {};
   try {
-    runId = String(JSON.parse(body).runId ?? "");
+    result = JSON.parse(body);
   } catch {
   }
+  const runId = String(result.runId ?? "");
   deps.log(runId ? `Pushed run ${runId} (${repo}${branch ? `@${branch}` : ""})` : "Pushed run.");
+  if (result.url) deps.log(result.url);
+  summary(
+    result.url ? `### Executable Stories
+
+[View this run](${result.url})` : "### Executable Stories\n\nRun pushed."
+  );
+  if (runId && deps.env.GITHUB_OUTPUT) {
+    deps.appendFile(deps.env.GITHUB_OUTPUT, `ingest-run-id=${runId}
+`);
+  }
+  const recommendations = result.recommendations ?? [];
+  if (recommendations.length > 0) {
+    deps.log(`
+Recommended scope for this change (${recommendations.length}):`);
+    for (const item of recommendations) {
+      deps.log(`  [${item.confidence}] ${item.title} \u2014 ${item.reason}`);
+    }
+    summary(`
+**Recommended scope for this change (${recommendations.length})**
+`);
+    summary("| Confidence | Case | Why |\n| --- | --- | --- |");
+    for (const item of recommendations) {
+      summary(`| ${cell(item.confidence)} | ${cell(item.title)} | ${cell(item.reason)} |`);
+    }
+  }
+  if (!parsed.values.gate) return EXIT_SUCCESS;
+  if (!gitSha) {
+    deps.error("--gate needs a commit sha: pass --git-sha or run inside a git repository.");
+    return EXIT_USAGE;
+  }
+  return await runGate({ baseUrl, key, repo, gitSha, onActions }, deps);
+}
+async function runGate({
+  baseUrl,
+  key,
+  repo,
+  gitSha,
+  onActions
+}, deps) {
+  const summary = summaryWriter(deps);
+  const query = `repo=${encodeURIComponent(repo)}&sha=${encodeURIComponent(gitSha)}`;
+  let response;
+  try {
+    response = await deps.fetchFn(new URL(`/api/v1/releases/gate?${query}`, baseUrl), {
+      headers: { Authorization: `Bearer ${key}` }
+    });
+  } catch (err) {
+    deps.error(`Could not reach the gate: ${err instanceof Error ? err.message : String(err)}`);
+    return EXIT_PUSH_FAILED;
+  }
+  const body = await response.text();
+  if (!response.ok) {
+    deps.error(`Gate check failed: HTTP ${response.status}: ${body.slice(0, 500)}`);
+    return EXIT_PUSH_FAILED;
+  }
+  let gate = {};
+  try {
+    gate = JSON.parse(body);
+  } catch {
+    deps.error(`Gate returned a non-JSON body: ${body.slice(0, 200)}`);
+    return EXIT_PUSH_FAILED;
+  }
+  for (const warning of gate.warnings ?? []) deps.log(`  warning: ${warning}`);
+  const commit = `${repo}@${gitSha.slice(0, 12)}`;
+  if (gate.status === "no-release") {
+    deps.log(`
+No release recorded for ${commit} \u2014 nothing to gate on.`);
+    summary("\n**Release gate: no release recorded for this commit**");
+    return EXIT_SUCCESS;
+  }
+  if (gate.status === "blocked") {
+    deps.error(`
+Release gate: BLOCKED for ${commit}`);
+    summary("\n**Release gate: blocked**\n");
+    for (const reason of gate.blocking ?? []) {
+      deps.error(`  - ${reason}`);
+      summary(`- ${reason}`);
+      if (onActions) deps.error(`::error::Release gate: ${reason}`);
+    }
+    return EXIT_GATE_BLOCKED;
+  }
+  deps.log(`
+Release gate: clear for ${commit}`);
+  summary("\n**Release gate: clear**");
   return EXIT_SUCCESS;
 }
 
@@ -12018,7 +12157,7 @@ SUBCOMMANDS
   init-astro         Scaffold a thin Astro docs site (Starlight + executable-stories-astro; live stories at /stories)
   new                Scaffold a docs page from a template (adr, runbook, decision-log, incident, scenario-note)
   check-links        Scan docs for broken internal/external links (CI-friendly exit code)
-  push               Send a run (StoryReport or raw run JSON) to Executable Stories Cloud
+  push               Send a run (StoryReport or raw run JSON) to a cloud ingest endpoint
   coverage           Compare your stories against a test-management system (read-only)
   sync               Push cases, executions, and evidence to TestRail or Xray (dry run by default)
   import-openapi     Generate API doc pages from an OpenAPI spec, linked to verifying stories