Replace sibling broadening warning with inline code comment

claude · claude · commit 93ff226e7078 · 2026-03-14T23:25:46.000Z
When CSS `+` (adjacent sibling) is transformed to StyleX's `siblingBefore()` (which emits `~`, general sibling), emit a `// NOTE:` comment on the computed key property instead of an info-level warning. This makes the semantic broadening visible directly in the generated code where it matters. https://claude.ai/code/session_01NACR4DTcJGrJ3xu7sWWQC9
diff --git a/src/__tests__/transform.test.ts b/src/__tests__/transform.test.ts
@@ -667,7 +667,7 @@ export const App = () => <Box><span /></Box>;
     expect(warning?.loc?.line).toBe(7);
   });
 
-  it("should emit info warning for & + & (adjacent sibling broadens to general)", () => {
+  it("should emit NOTE comment for & + & (adjacent sibling broadens to general)", () => {
     const source = `
 import styled from "styled-components";
 
@@ -688,15 +688,18 @@ export const App = () => <Thing />;
     );
 
     expect(result.code).not.toBeNull();
-    const infoWarnings = result.warnings.filter((w) => w.severity === "info");
-    expect(infoWarnings).toHaveLength(1);
-    expect(infoWarnings[0]).toMatchObject({
-      severity: "info",
-      type: "Sibling selector broadened: & + & (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match",
-    });
+    // No info warning — the broadening note is emitted as a code comment instead
+    const infoWarnings = result.warnings.filter(
+      (w) => w.severity === "info" && w.type.includes("Sibling selector broadened"),
+    );
+    expect(infoWarnings).toHaveLength(0);
+    // The output should contain a NOTE comment about the broadening
+    expect(result.code).toContain(
+      "// NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX",
+    );
   });
 
-  it("should NOT emit info warning for & ~ & (general sibling is exact match)", () => {
+  it("should NOT emit NOTE comment for & ~ & (general sibling is exact match)", () => {
     const source = `
 import styled from "styled-components";
 
@@ -717,8 +720,12 @@ export const App = () => <Thing />;
     );
 
     expect(result.code).not.toBeNull();
-    const infoWarnings = result.warnings.filter((w) => w.severity === "info");
+    const infoWarnings = result.warnings.filter(
+      (w) => w.severity === "info" && w.type.includes("Sibling selector broadened"),
+    );
     expect(infoWarnings).toHaveLength(0);
+    // No NOTE comment for general sibling — it's an exact match
+    expect(result.code).not.toContain("NOTE: CSS `+`");
   });
 
   it("should emit info warning when transient props are renamed on exported component", () => {
diff --git a/src/internal/logger.ts b/src/internal/logger.ts
@@ -103,8 +103,6 @@ export type WarningType =
   | "Unsupported css`` mixin: nested contextual conditions in after-base mixin"
   | "Unsupported css`` mixin: cannot infer base default for after-base contextual override (base value is non-literal)"
   | "css`` helper function interpolation references closure variable that cannot be hoisted"
-  | "Sibling selector broadened: & + & (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match"
-  | "Sibling selector broadened: + (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match"
   | "Using styled-components components as mixins is not supported; use css`` mixins or strings instead"
   | "styled(ImportedComponent) wraps a component whose file contains internal styled-components — convert the base component's file first to avoid CSS cascade conflicts"
   | "Transient $-prefixed props renamed on exported component — update consumer call sites to use the new prop names"
diff --git a/src/internal/lower-rules/finalize-decl.ts b/src/internal/lower-rules/finalize-decl.ts
@@ -84,13 +84,15 @@ export function finalizeDeclProcessing(ctx: DeclProcessingState): void {
       (merged as Record<string, unknown>).__computedKeys = entry.entries.map((e) => ({
         keyExpr: e.keyExpr,
         value: e.value,
+        leadingComment: e.leadingComment,
       }));
     } else {
       // No existing map, create a new nested object with default and __computedKeys
       const nested: Record<string, unknown> = { default: resolvedDefault };
       (nested as Record<string, unknown>).__computedKeys = entry.entries.map((e) => ({
         keyExpr: e.keyExpr,
         value: e.value,
+        leadingComment: e.leadingComment,
       }));
       styleObj[prop] = nested;
     }
diff --git a/src/internal/lower-rules/process-rules.ts b/src/internal/lower-rules/process-rules.ts
@@ -681,14 +681,8 @@ export function processDeclRules(ctx: DeclProcessingState): void {
           break;
         }
 
-        // Emit info warning for `+` since adjacent becomes general sibling
-        if (combinator === "+") {
-          warnings.push({
-            severity: "info",
-            type: "Sibling selector broadened: + (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match",
-            loc: computeSelectorWarningLoc(decl.loc, decl.rawCss, rule.selector),
-          });
-        }
+        // Track adjacent combinator so we can annotate the emitted computed keys
+        const isAdjacentCombinator = combinator === "+";
 
         // Register marker for the referenced component
         const refStyleKey = referencedDecl.styleKey;
@@ -769,7 +763,14 @@ export function processDeclRules(ctx: DeclProcessingState): void {
         for (const [prop, value] of Object.entries(sibBucket)) {
           const siblingValue = media ? { default: null, [media]: value } : value;
           const entry = getOrCreateComputedMediaEntry(prop, ctx);
-          entry.entries.push({ keyExpr: makeSiblingKeyExpr(), value: siblingValue });
+          entry.entries.push({
+            keyExpr: makeSiblingKeyExpr(),
+            value: siblingValue,
+            ...(isAdjacentCombinator && {
+              leadingComment:
+                "NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX",
+            }),
+          });
         }
         continue;
       }
@@ -2078,15 +2079,8 @@ function handleSiblingSelector(
   const { j, warnings, resolveThemeValue, resolveThemeValueFromFn, ancestorSelectorParents } =
     state;
 
-  // Emit info warning for `& + &` since adjacent becomes general sibling
+  // Track adjacent combinator so we can annotate the emitted computed keys
   const isAdjacent = /\+/.test(selector);
-  if (isAdjacent) {
-    warnings.push({
-      severity: "info",
-      type: "Sibling selector broadened: & + & (adjacent) becomes general sibling (~) in StyleX — interleaved non-matching elements will no longer block the match",
-      loc: computeSelectorWarningLoc(decl.loc, decl.rawCss, rule.selector),
-    });
-  }
 
   // Add to ancestorSelectorParents so the marker is injected into stylex.props() calls.
   // Also add to siblingMarkerParents to distinguish from forward/reverse selectors —
@@ -2176,7 +2170,13 @@ function handleSiblingSelector(
   for (const [prop, value] of Object.entries(bucket)) {
     const siblingValue = media ? { default: null, [media]: value } : value;
     const entry = getOrCreateComputedMediaEntry(prop, ctx);
-    entry.entries.push({ keyExpr: makeSiblingKeyExpr(), value: siblingValue });
+    entry.entries.push({
+      keyExpr: makeSiblingKeyExpr(),
+      value: siblingValue,
+      ...(isAdjacent && {
+        leadingComment: "NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX",
+      }),
+    });
   }
 }
 
diff --git a/src/internal/transform/helpers.ts b/src/internal/transform/helpers.ts
@@ -46,6 +46,8 @@ export type ComputedKeyEntry = {
   keyExpr: unknown;
   /** The value (can be nested object, string, number, etc.) */
   value: unknown;
+  /** Optional leading comment to attach to the emitted property */
+  leadingComment?: string;
 };
 
 export function objectToAst(j: API["jscodeshift"], obj: Record<string, unknown>): any {
@@ -145,6 +147,16 @@ export function objectToAst(j: API["jscodeshift"], obj: Record<string, unknown>)
         : literalToAst(j, entry.value);
     const prop = j.property("init", entry.keyExpr as any, valueAst);
     (prop as any).computed = true;
+    if (entry.leadingComment) {
+      (prop as any).comments = [
+        {
+          type: "CommentLine",
+          value: ` ${entry.leadingComment}`,
+          leading: true,
+          trailing: false,
+        },
+      ];
+    }
     props.push(prop);
   }
 
diff --git a/test-cases/selector-componentSiblingCombinator.output.tsx b/test-cases/selector-componentSiblingCombinator.output.tsx
@@ -37,11 +37,12 @@ const styles = stylex.create({
     paddingInline: 8,
     color: {
       default: "gray",
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":focus-visible", LinkMarker)]: "blue",
     },
     backgroundColor: {
       default: null,
-
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":hover", LinkMarker)]: {
         default: null,
         "@media (min-width: 768px)": "lightyellow",
diff --git a/test-cases/selector-sibling.output.tsx b/test-cases/selector-sibling.output.tsx
@@ -37,24 +37,28 @@ const styles = stylex.create({
   thing: {
     color: {
       default: "blue",
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":is(*)", ThingMarker)]: "red",
     },
     paddingBlock: 8,
     paddingInline: 16,
     backgroundColor: {
       default: null,
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":is(*)", ThingMarker)]: "lime",
     },
   },
   thingThemed: {
     color: {
       default: "blue",
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":is(*)", ThingThemedMarker)]: $colors.labelBase,
     },
   },
   row: {
     marginTop: {
       default: null,
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":is(*)", RowMarker)]: 16,
     },
   },
