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

package/src/tree/util/EXTEND_CALL_GRAPH_ANALYSIS.md

@@ -0,0 +1,244 @@
+# Extend.ts Call Graph Analysis
+
+## Analysis Method
+Tracing all function calls from exported entry points through the entire call graph.
+
+## Entry Points (Exported Functions)
+
+1. `tryExtendSelector` (line 700)
+2. `extendSelector` (line 731)
+3. `findChainedExtends` (line 2090)
+4. `applyExtensionAtLocation` (line 2152)
+
+## Complete Call Graph
+
+### From `tryExtendSelector`
+- `extendSelector()` ✅
+- `createSuccessResult()` ✅
+- `createErrorResult()` ✅
+
+### From `extendSelector`
+- `findExtendableLocations()` ✅ (external)
+- `checkAmpersandCrossingDuringExtension()` ✅
+- `handleAmpersandBoundaryCrossing()` ✅
+- `detectAndHandleBoundaryCrossing()` ✅
+- `extendSelectorList()` ✅
+- `selectBestLocation()` ✅
+- `handlePartialModeExtension()` ✅
+- `handleFullExtend()` ✅
+- `applyExtensionAtLocation()` ✅
+- `createExtendedSelectorList()` ✅
+
+### From `extendSelectorList`
+- `findExtendableLocations()` ✅ (external)
+- `extendSelector()` ✅ (recursive)
+- `createExtendedSelectorList()` ✅
+
+### From `selectBestLocation`
+- None (pure function)
+
+### From `handlePartialModeExtension`
+- `createValidatedIsWrapperWithErrors()` ✅
+- `createValidatedCompoundSelectorWithErrors()` ✅
+- `createIsWrapper()` ✅
+- `ComplexSelector.create()` ✅
+- `applyExtensionAtLocation()` ✅
+
+### From `handleFullExtend`
+- `createExtendedSelectorList()` ✅
+- `SelectorList.create()` ✅
+- `PseudoSelector.create()` ✅
+
+### From `handleCompoundFullExtend`
+- `detectAndHandleBoundaryCrossing()` ✅
+- `getIsSelectorArg()` ✅
+- `findExtendableLocations()` ✅ (external)
+- `extendWithinIsArg()` ✅
+- `createIsWrapper()` ✅
+- `createValidatedCompoundSelectorWithErrors()` ✅
+- `createExtendedSelectorList()` ✅
+
+**BUT**: `handleCompoundFullExtend` itself is **NEVER CALLED** ❌
+
+### From `createIsWrapper`
+- `deduplicateSelectors()` ✅
+- `SelectorList.create()` ✅
+- `PseudoSelector.create()` ✅
+
+### From `createValidatedIsWrapper`
+- `createValidatedIsWrapperWithErrors()` ✅
+
+**BUT**: `createValidatedIsWrapper` itself is **NEVER CALLED** ❌
+
+### From `createValidatedIsWrapperWithErrors`
+- `validateIsWrapper()` ✅
+- `createIsWrapper()` ✅
+
+### From `validateIsWrapper`
+- None (pure validation)
+
+### From `checkAmpersandCrossingDuringExtension`
+- `findAmpersandsInSelector()` ✅
+- `replaceAmpersandWithItsValue()` ✅
+- `replaceAmpersandWithEmpty()` ✅
+- `findExtendableLocations()` ✅ (external)
+
+### From `findAmpersandsInSelector`
+- `selector.nodes()` ✅ (method)
+
+### From `replaceAmpersandWithItsValue`
+- `selector.copy()` ✅ (method)
+- `ampersand.value.selector.copy()` ✅ (method)
+- `selectorCopy.nodes()` ✅ (method)
+- `findParentOfNode()` ✅
+- `replaceNodeInParent()` ✅
+
+### From `replaceAmpersandWithEmpty`
+- `selector.copy()` ✅ (method)
+- `selectorCopy.nodes()` ✅ (method)
+- `findParentOfNode()` ✅
+
+### From `handleAmpersandBoundaryCrossing`
+- `replaceAmpersandWithItsValue()` ✅
+- `extendSelector()` ✅ (recursive)
+- `markSelectorForHoisting()` ✅
+
+### From `findParentOfNode`
+- `root.nodes()` ✅ (method)
+
+### From `replaceNodeInParent`
+- None (direct mutation)
+
+### From `markSelectorForHoisting`
+- `selector.copy()` ✅ (method)
+
+### From `detectAndHandleBoundaryCrossing`
+- `findExtendableLocations()` ✅ (external)
+- `createFlattenedBoundaryCrossingResult()` ✅
+
+### From `createFlattenedBoundaryCrossingResult`
+- `CompoundSelector.create()` ✅
+- `createExtendedSelectorList()` ✅
+
+### From `getIsSelectorArg`
+- None (pure check)
+
+**BUT**: Only called from `handleCompoundFullExtend` which is unused ❌
+
+### From `extendWithinIsArg`
+- `extendSelector()` ✅ (recursive)
+
+**BUT**: Only called from `handleCompoundFullExtend` which is unused ❌
+
+### From `flattenGeneratedIs`
+- `flattenGeneratedIsInSelector()` ✅
+
+### From `flattenGeneratedIsInSelector`
+- `optimizeUnnecessaryIsWrapper()` ✅
+- `flattenGeneratedIs()` ✅ (recursive)
+- `SelectorList.create()` ✅
+- `CompoundSelector.create()` ✅
+- `ComplexSelector.create()` ✅
+- `PseudoSelector` constructor ✅
+
+### From `optimizeUnnecessaryIsWrapper`
+- None (pure optimization)
+
+### From `createProcessedSelector`
+- `createProcessedSelector()` ✅ (recursive)
+- `SelectorList.create()` ✅
+- `CompoundSelector.create()` ✅
+- `ComplexSelector.create()` ✅
+
+### From `createExtendedSelectorList`
+- `createProcessedSelector()` ✅
+- `SelectorList.create()` ✅
+
+### From `deduplicateSelectors`
+- None (pure function)
+
+### From `createValidatedCompoundSelector`
+- `createValidatedCompoundSelectorWithErrors()` ✅
+
+**BUT**: `createValidatedCompoundSelector` itself is **NEVER CALLED** ❌
+
+### From `createValidatedCompoundSelectorWithErrors`
+- `validateCompoundSelector()` ✅
+- `CompoundSelector.create()` ✅
+
+### From `validateCompoundSelector`
+- `validateCompoundSelector()` ✅ (recursive)
+
+### From `isValidCompoundSelector`
+- `isValidCompoundSelector()` ✅ (recursive)
+
+**Note**: `isValidCompoundSelector` is called from `validateCompoundSelector`... wait, let me check line 1955 again.
+
+Actually, looking at the code:
+- Line 1955: `isValidCompoundSelector` calls itself recursively
+- But `validateCompoundSelector` does NOT call `isValidCompoundSelector`
+- So `isValidCompoundSelector` is **UNUSED** ❌
+
+### From `applyExtensionAtLocation`
+- `applyExtensionAtPath()` ✅
+
+### From `applyExtensionAtPath`
+- `applyExtension()` ✅
+- `SelectorList.create()` ✅
+- `CompoundSelector.create()` ✅
+- `ComplexSelector.create()` ✅
+- `PseudoSelector.create()` ✅
+
+### From `applyExtension`
+- `SelectorList.create()` ✅
+- `PseudoSelector.create()` ✅
+
+## Unused Functions Summary
+
+### Confirmed Unused (Never Called)
+
+1. **`handleCompoundFullExtend`** (lines 1396-1477)
+   - Never called from anywhere
+   - Comment says it's for "special cases" but those cases are handled inline in `extendSelector`
+   - **Recommendation**: REMOVE
+
+2. **`createValidatedIsWrapper`** (lines 1517-1533)
+   - Never called - only `createValidatedIsWrapperWithErrors` is used
+   - **Recommendation**: REMOVE
+
+3. **`createValidatedCompoundSelector`** (lines 1972-1989)
+   - Never called - only `createValidatedCompoundSelectorWithErrors` is used
+   - **Recommendation**: REMOVE
+
+4. **`isValidCompoundSelector`** (lines 1936-1962)
+   - Never called - `validateCompoundSelector` has its own implementation
+   - **Recommendation**: REMOVE
+
+### Functions Only Used by Unused Functions
+
+5. **`getIsSelectorArg`** (lines 459-468)
+   - Only called from `handleCompoundFullExtend` (unused)
+   - **Recommendation**: REMOVE (unless needed elsewhere - check if it's a useful utility)
+
+6. **`extendWithinIsArg`** (lines 479-486)
+   - Only called from `handleCompoundFullExtend` (unused)
+   - **Recommendation**: REMOVE (it's just a thin wrapper around `extendSelector`)
+
+## Functions That ARE Used
+
+- All other functions are part of the active call graph
+- `validateCompoundSelector` is used (not `isValidCompoundSelector`)
+- `createValidatedIsWrapperWithErrors` is used (not `createValidatedIsWrapper`)
+- `createValidatedCompoundSelectorWithErrors` is used (not `createValidatedCompoundSelector`)
+
+## Recommendation
+
+Remove the following unused functions:
+1. `handleCompoundFullExtend` (~82 lines)
+2. `createValidatedIsWrapper` (~17 lines)
+3. `createValidatedCompoundSelector` (~18 lines)
+4. `isValidCompoundSelector` (~27 lines)
+5. `getIsSelectorArg` (~10 lines) - unless it's a useful utility
+6. `extendWithinIsArg` (~8 lines)
+
+**Total lines to remove**: ~162 lines

package/src/tree/util/EXTEND_DOCS.md

@@ -0,0 +1,24 @@
+---
+title: Extend docs index (canonical)
+---
+
+# Extend docs (canonical index)
+
+This directory accumulated many “working notes” over time. To keep things navigable, the **canonical** extend documentation is intentionally small:
+
+## Canonical docs to keep current
+
+- **Rules of extend**: `EXTEND_RULES.md`
+- **Where are the tests / where to add coverage**: `__tests__/EXTEND_TEST_INDEX.md`
+- **Implementation**: `extend.ts` (header comments)
+
+## Where to put operational/debug workflows
+
+Operational “what commands to run / what to read first” guidance should live in Cursor-native files so it auto-loads when editing extend code:
+
+- `.cursor/rules/subtrees/core__extend.mdc`
+
+## Historical notes
+
+Older audits, refactoring summaries, and one-off debugging notes were removed or archived to reduce noise. Use **git history** if you need to resurrect prior analysis.
+

package/src/tree/util/EXTEND_FINAL_SUMMARY.md

@@ -0,0 +1,95 @@
+# Extend Refactoring - Final Summary
+
+## Date
+2025-01-XX
+
+## Completed Work
+
+### Phase 1: Fixed `.foo.foo` Bug ✅
+- Updated `searchWithinCompoundSelector` to create unique paths for each matching component
+- Updated `extendSelector` to process ALL matching locations (not just first)
+- Added test cases verifying the fix
+
+### Phase 2: Removed Duplicate Code ✅
+- Consolidated `applyExtension` functions into `extend.ts`
+- Removed ~150 lines of duplicate code from `find-extendable-locations.ts`
+
+### Phase 3: Consolidated Normalization ✅
+- Simplified `createIsWrapper` to remove redundant flattening pass
+- Normalization now happens in single pass via `createProcessedSelector`
+
+### Phase 4: Reduced Node Copying ✅
+- Implemented copy-on-write in `createProcessedSelector`
+- Optimized SelectorList handling to avoid cloning unchanged selectors
+
+### Phase 5: Added Search Caching ✅
+- Implemented WeakMap-based caching for search results
+- Avoids re-searching same selector pairs
+
+### Phase 6: Split `extendSelector` ✅
+- Extracted `extendSelectorList` for SelectorList handling
+- Extracted `selectBestLocation` for location selection logic
+- Improved code organization and maintainability
+
+### Phase 7: Fast Path Optimization ✅
+- Already correctly handled duplicate components
+- No changes needed
+
+### Bonus: Removed Unused Functions ✅
+- Removed 6 unused functions (~162 lines):
+  - `handleCompoundFullExtend`
+  - `createValidatedIsWrapper`
+  - `createValidatedCompoundSelector`
+  - `isValidCompoundSelector`
+  - `getIsSelectorArg`
+  - `extendWithinIsArg`
+
+## Test Results
+
+### Baseline
+- Test Files: 7 failed | 5 passed (12 total)
+- Tests: 10 failed | 148 passed (158 total)
+
+### After Refactoring
+- Test Files: 7 failed | 5 passed (12 total)
+- Tests: 10 failed | 150 passed (160 total)
+
+**Key Success**: 
+- ✅ `.foo.foo` bug fixed (2 new tests added, both passing)
+- ✅ No new regressions introduced
+- ✅ Same number of failures as baseline
+
+## Code Quality Improvements
+
+1. **Reduced Code**: Removed ~312 lines total (150 duplicates + 162 unused)
+2. **Better Organization**: Split large functions into smaller, focused ones
+3. **Performance**: Added caching, reduced copying, consolidated passes
+4. **Maintainability**: Clearer function responsibilities, removed dead code
+5. **Bug Fix**: Fixed critical `.foo.foo` partial match bug
+
+## Documentation Created
+
+1. `EXTEND_FUNCTION_AUDIT.md` - Comprehensive function-by-function analysis
+2. `EXTEND_BASELINE.md` - Baseline test results
+3. `EXTEND_REFACTORING_SUMMARY.md` - Summary of all changes
+4. `EXTEND_CALL_GRAPH_ANALYSIS.md` - Call graph analysis identifying unused functions
+5. `EXTEND_UNUSED_FUNCTIONS.md` - Detailed unused function analysis
+6. `EXTEND_FINAL_SUMMARY.md` - This document
+
+## Files Modified
+
+- `extend.ts`: Fixed bug, removed duplicates, consolidated normalization, reduced copying, split functions, removed unused code
+- `find-extendable-locations.ts`: Fixed bug, removed duplicates, added caching
+- `extend-selector-algorithm.test.ts`: Added `.foo.foo` test cases
+
+## Remaining Pre-Existing Issues
+
+Some test failures remain from baseline (not introduced by refactoring):
+- These appear to be pre-existing issues unrelated to the refactoring
+- Should be addressed separately
+
+## Next Steps
+
+1. Review remaining test failures (pre-existing)
+2. Consider additional optimizations based on profiling
+3. Update documentation as needed