docs(docs): sync README and FEATURES with current CLI
ci / vet, staticcheck, test, build (push) Successful in 1m55s
ci / vet, staticcheck, test, build (push) Successful in 1m55s
README: add render command, fix exit code descriptions (2/10 not 1), bump integration version references to v0.3.0, fix Usage command list. FEATURES: document glint render section, colorized text output format, exit code table, --no-warn, --no-skipped, --list-vars in developer tools table, bump JSON schema example to v0.3.0 with column field. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
+45
-6
@@ -118,6 +118,30 @@ Jobs whose name starts with `.` are reusable templates; most rules are skipped f
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Pipeline rendering (`glint render`)
|
||||||
|
|
||||||
|
`glint render <PIPELINE>` resolves all `include:` and `extends:` chains and
|
||||||
|
writes the fully flattened pipeline to a single YAML file. This is what GitLab
|
||||||
|
CI processes server-side.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
glint render .gitlab-ci.yml # writes rendered.gitlab-ci.yml
|
||||||
|
glint render --output merged.yml .gitlab-ci.yml # custom output path
|
||||||
|
glint render --output - .gitlab-ci.yml | yq . # stream to stdout
|
||||||
|
glint render --offline --cache-dir ~/.cache/glint .gitlab-ci.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output order:** `stages`, `variables`, `default`, `workflow`, template jobs
|
||||||
|
(`.name`, alphabetical), then regular jobs (alphabetical). The `include:` key
|
||||||
|
(consumed by resolution) and `extends:` keys (merged into each job) are
|
||||||
|
stripped. All other fields are preserved verbatim.
|
||||||
|
|
||||||
|
Accepts the same network flags as `glint check`: `--token`, `--gitlab-url`,
|
||||||
|
`--cache-dir`, `--offline`, `--proxy`. When writing to a file (not stdout)
|
||||||
|
a summary line is printed to stderr: `rendered: <file> (N job(s), M stage(s))`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Context simulation
|
## Context simulation
|
||||||
|
|
||||||
Pass `--branch`, `--tag`, `--source`, or `--var` to evaluate `rules:if:` and
|
Pass `--branch`, `--tag`, `--source`, or `--var` to evaluate `rules:if:` and
|
||||||
@@ -184,27 +208,37 @@ test-job active active
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Output formats
|
## Output formats (`glint check`)
|
||||||
|
|
||||||
Pass `--format` to `glint check`. In structured formats the summary line is
|
Pass `--format` to `glint check`. In structured formats the summary line is
|
||||||
written to stderr so stdout contains only the machine-readable payload.
|
written to stderr so stdout contains only the machine-readable payload.
|
||||||
|
|
||||||
| Format | Flag | Description |
|
| Format | Flag | Description |
|
||||||
|--------|------|-------------|
|
|--------|------|-------------|
|
||||||
| Text (default) | `--format text` | Ruff-style `file:line: RULE [sev] message` |
|
| Text (default) | `--format text` | Four aligned columns (location, rule, severity, message); `error` in bold red, `warning` in bold orange; colors auto-detected (suppressed when `NO_COLOR` is set or stdout is not a terminal) |
|
||||||
| JSON | `--format json` | Stable schema (version 1); `findings` array + `summary` block |
|
| JSON | `--format json` | Stable schema (version 1); `findings` array + `summary` block |
|
||||||
| SARIF 2.1.0 | `--format sarif` | Consumed by GitHub Code Scanning and GitLab SAST |
|
| SARIF 2.1.0 | `--format sarif` | Consumed by GitHub Code Scanning and GitLab SAST |
|
||||||
| JUnit XML | `--format junit` | CI test-report artifact (`artifacts:reports:junit`) |
|
| JUnit XML | `--format junit` | CI test-report artifact (`artifacts:reports:junit`) |
|
||||||
| GitHub annotations | `--format github` | `::error file=…,line=…,title=RULE::message` inline PR comments |
|
| GitHub annotations | `--format github` | `::error file=…,line=…,title=RULE::message` inline PR comments |
|
||||||
|
|
||||||
|
**Exit codes:**
|
||||||
|
|
||||||
|
| Code | Meaning |
|
||||||
|
|------|---------|
|
||||||
|
| `0` | No findings (clean pipeline) |
|
||||||
|
| `2` | One or more error findings |
|
||||||
|
| `10` | One or more warning findings, no errors |
|
||||||
|
|
||||||
|
Use `--no-warn` to suppress all warnings; a pipeline with only warnings then exits `0`.
|
||||||
|
|
||||||
**JSON schema (`schema_version: 1`):**
|
**JSON schema (`schema_version: 1`):**
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"schema_version": 1,
|
"schema_version": 1,
|
||||||
"glint_version": "v0.2.20",
|
"glint_version": "v0.3.0",
|
||||||
"pipeline": ".gitlab-ci.yml",
|
"pipeline": ".gitlab-ci.yml",
|
||||||
"findings": [
|
"findings": [
|
||||||
{"rule":"GL004","severity":"error","file":".gitlab-ci.yml","line":14,
|
{"rule":"GL004","severity":"error","file":".gitlab-ci.yml","line":14,"column":1,
|
||||||
"job":"deploy","message":"stage \"production\" is not defined in 'stages'"}
|
"job":"deploy","message":"stage \"production\" is not defined in 'stages'"}
|
||||||
],
|
],
|
||||||
"summary": {"total": 1, "errors": 1, "warnings": 0}
|
"summary": {"total": 1, "errors": 1, "warnings": 0}
|
||||||
@@ -296,6 +330,8 @@ jobs or pipeline-level findings.
|
|||||||
| `mermaid` | Print Mermaid flowchart to stdout (paste into [mermaid.live](https://mermaid.live)) |
|
| `mermaid` | Print Mermaid flowchart to stdout (paste into [mermaid.live](https://mermaid.live)) |
|
||||||
| `html` | Write self-contained HTML to `--out` with mouse pan/zoom and a click-to-open job-detail sidebar |
|
| `html` | Write self-contained HTML to `--out` with mouse pan/zoom and a click-to-open job-detail sidebar |
|
||||||
|
|
||||||
|
**Context flags** (`--branch`, `--tag`, `--source`, `--var`, `--changes`, `--changes-from`) work on all modes and annotate or colour jobs based on their evaluated state. Use `--no-skipped` to remove jobs that would not run in the given context from all output entirely (tree, SVG, HTML, and Mermaid).
|
||||||
|
|
||||||
**Visual distinctions in SVG and HTML output:**
|
**Visual distinctions in SVG and HTML output:**
|
||||||
|
|
||||||
- **Regular** — blue circle with checkmark
|
- **Regular** — blue circle with checkmark
|
||||||
@@ -303,7 +339,7 @@ jobs or pipeline-level findings.
|
|||||||
- **Trigger** — purple circle with chevron
|
- **Trigger** — purple circle with chevron
|
||||||
- **Delayed** — yellow circle with clock
|
- **Delayed** — yellow circle with clock
|
||||||
- **`when: on_failure`** — red circle (`#d9534f`) with X mark; dashed chip border
|
- **`when: on_failure`** — red circle (`#d9534f`) with X mark; dashed chip border
|
||||||
- **Skipped** (with `--branch`/`--tag`/`--source` context flags) — grey circle, dimmed job name
|
- **Skipped** (with context flags, without `--no-skipped`) — grey circle, dimmed job name
|
||||||
|
|
||||||
In DAG pipelines (any job has `needs:`) the pipeline graph uses job-to-job
|
In DAG pipelines (any job has `needs:`) the pipeline graph uses job-to-job
|
||||||
Bézier connectors. In classic mode a bus-bar pattern (vertical rail + per-job
|
Bézier connectors. In classic mode a bus-bar pattern (vertical rail + per-job
|
||||||
@@ -318,7 +354,10 @@ shown as a tooltip in SVG viewers and as a sidebar panel in HTML output.
|
|||||||
|
|
||||||
| Tool | Description |
|
| Tool | Description |
|
||||||
|------|-------------|
|
|------|-------------|
|
||||||
|
| `glint render <PIPELINE>` | Resolve all includes and extends; write the fully merged pipeline to a single YAML file. See [Pipeline rendering](#pipeline-rendering-glint-render) above. |
|
||||||
| `glint explain <RULE>` | Print description, rationale, bad-YAML example, and fix for a rule. Case-insensitive (`gl007` = `GL007`). |
|
| `glint explain <RULE>` | Print description, rationale, bad-YAML example, and fix for a rule. Case-insensitive (`gl007` = `GL007`). |
|
||||||
| `glint explain` | List all rules with ID, severity, and title. |
|
| `glint explain` | List all rules with ID, severity, and title. |
|
||||||
| `--list-vars` | Print all resolved pipeline variables (pipeline + workflow rules + context) to stderr before linting. |
|
| `--no-warn` | (`glint check`) Discard all warning findings before output and exit-code calculation. |
|
||||||
|
| `--no-skipped` | (`glint graph`) Remove skipped jobs from graph output entirely. |
|
||||||
|
| `--list-vars` | (`glint check`, `glint graph`) Print all resolved pipeline variables to stderr before continuing. |
|
||||||
| `--version` / `-v` | Print the compiled version string. |
|
| `--version` / `-v` | Print the compiled version string. |
|
||||||
|
|||||||
@@ -52,15 +52,15 @@ task build
|
|||||||
glint [OPTIONS] <COMMAND>
|
glint [OPTIONS] <COMMAND>
|
||||||
|
|
||||||
Commands:
|
Commands:
|
||||||
check Lint a pipeline file — exits 0 (clean) or 1 (errors found)
|
check Lint a pipeline file — exits 0 (clean), 2 (errors), or 10 (warnings only)
|
||||||
|
render Resolve all includes and extends into a single merged YAML file
|
||||||
graph Visualise the pipeline as a job tree or Mermaid graph
|
graph Visualise the pipeline as a job tree or Mermaid graph
|
||||||
explain Print description and fix for a lint rule
|
explain Show description and fix for a lint rule (e.g. glint explain GL007)
|
||||||
lsp Start a Language Server Protocol server (stdin/stdout)
|
lsp Start a Language Server Protocol server (stdin/stdout)
|
||||||
```
|
```
|
||||||
|
|
||||||
Run `glint <command> --help` for all flags. See [USAGE.md](USAGE.md) for full
|
Run `glint <command> --help` for all flags. See [FEATURES.md](FEATURES.md) for the
|
||||||
examples covering output formats, context simulation, remote includes, cache,
|
complete feature reference.
|
||||||
graph modes, and project configuration.
|
|
||||||
|
|
||||||
## Integrations
|
## Integrations
|
||||||
|
|
||||||
@@ -71,7 +71,7 @@ Add to `.pre-commit-config.yaml` in your repository to run glint automatically w
|
|||||||
```yaml
|
```yaml
|
||||||
repos:
|
repos:
|
||||||
- repo: https://git.k3nny.fr/k3nny/glint
|
- repo: https://git.k3nny.fr/k3nny/glint
|
||||||
rev: v0.2.28
|
rev: v0.3.0
|
||||||
hooks:
|
hooks:
|
||||||
- id: glint
|
- id: glint
|
||||||
```
|
```
|
||||||
@@ -89,7 +89,7 @@ include:
|
|||||||
|
|
||||||
# As a Catalog component (after publishing to a GitLab instance):
|
# As a Catalog component (after publishing to a GitLab instance):
|
||||||
include:
|
include:
|
||||||
- component: $CI_SERVER_FQDN/k3nny/glint/check@v0.2.28
|
- component: $CI_SERVER_FQDN/k3nny/glint/check@v0.3.0
|
||||||
inputs:
|
inputs:
|
||||||
stage: validate # optional, default: validate
|
stage: validate # optional, default: validate
|
||||||
allow_failure: true # optional, default: false
|
allow_failure: true # optional, default: false
|
||||||
@@ -102,7 +102,7 @@ The component downloads the glint Linux binary, runs `glint check`, and respects
|
|||||||
Copy [`action.yml`](action.yml) from this repository, or mirror this repo to GitHub as `k3nny/glint` and reference it directly:
|
Copy [`action.yml`](action.yml) from this repository, or mirror this repo to GitHub as `k3nny/glint` and reference it directly:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
- uses: k3nny/glint@v0.2.28
|
- uses: k3nny/glint@v0.3.0
|
||||||
with:
|
with:
|
||||||
file: .gitlab-ci.yml # optional, default: .gitlab-ci.yml
|
file: .gitlab-ci.yml # optional, default: .gitlab-ci.yml
|
||||||
args: '--format sarif' # optional
|
args: '--format sarif' # optional
|
||||||
|
|||||||
Reference in New Issue
Block a user