Lint Rules Reference

Bivvy includes built-in lint rules to validate your configuration. Run bivvy lint to check your configuration for issues.

Severity Levels

Level	Description
Error	Prevents execution, must be fixed
Warning	Should be addressed, but won’t block
Hint	Informational suggestion

Output Formats

The lint command supports multiple output formats:

Human-readable (default):

bivvy lint

JSON output:

bivvy lint --format=json

SARIF output (for IDE/CI integration):

bivvy lint --format=sarif

Auto-Fix

Some rules support automatic fixes:

bivvy lint --fix

Strict Mode

Treat warnings as errors:

bivvy lint --strict

Built-in Rules

app-name-format

Severity: Warning (Error if empty) Auto-fix: Yes

Validates the app_name field follows naming conventions.

Checks:

• app_name is not empty (Error)
• app_name does not contain spaces (Warning)

Example - Invalid:

app_name: "My App Name"  # Warning: contains spaces

Example - Valid:

app_name: my-app-name

Suggestion: When spaces are detected, suggests kebab-case alternative.

---

required-fields

Severity: Error Auto-fix: No

Ensures required configuration fields are present.

Checks:

• app_name field must be present (Error)
• At least one workflow should be defined (Warning)

Example - Invalid:

# Missing app_name
steps:
  hello:
    command: echo hello

Example - Valid:

app_name: my-app
steps:
  hello:
    command: echo hello
workflows:
  default:
    steps: [hello]

---

circular-dependency

Severity: Error Auto-fix: No

Detects circular dependencies between steps in the depends_on field.

Checks:

• No step can be part of a dependency cycle

Example - Invalid:

steps:
  a:
    command: echo a
    depends_on: [b]
  b:
    command: echo b
    depends_on: [c]
  c:
    command: echo c
    depends_on: [a]  # Creates cycle: a -> b -> c -> a

Example - Valid:

steps:
  a:
    command: echo a
    depends_on: [b]
  b:
    command: echo b
    depends_on: [c]
  c:
    command: echo c

Diagnostic: Reports the full cycle path (e.g., “a -> b -> c -> a”).

---

self-dependency

Severity: Error Auto-fix: No

Detects steps that depend on themselves.

Checks:

• A step cannot list itself in depends_on

Example - Invalid:

steps:
  build:
    command: make build
    depends_on: [build]  # Error: self-dependency

Example - Valid:

steps:
  build:
    command: make build
    depends_on: [setup]

---

undefined-dependency

Severity: Error Auto-fix: No

Ensures all depends_on references point to existing steps.

Checks:

• Every step name in depends_on must exist in steps

Example - Invalid:

steps:
  build:
    command: make build
    depends_on: [nonexistent]  # Error: step doesn't exist

Example - Valid:

steps:
  setup:
    command: npm install
  build:
    command: npm run build
    depends_on: [setup]

---

undefined-template

Severity: Error Auto-fix: No

Validates that template references resolve to actual templates.

Checks:

• Template names in template field must exist in the registry

Example - Invalid:

steps:
  deps:
    template: nonexistent-template  # Error: template not found

Example - Valid:

steps:
  deps:
    template: brew  # Built-in template
    inputs:
      packages: [git, node]

---

template-inputs

Severity: Error/Warning Auto-fix: No

Validates that template inputs match their contracts.

Checks:

• Required inputs without defaults must be provided (Error)
• Input types must match the template contract (Error)
• Unknown inputs produce a warning (Warning)

Example - Invalid (missing required):

steps:
  deps:
    template: my-template
    # Missing required input 'packages'

Example - Invalid (wrong type):

steps:
  deps:
    template: my-template
    inputs:
      enabled: "not a boolean"  # Error: expected boolean

Example - Valid:

steps:
  deps:
    template: my-template
    inputs:
      packages: [git, node]
      enabled: true

unknown-requirement

Severity: Warning Auto-fix: No

Requirement name in a step’s requires list is not in the built-in registry or the config’s requirements map.

Checks:

• Every name in requires must be a known requirement

Example - Invalid:

steps:
  build:
    command: make build
    requires: [nonexistent-tool]  # Warning: unknown requirement

Example - Valid:

steps:
  build:
    command: make build
    requires: [ruby, node]

---

circular-requirement-dep

Severity: Error Auto-fix: No

Circular dependency chain detected in requirement install dependencies.

Example - Invalid: A requirement whose install template depends on itself through a chain.

---

unknown-environment-in-step

Severity: Warning Auto-fix: No

A step’s environments override block references an environment name that is not a built-in environment and not defined in settings.environments.

Example - Invalid:

steps:
  build:
    command: make build
    environments:
      nonexistent:  # Warning: unknown environment
        command: make build-fast

---

unknown-environment-in-only

Severity: Warning Auto-fix: No

A step’s only_environments list includes an environment name that is not a built-in environment and not defined in settings.environments.

Example - Invalid:

steps:
  build:
    command: make build
    only_environments: [nonexistent]  # Warning: unknown environment

---

environment-default-workflow-missing

Severity: Error Auto-fix: No

An environment’s default_workflow references a workflow that doesn’t exist in the config.

---

unreachable-environment-override

Severity: Warning Auto-fix: No

A step has an environment override for an environment that is excluded by its own only_environments list. The override can never take effect.

---

custom-environment-shadows-builtin

Severity: Warning Auto-fix: No

A custom environment name in settings.environments matches a built-in environment name (ci, docker, codespace, development).

---

redundant-environment-override

Severity: Hint Auto-fix: No

An environment override specifies field values identical to the base step.

---

redundant-env-null

Severity: Hint Auto-fix: No

An environment override sets an env var to null (remove), but that var is not present in the base step’s env map.

---

environment-circular-dependency

Severity: Error Auto-fix: No

Circular dependency detected in per-environment depends_on overrides.

---

install-template-missing

Severity: Hint Auto-fix: No

A requirement has no install template, so Bivvy cannot offer automatic installation.

---

service-requirement-without-hint

Severity: Warning Auto-fix: No

A service requirement (e.g., postgres-server) lacks an install_hint, making it hard for users to fix the gap manually.

---

IDE Integration

VS Code

Use the SARIF Viewer extension to see lint results inline:

bivvy lint --format=sarif > bivvy.sarif

GitHub Actions

Upload SARIF results to GitHub Code Scanning:

- name: Lint Bivvy config
  run: bivvy lint --format=sarif > bivvy.sarif
- uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: bivvy.sarif

JSON Output Schema

The JSON output format includes:

{
  "diagnostics": [
    {
      "rule_id": "circular-dependency",
      "severity": "error",
      "message": "Circular dependency detected: a -> b -> a",
      "file": ".bivvy/config.yml",
      "line": 5,
      "column": 3,
      "suggestion": null
    }
  ],
  "summary": {
    "total": 1,
    "errors": 1,
    "warnings": 0,
    "hints": 0
  }
}