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.

These instructions match this source version. For the published package, use the documentation linked from the latest release. Version-pinned links and examples become available when that version is released.

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.

Public preview scope

This project is in public preview. A grade is a review aid, not certification. The bundled thresholds and severities reflect maintainer judgment, and no implementation has been admitted to grading calibration yet. Review each finding against the source implementation before you change a production configuration.

The default packs run 27 checks for AA and 27 for CJA, from a shared catalog of 31. The checks read configuration only, so they do not confirm runtime event-ID delivery or product binding. The report marks any check it could not assess. Component-scoped suppression (components: in .sdr-grader.yaml) is recorded but not applied. See the platform coverage guide for the full check list.

The tool is verified on Ubuntu with Python 3.11 through 3.14. Other platforms and later Python versions are not yet verified. The package installs on Python 3.11 or newer.

See what the rubric marks healthy. Review what to fix.

21-second loop · Actual report excerpts from independent synthetic snapshots. Click the animation for a still image. Explore the complete synthetic CJA report with no findings, diagnostic CJA report, or synthetic AA report with no findings.

What it grades

sdr-grader checks schema hygiene, naming consistency, segment complexity, calculated metric maintainability, attribution coverage, and governance posture. Choose strict for tighter thresholds or pragmatic for the same checks with more forgiving thresholds and severities.

Rules assess the data in your snapshot. Unresolved references stay visible in the report. A reference from a calculated metric to a segment is not scored when it is explicitly typed, because the snapshot alone cannot establish whether the segment is available or valid. This also leaves genuinely invalid references of that kind unscored. Other reference penalties still apply. See the reference grading policy for eligibility and diagnostic details.

Optional checks can use operator-supplied JSON alongside the snapshot; 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.

Penalties apply per failed rule, so removing some entries from a mixed finding may leave its score unchanged. For consistent trends and comparisons, regrade historical snapshots with the same package and rubric, and review CI thresholds when upgrading. See the scoring implementation for details.

First local grade

This auth-free quickstart grades a tagged synthetic fixture, so you can confirm the installation before using production data or configuring Adobe credentials. It requires Python 3.11 or newer. The commands are verified on Ubuntu with Python 3.11 through 3.14; the macOS path has historical local exercise on Python 3.12, and the Windows commands are unverified guidance.

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.7.0 synthetic CJA snapshot.

macOS and Linux:

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

Windows PowerShell (unverified guidance):

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

Grade it with the installed command (Windows use is unverified):

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 shells with pipe support (Windows is unverified guidance):

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.

Snapshot JSON must have unique keys within each object, including nested objects. Duplicate keys are rejected before grading instead of silently keeping the last value. This applies to files, stdin, and child-generator output. It also applies to definitions, tag lists, and reference lists that a snapshot stores as JSON-encoded strings. Repeated keys in separate objects are valid. Files and stdin are read as UTF-8, with or without a byte order mark, whatever the terminal's locale. Invalid selected snapshots and trend inputs exit 1 and preserve existing reports; malformed optional history siblings are ignored and do not count as history evidence.

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. AA has extra checks that read admin evidence supplied this way. See the AA administration input guide. 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 from the latest published 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.7.0 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