@ultimat3/cli 6.0.0 → 7.0.0

package/src/ci-runs.ts

@@ -0,0 +1,179 @@
+// Which workflow runs `x ci` is about, and the three `gh run` calls that answer it. Selection
+// lives here rather than in the command so "the latest run of each workflow on this branch" is one
+// testable function over plain rows instead of a shape only a subprocess can produce.
+
+import { t } from '@ultimat3/schema';
+import type { GhHost } from './gh';
+import { ghJson, runGh } from './gh';
+import type { GhRepo } from './gh-target';
+
+/** The fields both `gh run list` and `gh run view` accept, named once so the two agree. */
+export const RUN_FIELDS =
+  'databaseId,status,conclusion,headBranch,displayTitle,workflowName,url,createdAt';
+
+const RUN_ROW = t.object({
+  databaseId: t.number,
+  status: t.string,
+  conclusion: t.nullable(t.string),
+  headBranch: t.string,
+  displayTitle: t.string,
+  workflowName: t.string,
+  url: t.string,
+  createdAt: t.string,
+});
+
+const STEP = t.object({ name: t.string, conclusion: t.nullable(t.string), number: t.number });
+
+const JOB = t.object({
+  name: t.string,
+  status: t.string,
+  conclusion: t.nullable(t.string),
+  url: t.string,
+  steps: t.array(STEP),
+});
+
+const RUN_LIST = t.array(RUN_ROW);
+const RUN_VIEW = RUN_ROW.extend({ jobs: t.array(JOB) });
+
+export interface CiStep {
+  readonly name: string;
+  readonly conclusion: string | null;
+  readonly number: number;
+}
+
+export interface CiJob {
+  readonly name: string;
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly url: string;
+  readonly steps: readonly CiStep[];
+}
+
+export interface CiRun {
+  readonly id: number;
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly branch: string;
+  readonly title: string;
+  readonly workflow: string;
+  readonly url: string;
+  readonly createdAt: string;
+}
+
+/**
+ * The conclusions that mean "this run is not green". `cancelled` and `timed_out` are in it because
+ * a cancelled run has told the reader nothing about their change, and a command that reported it
+ * as passing would be a green verdict over an unanswered question. `skipped` is not: a workflow
+ * whose conditions did not match was never asked.
+ */
+export const FAILED_CONCLUSIONS: readonly string[] = [
+  'failure',
+  'cancelled',
+  'timed_out',
+  'startup_failure',
+  'action_required',
+  'stale',
+];
+
+export const isFailed = (run: CiRun): boolean =>
+  run.conclusion !== null && FAILED_CONCLUSIONS.includes(run.conclusion);
+
+export const isRunning = (run: CiRun): boolean => run.status !== 'completed';
+
+interface RunRow {
+  readonly databaseId: number;
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly headBranch: string;
+  readonly displayTitle: string;
+  readonly workflowName: string;
+  readonly url: string;
+  readonly createdAt: string;
+}
+
+const runOf = (row: RunRow): CiRun => ({
+  id: row.databaseId,
+  status: row.status,
+  conclusion: row.conclusion,
+  branch: row.headBranch,
+  title: row.displayTitle,
+  workflow: row.workflowName,
+  url: row.url,
+  createdAt: row.createdAt,
+});
+
+/**
+ * The newest run of EACH workflow, which is the honest answer to "is CI green on this branch".
+ * Taking the newest run overall reports whichever workflow happened to finish last — this repo
+ * runs `ci` and `deploy-social-demo` off the same push, so half the time that is a verdict about
+ * a workflow the caller was not asking about.
+ */
+export function latestPerWorkflow(runs: readonly CiRun[]): readonly CiRun[] {
+  const newest = new Map<string, CiRun>();
+  for (const run of runs) {
+    const held = newest.get(run.workflow);
+    if (held === undefined || run.createdAt > held.createdAt) newest.set(run.workflow, run);
+  }
+  return [...newest.values()];
+}
+
+export async function listRuns(
+  host: GhHost,
+  repo: GhRepo,
+  branch: string,
+  limit: number,
+): Promise<readonly CiRun[]> {
+  const rows = await ghJson(
+    host,
+    [
+      'run',
+      'list',
+      '--repo',
+      repo.slug,
+      '--branch',
+      branch,
+      '--limit',
+      String(limit),
+      '--json',
+      RUN_FIELDS,
+    ],
+    RUN_LIST,
+    {
+      label: `gh run list --branch ${branch}`,
+      fix: `x ci --branch ${branch} --repo ${repo.slug} --json`,
+    },
+  );
+  return rows.map(runOf);
+}
+
+/** One run, with its jobs — `gh run view --json` carries both, so this is one round trip. */
+export async function viewRun(
+  host: GhHost,
+  repo: GhRepo,
+  id: number,
+): Promise<{ readonly run: CiRun; readonly jobs: readonly CiJob[] }> {
+  const viewed = await ghJson(
+    host,
+    ['run', 'view', String(id), '--repo', repo.slug, '--json', `${RUN_FIELDS},jobs`],
+    RUN_VIEW,
+    { label: `gh run view ${id}`, fix: `x ci --run ${id} --repo ${repo.slug} --json` },
+  );
+  return { run: runOf(viewed), jobs: viewed.jobs };
+}
+
+/**
+ * The failed steps' log, and only those. `--log` is the whole run — setup, caches, every green
+ * step — where `--log-failed` is the part a triage starts from, which is the difference between
+ * one command and three.
+ */
+export async function failedLog(host: GhHost, repo: GhRepo, id: number): Promise<string> {
+  const result = await runGh(
+    host,
+    ['run', 'view', String(id), '--repo', repo.slug, '--log-failed'],
+    {
+      label: `gh run view ${id} --log-failed`,
+      fix: `gh run view ${id} --repo ${repo.slug} --log   # the whole log, when the failed steps carry none`,
+    },
+  );
+  return result.stdout;
+}

