Models¶

Bases: StrEnum

High-level analysis perspective selector for CLI and MCP surfaces.

Bases: BaseModel

Pin-point position inside a source file.

Detectors attach a Location to every Violation they emit so that downstream consumers — IDE extensions, CLI reporters, dashboard renderers — can jump straight to the offending line. Both fields use 1-based indexing to match what editors display to users.

Bases: BaseModel

A single zen-principle violation detected in analysed code.

When a detector in the pipeline spots code that breaks an idiomatic rule — say, a function whose cyclomatic complexity exceeds the configured ceiling — it creates a Violation carrying the rule identity, a human-readable explanation, and an optional fix hint.

The model deliberately exposes get() and __getitem__() so that older test suites that treated results as plain dictionaries keep working unchanged. New code should use attribute access directly.

get(key, default=None)

121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

def get(self, key: str, default: object | None = None) -> object | None:
    """Retrieve a field value by name, falling back to *default*.

    This bridge keeps older test code that calls ``violation.get("severity")``
    running without modification.  Under the hood it delegates to
    ``getattr``, so any Pydantic field is reachable.

    Args:
        key (str): Attribute name matching one of the model fields
            (e.g. ``"principle"``, ``"severity"``).
        default (object | None, optional): Fallback returned when *key* does not
            correspond to an existing attribute.  Defaults to ``None``.

    Returns:
        object | None: The field value when *key* exists, otherwise
        *default*.

    Example:
        >>> v = Violation(principle="flat", severity=4, message="too deep")
        >>> v.get("severity")
        4
        >>> v.get("nonexistent", "fallback")
        'fallback'
    """
    return getattr(self, key, default)

Bases: BaseModel

Complexity measurement for a single callable block.

Radon (or an equivalent metric engine) walks the AST and produces one CyclomaticBlock per function, method, or top-level code block. The block records the callable's name, its McCabe complexity score, and the line where the definition starts — enough for a detector to decide whether the block breaches the configured threshold.

Bases: BaseModel

Aggregate complexity profile for an entire file or snippet.

After every callable has been scored individually, the analyser rolls the per-block numbers into a CyclomaticSummary. The average gives a quick health indicator, while the full blocks list lets detectors flag only the functions that actually exceed the threshold — avoiding noisy blanket warnings.

Bases: BaseModel

Container for every numeric measurement extracted from a source file.

The analyser's compute_metrics hook populates this model after parsing is complete. Downstream, the detection pipeline reads these numbers to decide which zen-principle thresholds have been crossed, and the MCP server serialises them back to the client alongside the violation list.

Bases: BaseModel

Quick-glance severity histogram for a single analysis run.

After the pipeline finishes, violations are bucketed into four tiers so that reporters can display a compact traffic-light summary without iterating the full violation list. The buckets mirror the tier boundaries defined in zen-config.yaml.

Bases: BaseModel

Project-wide severity breakdown across all analysed files.

While RulesSummary counts violations inside a single file, SeverityCounts rolls those numbers up to the whole repository or project scope. The ProjectSummary model embeds one instance so that dashboards can render a top-level health badge in a single read.

Bases: BaseModel

Spotlight on the file that accumulated the most violations.

After a repository scan, the server sorts files by violation count and surfaces the top offenders so that developers know where to focus remediation effort first. Each entry records the file path, the raw count, and — when determinable — the language that was used for analysis.

Bases: BaseModel

Bird's-eye health report spanning an entire repository scan.

When the MCP server analyses a multi-file project, it folds individual AnalysisResult objects into a single ProjectSummary — giving the caller total file and violation counts, a severity histogram, and a ranked list of the worst-offending files. This is the payload behind the analyze_zen_repository tool's summary section.

Bases: BaseModel

Execution metadata for one optional external analysis tool.

Bases: BaseModel

Optional external-analysis envelope attached to AnalysisResult.

Bases: BaseModel

