@trazum/cli 1.46.0 → 1.48.0

package/dist/index.js

@@ -2,7 +2,7 @@
 import { open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { join, resolve as resolvePath } from 'node:path';
 import { gunzipSync } from 'node:zlib';
-import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, detectFromSource, matchLocale, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
+import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
 import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
 import { dayOf, formatGap, median, spanDays } from './time.js';
 // Everything that reads the filesystem, on its own entry point so the web
@@ -11,6 +11,7 @@ import { CONFIG_FILENAME, DEFAULT_EXTENSIONS, budgetFor, BUNDLED_CATALOGUE, SAFE
 import { contentAt, gitAvailable, namesByRevision, pathInRepository, repositoryRoot, revisionsFor, } from './git.js';
 import { fetchProviderUsage, findCredential } from './connect.js';
 import { STORE_DIR, appendRecords, readStore, rewriteStore } from './store-fs.js';
+import { WAIVER_LOG, appendWaiverUse, readWaiverLog } from './waiver-log.js';
 import { DEFAULT_PORT, buildServer, listen } from './serve.js';
 import { WATCH_STATE_VERSION, checkWebhook, postWebhook, readWatchState, writeWatchState, } from './watch-run.js';
 import { LOCALE_ENV_VARS, detectLocale, getCliMessages } from './i18n/index.js';
@@ -2518,7 +2519,7 @@ async function commandConnect(args, pricing, t) {
  * same action planned twice — and no series, however long, becomes a
  * forecast.
  */
-async function commandHistory(args, pricing, t) {
+async function commandHistory(args, config, pricing, t) {
     /**
      * `--store` builds the series from measured spend already on disk.
      *
@@ -2617,7 +2618,22 @@ async function commandHistory(args, pricing, t) {
     if (history.periods.length < 3) {
         throw new Error(t.history.needsThree(String(history.periods.length)));
     }
-    const stamped = { ...history, unrecognizedFiles: unrecognized };
+    /**
+     * The waiver record — closing the gap 1.40 named and could not fill.
+     *
+     * 1.40 wanted to say "this finding has been waived three times in a row" and
+     * refused to, because the only material available was the config as it
+     * stands, and a past reconstructed from a present is a guess wearing a
+     * record's clothes. The material exists now: since 1.48 a waiver that
+     * silences a gate writes down that it did, and this reads those lines back.
+     *
+     * Read from the working directory rather than from the reports directory:
+     * the waiver record belongs to the repository whose gates fired, and the
+     * stored reports may have come from anywhere.
+     */
+    const waivers = await readWaiverLog('.');
+    const waiverReport = waiverHistory(waivers.uses, config.waive ?? []);
+    const stamped = { ...history, unrecognizedFiles: unrecognized, waivers: waiverReport };
     const n = (value) => value.toLocaleString(t.numberLocale);
     const day = (ms) => new Date(ms).toISOString().slice(0, 10);
     const pct = (value) => `${(value * 100).toFixed(1)}%`;
@@ -2659,6 +2675,56 @@ async function commandHistory(args, pricing, t) {
         for (const name of unrecognized) {
             out.push(md ? `- ${t.history.unrecognized(name)}` : `  ${t.history.unrecognized(name)}`);
         }
+        /**
+         * The waiver record, printed only once something has been recorded.
+         *
+         * Silent on a repository that has never waived anything, rather than a
+         * heading over "0 uses" — an empty section teaches a reader to skip the
+         * section, and this is the one they should not learn to skip.
+         */
+        if (waivers.present) {
+            out.push('');
+            out.push(md ? `### ${t.history.waiverHeading()}` : t.history.waiverHeading());
+            if (waiverReport.totalUses === 0) {
+                out.push(md ? `- ${t.history.waiverNoneRecorded()}` : `  ${t.history.waiverNoneRecorded()}`);
+            }
+            else {
+                const since = t.history.waiverSince(waiverReport.since ?? '', waiverReport.totalUses);
+                out.push(md ? `- ${since}` : `  ${since}`);
+                out.push(md ? `- _${t.history.waiverStartsHere()}_` : `  ${t.history.waiverStartsHere()}`);
+                for (const habit of waiverReport.habits) {
+                    out.push('');
+                    const head = t.history.waiverHabit(habit.gate, habit.uses, habit.days, habit.firstDay, habit.lastDay);
+                    out.push(md ? `- **${head}**` : `  ${head}`);
+                    const rows = [t.history.waiverVerdict(habit.verdict)];
+                    // The reason as it stands *now* — never read backwards onto an
+                    // older use, which is the same mistake the record exists to avoid.
+                    const latest = habit.reasons[habit.reasons.length - 1];
+                    if (latest !== undefined)
+                        rows.push(t.history.waiverReasonNow(latest));
+                    if (habit.reasons.length > 1)
+                        rows.push(t.history.waiverReasonsChanged(habit.reasons.length));
+                    const firstExpiry = habit.expiries[0];
+                    const lastExpiry = habit.expiries[habit.expiries.length - 1];
+                    if (habit.expiries.length > 1 && firstExpiry !== undefined && lastExpiry !== undefined) {
+                        rows.push(t.history.waiverExpiriesMoved(firstExpiry, lastExpiry, habit.expiries.length - 1));
+                    }
+                    if (!habit.stillConfigured)
+                        rows.push(t.history.waiverNoLongerConfigured());
+                    for (const row of rows)
+                        out.push(md ? `  - ${row}` : `    ${row}`);
+                }
+            }
+            if (waiverReport.neverUsed.length > 0) {
+                out.push('');
+                const dead = t.history.waiverNeverUsed(waiverReport.neverUsed.join(', '));
+                out.push(md ? `- ${dead}` : `  ${dead}`);
+            }
+            if (waivers.unreadable.length > 0) {
+                const bad = t.history.waiverUnreadable(waivers.unreadable.length, WAIVER_LOG);
+                out.push(md ? `- ${bad}` : `  ${bad}`);
+            }
+        }
         if (fromStore) {
             out.push('');
             const note = t.history.storeNoLabels();
@@ -2695,19 +2761,21 @@ async function commandVerify(args, pricing, t) {
     const againstPath = stringFlag(args, 'against');
     if (againstPath === undefined)
         throw new Error(t.verify.needsAgainst());
-    let plan;
-    try {
-        const parsed = JSON.parse(await readFile(planPath, 'utf8'));
-        if (parsed?.schemaVersion !== 1 || !Array.isArray(parsed.actions)) {
-            throw new Error(t.verify.badPlan(planPath));
-        }
-        plan = parsed;
-    }
-    catch (error) {
-        if (error instanceof SyntaxError)
-            throw new Error(t.verify.badPlan(planPath));
-        throw error;
+    /**
+     * One validator, shared with the browser since 1.47.
+     *
+     * The check here used to be `schemaVersion === 1 && Array.isArray(actions)`
+     * and nothing more, which accepts a file whose actions are arbitrary
+     * objects — `verifyPlan` would then read `label` off `undefined`, match it
+     * against no slice, and report `cannot-tell: workload-vanished` for every
+     * one. A verification of a document that was never a plan, rendered exactly
+     * like a real one.
+     */
+    const parsed = parsePlanDocument(await readFile(planPath, 'utf8'));
+    if (!parsed.ok) {
+        throw new Error(t.verify.badPlan(planPath, t.verify.planRefusal(parsed.why)));
     }
+    const plan = parsed.plan;
     const GZ = LOG_EXTENSIONS.map((ext) => `${ext}.gz`);
     const READABLE = [...LOG_EXTENSIONS, ...GZ];
     const target = await stat(againstPath).catch(() => null);
@@ -3330,7 +3398,16 @@ async function commandProfile(args, config, pricing, t) {
      * way, because a waived failure that vanished from the output would be a
      * finding deleted with extra steps.
      */
-    const waived = (gate) => {
+    /**
+     * Uses recorded this run, flushed after the gates have finished.
+     *
+     * Collected rather than written inline because `waived` is synchronous and
+     * called from seven places inside the gate pass. Writing from each of them
+     * would mean seven awaits threaded through the exit-code logic — the one
+     * part of this command where a mistake turns a red build green.
+     */
+    const waiverUses = [];
+    const waived = (gate, measuredUsd = null, limitUsd = null) => {
         const found = waiverFor(gate);
         if (found === null)
             return false;
@@ -3340,6 +3417,29 @@ async function commandProfile(args, config, pricing, t) {
         }
         const daysLeft = Math.max(0, Math.ceil((Date.parse(`${found.entry.until}T00:00:00Z`) + 86_400_000 - Date.now()) / 86_400_000));
         console.error(c.yellow(t.profile.waiveActive(gate, found.entry.reason, found.entry.until, String(daysLeft))));
+        /**
+         * Recorded **when it silences something**, never when it is configured.
+         *
+         * A waiver nobody's build has ever hit is not a habit — it is dead config
+         * — and the history reports the two apart. This is also the only honest
+         * way to build the record 1.40 refused to invent: it starts today and
+         * says so, rather than reconstructing a past from the present.
+         *
+         * The reason and the expiry are taken from the config **as it stands at
+         * this moment**, because that is the decision that was actually in force.
+         * Reading today's reason back onto last quarter's use is the same mistake
+         * one layer down.
+         */
+        waiverUses.push({
+            schemaVersion: 1,
+            day: waiverDay(new Date()),
+            gate,
+            reason: found.entry.reason,
+            until: found.entry.until,
+            commit: process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? null,
+            measuredUsd,
+            limitUsd,
+        });
         return true;
     };
     const applyGates = () => {
@@ -3389,7 +3489,7 @@ async function commandProfile(args, config, pricing, t) {
                 }
                 if (usd > limit) {
                     console.error(c.red(t.profile.labelBudgetFailed(label, formatUsd(usd), formatUsd(limit))));
-                    if (!waived(`byLabel:${label}`))
+                    if (!waived(`byLabel:${label}`, usd, limit))
                         process.exitCode = 1;
                 }
                 else {
@@ -3451,7 +3551,7 @@ async function commandProfile(args, config, pricing, t) {
                  * copy says so.
                  */
                 explainFailure(report.total.totalUsd - maxUsd);
-                if (!waived('maxUsd'))
+                if (!waived('maxUsd', report.total.totalUsd, maxUsd))
                     process.exitCode = 1;
             }
             else {
@@ -3486,7 +3586,7 @@ async function commandProfile(args, config, pricing, t) {
             }
             else if (againstDelta > maxGrowth) {
                 console.error(c.red(t.profile.maxGrowthUsdFailed(formatSignedUsd(againstDelta), formatUsd(maxGrowth))));
-                if (!waived('maxGrowthUsd'))
+                if (!waived('maxGrowthUsd', againstDelta, maxGrowth))
                     process.exitCode = 1;
             }
         }
@@ -3503,12 +3603,12 @@ async function commandProfile(args, config, pricing, t) {
             const gateCache = cacheEconomics(report.total);
             if (gateCache.deltaUsd > maxLoss) {
                 console.error(c.red(t.profile.maxCacheLossFailed(formatUsd(gateCache.deltaUsd), formatUsd(maxLoss))));
-                if (!waived('maxCacheLossUsd'))
+                if (!waived('maxCacheLossUsd', gateCache.deltaUsd, maxLoss))
                     process.exitCode = 1;
             }
             else if (gateCache.worstCaseDeltaUsd > maxLoss) {
                 console.error(c.red(t.profile.maxCacheLossWorstCase(report.total.assumedWriteTtlCalls, formatUsd(gateCache.worstCaseDeltaUsd), formatUsd(maxLoss))));
-                if (!waived('maxCacheLossUsd'))
+                if (!waived('maxCacheLossUsd', gateCache.worstCaseDeltaUsd, maxLoss))
                     process.exitCode = 1;
             }
             else {
@@ -3554,7 +3654,7 @@ async function commandProfile(args, config, pricing, t) {
                 if (worst.usd > maxDay) {
                     console.error(c.red(`${t.profile.maxDayFailed(worst.day, formatUsd(worst.usd), formatUsd(maxDay))}${suspect}`));
                     explainFailure(worst.usd - maxDay, { namesLargest: true });
-                    if (!waived('maxDayUsd'))
+                    if (!waived('maxDayUsd', worst.usd, maxDay))
                         process.exitCode = 1;
                 }
                 else {
@@ -3596,7 +3696,7 @@ async function commandProfile(args, config, pricing, t) {
             else if (report.sessionSpend.maxUsd > maxSession) {
                 console.error(c.red(t.profile.maxSessionFailed(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))));
                 explainFailure(report.sessionSpend.maxUsd - maxSession);
-                if (!waived('maxSessionUsd'))
+                if (!waived('maxSessionUsd', report.sessionSpend.maxUsd, maxSession))
                     process.exitCode = 1;
             }
             else {
@@ -3629,6 +3729,26 @@ async function commandProfile(args, config, pricing, t) {
             gateFailed = process.exitCode === 1;
         }
     };
+    /**
+     * Writes down every waiver that silenced something this run.
+     *
+     * **A failure here never fails the build.** The gate's job is the exit code;
+     * a read-only checkout or a full disk must not turn a passing build red on
+     * account of bookkeeping. The problem is reported and the gate's own verdict
+     * stands — which is also why this runs after `recordGates` rather than
+     * inside it: nothing about the exit code depends on the write.
+     */
+    const recordWaiverUses = async () => {
+        if (waiverUses.length === 0)
+            return;
+        for (const use of waiverUses) {
+            const failed = await appendWaiverUse('.', use);
+            if (failed !== null) {
+                console.error(c.dim(t.profile.waiveNotRecorded(WAIVER_LOG, failed)));
+                return;
+            }
+        }
+    };
     /**
      * The side files the caller asked for. Written on **both** output paths:
      * under --json the human rendering returns early, and the first version of
@@ -3777,6 +3897,7 @@ async function commandProfile(args, config, pricing, t) {
             ...(whatIf !== null ? { whatIf } : {}),
         }, null, 2));
         recordGates();
+        await recordWaiverUses();
         await writeSideFiles();
         return;
     }
@@ -4784,6 +4905,7 @@ async function commandProfile(args, config, pricing, t) {
     }
     reportProfileGaps(report, t, n, pricingStale);
     recordGates();
+    await recordWaiverUses();
     await writeSideFiles();
 }
 /**
@@ -6080,7 +6202,7 @@ async function main() {
             await commandVerify(args, pricing, t);
             break;
         case 'history':
-            await commandHistory(args, pricing, t);
+            await commandHistory(args, config, pricing, t);
             break;
         case 'connect':
             await commandConnect(args, pricing, t);