@trazum/cli 1.46.0 → 1.48.0

package/src/waiver-log.ts

@@ -0,0 +1,81 @@
+/**
+ * Where a waiver's uses are written down.
+ *
+ * The core decides what a use means and what a run of them adds up to; this
+ * decides where the bytes go — the same split every module here follows, so
+ * `@trazum/core` stays browser-safe and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, and never rewritten.** There is deliberately no prune, no
+ * compaction and no `--clear`: a record of decisions that the tool can erase
+ * is a record nobody can rely on, and the one thing a waiver history is for is
+ * being awkward six months later. Deleting the file is a thing a person does
+ * with `rm`, on purpose, having seen it.
+ *
+ * **A write that fails never fails the run.** The gate's job is the exit code.
+ * A read-only checkout, a full disk or a directory somebody's CI cannot create
+ * must not turn a passing build red on account of bookkeeping — the failure is
+ * reported and the gate's own verdict stands.
+ *
+ * **A line that will not parse is counted and skipped**, exactly as in the
+ * store. Losing the whole history because one line is broken would be the
+ * worst possible response; pretending the history is complete would be the
+ * second worst.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isWaiverUse } from '@trazum/core';
+import type { WaiverUse } from '@trazum/core';
+
+/** One file, not one per month: a waiver history is small and read whole. */
+export const WAIVER_LOG = '.trazum/waivers.jsonl';
+
+export interface WaiverReadResult {
+  uses: WaiverUse[];
+  /** 1-based positions of lines that would not parse. Named, never dropped quietly. */
+  unreadable: number[];
+  /** False when the file does not exist — "nothing recorded" is not "no file". */
+  present: boolean;
+}
+
+export async function readWaiverLog(root: string): Promise<WaiverReadResult> {
+  let raw: string;
+  try {
+    raw = await readFile(join(root, WAIVER_LOG), 'utf8');
+  } catch {
+    // Absent is the normal state of a repository that has never waived
+    // anything, and it is not an error.
+    return { uses: [], unreadable: [], present: false };
+  }
+
+  const uses: WaiverUse[] = [];
+  const unreadable: number[] = [];
+  raw.split('\n').forEach((line, index) => {
+    if (line.trim() === '') return;
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (isWaiverUse(parsed)) uses.push(parsed);
+      else unreadable.push(index + 1);
+    } catch {
+      unreadable.push(index + 1);
+    }
+  });
+  return { uses, unreadable, present: true };
+}
+
+/**
+ * Appends one use, and swallows any failure after reporting it.
+ *
+ * Returns the error message rather than throwing, so the caller can print it
+ * beside the gate's own output without the gate ever depending on the write.
+ */
+export async function appendWaiverUse(root: string, use: WaiverUse): Promise<string | null> {
+  const path = join(root, WAIVER_LOG);
+  try {
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, `${JSON.stringify(use)}\n`, { flag: 'a', mode: 0o600 });
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}