feat: experimental new stuff

Author: RJWadley

.cursor/rules/display-contexts.mdc

@@ -0,0 +1,78 @@
+---
+description: Details and examples about how properties that affect different display contexts (such as grid, flex, and block contexts) should be handled.
+globs: 
+alwaysApply: false
+---
+
+### **CSS Context and Feature Detection**
+
+#### **Primary Rule: The "Conservative (Same-Rule Only)" Approach**
+
+When analyzing CSS, a property's behavior is considered within a specific layout context (like `flex`, `grid`, or `block`) **ONLY IF** the `display` property establishing that context is explicitly declared within the **SAME CSS RULE**. Implicit contexts (e.g., `div` being block by default) or contexts set on parent rules are **NOT** considered.
+
+#### **Exception: Handling Item-Specific Properties (e.g., `place-self`)**
+
+This "same-rule" model makes it impossible to determine a context for properties that apply to flex/grid *items* rather than the container. The `display` property is on the parent, but the item-specific property is on the child.
+
+Therefore, for these specific properties, **we abandon context detection entirely**. You should generate tests that report the usage of these properties whenever they appear, regardless of context.
+
+**Example for the Exception:**
+
+*   **`place-self` (Item Property):** This property affects a grid or flex item. We can never know its context. Therefore, it should be reported whenever it is used.
+
+    ```css
+    .grid-container {
+      display: grid;
+    }
+    .grid-item {
+      place-self: center start; /* <<< DETECTED (Reported without context check) */
+    }
+
+    .some-other-element {
+      place-self: end;          /* <<< ALSO DETECTED (Reported without context check) */
+    }
+    ```
+
+---
+
+### **Examples Illustrating the Primary Rule**
+
+**1. Flex Context Detection:**
+
+*   **Detected:** `align-content` is detected as a flex property because `display: flex` is in the same rule.
+
+    ```css
+    .flex-container {
+      display: flex;
+      align-content: center; /* <<< DETECTED */
+    }
+    ```
+
+*   **NOT Detected:** `align-content` is *NOT* detected as a flex property because `display: flex` is in a different rule.
+
+    ```css
+    .parent { display: flex; }
+    .child {
+      align-content: center; /* <<< NOT DETECTED */
+    }
+    ```
+
+**2. Block Context Detection:**
+
+*   **Detected:** `align-content` is detected as a block property because `display: block` is in the same rule.
+
+    ```css
+    .block-element {
+      display: block;
+      align-content: start; /* <<< DETECTED */
+    }
+    ```
+
+*   **NOT Detected:** `align-content` is *NOT* detected, even on a `div`, because `display: block` is not explicitly written in the rule.
+
+    ```css
+    div {
+      align-content: start; /* <<< NOT DETECTED */
+    }
+    ```
+    

.cursor/rules/guiding-principles.mdc

@@ -0,0 +1,55 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+Excellent question. As we worked through the test failures, we established several key rules and heuristics beyond just the display context. These are crucial for building a robust and predictable checker.
+
+Here is a comprehensive summary of all the rules we've developed:
+
+1. The Display Context Rule: "Conservative, Same-Rule Only"
+
+This is the most important rule we established for container properties.
+
+Primary Rule: A property is only considered to be in a flex, grid, or block context if the corresponding display property (display: flex, display: block, etc.) is explicitly declared in the exact same CSS rule.
+
+Exception for Item-Specific Properties: For properties that apply to flex/grid items (like place-self or align-self), we abandon context detection entirely. We report them whenever they are used, as their context is set on a parent rule which we cannot reliably determine.
+
+2. The @supports Heuristic: "Exact Match Only"
+
+Because we can't build a full browser engine to evaluate complex @supports queries, we settled on a simple, predictable heuristic.
+
+Rule: We only consider a feature to be "guarded" (and thus suppress a warning) if the @supports query checks for the exact property and value being used.
+
+Example: align-content: stretch is only considered guarded by @supports (align-content: stretch). We would ignore a more general query like @supports (display: flex). This avoids the complexity of parsing logical operators (and, or, not) and trying to infer contextual relationships.
+
+3. The Value Normalization Rule: "Always Clean the Input"
+
+To handle variations in developer formatting, we apply two key normalization steps.
+
+Handle Comments with .trim(): PostCSS often includes trailing whitespace in a decl.value if a comment follows it (e.g., value: 'start /* comment */'). We must always call .trim() on the value before checking it.
+Handle Whitespace with .replace(/\s+/g, ' '): For multi-word values (like first baseline), we first normalize all internal whitespace to a single space. This makes checks like value.includes('first baseline') reliable, regardless of whether the developer wrote one space or several.
+
+4. The Special Values Rule: "Handle Keywords and Variables Conservatively"
+
+CSS has special values that require specific handling because we can't know their resolved value during static analysis.
+
+CSS-Wide Keywords (initial, unset, revert): We handle these on a per-property basis. For some properties (anchor-scope), these keywords effectively mean none. For others, we may need to check if they should trigger a general feature detection.
+
+CSS Variables (var(...)): This is the hardest case. Our current stance is that it's impossible to know what a variable resolves to. The most conservative approach is to assume it could be an unsupported value and trigger the general feature detection for that property (e.g., if we see align-content: var(--my-align), we would report a usage of align-content).
+
+5. The Architectural Rule: "Centralize Logic in approve()"
+
+To keep the checker maintainable and make adding new features easy, all feature detections are funneled through a single approve(decl, featureId) function.
+
+Purpose: This central function is responsible for handling all the common, repetitive logic:
+
+Determining the vendor prefix.
+
+Checking for @supports guards.
+
+Checking for the presence of fallback properties.
+
+Benefit: This keeps the main checking logic clean and focused only on identifying property: value pairs, without cluttering it with repeated checks for prefixes or @supports conditions.
+
+These five rules form the complete logical foundation of our checker. They provide a clear and consistent framework for how we handle the ambiguities and complexities of static CSS analysis.

.cursor/rules/run-tests.mdc

@@ -0,0 +1,6 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+Tests can be run with `bun run test`, which will use vitest's test runner. You can also run vitest directly using `bunx vitest run`.

.cursor/rules/verify-assumptions.mdc

@@ -0,0 +1,6 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+When working with the AST, always add comments to verify your assumptions before making changes. Even though I'm very familiar with the AST, I am sometimes surprised by the structure.

.gitignore

@@ -9,3 +9,6 @@ package-lock.json
 
 # System files
 .DS_Store
+
+# Secrets
+.env

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+}