From 263bbbd1edf783a70910b73001be89ceb6121baf Mon Sep 17 00:00:00 2001 From: k3nny Date: Fri, 26 Jun 2026 22:47:08 +0200 Subject: [PATCH] docs(docs): sync README and FEATURES with current CLI 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 --- FEATURES.md | 51 +++++++++++++++++++++++++++++++++++++++++++++------ README.md | 16 ++++++++-------- 2 files changed, 53 insertions(+), 14 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index 38be482..89b2255 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -118,6 +118,30 @@ Jobs whose name starts with `.` are reusable templates; most rules are skipped f --- +## Pipeline rendering (`glint render`) + +`glint render ` 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: (N job(s), M stage(s))`. + +--- + ## Context simulation 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 written to stderr so stdout contains only the machine-readable payload. | 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 | | 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`) | | 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_version": 1, - "glint_version": "v0.2.20", + "glint_version": "v0.3.0", "pipeline": ".gitlab-ci.yml", "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'"} ], "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)) | | `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:** - **Regular** — blue circle with checkmark @@ -303,7 +339,7 @@ jobs or pipeline-level findings. - **Trigger** — purple circle with chevron - **Delayed** — yellow circle with clock - **`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 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 | |------|-------------| +| `glint render ` | 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 ` | 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. | -| `--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. | diff --git a/README.md b/README.md index 25acf2b..11b5ba2 100644 --- a/README.md +++ b/README.md @@ -52,15 +52,15 @@ task build glint [OPTIONS] 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 - 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) ``` -Run `glint --help` for all flags. See [USAGE.md](USAGE.md) for full -examples covering output formats, context simulation, remote includes, cache, -graph modes, and project configuration. +Run `glint --help` for all flags. See [FEATURES.md](FEATURES.md) for the +complete feature reference. ## Integrations @@ -71,7 +71,7 @@ Add to `.pre-commit-config.yaml` in your repository to run glint automatically w ```yaml repos: - repo: https://git.k3nny.fr/k3nny/glint - rev: v0.2.28 + rev: v0.3.0 hooks: - id: glint ``` @@ -89,7 +89,7 @@ include: # As a Catalog component (after publishing to a GitLab instance): include: - - component: $CI_SERVER_FQDN/k3nny/glint/check@v0.2.28 + - component: $CI_SERVER_FQDN/k3nny/glint/check@v0.3.0 inputs: stage: validate # optional, default: validate 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: ```yaml -- uses: k3nny/glint@v0.2.28 +- uses: k3nny/glint@v0.3.0 with: file: .gitlab-ci.yml # optional, default: .gitlab-ci.yml args: '--format sarif' # optional