Function getFolderStructure

packages/core/src/utils/getFolderStructure.ts:298–349

(
  directory: string,
  options?: FolderStructureOptions,
)

 * @returns A promise resolving to the formatted folder structure string.
 */
export async function getFolderStructure(
  directory: string,
  options?: FolderStructureOptions,
): Promise<string> {
  const resolvedPath = path.resolve(directory);
  const mergedOptions: MergedFolderStructureOptions = {
    maxItems: options?.maxItems ?? MAX_ITEMS,
    ignoredFolders: options?.ignoredFolders ?? DEFAULT_IGNORED_FOLDERS,
    fileIncludePattern: options?.fileIncludePattern,
    fileService: options?.fileService,
    fileFilteringOptions:
      options?.fileFilteringOptions ?? DEFAULT_FILE_FILTERING_OPTIONS,
  };

  try {
    // 1. Read the structure using BFS, respecting maxItems
    const structureRoot = await readFullStructure(resolvedPath, mergedOptions);

    if (!structureRoot) {
      return `Error: Could not read directory "${resolvedPath}". Check path and permissions.`;
    }

    // 2. Format the structure into a string
    const structureLines: string[] = [];
    // Pass true for isRoot for the initial call
    formatStructure(structureRoot, '', true, true, structureLines);

    // 3. Build the final output string
    function isTruncated(node: FullFolderInfo): boolean {
      if (node.hasMoreFiles || node.hasMoreSubfolders || node.isIgnored) {
        return true;
      }
      for (const sub of node.subFolders) {
        if (isTruncated(sub)) {
          return true;
        }
      }
      return false;
    }

    let summary = `Showing up to ${mergedOptions.maxItems} items (files + folders).`;

    if (isTruncated(structureRoot)) {
      summary += ` Folders or files indicated with ${TRUNCATION_INDICATOR} contain more items not shown, were ignored, or the display limit (${mergedOptions.maxItems} items) was reached.`;
    }

    return `${summary}\n\n${resolvedPath}${path.sep}\n${structureLines.join('\n')}`;
  } catch (error: unknown) {
    console.error(`Error getting folder structure for ${resolvedPath}:`, error);
    return `Error processing directory "${resolvedPath}": ${getErrorMessage(error)}`;
  }
}