feat(gitlab-sim): 🚀 ajout graph

internal/fetcher/gitlab.go

@@ -0,0 +1,152 @@
+// Package fetcher retrieves remote GitLab CI YAML files via the GitLab REST API.
+package fetcher
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+)
+
+// TokenSource describes where a token was found, which determines the correct
+// authentication header to use with the GitLab API.
+type TokenSource int
+
+const (
+	TokenNone     TokenSource = iota
+	TokenPrivate              // GITLAB_TOKEN or GITLAB_PRIVATE_TOKEN → PRIVATE-TOKEN header
+	TokenJobToken             // CI_JOB_TOKEN → JOB-TOKEN header
+)
+
+// GitLabConfig holds everything needed to reach a GitLab instance.
+type GitLabConfig struct {
+	BaseURL string
+	Token   string
+	Source  TokenSource
+}
+
+// AutoConfig builds a GitLabConfig from environment variables.
+//
+// Base URL resolution order: CI_SERVER_URL → GITLAB_URL → https://gitlab.com
+// Token resolution order:    GITLAB_TOKEN → CI_JOB_TOKEN → GITLAB_PRIVATE_TOKEN
+func AutoConfig() GitLabConfig {
+	baseURL := firstNonEmpty(
+		os.Getenv("CI_SERVER_URL"),
+		os.Getenv("GITLAB_URL"),
+		"https://gitlab.com",
+	)
+
+	cfg := GitLabConfig{BaseURL: strings.TrimRight(baseURL, "/")}
+
+	if t := os.Getenv("GITLAB_TOKEN"); t != "" {
+		cfg.Token = t
+		cfg.Source = TokenPrivate
+	} else if t := os.Getenv("CI_JOB_TOKEN"); t != "" {
+		cfg.Token = t
+		cfg.Source = TokenJobToken
+	} else if t := os.Getenv("GITLAB_PRIVATE_TOKEN"); t != "" {
+		cfg.Token = t
+		cfg.Source = TokenPrivate
+	}
+
+	return cfg
+}
+
+// WithOverrides returns a copy of cfg with non-empty overrides applied.
+func (cfg GitLabConfig) WithOverrides(baseURL, token string) GitLabConfig {
+	if baseURL != "" {
+		cfg.BaseURL = strings.TrimRight(baseURL, "/")
+	}
+	if token != "" {
+		cfg.Token = token
+		cfg.Source = TokenPrivate
+	}
+	return cfg
+}
+
+// ForHost returns a copy of cfg with BaseURL set to https://<host>.
+// Used when a CI/CD component reference specifies a different GitLab host.
+func (cfg GitLabConfig) ForHost(host string) GitLabConfig {
+	cfg.BaseURL = "https://" + host
+	return cfg
+}
+
+// HasToken reports whether the config carries a usable token.
+func (cfg GitLabConfig) HasToken() bool { return cfg.Token != "" }
+
+// FetchFile downloads a single file from a GitLab project repository.
+// If no token is configured the request is sent unauthenticated (works for
+// public projects and GitLab CI/CD catalog components).
+//
+//   - project  — namespace/project path, e.g. "my-group/my-project"
+//   - filePath — repository file path, e.g. "/templates/ci.yml"
+//   - ref      — branch, tag, or commit SHA; empty string defaults to HEAD
+func (cfg GitLabConfig) FetchFile(project, filePath, ref string) ([]byte, error) {
+	encodedProject := url.PathEscape(project)
+	encodedFile := url.PathEscape(strings.TrimPrefix(filePath, "/"))
+
+	apiURL := fmt.Sprintf("%s/api/v4/projects/%s/repository/files/%s/raw",
+		cfg.BaseURL, encodedProject, encodedFile)
+
+	if ref == "" {
+		ref = "HEAD"
+	}
+
+	req, err := http.NewRequest(http.MethodGet, apiURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("building request: %w", err)
+	}
+
+	q := req.URL.Query()
+	q.Set("ref", ref)
+	req.URL.RawQuery = q.Encode()
+
+	// Add auth header only when a token is available.
+	if cfg.Token != "" {
+		switch cfg.Source {
+		case TokenJobToken:
+			req.Header.Set("JOB-TOKEN", cfg.Token)
+		default:
+			req.Header.Set("PRIVATE-TOKEN", cfg.Token)
+		}
+	}
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("GET %s: %w", apiURL, err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading response body: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		msg := strings.TrimSpace(string(body))
+		switch resp.StatusCode {
+		case http.StatusUnauthorized:
+			if cfg.Token == "" {
+				return nil, fmt.Errorf("authentication required (401) — set GITLAB_TOKEN or CI_JOB_TOKEN")
+			}
+			return nil, fmt.Errorf("authentication failed (401) — check your token")
+		case http.StatusNotFound:
+			return nil, fmt.Errorf("not found (404): %s@%s in project %s — check the project path, file path, and token permissions", filePath, ref, project)
+		default:
+			return nil, fmt.Errorf("unexpected status %d: %s", resp.StatusCode, msg)
+		}
+	}
+
+	return body, nil
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, v := range values {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}

internal/graph/includes.go

@@ -0,0 +1,127 @@
+package graph
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Includes returns a Mermaid flowchart showing include file dependencies.
+// sourcePath is the path to the main pipeline file; rawIncludes is Pipeline.Include.
+func Includes(sourcePath string, rawIncludes []any) string {
+	var sb strings.Builder
+	w := func(s string) { sb.WriteString(s + "\n") }
+	wf := func(f string, a ...any) { fmt.Fprintf(&sb, f+"\n", a...) }
+
+	w("---")
+	w("title: Include Dependencies")
+	w("---")
+	w("flowchart LR")
+	w("    classDef main fill:#e24329,stroke:#c73a1e,color:#fff,font-weight:bold")
+	w("    classDef project fill:#6b4fbb,stroke:#5a3fa0,color:#fff")
+	w("    classDef component fill:#1aaa55,stroke:#148a43,color:#fff")
+	w("    classDef local fill:#428fdc,stroke:#1068bf,color:#fff")
+	w("    classDef remote fill:#868686,stroke:#686868,color:#fff")
+	w("    classDef template fill:#fc6d26,stroke:#e56b1f,color:#fff")
+	w("")
+	wf("    root[\"%s\"]:::main", mermaidLabel(sourcePath))
+
+	if len(rawIncludes) == 0 {
+		return sb.String()
+	}
+
+	w("")
+
+	counter := 0
+	for _, entry := range rawIncludes {
+		for _, n := range parseIncludeEntry(entry, &counter) {
+			wf("    %s[\"%s\"]:::%s", n.id, n.label, n.class)
+			wf("    root --> %s", n.id)
+		}
+	}
+
+	return sb.String()
+}
+
+type incNode struct {
+	id, label, class string
+}
+
+func parseIncludeEntry(entry any, counter *int) []incNode {
+	newID := func() string {
+		*counter++
+		return fmt.Sprintf("inc%d", *counter)
+	}
+	switch v := entry.(type) {
+	case string:
+		return []incNode{{id: newID(), label: mermaidLabel(v), class: "local"}}
+	case map[string]any:
+		return parseIncludeMap(v, newID)
+	}
+	return nil
+}
+
+func parseIncludeMap(m map[string]any, newID func() string) []incNode {
+	if comp, ok := m["component"].(string); ok {
+		return []incNode{{
+			id:    newID(),
+			label: "component:<br>" + mermaidLabel(comp),
+			class: "component",
+		}}
+	}
+	if proj, ok := m["project"].(string); ok {
+		ref, _ := m["ref"].(string)
+		if ref == "" {
+			ref = "HEAD"
+		}
+		files := includeFileList(m["file"])
+		if len(files) == 0 {
+			return []incNode{{
+				id:    newID(),
+				label: fmt.Sprintf("project: %s @ %s", mermaidLabel(proj), ref),
+				class: "project",
+			}}
+		}
+		var nodes []incNode
+		for _, f := range files {
+			nodes = append(nodes, incNode{
+				id:    newID(),
+				label: fmt.Sprintf("project: %s<br>%s @ %s", mermaidLabel(proj), mermaidLabel(f), ref),
+				class: "project",
+			})
+		}
+		return nodes
+	}
+	if local, ok := m["local"].(string); ok {
+		return []incNode{{id: newID(), label: "local: " + mermaidLabel(local), class: "local"}}
+	}
+	if remote, ok := m["remote"].(string); ok {
+		return []incNode{{id: newID(), label: "remote:<br>" + mermaidLabel(remote), class: "remote"}}
+	}
+	if tmpl, ok := m["template"].(string); ok {
+		return []incNode{{id: newID(), label: "template:<br>" + mermaidLabel(tmpl), class: "template"}}
+	}
+	return nil
+}
+
+func includeFileList(v any) []string {
+	switch f := v.(type) {
+	case string:
+		return []string{f}
+	case []any:
+		var out []string
+		for _, item := range f {
+			if s, ok := item.(string); ok {
+				out = append(out, s)
+			}
+		}
+		return out
+	}
+	return nil
+}
+
+// mermaidLabel escapes s for use inside a Mermaid double-quoted node label.
+func mermaidLabel(s string) string {
+	s = strings.ReplaceAll(s, `"`, `'`)
+	s = strings.ReplaceAll(s, `#`, `&#35;`)
+	return s
+}

internal/graph/pipeline.go

@@ -0,0 +1,172 @@
+package graph
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"git.k3nny.fr/gitlab-sim/internal/model"
+)
+
+// Pipeline returns a Mermaid flowchart of pipeline jobs grouped by stage.
+//
+// Hidden template jobs (names starting with ".") are excluded.
+// When any job has a needs: list, DAG mode is used and individual needs arrows
+// are drawn. Otherwise, classic mode draws stage-ordering arrows between
+// stage subgraphs.
+func Pipeline(p *model.Pipeline) string {
+	var sb strings.Builder
+	w := func(s string) { sb.WriteString(s + "\n") }
+	wf := func(f string, a ...any) { fmt.Fprintf(&sb, f+"\n", a...) }
+
+	w("---")
+	w("title: Pipeline")
+	w("---")
+	w("flowchart LR")
+	w("    classDef regular fill:#428fdc,stroke:#1068bf,color:#fff")
+	w("    classDef manual fill:#fc6d26,stroke:#e56b1f,color:#fff")
+	w("    classDef trigger fill:#6b4fbb,stroke:#5a3fa0,color:#fff")
+	w("    classDef delayed fill:#fca326,stroke:#d98a1e,color:#333")
+	w("")
+
+	// Collect visible (non-template) job names; sort for stable output.
+	var visible []string
+	for name := range p.Jobs {
+		if !strings.HasPrefix(name, ".") {
+			visible = append(visible, name)
+		}
+	}
+	sort.Strings(visible)
+
+	if len(visible) == 0 {
+		w("    empty[\"no jobs defined\"]")
+		return sb.String()
+	}
+
+	// Assign stable numeric IDs so graph output is deterministic.
+	jobID := make(map[string]string, len(visible))
+	for i, name := range visible {
+		jobID[name] = fmt.Sprintf("j%d", i+1)
+	}
+
+	// Group jobs by stage; fall back to "test" (GitLab default) when unset.
+	byStage := make(map[string][]string)
+	for _, name := range visible {
+		stage := p.Jobs[name].Stage
+		if stage == "" {
+			stage = "test"
+		}
+		byStage[stage] = append(byStage[stage], name)
+	}
+
+	// Build ordered stage list: declared stages first, then undeclared extras.
+	seen := make(map[string]bool)
+	var stages []string
+	for _, s := range p.Stages {
+		if len(byStage[s]) > 0 && !seen[s] {
+			stages = append(stages, s)
+			seen[s] = true
+		}
+	}
+	for _, name := range visible {
+		stage := p.Jobs[name].Stage
+		if stage == "" {
+			stage = "test"
+		}
+		if !seen[stage] {
+			stages = append(stages, stage)
+			seen[stage] = true
+		}
+	}
+
+	// Emit one subgraph per stage.
+	for _, stage := range stages {
+		jobs := byStage[stage]
+		if len(jobs) == 0 {
+			continue
+		}
+		sort.Strings(jobs)
+		wf("    subgraph %s[\"%s\"]", stageID(stage), stage)
+		for _, name := range jobs {
+			wf("        %s[\"%s\"]:::%s", jobID[name], mermaidLabel(name), jobClass(p.Jobs[name]))
+		}
+		w("    end")
+		w("")
+	}
+
+	// DAG mode: at least one visible job has a needs: list.
+	dagMode := false
+	for _, name := range visible {
+		if len(p.Jobs[name].Needs) > 0 {
+			dagMode = true
+			break
+		}
+	}
+
+	if dagMode {
+		w("    %% DAG: needs dependencies")
+		for _, name := range visible {
+			for _, need := range p.Jobs[name].Needs {
+				dep := needsJobName(need)
+				if dep == "" {
+					continue
+				}
+				if depID, ok := jobID[dep]; ok {
+					wf("    %s --> %s", depID, jobID[name])
+				}
+			}
+		}
+	} else if len(stages) > 1 {
+		w("    %% Classic: stage ordering")
+		ids := make([]string, len(stages))
+		for i, s := range stages {
+			ids[i] = stageID(s)
+		}
+		wf("    %s", strings.Join(ids, " --> "))
+	}
+
+	return sb.String()
+}
+
+func stageID(s string) string { return "stage_" + sanitizeID(s) }
+
+func sanitizeID(s string) string {
+	var b strings.Builder
+	for _, r := range s {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '_':
+			b.WriteRune(r)
+		default:
+			b.WriteByte('_')
+		}
+	}
+	return b.String()
+}
+
+func jobClass(job model.Job) string {
+	if job.Trigger != nil {
+		return "trigger"
+	}
+	switch job.When {
+	case "manual":
+		return "manual"
+	case "delayed":
+		return "delayed"
+	}
+	return "regular"
+}
+
+func needsJobName(need any) string {
+	switch v := need.(type) {
+	case string:
+		return v
+	case map[string]any:
+		if _, cross := v["pipeline"]; cross {
+			return "" // cross-pipeline needs have no local counterpart
+		}
+		if j, ok := v["job"].(string); ok {
+			return j
+		}
+	}
+	return ""
+}

