@trazum/core 2.7.12 → 3.0.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.
Files changed (65) hide show
  1. package/dist/advisories.d.ts +14 -7
  2. package/dist/advisories.d.ts.map +1 -1
  3. package/dist/advisories.js +27 -20
  4. package/dist/advisories.js.map +1 -1
  5. package/dist/i18n/en.js +2 -2
  6. package/dist/i18n/en.js.map +1 -1
  7. package/dist/i18n/es.js +2 -2
  8. package/dist/i18n/es.js.map +1 -1
  9. package/dist/i18n/types.d.ts +2 -1
  10. package/dist/i18n/types.d.ts.map +1 -1
  11. package/dist/index.d.ts +3 -1
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +2 -1
  14. package/dist/index.js.map +1 -1
  15. package/dist/openrouter.d.ts +1 -1
  16. package/dist/openrouter.d.ts.map +1 -1
  17. package/dist/openrouter.js +1 -2
  18. package/dist/openrouter.js.map +1 -1
  19. package/dist/pricing-overlay.d.ts +1 -1
  20. package/dist/pricing-overlay.d.ts.map +1 -1
  21. package/dist/pricing-overlay.js +19 -9
  22. package/dist/pricing-overlay.js.map +1 -1
  23. package/dist/pricing.d.ts +8 -5
  24. package/dist/pricing.d.ts.map +1 -1
  25. package/dist/pricing.js +11 -99
  26. package/dist/pricing.js.map +1 -1
  27. package/dist/review.js +2 -1
  28. package/dist/review.js.map +1 -1
  29. package/dist/segment.d.ts +31 -1
  30. package/dist/segment.d.ts.map +1 -1
  31. package/dist/segment.js +52 -4
  32. package/dist/segment.js.map +1 -1
  33. package/dist/structure.d.ts +34 -0
  34. package/dist/structure.d.ts.map +1 -1
  35. package/dist/structure.js +143 -12
  36. package/dist/structure.js.map +1 -1
  37. package/dist/types.d.ts +6 -6
  38. package/dist/types.d.ts.map +1 -1
  39. package/dist/usage.js +11 -11
  40. package/dist/watch.d.ts +11 -1
  41. package/dist/watch.d.ts.map +1 -1
  42. package/dist/watch.js.map +1 -1
  43. package/dist/weekly.d.ts +140 -0
  44. package/dist/weekly.d.ts.map +1 -0
  45. package/dist/weekly.js +176 -0
  46. package/dist/weekly.js.map +1 -0
  47. package/dist/write.js +2 -2
  48. package/dist/write.js.map +1 -1
  49. package/package.json +1 -1
  50. package/src/advisories.ts +41 -25
  51. package/src/i18n/en.ts +2 -2
  52. package/src/i18n/es.ts +2 -2
  53. package/src/i18n/types.ts +2 -1
  54. package/src/index.ts +4 -2
  55. package/src/openrouter.ts +1 -2
  56. package/src/pricing-overlay.ts +21 -12
  57. package/src/pricing.ts +13 -101
  58. package/src/review.ts +1 -1
  59. package/src/segment.ts +50 -6
  60. package/src/structure.ts +152 -13
  61. package/src/types.ts +6 -6
  62. package/src/usage.ts +11 -11
  63. package/src/watch.ts +12 -1
  64. package/src/weekly.ts +281 -0
  65. package/src/write.ts +2 -2
