Config¶

mcp_zen_of_languages.config ¶

Configuration discovery, YAML loading, and pipeline override merging.

Every zen analysis session begins here. This module owns the lifecycle of zen-config.yaml—from locating the file on disk, through YAML parsing, to Pydantic-validated ConfigModel construction with fully resolved detector pipelines.

Discovery algorithm When no explicit path is supplied, the loader walks the filesystem upward from the current working directory, inspecting each directory for zen-config.yaml. The walk stops at the first directory that contains a pyproject.toml (the project-root marker), even when no config file has been found yet. This prevents accidental reads from unrelated parent projects.

Merge semantics User-supplied YAML keys are shallow-merged over built-in defaults so that a minimal config (e.g. just severity_threshold: 3) inherits every other default without the author having to repeat them.

Pipeline generation If the resolved config contains no pipelines section, the loader auto-generates one pipeline per declared language by projecting zen-principle rules through PipelineConfig.from_rules.

See Also

PipelineConfig: Per-language detector pipeline model. merge_pipeline_overrides: Merges user overrides into rule-derived base pipelines by detector type.

Classes¶

ConfigModel ¶

Bases: BaseModel

Root Pydantic model that holds every tunable knob for zen analysis.

ConfigModel is the single source of truth produced by load_config. Analyzers, the MCP server, and the CLI all receive a validated instance of this model—never a raw dictionary—so typos in YAML keys surface as ValidationError rather than silent mis-configuration.

ATTRIBUTE	DESCRIPTION
`languages`	Ordered list of language identifiers that the analysis session will support. Defaults to ten built-in languages (python, ruby, typescript, javascript, go, rust, bash, powershell, cpp, csharp). Adding an entry here causes `load_config` to auto-generate a pipeline for the language when the `pipelines` section is absent. TYPE: `list[str]`
`severity_threshold`	Minimum severity score (1-10) a violation must reach to be included in analysis results. Violations below this threshold are silently dropped. Default is `5`. TYPE: `int`
`pipelines`	Per-language detector pipeline configurations. Each entry pairs a language identifier with a list of `DetectorConfig` objects that control individual detectors. When the YAML file omits this key the loader auto-generates pipelines from zen-principle rules. TYPE: `list[PipelineConfig]`

Example YAML mapping::

languages:
  - python
  - typescript
severity_threshold: 3
pipelines:
  - language: python
    detectors:
      - type: cyclomatic_complexity
        max_cyclomatic_complexity: 8

Note

model_config = ConfigDict(extra="forbid") rejects unknown keys, turning YAML typos like severitythreshold into immediate validation errors instead of silently ignored fields.

See Also

PipelineConfig: Schema for individual pipeline entries. load_config: Factory that discovers, parses, merges, and validates YAML into a ConfigModel instance.

Functions¶

pipeline_for ¶

pipeline_for(language)

Resolve the effective detector pipeline for a single language.

Resolution follows a two-layer strategy:

Base layer — PipelineConfig.from_rules(language) projects the language's zen principles into detector configs, producing a pipeline whose thresholds mirror the canonical rules.
Override layer — if the user's pipelines list contains an entry whose language field matches, its detectors are merged on top of the base layer by detector type via merge_pipeline_overrides. Detectors present only in the base are kept unchanged; detectors present only in the override are appended.

When no matching override exists the base pipeline is returned unmodified, ensuring every supported language always gets a complete detector configuration even with a minimal YAML file.

PARAMETER	DESCRIPTION
`language`	Case-sensitive language identifier (e.g. `"python"`, `"typescript"`). TYPE: `str`

RETURNS	DESCRIPTION
`PipelineConfig`	Fully resolved `PipelineConfig` with base TYPE: `PipelineConfig`
`PipelineConfig`	detectors and any user overrides merged in.

See Also

PipelineConfig.from_rules: Builds the base pipeline from zen principles. merge_pipeline_overrides: Performs the per-detector-type merge of base and override configs.

Source code in src/mcp_zen_of_languages/config.py

