@codeyam/codeyam-cli 0.1.0-staging.79ef713 → 0.1.0-staging.7c30edc

package/codeyam-cli/templates/codeyam:memory.md

@@ -13,19 +13,14 @@ This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that
 
 ## Core Principle: Document Confusion, Not Information
 
-**Good rules** explain things that are NOT obvious from reading the code:
+**Valuable rules** capture knowledge that reading the code alone wouldn't reveal:
 
 - Historical context (why code evolved this way)
 - Hidden relationships (files that must change together)
 - Gotchas that caused bugs
 - Non-obvious conventions
 
-**Bad rules** document things Claude can easily ascertain:
-
-- What functions do (Claude can read the code)
-- Type definitions (Claude can see them)
-- Directory structure (Claude can explore it)
-- Basic patterns (Claude knows common patterns)
+Skip documenting things Claude can determine by reading code: function signatures, type definitions, directory structure, and common patterns.
 
 ## When to Use This Skill
 
@@ -275,7 +270,7 @@ Before generating each rule, verify it passes these tests:
 
 **2. Code-derivable check**: Read the files the rule will cover. Could the rule's content be determined by reading those files alone?
 
-- If YES → rule probably not needed (Claude can read the code)
+- If YES → the code is its own documentation — prefer keeping rules for non-derivable insights
 - If NO (historical context, edge cases, non-obvious behavior) → rule is valuable
 
 **3. Prevention check**: Would this rule have prevented one of the confusion commits you found?
