@metamask-previews/tooling-insight 1.0.1-preview-898fae5

package/dist/lib/fold.d.mts

@@ -0,0 +1,32 @@
+import type { Allowlist, SamplePoint, ToolEvent } from "./types.mjs";
+/**
+ * Classic histogram bucket upper bounds in milliseconds, covering sub-second
+ * scripts up to ~10 minutes. A synthetic `+Inf` bucket is always appended.
+ */
+export declare const DURATION_BUCKETS_MS: readonly number[];
+/**
+ * Fold raw CSV events into anonymized Prometheus sample points for pending days.
+ *
+ * @param events - All parsed tool events.
+ * @param allowlist - Skill and script allowlists used to filter events.
+ * @param instanceUuid - Per-install UUID used as the Prometheus `instance` label.
+ * @param lastPushedDay - The last UTC day that was successfully pushed, or null.
+ * @param todayUtc - The current UTC day (events on this day are not yet pushed).
+ * @returns An array of sample points ready for Prometheus exposition.
+ */
+export declare function fold(events: ToolEvent[], allowlist: Allowlist, instanceUuid: string, lastPushedDay: string | null, todayUtc: string): SamplePoint[];
+/**
+ * Returns the current UTC calendar day as `YYYY-MM-DD`.
+ *
+ * @param now - The current date; defaults to `new Date()`.
+ * @returns The UTC day string.
+ */
+export declare function todayUtcDay(now?: Date): string;
+/**
+ * Returns the latest `day` value across all sample points, or null for an empty array.
+ *
+ * @param samples - The sample points to inspect.
+ * @returns The maximum UTC day string, or null.
+ */
+export declare function maxDay(samples: SamplePoint[]): string | null;
+//# sourceMappingURL=fold.d.mts.map

package/dist/lib/fold.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.d.mts","sourceRoot":"","sources":["../../src/lib/fold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAIT,WAAW,EACX,SAAS,EACV,oBAAgB;AAQjB;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAEhD,CAAC;AA8JF;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAClB,MAAM,EAAE,SAAS,EAAE,EACnB,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,QAAQ,EAAE,MAAM,GACf,WAAW,EAAE,CA6If;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,OAAa,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,GAAG,IAAI,CAS5D"}

package/dist/lib/fold.mjs