def pipeline_for(self, language: str) -> PipelineConfig:
    """Resolve the effective detector pipeline for a single language.

    Resolution follows a two-layer strategy:

    1. **Base layer** — ``PipelineConfig.from_rules(language)`` projects
       the language's zen principles into detector configs, producing a
       pipeline whose thresholds mirror the canonical rules.
    2. **Override layer** — if the user's ``pipelines`` list contains an
       entry whose ``language`` field matches, its detectors are merged
       on top of the base layer by detector ``type`` via
       ``merge_pipeline_overrides``.  Detectors present only in the
       base are kept unchanged; detectors present only in the override
       are appended.

    When no matching override exists the base pipeline is returned
    unmodified, ensuring every supported language always gets a
    complete detector configuration even with a minimal YAML file.

    Args:
        language (str): Case-sensitive language identifier (e.g.
            ``"python"``, ``"typescript"``).

    Returns:
        PipelineConfig: Fully resolved ``PipelineConfig`` with base
        detectors and any user overrides merged in.

    See Also:
        ``PipelineConfig.from_rules``: Builds the base pipeline from
            zen principles.
        ``merge_pipeline_overrides``: Performs the per-detector-type
            merge of base and override configs.
    """
    from mcp_zen_of_languages.analyzers.pipeline import merge_pipeline_overrides

    base = PipelineConfig.from_rules(language)
    for pipeline in self.pipelines:
        if pipeline.language == language:
            return merge_pipeline_overrides(base, pipeline)
    return base

Functions¶

load_config ¶

load_config(path=None)

Discover, load, and validate zen-config.yaml into a ConfigModel.

The discovery algorithm searches for zen-config.yaml using a deterministic walk that balances convenience with safety:

Explicit path — when path is supplied the file is read directly; no filesystem walk occurs.
CWD check — Path.cwd() / "zen-config.yaml" is tried first.
Upward walk — each parent directory is inspected in order. The walk halts as soon as a directory containing pyproject.toml is reached (the project-root marker), even if no config was found, preventing accidental reads from unrelated ancestor projects.

Once a file is located the raw YAML is shallow-merged over the built-in defaults (ConfigModel()), so a minimal file that sets only severity_threshold: 3 inherits every other default without repetition.

If the merged config has an empty pipelines list, a pipeline is auto-generated for each language in languages by calling PipelineConfig.from_rules, guaranteeing that every declared language ships with a complete detector configuration.

PARAMETER	DESCRIPTION
`path`	Filesystem path to `zen-config.yaml`. Pass `None` (the default) to activate auto-discovery. Default to None. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`ConfigModel`	Validated `ConfigModel` reflecting the merged TYPE: `ConfigModel`
`ConfigModel`	configuration. Returns a default `ConfigModel` when no config
`ConfigModel`	file is found anywhere on the search path.

RAISES	DESCRIPTION
`yaml.YAMLError`	If the file contains invalid YAML syntax.
`ValidationError`	If merged values violate `ConfigModel` constraints (e.g. unknown keys due to `extra="forbid"`).

Examples:

Explicit path::

cfg = load_config("/repo/zen-config.yaml")

Auto-discovery from CWD::

cfg = load_config()  # walks CWD → parents → pyproject.toml

See Also

ConfigModel: The Pydantic model returned by this function. PipelineConfig.from_rules: Generates pipelines when pipelines is empty.

Source code in src/mcp_zen_of_languages/config.py

