capdrift 0.1.0

Show what a Dart package can do, what changed between versions, and whether that change violates your policy.

Changelog

0.1.0

First release.

Added

• capdrift diff <package> <from> <to>: reports capability changes between two published versions. Nothing else in the Dart ecosystem does this.
• capdrift inspect <package> [version]: capability profile of one version.
• capdrift audit [directory]: resolves the full dependency tree and reports what every package in it can do, separating capabilities you chose from ones you inherited.
• capdrift audit --include-dev: audits dev_dependencies as well. They never ship to your users, but they run on your machine and in CI with your credentials in the environment, and the report labels them dev only so a reader can tell which findings reach production.
• Scheduled corpus refresh workflow. The verify reference set is a snapshot, and an ageing set means verify quietly stops recognising near-misses of packages that became popular since. It regenerates monthly and opens a pull request only when the set actually changed.
• capdrift audit --approve and capdrift audit --baseline: approve the current capability state once, then report only drift from it. Drift confined to test and example surfaces is shown but exits 0.
• capdrift verify <package>: four checks for a name an assistant may have invented. Existence, then length-scaled Damerau-Levenshtein against a verified reference set of 162 popular packages, then adoption, then age against adoption. Similarity alone never warns.
• Seven capability families: network, process execution, filesystem, environment, native code, build hooks, platform.
• Platform capability detection: Android manifest permissions, iOS usage description keys, and the platforms a plugin ships native code for.
• Execution surface model. A finding in hook/ outranks the same finding in test/, and surface drives both report ordering and policy scoping. A native surface ranks above lib, because a plugin's manifest reaches every consumer while the Kotlin or Swift beside it cannot be read.
• Dependency resolution through dart pub get --no-precompile in a temporary directory with a temporary PUB_CACHE. It never writes into your project.
• Stable capability fingerprints (CF1:FAMILY:SURFACE:API:QUALIFIER), which are independent of file position so reformatting produces an empty diff.
• Surface-scoped policy in capdrift.yaml, with mandatory reasons on every rule.
• Four exit codes: 0 ALLOW, 1 REVIEW, 2 BLOCK, 3 INCOMPLETE.
• Text and versioned JSON output.

Verified

• Never-execute guarantee, enforced by a test that analyses a hostile fixture and asserts both that it did not run and that it was actually detected.
• Corpus A: 15 popular packages, 185 findings, 12 consumer facing.
• Corpus B: recall 8/8 against synthetic malicious fixtures, including a guard that an example app manifest never reports at native weight.
• Corpus C: no phantom changes across real version pairs.

Fixed before first release

Found by an external technical review, and each one verified against the code rather than taken on faith before being fixed.

• audit reported on a tree you may not have. It resolved fresh from the constraints instead of reading your committed pubspec.lock, so a project locked at http 1.5.0 was audited at 1.6.0. It now reads the lockfile by default, with --resolve for the deliberate "what would I get" question.
• Decompression was unbounded. The size check ran on the compressed bytes and again only after the archive had fully expanded. Measured: 299 KB of input materialised 300 MB before the limit fired. Decompression is now aborted mid-stream by a bounded sink, and stops at the limit.
• The documented 30 second analysis budget was never enforced. maxAnalysisTime was declared and read nowhere. It is now a real deadline producing INCOMPLETE.
• Baseline drift reported phantom removals. A package whose archive could not be fetched has an empty fingerprint set, which compared against a baseline read as every capability removed. Comparison now uses the same guard as approval.
• SECURITY.md overstated the network claim. dart pub get performs its own downloads, so "every network call goes through PubClient" was false.

Known limits

• Transitive packages carry no runtime-versus-dev attribution. A lockfile records that a package is transitive but not which root pulled it in, and the report states that rather than guessing.
• Path, git and SDK dependencies are skipped during resolution. They have no pub.dev archive to fetch, and the report says so rather than implying the tree was fully covered.