fix(move-file): parse local exports in index export cache (#318)

Implementing index export cache to parse local exports in addition to
re-exports

## Plan

- [x] Create IndexExports type and interface in export-management
- [x] Create getIndexExports function to parse local exports using AST
- [x] Update isFileExported to use the new cache system
- [x] Add comprehensive unit tests for getIndexExports
- [x] Add benchmark tests for performance validation
- [x] Update existing tests to cover local export scenarios
- [x] Run linting, build, and all tests
- [x] Format code
- [x] Update documentation
- [x] Address code review feedback
- [x] Update JSDoc comments to reflect cache usage

## Recent Changes

Updated documentation in `isFileExported()` to clarify:
- Function now uses the index exports cache system
- Cache parses local declarations but function only checks re-exports
- This addresses review feedback about outdated documentation

The distinction is important: `isFileExported()` checks if a **file** is
re-exported (e.g., `export * from './lib/utils'`), not if **symbols**
from that file are present as local exports in the index.

<!-- START COPILOT CODING AGENT SUFFIX -->



<details>

<summary>Original prompt</summary>


----

*This section details on the original issue you should resolve*

<issue_title>feat(move-file): parse local exports in index export
cache</issue_title>
<issue_description>## Summary
Enhance the index exports cache to parse and record *local* export
declarations in entrypoint (index) files in addition to existing
re-export ("export ... from") patterns.

Currently `getIndexExports()` only captures reexports and leaves
`exports` empty, forcing callers (e.g. `isFileExported`) to rely solely
on `reexports`. This prevents accurate detection of locally defined
exports (e.g. `export { foo, bar }`, `export const X = ...`, `export
function fn() {}`, `export class C {}`, and `export default ...`).
Supporting these will improve correctness of move-file validation
(unexported dependency checks, alias conversions) and reduce false
warnings.

## Motivation / Problem
When a project’s public surface is defined via local declarations in
`index.ts` rather than re-exporting from leaf modules, the current cache
misses them. As a result:
- `isFileExported()` incorrectly reports a file as unexported if it’s
aggregated via local declarations copied into the index.
- Move-file generator may warn about supposedly unexported relative
dependencies.
- Potential future optimizations (e.g., differentiating default vs named
exports) are blocked.

## Scope
Add robust parsing of local export declarations for
TypeScript/JavaScript index files, keeping the lightweight approach
(regex or jscodeshift) while maintaining performance. Preserve
separation between `exports` and `reexports` (per review feedback in PR
#316).

## Proposed Design
1. Reuse existing AST caching (jscodeshift + `astCache`) for structural
accuracy while minimizing parse cost.
2. Collect and normalize local export specifiers:
- Named declarations: `export const A`, `export function b`, `export
class C`, `export interface D`, `export type E`, `export enum F`.
   - Named list: `export { a, b as c }` (without `from`).
- Default exports: `export default X`, `export default function() {}`,
`export default class {}`.
3. Represent cache structure:
   ```ts
   interface IndexExports {
exports: Set<string>; // local named export identifiers (normalized)
reexports: Set<string>; // existing re-export specifiers ('./lib/util')
defaultExport?: string; // identifier or synthetic marker
('<anonymous>') if unnamed default
   }
   ```
4. Normalization Rules:
- Local identifiers stored exactly as defined (no extension logic
needed).
- Anonymous default exports mapped to a sentinel (e.g. `<default>` or
`<anonymous-default>`).
5. Backwards compatibility: existing callers using `reexports` remain
unchanged; add helper `isLocalSymbolExported(name)` if needed later.
6. Performance Strategy:
- Parse AST once via `astCache.getAST`; fall back to regex only if AST
unavailable.
   - Skip expensive symbol resolution—pure syntactic discovery.
   - Maintain content snapshot invalidation (existing logic).
7. Update `isFileExported` logic:
- If import specifier points to a file path: keep current re-export
check.
- If validation wants to infer export of an internal symbol (future),
can consult `exports` set.

## Tasks
- [ ] Extend `IndexExports` interface (add `defaultExport` field).
- [ ] Implement local export parsing function
(`collectLocalExports(ast): { names: Set<string>; default?: string }`).
- [ ] Integrate parsing into `getIndexExports` (only when content
contains `export`).
- [ ] Add unit tests covering:
  - Basic named exports (const/function/class/interface/type/enum).
  - Named list / alias exports (with `as`).
  - Default exports (named and anonymous).
  - Mixed local + re-exports in same file.
  - Empty index file (returns empty sets, undefined default).
  - Cache hit behavior (content unchanged).
  - Cache invalidation (content change updates sets).
- [ ] Update `is-file-exported.spec.ts` to include a scenario with local
declarations.
- [ ] Add benchmark cases to `export-management.bench.ts` for local
export detection (ensure negligible regression; target <5% throughput
impact).
- [ ] Update PR/Documentation: mention difference between local exports
and reexports.

## Acceptance Criteria
- All new tests pass; existing 770 tests remain green.
- Benchmarks show <5% performance degradation for export detection suite
or an offsetting improvement if AST parsing reduces regex overhead.
- `isFileExported` correctly returns true for files represented by local
declarations (when those files exist or are logically aggregated).
- No conflation between `exports` and `reexports`; clear docs in
`index-exports-cache.ts`.

## Performance Considerations
- AST parsing is already cached; incremental cost is node filtering for
export declarations.
- Provide fallback to fast regex ONLY if AST is unavailable (e.g., parse
error).
- Keep operations allocation-light (pre-size arrays where possible,
avoid repeated string normaliz...

</details>

- Fixes #317

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.

Author: LayZeeDK

packages/workspace/src/generators/move-file/benchmarks/index-exports-cache.bench.ts

@@ -0,0 +1,131 @@
+import {
+  beforeAll,
+  beforeAllIterations,
+  describe,
+  it,
+  beforeCycle,
+  afterCycle,
+} from '../../../../../../tools/tinybench-utils';
+import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import type { Tree } from '@nx/devkit';
+import {
+  getIndexExports,
+  clearIndexExportsCache,
+} from '../export-management/index-exports-cache';
+
+describe('Index Exports Cache', () => {
+  let tree: Tree;
+  let entryPoint: string;
+
+  // Move expensive tree creation to suite-level beforeAll
+  beforeAll(() => {
+    tree = createTreeWithEmptyWorkspace();
+    entryPoint = 'libs/my-lib/src/index.ts';
+  });
+
+  // Clear cache before each benchmark cycle
+  beforeCycle(() => {
+    clearIndexExportsCache();
+  });
+
+  afterCycle(() => {
+    clearIndexExportsCache();
+  });
+
+  describe('Parse re-exports only', () => {
+    beforeAllIterations(() => {
+      tree.write(
+        entryPoint,
+        `export * from './lib/file1';
+export * from './lib/file2';
+export * from './lib/file3';
+export { foo, bar } from './lib/file4';`,
+      );
+    });
+
+    it('should parse re-exports', () => {
+      getIndexExports(tree, entryPoint);
+    });
+  });
+
+  describe('Parse local named exports only', () => {
+    beforeAllIterations(() => {
+      tree.write(
+        entryPoint,
+        `export const FOO = 'foo';
+export const BAR = 'bar';
+export function myFunction() {}
+export class MyClass {}
+export interface IUser {}
+export type UserId = string;`,
+      );
+    });
+
+    it('should parse local named exports', () => {
+      getIndexExports(tree, entryPoint);
+    });
+  });
+
+  describe('Parse mixed exports', () => {
+    beforeAllIterations(() => {
+      tree.write(
+        entryPoint,
+        `export * from './lib/utils';
+export { foo } from './lib/helpers';
+export const LOCAL_CONST = 'value';
+export function localFn() {}
+export class LocalClass {}
+const internal = 1;
+export { internal as exposed };
+export default LocalClass;`,
+      );
+    });
+
+    it('should parse mixed exports', () => {
+      getIndexExports(tree, entryPoint);
+    });
+  });
+
+  describe('Cache hit performance', () => {
+    beforeAllIterations(() => {
+      tree.write(
+        entryPoint,
+        `export * from './lib/file1';
+export const FOO = 'foo';
+export function myFn() {}`,
+      );
+      // Prime the cache
+      getIndexExports(tree, entryPoint);
+    });
+
+    it('should retrieve from cache', () => {
+      getIndexExports(tree, entryPoint);
+    });
+  });
+
+  describe('Large file with many exports', () => {
+    beforeAllIterations(() => {
+      // Generate a large index file with 50 mixed exports
+      const lines: string[] = [];
+      for (let i = 0; i < 25; i++) {
+        lines.push(`export * from './lib/module${i}';`);
+        lines.push(`export const CONST_${i} = ${i};`);
+      }
+      tree.write(entryPoint, lines.join('\n'));
+    });
+
+    it('should parse large file with many exports', () => {
+      getIndexExports(tree, entryPoint);
+    });
+  });
+
+  describe('Empty file', () => {
+    beforeAllIterations(() => {
+      tree.write(entryPoint, '');
+    });
+
+    it('should handle empty file', () => {
+      getIndexExports(tree, entryPoint);
+    });
+  });
+});

packages/workspace/src/generators/move-file/cache/clear-all-caches.ts

@@ -1,4 +1,6 @@
 import { treeReadCache } from '../tree-cache';
+import { clearIndexExportsCache } from '../export-management/index-exports-cache';
+import { astCache } from '../ast-cache';
 
 /**
  * Clears all caches. Should be called when starting a new generator operation
@@ -10,6 +12,8 @@ import { treeReadCache } from '../tree-cache';
  * - Compiler paths cache
  * - Tree read cache
  * - Dependency graph cache
+ * - Index exports cache
+ * - AST cache
  *
  * @param projectSourceFilesCache - Cache for source files per project
  * @param fileExistenceCache - Cache for file existence checks
@@ -27,4 +31,6 @@ export function clearAllCaches(
   compilerPathsCache.value = undefined;
   treeReadCache.clear();
   dependencyGraphCache.clear();
+  clearIndexExportsCache();
+  astCache.clear();
 }

packages/workspace/src/generators/move-file/export-management/README.md

@@ -8,42 +8,71 @@ This module provides functions for managing exports in project entry points (ind
 
 ## Functions
 
-- **add-export-to-entrypoint.ts** - Add an export statement to a project's entry point file
-- **is-exported-from-project.ts** - Check if a file is exported from a project's entry point
-- **remove-export-from-entrypoint.ts** - Remove an export statement from a project's entry point
+- **index-exports-cache.ts** - Cache system for parsing and storing export information (both re-exports and local exports) from index files
+- **is-file-exported.ts** - Check if a file is re-exported from a project's entry point
+- **ensure-file-exported.ts** - Add an export statement to a project's entry point if not already present
+- **remove-file-export.ts** - Remove export statements for a file from a project's entry point
 - **should-export-file.ts** - Determine if a file should be exported based on generator options
-- **update-exports-in-entry-points.ts** - Update exports in both source and target entry points
+- **ensure-export-if-needed.ts** - Conditionally export a file based on strategy
+
+## Index Exports Cache
+
+The `index-exports-cache` module provides a cache system for parsing export information from index/entrypoint files. It supports:
+
+### Export Detection
+
+1. **Re-exports** (`reexports` Set)
+   - `export * from './lib/utils'`
+   - `export { foo, bar } from './lib/helpers'`
+   - `export type { User } from './types'`
+
+2. **Local Named Exports** (`exports` Set)
+   - Named declarations: `export const FOO = ...`, `export function fn() {}`, `export class C {}`
+   - TypeScript declarations: `export interface I {}`, `export type T = ...`, `export enum E {}`
+   - Named lists: `export { a, b as c }` (without `from`)
+
+3. **Default Exports** (`defaultExport` optional string)
+   - Named: `export default MyComponent`
+   - Anonymous: `export default function() {}`
+   - Expressions: `export default { ... }`
+
+### API
+
+```typescript
+import { getIndexExports } from './index-exports-cache';
+
+const exports = getIndexExports(tree, 'libs/mylib/src/index.ts');
+
+// Check re-exports
+exports.reexports.has('./lib/utils'); // boolean
+
+// Check local exports
+exports.exports.has('MyClass'); // boolean
+
+// Check default export
+exports.defaultExport === 'MyComponent'; // boolean
+```
 
 ## Usage
 
 ```typescript
-import { isExportedFromProject } from './export-management/is-exported-from-project';
-import { addExportToEntrypoint } from './export-management/add-export-to-entrypoint';
-import { removeExportFromEntrypoint } from './export-management/remove-export-from-entrypoint';
+import { isFileExported } from './export-management/is-file-exported';
+import { ensureFileExported } from './export-management/ensure-file-exported';
+import { removeFileExport } from './export-management/remove-file-export';
 
 // Check if file is exported
-const isExported = isExportedFromProject(
+const isExported = isFileExported(
   tree,
-  sourceFilePath,
-  sourceProject,
-  entryPointPaths,
+  project,
+  'lib/utils.ts',
+  cachedTreeExists,
 );
 
-// Add export to target project
-addExportToEntrypoint(
-  tree,
-  targetFilePath,
-  targetProject,
-  targetEntryPointPaths,
-);
+// Add export to project
+ensureFileExported(tree, project, 'lib/new-file.ts', cachedTreeExists);
 
-// Remove export from source project
-removeExportFromEntrypoint(
-  tree,
-  sourceFilePath,
-  sourceProject,
-  sourceEntryPointPaths,
-);
+// Remove export from project
+removeFileExport(tree, project, 'lib/old-file.ts', cachedTreeExists);
 ```
 
 ## Export Patterns
@@ -54,6 +83,7 @@ This module handles various export patterns:
 - **Wildcard exports**: `export * from './components/button';`
 - **Default exports**: `export { default as Button } from './components/button';`
 - **Barrel files**: Index files that re-export multiple modules
+- **Local exports**: `export const FOO = ...`, `export function fn() {}`, etc.
 
 ## Entry Point Detection
 
@@ -68,12 +98,24 @@ The module finds entry points by:
 
 All export management functions have comprehensive unit tests covering:
 
-- Export detection in various formats
+- Export detection in various formats (re-exports and local exports)
 - Export addition with proper formatting
 - Export removal without breaking other exports
+- Cache functionality and invalidation
 - Edge cases (no entry point, duplicate exports, etc.)
 
-Total: **52 tests**
+**Total: 80+ tests** including comprehensive index-exports-cache coverage
+
+## Performance
+
+The index exports cache uses jscodeshift for AST parsing, which provides:
+
+- Accurate parsing of all export patterns
+- Automatic caching to avoid re-parsing
+- Integration with existing AST cache
+- Efficient cache invalidation when files change
+
+See `../benchmarks/index-exports-cache.bench.ts` for performance benchmarks.
 
 ## Formatting
 
@@ -89,3 +131,4 @@ Export updates preserve code formatting:
 - [Core Operations](../core-operations/README.md) - Orchestrates export updates
 - [Project Analysis](../project-analysis/README.md) - Provides entry point paths
 - [Import Updates](../import-updates/README.md) - Complementary import updates
+- [Benchmarks](../benchmarks/README.md) - Performance benchmarks including export management

packages/workspace/src/generators/move-file/export-management/ensure-file-exported.ts

@@ -4,6 +4,8 @@ import { logger } from '@nx/devkit';
 import { getProjectEntryPointPaths } from '../project-analysis/get-project-entry-point-paths';
 import { removeSourceFileExtension } from '../path-utils/remove-source-file-extension';
 import { treeReadCache } from '../tree-cache';
+import { invalidateIndexExportsCache } from './index-exports-cache';
+import { astCache } from '../ast-cache';
 
 /**
  * Ensures the file is exported from the target project's entrypoint.
@@ -42,6 +44,8 @@ export function ensureFileExported(
     content += exportStatement;
     tree.write(indexPath, content);
     treeReadCache.invalidateFile(indexPath);
+    invalidateIndexExportsCache(indexPath);
+    astCache.invalidate(indexPath);
     logger.verbose(`Added export to ${indexPath}`);
   }
 }