Changelog

0.5.0 - 2026-07-14

Fixed

• A tool the job merely named can no longer outrank the one that failed. Found by running ci explain over real failing runs from public repositories. Three of nine — encode/httpx, prefecthq/prefect and home-assistant/core — were decided by the job's cast list rather than its cause of death:

  • scripts/check-style CI shells run under set -x, so every command is echoed into the log, passing or not. httpx's echo of ruff check (a run that passed), plus F401 quoted inside ruff's non-fatal warning about a malformed noqa directive, made a plain 1 failed, 1416 passed pytest failure come out as python_lint at 0.71.
  • pip announces every dev dependency it resolves, so Collecting mypy==1.17.1 puts mypy in the log of a job that never type-checked anything. Prefect's pytest collection error came out as python_type_check.

  Signals are now judged by the line they land on: a rule whose every signal appears only on a set -x echo, an Actions step header (Run …) or a pip install line has watched a tool get named, never fail, and defers to a rule that matched a real error. Scoring itself is unchanged, so an invocation sitting next to a genuine error still corroborates it and keeps it at full confidence — a real dotnet, helm or php failure scores exactly as before. This generalises INVOCATION_ONLY_PATTERNS, which had to name every tool one pattern at a time and switched itself off entirely as soon as a single signal fell outside the list.

• python_test_failure now recognises pytest's own verdict. The rule could match a named failing test (FAILED x::y) or a bare pytest invocation, but not ===== 1 failed, 1416 passed in 18.37s =====, short test summary info, or a collection error (ERROR tests/x.py - ValueError). A run that reported the count and not the names — -q, or any plugin that rewrites the summary — was therefore carried by its invocation alone and lost to whatever tool the job had merely mentioned. The = run and the in 12.3s tail are pytest's summary line and not jest's, so node test failures are unaffected.

