glint/ROADMAP.md

Roadmap

This document tracks planned improvements to glint. Items are grouped by theme, roughly in priority order within each group. Nothing here is a commitment — the tool is experimental and the list will shift as real usage surfaces better priorities.

---

Context-aware validation — ✓ single-context shipped in v0.2.0; expression evaluator hardened post-v0.2.0

Single-context simulation is fully implemented. Pass --branch, --tag, --source, or --var to either glint check or glint graph; jobs are evaluated and shown as active / manual / skipped.

# shipped: single-context simulation
glint check --branch develop .gitlab-ci.yml
glint check --tag v1.2.0 .gitlab-ci.yml
glint check --source merge_request_event --var CI_MERGE_REQUEST_TARGET_BRANCH_NAME=main .gitlab-ci.yml
glint graph tree --branch main .gitlab-ci.yml   # tree annotated with [skipped] / [manual]

Shipped post-v0.2.0 (unreleased)

• ✓ workflow:rules:variables: propagation — variables defined on the matching workflow:rules: entry are injected into the evaluation context before job rules:if: expressions are evaluated. Pipeline-level variables: defaults are also available. Priority chain (highest wins): --var > shortcuts > workflow-rule vars > pipeline defaults.
• ✓ Expression evaluator: multi-line expressions — newlines in block-scalar and folded YAML if: values are now treated as whitespace; || / && on a continuation line evaluate correctly.
• ✓ Expression evaluator: ${VAR} curly-brace syntax — ${CI_COMMIT_BRANCH} is equivalent to $CI_COMMIT_BRANCH everywhere.
• ✓ Expression evaluator: regex flags — /pattern/i, /pattern/m, /pattern/s are now supported; i maps to (?i) in Go's regexp.
• ✓ Expression evaluator: variable as regex RHS — $BRANCH =~ $PATTERN where $PATTERN holds a /regex/ string is evaluated correctly.
• ✓ Expression evaluator: bare true / false keywords — treated as the strings "true" / "false" matching GitLab CI's own behaviour; $GATEWAY_ENABLED == true now evaluates correctly.
• ✓ Expression evaluator: integer literals — $COUNT == 4, $ENABLED == 1, $DISABLED == 0 compare as decimal strings.

Remaining work

• Multi-context simulation — run multiple contexts in one invocation and print a comparison table:

  glint check --context branch=main --context branch=develop --context tag=v1.0.0 .gitlab-ci.yml
  

• Context-scoped linting — skip needs:/dependencies: cross-checks for jobs that are statically unreachable in the given context
• rules:changes: evaluation — path glob evaluation against the local git tree

---

Lint coverage

The current rule set covers the most common sources of broken pipelines. These are the gaps most likely to matter in practice.

• Variable reference validation — warn when a job references $VAR (or ${VAR}) that is not declared anywhere in variables:, default.variables, or the job itself
• services: validation — map form requires name; alias must be a valid DNS label
• rules:changes / rules:exists — warn on glob patterns that can never match (e.g. absolute paths, double ** on unsupported versions)
• timeout format — must be a duration string GitLab understands (1h 30m, 90 minutes, etc.)
• id_tokens: / secrets: — presence and required-key checks
• pages:publish — validate that the path is consistent with artifacts.paths
• inherit: completeness — flag when a job overrides a default field that would require inherit: default: false to suppress
• Unreachable jobs — detect jobs that can never run because every rules: branch evaluates to never (static analysis only, no variable expansion)
• Duplicate stage names — GitLab silently merges them; warn to avoid confusion
• cache:key:files — must be a list of paths, not a glob

---

Include resolution

• include: local: full resolution — ✓ shipped in v0.2.0; local files are read from disk, recursively resolved, and merged before linting
• include: remote: (URL) — ✓ shipped post-v0.2.0; plain HTTPS URLs are fetched (unauthenticated), parsed, and merged; sub-includes are resolved recursively; unreachable URLs emit [WARNING] and linting continues
• Recursive include depth limit — guard against include cycles across files
• Offline mode / cache — persist fetched remote templates to a local cache directory; --offline flag to skip network calls and use only cached copies
• include: inputs: — substitute CI component input values into fetched templates before merging, so component-scoped jobs get their correct stage: and keyword values

