@trazum/cli 1.36.0 → 1.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.36.0",
+  "version": "1.37.0",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.36.0"
+    "@trazum/core": "1.37.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -78,6 +78,16 @@ ${bold('OPTIONS FOR rank')}
   --model, --calls,           Price the recoverable tokens, as in optimize.
   --output-tokens, --batch
   --prompt <name>             Which marked prompt to take from each source file.
+  --by-source                 The fleet: one summary per service from the
+                              config's "sources" block (name → glob patterns
+                              over log paths), plus a rollup naming the source
+                              where the money is. Shares compare totals, and
+                              when the sources' logs cover different periods
+                              the report says so rather than letting a 3-day
+                              log look cheap beside a 30-day one. Budgets per
+                              service live in spend.bySource and fail the run
+                              naming the service. Files matching no pattern
+                              are named, never silently dropped.
   --markdown-out <file>       Also write the ranking as Markdown, for a CI job
                               summary or a pull request comment.
   --json                      The ranking as data.
@@ -1227,6 +1237,31 @@ ${bold('EXAMPLES')}
       'A ✗ is not a defect in the log; it is a finding this log cannot support yet. The README\'s recording recipe carries every field above.',
     dryRunNoGates: () =>
       '--dry-run produces no bill, so a gate beside it would exit green having judged nothing. Run the gates without --dry-run.',
+    bySourceNeedsConfig: () =>
+      '--by-source reads the "sources" block in trazum.config.json — a name per service, each with glob patterns over log paths — and this config has none. Name at least one source.',
+    bySourceNothingMatched: (sources) =>
+      'No log file matched any source pattern. The sources configured: ${sources}. Patterns match the paths as given on the command line.'.replace('${sources}', sources),
+    fleetHeading: (count, total, calls) => `The fleet: ${count} sources · ${total} · ${calls}`,
+    fleetRow: (name, usd, share, calls, span) => `${name}  ${usd}  ${share} of the fleet · ${calls} · ${span}`,
+    fleetSpan: (days) => `${days} days`,
+    fleetNoClock: () => 'no clock',
+    fleetWorst: (name, usd, share) =>
+      `${name} is where the money is: ${usd}, ${share} of the fleet's total.`,
+    fleetMismatchedSpans: () =>
+      'These sources cover different periods, so the shares above compare totals, not rates — a 3-day log looks cheap next to a 30-day one for reasons that have nothing to do with cost. Each row states its own span.',
+    fleetSplitBrain: (label, detail) =>
+      `The same workload runs on different models in different sources — ${label}: ${detail}. Same job, different rate cards; whether that is a decision or an accident is not in the logs.`,
+    fleetCacheUnderwater: (name, usd) =>
+      `Caching pays for the fleet overall but loses ${usd} in ${name} — the aggregate verdict was hiding it.`,
+    fleetUnmatched: (file) =>
+      `${file} matched no source pattern, so it is in no report above — spend missing from every bill until a pattern covers it.`,
+    fleetFooter: () =>
+      'Summaries per source; the full report for one service is "trazum profile <its logs>". Same thresholds, same findings, one source at a time.',
+    fleetBudgetOk: (name, usd, max) => `Within budget: ${name} spent ${usd} against its ${max} in spend.bySource.`,
+    fleetBudgetFailed: (name, usd, max) =>
+      `FAILED — ${name} spent ${usd} against its budget of ${max} in spend.bySource. The fleet total can be fine while one service bleeds; this gate names which.`,
+    fleetBudgetMissing: (name) =>
+      `${name} has a budget in spend.bySource and no logs matched it in this run, so nothing was measured for it. Not a pass: a service that did not appear is not a service under budget.`,
     coverageHeading: () => 'What this log cannot answer yet',
     needsLabel: (seen) =>
       `"label" on ${seen} records: without it every workload is one row, so no per-workload spend, no drill-down, and the levers describe a mixture rather than a decision.`,

package/src/i18n/es.ts

@@ -66,6 +66,18 @@ ${bold('OPCIONES DE rank')}
   --model, --calls,           Calcula el coste de los tokens recuperables, como
   --output-tokens, --batch    en optimize.
   --prompt <nombre>           Qué prompt marcado tomar de cada fichero de código.