• ANSI colour codes no longer hide the failure. CI tools colour their output and CI keeps the colour on (Airflow runs pytest with --color=yes, cargo honours CARGO_TERM_COLOR=always, jest and eslint colour by default), and the GitHub log API serves those escapes back with the ESC byte written out as the two literal characters ^[. The colour reset lands inside the failure line — ^[[31mFAILED^[[0m tests/…::… — so FAILED .*:: and every other pattern spanning a coloured token silently stopped matching. A real apache/airflow test failure was reported as artifact_or_cache_failure because the only signal left uncoloured was the bare pytest invocation. Both encodings (real \x1b and literalised ^[) are now stripped before matching; the strip is anchored to the escape introducer, so error[E0277], [ERROR] and ordinary indexing are untouched.

• Post-failure cleanup noise no longer outranks the real cause. actions/upload-artifact appears in every job that uploads anything, and "No files were found with the provided path" is a warning it emits when its glob matches nothing (it says so itself: "No artifacts will be uploaded"). Together they fire on the commonest shape in CI — a test fails, and the if: failure() step uploading logs for diagnosis finds nothing — which tied the real cause and beat it on declaration order. A rule carried only by such signals now defers to one that matched an actual error. A genuine artifact or cache failure is unaffected: it trips a terminal signal ("Failed to CreateArtifact", "Unable to download artifact", "Cache service responded with 500").

• The classifier no longer reads a command that merely ran as the failure. Three bugs of the same shape, all found by running ci explain over real failing runs from public repositories rather than over the fixture zoo:

  • \btsc\b matched the x86 time stamp counter in the flags : line of /proc/cpuinfo, which perf-sensitive projects dump into their log preamble. A real rust-lang/rust build failure came back as typescript_typecheck on the strength of a CPU feature name. tsc now only counts in command position (pnpm tsc, > tsc --noEmit, npx tsc, tsc -p …) or before a flag/verb.
  • docker build / docker buildx build / docker compose appear in every job that builds a container as a setup step, and cargo test / clippy appear in the command line of every Rust CI job, passing or not. A rule matching only such signals now defers to a rule that matched an actual error, reusing the deferral already in place for ambiguous network signals. They still count toward confidence when a real error sits beside them, so a genuine docker or clippy failure is unchanged.
  • Because scoring is by matched-pattern count, one bogus signal was enough to tie the rule that matched the real error and beat it on declaration order alone. The zoo missed all of this: its fixtures are clean, and a real log is not — the same error[E0277] that a fixture classifies correctly was misread in the wild because the job also happened to run docker buildx build. No fixture changes classification or confidence (221 fixtures, top-1 1.0).

Added

• patchrail schema ci-classes now serves a published schema for ci classes --format json, and the suite validates real output against it. It was the one JSON command with no schema, no conformance test and no cookbook entry — which is why 0.4.0 could move it from patchrail.ci_classes.v1 to .v2 in a minor bump without anything going red, and why the break reached consumers (this project's own GitHub Action among them) silently. Changing the contract now means shipping the schema that describes it: test_schema_conformance.py compares the schema_version the CLI emits against the const in the schema a user can fetch, so the two cannot drift apart again. The schema also encodes the v2 rule itself — unknown is valid under fallback and rejected inside classes — so putting the sentinel back into the denominator fails validation.
• docs/json-cookbook.md documents the ci classes payload with a coverage recipe (which supported classes has a log corpus never exercised?), and its sample output is pinned to the code by test_readme_claims.py in both directions, like the README's counts.

0.4.0 - 2026-07-14

Minor bump rather than a patch: ci classes --format json changes its contract. schema_version is now patchrail.ci_classes.v2 and unknown left classes and count (see Fixed). Scripts pinned to the v1 shape need a one-line update.

Fixed

• patchrail ci classes no longer counts unknown as a supported failure class. It reported "41 supported failure classes" and listed unknown — with a reproduction command — alongside the 40 real ones, contradicting the README, the docs and the fixture benchmark, all of which say 40. unknown is what ci explain returns when no rule matches, so a coverage script following the README (ci classes --format json) was dividing by a denominator containing an entry it could never cover. The sentinel is still reported, under a new fallback key, and named in the text and markdown output; it is just out of classes and count. JSON consumers: schema_version is now patchrail.ci_classes.v2.
• README: the redaction bullet advertised 23 secret-redaction patterns; the shipped table has 24. The class, fixture and redaction counts the README advertises are now derived from the code by tests/test_readme_claims.py, so they fail the build instead of going stale (the fixture count was already pinned by tests, and it was the only one of the three that had stayed correct).

Changed

• patchrail ci explain/classify now print a first-use hint when the log input is empty or whitespace-only. The common cause is the README one-liner gh run view --log-failed | patchrail ci explain pointed at a run whose logs GitHub already expired (or a run that has not failed), which pipes in nothing. The error keeps its exit code 2 and clean stdout; it just adds a line telling the user to point it at a recent failed run instead of leaving them guessing. Non-empty input is completely unaffected.

0.3.1 - 2026-07-11

Added

• patchrail ci explain/classify now turn an unknown result into a contribution on-ramp: the text and markdown reports append one line pointing the maintainer at the ci_failure_fixture issue template (.../issues/new?template=ci_failure_fixture.md) so an unrecognized log becomes a fixture request instead of a dead-end. The classifier's behavior and JSON output are unchanged — the pointer is presentation-only and appears solely when failure_class == "unknown".
• patchrail -V is now a short alias for --version. Both print patchrail <version> and exit 0, matching the conventional single-letter flag most CLIs expose (handy in bug reports and CI logs).
• New tests/test_schema_conformance.py validates real CLI output against src/patchrail/schemas/*.v1.schema.json with jsonschema (dev-only dependency; the installed package still ships with zero runtime dependencies). Previously _load_schema() only read schema files as text to print them via patchrail ci schema; nothing checked that a payload builder's output still matched its schema. Covers ci-result (every fixture in examples/ci-triage/, 221 cases), ci-benchmark, and ci-fixture-check.
• mypy --strict now runs on src/patchrail/ci/classify.py (the classifier engine) as a dev dependency and a CI step, alongside ruff check/ruff format --check. The module already passed strict type checking with no changes required; this locks that in against regressions. See [tool.mypy] in pyproject.toml.
• New sanitized github-actions-cmake-gcc-compile-error fixture covers a real CMake + g++ undeclared-identifier link failure for cpp_build_failure, which previously had a classifier rule but no fixture in the benchmark zoo despite the README advertising C++ support. Bringing the benchmark zoo to 220 cases.
• java_build_failure now also recognises kotlinc's own diagnostic format (e: File.kt: (line, col): ...), Unresolved reference:, and Kotlin Gradle task failures (:compileDebugKotlin FAILED). A maintainer pasting only the kotlinc excerpt of a Kotlin/Android CI failure — without the Gradle Execution failed for task / BUILD FAILED banner further down the log — previously fell through to unknown at 0.15 confidence. New sanitized github-actions-kotlin-compile-excerpt-no-banner fixture guards this, bringing the benchmark zoo to 221 cases.

Fixed

• patchrail ci explain/classify now normalize the GitHub Actions log line prefix before classifying, so the common one-liner gh run view <run-id> --log-failed --repo <owner/repo> | patchrail ci explain classifies identically to a saved raw log. gh prefixes every line with <job>\t<step>\t<timestamp> (and a UTF-8 BOM on the first line), which shifted real content off the start of the line and silently defeated the classifier's line-anchored (^) patterns — dropping confidence (e.g. go_lint and node_test_failure fell from 0.95 to 0.89 on sparse logs). The raw Actions log-download form (<timestamp> <line>) is normalized too. Regression cases in tests/test_ci_classify_expansion.py pin gh-prefixed == raw.

Changed

• Extracted the entire funded-issues subcommand group (20 argparse handlers, ~50 markdown/text/CSV/JSONL renderers, and the argparse wiring for all 20 sub-subcommands — 3853 of cli.py's 10368 lines) into a new src/patchrail/cli_funded.py module, registered from _build_parser() via cli_funded.register(subparsers). No behavior change: same commands, same flags, same output. cli.py drops from 10368 to ~5650 lines. If you import patchrail.cli._normalize_recheck_observation or similar funded-issues internals directly (rather than going through the public CLI), import from patchrail.cli_funded instead.

0.3.0 - 2026-07-09

Fixed

• Deterministic Go test failures are no longer misread as network_transient_failure when their logs contain incidental network-shaped noise (dial tcp, connection refused, context deadline exceeded, i/o timeout). The classifier now defers a broad transient-network match built entirely from these ambiguous signals to the concrete failure when one also matched, so a real bug isn't mislabeled "just retry". Genuine outages still classify as transient because they trip a terminal signal (DNS resolution, rate limit, gateway error, TLS handshake, or a git remote hang-up) outside the ambiguous set. go_test_failure also now recognises the canonical --- FAIL: marker. New go-integration-test-network-noise fixture guards this, bringing the benchmark zoo to 208 cases.

Added

• patchrail --version now prints the installed version (e.g. patchrail 0.3.0) and exits, so a maintainer can confirm which release they are running without invoking a subcommand.
• java_build_failure now also recognises sbt (Scala on the JVM). sbt prints none of the Maven/Gradle banners the rule keyed on, so a genuine (project / Test / compileIncremental) Compilation failed — or an sbt.TestsFailedException — previously fell through to unknown. New signals cover the sbt session banner, incremental-compile failure, Scala not found: value/not found: type errors, and the sbt test-failure exception; the reproduction command now suggests sbt test. New sanitized github-actions-sbt-scala-compile fixture (modelled on a real scalatest/scalatest GitHub Actions run) guards this, bringing the benchmark zoo to 209 cases.
• New sanitized ruby-rspec-parallel-failure fixture captures a real rubocop/rubocop RSpec failure tail (parallel/turbo_tests summary with pending before failures), bringing the benchmark zoo to 207 cases.
• New xcode_build_failure class classifies Apple-platform build and test failures from xcodebuild, swift build/swift test, and Swift Package Manager — Swift compile errors, missing modules (error: no such module), unresolved package dependencies, and XCTest failures (** BUILD FAILED **, ** TEST FAILED **, The following build commands failed:). Backed by three sanitized fixtures in examples/ci-triage/, bringing the benchmark zoo to 169 cases and the classifier to 40 failure classes.
• New docs_build_failure class classifies documentation-site build failures from Sphinx (sphinx-build -W warnings-as-errors, missing toctree entries), MkDocs (mkdocs build --strict broken links), and Docusaurus (docusaurus build broken links). Backed by three sanitized fixtures in examples/ci-triage/, bringing the benchmark zoo to 166 cases.
• patchrail ci classes lists every supported failure class with its likely subsystem and reproduction command (plus the unknown fallback), in stable order. Supports --format text|json|markdown and --out, so the set of classes the classifier can diagnose is discoverable from the CLI instead of only in the source. Closes #150.

Fixed

• Real RSpec failures now classify as ruby_bundle_failure instead of unknown. RSpec prints its rerun list as rspec ./path/to/thing_spec.rb[…] and its summary as N examples, [K pending, ]M failures (rspec, parallel and turbo_tests) — neither of which the old rspec .*failures? pattern matched, so a pasted spec-failure tail without bundler setup lines fell through to unknown. Two shape-matching patterns were added to the rule. Surfaced by dogfooding a real rubocop/rubocop CI run.
• Python CI logs no longer misclassify as python_dependency_resolution just because they run python -m pip install. That bare command line was a detection pattern, but it appears in almost every Python CI job regardless of what actually failed, so any failing Python job with no stronger signal was reported as a dependency-resolution conflict with the misleading "pin or relax the conflicting dependency range" advice. Dogfooded against a real pandas-dev/pandas 32-bit CI run whose pip install failed at metadata-generation-failed (a package build error, Rust not found) — it was reported as python_dependency_resolution (0.53). The boilerplate pattern is dropped, so a build/metadata failure with no genuine resolution signal now stays honest (unknown) instead. To keep recall on real conflicts, two genuine pip signals were added: pip's actual Requires-Python wording (requires a different Python:) and its no-distribution (from versions: …) line; the three synthetic no-matching-distribution fixtures were updated to include the real (from versions: …) output pip prints. Benchmark stays at 206/206 top-1 with all confidence floors met; the bundled dependency-failure demo now reports 0.89 (three genuine resolution signals) instead of 0.95. Regression covered in tests/.
• patchrail ci explain/classify no longer hangs on large CI logs. The github_actions_workflow rule paired two unanchored lookaheads ((?=[\s\S]*.github/workflows/…)(?=[\s\S]*Invalid workflow file…)); under re.search that compound is retried at every start position, so a log that mentions .github/workflows/*.yml (every actions/checkout step does) but not a workflow-error phrase drove the matcher into O(n²) backtracking and pegged a core at 100% for minutes. Dogfooded against a real cli/cli Go CI run (~200 KB) that never returned. The lookahead is now anchored with \A so it is evaluated once, in linear time; the "workflow path AND error phrase present" signal is unchanged. Regression covered in tests/.
• Rust CI failures no longer misclassify as node_dependency_install, dotnet_build_failure, or java_build_failure because of generic boilerplate. The Swatinem/rust-cache action prints Lockfiles considered: (which matched the old bare lockfile node signal) and cargo prints build failed, waiting for other jobs to finish (which matched the case-insensitive Build FAILED / BUILD FAILED banners). The node lockfile signal now requires a whole-word lockfile, and the .NET/Gradle banners are matched case-sensitively so they fire only on the tool's actual Build FAILED / BUILD FAILED output. A real tokio-rs/tokio rustdoc failure (error[E0433]) now classifies as rust_test_failure. Regression covered in tests/.
• Sharper reproduce commands for three failure classes surfaced by patchrail ci classes / ci explain. node_script_missing no longer suggests npm run build (which just re-triggers the "missing script" error) and instead runs npm run to list the scripts package.json actually defines, so you can compare against the one your workflow calls. security_scan_failure names the concrete scanners to rerun locally (npm audit, pip-audit, cargo audit, trivy fs ., bandit -r ., semgrep --config auto) instead of the generic "rerun the failing security scan locally". github_actions_workflow points at actionlint .github/workflows/, which validates workflow syntax and action refs locally, rather than only printing the YAML back with gh workflow view.
• Real GitHub Actions logs no longer misclassify as git_checkout_failure when checkout actually succeeded. The rule dropped three boilerplate signals that appear in almost every Actions log regardless of outcome — the actions/checkout setup step, the git submodule foreach post-job cleanup line, and a bare git-lfs mention — keeping only genuine checkout/clone/submodule/LFS failure markers (fatal: ..., Failed to fetch submodule, smudge filter lfs failed, error downloading object, …). Dogfooded against a real pallets/flask CI run whose pytest jobs failed on a conftest SyntaxError but were reported as a git checkout problem.
• python_test_failure now also recognizes pytest collection failures (ImportError while loading conftest ..., N errors during collection), so a broken conftest.py or import-time error surfaces as a test failure with the python -m pytest -q reproduce line instead of falling through to a weaker or wrong class.
• patchrail ci explain and ci classify now fail clearly on empty or whitespace-only input (from --log or stdin) instead of silently reporting failure_class: unknown with confidence 0.15 and exit code 0. They print log input is empty to stderr, exit with code 2, and write nothing to --out, so a bad shell redirect is no longer mistaken for an unclassifiable log. Closes #151.
• Added node_script_missing to the published ci-result schema enum; the classifier could already emit it, so a valid classification previously failed schema validation for downstream consumers. A new test guards that every rule class is declared in the schema enum.

0.2.0 - 2026-07-07

Removed

• Removed the commercial Guide: link that ci explain appended to text and Markdown reports, and the matching guide URL outputs from the GitHub Action. Reports now end after the classification; per-class remediation write-ups live in-repo under docs/fix/.
• Removed commercial product links and campaign-tagged URLs from the README, docs, and the PyPI project URL list.
• Removed the distribution and web-metrics tooling (ci share-links and the web metrics commands and store). PatchRail no longer ships link-tracking or distribution helpers.

Changed

• funded-issues is now explicitly labeled experimental. Discovery commands default to safe-only filtering, and risky entries require an explicit --include-risky flag.
• Rewrote the README around the open-source CI triage workflow: quickstart with real classifier output, honest feature table, local-first safety section, and the fixture contribution path.

Added

• Added node_script_missing CI classification so npm/pnpm/yarn jobs that call a missing package script are separated from dependency-install failures and routed to a workflow/script repair path.
• Added a permanent source-level blocklist to the funded-issues tracker: owners manually verified as fake-bounty sources are dropped at the merge_into_store choke point (counted as blocked in the merge summary) and purge_blocklisted_entries removes any legacy entries; track runs the purge on every merge so existing stores self-heal.
• Added funded-issues import-algora-board, an offline parser for a locally saved Algora organization bounty-board page. It extracts the funder-stated USD amount, GitHub issue reference, posting age, and declared claim count per bounty, and can merge the scored records into a tracker store. No network access is performed.
• Added read-only competition and payout-vs-effort scoring signals plus the funded-issues competition and funded-issues payout-effort batch commands, all derived from public metadata observations with no claims, comments, or maintainer contact.
• Added an offline owner-level source_noise heuristic and funded-issues apply-recheck, a local-file-only command that transitions tracker entries to closed / stale / active from recheck observations.
• Added .NET/NuGet/C# and xUnit fixture coverage for dotnet restore, dotnet build, and dotnet test failure modes, growing the public CI fixture zoo to 153 cases.

0.1.1 - 2026-06-12

• ci explain now ends text and Markdown reports with a Guide: link to the matching getpatchrail.com /fix remediation page; unknown or unpublished failure classes fall back to the /fix index without a network call.
• Added funded-issues fresh, a local read-only radar over the tracker store that surfaces recently posted or recently labeled funded issues for fast solver-side triage.
• Added pre_commit_hook_failure CI classification so pre-commit hook output is recognized directly while the CLI still avoids linking to a missing /fix page until that guide exists.

0.1.0 - 2026-06-02

• Initial public CI Janitor snapshot.
• Added patchrail ci explain and patchrail ci classify.
• Added local Markdown, JSON, and text reports.
• Added Apache-2.0 license and safety/ethics documentation.
• Added fixture-backed tests, local benchmark command, and GitHub Actions CI.
• Expanded the initial CI fixture zoo to 101 sanitized synthetic examples across Python, Node, TypeScript, Go, Rust, and GitHub Actions failure modes.
• Added a read-only GitHub Actions triage artifact workflow.
• Added the experimental local Agent Control Plane queue with SQLite-backed work items, approval states, audit export, CI result import, and proposal records.
• Added the experimental read-only funded-issues CLI over local metadata, with safe-only filtering and explicit anti-abuse blocked actions.
• Added permission-only adopter reporting and a public metrics tracker for pilot outcomes, adoption signals, and open-source program evidence gaps.
• Added release-prep evidence docs, package smoke checks, and manual publish gates. Release tags, PyPI publishing, GitHub Releases, and public announcements remain maintainer actions.