@@ -301,7 +296,7 @@ This caused a bug where `entity` matched `entityCode` (siblings, not parent-chil
 - Not code-derivable: Code doesn't explain why boundary checking matters
 - Prevention: Would prevent future prefix-matching bugs
 
-**❌ Bad rule** (fails tests):
+**Compare with a weaker alternative** (fails the checks):
 
 ```markdown
 ## Running Tests
@@ -309,9 +304,7 @@ This caused a bug where `entity` matched `entityCode` (siblings, not parent-chil
 Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
 ```
 
-- No confusion evidence (no commits showing people struggled with this)
-- Code-derivable: Anyone can see `jest.config.ts` exists
-- Doesn't prevent any confusion
+- No confusion evidence, code-derivable, and wouldn't prevent future mistakes
 
 ### 5B. Rule File Guidelines
 
@@ -319,17 +312,13 @@ Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
    - Rule for `src/api/` → `.claude/rules/src/api/architecture.md`
    - Rule for testing patterns → `.claude/rules/testing-patterns.md`
 
-2. **Paths must be specific**
-   - Good: `paths: ['src/api/**/*.ts']`
-   - Bad: `paths: ['**/*.ts']` (too broad, wastes context)
+2. **Paths must be specific** — use `paths: ['src/api/**/*.ts']` rather than `'**/*.ts'` (too broad wastes context)
 
 3. **Content should explain "why" not just "what"**
    - Focus on the reasoning, history, or gotcha
    - Be concise - every word costs context
 
-4. **Timestamp must be current**
-   - Use ISO 8601 format: `2026-01-27T15:30:00Z`
-   - This enables the pre-commit hook enforcement
+4. **Audit dates live in `.claude/codeyam-rule-state.json`** (managed by `codeyam memory touch`). Keep rule frontmatter limited to `paths`.
 
 ### Rule Template
 
@@ -337,7 +326,6 @@ Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
 ---
 paths:
   - 'specific/path/**/*.ts'
-timestamp: [CURRENT_ISO_TIMESTAMP]
 ---
 
 ## [Clear, Descriptive Title]
@@ -394,11 +382,11 @@ After generating rules based on your analysis and user answers:
 The pre-commit hook **blocks commits** when:
 
 - Code files matching a rule's `paths` are modified
-- The rule's `timestamp` is older than the code changes
+- The rule's `lastAuditedAt` in `.claude/codeyam-rule-state.json` is older than the code changes
 
 To proceed:
 
 1. Review the flagged rule(s)
 2. Update content if needed
-3. Update the `timestamp` to current time
+3. Run `codeyam memory touch` to mark rules as audited in `.claude/codeyam-rule-state.json`
 4. Stage and commit

package/codeyam-cli/templates/codeyam:setup.md

@@ -52,6 +52,18 @@ codeyam validate-mock .codeyam/universal-mocks/{path-to-your-mock}
 
 ## Setup Workflow
 
+### Step 0: Ensure Simulation Infrastructure
+
+Before configuring the dev server or mocks, ensure the simulation infrastructure is installed.
+
+```bash
+codeyam setup-simulations
+```
+
+This is **idempotent** — if already set up, each step is detected and skipped. On first run it installs analyzer dependencies, Playwright chromium, and creates baseline entities (several minutes). Subsequent runs complete in seconds.
+
+If it fails with "No web applications found", the project doesn't support simulations — inform the user and stop.
+
 ### Step 1: Configure Webapp Start Command
 
 **ACTION 1:** Read configuration files:

package/codeyam-cli/templates/rule-reflection-hook.py

@@ -120,6 +120,33 @@ def read_rule_content(rule_name):
     return text
 
 
+def load_memory_settings():
+    """
+    Load memory settings from .codeyam/config.json.
+    Returns dict with safe defaults when absent or malformed.
+    """
+    defaults = {
+        'conversationReflection': True,
+        'ruleMaintenance': True,
+        'promptModel': 'haiku',
+    }
+    try:
+        project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+        config_path = os.path.join(project_dir, '.codeyam', 'config.json')
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+        memory = config.get('memory', {})
+        if not isinstance(memory, dict):
+            return defaults
+        return {
+            'conversationReflection': memory.get('conversationReflection', True),
+            'ruleMaintenance': memory.get('ruleMaintenance', True),
+            'promptModel': memory.get('promptModel', 'haiku'),
+        }
+    except (IOError, json.JSONDecodeError, KeyError):
+        return defaults
+
+
 def get_stale_rules():
     """
     Run `codeyam memory status` and parse the output to find stale rules.
@@ -157,8 +184,8 @@ def get_stale_rules():
                 # Look for the next few lines for details
                 for j in range(i + 1, min(i + 4, len(lines))):
                     detail = lines[j].strip()
-                    if detail.startswith('Rule timestamp:'):
-                        rule_info['rule_timestamp'] = detail.replace('Rule timestamp:', '').strip()
+                    if detail.startswith('Last audited:'):
+                        rule_info['last_audited'] = detail.replace('Last audited:', '').strip()
                     elif detail.startswith('Newest file:'):
                         rule_info['newest_file'] = detail.replace('Newest file:', '').strip()
                     elif detail.startswith('File modified:'):
@@ -286,7 +313,7 @@ def build_stale_rules_context(stale_rules):
     parts.append("For each rule, review the rule content and the diff of changes, then:")
     parts.append("1. Determine if the rule content needs updating based on the code changes")
     parts.append("2. Update the rule if needed")
-    parts.append("3. ALWAYS update the timestamp (run `codeyam memory touch`)\n")
+    parts.append("3. ALWAYS run `codeyam memory touch` to mark rules as audited\n")
 
     for rule in stale_rules:
         parts.append(f"### {rule['name']}")
@@ -298,8 +325,8 @@ def build_stale_rules_context(stale_rules):
             parts.append(f"  Changed file: {rule['newest_file']}")
         if rule.get('file_modified'):
             parts.append(f"  File modified: {rule['file_modified']}")
-        if rule.get('rule_timestamp'):
-            parts.append(f"  Rule timestamp: {rule['rule_timestamp']}")
+        if rule.get('last_audited'):
+            parts.append(f"  Last audited: {rule['last_audited']}")
         if rule.get('diff'):
             parts.append(f"  Changes:")
             for line in rule['diff'].split('\n'):
@@ -373,7 +400,7 @@ def build_interruption_context(conversation_snippets, follow_up_prompt, modified
     return '\n'.join(parts)
 
 
-def spawn_claude_agent(prompt, log_file, project_dir):
+def spawn_claude_agent(prompt, log_file, project_dir, model='haiku'):
     """Spawn a detached claude -p agent as a background process."""
     try:
         log_fh = open(log_file, 'w')
@@ -381,7 +408,8 @@ def spawn_claude_agent(prompt, log_file, project_dir):
         env['CODEYAM_RULE_AGENT'] = '1'
         subprocess.Popen(
             ['claude', '-p', prompt,
-             '--model', 'haiku',
+             '--model', model,
+             '--no-session-persistence',
              '--output-format', 'stream-json', '--verbose',
              '--allowedTools', 'Read,Edit,Write,Bash,Glob,Grep'],
             cwd=project_dir,
@@ -427,6 +455,8 @@ def handle_stop(hook_input):
     agent spawn) runs first. The slow `get_stale_rules()` call (~10s) runs last
     so the hook timeout doesn't kill us before the critical work is done.
     """
+    settings = load_memory_settings()
+
     session_id = hook_input.get('session_id', '')
     transcript_path = hook_input.get('transcript_path', '')
 
@@ -452,8 +482,8 @@ def handle_stop(hook_input):
     invocation_ts = datetime.now().strftime('%Y%m%d-%H%M%S')
     invocation_id = f'{session_id}-{invocation_ts}'
 
-    # Fast: spawn conversation review agent first
-    if len(conversation_snippets) > 0:
+    # Fast: spawn conversation review agent first (if enabled)
+    if settings['conversationReflection'] and len(conversation_snippets) > 0:
         conv_context = build_conversation_context(conversation_snippets, modified_files)
         conv_context_file = marker_dir / f'{invocation_id}-conversation.context'
         conv_context_file.write_text(conv_context)
@@ -466,26 +496,27 @@ def handle_stop(hook_input):
             NOTIFICATION_FILE=str(conv_notification_file),
             PROJECT_DIR=project_dir,
         )
