How to file listing generator in developer workflows
- Step 1List the artifact — Open /archive-tools/file-listing-generator, drop the release ZIP, and pick listFormat: json for scripts or csv for a spreadsheet review. ZIP listing is metadata-only, so it is fast.
- Step 2Assert on contents — Load the JSON in a script and assert the manifest: expected paths present, forbidden paths (.env, *.pem, node_modules/) absent, and no unexpectedly large entries.
- Step 3Diff two builds by hand — List the previous and current artifact, then diff the two CSVs to see added, removed, or resized entries. For a structural archive diff, use /archive-tools/archive-diff over the two archives directly.
- Step 4Detect changes via crc32 — Compare the crc32 column across builds: a changed CRC on an entry whose size is unchanged is a content change you might otherwise miss.
- Step 5Normalise for reproducibility — Reproducible-build timestamps live in the archive itself, not the listing. Run /archive-tools/timestamp-normalizer on the artifact to fix dates, then re-list to confirm.
- Step 6Anchor with a checksum — Take an archive-level SHA-256 with /archive-tools/checksum-generator so CI can verify the exact artifact the listing describes.
Developer recipes and the right tool
The File Listing Generator covers the read/inventory step; sibling tools cover diffing, integrity, and reproducibility.
| Task | Tool | How |
|---|---|---|
| Audit what shipped in an artifact | File Listing Generator | List as json, assert paths in a script |
| Change detection across builds | File Listing Generator | Diff the crc32 / size columns of two listings |
| Structural diff of two archives | /archive-tools/archive-diff | Feed both archives; see added/removed/changed entries |
| Verify the exact artifact | /archive-tools/checksum-generator | Archive-level SHA-256 for CI to assert |
| Reproducible-build dates | /archive-tools/timestamp-normalizer | Normalise entry dates, then re-list to confirm |
JSON fields you can assert on
Fields available per entry in listFormat: json. Several are ZIP-only; design assertions around what your artifact format provides.
| Field | Type | Populated for | Assertion idea |
|---|---|---|---|
name | string | All formats | Forbidden path not present (no .env, no *.pem) |
size | number | All formats | No entry above an expected size ceiling |
ratio | string | ZIP (else 0.0%) | Spot already-compressed blobs that shouldn't be re-zipped |
crc32 | number | ZIP only | Unchanged size but changed CRC = content drift |
isEncrypted | boolean | ZIP only | Assert no entry is unexpectedly encrypted |
Cookbook
Developer-flavoured recipes. The JSON/CSV shapes are exactly what the tool emits; the scripts around them are illustrative.
Assert a release ZIP contains no secrets
List as JSON, then fail CI-style checks locally if a forbidden path appears. The listing is produced without extracting the artifact.
# File Listing Generator -> dist-listing.json (listFormat: json)
node -e "const L=require('./dist-listing.json');\
const bad=L.filter(e=>/\\.env$|\\.pem$|^node_modules\\//.test(e.name));\
if(bad.length){console.error('FORBIDDEN:',bad.map(e=>e.name));process.exit(1)}\
console.log('clean:',L.length,'entries')"Detect a content change with the same file size
Two builds, same byte size on a config file, different crc32 — a content change you would miss looking at sizes alone.
build-A-listing.csv: config/app.json,512,210,59.0%,...,3a4b5c6d,false
build-B-listing.csv: config/app.json,512,210,59.0%,...,77ee11aa,false
^^^^^^^^ crc32 changed -> content driftSpreadsheet review of an artifact
Open the CSV in Sheets, sort by size descending, and eyeball the biggest entries and their ratios in seconds.
name,size,compressedSize,ratio,lastModified,isDirectory,compressionMethod,crc32,isEncrypted assets/vendor.js,983040,310000,68.5%,2026-05-30T11:00:00.000Z,false,Deflate,aa01bb02,false assets/logo.png,204800,203500,0.6%,2026-05-30T11:00:00.000Z,false,Deflate,cc03dd04,false
Reproducible build: normalise then confirm
The listing reflects what is in the archive; to fix non-deterministic dates you normalise the archive, not the listing.
# 1. /archive-tools/timestamp-normalizer -> sets all entry dates to a fixed value # 2. File Listing Generator (txt) on the normalised ZIP: # Archive: dist-normalized.zip # Entries: 12 dist/index.js 4.7 KB 1980-01-01T00:00:00.000Z dist/index.css 1.2 KB 1980-01-01T00:00:00.000Z
Why a non-ZIP artifact listing looks thinner
If your build emits .tar.gz, expect reduced columns: ratio 0.0%, blank crc32/method/isEncrypted, and the archive's own date on every entry.
name,size,compressedSize,ratio,lastModified,isDirectory,compressionMethod,crc32,isEncrypted bin/server,5242880,5242880,0.0%,2026-05-30T11:00:00.000Z,false,,,false # -> for assertions on a tar.gz, rely on name/size; crc32/ratio aren't available
Edge cases and what actually happens
No public API or CLI yet
ManualThe tool runs one archive per page load with no programmatic endpoint, so you cannot wire it directly into a CI step. The closest scripted equivalents are fflate (Node) for ZIP/GZIP and a CLI like 7z for other formats.
Single archive per run — no batch
ManualThere is no folder or batch input. To inventory many artifacts at once, extract them with /archive-tools/batch-extraction-manager or roll them up with /archive-tools/batch-compression-report, which do accept multiple files.
crc32 only available for ZIP
ExpectedCRC-based change detection works for ZIP artifacts only. For tar.gz/7z, the crc32 column is blank; fall back to name/size comparison or take an archive-level SHA-256 with /archive-tools/checksum-generator.
Listing does not change the archive
By designThe tool is read-only; it produces a manifest and never rewrites the artifact. To change entry dates for reproducible builds, use /archive-tools/timestamp-normalizer, then re-list to verify.
ratio is 0.0% on a non-ZIP artifact
ExpectedcompressedSize equals size for non-ZIP formats, so the ratio reads 0.0% even though the data is compressed. Do not assert on ratio for tar.gz/7z; use /archive-tools/compression-ratio-calculator for real numbers.
Artifact over the tier cap
Rejected (tier limit)Free caps at 50 MB, Pro 500 MB, top tiers 2 GB. A big monorepo release bundle may need Pro or higher; the check runs before listing so oversized artifacts never start.
Artifact entry count over the cap
Rejected (tier limit)A bundle with tens of thousands of small files can exceed the entry cap (Free 500, Pro 50,000, top tiers 500,000) before the size cap. Upgrade or split it.
JSON crc32 is a number, CSV crc32 is hex
ExpectedIn CSV the crc32 is an 8-character zero-padded hex string; in JSON it is the raw integer. If you compare CRCs across the two outputs, convert one side rather than comparing them directly.
Frequently asked questions
Is there an API or CLI for this?
Not yet — the tool runs one archive per page load with no public endpoint. For scripted listing today, use fflate (Node) for ZIP/GZIP or a CLI like 7z for other formats.
How do I audit what shipped in an artifact?
List the ZIP as json and assert in a script: expected paths present, forbidden paths (.env, *.pem, node_modules/) absent, no oversized entries. The listing is produced without extracting.
Can I diff two builds?
List both and diff the CSVs, or for a structural diff feed the two archives to /archive-tools/archive-diff. The crc32 column catches same-size content changes the size column misses.
Does crc32 work for change detection?
Yes, for ZIP artifacts — a changed CRC on an unchanged size is content drift. For tar.gz/7z the column is blank, so use name/size or an archive-level SHA-256.
Can I batch many artifacts?
Not with this tool — it is single-archive. Use /archive-tools/batch-extraction-manager or /archive-tools/batch-compression-report for multiple files at once.
How do I make the listing reproducible?
The listing reflects the archive, so normalise the archive first with /archive-tools/timestamp-normalizer (e.g. to 1980-01-01), then re-list. The dates in the listing will then be stable.
Why is the ratio 0.0% on my tar.gz?
Non-ZIP formats report compressedSize equal to size, so ratio is 0.0% regardless of actual compression. Use /archive-tools/compression-ratio-calculator for real per-file ratios.
Is the crc32 the same in CSV and JSON?
It is the same value, but CSV renders it as 8-character hex and JSON as a raw integer. Convert before comparing across the two outputs.
Does listing modify the artifact?
No. The tool is read-only and never rewrites the archive — it only produces a manifest file.
What size and entry limits apply?
Free 50 MB / 500 entries, Pro 500 MB / 50,000, Pro-media and Developer 2 GB / 500,000. Both are enforced before processing.
Can I verify the exact artifact a listing describes?
Yes — take an archive-level SHA-256 with /archive-tools/checksum-generator and have CI assert it. The listing tells you what is inside; the checksum pins which archive it was.
Does the output need any special CI format?
No. CSV/JSON/TXT are standard; load them with any tooling. There is no JAD-specific wrapper around the listing.
Privacy first
Every JAD Archive tool runs entirely in your browser using fflate, @zip.js/zip.js, and the libarchive WASM bridge. Your archives never leave your device — verified by zero outbound network requests during processing.