[Enh]: Support `@file()` substitution function.

## What?

In the same way `@env()` and `@akv()` allow for string replacements in the DAB configuration, introduce `@file()` which reads from one or more designated JSON metadata files containing simple name/value dictionaries of `` pairs.

> [!IMPORTANT]
> This allows configuration metadata to be maintained in an external file and injected into the configuration during startup.

## Configuration

```json
{
"metadata-files": [
"./metadata.json",
"./descriptions.json"
]
}
```

Multiple metadata files may be merged. If duplicate keys exist across files, startup fails with an error.

### Example file

```json
{
"dbo.Users.Alias": "Users",
"dbo.Users.Email.MS_Description": "Email address used for authentication"
}
```

### Example usage

```json
{
"metadata-files": [
{ "path": "./metadata.json" }
],
"entities": {
"@file('dbo.Users.Alias')": {
"description": "@file('dbo.Users.Email.MS_Description')",
"source": {
"object": "dbo.Users",
"type": "table"
}
}
}
}
```

## Rules

These rules govern the implementation.

1. Any property name or value can be set using `@file()`.
2. The `@file()` function performs string replacement in the same way `@env()` and `@akv()` do.
3. Metadata files are merged into a single dictionary during startup.
4. If two files contain the same key, an exception is thrown.
5. Metadata files are read during configuration replacement and cached for the duration of startup.
6. Metadata files are not hot-reloaded.

## Syntax

```
@file('')
```

Where `` refers to a key in the merged metadata dictionary.

Example

```
@file('dbo.Users.MS_Description')
```

The resolved value replaces the entire property name or value.

Recursive replacement is allowed. Values returned from `@file()` may contain `@env()` or `@akv()` expressions, which are resolved according to the standard replacement order.

## Order of operation

`@file()` is resolved after `@env()` and `@akv()`.

```mermaid id="h3wh7n"
sequenceDiagram
actor Engine as Engine
participant ConfigInMem as ConfigInMem
participant Environment as Environment
participant AKV as AKV
participant File as MetadataFiles
participant Config as ConfigFile

Engine ->> Config: Load Config
Config -->> Engine: Config Data
Engine ->> ConfigInMem: Create In-Memory Config

Note over Engine: Perform Environment Replacements

activate Engine
ConfigInMem -->> Engine: Parse @env Values
Engine ->> Environment: Get
Environment -->> Engine: Values
Engine ->> ConfigInMem: Replace @env Values
deactivate Engine

Note over Engine: Perform Key Vault Replacements

activate Engine
ConfigInMem -->> Engine: Parse @akv Values
Engine ->> AKV: Request
AKV -->> Engine: Secrets
Engine ->> ConfigInMem: Replace @akv Values
deactivate Engine

Note over Engine: Load Metadata Files

activate Engine
Engine ->> File: Read Files
File -->> Engine: Dictionaries
Engine ->> Engine: Merge Dictionaries
deactivate Engine

Note over Engine: Perform File Metadata Replacements

activate Engine
ConfigInMem -->> Engine: Parse @file Values
Engine ->> Engine: Lookup Key
Engine ->> ConfigInMem: Replace @file Values
deactivate Engine

Note over Engine: Replacements Complete

Engine ->> Engine: Start
```

This also allows each `metadata-files.path` to be set using `@env()` or `@akv()`.

## JSON schema

1. `metadata-files` is an optional property of type `array`.
2. Each element in the array is an object containing:

* `path` of type `string`.
3. No schema-level constraints are enforced for these properties.

## Validation and errors

These rules are implemented in `dab validate` and `dab start`.

1. If `@file()` is present in the configuration, `metadata-files` must be defined.
2. `metadata-files[*].path` cannot use `@file()`.
3. If a metadata file path does not point to an existing file, throw an exception.
4. If a metadata file is not valid JSON containing a `` dictionary, throw an exception.
5. If duplicate keys appear across metadata files, throw an exception.
6. If a referenced `@file('')` does not exist in the merged metadata dictionary, throw an exception.
7. If `metadata-files` exists but no `@file()` references are used, do not throw an exception.

## Metadata file format

Each metadata file contains a simple dictionary.

```json id="1wgr17"
{
"key1": "value",
"key2": "value"
}
```

Each key maps to a string value used for configuration replacement.

## Configuration sample

This sample demonstrates replacing both entity names and property values.

```json id="m7r4n2"
{
"metadata-files": [
{ "path": "./metadata.json" }
],
"entities": {
"@file('dbo.Users.Alias')": {
"description": "@file('dbo.Users.MS_Description')",
"source": {
"object": "dbo.User",
"type": "table"
}
}
}
}
```

## Command line

### Configuration

```
dab configure --metadata-files.path "./file.json"
```

### Validation

`dab validate` and `dab start` enforce all validation rules.

## Considerations

1. Include an OpenTelemetry activity around each replacement.
2. Include an OpenTelemetry activity when loading and merging metadata files.
3. (Optional improvement) Include OTEL activities for `@env()` and `@akv()` replacements for consistency.