Stack audit example
A Python standard-library CLI that lists declarations and script names from explicitly supplied JSON manifests. It does not execute project scripts, install packages or contact a registry.
Run
Use Python 3.9 or later. From this directory:
python3 -B stack_audit.py fixtures/package.json
python3 -B test_stack_audit.py -v
The fixture is synthetic. No dependency installation is needed. Its report contains zod as a dependency, vitest as a dev dependency and test as a script name. The optional and peer sections are empty.
To inventory another project, supply its chosen manifest paths after stack_audit.py. The CLI does not discover workspaces for you. Read project instructions before choosing files. Don't point it at environment files or customer data.
What the output means
Each input produces one record, in argument order. Declaration and script names sort alphabetically. The four dependency sections remain separate; a name appearing in two sections appears in both. Missing sections are empty. The CLI prints a report only after every input passes validation. Read or validation failures exit with code 2 and no JSON on stdout.
The CLI checks the relevant JSON structure, not the complete package.json schema. It does not resolve dependency aliases, version ranges, lockfiles or transitive dependencies. Passing the same path twice produces two records. It reads the path you give it, including any symlink target, so use reviewed local files rather than arbitrary untrusted paths.
Version specifications and script bodies are omitted because they may include private URLs or credentials. Paths, dependency names and script names remain visible. Review those before sharing. A declaration isn't proof of installation, use, safety or personal recommendation.
Tests
test_stack_audit.py uses temporary synthetic files inside this directory and removes them when the tests finish. It checks multiple inputs, deterministic names, preservation of dependency sections, and omission of specifications and command bodies. A synthetic lifecycle command tries to create a marker file; the assertion requires that file to remain absent.
Invalid-input subtests cover malformed JSON, a non-object manifest, malformed section shapes, non-string values, invalid UTF-8 and a missing file. Each invalid batch must fail without a partial report or raw source text in the error.
See the article for the decision record that follows the inventory.