Artifact Diff

Compare

Compare artifacts before you gate a release

Goal: compare semantic structure and prompt output without touching a warehouse, then decide whether the change is safe to ship.

CLI

Artifact-only comparison

rawctx diff accepts package refs, local directories, and .rawctx.tar.gzarchives. For release gates, prefer comparing the same package lineage. Cross-package diff still helps with rename, migration, fork, and format-conversion reviews.

rawctx diff ./pkg-v1 ./pkg-v2
rawctx diff semantic ./pkg-v1 ./pkg-v2 --format json --severity breaking
rawctx diff @scope/jaffle-metrics@1.0.0 @scope/jaffle-metrics@1.1.0 --format github
rawctx diff ./native-pkg ./osi-export --format markdown

Python SDK

Structured reports for notebooks and CI

Use semantic_diff(), prompt_diff(), diff_artifacts(), and client-level diff() helpers when you want JSON-shaped reports instead of terminal text.

import rawctx

semantic = rawctx.semantic_diff("./pkg-v1", "./pkg-v2")
prompt = rawctx.prompt_diff("./pkg-v1", "./pkg-v2", max_tokens=2000)
combined = rawctx.diff_artifacts(
    "@scope/jaffle-metrics@1.0.0",
    "@scope/jaffle-metrics@1.1.0",
    registry="https://api.rawctx.dev",
)

with rawctx.RawctxClient(registry="https://api.rawctx.dev") as client:
    report = client.diff("./pkg-v1", "./pkg-v2")
    prompt_only = client.prompt_diff("./pkg-v1", "./pkg-v2", max_tokens=2000)

What gets compared

semanticpromptevaljson|github|markdown|junit

Top-level rawctx diff runs semantic and prompt comparison together. eval stays explicit because it measures model behavior, not deterministic package structure.

Lineage guidance

Use the same package name or release lineage when you attach severity gates or CI exit codes. Use cross-package diff when the review target is a migration or a structural handoff, not a drop-in upgrade.

Execution boundary

Diff reads artifacts only. It does not query a warehouse, execute SQL, or compare underlying data values.