feat: critical per-page defects, agent-native audit output (2.0.0)#44
Merged
Conversation
…ve (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>
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: 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>
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>
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.
Resolves #42: binary structural defects (an H1 count other than one, a missing
<title>or meta description) were detected per page but lost in sitemap aggregation, so a homepage split across four H1s surfaced nowhere in the summary. This adds acriticalDefectsrollup and a Critical Defects report section that surface them by impact (offending pages named, homepage first) regardless of prevalence, detected independently of scoring so no existing scores, grades, or exit codes change. To make the output agent-consumable,prioritizedFixesis now a structuredPrioritizedFix[](stableid/kind, full untruncatedaffectedPages, humansummary) and every report carries aschemaVersion. This is a breaking change (2.0.0) with docs ported intodocs/cli.mdanddocs/api.md, CHANGELOG and SKILL updated, and typecheck, 270 tests, lint, and e2e all passing.🤖 Generated with Claude Code