add a comment that describes the code relies on the unofficial docume…

…nt property
stylelint · jeddy3 · Aug 7, 2025 · Aug 1, 2025 · Aug 2, 2025 · Aug 3, 2025
commit ce24f1c09d69f63f8ecb121de83de64d3ad4f4d4
diff --git a/lib/rules/no-invalid-position-declaration/index.cjs b/lib/rules/no-invalid-position-declaration/index.cjs
diff --git a/lib/rules/no-invalid-position-declaration/index.mjs b/lib/rules/no-invalid-position-declaration/index.mjs
@@ -1,6 +1,6 @@
 import { isAtRule, isRule } from '../../utils/typeGuards.mjs';
 import findNodeUpToRoot from '../../utils/findNodeUpToRoot.mjs';
-import { isInDocument } from '../../utils/isInDocument.mjs';
+import isInDocument from '../../utils/isInDocument.mjs';
 import isStandardSyntaxDeclaration from '../../utils/isStandardSyntaxDeclaration.mjs';
 import { nestingSupportedAtKeywords } from '../../reference/atKeywords.mjs';
 import report from '../../utils/report.mjs';

diff --git a/lib/utils/__tests__/isInDocument.test.mjs b/lib/utils/__tests__/isInDocument.test.mjs
@@ -1,6 +1,7 @@
 import postcss from 'postcss';
+import postcssHtml from 'postcss-html';
 
-import { isInDocument } from '../isInDocument.mjs';
+import isInDocument from '../isInDocument.mjs';
 import naiveCssInJs from '../../__tests__/fixtures/postcss-naive-css-in-js.cjs';
 
 describe('isInDocument', () => {
@@ -135,4 +136,99 @@ describe('isInDocument', () => {
 
 		expect(isInDocument(decl)).toBe(true);
 	});
+
+	describe('with postcss-html parser', () => {
+		it('returns true for declarations in HTML style tags', () => {
+			const document = postcssHtml.parse('<style>a { color: red; --custom: blue; }</style>');
+			const decls = [];
+
+			document.walkDecls((decl) => decls.push(decl));
+
+			expect(decls).toHaveLength(2);
+			expect(isInDocument(decls[0])).toBe(true); // color: red
+			expect(isInDocument(decls[1])).toBe(true); // --custom: blue
+		});
+
+		it('returns true for declarations in HTML style attributes', () => {
+			const document = postcssHtml.parse('<div style="color: red; font-size: 14px;">content</div>');
+			const decls = [];
+
+			document.walkDecls((decl) => decls.push(decl));
+
+			expect(decls).toHaveLength(2);
+			expect(isInDocument(decls[0])).toBe(true); // color: red
+			expect(isInDocument(decls[1])).toBe(true); // font-size: 14px
+		});
+
+		it('returns true for declarations in multiple HTML style sources', () => {
+			const document = postcssHtml.parse(`
+				<style>body { margin: 0; }</style>
+				<div style="color: red;">content</div>
+				<style>.class { padding: 10px; }</style>
+			`);
+			const decls = [];
+
+			document.walkDecls((decl) => decls.push(decl));
+
+			expect(decls).toHaveLength(3);
+			expect(isInDocument(decls[0])).toBe(true); // margin: 0
+			expect(isInDocument(decls[1])).toBe(true); // color: red
+			expect(isInDocument(decls[2])).toBe(true); // padding: 10px
+		});
+
+		it('returns true for deeply nested declarations in HTML', () => {
+			const document = postcssHtml.parse(`
+				<style>
+					@media (min-width: 600px) {
+						.container {
+							display: grid;
+							@supports (display: grid) {
+								grid-template-columns: 1fr 1fr;
+							}
+						}
+					}
+				</style>
+			`);
+			const decls = [];
+
+			document.walkDecls((decl) => decls.push(decl));
+
+			expect(decls).toHaveLength(2);
+			expect(isInDocument(decls[0])).toBe(true); // display: grid
+			expect(isInDocument(decls[1])).toBe(true); // grid-template-columns
+		});
+
+		it('returns true for custom properties in HTML style attributes', () => {
+			const document = postcssHtml.parse(
+				'<div style="--theme-color: #ff0000; color: var(--theme-color);">content</div>',
+			);
+			const decls = [];
+
+			document.walkDecls((decl) => decls.push(decl));
+
+			expect(decls).toHaveLength(2);
+			expect(isInDocument(decls[0])).toBe(true); // --theme-color
+			expect(isInDocument(decls[1])).toBe(true); // color
+		});
+
+		it('handles edge case where root.parent might be undefined', () => {
+			// Test cases where HTML parsers may not properly set parent relationships
+			// Some parsers create Document nodes but don't always link Root.parent to Document
+			const document = postcssHtml.parse('<style>a { color: red; }</style>');
+			const root = document.first;
+			const decl = root.first.first;
+
+			// Verify the expected AST structure: Document -> Root -> Rule -> Declaration
+			expect(document.type).toBe('document');
+			expect(root.type).toBe('root');
+
+			// In some HTML parsing scenarios, root.parent may be undefined
+			// despite the root being contained within a document
+			expect(root.parent).toBeUndefined();
+
+			// Our function should still correctly detect that the declaration
+			// is within a document context through alternative means
+			expect(isInDocument(decl)).toBe(true);
+		});
+	});
 });
diff --git a/lib/utils/isInDocument.cjs b/lib/utils/isInDocument.cjs
diff --git a/lib/utils/isInDocument.mjs b/lib/utils/isInDocument.mjs
@@ -4,21 +4,20 @@ import { isDocument } from './typeGuards.mjs';
  * @param {import('postcss').Node} node
  * @returns {boolean}
  */
-export function isInDocument(node) {
+export default function isInDocument(node) {
 	let current = node;
 
 	while (current) {
 		if (isDocument(current)) return true;
 
-		// Check if current node has a document property
+		// Check for unofficial 'document' property from parsers like postcss-html
 		if (
 			'document' in current &&
 			current.document &&
 			isDocument(/** @type {import('postcss').Document} */ (current.document))
 		)
 			return true;
 
-		// Only assign if parent exists
 		if (!current.parent) break;
 
 		current = current.parent;