Skip to content

Commit 37736dd

Browse files
refactor(html): export the XML well-formed text check as a public helper
`isXmlWellFormedText` replaces the private `_isXmlWellFormedText` export, and AGENTS.md now forbids private exports in every file of the project, testing being the only exception. Claude-Session: https://claude.ai/code/session_01Bqhj38umy4coKMvXQT28NV
1 parent 88cfa9f commit 37736dd

5 files changed

Lines changed: 25 additions & 8 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ Path-shape regexps and their helpers live in `lib/util/identifier.js`: **import
111111

112112
> [!REQUIRED]
113113
114-
**Never add a `_`-prefixed export** (`module.exports._foo`), in a `syntax-parser.js` or anywhere in `lib/`, to share an internal helper with a sibling file: every export is reachable from the package, so other developers come to depend on it and it can't change freely. Keep the helper in the one file that uses it, or move the logic so one file owns it. The exception is a helper useful in its own right, exported under a public name with full JSDoc, as the HTML and CSS `escape*` / `decode*` helpers are.
114+
**Never add a `_`-prefixed export** (`module.exports._foo`) to any file in the project to share an internal helper with another file: every export is reachable, so other developers come to depend on it and it can't change freely. Keep the helper in the one file that uses it, or move the logic so one file owns it; a helper useful in its own right is exported under a public name with full JSDoc instead, as the HTML and CSS `escape*` / `decode*` helpers are. **The only exception is testing**: a private export a test needs to reach code no public entry point can.
115115

116116
### Don't enumerate module or source types
117117

‎lib/html/syntax-parser.js‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6529,12 +6529,16 @@ const escapeXmlText = (data) =>
65296529
.replace(/\r/g, "
");
65306530

65316531
/**
6532-
* Whether source text may be written back as it stands: every `&` in it opens
6533-
* a reference and no `<` sits in it, so a strict parser reads what it says.
6532+
* Whether XML text or an attribute value, as written in its source, may be
6533+
* written back unchanged: no `<` and every `&` opening a reference (§4.1).
6534+
* @example
6535+
* isXmlWellFormedText("a &amp; b"); // true
6536+
* isXmlWellFormedText("&undeclared;"); // true: a reference, declared or not
6537+
* isXmlWellFormedText("a & b"); // false: a strict parser refuses the bare `&`
65346538
* @param {string} raw the text or attribute value as written
65356539
* @returns {boolean} true when it is well-formed as written
65366540
*/
6537-
const _isXmlWellFormedText = (raw) =>
6541+
const isXmlWellFormedText = (raw) =>
65386542
!raw.includes("<") && !XML_BARE_AMPERSAND_REGEXP.test(raw);
65396543

65406544
/**
@@ -13391,7 +13395,7 @@ const _xmlOpenTag = (path, minify) => {
1339113395
_attrValues[i] === null &&
1339213396
valueStart > 0 &&
1339313397
raw.length < value.length &&
13394-
_isXmlWellFormedText(raw)
13398+
isXmlWellFormedText(raw)
1339513399
) {
1339613400
const written = _htmlSource.charAt(valueStart - 1);
1339713401
if (written === '"' || written === "'") {
@@ -15793,11 +15797,11 @@ module.exports.escapeAttribute = escapeAttribute;
1579315797
module.exports.escapeText = escapeText;
1579415798
module.exports.escapeXmlAttribute = escapeXmlAttribute;
1579515799
module.exports.escapeXmlText = escapeXmlText;
15796-
module.exports._isXmlWellFormedText = _isXmlWellFormedText;
1579715800
module.exports.grammar = grammar;
1579815801
module.exports.isAllAsciiWhitespace = isAllAsciiWhitespace;
1579915802
module.exports.isAsciiAlphanumeric = isAsciiAlphanumeric;
1580015803
module.exports.isAsciiWhitespace = isAsciiWhitespace;
15804+
module.exports.isXmlWellFormedText = isXmlWellFormedText;
1580115805
module.exports.metaTag = metaTag;
1580215806
module.exports.parseCssUrls = parseCssUrls;
1580315807
module.exports.parseHtml = parseHtml;

‎lib/html/syntax-printer.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,6 @@ const {
5151
_isRemovableEmptyAttribute,
5252
_isRemovableEmptyElement,
5353
_isSvgRoot,
54-
_isXmlWellFormedText,
5554
_keepComment,
5655
_minifyOpenTag,
5756
_namespaceOf,
@@ -80,6 +79,7 @@ const {
8079
escapeXmlText,
8180
isAllAsciiWhitespace,
8281
isAsciiAlphanumeric,
82+
isXmlWellFormedText,
8383
startsWithAsciiWhitespace,
8484
stripAsciiWhitespace
8585
} = require("./syntax-parser");
@@ -342,7 +342,7 @@ const _printXml = (path, writer, minify) => {
342342
}
343343
// The source's own spelling when shorter: a declared entity reference, or
344344
// a `>` it left bare. A `<` is a CDATA section, a bare `&` no reference.
345-
return raw.length < escaped.length && _isXmlWellFormedText(raw)
345+
return raw.length < escaped.length && isXmlWellFormedText(raw)
346346
? raw
347347
: escaped;
348348
}

‎test/unitCases/xml/printer.unittest.js‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,18 @@ b&#10;c">
333333
);
334334
});
335335

336+
it("should tell XML text well-formed as written from text a strict parser refuses", () => {
337+
const { isXmlWellFormedText } = require("../../../lib/html/syntax-parser");
338+
expect(isXmlWellFormedText("a &amp; b &#38; &#x26; &undeclared;")).toBe(
339+
true
340+
);
341+
expect(isXmlWellFormedText("a > b")).toBe(true);
342+
expect(isXmlWellFormedText("a & b")).toBe(false);
343+
expect(isXmlWellFormedText("&amp")).toBe(false);
344+
expect(isXmlWellFormedText("&1a;")).toBe(false);
345+
expect(isXmlWellFormedText("a < b")).toBe(false);
346+
});
347+
336348
it("should escape an `&` that opens no reference when minifying", () => {
337349
expect(printXml("<r>&amp", "minify")).toBe("<r>&amp;amp</r>");
338350
expect(printXml("<r>a & b</r>", "minify")).toBe("<r>a &amp; b</r>");

‎types.d.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38328,6 +38328,7 @@ declare namespace exports {
3832838328
export let isAllAsciiWhitespace: (s: string) => boolean;
3832938329
export let isAsciiAlphanumeric: (cc: number) => boolean;
3833038330
export let isAsciiWhitespace: (cc: number) => boolean;
38331+
export let isXmlWellFormedText: (raw: string) => boolean;
3833138332
export let metaTag: (name: string, content: string) => string;
3833238333
export let parseCssUrls: (input: string) => [string, number, number][];
3833338334
export let parseHtml: (

0 commit comments

Comments
 (0)