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

package/src/tree/util/EXTEND_UNUSED_FUNCTIONS_ANALYSIS.md

@@ -0,0 +1,227 @@
+# Why Were These Unused Functions Created? - LLM Analysis
+
+## Overview
+Based on the EXTEND_AUDIT.md (dated 2024-12-19) and code analysis, these unused functions appear to be the result of an **incomplete refactoring attempt** where an LLM tried to extract and consolidate logic but never fully integrated the new functions.
+
+## Pattern: Incomplete Refactoring
+
+The unused functions fall into two categories:
+1. **Extraction attempts** - Functions created to consolidate scattered logic, but the original inline code was never replaced
+2. **Defensive programming** - Functions created "just in case" for error handling scenarios that never materialized
+
+---
+
+## 1. `handleCompoundFullExtend` - Extraction Attempt
+
+### Why It Was Created
+Looking at the EXTEND_AUDIT.md and code comments, this function was created to:
+- **Consolidate compound selector handling in full mode**
+- Handle the special case of compound selectors containing `:is()` pseudo-selectors
+- Process all matching components (including `:is()` matches) in a single loop
+- Provide a cleaner separation of concerns
+
+### The Problem
+The comment at line 1376 says: *"handleCompoundFullExtend is only for special cases like extending within :is() pseudo-selectors"*
+
+But the actual logic for compound selectors in full mode is **already handled inline** in `extendSelector` at lines 1160-1203. The function was created but **never called** - the inline implementation was kept instead.
+
+### LLM Reasoning Pattern
+An LLM likely:
+1. Saw the complex inline logic for compound selectors in full mode
+2. Thought "this should be extracted into a function for clarity"
+3. Created `handleCompoundFullExtend` with the extracted logic
+4. **Forgot to actually call it** or decided the inline version was better
+5. Left both versions in the code
+
+This is a classic "extract function but forget to use it" pattern.
+
+---
+
+## 2. `createValidatedIsWrapper` - Defensive Programming / Alternative Approach
+
+### Why It Was Created
+From EXTEND_AUDIT.md line 38-53:
+- Created as a **fallback mechanism** for validation errors
+- Returns fallback selector instead of throwing
+- Has context-aware validation
+
+### The Problem
+The codebase **always throws errors** on validation failures (using `createValidatedIsWrapperWithErrors`). The fallback behavior was never needed or used.
+
+### LLM Reasoning Pattern
+An LLM likely:
+1. Thought "what if validation fails? Should we have a fallback?"
+2. Created the fallback version "just in case"
+3. But the actual code always uses the throwing version
+4. The fallback version was never integrated
+
+This is **defensive programming gone wrong** - creating functionality "just in case" that never gets used.
+
+---
+
+## 3. `createValidatedCompoundSelector` - Same Pattern
+
+### Why It Was Created
+Same as `createValidatedIsWrapper`:
+- Fallback mechanism for compound selector validation
+- Returns fallback instead of throwing
+
+### The Problem
+Only `createValidatedCompoundSelectorWithErrors` (which throws) is used. The fallback version was never needed.
+
+### LLM Reasoning Pattern
+Same defensive programming pattern - created as an alternative approach that was never adopted.
+
+---
+
+## 4. `isValidCompoundSelector` - Legacy / Duplicate Implementation
+
+### Why It Was Created
+This function appears to be a **simpler, older version** of `validateCompoundSelector`:
+- Returns boolean instead of detailed error information
+- Simpler implementation (just counts elements/IDs)
+- Recursive for nested compounds
+
+### The Problem
+`validateCompoundSelector` (lines 2022-2069) has its own complete implementation that:
+- Returns detailed error information
+- Has better error messages
+- Is actually used throughout the codebase
+
+`isValidCompoundSelector` was likely the **original implementation** that was replaced by `validateCompoundSelector`, but never removed.
+
+### LLM Reasoning Pattern
+An LLM likely:
+1. Started with `isValidCompoundSelector` (simple boolean check)
+2. Realized it needed more detailed error information
+3. Created `validateCompoundSelector` with better error reporting
+4. **Forgot to remove the old version**
+
+This is a **refactoring artifact** - old code left behind after improvement.
+
+---
+
+## 5. `getIsSelectorArg` - Utility Function for Unused Code
+
+### Why It Was Created
+A simple utility to extract the `:is()` argument from a component:
+- Checks if component is `:is()` pseudo-selector
+- Returns the SelectorList argument if valid
+- Clean, reusable utility
+
+### The Problem
+Only used by `handleCompoundFullExtend`, which itself is unused. The utility is fine, but it's **orphaned** because its only consumer was never integrated.
+
+### LLM Reasoning Pattern
+Created as a helper for `handleCompoundFullExtend`. When `handleCompoundFullExtend` wasn't integrated, this utility became orphaned.
+
+---
+
+## 6. `extendWithinIsArg` - Thin Wrapper for Unused Code
+
+### Why It Was Created
+A thin wrapper around `extendSelector` for extending within `:is()` arguments:
+- Sets specific flags (`partial: false`, `skipAmpersandCheck: true`, `hasMoreAfterIs`)
+- Provides a clean API for this specific use case
+
+### The Problem
+Only used by `handleCompoundFullExtend`, which is unused. The wrapper is fine, but **orphaned** like `getIsSelectorArg`.
+
+### LLM Reasoning Pattern
+Created as a convenience wrapper for `handleCompoundFullExtend`. When that function wasn't integrated, this became orphaned.
+
+---
+
+## Root Cause Analysis
+
+### Why LLMs Create Unused Functions
+
+1. **Incomplete Refactoring**
+   - Extract logic into a function
+   - Forget to replace the original code with a call to the new function
+   - Both versions remain in the codebase
+
+2. **Defensive Programming**
+   - Create alternative implementations "just in case"
+   - Never actually use them because the primary approach works fine
+   - Leave them in "for future use" that never comes
+
+3. **Refactoring Artifacts**
+   - Create improved version of a function
+   - Forget to remove the old version
+   - Both remain in codebase
+
+4. **Orphaned Dependencies**
+   - Create helper functions for a main function
+   - Main function never gets integrated
+   - Helpers become orphaned
+
+### Common LLM Patterns
+
+1. **"Extract but don't integrate"** - Creates cleaner functions but doesn't replace inline code
+2. **"Create alternatives"** - Makes multiple versions (with/without errors, with/without fallbacks)
+3. **"Forget to clean up"** - Leaves old versions when creating new ones
+4. **"Build infrastructure"** - Creates utilities for functions that never get used
+
+### Why This Happens
+
+LLMs often:
+- Focus on **creating** code more than **integrating** it
+- Create multiple approaches and forget to choose one
+- Don't trace through the full call graph to verify integration
+- Leave "just in case" code that seems useful but never gets used
+
+---
+
+## Lessons Learned
+
+1. **Always trace the call graph** - Verify functions are actually called
+2. **Remove old versions** - When creating improved versions, remove the old ones
+3. **Choose one approach** - Don't create multiple alternatives without choosing
+4. **Complete refactorings** - If extracting logic, actually replace the original
+5. **Avoid "just in case" code** - Only create what's actually needed
+
+---
+
+## Summary
+
+These unused functions represent **incomplete refactoring attempts** where:
+- Logic was extracted but never integrated (`handleCompoundFullExtend`)
+- Alternative approaches were created but never adopted (`createValidatedIsWrapper`, `createValidatedCompoundSelector`)
+- Old versions were left behind when new ones were created (`isValidCompoundSelector`)
+- Helper functions were orphaned when their consumers weren't integrated (`getIsSelectorArg`, `extendWithinIsArg`)
+
+### Evidence from EXTEND_AUDIT.md (2024-12-19)
+
+The audit document shows a similar pattern with `handleFullExtend`:
+- **Was marked as UNUSED** in the audit
+- **Was recommended to be INTEGRATED** (line 209: "SHOULD BE INTEGRATED")
+- **Actually WAS integrated** - it's now called at line 1054 in `extendSelector`
+
+This shows the pattern: an LLM created `handleFullExtend`, it was identified as unused, then **later integrated**. But `handleCompoundFullExtend` followed the same pattern and **never got integrated**.
+
+### The Pattern
+
+1. **First attempt**: Create `handleFullExtend` - initially unused, later integrated ✅
+2. **Second attempt**: Create `handleCompoundFullExtend` - created but never integrated ❌
+3. **Result**: One function integrated, one left behind
+
+This suggests **multiple refactoring sessions** where:
+- Some functions got integrated (`handleFullExtend`)
+- Others were created but forgotten (`handleCompoundFullExtend`)
+- The integration was incomplete
+
+### Why This Happens to LLMs
+
+1. **Session boundaries** - Different refactoring sessions, incomplete integration
+2. **Scope creep** - Start extracting one function, create others, forget to finish
+3. **Copy-paste patterns** - See `handleFullExtend` works, create `handleCompoundFullExtend` similarly, but forget to call it
+4. **Incomplete testing** - Create functions, test passes (because old code still works), forget to integrate
+
+The pattern suggests an LLM was trying to improve code organization but didn't complete the refactoring by:
+1. Actually calling the new functions
+2. Removing the old implementations  
+3. Cleaning up orphaned dependencies
+4. Following through on all extraction attempts, not just some
+
+This is a common issue when refactoring - it's easy to create new code, harder to fully integrate it and remove the old. The fact that `handleFullExtend` WAS integrated shows the intent was there, but the follow-through was incomplete.

