refactor(file): rename FileSymbol and related types to NativeDocumentSymbol; enhance file structure interfaces

Author: AndyLiner13

src/client-pipe.ts

@@ -637,24 +637,24 @@ export async function codebaseGetDiagnostics(
 
 // ── File Service Types ───────────────────────────────────
 
-export interface FileSymbolRange {
+export interface NativeDocumentSymbolRange {
   startLine: number;
   startChar: number;
   endLine: number;
   endChar: number;
 }
 
-export interface FileSymbol {
+export interface NativeDocumentSymbol {
   name: string;
   kind: string;
   detail?: string;
-  range: FileSymbolRange;
-  selectionRange: FileSymbolRange;
-  children: FileSymbol[];
+  range: NativeDocumentSymbolRange;
+  selectionRange: NativeDocumentSymbolRange;
+  children: NativeDocumentSymbol[];
 }
 
 export interface FileGetSymbolsResult {
-  symbols: FileSymbol[];
+  symbols: NativeDocumentSymbol[];
 }
 
 export interface FileReadContentResult {
@@ -759,6 +759,59 @@ export interface FileFindReferencesResult {
   references: Array<{file: string; line: number; character: number}>;
 }
 
+// ── Shared File Structure Types (Multi-Language) ─────────
+
+export interface FileSymbolRange {
+  startLine: number;
+  endLine: number;
+  startChar?: number;
+  endChar?: number;
+}
+
+export interface FileSymbol {
+  name: string;
+  kind: string;
+  detail?: string;
+  range: FileSymbolRange;
+  children: FileSymbol[];
+  exported?: boolean;
+  modifiers?: string[];
+}
+
+export type OrphanedCategory =
+  | 'import'
+  | 'export'
+  | 'comment'
+  | 'directive'
+  | 'footnote'
+  | 'linkdef';
+
+export interface OrphanedItem {
+  name: string;
+  kind: string;
+  detail?: string;
+  range: {start: number; end: number};
+  children?: OrphanedItem[];
+  category: OrphanedCategory;
+}
+
+export interface FileStructureStats {
+  totalSymbols: number;
+  totalOrphaned: number;
+  totalBlankLines: number;
+  coveragePercent: number;
+}
+
+export interface FileStructure {
+  symbols: FileSymbol[];
+  content: string;
+  totalLines: number;
+  fileType: 'typescript' | 'markdown' | 'json' | 'unknown';
+  orphaned: {items: OrphanedItem[]};
+  gaps: Array<{start: number; end: number; type: 'blank' | 'unknown'}>;
+  stats: FileStructureStats;
+}
+
 export interface FileCodeActionItem {
   index: number;
   title: string;
@@ -943,20 +996,20 @@ export async function fileExtractOrphanedContent(
 }
 
 /**
- * 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.
+ * Extract the complete file structure via the LanguageServiceRegistry.
+ * Returns FileStructure if the file type is supported, undefined otherwise.
  */
 export async function fileExtractStructure(
   filePath: string,
-): Promise<UnifiedFileResult> {
+): Promise<FileStructure | undefined> {
   const result = await sendClientRequest(
     'file.extractStructure',
     {filePath},
     30_000,
   );
-  assertResult<UnifiedFileResult>(result, 'file.extractStructure');
-  return result;
+  // The registry returns undefined for unsupported file types
+  if (result === undefined || result === null) return undefined;
+  return result as FileStructure;
 }
 
 // ── Recovery Handler ─────────────────────────────────────

src/tools/file/file-edit.ts

@@ -14,10 +14,6 @@ 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(getClientWorkspace(), file);
@@ -123,18 +119,17 @@ export const edit = defineTool({
     let targetLabel: string | undefined;
 
     if (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)) {
+      // Symbol targeting: resolve via registered language service
+      const structure = await fileExtractStructure(filePath);
+      if (!structure) {
+        const ext = path.extname(filePath).slice(1).toLowerCase();
         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.`,
+          `❌ Symbol targeting is not supported for .${ext} files.\n\n` +
+          `Use \`startLine\`/\`endLine\` instead.`,
         );
         return;
       }
 
-      const structure = await fileExtractStructure(filePath);
       const match = resolveSymbolTarget(structure.symbols, params.target);
 
       if (!match) {
@@ -146,7 +141,7 @@ export const edit = defineTool({
         return;
       }
 
-      // ts-morph ranges are 1-indexed; safety layer expects 0-indexed
+      // Ranges are 1-indexed; safety layer expects 0-indexed
       editStartLine = match.symbol.range.startLine - 1;
       editEndLine = match.symbol.range.endLine - 1;
       targetLabel = params.target;

src/tools/file/file-read.ts

@@ -11,9 +11,9 @@ import {
   fileExtractStructure,
   fileReadContent,
   fileHighlightReadRange,
-  OrphanedSymbolNode,
-  UnifiedFileSymbol,
-  UnifiedFileResult,
+  type OrphanedItem,
+  type FileSymbol,
+  type FileStructure,
 } from '../../client-pipe.js';
 import {getClientWorkspace} from '../../config.js';
 import {zod} from '../../third_party/index.js';
@@ -27,11 +27,6 @@ function resolveFilePath(file: string): string {
   return path.resolve(getClientWorkspace(), file);
 }
 
-// Supported TS/JS file extensions for structured extraction
-const STRUCTURED_EXTS = new Set([
-  'ts', 'tsx', 'js', 'jsx', 'mts', 'mjs', 'cts', 'cjs',
-]);
-
 // Special target keywords for orphaned content
 const SPECIAL_TARGETS = ['#imports', '#exports', '#comments'] as const;
 type SpecialTarget = typeof SPECIAL_TARGETS[number];
@@ -55,12 +50,12 @@ function addLineNumbers(content: string, startLine1: number): string {
 }
 
 function formatSkeletonEntry(
-  symbol: SymbolLike | OrphanedSymbolNode,
+  symbol: SymbolLike | OrphanedItem,
   indent = '',
   recursive = false,
 ): string[] {
   const lines: string[] = [];
-  // Both UnifiedFileSymbol and OrphanedSymbolNode are 1-indexed
+  // FileSymbol uses startLine/endLine, OrphanedItem uses start/end
   const startLine = 'startLine' in symbol.range ? symbol.range.startLine : symbol.range.start;
   const endLine = 'startLine' in symbol.range ? symbol.range.endLine : symbol.range.end;
   const range = startLine === endLine ? `${startLine}` : `${startLine}-${endLine}`;
@@ -129,15 +124,15 @@ interface NonSymbolBlock {
 }
 
 type LineOwner =
-  | { type: 'symbol'; symbol: UnifiedFileSymbol }
+  | { type: 'symbol'; symbol: FileSymbol }
   | { type: 'block'; block: NonSymbolBlock };
 
 /**
  * Group consecutive non-symbol items of the same type into atomic blocks.
  * Each block represents a contiguous run of the same non-symbol category.
  * Lines within symbol ranges are excluded — only "between-symbol" content forms blocks.
  */
-function buildNonSymbolBlocks(structure: UnifiedFileResult): NonSymbolBlock[] {
+function buildNonSymbolBlocks(structure: FileStructure): NonSymbolBlock[] {
   // Build set of lines owned by symbols so we can exclude them
   const symbolLines = new Set<number>();
   for (const sym of structure.symbols) {
@@ -148,26 +143,19 @@ function buildNonSymbolBlocks(structure: UnifiedFileResult): NonSymbolBlock[] {
 
   const tagged: Array<{ line: number; type: NonSymbolType }> = [];
 
-  for (const imp of structure.imports) {
-    for (let line = imp.range.start; line <= imp.range.end; line++) {
-      if (!symbolLines.has(line)) tagged.push({ line, type: 'import' });
-    }
-  }
-  for (const exp of structure.exports) {
-    for (let line = exp.range.start; line <= exp.range.end; line++) {
-      if (!symbolLines.has(line)) tagged.push({ line, type: 'export' });
-    }
-  }
-  for (const comment of structure.orphanComments) {
-    for (let line = comment.range.start; line <= comment.range.end; line++) {
-      if (!symbolLines.has(line)) tagged.push({ line, type: 'comment' });
-    }
-  }
-  for (const dir of structure.directives) {
-    for (let line = dir.range.start; line <= dir.range.end; line++) {
-      if (!symbolLines.has(line)) tagged.push({ line, type: 'directive' });
+  for (const item of structure.orphaned.items) {
+    const mappedType: NonSymbolType =
+      item.category === 'import' ? 'import' :
+      item.category === 'export' ? 'export' :
+      item.category === 'comment' ? 'comment' :
+      item.category === 'directive' ? 'directive' :
+      'comment'; // footnote/linkdef fall under comment for rendering
+
+    for (let line = item.range.start; line <= item.range.end; line++) {
+      if (!symbolLines.has(line)) tagged.push({ line, type: mappedType });
     }
   }
+
   for (const gap of structure.gaps) {
     for (let line = gap.start; line <= gap.end; line++) {
       if (!symbolLines.has(line)) tagged.push({ line, type: 'gap' });
@@ -197,7 +185,7 @@ function buildNonSymbolBlocks(structure: UnifiedFileResult): NonSymbolBlock[] {
  * Only covers lines within the requested range for efficiency.
  */
 function classifyLines(
-  structure: UnifiedFileResult,
+  structure: FileStructure,
   blocks: NonSymbolBlock[],
   startLine: number,
   endLine: number,
@@ -259,7 +247,7 @@ function expandToBlockBoundaries(
  * Returns the actual source-line range that the output covers (for highlighting).
  */
 function renderStructuredRange(
-  structure: UnifiedFileResult,
+  structure: FileStructure,
   allLines: string[],
   requestedStart: number,
   requestedEnd: number,
@@ -280,7 +268,7 @@ function renderStructuredRange(
   const owners = classifyLines(structure, blocks, expandedStart, expandedEnd);
 
   const result: string[] = [];
-  const emittedSymbols = new Set<UnifiedFileSymbol>();
+  const emittedSymbols = new Set<FileSymbol>();
   const emittedBlocks = new Set<NonSymbolBlock>();
 
   // Track the actual source-line range that the output covers
@@ -504,14 +492,11 @@ export const read = defineTool({
     }
 
     // Check if this is a TS/JS file that supports structured extraction
-    const ext = path.extname(filePath).slice(1).toLowerCase();
-    const isStructuredFile = STRUCTURED_EXTS.has(ext);
-
-    // Get unified structure for TS/JS files (one call replaces three)
-    let structure: UnifiedFileResult | undefined;
+    // Get file structure via registry (supports any registered language)
+    let structure: FileStructure | undefined;
     let allLines: string[] = [];
-    if (isStructuredFile) {
-      structure = await fileExtractStructure(filePath);
+    structure = await fileExtractStructure(filePath);
+    if (structure) {
       allLines = structure.content.split('\n');
     }
 
@@ -573,7 +558,7 @@ export const read = defineTool({
     // ── Skeleton mode (no targets, no line range) ─────────────
     if (targets.length === 0 && skeleton) {
       if (!structure) {
-        response.appendResponseLine('Skeleton mode requires a TypeScript or JavaScript file.');
+        response.appendResponseLine('Skeleton mode requires a supported structured file type.');
         return;
       }
 
@@ -582,22 +567,19 @@ export const read = defineTool({
         startLine: number;
         endLine: number;
         category: 'imports' | 'exports' | 'comments' | 'directives' | 'symbol' | 'raw';
-        symbol?: UnifiedFileSymbol;
+        symbol?: FileSymbol;
       }
 
       const pieces: SkeletonPiece[] = [];
 
-      for (const imp of structure.imports) {
-        pieces.push({ startLine: imp.range.start, endLine: imp.range.end, category: 'imports' });
-      }
-      for (const exp of structure.exports) {
-        pieces.push({ startLine: exp.range.start, endLine: exp.range.end, category: 'exports' });
-      }
-      for (const comment of structure.orphanComments) {
-        pieces.push({ startLine: comment.range.start, endLine: comment.range.end, category: 'comments' });
-      }
-      for (const dir of structure.directives) {
-        pieces.push({ startLine: dir.range.start, endLine: dir.range.end, category: 'directives' });
+      for (const item of structure.orphaned.items) {
+        const cat: SkeletonPiece['category'] =
+          item.category === 'import' ? 'imports' :
+          item.category === 'export' ? 'exports' :
+          item.category === 'comment' ? 'comments' :
+          item.category === 'directive' ? 'directives' :
+          'comments';
+        pieces.push({ startLine: item.range.start, endLine: item.range.end, category: cat });
       }
       for (const sym of structure.symbols) {
         pieces.push({ startLine: sym.range.startLine, endLine: sym.range.endLine, category: 'symbol', symbol: sym });
@@ -662,22 +644,22 @@ export const read = defineTool({
 
     // ── Targets mode ─────────────────────────────────────────
 
-    // Targets require structured extraction (TS/JS only)
+    // Targets require structured extraction
     if (!structure) {
       response.appendResponseLine(
-        'Target-based reading requires a TypeScript or JavaScript file.',
+        'Target-based reading requires a supported structured file type.',
       );
       return;
     }
 
     for (const target of targets) {
       if (isSpecialTarget(target)) {
         // Handle special keywords: #imports, #exports, #comments
-        const items = target === '#imports'
-          ? structure.imports
-          : target === '#exports'
-            ? structure.exports
-            : structure.orphanComments;
+        const categoryFilter =
+          target === '#imports' ? 'import' :
+          target === '#exports' ? 'export' :
+          'comment';
+        const items = structure.orphaned.items.filter(i => i.category === categoryFilter);
 
         if (skeleton) {
           for (const item of items) {
@@ -694,7 +676,7 @@ export const read = defineTool({
           }
         }
       } else {
-        // Symbol targeting (1-indexed ranges from ts-morph)
+        // Symbol targeting (1-indexed ranges)
         const match = resolveSymbolTarget(structure.symbols, target);
 
         if (!match) {