AFDocs: add Web Documentation Delivery Spec v0.6 checks - #747
rachaelrenk wants to merge 1 commit into
Conversation
Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR expands the AFDocs audit wrapper and skill guidance for Web Documentation Delivery Spec v0.6, including compatibility probes, reporting fields, partial-scan handling, and report-contract tests.
Concerns
- Valid
Link: rel="next"pagination is always marked fragile because header continuations are assigned a body position at EOF. - The embedded-data serialization probe misses rendered code/data blocks because it searches stripped HTML text for markdown fences.
- The embedded-data serialization probe analyzes challenge/error HTML bodies instead of only successful documentation pages, which can turn bot-protected partial scans into misleading content findings.
- Tests cover report assembly only; they do not exercise the new probe logic for pagination, markdown link portability, bot protection, or embedded data detection.
Verdict
Found: 0 critical, 3 important, 1 suggestions
Request changes
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| const signals = []; | ||
| const linkHeader = headers.link || ''; | ||
| const headerMatch = linkHeader.match(/<([^>]+)>;\s*rel="?next"?/i); | ||
| if (headerMatch) signals.push({ href: headerMatch[1], position: markdown.length, source: 'Link header' }); |
There was a problem hiding this comment.
Link header continuations are currently recorded at markdown.length, so an absolute working rel="next" header always fails the nearTop check and is reported as fragile. Treat headers as top-of-response instead.
| if (headerMatch) signals.push({ href: headerMatch[1], position: markdown.length, source: 'Link header' }); | |
| if (headerMatch) signals.push({ href: headerMatch[1], position: 0, source: 'Link header' }); |
| const text = htmlToText(table); | ||
| if (rows >= 25) elements.push({ type: 'table', rows, characters: text.length }); | ||
| } | ||
| for (const block of content.match(/```(?:json|ya?ml|csv)?[\s\S]{1024,}?```/gi) || []) { |
There was a problem hiding this comment.
htmlToText() has stripped the page markup, so rendered <pre><code> data examples no longer have markdown fences and the data block branch misses the large code/data blocks this check is meant to attribute. Inspect code blocks in the HTML before stripping tags, or run this part against the markdown response.
| } | ||
|
|
||
| function assessEmbeddedDataSerialization(samples) { | ||
| const analyses = samples |
There was a problem hiding this comment.
sample.html.body regardless of status, so 403/429 challenge pages or other error bodies can produce embedded-data results for interstitials instead of documentation content. Filter to successful, non-challenge HTML responses before calling bulkElements.
| message: 'Converted content is too large', | ||
| }; | ||
|
|
||
| test('creates a transparent v0.6 compatibility report when the CLI has 23 checks', () => { |
There was a problem hiding this comment.
💡 [SUGGESTION] The tests only cover buildReport; none of the new compatibility probes are exercised, so cases like Link header pagination, challenge responses, .md link content types, and embedded data detection can regress without failing tests. Add unit coverage for the pure probe helpers or inject sample responses into runV06CompatibilityChecks.
1 participant
Summary
Validation
node --test .agents/skills/afdocs-audit/scripts/afdocs_audit.test.mjsnode --check .agents/skills/afdocs-audit/scripts/afdocs_audit.mjsgit diff --checknpm run lint -- …could not run becausetrunkis not installed in the worktree.Operational context
The compatibility scan detected challenge pages during sustained automated documentation fetching. The workflow now reports this as a partial scan rather than publishing a misleading regression baseline.
Warp conversation
Co-Authored-By: Warp agent@warp.dev