renovate-log-parser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marius Shekow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,402 @@
+# renovate-log-parser
+
+`renovate-log-parser` is a CLI and web interface for manual and automated analyses of Renovate Bot debug logs (JSONL-formatted), which you get by either downloading a run's log from [https://developer.mend.io](https://developer.mend.io) (if you use Mend's _hosted_ GitHub app), or by setting the `LOG_FILE` environment variable for self-hosted Renovate.
+
+`renovate-log-parser` offers the following commands:
+
+- `detect-errors` is meant for CI pipelines; it scans the log for build-breaking problems and warnings and exits with error, helping you detect and solve hidden Renovate issues you would otherwise miss
+- `analyze` (with a corresponding SKILL.md) tells your coding agent (Codex, Copilot, Claude Code, etc.) about the log's structure, allowing it to efficiently read only the most relevant log lines in a token-efficient way, so that it can quickly (and cheaply) diagnose Renovate problems
+- `web` starts a temporary local web server that parses the log and serves a browser-based interface that you use to analyze and filter Renovate logs of _any_ length; this solves the problem of tedious, manual “grep”-like analyses where your text editor chokes on too large files
+
+## Background (why do I need this)
+
+This tool was born out of the need to solve various problems, such as:
+
+- Setting up Renovate in a project with many repositories (and development teams) is easy. But over time, subtle problems creep in that no one seems to notice. For instance, Renovate might stop creating PRs for intricate reasons, and it only posts a small notice-block about this problem to the _Dependency dashboard_ GitHub issue. Unfortunately, the development teams use _Jira_ for issues and never look at GitHub issues, so the problems remain unnoticed.
+- In practice, developers sometimes have problems with Renovate Bot. They wonder why Renovate does not do certain things (even though they think it should), or they are annoyed that Renovate does certain things they don't want it to do. Manual analysis (given the huge debug-level log) is very difficult for non-experts, as important information is often buried in _debug_\-level log lines rather than warning- or error-level log lines. And AI agents miss important information in large log files, or spend enormous amounts of tokens for the analysis. As a consequence, people tend to accept a sub-optimal Renovate configuration or become frustrated with Renovate in general.
+
+Consequently, a tool was needed that detects such subtle problems automatically, and that simplifies manual and AI-assisted analyses of Renovate log files.
+
+## Usage
+
+Run directly with `npx` (no install required):
+
+```bash
+# Detect build-breaking problems in a Renovate JSONL log (CI-friendly)
+npx renovate-log-parser detect-errors path/to/renovate.jsonl
+
+# Also write a machine-readable JSON report
+npx renovate-log-parser detect-errors path/to/renovate.jsonl --out report.json
+
+# Emit token-efficient stats for an AI coding agent
+npx renovate-log-parser analyze path/to/renovate.jsonl
+
+# Explore a log interactively in the Nuxt-based web UI
+npx renovate-log-parser web path/to/renovate.jsonl
+```
+
+Or install globally:
+
+```bash
+npm install -g renovate-log-parser
+renovate-log-parser --help
+```
+
+## Commands
+
+### `detect-errors <path>`
+
+Deterministically scans a Renovate debug log (JSONL) for build-breaking
+problems and warnings — designed to gate CI. It prints a human-readable summary
+to stdout and, with `--out`, writes a stable machine-readable JSON report.
+
+```bash
+renovate-log-parser detect-errors renovate.jsonl [--out report.json] \
+  [--ignore-file rules.json] [--fail-on-warn]
+```
+
+| Arg / option     | Default                             | Description                                       |
+| ---------------- | ----------------------------------- | ------------------------------------------------- |
+| `<path>`         | **required**                        | Path to the Renovate JSONL log                    |
+| `--out`          | (none)                              | Also write the machine-readable JSON report here  |
+| `--ignore-file`  | `./renovate-log-parser.ignore.json` | Ignore-rules file (a missing file means no rules) |
+| `--fail-on-warn` | `false`                             | Make warning findings affect the exit code        |
+
+**Exit codes:**
+
+- `0` = no non-ignored errors
+- `1` = ≥1 non-ignored error (or, with `--fail-on-warn`, ≥1 non-ignored warning)
+- `2` = tool/usage error (bad path, unreadable, bad args, malformed ignore file)
+
+**Detected categories**:
+
+- **Errors** (things Renovate would _not_ otherwise flag in a PR comment):
+  - `host-error-abort`: when Renovate skipped creating/updating PRs for a repository because one or more well-known registries were unreachable; looks for a `Repository finished` entry with `result: "external-host-error"`
+  - `log-error`: lines with error level (level=50)
+  - `log-fatal`: lines with fatal level (level=60)
+  - `config-migration`: when a repository needs a renovate.json migration; looks for a `Config migration necessary` entry carrying `oldConfig` + `newConfig`
+  - `abandoned-package`: when a repository contains one or more abandoned packages for which Renovate would not create a PR; reports one finding per package in an `Abandoned package statistics` entry
+- **Warnings**:
+  - `log-warn`: lines with warning level (level=40)
+  - `err-object`: reports lines with an `err` object, such as rawExec errors
+  - `repo-problem`: reports entries in `repoProblems` lines (which is a string-array)
+
+The JSON report's `counts` map always lists every category (zeros included) for stable run-over-run diffing in CI.
+
+**Ignore file** — silence expected findings with stable keys (line numbers shift
+as logs grow). A finding is ignored iff an active rule matches on `category` AND
+(optional `message` glob) AND (optional exact `repository`). Rules past their
+optional `expires` date are reported to stderr and skipped:
+
+```jsonc
+{
+  "version": 1,
+  "rules": [
+    {
+      "category": "err-object",
+      "message": "*lock file error*", // optional glob (* and ?)
+      "repository": "owner/repo", // optional exact match
+      "reason": "flaky nuget restore, JIRA-123", // optional, for humans
+      "expires": "2026-09-01", // optional ISO date; past => inactive + warn
+    },
+  ],
+}
+```
+
+Ignored findings still appear in the report with `"ignored": true`, but are
+excluded from the summary counts and the exit code.
+
+### `analyze <path>`
+
+Emits token-efficient structure for an AI coding agent (or a human). Without
+`--print` it writes compact single-line JSON whole-log **stats** to stdout; with `--print` it
+streams a filtered, line-ranged, limited **JSONL** slice of the log (one entry
+per line). The intended loop is: read the stats, pick the interesting line
+range, then `--print` just that range — reading only what you need.
+
+```bash
+# Whole-log stats: level counts + per-repository structure
+renovate-log-parser analyze renovate.jsonl
+
+# Print lines 500–560, keeping only npm-manager entries, first 20
+renovate-log-parser analyze renovate.jsonl --print \
+  --line-from 500 --line-to 560 --filter manager:npm --limit 20
+
+# Print every entry whose msg starts with "Found match at" (case-insensitive)
+renovate-log-parser analyze renovate.jsonl --print \
+  --filter-with-wildcard "msg:Found match at*"
+```
+
+| Arg / option                | Default                               | Description                                                                        |
+| --------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------- |
+| `<path>`                    | **required**                          | Path to the Renovate JSONL log                                                     |
+| `--print`                   | `false`                               | Print matching log lines (JSONL) instead of stats                                  |
+| `--ignored-fields`          | `v,time,logContext,pid,hostname,name` | CSV of root keys to strip in print mode (`msg` kept)                               |
+| `--line-from` / `--line-to` | (none)                                | Inclusive 0-indexed line range (print mode)                                        |
+| `--limit`                   | `50`                                  | Max lines to print (print mode)                                                    |
+| `--filter`                  | (none)                                | `key:val` scalar-**equals** filter, repeatable, AND'd                              |
+| `--filter-with-wildcard`    | (none)                                | `key:pattern` wildcard filter (`*` = any run), case-insensitive, repeatable, AND'd |
+| `--include-original-line`   | `false`                               | Add `_oL` (0-indexed source line) to each object                                   |
+
+**Stats mode** reports `levelCounts` (entries per numeric level) and a `repos`
+array — each repository's line span, unique branches, the rowids of its
+`branches info extended` and `packageFiles with updates` entries, its
+`repoProblems`, and its dependency inventory (`depNames`/`packageNames`, unioning
+root-level keys with the `packageFiles with updates` config).
+
+**Print mode** selects rows in order line-range -> filters -> `--limit` (first N
+by line order). Output is JSONL on stdout with the ignored root fields stripped
+(`msg` is never stripped); when the limit caps the result, a truncation notice is
+written to **stderr** so stdout stays a clean, pipeable stream.
+
+Both filter flags target a single root-level key and can be repeated (all
+conditions are AND'd, alongside any line range). `--filter` matches the value
+**exactly**; its value is auto-typed so it compares against the correctly-typed
+JSON — `true`/`false` become booleans and plain numbers become numbers (so
+`level:30` matches the numeric `level`), while everything else (including
+leading-zero or dotted values like `007` / `1.2.3`) stays a string.
+`--filter-with-wildcard` treats `*` as "any run of characters" (nothing else is
+special — `?` and `%` are literal) and matches case-insensitively. A pattern is
+anchored as written, so use a leading/trailing `*` for prefix/suffix/contains
+matching (e.g. `msg:*lock file*`).
+
+**Exit codes:** `0` = success · `2` = tool/usage error (bad path, unreadable, bad
+filter token).
+
+### `install-analyze-skill`
+
+Writes (or updates) a `renovate-log-analyzer` **SKILL.md** that teaches an AI
+coding agent (Codex, Copilot, Claude Code, …) how to drive the `analyze` command
+token-efficiently. It can optionally embed instructions for fetching the
+log from GitHub self-hosted Renovate workflows via the `gh` CLI.
+
+The command is interactive by default: it asks whether to install the skill
+**locally** or **globally**, and whether to include the GitHub-fetch section
+(and if so, the base URL, organization, repository, and Renovate workflow
+filename). All answers can also be supplied as flags to run non-interactively
+(e.g. in CI); any flag you pass skips its prompt.
+
+```bash
+# Interactive
+npx renovate-log-parser install-analyze-skill
+
+# Non-interactive, local, with a GitHub Enterprise fetch section
+npx renovate-log-parser install-analyze-skill --scope local --with-gh \
+  --gh-base-url github.example.com \
+  --gh-org acme --gh-repo app --gh-workflow renovate.yml
+```
+
+The skill is written to
+`<root>/.agents/skills/renovate-log-analyzer/SKILL.md`, where `<root>` is the
+current working directory (`local`) or your home directory (`global`).
+
+| Arg / option    | Default        | Description                                                            |
+| --------------- | -------------- | ---------------------------------------------------------------------- |
+| `--scope`       | (prompt)       | `local` (`<cwd>/.agents/skills`) or `global` (`~/.agents/skills`)      |
+| `--with-gh`     | (prompt)       | Include a "fetch logs from GitHub via `gh`" section                    |
+| `--gh-base-url` | (prompt if gh) | GitHub Enterprise host (e.g. `github.example.com`); blank = github.com |
+| `--gh-org`      | (prompt if gh) | GitHub organization/owner                                              |
+| `--gh-repo`     | (prompt if gh) | Repository name                                                        |
+| `--gh-workflow` | (prompt if gh) | Filename of the workflow that runs Renovate (e.g. `renovate.yml`)      |
+| `--yes`         | `false`        | Skip all prompts; fail if a required answer is missing                 |
+
+**Exit codes:** `0` = success · `2` = tool/usage error (missing required answer
+when non-interactive, or a write failure).
+
+### `web`
+
+Starts the bundled [Nuxt](https://nuxt.com) web UI (with [Nuxt UI](https://ui.nuxt.com)
+and Nuxt's built-in Nitro server) for interactive, filtered log exploration. Pass
+an optional log path to open it automatically; otherwise use the in-app file
+picker. The server keeps the parsed log in memory (SQLite-backed) and streams
+paged rows to the client.
+
+| Arg / option | Default     | Description                                        |
+| ------------ | ----------- | -------------------------------------------------- |
+| `[path]`     | (none)      | Renovate JSONL log to open automatically in the UI |
+| `--port`     | `3000`      | Port to listen on                                  |
+| `--host`     | `localhost` | Host to bind to                                    |
+| `--open`     | `true`      | Open the web UI in your browser                    |
+
+```bash
+# Open the UI on a specific log
+renovate-log-parser web path/to/renovate.jsonl
+
+# Just start the server (pick a file from inside the UI)
+renovate-log-parser web --port 4000 --no-open
+```
+
+**The viewer** renders every log line in a virtualized, fixed-height list — a
+colored level glyph (`T/D/I/W/E/F`) plus the entry's `msg`.
+Clicking a row's arrow opens a details slide-over with a recursive,
+collapsible JSON tree of the full entry.
+
+**Filtering** (all AND'd, debounced):
+
+- **Log levels** — a dropdown to show/hide entries by level.
+- **Repositories** — include/exclude by repository, plus a
+  "Repository-independent" pseudo-group for entries with no `repository`.
+- **Ignored fields** — hide noisy root keys from the row list (`msg` is always
+  kept).
+- **Free-text search** — a field selector whose first entry, **Raw search**,
+  matches the whole line (any key or value); any other field does a
+  case-insensitive `*`-wildcard match scoped to that field.
+- **Pills** — dynamic, individually toggleable/removable filters created from row
+  and JSON-tree context menus (e.g. show-only/hide a `field`, or a
+  `field == value`; nested keys create a scoped "contains" search on their
+  top-level ancestor).
+
+## Development
+
+This repository is an npm workspace: the publishable CLI lives at the root and
+the Nuxt app lives in [`web/`](./web).
+
+```bash
+# Install all workspace dependencies
+npm install
+
+# Run the CLI from source (no build step) via tsx
+npm run dev:cli -- detect-errors path/to/renovate.jsonl
+npm run dev:cli -- web
+
+# Run the Nuxt app in dev mode (HMR) directly
+npm run dev:web
+
+# Build everything (Nuxt .output + compiled CLI)
+npm run build
+
+# Run the compiled CLI
+node dist/cli.js --help
+```
+
+### Testing
+
+```bash
+npm test           # Unit + fixture tests (fast; no build, no network)
+npm run test:fixtures  # Only the fixture tests
+npm run test:e2e   # Packaging E2E tests (slow: builds, packs, installs)
+
+# One-off, needed by the browser tests inside the E2E suite:
+npx playwright-core install chromium
+```
+
+Three suites, each catching a different failure class:
+
+- **Unit tests** (`src/core/__tests__/*.test.ts`) — synthetic, hand-written
+  JSONL logs asserting the detection contracts in isolation.
+- **Fixture tests** (`src/core/__tests__/fixtures.test.ts`) — the full
+  Parser → ErrorDetector/Analyzer pipeline run over _real_ Renovate logs
+  captured against
+  [`MShekow/renovate-log-parser-test`](https://github.com/MShekow/renovate-log-parser-test)
+  and committed under `src/core/__tests__/fixtures/`:
+
+  | Fixture                       | What it demonstrates                                                                                                                                                 |
+  | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `external-host-error.jsonl`   | NPM registry blocked → the run aborts with `result: "external-host-error"`                                                                                           |
+  | `various-issues.jsonl`        | Abandoned packages, a required config migration, and an npm `lock file error` whose `err.stderr` reports a `Conflicting peer dependency`                             |
+  | `failed-dotnet-install.jsonl` | `builds.dotnet.microsoft.com` blocked → `Datasource connection error` (`DEPTH_ZERO_SELF_SIGNED_CERT`) and `Failed to generate lock file` / "No tool releases found." |
+
+  The assertions are deliberately _semantic_ rather than snapshot-based, since a
+  Renovate log is full of volatile data (timestamps, pid, hostname, logContext,
+  dependency versions). They assert only the signals each scenario was captured
+  to demonstrate.
+
+- **Packaging E2E tests** (`e2e/pack-install.e2e.ts`) — build, `npm pack`,
+  install the tarball into an empty throwaway project, then drive the installed
+  `renovate-log-parser` binary against a fixture. This is the only suite that
+  can catch a missing `package.json#files` entry, a dropped Nuxt `.output`
+  symlink, or a `dist/` import that only resolved because `src/` sat next to it.
+  Set `SKIP_E2E=1` to skip.
+
+  Its nested `web UI` block starts the installed `web` command and drives the
+  real UI in a headless Chromium, using the `playwright-core` _library_ — there
+  is no second test runner or config file, these are plain `node:test` cases in
+  the same file. Because they run against the installed tarball, they assert
+  that the shipped Nuxt bundle actually boots and serves, not merely that its
+  files are present. Chromium must be installed once with
+  `npx playwright-core install chromium`; when a browser test fails, a
+  screenshot, an HTML dump and the captured console/server output are written to
+  `e2e-artifacts/` (CI uploads them as a build artifact).
+
+### Regenerating the log fixtures
+
+The [`compose.yml`](./compose.yml) stack runs Renovate against the test
+repository, with an NGINX "firewall" that Docker DNS points selected hostnames
+at, so outbound access to them fails exactly as it would behind a corporate
+proxy. The base file blocks nothing; each scenario layers on an override that
+adds the hostnames it needs to block:
+
+```bash
+# Requires a .env with GITHUB_PAT (+ optionally LOCAL_UID / LOCAL_GID)
+docker compose -f compose.yml up -d                                         # various-issues
+docker compose -f compose.yml -f compose.external-host-error.yml up -d      # external-host-error
+docker compose -f compose.yml -f compose.failed-dotnet-install.yml up -d    # failed-dotnet-install
+
+docker compose ... wait renovate        # block until Renovate exits
+cp container-out-logs/out.log src/core/__tests__/fixtures/<scenario>.jsonl
+docker compose ... down -v              # discard the generated certificate
+```
+
+Renovate must start from a _pristine_ repository — leftover `renovate/*`
+branches make it take a different code path ("Branch already exists") and skip
+the very work the fixture captures. Close and delete them first.
+
+[`.github/workflows/verify-fixtures.yml`](./.github/workflows/verify-fixtures.yml)
+automates all of this weekly (and on demand): one job per scenario, run strictly
+in sequence since they share one test repository, each starting by wiping every
+Renovate PR and branch. It overwrites the committed fixture with the freshly
+generated log and re-runs the fixture tests against it — so a Renovate release
+that renames a message or drops a field turns the workflow red. Nothing is
+committed back; the regenerated log is uploaded as an artifact so the fixture
+can be updated deliberately. The workflow needs a `TEST_REPO_PAT` secret (a
+fine-grained PAT with contents + pull-request write access to the test repo).
+
+### Linting & formatting
+
+[ESLint](https://eslint.org) (flat config) and [Prettier](https://prettier.io) are set up at the workspace root.
+
+```bash
+npm run lint          # ESLint for src/ (type-aware) + web/ (Nuxt rules)
+npm run format        # Prettier write pass over all non-ignored files
+npm run format:check  # Prettier check (no writes — useful in CI)
+```
+
+- **Root (`src/`)** — [`eslint.config.mjs`](./eslint.config.mjs) uses `typescript-eslint` `recommendedTypeChecked` rules against `src/**/*.ts`, with `eslint-config-prettier` appended to disable any rules that conflict with Prettier. Prettier itself runs with its defaults (semicolons, double quotes, trailing commas).
+- **Web (`web/`)** — [`web/eslint.config.mjs`](./web/eslint.config.mjs) delegates to the auto-generated `@nuxt/eslint` config, which covers Vue, TypeScript, and Nuxt-specific rules. The `web/` directory is excluded from the root ESLint and Prettier configs so the two setups stay independent.
+
+### How it's built
+
+- **CLI** — TypeScript compiled with `tsc` to ESM in `dist/`. Uses
+  [`yargs`](https://yargs.js.org) for command parsing. `yargs` is the only
+  runtime dependency.
+- **Web** — a Nuxt UI app built with `nuxt build`. It shares the CLI's parsing
+  and filtering logic from `src/core/` (aliased into the bundle as
+  `renovate-core`), so the browser and the CLI query the same SQLite-backed
+  model. The `web` command runs the self-contained Nitro server
+  (`web/.output/server/index.mjs`) as a child process; when given a log path it
+  hands it off to the UI via a `?log=` query parameter.
+
+### What gets published
+
+Two `package.json` mechanisms cooperate so that both build outputs ship to npm:
+
+- **`files: ["dist", "web/.output"]`** — an allow-list of what goes into the
+  published tarball. npm always adds `package.json`, `README`, `LICENSE`, and the
+  `bin` target, then includes everything matched here — both directories,
+  recursively. This list takes precedence over `.gitignore`, which is why
+  `web/.output/` (gitignored as a build artifact) is still published.
+- **`prepublishOnly: "npm run build"`** — a lifecycle hook npm runs automatically
+  before packing on `npm publish`. It builds the Nuxt `.output` and compiles the
+  CLI `dist`, so both directories exist and are current by the time the `files`
+  allow-list is evaluated.
+
+```
+npm publish
+  └─ prepublishOnly → npm run build → build:web (nuxt build → web/.output/)
+                                    → build:cli (tsc        → dist/)
+  └─ pack tarball using `files`: dist/ + web/.output/ (+ package.json, README, LICENSE)
+  └─ upload to registry
+```
+
+The result is a lean, self-contained package (no source or `node_modules` leak).
+Verify locally with `npm pack --dry-run`.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { detectErrorsCommand } from "./commands/detect-errors.js";
+import { analyzeCommand } from "./commands/analyze.js";
+import { webCommand } from "./commands/web.js";
+import { installAnalyzeSkillCommand } from "./commands/install-analyze-skill.js";
+await yargs(hideBin(process.argv))
+    .scriptName("renovate-log-parser")
+    .usage("$0 <command> [options]")
+    .command(detectErrorsCommand)
+    .command(analyzeCommand)
+    .command(webCommand)
+    .command(installAnalyzeSkillCommand)
+    .demandCommand(1, "You need to specify a command. Try --help.")
+    .strict()
+    .alias("h", "help")
+    .alias("v", "version")
+    .fail((msg, err) => {
+    // Genuine thrown errors propagate; usage/validation failures exit with the
+    // tool/usage exit code (2).
+    if (err)
+        throw err;
+    console.error(msg);
+    console.error("\nRun with --help for usage.");
+    process.exit(2);
+})
+    .help()
+    .parseAsync();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAEjF,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/B,UAAU,CAAC,qBAAqB,CAAC;KACjC,KAAK,CAAC,wBAAwB,CAAC;KAC/B,OAAO,CAAC,mBAAmB,CAAC;KAC5B,OAAO,CAAC,cAAc,CAAC;KACvB,OAAO,CAAC,UAAU,CAAC;KACnB,OAAO,CAAC,0BAA0B,CAAC;KACnC,aAAa,CAAC,CAAC,EAAE,4CAA4C,CAAC;KAC9D,MAAM,EAAE;KACR,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC;KAClB,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC;KACrB,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IACjB,2EAA2E;IAC3E,4BAA4B;IAC5B,IAAI,GAAG;QAAE,MAAM,GAAG,CAAC;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC;KACD,IAAI,EAAE;KACN,UAAU,EAAE,CAAC"}

package/dist/commands/analyze.d.ts

@@ -0,0 +1,24 @@
+import type { CommandModule } from "yargs";
+interface AnalyzeArgs {
+    path: string;
+    print: boolean;
+    "ignored-fields": string;
+    "line-from"?: number;
+    "line-to"?: number;
+    limit: number;
+    filter?: string[];
+    "filter-with-wildcard"?: string[];
+    "include-original-line": boolean;
+}
+/**
+ * `analyze <path>` — emit token-efficient structure for an AI coding agent.
+ *
+ * Without `--print` it prints compact single-line JSON whole-log stats (level counts +
+ * per-repository structure). With `--print` it streams a filtered, line-ranged,
+ * limited JSONL slice to stdout (truncation notices go to stderr so stdout stays
+ * clean).
+ *
+ * Exit codes: 0 = success; 2 = tool/usage error (bad path, unreadable, bad args).
+ */
+export declare const analyzeCommand: CommandModule<object, AnalyzeArgs>;
+export {};

package/dist/commands/analyze.js

@@ -0,0 +1,114 @@
+import { resolve } from "node:path";
+import { Parser } from "../core/parser.js";
+import { Analyzer } from "../core/analyzer.js";
+import { parseKeyValueFilter, parseWildcardFilter } from "../core/filters.js";
+/** Default root keys stripped from print-mode output. `msg` is never stripped. */
+const DEFAULT_IGNORED_FIELDS = "v,time,logContext,pid,hostname,name";
+/**
+ * `analyze <path>` — emit token-efficient structure for an AI coding agent.
+ *
+ * Without `--print` it prints compact single-line JSON whole-log stats (level counts +
+ * per-repository structure). With `--print` it streams a filtered, line-ranged,
+ * limited JSONL slice to stdout (truncation notices go to stderr so stdout stays
+ * clean).
+ *
+ * Exit codes: 0 = success; 2 = tool/usage error (bad path, unreadable, bad args).
+ */
+export const analyzeCommand = {
+    command: "analyze <path>",
+    describe: "Emit token-efficient structure/stats for an AI coding agent",
+    builder: (yargs) => yargs
+        .positional("path", {
+        type: "string",
+        describe: "Path to the Renovate JSONL log",
+        demandOption: true,
+    })
+        .option("print", {
+        type: "boolean",
+        default: false,
+        describe: "Print matching log lines (JSONL) instead of stats",
+    })
+        .option("ignored-fields", {
+        type: "string",
+        default: DEFAULT_IGNORED_FIELDS,
+        describe: "CSV of root keys to strip in print mode (msg never stripped)",
+    })
+        .option("line-from", {
+        type: "number",
+        describe: "Inclusive 0-indexed lower line bound (print mode)",
+    })
+        .option("line-to", {
+        type: "number",
+        describe: "Inclusive 0-indexed upper line bound (print mode)",
+    })
+        .option("limit", {
+        type: "number",
+        default: 50,
+        describe: "Max lines to print (print mode)",
+    })
+        .option("filter", {
+        type: "string",
+        array: true,
+        describe: "key:val scalar-equals filter, repeatable, AND'd (print mode)",
+    })
+        .option("filter-with-wildcard", {
+        type: "string",
+        array: true,
+        describe: "key:pattern wildcard filter (* = any run), case-insensitive, " +
+            "repeatable, AND'd (print mode)",
+    })
+        .option("include-original-line", {
+        type: "boolean",
+        default: false,
+        describe: "Add _oL (0-indexed source line) to each printed object",
+    }),
+    handler: (argv) => {
+        const parser = new Parser();
+        try {
+            const logPath = resolve(process.cwd(), argv.path);
+            parser.load(logPath);
+            const analyzer = new Analyzer(parser);
+            if (argv.print) {
+                const filters = [
+                    ...(argv.filter ?? []).map(parseKeyValueFilter),
+                    ...(argv["filter-with-wildcard"] ?? []).map(parseWildcardFilter),
+                ];
+                const result = analyzer.print({
+                    ignoredFields: splitCsv(argv["ignored-fields"]),
+                    lineFrom: argv["line-from"],
+                    lineTo: argv["line-to"],
+                    limit: argv.limit,
+                    filters,
+                    includeOriginalLine: argv["include-original-line"],
+                });
+                if (result.entries.length > 0) {
+                    process.stdout.write(result.entries.map((e) => JSON.stringify(e)).join("\n") + "\n");
+                }
+                if (result.truncated) {
+                    process.stderr.write(`Truncated: printed ${result.emitted} of ${result.totalMatched} ` +
+                        `matching lines (--limit ${argv.limit}).\n`);
+                }
+            }
+            else {
+                const stats = analyzer.stats();
+                process.stdout.write(JSON.stringify(stats) + "\n");
+            }
+        }
+        catch (err) {
+            // Tool/usage error (bad path, unreadable, bad --filter token, …).
+            console.error(`analyze: ${err.message}`);
+            process.exitCode = 2;
+        }
+        finally {
+            parser.close();
+        }
+    },
+};
+/** Split a CSV option value into trimmed, non-empty tokens. */
+function splitCsv(value) {
+    return value
+        .split(",")
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+}
+//# sourceMappingURL=analyze.js.map

package/dist/commands/analyze.js.map

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

package/dist/commands/detect-errors.d.ts

@@ -0,0 +1,17 @@
+import type { CommandModule } from "yargs";
+interface DetectErrorsArgs {
+    path: string;
+    out?: string;
+    "ignore-file"?: string;
+    "fail-on-warn": boolean;
+}
+/**
+ * `detect-errors <path>` — deterministically scan a Renovate JSONL log for
+ * build-breaking problems (exit 1) and warnings, optionally writing a stable
+ * machine-readable JSON report.
+ *
+ * Exit codes: 0 = no non-ignored errors; 1 = ≥1 non-ignored error (or, with
+ * `--fail-on-warn`, ≥1 non-ignored warning); 2 = tool/usage error.
+ */
+export declare const detectErrorsCommand: CommandModule<object, DetectErrorsArgs>;
+export {};