@jevitate/cli 0.1.0 → 0.2.0

package/dist/log-correlation.js

@@ -0,0 +1,325 @@
+import { redactText } from "@jevitate/ai-core";
+import { worstOutcome } from "@jevitate/domain";
+import { normalizeRoute } from "@jevitate/explore";
+import { closeLogSources, openLogSources, } from "./log-sources.js";
+import { DotnetEntryGrouper, matchesLogDefect, matchesLogIgnore, normalizeLogMessage, parseLogDefectSpec, parseLogIgnoreSpec, parseLogLine, serverLogFingerprint, } from "./log-lines.js";
+const UNATTRIBUTED_ROUTE = "(run)";
+/** Only these levels are auto-attached as step evidence (a `--log-defect` match is ALWAYS attached,
+ *  whatever its level, since it is now a candidate defect). */
+const ATTACH_LEVELS = new Set(["warn", "error"]);
+export const DEFAULT_SERVER_LOG_DRAIN_MS = 3_000;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        t.unref?.();
+    });
+}
+/**
+ * Opens every source and starts correlating (#142). Returns `undefined` when `sources` is empty —
+ * a complete no-op, so a run without `--log-source` pays nothing.
+ */
+export function openServerLogRuntime(opts) {
+    if (opts.sources.length === 0)
+        return undefined;
+    return new ServerLogRuntime(opts);
+}
+export class ServerLogRuntime {
+    #handles;
+    #groupers = [];
+    #lines = [];
+    #stepEpoch = new Map();
+    #missionStartEpochMs = Date.now();
+    #secrets;
+    #matchers;
+    #drainMs;
+    #quietOk;
+    #logIgnore;
+    #ignoredLines = 0;
+    #inner;
+    #maxTotalLines = 20_000;
+    #finished = false;
+    #exitHook = () => {
+        for (const h of this.#handles)
+            h.killSync();
+    };
+    constructor(opts) {
+        this.#secrets = opts.secrets;
+        this.#matchers = opts.logDefect;
+        this.#drainMs = opts.drainMs ?? DEFAULT_SERVER_LOG_DRAIN_MS;
+        this.#quietOk = new Set(opts.quietOk ?? []);
+        this.#logIgnore = opts.logIgnore ?? [];
+        this.#inner = opts.onTranscriptEntry;
+        // One `openLogSources` call per spec: each source's `onLine` must stamp ITS OWN spec onto every
+        // `LogLine` (a shared callback across sources could not tell them apart). Each source also gets
+        // its OWN `DotnetEntryGrouper` (#165) — a multi-line .NET entry must never straddle two sources.
+        this.#handles = opts.sources.map((spec, i) => {
+            this.#groupers[i] = new DotnetEntryGrouper();
+            return openLogSources([spec], {
+                onLine: (raw, arrivalEpochMs) => {
+                    const grouper = this.#groupers[i];
+                    for (const entry of grouper.feed(raw, arrivalEpochMs))
+                        this.#pushLine(entry.raw, entry.epochMs, spec.raw);
+                },
+            })[0];
+        });
+        process.on("exit", this.#exitHook);
+    }
+    #pushLine(raw, epochMs, sourceRaw) {
+        if (this.#lines.length >= this.#maxTotalLines)
+            return;
+        const parsed = parseLogLine(raw, epochMs, sourceRaw);
+        // #169 item 3: a known-noise line is dropped here, BEFORE it can become step evidence, a
+        // `topMessages`/`byLevel` entry or a defect candidate — but it was still delivered by the
+        // source (already counted in `linesRead`), so it says nothing about the oracle's health.
+        if (this.#logIgnore.some((m) => matchesLogIgnore(parsed, m))) {
+            this.#ignoredLines += 1;
+            return;
+        }
+        this.#lines.push(parsed);
+    }
+    /** Flushes any still-pending `DotnetEntryGrouper` entry per source — the last entry in a .NET log
+     *  has no following header to trigger its own flush otherwise. */
+    #flushGroupers() {
+        this.#groupers.forEach((grouper, i) => {
+            const entry = grouper.flush();
+            const spec = this.#handles[i]?.spec.raw;
+            if (entry !== undefined && spec !== undefined)
+                this.#pushLine(entry.raw, entry.epochMs, spec);
+        });
+    }
+    /** Wraps the journal's own `TranscriptListener`: unchanged persistence, plus this step's epoch. */
+    onTranscriptEntry = (entry, all) => {
+        this.#stepEpoch.set(entry.step, Date.now());
+        this.#inner?.(entry, all);
+    };
+    /** Call once the mission function has returned. Waits out the drain window, closes every source,
+     *  and returns the correlated transcript/summary/defects. Idempotent (a second call is a no-op
+     *  empty result) — never blocks the mission itself, only this post-processing step. */
+    async finish(transcript) {
+        if (this.#finished)
+            return { transcript, summary: this.#summary([]), defects: [] };
+        this.#finished = true;
+        await sleep(this.#drainMs);
+        this.#flushGroupers();
+        await closeLogSources(this.#handles);
+        process.off("exit", this.#exitHook);
+        return this.#correlate(transcript);
+    }
+    /**
+     * Safety net for the mission-threw-before-`finish` path: closes every source immediately, with NO
+     * drain wait and no correlation. A no-op once `finish` already ran. Never throws.
+     */
+    async abort() {
+        if (this.#finished)
+            return;
+        this.#finished = true;
+        await closeLogSources(this.#handles);
+        process.off("exit", this.#exitHook);
+    }
+    #correlate(transcript) {
+        const windows = stepWindows(transcript, this.#stepEpoch, this.#missionStartEpochMs, this.#drainMs);
+        const perStep = new Map();
+        const perStepRaw = new Map();
+        const unattributed = [];
+        let attachedLines = 0;
+        for (const line of this.#lines) {
+            const win = windows.find((w) => line.epochMs >= w.startMs && line.epochMs <= w.endMs);
+            const isDefectCandidate = this.#matchers.some((m) => matchesLogDefect(line, m));
+            const attach = ATTACH_LEVELS.has(line.level) || isDefectCandidate;
+            if (win === undefined) {
+                if (attach)
+                    unattributed.push(line);
+                continue;
+            }
+            if (!attach)
+                continue;
+            attachedLines += 1;
+            const list = perStep.get(win.step) ?? [];
+            list.push({
+                level: line.level,
+                message: redactText(line.message, this.#secrets),
+                raw: redactText(line.raw, this.#secrets),
+                source: line.source,
+                epochMs: line.epochMs,
+                ...(line.target === undefined ? {} : { target: redactText(line.target, this.#secrets) }),
+            });
+            perStep.set(win.step, list);
+            const rawList = perStepRaw.get(win.step) ?? [];
+            rawList.push(line);
+            perStepRaw.set(win.step, rawList);
+        }
+        const augmented = transcript.map((entry) => {
+            const logs = perStep.get(entry.step);
+            return logs === undefined || logs.length === 0 ? entry : { ...entry, serverLogs: logs };
+        });
+        const defects = this.#matchers.length === 0 ? [] : this.#buildDefects(transcript, perStepRaw, unattributed);
+        const summary = this.#summary(unattributed, attachedLines);
+        return { transcript: augmented, summary, defects };
+    }
+    #buildDefects(transcript, perStepRaw, unattributed) {
+        const grouped = new Map();
+        const lastStep = transcript.length > 0 ? transcript[transcript.length - 1].step : 0;
+        const consider = (line, route, atStep) => {
+            const matched = this.#matchers.find((m) => matchesLogDefect(line, m));
+            if (matched === undefined)
+                return;
+            const normalizedMessage = normalizeLogMessage(line.message);
+            const fp = serverLogFingerprint(route, normalizedMessage, line.target);
+            const existing = grouped.get(fp);
+            if (existing !== undefined) {
+                existing.count += 1;
+                return;
+            }
+            // #169 item 3: the STORED route is templated too (the shared #95/#127 templater, same as the
+            // fingerprint already used internally) — two occurrences that only differ by an id in the URL
+            // read as the same defect everywhere, not just in the hash.
+            const templatedRoute = route === UNATTRIBUTED_ROUTE ? route : normalizeRoute(route);
+            grouped.set(fp, {
+                count: 1,
+                defect: {
+                    fingerprint: fp,
+                    related: [fp],
+                    kind: "server-log",
+                    title: `Server log ${line.level} on ${templatedRoute === UNATTRIBUTED_ROUTE ? "(unattributed)" : templatedRoute}${line.target === undefined ? "" : ` (${line.target})`}: ${normalizedMessage.slice(0, 80)}`,
+                    route: templatedRoute,
+                    level: line.level,
+                    message: redactText(line.message, this.#secrets),
+                    occurrences: 1,
+                    repro: { recordingStepIndex: recordingStepIndexFor(transcript, atStep) },
+                    serverLog: {
+                        sources: this.#handles.map((h) => h.spec.raw),
+                        matcher: matched.raw,
+                        normalizedMessage,
+                        drainMs: this.#drainMs,
+                    },
+                },
+            });
+        };
+        for (const entry of transcript) {
+            const route = entry.url;
+            for (const line of perStepRaw.get(entry.step) ?? [])
+                consider(line, route, entry.step);
+        }
+        for (const line of unattributed)
+            consider(line, UNATTRIBUTED_ROUTE, lastStep);
+        return [...grouped.values()].map(({ defect, count }) => ({ ...defect, occurrences: count }));
+    }
+    #summary(unattributed, attachedLines = 0) {
+        const byLevel = {};
+        for (const line of this.#lines)
+            byLevel[line.level] = (byLevel[line.level] ?? 0) + 1;
+        const counts = new Map();
+        for (const line of this.#lines) {
+            const message = normalizeLogMessage(line.message);
+            const key = `${line.level}|${line.target ?? ""}|${message}`;
+            const e = counts.get(key);
+            if (e === undefined)
+                counts.set(key, { level: line.level, message, ...(line.target === undefined ? {} : { target: line.target }), count: 1 });
+            else
+                e.count += 1;
+        }
+        const topMessages = [...counts.values()].sort((a, b) => b.count - a.count).slice(0, 10);
+        const sources = this.#handles.map((h) => ({
+            spec: h.spec.raw,
+            opened: h.opened,
+            linesRead: h.linesRead,
+            truncated: h.truncated,
+            ...(h.error === undefined ? {} : { error: h.error }),
+            ...(this.#quietOk.has(h.spec.raw) ? { quietOk: true } : {}),
+        }));
+        // Per-source health (#169): a source is unhealthy when it never opened/errored, OR it opened and
+        // delivered not one line while NOT declared `--log-quiet-ok` — a source the operator KNOWS runs
+        // quiet. Every declared source must be healthy for the oracle to count as "held": one dead/silent
+        // source among several is still a hole in the evidence, not proof of anything.
+        const unhealthy = sources.filter((s) => {
+            if (!s.opened || s.error !== undefined)
+                return true;
+            return s.linesRead === 0 && s.quietOk !== true;
+        });
+        const oracleOk = this.#matchers.length === 0 || unhealthy.length === 0;
+        const failedSpecs = unhealthy.filter((s) => !s.opened || s.error !== undefined).map((s) => s.spec);
+        const quietSpecs = unhealthy.filter((s) => s.opened && s.error === undefined).map((s) => s.spec);
+        let oracleReason;
+        if (oracleOk) {
+            oracleReason = undefined;
+        }
+        else if (quietSpecs.length === 0) {
+            oracleReason =
+                "the --log-defect oracle could not run: every declared --log-source failed to open or read a line — an absence of server-log defects proves nothing";
+        }
+        else if (failedSpecs.length === 0) {
+            oracleReason = "log source produced no lines";
+        }
+        else {
+            oracleReason = `the --log-defect oracle could not run: ${failedSpecs.join(", ")} failed to open or read a line; ${quietSpecs.join(", ")} produced no lines`;
+        }
+        return {
+            sources,
+            byLevel,
+            topMessages,
+            attachedLines,
+            unattributedLines: unattributed.length,
+            ignoredLines: this.#ignoredLines,
+            oracleOk,
+            ...(oracleReason === undefined ? {} : { oracleReason }),
+        };
+    }
+}
+/** Contiguous per-step correlation windows: `[previous settle, this settle]`, the LAST one extended
+ *  by `drainMs` so async backend work that lands after the mission's own bounds still attaches. */
+function stepWindows(transcript, stepEpoch, missionStartEpochMs, drainMs) {
+    const windows = [];
+    let prevEnd = missionStartEpochMs;
+    for (let i = 0; i < transcript.length; i++) {
+        const entry = transcript[i];
+        const settle = stepEpoch.get(entry.step) ?? prevEnd;
+        const isLast = i === transcript.length - 1;
+        const endMs = isLast ? settle + drainMs : settle;
+        windows.push({ step: entry.step, startMs: prevEnd, endMs });
+        prevEnd = settle;
+    }
+    return windows;
+}
+/**
+ * The flat `Recording` step index for a transcript step (#142's best-effort mapping): a failed
+ * action (`actOk: false`) never becomes a Recording step (`transcript.ts`'s own invariant), so this
+ * counts only the successful ones up to and including `uptoStep`. Clamped to 0 when none yet ran —
+ * `verify-fix` then replays from the start, which is always a safe (if wide) anchor.
+ */
+function recordingStepIndexFor(transcript, uptoStep) {
+    let idx = -1;
+    for (const e of transcript) {
+        if (e.step > uptoStep)
+            break;
+        if (e.actOk)
+            idx += 1;
+    }
+    return Math.max(0, idx);
+}
+/** Parses `--log-defect` values, failing closed on the first bad one. */
+export function parseLogDefectSpecs(raw) {
+    return raw.map(parseLogDefectSpec);
+}
+/** Parses `--log-ignore` values, failing closed on the first bad one (#169 item 3). */
+export function parseLogIgnoreSpecs(raw) {
+    return raw.map(parseLogIgnoreSpec);
+}
+/**
+ * Folds a server-log correlation result into an already-computed `MissionOutcome` (#142, follow-up
+ * on the exit-code requirement): a found `server-log` defect is at least `defects-found` — via
+ * `worstOutcome`, so it never DOWNGRADES a worse outcome (hang/crashed/inconclusive already proves
+ * more, or the same, than a defect). An unreadable `--log-defect` oracle (`oracleOk: false`) turns
+ * an otherwise-`clean` run `inconclusive` — its absence of defects proves nothing when the source
+ * that would have caught them was never demonstrably read. `undefined` (no `--log-source`) is a
+ * complete no-op.
+ */
+export function applyServerLogOutcome(outcome, run) {
+    if (run === undefined)
+        return outcome;
+    if (run.defects.length > 0)
+        return worstOutcome(outcome, "defects-found");
+    if (!run.summary.oracleOk && outcome === "clean")
+        return "inconclusive";
+    return outcome;
+}
+//# sourceMappingURL=log-correlation.js.map

package/dist/log-correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-correlation.js","sourceRoot":"","sources":["../src/log-correlation.ts"],"names":[],"mappings":"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"}

package/dist/log-lines.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Backend log line parsing, normalization and fingerprinting (#142). Pure and mechanical — never
+ * `eval`ed, never a model call. A parsed line is ONE of the run's evidence sources: it is
+ * correlated to the step it landed during (`log-correlation.ts`) and, with `--log-defect`,
+ * optionally promoted to a `server-log` defect.
+ */
+export type LogLevel = "error" | "warn" | "info" | "debug" | "unknown";
+/** True when `a` is at least as severe as `b`. `unknown` is never >= a NAMED level (fail closed). */
+export declare function levelAtLeast(a: LogLevel, b: LogLevel): boolean;
+/** A parsed backend log line. `raw`/`message` are UNREDACTED — callers redact before persisting. */
+export interface LogLine {
+    readonly level: LogLevel;
+    /** The human message: a JSON/logfmt log's `message`/`msg`/`error` field, else the whole line. */
+    readonly message: string;
+    /** The raw line exactly as read (for a multi-line entry — .NET console, #165 — every joined line). */
+    readonly raw: string;
+    /** The line's own timestamp (ms since epoch) when one parsed; else the arrival time. */
+    readonly epochMs: number;
+    /** True when `epochMs` came from the line itself, not from arrival order. */
+    readonly ownTimestamp: boolean;
+    /** The `--log-source` spec this line came from (its raw form, e.g. `file:/var/log/app.log`). */
+    readonly source: string;
+    /**
+     * The structured logger's own module/category (#169): a JSON log's `target`/`logger` field (Rust
+     * `tracing`'s `target`), so a `server-log` defect's fingerprint tells apart two distinct errors
+     * that happen to normalize to the same message class.
+     */
+    readonly target?: string;
+}
+/**
+ * Parses one raw log line — or, for the .NET console format (#165), one already-grouped multi-line
+ * entry (see `DotnetEntryGrouper`): JSON (`level`/`severity` + `time`/`timestamp`/`ts`), then logfmt
+ * (`level=error msg="…" time=…`), then the .NET default console formatter (`lvl: Category[id]` +
+ * indented continuation lines), then Serilog's bracketed console theme (`[HH:mm:ss ERR] …`), then a
+ * generic bracketed/bare level with an optional leading ISO timestamp, else falls back to the line
+ * verbatim with an `unknown` level and the arrival time. Never throws.
+ */
+export declare function parseLogLine(raw: string, arrivalEpochMs: number, source: string): LogLine;
+/** One raw (possibly multi-line, `\n`-joined) entry, ready for `parseLogLine`. */
+export interface RawLogEntry {
+    readonly raw: string;
+    readonly epochMs: number;
+}
+/**
+ * Groups the .NET default console formatter's multi-line entries (#165) — a `lvl: Category[id]`
+ * header followed by one or more indented message/exception-stack-trace lines — into ONE logical
+ * entry before it reaches `parseLogLine`. Stateful and meant for ONE `--log-source` (`log-
+ * correlation.ts` keeps one instance per source): lines arrive one at a time, in order, from `log-
+ * sources.ts`'s line splitter.
+ *
+ * A header line always starts a NEW pending entry (flushing whatever was pending first); an
+ * indented, non-blank line — while an entry is pending — extends it instead of starting its own;
+ * anything else (not indented, not itself a header) is its own one-line entry. Every other log
+ * format (JSON, logfmt, bracketed/bare) never triggers buffering: `feed` only holds a line back
+ * when it is itself a header or it is indented AND a header is already pending, so a single
+ * already-indented stray line with no pending entry passes straight through unchanged.
+ */
+export declare class DotnetEntryGrouper {
+    #private;
+    /** Feed one raw line. Returns the entries this line completed — usually 0 or 1, occasionally 2
+     *  (a pending entry flushed by, immediately followed by, this line's own one-line entry). */
+    feed(raw: string, epochMs: number): RawLogEntry[];
+    /** Flushes a still-pending entry (call when the source is closing: the log's last entry has no
+     *  following header/non-continuation line to trigger its own flush). `undefined` when idle. */
+    flush(): RawLogEntry | undefined;
+}
+/**
+ * The CLASS of a log message, for correlation-noise dedup and the `server-log` defect fingerprint:
+ * an ISO timestamp, then a uuid, are replaced by placeholders first (so a timestamp's own digits
+ * don't collide with the generic number-stripping below), then `@jevitate/explore`'s `messageClass`
+ * strips URLs, quoted values, long hex ids and remaining numbers. Two occurrences of one bug that
+ * differ only in an id, a count or a timestamp share a class.
+ */
+export declare function normalizeLogMessage(message: string): string;
+/**
+ * A `server-log` defect's fingerprint (#142): the templated route the line correlated to, plus the
+ * normalized message class, plus — when known (#169) — the logger's own `target`/`logger`/category
+ * (Rust `tracing`'s `target`, a JSON log's `logger`, a .NET entry's category). Two lines whose
+ * message happens to normalize the same, from two different loggers/modules, are DISTINCT defects:
+ * without `target` they would collapse into one fingerprint, hiding one of the two real bugs.
+ * Unattributed lines (outside every step window) are fingerprinted with `route = "(run)"` — still
+ * stable across repeated occurrences of the same line.
+ */
+export declare function serverLogFingerprint(route: string, normalizedMessage: string, target?: string): string;
+export declare class LogSpecError extends Error {
+    readonly code: "E_LOG_SPEC";
+    constructor(message: string);
+}
+/** A `--log-defect` matcher: a minimum level, or a `/regex/flags` pattern over the raw line. */
+export type LogDefectMatcher = {
+    readonly kind: "level";
+    readonly level: LogLevel;
+    readonly raw: string;
+} | {
+    readonly kind: "pattern";
+    readonly re: RegExp;
+    readonly raw: string;
+};
+/**
+ * Parses one `--log-defect` value: `/pattern/flags` (bounded length, compiled once via `new
+ * RegExp` — never `eval`ed) or a level name (`error`, `warn`, `info`, `debug`), matched as
+ * `level >= this`. Throws `LogSpecError` on anything else, so a bad spec is refused before any
+ * browser opens (the same fail-closed discipline as `--invariants`).
+ */
+export declare function parseLogDefectSpec(raw: string): LogDefectMatcher;
+/** Whether a parsed line matches a `--log-defect` matcher. */
+export declare function matchesLogDefect(line: Pick<LogLine, "level" | "raw">, matcher: LogDefectMatcher): boolean;
+/**
+ * A `--log-ignore` matcher (#169 item 3): known-noise lines (a periodic background job's own
+ * expected error, say) excluded from BOTH correlation (never attached as step evidence) and the
+ * `--log-defect` oracle (never a candidate defect, never counted in `topMessages`/`byLevel`) — but
+ * still counted toward the source's `linesRead` (the oracle demonstrably tailed something) and
+ * reported separately as `serverLogs.ignoredLines`, so an operator can see what was filtered.
+ */
+export type LogIgnoreMatcher = {
+    readonly kind: "pattern";
+    readonly re: RegExp;
+    readonly raw: string;
+} | {
+    readonly kind: "substring";
+    readonly value: string;
+    readonly raw: string;
+};
+/**
+ * Parses one `--log-ignore` value: `/pattern/flags` (bounded length, compiled once via `new RegExp`
+ * — never `eval`ed) or a plain substring, matched against the line's RAW text. Throws `LogSpecError`
+ * on anything empty/invalid/too long, failing closed before any browser opens.
+ */
+export declare function parseLogIgnoreSpec(raw: string): LogIgnoreMatcher;
+/** Whether a parsed line matches a `--log-ignore` matcher (substring/regex over the RAW line). */
+export declare function matchesLogIgnore(line: Pick<LogLine, "raw">, matcher: LogIgnoreMatcher): boolean;