Migrating from 2.0 to 2.1
Every breaking change of auditmysite 2.1 in one table: old, new, report-lint code and the reason.
auditmysite 2.1 deliberately carries breaking changes inside the 2.x line. There is no 3.0: the tool
is young and its consumers are few, so the breaks ship in a minor release instead of waiting for a
major one. Under strict SemVer that is a deviation, which is why this page lists every one of them.
The changelog has the same entries under ### Breaking in the
2.1.0 section; the contract behind
them is the output contract
and the JSON schemas in docs/. The changes of 2.0 itself are in Migrating to 2.0.
How to find what still reads the old shape
Run auditmysite-dev report-lint <JSON_FILE> on a report your tooling consumes (the command moved
out of auditmysite, see the table). Only a few changes have a lint check of their own; they are
named in the table. For the rest, validate your consumers against docs/json-report.schema.json and
docs/json-batch-report.schema.json: schema_version is 2.2 (2.0 for 2.0.x reports; the technician
index is 1.1).
Stored snapshots and cache entries written by 2.0 are cache misses; nothing needs to be deleted.
Migration table
“report-lint code” names the check id that report-lint raises for the change. “contract code” is a
code of the report validation (ReportContractError, listed in the output contract under
“Validation codes”). A dash means neither exists for this change. Entries are in the order of the
changelog.
CLI
| Old | New | report-lint code | Reason |
|---|---|---|---|
auditmysite URL wrote a PDF, a JSON report and the screen-reader sidecar into the working directory, asked for the request mode and a sitemap, and reported in German |
It prints a table, exits with the verdict and writes nothing. -o report.json or -o report.pdf writes a report (the format follows the extension), -f pdf alone writes <domain>-<date>-single-report.pdf with its JSON. --screen-reader-report is opt-in and replaces --no-screen-reader-report; --lang defaults to en; no prompt in an audit run (#910) |
- | A default run that fills the directory and asks questions does not fit scripts or CI. |
auditmysite report-lint, plan, replay, accname-diff; --debug-typ, --export-snapshot |
auditmysite-dev <command> (cargo run --features dev-tools --bin auditmysite-dev -- <command>); in auditmysite they fail as unknown arguments (#912) |
- | Maintainer tooling is not part of the installed binary. |
--performance, --seo, --security, --mobile, --html-conform, --stack, --skip-performance, --skip-mobile, --force-refresh, --no-sitemap-suggest, --detect-chrome, --technician |
--modules performance,seo,security,mobile,html-conform,stack (a11y alone runs the WCAG rules only); a fresh measurement is the default and --reuse-cache is the cache switch; --prefer-sitemap stays; auditmysite browser detect; --per-page-reports -f json --modules seo,html-conform -o <dir> replaces --technician. The old flags fail as unknown arguments (#913) |
- | One list instead of paired and macro flags; --full stays as the explicit spelling of the default. |
--design-quality, --ai-transparency, --dns-check |
Removed with their modules, findings and PDF chapters; they fail as unknown arguments (#915) | - | See “Opt-in checks” below. |
Modules and indicators
| Old | New | report-lint code | Reason |
|---|---|---|---|
UX, Journey, AI Visibility, Content Visibility, Source Quality and Commerce computed in every run; detail.modules.{ux,journey,source_quality,ai_visibility,content_visibility,commerce}, pages[].ux_score, pages[].journey_score, summary.ux_score, summary.journey_score, summary.commerce |
Computed only with --experimental <name>[,<name>] and then reported in one pages[].experimental block (a batch: summary.experimental); the listed keys are removed. The PDF has no chapter for them (#916) |
- | Unvalidated heuristics with weight 0 do not belong in the default run. |
detail.modules.design_quality, .ai_transparency, .network_dns, their findings and the finding domains of the same names |
Removed, with the dns collection method and the design_quality signal contract (#915) |
- | Opt-in checks with no validated basis; about 130 transitive crates go with them. |
detail.modules.tech_stack with findings, score, grade, audited_stacks; tech_stack findings; probes of /wp-admin/, /xmlrpc.php and others |
detail.modules.tech_stack holds only detected; --stack reads CMS and frameworks from in-page signals and sends no request of its own (#914) |
- | An audit must not probe the audited host for admin endpoints. |
detail.modules.dark_mode, the Dark Mode score entry, dark_mode.* findings, finding.domain: "dark_mode" |
Removed; the contrast check under dark emulation lives on in the contrast/* rules (#917) |
- | Design-choice indicators with weight 0; the contrast part is a real WCAG check. |
JSON, summary feed, SARIF
| Old | New | report-lint code | Reason |
|---|---|---|---|
overall_score (summary, pages[]; single and batch; Studio contract, technician index, -f ai), overall_score_weight_basis, overall_score_weight_basis_uniform, module_scores[].contributes_to_overall, viewport_scores.{desktop,mobile}.overall, viewport_scores.weighted_overall, score_breakdown.{desktop,mobile,viewport_blended}_overall, summary feed overallScore |
site_quality_score, site_quality_score_weight_basis, site_quality_score_weight_basis_uniform, module_scores[].contributes_to_site_quality_score, .site_quality, weighted_site_quality, ..._site_quality, siteQualityScore; schema_version 2.1 (#909) |
contract code overall_score is now site_quality_score |
The mixed score is named “site quality (optional modules)” everywhere, so it is no longer read as the accessibility result. Full key table: output contract. |
summary.accessibility_score_breakdown[].score, pages[].detail.accessibility_subcategory_scores |
Removed; read estimated_lost_points and weight_pct of the breakdown (100 - sum(estimated_lost_points) = accessibility_score); schema_version 2.2 (#902) |
accessibility_breakdown_reconciles_with_score |
The components now add up to the headline. Key table: output contract. |
decision.certificate (very_good … not_passed) in the JSON report, batch report, summary feed and Studio response; auditmysite.decision/2 |
Removed (auditmysite.decision/3); read decision.verdict for the outcome and summary.grade or accessibility_score for the band (#896) |
certificate_matches_accessibility_score removed; pdf_certificate_traceable_to_json is now pdf_score_traceable_to_json; contract code certificate removed |
A partial automated check that reports conformance: not_determined cannot issue anything that reads as a certificate. |
SARIF artifactLocation.uri (the page URL) |
A relative pseudo-path audited-pages/<host>/<path>; the page URL moves to run.artifacts and properties.pageUrl, the element is a logical location, and partialFingerprints and defaultConfiguration are new (#977) |
- | A page URL is not a file in the repository, and GitHub Code Scanning needs stable locations. |
help_url (SARIF helpUri) pointing to the W3C Understanding page |
help_url is the project’s rule page https://casoon.github.io/auditmysite/rules/<rule_id>/; the W3C page moves to understanding_url. Stored snapshots are cache misses (#929) |
- | Every rule has its own documentation page. |
findings[].rule_id, aggregation_key, id, related_rule, maps_to_finding, SARIF ruleId as a11y.* ids (a11y.alt_text.missing) |
The engine rule id (images/alt-missing, contrast/text-insufficient); rules that shared one taxonomy entry are separate findings now (forms/label-missing, forms/placeholder-as-label). Scores do not move (#918) |
- | One rule catalogue, one id. SARIF partialFingerprints change once because the rule id is part of them. |
risk.legal_flags counting only High and Critical findings |
Counts every legally relevant finding (BFSG/EAA relevance high or medium); severe_legal_flags (High or Critical) is new and drives verdict, risk score and risk level (#952) |
- | One definition, so a card cannot say “0 findings with possible legal relevance” next to a Medium 1.4.3 finding. A number a failing verdict names can be higher than before; the verdict itself does not change. |
risk.legal_flags covering WCAG Level A only |
Level A and AA (High/Critical, confirmed, covered by EN 301 549): a High contrast failure (1.4.3) is a legal flag, so such pages can reach a higher risk level or a failing verdict, and exit code (#922) | - | Level AA is what the law and EN 301 549 require. |
en301549_annex.standard_version EN 301 549 V3.2.1 (2021-03), 50 clauses, WCAG 2.2 criteria “outside the standard” with bfsg_relevance low |
EN 301 549 V4.1.1 (2026-09), 55 clauses, mapping_version 2; WCAG 2.2 A/AA findings get medium or high, and a confirmed High one (for example 3.3.8) is a legal flag; the retired 9.4.1.1 is dropped (#923) |
- | V4.1.1 is the edition that requires WCAG 2.2 A/AA. |
summary.failed_url_count as the only count of pages that did not pass |
summary.fail_url_count (verdict fail) and summary.warn_url_count (verdict warn) are new; failed_url_count stays as a deprecated alias (verdict not pass). The batch decision reason N URLs failed quality threshold reads N URL(s) failed its/their own check and N URL(s) with a warning, each only above zero (#899) |
- | Not marked “Breaking” in the changelog, because nothing is removed; a consumer that matches the old reason string must read the counts instead. |
Rules and report
| Old | New | report-lint code | Reason |
|---|---|---|---|
Rule ids pointer-cancellation (2.5.2), meta-refresh (2.2.1 note), timeouts (2.2.6), visual-presentation (1.4.8); library check_*_with_page functions of these notes |
manual/pointer-cancellation and manual/timing, which appear only where the criterion applies (a down-event handler attribute; form fields); the two AAA notes are removed without a replacement. timing/meta-refresh is unchanged (#1114) |
- | Unconditional hint-only notes said nothing about the page. A baseline reads the old finding ids as fixed (FINDING_ID_SCHEME stays 1); a [rules] filter on pointer-cancellation or meta-refresh keeps hitting the successor, one on timeouts or visual-presentation matches nothing. |
Page rules frame-tested, css-orientation-lock, text-spacing, focus-not-obscured-minimum, focus-not-obscured-enhanced, accessible-auth-paste-blocked |
Shared rules frames/cross-origin, orientation/root-rotated, text-spacing/clipped, focus/obscured, focus/obscured-enhanced, auth/paste-blocked, measured on the running page; a measurement that did not come back is capability_missing, never a pass (#1002–#1006) |
- | One source in a11y-rules. The old ids in [rules] filters keep working; finding ids change, so a baseline reads the old ones as fixed. |
| Accessibility callout of the management page with per-area sub-scores | Lists the points lost per area and states the arithmetic (100 − 7 = 93) (#902) |
accessibility_breakdown_reconciles_with_score fails a breakdown that does not sum to 100 - accessibility_score or whose component carries its own score |
The sub-scores did not add up to the headline. |
The explanation texts of a finding read from fields and accessors of output::explanations::RuleExplanation |
Fluent messages: methods customer_title(en), customer_description(en), user_impact(en), typical_cause(en), recommendation(en), technical_note(en) return a String; the struct carries its table key in key; explanation_text_key(key) returns rule-<id> for a key that is a rule id, and RuleExplanation::customer_title(en) of such an entry returns the rule’s title (#935) |
- | One text registry per rule id. No wording changed except the finding titles listed under “Changed” in the changelog. |
taxonomy::Rule fields title, title_en, description, user_impact, user_impact_en, technical_impact, technical_impact_en |
Rule::title(en), Rule::user_impact(en), Rule::technical_impact(en); description is gone without a replacement (#935) |
- | The texts moved into Fluent; nothing read description. |
Library
The library has a declared surface since 2.1: the CLI, the JSON report and the items in the
library reference are stable, every other
pub item is not. The JSON output is unchanged by every row below.
| Old | New | report-lint code | Reason |
|---|---|---|---|
PipelineConfig fields check_performance, check_seo, check_security, check_mobile, check_html_conform, check_stack, check_privacy, full_audit; a struct literal of PipelineConfig; Args fields performance, seo, … technician and apply_technician_preset; Args::no_screen_reader_report |
config.modules: ModuleSet (config.modules.contains(Module::Seo), config.modules.with(Module::Seo)), PipelineConfig::is_full_audit, PipelineConfig::default() plus the setters with_wcag_level, with_modules, with_experimental, with_interactive; Args::modules: Vec<ModuleChoice>, Args::module_enabled, Args::screen_reader_report; PipelineConfig::experimental and AuditReport::experimental are new (#933, #913, #916, #910) |
- | PipelineConfig is #[non_exhaustive], so a new field is no longer a break. JSON: full_audit is true whenever all six modules run, also when --modules lists them. |
Args fields debug_typ, export_snapshot; the Command variants plan, replay, accname-diff, report-lint; ReportLintFailOn and lint::lint |
Args.dev: DevOptions (never set by auditmysite), ReportLintFailOn in cli::report_lint, entry cli::report_lint::run_report_lint (#912) |
- | The maintainer tooling lives in auditmysite-dev. |
PipelineConfig::check_design_quality, check_ai_transparency, check_dns, check_dark_mode; AuditReport.experience module fields of the removed modules; dark_mode::*, AuditReport::with_dark_mode, ModuleData::DarkMode; the ai-transparency Cargo feature |
Removed (#915, #917) | - | The modules are gone. |
NormalizedReport::overall_score, ModuleScoreEntry::contributes_to_overall, ViewportScoreSet::overall, ViewportScores::weighted_overall; Studio types StudioAuditResponse, StudioModuleScore, StudioHistoryEntry fields with the old names |
The site_quality counterparts, as in the JSON row above (#909) |
contract code overall_score is now site_quality_score |
The rename follows the JSON. |
output::terminal::render_single_report, render_single_report_for, render_batch_report taking &Args; BudgetConfig in cli::config |
Take &TerminalOptions (TerminalOptions::from(&args) or TerminalOptions::default()); BudgetConfig lives in audit::budget and is still re-exported from cli::config (#934) |
- | Lower layers no longer import the CLI arguments. |
auditmysite::journey::*; screen_reader::bfsg, map_to_bfsg, wcag_21_aa_criteria, BfsgMapping |
auditmysite::page_flow::* (the crate-root re-exports analyze_journey, analyze_journey_with_dom_check, JourneyAnalysis, PageIntent are unchanged); wcag::en301549::EN301549_WEB_CLAUSES (#938) |
- | The name journey belongs to the interactive layer. |
Label and text functions that returned &'static str: seo::BotClass::label(en), seo::schema::schema_issue_label, security::SecurityCategory, seo::profile::{SeoMaturityLevel, PageType}, seo::SerpSignalStatus, page_flow::PageIntent, audit::prioritization::{Priority, Effort, ExecutionPriority}, output::report_model::Role, taxonomy::{IssueClass, Subcategory}, taxonomy::ScoreArea::localized_label, seo::schema_fit, seo::schema_parity, seo::page_health text functions, EvidenceSource::label, seo::schema_rules::{feature_label, status_text, manual_review_text}, audit::batch_consistency::help_region_name |
Return a String, because the texts now come from Fluent. Effort::label(en) reads “Low effort” / “Structural”, Role::label(true) reads “Editorial” and “Project Management”; Effort::short_label(en) is new (#936, #937) |
- | One text source per message. Take .as_str() or an owned String. |
auditmysite::assessment, commerce, html_conform, tech_stack, display, i18n, lint, util as pub modules; util::build_browser_client, util::truncate_url, lint::lint; analyze_html_conform, analyze_tech_stack, HtmlConformModule, TechStackModule |
pub(crate). The types stay at the crate root (AssessmentLevel, ContentArea, HtmlConformAnalysis, TechStackAnalysis, TechConfidence, AuditedDisplayMode, DisplayMode, DisplayModesInfo, VisualisationCount, I18n, …); cli::build_browser_client, cli::truncate_url, cli::report_lint::run_report_lint. Nineteen further modules (a11y_journey, accessibility, ai_visibility, annotations, best_practices, content_visibility, interaction, page_flow, patterns, performance, privacy, registry, screen_reader, security, seo, source_quality, taxonomy, ux, wcag) stay pub but are #[doc(hidden)] and may change in any release (#940) |
- | The library has a declared surface; cargo test --test library_surface guards it. |
Exhaustive construction and matching of AuditReport, BatchReport, NormalizedReport, NormalizedFinding, VerdictResult, Violation, WcagResults, the audit types their fields name, Verdict, AuditError, InteractiveMode, ReportLevel, AnnexKind, ExperimentalIndicator |
#[non_exhaustive]: build with AuditReport::new, BatchReport::from_reports, BatchError::new, SampleMetadata::new, SampleStratum::new, PerformanceResults::new or Default plus field assignment; a match on one of the enums needs a wildcard arm. WcagLevel, ColorPolicy, Severity stay exhaustive; Verdict::exit_code and Verdict::label are the stable mapping (#940) |
- | A new field or variant is no longer a breaking change. |
output::report_model::FindingGroup copying rule_id, finding_id, wcag_criterion, wcag_level, help_url, dimension, subcategory, issue_class, severity, confidence, false_positive_risk, verification, complexity, complexity_reason, complexity_kind, expected_impact, expected_impact_kind, bfsg_relevance, remediation_priority, occurrence_count, affected_elements; audit::normalized::BatchFinding |
FindingGroup::finding (the NormalizedFinding; finding_id is finding.id, help_url is finding.understanding_url, affected_elements is finding.occurrence_count); aggregate_batch_findings returns (NormalizedFinding, Vec<String>) pairs (#937) |
- | A view model that copies the finding can disagree with it. |
NormalizedFinding::category as a field; the validation code finding_domain |
NormalizedFinding::category(), derived from contract.domain; the code finding_domain is gone from audit::CONTRACT_CODES. Reading a finding back rejects a category that names another domain (#937) |
- | The two cannot disagree any more. |
Reading a finding back (cache, replay, Deserialize) accepting any rule_id and aggregation_key; Interpretation::per_module as a HashMap |
Rejects a rule_id its contract does not name and an aggregation_key other than the rule_id (the tool never writes either); per_module is a BTreeMap, so a serialized report lists the modules in key order (#937) |
- | Reproducible serialization; contradictory data is refused at the boundary. |
output::report_model::ActionItem struct literals |
New field affected_urls (the audited pages an action reaches; empty in the single-page report); security::SecurityIssueKind::from_stored is new (#1039) |
- | A batch action names the pages it reaches. |
Related
- Migrating to 2.0
- Output contract, including the decision contract and the validation codes.
- CLI and output contract for
report-lintand the output formats.