Use qualityGuide 05
Configuration
Configure built-in and external quality analyzers.
On this page
Configuration lives in quality.yml at the repository root.
quality init adds a YAML language-server comment that points compatible
editors to the published quality.yml JSON Schema.
version: 1
output: pretty
baseline: .quality-baseline.json
tools:
swiftlint:
enabled: true
required: true
eslint:
enabled: true
required: true
output accepts pretty, agent, json, sarif, or github. Use agent
for compact Markdown optimized for coding-agent context; use json or sarif
for complete machine-readable reports.
Tool settings
Each built-in adapter accepts:
enabled: include or exclude the toolcheck: participate inquality check; set false to retain format and fix operationsrequired: fail if its executable is unavailablecommand: override executable resolutionworking_directory: run from a repository-relative workspace directorycheck_args: replace arguments for checksformat_args: replace formatting argumentsfix_args: replace fix argumentstimeout_seconds: stop an invocation that exceeds this duration
Set required: false when a tool is useful locally but should not make every environment fail.
Repository-local commands
Relative commands resolve from the adapter’s working directory:
tools:
detekt:
enabled: true
required: true
working_directory: apps/android
command: ./gradlew
check_args: [detekt]
JavaScript adapters automatically prefer executables under node_modules/.bin. Android Lint locates nested Gradle wrappers automatically.
Repository tasks
Use tasks for canonical project gates that should participate in quality check without pretending to be a file-oriented formatter:
tasks:
typecheck:
name: TypeScript
command: pnpm
args: [run, typecheck]
extensions: [ts, tsx, astro]
config_files: [package.json, tsconfig.json, pnpm-lock.yaml]
Tasks run concurrently with built-in and custom adapters. Set
working_directory for a workspace-specific command. When extensions or
config_files are present, changed-file mode skips the task unless one of
those inputs changed. With neither field, the task always runs.
Tasks and custom adapters also accept timeout_seconds. In noninteractive Unix
runs, a timeout stops the analyzer and descendants in its isolated process group.
On Windows, timeout cleanup stops the process tree. Deliberately detached
processes are outside these boundaries. Unix analyzers that inherit terminal
input keep the caller’s group so prompts remain usable; their timeout stops the
direct child only. Output collection is bounded even when another process keeps
an inherited pipe open. If tree cleanup fails, the report includes recovery
guidance and the check remains failed.
During initialization, a canonical root package script is added as
repository-check when available. Detected analyzers receive check: false
so that script remains the source of truth without sacrificing quality format or quality fix. If no composite script exists, typecheck or
type-check is imported separately and analyzers continue to check normally.
Git hook steps
Hook behavior stays in version-controlled configuration:
hooks:
pre-push:
steps:
- name: Run local validation
command: pnpm
args: [run, pre-push]
pass_hook_args: false
covers: [pnpm run ci]
parser: generic
pass_hook_args forwards arguments supplied by Git. covers lists exact
GitHub Actions run: commands that a broader wrapper intentionally includes;
it changes quality ci plan coverage only and never changes what is executed.
parser normalizes failed output with the same generic, codespell,
eslint-json, github-annotations, swiftlint-json, ktlint-json,
santi-og-json, and typos-json parsers available to repository tasks. The
command must emit the format selected by the parser. Commands under covers must be non-empty single lines. See
Local CI and PR gates for execution and reporting behavior.
Validation
Unknown keys are rejected instead of silently ignored. Common typos include a suggestion so configuration mistakes fail early and clearly.