internal/graph/render.go

@@ -0,0 +1,363 @@
+package graph
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"sort"
+	"strings"
+	"time"
+
+	"git.k3nny.fr/gitlab-sim/internal/model"
+)
+
+// Layout constants (pixels) – tuned to resemble GitLab's full pipeline graph view.
+const (
+	chipW     = 178 // job chip width
+	chipH     = 34  // job chip height
+	chipGap   = 6   // vertical gap between chips in a column
+	iconCX    = 14  // status circle: x offset from chip left edge to circle centre
+	iconR     = 7   // status circle radius (14 px diameter)
+	textLeft  = 27  // job name text: x offset from chip left edge
+	labelH    = 30  // stage-name label area height (text + bottom gap)
+	topPad    = 40  // outer top padding
+	sidePad   = 40  // outer left / right padding
+	stageGap  = 50  // horizontal gap between stage columns (connector space)
+	botPad    = 48  // outer bottom padding (legend lives here)
+)
+
+type svgPt struct{ x, y int }
+
+// RenderPipeline writes a PNG (or SVG fallback) file with a GitLab CI-style
+// pipeline layout and returns the path to the generated file.
+func RenderPipeline(p *model.Pipeline, outDir string) (string, error) {
+	if err := os.MkdirAll(outDir, 0o755); err != nil {
+		return "", fmt.Errorf("creating output directory %s: %w", outDir, err)
+	}
+
+	svg, err := pipelineSVG(p)
+	if err != nil {
+		return "", err
+	}
+
+	ts := time.Now().Format("20060102-150405")
+	svgPath := filepath.Join(outDir, "pipeline-"+ts+".svg")
+	if err := os.WriteFile(svgPath, []byte(svg), 0o644); err != nil {
+		return "", fmt.Errorf("writing SVG: %w", err)
+	}
+
+	pngPath := filepath.Join(outDir, "pipeline-"+ts+".png")
+	if convertToPNG(svgPath, pngPath) {
+		_ = os.Remove(svgPath)
+		return pngPath, nil
+	}
+	return svgPath, nil
+}
+
+// convertToPNG tries rsvg-convert, Inkscape, magick, and convert (not on Windows).
+func convertToPNG(svgPath, pngPath string) bool {
+	type cand struct {
+		args    []string
+		skipWin bool
+	}
+	for _, c := range []cand{
+		{[]string{"rsvg-convert", "--output", pngPath, svgPath}, false},
+		{[]string{"inkscape", "--export-filename=" + pngPath, svgPath}, false},
+		{[]string{"magick", svgPath, pngPath}, false},
+		{[]string{"convert", svgPath, pngPath}, true},
+	} {
+		if c.skipWin && runtime.GOOS == "windows" {
+			continue
+		}
+		if bin, err := exec.LookPath(c.args[0]); err == nil {
+			if exec.Command(bin, c.args[1:]...).Run() == nil {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func pipelineSVG(p *model.Pipeline) (string, error) {
+	// Collect visible (non-template) job names in sorted order.
+	var visible []string
+	for name := range p.Jobs {
+		if !strings.HasPrefix(name, ".") {
+			visible = append(visible, name)
+		}
+	}
+	sort.Strings(visible)
+
+	if len(visible) == 0 {
+		return svgEmpty(), nil
+	}
+
+	// Group by stage; fall back to "test" (GitLab default) when stage is unset.
+	byStage := make(map[string][]string)
+	for _, name := range visible {
+		s := p.Jobs[name].Stage
+		if s == "" {
+			s = "test"
+		}
+		byStage[s] = append(byStage[s], name)
+	}
+
+	// Build ordered stage list: declared stages first, then undeclared extras.
+	seen := make(map[string]bool)
+	var stages []string
+	for _, s := range p.Stages {
+		if len(byStage[s]) > 0 && !seen[s] {
+			stages = append(stages, s)
+			seen[s] = true
+		}
+	}
+	for _, name := range visible {
+		s := p.Jobs[name].Stage
+		if s == "" {
+			s = "test"
+		}
+		if !seen[s] {
+			stages = append(stages, s)
+			seen[s] = true
+		}
+	}
+
+	// Compute per-stage column heights and job anchor points for connectors.
+	colH := make([]int, len(stages))   // height of the chip stack (no label)
+	colCtY := make([]int, len(stages)) // y centre of the chip stack
+	maxColH := 0
+	rightMid := make(map[string]svgPt)
+	leftMid := make(map[string]svgPt)
+
+	for i, stage := range stages {
+		jobs := byStage[stage]
+		sort.Strings(jobs)
+		n := len(jobs)
+		h := n*chipH + max(0, n-1)*chipGap
+		colH[i] = h
+		if h > maxColH {
+			maxColH = h
+		}
+		cx := sidePad + i*(chipW+stageGap)
+		for j, name := range jobs {
+			chy := topPad + labelH + j*(chipH+chipGap)
+			rightMid[name] = svgPt{cx + chipW, chy + chipH/2}
+			leftMid[name] = svgPt{cx, chy + chipH/2}
+		}
+		colCtY[i] = topPad + labelH + h/2
+	}
+
+	svgW := sidePad*2 + len(stages)*chipW + max(0, len(stages)-1)*stageGap
+	svgH := topPad + labelH + maxColH + botPad
+
+	// DAG mode: any visible job with a needs: list triggers job-to-job arrows.
+	dagMode := false
+	for _, name := range visible {
+		if len(p.Jobs[name].Needs) > 0 {
+			dagMode = true
+			break
+		}
+	}
+
+	var sb strings.Builder
+	w := func(s string) { sb.WriteString(s + "\n") }
+	wf := func(f string, a ...any) { fmt.Fprintf(&sb, f+"\n", a...) }
+
+	// ── Document ──────────────────────────────────────────────────────────────
+	wf(`<svg xmlns="http://www.w3.org/2000/svg" width="%d" height="%d" viewBox="0 0 %d %d">`,
+		svgW, svgH, svgW, svgH)
+
+	w(`  <defs>`)
+	// Subtle drop shadow for job chips.
+	w(`    <filter id="chip-shadow" x="-4%" y="-10%" width="108%" height="130%">`)
+	w(`      <feDropShadow dx="0" dy="1" stdDeviation="1.5" flood-color="#000000" flood-opacity="0.07"/>`)
+	w(`    </filter>`)
+	w(`  </defs>`)
+
+	// White page background.
+	wf(`  <rect width="%d" height="%d" fill="#ffffff"/>`, svgW, svgH)
+
+	// ── Stage columns ─────────────────────────────────────────────────────────
+	for i, stage := range stages {
+		cx := sidePad + i*(chipW+stageGap)
+		jobs := byStage[stage]
+		sort.Strings(jobs)
+
+		// Stage name – small, gray, uppercase, centered above the chip stack.
+		wf(`  <text x="%d" y="%d" text-anchor="middle" `+
+			`font-family="'GitLab Sans','Segoe UI',-apple-system,BlinkMacSystemFont,sans-serif" `+
+			`font-size="11" font-weight="600" letter-spacing="0.8" fill="#868686">%s</text>`,
+			cx+chipW/2, topPad+13, svgEsc(strings.ToUpper(stage)))
+
+		// Subtle separator line below stage name.
+		wf(`  <line x1="%d" y1="%d" x2="%d" y2="%d" stroke="#eaeaea" stroke-width="1"/>`,
+			cx, topPad+21, cx+chipW, topPad+21)
+
+		// Job chips.
+		for j, name := range jobs {
+			job := p.Jobs[name]
+			chy := topPad + labelH + j*(chipH+chipGap)
+			color := chipColor(job)
+
+			// Chip card (white, rounded, subtle border + shadow).
+			wf(`  <rect x="%d" y="%d" width="%d" height="%d" rx="4" `+
+				`fill="#ffffff" stroke="#dde1e7" stroke-width="1" filter="url(#chip-shadow)"/>`,
+				cx, chy, chipW, chipH)
+
+			// Colored status indicator circle.
+			wf(`  <circle cx="%d" cy="%d" r="%d" fill="%s"/>`,
+				cx+iconCX, chy+chipH/2, iconR, color)
+
+			// Icon symbol inside the circle.
+			drawChipIcon(&sb, job, cx+iconCX, chy+chipH/2)
+
+			// Job name text.
+			wf(`  <text x="%d" y="%d" dominant-baseline="middle" `+
+				`font-family="'GitLab Sans','Segoe UI',-apple-system,BlinkMacSystemFont,sans-serif" `+
+				`font-size="13" fill="#303030">%s</text>`,
+				cx+textLeft, chy+chipH/2, svgEsc(svgTrunc(name, 20)))
+		}
+	}
+
+	// ── Connectors ────────────────────────────────────────────────────────────
+	const connStroke = "#dbdbdb"
+
+	if dagMode {
+		// Job-to-job bezier curves from needs:.
+		for _, name := range visible {
+			for _, need := range p.Jobs[name].Needs {
+				dep := needsJobName(need)
+				if dep == "" {
+					continue
+				}
+				src, okS := rightMid[dep]
+				dst, okD := leftMid[name]
+				if !okS || !okD {
+					continue
+				}
+				cpX := (src.x + dst.x) / 2
+				wf(`  <path d="M%d,%d C%d,%d %d,%d %d,%d" stroke="%s" stroke-width="2" fill="none"/>`,
+					src.x, src.y, cpX, src.y, cpX, dst.y, dst.x-7, dst.y, connStroke)
+				// Small right-pointing triangle arrowhead.
+				wf(`  <polygon points="%d,%d %d,%d %d,%d" fill="%s"/>`,
+					dst.x-7, dst.y-4, dst.x, dst.y, dst.x-7, dst.y+4, connStroke)
+			}
+		}
+	} else {
+		// Classic: one connector per adjacent stage pair.
+		for i := 0; i < len(stages)-1; i++ {
+			x1 := sidePad + i*(chipW+stageGap) + chipW
+			x2 := sidePad + (i+1)*(chipW+stageGap)
+			y1 := colCtY[i]
+			y2 := colCtY[i+1]
+			midX := (x1 + x2) / 2
+
+			if y1 == y2 {
+				// Straight horizontal line.
+				wf(`  <line x1="%d" y1="%d" x2="%d" y2="%d" stroke="%s" stroke-width="2"/>`,
+					x1, y1, x2-7, y2, connStroke)
+			} else {
+				// L-shaped elbow: right → vertical → right.
+				wf(`  <polyline points="%d,%d %d,%d %d,%d %d,%d" `+
+					`stroke="%s" stroke-width="2" fill="none" stroke-linejoin="round"/>`,
+					x1, y1, midX, y1, midX, y2, x2-7, y2, connStroke)
+			}
+			// Arrowhead at the destination.
+			wf(`  <polygon points="%d,%d %d,%d %d,%d" fill="%s"/>`,
+				x2-7, y2-4, x2, y2, x2-7, y2+4, connStroke)
+		}
+	}
+
+	// ── Legend ────────────────────────────────────────────────────────────────
+	legend := []struct{ color, label string }{
+		{"#1f75cb", "regular"},
+		{"#fc6d26", "manual"},
+		{"#6b4fbb", "trigger"},
+		{"#fca326", "delayed"},
+	}
+	const legendItemW = 82
+	legendY := topPad + labelH + maxColH + botPad/2
+	lx0 := (svgW - len(legend)*legendItemW) / 2
+	for k, item := range legend {
+		lx := lx0 + k*legendItemW
+		wf(`  <circle cx="%d" cy="%d" r="6" fill="%s"/>`, lx+6, legendY, item.color)
+		wf(`  <text x="%d" y="%d" dominant-baseline="middle" `+
+			`font-family="'GitLab Sans','Segoe UI',-apple-system,BlinkMacSystemFont,sans-serif" `+
+			`font-size="11" fill="#868686">%s</text>`,
+			lx+16, legendY, item.label)
+	}
+
+	w(`</svg>`)
+	return sb.String(), nil
+}
+
+// drawChipIcon writes an SVG symbol inside the status circle to help identify
+// the job type at a glance.
+func drawChipIcon(sb *strings.Builder, job model.Job, cx, cy int) {
+	if job.Trigger != nil {
+		// Right-pointing chevron for trigger jobs.
+		fmt.Fprintf(sb, "  <polyline points=\"%d,%d %d,%d %d,%d\" "+
+			"stroke=\"#fff\" stroke-width=\"1.5\" fill=\"none\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n",
+			cx-3, cy-3, cx+3, cy, cx-3, cy+3)
+		return
+	}
+	switch job.When {
+	case "manual":
+		// Filled play triangle.
+		fmt.Fprintf(sb, "  <polygon points=\"%d,%d %d,%d %d,%d\" fill=\"#fff\"/>\n",
+			cx-3, cy-4, cx+5, cy, cx-3, cy+4)
+	case "delayed":
+		// Clock hands: vertical + horizontal.
+		fmt.Fprintf(sb, "  <circle cx=\"%d\" cy=\"%d\" r=\"5\" stroke=\"#fff\" stroke-width=\"1.2\" fill=\"none\"/>\n", cx, cy)
+		fmt.Fprintf(sb, "  <line x1=\"%d\" y1=\"%d\" x2=\"%d\" y2=\"%d\" stroke=\"#fff\" stroke-width=\"1.2\" stroke-linecap=\"round\"/>\n",
+			cx, cy, cx, cy-3)
+		fmt.Fprintf(sb, "  <line x1=\"%d\" y1=\"%d\" x2=\"%d\" y2=\"%d\" stroke=\"#fff\" stroke-width=\"1.2\" stroke-linecap=\"round\"/>\n",
+			cx, cy, cx+2, cy+1)
+	default:
+		// Regular job: small white checkmark outline.
+		fmt.Fprintf(sb, "  <polyline points=\"%d,%d %d,%d %d,%d\" "+
+			"stroke=\"#fff\" stroke-width=\"1.5\" fill=\"none\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n",
+			cx-3, cy, cx-1, cy+3, cx+4, cy-3)
+	}
+}
+
+func chipColor(job model.Job) string {
+	if job.Trigger != nil {
+		return "#6b4fbb"
+	}
+	switch job.When {
+	case "manual":
+		return "#fc6d26"
+	case "delayed":
+		return "#fca326"
+	}
+	return "#1f75cb"
+}
+
+func svgEsc(s string) string {
+	s = strings.ReplaceAll(s, "&", "&amp;")
+	s = strings.ReplaceAll(s, "<", "&lt;")
+	s = strings.ReplaceAll(s, ">", "&gt;")
+	return s
+}
+
+func svgTrunc(s string, maxLen int) string {
+	runes := []rune(s)
+	if len(runes) <= maxLen {
+		return s
+	}
+	return string(runes[:maxLen-1]) + "…"
+}
+
+func svgEmpty() string {
+	const w, h = 300, 80
+	return fmt.Sprintf(
+		`<svg xmlns="http://www.w3.org/2000/svg" width="%d" height="%d">`+
+			`<rect width="%d" height="%d" fill="#fff"/>`+
+			`<text x="%d" y="%d" text-anchor="middle" dominant-baseline="middle" `+
+			`font-family="sans-serif" font-size="13" fill="#868686">no jobs defined</text>`+
+			`</svg>`,
+		w, h, w, h, w/2, h/2)
+}

internal/linter/linter.go

@@ -97,8 +97,10 @@ func checkJob(name string, job model.Job, stageSet map[string]bool) []Finding {
 		})
 	}
 
-	// stage must exist in declared stages (if stages were declared)
-	if job.Stage != "" && len(stageSet) > 0 && !stageSet[job.Stage] {
+	// stage must exist in declared stages (if stages were declared).
+	// Skip when the stage value is a component input placeholder ($[[ inputs.xxx ]]):
+	// those are resolved server-side and cannot be validated locally.
+	if job.Stage != "" && !strings.Contains(job.Stage, "$[[") && len(stageSet) > 0 && !stageSet[job.Stage] {
 		findings = append(findings, Finding{
 			Severity: Error,
 			Job:      name,

internal/model/parser.go

@@ -13,7 +13,11 @@ func Parse(path string) (*Pipeline, error) {
 	if err != nil {
 		return nil, fmt.Errorf("reading file: %w", err)
 	}
+	return ParseBytes(data)
+}
 
+// ParseBytes parses YAML from an in-memory byte slice.
+func ParseBytes(data []byte) (*Pipeline, error) {
 	// First pass: decode into a raw map to extract job keys.
 	var raw map[string]yaml.Node
 	if err := yaml.Unmarshal(data, &raw); err != nil {

internal/resolver/includes.go

@@ -0,0 +1,245 @@
+package resolver
+
+import (
+	"fmt"
+	"strings"
+
+	"git.k3nny.fr/gitlab-sim/internal/fetcher"
+	"git.k3nny.fr/gitlab-sim/internal/model"
+)
+
+// IncludeWarning describes a remote include entry that could not be resolved.
+// These are surfaced to the user as [WARNING] lines before the lint findings.
+type IncludeWarning struct {
+	// Label is a short human-readable identifier shown in the warning message,
+	// e.g. "project my-group/templates:/ci.yml@main" or
+	// "component gitlab.com/components/golang/build@v1.0".
+	Label   string
+	Err     error // nil when Skipped is true
+	Skipped bool  // no token available — skipped without attempting a network call
+}
+
+func (w IncludeWarning) String() string {
+	if w.Skipped {
+		return fmt.Sprintf(
+			"%s: skipped — no GitLab token found (set GITLAB_TOKEN, CI_JOB_TOKEN, or GITLAB_PRIVATE_TOKEN); findings may be incomplete",
+			w.Label)
+	}
+	return fmt.Sprintf(
+		"%s: could not be fetched — %v; findings may be incomplete or contain false positives",
+		w.Label, w.Err)
+}
+
+// ResolveIncludes processes the pipeline's include: block.
+//
+// Project includes (include: project: ...) require authentication and are
+// skipped with a warning when no token is configured.
+//
+// Component includes (include: component: ...) attempt the fetch
+// unauthenticated first, so public CI/CD catalog components work without a
+// token. A warning is emitted when the fetch fails.
+//
+// Non-resolvable include forms (local, remote, template) are silently skipped.
+func ResolveIncludes(p *model.Pipeline, cfg fetcher.GitLabConfig) []IncludeWarning {
+	var warnings []IncludeWarning
+	for _, inc := range p.Include {
+		entry, ok := normaliseInclude(inc)
+		if !ok {
+			continue
+		}
+
+		if project, _ := entry["project"].(string); project != "" {
+			warnings = append(warnings, resolveProjectInclude(p, entry, project, cfg)...)
+			continue
+		}
+
+		if compRef, _ := entry["component"].(string); compRef != "" {
+			if w, ok := resolveComponentInclude(p, compRef, cfg); ok {
+				warnings = append(warnings, w)
+			}
+			continue
+		}
+
+		// local, remote, template — resolved by GitLab at runtime, skip silently.
+	}
+	return warnings
+}
+
+// resolveProjectInclude fetches all files listed under a single project: entry
+// and merges them into p.
+func resolveProjectInclude(p *model.Pipeline, entry map[string]any, project string, cfg fetcher.GitLabConfig) []IncludeWarning {
+	ref, _ := entry["ref"].(string)
+	var warnings []IncludeWarning
+
+	for _, filePath := range includeFiles(entry) {
+		label := fmt.Sprintf("project %s:%s", project, filePath)
+		if ref != "" {
+			label += "@" + ref
+		}
+
+		if !cfg.HasToken() {
+			warnings = append(warnings, IncludeWarning{Label: label, Skipped: true})
+			continue
+		}
+
+		data, err := cfg.FetchFile(project, filePath, ref)
+		if err != nil {
+			warnings = append(warnings, IncludeWarning{Label: label, Err: err})
+			continue
+		}
+
+		included, err := model.ParseBytes(data)
+		if err != nil {
+			warnings = append(warnings, IncludeWarning{Label: label, Err: fmt.Errorf("parsing YAML: %w", err)})
+			continue
+		}
+
+		mergeIncluded(p, included)
+	}
+	return warnings
+}
+
+// resolveComponentInclude fetches a CI/CD catalog component and merges it into p.
+// Returns (warning, true) if something went wrong; (zero, false) on success.
+func resolveComponentInclude(p *model.Pipeline, ref string, cfg fetcher.GitLabConfig) (IncludeWarning, bool) {
+	label := "component " + ref
+
+	// Variable interpolation (e.g. $CI_SERVER_FQDN) cannot be resolved locally.
+	if strings.ContainsRune(ref, '$') {
+		return IncludeWarning{
+			Label: label,
+			Err:   fmt.Errorf("component reference contains a CI variable that cannot be resolved at lint time"),
+		}, true
+	}
+
+	host, project, component, version, err := parseComponentRef(ref)
+	if err != nil {
+		return IncludeWarning{Label: label, Err: err}, true
+	}
+
+	hostCfg := cfg.ForHost(host)
+	data, err := fetchComponentFile(hostCfg, project, component, version)
+	if err != nil {
+		return IncludeWarning{Label: label, Err: err}, true
+	}
+
+	included, err := model.ParseBytes(data)
+	if err != nil {
+		return IncludeWarning{Label: label, Err: fmt.Errorf("parsing component YAML: %w", err)}, true
+	}
+
+	mergeIncluded(p, included)
+	return IncludeWarning{}, false
+}
+
+// parseComponentRef parses a CI/CD component reference of the form:
+//
+//	<host>/<project-path>/<component-name>@<version>
+//
+// The host is the GitLab instance FQDN. The last path segment before @ is the
+// component name; everything between host and component name is the project path.
+//
+// Examples:
+//
+//	gitlab.com/components/golang/build@v1.0.0
+//	gitlab.example.com/my-org/ci-templates/lint@main
+//	gitlab.com/components/secret-detection/secret-detection@~latest
+func parseComponentRef(ref string) (host, project, component, version string, err error) {
+	atIdx := strings.LastIndex(ref, "@")
+	if atIdx < 0 || atIdx == len(ref)-1 {
+		err = fmt.Errorf("component reference %q must include a version (e.g. @v1.0 or @main)", ref)
+		return
+	}
+	version = ref[atIdx+1:]
+	path := ref[:atIdx]
+
+	parts := strings.Split(path, "/")
+	// Minimum: host + at least one project segment + component = 3 parts.
+	if len(parts) < 3 {
+		err = fmt.Errorf("component reference %q must be <host>/<project>/<component>@<version>", ref)
+		return
+	}
+
+	host = parts[0]
+	component = parts[len(parts)-1]
+	project = strings.Join(parts[1:len(parts)-1], "/")
+	return
+}
+
+// fetchComponentFile fetches a component's template YAML from a GitLab project.
+// GitLab supports two layouts; both are attempted:
+//   - templates/<component>.yml  (single-file component)
+//   - templates/<component>/template.yml  (directory component)
+func fetchComponentFile(cfg fetcher.GitLabConfig, project, component, version string) ([]byte, error) {
+	primary := "templates/" + component + ".yml"
+	data, err := cfg.FetchFile(project, primary, version)
+	if err == nil {
+		return data, nil
+	}
+
+	fallback := "templates/" + component + "/template.yml"
+	data2, err2 := cfg.FetchFile(project, fallback, version)
+	if err2 != nil {
+		// Return the primary error — it refers to the canonical path.
+		return nil, fmt.Errorf("%v (also tried %s: %v)", err, fallback, err2)
+	}
+	return data2, nil
+}
+
+// normaliseInclude converts a raw include: list element to a string-keyed map.
+// An include: value can be a plain string (shorthand local) or a map.
+func normaliseInclude(raw any) (map[string]any, bool) {
+	switch v := raw.(type) {
+	case map[string]any:
+		return v, true
+	case string:
+		return map[string]any{"local": v}, true
+	}
+	return nil, false
+}
+
+// includeFiles returns the list of file paths from an include entry.
+// The file: key may be a single string or a list of strings.
+func includeFiles(entry map[string]any) []string {
+	raw, ok := entry["file"]
+	if !ok {
+		return nil
+	}
+	switch v := raw.(type) {
+	case string:
+		return []string{v}
+	case []any:
+		var paths []string
+		for _, item := range v {
+			if s, ok := item.(string); ok {
+				paths = append(paths, s)
+			}
+		}
+		return paths
+	}
+	return nil
+}
+
+// mergeIncluded copies jobs and stages from src into dst.
+// dst (the main pipeline) always wins when a key already exists.
+func mergeIncluded(dst, src *model.Pipeline) {
+	stageSet := make(map[string]bool, len(dst.Stages))
+	for _, s := range dst.Stages {
+		stageSet[s] = true
+	}
+	for _, s := range src.Stages {
+		if !stageSet[s] {
+			dst.Stages = append(dst.Stages, s)
+			stageSet[s] = true
+		}
+	}
+
+	for name, job := range src.Jobs {
+		if _, exists := dst.Jobs[name]; !exists {
+			dst.Jobs[name] = job
+			if raw, ok := src.RawJobs[name]; ok {
+				dst.RawJobs[name] = raw
+			}
+		}
+	}
+}