@jesscss/core 2.0.0-alpha.4 → 2.0.0-alpha.6

package/src/tree/util/EXTEND_ARCHITECTURE_ANALYSIS.md

@@ -0,0 +1,215 @@
+# Extend Architecture Analysis - Self-Referencing and Responsibility Boundaries
+
+## Current Architecture
+
+### Responsibility Layers
+
+1. **`extend-roots.ts`** - High-level orchestration
+   - Manages extend root relationships
+   - Processes extends recursively
+   - **Responsible for**: Detecting and filtering self-referencing extends
+   - **Responsible for**: Preventing circular references
+   - **Responsible for**: Deciding which extends should be processed
+
+2. **`extend.ts`** - Core extend logic
+   - `extendSelector()` - Performs the actual extension
+   - `tryExtendSelector()` - Wrapper with error handling
+   - **Responsible for**: Given valid inputs, perform the extension
+   - **Should NOT be responsible for**: Deciding whether to extend
+
+3. **`extend-helpers.ts`** - Utility functions
+   - Selector matching, component comparison, path building
+   - **Responsible for**: Pure utility functions
+
+## Current Self-Referencing Detection
+
+### In `extend-roots.ts` (lines 450-453, 472-475)
+
+```typescript
+// Skip self-referencing extends
+if (target.valueOf() === selectorWithExtend.valueOf()) {
+  return; // Early return - extend is skipped
+}
+
+// Later, for individual selectors:
+if (singleTarget.valueOf() === selectorWithExtend.valueOf()) {
+  continue; // Skip this selector
+}
+```
+
+### Analysis
+
+**✅ GOOD:**
+- Detection happens in `extend-roots.ts` where it belongs
+- Uses `valueOf()` for comparison (handles different object instances)
+- Early return prevents processing
+
+**❌ ISSUES:**
+
+1. **Incomplete Detection**: The check only compares `target` vs `selectorWithExtend`, but doesn't handle:
+   - Chained self-references: `.a:extend(.b)` where `.b:extend(.a)` exists
+   - Partial self-references: `.a.b:extend(.a)` (should this be skipped?)
+   - SelectorList self-references: `.a, .b:extend(.a, .b)`
+
+2. **Test Failure Analysis**: The test `should ignore self-referencing extends: .w:extend(.w)` is failing with:
+   - Error: `Cannot read properties of undefined (reading 'clone')` at `extendSelectorList` line 973
+   - Expected: `.w, .v.w.v { color: black; }`
+   - Received: `.w { color: black; }`
+   
+   This suggests:
+   - The self-reference check IS working (`.w:extend(.w)` is skipped)
+   - But something else is wrong - maybe `.v.w.v:extend(.w)` is also being skipped incorrectly?
+   - Or `extendSelectorList` is being called with an undefined result
+
+3. **Missing Logic**: The check at line 451 compares `target` (the selector being extended) with `selectorWithExtend` (the selector that has the `:extend()`). But:
+   - `target` is the selector in the `:extend(.target)` 
+   - `selectorWithExtend` is the selector that contains the `:extend()`
+   - For `.w:extend(.w)`, `target = .w` and `selectorWithExtend = .w`, so they match ✅
+   - But what about `.a.b:extend(.a)`? Should this be considered self-referencing?
+
+## Recommendations
+
+### 1. Keep Self-Referencing Detection in `extend-roots.ts`
+
+**✅ CORRECT APPROACH**: The user is right - `extendSelector` should NOT have self-referencing checks. It should be a pure function that:
+- Takes a target, find, and extendWith
+- Performs the extension
+- Returns the result
+
+**Decision logic** (should I extend?) belongs in `extend-roots.ts`.
+
+### 2. Enhance Self-Referencing Detection
+
+The current check is too simple. We should:
+
+**Option A: Keep Simple (Current)**
+- Only skip when `target === selectorWithExtend` (exact match)
+- This handles `.w:extend(.w)` but not `.a.b:extend(.a)`
+
+**Option B: Enhanced Detection**
+- Check if `target` is a component of `selectorWithExtend`
+- Check for circular chains using the `processedExtends` set
+- More sophisticated but might be overkill
+
+**Recommendation**: Start with Option A, but make the check more robust:
+- Handle SelectorList cases properly
+- Ensure the check happens before calling `extendSelector`
+- Add better error handling if `extendSelector` is called incorrectly
+
+### 3. Fix the Test Failure
+
+The error `Cannot read properties of undefined (reading 'clone')` at line 973 suggests:
+
+```typescript
+originalSelectors.push(extended.value[0]!.clone(true));
+```
+
+This means `extended.value[0]` is `undefined`. This could happen if:
+- `extendSelector` returns a SelectorList with an empty `value` array
+- `extendSelector` returns something unexpected
+- The self-reference check is working, but the result handling is wrong
+
+**Investigation needed:**
+1. Check what `extendSelector` returns when called with self-referencing (it shouldn't be called, but if it is...)
+2. Check if `extendSelectorList` handles empty results correctly
+3. Verify the flow when self-referencing is detected
+
+### 4. Architecture Improvements
+
+**Current Flow:**
+```
+extend-roots.ts:processExtend()
+  → Check self-reference (line 451)
+  → If not self-reference, call extendSelector()
+  → Handle result
+```
+
+**Problem**: If self-reference check fails or is bypassed, `extendSelector` gets called with invalid inputs.
+
+**Solution**: 
+- Make self-reference check more robust
+- Add defensive checks in `extendSelector` if needed (but only for error handling, not logic)
+- Ensure `extendSelectorList` handles edge cases
+
+### 5. Test Expectations Review
+
+The test expects:
+```css
+.w,
+.v.w.v {
+  color: black;
+}
+```
+
+This means:
+- `.w:extend(.w)` should be ignored (self-reference) ✅
+- `.v.w.v:extend(.w)` should work (not self-reference) ✅
+- Both rulesets should be combined
+
+**Current behavior**: Only `.w` is output, suggesting `.v.w.v:extend(.w)` is also being skipped incorrectly, OR the extend is working but the output is wrong.
+
+## Action Items
+
+1. **Remove naive self-reference check from `extendSelector`** ✅ (Already done)
+
+2. **Investigate test failure**:
+   - Why is `extended.value[0]` undefined?
+   - Is `.v.w.v:extend(.w)` being processed correctly?
+   - Is the self-reference check working for all cases?
+
+3. **Enhance self-reference detection in `extend-roots.ts`**:
+   - Ensure it handles SelectorList cases
+   - Add logging/debugging to verify it's working
+   - Consider if partial matches should be considered self-referencing
+
+4. **Add defensive checks** (if needed):
+   - In `extendSelectorList`, check if `extended.value[0]` exists before cloning
+   - But don't add logic checks - only error handling
+
+5. **Review test expectations**:
+   - Verify the test is correct
+   - Ensure it's testing the right behavior
+   - Check if test setup is correct
+
+## Conclusion
+
+The user is correct: `extendSelector` should remain a pure function that performs extensions when called. The responsibility for detecting and filtering self-referencing extends belongs in `extend-roots.ts`. 
+
+The current implementation has the right architecture, but:
+- The self-reference detection might need enhancement
+- There's a bug causing the test failure that needs investigation
+- The error handling in `extendSelectorList` might need improvement
+
+## Immediate Fixes
+
+### 1. Add Defensive Check in `extendSelectorList`
+
+The error `Cannot read properties of undefined (reading 'clone')` at line 977 suggests `extended.value[0]` is undefined. This is a defensive programming issue, not a logic issue.
+
+**Fix**: Add a check to ensure `extended.value.length > 0` before accessing `extended.value[0]`.
+
+This is acceptable because:
+- It's error handling, not business logic
+- It prevents crashes when unexpected inputs occur
+- It doesn't change the behavior of `extendSelector` itself
+
+### 2. Investigate Root Cause
+
+The empty SelectorList suggests:
+- `createExtendedSelectorList` might be creating empty SelectorLists
+- `extendSelector` might be returning unexpected results in edge cases
+- The self-reference check in `extend-roots.ts` might not be catching all cases
+
+**Next Steps**: 
+1. Add defensive check (done)
+2. Add logging to understand when empty SelectorLists are created
+3. Verify self-reference detection is working correctly
+4. Check if `createExtendedSelectorList` can return empty arrays
+
+### 3. Architecture Validation
+
+**✅ CORRECT**: Self-reference detection in `extend-roots.ts` (lines 450-453, 472-475)
+**✅ CORRECT**: `extendSelector` is a pure function without business logic checks
+**✅ CORRECT**: Defensive error handling in `extendSelectorList` (acceptable)
+
+**❓ NEEDS INVESTIGATION**: Why is `extendSelector` returning empty SelectorLists?

package/src/tree/util/EXTEND_AUDIT.md

@@ -0,0 +1,233 @@
+# Extend Utilities Architectural Audit
+
+## Analysis Date
+2024-12-19
+
+## Purpose
+Deep analysis of unused functions in `extend.ts` to determine:
+1. Why they exist
+2. Whether they solve problems that should be solved
+3. Whether they're better approaches than current code
+4. Whether they should be integrated or removed
+
+---
+
+## Unused Functions Analysis
+
+### 1. `handleFullExtend` (lines 910-977)
+**Status:** UNUSED - Logic is duplicated inline in `extendSelector`
+
+**Purpose:** 
+- Consolidates full extend logic (when `partial: false`)
+- Handles SelectorList, PseudoSelector, and CompoundSelector cases
+- Has performance optimization for generated selectors (mutates in place)
+
+**Current Implementation:**
+- Full extend logic is scattered throughout `extendSelector` (lines 723-830)
+- Handles root-level matches, pseudo-selector matches, compound matches, complex selector matches
+- Does NOT have the performance optimization for generated selectors
+
+**Analysis:**
+- ✅ **SHOULD BE INTEGRATED**: The current code duplicates this logic but is less organized
+- ✅ **BETTER APPROACH**: `handleFullExtend` consolidates the logic and has performance optimizations
+- ⚠️ **ISSUE**: Current code handles some cases `handleFullExtend` doesn't (e.g., boundary crossing detection)
+- **Recommendation**: Refactor `extendSelector` to use `handleFullExtend` for full extends, but keep boundary-crossing logic separate
+
+---
+
+### 2. `createValidatedIsWrapper` (lines 1077-1181)
+**Status:** UNUSED - Only `createValidatedIsWrapperWithErrors` is used
+
+**Purpose:**
+- Creates `:is()` wrapper with validation that returns fallback on conflicts
+- Has context-aware validation (checks if `:is()` would conflict with compound selector context)
+- Returns fallback selector instead of throwing
+
+**Current Implementation:**
+- Uses `createValidatedIsWrapperWithErrors` which throws on conflicts (line 794)
+- No fallback mechanism - always throws
+
+**Analysis:**
+- ❓ **UNCLEAR IF NEEDED**: The current approach throws errors, which might be correct
+- ⚠️ **POTENTIAL ISSUE**: If validation fails, we throw - but maybe we should fallback?
+- **Recommendation**: Review if fallback behavior is needed. If not, remove. If yes, integrate.
+
+---
+
+### 3. `optimizeTopLevelUnnecessaryIsWrapper` (lines 1548-1568)
+**Status:** UNUSED
+
+**Purpose:**
+- Optimizes standalone `:is()` pseudo-selectors that were generated
+- Unwraps `:is()` when it's not needed (e.g., `:is(.a)` → `.a`)
+- Only optimizes generated selectors (not user-authored)
+
+**Current Implementation:**
+- No optimization of unnecessary `:is()` wrappers
+- Generated `:is()` selectors are kept as-is
+
+**Analysis:**
+- ✅ **SHOULD BE INTEGRATED**: This is a valid optimization
+- ✅ **PERFORMANCE BENEFIT**: Reduces unnecessary `:is()` wrappers in output
+- ⚠️ **WHEN TO CALL**: Need to determine where in the pipeline to call this
+- **Recommendation**: Integrate into `flattenGeneratedIs` or call after extend operations
+
+---
+
+### 4. `handlePartialExtendAtRoot` (lines 1573-1584)
+**Status:** UNUSED
+
+**Purpose:**
+- Handles partial extends at root level (when `location.path.length === 0`)
+- Creates `:is()` wrapper for compound selectors
+- Falls back to selector list for other cases
+
+**Current Implementation:**
+- Root-level partial extends are handled inline (lines 619-688)
+- Uses `createExtendedSelectorList` directly
+- Has special handling for remainders and complex selector partial matches
+
+**Analysis:**
+- ⚠️ **PARTIALLY DUPLICATED**: Current code does more (handles remainders, complex selectors)
+- ❓ **SIMPLER APPROACH**: `handlePartialExtendAtRoot` is simpler but less complete
+- **Recommendation**: Current implementation is more complete. Remove `handlePartialExtendAtRoot` unless we want to simplify.
+
+---
+
+### 5. `needsPartialMatchProcessing` (lines 1589-1592)
+**Status:** UNUSED
+
+**Purpose:**
+- Checks if partial match result needs processing
+- Returns true for ComplexSelector or CompoundSelector
+
+**Current Implementation:**
+- No such check - processes all results directly
+
+**Analysis:**
+- ❓ **MAYBE USEFUL**: Could be used to skip processing for simple selectors
+- ⚠️ **LOW VALUE**: The check is trivial and doesn't add much
+- **Recommendation**: Remove unless we find a performance benefit
+
+---
+
+### 6. `processPartialMatchResult` (lines 1597-1607)
+**Status:** UNUSED - Stub function
+
+**Purpose:**
+- Placeholder for processing partial match results
+- Currently just returns result as-is
+- Comment says "This is where we would handle complex partial match scenarios"
+
+**Current Implementation:**
+- Partial match processing is done inline in `extendSelector`
+
+**Analysis:**
+- ⚠️ **INCOMPLETE WORK**: This was a placeholder that was never implemented
+- ❓ **MAYBE NEEDED**: Comment suggests there are complex scenarios not handled
+- **Recommendation**: Either implement it or remove it. Check if there are unhandled partial match scenarios.
+
+---
+
+### 7. `handleExtendLocationPartial` (lines 1612-1623)
+**Status:** UNUSED
+
+**Purpose:**
+- Handles extension location in partial mode
+- Creates `:is()` wrappers
+- Currently just calls `applyExtensionAtLocation`
+
+**Current Implementation:**
+- Partial mode handling is done inline in `extendSelector` (lines 616-722)
+- Has complex logic for root-level, component-level, and multiple matches
+
+**Analysis:**
+- ⚠️ **INCOMPLETE**: Function is a stub that doesn't do the actual work
+- ❓ **MAYBE INTENDED**: Was meant to consolidate partial mode logic but never completed
+- **Recommendation**: Remove - current inline implementation is more complete
+
+---
+
+### 8. `handleExtendLocationFull` (lines 1628-1645)
+**Status:** UNUSED
+
+**Purpose:**
+- Handles extension location in full mode
+- Calls `convertToIsWrapperIfNeeded` for compound selectors
+- Falls back to `applyExtensionAtLocation`
+
+**Current Implementation:**
+- Full mode handling is done inline in `extendSelector` (lines 723-830)
+- Has logic for root-level, pseudo-selector, boundary-crossing, compound, and complex selector cases
+
+**Analysis:**
+- ⚠️ **INCOMPLETE**: Function doesn't handle all the cases current code does
+- ❓ **MAYBE INTENDED**: Was meant to consolidate full mode logic but never completed
+- **Recommendation**: Remove - current inline implementation is more complete
+
+---
+
+### 9. `convertToIsWrapperIfNeeded` (lines 1650-1667)
+**Status:** UNUSED - Only called from unused `handleExtendLocationFull`
+
+**Purpose:**
+- Converts extended results to use `:is()` wrappers for compound selectors
+- Currently a stub with TODO comment
+
+**Current Implementation:**
+- Compound selector extensions create `:is()` wrappers directly (line 794)
+- Uses `createValidatedIsWrapperWithErrors`
+
+**Analysis:**
+- ⚠️ **INCOMPLETE WORK**: Stub function with TODO
+- ❓ **MAYBE NEEDED**: Comment suggests there's logic for compound boundary cases
+- **Recommendation**: Either implement the logic or remove. Check if current implementation handles all cases.
+
+---
+
+### 10. `createValidatedCompoundSelector` (lines 1708-1719)
+**Status:** UNUSED - Only `createValidatedCompoundSelectorWithErrors` is used
+
+**Purpose:**
+- Creates compound selector with validation that returns fallback on conflicts
+- Returns fallback selector instead of throwing
+
+**Current Implementation:**
+- Uses `createValidatedCompoundSelectorWithErrors` which throws on conflicts
+- No fallback mechanism
+
+**Analysis:**
+- ❓ **UNCLEAR IF NEEDED**: Current approach throws errors, which might be correct
+- ⚠️ **POTENTIAL ISSUE**: If validation fails, we throw - but maybe we should fallback?
+- **Recommendation**: Review if fallback behavior is needed. If not, remove. If yes, integrate.
+
+---
+
+## Summary & Recommendations
+
+### Functions to INTEGRATE:
+1. **`handleFullExtend`** - Consolidates full extend logic, has performance optimizations
+2. **`optimizeTopLevelUnnecessaryIsWrapper`** - Valid optimization that should be applied
+
+### Functions to REVIEW:
+1. **`createValidatedIsWrapper`** - Check if fallback behavior is needed vs throwing
+2. **`createValidatedCompoundSelector`** - Check if fallback behavior is needed vs throwing
+3. **`processPartialMatchResult`** - Check if there are unhandled partial match scenarios
+4. **`convertToIsWrapperIfNeeded`** - Check if compound boundary cases need special handling
+
+### Functions to REMOVE:
+1. **`handlePartialExtendAtRoot`** - Current implementation is more complete
+2. **`needsPartialMatchProcessing`** - Trivial check, no value
+3. **`handleExtendLocationPartial`** - Incomplete stub, current code is better
+4. **`handleExtendLocationFull`** - Incomplete stub, current code is better
+
+---
+
+## Action Items
+
+1. ✅ Review validation error handling - should we fallback or throw?
+2. ✅ Integrate `handleFullExtend` into `extendSelector` for full extends
+3. ✅ Integrate `optimizeTopLevelUnnecessaryIsWrapper` into flattening pipeline
+4. ✅ Investigate if `processPartialMatchResult` and `convertToIsWrapperIfNeeded` solve real problems
+5. ✅ Remove incomplete stub functions
+6. ✅ Enable ESLint `@typescript-eslint/no-unused-vars` to catch unused code

package/src/tree/util/EXTEND_BASELINE.md

@@ -0,0 +1,64 @@
+# Extend Tests Baseline
+
+## Date
+2025-01-XX (Before refactoring)
+
+## Test Command
+```bash
+cd packages/core && pnpm test -- --run extend
+```
+
+## Baseline Results
+
+### Summary
+- **Test Files**: 7 failed | 5 passed (12 total)
+- **Tests**: 10 failed | 148 passed (158 total)
+- **Duration**: 659ms
+
+### Failing Tests (10)
+
+1. **src/tree/util/__tests__/process-extends.test.ts**
+   - Entire test file failed
+
+2. **src/tree/__tests__/extend-import-style.test.ts**
+   - `compose type can be extended from parent when mutable`
+   - `import with mutable: false cannot be extended - collects extendNotAccessible warning`
+
+3. **src/tree/__tests__/extend-roots.test.ts**
+   - `child compose root cannot extend parent (compose is a boundary) - extend throws error`
+   - `children roots are accessible if mutable`
+
+4. **src/tree/__tests__/extend-rules.test.ts**
+   - `should ignore self-referencing extends: .w:extend(.w)`
+
+5. **src/tree/util/__tests__/extend-duplicate-validation.test.ts**
+   - `should allow duplicate same ID selectors for specificity (#foo#foo)`
+   - `should allow extending #foo with #foo (same ID)`
+
+6. **src/tree/util/__tests__/extend-selector-algorithm.test.ts**
+   - `should extend complex partial match with compound boundaries - example 6`
+   - Expected: `.a>.b.c>.d.e,.a>.f`
+   - Received: Different output
+
+7. **src/tree/util/__tests__/extend-simplified-cases.test.ts**
+   - `should extend with :is() selector - extract selectors from :is()`
+     - Expected: `.foo,.ext3,.ext4`
+     - Received: `.foo,:is(.ext3,.ext4)`
+   - `should extend with :is() selector in partial mode`
+     - Expected: `.foo :is(.bar,.ext3,.ext4)`
+     - Received: `.foo :is(.bar,:is(.ext3,.ext4))`
+
+## Notes
+
+- These failures appear to be pre-existing issues, not related to the refactoring
+- The `.foo.foo` bug is not currently tested, so we need to add a test case for it
+- Some failures are related to `:is()` flattening behavior
+- Some failures are related to duplicate ID selector handling
+
+## Next Steps
+
+1. Document these baseline failures
+2. Proceed with refactoring
+3. Verify that refactoring doesn't introduce new failures
+4. Fix the `.foo.foo` bug and add test case
+5. Address any new failures introduced by refactoring