+  --by-source                 La flota: un resumen por servicio desde el
+                              bloque "sources" de la config (nombre → patrones
+                              glob sobre rutas de registros), más un rollup
+                              que nombra la fuente donde está el dinero. Los
+                              porcentajes comparan totales, y cuando los
+                              registros cubren periodos distintos el informe
+                              lo dice en vez de dejar que un registro de 3
+                              días parezca barato junto a uno de 30. Los
+                              presupuestos por servicio viven en
+                              spend.bySource y hacen fallar la ejecución
+                              nombrando el servicio. Los ficheros sin patrón
+                              se nombran, nunca se descartan en silencio.
   --markdown-out <fichero>    Escribe además el ranking en Markdown, para el
                               resumen de un job de CI o un comentario de PR.
   --json                      El ranking como datos.
@@ -1243,6 +1255,31 @@ ${bold('EJEMPLOS')}
       'Una ✗ no es un defecto del registro; es un hallazgo que este registro aún no puede sostener. La receta de registro del README lleva todos los campos de arriba.',
     dryRunNoGates: () =>
       '--dry-run no produce factura, así que un gate a su lado saldría en verde sin haber juzgado nada. Corre los gates sin --dry-run.',
+    bySourceNeedsConfig: () =>
+      '--by-source lee el bloque "sources" de trazum.config.json — un nombre por servicio, cada uno con patrones glob sobre rutas de registros — y esta config no tiene ninguno. Nombra al menos una fuente.',
+    bySourceNothingMatched: (sources) =>
+      'Ningún fichero de registro coincidió con ningún patrón de fuente. Las fuentes configuradas: ${sources}. Los patrones casan con las rutas tal como se dan en la línea de comandos.'.replace('${sources}', sources),
+    fleetHeading: (count, total, calls) => `La flota: ${count} fuentes · ${total} · ${calls}`,
+    fleetRow: (name, usd, share, calls, span) => `${name}  ${usd}  ${share} de la flota · ${calls} · ${span}`,
+    fleetSpan: (days) => `${days} días`,
+    fleetNoClock: () => 'sin reloj',
+    fleetWorst: (name, usd, share) =>
+      `${name} es donde está el dinero: ${usd}, el ${share} del total de la flota.`,
+    fleetMismatchedSpans: () =>
+      'Estas fuentes cubren periodos distintos, así que los porcentajes de arriba comparan totales, no ritmos — un registro de 3 días parece barato junto a uno de 30 por motivos que nada tienen que ver con el coste. Cada fila indica su propio periodo.',
+    fleetSplitBrain: (label, detail) =>
+      `La misma carga corre en modelos distintos en fuentes distintas — ${label}: ${detail}. Mismo trabajo, tarifas distintas; si es una decisión o un accidente no está en los registros.`,
+    fleetCacheUnderwater: (name, usd) =>
+      `La caché es rentable para la flota en conjunto pero pierde ${usd} en ${name} — el veredicto agregado lo escondía.`,
+    fleetUnmatched: (file) =>
+      `${file} no coincidió con ningún patrón de fuente, así que no está en ningún informe de arriba — gasto ausente de todas las facturas hasta que un patrón lo cubra.`,
+    fleetFooter: () =>
+      'Resúmenes por fuente; el informe completo de un servicio es "trazum profile <sus registros>". Mismos umbrales, mismos hallazgos, una fuente cada vez.',
+    fleetBudgetOk: (name, usd, max) => `Dentro de presupuesto: ${name} gastó ${usd} contra su ${max} en spend.bySource.`,
+    fleetBudgetFailed: (name, usd, max) =>
+      `FALLÓ — ${name} gastó ${usd} contra su presupuesto de ${max} en spend.bySource. El total de la flota puede estar bien mientras un servicio sangra; este gate nombra cuál.`,
+    fleetBudgetMissing: (name) =>
+      `${name} tiene presupuesto en spend.bySource y ningún registro coincidió con él en esta ejecución, así que no se midió nada. No es un aprobado: un servicio que no apareció no es un servicio dentro de presupuesto.`,
     coverageHeading: () => 'Lo que este registro todavía no puede responder',
     needsLabel: (seen) =>
       `"label" en ${seen} registros: sin él todas las cargas son una sola fila, así que no hay gasto por carga, ni zoom, y las palancas describen una mezcla en vez de una decisión.`,

package/src/i18n/types.ts

