# Configuration

Project configuration provides user workspace settings to tooling commands.

- The project configuration loader is the single entry point for workspace configuration.
- The loader may load multiple configuration sources over time.

## Project Configuration Files

- Project-local configuration is read from YAML.
- By default, tools look for `masterbelt.yml` and then `masterbelt.yaml` in the working directory.
- When a configuration path is explicitly provided, tools read that file instead of the default paths.
- Relative explicit configuration paths are resolved from the working directory.
- If the explicitly provided configuration file does not exist or cannot be read, configuration loading fails.
- The currently implemented project-local configuration schema is empty.
- Unknown project-local configuration fields are invalid.
- If project-local YAML cannot be parsed, configuration loading fails.

## Code Generation Targets

- `targets: LIST` declares the code generation targets configured for the project.
- An absent `targets` key, or an empty list, means no targets are configured.
- Each list entry is a mapping with the following keys:
  - `kind: STRING` selects which generation behavior is used. The kind identifier is defined by each target's own specification.
  - `out: PATH` is the output root directory. Generated file paths are interpreted relative to this directory. Relative `out` paths are resolved from the project root. `out` is required.
  - `options: MAP` is a free-form mapping interpreted only by the target whose kind it carries. The shape of the options mapping is defined by each target's own specification. `options` is optional.
- Multiple entries with the same `kind` are allowed; each is configured and runs independently.
- A target entry with an empty or missing `kind` is invalid.
- A target entry with an empty or missing `out` is invalid.

## Entrypoint

- `entry: PATH` sets the project entrypoint file.
- Relative entrypoint paths are resolved from the working directory.
- Project configuration loading resolves the entrypoint path but does not validate its existence, file type, or extension.
- Source graph construction validates that the resolved entrypoint is an existing Masterbelt source file.
- Tools that build a Masterbelt source graph require an entrypoint file.
- Tools that operate only on explicit source inputs, such as `fmt`, do not require an entrypoint file.

## Validators

- `validators: MAP` configures the failure severity of master [validation](../masterdata/validation.md) rules.
- The outer key is the **entrypoint-visible master path** — the master as it is visible from the entry module. A top-level master uses its declared name (for example `Records`); a nested master uses its dotted path (for example `User.Friendships`); an aliased re-export `pub { User as U }` uses the alias (for example `U.Friendships`). The flattened codegen name (for example `UserFriendships`) is never used here.
- The inner key is a validator id declared in that master's `validation` section.
- The value is the override severity, either `error` or `warning`; no other value is accepted.

```yaml
validators:
  Records:
    nameRequired: warning
    valuePositive: error
  U.Friendships:
    uniquePair: warning
```

A failed `assert` defaults to `error` severity; a `validators` override can lower it to `warning`. An `error`-severity failure blocks the export and no artifact is written; a `warning`-severity failure is reported but does not block. Configuration is validated before validators run, so a typo is visible even when a master imported zero records:

- A master path that matches no master is `masterbelt.validation.config_unknown_master`.
- A validator id that matches no rule under a known master is `masterbelt.validation.config_unknown_validator`.
- A severity outside `error` / `warning` is `masterbelt.validation.config_invalid_severity`.

Each of these config diagnostics blocks the export. The `validators` mapping is parsed under the same strict YAML rules as the rest of project configuration, so unknown top-level keys are still rejected.

## Path-Specific Configuration

- The currently implemented path-specific configuration source is EditorConfig.

### Discovery

- Tools discover EditorConfig files by walking from the input file directory toward the filesystem root.
- For standard input, tools walk from the current working directory.
- Discovery stops after reading an EditorConfig file with `root = true`.

### Formatter Indentation

Formatter indentation is resolved from the matching EditorConfig properties for the specific input or output path.

- Configuration is path-specific. Settings for one file pattern, such as `*.mst`, must not be reused for another file pattern, such as `*.ts`.
- If `indent_style = tab`, one formatter indentation level is one tab.
- If `indent_style = space`, one formatter indentation level is `indent_size` spaces.
- If `indent_size` is unset, `tab`, or not a positive decimal integer, the formatter default indentation is used.
- If no matching EditorConfig indentation is found, the formatter default indentation is used.