@trazum/cli 1.50.10 → 1.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trazum/cli",
3
- "version": "1.50.10",
3
+ "version": "1.51.0",
4
4
  "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
5
5
  "license": "MIT",
6
6
  "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
37
37
  "prepublishOnly": "npm run build && npm test"
38
38
  },
39
39
  "dependencies": {
40
- "@trazum/core": "1.50.10"
40
+ "@trazum/core": "1.51.0"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
package/src/i18n/en.ts CHANGED
@@ -61,6 +61,8 @@ ${bold('USAGE')}
61
61
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
62
62
  trazum quality <log> --label <name> --at <iso> [--gate]
63
63
  trazum semantic <prompt> [--yes]
64
+ trazum commitment <log> --floor <usd> --discount <pct> [--months 12]
65
+ trazum report <log> --year <yyyy>
64
66
  trazum owners <log>
65
67
  trazum ladder <log>
66
68
  trazum feedback
@@ -160,6 +162,26 @@ ${bold('OPTIONS FOR semantic')}
160
162
  pairs the rules engine already catches are dropped, and every token figure is
161
163
  counted rather than believed. Optional, and always will be.
162
164
 
165
+ ${bold('OPTIONS FOR commitment')}
166
+ --floor <usd> What you commit to spending each month, after
167
+ the discount. Required.
168
+ --discount <pct> What you get off list. 20 and 0.2 both work.
169
+ --months <n> How long the deal runs. Defaults to 12.
170
+
171
+ Replays measured whole months against the deal's terms. Both directions are
172
+ priced: the months that cleared the floor, and what the floor cost in the
173
+ months that fell short — kept as its own figure, because netted into the
174
+ saving it disappears. An as-if calculation about the past, never a forecast.
175
+
176
+ ${bold('OPTIONS FOR report')}
177
+ --year <yyyy> Required. Which year to assemble.
178
+ --json Also emit the record as JSON.
179
+
180
+ Everything comes from the store and the plans you already keep — nothing is
181
+ computed that cannot be checked against a document that already exists.
182
+ Months with no record are named rather than filled, promises are kept in
183
+ three outcomes rather than two, and the report lists what it cannot say.
184
+
163
185
  ${bold('OPTIONS FOR prune')}
164
186
  --cases <file> One input per line, or a JSON array. Required.
165
187
  --yes Actually spend the calls. Without it the estimate is
@@ -1011,6 +1033,67 @@ ${bold('EXAMPLES')}
1011
1033
  `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
1012
1034
  },
1013
1035
 
1036
+ annual: {
1037
+ heading: (year) => `The year ${year}, from what was already written down`,
1038
+ needsYear: () => '--year is required, as four digits: trazum report <log> --year 2026.',
1039
+ spent: (usd, calls, months) => `${usd} across ${calls} calls, over ${months} recorded months.`,
1040
+ missing: (months) =>
1041
+ `No record at all for ${months}. Those months are named rather than filled: a year that quietly covers part of itself and prints an annual total is wrong by the rest and says nothing about it.`,
1042
+ promises: (planned, arrived, notArrived, cannotTell) =>
1043
+ `${planned} actions planned. ${arrived} arrived, ${notArrived} did not, and ${cannotTell} could not be judged. Three outcomes, never two \u2014 the third is the one an ordinary annual report folds into the flattering one.`,
1044
+ projected: (usd) => `The plans projected ${usd} of savings.`,
1045
+ noArrivedFigure: () =>
1046
+ 'There is deliberately no figure beside it for what arrived. A verification says WHETHER each action landed; it has never carried a per-action dollar figure for the saving. Assembling one here would mean deciding which of several observed numbers is "the saving" \u2014 a judgement the verification refused to make, and exactly the annual-report arithmetic this document replaces.',
1047
+ outcomes: (recorded, parsed, unrecordedUsd) =>
1048
+ `${recorded} of ${parsed} calls recorded an outcome; ${unrecordedUsd} of the year\u2019s spend did not.`,
1049
+ noOutcomes: () =>
1050
+ 'No outcome was recorded this year, so nothing here says what the money bought. That is not a success rate of zero \u2014 an uninstrumented year and a failing year are different sentences.',
1051
+ cannotSayHeading: () => 'What this record cannot say',
1052
+ cannotSay: (kind) =>
1053
+ kind === 'months-missing'
1054
+ ? 'what happened in the months with no record'
1055
+ : kind === 'nothing-was-planned'
1056
+ ? 'whether anything was promised, because no plan was made'
1057
+ : kind === 'nothing-was-verified'
1058
+ ? 'whether the promises were kept, because no plan was verified'
1059
+ : kind === 'some-promises-unjudgeable'
1060
+ ? 'whether some promises were kept \u2014 they could not be judged from the logs that exist'
1061
+ : kind === 'arrived-savings-not-quantified'
1062
+ ? 'how many dollars the kept promises were worth'
1063
+ : kind === 'no-outcomes-recorded'
1064
+ ? 'what any of the money bought'
1065
+ : 'what the uninstrumented share of the traffic did',
1066
+ noNewData: () =>
1067
+ 'Every figure above comes from the store and the plans you already keep. Nothing was computed here that cannot be checked against a document that already exists \u2014 which is the only reason an annual report is worth trusting, since it is the document most likely to be quoted out of the room it was written in.',
1068
+ },
1069
+
1070
+ commitment: {
1071
+ heading: (floor, discount, months) =>
1072
+ `A ${months}-month commitment: ${floor} a month at ${discount} off`,
1073
+ needsTerms: () =>
1074
+ '--floor and --discount are required, and --months defaults to 12. Take them from the contract the provider is offering you: the floor is what you commit to spending each month after the discount, and the discount is what you get off list.',
1075
+ asIf: () =>
1076
+ 'This is what the deal WOULD HAVE done on the traffic you actually had. It is a measurement of the past, not a prediction \u2014 every month below happened.',
1077
+ columns: { month: 'month', list: 'list', paid: 'would pay', saving: 'saving' },
1078
+ net: (usd, months) => `Net over ${months} measured months: ${usd}.`,
1079
+ good: (usd) => `The months that cleared the floor saved ${usd}.`,
1080
+ lost: (usd, months) =>
1081
+ `${months} of them fell short, and the floor you would have paid for capacity nobody used comes to ${usd}. That figure is kept separate on purpose: netted into the line above it disappears, and the disappearing is what a vendor\u2019s slide relies on.`,
1082
+ noShortfall: () => 'No measured month would have fallen short of the floor.',
1083
+ breakEven: (usd) =>
1084
+ `Break-even is ${usd} of monthly spend. Below it you pay the floor for less usage than it buys; above it the saving grows.`,
1085
+ spread: (low, high, median) =>
1086
+ `Measured spread: ${low} to ${high}, median ${median}. That is the shortfall risk in the only form a log can state it \u2014 a count of real months and the range they covered, rather than a probability from a distribution nobody fitted.`,
1087
+ shortTerm: (covered, term) =>
1088
+ `This replays ${covered} months against a ${term}-month commitment. It is a real answer about ${covered} months and not about ${term}.`,
1089
+ cannotTell: (why, needed) =>
1090
+ why === 'no-history'
1091
+ ? 'Nothing to replay: this log has no whole months in it.'
1092
+ : `Cannot judge this from ${needed === '0' ? 'what exists' : `what exists \u2014 ${needed} more whole month(s) would settle it`}. A commitment is signed for a year, and an answer from one month is a year-long decision made on a fortnight of evidence.`,
1093
+ neverAForecast: () =>
1094
+ 'Nothing here is annualised, extrapolated or fitted to a trend. If next quarter looks nothing like last quarter, this arithmetic says nothing about it \u2014 which is the honest limit of what a log can tell you about a contract.',
1095
+ },
1096
+
1014
1097
  owners: {
1015
1098
  heading: () => 'Whose money',
1016
1099
  noOwners: () =>
package/src/i18n/es.ts CHANGED
@@ -48,6 +48,8 @@ ${bold('USO')}
48
48
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
49
49
  trazum quality <log> --label <name> --at <iso> [--gate]
50
50
  trazum semantic <prompt> [--yes]
51
+ trazum commitment <log> --floor <usd> --discount <pct> [--months 12]
52
+ trazum report <log> --year <yyyy>
51
53
  trazum owners <log>
52
54
  trazum ladder <log>
53
55
  trazum feedback
@@ -150,6 +152,27 @@ ${bold('OPCIONES DE semantic')}
150
152
  carácter contra el prompt, los pares que el motor de reglas ya caza se
151
153
  descartan, y toda cifra de tokens se cuenta en vez de creérsela.
152
154
 
155
+ ${bold('OPCIONES DE commitment')}
156
+ --floor <usd> Lo que te comprometes a gastar cada mes, después
157
+ del descuento. Obligatorio.
158
+ --discount <pct> Lo que te quitan de tarifa. Vale 20 y vale 0.2.
159
+ --months <n> Cuánto dura el acuerdo. Por defecto 12.
160
+
161
+ Replica los meses completos medidos contra las condiciones del acuerdo. Se
162
+ tarifan las dos direcciones: los meses que superaron el suelo, y lo que
163
+ costó el suelo en los meses que se quedaron cortos — como cifra aparte,
164
+ porque metida en el ahorro desaparece. Un cálculo sobre el pasado, nunca una
165
+ previsión.
166
+
167
+ ${bold('OPCIONES DE report')}
168
+ --year <yyyy> Obligatorio. Qué año montar.
169
+ --json Emite también el registro como JSON.
170
+
171
+ Todo sale del almacén y de los planes que ya guardas — no se calcula nada
172
+ que no se pueda comprobar contra un documento que ya existe. Los meses sin
173
+ registro se nombran en vez de rellenarse, las promesas se cuentan en tres
174
+ resultados y no en dos, y el informe lista lo que no puede decir.
175
+
153
176
  ${bold('OPCIONES DE prune')}
154
177
  --cases <fichero> Una entrada por línea, o un array JSON. Obligatorio.
155
178
  --yes Gasta las llamadas de verdad. Sin él se imprime la
@@ -1047,6 +1070,67 @@ ${bold('EJEMPLOS')}
1047
1070
  `${path} existe y no se pudo interpretar, así que no se escribió nada encima. Arréglalo o muévelo primero.`,
1048
1071
  },
1049
1072
 
1073
+ annual: {
1074
+ heading: (year) => `El a\u00f1o ${year}, a partir de lo que ya estaba escrito`,
1075
+ needsYear: () => '--year es obligatorio, con cuatro d\u00edgitos: trazum report <log> --year 2026.',
1076
+ spent: (usd, calls, months) => `${usd} en ${calls} llamadas, sobre ${months} meses registrados.`,
1077
+ missing: (months) =>
1078
+ `Sin ning\u00fan registro de ${months}. Esos meses se nombran en vez de rellenarse: un a\u00f1o que cubre parte de s\u00ed mismo en silencio e imprime un total anual est\u00e1 equivocado en el resto y no dice nada al respecto.`,
1079
+ promises: (planned, arrived, notArrived, cannotTell) =>
1080
+ `${planned} acciones planeadas. ${arrived} llegaron, ${notArrived} no, y ${cannotTell} no se pudieron juzgar. Tres resultados, nunca dos \u2014 el tercero es el que un informe anual normal mete dentro del que favorece.`,
1081
+ projected: (usd) => `Los planes proyectaron ${usd} de ahorro.`,
1082
+ noArrivedFigure: () =>
1083
+ 'A prop\u00f3sito no hay una cifra al lado de lo que lleg\u00f3. Una verificaci\u00f3n dice SI cada acci\u00f3n aterriz\u00f3; nunca ha llevado una cifra en d\u00f3lares por acci\u00f3n del ahorro. Montarla aqu\u00ed significar\u00eda decidir cu\u00e1l de varios n\u00fameros observados es "el ahorro" \u2014 un juicio que la verificaci\u00f3n se neg\u00f3 a hacer, y justo la aritm\u00e9tica de informe anual que este documento sustituye.',
1084
+ outcomes: (recorded, parsed, unrecordedUsd) =>
1085
+ `${recorded} de ${parsed} llamadas registraron un resultado; ${unrecordedUsd} del gasto del a\u00f1o no.`,
1086
+ noOutcomes: () =>
1087
+ 'No se registr\u00f3 ning\u00fan resultado este a\u00f1o, as\u00ed que nada de esto dice qu\u00e9 compr\u00f3 el dinero. Eso no es una tasa de \u00e9xito de cero \u2014 un a\u00f1o sin instrumentar y un a\u00f1o que falla son frases distintas.',
1088
+ cannotSayHeading: () => 'Lo que este registro no puede decir',
1089
+ cannotSay: (kind) =>
1090
+ kind === 'months-missing'
1091
+ ? 'qu\u00e9 pas\u00f3 en los meses sin registro'
1092
+ : kind === 'nothing-was-planned'
1093
+ ? 'si se prometi\u00f3 algo, porque no se hizo ning\u00fan plan'
1094
+ : kind === 'nothing-was-verified'
1095
+ ? 'si se cumplieron las promesas, porque no se verific\u00f3 ning\u00fan plan'
1096
+ : kind === 'some-promises-unjudgeable'
1097
+ ? 'si algunas promesas se cumplieron \u2014 no se pudieron juzgar con los logs que existen'
1098
+ : kind === 'arrived-savings-not-quantified'
1099
+ ? 'cu\u00e1ntos d\u00f3lares val\u00edan las promesas cumplidas'
1100
+ : kind === 'no-outcomes-recorded'
1101
+ ? 'qu\u00e9 compr\u00f3 nada de ese dinero'
1102
+ : 'qu\u00e9 hizo la parte del tr\u00e1fico sin instrumentar',
1103
+ noNewData: () =>
1104
+ 'Todas las cifras de arriba salen del almac\u00e9n y de los planes que ya guardas. Aqu\u00ed no se ha calculado nada que no se pueda comprobar contra un documento que ya existe \u2014 que es la \u00fanica raz\u00f3n por la que un informe anual merece confianza, siendo el documento con m\u00e1s probabilidad de acabar citado fuera de la sala donde se escribi\u00f3.',
1105
+ },
1106
+
1107
+ commitment: {
1108
+ heading: (floor, discount, months) =>
1109
+ `Un compromiso de ${months} meses: ${floor} al mes con ${discount} de descuento`,
1110
+ needsTerms: () =>
1111
+ '--floor y --discount son obligatorios, y --months son 12 por defecto. S\u00e1calos del contrato que te ofrecen: el suelo es lo que te comprometes a gastar cada mes despu\u00e9s del descuento, y el descuento es lo que te quitan de tarifa.',
1112
+ asIf: () =>
1113
+ 'Esto es lo que el acuerdo HABR\u00cdA hecho sobre el tr\u00e1fico que realmente tuviste. Es una medici\u00f3n del pasado, no una predicci\u00f3n \u2014 todos los meses de abajo ocurrieron.',
1114
+ columns: { month: 'mes', list: 'tarifa', paid: 'pagar\u00edas', saving: 'ahorro' },
1115
+ net: (usd, months) => `Neto sobre ${months} meses medidos: ${usd}.`,
1116
+ good: (usd) => `Los meses que superaron el suelo ahorraron ${usd}.`,
1117
+ lost: (usd, months) =>
1118
+ `${months} de ellos se quedaron cortos, y el suelo que habr\u00edas pagado por capacidad que nadie us\u00f3 suma ${usd}. Esa cifra se mantiene aparte a prop\u00f3sito: metida en la l\u00ednea de arriba desaparece, y esa desaparici\u00f3n es de lo que vive la diapositiva de un comercial.`,
1119
+ noShortfall: () => 'Ning\u00fan mes medido se habr\u00eda quedado por debajo del suelo.',
1120
+ breakEven: (usd) =>
1121
+ `El equilibrio est\u00e1 en ${usd} de gasto mensual. Por debajo pagas el suelo por menos uso del que compra; por encima el ahorro crece.`,
1122
+ spread: (low, high, median) =>
1123
+ `Dispersi\u00f3n medida: de ${low} a ${high}, mediana ${median}. Ese es el riesgo de quedarse corto en la \u00fanica forma en que un log puede expresarlo \u2014 un recuento de meses reales y el rango que cubrieron, no una probabilidad de una distribuci\u00f3n que nadie ajust\u00f3.`,
1124
+ shortTerm: (covered, term) =>
1125
+ `Esto replica ${covered} meses contra un compromiso de ${term} meses. Es una respuesta real sobre ${covered} meses y no sobre ${term}.`,
1126
+ cannotTell: (why, needed) =>
1127
+ why === 'no-history'
1128
+ ? 'Nada que replicar: este log no tiene meses completos.'
1129
+ : `No se puede juzgar con ${needed === '0' ? 'lo que hay' : `lo que hay \u2014 ${needed} mes(es) completo(s) m\u00e1s lo zanjar\u00edan`}. Un compromiso se firma por un a\u00f1o, y una respuesta de un mes es una decisi\u00f3n anual tomada con quince d\u00edas de evidencia.`,
1130
+ neverAForecast: () =>
1131
+ 'Aqu\u00ed nada se anualiza, se extrapola ni se ajusta a una tendencia. Si el pr\u00f3ximo trimestre no se parece al anterior, esta aritm\u00e9tica no dice nada sobre \u00e9l \u2014 que es el l\u00edmite honesto de lo que un log puede contarte sobre un contrato.',
1132
+ },
1133
+
1050
1134
  owners: {
1051
1135
  heading: () => 'De qui\u00e9n es el dinero',
1052
1136
  noOwners: () =>
package/src/i18n/types.ts CHANGED
@@ -268,6 +268,37 @@ export interface CliMessages {
268
268
  * The ladder. Every line here exists to stop somebody reading "we route to
269
269
  * the cheap model first" as a saving without the number that decides it.
270
270
  */
271
+ annual: {
272
+ heading(year: string): string;
273
+ needsYear(): string;
274
+ spent(usd: string, calls: string, months: string): string;
275
+ missing(months: string): string;
276
+ promises(planned: string, arrived: string, notArrived: string, cannotTell: string): string;
277
+ projected(usd: string): string;
278
+ noArrivedFigure(): string;
279
+ outcomes(recorded: string, parsed: string, unrecordedUsd: string): string;
280
+ noOutcomes(): string;
281
+ cannotSayHeading(): string;
282
+ cannotSay(kind: string): string;
283
+ noNewData(): string;
284
+ };
285
+
286
+ commitment: {
287
+ heading(floor: string, discount: string, months: string): string;
288
+ needsTerms(): string;
289
+ asIf(): string;
290
+ columns: { month: string; list: string; paid: string; saving: string };
291
+ net(usd: string, months: string): string;
292
+ good(usd: string): string;
293
+ lost(usd: string, months: string): string;
294
+ noShortfall(): string;
295
+ breakEven(usd: string): string;
296
+ spread(low: string, high: string, median: string): string;
297
+ shortTerm(covered: string, term: string): string;
298
+ cannotTell(why: string, needed: string): string;
299
+ neverAForecast(): string;
300
+ };
301
+
271
302
  owners: {
272
303
  heading(): string;
273
304
  noOwners(): string;
package/src/index.ts CHANGED
@@ -41,6 +41,9 @@ import {
41
41
  conform,
42
42
  BREAK_EVEN_BAND,
43
43
  allocate,
44
+ annualRecord,
45
+ replayCommitment,
46
+ coversTheTerm,
44
47
  runExperiment,
45
48
  qualityGate,
46
49
  semanticPassCost,
@@ -256,7 +259,11 @@ interface Args {
256
259
  const VALUE_FLAGS = new Set([
257
260
  'a',
258
261
  'at',
262
+ 'year',
259
263
  'b',
264
+ 'floor',
265
+ 'discount',
266
+ 'months',
260
267
  'min-outcomes',
261
268
  'against',
262
269
  'contract',
@@ -591,6 +598,8 @@ const COMMAND_FLAGS: Record<string, string[]> = {
591
598
  quality: ['label', 'at', 'gate', 'pricing', 'pricing-live'],
592
599
  semantic: ['yes', 'model', 'pricing', 'pricing-live'],
593
600
  owners: ['pricing', 'pricing-live', 'since', 'until'],
601
+ commitment: ['floor', 'discount', 'months', 'pricing', 'pricing-live'],
602
+ report: ['year', 'json', 'pricing', 'pricing-live'],
594
603
  where: [],
595
604
  rules: [],
596
605
  blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -2876,6 +2885,297 @@ async function commandOwners(
2876
2885
  console.log();
2877
2886
  }
2878
2887
 
2888
+ /**
2889
+ * `trazum commitment <log> --floor <usd> --discount <pct> [--months 12]`
2890
+ *
2891
+ * What a committed-use deal would have been worth **on the traffic you
2892
+ * actually had**. Every team that signs one of these is doing arithmetic in a
2893
+ * spreadsheet against a number they guessed, and it is the highest-stakes
2894
+ * instance of exactly the failure this product exists to end — because the
2895
+ * guess is annual and signed.
2896
+ *
2897
+ * Nothing here projects. "On the traffic you actually had, this would have
2898
+ * saved $X" is a measurement; "you will save $X" is a claim about the future
2899
+ * this product has refused at every scale since 1.27.
2900
+ */
2901
+ async function commandCommitment(
2902
+ args: Args,
2903
+ config: TrazumConfig,
2904
+ pricing: PricingCatalogue,
2905
+ t: CliMessages,
2906
+ ): Promise<void> {
2907
+ const path = args.positional[0];
2908
+ if (path === undefined) throw new Error(t.errors.missingInputFile());
2909
+
2910
+ const floorRaw = stringFlag(args, 'floor');
2911
+ const discountRaw = stringFlag(args, 'discount');
2912
+ const floor = floorRaw === undefined ? Number.NaN : Number(floorRaw);
2913
+ const discountInput = discountRaw === undefined ? Number.NaN : Number(discountRaw);
2914
+ if (!Number.isFinite(floor) || floor <= 0 || !Number.isFinite(discountInput) || discountInput <= 0) {
2915
+ throw new Error(t.commitment.needsTerms());
2916
+ }
2917
+ // Written either way in a contract, so read either way: 20 and 0.2 are the
2918
+ // same deal, and refusing one of them would be pedantry with a stack trace.
2919
+ const discount = discountInput > 1 ? discountInput / 100 : discountInput;
2920
+ const months = Number(stringFlag(args, 'months') ?? 12);
2921
+ const terms = { monthlyFloorUsd: floor, discount, months };
2922
+
2923
+ const report = profileUsage(await readUsageLog(path, t), { catalogue: pricing });
2924
+ /**
2925
+ * Whole calendar months only.
2926
+ *
2927
+ * A partial month replayed against a monthly floor is a shortfall the
2928
+ * traffic never had — the deal would be judged against a fortnight of usage
2929
+ * and a full month of commitment. Dropping them costs an answer; keeping
2930
+ * them would manufacture one.
2931
+ */
2932
+ const byMonth = new Map<string, number>();
2933
+ for (const day of report.spendByDay) {
2934
+ const key = day.day.slice(0, 7);
2935
+ byMonth.set(key, (byMonth.get(key) ?? 0) + day.usd);
2936
+ }
2937
+ const days = new Map<string, Set<string>>();
2938
+ for (const day of report.spendByDay) {
2939
+ const key = day.day.slice(0, 7);
2940
+ const set = days.get(key) ?? new Set<string>();
2941
+ set.add(day.day);
2942
+ days.set(key, set);
2943
+ }
2944
+ const whole = [...byMonth.entries()]
2945
+ .filter(([key]) => {
2946
+ const [y, m] = key.split('-').map(Number);
2947
+ const inMonth = new Date(Date.UTC(y ?? 2026, m ?? 1, 0)).getUTCDate();
2948
+ return (days.get(key)?.size ?? 0) >= inMonth - 2;
2949
+ })
2950
+ .map(([month, usd]) => ({ month, usd }))
2951
+ .sort((a, b) => a.month.localeCompare(b.month));
2952
+
2953
+ const replay = replayCommitment(whole, terms);
2954
+ const coverage = coversTheTerm(replay, terms);
2955
+ const n = (value: number): string => value.toLocaleString(t.numberLocale);
2956
+ const pct = (value: number): string => `${(value * 100).toFixed(0)}%`;
2957
+
2958
+ console.log();
2959
+ console.log(c.bold(t.commitment.heading(formatUsd(floor), pct(discount), n(months))));
2960
+ console.log(` ${c.dim(wrap(t.commitment.asIf(), 74, ' '))}`);
2961
+ console.log();
2962
+
2963
+ if (replay.unknown !== null) {
2964
+ console.log(
2965
+ ` ${c.yellow('?')} ${wrap(t.commitment.cannotTell(replay.unknown, n(replay.monthsNeeded ?? 0)), 74, ' ')}`,
2966
+ );
2967
+ console.log();
2968
+ console.log(` ${c.dim(t.commitment.breakEven(formatUsd(replay.breakEvenMonthlyUsd)))}`);
2969
+ console.log();
2970
+ return;
2971
+ }
2972
+
2973
+ const col = t.commitment.columns;
2974
+ const rows = replay.months.map((m) => ({
2975
+ month: m.month,
2976
+ list: formatUsd(m.listUsd),
2977
+ paid: formatUsd(m.paidUsd),
2978
+ // Signed: every month in this column can go either way, and formatUsd
2979
+ // renders a negative as `$-2,400`, which reads as a typo. The sign carries
2980
+ // the whole meaning here, so it goes where a reader expects it.
2981
+ saving: formatSignedUsd(m.savingUsd),
2982
+ shortfall: m.shortfall,
2983
+ }));
2984
+ const w = {
2985
+ month: Math.max(...rows.map((r) => r.month.length), col.month.length),
2986
+ list: Math.max(...rows.map((r) => r.list.length), col.list.length),
2987
+ paid: Math.max(...rows.map((r) => r.paid.length), col.paid.length),
2988
+ saving: Math.max(...rows.map((r) => r.saving.length), col.saving.length),
2989
+ };
2990
+ console.log(
2991
+ c.dim(
2992
+ ` ${col.month.padEnd(w.month)} ${col.list.padStart(w.list)} ` +
2993
+ `${col.paid.padStart(w.paid)} ${col.saving.padStart(w.saving)}`,
2994
+ ),
2995
+ );
2996
+ for (const row of rows) {
2997
+ const tint = row.shortfall ? c.red : c.dim;
2998
+ console.log(
2999
+ ` ${row.month.padEnd(w.month)} ${row.list.padStart(w.list)} ` +
3000
+ `${row.paid.padStart(w.paid)} ${tint(row.saving.padStart(w.saving))}`,
3001
+ );
3002
+ }
3003
+
3004
+ console.log();
3005
+ console.log(` ${c.bold(t.commitment.net(formatUsd(replay.netUsd), n(replay.months.length)))}`);
3006
+ console.log(` ${c.dim(t.commitment.good(formatUsd(replay.savedInGoodMonthsUsd)))}`);
3007
+ if (replay.shortfallMonths > 0) {
3008
+ console.log(
3009
+ ` ${c.yellow('!')} ${wrap(
3010
+ t.commitment.lost(formatUsd(replay.lostToUnusedFloorUsd), n(replay.shortfallMonths)),
3011
+ 74,
3012
+ ' ',
3013
+ )}`,
3014
+ );
3015
+ } else {
3016
+ console.log(` ${c.dim(t.commitment.noShortfall())}`);
3017
+ }
3018
+
3019
+ console.log();
3020
+ console.log(` ${c.dim(wrap(t.commitment.breakEven(formatUsd(replay.breakEvenMonthlyUsd)), 74, ' '))}`);
3021
+ if (replay.spread !== null) {
3022
+ console.log(
3023
+ ` ${c.dim(
3024
+ wrap(
3025
+ t.commitment.spread(
3026
+ formatUsd(replay.spread.lowUsd),
3027
+ formatUsd(replay.spread.highUsd),
3028
+ formatUsd(replay.spread.medianUsd),
3029
+ ),
3030
+ 74,
3031
+ ' ',
3032
+ ),
3033
+ )}`,
3034
+ );
3035
+ }
3036
+ // Said, not enforced: a shorter history is a real answer about a shorter
3037
+ // period, and the gap must not go unmarked.
3038
+ if (coverage.short) {
3039
+ console.log();
3040
+ console.log(
3041
+ ` ${c.yellow('!')} ${wrap(t.commitment.shortTerm(n(coverage.covered), n(coverage.ofMonths)), 74, ' ')}`,
3042
+ );
3043
+ }
3044
+ console.log();
3045
+ console.log(` ${c.dim(wrap(t.commitment.neverAForecast(), 74, ' '))}`);
3046
+ console.log();
3047
+ }
3048
+
3049
+ /**
3050
+ * `trazum report <log> --year <yyyy>` — the year, from what was already
3051
+ * written down.
3052
+ *
3053
+ * The last chapter of the arc, and the one that turns this product's argument
3054
+ * into something a stranger can audit. **No new data**: everything here comes
3055
+ * from the store and the plans a team already keeps, and nothing is computed
3056
+ * that could not be checked against a document that already exists.
3057
+ *
3058
+ * That constraint is the whole design. An annual report is the document most
3059
+ * likely to be quoted out of the room it was written in, and the one nobody
3060
+ * goes back to verify.
3061
+ */
3062
+ async function commandReport(
3063
+ args: Args,
3064
+ config: TrazumConfig,
3065
+ pricing: PricingCatalogue,
3066
+ t: CliMessages,
3067
+ ): Promise<void> {
3068
+ const path = args.positional[0];
3069
+ if (path === undefined) throw new Error(t.errors.missingInputFile());
3070
+ const year = stringFlag(args, 'year');
3071
+ if (year === undefined || !/^\d{4}$/.test(year)) throw new Error(t.annual.needsYear());
3072
+
3073
+ const report = profileUsage(await readUsageLog(path, t), { catalogue: pricing });
3074
+
3075
+ /**
3076
+ * One period per calendar month, built from the day series.
3077
+ *
3078
+ * Partial months are kept here, unlike in `commitment`: a year report is
3079
+ * about what happened, and a month that only ran for a week still happened.
3080
+ * What it must not do is imply the month was whole, which is why the count
3081
+ * of recorded months is stated beside the total.
3082
+ */
3083
+ const byMonth = new Map<string, { usd: number; calls: number }>();
3084
+ for (const day of report.spendByDay) {
3085
+ const key = day.day.slice(0, 7);
3086
+ const entry = byMonth.get(key) ?? { usd: 0, calls: 0 };
3087
+ entry.usd += day.usd;
3088
+ entry.calls += day.calls;
3089
+ byMonth.set(key, entry);
3090
+ }
3091
+ const outcomes = outcomeReport(report.outcomeTally, config.outcomes ?? null);
3092
+ const periods = [...byMonth.entries()]
3093
+ .map(([month, entry], index) => ({
3094
+ month,
3095
+ usd: entry.usd,
3096
+ calls: entry.calls,
3097
+ /**
3098
+ * Attached only when something was **recorded**, not merely parsed.
3099
+ *
3100
+ * The first version keyed on `parsed > 0`, which is true of any log with
3101
+ * calls in it — so a year that recorded no outcome at all still got an
3102
+ * outcomes object saying "0 of 120", and the honest sentence ("no
3103
+ * outcome was recorded this year, so nothing here says what the money
3104
+ * bought") was unreachable. A zero dressed as a measurement, which is
3105
+ * the exact failure the field's own contract forbids.
3106
+ *
3107
+ * Attached to the first month rather than divided across them: dividing
3108
+ * would invent a monthly figure nobody measured, and the year's total is
3109
+ * what this document reports.
3110
+ */
3111
+ ...(index === 0 && outcomes.coverage.recorded > 0 ? { outcomes } : {}),
3112
+ }))
3113
+ .sort((a, b) => a.month.localeCompare(b.month));
3114
+
3115
+ const record = annualRecord(year, periods);
3116
+ const n = (value: number): string => value.toLocaleString(t.numberLocale);
3117
+
3118
+ console.log();
3119
+ console.log(c.bold(t.annual.heading(year)));
3120
+ console.log();
3121
+ console.log(
3122
+ ` ${t.annual.spent(formatUsd(record.totalUsd), n(record.totalCalls), n(record.months.length))}`,
3123
+ );
3124
+ if (record.missingMonths.length > 0) {
3125
+ console.log(
3126
+ ` ${c.yellow('!')} ${wrap(t.annual.missing(record.missingMonths.join(', ')), 74, ' ')}`,
3127
+ );
3128
+ }
3129
+
3130
+ console.log();
3131
+ const p = record.promises;
3132
+ console.log(
3133
+ ` ${wrap(t.annual.promises(n(p.planned), n(p.arrived), n(p.notArrived), n(p.cannotTell)), 74, ' ')}`,
3134
+ );
3135
+ if (p.projectedUsd > 0) {
3136
+ console.log(` ${t.annual.projected(formatUsd(p.projectedUsd))}`);
3137
+ console.log(` ${c.dim(wrap(t.annual.noArrivedFigure(), 74, ' '))}`);
3138
+ }
3139
+
3140
+ console.log();
3141
+ if (record.outcomes === null) {
3142
+ console.log(` ${c.dim(wrap(t.annual.noOutcomes(), 74, ' '))}`);
3143
+ } else {
3144
+ console.log(
3145
+ ` ${wrap(
3146
+ t.annual.outcomes(
3147
+ n(record.outcomes.recorded),
3148
+ n(record.outcomes.parsed),
3149
+ formatUsd(record.outcomes.unrecordedUsd),
3150
+ ),
3151
+ 74,
3152
+ ' ',
3153
+ )}`,
3154
+ );
3155
+ }
3156
+
3157
+ /**
3158
+ * The section an annual report is usually missing, and the reason this one
3159
+ * is worth trusting: a document that lists its own blind spots is a document
3160
+ * somebody can act on the rest of.
3161
+ */
3162
+ if (record.cannotSay.length > 0) {
3163
+ console.log();
3164
+ console.log(` ${c.bold(t.annual.cannotSayHeading())}`);
3165
+ for (const kind of record.cannotSay) {
3166
+ console.log(` ${c.dim('·')} ${wrap(t.annual.cannotSay(kind), 70, ' ')}`);
3167
+ }
3168
+ }
3169
+
3170
+ console.log();
3171
+ console.log(` ${c.dim(wrap(t.annual.noNewData(), 74, ' '))}`);
3172
+ console.log();
3173
+
3174
+ if (boolFlag(args, 'json')) {
3175
+ console.log(JSON.stringify(record, null, 2));
3176
+ }
3177
+ }
3178
+
2879
3179
  function commandModels(t: CliMessages, pricing: PricingCatalogue): void {
2880
3180
  const n = (value: number): string => value.toLocaleString(t.numberLocale);
2881
3181
  const col = t.models.columns;
@@ -9076,6 +9376,12 @@ async function main(): Promise<void> {
9076
9376
  case 'models':
9077
9377
  commandModels(t, pricing);
9078
9378
  break;
9379
+ case 'report':
9380
+ await commandReport(args, config, pricing, t);
9381
+ break;
9382
+ case 'commitment':
9383
+ await commandCommitment(args, config, pricing, t);
9384
+ break;
9079
9385
  case 'owners':
9080
9386
  await commandOwners(args, config, pricing, t);
9081
9387
  break;