@trazum/cli 1.10.0 → 1.25.0

package/src/markdown.ts

@@ -8,7 +8,9 @@ import type {
   PromptProfile,
   RuleLevel,
 } from '@trazum/core';
-import { formatSignedUsd, formatUsd, getMessages, getModel } from '@trazum/core';
+import { TTL_1H_MS, UNLABELLED, formatSignedUsd, formatUsd, getMessages, getModel, sharesOf } from '@trazum/core';
+import { dayOf, formatGap, median, spanDays } from './time.js';
+import type { AgainstDriver, BillLevers, CacheEconomics, RepriceReport, UsageProfileReport } from '@trazum/core';
 
 /**
  * Markdown for the places a pull request is actually read.
@@ -715,3 +717,415 @@ export function renderBlameMarkdown(input: BlameMarkdownInput): string {
 
   return lines.join('\n');
 }
+
+export interface ProfileMarkdownInput {
+  report: UsageProfileReport;
+  levers: BillLevers;
+  cache: CacheEconomics;
+  t: CliMessages;
+  /**
+   * The `--since`/`--until` values as the user typed them, when a window was
+   * applied. Passed through rather than re-derived from `timeWindow`'s epoch
+   * bounds, because a bare `--until 2026-08-14` includes that whole day —
+   * rendering the internal exclusive bound would print the *next* day and
+   * disagree with the terminal about which window this was.
+   */
+  window?: { since: string; until: string };
+  /**
+   * Passed only when the price table is old enough to matter, so the
+   * threshold lives once, beside the terminal's. Rendered loud: staleness
+   * does not name its own size the way a skipped line does.
+   */
+  stalePricing?: { date: string; days: number };
+  /**
+   * The comparison, when `--against` was given — the section the terminal
+   * has had since 1.11 and the markdown did not, so a CI summary reporting
+   * on two logs showed only one of them. The drivers arrive computed (core's
+   * `driversBetween`) rather than derived here: the sign convention has one
+   * implementation, and this is a rendering.
+   */
+  /**
+   * The repricing, when `--what-if` was given. Arrives computed from core's
+   * `repriceProfile` rather than derived here: three surfaces must not
+   * disagree about what a move would cost, and this is a rendering.
+   */
+  whatIf?: RepriceReport | null;
+  against?: {
+    previousTotalUsd: number;
+    previousCalls: number;
+    labelDrivers: AgainstDriver[];
+    modelDrivers: AgainstDriver[];
+    /** True when both spans are known and intersect. */
+    overlap: { from: string; to: string } | null;
+    /** Nothing in the previous log could be priced — its own answer. */
+    nothingPriced: boolean;
+  };
+}
+
+/**
+ * `trazum profile` as GitHub-flavoured markdown, for a job summary or a
+ * pull-request comment.
+ *
+ * The terminal report is the source of truth and this reuses its message
+ * catalogue line for line, because two renderings of the same finding drift the
+ * moment they are worded twice — the sign conventions here (`positive means
+ * worse` on the cache delta, ceilings that must be named as ceilings) have each
+ * already produced a bug when restated by hand.
+ *
+ * A finding that only exists in a terminal is a finding the reader's tooling
+ * never surfaces; this is the other half of the `--json` lesson, for humans
+ * reading CI instead of machines.
+ */
+export function renderProfileMarkdown(input: ProfileMarkdownInput): string {
+  const { report, levers, cache, t, window, stalePricing, against, whatIf } = input;
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+  const pct = (share: number): string => `${(share * 100).toFixed(1)}%`;
+  const shares = sharesOf(report.total);
+  const showLabel = (label: string): string =>
+    label === UNLABELLED ? t.profile.unlabelled() : label;
+
+  const lines: string[] = [];
+  lines.push(`### ${t.profile.heading()}`);
+  lines.push('');
+  lines.push(`**${t.profile.spent(t.profile.calls(report.total.calls), formatUsd(report.total.totalUsd))}**`);
+  lines.push('');
+  // The span, under the same rule as the terminal: stated, never extrapolated,
+  // with partial coverage said in the same breath.
+  if (report.span !== null) {
+    const totalParsed = report.total.calls + report.unpriced.calls;
+    const partial =
+      report.span.calls < totalParsed
+        ? ` ${mdText(t.profile.spanPartial(n(report.span.calls), n(totalParsed)))}`
+        : '';
+    lines.push(
+      `_${mdText(t.profile.spanLine(dayOf(report.span.fromMs), dayOf(report.span.toMs), spanDays(report.span.fromMs, report.span.toMs)))}${partial}_`,
+    );
+    lines.push('');
+  }
+  // The window before any figure, and the undated count loud — the same order
+  // and the same volume as the terminal, for the same reasons.
+  if (report.timeWindow !== null) {
+    lines.push(`_${mdText(t.profile.windowLine(window?.since ?? '—', window?.until ?? '—'))}_`);
+    lines.push('');
+    if (report.timeWindow.undatedExcluded > 0) {
+      lines.push(`> ⚠️ ${mdText(t.profile.windowUndated(report.timeWindow.undatedExcluded))}`);
+      lines.push('');
+    }
+  }
+  lines.push('| | USD | % | tokens |');
+  lines.push('|---|---:|---:|---:|');
+  const parts: Array<[string, number, number, number]> = [
+    [t.profile.partInput(), report.total.inputUsd, shares.input, report.total.inputTokens],
+    [t.profile.partCacheRead(), report.total.cacheReadUsd, shares.cacheRead, report.total.cacheReadTokens],
+    [t.profile.partCacheWrite(), report.total.cacheWriteUsd, shares.cacheWrite, report.total.cacheWriteTokens],
+    [t.profile.partOutput(), report.total.outputUsd, shares.output, report.total.outputTokens],
+  ];
+  for (const [name, usd, share, tokens] of parts) {
+    // Catalogue text, not user data: no escaping into a code cell needed.
+    lines.push(`| ${name} | ${formatUsd(usd)} | ${pct(share)} | ${n(tokens)} |`);
+  }
+  lines.push('');
+
+  /**
+   * A doubled bill, said before anything above is believed. A CI summary
+   * showing a total nobody can trust is worse than one showing no total.
+   */
+  if (report.duplicateLines.count > 0) {
+    lines.push(
+      `> ⚠️ ${mdText(t.profile.duplicateLines(report.duplicateLines.count, formatUsd(report.duplicateLines.usd)))}`,
+    );
+    lines.push('');
+  }
+
+  // The most expensive day against the median day, loud past twice it — the
+  // same sentence and the same yardstick the terminal prints.
+  if (report.spendByDay.length >= 2) {
+    const medianUsd = median(report.spendByDay.map((d) => d.usd));
+    const peak = report.spendByDay.reduce((a, b) => (b.usd > a.usd ? b : a));
+    if (medianUsd > 0) {
+      const sentence = t.profile.dayPeak(peak.day, formatUsd(peak.usd), (peak.usd / medianUsd).toFixed(1));
+      const labelClause =
+        peak.topLabel !== null && report.byLabel.length > 1
+          ? ` ${t.profile.dayPeakLabel(showLabel(peak.topLabel), formatUsd(peak.topLabelUsd))}`
+          : '';
+      const loud = peak.usd > 2 * medianUsd;
+      lines.push(loud ? `> ⚠️ ${mdText(`${sentence}${labelClause}`)}` : `_${mdText(`${sentence}${labelClause}`)}_`);
+      lines.push('');
+    }
+
+    /**
+     * The series itself, most recent days last — the shape the peak sentence
+     * summarises, for the reader who wants to see the week. Capped at 14
+     * days with the earlier ones counted out loud: silent truncation reads
+     * as "covered everything" when it did not.
+     */
+    const DAYS_SHOWN = 14;
+    const shown = report.spendByDay.slice(-DAYS_SHOWN);
+    lines.push(`| ${t.profile.dayTableDay()} | USD | ${t.profile.dayTableCalls()} | ${t.profile.dayTableTop()} |`);
+    lines.push('|---|---:|---:|---|');
+    for (const day of shown) {
+      const top = day.topLabel === null ? '—' : mdTextCell(showLabel(day.topLabel));
+      lines.push(`| ${day.day} | ${formatUsd(day.usd)} | ${n(day.calls)} | ${top} |`);
+    }
+    if (report.spendByDay.length > DAYS_SHOWN) {
+      lines.push('');
+      lines.push(`_${mdText(t.profile.dayTableEarlier(report.spendByDay.length - DAYS_SHOWN))}_`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`#### ${t.profile.leversHeading()}`);
+  lines.push('');
+  if (levers.slices.length === 0) {
+    lines.push(mdText(t.profile.leversNone()));
+  } else {
+    for (const slice of levers.slices.slice(0, 5)) {
+      lines.push(
+        `- **${mdText(t.profile.leverSlice(showLabel(slice.label), slice.modelName, formatUsd(slice.combinedUsd), pct(slice.shareOfBill)))}** — ${mdText(t.profile.leverCalls(t.profile.calls(slice.calls), formatUsd(slice.spentUsd)))}`,
+      );
+      if (slice.route) {
+        lines.push(`  - ${mdText(t.profile.leverRoute(slice.route.candidate.displayName, formatUsd(slice.route.savingUsd)))}`);
+      }
+      if (slice.batch) {
+        lines.push(`  - ${mdText(t.profile.leverBatch(formatUsd(slice.batch.savingUsd)))}`);
+      }
+    }
+  }
+  lines.push('');
+  lines.push(`_${mdText(t.profile.leverPromptCeiling(formatUsd(levers.promptCeilingUsd), pct(levers.promptCeilingShare)))}_`);
+  lines.push('');
+
+  /**
+   * The same request sent again — money that bought nothing the call before
+   * it had not already paid for. Loud in a summary, and hedged in the same
+   * words the terminal uses.
+   */
+  if (report.repeatedTurns.length > 0) {
+    lines.push(`#### ${t.profile.repeatsHeading()}`);
+    lines.push('');
+    for (const row of report.repeatedTurns.slice(0, 3)) {
+      lines.push(
+        `> ⚠️ ${mdText(t.profile.repeatsFound(showLabel(row.label), row.modelName, n(row.repeats), n(row.checkedCalls), n(Math.round(row.withinMs / 1000)), formatUsd(row.usd)))}`,
+      );
+      lines.push('');
+    }
+    lines.push(`_${mdText(t.profile.repeatsAdvice())}_`);
+    lines.push('');
+  }
+
+  /**
+   * How big the calls are — the half of the bill the totals table can only
+   * name. Same threshold and same two sentences as the terminal, because a
+   * CI summary that summarises differently is a second opinion nobody asked
+   * for.
+   */
+  if (report.inputShapes.length > 0) {
+    lines.push(`#### ${t.profile.inputShapeHeading()}`);
+    lines.push('');
+    for (const shape of report.inputShapes.slice(0, 3)) {
+      const who = showLabel(shape.label);
+      if (shape.medianWithinTokens === null || shape.p95WithinTokens === null || shape.p95OverMedian === null) {
+        lines.push(`- ${mdText(t.profile.inputHuge(who, shape.modelName, t.profile.calls(shape.calls), formatUsd(shape.inputUsd)))}`);
+        continue;
+      }
+      const skewed = shape.p95OverMedian >= 4;
+      lines.push(
+        `- **${mdText(skewed
+          ? t.profile.inputSkewed(who, shape.modelName, n(shape.medianWithinTokens), n(shape.p95WithinTokens), shape.p95OverMedian.toFixed(1), formatUsd(shape.inputUsd))
+          : t.profile.inputEven(who, shape.modelName, n(shape.medianWithinTokens), n(shape.p95WithinTokens), formatUsd(shape.inputUsd)))}**`,
+      );
+      lines.push(`  - ${mdText(skewed ? t.profile.inputSkewedAdvice() : t.profile.inputEvenAdvice())}`);
+      if (shape.cachedShare >= 0.5) {
+        lines.push(`  - ${mdText(t.profile.inputMostlyCached(pct(shape.cachedShare)))}`);
+      } else if (shape.cachedShare < 0.1) {
+        lines.push(`  - ${mdText(t.profile.inputFullRate())}`);
+      }
+    }
+    lines.push('');
+  }
+
+  /**
+   * The repricing, with the assumption above the figure here too — a pull
+   * request comment is exactly where a dollar amount with the caveat
+   * underneath would be read as a recommendation and merged.
+   */
+  if (whatIf !== undefined && whatIf !== null) {
+    lines.push(`#### ${t.profile.whatIfHeading(whatIf.target.displayName)}`);
+    lines.push('');
+    lines.push(`_${mdText(t.profile.whatIfAssumption())}_`);
+    lines.push('');
+    if (whatIf.slices.length === 0) {
+      lines.push(mdText(t.profile.whatIfNothingToMove()));
+      lines.push('');
+    } else {
+      lines.push(
+        `**${mdText(t.profile.whatIfTotal(formatUsd(whatIf.currentUsd), formatUsd(whatIf.targetUsd), formatUsd(Math.abs(whatIf.deltaUsd))))}**`,
+      );
+      lines.push('');
+      for (const slice of whatIf.slices.slice(0, 5)) {
+        lines.push(`- ${mdText(t.profile.whatIfSlice(showLabel(slice.label), slice.model, formatUsd(slice.currentUsd), formatUsd(slice.targetUsd)))}`);
+      }
+      lines.push('');
+    }
+    for (const slice of whatIf.overContext.slice(0, 3)) {
+      lines.push(
+        `> ⚠️ ${mdText(t.profile.whatIfOverContext(showLabel(slice.label), n(slice.maxCallInputTokens), n(whatIf.target.contextWindow), formatUsd(slice.currentUsd)))}`,
+      );
+      lines.push('');
+    }
+    if (whatIf.alreadyOnTarget.calls > 0) {
+      lines.push(`_${mdText(t.profile.whatIfAlreadyThere(t.profile.calls(whatIf.alreadyOnTarget.calls), formatUsd(whatIf.alreadyOnTarget.usd)))}_`);
+      lines.push('');
+    }
+    if (whatIf.unpricedCalls > 0) {
+      lines.push(`_${mdText(t.profile.whatIfUnpriced(t.profile.calls(whatIf.unpricedCalls), whatIf.unpricedModels.join(', ')))}_`);
+      lines.push('');
+    }
+  }
+
+  // The cache verdict, with the same refusal to answer an unsettled question.
+  const unsettled = cache.worstCaseVerdict !== cache.verdict && report.total.assumedWriteTtlCalls > 0;
+  if (unsettled) {
+    lines.push(`> ⚠️ ${mdText(t.profile.cacheTtlUnsettled(report.total.assumedWriteTtlCalls, formatUsd(-cache.deltaUsd), formatUsd(cache.worstCaseDeltaUsd)))}`);
+    lines.push('');
+  } else if (cache.verdict === 'lost-money') {
+    lines.push(`> ⚠️ ${mdText(t.profile.cacheLost(formatUsd(cache.deltaUsd), n(report.total.cacheWriteTokens), n(report.total.cacheReadTokens)))}`);
+    lines.push('');
+  } else if (cache.verdict === 'paid-off') {
+    lines.push(mdText(t.profile.cachePaidOff(formatUsd(-cache.deltaUsd))));
+    lines.push('');
+  }
+
+  // Whether the TTL fits the gaps — the mechanism behind the verdict above,
+  // with the two failing verdicts loud and the rest quiet, as on the terminal.
+  for (const fit of report.cacheTtlFit.slice(0, 3)) {
+    const who = showLabel(fit.label);
+    const gap = formatGap(fit.medianGapMs);
+    const sentence =
+      fit.verdict === 'expires-before-reuse'
+        ? fit.medianGapMs > TTL_1H_MS
+          ? t.profile.ttlFitExpiresBoth(who, fit.modelName, gap)
+          : t.profile.ttlFitExpires(who, fit.modelName, gap)
+        : fit.verdict === 'overlong-ttl'
+          ? t.profile.ttlFitOverlong(who, fit.modelName, gap, formatUsd(fit.overpayUsd))
+          : fit.verdict === 'unsettled'
+            ? t.profile.ttlFitUnsettledGap(who, fit.modelName, gap)
+            : t.profile.ttlFitFits(who, fit.modelName, gap);
+    const loud = fit.verdict === 'expires-before-reuse' || fit.verdict === 'overlong-ttl';
+    lines.push(loud ? `> ⚠️ ${mdText(sentence)}` : `_${mdText(sentence)}_`);
+    lines.push('');
+  }
+
+  // Conversations that never came back: the fact loud, the ceiling quiet —
+  // decided by the slice's own reads, exactly as on the terminal.
+  const readsBySlice = new Map(
+    report.byLabelAndModel.map((r) => [`${r.label}\n${r.model}`, r.breakdown.cacheReadTokens]),
+  );
+  for (const row of report.singleTurnCacheWrites.slice(0, 3)) {
+    const who = showLabel(row.label);
+    const reads = readsBySlice.get(`${row.label}\n${row.model}`) ?? 0;
+    const sentence =
+      reads === 0
+        ? t.profile.singleTurnConfirmed(who, row.modelName, n(row.singleTurnSessions), n(row.sessions), formatUsd(row.singleTurnWriteUsd))
+        : t.profile.singleTurnCeiling(who, row.modelName, n(row.singleTurnSessions), n(row.sessions), formatUsd(row.singleTurnWriteUsd));
+    lines.push(reads === 0 ? `> ⚠️ ${mdText(sentence)}` : `_${mdText(sentence)}_`);
+    lines.push('');
+  }
+
+  for (const growth of report.conversations.slice(0, 3)) {
+    lines.push(
+      `- ${mdText(t.profile.historyGrowth(showLabel(growth.label), growth.modelName, n(Math.round(growth.minTurnTokens)), n(Math.round(growth.maxTurnTokens)), n(growth.longestSession)))} ${mdText(t.profile.historyCeiling(formatUsd(growth.growthUsd), pct(growth.shareOfBill), formatUsd(growth.flatUsd), formatUsd(growth.inputUsd)))}`,
+    );
+  }
+  if (report.conversations.length > 0) lines.push('');
+
+  if (report.total.truncatedCalls > 0 && report.total.outputUsd > 0) {
+    lines.push(
+      `> ⚠️ ${mdText(t.profile.truncatedWaste(t.profile.calls(report.total.truncatedCalls), formatUsd(report.total.truncatedOutputUsd), pct(report.total.truncatedOutputUsd / report.total.outputUsd)))}`,
+    );
+    lines.push('');
+    // The suspects, with the rate over calls that measured — the terminal's
+    // denominator, because a workload logging the field half the time is not
+    // one whose other half completed.
+    const truncatedLabels = report.byLabel
+      .filter((row) => row.breakdown.truncatedCalls > 0)
+      .sort((a, b) => b.breakdown.truncatedOutputUsd - a.breakdown.truncatedOutputUsd);
+    if (truncatedLabels.length > 0 && report.byLabel.length > 1) {
+      for (const row of truncatedLabels.slice(0, 3)) {
+        lines.push(
+          `- ${mdText(t.profile.truncatedBy(showLabel(row.label), n(row.breakdown.truncatedCalls), n(row.breakdown.stopReasonCalls), pct(row.breakdown.truncatedCalls / row.breakdown.stopReasonCalls), formatUsd(row.breakdown.truncatedOutputUsd)))}`,
+        );
+      }
+      lines.push('');
+    }
+    const truncationCeiling = report.outputShapes.find((shape) => shape.p95WithinTokens !== null);
+    if (truncationCeiling !== undefined) {
+      lines.push(`_${mdText(t.profile.truncatedCeiling(n(truncationCeiling.p95WithinTokens!)))}_`);
+      lines.push('');
+    }
+  }
+
+  /**
+   * This bill against the previous one. The convention prints before the
+   * first figure it governs, and the overlap warning between the figure and
+   * the drivers built from it — the terminal's order, for the terminal's
+   * reason: a caveat below a number is a number somebody already acted on.
+   */
+  if (against !== undefined) {
+    lines.push(`#### ${t.profile.againstHeading()}`);
+    lines.push('');
+    if (against.nothingPriced) {
+      lines.push(mdText(t.profile.againstNothingPriced()));
+      lines.push('');
+    } else {
+      const delta = report.total.totalUsd - against.previousTotalUsd;
+      const growthPct =
+        against.previousTotalUsd > 0
+          ? `${delta >= 0 ? '+' : ''}${((delta / against.previousTotalUsd) * 100).toFixed(1)}%`
+          : '—';
+      lines.push(
+        `**${mdText(t.profile.againstTotals(formatUsd(against.previousTotalUsd), formatUsd(report.total.totalUsd), formatSignedUsd(delta), growthPct, t.profile.calls(against.previousCalls), t.profile.calls(report.total.calls)))}**`,
+      );
+      lines.push('');
+      if (against.overlap !== null) {
+        lines.push(`> ⚠️ ${mdText(t.profile.againstOverlap(against.overlap.from, against.overlap.to))}`);
+        lines.push('');
+      }
+      const describe = (driver: AgainstDriver, shown: string): string =>
+        driver.was === null
+          ? t.profile.againstDriverNew(formatSignedUsd(driver.delta), shown)
+          : driver.now === null
+            ? t.profile.againstDriverGone(formatSignedUsd(driver.delta), shown)
+            : t.profile.againstDriver(formatSignedUsd(driver.delta), shown, formatUsd(driver.was), formatUsd(driver.now));
+      for (const driver of against.labelDrivers.slice(0, 5)) {
+        lines.push(`- ${mdText(describe(driver, showLabel(driver.key)))}`);
+      }
+      if (against.modelDrivers.length > 0) {
+        lines.push('');
+        lines.push(`_${mdText(t.profile.againstByModel())}_`);
+        for (const driver of against.modelDrivers.slice(0, 3)) {
+          lines.push(`- ${mdText(describe(driver, driver.key))}`);
+        }
+      }
+      lines.push('');
+    }
+  }
+
+  // The provenance caveat before the data gaps: a stale table qualifies every
+  // dollar above, and it does not name its own size the way a skipped line does.
+  if (stalePricing !== undefined) {
+    lines.push(`> ⚠️ ${mdText(t.profile.pricesStale(stalePricing.date, stalePricing.days))}`);
+    lines.push('');
+  }
+  if (report.unpricedModels.length > 0) {
+    lines.push(`> ⚠️ ${mdText(t.profile.unpriced(report.unpricedModels.join(', '), report.unpriced.calls))}`);
+    lines.push('');
+  }
+  if (report.skippedLines.length > 0) {
+    const shown = report.skippedLines.slice(0, 5).join(', ');
+    lines.push(`_${mdText(t.profile.skipped(report.skippedLines.length, report.skippedLines.length > 5 ? `${shown}…` : shown))}_`);
+    lines.push('');
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}

package/src/time.ts

@@ -0,0 +1,32 @@
+/**
+ * The clock's little formatters, shared by the terminal and the markdown
+ * renderings so the two cannot drift — the same reason `formatUsd` lives once.
+ */
+
+/** A gap, in the coarsest unit that keeps one significant figure honest. */
+export function formatGap(ms: number): string {
+  if (ms < 90_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 90 * 60_000) return `${Math.round(ms / 60_000)}m`;
+  if (ms < 36 * 3_600_000) return `${(ms / 3_600_000).toFixed(1)}h`;
+  return `${(ms / 86_400_000).toFixed(1)}d`;
+}
+
+/** `YYYY-MM-DD`, UTC — the same bucketing the core's spendByDay uses. */
+export const dayOf = (ms: number): string => new Date(ms).toISOString().slice(0, 10);
+
+/** The span's length in days, one decimal. */
+export const spanDays = (fromMs: number, toMs: number): string =>
+  ((toMs - fromMs) / 86_400_000).toFixed(1);
+
+/**
+ * The median of a list, the yardstick a spike cannot inflate.
+ *
+ * A mean would let the most expensive day raise the bar it is measured
+ * against; the median holds still. Returns 0 for an empty list.
+ */
+export function median(values: readonly number[]): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1 ? sorted[mid]! : (sorted[mid - 1]! + sorted[mid]!) / 2;
+}