Meet Swarm
Zedbee Swarm is a diff-aware quality and security gate for JavaScript and TypeScript teams. It inspects the exact change being proposed, attributes findings to that change, and blocks only the problems your team has chosen to stop.
Swarm sits between staged work and shared history. It gives developers fast, explainable feedback while giving engineering teams a consistent policy across local development, CI, and coding-agent workflows.
zedbee package.npm install --save-dev zedbee
npx zedbee init
npx zedbee scanA gate for the proposed change
Most developer tools analyze whatever happens to be present in the working directory. Swarm begins with a more precise question:
What is this team about to commit?
For an ordinary local scan, the exact Git index is the target. Swarm compares it with committed HEAD, runs the enabled checks, attributes relevant changes, and evaluates the result against repository policy.
Unstaged edits remain outside that decision.
Inspect broadly. Attribute narrowly.
Some correctness questions cannot be answered by looking at one changed line.
Type checking may require a complete TypeScript project. Dependency analysis needs the workspace graph. Duplication and dead-code checks may need to inspect the surrounding repository.
Swarm gives each analyzer the context it needs, then separates analysis scope from developer responsibility. Existing unrelated findings do not become the current developer’s backlog simply because a broad check discovered them.
Understand attribution with worked examplesworkspace or complete file
selected target changes
new or worsened issues
The selected Git state is the source of truth
If you stage a file and continue editing it, Swarm scans the staged version. The later working-tree version does not replace it.
This distinction matters for partially staged files, repository policy, source excerpts, and every finding location. The result describes the change Git will commit, not the state of an editor tab.
.zedbeerc.jsonc, run git add .zedbeerc.jsonc for the next local scan to use the update. Saving the file without staging it does not change that scan’s settings.git add --patch src/authenticate.ts
git diff --cached
npx zedbee scanOne managed suite. One policy surface.
Swarm coordinates a bounded set of pinned analyzers under one configuration and reporting contract.
The managed suite covers
- Formatting and lint
- TypeScript correctness
- Cyclomatic and readability complexity
- Structural security and secrets
- Duplication and dependency architecture
- Dead code and package hygiene
- React correctness and DOM accessibility
- Vulnerable dependencies
Use a profile to establish the baseline, then configure supported rules, thresholds, severities, timing, overrides, and exclusions where the repository needs them.
Preview your repository’s recommended setupCompare checks, profiles, and engine versions{
"$schema": "./node_modules/zedbee/schema/zedbee.schema.json",
"schemaVersion": 1,
"profile": "recommended",
"checks": {
"structuralSecurity": { "severity": "error" },
"secrets": { "severity": "error" },
"vulnerabilities": {
"severity": "error",
"onUnavailable": "block"
}
}
}Security includes the scanner itself
Repository content, project configuration, and analyzer output are treated as untrusted inputs.
Swarm uses isolated snapshots, inert managed analyzer configuration, bounded child processes, validated paths, redacted secret handling, and checksum-verified managed binaries. It does not run project lifecycle scripts or executable project analyzer configuration as part of a scan.
Network behavior is documented and surfaced during setup.
Review the scanner’s security modelExplore the built-in structural security rulesUnderstand privacy and data handlingOSV vulnerability request
- Package name
- sent
- Exact package version
- sent
- npm ecosystem identifier
- sent
Source code and file hashes are not sent to OSV.
Three outcomes, three different meanings
A trustworthy quality gate must distinguish a clean result from an unavailable one.
Exit code 2 means the result is incomplete. It must not be interpreted as a clean scan.
Teams can decide whether a supported online-service outage blocks or warns, but Swarm keeps the missing analysis visible.
- 0
- Scan completed without blocking findings
- 1
- Scan completed and repository policy blocked the change
- 2
- Required analysis could not complete
One decision, multiple interfaces
Developers can use Swarm through its branded interactive terminal. Automation can consume deterministic text or versioned JSON. CI and enterprise systems can ingest SARIF 2.1.0.
The presentation changes for its audience. The underlying findings, attribution, and policy decision remain consistent.
Explicit text, JSON, and SARIF exports contain every finding and incomplete-check notification. Terminal preview limits do not abbreviate these exports.
npx zedbee scanBoundaries are part of the contract
Swarm documents what each check can establish and what remains outside its scope.
Its structural security rules are intentionally narrower than a general dataflow or taint-analysis platform. Secret scanning covers selected supported files, not complete Git history. Vulnerability analysis uses the online OSV API and does not include an offline advisory database.
Swarm also uses its own managed analyzer settings rather than loading executable project ESLint, Prettier, Babel, Secretlint, or plugin configuration.
These are deliberate boundaries, not hidden footnotes.
- What it inspects
- When it runs
- How findings are attributed
- Which engine it uses
- What can be configured
- Important limitations
Choose your next step
Start with the change in front of you.
Install Swarm, stage a change, and see how an attributable quality gate fits into your team’s workflow.
Run your first secure scannpm install --save-dev zedbee
npx zedbee init