File Resolution

Configuration file discovery and resolution system with support for multiple file formats and directory traversal.

Core Functions

detectConfigurationFile

function detectConfigurationFile(
  fileSystem: IFileSystem,
  configFileOrFolderUri: string | null,
  logger?: AutorestLogger,
  walkUpFolders?: boolean
): Promise<string | undefined>;

Detects and returns the path to a single configuration file in the specified location.

Parameters:

• fileSystem: IFileSystem - File system interface for file operations
• configFileOrFolderUri: string | null - URI or folder path to search in
• logger?: AutorestLogger - Optional logger for diagnostic messages
• walkUpFolders?: boolean - Whether to recursively check parent folders (default: false)

Returns:

• Promise<string | undefined> - Path to the detected configuration file, or undefined if none found

Resolution Priority:

1. Files named with the default configuration name (typically readme.md)
2. Shortest filename among detected configuration files

Example:

import { detectConfigurationFile } from "@autorest/configuration";
import { RealFileSystem } from "@azure-tools/datastore";

const fileSystem = new RealFileSystem();
const configFile = await detectConfigurationFile(
  fileSystem,
  "./config",
  logger,
  true // Walk up parent folders
);

if (configFile) {
  console.log(`Found configuration: ${configFile}`);
}

detectConfigurationFiles

function detectConfigurationFiles(
  fileSystem: IFileSystem,
  configFileOrFolderUri: string | null,
  logger?: AutorestLogger,
  walkUpFolders?: boolean
): Promise<Array<string>>;

Detects and returns paths to all configuration files in the specified location.

Parameters:

• fileSystem: IFileSystem - File system interface for file operations
• configFileOrFolderUri: string | null - URI or folder path to search in
• logger?: AutorestLogger - Optional logger for diagnostic messages
• walkUpFolders?: boolean - Whether to recursively check parent folders (default: false)

Returns:

• Promise<Array<string>> - Array of paths to all detected configuration files

Example:

import { detectConfigurationFiles } from "@autorest/configuration";
import { RealFileSystem } from "@azure-tools/datastore";

const fileSystem = new RealFileSystem();
const configFiles = await detectConfigurationFiles(
  fileSystem,
  "./",
  logger
);

console.log(`Found ${configFiles.length} configuration files:`);
configFiles.forEach(file => console.log(`  ${file}`));

Configuration File Constants

DefaultConfiguration

const DefaultConfiguration: string;

The default configuration file name that AutoRest looks for (typically readme.md).

MagicString

const MagicString: string;

Magic string used to identify AutoRest configuration files.

Supported File Formats

The file resolution system supports multiple configuration file formats:

Markdown Files (.md)

• Literate YAML format with embedded code blocks
• Support for conditional configuration via guard expressions
• Primary format for complex configuration scenarios

YAML Files (.yaml, .yml)

• Standard YAML configuration format
• Direct configuration specification
• Suitable for simple configuration scenarios

JSON Files (.json)

• JSON configuration format
• Structured configuration data
• Programmatic configuration generation

Resolution Behavior

Directory Search

When given a directory path, the resolver:

1. Searches for files with supported extensions
2. Prioritizes files with the default configuration name
3. Returns the shortest filename if multiple files are found
4. Optionally walks up parent directories if walkUpFolders is true

File Detection

The resolver identifies configuration files by:

1. File extension matching (.md, .yaml, .yml, .json)
2. Content analysis for markdown files
3. Presence of AutoRest configuration markers

Null Input Handling

When configFileOrFolderUri is null:

• Returns empty array for detectConfigurationFiles
• Returns undefined for detectConfigurationFile
• No file system operations are performed

Usage Patterns

Basic File Detection

import { detectConfigurationFile } from "@autorest/configuration";
import { RealFileSystem } from "@azure-tools/datastore";

const fileSystem = new RealFileSystem();

// Detect configuration in current directory
const configFile = await detectConfigurationFile(fileSystem, ".");

// Detect configuration in specific folder
const configFile2 = await detectConfigurationFile(fileSystem, "./config");

// Detect configuration with parent folder search
const configFile3 = await detectConfigurationFile(fileSystem, ".", logger, true);

Multiple Configuration Files

import { detectConfigurationFiles } from "@autorest/configuration";

// Find all configuration files in a directory
const allConfigs = await detectConfigurationFiles(fileSystem, "./configs");

// Process each configuration file
for (const configFile of allConfigs) {
  const content = await fileSystem.readFile(configFile);
  // Process configuration content
}

Integration with Configuration Manager

import { 
  detectConfigurationFile, 
  ConfigurationManager 
} from "@autorest/configuration";

const configFile = await detectConfigurationFile(fileSystem, configPath);
if (configFile) {
  const configManager = new ConfigurationManager(configFile, fileSystem);
  // Use detected configuration file
}

isConfigurationDocument

function isConfigurationDocument(content: string): Promise<boolean>;

Checks whether a document is a literate configuration document by looking for the AutoRest magic string.

Parameters:

• content: string - Document content to check for configuration markers

Returns:

• Promise<boolean> - True if the document contains AutoRest configuration, false otherwise

Usage:

import { isConfigurationDocument } from "@autorest/configuration";

const content = await fileSystem.readFile("readme.md");
const isConfig = await isConfigurationDocument(content);

if (isConfig) {
  console.log("File contains AutoRest configuration");
}

Error Handling

The file resolution functions handle various error conditions:

• File system access errors: Logged but don't prevent operation
• Invalid paths: Return empty results gracefully
• Permission errors: Logged with appropriate error messages
• Network errors: For remote file systems, handled gracefully

The functions are designed to be robust and continue operation even when some file system operations fail.