-        spawn_claude_agent(conv_prompt, conv_log_file, project_dir)
+        spawn_claude_agent(conv_prompt, conv_log_file, project_dir, model=settings['promptModel'])
 
     # Slow (~10s): check for stale rules last — if the hook timeout kills us
     # here, the conversation agent and marker are already handled
-    stale_rules = get_stale_rules()
-
-    if len(stale_rules) > 0:
-        stale_context = build_stale_rules_context(stale_rules)
-        stale_context_file = marker_dir / f'{invocation_id}-stale.context'
-        stale_context_file.write_text(stale_context)
-
-        stale_log_file = marker_dir / f'{invocation_id}-stale.log'
-        stale_notification_file = marker_dir / 'rule-notification-stale.md'
-        stale_prompt = load_prompt_template(
-            'stale-rules-prompt.txt',
-            CONTEXT_FILE=str(stale_context_file),
-            NOTIFICATION_FILE=str(stale_notification_file),
-            PROJECT_DIR=project_dir,
-        )
-        spawn_claude_agent(stale_prompt, stale_log_file, project_dir)
+    if settings['ruleMaintenance']:
+        stale_rules = get_stale_rules()
+
+        if len(stale_rules) > 0:
+            stale_context = build_stale_rules_context(stale_rules)
+            stale_context_file = marker_dir / f'{invocation_id}-stale.context'
+            stale_context_file.write_text(stale_context)
+
+            stale_log_file = marker_dir / f'{invocation_id}-stale.log'
+            stale_notification_file = marker_dir / 'rule-notification-stale.md'
+            stale_prompt = load_prompt_template(
+                'stale-rules-prompt.txt',
+                CONTEXT_FILE=str(stale_context_file),
+                NOTIFICATION_FILE=str(stale_notification_file),
+                PROJECT_DIR=project_dir,
+            )
+            spawn_claude_agent(stale_prompt, stale_log_file, project_dir, model=settings['promptModel'])
 
 
 def handle_user_prompt_submit(hook_input):
