BlueGit

timfa bluegit

Files

bluegit / internal / cispec / doc.go

doc.go

doc.go 7.3 KiB Download Raw
1// Package cispec is de blue-ci-cd.yml-specificatie.
2// De infopagina en GET /api/v1/ci/spec gebruiken allebei Build, zodat de
3// tekst en de presets niet uit elkaar lopen.
4package cispec
5
6import (
7 "bytes"
8 "encoding/json"
9
10 "gitlab.com/Timfa/bluegit/internal/i18n"
11 "gitlab.com/Timfa/bluegit/internal/images"
12)
13
14// Doc is het document dat de pagina tekent en de API teruggeeft.
15type Doc struct {
16 File string `json:"file"`
17 Example string `json:"example"`
18 Sections []Section `json:"sections"`
19}
20
21// Section is één blok: sleutelwoorden, variabelen, verschillen of presets.
22type Section struct {
23 ID string `json:"id"`
24 Title string `json:"title"`
25 Intro string `json:"intro,omitempty"`
26 Kind string `json:"kind"`
27 Items []Item `json:"items,omitempty"`
28 Variables []Variable `json:"variables,omitempty"`
29 Lines []string `json:"lines,omitempty"`
30 Presets []Preset `json:"presets,omitempty"`
31}
32
33// Item is één sleutelwoord.
34type Item struct {
35 Name string `json:"name"`
36 Summary string `json:"summary"`
37}
38
39// Variable is een voorgedefinieerde CI_-variabele.
40// Scope is both, container of mr en blijft in het Engels, ook als de pagina vertaald is.
41type Variable struct {
42 Name string `json:"name"`
43 Scope string `json:"scope"`
44 Where string `json:"where"`
45 Summary string `json:"summary"`
46}
47
48// Preset is één image-alias zoals Steve die bouwt of mapt.
49type Preset struct {
50 Name string `json:"name"`
51 Runtime string `json:"runtime"`
52 From string `json:"from"`
53 Tools []string `json:"tools"`
54 Mode string `json:"mode"`
55}
56
57const example = `image: bluegit/base
58unit:
59 stage: test
60 image: bluegit/node
61 script:
62 - node --version
63plain:
64 stage: test
65 image: node:22
66 script:
67 - node --version
68`
69
70// Build maakt het document in lang. presets nil gebruikt de ingebouwde lijst.
71func Build(lang i18n.Lang, presets []images.Preset) Doc {
72 if presets == nil {
73 presets = images.Builtin()
74 }
75 t := func(key string) string { return i18n.T(lang, key) }
76 kw := func(name, key string) Item { return Item{Name: name, Summary: t(key)} }
77 where := map[string]string{
78 "both": t("info.where.both"),
79 "container": t("info.where.container"),
80 "mr": t("info.where.mr"),
81 }
82 variable := func(name, scope string) Variable {
83 return Variable{Name: name, Scope: scope, Where: where[scope], Summary: t("info.var." + name)}
84 }
85 doc := Doc{
86 File: "blue-ci-cd.yml",
87 Example: example,
88 Sections: []Section{
89 {
90 ID: "pipeline", Title: t("info.sec.pipeline"), Kind: "keywords",
91 Items: []Item{
92 kw("stages", "info.kw.stages"),
93 kw("variables", "info.kw.variables"),
94 kw("image", "info.kw.image"),
95 kw("default", "info.kw.default"),
96 kw("include", "info.kw.include"),
97 kw("before_script", "info.kw.before_script"),
98 kw("after_script", "info.kw.after_script"),
99 kw("cache", "info.kw.cache"),
100 kw("workflow", "info.kw.workflow"),
101 kw("jobs", "info.kw.jobs"),
102 },
103 },
104 {
105 ID: "jobs", Title: t("info.sec.job"), Kind: "keywords",
106 Items: []Item{
107 kw("stage", "info.kw.stage"),
108 kw("image", "info.kw.image"),
109 kw("before_script", "info.kw.before_script"),
110 kw("script", "info.kw.script"),
111 kw("after_script", "info.kw.after_script"),
112 kw("needs", "info.kw.needs"),
113 kw("rules", "info.kw.rules"),
114 kw("only", "info.kw.only"),
115 kw("except", "info.kw.except"),
116 kw("when", "info.kw.when"),
117 kw("allow_failure", "info.kw.allow_failure"),
118 kw("artifacts", "info.kw.artifacts"),
119 kw("cache", "info.kw.cache"),
120 kw("resource_group", "info.kw.resource_group"),
121 kw("timeout", "info.kw.timeout"),
122 kw("retry", "info.kw.retry"),
123 kw("parallel", "info.kw.parallel"),
124 kw("services", "info.kw.services"),
125 kw("environment", "info.kw.environment"),
126 kw("interruptible", "info.kw.interruptible"),
127 kw("doNotInterrupt", "info.kw.doNotInterrupt"),
128 kw("tags", "info.kw.tags"),
129 kw("extends", "info.kw.extends"),
130 },
131 },
132 {
133 ID: "rules", Title: t("info.sec.rules"), Kind: "keywords",
134 Intro: t("info.rules.intro"),
135 Items: []Item{
136 kw("if", "info.kw.if"),
137 kw("changes", "info.kw.changes"),
138 kw("exists", "info.kw.exists"),
139 kw("when", "info.kw.when"),
140 },
141 },
142 {
143 ID: "variables", Title: t("info.sec.variables"), Kind: "variables",
144 Variables: []Variable{
145 variable("CI", "both"),
146 variable("CI_CONFIG_PATH", "both"),
147 variable("CI_SERVER_NAME", "both"),
148 variable("CI_COMMIT_SHA", "both"),
149 variable("CI_COMMIT_SHORT_SHA", "both"),
150 variable("CI_COMMIT_REF", "both"),
151 variable("CI_COMMIT_REF_NAME", "both"),
152 variable("CI_COMMIT_REF_SLUG", "both"),
153 variable("CI_COMMIT_TITLE", "both"),
154 variable("CI_COMMIT_TIMESTAMP", "both"),
155 variable("CI_COMMIT_BRANCH", "both"),
156 variable("CI_COMMIT_TAG", "both"),
157 variable("CI_DEFAULT_BRANCH", "both"),
158 variable("CI_PIPELINE_ID", "both"),
159 variable("CI_PIPELINE_SOURCE", "both"),
160 variable("CI_PIPELINE_URL", "both"),
161 variable("CI_PROJECT_PATH", "both"),
162 variable("CI_PROJECT_NAME", "both"),
163 variable("CI_PROJECT_NAMESPACE", "both"),
164 variable("CI_PROJECT_URL", "both"),
165 variable("CI_API_URL", "both"),
166 variable("CI_JOB_ID", "container"),
167 variable("CI_JOB_NAME", "container"),
168 variable("CI_JOB_STAGE", "container"),
169 variable("CI_JOB_URL", "container"),
170 variable("CI_JOB_TOKEN", "container"),
171 variable("CI_NODE_INDEX", "container"),
172 variable("CI_NODE_TOTAL", "container"),
173 variable("CI_ENVIRONMENT_NAME", "container"),
174 variable("CI_ENVIRONMENT_URL", "container"),
175 variable("CI_MERGE_REQUEST_ID", "mr"),
176 variable("CI_MERGE_REQUEST_IID", "mr"),
177 variable("CI_MERGE_REQUEST_TITLE", "mr"),
178 variable("CI_MERGE_REQUEST_SOURCE_BRANCH_NAME", "mr"),
179 variable("CI_MERGE_REQUEST_SOURCE_BRANCH_SHA", "mr"),
180 variable("CI_MERGE_REQUEST_TARGET_BRANCH_NAME", "mr"),
181 variable("CI_MERGE_REQUEST_TARGET_BRANCH_SHA", "mr"),
182 variable("CI_MERGE_REQUEST_PROJECT_PATH", "mr"),
183 variable("CI_MERGE_REQUEST_PROJECT_URL", "mr"),
184 },
185 },
186 {
187 ID: "differences", Title: t("info.sec.diff"), Kind: "list",
188 Lines: []string{
189 t("info.diff.file"),
190 t("info.diff.runner"),
191 t("info.diff.include"),
192 t("info.diff.unsupported"),
193 t("info.diff.services"),
194 t("info.diff.env"),
195 t("info.diff.retry"),
196 t("info.diff.parallel"),
197 t("info.diff.rules"),
198 t("info.diff.mr"),
199 t("info.diff.cache"),
200 t("info.diff.images"),
201 },
202 },
203 {
204 ID: "presets", Title: t("info.sec.presets"), Kind: "presets",
205 Intro: t("info.presets.intro") + " " + t("info.presets.config"),
206 Presets: presetDocs(presets),
207 },
208 },
209 }
210 return doc
211}
212
213func presetDocs(in []images.Preset) []Preset {
214 out := make([]Preset, 0, len(in))
215 for _, p := range in {
216 mode := "dockerfile"
217 if p.Direct != "" {
218 mode = "image"
219 }
220 tools := p.Tools
221 if tools == nil {
222 tools = []string{}
223 }
224 out = append(out, Preset{
225 Name: p.Name, Runtime: p.Runtime, From: p.From, Tools: tools, Mode: mode,
226 })
227 }
228 return out
229}
230
231// Marshal is de JSON die de pagina in het scriptblok zet en de API schrijft.
232func Marshal(doc Doc) []byte {
233 var buf bytes.Buffer
234 enc := json.NewEncoder(&buf)
235 enc.SetEscapeHTML(true)
236 _ = enc.Encode(doc)
237 return buf.Bytes()
238}