Masterbelt

masterbelt/masterbelt

Configuration

Synced from main@9490864MarkdownSource

#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 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.
Specification