# JSON report

> The JSON report printed by patchula lookup --json and patchula run --json: repositories, dependencies, updates and lookup failures.

`patchula lookup --json` and `patchula run --json` print one report for the whole batch. This page describes schema version 8.

```json
{
  "schemaVersion": 8,
  "repositories": [{
    "repository": "owner/repo",
    "status": "complete",
    "reason": null,
    "packageFiles": [{
      "path": "Cargo.toml",
      "dependencies": [{
        "manager": "cargo",
        "name": "serde",
        "package": "serde",
        "current": {"value": "1", "version": "1.0.0", "digest": null},
        "updates": [{
          "newValue": "1", "newVersion": "1.1.0", "newDigest": null,
          "updateType": "minor", "group": null
        }]
      }]
    }]
  }],
  "stats": {"requests": 12, "notModified": 9, "cacheHits": 3, "extractionHits": 0, "lookups": 4, "phaseMicros": {}}
}
```

Readers should reject any other `schemaVersion`. Unknown fields are rejected too, so a new field means a new version. Version 8 added `cooldown` to a `heldBack` entry, naming the repository’s committed Cargo cooldown (`hours` and the config `file` that commits it) when the cooldown rather than `waitHours` holds the release, and to an `updates` entry, set only on a security fix proposed inside the cooldown so the lockfile run knows Cargo must allow the too-new release. Version 7 added the repository `stale` status for a repository that changed under the run, and `stale` as a pull request action status, with the `actions` object at its own version 3; version 6 split branch and pull request statuses, added the `stale` branch status and limited an image `state` to the ones in [security](https://count-patchula.sweepy.dev/guide/security/), with the `actions` object at its own version 2; version 5 added a dependency’s `registry`; version 4 added the `reason` of a notice that is not a template update; version 3 added an image rebuild’s `image` check.

## Repositories

| Field | |
| - | - |
| `repository` | `owner/name` |
| `status` | `complete`, `skipped`, `stale` or `error` |
| `reason` | Why it was skipped, raced or failed; null when complete |
| `packageFiles` | Files with dependencies, each with a `path` and `dependencies` |
| `warnings` | Optional. Files skipped, stale registry data and similar |
| `skipped` | Optional. Declarations that are not read as versions, such as images built from variables: `manager`, `path`, `line`, `value` and `reason` |
| `notices` | Optional. Newer versions that are reported and never proposed: a [Copier template](https://count-patchula.sweepy.dev/guide/managers/#copier)’s tags, which only `copier update` applies, and a release whose declaration cannot be rewritten to allow it without guessing, such as a Composer `^1 \| ^2` needing 3.0. Each has `manager`, `path`, `line`, `name`, `package`, `current`, `available`, and `compareUrl` when the host has a compare page; the second kind also has a `reason` |
| `lookupFailures` | Optional. Dependencies whose lookup failed; see [below](#lookup-failures) |
| `tooling` | Optional. [Tooling warnings](https://count-patchula.sweepy.dev/guide/auto-merge/#tooling-warnings) that hold on a live run, one per rule: `rule`, optional `detail` (`native` for `merge-without-ci`, `reviews-only` or `tagged-release`), the `branches` it applies to, and optional `silenced` with the reason from `warnings.quiet` |
| `defaultBranch`, `commit` | Optional. The branch and commit that were read |

A `complete` repository with no package files had nothing the Count supports.

A `stale` repository is one that changed under the run — its default branch moved, a pull request it was reconciling changed, or its write inventory disagreed with what the run read — so the run stopped before writing against the stale view rather than report a failure. Only a real run reports it: the report carries `actions` and is never a dry run. The server runs the repository again, and `run` exits 5 when a repository went stale and none errored.

## Lookup failures

Each entry in `lookupFailures` is a dependency whose registry lookup failed, so its updates are unknown. A repository with lookup failures is still `complete`, and the failure is not repeated in `warnings`.

```json
"lookupFailures": [{
  "manager": "npm",
  "path": "package.json",
  "name": "is-number",
  "package": "is-number",
  "datasource": "npm",
  "kind": "network",
  "message": "HTTP 503"
}]
```

| Field | |
| - | - |
| `manager`, `path`, `name`, `package` | The dependency, as in `packageFiles` |
| `datasource` | Where it was looked up, such as `npm`, `docker` or `github-tags` |
| `kind` | `network` (unreachable, or a 5xx answer), `auth` (401, 403 or 407), `not-found`, `rate-limit`, `parse` (an answer the Count could not read) or `other` |
| `message` | The error in words |

A failed digest lookup, such as an image tag whose digest could not be read, is a lookup failure too. Declarations in `skipped` and dependencies a rule ignores are never looked up, so they never fail. `lookup` and `apply` exit 4 when this list is not empty.

## Dependencies

| Field | |
| - | - |
| `manager` | The manager name used in configuration, such as `npm` or `cargo` |
| `name` | The name in the manifest |
| `package` | The registry identity; differs from `name` for aliases |
| `registry` | Optional. The [registry](https://count-patchula.sweepy.dev/guide/sources/#package-registries) the package was looked up in, when it is not the source’s public one |
| `occurrence` | Optional. Tells apart the same name declared more than once in a file |
| `current.value` | The text in the manifest, such as `^1.2` |
| `current.version` | The resolved version, or null when unknown |
| `current.digest` | The pinned digest, or null |
| `updates` | Proposed updates, in no particular order |
| `metadata` | Optional. See below |

## Updates

| Field | |
| - | - |
| `newValue`, `newVersion`, `newDigest` | The target; at least one is set. A `null` `newValue` with a `newVersion` is a lockfile-only update: only a lockfile changes. For a direct dependency that is a release its declaration already allows; a transitive package, which has no declaration, moves the same way |
| `updateType` | `major`, `minor`, `patch`, `digest` or `pin` |
| `group` | The group name from configuration, or null |
| `policy` | Optional. The policy that applies: versions, wait, windows, merge, labels. `waitHours` is the effective wait: a committed Cargo cooldown is already folded in |
| `releaseAge` | Optional. `publishedAt` and the `evaluatedAt` it was judged against |
| `fixes` | Optional. IDs of the current version’s advisories that the target no longer has |
| `cooldown` | Optional. On a security fix, the committed Cargo cooldown the target may sit inside: `hours` and the config `file`. The lockfile run’s Cargo must allow the too-new release for this update |
| `image` | Optional. For a pinned image’s new digest, the SBOM comparison: `state`, the compared `platforms`, the `sboms` read (`digest`, `source`, `generator`), `os`, `packages`, the `fixed` advisories with their `package`, `old` and `new` versions and `platforms`, `introduced` advisory IDs (most severe first), `introducedDetails` (OSV’s records for up to five of them), `detail` and `silenced` |

## Dependency metadata

| Field | |
| - | - |
| `source`, `kinds` | Where the dependency came from and its kinds, such as `devDependencies`, or `transitive` for a vulnerable package only a lockfile records |
| `locations` | Byte offsets, line, column and a pointer into the file |
| `resolution` | How `current.version` was found: `declared`, `lockfile`, `pinned-commit`, `floating-ref`, `release-line` (an installed pin, such as a `.tool-versions` or `.nvmrc` version) or `supported-range` (a runtime constraint such as `engines.node`). `lockfile` covers every manager whose lockfile recorded the resolved version — npm, Bun, Cargo, Bundler, Composer, Pyproject, Go (a `require` version in `go.mod` is the version Go’s resolution recorded) and Terraform providers |
| `heldBack` | Updates waiting on release age, per update type, with when they become eligible. An entry’s optional `cooldown` (`hours`, `file`) names a committed Cargo cooldown holding the release, in which case `eligibleAt` follows it and the dashboard offers no early-create box |
| `lookup` | When the lookup ran, whether a stored catalog view was reused (`catalog` with `fetchedAt` and `reused`), disabled update types, and versions rejected as deprecated or yanked |
| `tagDigests` | For GitHub Actions, the commit each proposed tag points at |
| `image` | Optional. For a pinned image, the current digest’s warning state, in the same shape as an update’s `image` |
| `advisories` | Optional. OSV advisories affecting the current version: `id`, `aliases` (CVE IDs among them), `severity`, `summary`, `url` and `fixedIn`, the lowest fixed release above the current one |
| `stale` | Registry data used past its freshness because the registry was rate-limited, with the time it was fetched |
| `credentialed` | Optional, `true` when a request made to look the dependency up, read its digests or read its image carried an operator registry’s credentials or a registry account’s token, directly or through a mirror; such a dependency’s lookup data is withheld from the [repository API](https://count-patchula.sweepy.dev/guide/server/#repository-api) |

## Actions

`run --json` adds an `actions` object. `lookup` leaves it out.

```json
"actions": {
  "schemaVersion": 3,
  "dryRun": true,
  "branches": [{
    "repository": "owner/repo",
    "branch": "patchula/example-major-0123456789abcdef",
    "baseCommit": "…",
    "status": "planned",
    "reason": "would create branch",
    "message": "chore(deps): update example to 2.0.0",
    "previousCommit": null,
    "commit": null,
    "verified": null,
    "lockfilePending": false,
    "files": [{"path": "mise.toml", "blobSha": "…", "diff": "--- a/mise.toml\n+++ b/mise.toml\n…"}]
  }],
  "pullRequests": [{
    "repository": "owner/repo",
    "branch": "patchula/example-major-0123456789abcdef",
    "number": null,
    "url": null,
    "status": "planned",
    "reason": null
  }]
}
```

A branch’s status is one of `planned`, `created`, `updated`, `rebased`, `unchanged`, `merged`, `deleted`, `skipped`, `stale`, `protected` and `error`. `stale` means the default branch changed or moved after the Count read it, so nothing was written; the server runs the repository again. A pull request’s status is one of `planned`, `created`, `updated`, `unchanged`, `closed`, `merged`, `skipped`, `stale`, `protected` and `error`; `stale` means a publish race — the PR changed under the run, or its head did not show the published commit — so a rerun retries it. A dry run never reports a write (`created`, `updated`, `rebased`, `closed`, `merged` or `deleted`) and has no `commit`. A published branch has its `commit` and `verified: true`.

`skipped`, `stale`, `protected` and `error` always carry a `reason`. A `protected` or `error` action makes its repository an `error`, and the CLI exits with 1.

`blobSha` is the Git blob SHA of the new file, and `diff` is a unified diff against the base commit.
