# leita.report/1

`leita --report out.json` writes one JSON object describing one finished scan
of one target. This is its schema. A later version that a reader of this one
would misread gets a new `schema` value; adding a member does not.

Conventions:

- Sizes are bytes on disk, as integers. They can exceed 2^53 only past 8 PiB.
- Times are ISO 8601 in UTC to the second, such as `2026-09-23T10:41:02Z`.
  The scan's duration is an ISO 8601 duration, such as `PT1.500S`.
- `share` is a fraction of `totals.bytes`, 0 to 1, to six places.
- Every member is always present. One that is unknown or was not asked for is
  `null`, not left out. The one exception is `path_base64`, below.
- Paths are full paths, joined with the separator of the machine that scanned.

## Paths that are not UTF-8

A filesystem can name a file with bytes that are not UTF-8, and JSON text has to
be UTF-8. Such a `path` has each invalid byte replaced by U+FFFD, so it stays
readable. A `path_base64` member beside it then carries the exact bytes in
standard base64 with padding. A `path_base64` member is present only on such
paths, so a program can rebuild the real path with
`path_base64 ?? utf8(path)`. Control characters such as a newline are valid
UTF-8 and appear in `path` as JSON escapes.

## Members

```
schema               "leita.report/1"
generated            time the report was built
generator            {"name": "leita", "version": string}
target               {"path", "volume", "filesystem", "engine"}
  path               the directory, drive or image scanned
  volume             the device behind it, or null
  filesystem         "ntfs" "refs" "exfat" "fat32" "network" "other", or null
  engine             "mft" (read NTFS's table), "walk", "synthetic", or null
scan                 {"started": time or null, "duration": ISO 8601 duration}
totals               {"bytes", "files", "directories"}
  bytes              on disk under the target, the target's own included
  files              files under the target; another hard link to a file
                     already counted is not counted again
  directories        directories under the target, not counting the target
space                {"total", "free"} of the volume, or null when unknown
compared             {"taken": time, "bytes"}, the earlier scan of the same
                     place that sizes are compared with, or null for none
largest_directories  entries, largest first
largest_files        entries, largest first
kinds                one per kind, in the order below
reclaim              {"bytes", "groups"}, or null unless asked for (--reclaim)
generated_by         "Generated by leita <version> on <time>"
```

An entry:

```
path            the full path (and path_base64, see above)
bytes           on disk; a directory's includes everything under it
share           of totals.bytes
kind            one of the kinds below
bytes_before    what it held in the compared scan, or null
change          bytes - bytes_before, or null
```

`bytes_before` is null when no scan is compared. It is also null when the
compared scan kept no record of the entry. A scan keeps only entries of at
least 1 MiB, so a null means the entry was under 1 MiB then, or not there.

A kind:

```
kind     "folder" "multimedia" "image" "archive" "document" "text" "binary"
         "cache" "other"
name     as a person reads it: "Folder", "Multimedia", ...
bytes    on disk
files    how many files
share    of totals.bytes
```

A kind is decided by a file's name. Everything under a build or cache directory
(node_modules, target, .cache, ...) is `cache`. A directory's own allocation is
`folder`. The kinds' bytes add up to `totals.bytes`. An entry's `kind` follows
the same rules, and a directory entry is `folder` or `cache`.

A Reclaim group, with categories in the order below and empty ones left out:

```
category  "dependencies" "build_output" "python" "package_cache" "app_cache"
          "trash"
name      as a person reads it
reason    why deleting it loses nothing
bytes     the group's total
items     [{"path", "bytes", "share"}], largest first
```

The top-level `reclaim.bytes` is the sum of the groups.