Pixellint

Pixellint is a spec-first validator for pixels, postbacks, 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.

$ 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).

Install

cargo install pixellint

Use it

QA

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

pixellint validate url 'https://px.ads.linkedin.com/collect?pid=123456&fmt=gif'
pixellint validate postback @conversion-endpoint.txt --json
curl -s "$TAG_URL" | pixellint validate vast -

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

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. That makes it usable as a gate:

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

Agents

cargo install pixellint-mcp

pixellint-mcp speaks MCP over stdio and exposes two tools:

• list_rulepacks
• 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.

Library

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.

Select packs per run:

pixellint validate url "$ARTIFACT" --rulepack core
pixellint validate url "$ARTIFACT" --except vendor/meta
pixellint list-rulepacks --json

Full rule inventory with citations: docs/STANDARDS.md.

Evidence levels

Findings say where their authority comes from, and you can hold packs to different standards accordingly:

• normative: a formal standard such as the WHATWG URL Standard or an RFC
• official_vendor: a parameter contract the vendor publishes, with the URL
• official_template: vendor-published templates or SDK behavior
• ecosystem_reference: consistent real-world behavior the vendor generates in its own UI but does not document
• heuristic: Pixellint's judgment, labeled as such

The manifest loader refuses to compile a pack that claims official_vendor without citing documentation.

Custom rulepacks

Rulepacks are data, not code. First-party vendor packs are written in the same JSON format you can write for an internal endpoint:

{
  "id": "custom/acme",
  "display_name": "Acme internal pixel",
  "description": "Contract for the internal conversion endpoint.",
  "vendor": "acme",
  "source_level": "heuristic",
  "match": { "hosts": ["px.acme.example"], "path_prefixes": ["/collect"] },
  "params": [
    { "name": "aid", "requirement": "required", "format": { "kind": "integer" } },
    { "name": "ev", "requirement": "required", "format": { "kind": "enum", "values": ["view", "purchase"] } }
  ]
}

pixellint validate url 'https://px.acme.example/collect?ev=purchase' --rulepack-file acme.json

The format is documented in docs/RULEPACK_SCHEMA.md.

What Pixellint does not do

• It does not extract artifacts from documents. Callers such as Vastlint parse VAST, HTML, or GTM containers and hand Pixellint the URLs they found. The planned document-level result model is in docs/MULTI_ARTIFACT_SCHEMA.md.
• It does not fire requests or check whether an endpoint responds.
• It does not enforce privacy or consent frameworks yet.
• It does not auto-fix. Findings carry fix hints; applying them is on you.

Evidence

Every rule is backed by tests: unit tests in crates/pixellint-core/src/, a golden corpus in fixtures/ with one directory per rulepack, and integration tests that drive the real CLI binary and the real MCP stdio transport.

cargo test --workspace

Docs

• Standards and rule inventory
• Rulepack manifest schema
• Architecture
• Roadmap
• Multi-artifact output model

License

Apache-2.0. Pixellint is not affiliated with or endorsed by any vendor named in its rulepacks; see NOTICE.