@@ -975,6 +975,26 @@ export interface CliMessages {
     dryRunNoCacheTraffic(): string;
     dryRunFooter(): string;
     dryRunNoGates(): string;
+    /**
+     * `--by-source`: the fleet. One summary per service, the rollup naming
+     * the worst offender, cross-source findings a merged bill cannot make,
+     * and per-source budgets that fail naming the service.
+     */
+    bySourceNeedsConfig(): string;
+    bySourceNothingMatched(sources: string): string;
+    fleetHeading(count: string, total: string, calls: string): string;
+    fleetRow(name: string, usd: string, share: string, calls: string, span: string): string;
+    fleetSpan(days: string): string;
+    fleetNoClock(): string;
+    fleetWorst(name: string, usd: string, share: string): string;
+    fleetMismatchedSpans(): string;
+    fleetSplitBrain(label: string, detail: string): string;
+    fleetCacheUnderwater(name: string, usd: string): string;
+    fleetUnmatched(file: string): string;
+    fleetFooter(): string;
+    fleetBudgetOk(name: string, usd: string, max: string): string;
+    fleetBudgetFailed(name: string, usd: string, max: string): string;
+    fleetBudgetMissing(name: string): string;
     coverageHeading(): string;
     needsLabel(seen: string): string;
     needsSession(seen: string): string;

package/src/index.ts

@@ -23,6 +23,8 @@ import {
   coverageDrift,
   driversBetween,
   explainGateFailure,
+  assignSources,
+  fleetRollup,
   labelCoverage,
   measuredUsage,
   gateMargin,
@@ -74,6 +76,7 @@ import {
 import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
 import { dayOf, formatGap, median, spanDays } from './time.js';
 import type {
+  FleetSource,
   MeasuredUsage,
   BaselineBreach,
   BaselineChange,
@@ -461,7 +464,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   ],
   check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline'],
   baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
-  profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd', 'label', 'since', 'until', 'dry-run', 'markdown-summary'],
+  profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd', 'label', 'since', 'until', 'dry-run', 'markdown-summary', 'by-source'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2241,10 +2244,17 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
   const target = await stat(path).catch(() => null);
   let logFiles: string[] = [path];
   if (target?.isDirectory()) {
-    const entries = await readdir(path, { withFileTypes: true });
+    /**
+     * Recursive under `--by-source`, flat otherwise. The fleet's whole point
+     * is one directory per service, so the walk must descend; the flat mode
+     * keeps its long-standing behaviour because a directory of rotated logs
+     * with an unrelated subfolder should not quietly absorb it.
+     */
+    const bySourceMode = boolFlag(args, 'by-source');
+    const entries = await readdir(path, { withFileTypes: true, recursive: bySourceMode });
     logFiles = entries
       .filter((entry) => entry.isFile() && READABLE.some((ext) => entry.name.endsWith(ext)))
-      .map((entry) => join(path, entry.name))
+      .map((entry) => join(entry.parentPath ?? path, entry.name))
       .sort((a, b) => a.localeCompare(b));
     if (logFiles.length === 0) {
       throw new Error(t.profile.noLogsInDirectory(path, READABLE.join(', ')));
@@ -2266,6 +2276,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
   // A file that does not end in a newline would otherwise glue its last record
   // to the next file's first one, and both would be reported as unreadable.
   const raw = logTexts.map((text) => (text.endsWith('\n') ? text : `${text}\n`)).join('');
+
   /**
    * The drill-down. A label that matches nothing is an error naming the labels
    * that exist — the route command's rule, for the route command's reason: a
@@ -2368,6 +2379,123 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const pct = (share: number): string => `${(share * 100).toFixed(1)}%`;
 
+  /**
+   * `--by-source`: one report per service, plus the rollup — the fleet.
+   *
+   * A merged bill is right for one service and wrong for twelve: it hides
+   * which service the money comes from, per-service budgets cannot exist,
+   * and the findings a comparison between services could make are invisible.
+   * Files are assigned to sources by the most specific matching glob from the
+   * config's `sources` block; a file matching no source is named loudly,
+   * because a log that silently joined no report is spend missing from every
+   * bill.
+   */
+  if (boolFlag(args, 'by-source')) {
+    const sourceDefs = config.sources;
+    if (sourceDefs === undefined || Object.keys(sourceDefs).length === 0) {
+      throw new Error(t.profile.bySourceNeedsConfig());
+    }
+    const { bySource, unmatched } = assignSources(logFiles, sourceDefs);
+    if (bySource.size === 0) {
+      throw new Error(t.profile.bySourceNothingMatched(Object.keys(sourceDefs).join(', ')));
+    }
+
+    const textByFile = new Map(logFiles.map((file, i) => [file, logTexts[i]!]));
+    const fleetSources: FleetSource[] = [];
+    const cacheDeltas = new Map<string, number>();
+    for (const [name, files] of [...bySource.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+      const text = files
+        .map((file) => textByFile.get(file)!)
+        .map((chunk) => (chunk.endsWith('\n') ? chunk : `${chunk}\n`))
+        .join('');
+      const sourceReport = profileUsage(text, { catalogue: pricing, label: onlyLabel, sinceMs, untilMs });
+      fleetSources.push({ name, report: sourceReport });
+      cacheDeltas.set(name, cacheEconomics(sourceReport.total).deltaUsd);
+    }
+    const aggregate = profileUsage(raw, { catalogue: pricing, label: onlyLabel, sinceMs, untilMs });
+    const rollup = fleetRollup(fleetSources, {
+      cacheDeltas,
+      aggregateCacheDelta: cacheEconomics(aggregate.total).deltaUsd,
+    });
+
+    if (boolFlag(args, 'json')) {
+      console.log(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            bySource: fleetSources.map((source) => ({ name: source.name, report: source.report })),
+            rollup: {
+              totalUsd: rollup.totalUsd,
+              calls: rollup.calls,
+              sources: rollup.sources,
+              worst: rollup.worst,
+              mismatchedSpans: rollup.mismatchedSpans,
+              splitBrains: rollup.splitBrains,
+              cacheUnderwater: rollup.cacheUnderwater,
+              unmatchedFiles: unmatched,
+            },
+          },
+          (key, value) => (value instanceof Map ? undefined : value),
+          2,
+        ),
+      );
+    } else {
+      console.log(c.bold(t.profile.fleetHeading(n(rollup.sources.length), formatUsd(rollup.totalUsd), t.profile.calls(rollup.calls))));
+      for (const row of rollup.sources) {
+        const span = row.spanDays === null ? t.profile.fleetNoClock() : t.profile.fleetSpan(row.spanDays.toFixed(1));
+        console.log(
+          `  ${t.profile.fleetRow(row.name, formatUsd(row.usd), pct(row.share), t.profile.calls(row.calls), span)}`,
+        );
+      }
+      if (rollup.worst !== null && rollup.sources.length > 1) {
+        console.log();
+        console.log(`  ${c.yellow('!')} ${c.bold(wrap(t.profile.fleetWorst(rollup.worst.name, formatUsd(rollup.worst.usd), pct(rollup.worst.share)), 74, '    '))}`);
+      }
+      if (rollup.mismatchedSpans) {
+        console.log(`  ${c.dim(wrap(t.profile.fleetMismatchedSpans(), 74, '  '))}`);
+      }
+      for (const split of rollup.splitBrains.slice(0, 3)) {
+        console.log();
+        console.log(
+          `  ${c.yellow('!')} ${wrap(t.profile.fleetSplitBrain(split.label, split.sources.map((v) => `${v.name} → ${v.model} (${formatUsd(v.usd)})`).join(', ')), 74, '    ')}`,
+        );
+      }
+      for (const under of rollup.cacheUnderwater.slice(0, 3)) {
+        console.log(
+          `  ${c.yellow('!')} ${wrap(t.profile.fleetCacheUnderwater(under.name, formatUsd(under.deltaUsd)), 74, '    ')}`,
+        );
+      }
+      for (const file of unmatched) {
+        console.log(`  ${c.yellow('!')} ${wrap(t.profile.fleetUnmatched(file), 74, '    ')}`);
+      }
+      console.log();
+      console.log(`  ${c.dim(wrap(t.profile.fleetFooter(), 74, '  '))}`);
+    }
+
+    /**
+     * The per-source gates. Each budget judges its own service and the run
+     * fails naming the service — a total that hides which source crossed its
+     * line is the rendering this mode exists to end. Waivable per source
+     * through `bySource:<name>`, under the same expiry discipline.
+     */
+    const bySourceBudgets = config.spend?.bySource ?? {};
+    for (const [name, limit] of Object.entries(bySourceBudgets)) {
+      const found = fleetSources.find((source) => source.name === name);
+      if (found === undefined) {
+        console.error(c.dim(t.profile.fleetBudgetMissing(name)));
+        continue;
+      }
+      const usd = found.report.total.totalUsd;
+      if (usd > limit) {
+        console.error(c.red(t.profile.fleetBudgetFailed(name, formatUsd(usd), formatUsd(limit))));
+        process.exitCode = 1;
+      } else {
+        console.error(c.dim(t.profile.fleetBudgetOk(name, formatUsd(usd), formatUsd(limit))));
+      }
+    }
+    return;
+  }
+
   /**
    * `--dry-run`: what this log could and could not answer, and no bill.
    *