Skip to main content

Project configuration preview

:::warning Unreleased feature The published v1.1.0 binary does not recognize --config. This page documents behavior currently on the main branch so early testers can provide feedback. Do not add it to release-pinned CI until a release includes the option. :::

Project configuration gives rules explicit context that one syntax tree cannot provide, such as whether a source is an executable, sourced plugin entrypoint, autoloaded function, completion, or test fixture. Version 1 does not discover a configuration file automatically, so pass --config on every invocation.

Try the standalone example​

Build the current source checkout:

git clone https://github.com/z-shell/zsh-lint.git
cd zsh-lint
go build -o ./zsh-lint ./cmd/zsh-lint
./zsh-lint --config examples/standalone/zsh-lint.json \
  examples/standalone/script.zsh

The source checkout's examples/standalone and examples/plugin directories contain the validated examples used on this page. Their delivery is tracked in zsh-lint issue 182.

Minimal configuration​

{
  "version": 1,
  "project": {
    "kind": "application",
    "minimum_zsh": "5.8",
    "function_namespaces": []
  },
  "sources": [{"root": "script.zsh", "profile": "standalone-executable"}]
}

Paths are relative to the directory containing the configuration. Every input must stay under that directory and match one source root.

Source profiles​

ProfileUse it for
standalone-executableA script launched as its own process.
startup-fileFiles such as .zshrc or .zprofile.
sourced-libraryPlugin entrypoints and libraries loaded into an existing shell.
autoload-functionOne function body loaded through Zsh autoload.
test-fixtureTest inputs that should not inherit production lifecycle assumptions.

The optional completion role is valid only with autoload-function.

Plugin example​

./zsh-lint --config examples/plugin/zsh-lint.json \
  examples/plugin/example.plugin.zsh \
  examples/plugin/functions/example-run \
  examples/plugin/completions/_example \
  examples/plugin/tests/example-fixture.zsh

Configured analysis treats the complete explicit input list as one project. Files you omit are outside cross-file validation.

For the strict schema and failure contract, see the source-adjacent project configuration contract.