@bookedsolid/rea 0.45.0 → 0.47.0

package/dist/cli/audit-timeline.d.ts

@@ -0,0 +1,180 @@
+/**
+ * `rea audit timeline [--bucket=HOUR|DAY|<DUR>] [--since=DUR] [--json]`
+ * — 0.46.0 charter item 2.
+ *
+ * Time-bucketed event counts over the audit log. Useful for spotting
+ * activity spikes ("what happened during the 3pm CI build?") and
+ * day/week cadence patterns.
+ *
+ * # Bucket sizes
+ *
+ *   - `HOUR` (default) — bucket boundaries align to the UTC hour
+ *     (`HH:00:00.000Z`)
+ *   - `DAY` — bucket boundaries align to the UTC day
+ *     (`YYYY-MM-DDT00:00:00.000Z`)
+ *   - `<DUR>` (`15m`, `30m`, `1h`, `2h`, `1d`, etc) — arbitrary
+ *     duration. Boundaries align to the UTC epoch (multiples of the
+ *     bucket size from `1970-01-01T00:00:00Z`). The `<DUR>` form is
+ *     useful for sub-hour cadence (`--bucket=15m`) or unusual cuts
+ *     (`--bucket=6h` for "morning / afternoon / evening / night").
+ *
+ * Bucket boundaries are half-open `[start, end)` so a record at
+ * `15:00:00.000Z` lands in the `15:00 → 16:00` bucket, not the
+ * `14:00 → 15:00` one.
+ *
+ * # Window
+ *
+ *   - `--since=DUR` with same shape as `audit summary` / `audit
+ *     by-tool` (`24h`, `7d`, etc). When set, the timeline emits a
+ *     bucket for every interval intersecting `[now - DUR, now]`, even
+ *     zero-count ones — silence is signal too. Without `--since`,
+ *     buckets are emitted only for intervals that actually contain a
+ *     record (no implicit filler — we don't know the operator's
+ *     intended window).
+ *
+ * # Output (default `--bucket=HOUR`, last 24h)
+ *
+ *     rea audit timeline (last 24h, hourly)
+ *     ──────────────────────────────────────
+ *     2026-05-16 14:00  ▁▁▁▁▁                    23 events
+ *     2026-05-16 15:00  ▁▁▁▁▁▁▁▁                 47 events
+ *     2026-05-16 16:00  ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁       127 events  ← peak
+ *     2026-05-16 17:00  ▁▁▁▁▁▁▁▁▁▁▁▁             89 events
+ *     …
+ *
+ * The histogram bar uses a single Unicode block char (▁) repeated
+ * proportionally to peak — chosen for terminal friendliness over the
+ * staircase forms (▁▂▃▄▅▆▇█) because the staircase forms render
+ * unevenly in many terminals and the proportional bar carries the
+ * same information at-a-glance. Bar width is capped at 32 chars so
+ * the line still fits in a typical 100-col terminal alongside the
+ * timestamp and count.
+ *
+ * Peak marker (`← peak`) sits next to the bucket with the highest
+ * count. Ties go to the first occurrence.
+ *
+ * # JSON output
+ *
+ *     {
+ *       "schema_version": 1,
+ *       "bucket": { "raw": "HOUR", "seconds": 3600 },
+ *       "window": {
+ *         "seconds": 86400,
+ *         "start":   "2026-05-16T14:00:00.000Z",
+ *         "end":     "2026-05-17T14:00:00.000Z"
+ *       },
+ *       "buckets": [
+ *         { "start": "2026-05-16T14:00:00.000Z",
+ *           "end":   "2026-05-16T15:00:00.000Z",
+ *           "count": 23 },
+ *         …
+ *       ],
+ *       "total_events": 287,
+ *       "peak_index": 2,
+ *       "files_scanned": ["/abs/path/.rea/audit.jsonl"]
+ *     }
+ */
+import type { Command } from 'commander';
+export declare const AUDIT_TIMELINE_SCHEMA_VERSION = 1;
+/**
+ * Hard ceiling on the number of buckets the command will produce. A
+ * `--since=7d` with `--bucket=1m` would emit 10,080 buckets — well
+ * past what a terminal renderer handles gracefully. Capping at 2000
+ * still allows `--bucket=15m --since=21d` (`~2016 buckets`) which
+ * covers the realistic ops use cases.
+ */
+export declare const MAX_BUCKETS = 2000;
+export declare class AuditTimelineOptionError extends Error {
+    constructor(message: string);
+}
+export interface AuditTimelineBucket {
+    /** Inclusive start (ISO-8601 UTC). */
+    start: string;
+    /** Exclusive end (ISO-8601 UTC). `end - start === bucket.seconds`. */
+    end: string;
+    count: number;
+}
+export interface AuditTimelineResult {
+    schema_version: typeof AUDIT_TIMELINE_SCHEMA_VERSION;
+    bucket: {
+        /** The raw `--bucket` value (e.g. `HOUR`, `15m`). */
+        raw: string;
+        /** Resolved bucket size in seconds. */
+        seconds: number;
+    };
+    window: {
+        seconds: number | null;
+        start: string | null;
+        end: string | null;
+    };
+    buckets: AuditTimelineBucket[];
+    total_events: number;
+    /** Index of the bucket with the highest count. `-1` when no events. */
+    peak_index: number;
+    files_scanned: string[];
+    /**
+     * 0.47.0 charter item 2: when `--since` was NOT specified and the
+     * audit log spans more than `MAX_BUCKETS` buckets at the requested
+     * cadence, the timeline auto-clamps the window to the widest duration
+     * that fits. This field carries the duration string that was actually
+     * applied (e.g. `"7d"`) — `null` when no clamping fired (the common
+     * case). Dashboard consumers use this to flag "the window you saw is
+     * not the whole log" in their UI.
+     */
+    clamped_since: string | null;
+}
+export interface ComputeAuditTimelineOptions {
+    /** Override CWD. Tests set this; production uses `process.cwd()`. */
+    baseDir?: string;
+    /** `--since` (e.g. `24h`, `7d`). Parsed via parseDuration. */
+    since?: string;
+    /** `--bucket` value (`HOUR`, `DAY`, or duration). Default `HOUR`. */
+    bucket?: string;
+    /** Test seam — pin "now". */
+    now?: Date;
+}
+/**
+ * Resolve `--bucket` to a number of seconds. Accepts:
+ *   - `HOUR` / `H` / `1H` (case-insensitive) → 3600
+ *   - `DAY`  / `D` / `1D` (case-insensitive) → 86400
+ *   - duration form (`15m`, `30s`, `2h`, `1d`, `1w`) → parsed via
+ *     `parseDurationSeconds` for shape compatibility with `--since`
+ *
+ * Bucket size must be >= 1 second; on the upper end we accept any
+ * value but `MAX_BUCKETS` will bound the rendered output.
+ */
+export declare function resolveBucketSeconds(raw: string): number;
+/**
+ * Format a duration in seconds as the coarsest single-unit compact
+ * string that round-trips through `parseDurationSeconds`. Mirrors the
+ * shape `--since` accepts (`s`/`m`/`h`/`d`/`w`).
+ *
+ * 0.47.0 charter item 1: powers the helpful-error suggestion + the
+ * auto-clamp `clamped_since` field. The largest-unit pass keeps the
+ * suggestion readable — `"21d"` not `"1814400s"`.
+ */
+export declare function formatDurationCompact(seconds: number): string;
+/**
+ * Compute the bucketed timeline. Pure (read-only). Throws
+ * `AuditTimelineOptionError` on bad `--since` / `--bucket`; throws on
+ * unreadable rotated segments (mirror of audit-summary's stance).
+ */
+export declare function computeAuditTimeline(options?: ComputeAuditTimelineOptions): Promise<AuditTimelineResult>;
+/**
+ * Render the result as a human-readable terminal block with inline
+ * histogram bars. See module docstring for the rendering choices.
+ */
+export declare function renderAuditTimeline(result: AuditTimelineResult): string;
+export interface RunAuditTimelineOptions {
+    since?: string;
+    bucket?: string;
+    json?: boolean;
+    /** Test seam — pin "now". */
+    now?: Date;
+}
+/** Commander entrypoint. */
+export declare function runAuditTimeline(options: RunAuditTimelineOptions): Promise<void>;
+/**
+ * Register `rea audit timeline` under the `audit` command group.
+ */
+export declare function registerAuditTimelineCommand(auditCommand: Command): void;