pixellint

# Pixellint

[![Rust](https://github.com/aleksUIX/pixellint/actions/workflows/rust.yml/badge.svg)](https://github.com/aleksUIX/pixellint/actions/workflows/rust.yml)
[![crates.io](https://img.shields.io/crates/v/pixellint.svg)](https://crates.io/crates/pixellint)
[![npm](https://img.shields.io/npm/v/pixellint.svg)](https://www.npmjs.com/package/pixellint)
[![docs.rs](https://img.shields.io/docsrs/pixellint-core)](https://docs.rs/pixellint-core)
[![license](https://img.shields.io/crates/l/pixellint.svg)](LICENSE)

Pixellint is a spec-first validator for pixels, postbacks, conversion API
payloads, and other measurement artifacts. It runs in a terminal, in CI, and in agents, and every
finding carries a stable id, a severity, an evidence level, and the document it
came from.

Broken pixels cost attribution, QA time, and campaign money. The tooling that
exists is fragmented: vendor-specific helpers, enterprise tag auditors, and
schema linters that know nothing about ad tech. Pixellint is the open
validation layer underneath all of that.

```bash
$ pixellint validate url 'https://www.facebook.com/tr?ev=Purchse&em=buyer@example.com'
rulepack: core
  ok
rulepack: vendor/meta (vendor: meta)
  error   vendor.meta.param.id.missing   `id` is required on Meta Pixel requests but is not present. It is the numeric Pixel ID from Events Manager.
    fix: Set `id` to the numeric Pixel ID shown in Events Manager.
    docs: https://developers.facebook.com/docs/meta-pixel/get-started
  warning vendor.meta.param.ev.invalid   `ev` is `Purchse`, which is not one of the documented values: PageView, AddPaymentInfo, ...
    fix: Use a standard event name, or confirm the custom event is registered in Events Manager.
    docs: https://developers.facebook.com/docs/meta-pixel/reference
  error   vendor.meta.pii.unhashed_email A parameter carries what looks like a raw email address. Meta requires customer information to be normalized and SHA-256 hashed before it is sent.
    fix: Normalize the value, hash it with SHA-256, and send the hex digest instead of the plain address.
    docs: https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching

2 error(s), 1 warning(s), 0 info message(s) across 2 rulepack(s).
```

Server-side events are checked in the body, one event at a time:

```bash
$ pixellint validate json '{"data":[{"event_name":"Purchase","event_time":1770000000000,
    "action_source":"website","user_data":{"em":"buyer@example.com"}}]}'
rulepack: vendor/meta-conversions-api (vendor: meta)
  error   vendor.meta-conversions-api.body.event_time.invalid `event_time` must be at most 10 digits, but `1770000000000` has 13. Meta documents it as a Unix timestamp in seconds...
    fix: Send seconds, not milliseconds: divide a JavaScript `Date.now()` by 1000 and floor it.
  error   vendor.meta-conversions-api.body.purchase_requires_value_and_currency A `Purchase` event is missing `custom_data.value` or `custom_data.currency`.
  error   vendor.meta-conversions-api.body.website_requires_source_url The event is marked `action_source: website` but carries no `event_source_url`.
```

## Install

```bash
cargo install pixellint          # CLI
cargo install pixellint-mcp      # MCP server
npm install pixellint            # library, WASM-backed
```

Or paste a URL into the playground at [pixellint.org](https://pixellint.org),
which runs the same engine in your browser. Artifacts you test may be stored;
see [privacy](https://pixellint.org/privacy/). Vendor contracts are at
[pixellint.org/packs/](https://pixellint.org/packs/). Guides for pixels,
conversion APIs, and consent are at
[pixellint.org/docs/](https://pixellint.org/docs/).

Start with the contracts people actually hit:

- [Conversion API validator](https://pixellint.org/docs/conversion-api-validator/)
- [Pixel not firing](https://pixellint.org/docs/pixel-not-firing/)
- [Conversions API not working](https://pixellint.org/docs/conversions-api-not-working/)
- [What is a conversion API](https://pixellint.org/docs/what-is-a-conversion-api/)
- [Reddit CAPI](https://pixellint.org/docs/reddit-pixel-and-capi/)
- [DART Floodlight tags](https://pixellint.org/docs/floodlight-and-campaign-manager/)
- [Facebook Pixel Helper vs Network](https://pixellint.org/docs/facebook-pixel-debugger/)
- [Pinterest standard events](https://pixellint.org/docs/pinterest-tag-and-capi/)

## Use it

### QA

Validate an inline artifact, a file with `@path`, or stdin with `-`:

```bash
pixellint validate url 'https://px.ads.linkedin.com/collect?pid=123456&fmt=gif'
pixellint validate postback @conversion-endpoint.txt --json
printf '%s\n' 'https://example.com/tracking?cb=[CACHEBUSTING]' | pixellint validate vast - --state template
```

Callers that already extracted many URLs (Vastlint, an HTML adapter) pass them
as a document. Identical values validate once:

```bash
pixellint validate-many @extracted.json --json
```

`extracted.json` is the wrapper in
[docs/MULTI_ARTIFACT_SCHEMA.md](docs/MULTI_ARTIFACT_SCHEMA.md), or a JSON array
of URL strings. Pixellint does not parse VAST, HTML, or GTM.

`vast` means one tracking URL extracted from VAST, not a VAST XML document.
It enables the IAB VAST macro-name checks on that URL.

Use `request` for a complete HTTP capture. It links endpoint, method, headers,
query fields and body so the destination's transport and payload rules run
together:

```bash
pixellint validate request @captured-request.json --json
```

The capture has string `url` and `method`, a `headers` object or list of
`{ "name": "...", "value": "..." }` entries, and an optional raw string `body`.
See [docs/HTTP_REQUEST_SCHEMA.md](docs/HTTP_REQUEST_SCHEMA.md) for examples and
validation limits. A bare URL passed as `request` keeps its existing behavior.

If the artifact is still a template with unexpanded macros, say so, and macro
rules adjust:

```bash
pixellint validate url 'https://example.com/pixel?cb=[CACHEBUSTING]' --state template
```

### CI

`pixellint validate` exits `0` when the artifact is clean or only produced
warnings, `1` when any error-severity finding is present, and `2` on a usage or
input problem.

```yaml
- uses: aleksUIX/pixellint@v0.31.12
  with:
    path: fixtures/conversion-pixel.txt
    kind: url
```

`version` selects the CLI release (`auto` follows the action's own `v*` tag).
Linux and macOS runners, x86_64 and aarch64. The Action downloads a prebuilt
tarball from GitHub Releases.

Or install the CLI:

```yaml
- name: Validate tracking artifacts
  run: |
    cargo install pixellint
    pixellint validate url @fixtures/conversion-pixel.txt
```

### Agents

```bash
cargo install pixellint-mcp
```

`pixellint-mcp` speaks MCP over stdio and exposes three tools. It does not
send artifacts; there is no hosted MCP on pixellint.org. Playground artifacts
on pixellint.org may be stored; see [pixellint.org/privacy](https://pixellint.org/privacy/).

- MCP Registry name: `mcp-name: io.github.aleksUIX/pixellint`

- `list_rulepacks`
- `list_vendors`, optionally filtered by `category` or attributing a single `host`
- `validate_artifact`, taking `artifact_kind`, `artifact`, and optional
  `claimed_vendor`, `expansion_state`, `rulepacks`, `except_rulepacks`

Responses include the structured findings, the detected vendors, and a
severity summary, so an agent can act on the result without parsing prose.

### Node

The npm wrapper requires Node.js 18 or newer. Its ESM entry uses `node:module`
to load the Node-target WASM build. For a browser integration, build
`pixellint-wasm` for a browser target and supply a browser loader, as the
playground does.

```js
import { validate, isOk } from "pixellint";

const summary = validate("https://www.facebook.com/tr?ev=Purchase");
isOk(summary); // false, the pixel id is missing
```

### Library

```rust
use pixellint_core::{ArtifactKind, Engine, ExpansionState, ValidationOptions, ValidationRequest};

let engine = Engine::default();
let request = ValidationRequest {
    artifact_kind: ArtifactKind::Url,
    artifact: "https://www.facebook.com/tr?id=1234567890123456&ev=PageView".to_string(),
    claimed_vendor: None,
    expansion_state: ExpansionState::Unknown,
};

let summary = engine.validate(&request, &ValidationOptions::default())?;
assert!(summary.is_ok());
```

## Rulepacks

`core` runs on every URL-like artifact. Vendor packs run only when the artifact
targets their endpoints, so you get vendor checks without asking for them, and
nothing fires on an endpoint it does not understand. A conversion API body has
no endpoint to go by, so those packs claim it by the shape of the payload.

The table shows selected built-in packs. Run `pixellint list-rulepacks --json`
for the complete inventory in your installed build.

| Rulepack | Covers | Evidence |
| --- | --- | --- |
| `core` | URL validity, transport, credentials, fragments, ad-tech macro handling, IAB consent signals | normative |
| `vendor/meta` | `facebook.com/tr` pixel requests | official vendor |
| `vendor/meta-conversions-api` | Graph API events edge, URL and JSON event payload | official vendor |
| `vendor/google-analytics` | GA4 Measurement Protocol, URL and JSON event payload | official vendor |
| `vendor/google-analytics-collect` | The `/g/collect` transport the Google tag uses in the browser | ecosystem reference |
| `vendor/google-tag-manager` | `gtm.js`, `gtag/js`, and `ns.html` loader requests | official vendor |
| `vendor/google-ads-conversion` | Google Ads conversion and view-through pixels | official vendor |
| `vendor/google-ads-click-conversions` | Google Ads UploadClickConversions JSON | official vendor |
| `vendor/floodlight` | Campaign Manager Floodlight activity tags | official vendor |
| `vendor/cm360-tracking-ad` | CM360 tracking ads, `dc_trk_aid` and `dc_trk_cid` | official vendor |
| `vendor/cm360-vast-event` | CM360 VAST event pixels, `dc_oe` on googlesyndication | ecosystem reference |
| `vendor/google-ad-manager` | Ad Manager `/gampad/ads`, `iu` `sz` `output` `env` `gdfp_req` `correlat