package/src/tree/util/NODE_COPY_REDUCTION_PLAN.md

@@ -0,0 +1,12 @@
+# Node Copy Reduction Plan
+
+The canonical dev-facing docs for this plan now live under root `docs/`.
+
+Read these instead:
+
+- `docs/future/node-copy-reduction/README.md`
+- `docs/future/node-copy-reduction/migration.md`
+- `docs/future/node-copy-reduction/subsystems.md`
+
+This package-local file is left only as a pointer because the work applies across
+the eval/runtime architecture, not just `packages/core/src/tree/util`.

package/src/tree/util/__tests__/EXTEND_TEST_INDEX.md

@@ -0,0 +1,59 @@
+# Extend test index (core)
+
+This doc exists to make **extend-related tests** easy to find (especially for LLM-assisted debugging).
+
+**Before changing extend logic:** See `../EXTEND_RULES.md` for the single set of rules and the header comments in `../extend.ts` for implementation context. Keep operational “what to run / where to look” guidance in Cursor-native files (e.g. `.cursor/rules/subtrees/core__extend.mdc`).
+
+Historical deep-dive audits and refactoring notes were archived/removed from this directory to reduce noise; use git history if you need them.
+
+## “Where are the extend tests?”
+
+There are two main clusters:
+
+### 1) Extend **integration** tests (eval → toString)
+- `src/tree/__tests__/extend-eval-integration.test.ts`
+  - High-level behavior checks across eval + serialization.
+  - Includes the rule: **Exact extend matches a single OR-branch** (does not require all `:is(...)` branches).
+
+### 2) Extend **utility / algorithm** tests
+Located in `src/tree/util/__tests__/`:
+
+- `extend-core-unit.test.ts`
+  - Main focused unit suite for the rebuilt `tryExtendSelector()` path in `extend-core.ts`.
+  - This is the current source of truth for exact vs partial rewriting, ampersand crossing/hoisting, and seam-aware rewrite behavior.
+
+- `selector-match-unit.test.ts`
+  - Main focused unit suite for `selectorMatch()` in `selector-match-core.ts`.
+  - This is the current source of truth for selector comparison/matching semantics, alternates, pseudo boundaries, and ampersand crossing detection.
+
+- `extend-comment-handling.test.ts`
+  - Legacy-but-still-distinct coverage for comment preservation/duplication behavior.
+
+- `extend-ampersand-boundary.test.ts`
+  - Legacy boundary-oriented tests that still exercise nested/ruleset-level ampersand behavior.
+
+- `process-extends.test.ts`
+  - Tests orchestration / application ordering for registered extends.
+
+- `extend-pipeline-bench.test.ts`
+  - Bench coverage, not a primary behavior suite.
+
+## Extend evaluation / ruleset plumbing (non-util tests)
+
+- `src/tree/__tests__/extend-rules.test.ts`
+  - Extend behavior inside rulesets; includes chaining-related expectations.
+
+- `src/tree/__tests__/extend-roots.test.ts`
+  - Extend root registry / hoisting behavior.
+
+- `src/tree/__tests__/extend-import-style.test.ts`
+  - Extend interaction with import-style logic.
+
+## What’s missing / where to add new coverage
+
+If you are fixing a fixture like `tests-unit/extend-exact/extend-exact.less`, the most “direct” core place to add a reproduction is:
+
+- `src/tree/__tests__/extend-eval-integration.test.ts` (if it’s an eval/print behavior)
+- `src/tree/util/__tests__/selector-match-unit.test.ts` (if it’s primarily a matcher problem)
+- `src/tree/util/__tests__/extend-core-unit.test.ts` (if it’s primarily a rewrite problem)
+- `src/tree/util/__tests__/extend-ampersand-boundary.test.ts` (if it’s specifically about implicit `&` / parent prefix crossings)

