Add `Activity Diagram` Documentation for application-flow using `mermaid`

[ghostwriter]

Inspired by: https://docs.phpdoc.org/guide/internals/flow.html#application-flow

Example: Activity Diagram for Creating a Project Directory

Flow:

• Start: The user starts the CLI application.
• Input Name: The user inputs a project name.
• Format Name to Kebab-case: Convert the project name to kebab-case.
• Get Current Working Directory
  • If not, display an error and end the process.
  • If so, proceed to the next step.
• Check if Directory Exists: Check if a directory with the formatted name already exists.
  • If the directory exists, display an error and end the process.
  • If not, proceed to the next step.
• Create Directory: Create the directory with the formatted name.
• Confirm Success: Display a success message.
• End: End the process.

The tool would generate

 ```mermaid
  graph TD
      A(Start) --> B(Input Name)
      B --> C{Format Name to Kebab-case}
      C --> D{Get Current Working Directory}
      D -- Fail --> E[Display Error: Could not get CWD]
      D -- Success --> F{Directory Exists?}
      F -- Yes --> G[Display Error: Directory exists]
      F -- No --> H(Create Directory)
      H --> I[Display Success]
      E --> J(End)
      G --> J(End)
      I --> J(End)
\```

Which GitHub will render as the example below.

eg.

graph TD
    A(Start) --> B(Input Name)
    B --> C{Format Name to Kebab-case}
    C --> D{Get Current Working Directory}
    D -- Fail --> E[Display Error: Could not get CWD]
    D -- Success --> F{Directory Exists?}
    F -- Yes --> G[Display Error: Directory exists]
    F -- No --> H(Create Directory)
    H --> I[Display Success]
    E --> J(End)
    G --> J(End)
    I --> J(End)

Loading

PHP

#!/usr/bin/env php
<?php

declare(strict_types=1);

final class ProjectCreator
{
    public function run(array $arguments): void
    {
        if (count($arguments) < 2) {
            $this->outputError('Please provide a project name.');
            exit(1);
        }

        $projectName = $arguments[1];
        $formattedName = $this->formatToKebabCase($projectName);
        $currentWorkingDirectory = getcwd();

        if ($currentWorkingDirectory === false) {
            $this->outputError('Could not determine the current working directory.');
            exit(1);
        }

        $directoryPath = $currentWorkingDirectory . DIRECTORY_SEPARATOR . $formattedName;

        if (file_exists($directoryPath)) {
            $this->outputError("Directory '{$formattedName}' already exists.");
            exit(1);
        }

        if (! mkdir($directoryPath, 0755, true)) {
            $this->outputError('Failed to create project directory.');
            exit(1);
        }

        $this->outputSuccess("Project directory '{$formattedName}' created successfully.");
        exit(0);
    }

    private function formatToKebabCase(string $input): string
    {
        return strtolower(preg_replace('/[^\w]+/', '-', trim($input)));
    }

    private function outputError(string $message): void
    {
        fwrite(STDERR, "Error: {$message}" . PHP_EOL);
    }

    private function outputSuccess(string $message): void
    {
        fwrite(STDOUT, "{$message}" . PHP_EOL);
    }
}

$projectCreator = new ProjectCreator();
$projectCreator->run($argv);

[ghostwriter]

https://github.com/mermaid-js/mermaid-cli
https://mermaidchart.com/play
https://mermaid.live/