def load_config(path: str | None = None) -> ConfigModel:  # noqa: C901, PLR0912
    """Discover, load, and validate ``zen-config.yaml`` into a ``ConfigModel``.

    The discovery algorithm searches for ``zen-config.yaml`` using a
    deterministic walk that balances convenience with safety:

    1. **Explicit path** — when *path* is supplied the file is read
       directly; no filesystem walk occurs.
    2. **CWD check** — ``Path.cwd() / "zen-config.yaml"`` is tried first.
    3. **Upward walk** — each parent directory is inspected in order.
       The walk halts as soon as a directory containing
       ``pyproject.toml`` is reached (the project-root marker), even if
       no config was found, preventing accidental reads from unrelated
       ancestor projects.

    Once a file is located the raw YAML is shallow-merged over the
    built-in defaults (``ConfigModel()``), so a minimal file that sets
    only ``severity_threshold: 3`` inherits every other default without
    repetition.

    If the merged config has an empty ``pipelines`` list, a pipeline is
    auto-generated for each language in ``languages`` by calling
    ``PipelineConfig.from_rules``, guaranteeing that every declared
    language ships with a complete detector configuration.

    Args:
        path (str | None, optional): Filesystem path to ``zen-config.yaml``.  Pass
            ``None`` (the default) to activate auto-discovery. Default to None.

    Returns:
        ConfigModel: Validated ``ConfigModel`` reflecting the merged
        configuration.  Returns a default ``ConfigModel`` when no config
        file is found anywhere on the search path.

    Raises:
        yaml.YAMLError: If the file contains invalid YAML syntax.
        ValidationError: If merged values violate ``ConfigModel``
            constraints (e.g. unknown keys due to ``extra="forbid"``).

    Examples:
        Explicit path::

            cfg = load_config("/repo/zen-config.yaml")

        Auto-discovery from CWD::

            cfg = load_config()  # walks CWD → parents → pyproject.toml

    See Also:
        ``ConfigModel``: The Pydantic model returned by this function.
        ``PipelineConfig.from_rules``: Generates pipelines when
            ``pipelines`` is empty.
    """
    from pathlib import Path

    default = ConfigModel()

    if not path:
        cwd_config = Path.cwd() / "zen-config.yaml"
        if cwd_config.exists():
            path = str(cwd_config)
        else:
            current = Path.cwd()
            for parent in [current, *current.parents]:
                candidate = parent / "zen-config.yaml"
                if candidate.exists():
                    path = str(candidate)
                    break
                if (parent / "pyproject.toml").exists():
                    break

    if not path:
        return default
    try:
        with Path(path).open() as f:
            data = yaml.safe_load(f) or {}
        merged = {**default.model_dump(), **data}
        env_severity_threshold = os.environ.get("ZEN_SEVERITY_THRESHOLD")
        if env_severity_threshold is not None:
            try:
                merged["severity_threshold"] = int(env_severity_threshold)
            except ValueError as exc:
                msg = (
                    "Environment variable ZEN_SEVERITY_THRESHOLD must be an integer "
                    f"between 1 and 10; got {env_severity_threshold!r}"
                )
                raise ValueError(msg) from exc
        cfg = ConfigModel.model_validate(merged)
        if not cfg.pipelines:
            cfg = cfg.model_copy(
                update={
                    "pipelines": [
                        PipelineConfig.from_rules(lang) for lang in cfg.languages
                    ],
                },
            )
    except FileNotFoundError:
        return default
    except Exception:
        raise
    else:
        return cfg

mcp_zen_of_languages.languages.configs ¶

Pydantic configuration models for violation detectors across all supported languages.

Each model inherits from DetectorConfig and adds fields specific to a single detector type. The type literal acts as a discriminator so the pipeline can deserialize heterogeneous detector configurations from zen-config.yaml into the correct Pydantic class.

See Also

mcp_zen_of_languages.analyzers.pipeline: Merges these configs with rule-derived defaults at analysis time.

Classes¶

RuleContext ¶

Bases: BaseModel

Rule-scoped metadata preserved for composite detectors.

Composite detectors may cover several rule ids while sharing one detector implementation and one config type. This model keeps the original principle-specific metadata so detectors can render the correct rule label, severity, and default violation messages at emission time.

DetectorConfig ¶

Bases: BaseModel

Base configuration shared by every violation detector.

Subclasses add detector-specific fields while inheriting common metadata like principle_id, severity, and violation_messages.

ATTRIBUTE	DESCRIPTION
`type`	Discriminator string that uniquely identifies the detector kind. TYPE: `str`
`principle_id`	Optional zen principle identifier this detector enforces. TYPE: `str \| None`
`principle`	Human-readable name of the zen principle, used as a fallback violation message when no specific messages are configured. TYPE: `str \| None`
`severity`	Violation severity on a 1-10 scale (1 = informational, 10 = critical). TYPE: `int \| None`
`violation_messages`	Ordered list of message templates; the first matching template is selected at report time. TYPE: `list[str] \| None`
`detectable_patterns`	Literal strings or `!`-prefixed required-absence patterns that the rule-pattern detector scans for. TYPE: `list[str] \| None`
`recommended_alternative`	Suggestion text appended to violation reports when a better practice exists. TYPE: `str \| None`
`rule_contexts`	Rule-specific metadata map used by composite detectors to emit precise principle labels and severities. TYPE: `dict[str, RuleContext]`

Functions¶

select_violation_message ¶

select_violation_message(
    *, contains=None, index=0, rule_id=None
)

Choose a violation message by substring match or positional index.

When contains is given, the first message whose text includes that substring is returned. Otherwise the message at index is used, falling back to the first message, the principle name, or the type discriminator if no messages are configured.

PARAMETER	DESCRIPTION
`contains`	Optional substring to match against available messages. Default to None. TYPE: `str \| None` DEFAULT: `None`
`index`	Zero-based position selecting a message when no substring match is requested. Default to 0. TYPE: `int` DEFAULT: `0`
`rule_id`	Optional rule identifier for composite detectors. When provided and available, message selection uses that rule's preserved context. Default to None. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`str`	The selected violation message text. TYPE: `str`