package/src/tree/util/__tests__/OPTIMIZATION-ANALYSIS.md

@@ -0,0 +1,130 @@
+# ExtendLocation API Optimization Analysis
+
+## Summary
+
+After migrating from the legacy `matchSelectors` API to the new `findExtendableLocations` API, we have successfully maintained and verified the performance optimizations that were crucial for the extend functionality. The optimization system provides significant performance improvements ranging from **1.3x to 31x speedup** depending on the scenario.
+
+## Benchmark Test Suite
+
+The comprehensive benchmark test suite in `selector-benchmark.test.ts` validates all optimization layers:
+
+## Optimization Layers Analysis
+
+### OPTIMIZATION 1: Exact Match Cache
+- **Performance**: 1.3x speedup for exact matches
+- **Purpose**: Cache identical selector matches to avoid redundant computation
+- **Impact**: Moderate improvement for exact matches, most beneficial for repeated operations
+
+### OPTIMIZATION 2 & 3: KeySet Fast Rejection  
+- **Performance**: 9.3x to 14.6x speedup for disjoint/non-subset selectors
+- **Purpose**: Early bailout for impossible matches using set theory
+- **Impact**: **Highest impact optimization** - eliminates expensive tree traversal for most non-matching cases
+
+### OPTIMIZATION 4: Fast Path Patterns
+- **Performance**: 1.6x to 4.8x speedup for common selector patterns
+- **Purpose**: Optimized algorithms for frequent CSS patterns (simple-to-simple, compound-to-simple, etc.)
+- **Impact**: Good improvement for typical CSS use cases
+
+## Real-World Performance Impact
+
+### Non-Matching Scenarios (Most Common)
+In real stylesheets, the vast majority of extend operations don't find matches. These scenarios show the most dramatic improvements:
+
+- **Simple different classes**: 5.4x speedup
+- **Different IDs**: 5.2x speedup  
+- **Disjoint compounds**: 10.6x speedup
+- **Complex different structures**: **31.0x speedup**
+
+### Overall Performance
+- **Average speedup across all scenarios**: 4.2x
+- **Best case speedup**: 31x (complex non-matching selectors)
+- **Worst case**: Still maintains correctness with minimal overhead
+
+## Why These Optimizations Are Worthwhile
+
+### 1. **Volume Characteristics**
+Real CSS stylesheets contain thousands of selectors, and extend operations are tested against most of them. A 10x speedup on operations that happen thousands of times results in massive compilation time savings.
+
+### 2. **Non-Match Dominance**  
+In typical extend scenarios, 90%+ of selector comparisons result in no match. Our optimizations are specifically designed to fast-reject these cases with minimal computation.
+
+### 3. **Complexity Scaling**
+Without optimizations, complex selectors with :is(), nested structures, and long combinator chains become exponentially expensive. The optimizations provide linear or near-constant time rejection for most cases.
+
+### 4. **Cache Locality**
+The KeySet optimization works on compact bit-sets rather than full AST traversal, providing better CPU cache performance.
+
+## Test Results Summary
+
+### KeySet Fast Rejection (Most Important)
+```
+🔥 OPTIMIZATION 2 & 3: KeySet Fast Rejection
+===============================================
+🏁 Disjoint selectors (with KeySet rejection)
+   Total: 10.26ms
+   Average: 0.0001ms per operation  
+   Ops/sec: 9,743,937
+🏁 Disjoint selectors (no KeySet rejection)
+   Total: 148.25ms
+   Average: 0.0015ms per operation
+   Ops/sec: 674,555
+   🚀 KeySet rejection speedup: 14.4x
+```
+
+### Fast Path Patterns  
+```
+🔥 OPTIMIZATION 4: Fast Path Patterns
+======================================
+🏁 Simple to Simple (with fast path)
+   Ops/sec: 8,629,182
+🏁 Simple to Simple (no fast path)  
+   Ops/sec: 2,039,328
+   🚀 Simple to Simple speedup: 4.2x
+
+🏁 Complex Selector (short) (with fast path)
+   Ops/sec: 11,296,670  
+🏁 Complex Selector (short) (no fast path)
+   Ops/sec: 2,345,454
+   🚀 Complex Selector speedup: 4.8x
+```
+
+### Non-Matching Scenarios (Real-World Critical)
+```
+🔥 NON-MATCHING SCENARIOS (Most Common)
+========================================
+🏁 Complex with different structure (optimized)
+   Ops/sec: 5,954,951
+🏁 Complex with different structure (unoptimized)  
+   Ops/sec: 192,076
+   🚀 Complex with different structure speedup: 31.0x
+```
+
+## Verification of Correctness
+
+All optimizations maintain semantic correctness:
+- ✅ Same `hasMatches` results between optimized and unoptimized paths
+- ✅ All existing extend algorithm tests pass (10/10)
+- ✅ Optimizations only affect performance, not behavior
+
+## Individual Optimization Testing
+
+The benchmark suite can disable each optimization individually:
+
+1. **`findExtendableLocationsNoExactCache`** - Bypasses exact match caching
+2. **`findExtendableLocationsNoKeySetRejection`** - Bypasses KeySet fast rejection  
+3. **`findExtendableLocationsNoFastPath`** - Bypasses fast path patterns
+4. **`findExtendableLocationsNoOptimizations`** - Bypasses all optimizations
+
+This allows us to measure the individual contribution of each optimization layer and verify that they work correctly in isolation.
+
+## Conclusion
+
+The optimization system migrated to the new ExtendLocation API is **highly effective** and **well-justified**:
+
+1. **Provides 4.2x average speedup** across diverse scenarios
+2. **Up to 31x speedup** for the most common case (non-matching complex selectors)  
+3. **Maintains perfect correctness** - all functionality tests pass
+4. **Scales well** - performance improves dramatically as selector complexity increases
+5. **Real-world impact** - optimizes the 90%+ case of non-matching selectors that dominate extend operations
+
+The optimizations are essential for making the extend functionality performant in real-world CSS codebases with thousands of selectors.

