feat(file-structure): introduce unified file structure types and extraction method for TS/JS files

Author: AndyLiner13

src/client-pipe.ts

@@ -785,6 +785,44 @@ export interface OrphanedContentResult {
   };
 }
 
+// ── Unified File Structure Types ─────────────────────────
+
+export interface UnifiedFileSymbolRange {
+  startLine: number;   // 1-indexed
+  startChar: number;   // 0-indexed (column)
+  endLine: number;     // 1-indexed
+  endChar: number;     // 0-indexed (column)
+}
+
+export interface UnifiedFileSymbol {
+  name: string;
+  kind: string;
+  detail?: string;
+  range: UnifiedFileSymbolRange;
+  children: UnifiedFileSymbol[];
+  exported?: boolean;
+  modifiers?: string[];
+}
+
+export interface UnifiedFileResult {
+  symbols: UnifiedFileSymbol[];
+  content: string;
+  totalLines: number;
+  imports: OrphanedSymbolNode[];
+  exports: OrphanedSymbolNode[];
+  orphanComments: OrphanedSymbolNode[];
+  directives: OrphanedSymbolNode[];
+  gaps: Array<{start: number; end: number; type: 'blank' | 'unknown'}>;
+  stats: {
+    totalImports: number;
+    totalExports: number;
+    totalOrphanComments: number;
+    totalDirectives: number;
+    totalBlankLines: number;
+    coveragePercent: number;
+  };
+}
+
 export interface FileFindReferencesResult {
   references: Array<{file: string; line: number; character: number}>;
 }
@@ -970,6 +1008,23 @@ export async function fileExtractOrphanedContent(
   return result;
 }
 
+/**
+ * Extract the complete file structure using ts-morph only.
+ * Returns symbols, content, imports, exports, comments, directives, gaps, and stats.
+ * Single round-trip replacement for fileGetSymbols + fileExtractOrphanedContent + fileReadContent.
+ */
+export async function fileExtractStructure(
+  filePath: string,
+): Promise<UnifiedFileResult> {
+  const result = await sendClientRequest(
+    'file.extractStructure',
+    {filePath},
+    30_000,
+  );
+  assertResult<UnifiedFileResult>(result, 'file.extractStructure');
+  return result;
+}
+
 // ── Recovery Handler ─────────────────────────────────────
 
 let clientRecoveryHandler: (() => Promise<void>) | undefined;

src/tools/file/file-edit.ts

@@ -6,14 +6,18 @@
 
 import path from 'node:path';
 
-import {fileGetSymbols, fileReadContent} from '../../client-pipe.js';
+import {fileExtractStructure, fileReadContent} from '../../client-pipe.js';
 import {getHostWorkspace} from '../../config.js';
 import {zod} from '../../third_party/index.js';
 import {ToolCategory} from '../categories.js';
 import {defineTool} from '../ToolDefinition.js';
 import {executeEditWithSafetyLayer} from './safety-layer.js';
 import {resolveSymbolTarget} from './symbol-resolver.js';
 
+const STRUCTURED_EXTS = new Set([
+  'ts', 'tsx', 'js', 'jsx', 'mts', 'mjs', 'cts', 'cjs',
+]);
+
 function resolveFilePath(file: string): string {
   if (path.isAbsolute(file)) return file;
   return path.resolve(getHostWorkspace(), file);
@@ -58,7 +62,7 @@ export const edit = defineTool({
     ),
     target: zod.string().optional().describe(
       'Symbol name to scope the edit: "UserService.findById". ' +
-      'Uses VS Code DocumentSymbols for precise targeting.',
+      'Only supported for TS/JS family files (.ts, .tsx, .js, .jsx, .mts, .mjs, .cts, .cjs).',
     ),
     startLine: zod.number().int().optional().describe(
       'Fallback: start line (1-indexed). Used when target is not specified.',
@@ -119,21 +123,32 @@ export const edit = defineTool({
     let targetLabel: string | undefined;
 
     if (params.target) {
-      // Symbol targeting: resolve via DocumentSymbols
-      const symbolsResult = await fileGetSymbols(filePath);
-      const match = resolveSymbolTarget(symbolsResult.symbols, params.target);
+      // Symbol targeting: resolve via ts-morph extraction (TS/JS family only)
+      const ext = path.extname(filePath).slice(1).toLowerCase();
+      if (!STRUCTURED_EXTS.has(ext)) {
+        response.appendResponseLine(
+          `❌ Symbol targeting is only supported for TS/JS family files ` +
+          `(.ts, .tsx, .js, .jsx, .mts, .mjs, .cts, .cjs).\n\n` +
+          `Use \`startLine\`/\`endLine\` instead for .${ext} files.`,
+        );
+        return;
+      }
+
+      const structure = await fileExtractStructure(filePath);
+      const match = resolveSymbolTarget(structure.symbols, params.target);
 
       if (!match) {
-        const available = symbolsResult.symbols.map(s => `${s.kind} ${s.name}`).join(', ');
+        const available = structure.symbols.map(s => `${s.kind} ${s.name}`).join(', ');
         response.appendResponseLine(
           `❌ Symbol "${params.target}" not found in ${relativePath}.\n\n` +
           `Available symbols: ${available || 'none'}`,
         );
         return;
       }
 
-      editStartLine = match.symbol.range.startLine;
-      editEndLine = match.symbol.range.endLine;
+      // ts-morph ranges are 1-indexed; safety layer expects 0-indexed
+      editStartLine = match.symbol.range.startLine - 1;
+      editEndLine = match.symbol.range.endLine - 1;
       targetLabel = params.target;
     } else if (params.startLine !== undefined && params.endLine !== undefined) {
       // Line-based targeting (convert 1-indexed to 0-indexed)