Skip to content

Configuration.md

Latest commit

 

History

History
124 lines (86 loc) · 3.62 KB

Configuration.md

File metadata and controls

124 lines (86 loc) · 3.62 KB

Configuration

Align reads align.toml from the current working directory.

File Structure

Rules are declared as TOML tables whose keys form the directory glob and filename:

[vars]
node_version = ">=18"

["services/*"."package.json"]
name = "must-have-package-json"
check = "file_exists"

The table path has two roles:

  • All segments except the last form the directory glob (path)
  • The last segment is the file to check (expect)

[vars] Section (optional)

Key-value pairs that can be referenced in rule fields using the var: prefix. See Variables and References.

[vars]
node_version = ">=18"

Rule Tables

Each TOML table with a check field is a rule. The table path encodes the directory and file being checked.

Basic Form

When the last segment is a filename, it becomes both the rule name (if name is omitted) and the file to check:

["services/*"."package.json"]
check = "file_exists"

This creates a rule named package.json that checks for package.json in every services/* directory.

Named Rules with Explicit expect

When you need multiple rules targeting the same file, or want a descriptive rule ID, use a named last segment with an explicit expect field:

["services/*".must-have-engines]
check = "field_exists"
expect = "package.json"
format = "json"
field = "engines"

Here the last segment (must-have-engines) becomes the rule name, and expect specifies the file.

Nested Paths

Table paths can have any number of segments for deeply nested directory structures:

["infra/*"."subinfra/*"."README.md"]
name = "must-have-readme"
check = "file_exists"

All segments except the last are joined to form the glob: infra/*/subinfra/*.

Rule Fields

Field Required Description
check yes The check type (see Check Types)
name no Rule name for output (defaults to last table segment)
expect no File to check (defaults to last table segment)
pattern conditional Substring to search for. Supports var:, env:, and file: prefixes. Required for *_contains checks.
format conditional File format for structured parsing: "json", "yaml", "toml". Required for field_* checks.
field conditional Dot-notation path to the field (e.g. "engines.node"). Required for field_* checks.
when no Conditional execution. Rule is skipped unless the condition is met (see Conditional Rules).

Conditional Rules

The when field makes a rule run only when a condition is met. Conditions are evaluated against [vars].

Truthy check -- rule runs if the variable is set and non-empty:

[vars]
ci = "env:CI"

["services/*".strict-engines]
check = "field_exists"
expect = "package.json"
format = "json"
field = "engines"
when = "ci"

Equality check -- rule runs if the variable equals a specific value:

[vars]
mode = "env:ALIGN_MODE"

["services/*".prod-dockerfile]
check = "file_exists"
expect = "Dockerfile"
when = "mode=production"

If when references a variable that doesn't exist, the rule is skipped. Combined with env: in vars, this lets you gate rules on environment variables.

Glob Patterns

Directory segments in the table path support * as a wildcard matching a single directory level:

  • "services/*" -- all immediate subdirectories of services/
  • "packages/*"."apps/*" -- nested wildcards
  • "services/api" -- literal path (no wildcard)

Only directories are matched; files are skipped.