package/src/review.ts CHANGED
@@ -163,7 +163,7 @@ export async function reviewExamples(
163
163
 
164
164
  const fresh = group.redundant.filter((index) => !claimed.has(index) && index !== group.keep);
165
165
  if (fresh.length === 0) continue;
166
- fresh.forEach((index) => claimed.add(index));
166
+ for (const index of fresh) claimed.add(index);
167
167
 
168
168
  groups.push({
169
169
  ...group,
package/src/segment.ts CHANGED
@@ -210,6 +210,54 @@ function quotedSpans(text: string, reserved: readonly Match[]): Match[] {
210
210
  return found;
211
211
  }
212
212
 
213
+ /**
214
+ * The first of `ranges` that overlaps `[start, end)`, if one does.
215
+ *
216
+ * `ranges` is in order of where each begins and no two of them overlap, which
217
+ * makes it in order of where each ends as well. So the first range that ends
218
+ * after `start` is the only one that can be the first to overlap, and it is
219
+ * found by halving, not by looking at each.
220
+ *
221
+ * It was looked for one by one, with `find`, once for every match. A text of
222
+ * nothing but protected spans has as many reservations as matches, and the
223
+ * work grew with the square of them: 70 kB of placeholders, tags and code
224
+ * spans took half a second, and the 400 kB the HTTP API accepts took 26 to 30
225
+ * seconds, measured on 2026-11-18 (#716). A test with a five-second budget
226
+ * was the only thing that had noticed, and only on a slow machine.
227
+ */
228
+ export function firstOverlap(ranges: readonly Match[], start: number, end: number): Match | undefined {
229
+ let low = 0;
230
+ let high = ranges.length;
231
+ while (low < high) {
232
+ const middle = (low + high) >>> 1;
233
+ const range = ranges[middle];
234
+ if (range !== undefined && range.end > start) high = middle;
235
+ else low = middle + 1;
236
+ }
237
+ const candidate = ranges[low];
238
+ return candidate !== undefined && candidate.start < end ? candidate : undefined;
239
+ }
240
+
241
+ /**
242
+ * Whether one of `quotes` holds the whole of `[start, end)`.
243
+ *
244
+ * `quotes` is in order and no two overlap, so the only one that can hold the
245
+ * span is the last to begin at or before `start`. Asked of every reservation,
246
+ * and answered by looking at every quotation, it was the same square again.
247
+ */
248
+ export function heldBy(quotes: readonly Match[], start: number, end: number): boolean {
249
+ let low = 0;
250
+ let high = quotes.length;
251
+ while (low < high) {
252
+ const middle = (low + high) >>> 1;
253
+ const quote = quotes[middle];
254
+ if (quote !== undefined && quote.start <= start) low = middle + 1;
255
+ else high = middle;
256
+ }
257
+ const candidate = quotes[low - 1];
258
+ return candidate !== undefined && end <= candidate.end;
259
+ }
260
+
213
261
  /** Splits the text into segments, marking what must not be modified. */
214
262
  export function segment(text: string): Segment[] {
215
263
  /*
@@ -231,8 +279,6 @@ export function segment(text: string): Segment[] {
231
279
 
232
280
  for (const { kind, regex, trimTrailing } of PATTERNS) {
233
281
  const reserved = [...kept].sort((a, b) => a.start - b.start);
234
- const overlapping = (start: number, end: number): Match | undefined =>
235
- reserved.find((range) => start < range.end && end > range.start);
236
282
 
237
283
  // Copy the regex so lastIndex is not shared between calls.
238
284
  const re = new RegExp(regex.source, regex.flags);
@@ -247,7 +293,7 @@ export function segment(text: string): Segment[] {
247
293
  if (matched.length === 0) continue;
248
294
  const start = m.index;
249
295
  const end = start + matched.length;
250
- const hit = overlapping(start, end);
296
+ const hit = firstOverlap(reserved, start, end);
251
297
  if (hit !== undefined) {
252
298
  // Not simply skipped: the scan resumes where the reservation ends, so
253
299
  // a legitimate match sitting just past it is still found.
@@ -262,9 +308,7 @@ export function segment(text: string): Segment[] {
262
308
  // reservation a quotation swallows is dropped in favour of the quotation.
263
309
  const quoted = quotedSpans(text, kept);
264
310
  if (quoted.length > 0) {
265
- const inside = (range: Match): boolean =>
266
- quoted.some((quote) => range.start >= quote.start && range.end <= quote.end);
267
- const outside = kept.filter((range) => !inside(range));
311
+ const outside = kept.filter((range) => !heldBy(quoted, range.start, range.end));
268
312
  kept.length = 0;
269
313
  kept.push(...outside, ...quoted);
270
314
  }
package/src/structure.ts CHANGED
@@ -782,19 +782,7 @@ export function findRestatedFormat(prompt: string, count: TokenCounter): Restate
782
782
  const prose = analysableText(prompt);
783
783
  const proseSentences = sentences(prose);
784
784
 
785
- const restatedKeys = new Set<string>();
786
- const guiltySentences = new Set<number>();
787
-
788
- proseSentences.forEach((sentence, index) => {
789
- for (const key of keys) {
790
- // Word boundary that also survives snake_case and kebab-case names.
791
- const pattern = new RegExp(`(?<![\\p{L}\\p{N}_-])${escapeRegExp(key)}(?![\\p{L}\\p{N}_-])`, 'iu');
792
- if (pattern.test(sentence)) {
793
- restatedKeys.add(key);
794
- guiltySentences.add(index);
795
- }
796
- }
797
- });
785
+ const { restatedKeys, guiltySentences } = keysInSentences(keys, proseSentences);
798
786
 
799
787
  if (restatedKeys.size < RESTATED_KEY_MINIMUM) return null;
800
788
 
@@ -811,6 +799,157 @@ function escapeRegExp(text: string): string {
811
799
  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
812
800
  }
813
801
 
802
+ /**
803
+ * Which keys the prose names, and in which sentences: a key counts where it
804
+ * stands with no letter, digit, `_` or `-` on either side, compared without
805
+ * case. The pattern that says so exactly is `keyPattern`.
806
+ *
807
+ * **It used to ask that pattern of every sentence for every key, building it
808
+ * anew each time**, and that is the square of the text: a prompt of 40,000
809
+ * characters, half a schema of 1,778 keys and half prose, made `optimize`
810
+ * take 6.8 seconds, and one of 80,000 characters took 38, measured on
811
+ * 2026-11-18 (#772). The HTTP API accepts 400,000.
812
+ *
813
+ * So the prose is read once. It is cut where a key can start or end: a run of
814
+ * the characters the boundary looks at, or one other character. A key is cut
815
+ * the same way, and both are folded so that what the pattern calls equal is
816
+ * equal here. Every key is then looked for in one pass over the pieces, the
817
+ * way a dictionary of words is looked for in a text (Aho and Corasick, 1975),
818
+ * and a place where one is found is confirmed by the key's own pattern,
819
+ * anchored there. The pattern still decides; this only finds where to ask it.
820
+ *
821
+ * The answer is the one the old loop gave, in its order: `restated-format-scaling.test.js`
822
+ * holds the two side by side, and holds the fold to the engine's own
823
+ * case-insensitive comparison over every cased character.
824
+ */
825
+ export function keysInSentences(
826
+ keys: readonly string[],
827
+ sentences: readonly string[],
828
+ ): { restatedKeys: Set<string>; guiltySentences: Set<number> } {
829
+ const restatedKeys = new Set<string>();
830
+ const guiltySentences = new Set<number>();
831
+ if (keys.length === 0 || sentences.length === 0) return { restatedKeys, guiltySentences };
832
+
833
+ const patterns = keys.map((key) => keyPattern(key, 'iuy'));
834
+ const seen = new Map<string, { fold: string; run: boolean }>();
835
+ const lengths: number[] = [];
836
+ const root: KeyNode = { next: new Map(), fail: null, ends: [], link: null };
837
+ keys.forEach((key, index) => {
838
+ const pieces = keyPieces(key, seen);
839
+ lengths.push(pieces.length);
840
+ let node = root;
841
+ for (const { piece } of pieces) {
842
+ let child = node.next.get(piece);
843
+ if (child === undefined) {
844
+ child = { next: new Map(), fail: root, ends: [], link: null };
845
+ node.next.set(piece, child);
846
+ }
847
+ node = child;
848
+ }
849
+ node.ends.push(index);
850
+ });
851
+ const queue = [...root.next.values()];
852
+ for (let head = 0; head < queue.length; head++) {
853
+ const node = queue[head]!;
854
+ for (const [piece, child] of node.next) {
855
+ let fail = node.fail!;
856
+ while (fail !== root && !fail.next.has(piece)) fail = fail.fail!;
857
+ child.fail = node === root ? root : (fail.next.get(piece) ?? root);
858
+ child.link = child.fail.ends.length > 0 ? child.fail : child.fail.link;
859
+ queue.push(child);
860
+ }
861
+ }
862
+
863
+ sentences.forEach((sentence, index) => {
864
+ const pieces = keyPieces(sentence, seen);
865
+ const found = new Set<number>();
866
+ let node = root;
867
+ pieces.forEach(({ piece }, at) => {
868
+ while (node !== root && !node.next.has(piece)) node = node.fail!;
869
+ node = node.next.get(piece) ?? root;
870
+ for (let end: KeyNode | null = node.ends.length > 0 ? node : node.link; end !== null; end = end.link) {
871
+ for (const key of end.ends) {
872
+ if (found.has(key)) continue;
873
+ const first = at - lengths[key]! + 1;
874
+ // The pattern's own boundary, read off the pieces: a run of key
875
+ // characters is never cut, so one on either side is a letter there.
876
+ if (pieces[first - 1]?.run === true || pieces[at + 1]?.run === true) continue;
877
+ const pattern = patterns[key]!;
878
+ pattern.lastIndex = pieces[first]!.at;
879
+ if (pattern.test(sentence)) found.add(key);
880
+ }
881
+ }
882
+ });
883
+ if (found.size === 0) return;
884
+ guiltySentences.add(index);
885
+ for (const key of [...found].sort((a, b) => a - b)) restatedKeys.add(keys[key]!);
886
+ });
887
+ return { restatedKeys, guiltySentences };
888
+ }
889
+
890
+ /** A key, named in prose: not inside a longer name, and in any case. */
891
+ export function keyPattern(key: string, flags = 'iu'): RegExp {
892
+ // Word boundary that also survives snake_case and kebab-case names.
893
+ return new RegExp(`(?<![\\p{L}\\p{N}_-])${escapeRegExp(key)}(?![\\p{L}\\p{N}_-])`, flags);
894
+ }
895
+
896
+ interface KeyNode {
897
+ next: Map<string, KeyNode>;
898
+ fail: KeyNode | null;
899
+ /** The keys that end here, by index. */
900
+ ends: number[];
901
+ /** The nearest node down the fail chain where a key ends. */
902
+ link: KeyNode | null;
903
+ }
904
+
905
+ /** What `keyPattern`'s boundary reads as part of a name, under the same flags. */
906
+ const KEY_CHAR = /^[\p{L}\p{N}_-]$/iu;
907
+
908
+ /**
909
+ * Code points the engine compares as equal without case and that a lower- or
910
+ * upper-casing does not bring together. Found by comparing `foldKeyChar` with
911
+ * the engine over every code point on Node 22; `restated-format-scaling.test.js` repeats
912
+ * that comparison over the cased ones on whatever runs the tests. A pair the
913
+ * engine does not join costs nothing: the key's own pattern confirms a match.
914
+ */
915
+ const FOLD_TOGETHER: Readonly<Record<string, string>> = {
916
+ 'ΐ': 'ΐ',
917
+ 'ΰ': 'ΰ',
918
+ 'st': 'ſt',
919
+ };
920
+
921
+ /**
922
+ * One code point as `keyPieces` compares it: lowered, raised and lowered
923
+ * again, each step taken only when it gives one code point back.
924
+ */
925
+ export function foldKeyChar(char: string): string {
926
+ let fold = char;
927
+ for (const change of [(text: string) => text.toLowerCase(), (text: string) => text.toUpperCase(), (text: string) => text.toLowerCase()]) {
928
+ const next = change(fold);
929
+ if ([...next].length === 1) fold = next;
930
+ }
931
+ return FOLD_TOGETHER[fold] ?? fold;
932
+ }
933
+
934
+ /** A text cut where a key can start or end: each run of name characters, and each other character, folded, with where it starts. */
935
+ function keyPieces(text: string, seen: Map<string, { fold: string; run: boolean }>): Array<{ piece: string; at: number; run: boolean }> {
936
+ const pieces: Array<{ piece: string; at: number; run: boolean }> = [];
937
+ let at = 0;
938
+ for (const char of text) {
939
+ let known = seen.get(char);
940
+ if (known === undefined) {
941
+ known = { fold: foldKeyChar(char), run: KEY_CHAR.test(char) };
942
+ seen.set(char, known);
943
+ }
944
+ const { fold, run } = known;
945
+ const last = pieces[pieces.length - 1];
946
+ if (run && last !== undefined && last.run) last.piece += fold;
947
+ else pieces.push({ piece: fold, at, run });
948
+ at += char.length;
949
+ }
950
+ return pieces;
951
+ }
952
+
814
953
  // --------------------------------------------------------------------------
815
954
  // An output schema the API could carry instead of the prompt
816
955
  // --------------------------------------------------------------------------
package/src/types.ts CHANGED
@@ -332,14 +332,14 @@ export interface ModelPricing {
332
332
  /** What the provider answered, in the provider's words. */
333
333
  because: string;
334
334
  };
335
- /** Capability, on a vendor-neutral scale. */
336
- capability: Capability;
337
335
  /**
338
- * @deprecated Use `capability`. Anthropic's ladder used as a generic axis
339
- * stopped making sense once other providers were priced. Kept in step with
340
- * `capability` for the whole of 1.x and removed in 2.0 — see VERSIONING.md.
336
+ * Capability, on a vendor-neutral scale.
337
+ *
338
+ * The only one a model carries since 3.0.0, which removed `tier`, deprecated
339
+ * since 1.8.0. A pricing overlay that still writes `tier` is refused, naming
340
+ * the key, rather than read or ignored.
341
341
  */
342
- tier: 'haiku' | 'sonnet' | 'opus' | 'frontier' | 'unknown';
342
+ capability: Capability;
343
343
  /** Promotional pricing, when one is running. */
344
344
  promo?: {
345
345
  inputPerMTok: number;
package/src/usage.ts CHANGED
@@ -793,7 +793,7 @@ function readCount(...candidates: unknown[]): Count {
793
793
  }
794
794
 
795
795
  /** Zero for an absent count. Callers reject corrupt ones before reaching this. */
796
- const valueOf = (count: Count): number => (count.kind === 'ok' ? count.value : 0);
796
+ const countOf = (count: Count): number => (count.kind === 'ok' ? count.value : 0);
797
797
 
798
798
  /**
799
799
  * One line of a usage log, or `null` when it is not one.
@@ -1008,23 +1008,23 @@ export function parseUsageLine(line: string): UsageRecord | null {
1008
1008
 
1009
1009
  // Both providers that fold cached tokens into the prompt count, one
1010
1010
  // subtraction. They cannot coexist on a record: the shapes share no field.
1011
- const cached = valueOf(counts.openAiCached!) + valueOf(counts.geminiCached!);
1011
+ const cached = countOf(counts.openAiCached!) + countOf(counts.geminiCached!);
1012
1012
  // Inside the OpenAI total like the cached tokens, and taken out of it the same way.
1013
- const openAiWritten = valueOf(counts.openAiWrite!);
1014
- const flatWrite = valueOf(counts.cacheWrite!);
1015
- const split5m = valueOf(counts.write5m!);
1016
- const split1h = valueOf(counts.write1h!);
1013
+ const openAiWritten = countOf(counts.openAiWrite!);
1014
+ const flatWrite = countOf(counts.cacheWrite!);
1015
+ const split5m = countOf(counts.write5m!);
1016
+ const split1h = countOf(counts.write1h!);
1017
1017
  const hasSplit = counts.write5m!.kind === 'ok' || counts.write1h!.kind === 'ok';
1018
1018
  // OpenAI's lifetimes, taken only when they add up to the writes they split.
1019
1019
  const openAiSplitGiven = counts.openAiWrite30m!.kind === 'ok' || counts.openAiWrite12h!.kind === 'ok';
1020
1020
  const openAiSplitAgrees =
1021
1021
  counts.openAiWrite30m!.kind === 'ok' && counts.openAiWrite12h!.kind === 'ok'
1022
- && valueOf(counts.openAiWrite30m!) + valueOf(counts.openAiWrite12h!) === openAiWritten;
1023
- const openAiLong = openAiSplitAgrees ? valueOf(counts.openAiWrite12h!) : 0;
1022
+ && countOf(counts.openAiWrite30m!) + countOf(counts.openAiWrite12h!) === openAiWritten;
1023
+ const openAiLong = openAiSplitAgrees ? countOf(counts.openAiWrite12h!) : 0;
1024
1024
 
1025
1025
  return {
1026
1026
  model,
1027
- inputTokens: Math.max(0, valueOf(counts.input!) - cached - openAiWritten) + valueOf(counts.geminiToolPrompt!),
1027
+ inputTokens: Math.max(0, countOf(counts.input!) - cached - openAiWritten) + countOf(counts.geminiToolPrompt!),
1028
1028
  cacheReadTokens: counts.cacheRead!.kind === 'ok' ? counts.cacheRead!.value : cached,
1029
1029
  /**
1030
1030
  * The split when the log carries it, the flat number otherwise — and
@@ -1045,7 +1045,7 @@ export function parseUsageLine(line: string): UsageRecord | null {
1045
1045
  * by the model, since the line alone cannot say whose API wrote it.
1046
1046
  */
1047
1047
  writeTtlKnown: hasSplit || (flatWrite === 0 && (openAiSplitGiven ? openAiSplitAgrees : openAiWritten === 0)),
1048
- outputTokens: valueOf(counts.output!) + valueOf(counts.geminiThoughts!),
1048
+ outputTokens: countOf(counts.output!) + countOf(counts.geminiThoughts!),
1049
1049
  /**
1050
1050
  * Trimmed and internally normalised: any whitespace run becomes one space.
1051
1051
  * A label is a workload name, and it is also used as half of structured keys
@@ -1118,7 +1118,7 @@ export function parseUsageLine(line: string): UsageRecord | null {
1118
1118
  ...(record.batch === true || usage.service_tier === 'batch' ? { batch: true as const } : {}),
1119
1119
  /* Said by the record alone: nothing a provider returns names who was waiting. */
1120
1120
  ...(record.interactive === true ? { interactive: true as const } : {}),
1121
- ...(valueOf(webSearch) > 0 ? { webSearchRequests: valueOf(webSearch) } : {}),
1121
+ ...(countOf(webSearch) > 0 ? { webSearchRequests: countOf(webSearch) } : {}),
1122
1122
  ...(openAiSplitGiven && !openAiSplitAgrees ? { writeSplitContradicted: true as const } : {}),
1123
1123
  };
1124
1124
  }
package/src/watch.ts CHANGED
@@ -97,9 +97,20 @@ export interface WatchThresholds {
97
97
  maxCacheLossUsd?: number;
98
98
  }
99
99
 
100
+ /**
101
+ * The part of a priced report a gate is judged against.
102
+ *
103
+ * A connected report (`BucketedReport`) has all of it. So does what is read
104
+ * out of the sessions a coding agent keeps on disk, which has no buckets and
105
+ * is shaped to this instead of being made to pretend it has them.
106
+ */
107
+ export type WatchedReport = Pick<BucketedReport, 'span' | 'byDay'> & {
108
+ total: Pick<BucketedReport['total'], 'totalUsd'>;
109
+ };
110
+
100
111
  export interface WatchOptions {
101
112
  /** Priced measurements for the period being watched. */
102
- report: BucketedReport;
113
+ report: WatchedReport;
103
114
  thresholds: WatchThresholds;
104
115
  /** The cache verdict over the same report, when the caller computed one. */
105
116
  cacheDeltaUsd?: number;
package/src/weekly.ts ADDED
@@ -0,0 +1,281 @@
1
+ /**
2
+ * The week in three paragraphs: what it cost, what moved against the week
3
+ * before, and the three changes worth making first.
4
+ *
5
+ * Nothing here is estimated. The bill and the movement are two measured
6
+ * reports, one per week, priced by the same catalogue; the changes are the
7
+ * ranked actions `buildPlan` already derives from the week's own report, and
8
+ * each carries what was measured before it. A saving that has not happened is
9
+ * a projection and says so; `verify` is what measures it afterwards.
10
+ *
11
+ * **A figure in the summary is a figure in the bill.** The summary is text a
12
+ * person reads in an issue and acts on, so every dollar amount and every
13
+ * percentage it prints has to be one the two reports (or the plan made from
14
+ * them) hold. `billFigures` works the allowed set out from the reports
15
+ * themselves, by a route that shares no code with the builder, and
16
+ * `strayFigures` reads a rendered summary and names what is not in it. The CLI
17
+ * refuses to write a summary with a stray figure in it: a wrong number in a
18
+ * weekly note is worse than no note, because nobody re-adds it.
19
+ *
20
+ * Browser-safe like the rest of the core: reports in, one document out. The
21
+ * words belong to whoever renders it, in the reader's language.
22
+ */
23
+
24
+ import { formatUsd } from './savings.js';
25
+ import type { PlanActionKind, PlanAssumption, PlanDocument } from './plan.js';
26
+ import type { UsageProfileReport } from './usage.js';
27
+
28
+ const DAY_MS = 86_400_000;
29
+ export const WEEK_MS = 7 * DAY_MS;
30
+
31
+ /** How many changes a weekly summary names. Three is the issue's number; more is a list nobody acts on. */
32
+ export const WEEKLY_CHANGES = 3;
33
+ /** How many models the bill and the movement name before saying how many more there are. */
34
+ export const WEEKLY_MODELS = 5;
35
+ export const WEEKLY_MOVERS = 3;
36
+
37
+ /** A window, half-open like every window in the profile: two adjacent weeks share no call. */
38
+ export interface WeekWindow {
39
+ sinceMs: number;
40
+ untilMs: number;
41
+ /** The first UTC day inside it, `YYYY-MM-DD`. */
42
+ firstDay: string;
43
+ /** The last UTC day inside it. */
44
+ lastDay: string;
45
+ }
46
+
47
+ const dayOf = (ms: number): string => new Date(ms).toISOString().slice(0, 10);
48
+
49
+ const windowOf = (sinceMs: number, untilMs: number): WeekWindow => ({
50
+ sinceMs,
51
+ untilMs,
52
+ firstDay: dayOf(sinceMs),
53
+ lastDay: dayOf(untilMs - 1),
54
+ });
55
+
56
+ /**
57
+ * The week ending at `untilMs` and the week before it.
58
+ *
59
+ * Seven days each, back to back, with no overlap and no gap: the week before
60
+ * ends at the instant this one begins.
61
+ */
62
+ export function weekWindows(untilMs: number): { current: WeekWindow; previous: WeekWindow } {
63
+ return {
64
+ current: windowOf(untilMs - WEEK_MS, untilMs),
65
+ previous: windowOf(untilMs - 2 * WEEK_MS, untilMs - WEEK_MS),
66
+ };
67
+ }
68
+
69
+ export interface WeeklyModelRow {
70
+ model: string;
71
+ calls: number;
72
+ usd: number;
73
+ }
74
+
75
+ export interface WeeklyMover {
76
+ model: string;
77
+ previousUsd: number;
78
+ currentUsd: number;
79
+ deltaUsd: number;
80
+ }
81
+
82
+ export interface WeeklyChange {
83
+ rank: number;
84
+ kind: PlanActionKind;
85
+ /** The workload, `UNLABELLED` when the log named none. */
86
+ label: string;
87
+ model: string;
88
+ /** Projected, for route and batch: not measured, and never rendered as if it were. */
89
+ projectedSavingUsd: number | null;
90
+ /** Measured: money already spent on the problem the change fixes. */
91
+ measuredStakeUsd: number | null;
92
+ /** What this workload and model cost this week, measured. Null when the plan did not record it. */
93
+ sliceUsd: number | null;
94
+ sliceCalls: number | null;
95
+ routeTo: string | null;
96
+ /** What the log cannot confirm about this change, as the plan states it. */
97
+ assumes: PlanAssumption[];
98
+ }
99
+
100
+ export interface WeeklySummary {
101
+ current: WeekWindow;
102
+ previous: WeekWindow;
103
+ /** This week's bill: what could be priced, and only that. */
104
+ totalUsd: number;
105
+ calls: number;
106
+ /** Priced models, largest first, at most `WEEKLY_MODELS`; `moreModels` counts the rest. */
107
+ models: WeeklyModelRow[];
108
+ moreModels: number;
109
+ unpricedModels: string[];
110
+ unpricedCalls: number;
111
+ /** Calls with no clock that a windowed report cannot place in any week. */
112
+ undatedExcluded: number;
113
+ /**
114
+ * Against the week before, or null when that week holds no call: a ratio
115
+ * against nothing is not a change, and the summary says there was no week
116
+ * to compare rather than print a number for it.
117
+ */
118
+ comparison: null | {
119
+ previousUsd: number;
120
+ previousCalls: number;
121
+ deltaUsd: number;
122
+ /** Null when the week before cost nothing priced: no percentage of zero. */
123
+ deltaPct: number | null;
124
+ movers: WeeklyMover[];
125
+ };
126
+ /** The first `WEEKLY_CHANGES` actions of the plan, largest money first. */
127
+ changes: WeeklyChange[];
128
+ /** How many actions the plan had in all. */
129
+ changesAvailable: number;
130
+ }
131
+
132
+ const pricedModels = (report: UsageProfileReport): WeeklyModelRow[] =>
133
+ report.byModel
134
+ .filter((row) => !report.unpricedModels.includes(row.model))
135
+ .map((row) => ({ model: row.model, calls: row.breakdown.calls, usd: row.breakdown.totalUsd }));
136
+
137
+ /**
138
+ * Builds the summary from the week's report, the week before's, and the plan
139
+ * made from this week's.
140
+ */
141
+ export function buildWeeklySummary(
142
+ current: UsageProfileReport,
143
+ previous: UsageProfileReport,
144
+ plan: PlanDocument,
145
+ windows: { current: WeekWindow; previous: WeekWindow },
146
+ ): WeeklySummary {
147
+ const models = pricedModels(current);
148
+
149
+ let comparison: WeeklySummary['comparison'] = null;
150
+ if (previous.total.calls > 0) {
151
+ const before = new Map(pricedModels(previous).map((row) => [row.model, row.usd]));
152
+ const now = new Map(models.map((row) => [row.model, row.usd]));
153
+ const movers: WeeklyMover[] = [...new Set([...before.keys(), ...now.keys()])]
154
+ .map((model) => {
155
+ const previousUsd = before.get(model) ?? 0;
156
+ const currentUsd = now.get(model) ?? 0;
157
+ return { model, previousUsd, currentUsd, deltaUsd: currentUsd - previousUsd };
158
+ })
159
+ .filter((row) => row.deltaUsd !== 0)
160
+ .sort((a, b) => Math.abs(b.deltaUsd) - Math.abs(a.deltaUsd) || a.model.localeCompare(b.model))
161
+ .slice(0, WEEKLY_MOVERS);
162
+ const previousUsd = previous.total.totalUsd;
163
+ const deltaUsd = current.total.totalUsd - previousUsd;
164
+ comparison = {
165
+ previousUsd,
166
+ previousCalls: previous.total.calls,
167
+ deltaUsd,
168
+ deltaPct: previousUsd > 0 ? (deltaUsd / previousUsd) * 100 : null,
169
+ movers,
170
+ };
171
+ }
172
+
173
+ const changes: WeeklyChange[] = plan.actions.slice(0, WEEKLY_CHANGES).map((action, index) => ({
174
+ rank: index + 1,
175
+ kind: action.kind,
176
+ label: action.label,
177
+ model: action.model,
178
+ projectedSavingUsd: action.savingUsd,
179
+ measuredStakeUsd: action.stakeUsd,
180
+ sliceUsd: action.detail.baseline?.usd ?? null,
181
+ sliceCalls: action.detail.baseline?.calls ?? null,
182
+ routeTo: action.detail.routeTo?.displayName ?? null,
183
+ assumes: [...action.assumes],
184
+ }));
185
+
186
+ return {
187
+ current: windows.current,
188
+ previous: windows.previous,
189
+ totalUsd: current.total.totalUsd,
190
+ calls: current.total.calls,
191
+ models: models.slice(0, WEEKLY_MODELS),
192
+ moreModels: Math.max(0, models.length - WEEKLY_MODELS),
193
+ unpricedModels: [...current.unpricedModels],
194
+ unpricedCalls: current.unpriced.calls,
195
+ undatedExcluded: current.timeWindow?.undatedExcluded ?? 0,
196
+ comparison,
197
+ changes,
198
+ changesAvailable: plan.actions.length,
199
+ };
200
+ }
201
+
202
+ /** The figures a summary may print, as the strings it prints them as. */
203
+ export interface BillFigures {
204
+ /** Every dollar amount, as `formatUsd` writes it and without a sign. */
205
+ usd: ReadonlySet<string>;
206
+ /** Every percentage, one decimal, without a sign and without the `%`. */
207
+ pct: ReadonlySet<string>;
208
+ }
209
+
210
+ /**
211
+ * What the reports hold, worked out from the reports.
212
+ *
213
+ * It reads the two reports and the plan directly and shares nothing with
214
+ * `buildWeeklySummary`, so a figure the builder gets wrong (a total scaled, a
215
+ * delta taken the wrong way round, a saving summed across actions that
216
+ * overlap) is not in this set and is named by `strayFigures`.
217
+ */
218
+ export function billFigures(
219
+ current: UsageProfileReport,
220
+ previous: UsageProfileReport,
221
+ plan: PlanDocument,
222
+ ): BillFigures {
223
+ const usd = new Set<string>(['$0']);
224
+ const pct = new Set<string>();
225
+ const add = (value: number | null | undefined): void => {
226
+ if (value === null || value === undefined || !Number.isFinite(value)) return;
227
+ usd.add(formatUsd(Math.abs(value)));
228
+ };
229
+
230
+ add(current.total.totalUsd);
231
+ add(previous.total.totalUsd);
232
+ add(current.total.totalUsd - previous.total.totalUsd);
233
+ const rows = (report: UsageProfileReport) => new Map(report.byModel.map((row) => [row.model, row.breakdown.totalUsd]));
234
+ const now = rows(current);
235
+ const before = rows(previous);
236
+ for (const model of new Set([...now.keys(), ...before.keys()])) {
237
+ const a = now.get(model) ?? 0;
238
+ const b = before.get(model) ?? 0;
239
+ add(a);
240
+ add(b);
241
+ add(a - b);
242
+ }
243
+ for (const action of plan.actions) {
244
+ add(action.savingUsd);
245
+ add(action.stakeUsd);
246
+ add(action.detail.baseline?.usd);
247
+ }
248
+ if (previous.total.totalUsd > 0) {
249
+ const change = ((current.total.totalUsd - previous.total.totalUsd) / previous.total.totalUsd) * 100;
250
+ pct.add(Math.abs(change).toFixed(1));
251
+ }
252
+ return { usd, pct };
253
+ }
254
+
255
+ /**
256
+ * Prose a reader sees as prose is checked; what names a workload, a model or a
257
+ * command is not. Those are written between backticks, and a label such as
258
+ * `50% off` is the author's word, not a figure Trazum computed.
259
+ */
260
+ const withoutCode = (text: string): string => text.replace(/`[^`\n]*`/g, '');
261
+
262
+ /**
263
+ * The dollar amounts and percentages in a rendered summary that no report
264
+ * holds. Empty when every one is accounted for.
265
+ */
266
+ export function strayFigures(markdown: string, figures: BillFigures): string[] {
267
+ const prose = withoutCode(markdown);
268
+ const stray: string[] = [];
269
+ for (const [amount] of prose.matchAll(/\$\d[\d,]*(?:\.\d+)?/g)) {
270
+ if (!figures.usd.has(amount)) stray.push(amount);
271
+ }
272
+ for (const [, number] of prose.matchAll(/(\d+(?:\.\d+)?)%/g)) {
273
+ if (number !== undefined && !figures.pct.has(number)) stray.push(`${number}%`);
274
+ }
275
+ return [...new Set(stray)];
276
+ }
277
+
278
+ /** The identifier a weekly summary carries so a re-run replaces it rather than adding a second. */
279
+ export function weeklyMarker(lastDay: string): string {
280
+ return `<!-- trazum-weekly:${lastDay} -->`;
281
+ }
package/src/write.ts CHANGED
@@ -83,7 +83,7 @@ export const OUTPUT_FORMATS = ['prose', 'json', 'list', 'table'] as const;
83
83
  export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
84
84
 
85
85
  const answered = (answers: Answers, id: string): boolean =>
86
- Object.prototype.hasOwnProperty.call(answers, id) && answers[id] !== null;
86
+ Object.hasOwn(answers, id) && answers[id] !== null;
87
87
 
88
88
  const shapeIs = (...formats: readonly OutputFormat[]) => (answers: Answers): boolean => {
89
89
  const shape = answers['output-shape'];
@@ -155,7 +155,7 @@ export interface Interview {
155
155
 
156
156
  export function interview(answers: Answers): Interview {
157
157
  const open = SLOTS.filter((entry) => isOpen(entry, answers));
158
- const has = (entry: Slot) => Object.prototype.hasOwnProperty.call(answers, entry.id);
158
+ const has = (entry: Slot) => Object.hasOwn(answers, entry.id);
159
159
  const unasked = open.filter((entry) => !has(entry));
160
160
  return {
161
161
  next: unasked[0]?.id ?? null,