---

Output formats

Right now the only output is plain-text findings. Structured output enables integration with other tools.

• JSON (--format json) — machine-readable findings with file, job, severity, rule ID, and message; stable schema
• SARIF (--format sarif) — Static Analysis Results Interchange Format; consumed natively by GitHub Code Scanning and GitLab SAST
• JUnit XML (--format junit) — lets CI pipelines publish lint results as a test report artifact
• GitHub / GitLab annotation format — emit ::error file=…,line=…::message lines so findings appear as inline comments in PR diffs

---

Pipeline graph improvements

The SVG renderer and terminal tree cover the basic layout. These would bring it closer to GitLab's full interactive view.

• Terminal job tree — ✓ shipped in v0.2.0 as glint graph tree; stages as branches, jobs as leaves, context-aware annotations
• glint graph includes shows jobs per file — ✓ shipped post-v0.2.0; each include node shows the jobs it defines as dashed-arrow rounded nodes in a distinct style
• Multi-job connector accuracy — draw one connector per job pair rather than one per stage pair in classic mode, so pipelines with uneven columns look correct
• Job tooltip / detail panel — embed a hidden <title> and <desc> per chip so SVG viewers show stage, when, image, and needs on hover
• when: on_failure visual distinction — dashed border or distinct icon for failure-path jobs
• Blocked / skipped state colouring — grey out jobs that are statically unreachable given known rules: conditions
• Interactive HTML output — self-contained .html file with pan/zoom and a job-detail sidebar; no external dependencies
• Mermaid pipeline output — keep pipeline.go but wire it up through --graph pipeline --format mermaid for users who want to paste into mermaid.live

---

Findings quality — ✓ file and line numbers shipped post-v0.2.0

File and line numbers on findings — ✓ shipped post-v0.2.0; every [ERROR] / [WARNING] now includes the source file and exact line of the job key (e.g. job "deploy" (src/deploy.yml:14): …). Works across local includes, remote project templates, and fetched component templates.

Remaining improvements

• needs: optional: true false-positive errors — ✓ shipped post-v0.2.0; optional missing needs are downgraded to [WARNING]
• extends: jobs with missing script false errors — ✓ shipped post-v0.2.0; jobs using extends: that have no script after resolution emit [WARNING] (the script may come from an unfetchable remote base)
• rules:if: static reachability — report when a job's entire rules: block can never evaluate to when: on_success given the declared pipeline variables (pure static, no context required)

---

CI / editor integration

• GitLab CI template — a .gitlab-ci.yml snippet that runs glint as a pipeline-validation job before the real pipeline executes; publishable to the GitLab CI/CD Catalog
• GitHub Actions action — uses: k3nny/glint@v1 wrapper for repositories that mirror or manage GitLab pipelines from GitHub
• Pre-commit hook — entry for pre-commit so glint runs automatically on git commit when .gitlab-ci.yml changes
• LSP server — glint lsp mode exposing diagnostics over the Language Server Protocol; enables inline squiggles in VS Code, JetBrains, Neovim, etc. without a dedicated extension
• VS Code extension — thin wrapper around the LSP server with syntax highlighting for .gitlab-ci.yml

---

Configuration

• .glint.yml config file — project-level configuration for:
  • Rule suppression by rule ID (e.g. ignore: [no-only, missing-stages])
  • Severity overrides (demote specific errors to warnings)
  • Custom stages allowlist for projects that use a non-standard default set
  • Token and URL defaults so flags are not needed in every invocation
• Inline suppression comments — # glint: ignore next-line <rule-id> in the pipeline YAML

---

Reliability and developer experience

• Structured rule IDs — assign a stable short ID to every rule (e.g. GS001) so suppression, documentation, and SARIF output are stable across versions
• --explain <rule-id> — print the rule description, rationale, and an example fix
• Semantic versioning and first release — shipped as v0.1.0 (2026-06-07)
• Subcommand CLI — shipped as v0.2.0 (2026-06-11); glint check / glint graph [mode] with ruff-style --help
• Changelog automation — generate release notes from Conventional Commits via git-cliff or similar
• Fuzz testing — add a go test -fuzz target for the YAML parser to harden it against malformed input