Use cases

Sverka is a framework for running local checks. CI compilation is one use case — not the only one. Here are the concrete scenarios Sverka supports.

1. Local checks runnerCopy Anchor Link

Run lint, typecheck, and test locally with a single command. Get structured findings back. No CI required.

# Define checks in sverka.config.ts
sverka run --evaluate

# Get SARIF output
sverka run --format sarif

# View findings in terminal
sverka view .sverka/findings.sarif

# Start web dashboard
sverka ui

Why this matters: You find problems at write time, not at push time. No more "it worked on my machine but CI failed" — the same workflow runs locally and in CI.

2. CI compilationCopy Anchor Link

Compile the same workflow definition to GitHub Actions or GitLab CI YAML.

# Compile to GitHub Actions
sverka compile --target github

# Compile to GitLab CI
sverka compile --target gitlab

The generated YAML is a thin wrapper that runs sverka run in CI. Your workflow definition stays in TypeScript — the YAML just bootstraps Sverka and executes the same plan.

Why this matters: One definition, two execution modes. Local runs for fast feedback. CI runs for enforcement. No duplication.

3. Agent orchestrationCopy Anchor Link

AI agents delegate check orchestration to Sverka instead of running tools one by one.

# Agent runs this instead of 10 separate tool calls:
sverka run --format json

One command. The agent gets structured JSON with:

• Step status (success/failure/skipped)
• Findings count by severity
• Policy verdict (pass/fail)
• Duration

Why this matters: Fewer tool-call round-trips. Lower token cost. More stable agent behavior. The agent delegates orchestration; Sverka handles execution.

4. SARIF toolingCopy Anchor Link

Sverka normalizes SARIF from any tool (ESLint, Semgrep, CodeQL, SonarCloud) into a unified Finding[]. You can:

• Serialize findings back to SARIF: serializeSarif(findings)
• View in terminal: sverka view findings.sarif
• Generate HTML reports: sverka view findings.sarif --format web
• Dashboard: sverka ui serves a local web dashboard
• Policy gate: evaluateGate({ findings }) enforces severity rules

Why this matters: SARIF is the industry standard for static analysis results. Sverka makes it easy to collect, normalize, view, and enforce findings from any tool.

5. Policy enforcementCopy Anchor Link

Define severity policies and enforce them as a gate.

import { createPolicy, evaluatePolicy } from "@sverka/verification";

const policy = createPolicy({
  failOn: [
    { severity: "critical", onlyNew: false },
    { severity: "high", onlyNew: false },
  ],
});

const { verdict } = evaluatePolicy(findings, policy, []);
// verdict: "pass" | "fail"

Why this matters: Consistent quality bars. Local and CI enforce the same rules. No more "CI is stricter than local" — the policy is code.

6. Multi-target compilationCopy Anchor Link

The same workflow compiles to multiple CI targets:

Why this matters: No lock-in. Define once, compile to any target. Switch CI providers without rewriting your checks.

7. Agent benchmarkingCopy Anchor Link

@sverka/arena runs agents against tasks with and without a plugin, then measures tokens, tool calls, wall time, and (optionally) a blind judge score.

sverka-arena doctor    # verify the environment
sverka-arena run       # run the matrix (models × plugins × repetitions)
sverka-arena report .arena/results.json

Why this matters: "Does this skill help?" is measurable. Arena puts a number on plugin impact instead of guessing.

See Arena — benchmarking agents for config and command details.

Next stepsCopy Anchor Link

• Concepts — design principles and architecture.
• SARIF pipeline — serialize, view, dashboard.
• First workflow — hands-on tutorial.
• Agent integration — skill + CLI for agents.