TAR to JSON — an inventory a build check can assert against
A tarball from a CI job is usually inspected by scrolling verbose tar output, which is hard to assert on. This route reads the tar entry by entry inside the browser tab and emits a JSON inventory: names, kinds, uncompressed payload lengths, counts and extension grouping. Nothing is uploaded, no member is written to a folder, and the output is small enough to diff or assert in a script.
tar mode bits, owner and group names are not carried into ZIP; directories are written as empty entries.
Processed on your device. Files aren’t sent anywhere.
Why a tarball needs an inventory
Verbose listing output is human text. An inventory is data, which means it can be compared, filtered and asserted.
- Each entry carries its name and kind, file or directory.
- File entries report payload bytes. In a plain TAR those bytes are already uncompressed; the count excludes headers and block padding.
- Directories appear as entries, so the tree shape is visible.
- Counts summarise entries, files, directories and total bytes.
- byExtension groups entries, which is where unexpected artefacts stand out.
The JSON the route produces
The schema is fixed, so a check written against one tarball works against the next.
| Field | Use in an assertion |
|---|---|
| source | confirms which input file was read |
| container | confirms the archive type that was parsed |
| entries[] | name, kind, payload bytes, and target (null for supported entries) |
| counts | assert entry, file and directory totals |
| byExtension | count regular files by their filename extensions |
| note | states what the inventory represents |
Fields that are not in the output
The inventory holds no file contents, no hashes, no modification times and no compression ratio. Contents would turn a summary into a data dump; a ratio would invite claims the reader cannot verify per member.
The symlink and other counts read zero because unsupported entries are rejected during the read rather than tallied. A tar containing symlinks, hardlinks, device entries, PAX or GNU extended headers, absolute or traversal paths, duplicate paths or non-UTF8 names produces an error, not a partial inventory.
Inventory questions for build checks
Are the byte figures the tar's stored sizes?
Does the JSON tell me whether the tarball is safe?
Does converting restore permissions or owners?
Writing assertions against the inventory
A source-only bundle should look like a source-only bundle: expected directories, no compiled output.
The directory count includes only explicit directory records; nested paths do not require one record for every implied folder. Check names when a count differs. Equal names and byte lengths also do not prove equal file contents: this inventory has no payload hashes.
- Convert the artefact .tar to JSON in the studio.
- Assert the directory count matches the tree you expected to ship.
- Assert byExtension contains no compiled or generated extensions.
- Compare total bytes with the previous build to spot a payload that grew unexpectedly.
- Keep the JSON next to the tarball so the check is reproducible.
- If conversion stops, read the reason and correct the input where possible. A repeated run of the same unsupported TAR will not make the limit disappear.
A listing you can assert on is worth more than a listing you can only read.
Why the JSON route exists alongside the text route
When the read stops
- The input ceiling is 12 MiB for one uncompressed TAR.
- At most 200 entries and 8 MiB per member are accepted.
- Plain TAR requires no decompression. Shared payload bounds are checked, but gzip expansion limits matter for the TGZ route instead.
- PAX/GNU extension records, links, special types, unsafe names and malformed headers are refused.
- Header checksums do not verify payload bytes; use an external content hash if that assurance is required.