@@ -495,6 +526,12 @@ def handle_user_prompt_submit(hook_input):
     marker file is stale (transcript has lines beyond the marker). If so, spawns a
     rule-reflection agent focused on the interruption.
     """
+    settings = load_memory_settings()
+
+    # Interruption detection is part of conversation reflection
+    if not settings['conversationReflection']:
+        return
+
     session_id = hook_input.get('session_id', '')
     transcript_path = hook_input.get('transcript_path', '')
     follow_up_prompt = hook_input.get('prompt', '')
@@ -561,7 +598,7 @@ def handle_user_prompt_submit(hook_input):
         NOTIFICATION_FILE=str(notification_file),
         PROJECT_DIR=project_dir,
     )
-    spawn_claude_agent(prompt, log_file, project_dir)
+    spawn_claude_agent(prompt, log_file, project_dir, model=settings['promptModel'])
 
 
 def main():

package/codeyam-cli/templates/rules-instructions.md

@@ -6,7 +6,27 @@ Rules provide context-specific guidance when working in files matching their `pa
 
 1. **One concept per rule** - Each rule should cover a single topic. If you're documenting two unrelated things, create two rules.
 2. **Paths must match content scope** - A rule about one specific file should have that file in `paths`, not a broad `**/*.ts` pattern.
-3. **Be concise** - Every word costs context. Use bullets and tables.
+3. **Keep rules SHORT** - Most rules should be **1-4 bullets**. Only complex multi-file architectural overviews should exceed ~10 lines. Every word costs context.
+
+### Good vs Bad Rule Length
+
+**Good** — a typical rule (4 bullets):
+
+```markdown
+---
+paths:
+  - 'packages/ai/src/lib/generateMockData.ts'
+---
+
+# Mock Data Generation
+
+- Entry point: `generateMockData()` in `generateMockData.ts`
+- Uses `convertDotNotation` to transform flat schema into nested objects
+- Schema entry ORDER matters — `key[]` must come before `key[].property` or arrays get overwritten
+- Test with exact ordering from database, not just same entries
+```
+
+**Bad** — same info bloated to 40+ lines with unnecessary headers, restating what the code says, and paragraphs instead of bullets.
 
 ## When to Create a New Rule
 
@@ -17,23 +37,13 @@ Create a new rule when:
 - The user explains something that isn't clear from the code
 - An existing rule is covering multiple unrelated topics (split it)
 
-## Before Creating: The Confusion Test
+## Before Creating: What Makes a Rule Valuable?
 
-Only create rules that document genuinely confusing aspects—not things Claude can figure out by reading code and will likely come up again in future sessions.
+A rule earns its place when it meets these criteria:
 
-**Ask yourself:**
-
-1. **Could Claude figure this out by reading the code?**
-   - If YES → don't create the rule
-   - If NO → proceed
-
-2. **Does this explain "why" not just "what"?**
-   - Good: Historical context, gotchas, non-obvious behavior, non-obvious architectural decisions
-   - Bad: Bug fixes, Limitations (unless the user requests the limitation be noted), What functions do (unless providing a high-level architectural overview)
-
-3. **Would this have prevented a past mistake?**
-   - If you can point to a bug or confusion this would have prevented → create it
-   - If it's just "nice to know" → skip it
+1. **Beyond the code** — It captures knowledge that reading the source alone wouldn't reveal (historical context, non-obvious interactions, gotchas).
+2. **Explains "why" over "what"** — Gotchas, non-obvious behavior, architectural decisions. (Function signatures, bug fixes, and limitations are already visible in code.)
+3. **Prevents real mistakes** — It would have saved someone from a past confusion or bug, not just a "nice to know."
 
 ### Examples
 
@@ -44,10 +54,7 @@ Only create rules that document genuinely confusing aspects—not things Claude
 - Debugging strategies for a particular area of the repo
 - "Use `pnpm test` to run tests" (if there is more than one way to run tests and this way is preferred)
 
-**❌ Not worth documenting:**
-
-- "The auth module handles authentication" (obvious from reading code)
-- "This function takes X and returns Y" (Claude can read the signature)
+Skip things like "The auth module handles authentication" or "This function takes X and returns Y" — Claude can read the code and infer these.
 
 ## Path Specificity
 
@@ -60,17 +67,25 @@ The `paths` field controls when the rule is shown. Match the scope of your conte
 | Directory     | `'path/to/dir/**/*.ts'` | Rule about the queue system in `utils/queue/`          |
 | Cross-cutting | Multiple specific paths | Testing rule with paths to test configs and test files |
 
-**Anti-pattern**: Don't use `'**/*.ts'` for a rule about one specific feature.
+Match path specificity to content scope — use `'path/to/feature.ts'` for a single-feature rule, not `'**/*.ts'`.
+
+## File Placement
 
-## File Structure
+Place each rule at the **deepest common directory** shared by all its `paths` entries:
 
-Rules mirror the source code structure:
+1. Take all paths from the rule's frontmatter
+2. Strip filenames — keep only the directory portions
+3. Find the longest shared directory prefix
+4. Place the rule `.md` file in `.claude/rules/<that-prefix>/`
 
-| Source Location      | Rule Location                           |
-| -------------------- | --------------------------------------- |
-| `src/api/auth.ts`    | `.claude/rules/src/api/auth.md`         |
-| `src/utils/queue/**` | `.claude/rules/src/utils/queue.md`      |
-| Test configuration   | `.claude/rules/testing/jest-configs.md` |
+| Paths in frontmatter                                       | Deepest common dir     | Rule location                                  |
+| ---------------------------------------------------------- | ---------------------- | ---------------------------------------------- |
+| `packages/ai/src/lib/foo.ts`, `packages/ai/src/lib/bar.ts` | `packages/ai/src/lib/` | `.claude/rules/packages/ai/src/lib/foo-bar.md` |
+| `packages/ai/src/lib/a.ts`, `packages/ai/src/utils/b.ts`   | `packages/ai/src/`     | `.claude/rules/packages/ai/src/a-and-b.md`     |
+| `packages/ai/**`, `packages/types/**`                      | `packages/`            | `.claude/rules/packages/ai-types.md`           |
+| `src/api/auth.ts` (single file)                            | `src/api/`             | `.claude/rules/src/api/auth.md`                |
+
+Reserve the top level of `.claude/rules/` for rules whose paths genuinely span the entire repo.
 
 ## Required Frontmatter
 
@@ -79,14 +94,14 @@ Rules mirror the source code structure:
 paths:
   - 'specific/path/to/file.ts'
   - 'another/specific/path/*.ts'
-timestamp: 2026-01-30T00:00:00Z
 ---
 ```
 
-| Field       | Purpose                                                          |
-| ----------- | ---------------------------------------------------------------- |
-| `paths`     | Glob patterns - be specific to avoid loading rules unnecessarily |
-| `timestamp` | ISO 8601 - update when rule is reviewed                          |
+| Field   | Purpose                                                          |
+| ------- | ---------------------------------------------------------------- |
+| `paths` | Glob patterns - be specific to avoid loading rules unnecessarily |
+
+**Note:** Audit dates live in `.claude/codeyam-rule-state.json` (managed by `codeyam memory touch`). Keep rule frontmatter limited to `paths`.
 
 ## Content Guidelines
 
@@ -95,15 +110,9 @@ timestamp: 2026-01-30T00:00:00Z
 - Good: "Run `pnpm test:api` for API tests"
 - Bad: "Make sure to run the appropriate tests"
 
-### Focus on What, Not What Not
-
-- Good: "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`"
-- Bad: "WARNING: Don't store tokens in localStorage!"
-
-### Keep Rules Short
+### Focus on What to Do
 
-- Target 30-50 lines
-- If a rule exceeds 60 lines, consider splitting it
+- "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`" tells the reader exactly where to look and what pattern to follow.
 
 ## Categories
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam/codeyam-cli",
-  "version": "0.1.0-staging.79ef713",
+  "version": "0.1.0-staging.7c30edc",
   "description": "Local development CLI for CodeYam analysis",
   "type": "module",
   "bin": {

package/packages/ai/src/lib/astScopes/processExpression.js

@@ -3,10 +3,66 @@ import * as crypto from 'crypto';
 import { StructuredPath } from "./paths.js";
 import { nodeToSource } from "./nodeToSource.js";
 import { methodRegistry, ArrayPushSemantics } from "./methodSemantics.js";
-import { isArithmeticOperator, isAssignmentOperator, isBitwiseCompoundOperator, isComparisonOperator, isDefinedType, isNumericCompoundOperator, leftOrRightType, unwrapExpression, } from "./sharedPatterns.js";
+import { getComparisonOperatorString, isArithmeticOperator, isAssignmentOperator, isBitwiseCompoundOperator, isComparisonOperator, isDefinedType, isNumericCompoundOperator, leftOrRightType, unwrapExpression, } from "./sharedPatterns.js";
 import { processBindingPattern } from "./processBindings.js";
 import { extractConditionalEffectsFromTernary, findUseStateSetters, } from "./conditionalEffectsExtractor.js";
 import { detectArrayDerivedPattern } from "./arrayDerivationDetector.js";
+/**
+ * Recursively extracts root variable names from an expression AST node.
+ * Used to identify which variables flow into JSX expression children,
+ * so we can link them to the return value schema.
+ *
+ * Examples:
+ * - `filteredTopPaths.map(...)` → ['filteredTopPaths']
+ * - `a && b` → ['a', 'b']
+ * - `condition ? x : y` → ['condition', 'x', 'y']
+ */
+function extractRootVariableNames(node) {
+    const ignoredIdentifiers = new Set([
+        'undefined',
+        'null',
+        'true',
+        'false',
+        'NaN',
+        'Infinity',
+    ]);
+    if (ts.isIdentifier(node)) {
+        const name = node.text;
+        return ignoredIdentifiers.has(name) ? [] : [name];
+    }
+    if (ts.isPropertyAccessExpression(node)) {
+        return extractRootVariableNames(node.expression);
+    }
+    if (ts.isCallExpression(node)) {
+        return extractRootVariableNames(node.expression);
+    }
+    if (ts.isBinaryExpression(node)) {
+        return [
+            ...extractRootVariableNames(node.left),
+            ...extractRootVariableNames(node.right),
+        ];
+    }
+    if (ts.isPrefixUnaryExpression(node)) {
+        return extractRootVariableNames(node.operand);
+    }
+    if (ts.isConditionalExpression(node)) {
+        return [
+            ...extractRootVariableNames(node.condition),
+            ...extractRootVariableNames(node.whenTrue),
+            ...extractRootVariableNames(node.whenFalse),
+        ];
+    }
+    if (ts.isParenthesizedExpression(node)) {
+        return extractRootVariableNames(node.expression);
+    }
+    // Stop recursion at JSX elements and other terminal nodes
+    if (ts.isJsxElement(node) ||
+        ts.isJsxFragment(node) ||
+        ts.isJsxSelfClosingElement(node)) {
+        return [];
+    }
+    return [];
+}
 /**
  * Checks if a JSX element has props that reference variables from the parent scope.
  * This is used to detect unconditionally-rendered children that should have their
@@ -966,6 +1022,8 @@ export function extractConditionalUsage(condition, context, location, options =
                 }
                 return literalValue;
             };
+            // Get the comparison operator string for the compound condition
+            const comparisonOperator = getComparisonOperatorString(unwrapped.operatorToken.kind);
             // Helper to add a condition
             const addCondition = (path, conditionType, comparedValues, requiredValue, sourceExpr) => {
                 const usage = {
@@ -1001,6 +1059,7 @@ export function extractConditionalUsage(condition, context, location, options =
                         comparedValues,
                         isNegated,
                         requiredValue,
+                        ...(comparisonOperator && { comparisonOperator }),
                         ...(chainInfo.currentOrGroupId && {
                             orGroupId: chainInfo.currentOrGroupId,
                         }),
@@ -2456,6 +2515,15 @@ export function processExpression({ node, context, targetPath, typeHint, }) {
             for (const child of unwrappedNode.children) {
                 // Process expressions in JSX children: <div>{expr}</div>
                 if (ts.isJsxExpression(child) && child.expression) {
+                    // When processing return value JSX, link root variables to return value schema
+                    if (targetPath && targetPath.base !== '') {
+                        const varNames = [
+                            ...new Set(extractRootVariableNames(child.expression)),
+                        ];
+                        for (const varName of varNames) {
+                            context.addEquivalence(targetPath.withProperty(varName), StructuredPath.fromBase(varName));
+                        }
+                    }
                     // Process the expression with StructuredPath.empty() as targetPath
                     // to trigger type registration without imposing prefix
                     processExpression({
@@ -2486,6 +2554,15 @@ export function processExpression({ node, context, targetPath, typeHint, }) {
         for (const child of unwrappedNode.children) {
             // Process expressions in JSX children: <>{expr}</>
             if (ts.isJsxExpression(child) && child.expression) {
+                // When processing return value JSX, link root variables to return value schema
+                if (targetPath && targetPath.base !== '') {
+                    const varNames = [
+                        ...new Set(extractRootVariableNames(child.expression)),
+                    ];
+                    for (const varName of varNames) {
+                        context.addEquivalence(targetPath.withProperty(varName), StructuredPath.fromBase(varName));
+                    }
+                }
                 // Process the expression to extract structure
                 processExpression({
                     node: child.expression,