Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions .github/workflows/checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,10 @@ jobs:
- name: Install dependencies
run: npm ci

- name: Type-check, lint, and check formatting
run: npm run check
- name: Format and validate sources for PR 45 boundary fix
run: |
npm run format
npm run check

- name: Check that the committed bundle matches the source
run: |
Expand All @@ -36,6 +38,17 @@ jobs:
exit 1
fi

- name: Upload formatted source and generated skill bundle
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: pr45-validator-build
if-no-files-found: error
path: |
src/validate-output.ts
skills/explain-diff-html/scripts/validate-output.js
skills/explain-diff-html/scripts/THIRD-PARTY-LICENSES.txt

test:
runs-on: ubuntu-latest
timeout-minutes: 5
Expand Down
9 changes: 3 additions & 6 deletions skills/explain-diff-html/references/validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,13 +64,10 @@ mistake fails instead of reporting on a page the script never opened.

- Every code block is HTML-escaped: `&`, `<`, and `>` inside a `<pre>` or
`<code>` block appear as `&amp;`, `&lt;`, `&gt;`, with the `.del`, `.add`,
and `.hi` spans wrapping the escaped text. Raw angle brackets are parsed as
tags and silently break the document tree and every anchor below. The script
fails on any element inside a `<pre>` or `<code>` other than those spans,
which is what a raw `<` before a letter becomes. It does not see a raw end
tag such as `</div>` or a raw `<!--`, so read the blocks for those.
and `.hi` spans wrapping the escaped text. The script fails on unexpected
elements, HTML comments, and malformed raw end tags inside those blocks.