Aggregated universal-dogma signal derived from one or more violations.

Bases: BaseModel

Shared cross-language dogma-domain signal aggregated from dogma findings.

Bases: BaseModel

Universal-dogma findings attached to a single AnalysisResult.

Bases: BaseModel

Primary output produced by every language analyser.

A call to BaseAnalyzer.analyze() returns exactly one AnalysisResult. It bundles the computed metrics, the full violation list, and a composite health score into a single, JSON-serialisable envelope. The MCP server forwards this model directly to the client; the CLI formats it for terminal display.

Like Violation, this model supports bracket access (result["violations"]) so that legacy dict-oriented test assertions continue to pass without rewrites.

Bases: BaseModel

Per-file wrapper used when scanning an entire repository.

During a repository-wide analysis the server produces one RepositoryAnalysis per source file, pairing the file's path and detected language with the full AnalysisResult. Collecting these into a list gives the MCP client an iterable, JSON-friendly manifest of every file that was inspected.

Bases: BaseModel

Record of a recognised architectural or design pattern.

Pattern detectors walk the AST looking for well-known structures — factory functions, observer registrations, strategy switches — and emit a PatternFinding for each match. The finding carries the pattern's canonical name, an optional source location, and a free-form detail string for context that doesn't fit a structured field.

Bases: BaseModel

Bundled response from the architectural-pattern detection pass.

The analyze_zen_patterns MCP tool returns a PatternsResult containing every pattern that was matched in the target code. An empty patterns list simply means no known patterns were detected — it is not an error condition.

Bases: BaseModel

Opaque wrapper around a language-specific parse tree.

Each analyser's parse_code hook returns a ParserResult so that the pipeline can carry the tree through the AnalysisContext without knowing whether the underlying parser produced a tree-sitter node, a stdlib ast.Module, or something else entirely. The type tag lets downstream consumers branch on the parser kind when they need to inspect the tree directly.

Bases: BaseModel

A single circular dependency path found in the import graph.

When the dependency analyser builds a directed graph of module imports and detects a strongly-connected component, it records each cycle as a DependencyCycle. The cycle list names the modules in traversal order — the last element implicitly links back to the first, closing the loop.

Bases: BaseModel

Full dependency-graph report for a codebase or file set.

The dependency analyser constructs a directed graph where each node is a module and each edge is an import statement. After graph construction it runs cycle detection (e.g. Tarjan's algorithm) and packages the raw topology together with any circular paths into this model. Detectors use it to flag architectural violations such as layering breaches or tangled dependency clusters.

Bases: BaseModel

A zen-principle violation enriched with its source file context.

analyze_batch collects violations from multiple files and adds the originating file path and language to each entry so that LLM agents can act on them without needing to correlate back to the original per-file result.

Bases: BaseModel

File-level hotspot record for the batch summary.

The analyze_batch_summary tool ranks files by their worst violations and returns the top offenders as BatchHotspot entries. Each entry captures the file path, language, violation count, and the maximum severity found so that LLM agents can prioritise remediation effort without reading every violation.

Bases: BaseModel

Paginated result returned by a single analyze_batch call.

Each invocation of analyze_batch returns exactly one BatchPage. The cursor field encodes the position to resume from on the next call; a None cursor means the caller has received all violations. The violations list contains only the highest-severity items that fit within the requested max_tokens budget.

Bases: BaseModel

One-shot health overview for the analyze_batch_summary tool.

Unlike the paginated BatchPage, a BatchSummary always fits in a single LLM context window — it trades full violation detail for a compact health score and the top-5 hotspot files. LLM agents can use this as a quick triage step before deciding which analyze_batch pages to retrieve.

Bases: BaseModel

Enumeration of every language the server can currently analyse.

The list_zen_languages MCP tool returns a LanguagesResult so clients can discover which language keys are valid before calling analysis endpoints. The list is populated at startup from the AnalyzerFactory registry and stays stable for the lifetime of the server process.