NAME

detect_circular_aliases.pl - Detect circular references in YAML or JSON alias files

SYNOPSIS

perl detect_circular_aliases.pl [options]

Options:
  --file=FILENAME -f   Path to the alias file to analyze (default: aliases.yml)
  --format=FORMAT -t   Explicitly specify format: YAML or JSON
                       (default: auto-detect from file extension)
  --debug         -d   Enable debug output showing full alias expansion
  --help          -h   Display usage information

detect_circular_aliases.pl  [-h] [-d] -f /some/path/to/aliases.yml [-t YAML or JSON]

DESCRIPTION

This script analyzes YAML or JSON alias files to identify circular references between aliases. It detects situations where alias A references alias B, which in turn references back to alias A, either directly or through a chain of other aliases.

The script handles various formats of alias definitions including: - Direct string references - Comma-separated lists - Array entries - Nested references

ARGUMENTS

--file=FILENAME or -f FILENAME

Path to the alias file to analyze. Defaults to 'aliases.yml' if not specified.

--format=FORMAT or -t FORMAT

Explicitly specify the file format as either 'YAML' or 'JSON'. If not specified, the format is auto-detected from the file extension:

- '.yml', '.yaml', or '.YAML' for YAML format
- '.json', '.jsn', or '.JSON' for JSON format

--debug or -d

Enable debug output to print the full expansion of each alias for verification and troubleshooting purposes.

--help or -h

Display usage information and exit.

OUTPUT

The script outputs:

1. Warnings for any detected circular references, showing the complete path
2. With the --debug flag, also prints the full expansion of each alias for
   verification and troubleshooting purposes.

EXAMPLE

For a YAML file with:

Jill: Jill@example.com, VP
VP: Jill
tech_team:
  - john@company.com, mary
  - dev_leads
dev_leads:
  - sarah@company.com
  - tech_team

Or a JSON file with:

{
    "Jill": "Jill@example.com, VP",
    "VP": "Jill",
    "tech_team": [
        "john@company.com, mary",
        "dev_leads"
    ],
    "dev_leads": [
        "sarah@company.com",
        "tech_team"
    ]
}

The script will detect and report: WARNING: Circular references detected: Jill -> VP -> Jill tech_team -> dev_leads -> tech_team

INTERNAL FUNCTIONS

detect_circular_references($aliases)

Main entry point for circular reference detection. Takes a hash reference of aliases and returns an array of paths representing circular references.

check_circular($key, $aliases, $path, $seen_paths, $circular_references)

Recursive function that follows alias references, tracking the path to detect circular references.

process_item($item, $aliases, $path, $seen_paths, $circular_references)

Processes individual items within alias values, handling comma-separated values and recursively checking for circular references.

expand_alias($key, $aliases, $seen, $indent)

Expands an alias for verification purposes, showing the full hierarchy of values.

expand_scalar_item($item, $aliases, $seen, $indent)

Helper function to expand scalar items within alias values.

LIMITATIONS

The script does not handle complex structures beyond arrays and scalars. Hash references within alias values would require additional processing logic. That does not seem to be needed in practical use.

The script assumes the file holds email alias definitions. Single line values are stored as string entries. Multi-line alias values are stored as arrays.

This script is presented to demonstrate how to use Mail::Alias::LocalFile

AUTHOR Russ Brewer (RBREW)

Created on March 3, 2025