feat(symbol-resolver): implement findQualifiedPaths function for suggesting qualified paths

feat(file-read): enhance error handling with qualified path suggestions for unresolved targets
feat(codebase-map): add directory validation for workspace paths before scanning

Author: AndyLiner13

src/tools/codebase/codebase-map.ts

@@ -4,6 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import {existsSync, statSync} from 'node:fs';
+import path from 'node:path';
+
 import {
   codebaseGetOverview,
   type CodebaseTreeNode,
@@ -242,6 +245,17 @@ export const map = defineTool({
     const symbols = params.symbols ?? false;
     const metadata = params.metadata ?? false;
 
+    // Resolve relative paths against workspace root for validation
+    const resolvedDir = path.isAbsolute(dir) ? dir : path.resolve(rootDir, dir);
+
+    // Validate directory exists before scanning
+    if (!existsSync(resolvedDir)) {
+      throw new Error(`Directory not found: "${dir}". Verify the path exists and is accessible.`);
+    }
+    if (!statSync(resolvedDir).isDirectory()) {
+      throw new Error(`Path is not a directory: "${dir}". The "dir" parameter must point to a folder, not a file.`);
+    }
+
     // Dynamic timeout based on request scope
     const dynamicTimeout =
       TIMEOUT_BASE_MS +

src/tools/file/file-read.ts

@@ -19,7 +19,7 @@ import {getClientWorkspace} from '../../config.js';
 import {zod} from '../../third_party/index.js';
 import {ToolCategory} from '../categories.js';
 import {CHARACTER_LIMIT, defineTool} from '../ToolDefinition.js';
-import {resolveSymbolTarget} from './symbol-resolver.js';
+import {resolveSymbolTarget, findQualifiedPaths} from './symbol-resolver.js';
 import type {SymbolLike} from './symbol-resolver.js';
 
 function resolveFilePath(file: string): string {
@@ -700,6 +700,15 @@ export const read = defineTool({
           response.appendResponseLine(
             `"${target}": Not found. Available: ${available || 'none'}`,
           );
+
+          // Check if the target exists as a nested child and suggest qualified path
+          const qualifiedPaths = findQualifiedPaths(structure.symbols, target);
+          if (qualifiedPaths.length > 0) {
+            const suggestions = qualifiedPaths.map(p => `"${p}"`).join(', ');
+            response.appendResponseLine(
+              `Hint: Did you mean ${suggestions}? Use the qualified dot-path to target nested symbols.`,
+            );
+          }
           continue;
         }
 

src/tools/file/symbol-resolver.ts

@@ -101,6 +101,38 @@ export function getChildNames(
   return symbol.children.map(c => c.name);
 }
 
+/**
+ * Search all children (recursively) of all top-level symbols for a name match.
+ * Returns the qualified dot-path(s) if found, e.g. ["ParentSection.ChildName"].
+ * Useful for suggesting the correct qualified path when an unqualified name fails.
+ */
+export function findQualifiedPaths(
+  symbols: SymbolLike[],
+  targetName: string,
+): string[] {
+  const results: string[] = [];
+
+  function searchChildren(children: SymbolLike[], parentPath: string): void {
+    for (const child of children) {
+      const qualifiedPath = `${parentPath}.${child.name}`;
+      if (nameMatches(child.name, targetName)) {
+        results.push(qualifiedPath);
+      }
+      if (child.children.length > 0) {
+        searchChildren(child.children, qualifiedPath);
+      }
+    }
+  }
+
+  for (const symbol of symbols) {
+    if (symbol.children.length > 0) {
+      searchChildren(symbol.children, symbol.name);
+    }
+  }
+
+  return results;
+}
+
 /**
  * Format a symbol's range as 1-indexed "lines X-Y of Z".
  * Takes 0-indexed line numbers (legacy path).