Data Handling

/**
 * Base and localized content directory paths
 */
type ContentPaths = {
  contentPath: string;
  contentPathLocalized: string;
};

/**
 * Globby options type (re-exported from globby library)
 */
type GlobbyOptions = import("globby").Options;

/**
 * Re-export of globby library for direct usage
 */
const Globby: typeof import("globby");

/**
 * Default glob patterns for excluding files
 */
const GlobExcludeDefault: string[];
// Includes:
// - "**/_*.{js,jsx,ts,tsx,md,mdx}"
// - "**/_*/**"
// - "**/*.test.{js,jsx,ts,tsx}"
// - "**/__tests__/**"

/**
 * Finds data file path in content directories, prioritizing localized path
 * @param params - Parameters for data file search
 * @param params.filePath - Relative path to the data file
 * @param params.contentPaths - Content directory paths to search
 * @returns Promise resolving to absolute file path or undefined if not found
 */
function getDataFilePath(params: {
  filePath: string;
  contentPaths: ContentPaths;
}): Promise<string | undefined>;

/**
 * Reads and parses YAML/JSON data file from content directories
 * @param params - Parameters for reading data file
 * @param params.filePath - Relative path to the data file
 * @param params.contentPaths - Content directory paths to search
 * @returns Promise resolving to parsed data
 * @throws Error if file cannot be parsed
 */
function readDataFile(params: {
  filePath: string;
  contentPaths: ContentPaths;
}): Promise<unknown>;

/**
 * Returns ordered list of content paths (localized first, then base)
 * @param contentPaths - Content paths object
 * @returns Array of content paths in priority order
 */
function getContentPathList(contentPaths: ContentPaths): string[];

import { 
  getDataFilePath, 
  readDataFile, 
  getContentPathList 
} from "@docusaurus/utils";

const contentPaths = {
  contentPath: "/website/docs",
  contentPathLocalized: "/website/i18n/en/docusaurus-plugin-content-docs/current",
};

// Find data file path
const dataFilePath = await getDataFilePath({
  filePath: "authors.yml",
  contentPaths,
});
console.log("Found data file at:", dataFilePath);
// Searches in localized path first, then base path

// Read and parse data file
try {
  const authorsData = await readDataFile({
    filePath: "authors.yml",
    contentPaths,
  });
  console.log("Authors data:", authorsData);
  // Automatically detects YAML or JSON format
} catch (error) {
  console.error("Failed to parse data file:", error.message);
}

// Get search order
const searchPaths = getContentPathList(contentPaths);
console.log("Search order:", searchPaths);
// Result: ["/website/i18n/en/docusaurus-plugin-content-docs/current", "/website/docs"]

/**
 * Finds first folder containing the specified file
 * @param folderPaths - Array of folder paths to search in
 * @param relativeFilePath - Relative path to the file to find
 * @returns Promise resolving to folder path or undefined if not found
 */
function findFolderContainingFile(
  folderPaths: string[],
  relativeFilePath: string
): Promise<string | undefined>;

/**
 * Fail-fast version of findFolderContainingFile that throws if file not found
 * @param folderPaths - Array of folder paths to search in
 * @param relativeFilePath - Relative path to the file to find
 * @returns Promise resolving to folder path
 * @throws Error if file not found in any folder
 */
function getFolderContainingFile(
  folderPaths: string[],
  relativeFilePath: string
): Promise<string>;

import { findFolderContainingFile, getFolderContainingFile } from "@docusaurus/utils";

const searchFolders = [
  "/website/docs",
  "/website/blog",
  "/website/src",
];

// Safe search (returns undefined if not found)
const foundFolder = await findFolderContainingFile(
  searchFolders,
  "package.json"
);

if (foundFolder) {
  console.log(`Found package.json in: ${foundFolder}`);
} else {
  console.log("package.json not found in any folder");
}

// Fail-fast search (throws if not found)
try {
  const requiredFolder = await getFolderContainingFile(
    searchFolders,
    "docusaurus.config.js"
  );
  console.log(`Config found in: ${requiredFolder}`);
} catch (error) {
  console.error("Config file is required but not found:", error.message);
}

/**
 * Windows-safe globby wrapper that converts paths to posix format
 * @param patterns - Glob patterns to match
 * @param options - Globby options (optional)
 * @returns Promise resolving to array of matched file paths
 */
function safeGlobby(
  patterns: string[],
  options?: GlobbyOptions
): Promise<string[]>;

/**
 * Globs and filters files that can contain translatable source code
 * @param patterns - Glob patterns for source files
 * @returns Promise resolving to array of translatable source file paths
 */
function globTranslatableSourceFiles(patterns: string[]): Promise<string[]>;

/**
 * Creates matcher function from glob patterns using Micromatch
 * @param patterns - Array of glob patterns
 * @returns Function that tests if a string matches any pattern
 */
function createMatcher(patterns: string[]): (str: string) => boolean;

/**
 * Creates matcher for absolute file paths resolved from root folders
 * @param patterns - Glob patterns to match
 * @param rootFolders - Root folders to resolve patterns against
 * @returns Function that tests if absolute file path matches patterns
 */
function createAbsoluteFilePathMatcher(
  patterns: string[],
  rootFolders: string[]
): (absoluteFilePath: string) => boolean;

import { 
  safeGlobby, 
  globTranslatableSourceFiles,
  createMatcher,
  createAbsoluteFilePathMatcher,
  GlobExcludeDefault 
} from "@docusaurus/utils";

// Safe globbing with cross-platform compatibility
const markdownFiles = await safeGlobby([
  "docs/**/*.md",
  "blog/**/*.md",
], {
  ignore: GlobExcludeDefault, // Exclude test files and private files
});
console.log("Found markdown files:", markdownFiles);

// Find translatable source files
const translatableFiles = await globTranslatableSourceFiles([
  "src/**/*.{js,jsx,ts,tsx}",
  "docs/**/*.{md,mdx}",
]);
console.log("Translatable files:", translatableFiles);

// Create pattern matcher
const isTestFile = createMatcher([
  "**/*.test.{js,ts}",
  "**/__tests__/**",
  "**/test/**",
]);

console.log(isTestFile("src/utils.test.js")); // true
console.log(isTestFile("src/utils.js"));      // false

// Create absolute path matcher
const isDocFile = createAbsoluteFilePathMatcher(
  ["docs/**/*.md"],
  ["/website"]
);

console.log(isDocFile("/website/docs/intro.md")); // true
console.log(isDocFile("/website/src/index.js"));  // false

import { 
  getContentPathList, 
  getDataFilePath,
  readDataFile 
} from "@docusaurus/utils";

// Example: Loading plugin configuration with i18n support
async function loadPluginConfig(pluginId: string) {
  const contentPaths = {
    contentPath: `/website/docs`,
    contentPathLocalized: `/website/i18n/en/docusaurus-plugin-content-docs/${pluginId}`,
  };

  try {
    // Try to load localized config first, then fallback to base
    const configData = await readDataFile({
      filePath: "config.yml",
      contentPaths,
    });
    
    return configData;
  } catch (error) {
    console.warn(`No config file found for plugin ${pluginId}, using defaults`);
    return {};
  }
}

// Example: Processing files in priority order
async function processContentFiles(contentPaths: ContentPaths) {
  const searchPaths = getContentPathList(contentPaths);
  
  for (const searchPath of searchPaths) {
    const files = await safeGlobby(["**/*.md"], {
      cwd: searchPath,
      absolute: true,
    });
    
    console.log(`Processing ${files.length} files from ${searchPath}`);
    // Process files from this directory
  }
}