diff --git a/test-cases/selector-siblingBaseAfter.output.tsx b/test-cases/selector-siblingBaseAfter.output.tsx
@@ -19,6 +19,7 @@ const styles = stylex.create({
   thing: {
     color: {
       default: "blue",
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":is(*)", ThingMarker)]: "red",
     },
     paddingBlock: 8,
diff --git a/test-cases/selector-siblingMarkerScoping.output.tsx b/test-cases/selector-siblingMarkerScoping.output.tsx
@@ -28,14 +28,17 @@ const styles = stylex.create({
     padding: 8,
     borderTopWidth: {
       default: null,
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":is(*)", RowMarker)]: 1,
     },
     borderTopStyle: {
       default: null,
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":is(*)", RowMarker)]: "solid",
     },
     borderTopColor: {
       default: null,
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":is(*)", RowMarker)]: "gray",
     },
   },
diff --git a/test-cases/selector-siblingMedia.output.tsx b/test-cases/selector-siblingMedia.output.tsx
@@ -19,7 +19,7 @@ const styles = stylex.create({
     padding: 8,
     marginTop: {
       default: null,
-
+      // NOTE: CSS `+` (adjacent sibling) becomes `~` (general sibling) in StyleX
       [stylex.when.siblingBefore(":is(*)", ThingMarker)]: {
         default: null,
         "@media (min-width: 768px)": 16,
