align

A monorepo structural alignment checker. Scans a codebase against rules defined in align.toml and reports which directories comply with or violate declared standards.

Install

Download a pre-built binary from Releases:

# Linux / macOS
curl -fsSL https://github.com/skooch/align-internal/releases/latest/download/align-$(uname -m)-$(uname -s | tr A-Z a-z).tar.gz | tar xz
sudo mv align /usr/local/bin/

Or build from source (requires Zig 0.15.2+):

zig build -Doptimize=ReleaseSafe
# binary at zig-out/bin/align

Usage

Generate a starter config, or create an align.toml manually:

align init

[vars]
node_version = ">=18"

# Table path = directory glob + filename
["services/*"."package.json"]
name = "must-have-package-json"
check = "file_exists"

# Named rule with explicit expect (last segment becomes rule ID)
["services/*".no-env-files]
check = "file_not_exists"
expect = ".env"

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

["services/*".correct-node-version]
check = "field_contains"
expect = "package.json"
format = "json"
field = "engines.node"
pattern = "var:node_version"

Run:

$ align
PASS  must-have-package-json  services/api   package.json exists
PASS  must-have-package-json  services/web   package.json exists
FAIL  must-have-engines       services/auth  package.json missing field "engines"

Results: 8 passed, 1 failed, 9 total

Exit code 1 if any rules fail, 0 if all pass.

CLI Options

Usage: align [COMMAND] [OPTIONS]

Commands:
  init                   Generate a starter align.toml

Options:
  -c, --config <PATH>    Config file path (default: align.toml)
  -f, --format <FORMAT>  Output format: text, json (default: text)
  -q, --quiet            Only show failures and summary
  -V, --version          Show version
  -h, --help             Show this help message

JSON output is useful for CI integrations:

align --format json | jq '.failed'

GitHub Action

Use align as a GitHub Action in your CI pipeline:

- uses: skooch/align-internal@v1
  with:
    config: 'align.toml'  # optional, this is the default

The action downloads a pre-built binary, runs the checks, creates GitHub annotations for failures, and writes a job summary.

Inputs:

Input	Default	Description
config	align.toml	Path to config file
version	latest	Release version (e.g. v0.1.0)

Outputs: passed, failed, total

Git Hook

Use align as a pre-commit hook:

# .git/hooks/pre-commit
#!/bin/sh
align --quiet

Documentation

See the docs/ directory for full documentation:

• Home -- overview and quick start
• Configuration -- align.toml format reference
• Check Types -- every check type with examples
• Variables and References -- var:, env:, and file: syntax
• Examples -- real-world monorepo configs

Testing

zig build test              # unit tests
zig build integration-test  # CLI integration tests