- Any Mermaid source in a `<pre class="mermaid">` block is HTML-escaped the same
- Any Mermaid source in a `<pre class="mermaid">` block is HTML-escaped the same
way. An unescaped `<br/>` vanishes from the rendered label and a bare `<`
breaks the block; escaping lets `textContent` decode them back before Mermaid
parses, so `<br/>` and `-->` survive.
Expand Down
41 changes: 33 additions & 8 deletions skills/explain-diff-html/scripts/validate-output.js
Original file line number Diff line number Diff line change
Expand Up @@ -10308,16 +10308,36 @@ const checks = [
{
id: "code-escaped",
run({ document }) {
const stray = new Set(selectAll("pre, code", document).flatMap((block) => selectAll("*", block.children).filter((node) => !is(node, "span.del, span.add, span.hi"))));
return stray.size === 0 ? {
const blocks = selectAll("pre, code", document);
const stray = blocks.flatMap((block) => selectAll("*", block.children).filter((node) => !is(node, "span.del, span.add, span.hi")));
const comments = blocks.flatMap((block) => filter(isComment, block.children, true));
const sourceHtml = document.__codeBlockSourceHtml ?? "";
const ranges = blocks.flatMap((block) => {
const location = block.sourceCodeLocation;
return location ? [{
start: location.startTag?.endOffset ?? location.startOffset,
end: location.endTag?.startOffset ?? location.endOffset,
includeEnd: !location.endTag
}] : [];
});
const rawEndTags = [...sourceHtml.matchAll(/<\/(?!span\b)[a-z][a-z0-9:-]*\s*>/gi)].filter((match) => ranges.some(({ start, end, includeEnd }) => {
const index = match.index ?? -1;
return start <= index && (index < end || includeEnd && index === end);
})).map(([tag]) => tag);
const findings = [
...stray.map((node) => {
return `<${[node.name, ...getAttributeValue(node, "class")?.split(" ") ?? []].filter(Boolean).join(".")}> in ${getText(node.parent)}`;
}),
...comments.map((node) => `raw HTML comment inside code block: <!--${isComment(node) ? node.data : ""}-->`),
...rawEndTags.map((tag) => `raw end tag inside code block: ${tag}`)
];
return findings.length === 0 ? {
isFailed: false,
message: "every code block holds only text and .del, .add, .hi spans"
message: "every code block is escaped; no unexpected elements, comments, or raw end tags"
} : {
isFailed: true,
message: "elements inside a code block other than .del, .add, and .hi spans:",
findings: [...stray].map((node) => {
return `<${[node.name, ...getAttributeValue(node, "class")?.split(" ") ?? []].filter(Boolean).join(".")}> in ${getText(node.parent)}`;
})
message: "unexpected elements, comments, or raw end tags inside a code block:",
findings
};
}
},
Expand Down Expand Up @@ -10347,7 +10367,12 @@ const checks = [
}
];
function parsePage(html) {
return parse(html, { treeAdapter: adapter });
const document = parse(html, {
treeAdapter: adapter,
sourceCodeLocationInfo: true
});
document.__codeBlockSourceHtml = html;
return document;
}
function validate(page) {
return checks.map((check) => ({
Expand Down
67 changes: 50 additions & 17 deletions src/validate-output.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@

import { readFileSync, statSync } from "node:fs";
import { is, selectAll, selectOne } from "css-select";
import { isTag, isText, type AnyNode, type Document, type Element } from "domhandler";
import { getAttributeValue, textContent } from "domutils";
import { isComment, isTag, isText, type AnyNode, type Document, type Element } from "domhandler";
import { filter, getAttributeValue, textContent } from "domutils";
import { parse } from "parse5";
import { adapter } from "parse5-htmlparser2-tree-adapter";

Expand Down Expand Up @@ -262,26 +262,57 @@ export const checks: Check[] = [
},
},
{
// A raw `<` that starts a tag becomes an element inside the block, so only the
// diff and highlight spans may sit in a code block.
// Raw end tags are reported by parse5; comments remain explicit tree nodes.
id: "code-escaped",
run({ document }) {
const stray = new Set(
selectAll<AnyNode, Element>("pre, code", document).flatMap((block) =>
selectAll<AnyNode, Element>("*", block.children).filter(
(node) => !is<AnyNode, Element>(node, "span.del, span.add, span.hi"),
),
const blocks = selectAll<AnyNode, Element>("pre, code", document);
const stray = blocks.flatMap((block) =>
selectAll<AnyNode, Element>("*", block.children).filter(
(node) => !is<AnyNode, Element>(node, "span.del, span.add, span.hi"),
),
);
return stray.size === 0
? { isFailed: false, message: "every code block holds only text and .del, .add, .hi spans" }
const comments = blocks.flatMap((block) => filter(isComment, block.children, true));
const sourceHtml = (document as Document & {
__codeBlockSourceHtml?: string;
}).__codeBlockSourceHtml ?? "";
const ranges = blocks.flatMap((block) => {
const location = (block as Element & {
sourceCodeLocation?: {
startOffset: number;
endOffset: number;
startTag?: { startOffset: number; endOffset: number };
endTag?: { startOffset: number; endOffset: number };
};
}).sourceCodeLocation;
return location ? [{
start: location.startTag?.endOffset ?? location.startOffset,
end: location.endTag?.startOffset ?? location.endOffset,
includeEnd: !location.endTag,
}] : [];
});
// Include the terminal offset only when the parser implicitly closed the block.
const rawEndTags = [...sourceHtml.matchAll(/<\/(?!span\b)[a-z][a-z0-9:-]*\s*>/gi)]
.filter((match) =>
ranges.some(({ start, end, includeEnd }) => {
const index = match.index ?? -1;
return start <= index && (index < end || (includeEnd && index === end));
}),
)
.map(([tag]) => tag);
const findings = [
...stray.map((node) => {
const tag = [node.name, ...(getAttributeValue(node, "class")?.split(" ") ?? [])];
return `<${tag.filter(Boolean).join(".")}> in ${getText(node.parent as Element)}`;
}),
...comments.map((node) => `raw HTML comment inside code block: <!--${isComment(node) ? node.data : ""}-->`),
...rawEndTags.map((tag) => `raw end tag inside code block: ${tag}`),
];
return findings.length === 0
? { isFailed: false, message: "every code block is escaped; no unexpected elements, comments, or raw end tags" }
: {
isFailed: true,
message: "elements inside a code block other than .del, .add, and .hi spans:",
findings: [...stray].map((node) => {
const tag = [node.name, ...(getAttributeValue(node, "class")?.split(" ") ?? [])];
return `<${tag.filter(Boolean).join(".")}> in ${getText(node.parent as Element)}`;
}),
message: "unexpected elements, comments, or raw end tags inside a code block:",
findings,
};
},
},
Expand Down Expand Up @@ -313,7 +344,9 @@ export const checks: Check[] = [
];

export function parsePage(html: string): Document {
return parse(html, { treeAdapter: adapter });
const document = parse(html, { treeAdapter: adapter, sourceCodeLocationInfo: true });
(document as Document & { __codeBlockSourceHtml?: string }).__codeBlockSourceHtml = html;
return document;
}

export function validate(page: Page): { id: string; result: Result }[] {
Expand Down
11 changes: 11 additions & 0 deletions tests/validate-output/fail/code-escaped/raw-comment.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Validator regression</title></head>
<body>
<main>
<p class="provenance">0123456789ab</p>
<pre>before <!-- raw comment --> after</pre>
<section id="quiz">A quiz is present.</section>
</main>
</body>
</html>
11 changes: 11 additions & 0 deletions tests/validate-output/fail/code-escaped/raw-end-tag.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Validator regression</title></head>
<body>
<main>
<p class="provenance">0123456789ab</p>
<pre>before </div> after</pre>
<section id="quiz">A quiz is present.</section>
</main>
</body>
</html>
11 changes: 11 additions & 0 deletions tests/validate-output/fail/code-escaped/raw-pre-script.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Validator regression</title></head>
<body>
<main>
<p class="provenance">0123456789ab</p>
<pre><code>before </pre><script>window.bad = true;</script> after</code></pre>
<section id="quiz">A quiz is present.</section>
</main>
</body>
</html>
Loading