docs(transformer/styled-components): add comments about CSSMinifier

[Dunqing]

Added some comments to describe CSSMinifier, and clarify why quasis.set_len(expressions.len() + 1); is safe.

Also, there is a assert in codegen to ensure that quasis is always one greater than expressions

oxc/crates/oxc_codegen/src/gen.rs

Lines 2091 to 2092 in c003eba

	debug_assert_eq!(self.quasis.len(), self.expressions.len() + 1);

In addition, I found that we can use truncate() instead of set_len. Both are the same, but truncate is a safe function.

[Dunqing]

• fix(transformer/legacy-decorator): decorated fields with the declare modifier are not transformed #12212
• refactor(transformer/styled-components): do not allocate temp data into arena #12198
• fix(transformer/styled-components): template literal expressions order is wrong after minification #12211
• test(transformer/styled-components): add failing test case for comment removal #12202
• perf(transformer/styled-components): cache block name #12200
• fix(transformer/styled-components): should use source path to generate file hash when the path is absoulte path #12199
• docs(transformer/styled-components): add comments about CSSMinifier #12197 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• 0-merge - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[codspeed-hq]

CodSpeed Instrumentation Performance Report

Merging #12197 will not alter performance

_{Comparing 07-10-docs_transformer_styled-components_add_comments_about_cssminifier (86eb108) with main (daf6087)}

Summary

✅ 34 untouched benchmarks

[graphite-app]

Merge activity

• Jul 10, 4:27 PM UTC: The merge label '0-merge' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
• Jul 10, 5:03 PM UTC: The merge label '0-merge' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
• Jul 10, 5:03 PM UTC: overlookmotel added this pull request to the Graphite merge queue.
• Jul 10, 5:08 PM UTC: The merge label '0-merge' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
• Jul 10, 5:09 PM UTC: The merge label '0-merge' was removed. This PR will no longer be merged by the Graphite merge queue
• Jul 10, 5:12 PM UTC: Merged by the Graphite merge queue.

[overlookmotel]

Apart from the typo Graphite's spotted (it finally got something right), all looks good. Thank you for documenting this.

[overlookmotel]

What makes it true that "template literal has ensured that quasis always has one more element than expressions"? How is that ensured?

If in some other transform, I do expressions.push(...) without corresponding quasis.push(...) by accident, this invariant is broken, and quasis.set_len(expressions.len() + 1) is UB. Safety invariants should be local and provable. "SAFETY: There are no bugs in the rest of the codebase" isn't very convincing!

Also, there is a assert in codegen to ensure that quasis is always one greater than expressions

oxc/crates/oxc_codegen/src/gen.rs

Lines 2091 to 2092 in c003eba

	debug_assert_eq!(self.quasis.len(), self.expressions.len() + 1);

1. It's debug_assert! not assert!. That's no good as a safety guarantee.
2. It's in codegen. Even if it was assert!, it's too late. We's already invoke UB before we get to that.

In addition, I found that we can use truncate() instead of set_len. Both are the same, but truncate is a safe function.

truncate would be fine - it might panic if some other code has broken the rule, but won't cause UB.

Or we could add an assertion at top of the function assert!(quasis.len() == expressions.len() + 1), and then use unsafe set_len.

But... this PR is mainly about adding comments. Let's leave it as is here, and address it in a separate PR.

[overlookmotel]

Personally, I'd quite like to make this a type system invariant by changing TemplateLiteral to:

pub struct TemplateLiteral<'a> {
    pub span: Span,
    pub lead: Vec<'a, TemplateElementAndExpression<'a>>,
    pub tail: TemplateElement<'a>,
}

pub struct TemplateElementAndExpression<'a> {
    quasi: TemplateElement<'a>,
    expression: Expression<'a>,
}

Then we can stop worrying about this! Rust will prevent us making mistakes.

[overlookmotel]

@Dunqing Ping just to make sure you see this. I had to mark it as "resolved" to merge the PR.

[Dunqing]

The new type looks good, the current one is probably to align with the ESTree. I will add that assertion later.

[overlookmotel]

#12213