just-check

Reusable linting for Just task runner. Install once, use across multiple projects.

---

• Runs linters (shellcheck, yamlfmt, gitleaks, etc.) with one command
• Skips what you don't need - no XML files? No XML linting, No yaml fiels - skips yaml linting - and so on.
• Add language-specific pack of linters (Go, Java, Node/TypeScript) on top
• Centralized linting - update once, affects all projects
• No copy-paste of linter scripts and configs between projects

Requirements

• Just - task runner
• mise - tool version manager
• Git

Quick Start

1. Copy an example justfile to your project:

   • examples/base-justfile - Scripts/configs/docs only
   • examples/go-justfile - Go project
   • examples/java-justfile - Java/Maven project
   • examples/node-justfile - Node/TypeScript project

2. Run setup:

   just setup-devtools  # Downloads to ~/.local/share/just-check
   just lint            # Runs all linters
   

That's it.

Updates

Run just setup-devtools again to check for updates:

• Interactive: Prompts "Update available: vX.Y.Z. Update? [y/N]"
• CI/non-interactive: Auto-updates to latest tag

How it works

You get base linters for free. Add language-specific linters if needed. Disable base linters you dont want.

• lint - General linters that work on most project (YAML, shell, secrets, etc.). Override to add Go/Java/Node linters
• Individual recipes - Run them seperatly, example just lint-yaml or just lint-shell.

Base Linters

Run on every project. Skip automatically if no relevant files found:

Recipe	Tool	Checks	Skips when
lint-commits	gommitlint	Commit message format	On default branch or no new commits
lint-secrets	gitleaks	Secrets/credentials	Never (scans commits)
lint-yaml	yamlfmt	YAML formatting	No .yml/.yaml files
lint-markdown	rumdl	Markdown style	No .md files
lint-shell	shellcheck	Shell script bugs	No .sh/.bash files
lint-shell-fmt	shfmt	Shell formatting	No .sh/.bash files
lint-shell-fix	shellcheck+shfmt	Auto-fix shell scripts	No .sh/.bash files
lint-actions	actionlint	CI workflow syntax	No workflow directories
lint-license	reuse	License compliance	Never (scans all)
lint-container	hadolint	Dockerfile best practices	No Containerfile/Dockerfile
lint-xml	xmllint	XML syntax/formatting	No .xml files

Language-Specific Linters

Java

Recipe	Tool	Description
lint-java	maven	Run all (checkstyle + pmd + spotbugs)
lint-java-checkstyle	checkstyle	Style checks
lint-java-pmd	pmd	Static analysis
lint-java-spotbugs	spotbugs	Bug detection
lint-java-fmt	formatter	Check formatting
lint-java-fmt-fix	formatter	Fix formatting

Node/TypeScript

Recipe	Tool	Description
lint-node	npm	Run all (eslint + prettier + types)
lint-node-eslint	eslint	Code quality checks (JS/TS)
lint-node-format	prettier	Code formatting check
lint-node-format-fix	prettier	Fix code formatting
lint-node-ts-types	tsc	TypeScript type checking

Go

Recipe	Tool	Description
lint-go	go	Run all (vet + staticcheck + govulncheck + golangci-lint + wsl)
lint-go-vet	go vet	Built-in static analysis
lint-go-staticcheck	staticcheck	Advanced static analysis
lint-go-vulncheck	govulncheck	Vulnerability scanning
lint-go-golangci	golangci-lint	Multi-linter runner
lint-go-wsl	wsl	Whitespace linting
lint-go-fmt	gofmt	Check formatting
lint-go-fmt-fix	gofmt	Fix formatting
lint-go-wsl-fix	wsl	Fix whitespace issues

Security Scanning

Optional security scanners for container images and repository best practices:

Recipe	Tool	Description
security-trivy	trivy	Container/filesystem vulnerability scanning
security-dockle	dockle	Container best practices (complements hadolint)
security-scorecard	scorecard	OSSF security best practices

Add language-specific linters

Add language-specific recipes to your justfile. The verify.sh script (called by just verify) automatically detects recipes with these names and includes them in the summary:

• Java: lint-java-checkstyle, lint-java-pmd, lint-java-spotbugs
• Node: lint-node-eslint, lint-node-format, lint-node-ts-types
• Go: lint-go-vet, lint-go-staticcheck, lint-go-vulncheck, lint-go-golangci, lint-go-wsl
• Security: security-trivy, security-dockle, security-scorecard

