npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

ballast-cli

v0.1.1

Published

Compliance-as-code for AI systems. Scan your repo, classify it against the EU AI Act, generate the paperwork, and catch governance drift in CI.

Readme

Ballast

Compliance-as-code for AI systems.

Ship AI with your papers in order.

CI npm License: MIT


In 1876, after years of campaigning by Samuel Plimsoll, British ships were required to carry a painted line on the hull. Load past it and the mark disappears underwater — visible from the dock, to anyone, without paperwork or an inspector. The limit became legible instead of arguable.

It took another fourteen years to matter. The 1876 Act let the shipowner decide where to paint the line, and some painted it on the funnel; the mark only became meaningful once its position was derived from the ship, in the Board of Trade's 1886 load line tables, and made compulsory in 1890. That second half of the story is the one this project is actually about.

Governance documentation for AI systems is currently the opposite: written once, in a document nobody opens, describing a system that has since changed nine times.

Ballast puts the line back on the hull.

npx ballast-cli demo

Or replay the recorded run in your browser, no install: ballast.theogandolphe.com — the terminal there is not a video. It replays the committed cassettes and takes your input.

What it does

ballast init       Answer nine questions a scanner cannot answer for you
ballast scan       Find every model, SDK, prompt, tool definition and credential
ballast classify   Propose a risk classification — you confirm it
ballast generate   Write the risk assessment, model cards and compliance matrix
ballast check      Fail CI when the code and the paperwork disagree

The last one is the point. Everything else produces documents; check keeps them true.

── Governance drift ─────────────────────────────────────────────
  ! New model gpt-4o-mini is called but not declared.
    src/screening.ts:42

  The AI surface of this repository changed without the manifest
  being updated. Review the changes, then run `ballast scan --write`
  to record them, and re-run `ballast classify`.

It runs with no API key, no network, and no per-run cost, because a check that bills you per pull request gets budgeted away, and one that needs a secret cannot run on forks.

Why this exists

The EU AI Act's obligations are landing in waves, and the waves keep moving. The Digital Omnibus on AI — Regulation (EU) 2026/1744, in force since 27 July 2026 — deferred high-risk obligations for standalone Annex III systems to 2 December 2027 and embedded-product systems to 2 August 2028, while leaving the Article 50 transparency duties for chatbots and generative AI on 2 August 2026 and GPAI obligations where they have been since 2 August 2025. Generative systems already on the market get until 2 December 2026 for Article 50(2)'s machine-readable marking, and nothing else moved.

So the live question for most engineering teams is not "is the AI Act coming" but the harder one: which obligation applies to this system, and when. That question is answered from the code, and the answer changes every time the code does.

Ballast is built for the engineer who was just asked whether their feature is compliant, and who is the only person who actually knows what the system does.

Ballast is late to this, and this README should say so. The commercial platforms — Credo AI, Holistic AI, OneTrust, IBM watsonx.governance — sell dashboards to a Chief Risk Officer, and the compliance-automation vendors who already own that buyer, Vanta and Drata, are adding AI modules to an install base Ballast does not have. Separately, at least five open-source tools already read code or traffic against the AI Act: Systima Comply, Regula, Warden and ArkForge's MCP scanner scan source; AIR Blackbox intercepts calls at runtime. Some are good. Systima Comply in particular detects frameworks with a real AST where Ballast currently uses line-based matching, and it ships a baseline-and-diff command of its own.

What differs is what happens after the scan. Those tools report findings and scaffold templates. Ballast drafts the actual documents — risk assessment, model cards, compliance matrix — from a dated corpus of 38 AI Act provisions and 48 obligations, through an agent pipeline with a critic that attacks the draft and a human confirmation gate that blocks generation until someone accepts the classification. Whether that is worth more than a better scanner is a fair question, and docs/business/competitive-analysis.md argues it honestly, including a table of where the alternatives are ahead.

How the agents work

classify and generate run four agents with deliberately narrow jobs.

| | | | | --- | --- | --- | | Surveyor | reads the code | Sandboxed read_file / list_files / grep, nothing else. Establishes what the system actually does with the models it calls. Reports what it could not determine. | | Pilot | classifies | Reasons from the Surveyor's observations and your questionnaire answers to an EU AI Act tier and NIST AI RMF mapping. | | Drafter | writes | Produces the documents. Every substantive claim must carry a reference to a finding, a config answer, or a provision. | | Examiner | attacks the draft | Adversarial critic. Hunts for claims the evidence does not support — especially claims about controls that do not exist. |

