Documentation/Linting/

Getting Started with Linting

Getting Started with Linting

This guide walks you through running your first lint, reading the output, and deciding what to fix. No configuration file needed -- 8Vast's linter works out of the box.

Quick start

8v lint .

That's it. 8Vast scans every file in the current directory — Rust, TypeScript, Python, Go, or any other supported language. It runs built-in rules, detects external tools (Clippy, ESLint, Ruff), and merges everything into one report.

Understanding the output

A lint run produces a list of findings. Each finding looks like this:

src/handlers/auth.rs:42:5
  [ERROR] error-swallowed
  Error variant ignored: `Err(_) => {}`

src/lib.rs:187:1
  [WARNING] function-too-long
  `process_request` is 87 lines (limit: 50)

src/db/queries.rs:15:12
  [WARNING] no-unwrap
  `.unwrap()` will panic if the value is None

Each entry has four parts:

  • Location -- file path, line number, column number.
  • Severity -- [ERROR] for issues that likely cause bugs or hide failures. [WARNING] for issues worth fixing but less urgent.
  • Rule ID -- the identifier for the rule that fired (e.g., error-swallowed). Use this to look up the rule, suppress it, or configure it.
  • Message -- a description of the problem, often including the specific code that triggered it.

At the end of the report, you'll see a summary:

3 findings (1 error, 2 warnings) in 47 files

Filtering

You don't always want to see everything. These flags narrow the scope:

# Only specific rules
8v lint . --rule error-swallowed,no-unwrap

# Only files changed since a branch
8v lint . --git-diff main

# Only errors (skip warnings)
8v lint . --severity error

# Specific files or directories
8v lint src/handlers/ src/db/

--git-diff is useful in CI -- lint only what changed in the pull request instead of the entire codebase.

Output formats

8v lint .                    # Human-readable (default)
8v lint . --format json      # Machine-readable JSON
8v lint . --format summary   # Grouped by category with counts

The JSON format outputs one object per finding with file, line, column, severity, rule, and message fields. Pipe it to jq or feed it to other tools.

The summary format groups findings by category (error handling, performance, security, etc.) and shows counts. Useful for getting a high-level view of code health.

Language support

The analysis engine is language-agnostic. What varies is the depth of built-in rules:

LanguageBuilt-in rulesExternal toolsCustom YAML rules
Rust156 rules (deep)Clippy, cargo checkYes
TypeScript3 rules + metricstsc, ESLintYes
PythonMetricsRuff, mypyYes
Go, Java, C, C++, ...Metrics—Yes

For any language, you can write custom YAML rules to catch patterns specific to your project. See Custom Rules.

For languages with built-in rules, 8Vast catches patterns other tools miss — especially in error handling and silent failures. If you need something the built-in rules don't cover, write it in YAML or native Rust.

What it catches

Built-in rules cover six categories:

Error handling — swallowed errors, broken error chains, errors logged at the wrong level. These are what most distinguish 8Vast's linter. Code that compiles and runs but silently loses errors.

Safety — panics in libraries, undocumented unsafe, blocking calls in async. Things that compile but break at runtime.

Performance — clones in loops, large futures, locks held across .await. Patterns that waste resources.

Security — SQL injection, command injection, hardcoded secrets, path traversal. Attack surfaces.

Metrics — function length, nesting depth, cognitive complexity. Configurable thresholds. Works on ANY language.

Test quality — missing assertions, trivial assertions, ignored tests. Patterns that erode test trust.

For the complete list, see the Rules Reference.

Suppressing rules

Sometimes a rule fires on code you've reviewed and decided is correct. Suppress it inline:

// Suppress for this line
let value = map.get("key").unwrap(); // vast-lint: skip(no-unwrap)

Or suppress a rule for an entire file by placing a comment at the top:

// vast-lint: allow-file(function-too-long, no-unwrap)

Inline suppression is intentionally visible -- it signals to anyone reading the code that someone made a deliberate choice here, not an oversight.

External tools

8Vast auto-detects and runs external analysis tools alongside its own rules:

  • Rust: Clippy, cargo check
  • TypeScript: tsc, ESLint
  • Python: Ruff, mypy
  • .NET: dotnet build

All output merges into one unified report. You don't need to run these tools separately — 8Vast finds and runs them for you. To pass specific arguments or disable a tool, see Configuration.

Next

Referenced by