No need to override lint - just define the recipes and they're picked up automatically.

Java/Maven Project

java_lint := devtools_dir + "/linters/java"

# Run all Java linters together (convenience command)
[group('lint')]
lint-java:
    @{{java_lint}}/lint.sh

# Individual Java linters (auto-detected by verify.sh)
[group('lint')]
lint-java-checkstyle:
    @{{java_lint}}/checkstyle.sh

[group('lint')]
lint-java-pmd:
    @{{java_lint}}/pmd.sh

[group('lint')]
lint-java-spotbugs:
    @{{java_lint}}/spotbugs.sh

[group('lint')]
lint-java-fmt:
    @{{java_lint}}/format.sh check

[group('fix')]
lint-java-fmt-fix:
    @{{java_lint}}/format.sh fix

When you run just verify, the verify script automatically detects lint-java-checkstyle, lint-java-pmd, and lint-java-spotbugs recipes and includes them in the summary table. You can also run just lint-java to execute all Java linters together.

See examples/java-justfile for a complete example.

Node/TypeScript Project

node_lint := devtools_dir + "/linters/node"

# Run all Node linters together (convenience command)
[group('lint')]
lint-node:
    @{{node_lint}}/lint.sh

# Individual Node linters (auto-detected by verify.sh)
[group('lint')]
lint-node-eslint:
    @{{node_lint}}/eslint.sh

[group('lint')]
lint-node-format:
    @{{node_lint}}/format.sh check

[group('lint')]
lint-node-ts-types:
    @{{node_lint}}/types.sh

[group('fix')]
lint-node-format-fix:
    @{{node_lint}}/format.sh fix

When you run just verify, the verify script automatically detects lint-node-* recipes and includes them in the summary table. You can also run just lint-node to execute all Node linters together.

See examples/node-justfile for a complete example.

Go Project

go_lint := devtools_dir + "/linters/go"

# Run all Go linters together (convenience command)
[group('lint')]
lint-go:
    @{{go_lint}}/lint.sh

# Individual Go linters (auto-detected by verify.sh)
[group('lint')]
lint-go-vet:
    @{{go_lint}}/vet.sh

[group('lint')]
lint-go-staticcheck:
    @{{go_lint}}/staticcheck.sh

[group('lint')]
lint-go-vulncheck:
    @{{go_lint}}/govulncheck.sh

[group('lint')]
lint-go-golangci:
    @{{go_lint}}/golangci-lint.sh

[group('lint')]
lint-go-wsl:
    @{{go_lint}}/wsl.sh

[group('lint')]
lint-go-fmt:
    @{{go_lint}}/format.sh check

[group('fix')]
lint-go-fmt-fix:
    @{{go_lint}}/format.sh fix

[group('fix')]
lint-go-wsl-fix:
    @{{go_lint}}/wsl.sh fix

[group('fix')]
lint-go-golangci-fix:
    @{{go_lint}}/golangci-lint.sh fix

When you run just verify, the verify script automatically detects lint-go-* recipes and includes them in the summary table. You can also run just lint-go to execute all Go linters together.

See examples/go-justfile for a complete example.

Rust Project

# Rust linters (add to verify.sh detection if needed)
[group('lint')]
lint-rust:
    cargo fmt --check
    cargo clippy -- -D warnings

Note: Rust linters are not auto-detected by verify.sh yet. You can add detection in scripts/verify.sh following the Java/Node/Go pattern, or run them separately with just lint-rust.

Security Scanning

security_lint := devtools_dir + "/linters/security"

# Container vulnerability scanning (trivy)
[group('security')]
security-trivy:
    @{{security_lint}}/trivy.sh

# Container best practices (dockle)
[group('security')]
security-dockle:
    @{{security_lint}}/dockle.sh

# OSSF Scorecard
[group('security')]
security-scorecard:
    @{{security_lint}}/scorecard.sh

Security scanners are auto-detected by verify.sh and included in the summary. They gracefully skip if:

• Required tools are not installed
• No container images/files are found
• Authentication token is not configured (scorecard)

Minimal Project (base linters only)

# Run all linters with summary (base linters only)
lint: _ensure-devtools
    @{{devtools_dir}}/scripts/verify.sh

Multiple Languages

# Define linters from multiple languages - verify.sh auto-detects them all
lint: _ensure-devtools
    @{{devtools_dir}}/scripts/verify.sh

# Java linters
lint-java-checkstyle:
    @{{java_lint}}/checkstyle.sh

