postcss: `Result.root` that is typed as `Document | Root` breaks the semantics of the `root` property

Ever since the addition of Document I’ve been “arguing” with the types of PostCSS a lot more. I’ve also been unable to add meaningful support for any syntax that makes use of the Document node because those syntax plugins have blocking issues that prevent real support.

Any plugin works equally bad or well as it did before this addition and none leverage this new node type.

So from my perspective the addition of Document isn’t beneficial.

I feel that the current implementation isn’t quite right.
I don’t know what should be changed to fix this.

---

This specific issue is about this code :

https://github.com/postcss/postcss/blob/a0a82d3530ce7dfbfe1f12aa76c20f1b3f95eb7c/lib/result.d.ts#L144

What I want to do :

• parse a stylesheet that is a foo.css file
• access the Root node

I already know that it is a Root node but now the type system is complaining and saying that it can be a Document node.

I can override this and tell TypeScript that it really is a Root node.
But what if someone uses one of the syntaxes that does return a Document in this case.

Which steps should I take :

• warn on Document nodes in Result.root?
• throw an error?
• traverse the Document nodes in search of Root nodes?

---

I think result.root must always return a Root node.
Never a Document node.

Maybe a new property can be added to expose Document nodes?