sdr-grader

A deterministic, rule-based linter for Adobe Customer Journey Analytics (CJA) and Adobe Analytics (AA) implementations. It consumes JSON snapshots from cja_auto_sdr and aa_auto_sdr, evaluates them against a versioned YAML rubric, and produces a self-contained HTML report card plus machine-readable JSON.

File and directory grading make no network requests or Adobe API calls: the same input and rubric always produce the same grade. The convenience modes --dataview and --rsid are different: they launch a child generator, and that child calls Adobe APIs before the local grader runs.

What it grades

sdr-grader ships strict and pragmatic rubric packs. Both cover schema hygiene, naming consistency, segment complexity, calculated metric maintainability, attribution coverage, and governance posture. strict uses tight, master-cert-grade thresholds; pragmatic uses the same rule IDs with looser thresholds and severities.

Bundled pack 2.0 has 27 rule IDs. Its scores are not comparable with pack 1.0, so re-baseline CI thresholds, trends, and leaderboards after upgrading. Every default rule grades data carried by the snapshot. Optional registered checks can use operator-supplied JSON; see Supplementary inputs.

How it grades

1. Adapt the platform snapshot into a normalized implementation.
2. Run rules from the selected rubric pack.
3. Score each weighted category from fired and available severity.
4. Assign a letter using the pack's descending grade-scale bands.

The scoring implementation is pinned with this release at src/sdr_grader/core/grade_calc.py.

First local grade

This auth-free quickstart works from any writable directory after installing Python 3.11 or newer. It grades a tagged synthetic fixture, so you can confirm the installation before using production data or configuring Adobe credentials.

Install the released grader with uv (or use pipx or another isolated Python tool installer):

uv tool install sdr-grader
sdr-grader --version

Download the v1.2.4 synthetic CJA snapshot.

macOS and Linux:

curl -fL -o cja_snapshot_clean.json https://raw.githubusercontent.com/brian-a-au/sdr-grader/v1.2.4/tests/fixtures/cja_snapshot_clean.json

Windows PowerShell:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/brian-a-au/sdr-grader/v1.2.4/tests/fixtures/cja_snapshot_clean.json" -OutFile "cja_snapshot_clean.json"

Grade it with the installed command on macOS, Linux, or Windows:

sdr-grader cja_snapshot_clean.json --output grade.html --json grade.json --quiet

Open the local HTML report:

open grade.html                 # macOS
xdg-open grade.html             # Linux

Start-Process .\grade.html      # Windows PowerShell

Live snapshots have two separate optional prerequisites:

• CJA: install cja_auto_sdr using its Installation instructions, then configure its Adobe credentials. Generate with --include-all-inventory; without the complete CJA inventory, calculated-metric and segment inputs are empty and those rules stay silent.
• AA: install aa_auto_sdr using its Installation instructions, then configure its Adobe credentials. AA includes both inventories by default.

The upstream CJA Component Inventory Overview documents the complete set of --include-* switches.

Using sdr-grader

The following are installed-user workflows. Generate live snapshots only after installing and authenticating the appropriate prerequisite above:

# CJA: include the complete component inventory.
cja_auto_sdr dv_prod_web --include-all-inventory --format json --output snapshot.json

# AA: inventory is included by default.
aa_auto_sdr prod_us --format json --output snapshot.json

# Either platform is auto-detected from the resulting JSON.
sdr-grader snapshot.json --output grade.html --json grade.json

For an installed streaming workflow on macOS, Linux, or Windows shells with pipe support:

cja_auto_sdr dv_prod_web --include-all-inventory --format json --output - | sdr-grader - --output grade.html
aa_auto_sdr prod_us --format json --output - | sdr-grader - --output grade.html

Input modes

One run grades one platform. Keep CJA and AA snapshots in separate directories. Directory history uses only same-platform, same-instance siblings; trend mode rejects mixed-platform or mixed-instance input rather than combining it.

Supplementary inputs

Forked rubrics can read optional JSON from Implementation.supplementary_data. Attach it with repeatable --extra-input KEY=PATH flags; a rule whose key is absent stays silent. The tagged supplementary-input contract defines keys, paths, and failure behavior.

Output

• HTML report card at --output PATH (default grade-{report-id}.html) is a single self-contained file with no external CSS or JavaScript.
• JSON output at --json PATH uses schema 1 and contains stable instance, adapter, rubric, and grader identity plus the complete report model. See the tagged JSON output contract.

HTML color packs

Generated HTML supports exactly four built-in color packs, in this public order: default, ADBE, OMTR, BLUE. Select one for a normal report or a trend report with the case-sensitive --color-pack option:

sdr-grader snapshot.json --color-pack ADBE --output grade.html
sdr-grader snapshots/ --trend --color-pack BLUE --output trend.html

The same choice is available to renderer API callers:

from sdr_grader.render import render
from sdr_grader.trend import render_trend

grade_html = render(report, color_pack="OMTR")
trend_html = render_trend(trend, color_pack="BLUE")

--pack and --color-pack are independent. --pack selects the scoring rubric (strict or pragmatic); --color-pack selects only the presentation palette for generated HTML. It does not enter the report model or separately written JSON, and does not change findings, scoring, grades, or exit codes.

The named palettes use source swatches as design inspiration only. They are not official brand assets, contain no logos, and do not imply affiliation, sponsorship, endorsement, or approval by any company. Reviewed text and essential-graphic color pairs are tested at WCAG contrast thresholds, but color is not the only severity cue: reports retain severity text and bordered structure. Print-specific foreground, background, and border roles are also tested. Every palette remains embedded in the same self-contained HTML, so reports continue to work offline without external CSS or JavaScript.

Rendered examples for this release:

Troubleshooting

Missing generators, Adobe authentication, incomplete inventories, platform detection, directory mixing, compatibility warnings, output paths, and privacy are covered in the tagged troubleshooting guide.

Before sharing an HTML or JSON report, follow the current report-sharing privacy matrix.

Integrating sdr-grader

• CI integration — use --fail-below safely in automation.
• Trend reports — filename conventions and flag interactions.
• Internal leaderboards — build a distribution reference from collected JSON outputs.
• Supplementary inputs — attach repeatable --extra-input KEY=PATH data.
• Claude Code skill — query a grade without rerunning the grader.

Extending sdr-grader

Start with the tagged customization guide, then choose the narrowest extension surface:

• Project configuration — suppressions in .sdr-grader.yaml.
• Rubric format — fork or create a YAML pack.
• Check-function guide — add rule logic.
• Adapter guide — add a platform in a source checkout.

Maintaining sdr-grader

These are source-checkout workflows. Run them from the repository root after cloning the v1.2.4 source tree:

uv sync
uv run pytest
uv run ruff check
uv run python scripts/build_cja_fixtures.py
uv run python scripts/generate_examples.py
uv run python scripts/generate_grade_examples.py
uv run python scripts/generate_trend_example.py

Maintainer references:

• Platform coverage — CJA/AA compatibility evidence and known gaps.
• Calibration corpus — private compatibility and calibration admission.
• Threshold calibration — admitted-cohort status.
• Rubric audit — rule premises against Adobe documentation.
• Release checklist — publication, recovery, and announcement gates.

Community

• Contributing
• Code of Conduct
• Security and privacy
• Issues