# Node linters
lint-node-eslint:
    @{{node_lint}}/eslint.sh

All defined lint-* recipes are automatically detected and included in the summary.

Customizing and Skipping Linters

You can override any linter recipe in your project's justfile to customize behavior or skip checks.

Disable or Skip a Linter

Two options to disable a linter:

Option 1: Hide completely - empty recipe (no output), linter won't appear in summary:

[group('lint')]
lint-license:

Option 2: Show as skipped - output message containing "Skip", shown as skipped in summary:

[group('lint')]
lint-license:
    @echo "Skipping license check - not required for this project"

Result in summary:

# Option 1: not shown at all
# Option 2:
License                reuse         -  skipped

Customize a Linter

Override a recipe to use custom configurations or different tools:

# Use custom shellcheck config
lint-shell:
    @shellcheck --severity=warning --exclude=SC2034 **/*.sh

# Run checkstyle with custom rules
lint-java-checkstyle:
    @mvn checkstyle:check -Dcheckstyle.config.location=custom-checks.xml

Conditional Linting

Skip linters conditionally based on environment or files:

# Skip license check in development, run in CI
lint-license:
    #!/usr/bin/env bash
    if [[ "${CI:-}" == "true" ]]; then
        {{lint}}/license.sh
    else
        echo "Skipping license check in development"
    fi

# Skip spotbugs if no Java code changed
lint-java-spotbugs:
    #!/usr/bin/env bash
    if git diff --name-only main | grep -q "\.java$"; then
        {{java_lint}}/spotbugs.sh
    else
        echo "Skipping SpotBugs - no Java files changed"
    fi

Note: The justfile is the interface - verify.sh respects all recipe overrides. Changes take effect immediately without updating just-check.

Utilities

Use colors.sh for consistent output in custom recipes:

my-recipe:
    #!/usr/bin/env bash
    source "{{colors}}"
    just_header "My Task" "some command"
    just_run "Task description" some command arg1 arg2
    just_success "Task completed"

Available functions:

Function	Description
just_header "Title" "cmd"	Cyan header with dim command
just_run "desc" cmd args...	Run command, show output only on failure
just_success "msg"	Green ✓ message
just_error "msg"	Red ✗ message
just_warn "msg"	Yellow ! message

Configuration

Override Default Linter Configs

Linters use sensible defaults (e.g., excluding target/, node_modules/, generated-sources/). Override by adding config files to your project:

Linter	Project config file	Default exclusions
yamlfmt	.yamlfmt	target/, node_modules/, generated-sources/, dist/, build/
spotbugs	development/spotbugs-exclude.xml or .spotbugs-exclude.xml	*generated-sources*
gitleaks	.gitleaks.toml	none
rumdl	.rumdl.toml	CHANGELOG.md

Example .yamlfmt:

exclude:
  - target/
  - my-custom-dir/
formatter:
  type: basic
  retain_line_breaks_single: true

Example development/spotbugs-exclude.xml:

<FindBugsFilter>
    <Match><Package name="~com\.example\.generated.*"/></Match>
</FindBugsFilter>

Custom Repository Location

Override the default repository URL via environment variable:

# Bash/Zsh - add to .bashrc or .zshrc
export JUST_CHECK_REPO="https://internal.git/org/just-check"

# Fish - add to config.fish
set -gx JUST_CHECK_REPO "https://internal.git/org/just-check"

The justfile picks this up automatically:

devtools_repo := env("JUST_CHECK_REPO", "https://codeberg.org/itiquette/just-check")

CI Integration

The verify.sh script automatically detects the CI environment and adjusts output accordingly:

Environment	Detection	Output
Local/Console	No CI env vars	Colored table in terminal
GitHub/Forgejo/Gitea Actions	GITHUB_STEP_SUMMARY set	Markdown summary in Actions UI
GitLab CI	CI_JOB_URL set	Console output (fallback)

CI Actions Summary

When running in CI with step summary support, results appear in the job summary with:

• Markdown table showing each linter's status
• Expandable error details for failed linters
• Pass/fail/skip counts

No configuration needed - detection is automatic.

License

This project is licensed under the MIT License. Documentation and configuration files are licensed under CC0-1.0.

See the SPDX headers in each file for details. This project is REUSE compliant.

Origin

Fork of devbase-check by Digg - Agency for Digital Government. This fork extends the original with additional language support (Go, security scanning) and features beyond the upstream project's scope.