eirmos 0.4.0__py3-none-any.whl

eirmos/__init__.py

@@ -0,0 +1,70 @@
+"""CI/CD pipeline visualiser.
+
+A small library + CLI for parsing CI/CD pipeline definitions and
+rendering them in various formats (tree, mermaid, dot, summary).
+
+Supported systems: GitLab CI, GitHub Actions, Jenkins, CircleCI,
+Azure Pipelines, Bitbucket Pipelines, Drone CI, Woodpecker CI,
+Travis CI, AppVeyor, Buildkite, Codefresh, Semaphore.
+
+The package is organised in clear architectural layers:
+
+    parsers/    - read pipeline definition files and produce a domain model
+    graph.py    - build a dependency graph from a parser
+    formatters/ - render graphs to text/diagram formats
+    cli.py      - thin command-line entry point
+    colors.py   - ANSI color helpers (presentation only)
+
+New CI systems can be supported by implementing
+:class:`eirmos.parsers.base.BasePipelineParser` and
+registering a :class:`eirmos.parsers.registry.ParserAdapter`.
+"""
+
+from .colors import Colors
+from .parsers.gitlab import GitLabCIParser
+from .parsers.github import GitHubActionsParser
+from .parsers.jenkins import JenkinsParser
+from .parsers.circleci import CircleCIParser
+from .parsers.azure import AzurePipelinesParser
+from .parsers.bitbucket import BitbucketPipelinesParser
+from .parsers.drone import DroneParser, WoodpeckerParser
+from .parsers.travis import TravisCIParser
+from .parsers.appveyor import AppVeyorParser
+from .parsers.buildkite import BuildkiteParser
+from .parsers.codefresh import CodefreshParser
+from .parsers.semaphore import SemaphoreParser
+from .parsers.base import BasePipelineParser
+from .parsers.registry import ParserAdapter, REGISTRY, register_adapter
+from .graph import DependencyGraph
+from .formatters.tree import TreeFormatter
+from .formatters.mermaid import MermaidFormatter
+from .formatters.dot import DotFormatter
+from .formatters.summary import SummaryFormatter
+from .formatters.variables import VariableFormatter
+
+__all__ = [
+    "Colors",
+    "BasePipelineParser",
+    "GitLabCIParser",
+    "GitHubActionsParser",
+    "JenkinsParser",
+    "CircleCIParser",
+    "AzurePipelinesParser",
+    "BitbucketPipelinesParser",
+    "DroneParser",
+    "WoodpeckerParser",
+    "TravisCIParser",
+    "AppVeyorParser",
+    "BuildkiteParser",
+    "CodefreshParser",
+    "SemaphoreParser",
+    "ParserAdapter",
+    "REGISTRY",
+    "register_adapter",
+    "DependencyGraph",
+    "TreeFormatter",
+    "MermaidFormatter",
+    "DotFormatter",
+    "SummaryFormatter",
+    "VariableFormatter",
+]