package/src/tree/util/__tests__/WALK_AND_CONSUME_DESIGN.md

@@ -0,0 +1,138 @@
+# Walk-and-Consume Algorithm Design
+
+## Current Architecture (3-Phase Pipeline)
+
+The current extend pipeline has three separate traversal phases:
+
+1. **Search**: `findExtendableLocations(target, find)` → walks the AST, collects `ExtendLocation[]`
+2. **Classify**: `selectorCompare(target, find)` → another traversal to determine match type
+3. **Apply**: `extendSelector(target, find, extendWith, partial)` → uses locations to decide
+   what transformation to apply, then constructs new AST nodes
+
+### Where the Time Goes
+
+| Hotspot | Cause | Status |
+|---------|-------|--------|
+| `applyExtendsToSelector` growing list | O(N²) for N same-target instructions | **Fixed** (batched) |
+| `selectorCompare` SelectorList sort | O(N log N) per comparison | **Fixed** (Set-based) |
+| `areCompoundSelectorsEquivalent` expansion | (N+1)^K combinatorial explosion | **Fixed** (pointer walk) |
+| `processExtends` per-instruction diagnostics | O(I) × cost_per_extend per ruleset | **Not fixed** |
+| Triple traversal per extend call | search + classify + apply | **Not fixed** |
+
+## Walk-and-Consume Design
+
+### Core Idea
+
+Replace the 3-phase pipeline with a single recursive descent that:
+1. Walks the target selector tree (depth-first)
+2. At each node, checks if it matches `find`
+3. If it matches, **immediately transforms** it (wrap in `:is()`, add to list, etc.)
+4. Returns the transformed (or original) node
+
+### Context Threading
+
+The transformation depends on context. The walker carries a `WalkContext`:
+
+```typescript
+interface WalkContext {
+  /** Are we at the top-level selector (not inside a compound/complex/pseudo)? */
+  isRoot: boolean;
+  /** Parent node type */
+  parentType: 'SelectorList' | 'ComplexSelector' | 'CompoundSelector' | 'PseudoSelector' | null;
+  /** Is there content before this node in the parent container? */
+  hasContentBefore: boolean;
+  /** Is there content after this node in the parent container? */
+  hasContentAfter: boolean;
+  /** Index within parent container */
+  indexInParent: number;
+}
+```
+
+### Transformation Rules (Context → Action)
+
+| Context | Partial Mode | Full Mode |
+|---------|-------------|-----------|
+| Root, whole match | SelectorList(target, extendWith) | SelectorList(target, extendWith) |
+| Inside CompoundSelector | `:is(matched, extendWith)` + rest | reject (return unchanged) |
+| Inside ComplexSelector | `:is(matched, extendWith)` + rest | `:is(matched, extendWith)` + rest |
+| Inside PseudoSelector arg | recurse into arg | recurse into arg (with boundary check) |
+| Inside SelectorList | extend each matching item | extend each matching item |
+
+### Implementation Strategy
+
+Rather than rewriting the entire 3600-line file at once, we implement incrementally:
+
+#### Phase 1: Unified `walkAndExtend` for Simple Cases
+- SimpleSelector target + SimpleSelector find (most common case)
+- Handles: root match, inside SelectorList, inside CompoundSelector, inside ComplexSelector
+- Bypasses: ampersand crossing, boundary crossing, `:is()` normalization
+- **Test**: run all 941 tests, fall back to old path for complex cases
+
+#### Phase 2: Compound and Complex find selectors
+- CompoundSelector find (e.g., `.a.b:extend(.a.b)`)
+- ComplexSelector find (e.g., `.a .b:extend(.a .b)`)
+
+#### Phase 3: Batch multi-instruction walk
+- Walk once, apply ALL matching instructions simultaneously
+- Eliminates the per-instruction diagnostic loop in `processExtends`
+- Key for Bootstrap performance
+
+#### Phase 4: Remove old code paths
+- Once all cases are covered and tests pass, remove the 3-phase pipeline
+
+### Phase 1 Implementation Detail
+
+```typescript
+function walkAndExtend(
+  target: Selector,
+  find: Selector,
+  extendWith: Selector,
+  partial: boolean,
+  ctx: WalkContext
+): Selector {
+  // 1. Check for exact match at this node
+  if (componentsMatch(target, find)) {
+    return applyTransformation(target, find, extendWith, partial, ctx);
+  }
+
+  // 2. Recurse into container nodes
+  if (isNode(target, 'SelectorList')) {
+    return walkSelectorList(target, find, extendWith, partial, ctx);
+  }
+  if (isNode(target, 'ComplexSelector')) {
+    return walkComplexSelector(target, find, extendWith, partial, ctx);
+  }
+  if (isNode(target, 'CompoundSelector')) {
+    return walkCompoundSelector(target, find, extendWith, partial, ctx);
+  }
+  if (isNode(target, 'PseudoSelector') && target.value.arg) {
+    return walkPseudoSelector(target, find, extendWith, partial, ctx);
+  }
+
+  // 3. No match, return unchanged
+  return target;
+}
+```
+
+### Key Invariant
+
+The walk-and-consume MUST produce identical output to the current pipeline for all
+existing test cases. Unit tests serve as the guardrail — any behavioral difference
+is a bug in the new implementation.
+
+### Boundary Between Old and New
+
+During incremental rollout, `extendSelector` becomes a dispatcher:
+
+```typescript
+function extendSelector(target, find, extendWith, partial, ...): Selector {
+  // Try walk-and-consume for supported cases
+  if (canUseWalkAndConsume(target, find)) {
+    return walkAndExtend(target, find, extendWith, partial, ROOT_CTX);
+  }
+  // Fall back to existing 3-phase pipeline
+  return extendSelectorLegacy(target, find, extendWith, partial, ...);
+}
+```
+
+This lets us expand coverage gradually while maintaining correctness.

package/src/tree/util/__tests__/_archive/2026-02-09__OPTIMIZATION-ANALYSIS.md

@@ -0,0 +1,9 @@
+# ExtendLocation API Optimization Analysis (archived)
+
+This file used to exist in `__tests__/` as a long-form analysis.
+
+It duplicated the package-root analysis, so it was archived once at:
+
+- `packages/core/_archive/2026-02-09__OPTIMIZATION-ANALYSIS.md`
+
+

package/src/tree/util/__tests__/_archive/README.md

@@ -0,0 +1,4 @@
+# Archived docs (`packages/core/src/tree/util/__tests__`)
+
+This folder holds dated snapshots of ad-hoc notes that used to live alongside tests.
+