cmate 1.0.0

CMate - declarative configuration validation engine

CMate

Your Config Validation Companion

Introduction • Installation • Quick Start • Guide • 中文 • License

---

Introduction

CMate (Config Mate) is a declarative validation engine for configuration files. The name draws inspiration from the chess term Check Mate — it's your configuration "check mate", catching config issues before they reach production.

Why CMate?

Basic correctness checking is table stakes. The real challenge is: the same configuration fields may have entirely different optimal values depending on the deployment scenario.

Take LLM inference services as an example: a PD co-located deployment and a PD disaggregated deployment may require very different recommended values for the same parameter; DeepSeek models and general-purpose models need different validation rule sets. The combinatorial logic of "which fields should have what values under which conditions" typically lives only in expert knowledge — hard to capture and share.

CMate solves this by using context variables to manage scenario switching, and severity levels to distinguish between recommended and mandatory settings. Expert knowledge gets encoded into distributable, executable .cmate rule files.

Key Features

• Intuitive DSL: Syntax inspired by Python, Shell, and JsonPath — writing a validation rule feels like writing a unit test
• Context-driven: Pass context variables via -C to adapt the same rule file to different deployment scenarios
• Three severity levels: error (mandatory) / warning (alert) / info (recommendation), filterable at runtime
• Multiple data sources: Validate JSON, YAML config files and environment variables
• Env script generation: Automatically generates set_env.sh from [par env] rules — source it to apply or revert environment variables
• pytest-style output: Collection, execution, and reporting follow pytest conventions
• Control flow: if/elif/else/fi conditionals and for/done loops
• Extensible functions: Built-in len(), int(), str(), etc., with custom extensions via custom_fn.py

Installation

Requirements

• Python >= 3.7

Install via pip

pip install cmate

Install from source

git clone https://gitcode.com/AvadaKedavrua/cmate.git
cd cmate
pip install -e .

Quick Start

For a full walkthrough, see the Quick Start Guide.

Create demo.cmate:

[metadata]
name = 'Server Port Validation'
version = '1.0'
---

[targets]
config: 'Application config file' @ 'json'
---

[contexts]
env: 'Deployment environment, options: dev / staging / production'
---

[global]
min_port = 1024
if ${context::env} == 'production':
    min_port = 8000
fi
---

[par config]
assert ${config::port} > ${min_port}, 'Port number is too low', error
assert ${config::host} != '', 'Hostname must not be empty', error
assert ${config::timeout} >= 1000, 'Recommended timeout >= 1000ms', info

Create app.json:

{
  "port": 8080,
  "host": "localhost",
  "timeout": 5000
}

Run:

cmate run demo.cmate -c config:app.json -C env:production

Environment Variable Script Generation

When a rule file contains a [par env] section, cmate run automatically generates a set_env.sh script in the current directory. The script sets (or unsets) environment variables to match the expected values declared in your rules:

# Apply the recommended environment variables
source set_env.sh

# Revert to the values before cmate was run
source set_env.sh 0

Customize the output path or disable generation:

# Custom path
cmate run rules.cmate -c env --env-script /tmp/my_env.sh

# Disable generation
cmate run rules.cmate -c env --no-env-script

Rule File Syntax

A .cmate file consists of sections separated by ---:

[metadata] — Metadata

[metadata]
name = 'Rule set name'
version = '1.0'
authors = [{"name": "Author"}]
description = 'Rule set description'
---

[targets] — Validation targets

Declare which configuration files are needed as input. Format: name: 'description' @ 'format':

[targets]
config: 'Main config file' @ 'json'
env_config: 'Environment config' @ 'yaml'
---

Supply actual file paths at runtime via -c: cmate run rules.cmate -c config:app.json

The special target env reads current environment variables without a file path.

[contexts] — Context variables

Declare which context variables the rule file accepts for scenario-based branching:

[contexts]
deploy_mode: 'Deployment mode, options: pd_mix / pd_disaggregation / ep'
model_type: 'Model type, e.g. deepseek / general'
---

Supply values at runtime via -C: cmate run rules.cmate -c config:app.json -C deploy_mode:ep

Reference in rules with ${context::variable_name}.

[global] — Global variables

Define global variables and conditional assignment logic, available in subsequent [par] sections:

[global]
max_connections = 100

if ${context::env} == 'production':
    max_connections = 500
fi
---

[par <target>] — Partition rules

par is short for partition. Each partition corresponds to a target and contains assert statements:

[par config]
# Basic assertion: assert <expression>, 'message', <severity>
assert ${config::enabled} == true, 'Service must be enabled', error
assert ${config::port} > 1024, 'Port should be above 1024', info

# Conditional assertion
if ${context::deploy_mode} == 'production':
    assert ${config::ssl} == true, 'SSL is required in production', error
fi

# Loop assertion
for host in ${config::allowed_hosts}:
    assert ${host} != '', 'Hostname must not be empty', error
done

# alert statement: flag a field for manual review, no condition evaluated
alert ${config::model_path}, 'Please verify the model path', warning

Severity Levels

Level	Meaning	Output Label
error	Mandatory — failure if not met	[NOK]
warning	Alert — recommended fix	[WARNING]
info	Recommendation — for reference	[RECOMMEND]

Use -s to filter minimum severity: cmate run rules.cmate -c config:app.json -s warning runs only warning and error rules.

Data Access & Expressions

# Access config values (namespace::jsonpath style)
${config::server.port}
${config::items[0].name}
${context::deploy_mode}

# Comparison: ==, !=, <, >, <=, >=, =~ (regex match), in
# Logical: and, or, not
# Arithmetic: +, -, *, /, //, %, **
# Built-in functions: len(), int(), str(), range(), path_exists(), is_port_in_use(), etc.

CLI Reference

# Run validation
cmate run <rule_file> [options]
  -c, --configs   Config files: '<name>:<path>[@<format>]' or 'env'
  -C, --contexts  Context variables: '<name>:<value>'
  -s, --severity  Minimum severity filter: info | warning | error (default: info)
  -x, --fail-fast Stop on first failure
  -v, --verbose   Verbose output
  -k, --lines     Filter rules by line number: '10,20,30'
  -co, --collect-only  List rules without executing
  --output-path   Directory for JSON result output

# Inspect rule file
cmate inspect <rule_file> [options]
  -f, --format    Output format: text | json (default: text)

Project Structure

cmate/
├── cmate/
│   ├── cmate.py        # CLI entry point and core orchestration
│   ├── lexer.py        # Lexer (tokenizer)
│   ├── parser.py       # Parser (grammar)
│   ├── _ast.py         # AST node definitions
│   ├── visitor.py      # AST traversal and evaluation
│   ├── _test.py        # Test runner (pytest-style output)
│   ├── data_source.py  # Data source (namespace::path key-value store)
│   ├── custom_fn.py    # Extensible custom functions
│   └── util.py         # Utilities
├── presets/            # Preset rule file examples
├── tests/             # Unit tests
└── pyproject.toml     # Project configuration

Contributing

Issues and Pull Requests are welcome.

# Development setup
git clone https://gitcode.com/AvadaKedavrua/cmate.git
cd cmate
pip install -e ".[dev]"

# Run tests
pytest tests/

# Lint
lintrunner -a

License

CMate is licensed under Mulan PSL v2.

Copyright (c) 2025-2026 Huawei Technologies Co.,Ltd.

Licensed under the Mulan PSL v2.
You may obtain a copy of the License at:

    http://license.coscl.org.cn/MulanPSL2

THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
See the Mulan PSL v2 for more details.