eirmos/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m eirmos``."""
+
+import sys
+from .cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())

eirmos/_yaml.py

@@ -0,0 +1,25 @@
+"""YAML loader configured for GitLab CI specifics.
+
+Importing this module has the side effect of registering the
+``!reference`` constructor on ``yaml.SafeLoader``.  Centralising
+the import means PyYAML is loaded exactly once and there's a
+single place to change the loader configuration.
+"""
+
+import sys
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - import-time guard
+    print("ERROR: PyYAML is required. Install with: pip install pyyaml")
+    sys.exit(1)
+
+
+def _reference_constructor(loader, node):
+    """Handle GitLab CI ``!reference`` tags by returning the sequence as-is."""
+    return loader.construct_sequence(node)
+
+
+yaml.add_constructor('!reference', _reference_constructor, Loader=yaml.SafeLoader)
+
+__all__ = ["yaml"]

eirmos/cli.py

@@ -0,0 +1,181 @@
+"""Command-line entry point.
+
+Kept intentionally thin: argument parsing + parser/formatter
+selection. All real logic lives in the dedicated modules.
+
+Parser selection is driven by the
+:mod:`eirmos.parsers.registry`, so adding a new CI/CD
+system is a matter of registering a :class:`ParserAdapter`.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .colors import Colors
+from .graph import DependencyGraph
+from .parsers import detect as detect_adapter, REGISTRY
+from .parsers.gitlab import GitLabCIParser
+from .formatters.tree import TreeFormatter
+from .formatters.mermaid import MermaidFormatter
+from .formatters.dot import DotFormatter
+from .formatters.summary import SummaryFormatter
+from .formatters.variables import VariableFormatter
+
+
+FORMATTERS = {
+    'tree': TreeFormatter,
+    'mermaid': MermaidFormatter,
+    'dot': DotFormatter,
+    'summary': SummaryFormatter,
+    'variables': VariableFormatter,
+}
+
+
+def find_ci_files(base_path):
+    """Find all GitLab CI files in the repository.
+
+    Kept for backwards compatibility with previous releases of the
+    package; the CLI now relies on the parser registry.
+    """
+    patterns = ['**/*.gitlab-ci.yml', '**/*.gitlab-ci.yaml', '.gitlab-ci.yml']
+    files = set()
+    for pattern in patterns:
+        for f in Path(base_path).glob(pattern):
+            files.add(f)
+    return sorted(files)
+
+
+def build_arg_parser():
+    supported = ', '.join(a.name for a in REGISTRY) or 'none registered'
+    arg_parser = argparse.ArgumentParser(
+        prog='eirmos',
+        description=(
+            'CI/CD Pipeline Visualiser - Parse and visualise job dependencies. '
+            f'Supported systems: {supported}.'
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    arg_parser.add_argument('path', nargs='?', default='.',
+                            help='Path to repository root (default: current directory)')
+    arg_parser.add_argument('--format', '-f', choices=list(FORMATTERS.keys()),
+                            default='tree', help='Output format (default: tree)')
+    arg_parser.add_argument('--stage', '-s', default=None,
+                            help='Filter output to a specific stage')
+    arg_parser.add_argument('--job', '-j', default=None,
+                            help='Show detailed dependencies for a specific job')
+    arg_parser.add_argument('--no-includes', action='store_true',
+                            help='Do not follow local include directives (GitLab only)')
+    arg_parser.add_argument('--output', '-o', default=None,
+                            help='Output file path (default: stdout)')
+    arg_parser.add_argument('--no-color', action='store_true',
+                            help='Disable colored output')
+    arg_parser.add_argument('--list-stages', action='store_true',
+                            help='List all stages and exit')
+    arg_parser.add_argument('--list-jobs', action='store_true',
+                            help='List all jobs and exit')
+    arg_parser.add_argument('--ci', default=None,
+                            choices=[a.name for a in REGISTRY],
+                            help='Force a specific CI system instead of auto-detection')
+    return arg_parser
+
+
+def _select_ci_file(base_path, forced_name=None):
+    """Return ``(adapter, main_ci_file)`` for ``base_path``.
+
+    If ``forced_name`` is given, only that adapter is consulted.
+    Otherwise the registry is queried in registration order and the
+    first hit wins. As a last-resort fallback we still recognise
+    misplaced ``*.gitlab-ci.yml`` files so existing behaviour is
+    preserved.
+    """
+    if forced_name:
+        for adapter in REGISTRY:
+            if adapter.name == forced_name:
+                main = adapter.detect(base_path)
+                if main is not None:
+                    print(f"{Colors.DIM}Forced CI system: {adapter.name} "
+                          f"({main.name}){Colors.RESET}", file=sys.stderr)
+                    return adapter, main
+        return None, None
+
+    adapter, main_file = detect_adapter(base_path)
+    if adapter is not None:
+        print(f"{Colors.DIM}Detected {adapter.name}: {main_file.name}"
+              f"{Colors.RESET}", file=sys.stderr)
+        return adapter, main_file
+
+    # Legacy fallback: any stray *.gitlab-ci.yml
+    ci_files = find_ci_files(base_path)
+    if ci_files:
+        print(f"WARNING: No CI definition found at root. "
+              f"Found {len(ci_files)} GitLab CI files; using {ci_files[0].name}.",
+              file=sys.stderr)
+        # Build a synthetic adapter for legacy callers.
+        from .parsers.registry import ParserAdapter
+        legacy = ParserAdapter(
+            name="GitLab CI",
+            parser_class=GitLabCIParser,
+            detect=lambda _: ci_files[0],
+            parser_kwargs=lambda args: {
+                'follow_includes': not getattr(args, 'no_includes', False),
+            },
+        )
+        return legacy, ci_files[0]
+
+    return None, None
+
+
+def main(argv=None):
+    args = build_arg_parser().parse_args(argv)
+
+    if args.no_color or args.output or not sys.stdout.isatty():
+        Colors.disable()
+
+    base_path = Path(args.path).resolve()
+    if not base_path.exists():
+        print(f"ERROR: Path '{args.path}' does not exist.", file=sys.stderr)
+        return 1
+
+    adapter, main_ci_file = _select_ci_file(base_path, forced_name=args.ci)
+    if not main_ci_file or adapter is None:
+        supported = ', '.join(a.name for a in REGISTRY)
+        print(f"ERROR: No supported CI files found ({supported}).", file=sys.stderr)
+        return 1
+
+    print(f"{Colors.DIM}Parsing CI files from: {base_path}{Colors.RESET}", file=sys.stderr)
+
+    parser = adapter.parser_class(base_path=base_path, **adapter.parser_kwargs(args))
+    parser.parse(main_ci_file)
+
+    print(f"{Colors.DIM}Parsed {len(parser.parsed_files)} files, "
+          f"found {len(parser.jobs)} jobs.{Colors.RESET}\n", file=sys.stderr)
+
+    if args.list_stages:
+        graph = DependencyGraph(parser)
+        for stage in graph.get_ordered_stages():
+            count = len(graph.stage_jobs.get(stage, []))
+            print(f"{stage} ({count} jobs)")
+        return 0
+
+    if args.list_jobs:
+        for job_name in sorted(parser.jobs.keys()):
+            stage = parser.get_job_stage(job_name)
+            print(f"{job_name:<60} [{stage}]")
+        return 0
+
+    graph = DependencyGraph(parser)
+    formatter = FORMATTERS[args.format](parser, graph)
+    output = formatter.render(filter_stage=args.stage, filter_job=args.job)
+
+    if args.output:
+        with open(args.output, 'w') as f:
+            f.write(output)
+        print(f"Output written to: {args.output}", file=sys.stderr)
+    else:
+        print(output)
+    return 0
+
+
+if __name__ == '__main__':  # pragma: no cover
+    sys.exit(main())

eirmos/colors.py

@@ -0,0 +1,32 @@
+"""ANSI color codes used by the text formatters.
+
+This module is purposely tiny — it is the only place that knows
+about terminal escape sequences.  Other layers should depend on
+``Colors`` rather than hard-coding escape codes so they can be
+disabled centrally (e.g. when writing to a file or a non-TTY).
+"""
+
+
+class Colors:
+    HEADER = '\033[95m'
+    BLUE = '\033[94m'
+    CYAN = '\033[96m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    RED = '\033[91m'
+    BOLD = '\033[1m'
+    DIM = '\033[2m'
+    RESET = '\033[0m'
+
+    @classmethod
+    def disable(cls):
+        """Replace all color codes with empty strings (irreversible)."""
+        cls.HEADER = ''
+        cls.BLUE = ''
+        cls.CYAN = ''
+        cls.GREEN = ''
+        cls.YELLOW = ''
+        cls.RED = ''
+        cls.BOLD = ''
+        cls.DIM = ''
+        cls.RESET = ''

eirmos/formatters/__init__.py

@@ -0,0 +1,22 @@
+"""Output formatters for ``DependencyGraph`` instances.
+
+All formatters share the same constructor signature
+``Formatter(parser, graph)`` and a ``render(filter_stage=None,
+filter_job=None) -> str`` method, making them interchangeable.
+"""
+
+from .base import BaseFormatter
+from .tree import TreeFormatter
+from .mermaid import MermaidFormatter
+from .dot import DotFormatter
+from .summary import SummaryFormatter
+from .variables import VariableFormatter
+
+__all__ = [
+    "BaseFormatter",
+    "TreeFormatter",
+    "MermaidFormatter",
+    "DotFormatter",
+    "SummaryFormatter",
+    "VariableFormatter",
+]

eirmos/formatters/base.py

@@ -0,0 +1,19 @@
+"""Common base class for formatters."""
+
+import re
+
+
+class BaseFormatter:
+    """Tiny shared base — keeps formatter API uniform."""
+
+    def __init__(self, parser, graph):
+        self.parser = parser
+        self.graph = graph
+
+    def render(self, filter_stage=None, filter_job=None):  # pragma: no cover
+        raise NotImplementedError
+
+    @staticmethod
+    def sanitize_id(name):
+        """Sanitize a name for use as a Mermaid/DOT identifier."""
+        return re.sub(r'[^a-zA-Z0-9_]', '_', name)

eirmos/formatters/dot.py

@@ -0,0 +1,59 @@
+"""Graphviz DOT formatter."""
+
+from .base import BaseFormatter
+
+
+class DotFormatter(BaseFormatter):
+    """Outputs a Graphviz DOT diagram."""
+
+    def render(self, filter_stage=None, filter_job=None):
+        lines = [
+            "digraph pipeline {",
+            "    rankdir=TB;",
+            "    node [shape=box, style=rounded, fontname=\"Helvetica\"];",
+            "    edge [fontname=\"Helvetica\", fontsize=10];",
+            "",
+        ]
+
+        stages = self.graph.get_ordered_stages()
+
+        for stage in stages:
+            if filter_stage and stage != filter_stage:
+                continue
+
+            jobs = self.graph.stage_jobs.get(stage, [])
+            if not jobs:
+                continue
+
+            lines.append(f"    subgraph cluster_{self.sanitize_id(stage)} {{")
+            lines.append(f"        label=\"{stage}\";")
+            lines.append(f"        style=dashed;")
+            lines.append(f"        color=\"#003087\";")
+
+            for job_name in sorted(jobs):
+                sid = self.sanitize_id(job_name)
+                trigger = self.parser.get_job_triggers(job_name)
+                color = '#00AEEF' if trigger else '#003087'
+                shape = 'doubleoctagon' if trigger else 'box'
+                lines.append(
+                    f"        {sid} [label=\"{job_name}\", "
+                    f"color=\"{color}\", shape={shape}];"
+                )
+            lines.append("    }")
+            lines.append("")
+
+        for src, dst, etype in self.graph.edges:
+            src_id = self.sanitize_id(src)
+            dst_id = self.sanitize_id(dst)
+            if etype == 'needs':
+                lines.append(f"    {src_id} -> {dst_id};")
+            elif etype == 'needs-optional':
+                lines.append(f"    {src_id} -> {dst_id} [style=dashed, label=\"optional\"];")
+            elif etype == 'trigger':
+                lines.append(
+                    f"    {src_id} -> {dst_id} [style=bold, color=\"#FF6600\", "
+                    f"label=\"trigger\"];"
+                )
+
+        lines.append("}")
+        return '\n'.join(lines)

eirmos/formatters/mermaid.py

@@ -0,0 +1,55 @@
+"""Mermaid flowchart formatter."""
+
+from .base import BaseFormatter
+
+
+class MermaidFormatter(BaseFormatter):
+    """Outputs a Mermaid diagram."""
+
+    def render(self, filter_stage=None, filter_job=None):
+        lines = ["```mermaid", "flowchart TD", ""]
+
+        stages = self.graph.get_ordered_stages()
+        rendered_jobs = set()
+
+        for stage in stages:
+            if filter_stage and stage != filter_stage:
+                continue
+
+            jobs = self.graph.stage_jobs.get(stage, [])
+            if not jobs:
+                continue
+
+            lines.append(f"    subgraph {self.sanitize_id(stage)}[\"{stage}\"]")
+            for job_name in sorted(jobs):
+                if filter_job and filter_job != job_name:
+                    preds = [src for src, dst, _ in self.graph.edges if dst == job_name]
+                    succs = [dst for _, dst, _ in self.graph.edges if dst == job_name]
+                    if filter_job not in preds and filter_job not in succs:
+                        continue
+
+                sid = self.sanitize_id(job_name)
+                trigger = self.parser.get_job_triggers(job_name)
+                if trigger:
+                    lines.append(f"        {sid}[[\"{job_name}\"]]\n")
+                else:
+                    lines.append(f"        {sid}[\"{job_name}\"]\n")
+                rendered_jobs.add(job_name)
+            lines.append("    end")
+            lines.append("")
+
+        lines.append("    %% Dependencies")
+        for src, dst, etype in self.graph.edges:
+            if src not in rendered_jobs and dst not in rendered_jobs:
+                continue
+            src_id = self.sanitize_id(src)
+            dst_id = self.sanitize_id(dst)
+            if etype == 'needs':
+                lines.append(f"    {src_id} --> {dst_id}")
+            elif etype == 'needs-optional':
+                lines.append(f"    {src_id} -.-> {dst_id}")
+            elif etype == 'trigger':
+                lines.append(f"    {src_id} ==> {dst_id}")
+
+        lines.append("```")
+        return '\n'.join(lines)

eirmos/formatters/summary.py

@@ -0,0 +1,79 @@
+"""Compact summary formatter."""
+
+import re
+from collections import defaultdict
+
+from ..colors import Colors
+from .base import BaseFormatter
+
+
+class SummaryFormatter(BaseFormatter):
+    """Outputs a compact summary view."""
+
+    def render(self, filter_stage=None, filter_job=None):
+        lines = []
+        lines.append(f"\n{Colors.BOLD}Pipeline Summary{Colors.RESET}")
+        lines.append(f"{'─' * 60}")
+
+        templates = getattr(self.parser, 'templates', {}) or {}
+
+        lines.append(f"\n{Colors.BOLD}Statistics:{Colors.RESET}")
+        lines.append(f"  Total jobs:      {len(self.parser.jobs)}")
+        lines.append(f"  Total templates: {len(templates)}")
+        lines.append(f"  Total stages:    {len(self.graph.get_ordered_stages())}")
+        lines.append(f"  Total edges:     {len(self.graph.edges)}")
+        lines.append(f"  Files parsed:    {len(self.parser.parsed_files)}")
+
+        lines.append(f"\n{Colors.BOLD}Stages:{Colors.RESET}")
+        for stage in self.graph.get_ordered_stages():
+            jobs = self.graph.stage_jobs.get(stage, [])
+            bar = '█' * min(len(jobs), 40)
+            lines.append(f"  {stage:<20} {Colors.BLUE}{bar}{Colors.RESET} ({len(jobs)})")
+
+        lines.append(f"\n{Colors.BOLD}Most Connected Jobs (by needs):{Colors.RESET}")
+        job_deps = {}
+        for job_name in self.parser.jobs:
+            needs = self.parser.get_job_needs(job_name)
+            succs = self.graph.get_successors(job_name)
+            job_deps[job_name] = len(needs) + len(succs)
+
+        top_jobs = sorted(job_deps.items(), key=lambda x: x[1], reverse=True)[:15]
+        for job_name, count in top_jobs:
+            if count > 0:
+                lines.append(f"  {job_name:<55} {Colors.GREEN}{count}{Colors.RESET}")
+
+        trigger_jobs = [j for j in self.parser.jobs if self.parser.get_job_triggers(j)]
+        if trigger_jobs:
+            lines.append(f"\n{Colors.BOLD}Child Pipeline Triggers:{Colors.RESET}")
+            for job_name in sorted(trigger_jobs):
+                trigger = self.parser.get_job_triggers(job_name)
+                inc = trigger.get('include', 'unknown')
+                lines.append(f"  {Colors.YELLOW}{job_name}{Colors.RESET}")
+                lines.append(f"    ⟶ {inc}")
+
+        roots = self.graph.get_roots()
+        if roots:
+            lines.append(f"\n{Colors.BOLD}Root Jobs (no 'needs' dependencies):{Colors.RESET}")
+            for job_name in sorted(roots)[:20]:
+                stage = self.parser.get_job_stage(job_name)
+                lines.append(f"  {job_name:<50} {Colors.DIM}[{stage}]{Colors.RESET}")
+            if len(roots) > 20:
+                lines.append(f"  ... and {len(roots) - 20} more")
+
+        # CUSTOM_BUILD options mapping (GitLab CI specific)
+        lines.append(f"\n{Colors.BOLD}CUSTOM_BUILD → Job Mapping:{Colors.RESET}")
+        custom_build_map = defaultdict(list)
+        for job_name, job in self.parser.jobs.items():
+            for rule in job.get('rules', []) or []:
+                if isinstance(rule, dict) and 'if' in rule:
+                    matches = re.findall(r'CUSTOM_BUILD\s*==\s*"([^"]+)"', str(rule['if']))
+                    for m in matches:
+                        custom_build_map[m].append(job_name)
+
+        for cb_name in sorted(custom_build_map.keys()):
+            jobs = custom_build_map[cb_name]
+            lines.append(f"\n  {Colors.CYAN}{cb_name}{Colors.RESET}:")
+            for j in sorted(set(jobs)):
+                lines.append(f"    → {j}")
+
+        return '\n'.join(lines)