Three design decisions carry most of the weight:

The model cannot invent law. The Pilot's output schema constrains citations to a closed enum built from the bundled knowledge base. A fabricated article number fails schema validation instead of reaching a document. Prompting alone does not survive contact with a confident model.

A human confirms the classification. classify writes its conclusion as proposed. generate refuses to run until a person has accepted it, and records who and when. Machines may propose a legal classification; people accept one.

The Examiner's unresolved objections are printed, not buried. Each document gets at most maxCriticIterations examinations — two by default, so one redraft — and any blocking objection still standing afterwards is printed and carried into the document's open questions. A pipeline that loops until the critic gives up produces documents that satisfy the critic rather than documents that are true.

Ballast also logs its own model calls, tool calls, validation retries and human sign-offs to ballast/audit-log.jsonl — model version, token counts, request hashes, latency, and whether the call was live or replayed. A tool that tells other teams to keep records of what their AI systems did has no business failing to keep its own. Prompt and response content is deliberately never logged: these files get committed, and prompts embed source code.

Install

npm install -g ballast-cli

Or run it without installing: npx ballast-cli <command>. Requires Node 22 or later. scan, check and demo never call a model and need no key. classify and generate use ANTHROPIC_API_KEY — your own key, billed to you, typically a few cents per run.

All four agents have been run against the live API end to end. docs/example-run.md walks through it: 19 model calls, roughly $1.03, the Pilot committing to provider and recording in the same breath that the commercial relationship "was not specified", and the schema layer bouncing three malformed model cards before any of them reached a document. Both transcripts and the documents they produced are committed, so the whole run replays with no key:

ballast classify examples/resume-screener --offline assets/demo-cassettes/classify.jsonl
ballast generate examples/resume-screener --offline assets/demo-cassettes/generate.jsonl

To make the agent stages replayable offline for others, record a session once against the bundled example:

ANTHROPIC_API_KEY=... pnpm cassettes:record

That writes transcripts to assets/demo-cassettes/, which classify --offline and generate --offline replay. Cassettes are keyed by a hash that includes the prompt version, so editing a prompt invalidates them and replay fails loudly rather than serving an answer to a question no longer being asked.

In CI

name: AI governance
on: pull_request

jobs:
  ballast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: theogandolphe/ballast@main

The action writes the drift report to the workflow summary and exposes a verdict output. Pin it to a tag once one exists; @main is honest about where it currently points.

Exit codes: 0 clean, 1 material drift, 2 no committed baseline to check against.

What it writes

ballast/
├── manifest.yaml         The declared AI surface. Read this one in a PR.
├── surface.json          Exact scan baseline. `check` diffs against it.
├── classification.yaml   The risk classification and who confirmed it.
├── risk-assessment.md    Risks, mitigations, and what could not be established.
├── compliance-matrix.md  Obligation → status → evidence, with dates.
├── model-cards/          One per model, describing your use of it.
└── audit-log.jsonl       Every agent interaction. Not committed by default.

All of it is meant to be committed. Governance artifacts outside version control cannot be reviewed, cannot be diffed, and cannot be trusted to describe the code as it shipped.

Limits, stated plainly

Ballast reads source code and a questionnaire. It cannot see your production behaviour, your training data, your evaluation results, or your operational processes, and it says so in the documents it writes rather than writing around the gap.

The knowledge base is a curated subset of the EU AI Act and NIST AI RMF, versioned and dated. It does not cover national implementing law, harmonised standards, or sector-specific regulation. Prompt and tool-definition detection is heuristic and marked as such — every finding carries a confidence tier, and the tool never claims more than it can show.

This is not legal advice. It is a way to keep an accurate, reviewable record of what your systems do, so that the conversation with someone who does give legal advice starts from facts. See docs/regulatory-notes.md for the methodology and its boundaries.

Documentation

Contributing

The most useful contribution is a missing SDK. src/scanner/registry/known-sdks.ts is plain data — add an entry, add a fixture under test/fixtures/repos/, open a pull request. Extending the knowledge base is similarly mechanical and similarly valuable.

pnpm install
pnpm verify      # lint, typecheck, test, build — the same gates CI runs

CONTRIBUTING.md covers both in detail, along with the two invariants a pull request must not break: the determinism contract behind ballast check, and the closed citation enum that stops an agent inventing law.

License

MIT © Theo Gandolphe