feat: stable codes on every finding (2.1.0)#45
Merged
Conversation
Every AuditFinding now carries a `code` namespaced as <factor-id>.<check>[.<variant>] (e.g. technical-seo.h1.multiple), so agents and integrations key on a stable machine identifier instead of regex-matching the human message (which can change between releases). 212 codes across all 19 analyzers; the registry is in docs/finding-codes.md. `code` is required on AuditFinding, so the compiler guarantees coverage, and a test enforces the convention and global uniqueness. hasMissingMetaDescription (the --require-meta gate) now keys on the technical-seo.meta-description.missing code rather than a message prefix — the first consumer migrated to codes. schemaVersion bumped to 1.1 (additive: findings gained the code field). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The api.md runSitemapAudit example printed '1.0', but SCHEMA_VERSION was bumped to '1.1' in 2.1.0. Align the doc with the actual value. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
arberx
added a commit
that referenced
this pull request
Jun 4, 2026
* feat: surface critical per-page defects, make audit output agent-native (2.0.0) Resolves #42. Binary structural defects (an H1 count other than one, a missing <title>, a missing meta description) were detected per page but lost in sitemap aggregation: prioritizedFixes ranked by prevalence only, the factor score averaged them away to a passing grade, and crossCuttingIssues was keyed by factor. A homepage split across four H1s appeared nowhere in the summary. - Detect critical defects straight from the DOM, independent of scoring, so no existing score, grade, or exit code changes. New criticalDefects rollup on sitemap/static reports plus a Critical Defects section in the text and markdown output, grouped by defect with every affected page named (homepage and high sitemap-priority pages first). Shown even with --top-issues. - Make the output agent-native: prioritizedFixes is now a structured PrioritizedFix[] (stable id, kind, severity, full affectedPages, affectsHomepage, prevalencePct, summary) instead of prose strings, and every report carries a schemaVersion so parsers detect shape drift. - No truncation in the end-of-report sections: every issue and every affected page is listed. BREAKING CHANGE: SitemapAuditReport.prioritizedFixes is now PrioritizedFix[] (read .summary for the previous one-liner); reports gain a required schemaVersion field. Bumped to 2.0.0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat: add --format agent, a slim agent-native decision output Returns { schemaVersion, tool, mode, url, score, grade, pass, criticalDefectCount, issues } as JSON, where issues is the ranked PrioritizedFix[] and the per-factor/per-page detail is omitted, so an agent can act on the decision without averaging and re-ranking scores. Single-page reuses the sitemap critical-defect and cross-cutting aggregation over a one-page site; --detect-platform falls back to JSON. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat: stable codes on every finding (2.1.0) (#45) * feat: add stable codes to every finding (2.1.0) Every AuditFinding now carries a `code` namespaced as <factor-id>.<check>[.<variant>] (e.g. technical-seo.h1.multiple), so agents and integrations key on a stable machine identifier instead of regex-matching the human message (which can change between releases). 212 codes across all 19 analyzers; the registry is in docs/finding-codes.md. `code` is required on AuditFinding, so the compiler guarantees coverage, and a test enforces the convention and global uniqueness. hasMissingMetaDescription (the --require-meta gate) now keys on the technical-seo.meta-description.missing code rather than a message prefix — the first consumer migrated to codes. schemaVersion bumped to 1.1 (additive: findings gained the code field). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: correct schemaVersion example value to 1.1 The api.md runSitemapAudit example printed '1.0', but SCHEMA_VERSION was bumped to '1.1' in 2.1.0. Align the doc with the actual value. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * fix: cross-cutting reach unions all recommendations, not just the top buildPrioritizedFixes derived a cross-cutting fix's affectedPages, prevalencePct, and affectsHomepage from only the top recommendation's affectedUrls. The entry is identified by the factor (factorId / factorName), so its reach must cover the whole factor: a homepage hit only by a secondary recommendation read as affectsHomepage=false, and prevalence undercounted. Union every recommendation's pages instead, sorted homepage-first, so the three fields stay consistent and factor-level. Adds a regression test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #44 (base
arberx/aeo-audit-issue-42). EveryAuditFindingnow carries a stablecodenamespaced as<factor-id>.<check>[.<variant>](e.g.technical-seo.h1.multiple,schema-validity.singleton.duplicate), so agents and integrations key on a machine identifier instead of regex-matching the humanmessage. There are 212 codes across all 19 analyzers (full registry indocs/finding-codes.md);codeis required on the type so the compiler guarantees coverage, andtest/finding-codes.test.tsenforces the convention and global uniqueness. The edits are purely additive — verified at the word level (212code:insertions, nothing removed), and all analyzer tests (which assert exact messages and scores) still pass, so behavior is unchanged. As the first consumer migrated to codes,hasMissingMetaDescription(the--require-metagate) now keys ontechnical-seo.meta-description.missing;schemaVersionis bumped to1.1(additive) and the package to2.1.0.🤖 Generated with Claude Code