renovate-log-parser 0.1.0

package/dist/core/filters.js

@@ -0,0 +1,95 @@
+/**
+ * Shared filter model for renovate-log-parser.
+ *
+ * All three commands (detect-errors, analyze, web) describe the same kinds of
+ * filters. They are represented here as a small, closed set of primitives that
+ * the {@link QueryBuilder} translates into parameterized SQL. Filters are always
+ * AND'd together.
+ *
+ * Design decisions:
+ *  - Only root-level JSON keys are addressable in v1 (`$.<key>`), though the
+ *    helpers below already build JSON paths so nested support is a non-breaking
+ *    extension later.
+ *  - `equals` matches scalar (string/number/boolean) values only. Against a
+ *    non-scalar value it simply does not match.
+ *  - `like` is a simple, case-insensitive wildcard match on a single field
+ *    where `*` (and only `*`) is a wildcard. It is translated to a SQLite
+ *    `LIKE ... ESCAPE` comparison (see {@link globStarToLike}).
+ */
+/**
+ * Build a SQLite JSON path for a root-level key.
+ *
+ * Uses `$."key"` quoting so keys containing dots, spaces or reserved characters
+ * (common in Renovate logs, e.g. datasource URLs used as keys) are handled
+ * safely. Embedded double quotes are escaped per the JSON path grammar.
+ */
+export function jsonPath(field) {
+    const escaped = field.replace(/"/g, '""');
+    return `$."${escaped}"`;
+}
+/** SQL expression that extracts a root-level key from the `logentry` column. */
+export function extractExpr(field, column = "logentry") {
+    return `json_extract(${column}, '${jsonPath(field)}')`;
+}
+/** Parse a `key:val` CLI filter token into an {@link EqualsFilter}. */
+export function parseKeyValueFilter(token) {
+    const { field, value } = splitKeyValue(token);
+    return { type: "equals", field, value: coerceScalar(value) };
+}
+/**
+ * Parse a `key:pattern` CLI token into a {@link LikeFilter}, where `*` in the
+ * pattern is a wildcard (matching is case-insensitive; see {@link globStarToLike}).
+ */
+export function parseWildcardFilter(token) {
+    const { field, value } = splitKeyValue(token);
+    return { type: "like", field, pattern: value };
+}
+/** Split a `key:value` token on its FIRST colon, validating a non-empty key. */
+function splitKeyValue(token) {
+    const idx = token.indexOf(":");
+    if (idx === -1) {
+        throw new Error(`Invalid filter "${token}". Expected the form key:value (e.g. repository:foo/bar).`);
+    }
+    const field = token.slice(0, idx);
+    const value = token.slice(idx + 1);
+    if (field.length === 0) {
+        throw new Error(`Invalid filter "${token}". The key must not be empty.`);
+    }
+    return { field, value };
+}
+/**
+ * Translate a simple `*`-only user glob into a SQLite `LIKE` pattern.
+ *
+ * `LIKE`'s own metacharacters (`%`, `_`) and the escape character (`\`) are
+ * escaped so they match literally; then `*` is mapped to `%` (any run of
+ * characters). The resulting pattern must be used with `ESCAPE '\'`. Matching
+ * is anchored exactly as written — a leading/trailing `*` is required for
+ * prefix/suffix/contains behaviour.
+ */
+export function globStarToLike(pattern) {
+    return pattern.replace(/[\\%_]/g, "\\$&").replace(/\*/g, "%");
+}
+/** Strict numeric literal: an integer or simple decimal, no leading zeros. */
+const NUMERIC_LITERAL = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+/**
+ * Coerce a raw CLI string value to its scalar type so `equals` filters compare
+ * against the correctly-typed JSON value.
+ *
+ * Renovate stores many root fields as numbers (`level`, `pid`, `v`) or booleans,
+ * and SQLite never treats a numeric value as equal to a text value — so without
+ * this, `--filter level:30` would compare `30 = '30'` and never match.
+ *
+ * Coercion is deliberately conservative: only `true`/`false` and strict numeric
+ * literals are converted. Leading-zero (`007`) and dotted/version-like (`1.2.3`)
+ * values stay strings, since those are meaningful string identifiers.
+ */
+export function coerceScalar(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (NUMERIC_LITERAL.test(value))
+        return Number(value);
+    return value;
+}
+//# sourceMappingURL=filters.js.map

package/dist/core/filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.js","sourceRoot":"","sources":["../../src/core/filters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA+FH;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAgB;IACvC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,OAAO,MAAM,OAAO,GAAG,CAAC;AAC1B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,KAAgB,EAAE,MAAM,GAAG,UAAU;IAC/D,OAAO,gBAAgB,MAAM,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;AACzD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AACjD,CAAC;AAED,gFAAgF;AAChF,SAAS,aAAa,CAAC,KAAa;IAClC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,mBAAmB,KAAK,2DAA2D,CACpF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACnC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,+BAA+B,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAChE,CAAC;AAED,8EAA8E;AAC9E,MAAM,eAAe,GAAG,8BAA8B,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACtD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/ignore-file.d.ts

@@ -0,0 +1,52 @@
+/** Default ignore-file location, resolved relative to the current directory. */
+export declare const DEFAULT_IGNORE_FILE = "renovate-log-parser.ignore.json";
+/** A single ignore rule as authored in the JSON file. */
+export interface IgnoreRule {
+    /** Required finding category to silence (e.g. `err-object`). */
+    category: string;
+    /** Optional glob matched against `finding.message` (`*`/`?` wildcards). */
+    message?: string;
+    /** Optional exact `repository` match. */
+    repository?: string;
+    /** Optional human-facing justification (unused by matching). */
+    reason?: string;
+    /** Optional ISO date; once past, the rule is inactive. */
+    expires?: string;
+}
+/** On-disk ignore-file shape. */
+export interface IgnoreFile {
+    version: number;
+    rules: IgnoreRule[];
+}
+/** The subset of a finding needed to evaluate ignore rules. */
+export interface IgnorableFinding {
+    category: string;
+    message: string;
+    repository?: string;
+}
+/** Options controlling how the ignore file is loaded. */
+export interface LoadIgnoreOptions {
+    /** Sink for non-fatal warnings (defaults to `console.error`). */
+    warn?: (message: string) => void;
+    /** Whether the path was explicitly supplied via `--ignore-file`. */
+    explicit?: boolean;
+}
+/**
+ * Load and validate the active ignore rules from a file.
+ *
+ * A missing file yields an empty rule set (missing file = no rules). Expired
+ * rules are dropped with a warning. A malformed file throws (surfaced by the
+ * caller as a tool/usage error).
+ */
+export declare function loadIgnoreRules(path: string, options?: LoadIgnoreOptions): IgnoreRule[];
+/**
+ * Return the first active rule that ignores the given finding, or `undefined`.
+ * All present rule fields must match; absent fields are wildcards.
+ */
+export declare function matchIgnoreRule(finding: IgnorableFinding, rules: readonly IgnoreRule[]): IgnoreRule | undefined;
+/**
+ * Compile a glob (`*` = any run, `?` = one char) into an anchored, case-
+ * sensitive RegExp — matching the case-sensitive `GLOB` semantics used
+ * elsewhere in the tool. All other characters are matched literally.
+ */
+export declare function globToRegExp(glob: string): RegExp;

package/dist/core/ignore-file.js

@@ -0,0 +1,104 @@
+/**
+ * Ignore-file support for `detect-errors`.
+ *
+ * Line numbers in a Renovate log shift as the log grows, so ignore rules key on
+ * stable attributes instead: a required `category`, plus optional `message`
+ * glob, optional exact `repository`, an optional human `reason`, and an optional
+ * `expires` ISO date. A finding is ignored iff an **active** rule matches on
+ * category AND (message glob, if present) AND (repository, if present).
+ *
+ * Expired rules (past `expires`) are inactive and reported to stderr on load, so
+ * a temporary silence surfaces again once its window closes.
+ */
+import { existsSync, readFileSync } from "node:fs";
+/** Default ignore-file location, resolved relative to the current directory. */
+export const DEFAULT_IGNORE_FILE = "renovate-log-parser.ignore.json";
+/**
+ * Load and validate the active ignore rules from a file.
+ *
+ * A missing file yields an empty rule set (missing file = no rules). Expired
+ * rules are dropped with a warning. A malformed file throws (surfaced by the
+ * caller as a tool/usage error).
+ */
+export function loadIgnoreRules(path, options = {}) {
+    const warn = options.warn ?? ((m) => console.error(m));
+    if (!existsSync(path)) {
+        if (options.explicit) {
+            warn(`Ignore file not found (continuing with no rules): ${path}`);
+        }
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ignore file ${path}: ${err.message}`, { cause: err });
+    }
+    const file = parsed;
+    if (!file || typeof file !== "object" || !Array.isArray(file.rules)) {
+        throw new Error(`Invalid ignore file ${path}: expected an object with a "rules" array.`);
+    }
+    const now = Date.now();
+    const active = [];
+    for (const [index, raw] of file.rules.entries()) {
+        const rule = raw;
+        if (!rule || typeof rule.category !== "string" || rule.category === "") {
+            throw new Error(`Invalid ignore file ${path}: rule #${index} is missing a "category".`);
+        }
+        if (rule.expires !== undefined && isExpired(rule.expires, now)) {
+            warn(`Ignore rule for "${rule.category}" expired on ${rule.expires}; it is no longer active.`);
+            continue;
+        }
+        active.push({
+            category: rule.category,
+            message: rule.message,
+            repository: rule.repository,
+            reason: rule.reason,
+            expires: rule.expires,
+        });
+    }
+    return active;
+}
+/** True when `expires` is a valid date that lies in the past. */
+function isExpired(expires, now) {
+    const ts = Date.parse(expires);
+    return !Number.isNaN(ts) && ts < now;
+}
+/**
+ * Return the first active rule that ignores the given finding, or `undefined`.
+ * All present rule fields must match; absent fields are wildcards.
+ */
+export function matchIgnoreRule(finding, rules) {
+    return rules.find((rule) => {
+        if (rule.category !== finding.category)
+            return false;
+        if (rule.repository !== undefined &&
+            rule.repository !== finding.repository) {
+            return false;
+        }
+        if (rule.message !== undefined &&
+            !globToRegExp(rule.message).test(finding.message)) {
+            return false;
+        }
+        return true;
+    });
+}
+/**
+ * Compile a glob (`*` = any run, `?` = one char) into an anchored, case-
+ * sensitive RegExp — matching the case-sensitive `GLOB` semantics used
+ * elsewhere in the tool. All other characters are matched literally.
+ */
+export function globToRegExp(glob) {
+    let out = "";
+    for (const ch of glob) {
+        if (ch === "*")
+            out += ".*";
+        else if (ch === "?")
+            out += ".";
+        else
+            out += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}
+//# sourceMappingURL=ignore-file.js.map

package/dist/core/ignore-file.js.map

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

package/dist/core/levels.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Renovate log level metadata: numeric level -> single-letter glyph + semantic
+ * color. Shared by the web UI (row glyphs) and any CLI text rendering.
+ *
+ * Colors are expressed as semantic tokens (not raw hex) so the web layer can
+ * map them onto Nuxt UI / Tailwind classes: info = green, warn = amber,
+ * error = red, fatal = red (filled),
+ * trace/debug = muted; unknown levels render their raw number.
+ */
+/** Semantic color token for a log level. */
+export type LevelColor = "muted" | "neutral" | "green" | "amber" | "red" | "red-filled";
+/** Presentation metadata for a single Renovate log level. */
+export interface LevelMeta {
+    /** Numeric level as emitted by Renovate (bunyan levels). */
+    level: number;
+    /** Human name (trace/debug/info/warn/error/fatal). */
+    name: string;
+    /** Single uppercase glyph shown in the UI. */
+    symbol: string;
+    /** Semantic color token. */
+    color: LevelColor;
+}
+/** All known Renovate log levels, keyed by numeric level. */
+export declare const LEVELS: Readonly<Record<number, LevelMeta>>;
+/** Levels considered build-breaking errors by `detect-errors`. */
+export declare const ERROR_LEVELS: readonly number[];
+/** The warn level surfaced as a (non-breaking) warning by `detect-errors`. */
+export declare const WARN_LEVEL = 40;
+/**
+ * Resolve presentation metadata for a level. Unknown/unexpected levels fall
+ * back to their raw number rendered in a muted color.
+ */
+export declare function levelMeta(level: number): LevelMeta;

package/dist/core/levels.js

@@ -0,0 +1,35 @@
+/**
+ * Renovate log level metadata: numeric level -> single-letter glyph + semantic
+ * color. Shared by the web UI (row glyphs) and any CLI text rendering.
+ *
+ * Colors are expressed as semantic tokens (not raw hex) so the web layer can
+ * map them onto Nuxt UI / Tailwind classes: info = green, warn = amber,
+ * error = red, fatal = red (filled),
+ * trace/debug = muted; unknown levels render their raw number.
+ */
+/** All known Renovate log levels, keyed by numeric level. */
+export const LEVELS = {
+    10: { level: 10, name: "trace", symbol: "T", color: "muted" },
+    20: { level: 20, name: "debug", symbol: "D", color: "neutral" },
+    30: { level: 30, name: "info", symbol: "I", color: "green" },
+    40: { level: 40, name: "warn", symbol: "W", color: "amber" },
+    50: { level: 50, name: "error", symbol: "E", color: "red" },
+    60: { level: 60, name: "fatal", symbol: "F", color: "red-filled" },
+};
+/** Levels considered build-breaking errors by `detect-errors`. */
+export const ERROR_LEVELS = [50, 60];
+/** The warn level surfaced as a (non-breaking) warning by `detect-errors`. */
+export const WARN_LEVEL = 40;
+/**
+ * Resolve presentation metadata for a level. Unknown/unexpected levels fall
+ * back to their raw number rendered in a muted color.
+ */
+export function levelMeta(level) {
+    return (LEVELS[level] ?? {
+        level,
+        name: String(level),
+        symbol: String(level),
+        color: "muted",
+    });
+}
+//# sourceMappingURL=levels.js.map

package/dist/core/levels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.js","sourceRoot":"","sources":["../../src/core/levels.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,MAAM,GAAwC;IACzD,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE;IAC7D,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE;IAC/D,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE;IAC5D,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE;IAC5D,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE;IAC3D,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE;CACnE,CAAC;AAEF,kEAAkE;AAClE,MAAM,CAAC,MAAM,YAAY,GAAsB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAExD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,CACL,MAAM,CAAC,KAAK,CAAC,IAAI;QACf,KAAK;QACL,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC;QACrB,KAAK,EAAE,OAAO;KACf,CACF,CAAC;AACJ,CAAC"}

package/dist/core/parser.d.ts

@@ -0,0 +1,57 @@
+import type { SqlParam } from "./query-builder.js";
+/** Result of a successful {@link Parser.load}. */
+export interface LoadResult {
+    /** Absolute path of the source log that was loaded. */
+    path: string;
+    /** md5 of the source file content (also the cache key). */
+    md5: string;
+    /** Absolute path of the backing SQLite cache file. */
+    dbPath: string;
+    /** Total number of log lines (rows) in the database. */
+    totalLines: number;
+    /** Whether an existing valid cache was reused (vs. freshly parsed). */
+    cached: boolean;
+}
+/** A synthetic entry stored for a line that was not valid JSON. */
+export interface ParseErrorEntry {
+    _parseError: true;
+    _raw: string;
+}
+/** A synthetic entry stored for a blank line. */
+export interface BlankEntry {
+    _blank: true;
+}
+export declare class Parser {
+    private db?;
+    private info?;
+    /** Metadata about the currently-loaded log, or `undefined` if none. */
+    get loaded(): LoadResult | undefined;
+    /** The open database handle. Throws if no log has been loaded. */
+    private requireDb;
+    /**
+     * Load a log file, reusing a valid cache when possible.
+     *
+     * @param absolutePath Absolute path to the Renovate JSONL log.
+     */
+    load(absolutePath: string): LoadResult;
+    /** Create the schema, insert every line in a transaction, then index. */
+    private build;
+    private countRows;
+    /**
+     * Run a SELECT statement and return rows as plain objects.
+     *
+     * @param sql A SELECT statement.
+     * @param params Bound parameters for `?` placeholders.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: readonly SqlParam[]): T[];
+    /**
+     * Run a SELECT that includes a `logentry` column and return each row's parsed
+     * JSON entry alongside its line number.
+     */
+    queryEntries<T = Record<string, unknown>>(sql: string, params?: readonly SqlParam[]): {
+        line: number;
+        entry: T;
+    }[];
+    /** Close the underlying database handle (idempotent). */
+    close(): void;
+}

package/dist/core/parser.js

@@ -0,0 +1,201 @@
+/**
+ * Parser — loads a Renovate JSONL log into a cached SQLite database and answers
+ * SQL queries against it.
+ *
+ * Behaviour:
+ *  - The cache key is the md5 of the file *content*, stored at
+ *    `<os.tmpdir()>/renovate-log-parser-<md5>.db`. Identical logs at different
+ *    paths share a cache; a changed file re-parses.
+ *  - On every load, orphaned caches (zero rows — e.g. from a crashed parse) are
+ *    deleted. Valid caches for other logs are preserved (no TTL/size cap).
+ *  - The table has one JSON `logentry` column; `line` is an INTEGER PRIMARY KEY
+ *    aliasing rowid and equal to the original 0-indexed file line number.
+ *  - Parsing runs in a single transaction, so a crash leaves zero rows (which
+ *    the orphan check then rebuilds) rather than a half-populated cache.
+ *  - Malformed lines are stored as `{"_parseError":true,"_raw":"…"}`; blank
+ *    lines as `{"_blank":true}`, keeping rowid == line number.
+ *  - Expression indices back the hot filter fields (level/repository/branch and
+ *    err-presence) so QueryBuilder-generated WHERE clauses stay fast.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Prefix for cache database files in the temp directory. */
+const DB_PREFIX = "renovate-log-parser-";
+const DB_SUFFIX = ".db";
+export class Parser {
+    db;
+    info;
+    /** Metadata about the currently-loaded log, or `undefined` if none. */
+    get loaded() {
+        return this.info;
+    }
+    /** The open database handle. Throws if no log has been loaded. */
+    requireDb() {
+        if (!this.db) {
+            throw new Error("No log loaded. Call load() first.");
+        }
+        return this.db;
+    }
+    /**
+     * Load a log file, reusing a valid cache when possible.
+     *
+     * @param absolutePath Absolute path to the Renovate JSONL log.
+     */
+    load(absolutePath) {
+        if (!existsSync(absolutePath)) {
+            throw new Error(`Log file not found: ${absolutePath}`);
+        }
+        const content = readFileSync(absolutePath);
+        const md5 = createHash("md5").update(content).digest("hex");
+        const dbPath = join(tmpdir(), `${DB_PREFIX}${md5}${DB_SUFFIX}`);
+        // Close any previously-opened handle before switching logs.
+        this.close();
+        // Remove orphaned (zero-row / invalid) caches across the temp dir.
+        cleanupOrphans();
+        if (existsSync(dbPath) && isValidCache(dbPath)) {
+            this.db = new DatabaseSync(dbPath);
+            const totalLines = this.countRows();
+            this.info = { path: absolutePath, md5, dbPath, totalLines, cached: true };
+            return this.info;
+        }
+        // (Re)build the cache from scratch.
+        if (existsSync(dbPath))
+            rmSync(dbPath, { force: true });
+        this.db = new DatabaseSync(dbPath);
+        const totalLines = this.build(content.toString("utf8"));
+        this.info = { path: absolutePath, md5, dbPath, totalLines, cached: false };
+        return this.info;
+    }
+    /** Create the schema, insert every line in a transaction, then index. */
+    build(raw) {
+        const db = this.requireDb();
+        db.exec("CREATE TABLE logs (line INTEGER PRIMARY KEY, logentry TEXT NOT NULL)");
+        const lines = splitLines(raw);
+        const insert = db.prepare("INSERT INTO logs (line, logentry) VALUES (?, ?)");
+        db.exec("BEGIN");
+        try {
+            for (const [i, line] of lines.entries()) {
+                insert.run(i, normalizeLine(line));
+            }
+            db.exec("COMMIT");
+        }
+        catch (err) {
+            db.exec("ROLLBACK");
+            throw err;
+        }
+        // Expression indices matching QueryBuilder's json_extract expressions.
+        db.exec("CREATE INDEX idx_level ON logs (json_extract(logentry, '$.level'))");
+        db.exec(`CREATE INDEX idx_repository ON logs (json_extract(logentry, '$.repository'))`);
+        db.exec("CREATE INDEX idx_branch ON logs (json_extract(logentry, '$.branch'))");
+        db.exec("CREATE INDEX idx_err ON logs (json_extract(logentry, '$.err')) WHERE json_extract(logentry, '$.err') IS NOT NULL");
+        return lines.length;
+    }
+    countRows() {
+        const row = this.requireDb()
+            .prepare("SELECT COUNT(*) AS n FROM logs")
+            .get();
+        return row.n;
+    }
+    /**
+     * Run a SELECT statement and return rows as plain objects.
+     *
+     * @param sql A SELECT statement.
+     * @param params Bound parameters for `?` placeholders.
+     */
+    query(sql, params = []) {
+        const stmt = this.requireDb().prepare(sql);
+        const rows = stmt.all(...params);
+        // node:sqlite returns null-prototype objects; normalize to plain objects.
+        return rows.map((r) => ({ ...r }));
+    }
+    /**
+     * Run a SELECT that includes a `logentry` column and return each row's parsed
+     * JSON entry alongside its line number.
+     */
+    queryEntries(sql, params = []) {
+        return this.query(sql, params).map((r) => ({ line: r.line, entry: JSON.parse(r.logentry) }));
+    }
+    /** Close the underlying database handle (idempotent). */
+    close() {
+        if (this.db) {
+            this.db.close();
+            this.db = undefined;
+            this.info = undefined;
+        }
+    }
+}
+/**
+ * Split raw file content into lines matching `wc -l` semantics: a single
+ * trailing newline does not produce an extra empty line.
+ */
+function splitLines(raw) {
+    const lines = raw.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines;
+}
+/** Map one source line to the JSON text stored in the `logentry` column. */
+function normalizeLine(line) {
+    const trimmed = line.endsWith("\r") ? line.slice(0, -1) : line;
+    if (trimmed.trim().length === 0) {
+        return JSON.stringify({ _blank: true });
+    }
+    try {
+        JSON.parse(trimmed);
+        // Valid JSON: store as-is to preserve exact content.
+        return trimmed;
+    }
+    catch {
+        return JSON.stringify({
+            _parseError: true,
+            _raw: trimmed,
+        });
+    }
+}
+/** A cache is valid if it has a `logs` table containing at least one row. */
+function isValidCache(dbPath) {
+    let db;
+    try {
+        db = new DatabaseSync(dbPath, { readOnly: true });
+        const row = db.prepare("SELECT COUNT(*) AS n FROM logs").get();
+        return row.n > 0;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * Delete orphaned cache files (missing/empty `logs` table) from the temp dir.
+ * A currently-targeted cache that is invalid is removed here and rebuilt by the
+ * caller; valid caches (including for other logs) are preserved.
+ */
+function cleanupOrphans() {
+    let entries;
+    try {
+        entries = readdirSync(tmpdir());
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (!name.startsWith(DB_PREFIX) || !name.endsWith(DB_SUFFIX))
+            continue;
+        const full = join(tmpdir(), name);
+        if (!isValidCache(full)) {
+            try {
+                rmSync(full, { force: true });
+            }
+            catch {
+                // Best-effort cleanup; ignore files we cannot remove.
+            }
+        }
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/core/parser.js.map

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

package/dist/core/query-builder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * QueryBuilder — translates the shared {@link Filter} model into a single
+ * parameterized SQL SELECT against the parser's `logs` table.
+ *
+ * All filters are AND'd. WHERE
+ * fragments reuse the exact `json_extract(...)` expressions that the parser
+ * indexes, so the query planner can use those expression indices.
+ *
+ * The builder never interpolates user values into SQL text; every value is a
+ * bound parameter. Wildcard (`like`) filters compare a single field with a
+ * case-insensitive SQLite `LIKE ... ESCAPE`; the `*`-to-`%` translation
+ * and escaping happen in {@link globStarToLike}.
+ */
+import { type Filter } from "./filters.js";
+/** A parameter bound into a prepared statement. */
+export type SqlParam = string | number | bigint | null | Uint8Array;
+/** A fully-built, parameterized query ready for {@link Parser.query}. */
+export interface BuiltQuery {
+    sql: string;
+    params: SqlParam[];
+}
+/** Options that shape the SELECT independent of row-matching filters. */
+export interface QueryOptions {
+    /** Restrict to rows with rowid >= this (original 0-indexed line). */
+    lineFrom?: number;
+    /** Restrict to rows with rowid <= this (original 0-indexed line). */
+    lineTo?: number;
+    /** Maximum number of rows to return. */
+    limit?: number;
+    /** Number of matching rows to skip (for pagination). */
+    offset?: number;
+    /** Sort direction by rowid (line order). Defaults to ascending. */
+    order?: "asc" | "desc";
+}
+/**
+ * Build a parameterized SELECT for the given filters and options.
+ *
+ * @param filters Row-matching filters, AND'd together.
+ * @param options Line range, ordering, and pagination.
+ * @param columns SELECT list. Defaults to `rowid, logentry`.
+ */
+export declare function buildQuery(filters?: readonly Filter[], options?: QueryOptions, columns?: string): BuiltQuery;
+/**
+ * Build a `SELECT COUNT(*)` for the given filters (ignores pagination/order),
+ * used by the web `total` count.
+ */
+export declare function buildCountQuery(filters?: readonly Filter[], options?: Pick<QueryOptions, "lineFrom" | "lineTo">): BuiltQuery;