@@ -0,0 +1,288 @@
+const TERMINAL_EVENT_TYPES = new Set([
+    'success',
+    'failure',
+    'interrupted',
+]);
+/**
+ * Classic histogram bucket upper bounds in milliseconds, covering sub-second
+ * scripts up to ~10 minutes. A synthetic `+Inf` bucket is always appended.
+ */
+export const DURATION_BUCKETS_MS = [
+    100, 250, 500, 1000, 2000, 5000, 10000, 30000, 60000, 120000, 300000, 600000,
+];
+/**
+ * Extract the UTC calendar day from an ISO-8601 timestamp string.
+ *
+ * @param iso - An ISO-8601 timestamp string.
+ * @returns The `YYYY-MM-DD` portion of the timestamp.
+ */
+function utcDayFromIso(iso) {
+    return iso.slice(0, 10);
+}
+/**
+ * Convert a `YYYY-MM-DD` UTC day string to a Unix timestamp at midnight UTC.
+ *
+ * @param day - A UTC day string in `YYYY-MM-DD` format.
+ * @returns Milliseconds since epoch for midnight UTC on that day.
+ */
+function utcMidnightMs(day) {
+    const parts = day.split('-');
+    const year = Number(parts[0]);
+    const month = Number(parts[1]);
+    const dayOfMonth = Number(parts[2]);
+    return Date.UTC(year, month - 1, dayOfMonth);
+}
+/**
+ * Returns true when a given day has pending (unpushed) events.
+ * Today's events are excluded so the day is complete before pushing.
+ *
+ * @param day - UTC calendar day of the event.
+ * @param lastPushedDay - The most recently pushed day, or `null` if never pushed.
+ * @param todayUtc - The current UTC calendar day.
+ * @returns `true` when the day is after `lastPushedDay` and before today.
+ */
+function isDayPending(day, lastPushedDay, todayUtc) {
+    if (day >= todayUtc) {
+        return false;
+    }
+    if (lastPushedDay === null) {
+        return true;
+    }
+    return day > lastPushedDay;
+}
+/**
+ * Strip the well-known tool-type prefix (`skill:` or `yarn:`) from a tool name.
+ *
+ * @param toolName - Raw tool name from the CSV event.
+ * @param toolType - The parsed tool type for the event.
+ * @returns The tool name without its prefix, or unchanged when no prefix matches.
+ */
+function stripToolName(toolName, toolType) {
+    if (toolType === 'skill' && toolName.startsWith('skill:')) {
+        return toolName.slice('skill:'.length);
+    }
+    if (toolType === 'yarn_script' && toolName.startsWith('yarn:')) {
+        return toolName.slice('yarn:'.length);
+    }
+    return toolName;
+}
+/**
+ * Map a raw CSV event to its Prometheus `event_type` label value.
+ * Returns `null` for `end` events whose `success` field is not a boolean.
+ *
+ * @param event - The raw tool event to classify.
+ * @returns The corresponding `EventTypeLabel`, or `null` to drop the event.
+ */
+function mapEventType(event) {
+    // Switch over the exhaustive CsvEventType union.
+    switch (event.event_type) {
+        case 'start':
+            return 'start';
+        case 'interrupted':
+            return 'interrupted';
+        case 'end':
+            if (event.success === true) {
+                return 'success';
+            }
+            if (event.success === false) {
+                return 'failure';
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Returns true when the stripped tool name appears on the allowlist for its type.
+ *
+ * @param strippedName - Tool name after prefix stripping.
+ * @param toolType - The tool type (skill or yarn_script).
+ * @param allowlist - The combined skill and script allowlist.
+ * @returns `true` when the tool is allowlisted.
+ */
+function isAllowlisted(strippedName, toolType, allowlist) {
+    if (toolType === 'skill') {
+        // The allowlist is built from the MetaMask/ConsenSys skills repo cache:
+        // extractSkillNames reads directory names (e.g. `create-pr`) and stores
+        // them with the `mms-` prefix (e.g. `mms-create-pr`). A skill event passes
+        // only when its logged name — after stripping the `skill:` type prefix —
+        // is found verbatim in that Set. Skills not present in the repo cache
+        // (e.g. personal Cursor skills logged as `skill:pr-review-queue`) never
+        // match because the Set has `mms-pr-review-queue`, not `pr-review-queue`.
+        return allowlist.skills.has(strippedName);
+    }
+    return allowlist.scripts.has(strippedName);
+}
+/**
+ * Build a stable string key that uniquely identifies a (day, labels, metric) combination.
+ *
+ * @param day - UTC calendar day string.
+ * @param labels - Prometheus label set for the sample.
+ * @param metric - Prometheus metric name.
+ * @returns A JSON-serialised key.
+ */
+function groupKey(day, labels, metric) {
+    return JSON.stringify({ day, metric, labels });
+}
+/**
+ * Fold raw CSV events into anonymized Prometheus sample points for pending days.
+ *
+ * @param events - All parsed tool events.
+ * @param allowlist - Skill and script allowlists used to filter events.
+ * @param instanceUuid - Per-install UUID used as the Prometheus `instance` label.
+ * @param lastPushedDay - The last UTC day that was successfully pushed, or null.
+ * @param todayUtc - The current UTC day (events on this day are not yet pushed).
+ * @returns An array of sample points ready for Prometheus exposition.
+ */
+export function fold(events, allowlist, instanceUuid, lastPushedDay, todayUtc) {
+    const usageCounts = new Map();
+    const durationSums = new Map();
+    // Keyed by the same group key as durationSums (terminal events with a duration).
+    const durationHistograms = new Map();
+    for (const event of events) {
+        const day = utcDayFromIso(event.created_at);
+        if (!isDayPending(day, lastPushedDay, todayUtc)) {
+            continue;
+        }
+        const strippedName = stripToolName(event.tool_name, event.tool_type);
+        if (!isAllowlisted(strippedName, event.tool_type, allowlist)) {
+            continue;
+        }
+        const eventTypeLabel = mapEventType(event);
+        if (!eventTypeLabel) {
+            continue;
+        }
+        const labels = {
+            repo: event.repo,
+            tool_name: strippedName,
+            tool_type: event.tool_type,
+            event_type: eventTypeLabel,
+            agent_vendor: event.agent_vendor,
+            instance: instanceUuid,
+        };
+        const usageMetric = 'metamask_devtools_usage_count';
+        const usageKey = groupKey(day, labels, usageMetric);
+        const existingUsage = usageCounts.get(usageKey);
+        if (existingUsage) {
+            existingUsage.value += 1;
+        }
+        else {
+            usageCounts.set(usageKey, {
+                metric: usageMetric,
+                labels,
+                value: 1,
+                day,
+                timestampMs: utcMidnightMs(day),
+            });
+        }
+        if (TERMINAL_EVENT_TYPES.has(eventTypeLabel) &&
+            event.duration_ms !== null) {
+            const durationMetric = 'metamask_devtools_duration_sum_ms';
+            const durationKey = groupKey(day, labels, durationMetric);
+            const existingDuration = durationSums.get(durationKey);
+            if (existingDuration) {
+                existingDuration.value += event.duration_ms;
+            }
+            else {
+                durationSums.set(durationKey, {
+                    metric: durationMetric,
+                    labels,
+                    value: event.duration_ms,
+                    day,
+                    timestampMs: utcMidnightMs(day),
+                });
+            }
+            // Accumulate the histogram for the same group key (reuse durationKey
+            // since both are keyed on the same (day, labels) combination).
+            const existing = durationHistograms.get(durationKey);
+            if (existing) {
+                existing.sum += event.duration_ms;
+                existing.count += 1;
+                // Cumulative: increment every bucket whose upper bound >= duration.
+                existing.bucketCounts = existing.bucketCounts.map((count, i) => event.duration_ms !== null &&
+                    event.duration_ms <= DURATION_BUCKETS_MS[i]
+                    ? count + 1
+                    : count);
+            }
+            else {
+                const bucketCounts = DURATION_BUCKETS_MS.map((bound) => event.duration_ms !== null && event.duration_ms <= bound ? 1 : 0);
+                durationHistograms.set(durationKey, {
+                    day,
+                    labels,
+                    sum: event.duration_ms,
+                    count: 1,
+                    bucketCounts,
+                });
+            }
+        }
+    }
+    const histogramSamples = [];
+    for (const acc of durationHistograms.values()) {
+        const { day, labels } = acc;
+        const timestampMs = utcMidnightMs(day);
+        histogramSamples.push({
+            metric: 'metamask_devtools_duration_ms_sum',
+            labels,
+            value: acc.sum,
+            day,
+            timestampMs,
+        });
+        histogramSamples.push({
+            metric: 'metamask_devtools_duration_ms_count',
+            labels,
+            value: acc.count,
+            day,
+            timestampMs,
+        });
+        acc.bucketCounts.forEach((count, i) => {
+            histogramSamples.push({
+                metric: 'metamask_devtools_duration_ms_bucket',
+                labels,
+                value: count,
+                day,
+                timestampMs,
+                le: String(DURATION_BUCKETS_MS[i]),
+            });
+        });
+        // The +Inf bucket equals total count (every observation falls below +Inf).
+        histogramSamples.push({
+            metric: 'metamask_devtools_duration_ms_bucket',
+            labels,
+            value: acc.count,
+            day,
+            timestampMs,
+            le: '+Inf',
+        });
+    }
+    return [
+        ...usageCounts.values(),
+        ...durationSums.values(),
+        ...histogramSamples,
+    ];
+}
+/**
+ * Returns the current UTC calendar day as `YYYY-MM-DD`.
+ *
+ * @param now - The current date; defaults to `new Date()`.
+ * @returns The UTC day string.
+ */
+export function todayUtcDay(now = new Date()) {
+    return now.toISOString().slice(0, 10);
+}
+/**
+ * Returns the latest `day` value across all sample points, or null for an empty array.
+ *
+ * @param samples - The sample points to inspect.
+ * @returns The maximum UTC day string, or null.
+ */
+export function maxDay(samples) {
+    if (samples.length === 0) {
+        return null;
+    }
+    // Reduce over string[] so there is no undefined initial value issue — reduce without
+    // initialValue on a non-empty array is always safe and avoids a dead branch.
+    return samples
+        .map((sample) => sample.day)
+        .reduce((max, day) => (day > max ? day : max));
+}
+//# sourceMappingURL=fold.mjs.map

package/dist/lib/fold.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.mjs","sourceRoot":"","sources":["../../src/lib/fold.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  Allowlist,\n  EventTypeLabel,\n  MetricName,\n  SampleLabels,\n  SamplePoint,\n  ToolEvent,\n} from './types';\n\nconst TERMINAL_EVENT_TYPES: ReadonlySet<EventTypeLabel> = new Set([\n  'success',\n  'failure',\n  'interrupted',\n]);\n\n/**\n * Classic histogram bucket upper bounds in milliseconds, covering sub-second\n * scripts up to ~10 minutes. A synthetic `+Inf` bucket is always appended.\n */\nexport const DURATION_BUCKETS_MS: readonly number[] = [\n  100, 250, 500, 1000, 2000, 5000, 10000, 30000, 60000, 120000, 300000, 600000,\n];\n\n/** Accumulated histogram state for a single group/day. */\ntype HistogramAccumulator = {\n  /** UTC calendar day this group belongs to. */\n  day: string;\n  /** Prometheus label set shared by every sample in this group. */\n  labels: SampleLabels;\n  /** Sum of all observed durations for this group. */\n  sum: number;\n  /** Count of all observed durations for this group. */\n  count: number;\n  /**\n   * Cumulative bucket counts, one entry per `DURATION_BUCKETS_MS` boundary.\n   * `bucketCounts[i]` is the number of observations where `duration_ms <= DURATION_BUCKETS_MS[i]`.\n   */\n  bucketCounts: number[];\n};\n\n/**\n * Extract the UTC calendar day from an ISO-8601 timestamp string.\n *\n * @param iso - An ISO-8601 timestamp string.\n * @returns The `YYYY-MM-DD` portion of the timestamp.\n */\nfunction utcDayFromIso(iso: string): string {\n  return iso.slice(0, 10);\n}\n\n/**\n * Convert a `YYYY-MM-DD` UTC day string to a Unix timestamp at midnight UTC.\n *\n * @param day - A UTC day string in `YYYY-MM-DD` format.\n * @returns Milliseconds since epoch for midnight UTC on that day.\n */\nfunction utcMidnightMs(day: string): number {\n  const parts = day.split('-');\n  const year = Number(parts[0]);\n  const month = Number(parts[1]);\n  const dayOfMonth = Number(parts[2]);\n  return Date.UTC(year, month - 1, dayOfMonth);\n}\n\n/**\n * Returns true when a given day has pending (unpushed) events.\n * Today's events are excluded so the day is complete before pushing.\n *\n * @param day - UTC calendar day of the event.\n * @param lastPushedDay - The most recently pushed day, or `null` if never pushed.\n * @param todayUtc - The current UTC calendar day.\n * @returns `true` when the day is after `lastPushedDay` and before today.\n */\nfunction isDayPending(\n  day: string,\n  lastPushedDay: string | null,\n  todayUtc: string,\n): boolean {\n  if (day >= todayUtc) {\n    return false;\n  }\n  if (lastPushedDay === null) {\n    return true;\n  }\n  return day > lastPushedDay;\n}\n\n/**\n * Strip the well-known tool-type prefix (`skill:` or `yarn:`) from a tool name.\n *\n * @param toolName - Raw tool name from the CSV event.\n * @param toolType - The parsed tool type for the event.\n * @returns The tool name without its prefix, or unchanged when no prefix matches.\n */\nfunction stripToolName(\n  toolName: string,\n  toolType: ToolEvent['tool_type'],\n): string {\n  if (toolType === 'skill' && toolName.startsWith('skill:')) {\n    return toolName.slice('skill:'.length);\n  }\n  if (toolType === 'yarn_script' && toolName.startsWith('yarn:')) {\n    return toolName.slice('yarn:'.length);\n  }\n  return toolName;\n}\n\n/**\n * Map a raw CSV event to its Prometheus `event_type` label value.\n * Returns `null` for `end` events whose `success` field is not a boolean.\n *\n * @param event - The raw tool event to classify.\n * @returns The corresponding `EventTypeLabel`, or `null` to drop the event.\n */\nfunction mapEventType(event: ToolEvent): EventTypeLabel | null {\n  // Switch over the exhaustive CsvEventType union.\n  switch (event.event_type) {\n    case 'start':\n      return 'start';\n    case 'interrupted':\n      return 'interrupted';\n    case 'end':\n      if (event.success === true) {\n        return 'success';\n      }\n      if (event.success === false) {\n        return 'failure';\n      }\n      return null;\n    default:\n      return null;\n  }\n}\n\n/**\n * Returns true when the stripped tool name appears on the allowlist for its type.\n *\n * @param strippedName - Tool name after prefix stripping.\n * @param toolType - The tool type (skill or yarn_script).\n * @param allowlist - The combined skill and script allowlist.\n * @returns `true` when the tool is allowlisted.\n */\nfunction isAllowlisted(\n  strippedName: string,\n  toolType: ToolEvent['tool_type'],\n  allowlist: Allowlist,\n): boolean {\n  if (toolType === 'skill') {\n    // The allowlist is built from the MetaMask/ConsenSys skills repo cache:\n    // extractSkillNames reads directory names (e.g. `create-pr`) and stores\n    // them with the `mms-` prefix (e.g. `mms-create-pr`). A skill event passes\n    // only when its logged name — after stripping the `skill:` type prefix —\n    // is found verbatim in that Set. Skills not present in the repo cache\n    // (e.g. personal Cursor skills logged as `skill:pr-review-queue`) never\n    // match because the Set has `mms-pr-review-queue`, not `pr-review-queue`.\n    return allowlist.skills.has(strippedName);\n  }\n  return allowlist.scripts.has(strippedName);\n}\n\n/** Opaque key used to group events into a single `SamplePoint`. */\ntype GroupKey = string;\n\n/**\n * Build a stable string key that uniquely identifies a (day, labels, metric) combination.\n *\n * @param day - UTC calendar day string.\n * @param labels - Prometheus label set for the sample.\n * @param metric - Prometheus metric name.\n * @returns A JSON-serialised key.\n */\nfunction groupKey(\n  day: string,\n  labels: SampleLabels,\n  metric: MetricName,\n): GroupKey {\n  return JSON.stringify({ day, metric, labels });\n}\n\n/**\n * Fold raw CSV events into anonymized Prometheus sample points for pending days.\n *\n * @param events - All parsed tool events.\n * @param allowlist - Skill and script allowlists used to filter events.\n * @param instanceUuid - Per-install UUID used as the Prometheus `instance` label.\n * @param lastPushedDay - The last UTC day that was successfully pushed, or null.\n * @param todayUtc - The current UTC day (events on this day are not yet pushed).\n * @returns An array of sample points ready for Prometheus exposition.\n */\nexport function fold(\n  events: ToolEvent[],\n  allowlist: Allowlist,\n  instanceUuid: string,\n  lastPushedDay: string | null,\n  todayUtc: string,\n): SamplePoint[] {\n  const usageCounts = new Map<GroupKey, SamplePoint>();\n  const durationSums = new Map<GroupKey, SamplePoint>();\n  // Keyed by the same group key as durationSums (terminal events with a duration).\n  const durationHistograms = new Map<GroupKey, HistogramAccumulator>();\n\n  for (const event of events) {\n    const day = utcDayFromIso(event.created_at);\n    if (!isDayPending(day, lastPushedDay, todayUtc)) {\n      continue;\n    }\n\n    const strippedName = stripToolName(event.tool_name, event.tool_type);\n    if (!isAllowlisted(strippedName, event.tool_type, allowlist)) {\n      continue;\n    }\n\n    const eventTypeLabel = mapEventType(event);\n    if (!eventTypeLabel) {\n      continue;\n    }\n\n    const labels: SampleLabels = {\n      repo: event.repo,\n      tool_name: strippedName,\n      tool_type: event.tool_type,\n      event_type: eventTypeLabel,\n      agent_vendor: event.agent_vendor,\n      instance: instanceUuid,\n    };\n\n    const usageMetric: MetricName = 'metamask_devtools_usage_count';\n    const usageKey = groupKey(day, labels, usageMetric);\n    const existingUsage = usageCounts.get(usageKey);\n    if (existingUsage) {\n      existingUsage.value += 1;\n    } else {\n      usageCounts.set(usageKey, {\n        metric: usageMetric,\n        labels,\n        value: 1,\n        day,\n        timestampMs: utcMidnightMs(day),\n      });\n    }\n\n    if (\n      TERMINAL_EVENT_TYPES.has(eventTypeLabel) &&\n      event.duration_ms !== null\n    ) {\n      const durationMetric: MetricName = 'metamask_devtools_duration_sum_ms';\n      const durationKey = groupKey(day, labels, durationMetric);\n      const existingDuration = durationSums.get(durationKey);\n      if (existingDuration) {\n        existingDuration.value += event.duration_ms;\n      } else {\n        durationSums.set(durationKey, {\n          metric: durationMetric,\n          labels,\n          value: event.duration_ms,\n          day,\n          timestampMs: utcMidnightMs(day),\n        });\n      }\n\n      // Accumulate the histogram for the same group key (reuse durationKey\n      // since both are keyed on the same (day, labels) combination).\n      const existing = durationHistograms.get(durationKey);\n      if (existing) {\n        existing.sum += event.duration_ms;\n        existing.count += 1;\n        // Cumulative: increment every bucket whose upper bound >= duration.\n        existing.bucketCounts = existing.bucketCounts.map((count, i) =>\n          event.duration_ms !== null &&\n          event.duration_ms <= (DURATION_BUCKETS_MS[i] as number)\n            ? count + 1\n            : count,\n        );\n      } else {\n        const bucketCounts = DURATION_BUCKETS_MS.map((bound) =>\n          event.duration_ms !== null && event.duration_ms <= bound ? 1 : 0,\n        );\n        durationHistograms.set(durationKey, {\n          day,\n          labels,\n          sum: event.duration_ms,\n          count: 1,\n          bucketCounts,\n        });\n      }\n    }\n  }\n\n  const histogramSamples: SamplePoint[] = [];\n  for (const acc of durationHistograms.values()) {\n    const { day, labels } = acc;\n    const timestampMs = utcMidnightMs(day);\n\n    histogramSamples.push({\n      metric: 'metamask_devtools_duration_ms_sum',\n      labels,\n      value: acc.sum,\n      day,\n      timestampMs,\n    });\n\n    histogramSamples.push({\n      metric: 'metamask_devtools_duration_ms_count',\n      labels,\n      value: acc.count,\n      day,\n      timestampMs,\n    });\n\n    acc.bucketCounts.forEach((count, i) => {\n      histogramSamples.push({\n        metric: 'metamask_devtools_duration_ms_bucket',\n        labels,\n        value: count,\n        day,\n        timestampMs,\n        le: String(DURATION_BUCKETS_MS[i]),\n      });\n    });\n\n    // The +Inf bucket equals total count (every observation falls below +Inf).\n    histogramSamples.push({\n      metric: 'metamask_devtools_duration_ms_bucket',\n      labels,\n      value: acc.count,\n      day,\n      timestampMs,\n      le: '+Inf',\n    });\n  }\n\n  return [\n    ...usageCounts.values(),\n    ...durationSums.values(),\n    ...histogramSamples,\n  ];\n}\n\n/**\n * Returns the current UTC calendar day as `YYYY-MM-DD`.\n *\n * @param now - The current date; defaults to `new Date()`.\n * @returns The UTC day string.\n */\nexport function todayUtcDay(now = new Date()): string {\n  return now.toISOString().slice(0, 10);\n}\n\n/**\n * Returns the latest `day` value across all sample points, or null for an empty array.\n *\n * @param samples - The sample points to inspect.\n * @returns The maximum UTC day string, or null.\n */\nexport function maxDay(samples: SamplePoint[]): string | null {\n  if (samples.length === 0) {\n    return null;\n  }\n  // Reduce over string[] so there is no undefined initial value issue — reduce without\n  // initialValue on a non-empty array is always safe and avoids a dead branch.\n  return samples\n    .map((sample) => sample.day)\n    .reduce((max, day) => (day > max ? day : max));\n}\n"]}

package/dist/lib/log.cjs

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = createLogger;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const paths_1 = require("./paths.cjs");
+const MAX_LOG_BYTES = 1024 * 1024;
+const MAX_ROTATED = 3;
+/**
+ * Create the log directory if it does not yet exist.
+ *
+ * @param path - Absolute path to the log file whose parent directory to create.
+ */
+function ensureLogDir(path) {
+    const dir = (0, node_path_1.dirname)(path);
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    }
+}
+/**
+ * Rotate the log file when it exceeds 1 MiB.
+ *
+ * @param path - Absolute path to the log file to rotate.
+ */
+function rotateIfNeeded(path) {
+    if (!(0, node_fs_1.existsSync)(path)) {
+        return;
+    }
+    const { size } = (0, node_fs_1.statSync)(path);
+    if (size <= MAX_LOG_BYTES) {
+        return;
+    }
+    for (let index = MAX_ROTATED; index >= 1; index -= 1) {
+        const from = index === 1 ? path : `${path}.${index - 1}`;
+        const to = `${path}.${index}`;
+        if ((0, node_fs_1.existsSync)(from)) {
+            if ((0, node_fs_1.existsSync)(to)) {
+                (0, node_fs_1.unlinkSync)(to);
+            }
+            (0, node_fs_1.renameSync)(from, to);
+        }
+    }
+}
+/**
+ * Create a structured logger that appends JSON lines to the anonymizer log file,
+ * rotating when the file exceeds 1 MiB.
+ *
+ * @param cli - The CLI name to embed in every log entry.
+ * @param logPath - Path to the log file; defaults to the configured anonymizer log path.
+ * @returns An object with `info`, `error`, and `readLog` methods.
+ */
+function createLogger(cli, logPath = (0, paths_1.getAnonymizerLogPath)()) {
+    /**
+     * Append an entry to the log file, rotating first when needed.
+     *
+     * @param entry - The log entry to serialise.
+     * @param verbose - When true, also writes to stdout.
+     */
+    const write = (entry, verbose) => {
+        ensureLogDir(logPath);
+        rotateIfNeeded(logPath);
+        const line = `${JSON.stringify(entry)}\n`;
+        (0, node_fs_1.writeFileSync)(logPath, line, { flag: 'a' });
+        if (verbose) {
+            process.stdout.write(line);
+        }
+    };
+    return {
+        /**
+         * Log an informational message.
+         *
+         * @param message - The message to log.
+         * @param extra - Optional extra data to attach to the log entry.
+         * @param verbose - When true, also writes to stdout.
+         */
+        info(message, extra, verbose = false) {
+            write({
+                ts: new Date().toISOString(),
+                cli,
+                level: 'info',
+                message,
+                // exactOptionalPropertyTypes: omit the key when undefined rather than
+                // assigning undefined to an optional property.
+                ...(extra === undefined ? {} : { extra }),
+            }, verbose);
+        },
+        /**
+         * Log an error message.
+         *
+         * @param message - The message to log.
+         * @param extra - Optional extra data to attach to the log entry.
+         * @param verbose - When true, also writes to stdout.
+         */
+        error(message, extra, verbose = false) {
+            write({
+                ts: new Date().toISOString(),
+                cli,
+                level: 'error',
+                message,
+                ...(extra === undefined ? {} : { extra }),
+            }, verbose);
+        },
+        /**
+         * Read the full contents of the log file.
+         *
+         * @returns The log file contents, or an empty string if the file does not exist.
+         */
+        readLog() {
+            if (!(0, node_fs_1.existsSync)(logPath)) {
+                return '';
+            }
+            return (0, node_fs_1.readFileSync)(logPath, 'utf8');
+        },
+    };
+}
+//# sourceMappingURL=log.cjs.map

package/dist/lib/log.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.cjs","sourceRoot":"","sources":["../../src/lib/log.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  existsSync,\n  mkdirSync,\n  readFileSync,\n  renameSync,\n  statSync,\n  unlinkSync,\n  writeFileSync,\n} from 'node:fs';\nimport { dirname } from 'node:path';\n\nimport { getAnonymizerLogPath } from './paths';\n\n/** One structured log entry written to the anonymizer log file. */\nexport type LogEntry = {\n  /** ISO-8601 timestamp of when the entry was written. */\n  ts: string;\n  /** The CLI name that produced the entry. */\n  cli: string;\n  /** Severity level. */\n  level: 'info' | 'error';\n  /** Human-readable message. */\n  message: string;\n  /** Optional extra structured data to attach to the entry. */\n  extra?: Record<string, unknown>;\n};\n\n/** The type returned by `createLogger`. */\nexport type LoggerInstance = {\n  /** Log an informational message. */\n  info: (\n    message: string,\n    extra?: Record<string, unknown>,\n    verbose?: boolean,\n  ) => void;\n  /** Log an error message. */\n  error: (\n    message: string,\n    extra?: Record<string, unknown>,\n    verbose?: boolean,\n  ) => void;\n  /** Read the full contents of the log file. */\n  readLog: () => string;\n};\n\nconst MAX_LOG_BYTES = 1024 * 1024;\nconst MAX_ROTATED = 3;\n\n/**\n * Create the log directory if it does not yet exist.\n *\n * @param path - Absolute path to the log file whose parent directory to create.\n */\nfunction ensureLogDir(path: string): void {\n  const dir = dirname(path);\n  if (!existsSync(dir)) {\n    mkdirSync(dir, { recursive: true });\n  }\n}\n\n/**\n * Rotate the log file when it exceeds 1 MiB.\n *\n * @param path - Absolute path to the log file to rotate.\n */\nfunction rotateIfNeeded(path: string): void {\n  if (!existsSync(path)) {\n    return;\n  }\n  const { size } = statSync(path);\n  if (size <= MAX_LOG_BYTES) {\n    return;\n  }\n  for (let index = MAX_ROTATED; index >= 1; index -= 1) {\n    const from = index === 1 ? path : `${path}.${index - 1}`;\n    const to = `${path}.${index}`;\n    if (existsSync(from)) {\n      if (existsSync(to)) {\n        unlinkSync(to);\n      }\n      renameSync(from, to);\n    }\n  }\n}\n\n/**\n * Create a structured logger that appends JSON lines to the anonymizer log file,\n * rotating when the file exceeds 1 MiB.\n *\n * @param cli - The CLI name to embed in every log entry.\n * @param logPath - Path to the log file; defaults to the configured anonymizer log path.\n * @returns An object with `info`, `error`, and `readLog` methods.\n */\nexport function createLogger(\n  cli: string,\n  logPath = getAnonymizerLogPath(),\n): LoggerInstance {\n  /**\n   * Append an entry to the log file, rotating first when needed.\n   *\n   * @param entry - The log entry to serialise.\n   * @param verbose - When true, also writes to stdout.\n   */\n  const write = (entry: LogEntry, verbose: boolean): void => {\n    ensureLogDir(logPath);\n    rotateIfNeeded(logPath);\n    const line = `${JSON.stringify(entry)}\\n`;\n    writeFileSync(logPath, line, { flag: 'a' });\n    if (verbose) {\n      process.stdout.write(line);\n    }\n  };\n\n  return {\n    /**\n     * Log an informational message.\n     *\n     * @param message - The message to log.\n     * @param extra - Optional extra data to attach to the log entry.\n     * @param verbose - When true, also writes to stdout.\n     */\n    info(\n      message: string,\n      extra?: Record<string, unknown>,\n      verbose = false,\n    ): void {\n      write(\n        {\n          ts: new Date().toISOString(),\n          cli,\n          level: 'info',\n          message,\n          // exactOptionalPropertyTypes: omit the key when undefined rather than\n          // assigning undefined to an optional property.\n          ...(extra === undefined ? {} : { extra }),\n        },\n        verbose,\n      );\n    },\n    /**\n     * Log an error message.\n     *\n     * @param message - The message to log.\n     * @param extra - Optional extra data to attach to the log entry.\n     * @param verbose - When true, also writes to stdout.\n     */\n    error(\n      message: string,\n      extra?: Record<string, unknown>,\n      verbose = false,\n    ): void {\n      write(\n        {\n          ts: new Date().toISOString(),\n          cli,\n          level: 'error',\n          message,\n          ...(extra === undefined ? {} : { extra }),\n        },\n        verbose,\n      );\n    },\n    /**\n     * Read the full contents of the log file.\n     *\n     * @returns The log file contents, or an empty string if the file does not exist.\n     */\n    readLog(): string {\n      if (!existsSync(logPath)) {\n        return '';\n      }\n      return readFileSync(logPath, 'utf8');\n    },\n  };\n}\n"]}

package/dist/lib/log.d.cts

@@ -0,0 +1,32 @@
+/** One structured log entry written to the anonymizer log file. */
+export type LogEntry = {
+    /** ISO-8601 timestamp of when the entry was written. */
+    ts: string;
+    /** The CLI name that produced the entry. */
+    cli: string;
+    /** Severity level. */
+    level: 'info' | 'error';
+    /** Human-readable message. */
+    message: string;
+    /** Optional extra structured data to attach to the entry. */
+    extra?: Record<string, unknown>;
+};
+/** The type returned by `createLogger`. */
+export type LoggerInstance = {
+    /** Log an informational message. */
+    info: (message: string, extra?: Record<string, unknown>, verbose?: boolean) => void;
+    /** Log an error message. */
+    error: (message: string, extra?: Record<string, unknown>, verbose?: boolean) => void;
+    /** Read the full contents of the log file. */
+    readLog: () => string;
+};
+/**
+ * Create a structured logger that appends JSON lines to the anonymizer log file,
+ * rotating when the file exceeds 1 MiB.
+ *
+ * @param cli - The CLI name to embed in every log entry.
+ * @param logPath - Path to the log file; defaults to the configured anonymizer log path.
+ * @returns An object with `info`, `error`, and `readLog` methods.
+ */
+export declare function createLogger(cli: string, logPath?: string): LoggerInstance;
+//# sourceMappingURL=log.d.cts.map

package/dist/lib/log.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.cts","sourceRoot":"","sources":["../../src/lib/log.ts"],"names":[],"mappings":"AAaA,mEAAmE;AACnE,MAAM,MAAM,QAAQ,GAAG;IACrB,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,IAAI,EAAE,CACJ,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,KACd,IAAI,CAAC;IACV,4BAA4B;IAC5B,KAAK,EAAE,CACL,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,KACd,IAAI,CAAC;IACV,8CAA8C;IAC9C,OAAO,EAAE,MAAM,MAAM,CAAC;CACvB,CAAC;AA0CF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,OAAO,SAAyB,GAC/B,cAAc,CA8EhB"}

package/dist/lib/log.d.mts

@@ -0,0 +1,32 @@
+/** One structured log entry written to the anonymizer log file. */
+export type LogEntry = {
+    /** ISO-8601 timestamp of when the entry was written. */
+    ts: string;
+    /** The CLI name that produced the entry. */
+    cli: string;
+    /** Severity level. */
+    level: 'info' | 'error';
+    /** Human-readable message. */
+    message: string;
+    /** Optional extra structured data to attach to the entry. */
+    extra?: Record<string, unknown>;
+};
+/** The type returned by `createLogger`. */
+export type LoggerInstance = {
+    /** Log an informational message. */
+    info: (message: string, extra?: Record<string, unknown>, verbose?: boolean) => void;
+    /** Log an error message. */
+    error: (message: string, extra?: Record<string, unknown>, verbose?: boolean) => void;
+    /** Read the full contents of the log file. */
+    readLog: () => string;
+};
+/**
+ * Create a structured logger that appends JSON lines to the anonymizer log file,
+ * rotating when the file exceeds 1 MiB.
+ *
+ * @param cli - The CLI name to embed in every log entry.
+ * @param logPath - Path to the log file; defaults to the configured anonymizer log path.
+ * @returns An object with `info`, `error`, and `readLog` methods.
+ */
+export declare function createLogger(cli: string, logPath?: string): LoggerInstance;
+//# sourceMappingURL=log.d.mts.map

package/dist/lib/log.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.mts","sourceRoot":"","sources":["../../src/lib/log.ts"],"names":[],"mappings":"AAaA,mEAAmE;AACnE,MAAM,MAAM,QAAQ,GAAG;IACrB,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,IAAI,EAAE,CACJ,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,KACd,IAAI,CAAC;IACV,4BAA4B;IAC5B,KAAK,EAAE,CACL,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,KACd,IAAI,CAAC;IACV,8CAA8C;IAC9C,OAAO,EAAE,MAAM,MAAM,CAAC;CACvB,CAAC;AA0CF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,OAAO,SAAyB,GAC/B,cAAc,CA8EhB"}