package/src/cmd-affected.ts

@@ -0,0 +1,109 @@
+// `x affected` — the workspaces a diff forces a re-test of, closed transitively over the workspace
+// graph. `x verify` runs everything, which is right for a gate and wrong for the loop an agent
+// iterates in; without this command that agent invents its own scoping, and an invented one that
+// misses a transitive dependent is a green checkmark on a broken repo.
+//
+// CLI wiring only. What a diff touches is `affected.ts`, what the workspaces are is
+// `workspace-graph.ts` — the `cmd-jobs.ts` / `jobs-report.ts` split, repeated.
+
+import { affectedScope, DEFAULT_BASE } from './affected';
+import type { CliCommand, CommandContext } from './command';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { flagBool } from './parse';
+import { renderTable } from './table';
+
+const HEADER = ['workspace', 'dir'] as const;
+
+/**
+ * Every catalog row the affected surface renders — this command's four and the one `x test
+ * --affected` prints when nothing is affected. One list, because the two commands are one surface
+ * and a per-file list would leave whichever half nobody thought about unchecked.
+ *
+ * The rule it exists for: `msg()` answers `⟦key⟧` for a key the catalog lacks, which is loud in the
+ * terminal and completely silent to a build, so a command can ship a summary no locale renders.
+ * `cmd-affected.test.ts` holds `messages.ts` to this list.
+ */
+export const AFFECTED_MESSAGE_KEYS = [
+  'cli.affected.count',
+  'cli.affected.none',
+  'cli.affected.rootWide',
+  'cli.affected.dirty',
+  'cli.test.affected.none',
+] as const;
+
+export const affectedCommand: CliCommand = {
+  spec: {
+    name: 'affected',
+    summary: 'the workspaces a diff touches, and every workspace that depends on one of them',
+    usage: 'x affected [--base <ref>] [--dirty] [--paths] [--json]',
+    flags: [
+      {
+        name: 'base',
+        type: 'string',
+        summary: `git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
+      },
+      {
+        name: 'dirty',
+        type: 'boolean',
+        summary: 'also count uncommitted work — every agent sharing this checkout, not only yours',
+      },
+      { name: 'paths', type: 'boolean', summary: 'print bare directories instead of a table' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    // The one resolver `x test --affected` narrows with, so this command reports exactly what that
+    // one runs. It reads `--base` before git is spawned (a malformed ref must not cost a
+    // subprocess) and takes the diff at the CHECKOUT root, which is what git prints paths against.
+    const { selection, root, plan } = await affectedScope({
+      runner: ctx.runner,
+      cwd: ctx.cwd,
+      args: ctx.args,
+      command: 'affected',
+    });
+    const params = { base: selection.base, changed: plan.changed.length };
+    const table = renderTable(
+      HEADER,
+      plan.workspaces.map((workspace) => [workspace.name, workspace.dir]),
+    ).map((line) => `  ${line}`);
+    const data: JsonValue = {
+      base: selection.base,
+      dirty: selection.dirty,
+      root,
+      changed: [...plan.changed],
+      ignored: [...plan.ignored],
+      rootWide: [...plan.rootWide],
+      workspaces: plan.workspaces.map((workspace) => ({
+        name: workspace.name,
+        dir: workspace.dir,
+      })),
+      paths: plan.workspaces.map((workspace) => workspace.dir),
+    };
+    return {
+      // An empty answer is a fact, not a failure: a `.md`-only diff genuinely re-checks nothing,
+      // and reporting it red would fail a build for editing a doc. The count is in the summary and
+      // `data.changed`/`data.ignored` say what was looked at, so "green because nothing is
+      // affected" is never mistaken for "green because everything passed".
+      ok: true,
+      command: 'affected',
+      summary:
+        plan.workspaces.length === 0
+          ? msg('cli.affected.none', params)
+          : msg('cli.affected.count', { ...params, count: plan.workspaces.length }),
+      lines: [
+        ...(selection.dirty ? [msg('cli.affected.dirty')] : []),
+        ...(plan.rootWide.length === 0
+          ? []
+          : [msg('cli.affected.rootWide', { files: plan.rootWide.join(', ') })]),
+        ...(plan.workspaces.length === 0
+          ? []
+          : // `--paths` changes only what the human sees; `--json` carries both projections on
+            // every run, so the two renderers can never state different sets.
+            flagBool(ctx.args, 'paths')
+            ? plan.workspaces.map((workspace) => workspace.dir)
+            : table),
+      ],
+      data,
+    };
+  },
+};

package/src/cmd-build.ts

@@ -14,6 +14,13 @@ import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagString } from './parse';
+import type { StaticReport } from './static-report';
+import {
+  readStaticReport,
+  removeStaticReport,
+  renderStaticReport,
+  staticReportData,
+} from './static-report';
 
 export const BUILD_TARGETS = ['docker', 'binary', 'static'] as const;
 
@@ -111,14 +118,19 @@ export function preflightResult(verify: CommandResult): CommandResult {
  * `✗ built docker`; and the builder's own logs went only into `lines`, which is declared human-only
  * and which `renderJson` drops — so CI, which runs `--json`, got the exit code and nothing to act
  * on. The output now rides in `data` and `lines` renders that same string.
+ *
+ * `report` is the static target's inventory, and BOTH renderers get it: `--json` is the house rule,
+ * but an agent reading terminal output is the primary developer here, so a silent human path is the
+ * same defect in a different costume. `lines` still carries nothing `data` does not (#242).
  */
 export function buildResult(input: {
   readonly target: BuildTarget;
   readonly artifact: string;
   readonly command: readonly string[];
   readonly result: ExecResult;
+  readonly report?: StaticReport;
 }): CommandResult {
-  const { result, target } = input;
+  const { report, result, target } = input;
   const output = result.ok ? '' : execOutput(result);
   return {
     ok: result.ok,
@@ -139,8 +151,13 @@ export function buildResult(input: {
       artifact: input.artifact,
       durationMs: result.durationMs,
       ...(result.ok ? {} : { output }),
+      ...staticReportData(report),
     },
-    lines: result.ok ? [] : output.split('\n'),
+    lines: result.ok
+      ? report === undefined
+        ? []
+        : renderStaticReport(report)
+      : output.split('\n'),
   };
 }
 
@@ -178,11 +195,20 @@ export const buildCommand: CliCommand = {
       flagString(ctx.args, 'out') ?? join(root, '.x', target === 'static' ? 'static' : 'app');
     const tag = flagString(ctx.args, 'tag') ?? 'ultimate-app:dev';
     const command = argsFor(target, { root, tag, out });
+    // Removed BEFORE the builder runs, so a build that writes no inventory can never be reported
+    // with the last one's: a stale emitted list is worse than none, because it reads as this run's.
+    if (target === 'static') await removeStaticReport(root);
+    const result = await ctx.runner(command, { cwd: root });
+    // `prerenderSite` writes it; an app whose `apps/web/prerender.ts` does not call that writes no
+    // `.x/build-stats.json` either, and `x verify`'s `budgets` step already reds that app with
+    // `X_BUDGET_UNMEASURED` — so the absence needs no second code here.
+    const report = target === 'static' && result.ok ? await readStaticReport(root) : undefined;
     return buildResult({
       target,
       artifact: target === 'docker' ? tag : out,
       command,
-      result: await ctx.runner(command, { cwd: root }),
+      result,
+      ...(report === undefined ? {} : { report }),
     });
   },
 };

package/src/cmd-ci.ts

@@ -0,0 +1,273 @@
+// `x ci` — one command instead of three. `gh run view` prints a tree of ticks and one cross, and
+// the error is inside a per-job log that is mostly setup noise; for a `verify` job that log tail IS
+// the findings block, with its `X_*` codes and executable `fix:` lines already in it. So this
+// command fetches the runs, opens only the failed steps' log, and hands back the findings the gate
+// already wrote — in the same three-line shape every other Ultimate error is printed in.
+
+import { UltimateError } from '@ultimat3/core';
+import type { CiLogLine } from './ci-log';
+import { findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
+import type { CiJob, CiRun } from './ci-runs';
+import { failedLog, isFailed, isRunning, latestPerWorkflow, listRuns, viewRun } from './ci-runs';
+import type { CliCommand, CommandContext } from './command';
+import { parseIntFlag } from './flag-number';
+import type { GhRepo } from './gh-target';
+import { currentBranch, resolveRepo } from './gh-target';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import { flagBool, flagString } from './parse';
+
+/**
+ * Every catalog key this command renders, declared — `msg()` answers `⟦key⟧` for a key nobody
+ * added, which is loud in a terminal and SILENT to a build. `cmd-ci.test.ts` holds this list
+ * against the catalog, so a missing string is a failing test rather than a rendered artefact.
+ */
+export const CI_MESSAGE_KEYS = [
+  'cli.ci.failed',
+  'cli.ci.green',
+  'cli.ci.running',
+  'cli.ci.run',
+  'cli.ci.job',
+  'cli.ci.jobs.other',
+  'cli.ci.tail',
+  'cli.ci.pending',
+  'cli.ci.logs.empty',
+] as const;
+
+/** Log lines kept per failed job. Enough to hold a findings block, short enough to read. */
+export const TAIL_LINES = 40;
+
+/** How far back a branch's run history is read before "the latest run of each workflow". */
+export const RUN_LOOKBACK = 20;
+
+/** No run to triage. The remedy is a branch that has one, or the id of the run in question. */
+export class CiRunNotFoundError extends UltimateError {
+  constructor(input: { branch: string; repo: string }) {
+    super({
+      code: 'X_CI_RUN_NOT_FOUND',
+      cause: `no workflow run on ${input.repo} for branch "${input.branch}"`,
+      fix: `x ci --branch main --repo ${input.repo} --json`,
+    });
+  }
+}
+
+const RUN_FLAG = { name: 'run', command: 'ci', min: 1, example: 'x ci --run 32484583944 --json' };
+const TAIL_FLAG = { name: 'tail', command: 'ci', min: 1, example: 'x ci --tail 80 --json' };
+
+export const ciCommand: CliCommand = {
+  spec: {
+    name: 'ci',
+    summary: 'the workflow runs for this branch, and the findings inside the failed steps log',
+    usage: 'x ci [--branch <name>] [--run <id>] [--repo owner/name] [--tail <n>] [--full] [--json]',
+    flags: [
+      { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
+      { name: 'branch', type: 'string', summary: 'branch to read runs for; this one by default' },
+      { name: 'run', type: 'string', summary: 'one run id, instead of this branch latest' },
+      {
+        name: 'tail',
+        type: 'string',
+        summary: `log lines kept per failed job (default ${TAIL_LINES})`,
+      },
+      { name: 'full', type: 'boolean', summary: 'the whole failed-step log, not the tail' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const repo = await resolveRepo(ctx, 'ci', flagString(ctx.args, 'repo'));
+    const rawRun = flagString(ctx.args, 'run');
+    const rawTail = flagString(ctx.args, 'tail');
+    const limit = flagBool(ctx.args, 'full')
+      ? Number.POSITIVE_INFINITY
+      : rawTail === undefined
+        ? TAIL_LINES
+        : parseIntFlag(rawTail, TAIL_FLAG);
+    if (rawRun !== undefined) {
+      const viewed = await viewRun(ctx, repo, parseIntFlag(rawRun, RUN_FLAG));
+      return report(repo, viewed.run.branch, [await inspect(ctx, repo, viewed, limit)]);
+    }
+    const branch = flagString(ctx.args, 'branch') ?? (await currentBranch(ctx));
+    const runs = latestPerWorkflow(await listRuns(ctx, repo, branch, RUN_LOOKBACK));
+    if (runs.length === 0) throw new CiRunNotFoundError({ branch, repo: repo.slug });
+    const inspected: RunReport[] = [];
+    for (const run of runs) {
+      // Only a failed run is opened. A green run's jobs are 35 rows saying `success`, and fetching
+      // them would turn the fast answer ("CI is green") into the slow one.
+      inspected.push(
+        isFailed(run) ? await inspect(ctx, repo, await viewRun(ctx, repo, run.id), limit) : { run },
+      );
+    }
+    return report(repo, branch, inspected);
+  },
+};
+
+interface JobFailure {
+  readonly job: string;
+  readonly conclusion: string;
+  readonly url: string;
+  readonly failedSteps: readonly string[];
+  readonly tail: readonly string[];
+}
+
+interface RunReport {
+  readonly run: CiRun;
+  readonly jobs?: readonly CiJob[];
+  readonly failures?: readonly JobFailure[];
+  readonly findings?: readonly Finding[];
+}
+
+const stepFailed = (conclusion: string | null): boolean =>
+  conclusion !== null && conclusion !== 'success' && conclusion !== 'skipped';
+
+/**
+ * One failed run, opened. The findings are attributed to the job whose lines produced them, and
+ * a job the log attributes nothing to falls back to the whole log — a format change on GitHub's
+ * side must cost the attribution, never the finding.
+ */
+async function inspect(
+  ctx: CommandContext,
+  repo: GhRepo,
+  viewed: { readonly run: CiRun; readonly jobs: readonly CiJob[] },
+  limit: number,
+): Promise<RunReport> {
+  const { run, jobs } = viewed;
+  if (!isFailed(run)) return { run, jobs };
+  const lines = parseLogLines(await failedLog(ctx, repo, run.id));
+  const failed = jobs.filter((job) => stepFailed(job.conclusion));
+  // A run can fail with no failed JOB — a startup failure, a cancelled matrix — and the log is
+  // then the only thing that knows which name to file it under.
+  const names = failed.length > 0 ? failed.map((job) => job.name) : jobsInLog(lines);
+  const failures: JobFailure[] = [];
+  const findings: Finding[] = [];
+  for (const name of names) {
+    const own = lines.filter((line) => line.job === name);
+    const pool: readonly CiLogLine[] = own.length > 0 ? own : lines;
+    const job = failed.find((candidate) => candidate.name === name);
+    for (const finding of findingsFrom(pool)) {
+      findings.push(finding.at === undefined ? { ...finding, at: name } : finding);
+    }
+    failures.push({
+      job: name,
+      conclusion: job?.conclusion ?? conclusionOf(run),
+      url: job?.url ?? run.url,
+      failedSteps: (job?.steps ?? [])
+        .filter((step) => stepFailed(step.conclusion))
+        .map((step) => step.name),
+      tail: tailOf(lines, name, limit),
+    });
+  }
+  return { run, jobs, failures, findings: dedupe(findings) };
+}
+
+/**
+ * The same block can be reached twice — once per job when the log attributes nothing, once per
+ * attempt when a run was re-run — and two copies of one finding read as two problems.
+ */
+function dedupe(findings: readonly Finding[]): readonly Finding[] {
+  const seen = new Set<string>();
+  return findings.filter((finding) => {
+    const key = `${finding.code} ${finding.cause}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+const conclusionOf = (run: CiRun): string => run.conclusion ?? msg('cli.ci.pending');
+
+function report(repo: GhRepo, branch: string, reports: readonly RunReport[]): CommandResult {
+  const failed = reports.filter((entry) => isFailed(entry.run));
+  const running = reports.filter((entry) => isRunning(entry.run));
+  const findings = dedupe(reports.flatMap((entry) => entry.findings ?? []));
+  return {
+    ok: failed.length === 0,
+    command: 'ci',
+    summary:
+      failed.length > 0
+        ? msg('cli.ci.failed', {
+            failed: failed.length,
+            runs: reports.length,
+            branch,
+            findings: findings.length,
+          })
+        : running.length > 0
+          ? msg('cli.ci.running', { running: running.length, runs: reports.length, branch })
+          : msg('cli.ci.green', { runs: reports.length, branch }),
+    findings,
+    lines: reports.flatMap(runLines),
+    data: {
+      repo: repo.slug,
+      branch,
+      counts: {
+        runs: reports.length,
+        failed: failed.length,
+        running: running.length,
+        findings: findings.length,
+      },
+      runs: reports.map(runJson),
+    },
+  };
+}
+
+function runLines(entry: RunReport): readonly string[] {
+  const out = [
+    msg('cli.ci.run', {
+      conclusion: conclusionOf(entry.run),
+      workflow: entry.run.workflow,
+      url: entry.run.url,
+    }),
+  ];
+  const failures = entry.failures ?? [];
+  for (const failure of failures) {
+    out.push(
+      msg('cli.ci.job', {
+        conclusion: failure.conclusion,
+        job: failure.job,
+        steps: failure.failedSteps.join(', '),
+      }),
+    );
+    if (failure.tail.length === 0) {
+      out.push(msg('cli.ci.logs.empty', { url: failure.url }));
+      continue;
+    }
+    out.push(msg('cli.ci.tail', { job: failure.job }));
+    for (const line of failure.tail) out.push(`      | ${line}`);
+  }
+  const jobs = entry.jobs;
+  if (jobs !== undefined && jobs.length > failures.length) {
+    out.push(msg('cli.ci.jobs.other', { count: jobs.length - failures.length }));
+  }
+  return out;
+}
+
+function runJson(entry: RunReport): JsonValue {
+  return {
+    id: entry.run.id,
+    workflow: entry.run.workflow,
+    status: entry.run.status,
+    conclusion: entry.run.conclusion,
+    title: entry.run.title,
+    url: entry.run.url,
+    createdAt: entry.run.createdAt,
+    // Absent rather than empty on a run that was never opened: `jobs: []` on a green run would
+    // claim the run has no jobs, which is a different statement from "nobody asked".
+    ...(entry.jobs === undefined
+      ? {}
+      : {
+          jobs: entry.jobs.map((job) => ({
+            name: job.name,
+            status: job.status,
+            conclusion: job.conclusion,
+            url: job.url,
+          })),
+        }),
+    ...(entry.failures === undefined
+      ? {}
+      : {
+          failures: entry.failures.map((failure) => ({
+            job: failure.job,
+            url: failure.url,
+            failedSteps: [...failure.failedSteps],
+            tail: [...failure.tail],
+          })),
+        }),
+  };
+}