.zedbeerc.jsonc

Keep the policy for your project alongside its code, with explicit settings you can review in Git.

Repository configuration

One data file at the Git repository root

By default, Swarm reads .zedbeerc.jsonc at the root of the Git repository being scanned. It is not a file inside the installed Zedbee package or a setting stored in your CI provider.

The format is JSON with comments and trailing commas allowed. schemaVersion identifies the configuration format and must be 1. The optional $schema points your editor at the schema bundled with the installed package; it does not require the website to be online.

Use npx zedbee init to preview an initial setup. If the default file is absent from the selected Git state, Swarm uses recommended defaults. A present but invalid file is an error, not a request to silently fall back to defaults.

Configuration is data, not executable code. Swarm does not load a JavaScript configuration file or import your project’s native analyzer configuration.

{
  "$schema": "./node_modules/zedbee/schema/zedbee.schema.json",
  "schemaVersion": 1,
  "profile": "recommended",
  "checks": {
    "formatting": {
      "settings": { "printWidth": 100 }
    }
  },
  "failOnIncomplete": true
}

When edits apply

Save, stage, commit: three different moments

For a local scan, save your edit and run git add .zedbeerc.jsonc. The next ordinary scan and zedbee checks use that staged version. If you edit it again, stage it again. Saving alone does not replace the configuration already in the index.

For CI base mode, commit the file on the branch being checked and push it. A CI run uses the copy in the commit it checks out. Rerunning an older commit still uses that commit’s settings; rewriting the file after checkout does not change the scan policy.

You do not need to merge the settings into main first. --base origin/main chooses the code comparison, not the branch from which configuration is loaded. Local and CI scans normally share this one file.

See the CI configuration workflow

Which settings does the scan use?
Your change	When it takes effect
Save the file	Not yet. Scans still use the previously staged or committed settings.
Stage the file	The next local scan uses the staged settings. CI is unchanged.
Commit and push	CI uses the update when its job checks out a commit containing it.

Configuration reference

What belongs in the file?

Keep the file focused on deliberate changes. Omitted optional settings inherit their defaults. Unknown top-level fields are rejected by the configuration schema.

Top-level configuration fields
Field	Purpose	Default / requirement
`$schema`	Local editor validation and completion.	Optional schema path
`schemaVersion`	Configuration format version, not the Zedbee package version.	Required: 1
`profile`	Base set of check policies.	recommended
`checks`	Repository-wide settings keyed by check ID.	Profile settings
`overrides`	Ordered file-scoped patches to check policies.	Empty list
`pathExclusions`	Named checks intentionally suppressed for matching paths, with a reason.	Empty list
`reporting`	Source visibility, terminal finding limit, temporary-report age, and agent guidance.	interactive source; 25 findings; 24h report age
`resources`	Optional Git-command timeouts and output limits during scans.	No configured timeout override
`failOnIncomplete`	Default policy for enabled checks that cannot complete without a more specific disposition.	true

Every check accepts severity (off, warn, error) and timing (relevant, always). Additional fields are check-specific: formatting has managed settings; lint and React checks expose bundled rules; complexity checks have max and blockWorsening; duplication has workspace-wide thresholds and settings. Typed lint also supports typeInformation, while vulnerabilities supports repository-wide onUnavailable.

Use the installed editor schema to discover accepted options and zedbee checks --format json to inspect resolved values. Do not copy a native ESLint or Prettier configuration wholesale into checks; only Zedbee’s managed settings and bundled rule inventory are accepted.

Find check IDs and their coverage

Override precedence

Later matching fields win, not the whole object

For each repository-relative file, Swarm starts with the profile, applies repository-level checks, then applies every matching entry in overrides in array order. A later match replaces only fields it supplies. Exclusions are applied after those patches.

In this example, packages/legacy/view.ts receives printWidth: 120. Another file under packages/ receives 90; a file outside packages/ keeps 100. All three keep singleQuote: true because neither override replaces it.

Use forward-slash, repository-relative patterns. Two files in the same workspace can have different supported file policies.

Duplication settings such as threshold and settings.minLines are workspace-wide and are rejected in file overrides. OSV onUnavailable is repository-wide and is also rejected there. Severity and timing overrides remain available, but workspace-wide checks resolve their scope conservatively rather than treating every finding as an independent file check.

{
  "schemaVersion": 1,
  "checks": {
    "formatting": {
      "settings": {
        "printWidth": 100,
        "singleQuote": true
      }
    }
  },
  "overrides": [
    {
      "files": ["packages/**"],
      "checks": {
        "formatting": {
          "settings": { "printWidth": 90 }
        }
      }
    },
    {
      "files": ["packages/legacy/**"],
      "checks": {
        "formatting": {
          "settings": { "printWidth": 120 }
        }
      }
    }
  ]
}

Intentional exclusions

Suppress only the checks and paths you mean

Each exclusion needs at least one path pattern, at least one check ID, and a short reason. A matching exclusion wins over earlier overrides for the named checks. It does not turn every check off for that file.

The example suppresses formatting and lint under generated/. Other enabled checks can still inspect those files. Configured exclusions and matches against the selected changes are recorded in JSON reports.

Exclusion patterns support ordinary *, **, and ? matching. Use forward slashes. Absolute paths, parent traversal, negation, braces, and extended globs are rejected for exclusions.

An exclusion removes coverage; it does not fix the finding.

Keep patterns narrow and record why the skipped analysis is intentional. Do not exclude a path just to make an unexpected failure disappear.

{
  "schemaVersion": 1,
  "pathExclusions": [
    {
      "files": ["generated/**"],
      "checks": ["formatting", "lint"],
      "reason": "Generated output is owned by the code generator."
    }
  ]
}

Output and validation

Change presentation without changing the gate

sourceExcerpts accepts never, interactive, or always. An explicit --include-source or --no-source overrides ordinary source visibility for that scan. Secret finding content remains redacted under every choice.

terminalFindingLimit accepts a positive integer or "all". It limits the terminal finding preview, not complete text, JSON, or SARIF exports. temporaryReportMaxAge accepts a whole-number duration in minutes, hours, or days; expiration makes temporary reports eligible for cleanup on a later maintenance run, not durable archives.

Advanced Git limits live under resources.git: softTimeout, hardTimeout, and outputLimitBytes. Timeout durations use positive whole numbers with ms, s, m, or h; a configured hard timeout must exceed a configured soft timeout. Output limits are positive whole byte counts.

After editing, stage the file and run npx zedbee checks. Fix schema or parsing errors rather than assuming a partially valid policy will be used. Reporting settings do not change whether a finding or incomplete check blocks the scan.

Configure incomplete-result behavior

{
  "schemaVersion": 1,
  "reporting": {
    "sourceExcerpts": "interactive",
    "terminalFindingLimit": 25,
    "temporaryReportMaxAge": "24h"
  }
}